# Suprnova - complete manual

> Every chapter of the Suprnova manual, inlined. Version 4.6.2. Source: https://github.com/eas4ai/suprnova

Individual chapters are at https://suprnova.app/docs/<slug>.md; the index is at https://suprnova.app/llms.txt.

---


# Prologue

---

<!-- /docs/changelog -->

# Changelog

A readable, per-version log of what changed in Suprnova. Each version
section is that version's release record. A version is released when its
version commit and matching `v<version>` tag are pushed atomically. Newest first.

## 4.6.2 - 2026-10-23

### Added

- **`HttpEmbedder` reports the usage its provider sends.** `Embedder` gains
  `embed_documents_metered` and `embed_query_metered`, which return the vectors
  with the provider's own `usage` (`prompt_tokens`, `total_tokens`) as a
  `Metered<T>`; the HTTP provider reads it from the OpenAI-compatible response
  and sums it across batches, and every other provider reports `None`, so an
  application that pays per token settles the bill from the provider's count
  instead of an estimate (#212).
- **`HttpEmbedder` runs over an application-owned transport.**
  `HttpEmbedder::with_transport` takes an `EmbeddingTransport`: the application
  sends each `TransportRequest` (the pinned endpoint, headers, JSON body,
  timeout and response cap) through its own HTTP client, credential resolver
  and admission rules and returns a `TransportResponse` with the status,
  headers and body. The embedding protocol, retries, `Retry-After`, parsing and
  vector validation stay in the framework, which also refuses a body over the
  cap whatever the transport did (#213).
- **`LazyEmbedder` registers a shipped profile and loads the model on first
  use.** `SearchRegistry::register_embedder` can take a `LazyEmbedder` built
  from a shipped `ModelProfile` and a loader; the service starts and tests run
  without downloading weights. The generation coordinator calls the new
  `Embedder::resolve_profile` before it pins a generation, so the generation
  still records the loaded model's revision, and a loaded model whose id or
  dimensions differ from the shipped profile is refused by name (#214).
- **A search generation an interrupted build left behind can be reclaimed.**
  `generations::reclaim_generation(index, generation)` and `search:reclaim`
  release the creation lease of a `creating` generation so the next create
  call resumes at once instead of waiting the 60-second lease out, publish a
  `building` generation that was never switched to, and report one that is
  already current. The caller vouches for exclusive ownership, such as its own
  migration lock; `SearchEngine::release_creation_lease` is the driver hook,
  a no-op for drivers without leases (#215).
- **A Cloudflare CDN driver for static publication.** `CloudflareDriver`
  (feature `cdn-cloudflare`, on by default and free of new dependencies) works
  the way an R2 bucket with a custom domain already does: the bucket is the
  publication disk through `S3Config` with the R2 endpoint, the custom domain
  serves it, and nothing runs at the edge. The driver owns a few rules on the
  zone, created on the first switch and corrected on every later one: two URL
  rewrites that serve `/about` and `/about/` from the mirrored
  `about/index.html`, a response header rule that carries the published
  headers, and a cache rule that caches a response only when its own
  `Cache-Control` allows a shared cache, as the published objects' does. It
  purges by URL in batches of 100 or by prefix, and removes
  its rules on a first-publication rollback. `CloudflareDriver::for_origin`
  covers a hostname that mixes dynamic pages: the proxied application serves
  the published objects itself and the driver keeps the cache rule and the
  purges. R2 charges no egress.
- **An application's own 5xx page is sent as built.** With debug off, the
  framework answered every browser 5xx with its minimal status-only view,
  which also replaced a 503 page the application built on purpose, with its
  recovery link and `Content-Security-Policy`. `HttpResponse::error_view()`
  marks such a response as the application's own error view, and the
  production view leaves it alone, body and headers. Unmarked 5xx responses
  keep the minimal view; with debug on the development error page still
  replaces a marked response that carries an error report (#217).

## 4.6.1 - 2026-10-23

### Fixed

- **A Live action's framework frames fit their stack budget again in a debug
  build.** The static publication lookup that 4.6.0 added to every `GET`
  request built its 65 KB future in the request's own frame, so the frames
  below a Live action grew past the 1 MiB budget that leaves the action room
  on Tokio's default 2 MiB stack, and a deep action in a debug build could
  overflow it. The lookup now builds in a frame of its own that returns first.
- **A fresh scaffold passes its own page budget test and `cargo fmt --check`.**
  The React, Vue and Svelte kits' `tests/page_budget.rs` audited
  `routes::register()` alone, so the Live script every page loads from
  `/__live/assets` returned 404 and the test failed on a new application. It
  now audits the router `cmd/main.rs` serves, and the notes topic's gate rule
  moved from `bootstrap::register` into `live::authorize()` so both can call
  it. The kits also wrote the Live topic setup, the asset share and the page
  budget test on lines rustfmt rewrites; the templates now carry rustfmt's
  layout, and the test's layout no longer depends on the application name.
- **The page budget audit's URL mode counts the bytes that cross the wire.**
  `budget:audit <url>` and `PageBudget::audit_url` asked for uncompressed
  responses and counted decoded bytes as transfer, while a HAR capture of the
  same visit counted the compressed bytes, so the two modes disagreed on a
  page that serves gzip. A URL audit now asks for gzip, counts the compressed
  bytes for the transfer, asset and font rules, and reads the decoded body for
  the rest. This fix landed after the `v4.6.1` tag.

## 4.6.0 - 2026-10-22

### Added

- **Lossless PNG recompression.** `Image::recompress_png(PngEffort)` runs
  oxipng over a PNG after the pipeline's pixel operations, and the synchronous
  `suprnova::recompress_png` helper does the same on PNG bytes. `PngEffort::Fast`
  is oxipng's default level; `PngEffort::Maximum` is level 6 with Zopfli.
  Pixels, transparency, indexed palettes, the ICC profile and the colour chunks
  are kept; text, time and location metadata are removed; the output is never
  larger than the input. The `media` feature carries the dependency.
- **Inertia pages in RenderCache.** A page declares its cache shape on the
  `InertiaProps` struct: `#[inertia(cacheable)]` on the struct, and
  `#[inertia(public)]` or `#[inertia(per_request)]` on every field (a field
  without a marker, an unknown field name or the marker on a non-props type
  fails to compile). `Inertia::cache_page::<Props>(route, component, public_shared,
  per_request_shared)` registers the page at boot. RenderCache stores the public
  shell and stitches the per-request props in after the route guards run; the
  assembled response is `private, no-store`. Representations are keyed on
  `X-Inertia`, the partial set, the asset version and the other protocol
  headers, which the response lists in `Vary`; a stale asset version answers
  409 before any cached bytes leave. `suprnova generate-types` writes the
  declarations into `inertia-props.ts` as `inertiaPropCache`
  (`manual/render-cache.md`, `manual/frontend-typescript-types.md`).
- **A page budget audit.** `TestClient::audit_page(url, &PageBudget)` renders a
  page through the in-process request path, follows the assets the document
  references (scripts, stylesheets and their imports, images and source sets,
  fonts, icons, media, inline styles, the web app manifest) and returns every
  failed rule with the asset, the rule, the measured value and the allowed
  value. The rules cover total transfer, per-asset size, raster format against
  size (WebP or AVIF with a fallback above the threshold; a PNG within a
  margin of its oxipng fast-preset size), the one-year immutable policy on
  fingerprinted assets, no cookie on or for a static asset, no redirect on the
  first request, a font budget and the third-party hosts the page reaches. The
  `budget:audit <url | file.har>` console command applies the same rules to a
  live URL or a HAR capture. Every budget is configurable on `PageBudget` and,
  for the command, through `PAGE_BUDGET_*` environment variables
  (`manual/page-budget.md`). All three modes measure the application's own
  resources and list every third-party host, which the allowed-host rule
  governs, so a HAR capture and the in-process audit of one page agree. The React, Vue, Svelte and Live starter kits ship
  `tests/page_budget.rs` over their public pages; the dogfood application runs
  the same audit.

- **Static publication of public Inertia pages.** A route declared with
  `Router::public_page::<Props>` (or a public group plus
  `Inertia::public_page::<Props>`) renders without a session, CSRF token or
  nonce, and the application publishes its HTML and JSON objects, its
  fingerprinted assets and its transcoded images to a storage disk the CDN
  serves. Publication runs as an application boot task after the listener is
  bound, so the health check never waits for it. Every page references its
  assets by versioned key and the manifest write is the only switch, so the
  previous publication stays live until the new one is complete; a storage
  lease and a conditional manifest write keep two publishers from racing, and
  graceful shutdown waits for a delivery in progress. Pages regenerate by
  dependency tag after a committed transaction or job, delivered across
  processes through the bound `BroadcastHub`, and on a revalidate interval. The
  `CdnDriver` trait ships a CloudFront driver (origin switch, invalidation, a
  viewer-response function that restores the recorded headers); without a
  driver the origin serves the published objects from the manifest and mirrors
  them to stable bucket keys after the switch. Public pages get a
  hash-based `Content-Security-Policy` with `'unsafe-inline'` and nonces
  removed from every script directive; private pages keep their nonces, and the
  origin sends `Strict-Transport-Security` only on HTTPS it can trust.
  Images are published as WebP at quality 85 or higher, AVIF when ImageMagick
  is configured, with the metadata-stripped original as the fallback, and kept
  PNGs go through `recompress_png` at the maximum preset. Same-origin absolute
  image URLs and inline raster `data:` images go through the same preparation
  and are published as objects; a page whose own CSS (a `style` attribute or a
  `<style>` element) carries a raster image refuses publication, naming the
  route, and the origin keeps serving it. Third-party images and linked
  stylesheets are published unchanged. `static:publish`,
  `static:status` and `static:prune` are the console commands; prune keeps the
  live publication and retired versions inside their grace period. The React,
  Vue and Svelte kits ship a client that fetches the published JSON for public
  navigations and sends everything else to the origin
  (`manual/static-publication.md`).

- **Live bindings for Inertia pages.** `#[inertia(live(topic = "notes", only =
  ["stats"]))]` on an `InertiaProps` struct binds a Live topic to a list of its
  props, checked at compile time against the struct and carried into the
  generated TypeScript. A bound page renders through
  `InertiaResponse::live::<Props>("Dashboard")`, naming each topic family
  instance with `.scope(family, key)` and loading its data in `.load(...)`;
  the response reads the topic cursors before the loader runs and carries them
  under the reserved `liveBindings` page key. Topics are the Live registry's
  own: `LiveRegistry::builder().topic(name)` and `.public_topic(name)`
  register them, `.topic_family(name)` gives per-key instances such as
  `notes.42` under one `live:topic.{name}` ability (`.load_with(...)` takes
  the response builder for deferred and optional props), and every binding goes
  through Live's subscription log, authorization and transports; a private
  topic without an authorizer refuses to boot, and a binding the viewer may
  not subscribe to is omitted from the page instead of leaking its cursor. A
  change registered with `LiveTopics::changed` signals after the commit of its
  transaction and never after a rollback, coalesced to one signal per topic
  per request or job and excluding the sender's own page;
  `on_model_scoped` publishes a model's saves and deletes to the instance it
  maps to. A signal carries only the topic, its cursor and generation, and
  the affected prop names. The configured `BroadcastHub` owns each topic's cursor and its rate
  (`LIVE_TOPIC_SIGNAL_INTERVAL_MS`, default 100 ms); with the Redis Streams
  hub a signal reaches pages on every node, without a hub it reaches the
  publishing process only; an instance with no member and no activity for
  `LIVE_TOPIC_INSTANCE_RETENTION_SECS` (default one day) retires and comes
  back with a new generation at cursor 0, which the client treats as a reset
  of its bound props. The React, Vue and
  Svelte kits ship one client
  core with an adapter each: a signal older than the render is dropped, a
  burst reloads once with the union of its props, a failed reload retries
  with bounded backoff, and polling stays as the fallback. The kit dashboards
  bind `stats` to the per-user `notes` family (`manual/live.md`,
  `manual/frontend-pages.md`).

- **Event sourcing.** `#[suprnova::domain_event(name, version)]` declares a
  fact with a stable stored name and schema version, `#[suprnova::aggregate]`
  plus the `AggregateRoot` trait rebuild an aggregate from its history, and
  `Aggregate::record(..).await` then `Aggregate::persist().await` appends facts
  in their own transaction with an optimistic version check, so two writers
  never record the same aggregate version (a stale version is a 409 conflict).
  `apply` receives a `Fact` view that is identical when recording and when
  rebuilding, so a snapshot always equals a full rebuild. `Projector` handlers
  keep read models and `Reactor` handlers run side effects once; a
  `QueuedProjector` runs on the queue worker and never reads a synchronous
  projection. Projectors checkpoint by stored event id and `EventReplay`
  rebuilds them from the start in event order, synchronous handlers before
  queued ones per page, while reactors stay silent. Snapshots shorten rebuilds.
  Three tables (`stored_events`, `snapshots`, `projector_checkpoints`) ship as
  a framework migration for SQLite, PostgreSQL and MySQL/MariaDB; rolling it
  back drops the history. Two domain events with one stored name refuse to
  boot. The console commands are `event-sourcing:replay`,
  `event-sourcing:events` and `event-sourcing:snapshot`. A projector that
  changes a Live-bound topic signals once after the transaction commits, never
  on rollback and never during replay. The dogfood app shows a shared tally on
  a Live page (`manual/event-sourcing.md`).
- **`DB_OUTCOME_SETTLE_TIMEOUT`** (`DatabaseConfig::outcome_settle_timeout`,
  default 30 s) bounds how long a caller whose `persist` was cancelled during
  the commit waits, on its next call, for the transaction's real outcome
  before reporting it as unknown; `Aggregate::is_settled()` says whether that
  wait is pending. It never cancels or bounds a transaction, query or commit.

### Changed

- **The default lossy encode quality is 85, not 70.** JPEG and lossy WebP
  encoded without an explicit `quality` call now use 85, which
  `DEFAULT_IMAGE_QUALITY` names. Quality below 85 blurs images.
- **Inertia protocol middleware runs before RenderCache** whatever order the
  application registered them in, so an asset mismatch is answered before a
  stored page could be replayed. A cacheable Inertia route with an opaque
  share hook or provider fails boot with the route name; declare the shared
  props by name instead. Middleware boxed through the public `into_boxed`
  keeps its type identity, so ordering and boot checks see it.
- **Static files get a cache policy by file name.** `StaticFiles` serves a
  fingerprinted file (Vite's `name-<hash>` convention, confirmed by the build
  manifest when one is configured, so an all-lowercase hash counts;
  `fingerprint(pattern)` changes the convention for other files) with
  `public, max-age=31536000, immutable`, and every
  other file with `public, max-age=3600` unless `cache_control(...)` sets
  another value. Before, `cache_control` applied to every file and nothing was
  sent when it was unset. A static file response no longer sets the session or
  XSRF cookie when the request left the session untouched; a request that
  changed the session (a remember-me rotation, a regeneration) still gets its
  cookies.

- **`cdn-cloudfront` is a default feature.** It reuses the AWS signing stack
  the S3 disk and the SQS queue driver already carry and adds `quick-xml` for
  the distribution configuration; turn it off with `default-features = false`.

- **`LiveStreams::refresh` follows the shared topic rules** for cursor,
  fanout, scope, socket exclusion and rate, and
  `LiveStreamErrorKind::RuntimeUnavailable` also covers an unavailable
  configured publisher.

### Fixed

- **The MariaDB vector driver reads a quoted index distance.** MariaDB 12.3.3
  renders the vector index option as `` `DISTANCE`='cosine' `` in
  `SHOW CREATE TABLE`, where 12.3.1 rendered `DISTANCE=cosine`. The driver
  kept the quotes, saw a distance mismatch and refused every `similar` call;
  it now strips them (#216).
- **A savepoint rollback discards the callbacks of the work it rolls back.**
  Nested transactions and named savepoints in `DB::transaction` now record
  their after-commit and rollback callbacks under one lock with the savepoint
  they belong to, and each savepoint statement and its bookkeeping complete
  together even when the caller is cancelled. Before, a nested transaction
  rolled back to an enclosing savepoint could still run its after-commit
  callbacks when the outer transaction committed. A panicking callback no
  longer stops the callbacks after it.

- **The built-in driver honours the JPEG quality setting.** The OxideAV
  registry encoder ignored the quality option and wrote every JPEG at 75. The
  driver now calls the JPEG encoder directly with the pipeline's quality.
- **Two tools with one name in different crates now fail the build at link
  time.** Every `#[tool]` emits one marker symbol, `__suprnova_tool_` followed
  by the tool's name, so the linker reports a duplicate symbol that names the
  tool when two crates declare the same name. Before, such a duplicate was only
  refused when the application booted; that check stays as a second net. A crate
  that forbids unsafe code still builds its tools.
- **Tool schemas publish integer fields with their bounds and no JSON Schema
  format.** `schemars` wrote Rust's integer formats such as `uint64` and `int32`,
  which clients do not know: Claude Code logged `unknown format "uint64" ignored`
  for every such field, and strict clients reject the schema. The bounds carry
  the same information. The WebMCP browser schemas and the `tool-schemas.ts`
  file that `suprnova generate-types` writes follow the same rule.

## 4.5.1 - 2026-10-21

### Fixed

- **The locked dependency set no longer carries the webpki advisories
  RUSTSEC-2026-0381, 0382 and 0383.** `rustls-webpki` 0.103.16, `webpki-roots`
  1.0.10 and `webpki-root-certs` 1.0.10 replace versions whose bundled roots
  trusted distrusted emSign intermediates. Binaries built from the tag with
  `--locked`, the CLI among them, get the fixed versions.

## 4.5.0 - 2026-10-21

### Changed

- **Three public enums have new variants.** `Revocation` gains
  `DocumentRelationsBefore`, `RegistrationOutcome` gains `Unavailable` and
  `MetadataErrorKind` gains `TooManyBrowserTools`. A `match` over one of them
  with no wildcard arm no longer compiles. (#174, #167, #166)
- **Database search vector delivery now uses retryable claims.** Concurrent
  delivery reports an in-flight error, and a stalled vector call times out after
  45 seconds. (#202)
- **Search touches now report an error when a declared relation key is missing
  or cannot be read from the model.** (#203)
- **Eloquent counter updates now use the saved row to check search eligibility
  and invalidate cached pages.** (#198)
- **New starter kits offer more search results only when another accessible page
  is available.** (#196)
- **Successful search requests now bootstrap session and CSRF cookies for new
  clients.** Reuse them when reporting search clicks. (#195)
- **Event retries now resolve their original provenance before checking the
  target's current existence or access scope.** (#192)
- **Newly generated starter explanations retain every contributing history
  event.** Regenerate existing recommendations to refresh their stored
  provenance. (#193)
- **Starter recommendation reads load ranked candidates in bounded pages and
  load similarity histories only for selected peers and the viewer.** Custom
  search engines now need key lookups for starter reads, as they do for graph
  reads. (#194)
- **Quoted phrases now constrain semantic and hybrid searches using each
  engine's lexical phrase matching rules.** (#191)
- **Indexing and semantic queries now require the provider's model id and
  revision to match the generation.** Rebuild with `search:reindex` after
  changing models. (#187)
- **Worker boot now constructs configured search providers before validating
  searchable indexes.** (#188)
- **Configured search providers are now available inside application bootstrap
  hooks for server, worker and console processes.** (#199)
- **Qdrant now supports retained flush fences and index deletion through the
  search maintenance commands.** Flush fences use the configured tombstone
  lifetime. (#189)
- **Qdrant generation deletion can now resume from the dropping state while
  ordinary writes continue to reject that state.** (#190)
- **Qdrant hash lookups now retain the source version when skipping unchanged
  documents, preserving stale-write protection.** (#186)
- **Loading a searchable model without timestamps now reads its content and
  search version together.** Locking model reads keep their row locks until the
  version is loaded; ordinary reads use one SELECT on Postgres, MySQL and
  SQLite. (#178)
- **Saving a searchable model without timestamps now updates the search version
  carried by that same instance, including saves in an explicit transaction.**
  (#177)
- **Graph traversal now replaces earlier paths with stronger later paths,
  including when the node limit is full.** (#176)
- **`RecommendationRun` now exposes `ranking_digest`.** Apply the new
  recommendation migration when upgrading. (#175)
- **Custom graph stores must handle `DocumentRelationsBefore`, which removes
  stale relation facts while keeping the document node and its engagement
  edges.** (#174)
- **Serialized recommendation explanations now omit social and shared-engagement
  edge references.** Server-side explanations keep them for verification. (#173)
- **On MySQL and MariaDB, an email address now matches an account only when it
  equals the stored address after trimming and lowercasing.** Accent variants
  and other collation folds, such as `ss` for `ß`, no longer match at sign-in,
  password reset, email verification, passkeys or OAuth linking; Postgres and
  SQLite already compared exactly. A user who typed an unaccented form of an
  accented address types it exactly after upgrading. (#167)
- **`UserProvider` gained `rehash_password_for_sign_in(user, credentials,
  recorded_epoch)`, the rehash the session guard's `attempt` calls.** It checks
  the stored epoch and the verified hash, writes atomically and returns the
  snapshot it wrote. The default calls `rehash_password_if_required` only for a
  user without a credential epoch, so a custom provider that upgrades hashes on
  sign-in implements the new method; `once` and `logout_other_devices` still
  call the old one. The built-in Eloquent and database providers implement it.
  (#168)

### Fixed

- **Database search vector updates and deletions now release their SQL
  connection before calling the vector store, avoiding deadlocks on shared
  pools.** (#202)
- **Search touches now find parent keys even when a child hides or renames them
  in JSON output.** (#203)
- **Retiring a database search generation now removes list tables for attributes
  that have since been removed from the index definition.** (#201)
- **Database search now detects MySQL and MariaDB separately for each named
  connection, so generation tables use the correct collation.** (#200)
- **Incrementing or decrementing a counter now adds or removes search results
  when the new value crosses a model's indexing threshold.** (#198)
- **Starter kit notes search now stops offering more results at the accessible
  hit cap, even when more notes match the query.** (#196)
- **A first JSON search without a cookie now returns an impression that a later
  click from the same client can validate.** (#195)
- **Retrying a recorded recommendation event now succeeds after its target is
  deleted or its access scope changes.** (#192)
- **Starter explanations now include peers' shared-target events and all
  repeated positive events, so verification detects removed contributors.**
  (#193)
- **Reading a short starter recommendation list no longer loads the whole
  visible catalog, and still fills the list after filtering inaccessible
  targets.** (#194)
- **Semantic and hybrid searches now exclude documents missing required quoted
  phrases and refill filtered candidates to preserve result depth.** (#191)
- **Replacing an embedding provider with another model of the same dimensions
  now reports a rebuild error instead of silently mixing incompatible vectors.**
  (#187)
- **Workers with searchable models now start with an environment-selected HTTP
  or fastembed provider.** (#188)
- **Fresh starter kits can create the notes search generation with the
  configured provider during bootstrap.** Initialization failures now name
  likely causes. (#199)
- **Qdrant flushes now block delayed writes, including keys absent at the start,
  and deleting an index removes its collections and generation metadata.**
  (#189)
- **Pruning a retired Qdrant generation now removes its collection and metadata
  instead of failing after deletion starts.** (#190)
- **Unchanged Qdrant documents now keep their latest version, so delayed older
  removals cannot delete them.** (#186)
- **A concurrent save can no longer make a loaded search document carry a newer
  version than the row content it contains.** (#178)
- **A borrowed save no longer leaves a searchable model reporting its previous
  search version after the database has saved a new revision.** (#177)
- **Graph recommendations now use a stronger indirect route even when a weaker
  direct route reached the item first, and explain the route used.** (#176)
- **Recommendations created before an upgrade now obey the current peer minimum,
  and changing ranking settings refreshes unchanged users on the next full
  run.** (#175)
- **Editing a document now keeps its recommendation engagement signals while
  rebuilding declared relations, including when a document job is retried.**
  (#174)
- **Recommendation explanations no longer reveal which followed accounts engaged
  through edge keys that a client can recompute.** (#173)
- **Cancelling a text stream from a response callback now leaves its status
  clear, and callbacks cannot overwrite a replacement request's state.** (#184)
- **Event streams now stay open after a connection error so the browser can
  reconnect and continue receiving messages.** (#183)
- **Stream readers mounted together with the same id now share their text and
  callbacks in all three Inertia kits.** (#182)
- **Stream requests now use the fresh CSRF cookie after sign-in, so Inertia
  navigation no longer leaves them sending a stale token.** (#181)
- **Adding a source to a Content Security Policy now changes only the policy
  containing its directive, keeping other policies in the header unchanged.**
  (#180)
- **Live now announces interrupted actions to screen readers in the shipped
  browser bundles.** (#172)
- **A sign-up whose address collides with an existing account only under the
  database's looser comparison answers the same generic response as a registered
  address and creates nothing, instead of a conflict error.** (#167)
- **Schema watchers now report new form request refusals even when the generated
  file stays unchanged, without repeating unchanged refusals on every edit.**
  (#171)
- **Postgres schema dumps now remove entire multiline extension comments even
  when they contain semicolons, preventing invalid snapshots.** (#170)
- **Live components now reject more than 64 browser tools on the server,
  preventing oversized tool metadata from disabling ordinary clicks.** (#166)
- **Headless Live tools now report when their growing state no longer fits a
  follow-up request, so agents can restart instead of receiving an unusable
  handle.** (#165)
- **Concurrent fresh database migrations now recover when another migration
  creates the authorization server or agent auth tables first on Postgres.**
  (#164)
- **Concurrent agent assertions now share one provider key-set fetch, preventing
  unknown keys from triggering duplicate requests to the provider.** (#163)
- **Live tool actions now accept optional dates and date-times, and date-times
  in lists and maps, without failing before the action runs.** (#169)
- **Password resets now cancel password sign-ins already in progress, so an old
  password cannot create a new session after the reset.** (#168)
- **Agent tools now refuse guards that use a different user provider from the
  caller's default guard, preventing matching ids from signing in as another
  person.** (#160)
- **Built-in approval and agent claim forms now refuse agent tool submissions,
  even when the tool has your signed-in session and a valid form token.** (#161)
- **On MySQL and MariaDB, accent-insensitive email comparisons could let a
  different mailbox receive a magic link for another account.** Account lookups
  now require byte equality after trimming and lowercasing, and magic links go
  to the stored account address. Conflicting registrations return the same
  generic response without issuing a token. (#167)
- **On MySQL and MariaDB, an email change that differed only by accents could
  still receive a verification stamp for the old address.** Verification now
  checks the exact address atomically, so that change refuses the stamp. (#162)

## 4.4.0 - 2026-10-20

### Added

- **Handlers become agent tools with `#[tool]`.** A routed `#[handler]` marked
  `#[tool]` is a tool agents can call. `#[tool_input]` derives the input's
  JSON Schema (draft 2020-12) from the struct and its `serde` and `validator`
  attributes, so an agent is told what the server enforces. `tool_scopes!`
  declares scopes, and a `ToolCaller` argument tells the handler and its
  policies who is calling: a `public` guest, a `user` or an `agent` account.
  A tool call runs the route's middleware, validation, policies and rate
  limits, under per-caller and per-address budgets. An invalid or duplicate
  name, a missing description or an undeclared scope fails the build. See
  [Agents](agents.md).
- **An MCP endpoint serves the application's tools.**
  `Router::agents(AgentsConfig::new())` serves `POST /mcp` over MCP's
  Streamable HTTP transport, revision 2026-07-28, and to `initialize`-based
  clients of revisions 2025-06-18 and 2025-11-25, without sessions. It serves
  protected resource and authorization server metadata at the well-known
  locations under the application's root, lists every tool to a client
  without a token and only the tools a token may call to one with a token,
  runs `public` tools without a token, answers 401 and 403 with the scopes a
  call needs, so a client's first call of a tool that needs a token sends it
  to sign in, refuses a foreign `Origin`, and bounds the body, the answer
  and the run time. Structured results follow the session's revision: on
  2026-07-28 a tool's output schema and result pass through as declared, and
  on the two older revisions a non-object output schema is left out of
  `tools/list` and a non-object result comes back as text alone.
- **Users approve MCP clients through a built-in OAuth server.**
  `AgentsConfig::oauth_server(OAuthServer::new())` mounts the new Magnetar
  authorization server plugin: OAuth 2.1 with the authorization code grant and
  PKCE `S256`, clients identified by a client ID metadata document or dynamic
  registration, exact redirect URIs, tokens bound to the MCP endpoint and the
  approved scopes, refresh tokens rotated on every use, revocation, and tokens
  stored only as digests. Default approval and connected-agents pages ship,
  and `ConnectedAgents` lists and revokes a user's grants. Its issuer is
  `APP_URL`.
- **Tokens from an outside identity provider sign users in.** `OutsideIssuer`,
  added with `AgentsConfig::resolver`, accepts the user tokens a provider you
  name signs, checked against its published keys for issuer, audience, expiry
  and scope. It finds the user by `sub`, by an id the issuer assigns
  (`id_claim`, such as Microsoft Entra's `oid`) or by a claim the token marks
  verified.
- **Agents hold accounts of their own under auth.md.**
  `AgentsConfig::agent_auth(AgentAuth::new())` serves auth.md v0.6.0 from the
  new Magnetar agent auth plugin: anonymous, `service_auth` and ID-JAG
  registration, the `/auth.md` document, a claim page with a six-digit code,
  revocation by token and by Security Event Token, registration rate limits
  and audit events. A claim dispatches `AgentClaimed`, delivered at least once
  with a stable `event_id`. The `agents:key`, `agents:revoke-all` and
  `agents:prune` commands print a signing key, revoke every agent credential
  and run the maintenance pass.
- **Live actions can be agent tools, in the browser and headless.** `#[tool]`
  on a Live action offers it to agents, with fields marked `#[agent_visible]`
  as the result. The Live runtime registers a mounted component's tools with
  WebMCP. An action marked `headless` is also callable over MCP with no
  browser, through a sealed state handle bound to the caller; the Gate
  ability `live:{component}.mount` checks the mount properties an agent sends,
  and `#[resolve(...)]` fills a property from the caller instead.
- **Pages offer server tools to agents in the browser.**
  `Router::share_tools`, `with_tools` on a route, a group, an Inertia response
  or a Live document, and `PageTools::add` choose the tools each page
  registers with WebMCP. A page lists only the tools its viewer may call, a
  page of public tools stays shared in RenderCache, and the page refreshes its
  data after a write tool. With `WEBMCP_ORIGIN_TRIAL_TOKEN` set, every HTML
  response carries the `Origin-Trial` header.
- **The React, Vue and Svelte kits register page and form tools.** New
  projects call `installPageTools(router)` and ship `usePageTool`, for a tool
  that lives while its component is mounted, and `useFormTool`, which makes a
  form a tool that fills and submits it through Inertia. A destructive form is
  filled and left for the user to submit. `suprnova generate-types` writes
  each form request's input schema to `frontend/src/types/tool-schemas.ts`.
  The kits' `core.ts`, `suprnova-webmcp` and the Live runtime read a page's
  tools by the keys they know and ignore the rest, so a later release can add
  a field without breaking a scaffolded application. A change an older reader
  must not ignore raises the payload's `v`.
- **Rust front ends compiled to WebAssembly register WebMCP tools.** The new
  `suprnova-webmcp` crate registers typed page tools, with the input schema
  the server derives, for as long as their handles live, and calls the
  application's server tools with the session and the CSRF token. Built for a
  target without a browser it compiles and answers unsupported.
- **Tests call tools as any caller.** `TestClient::tool` and
  `TestClient::live_tool` call a tool as a page does, and `TestClient::mcp`
  calls the MCP endpoint as a guest, a user with chosen scopes or an agent,
  claimed or not, without an OAuth or auth.md ceremony. `Agents::fake` mints
  a token for a chosen caller, and `TestResponse::page_tools` reads the tools
  a page offers.
- **Test requests can come from an address and carry any body.**
  `TestClient::with_peer_address` sends requests as if from that TCP peer, so
  `Request::ip()` and limits keyed by the client address see it.
  `TestRequest::body` sends a body of any content type as it is.
- **Applications build their own consent pages on `AgentApprovals` and
  `AgentClaims`.** `AgentApprovals::of(&request)` reads the signed-in user's
  pending authorization as a `PendingApproval` and records the decision as an
  `ApprovalDecision`. `AgentClaims::of(&request)` reads a `PendingClaim` and
  confirms it with the user's code as a `ClaimConfirmation`. Both answer 403
  to a tool call, so an agent never approves or claims for the user it acts
  as. The framework's default pages use them too. `ConsentPageHeaders`
  refuses framing with `frame-ancestors 'none'`, and sets `no-store` and
  `no-referrer`, on every answer of a consent route, error pages included,
  and keeps the application's nonce policy.
- **`url::same_origin_path` checks a return address, and
  `Redirect::intended_url` reads the intended one.** `same_origin_path`
  accepts only a path that starts with a single `/` and holds no control
  byte, so a sign-in page checks a `return_to` with it before
  `Redirect::set_intended_url` stores it. `Redirect::intended_url()` returns
  the address `Redirect::intended` would follow, without spending it, as
  Laravel's `getIntendedUrl` does.
- **An application's migrator can create the agents tables and a
  case-insensitive email index.** `suprnova::agents::migrations()` creates
  both plugins' tables, only what is missing. Its rollback leaves them in
  place, and its documentation gives the statements that drop them.
  `suprnova::auth::migrations::UniqueEmailIgnoringCase::on(table, column)`
  adds a unique index on `LOWER(column)` on SQLite, PostgreSQL and MySQL
  8.0.13 or later. On MariaDB and older MySQL it checks that the column has a
  unique index of its own and a `_ci` collation. It refuses a table that
  already holds addresses that differ only in case, and its index name fits
  every engine's identifier limit.
- **Tests build a router with agent auth without a signing key.**
  `suprnova::testing::install_test_agent_auth_key()` gives the test process a
  generated key when the environment names none.
- **`#[tool_output]` and `#[tool_schema]` derive schemas through the
  framework.** `#[tool_output]` marks a tool's output type, any struct or
  enum, and derives `Serialize` and `JsonSchema` with no `serde` or
  `schemars` dependency of the application's own. `#[tool_schema]` gives a
  type nested in a tool's input or output its schema, and
  `suprnova_webmcp::tool_schema` does the same for a page tool's input.
- **Tools can carry WebMCP's `debugging` hint.**
  `#[tool(annotations(debugging))]` on a server tool or a Live action, the
  `debugging` option of the kits' `usePageTool` and `useFormTool`, and
  `PageTool::debugging` mark a tool meant for debugging and developer
  tooling rather than end users. The MCP endpoint does not send it.
- **New projects serve agents.** `suprnova new` writes a fresh agent auth
  signing key into `.env`, readable by its owner only (mode 0600), and
  `.env.example` names both variables with no value. Every kit serves the
  MCP endpoint, the OAuth server and agent auth from `src/agents.rs`, and its
  migrator creates both plugins' tables. The Inertia and Live kits' migrator
  also creates a case-insensitive unique email index, and their sign-in sends
  a signed-in user who opens a sign-in link on to a same-origin `return_to`
  and keeps the intended address through sign-in and registration. Every kit
  folds an email address to ASCII lowercase before validating it, and bounds
  names at 255 characters and addresses at 254.
- **The agents maintenance pass prunes the OAuth server's ended rows.** The
  five-minute pass in `serve` and `agents:prune` delete lapsed pending
  authorizations and codes, expired tokens, and grants revoked longer ago
  than the retention, whenever the router mounts the OAuth server, with agent
  auth or without. A live grant or token is never pruned. `agents:prune`
  needs agent auth only for `--retry-failed`.
- **The Inertia and Live kits ship their own approval, claim and
  connected-agents pages.** The React, Vue and Svelte kits render
  `Agents/Approve`, `Agents/Claim` and `Agents/Connected` at
  `/oauth/approve`, `/agent/claim` and `/connected-agents` on the consent
  facade, and an approval leaves for the client by a location visit. The
  Live kit serves the same three pages as plain server-rendered documents
  with native forms, and an approval leaves through a short page whose meta
  refresh and link go to the client, which `form-action 'self'` allows. Every
  route runs `ConsentPageHeaders`, no consent page offers a tool, and text a
  client, an agent or the user chose sits in `<bdi>`. See
  [Starter Kits](starter-kits.md).
- **The API kit serves agents, with a sign-in for consent only.** A new API
  project serves the MCP endpoint and both plugins with the framework's
  default pages. A browser signs in at `/login` only to approve a client or
  claim an agent: the session runs on the consent pages alone, ends after
  15 minutes idle, keeps its cookie for the browser session, and ends at
  `POST /logout`. `GET /api/connected-agents` lists the user's connected
  clients and agents, and `DELETE /api/connected-agents/clients/{grant}` and
  `/agents/{registration}` revoke one. Registration mails a link that
  verifies the address, which a claim needs, and
  `POST /api/email/verification-notification` mails a new one.
- **`Auth::email_verification()` verifies an address for its signed-in
  owner.** `issue` mints a single-use link token for the signed-in user, and
  `issue_for` one for an account the request just registered. The
  application mails the link. `verify` verifies the address only for the
  user signed in where the link opens, only while the account still holds
  the address the link was mailed to, and answers `Verified`,
  `AlreadyVerified`, `OtherAccount`, `AddressChanged`, `Expired`, `Unknown` or
  `SignIn`. Anyone can register another person's address with a password of
  their own, so a link that verified whoever opened it would verify that
  account. Verifying changes no credential and starts no session.
- **Consent pages refuse a form tool's submission.** A kit's form tool sends
  the form it submits with the `Suprnova-Form-Tool` header, which
  `suprnova::agents::FORM_TOOL_HEADER` names. `AgentApprovals::of` and
  `AgentClaims::of` refuse it with 403, as they refuse a tool call, so a form
  tool on an approval or claim page cannot approve or claim.
- **New projects ship two notes tools.** The Inertia and Live kits serve
  `search_notes` at `GET /notes/search` and `create_note` at
  `POST /notes/tools`, under the `notes:read` and `notes:write` scopes, each
  acting on the caller's own notes. The notes page offers both to an agent in
  the browser.
- **The Live input takes `maxlength`.** The component library's input sets
  the attribute only when a caller passes one. The Live kit's account forms
  bound the name at 255 characters and the address at 254.

- **`#[tool]` warns over WebMCP's budgets.** The build warns when a tool's
  name passes 30 characters, when its description passes 500, and when an
  input field has no description, and boot logs the same. The warnings never
  refuse a tool. A tool that keeps a long name on purpose sets
  `budget = ignore` in its marking, which quiets the build warning for that
  tool alone; boot still logs its budget warnings.
- **Live tools describe their arguments.** `arguments(amount = "How much to
  add.")` on a Live tool marking gives each action parameter the description
  an agent reads; an argument name the action does not have fails the build.
  A mount parameter takes a doc comment.
- **The Inertia frontends pin `webmcp-types`.** The React, Vue and Svelte
  kits' browser helpers use the community's `webmcp-types` 0.1.10 definitions
  for the model context, tool definitions and tool results.

### Changed

- **Tool names are identifiers.** A tool name is 1 to 64 ASCII letters,
  digits and underscores, so every model's tool calling accepts it; a name
  with a dot or a hyphen fails the build. The shipped tools are renamed verb
  first: `posts.create` is `create_post`, `notes.search` is `search_notes`.
  A browser instance of a Live tool joins the tool name and the instance key
  with a hyphen, and the whole fits in 64 characters: a root mount that does
  not fit fails at declaration, and the Live checker reports an island that
  does not. An application with dotted tool names renames them.
- **`MagnetarLifecycleEvent` and `LifecycleEvent` carry an `attributes`
  map.** Agent auth events record the registration, the client address and
  the fields auth.md names for each kind in it; it is empty for the other
  kinds. Code that builds either struct field by field, or destructures it
  without `..`, no longer compiles.
- **Three public enums have new variants.** `LifecycleEventKind` gains the
  nine agent auth audit kinds, from `AgentRegistrationCreated` to
  `AgentRegistrationRevoked`. `CryptPurpose` gains `LiveAgentHandle` and
  `HandlerArgKind` gains `Context`. A `match` over one of them without a
  wildcard arm no longer compiles.
- **The `agents` feature is on by default.** An application that keeps the
  framework's default features compiles the agent tools, the OAuth server and
  agent auth, and Magnetar's `migrate` creates their eight tables when it next
  runs. Nothing is served until the router calls `Router::agents`.
- **`generate-types` and `serve` write `frontend/src/types/tool-schemas.ts`.**
  The file holds the input schema of each form request, or an empty list,
  beside the Inertia props types. Each run brings it up to date and names
  each request it cannot describe exactly as the server does.
- **`Redirect::intended` follows only a path, an `http` or `https` URL, or a
  relative reference.** It ignores a stored value with another scheme, such
  as `javascript:`, `mailto:` or `localhost:3000/x`, and one with surrounding
  whitespace or a backslash anywhere, and redirects to its fallback instead.
  A browser trims whitespace and reads `\` as `/`, so such a value could
  leave the application. See
  [Storing the intended URL](responses.md#storing-the-intended-url).
- **An Inertia error page keeps a `no-store` the replaced response carried.**
  The error page set `Cache-Control: no-cache, private` on every page it
  rendered. It now sets `no-store` when the response it replaces said
  `no-store`, so a page that must not be stored stays unstored when it fails.
- **Magnetar's `auth_tokens` table gains an `address_digest` column.** A
  token that verifies an email address keeps the SHA-256 of the address it
  was mailed to. Magnetar's `migrate` adds the nullable column the first time
  it runs.
- **A custom Magnetar engine, store or token binding refuses email
  verification until it implements the new methods.**
  `MagnetarPasswordAuthEngine` gains `email_verification_issue` and
  `email_verification_verify`, `TokenStore` gains `issue_bound` and
  `inspect`, and `UserStore` gains `mark_email_verified_for`. `TokenFields`
  gains `read_address_digest` and `write_address_digest`. Each has a default,
  so existing code compiles, and the defaults refuse, so
  `Auth::email_verification()` fails closed until they are implemented.

### Fixed

- **Concurrent writes no longer fail on MariaDB 11.8 and later.** These
  releases turn `innodb_snapshot_isolation` on by default, under which a
  transaction that updates a row another transaction changed after its
  first read fails with error 1020, "Record has changed since last read",
  where MySQL waits and works on the latest row. Two overlapping writes to
  one table failed one of them with a 500, because each advances the
  RenderCache ledger, and two requests spending one email verification or
  password reset link at once could fail the losing request with a database
  error instead of answering that the link was used. Every connection the
  framework opens to MySQL or MariaDB now runs
  `SET SESSION innodb_snapshot_isolation = OFF` once, when it opens. A
  server without the variable, MySQL included, refuses it as unknown and
  the connection opens as before. The statement never fails a connection:
  any other refusal, as a MySQL-compatible proxy or service may give, is
  logged once per pool at `warn`, and the connection opens with the
  server's own setting. See
  [MySQL semantics on MariaDB](database.md#mysql-semantics-on-mariadb).
- **`DB::transaction_with_attempts` retries by the database's error code.**
  It re-runs an attempt the database refused with MySQL or MariaDB error
  1213, 1205 or 1020, or Postgres SQLSTATE 40001 or 40P01, and returns any
  other database error at once, even one whose message mentions a
  deadlock. It used to match the word "deadlock" in the message, so a lock
  wait timeout and MariaDB's error 1020 were never retried. An error with no
  database code is still matched by its message.
- **A Postgres schema dump loads where an administrator installed an
  extension.** `schema:dump` copied the comment an extension sets on
  itself, such as `COMMENT ON EXTENSION vector`. Loading that dump as the
  application's role failed with "must be owner of extension", because the
  extension belongs to the role that installed it. The dump now leaves those
  comments out, and `CREATE EXTENSION` sets them again.
- **Magnetar's tables hold long values on MySQL and MariaDB.** Byte
  columns were limited to 255 bytes. These hold passkey and OAuth sign-in
  steps, two-factor secrets and recovery codes, and saved provider tokens.
  So were the session user agent and the passkey credential id, public key
  and provider scope columns. A longer value failed to save, so passkey,
  two-factor and social sign-in could fail there. Magnetar's `migrate`
  widens the existing columns the first time it runs. It keeps each
  column's character set and collation, and leaves a column that an index
  covers alone, with a warning.
- **Two servers migrating Magnetar's tables at once no longer collide.** A
  table, index, column or marker that another process created first counts
  as created.
- **Registration answers a validation failure with 422.**
  `Auth::password().register` answered a weak password or an unusable
  address with 401. It now answers the framework's validation error, with
  the message under the field.
- **Email addresses longer than 254 characters never reach the database.**
  Sign-in with one answers as an unknown address does. Sign-up, the account
  import and OAuth email completion refuse one as a validation error. Such
  an address is still counted toward lockouts. An account that already
  holds one can no longer sign in by email; `migrate` logs how many exist,
  once per database.
- **Session metadata stays within its columns.** A session keeps at most
  1,024 characters of the user agent. A lockout records the client address
  only when it parses as an IP address.
- **New projects get every default feature of the framework.** A new
  project's `Cargo.toml` turns the framework's default features off and lists
  the ones it keeps. The list lacked `search-media` and `agents`, so a new
  project had neither media search nor agent tools. It now lists both.
- **A form request on GET or HEAD reads its query.** As Laravel validates the
  query of a GET, a form request on a GET or HEAD request without a body
  reads its query string as it reads a url-encoded body: it decodes,
  validates and names its fields as `request.query_into()` does. Such a
  request was refused with 415. A request with a body still reads the body,
  and other methods are unchanged.
- **Precognition and the real request read a query alike.** A query value
  holding a JSON object reads as that object where a struct or a map belongs,
  and stays text everywhere else, in Precognition, a GET form request and
  `request.query_into()`. Precognition decoded the object wherever it stood,
  so a route could pass Precognition and fail the real submission.
- **An `Option` Live mount parameter can be left out.** Every mount parameter
  was registered as required, and no codec decodes null, so an `Option<T>`
  parameter could never be `None`. It is now optional: left out or null, it
  mounts as `None`.
- **A page's scripts and styles no longer become the previous URL.** The
  session recorded any successful GET as the previous URL: a script or
  stylesheet that `StaticFiles` served, a request a global middleware
  answered before any route matched, and an AJAX request. Without a
  `Referer`, `Redirect::back()` could then send the user to a `.js` file. As
  in Laravel, the session now records a GET only when a route answered it,
  the fallback route included, and skips a request that sends
  `X-Requested-With: XMLHttpRequest`. A file that `StaticFiles` serves is
  never recorded.
- **Two uses of one email verification link at once no longer answer 500 on
  MariaDB.** MariaDB 11.8 and later end a transaction that writes a row a
  concurrent one changed, so the second of two concurrent uses of one
  Magnetar verification token answered 500. The losing use now reads the
  token as already used, on every engine. A consume the database ends in a
  deadlock or a serialization conflict runs again, up to three times, and
  answers a conflict rather than an internal error if every run conflicts.
- **Pages keep their styles under the Vite dev server.** In development,
  `SecurityHeaders` allowed the dev server in `script-src` and `connect-src`
  only, so the browser refused the stylesheet link the framework puts in the
  head, and a page under the balanced preset rendered with no styles. The
  dev server is now allowed in `style-src`, `font-src` and `img-src` as well.
- **A panic the panic hook reports carries its request.** A panic raised
  inside a request or job scope but outside the framework's own catch
  reached the tracker without the scope's request id, request, route and
  user, which an error reported in the same scope carries. It now carries
  them. The hook never waits on a lock the panicking thread may still hold:
  a field it cannot read at once is left out, and if the request's auth
  state is locked, the event names no user rather than a wrong one.
- **A panic reported while another report resolves its stack is kept.** The
  panic hook gave up the whole event when the symbol resolver was busy, so
  the one event a reporter exists for could vanish and only a counter said
  so. The hook now sends the event without frames and says so in its
  payload; the message, location, request and release all arrive.

## 4.3.0 - 2026-10-18

### Added

- **Searchable models can declare ordered media parts.** Path fields name an
  image, audio or video kind and a storage disk. Indexing loads bounded parts
  through Storage. Boot and settings sync reject incompatible model profiles.
- **EmbeddingGemma 2 can embed images, audio and video locally.** The media
  profile verifies both encoder graphs and their weights with the text model.
  Rust processors prepare image patches and WAV log-mel features. Video uses
  a host ffmpeg binary with a timeout. Reference fixtures run without ONNX.
- **A knowledge-graph recommender ranks from your own events and relations.**
  `RECOMMEND_ENGINE=graph` selects it. A queued rebuild derives a graph of
  shared engagement (stored only where `RECOMMEND_MIN_PEERS` actors agree),
  public engagement for the types `RECOMMEND_PUBLIC_EVENT_TYPES` lists, and
  relations declared with `Recommend::graph_relation`. Reads authorize every
  node and edge first, blend graph paths, stored vectors, followed actors'
  agreement, freshness, negatives and trust risk per surface with diversity
  caps, cite the evidence each row rests on, and answer with the starter's
  rows when the graph's support is thin.
- **The graph lives in your database or in Memgraph.** The `GraphStore` trait
  ships a `database` store and, behind the `graph-memgraph` feature, a
  `memgraph` store over Bolt. `recommendations:graph-rebuild` rebuilds the
  graph into a new generation and switches readers when it completes.
- **Search engines recommend and discover from their stored vectors.**
  `SearchEngine` gains `stored_vectors`, `recommend` and `discover`; Qdrant
  answers the latter two natively, and the database and collection engines
  fold their stored vectors. `Recommend::discover` steers a discover query by
  the viewer's own events. `SearchEngine::stored_keys` reports which documents
  a generation holds, so the graph engine leaves out a document that left its
  index; every shipped engine implements it, and a custom engine needs it to
  serve the graph engine.

### Changed

- **Recommendation, search and explanation structs carry new fields.** `RecommendConfig` gains the graph settings and
  `min_peers`, `SearchConfig` gains `media_max_bytes`, `IndexTimeSettings`
  gains `embed_media`, and `RecommendationExplanation` gains `engine`,
  `evidence` and `fallback_reason`. Code that builds one of them field by
  field without `..Default::default()` no longer compiles.

### Fixed

- **A starter suggestion stands on at least three peers.** The starter engine kept a
  collaborative candidate a single peer contributed, and its explanation
  showed a peer count of 1 beside the shared item, which points at that
  person; the candidate was one of their own views or purchases.
  `Recommend::for_user` and `Recommend::similar_to` now count a collaborative
  candidate only when `RECOMMEND_MIN_PEERS` distinct peers contribute it,
  default 3. With fewer, it can still arrive through the affinity, popularity
  or recent tier, which names no peers.
- **A model without `updated_at` keeps a search version per row.** A searchable model without
  `updated_at` carried version 0 in every document, so a recommendation event
  or a graph fact could not tell one revision of the row from the next. Each
  save now raises a version kept in the new `search_source_versions` table, in
  the save's own transaction, and Eloquent loads the kept versions with the
  rows, so `to_search_document()` returns the row's version without a query of
  its own. Run your migrations: the table comes with
  `suprnova::search::migrations()`.
- **A local embedding model keeps its memory bounded on long documents.** The `fastembed`
  provider padded every text in a batch to the batch's longest, and attention
  memory grows with the square of that length, so one long document among
  short ones could take a single inference call past 24 GB. It now measures
  each text with the model's own tokenizer and batches texts of similar
  length: `SEARCH_EMBED_BATCH` counts texts of 512 tokens, a longer text takes
  the room of several by the square of its length, and a text longer than
  that runs alone.

## 4.2.1 - 2026-10-16

### Added

- **Add a source to a preset's Content-Security-Policy (#156).**
  `SecurityHeaders::csp_source(directive, source)` and
  `ContentSecurityPolicy::with_source(directive, source)` add one source to a
  directive of the policy `from_env` selected, keeping the preset, its
  report-only mode and its reporting origins. A directive the policy leaves
  out starts from the sources it falls back to. An application that allows an
  analytics host in `connect-src` no longer copies the preset's policy string.
- **Stream hooks in every Inertia kit.** New React, Vue and Svelte applications
  get `frontend/src/lib/stream/`, Suprnova's own client for the responses
  `HttpResponse::stream_bytes`, `stream_json` and `event_stream` send:
  `useStream`, `useJsonStream`, `useEventStream` and `useJsonEventStream`, with
  the names, options and results of Laravel's stream packages. They send the
  CSRF token from the root template's meta tag or the `XSRF-TOKEN` cookie, and
  cancel their request when the component unmounts. An existing application
  can copy the two files from a new scaffold of its kit.

### Fixed

- **`View::share` reaches the Inertia root template (#157).** The root
  template rendered without the data shared with every view, so a value
  shared with `View::share` or `View::share_for_request` never reached it,
  where Laravel's shared data reaches `app.blade.php`. It now reads them with
  Askama's `value` filter, as other views do:
  `{% if let Ok(domain) = "plausible_domain"|value::<String> %}`. Keep such a
  read inside the `if let` unless every deployment shares the value, since a
  missing value fails the render.

## 4.2.0 - 2026-10-16

### Added

- **Model search.** `Searchable` and the typed `Model::search` builder provide
  native database, Qdrant, collection and null engines, filters, facets,
  highlights, scopes and generation rebuilds. Hybrid search uses fastembed
  or OpenAI-compatible HTTP embeddings, with EmbeddingGemma 2 as the default
  local model. Opt-in analytics, query suggestions, JSON search and click
  routes, the Live search-box, the kits' notes search and a judged relevance
  and latency baseline complete the search surface.
- **Starter recommendations.** `Recommend` records immutable, deduplicated
  events and reads scoped collaborative recommendations with affinity,
  popularity and recent-document fallbacks. Completed runs carry projected
  explanations, metrics and event provenance; commands generate snapshots,
  report status and apply application-owned retention.
- **Opt-in local search inference.** The `search-fastembed` feature enables
  local embeddings, sparse models and reranking. It is off by default; its
  `ort` build script downloads ONNX Runtime at compile time. The default
  search build downloads nothing.
- **pgvector driver.** `PgVectorDriver` joins the vector drivers behind the
  `vector-pgvector` default feature: a Postgres application stores and
  searches embeddings in its own database.
- **Search pages in RenderCache.** A search on a cached route is stored like
  any other render and goes stale when one of its indexes changes: a document
  write or removal, a generation switch or a settings sync. Viewer-scoped and
  analytics searches are never stored, and `without_render_cache()` keeps one
  search out of the cache.

### Fixed

- **`Head::canonical()` keeps a `//` request path on the app's origin (#155).**
  A request for `//evil.example/x` gave a canonical link to another host. The
  head now takes the request URL as `url::current` builds it,
  `https://example.com//evil.example/x`, under the public root.
- **Inertia kits paint styled under the Vite dev server (#153).** The kits
  list `src/app.css` as its own Vite entry, so the first server-rendered page
  loads it as a `<link>` with the request's nonce instead of waiting for the
  entry's JavaScript. `main.ts` and `main.tsx` no longer import it. In an
  existing application, add `.entry_points(["src/app.css"])` to its
  `InertiaConfig`, add `'src/app.css'` to the Vite build `input`, and remove
  the import.
- **The CLI installs on macOS without warnings (#152).** The browser
  certificate store helpers that only the Linux install path uses are now
  compiled on Linux only.
- **Public responses no longer carry the session or `XSRF-TOKEN` cookie
  (#154).** A response marked `Cache-Control: public` or given an `s-maxage`
  could be stored by a CDN or caching proxy with its `Set-Cookie` lines and
  replayed to other visitors. The session and CSRF middleware now leave off
  the cookies the reader already holds; a public response that must deliver a
  cookie, such as a new session or a rotated remember-me cookie, goes out
  `private, no-store` instead.
- **The reset email greets the user by name under Magnetar.**
  `PasswordReset::send_link` now looks the account up and greets its name, as
  the verification and password-changed emails do. A failed lookup sends the
  plain greeting and logs a warning.

## 4.1.0 - 2026-10-15

### Added

- **Error reporting through Sentry-compatible trackers.** `Reporter` drivers
  send scrubbed errors to Rustrak, Sentry or GlitchTip, with bounded background
  delivery and shutdown flushing. Laravel-shaped helpers and exclusions cover
  handled errors; requests and background work share the reporting path. Logs,
  traces and browser reporting are opt-in. The CLI offers local Rustrak, and
  the [reporting chapter](error-reporting.md) documents setup and privacy.
- **Security headers with per-request CSP nonces.** `SecurityHeaders` provides
  strict, balanced and relaxed presets, validated environment configuration,
  report-only CSP and violation reporting, HTTPS-only HSTS, and route or group
  overrides. New full-stack projects register it before every other global
  middleware; existing applications opt in by registering it. The manual
  covers every header and the [upgrade guide](upgrade-4.1.md) shows the
  registration.

### Fixed

- **Framework scripts and asset links share the request's CSP nonce.** Inertia
  documents and error pages, Vite tags, Head links and scripts, Live bootstrap
  assets and stitched RenderCache hits use the nonce the middleware generated.
  The document exposes it to Vite and Inertia's client through the `csp-nonce`
  meta element. Complete nonce pages render on every request.
- **The Live starter's Name boxes show the right name.** The register form's
  Name box started with the word "name", and the profile form showed "name"
  instead of the user's display name, so saving it unchanged renamed the
  user. Both now read the component's own field.
- **Live component libraries cannot change the application's error
  handling.** The component scan admitted `Exceptions::reportable`,
  `dont_retry` and `dont_retry_when`, so a library could change how the
  application handles errors and hide its own failures from the error
  tracker. `live:add` now refuses a library that names them, the reporting
  exclusions or `Request::csp_nonce`; reporting an error stays allowed.

## 4.0.4 - 2026-10-15

### Fixed

- **A fresh Inertia starter app hydrates its first page without a mismatch.**
  The React, Vue and Svelte kits loaded their Fluent catalog only in the
  browser, so with server-side rendering, on by default since 4.0.0, the
  server rendered the raw `welcome` key and the browser the translated
  heading, and React reported a hydration error. New projects render the
  same heading from the title prop in both places.
- **A field shows its own validation message.** The Live response named each
  issue by its message identifier alone, so a `live:error` output under a
  rejected field read the runtime's generic "Validation failed" while the
  text a `#[validate(message = "...")]` rule or the validation catalog
  provides never reached the page. The server now resolves that text in the
  request's locale and sends it beside the identifier, and the field's error
  output shows it. An issue without text, such as a value the field cannot
  decode, keeps the generic announcement.
- **A user who changes their own password stays signed in.** The session
  that made the change recorded the password's earlier epoch, so the check
  that ends sign-ins from before a password change ended it too on its next
  request, with every other session of the user. A request that resolved
  the signed-in user and writes that user's password column through the
  model (`save`, `update`, and their transactional forms) now binds its
  sign-in to the epoch of the values sent to storage once the write
  commits, so that session continues while every other session and
  remember-me cookie of the user still ends. `EloquentUserProvider`
  recognizes the written model; a provider of your own implements
  `UserProvider::written_user` to do the same, and a model whose hash lives
  in another column names it from `Authenticatable::auth_password_name`. A
  write that bypasses the model, such as a query-builder update, is not
  seen.
- **A fresh scaffold is rustfmt-clean.** `suprnova new` wrote the shared
  backend templates, the Live kit and the API starter in a layout rustfmt's
  2024 style edition rewrites (import order and line wrapping), so a
  developer's first `cargo fmt` changed files they had not touched. The
  templates now carry that layout, and a test formats a fresh scaffold of
  every kind with `cargo fmt --check`.
- **The account's own ImageMagick policy applies again.** The magick driver
  starts ImageMagick with `HOME` naming its policy directory, which hid the
  service account's `~/.config/ImageMagick` from its runs, so a policy or
  configuration the operator kept there stopped applying in 4.0.0. The
  driver now puts that directory (`$XDG_CONFIG_HOME/ImageMagick`, else
  `$HOME/.config/ImageMagick`) on `MAGICK_CONFIGURE_PATH` after the
  operator's value and before its own directory's last entry: the
  account's denials and configuration apply as before, and the framework's
  policy is still the last ImageMagick reads.
- **The framework's frames below a Live action fit Tokio's default stack.**
  In a debug build the server, the after-response and task-local wrappers,
  the session middleware and the Live engine used about 1.75 MiB of stack
  before an action ran, so an action a little deeper overflowed a thread
  with Tokio's 2 MiB default. The request future is now boxed before each
  wrapper holds it, as are the Live dispatch and the session handler, and
  those frames use under 0.8 MiB. A test runs a Live action through the
  real server on a thread with the 2 MiB default and fails when the frames
  below the action pass 1 MiB.
- **The scroll area's size token is defined.** 4.0.2 bounded the region
  with `--sn-scroll-area-size` and left the token undefined, so the shared
  stylesheet never named it and the engine's token check failed. The shared
  stylesheet now defines it at 16rem; a page or a region still sets its own.

### Changed

- **Starter kits ship no translations.** React, Vue, Svelte, Live and API
  scaffolds include no catalogs, browser translation modules or locale
  middleware, and their pages render English text. The framework's
  localization is unchanged. An existing application keeps its own files;
  one that translates in the browser under server-side rendering renders
  raw keys on the server, and the upgrade guide shows the two ways out:
  remove the browser translations as new projects do, or translate on the
  server with `Lang::get` and pass the text in props.

## 4.0.3 - 2026-10-13

### Fixed

- **Breadcrumbs sit on one line.** The base stylesheet spaces stacked list
  items with a top margin, which dropped every crumb after the first below
  the first in `suprnova.breadcrumbs`. The crumbs now carry no margin and
  the row aligns them on the baseline.
- **Avatar group members sit on one row.** The same list-item margin
  dropped every member after the first in `suprnova.avatar`; the members
  now carry only their overlap.

## 4.0.2 - 2026-10-13

### Added

- **A flash region can time its messages out.** `flash_region` takes a
  `duration` in milliseconds; a region rendered with one hides each message
  that long after it appears and holds the timer while the pointer or focus
  is on the region, as the toast region does. The default, 0, keeps every
  message until the next document. The region is now wrapped in the
  `sn-flash-region` element on every branch, which does nothing without a
  duration.

### Fixed

- **The horizontal separator has a width inside a grid or flex parent.**
  A browser's own `hr` carries auto inline margins, which took the free
  space of the track and left `suprnova.separator` no width at all; the
  rule now sets them to zero.
- **The scroll area scrolls.** `suprnova.scroll-area` bounded its block
  size by the measure token, about 640px, so most content fit without a
  scrollbar. The bound is now 16rem, and a page sets
  `--sn-scroll-area-size` on the region or an ancestor for another.

### Changed

- **The tooltip bubble follows the color scheme.** `suprnova.tooltip` drew
  its bubble in the text color with inverse text, a light bubble on a dark
  page. It now sits on the surface tokens with the border and shadow the
  popover and the dropdown menu use, so it re-themes with them.

## 4.0.1 - 2026-10-13

### Fixed

- **The validation summary shows only while a field or the action is in
  error.** `suprnova.validation-summary` rendered its red box and title on
  a form nobody had submitted, and listed nothing after a failed one: its
  stylesheet hid the section only when it was empty, and the macro always
  wrote the title inside it. The section now hides until one of its entries
  shows. The new `summary_entry(name, label)` macro, called inside the
  summary, renders one entry per field the action validates: hidden until
  that field's validation fails, then a link that focuses the field. The
  action's own failure shows as the last entry, announced politely. A
  summary called with no entries still shows the action's failure.


### Added

- **The artisan generators.** Twenty-one `suprnova make:*` commands each
  write one file from a stub and declare its module in `src/lib.rs` and the
  directory's `mod.rs`: `make:factory` (a `Factory` for a model, in
  `src/factories/`), `make:seeder` (a `Seeder`, `src/seeders/`), `make:cast`
  (a `Cast`, `src/casts/`), `make:channel` (a private broadcast `Channel`,
  `src/broadcasting/`), `make:class` (a plain struct, `src/`), `make:enum`
  (`src/enums/`), `make:event` (an `Event`, `src/events/`), `make:listener`
  (a `Listener` of one event or any event, `src/listeners/`), `make:job` (a
  queued `Job`, `src/jobs/`), `make:job-middleware` (a `JobMiddleware`,
  `src/jobs/middleware/`), `make:mail` (a `Mailable`, `src/mail/`),
  `make:notification` (a mail `Notification`, `src/notifications/`),
  `make:observer` (an `Observer` of a model, `src/observers/`),
  `make:policy` (a `#[policy]` with the seven model abilities,
  `src/policies/`), `make:provider` (the `register` function the bootstrap
  calls, `src/providers/`), `make:resource` (a JSON:API `Data` struct,
  `src/resources/`), `make:rule` (a validation `Rule`, `src/rules/`),
  `make:scope` (a `GlobalScope`, `src/scopes/`), `make:test` (an integration
  test in `tests/`, which declares nothing), `make:trait` (a trait with a
  default method, `src/concerns/`) and `make:interface` (a trait with
  required methods only, `src/contracts/`). A name that is not a Rust
  identifier is refused with exit status 1, an existing file is kept unless
  `--force` is given, and each command prints the path it wrote.
  `make:factory`, `make:observer`, `make:policy` and `make:scope` take
  `--model`, and `make:listener` takes `--event`.
- **The Live starter kit.** `suprnova new --frontend live`, or the fourth
  choice of its prompt, scaffolds an application with no Node toolchain: no
  `frontend/`, no `package.json` and no Vite config. Its pages (home,
  register, sign in, forgot and reset password, verify email, the
  dashboard, the notes list and one note, and the error page) are
  server-rendered Live documents in a guest layout or an application layout
  with the navigation, the signed-in user and the toast. Live components
  carry the account forms, which show each validation message under its
  field; the dashboard's note counts, which refresh without a page load
  when a note is saved; the display-name form; and the notes page, with a
  search bound to the URL's `?search=`, a form that writes a note, and a
  load-more list. The kit keeps the Inertia kits' models, migrations,
  account flows and route names, and installs the library components its
  views import under `templates/suprnova-ui/`, recorded in `suprnova.toml`.
  `suprnova docker:init` writes a Live project a Dockerfile with no Node
  stage, and `suprnova make:inertia` refuses in one.
- **MongoDB connections.** The `database-mongodb` feature (off by default)
  adds the `Mongo` facade on the official `mongodb` driver: `MONGODB_URI` and
  `MONGODB_DATABASE` (or `MongoConfig::builder()`, with pool options and
  named connections) configure it, the server and the workers register it at
  boot, and `Mongo::connection`, `connection_named`, `database`,
  `collection::<T>` and `ping` reach it. A missing or malformed URI is an
  error naming `MONGODB_URI`, and an unreachable server fails the first call
  that needs it with a `FrameworkError`.
- **MongoDB queue.** With `database-mongodb`, `QUEUE_DRIVER=mongodb` keeps
  jobs in a `jobs` collection (`MongoQueueDriver`), reserving each with one
  atomic `findOneAndUpdate`, and brings `MongoFailedJobStore` over
  `failed_jobs` and `MongoBatchRepository` over `job_batches`, whose
  settlements move the counters with `$inc` in one update and count a
  redelivered job once.
- **MongoDB cache.** With `database-mongodb`, `CACHE_DRIVER=mongodb` selects
  `MongoCache` over the `cache` and `cache_locks` collections, with TTL
  indexes on the expiry, atomic `add` and counters, tags, and locks shared
  by every process.
- **MongoDB sessions.** `SESSION_DRIVER` selects the session store:
  `database` (the default) or, with `database-mongodb`, `mongodb`, which
  keeps sessions in a `sessions` collection (`MongoSessionDriver`) and
  promotes a two-factor session with one atomic update. `Config::init`
  refuses an unknown `SESSION_DRIVER`.
- **MongoDB document models.** `#[suprnova::document(collection = "...")]`
  stores a struct in a collection with the Eloquent calls of the
  `DocumentModel` trait: `create`, `find`, `find_or_fail`, `all`, `query`,
  `save`, `update`, `delete`, `fresh`, `refresh`, `make` and `fill`. The key
  is an `ObjectId` stored as `_id` unless `primary_key` names a field;
  `fillable`, `guarded`, `casts`, `hidden` and `visible` take the `#[model]`
  syntax; `chrono` dates are stored as BSON datetimes and decimals as
  `Decimal128`; `created_at` and `updated_at` are managed; `soft_deletes`
  adds `with_trashed`, `only_trashed`, `restore` and `force_delete`;
  `#[embeds_one]` and `#[embeds_many]` fields store embedded documents with
  relation methods; `push`, `push_unique`, `pull`, `increment` and
  `decrement` change one field; the model events reach listeners and a
  `DocumentObserver` registered with `#[suprnova::observer]`; and the model
  serializes through serde and binds from routes by its key.
- **MongoDB document queries.** A document model's `query()` answers a
  `DocumentQuery` with `where_` (`=`, `!=`, `<`, `<=`, `>`, `>=`, `like`),
  `or_where`, `where_in`, `where_not_in`, `where_null`, `where_not_null`,
  `where_between`, `where_date`, `where_exists`, `where_raw`, `order_by`,
  `skip`, `take`, `project`, `get`, `first`, `count`, `exists`, `pluck`,
  `distinct`, `sum`, `avg`, `min`, `max`, `paginate`, `simple_paginate`,
  `update`, `upsert`, `delete`, `force_delete`, `increment`, `decrement`,
  `push`, `pull` and `unset`, and `group_by` with `count`, `sum`, `avg`,
  `min` and `max` aggregates. `to_filter()` and `to_pipeline()` answer the
  BSON the builder sends, and a chain MongoDB cannot run as written, such as
  `take` before `update`, is an error naming the call.
- **MongoDB relations.** `relations = { ... }` on `#[suprnova::document]`
  declares `HasOne`, `HasMany`, `BelongsTo` and `BelongsToMany` between
  documents (the many-to-many kept as arrays of keys on both sides, written
  by `attach`, `detach`, `detach_all` and `sync`) and `BelongsToModel<M>` to
  an SQL model, and `#[suprnova::model]` declares `HasManyDocuments<D>` and
  `HasOneDocument<D>`; each reads through its own store, `DocumentQuery::with`
  and the SQL `with` and `with_count` load them with one query per relation,
  dotted paths cross the stores, and a relation whose key types cannot match
  fails the build naming both models.
- **Concurrent tasks.** The `Concurrency` facade runs `#[concurrent_task]`
  functions (an `async fn` with serde input and output, registered by name)
  side by side: `run` answers each `TaskResult` in order, `run_named` answers
  them by key, `with_timeout` ends a task that outlives it with an error
  naming it, and `driver` picks a driver for one call. The `tokio` driver
  (the default), the `process` driver (each task in a console process through
  the hidden `concurrency:run` command) and the `sync` driver implement
  `ConcurrencyDriver`; `CONCURRENCY_DRIVER` selects the default, and
  `Concurrency::extend` adds a driver.
- **Deferred concurrent tasks.** `Concurrency::defer` returns at once and runs
  its tasks after the response has been sent, logging a failed task without
  touching the response; outside a request the returned handle runs them when
  it is awaited or dropped.
- **A guard in use per request.** `TestClient::acting_as_with_guard` selects
  the named guard as the one `Auth::user`, `Auth::id`, `Auth::check` and the
  auth middleware without a guard name answer through for that request, as
  Laravel's `actingAs` with a guard calls `shouldUse`; the configured default
  guard is untouched outside that request.
- **One guard instance per request.** Inside a request the auth manager builds
  one instance per guard name and keeps it, so a custom guard's factory runs
  once per request and a guard may keep its user on the instance.
- **Factory record batches.** `create_many` accepts a count or per-record
  attribute maps, with each map overriding the factory definition.
- **Custom ULID lengths.** `ulid_with_length` and the `length` modifier
  create ULID columns with the length your schema needs.
- **Schema SQL previews.** `Blueprint::create_sql` returns the validated
  CREATE statements for your selected database engine.
- **Seeder composition.** `call` runs children in order with console progress;
  `call_silent` suppresses progress and `call_once` skips completed children.
- **Seeder parameters.** `call_with` passes an attribute map to `run_with`
  while existing `run` implementations keep working.
- **Root seeders.** `register_root` selects the seeder a bare `db:seed` runs.
- **Seeder connection selection.** `db:seed --database` scopes default
  queries and factories to the named connection for the invocation.

- **Conditional resource field groups.** `merge_when` merges an object into
  resource attributes when its condition holds, with sparse fieldsets applied
  to the merged fields.
- **Relation existence flags.** `with_exists` loads a boolean per parent
  without loading related models, alongside any requested rows or counts.
- **Resources read existence flags.** `when_exists_loaded` emits loaded true
  and false values and omits fields whose flag was not loaded.
- **Application-wide JSON:API information.** `jsonapi_default` sets boot-time
  implementation information for every resource document; a response can override it.
- **Cursors over several columns.** Cursor pages preserve each ordered column
  and direction, with named typed boundaries available through `Cursor::parameter`.
- **Page item transformations.** `through` changes a length-aware, simple or
  cursor page's item type while preserving all pagination metadata.
- **Missing-row messages on query builders.** `first_or_fail` names the model
  or table, and `first_or_fail_with` accepts your message while keeping HTTP 404.
- **Nested closure transactions.** Inner `DB::transaction` calls use savepoints;
  an inner rollback keeps the outer transaction open.
- **Transaction depth.** `DB::transaction_level()` reports the ambient nesting level.
- **Rollback callbacks.** `DB::after_rollback` runs compensation for the enclosing
  rollback and preserves callbacks from successful inner scopes until the outer outcome.
- **Guards before transactions.** `DB::before_starting_transaction` runs listeners
  before BEGIN or a savepoint and propagates a listener's error without starting it.
- **Raw query expressions.** `DB::raw` supplies SQL for updates, grouping and
  aggregate filters while ordinary values and raw-fragment bindings stay bound.
- **Table query ranges.** `where_between`, `where_not_between` and their OR forms
  accept inclusive bounds, raw expressions and scalar subqueries.
- **Table query maximums.** `max` reads typed values and returns none for an empty set.
- **Table queries ordered by age.** `oldest` and `oldest_by` order rows ascending.
- **Seeded random query ordering.** `in_random_order()` orders rows randomly on
  both builders, and `in_random_order_seeded(seed)` repeats an order with RAND(seed)
  on MySQL and setseed with random() on Postgres; SQLite orders by a seed-derived expression over each row's `rowid`, then by the `rowid`, on both builders, so the same seed repeats the order for any primary key type, a union and its pages included.
- **Inspect applied model scopes.** `apply_scopes` returns the builder with
  its registered global scopes and soft-delete filter applied once.
- **Polymorphic existence queries.** `has_morph`, `doesnt_have_morph` and
  their constrained forms query the relation's targets and registered types
  and aliases; the wildcard covers the targets the relation declares, and
  wildcard absence includes rows with a null type.
- **Delete loaded pivots by their keys.** Pivots without an `id` delete
  their original key pair; morph pivots also keep the type in the predicate.
- **Eager limits apply per parent.** Has-one, has-many, morph-one and
  morph-many constraints use a partitioned window for `limit` and `take`.
- **Morph relations fill ownership on writes.** `create`, `save` and
  `upsert` set the owner's id and type on morph-one and morph-many children.
- **Loaded model lookup by key.** Collections find one model, another model's
  key, or several keys, and return a supplied fallback for a missing key.
- **Constrained loading on model collections.** `load_with` loads a relation
  onto existing models with a typed builder constraint.
- **Model collection deduplication by key.** `unique_models` keeps the last
  copy of each model while retaining the first occurrence's key order.
- **Model collection differences by key.** `diff_models` removes matching
  identities even when the models' other attributes differ.
- **Enum collection casts.** `AsEnumCollection` reads and writes JSON arrays
  of the same variant strings as `AsEnum`.
- **Runtime appended attributes.** `append` selects registered accessors
  for every later conversion of one model instance.
- **Complete raw original snapshots.** `get_raw_originals` returns every
  loaded column before casts; `get_raw_original_or` supplies absent values.
- **Instance visibility changes.** `make_hidden`, `make_visible`, and their
  conditional forms update the lists used by later model conversions.

- **A single-server default for scheduled tasks.** `Schedule::always_on_one_server()`
  elects one replica per tick for every task; `.on_every_server()` opts out.
- **Interrupt running schedules.** `schedule:interrupt` writes a shared cache
  mark. Runs stop before starting another task, and the next run clears it.
- **Stored keys for chunk cursors.** `chunk_by_id` advances from the raw stored
  key, so primary-key casts cannot skip or repeat rows.
- **A database default scoped to one task.** `DB::with_default_connection(name, future)`
  routes default database and model queries to that pool. `DB::default_connection()`
  names the current pool, and concurrent tasks keep their own defaults.
- **Declared model defaults.** `#[model(defaults(field = value, ...))]` fills new
  instances and partial creates while preserving supplied attributes.
- **Related records map in chunks.** `chunk_map` on belongs-to-many and
  through relations maps each record in bounded batches and returns values
  in order, with pivot context on many-to-many records.
- **Related records are found or created with their keys.** `first_or_create`
  on has-one, has-many and belongs-to-many sets the relation's foreign key
  or attaches the pivot row, including custom relation keys.
- **Relation counters create or increment.** `increment_or_create` on
  has-one, has-many and belongs-to-many uses the default for a new record
  or adds the supplied step and extra columns to an existing record.
- **Through relations return an unsaved fallback.** `find_or_new` searches
  the relation's reachable records and returns a new instance when none match.
- **Has-one-through compares in one query.** `is` asks the database whether
  the relation reaches a model without loading the target.
- **Queue worker idle delays.** `queue:work --sleep` sets the seconds between
  empty polls beside the existing millisecond `--poll` option.
- **Queue worker attempt controls.** `--tries` and `--timeout` set a worker's
  attempt budget and timeout without changing the queued payload.
- **Queue workers with a stopping point.** `--once` settles one job and
  `--stop-when-empty` drains available jobs before the worker exits.
- **Queue worker memory limits.** `--memory` checks resident memory from
  procfs after each job and returns status 12 when it exceeds the limit.
- **Filtered queue absence assertions.** `assert_not_pushed` rejects a
  captured job that satisfies your predicate.
- **Filtered queue assertions.** `assert_pushed_on_queue` matches the queue
  and your predicate against the same captured job.
- **Commands after the response.** `Bus::dispatch_after_response` runs a
  command after the response body is written and the socket flush succeeds.
- **Typed bus capture lists.** `dispatched`, `dispatched_sync` and
  `dispatched_after_response` return captured commands for iterator filters.
- **Markdown responses.** `HttpResponse::markdown` and `markdown` preserve
  your source with a UTF-8 Markdown content type.
- **QUERY routes.** `query!` and the fluent routing methods accept QUERY,
  and `any!` includes it with the other supported methods.
- **Sign out your other devices.** `Auth::logout_other_devices` verifies your
  password and revokes other sessions and remember credentials while keeping
  the current browser signed in.
- **Typed notification assertions.** The notification fake filters recorded
  notifications by concrete type, recipient route, and notification contents.
  Existing name-based assertions keep working.
- **Copy files across disks.** `Storage::copy_to_disk` streams between disk
  names or ready-made disk handles and keeps the source.
- **Move files across disks.** `Storage::move_to_disk` copies the file before
  deleting the source and reports transfer or deletion failures.
- **Forget several disks.** `Storage::forget` accepts one name or a list and
  reports whether any registered disk was removed.
- **Purge one disk or every disk.** `Storage::purge(name)` drops one named disk
  and `purge_all` drops every disk.
- **Store a ready-made disk.** `Storage::set` registers an operator under a
  name and replaces the previous disk and its public URL.

- **Language-specific slugs.** `Str::slug_in` applies the named language's
  ASCII spelling, including German `ä` as `ae`.
- **Word limits keep markup.** `Str::words` limits space-separated runs
  while retaining markup and whitespace between words.
- **Esperanto and Italian word forms.** Plural and singular helpers now
  use all eight languages from doctrine/inflector, selected by the current
  locale.
- **Plurals for class names.** `Str::plural_studly` and `Str::plural_pascal`
  inflect the last word of a class name.
- **Counted labels use exact integers.** `Str::plural_with_count` adds
  the count in the current locale's number format, preserving every digit.
- **Redis environment connections.** With `REDIS_URL` unset, the default
  connection reads `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, and `REDIS_DB`.
- **A cache connection for Redis.** The `cache` connection uses the same
  server and credentials with `REDIS_CACHE_DB`, defaulting to 1.
- **Redis scripts by SHA.** `RedisConnection::evalsha` runs a loaded script
  with prefixed keys and unchanged script arguments.
- **Raw Redis command lines.** `RedisConnection::execute_raw` sends a command
  line with the existing read retry policy and shared-connection guards.

- **The built-in custom log channel.** Set `LOG_CHANNEL=custom` and
  `LOG_CHANNEL_DRIVER` to a driver registered with `Log::extend` in the
  bootstrap. A missing or unregistered driver fails boot.
- **Percentages in a named locale.** `Lang::percentage_in` formats in the
  named locale without changing the current one.
- **Precision controls for numbers.** `Lang::format_with_max_precision` and
  `Lang::percentage_with_max_precision` cap fraction digits and drop trailing
  zeros. `Lang::format` keeps fixed precision.
- **Default number locales.** `Lang::use_locale` sets the default outside
  request scopes.
- **Temporary number locales.** `Lang::with_locale` restores the previous
  locale when its closure returns or panics.
- **Generated downloads stream as you produce them.**
  `HttpResponse::stream_download(stream, name, content_type)` sends each
  chunk without buffering the export and writes a safe download filename.
- **File response headers and dispositions.** `HttpResponse::file_with`
  and `download_with`, and `Storage::response_with` and `download_with`,
  accept caller headers and a disposition. Your content type and cache
  policy reach the client.
- **Schema dumps without migration data.** `schema:dump --without-migration-data`
  writes the schema while leaving applied migration rows out of the file.
- **Named connections for schema dumps.** `schema:dump --database reporting`
  dumps `DATABASE_REPORTING_URL`; an unknown connection fails with its name.
- **Input preparation before authorization.** Form and multipart request hooks
  expose `prepare_for_validation`. `Request::transform_input` normalizes text
  when parsing starts, preserving authorization before the body is read.
- **MIME family allowlists.** `MimeType` accepts entries such as `image/*`
  while retaining content detection and rejecting spoofed image headers.
- **Column comparisons take an operator.** Both query builders expose
  `where_column_op(a, op, b)`, with the existing identifier and operator checks.
- **Cross joins take conditions.** Both query builders expose
  `cross_join_with(table, closure)`; the closure's `ON` values stay bound.
- **Equality shortcuts on both builders.** `r#where(column, value)`,
  `db_where(column, value)` and `or_where(column, value)` use `=`.
- **Previous values after a model save.** `get_previous(attribute)` reads
  the stored value before the last save changed that attribute, alongside
  `was_changed`, `get_changes` and the original-value accessors.

- **Precognition with per-route opt-in.** Add `Precognitive` to a route
  or group to validate a draft without running the handler body. A passing
  request answers `204` with `Precognition-Success: true`; every marked
  response carries `Precognition: true`, and every response from the route
  adds `Precognition` to `Vary`.
  - `Precognition-Validate-Only` narrows rules before every validation
    stage, including the asynchronous hook. Names match exactly, with
    `*` matching one segment; an empty list validates no fields. An
    unlisted parse failure does not block the answer, and after-validation
    hook errors are never filtered.
  - Live validation reads query data for `GET` and `DELETE`, multipart
    files and fields, and inline `Request::validate::<T>()`.
  - A marked request neither saves the session nor becomes the previous
    URL, so live validation leaves flash data for the next page.
  - The `422` message summarises the first error and the count of the
    rest, with the count suffix localized through the catalog and the
    field-keyed `errors` bag kept.
  - `with_precognition()` sends the request header, and
    `assert_successful_precognition()` checks the status and success
    header. The new [Precognition chapter](precognition.md) covers
    the Inertia 3.8 Vue, React and Svelte clients, uploads, narrowed rules
    and side effects.

- **The Svelte kit on Inertia 3.8 and its Vite plugin.** The kit pinned
  `@inertiajs/svelte` to the 3.6 client, globbed its pages by hand in both
  entries, and passed `createInertiaApp` no `title`, `serverHead` or `nonce`.
  It now declares `@inertiajs/svelte`, `@inertiajs/core` and `@inertiajs/vite`
  at `^3.8.0`. The plugin resolves `pages: './pages'` and wraps `src/ssr.ts`,
  a single `createInertiaApp` call, into the SSR server, which
  `npm run build:ssr` still writes to `frontend/bootstrap/ssr/ssr.js`. The
  entry reads its `nonce` from `<meta property="csp-nonce">` when the document
  has one (K01, K05, K18, K19).
- **Svelte kit layouts, links and titles.** Every page drew its own frame,
  reached other pages through anchors that reloaded the document, and set
  no tab title. `layouts/AppLayout.svelte` and `layouts/GuestLayout.svelte`
  now frame the pages through `createInertiaApp`'s `layout` option and stay
  mounted across visits. Both layouts show the signed-in user from the
  shared `auth` prop, or sign-in and register links for a visitor, through
  `components/AccountLinks.svelte`.
  Every navigation is a `Link`, and sign-out is a `Link` with
  `method="post"` rendered as a button. The dashboard sets the
  layout's heading with `setLayoutProps`. `@inertiajs/svelte` has no `Head`
  component, so `components/Head.svelte` titles each page `Title - App`
  through `<svelte:head>` (K06, K07, K16).
- **A flash toast in the Svelte kit.** No page read `page.flash`, so an
  action showed no feedback. Both layouts now show `page.flash.toast` on
  the one page that carries it, typed by the generated `flashDataType`
  (K17).
- **The Svelte kit's dashboard, notes pages and auth forms.** The dashboard
  now loads its `stats` with `Deferred` and polls them with `usePoll`,
  loads `recent_notes` with `WhenVisible`, and changes the display name
  through `useHttp`, showing the new name at once in the page and the
  layout and putting the old one back with the field's error on a `422`. The new `Notes/Index` page creates
  a note with the `Form` component, remembers its search with
  `useRemember`, scrolls with `InfiniteScroll`, and opens `Notes/Show`
  with a prefetched, instant `Link`. The auth pages submit through `Form`
  instead of `useForm`, and Login turns its `remember` checkbox into a
  boolean with `transform` (K11, K12, K13, K14, K15, K21).
- **The React starter runs on Inertia 3.8 through its Vite plugin.** The kit
  pinned `@inertiajs/react` at `^3.6.1`, resolved pages with its own
  `import.meta.glob` in both entries, and passed `createInertiaApp` no title
  callback, no server head and no CSP nonce. It now declares the adapter,
  `@inertiajs/core` and `@inertiajs/vite` at `^3.8.0`, resolves pages through
  the plugin's `pages: './pages'`, and builds `src/ssr.tsx` through the
  plugin, so `npm run build:ssr` still lands `frontend/bootstrap/ssr/ssr.js`
  for `suprnova ssr:start`. Both entries pass a `title` callback that appends
  the project's name (from `frontend/src/lib/app.ts`) and `serverHead: true`;
  the browser entry passes the nonce of `<meta property="csp-nonce">` when the
  document carries one. A new `npm run check` script type-checks the kit (K01,
  K05, K18, K19).
- **The React starter has persistent layouts, `Link` navigation and page
  titles.** Each page drew its own frame and reached other pages through
  `<a href>`, which reloaded the document on every click, and no page set a
  title. `layouts/GuestLayout.tsx` (the `auth/` pages) and
  `layouts/AppLayout.tsx` (navigation and a heading) now come from
  `createInertiaApp`'s `layout` option and stay mounted between pages that
  share them. Both show the signed-in user from the shared `auth` prop:
  the name and a sign-out `Link` with `method="post"` rendered as a button,
  or the sign-in and register links for a guest. Every application link is a `Link`, every page sets
  `<Head title>`, and the dashboard sets the layout's heading with
  `setLayoutProps` (K06, K07, K16).
- **The React starter shows the flash toast.** No page read `page.flash`,
  so a sign-in, a registration or a reset showed no feedback. Both layouts
  render `components/FlashToast.tsx`, which shows `page.flash.toast`,
  typed by the generated `flashDataType`, read from the page on every
  render, so it is gone on the next visit (K17).
- **The React starter demonstrates deferred, optional, polled, optimistic
  and infinite-scroll pages.** The dashboard sent one prop, nothing was
  paginated, and the auth pages posted through `useForm`. `Dashboard` now
  renders `stats` with `Deferred` and a fallback, polls it with
  `usePoll(10000, { only: ['stats'] })`, loads `recent_notes` with
  `WhenVisible`, and changes the display name through `useHttp`, showing
  the new name at once and putting the old one back with `errors.name` on
  a `422`; a saved name reloads the shared `auth` prop, so the layout
  shows it too. The new `Notes/Index` page creates a note with `Form`,
  remembers its search with `useRemember`, lists the signed-in user's
  notes with `InfiniteScroll` over the cursor paginator, and opens a note
  through a prefetched instant visit to the new `Notes/Show` page. Every
  auth page, the verification resend included, submits through `Form` and
  disables its button while `processing` (K11, K12, K13, K14, K15, K21).

- **Third-party Live component libraries.** A library is a git repository
  with one fixed tree: `library.json` at its root and, under `components/`,
  one directory per component holding its `manifest.json`, the files the
  manifest names and a `manifest.sig`. A component can carry the Rust of a
  Live component as well as a view, a stylesheet and a script.
  `suprnova live:add acme/acme-ui/counter` installs one by address from
  GitHub, or from GitLab or Codeberg with the host first, at the newest
  `v<semver>` tag or the one `@<version>` names; an `https://` URL of a
  component directory and a `./path` on disk work too. Every component is
  signed with Ed25519 over a hash of everything that arrived. The first
  install pins the library's key in `suprnova.toml` once you confirm on a
  terminal, and every later version must be signed by that key, or by a new
  key the pinned one handed over to in `library.json`'s `previousKeys`.
  Before it writes anything, `live:add` scans every view, stylesheet, script
  and Rust file as data, runs none of it, admits only what it can classify,
  and shows a plan of every file, module declaration, registration and
  capability. A component reaches a database, the network, files, mail, a
  queue, a cache, the session, the environment or a process only through
  Suprnova's API, and you approve each of those nine capabilities by name,
  on a terminal or with `--allow`; `--yes` confirms a plan and never
  approves a capability or pins a key. `live:add` writes a component's Rust
  under `src/live/<namespace>/`, registers it in your registry builder,
  never changes `Cargo.toml` or `Cargo.lock`, and records the source,
  version, commit, digests, hash, signature, registrations and approvals in
  `suprnova.toml`, which `live:check` now verifies offline. An install holds
  a lock on the project and writes a journal before its first write, so a
  failed or killed install leaves nothing behind, and `suprnova serve`
  waits for it before it builds (`suprnova live:wait`). Authors scaffold,
  check and sign a library with `suprnova live:registry new`, `check` and
  `sign`, and move it to a new key with `rotate-key`; `new` adds a
  `preview/` application that renders each component from where it sits,
  and keeps the private key in your configuration directory, or where
  `SUPRNOVA_LIBRARY_KEY` names it. Each library's
  stylesheets and scripts are served at `/<namespace>-ui/{component}/{file}`
  by one `Router::try_live_ui_assets_for("<namespace>")` call, which
  `live:add` names at the library's first install. See [Installing Live
  Components](live-add.md) and [Live Component
  Libraries](live-libraries.md).
- **Route model binding by type.** `#[handler]` binds an argument by its
  type alone (`post: Post`) whenever the type implements `RouteBinding`,
  which every `#[model]` does, and `Option<T>` binds `None` when its
  optional parameter is absent. Routes take `{post:slug}` segments,
  `#[model(route_key = "...")]` sets a model's default column, children
  bind through their parent's relations (`scope_bindings()`,
  `without_scoped_bindings()`), and routes, groups and resources take
  `with_trashed()` and `missing()`. A generic `#[handler]`, and a
  `#[handler]` that a closure route, middleware, another handler or a
  `missing()` handler calls with the request, binds at the request as the
  route's own handler does. Such a handler that takes a scoped child
  without its parent finds it through the parent the route's handler
  binds; where the router cannot see how the route's handler binds that
  parent, the request answers 500 and names the parent to take. One that
  cannot return the `missing()` response hands it to the middleware or
  route handler that called it, which answers with it in place of a 404,
  so the middleware outside that caller sees it as it sees the route's
  own. `Router::bind` and `Router::model`
  register custom resolution, `#[model(custom_route_binding)]` with
  `suprnova::database::resolve_model_route_binding` overrides a model's own,
  and `#[derive(RouteBinding)]` binds a unit-only enum. `resource!` and
  `api_resource!` build resources from a module's `#[handler]` functions,
  nested resources (`users.posts`) included. `route()` and `try_route()`
  take bound values, named or as one positional value: a `#[model]` row,
  a derived enum, a `RouteParam<T>`, or any type that implements
  `RouteValue` with one call to `bound_route_value`. `try_route` is
  re-exported at the crate root. `Router::prepare_bindings()` runs the
  startup checks for a router a test builds. See [Routing](routing.md).
- **Serving under a path prefix.** Behind a trusted proxy, an application
  serves under the prefix `X-Forwarded-Prefix` names, or under the path in
  `APP_URL`. Every URL the framework builds for the browser carries that
  public root once: `route()` and the signed URLs, redirects and the
  previous and intended URLs, Inertia's page URL and Vite tags, Live's
  endpoints, assets and reflected URLs, pagination links, storage URLs and
  the session, XSRF and remember-me cookie paths. `url::root()` returns
  the root for a template, and a third-party component's view may call it
  before a constant path. `RootShare` gives every Inertia page the root,
  and a new scaffold works under a prefix. See
  [Deployment Overview](deployment.md) and [URL Generation](urls.md).
- **The rest of Laravel's Image API.** `Image::orient`, `using`,
  `transform`, `rotate_with_background`, `flip`, `flop`, `optimize`,
  `width`, `height`, `to_webp`, `to_jpg`, `to_jpeg`, `to_png`, `to_gif`,
  `to_bmp`, `to_base64`, `to_data_uri` and `store_as`, with `Color`,
  `ImagePixels`, `CustomTransformation` and `register_transformation` for
  a step of your own. See [Images](images.md).
- **Running on a Laravel database.** A Suprnova application runs on a
  database a Laravel 13 application created, and beside that application.
  `jobs`, `job_batches`, `failed_jobs`, `sessions`, `notifications`, the
  scaffold's `users`, `features` (laravel/pennant) and `roles`,
  `permissions`, `model_has_roles`, `model_has_permissions` and
  `role_has_permissions` (spatie/laravel-permission) take the layouts
  Laravel's and the packages' migrations create. Data those layouts have no
  column for lives in `suprnova_jobs_reservations`,
  `job_batch_settlements`, `suprnova_feature_details`,
  `suprnova_role_details` and `suprnova_permission_details`. The framework
  ships `queue::migrations::{CreateJobsTable, CreateJobBatchesTable,
  CreateFailedJobsTable}` and `session::migrations::CreateSessionsTable`,
  and each migration leaves a table Laravel or a package created exactly
  as it is. `NOTIFICATIONS_MORPH_KEY` and `RBAC_MODEL_KEY` pick `int`,
  `uuid` or `ulid` keys, and `FEATURES_USER_SCOPE` names the user scope
  Pennant stores. See [Running on a Laravel
  Database](laravel-database.md).
- **`LARAVEL_SHARED_DATABASE`.** For an application that shares its
  database with a running Laravel application: the framework and Magnetar
  write `$2y$` bcrypt hashes Laravel 13 accepts with `HASH_VERIFY=true`, a
  valid sign-in rewrites a `$2b$` or Argon2id hash as `$2y$` and fails
  with the storage error, signing nobody in, when that rewrite cannot be
  stored, Magnetar no longer upgrades bcrypt to Argon2id, and an unrouted
  database-queue job is stored on the queue `suprnova`, which Laravel's
  worker does not read.
  `LaravelDatabase::share` turns it on from code.
- **Morph aliases.** `#[model(morph_type = "App\\Models\\Post",
  morph_aliases = ["post"])]`: `MorphTo`, `MorphOne` and `MorphMany`,
  direct and eager, `has`, `with_count` and the aggregates accept every
  name; writes store the `morph_type`.
- **`Application::run_with_args`** parses the given arguments instead of
  the process's and returns its failures to the caller as a
  `FrameworkError`; `run()` still prints them and exits.
- **`HasRoles::rbac_model_types()`** names every `model_type` a model's
  role and permission assignments are read under: its `morph_type`, its
  aliases and the Rust type path an earlier release stored.
- **Merge props merge at nested paths in either direction.**
  `Prop::append_at(paths, match_on)` and `Prop::prepend_at(paths,
  match_on)` are Laravel's `append($path, $matchOn)` and
  `prepend($path, $matchOn)`: they take one path or a list, add
  `{path}.{match_on}` to `matchPropsOn` when a field is named, and one
  prop can append at one path and prepend at another, which the single
  direction of `merge_with_path` could not express.
  `.append_at(["a.items", "b"], "id")` on a prop `feed` emits
  `mergeProps: ["feed.a.items", "feed.b"]` and `matchPropsOn:
  ["feed.a.items.id", "feed.b.id"]`.
- **Once props take Laravel's options.** `until` takes a moment or a
  span, as Laravel's `until(DateTimeInterface|DateInterval|int)` does: a
  `DateTime<Utc>`, a `std::time::Duration`, a `chrono::Duration` or whole
  seconds, through the new `OnceUntil`. `fresh` takes a `bool`,
  `OnceOptions::once(false)` turns the flag off, `Prop::once_with(options)`
  sets the flag, key and expiry in one call (Laravel's `once($value, $as,
  $until)`), and `as_key` takes an enum whose `Display` names the key.
  `expiresAt` is the expiry in milliseconds counted in whole seconds, as
  Laravel counts it. The server still refuses a client's cache claim
  past a `DateTime` deadline, which Laravel leaves to the client.
- **`App::inertia_share_once` returns the shared once prop**, a
  `SharedOnceProp` that takes `as_key`, `until`, `fresh` and `once_with`
  as Laravel's `shareOnce` returns a chainable `OnceProp`. A shared once
  prop could not take a cache key, an expiry or `fresh` before; only the
  `InertiaSharedData` provider could reach them.
  `InertiaRegistry::share_once` returns the same handle.
- **Scroll props take any page-facts provider and can read them from the
  loaded value.** Every `.scroll` builder and `Prop::scroll` take a
  `ScrollMetadata` or anything implementing `ProvidesScrollMetadata`, so
  `.scroll("posts", &page, &page)` is Laravel's `Inertia::scroll($paginator)`.
  `InertiaResponse::scroll_lazy`, `scroll_lazy_with` and
  `Prop::scroll_lazy` describe a lazily loaded list from the value its
  resolver returns, as Laravel's callable metadata does, and ship the
  `scrollProps` entry with that value.
- **Paginators report the scroll facts Laravel's `fromPaginator` does.** A
  `CursorPaginator`'s current page is `1` on its first page, else the
  cursor it was fetched with (`Pagination::cursor` records it in the new
  `current_cursor`, `with_current_cursor` sets it), else the request's
  cursor parameter; it was always `null`. `Paginator` (the simple
  paginator) takes a page parameter name, `with_page_name`, used by its
  URLs and its `pageName`, where it was fixed to `page`.
- **Prop providers, page and shared.** A type implementing
  `ProvidesInertiaProperties` expands into props once per render with a
  `RenderContext` of the page component and the request, Laravel's
  interface of the same name. A page takes any number with
  `InertiaResponse::provide`, the shared props any number with
  `InertiaRegistry::share_provider`; shared providers' keys count as
  shared keys, and `flush_shared` clears them. A page also takes any
  number of `#[derive(Data)]` objects with `with_data` (and
  `try_with_data`), where it took one, through `Inertia::data`, with no
  request or component context.
- **A prop value can convert itself with its context.** A type
  implementing `ProvidesInertiaProperty` (Laravel's interface of the same
  name), attached with `InertiaResponse::with_property` or
  `Prop::property`, is converted when the prop is sent, with a
  `PropertyContext` of its key path, its sibling props and the request,
  so a price can format itself with the page's currency. No value type
  received its key path, siblings or request before.
- **An application-owned Inertia root document.** The framework wrote every
  first visit's whole document itself, so an application had no place for
  its own favicon, fonts, meta tags or attributes on `<html>` and `<body>`.
  `#[inertia_root(path = "app.html")]` declares an Askama template under
  `templates/` that receives the framework's parts (`title`, `head`, `body`,
  `lang`, `csrf_token`, `nonce`, `ssr` and `view`), checked at compile time,
  and `InertiaConfig::root_template` renders every first visit through it.
  `root_template_with` chooses the template per request, Laravel's
  `rootView(Request)`, and error pages go through the same choice;
  `InertiaResponse::with_view_data` hands the template values of any
  serializable type that never reach the page props, Laravel's
  `withViewData`. The page JSON is written straight into the template's
  output: a first visit with a 1 MiB prop allocates 5,386,301 bytes
  through a template against 5,386,925 through the framework's document,
  and a 3 MiB page comes back whole. A template
  that fails to render is an error response, never part of a document.
  `InertiaConfig::mount_id` names the mount element and the page data
  element, `app` by default, for a client that mounts on another id. Without
  a template the first visit is byte for byte what it was.
- **`Inertia::version` and `Inertia::get_version`.** Laravel's runtime
  setter and getter for the asset version. `Inertia::version` takes a
  string, a function called on every read, or `None::<String>` for the
  empty version (Laravel's `null`), and replaces the installed config's
  version; `Inertia::get_version` returns the current one. Every page built
  after the call advertises it, and the version middleware
  `Inertia::install` registers now reads `Inertia::get_version` per request
  instead of the version captured at install (RF-05).
- **Big integers survive the trip to the browser.** JavaScript reads
  integers exactly only up to 9007199254740991, so a 64-bit id beyond it,
  9007199254740993 for one, reached an Inertia page as 9007199254740992.
  With the new `InertiaConfig::preserve_big_integers(true)` setting, or
  `InertiaResponse::preserve_big_integers(true)` for one response, every
  integer beyond plus or minus 9007199254740991 in props and flash, at
  any depth, is sent as `{"$bigint": "<digits>"}` and the page carries
  `preserveBigIntegers: true`, so the Inertia client restores it as an
  exact `BigInt`, as Laravel's `preserve_big_integers` does. Off by
  default; when off nothing is wrapped and the flag is absent (JE-04,
  JE-05).
- **`Inertia::back(status, fallback)` and
  `InertiaConfig::store_previous_url`.** `back` is Laravel's
  `Inertia::back()`: the request's `Referer` when it is a path on this host
  under the public root, else the session's previous URL, else the
  fallback, else `/` (RF-18). `store_previous_url` (on by default) turns the
  previous-URL recording of Inertia visits off (MW-06).
- **Inertia flash on the facade: `Inertia::flash`, `flash_many`,
  `get_flashed`, `pull_flashed`, `clear_history` and `preserve_fragment`.**
  `flash` takes a string key or any type implementing the new `FlashKey`
  trait, such as an application's enum of toast kinds; `get_flashed(&req)`
  returns exactly what `pull_flashed(&req)` removes (RF-17, RF-19, RF-08,
  RF-09).
- **Shared data and render settings on the `Inertia` facade.**
  `Inertia::share(key, value)`, `share_many`, `share_data` (a
  `#[derive(Data)]` object's eager fields) and `share_provider` take the
  forms Laravel's `Inertia::share` takes; `get_shared(key, default)` and
  `get_shared_all()` read shared data back. `transform_component_using`
  renames components before they render, and
  `InertiaConfig::ensure_pages_exist` (with `pages_dir` and
  `page_extensions`) makes a component with no page file an error naming the
  component and the directory, for a name given as a string too (RF-02,
  RF-03, RF-07, RF-15).
- **SSR controls on the `Inertia` facade.** `Inertia::disable_ssr(bool)`
  and `disable_ssr_if(fn)` replace the configuration's switch, per request
  for the function, and can turn SSR on as well as off;
  `without_ssr(patterns)` adds exclusions; `configure_ssr_request_using(fn)`
  adjusts the request sent to the worker through the new `SsrRequest`
  (headers, a bearer token, the timeout), so a worker that needs a token can
  be reached (RF-11, RF-12, RF-13).
- **`Inertia::location(url or redirect)`**, Laravel's `Inertia::location`,
  beside `InertiaResponse::location`, both taking a URL or a `Redirect`
  through the new `InertiaLocation` (RF-16, HM-04).
- **Inertia middleware hooks and the stack on a route group.** The
  `InertiaMiddlewareHooks` trait carries Laravel's overridable middleware
  decisions (`version`, `share`, `share_once`, `root_view`, `url_resolver`,
  `on_empty_response`, `on_version_change`, `on_redirect_with_fragment`),
  each defaulting to the framework's behaviour; `InertiaConfig::hooks`
  installs an implementation, `DefaultInertiaHooks` is the framework's
  answer to start from, and `InertiaVisit` is the request an `on_*` hook
  answers. `Inertia::middleware(&cfg)` is the whole stack as one middleware
  for a route group, and `InertiaConfig::register_globally(false)` makes
  `Inertia::install` register it as the named middleware `inertia` instead
  of on every route, so an API group carries no `Vary: X-Inertia` and has no
  redirect turned into `303` (MW-08, MW-10).
- **The SSR call is a driver you can replace.** The `SsrGateway` trait
  carries `dispatch`, `is_healthy` and the capabilities `disable`, `except`
  and `configure_request_using`, each a default an implementation
  overrides, as Laravel's `Gateway`, `DisablesSsr`, `ExcludesSsrPaths`,
  `ConfiguresSsrRequests` and `HasHealthCheck` do. `HttpGateway` is the
  default; `App::bind::<dyn SsrGateway>(Arc::new(..))` makes an
  application's own gateway render every first visit. `Inertia::disable_ssr`,
  `disable_ssr_if`, `without_ssr` and `configure_ssr_request_using` act on
  the bound gateway and log a warning naming the capability it lacks.
  `Inertia::ssr_is_healthy()` returns the gateway's health: the HTTP
  gateway asks `GET {url}/health` within the SSR timeout, through the
  request configurator, `Some(true)` on a 2xx and `Some(false)` otherwise,
  and `None` means the gateway has no health check. `detect_ssr_bundle` and
  `CONVENTIONAL_BUNDLE_PATHS` are Laravel's `BundleDetector` (SS-10, SS-13).
- **`SsrRenderFailed`, the event of a failed SSR render.** It carries the
  page's component and URL and the worker's error JSON: `error`,
  `error_type` (an `SsrErrorType`: `browser-api`, `component-resolution`,
  `render`, `connection` or `unknown`), `hint`, `browser_api`, `stack` and
  `source_location`. A worker that cannot be reached dispatches it with type
  `connection` and the transport error. It is dispatched before the visit
  falls back to the client, and only when something listens or a fake
  records it (SS-08).
- **SSR through the Vite dev server in development.** While the Vite hot
  file exists, a first visit in development is posted to the dev server's
  `/__inertia_ssr` without the bundle check, so no SSR bundle or worker
  process is needed while developing. `suprnova serve` writes the dev
  server's URL to `public/hot` when it starts Vite and removes the file when
  Vite stops or `serve` exits, as Laravel's Vite plugin does, and the
  full-stack scaffold ignores `/public/hot`. `SsrConfig::hot_url`
  (`InertiaConfig::ssr_hot_url`) sends every first visit in development to
  another address, and `SsrConfig::hot_file` (`InertiaConfig::ssr_hot_file`,
  default `public/hot`) names another file; the address is the hot URL,
  else the file's content, else the `vite_dev_server` URL. Without the file
  the visit takes the worker path, whatever listens at the dev server's
  port, and production never goes hot. `suprnova serve` writes the file
  only when `frontend/package.json` declares `@inertiajs/vite`, the Inertia
  Vite plugin that serves `/__inertia_ssr`: without it the dev server serves
  no SSR, so no file is written and a first visit takes the worker path
  (SS-05).
- **SSR runtime settings.** `SsrConfig::runtime` (`node` by default, or
  `bun`, `deno` or a path) and `ensure_runtime_exists` (off by default), set
  with `InertiaConfig::ssr_runtime` and `ssr_ensure_runtime_exists`, are
  Laravel's `inertia.ssr.runtime` and `ensure_runtime_exists` for
  `ssr:start`.

- **`Inertia::handle_exceptions_using(callback)` decides every error
  response**, Laravel's `Inertia::handleExceptionsUsing`. The callback
  receives an `InertiaErrorResponse` for each error response the framework
  renders - a handler's or a middleware's `Err`, a panic, the router's
  `404`, a middleware's own `{"message": ...}` answer - for every request
  type, an API client's included. It reads `status()`, `error()` (the error
  report, or the panic's message and location), `request()`, `method()`
  and `response()`, which with debug on is the development error page where
  that page applies. It returns `render(component, props)` for an Inertia
  page at the original status, `respond_with(response)` for any other
  response, or `None` to keep the response. A callback that panics is a
  bug the panic boundary reports as the sanitized `500` with its report,
  inside the stack and at the server alike. A JSON client's validation
  `422` reaches the callback like any other error, as in Laravel; an
  Inertia visit's validation failure reaches it as the `303` back to the
  form, since the error-response middleware sits outside the validation
  redirect, so an Inertia form still goes back with its errors flashed. A
  rendered page carries the shared props, the middleware
  hooks' `share` and `share_once` included, only after
  `with_shared_data()`. `InertiaConfig::error_page` is now the default
  callback and keeps its rule; an app that sets both gets its callback. A
  later call replaces the callback, which lives on the active container, so
  a callback installed under `TestContainer::fake()` stays in that test
  (EX-01, EX-02, EX-03, EX-06, EX-07).
- **`ssr:start`, `ssr:stop` and `ssr:check` on the application binary**,
  Laravel's `inertia:start-ssr`, `inertia:stop-ssr` and `inertia:check-ssr`.
  They read the Inertia configuration the application installed, so they
  start, stop and check the worker first visits dispatch to; they run both
  bootstrap hooks, since the scaffold installs Inertia in `http_bootstrap`,
  bind no port and boot no runtime driver, and fail naming
  `Inertia::install` when nothing is installed. `ssr:start --runtime`
  overrides `InertiaConfig::ssr_runtime`, and the command exits with the
  status its worker exited with (CM-01, CM-02, CM-03, SS-10).
- **`suprnova ssr:stop [--graceful]`**, the CLI's `inertia:stop-ssr`: it
  runs the application binary's `ssr:stop` (above) from the project
  directory, passing `--graceful` through, so it stops the worker at the
  URL the application installed (CM-02).
- **`suprnova generate-types` types wide integers as `number | bigint` in a
  project that preserves big integers.** With `preserve_big_integers` on, an
  `i64` past 2^53 reaches the page as a `BigInt`, which a `number` type
  misnames, so `i64`, `u64`, `i128`, `u128`, `isize` and `usize` are
  `number | bigint` when a `.rs` file under `src/` calls
  `preserve_big_integers(..)` with anything but a literal `false`
  (parenthesized or not), such as `true` or a variable, or with the new
  `--big-integers` flag, which `generate-types` and `serve` both take and
  `serve` keeps for every regeneration on save, and `number` otherwise, as
  every integer and float was in 3.2.1. Narrower integers and floats stay
  `number`, and a wide map key stays `number` (T03).
- **`suprnova generate-types` writes page types and types `usePage()`.** In
  3.2.1 `inertia-props.ts` held only the props interfaces, so a page picked
  its interface by hand and typed any shared props inline. The file now opens
  with `import '@inertiajs/core'` and ends with `Pages`, which maps each
  component to the struct a handler renders it with (read from
  `inertia_response!`, `InertiaResponse::new(..).with_data(..)` and
  `Inertia::data`, given the struct itself or a local binding or parameter
  that declares or builds it, with Rust's shadowing applied), `SharedProps`
  (`root` and the fields of the struct `Inertia::share_data` is given or
  marked `#[inertia_props(shared)]`), `Errors`, `PageProps<C>`, and a
  `declare module '@inertiajs/core'` block setting `sharedPageProps`,
  `errorValueType` and, for a struct marked `#[inertia_props(flash)]`,
  `flashDataType`, so `usePage()` is typed with no argument. `Errors` is
  `Record<string, string>` and `errorValueType` is `string`, or both say
  `string[]` when a `with_all_errors(..)` call under `src/` passes anything
  but a literal `false` (read as `preserve_big_integers(..)` is), since the
  server then sends every message per field as an array. The `InertiaProps`
  derive takes the two markers and refuses any other form. A component
  rendered with two structs, two shared or two flash structs, or a struct
  named like a generated declaration fails the command with every conflict
  named and leaves the file as it was (T01, T02).
- **A route helper names the page its route renders.** `routes.ts` helpers
  returned only `url` and `method`, so `<Link instant>` and `<Form
  instant>` could not make an instant visit through one. A helper now
  carries `component`, Inertia's `UrlMethodPair.component`, when its
  handler names exactly one component as a string literal (in
  `inertia_response!`, `InertiaResponse::new` or the `Inertia` facade's
  render calls) or its route is a `Router::inertia` route. A handler naming
  none, several, or one it computes gets none. A handler inside an `impl`
  block (`#[handler(Self = Posts)]`, registered as
  `controllers::posts::Posts::index`) is read from its method like a free
  function, for its component and its request type, and a free function
  of the same name in the same file keeps its own.
  `Router::inertia` routes, which `routes.ts` left out, now get helpers
  under `controllers.inertia`, and `RouteConfig` declares
  `component?: string` (T05).
- **`suprnova::testing::TestClient`, one in-process test client.** Every HTTP
  test copied its own loopback harness - a port, a hyper client and
  hand-carried session cookies - because `handle_request` takes a body only
  hyper builds. `TestClient::new(router, registry)` sends `get`, `post`,
  `put`, `patch`, `delete` and `send(method, path)` requests with `header`,
  `json`, `form` and `inertia()` (an Inertia visit's headers with the
  installed asset version) over an in-memory connection, never a port, in the
  task that awaits it, so a `TestContainer` scope still applies. It carries
  every cookie a response sets to the next request and drops the ones a
  response expires, keeps each response's error report, gives every
  `TestResponse` the session store `with_session_store` names, and fails a
  request that has not answered after 10 seconds, naming its method and path.
  Under a public path prefix (`APP_URL=https://example.test/billing`) a page's
  url is the public `/billing/users` while the router matches `/users`, so the
  client keeps the root each request was served under and replays a reload to
  the internal path, `/users` with the page's query, sending again the
  `X-Forwarded-Prefix` header the page's request sent. See [HTTP
  Tests](http-tests.md#the-test-client) (TS-01, TS-10).
- **Laravel's prop assertions and scopes on `AssertableInertia`.** It had
  `has`, `missing`, `where_` and `count` only. It now has `has_all`,
  `has_any`, `missing_all`, `count_between`, `where_not`, `where_null`,
  `where_not_null`, `where_all`, `where_type` (`string`, `integer`,
  `double`, `boolean`, `array` and `null`, joined by `|`; an unknown name
  fails), `where_all_type` and `where_contains`, and `count` counts an
  object as well. `scope`, `first`, `each`, `has_with` and `has_count_with`
  run a callback over a nested object or array whose failures name the full
  dotted path (`user.name`). A scope fails when it ends with a prop no
  assertion touched, unless `etc()` was called in it; the page's top level
  never checks, as Laravel's `assertInertia` does not (TS-06).
- **Inertia reloads through the client, full and by deferred group.** A
  reload needed a `with_reload` closure wired to the test's own harness. A
  page from a `TestClient` response now reloads through that client with
  its cookies, and `with_reload` still replaces it for a custom harness.
  `reload()` replays the page with no partial-reload header and asserts the
  same component, url and version; `load_deferred_props_of(groups)`
  requests the props of the named groups only, every group for an empty
  list, and fails naming a group the page does not defer instead of
  requesting nothing. `reload_with`, `reload_only_with`,
  `reload_except_with` and `load_deferred_props_with` run a callback over
  the reloaded page (TS-07, TS-08).
- **Inertia page readers, the flash a redirect leaves, and big integers in
  tests.** `AssertableInertia` gains `missing_flash`, `to_page()` (with
  `encryptHistory` and `clearHistory` only when the page set them),
  `encrypt_history()` and `clear_history()`, and `TestResponse` gains
  `inertia_page()` and `inertia_props(path)`. A handler that flashes and
  redirects leaves its Inertia flash in the session, and the redirect carries
  no page to assert it on; `assert_inertia_flash(key, expected)` and
  `assert_inertia_flash_missing(key)` read it through the attached session
  store. A page with `preserveBigIntegers` sends integers beyond 2^53 - 1 as
  `{"$bigint": "<digits>"}` markers, and the markers in props and flash are
  decoded before any assertion or reader sees them, so
  `where_("id", 9007199254740993_i64)` passes against the page the handler
  built. A marker whose digits fit no 64-bit integer, such as
  `{"$bigint": "18446744073709551616"}`, which only a hand-built page object
  carries, fails naming its path and digits rather than staying an object that
  `where_type("id", "integer")` rejects and `to_page()` shows (TS-12, TS-13,
  TS-14, TS-15, TS-16).
- **`InertiaConfig::testing_ensure_pages_exist`, on by default.**
  `AssertableInertia::component(name)` passed for a component with no page
  file, so a test stayed green while the browser showed a blank page. With
  an Inertia configuration installed it now also looks for the file under
  `pages_dir` with one of `page_extensions`, the lookup
  `ensure_pages_exist` does at render time, and fails with
  `Inertia page component file [Name] does not exist.`, the directory and
  the extensions it tried. `component_exists(name, bool)` decides the check
  for one assertion, and with no configuration installed nothing is
  checked (TS-03).
- **Inertia DevTools records each request.** The Inertia DevTools browser
  extension reads its entries from the server, and Suprnova had no server
  side, so the extension showed nothing. `InertiaConfig::devtools` takes a
  `DevToolsConfig` with Laravel's settings, read from the same
  `INERTIA_DEVTOOLS_ENABLED`, `_TTL_HOURS`, `_PRUNE_INTERVAL_SECONDS`,
  `_LIMIT` and `_GATE` variables. The application opts in with
  `.devtools(DevToolsConfig::new())`, as a new project's bootstrap does.
  With `enabled` unset, it records only when `APP_ENV` is set and names
  `local`; an unset `APP_ENV`, which Laravel reads as production, records
  nothing. `enabled(true)` and `enabled(false)` decide outright. `Inertia::install` and
  `Inertia::middleware` then put `DevToolsMiddleware` outermost in the
  Inertia stack, and it skips the `except` paths (`_inertia/devtools*` and
  `_suprnova/*` by default). A failure while recording drops the entry and
  leaves the response as it was; a write failure is logged at `warn` once
  and pauses recording into that directory for 30 seconds. See [Inertia
  DevTools](frontend-inertia-devtools.md) (DT-01, DT-10).
- **The entry of a request, its headers and the first-visit tag.** Each
  recorded request stores Laravel's entry key for key: a ULID, the tab,
  batch and visit ids from the extension's headers, the timestamp, method,
  URL, status, redirect location and server time, the request type
  (`precognition` first, then `initial` or `http`, `deferred`, `poll`,
  `partial`, `prefetch`, `navigate`), the request and response headers,
  the request body (an Inertia write's JSON or form input with uploads
  summarized, read up to the request body cap) and the response body (the
  page object, or text up to 256,000 bytes), the route with its handler's
  type name, and for a rendered page the component, its
  page file and the render call's file and line, which
  `InertiaResponse::new`, `inertia_response!`, `Inertia::paginate`,
  `Inertia::data` and `Router::inertia` take through `#[track_caller]`.
  The response carries `X-Inertia-Devtools-Id`, `-Parent-Out`, and
  `-Base-Path` under a public root, and a first visit's `200` document
  carries the id in a `<script data-inertia-devtools-id>` tag before
  `</body>` (DT-02, DT-04, Precognition row 057).
- **Prop kinds and their sources in DevTools entries.** An entry lists
  each prop the client received with its kind in Laravel's order
  (`always`, `defer` only on the extension's deferred visit with its
  group, `optional`, `merge`, `scroll`, `once`), `reset`, `once`,
  `mergeDirection`, `deepMerge` for a deep merge or a `match_on`, and
  `rescued`. A shared key names the `Inertia::share`, `share_many`,
  `share_data` or `App::inertia_share*` call that shared it, and the
  `InertiaConfig::hooks` call for a hook share; a render prop names the line
  that gives its key. Deep paths without metadata are pruned, and
  `propValues` holds what the client received (DT-03).
- **The DevTools entry endpoints.** `GET /_inertia/devtools/entries`
  lists entries newest first, filtered by `component`, `type`, `exclude`,
  `offset` and `limit`, and `GET /_inertia/devtools/entries/{id}` answers
  one entry, or `404 {"message": "Not found."}`. An `APP_ENV` naming the
  `local` environment admits every request; elsewhere, an unset `APP_ENV`
  included, only the user the configured gate ability allows is admitted,
  else `403 {"message": "Forbidden."}`. An entry request
  reflashes the session, never becomes the previous URL, and is never
  recorded (DT-05, DT-06, DT-09).
- **DevTools storage and redaction.** Entries are one JSON file each under
  `storage_path("inertia-devtools")`, listed newest first in `_meta.json`,
  pruned after 24 hours once the last prune is 300 seconds old, and kept
  to the newest 100 per browser tab. Before a write, the redaction keys
  (`password`, `token`, `api_key` and seven more) and headers (`cookie`,
  `authorization` and four more) become `[REDACTED]` in bodies, prop
  values, headers and URL query parameters, without regard to case, and a
  header value that is not text becomes `[UNSERIALIZABLE]` (DT-07, DT-08).
- **The scaffold's notes: a list, a page and a form over the signed-in
  user's own notes.** A new application had nothing a kit page could
  scroll, open or write: its dashboard sent one eager prop and no handler
  paginated anything. `suprnova new` now writes a `create_notes_table`
  migration and a `Note` model that belongs to a user (the `User` model
  gains `has_many` notes), and three routes behind the dashboard's
  authentication: `GET /notes` lists the user's notes 10 at a time with
  `cursor_paginate` through `Inertia::paginate`, filtered by the `search`
  query parameter in title or body without regard to case, and sends
  `search` back; `GET /notes/{id}` shows one, and answers `404` for a note
  of another user; `POST /notes` validates `title` (1 to 255 characters)
  and `body` (at most 10000), writes the note and flashes a toast. Every
  handler reads notes through `Note::owned_by`, and none lists accounts
  (K12, K14).
- **The scaffold's dashboard defers `stats` and leaves `recent_notes`
  optional.** The dashboard sends the user's note count and the notes
  written today as a deferred `stats`, and the user's five newest notes as
  an optional `recent_notes` the page asks for when it scrolls them into
  view (K14).
- **The signed-in user on every page of the scaffold.** A layout had no
  way to name the signed-in user outside the dashboard. The scaffold now
  shares `auth`, the signed-in user or `null`, with
  `App::inertia_share_lazy`, read from the request's session for each
  response that sends it, and `SharedData` in `src/props/shared.rs`, marked
  `#[inertia_props(shared)]`, adds `auth` to the generated `SharedProps`
  (K12).
- **A JSON handler for the display name.** `POST /profile/name` takes
  `{"name": ...}`, saves it on the signed-in user, and answers `200` with
  `{"user": {...}}`, or `422` with the framework's validation body for an
  empty name or one over 255 characters, for the dashboard's `useHttp`
  form (K21).
- **Flashed toasts after every account action.** Nothing a new
  application did told the user it worked: the server sends `page.flash`,
  but the scaffold flashed nothing. A `Toast` in `src/props/flash.rs` is
  now flashed under `toast` after sign-in, registration, a reset-link
  request, a password reset, email verification, a verification resend,
  sign-out and a saved note, and the `Flash` struct beside it, marked
  `#[inertia_props(flash)]`, makes `suprnova generate-types` type
  `page.flash.toast` as Inertia's `flashDataType` (K17).
- **Laravel's route names in the scaffold.** The scaffold's routes carry
  the names Laravel's kits give them: `dashboard`, `notes.index`,
  `notes.show`, `notes.store`, `profile.name`, `login`, `register`,
  `password.request`, `password.email`, `password.reset`,
  `password.update`, `verification.notice`, `verification.send`,
  `verification.verify` and `logout` (K12).
- **The sources and the manual cite the Inertia.js client at 3.8.0.**
  The framework's comments cited the client at 3.6.1 and 3.1.1, and the
  frontend chapter named 3.4.0. Each rule they cite was read again in the
  3.8.0 client, and every citation names its 3.8.0 file and line; the
  frontend chapter and the CSRF chapter name 3.8.0, and the frontend
  chapter lists `@inertiajs/vite` (K01).
- **The Vue kit runs on Inertia 3.8 and its Vite plugin.** The kit pinned
  `@inertiajs/vue3` at `^3.6.1`, found its pages with a hand-written
  `import.meta.glob` in each entry, and passed `createInertiaApp` no title, no
  server head and no nonce. It now declares `@inertiajs/vue3`,
  `@inertiajs/core` and `@inertiajs/vite` at `^3.8.0`, and `vite.config.ts`
  runs `inertia()`. Both entries name their pages with `pages: './pages'`. The
  SSR entry is the `createInertiaApp(..)` statement the plugin wraps with
  `createServer`, so `npm run build:ssr` still writes
  `frontend/bootstrap/ssr/ssr.js`. Because the kit declares the plugin,
  `suprnova serve` writes the hot file, and with SSR on, a first visit in
  development renders through the dev server's `/__inertia_ssr` with no worker
  running. The browser entry passes a `title` callback that appends the
  application's name, the same name the server's `default_title` uses,
  `serverHead: true`, and the nonce from `<meta property="csp-nonce">` when
  the document has one. `npm run check`, `npm run build` and
  `npm run build:ssr` pass on a fresh scaffold (K01, K05, K18, K19).
- **Vue kit pages navigate with `Link`, title themselves with `Head`, and
  share two persistent layouts.** Every page drew its own frame, reached
  other pages through `<a href>`, which reloads the whole document, and
  left the tab untitled. The kit now ships `layouts/AppLayout.vue`
  (navigation, the flash toast and a heading) and `layouts/GuestLayout.vue`
  for the pages under `auth/`, applied through the `layout` option so a
  layout stays mounted between two pages that share it. Both show
  `components/AccountLinks.vue`, which reads the shared `auth.user`: the
  name and a sign-out `Link` that posts as a button without keeping the
  page's state, or the sign-in and register links for a guest, so the home
  and error pages never offer a guest a sign-out. Every
  application link is a `Link` built from `root`, every page sets its title
  with `Head`, and the dashboard sets the layout's heading with
  `setLayoutProps`, which the next page clears (K06, K07, K16).
- **The Vue kit shows the flash toast.** The server's `page.flash` reached
  no kit page, so a sign-in, a sign-out or a saved note gave no feedback.
  `components/FlashToast.vue` renders `page.flash.toast`, typed by the
  generated `flashDataType`, in both layouts, straight from the page, so it
  shows once, on the page it was flashed for (K17).
- **The Vue kit's dashboard and notes pages use Inertia's client features.**
  The dashboard rendered one eager prop and the kit had no list page, so a
  new application had nothing to copy for deferred, optional or scroll
  props. `Dashboard.vue` now renders `stats` inside `Deferred` with a
  fallback, polls it with `usePoll(10000, { only: ['stats'] })`, loads
  `recent_notes` with `WhenVisible` when it scrolls into view, and saves the
  display name through `useHttp` with an optimistic update that a `422`
  reverts while showing `errors.name`; a saved name reloads the shared
  `auth` prop, so the layout shows it. The new `Notes/Index.vue` creates a
  note with `Form`, remembers its search with `useRemember`, lists the
  signed-in user's notes with `InfiniteScroll`, and opens one as an
  instant visit to the new `Notes/Show.vue` from a prefetching `Link`
  whose page props keep the shared props, `root` among them. The
  five auth pages submit through `Form` in place of `useForm`, read
  `errors` and `processing` from its slot, and keep the sign-in page's
  remember checkbox, sent as a boolean (K11, K12, K13, K14, K15, K21).
- **Signed-route middleware.** `ValidateSignature` lets a request with a
  valid signature reach the handler and answers a missing, wrong or expired
  one with `403` and `Invalid signature.`, as Laravel's
  `InvalidSignatureException` does. Build it with `ValidateSignature::new()`
  or `ValidateSignature::relative(ignore)`, or register
  `ValidateSignature::from_alias_args` as the `signed` alias, which reads
  `signed:relative,utm_source`.
- **Signature checks that ignore added parameters.** `ignore(names)` on the
  middleware, the alias arguments, `ValidateSignature::except(names)` for
  the whole application, `url::has_valid_signature_ignoring` and
  `verify_signature_ignoring` leave the named query parameters, such as a
  `utm_source` a mail client appends, out of the verified text. `signature`
  and `expires` cannot be ignored.
- **The previous path.** `url::previous_path(fallback)` returns the path of
  the session's previous URL without its query, the public root or a
  trailing slash, as Laravel's `url()->previousPath()` does.
- **Secure URLs with segments.** `url::secure_with(path, segments)` appends
  each segment percent-encoded as one path segment and upgrades the URL to
  `https` like `url::secure`. It is Laravel's `url()->secure($path,
  $parameters)`.

- **Error reporting callbacks.** `Exceptions::reportable` runs your callback
  for every reported error, or only for errors that wrap the type its closure
  takes; `.stop()` keeps later callbacks and the `framework error` log line
  from running for an error that callback receives.
- **Reporting an error you handle.** `Exceptions::report` sends an error
  through your callbacks and then the `framework error` log line.
- **Errors that end a job's retries.** `Exceptions::dont_retry::<E>()` and
  `Exceptions::dont_retry_when` name the errors that make the worker fail a
  queued job at once, whatever tries it has left;
  `Exceptions::should_stop_retries` answers for one error.
- **Error types on the development error page.** The page names the wrapped
  error's type, the `FrameworkError` variant, or `panic` above its headline,
  and `ErrorReport::type_name` returns the same name.
- **Editor links on the development error page.** With `APP_EDITOR` set,
  each frame's location links to its line in your editor: a Laravel editor
  name uses that editor's URL format, a value holding `{file}` is a template,
  and any other name opens `<name>://open?file=...&line=...`.

- **Required while a condition holds.** `RequiredIf::when(condition)` takes a
  `bool` or a closure answering one, requires the field with the required
  message while it holds and passes the field otherwise, as Laravel's
  `Rule::requiredIf` does.
- **Image dimensions on uploads.** `Dimensions<D>` reads an image's width and
  height from its header and refuses the file with `validation-dimensions`
  when it breaks the `min_width`, `max_width`, `min_height`, `max_height`,
  `width`, `height` or `ratio` a `DimensionLimits` type sets, or when its size
  cannot be read.
- **The IP address message.** `#[validate(ip)]` reads `The address field must
  be a valid IP address.` in place of the generic failure message.
- **Nested middleware names.** `make:middleware Admin/EnsureRole` writes
  `src/middleware/admin/ensure_role.rs` and declares each module on the way.
- **Middleware tests.** `make:middleware --test` writes a test under `tests/`
  that runs the middleware in front of a route through `TestClient`.
- **`make:view`.** `make:view admin.dashboard` (or `admin/dashboard`) writes
  `templates/admin/dashboard.html` and a `#[suprnova::view]` struct naming it
  in `src/views/admin/dashboard.rs`, declares its modules, keeps existing
  files unless `--force` is given, and with `--test` writes a test that
  renders it.
- **Nested Inertia pages.** `make:inertia Admin/Users` writes
  `frontend/src/pages/Admin/UsersPage.<ext>`, `--force` overwrites an
  existing page, and `--test` writes a test that renders the page and checks
  its file.

- **Trusted hosts.** The `TrustHosts` middleware answers `400 Bad request.`
  to a request whose host is invalid or matches none of your patterns.
  `TrustHosts::new()` trusts the `APP_URL` host and its subdomains,
  `TrustHosts::at(patterns, subdomains)` trusts the regular expressions you
  list, matched without regard to case, and the local environment trusts
  every host.
- **CSRF tokens in JSON bodies.** `CsrfMiddleware` reads a top-level string
  `_token` from a JSON body as it reads one from a form, ahead of the
  `X-CSRF-TOKEN` and `X-XSRF-TOKEN` headers, with `""` and `"0"` counting
  as no value.

- **Controller middleware.** A `ResourceController` lists `ControllerMiddleware`
  values in its `middleware` method, and a module named by `resource!` in a
  `pub fn middleware()`. Each runs on the actions `only` and `except` scope it
  to, after the group's middleware, and a name no alias or group carries fails
  the registration.
- **Resource middleware at registration.** `ResourceRoutes::middleware` and
  `ResourceDef::middleware` scope a `ControllerMiddleware` to some actions,
  running before the controller's own list.
- **Resources inside groups.** `resource!` is an item of `group!` and takes the
  group's prefix, name prefix, middleware, session block and binding settings.
- **Routes leave group middleware out.** `without_middleware::<M>()` and
  `without_middleware_named(name)` remove a middleware a route's group or its
  own registration gives it, by type or by alias; the global middleware still runs.
- **`route_has`.** Returns true only when every route name in a list is
  registered, as Laravel's `Route::has` does.

- **Encrypters with their own key.** `Encrypter::new(key)` encrypts and
  decrypts with `encrypt_string_for`, `decrypt_string_for`, `encrypt` and
  `decrypt` under the key you give it, and leaves `Crypt` as it was. It
  writes the payload `Crypt` writes, so a value either one wrote under a key
  opens with the other.
- **Key generation that returns its error.** `EncryptionKey::try_generate`
  and `Crypt::try_generate_key` return the refusal of the operating system
  random source as an error, where `EncryptionKey::generate` panics.
- **Gate checks for the signed-in user.** `Gate::inspect_current` and
  `Gate::none_current` check the user of the route's guard, the user
  `#[authorize]` checks. A guest reaches only the gates defined with
  `define_optional`, which receive `None`, and every other ability answers
  the default denial.
- **After hooks that see the resource.** `Gate::after_with_arguments`
  registers an after hook that receives the resource with the user, the
  action and the running decision, and fills only an undecided result.
- **`GateEvaluated` events.** Every gate check dispatches `GateEvaluated`
  with the user's type, the user's identifier when the check found the user
  itself, the action, the resource's type and the decision.
- **Request guards that receive their provider.**
  `Auth::via_request_with_provider` hands the resolver the request and the
  user provider that the guard's configuration names.
- **Rate-limiter hits with a default or a date.** `RateLimiter::hit_for_minute`
  counts a hit in a 60-second window, as Laravel's `hit($key)` does, and
  `RateLimiter::hit_until` counts one in a window that ends at a given time; a
  time that has passed opens no window.
- **Guest and user throttle limits.** `throttle:10|60,1` allows a guest 10
  requests a minute and a signed-in user 60, as Laravel's `throttle` reads
  its first argument.
- **Throttle counts that stop at the limit.** The throttle middleware checks
  every limit before it counts a request, then counts each bucket with one
  conditional increment that leaves a full bucket's count where it was, so a
  request refused at either step is not counted in the bucket that refused
  it, and a concurrent burst admits at most the limit. Limits whose keys
  collide count under the keys the limiter returns, so two limits on one key
  share one bucket, the bucket `RateLimiter::attempts` reads.
- **Conditional increments.** `CacheStore::increment_if_below` and
  `Cache::increment_if_below` add to a counter only while it is below a
  ceiling and answer `ConditionalIncrement::Incremented` with the new value
  or `ConditionalIncrement::Unchanged` with the value as it stands. The
  in-memory and Redis stores compare and write in one atomic step; a custom
  store gets a default that reads and then increments.
  `RateLimiter::increment_if_below` does the same for a rate-limiter bucket
  and opens its window as `increment` does.
- **Named hasher drivers.** `hashing::extend` registers a driver under a name
  and `HASH_DRIVER` selects it, as Laravel's `Hash::extend` does; it refuses a
  built-in algorithm's name, a name registered before, and a registration
  after the first hash.
- **`ARGON_TIME`.** The hashing configuration reads Laravel's `ARGON_TIME` as
  the Argon time when `HASH_TIME` is unset; `HASH_TIME` still wins.
- **The verified gate redirects by route name.**
  `EnsureEmailVerifiedMiddleware::redirect_to_route(name)` resolves the route
  on each request; a name no route carries fails the request with a `500`
  whose error names it.
- **Your own verification message.**
  `MustVerifyEmail::send_email_verification_notification` sends the
  verification link, and a model overrides it to send its own message.
  `EmailVerification::send_link` calls it, and `resend` calls it through the
  new `UserProvider::send_email_verification_notification`. The default sends
  the new `VerifyEmailNotification`, a mail notification through `Notify`
  that reads as the mail did, and needs no notification setup.
- **Your own reset message.** `CanResetPassword::send_password_reset_notification`
  sends the reset link on the provider path, through the new
  `UserProvider::send_password_reset_notification`; the default sends
  `PasswordResetMail` to `email_for_reset()`.
- **A timebox on reset links.** `PasswordReset::send_link` holds every
  answer, a refusal and an error included, until `PASSWORD_RESET_TIMEBOX_MS`
  milliseconds (200 by default) have passed, so an unknown address answers no
  sooner than a known one.
- **A rehash step in the sign-in.** `UserProvider::rehash_password_if_required`
  runs after the password validates and before the user is signed in, in
  `attempt`, `once` and `Auth::logout_other_devices`.
- **Attachments compared by content.** `Attachment::is_equivalent` and
  `is_equivalent_with` compare the name, bytes and content type, and
  `OutgoingMessage::has_equivalent_attachment` and `has_attached_data` check
  a sent message with them; `has_attachment` still matches the name only.
- **Raw data attachments on the builder.** `MailBuilder::attach_data(bytes,
  name, content_type)` attaches in-memory data, as Laravel's `attachData` does.
- **A mailable's own recipients.** `Mailable::to`, `cc`, `bcc` and `reply_to`
  give a mailable its own lists; a send or a queue merges them ahead of the
  builder's, skips an address already present, and `Mail::always_to` still
  replaces every recipient.
- **Mailables sent alone.** `Mail::send`, `Mail::queue`, `Mail::later`,
  `Mail::on_queue` and `Mail::queue_on` send or queue a mailable to its own
  recipients and refuse one with none before anything is sent or pushed.
- **Boolean mail fake checks.** `MailFake::has_sent`, `has_sent_mailable::<M>()`
  and `has_queued` answer whether a mailable was sent or queued; a queued
  mailable does not count as sent.
- **Mailable delays.** `Mailable::delay` delays `Mail::queue` and
  `MailBuilder::queue`; an explicit `later` delay wins.
- **Notification delays per channel.** `Notification::delay(channel)` delays
  that channel's job when `Notify::queue` pushes it.
- **`BroadcastNotificationCreated`.** The broadcast notification channel
  dispatches it with the notification's name, the route, the data and the
  message's queue and connection, after the publish or the push.
- **Queued broadcast notifications.** A notification that implements
  `NotificationBroadcast::to_broadcast` and is registered with
  `register_broadcast_renderer` supplies a `BroadcastMessage`; one that names
  a queue or a connection with `on_queue` or `on_connection` is published by
  a queued `BroadcastNotificationJob`, which the worker knows without
  registration.
- **Notification mail attachments by path.** `MailRendering::attach`,
  `attach_data`, `attach_path` and `attach_many` attach files, the last two
  with `AttachOptions` for the name and content type; files are read at
  delivery, the content type follows the extension, and a file that cannot
  be read fails the delivery naming the path.
- **Delayed queued listeners.** `QueuedListener::delay(duration)` and
  `delay_until(|event| ...)` delay the listener's job, winning over the job's
  own `Job::delay`.
- **Per-connection after-commit.** `QUEUE_<CONNECTION>_AFTER_COMMIT` and
  `Queue::set_connection_after_commit` give a queue connection its own
  after-commit setting, which `Queue::connection_after_commit` reads.
- **A job's own after-commit choice.** `Job::after_commit_choice()` answers
  `Some(true)`, `Some(false)` or `None`, so a job can push ahead of the
  commit even when its connection or `QUEUE_AFTER_COMMIT` waits.
- **A Pusher HTTP API client.** `PusherClient::new(config, registry)` and
  `PusherBroadcastHub::client()` query channels and presence users, publish
  a batch in one request, end a user's connections and send any other
  signed `GET`, with channel names through the registry's wire mapping and
  errors that never quote the secret or a signature.
- **Marked console lines.** `console::error`, `console::warn` and
  `console::info` print one line marked `ERROR`, `WARN` or `INFO`, on the
  standard error for the first two and the output for the third, styled on a
  terminal unless `NO_COLOR` is set and plain text in a test.
- **Console verbosity flags.** Every command accepts `-q` or `--quiet` and
  `-v` to `-vvv` before its name, and after it unless it takes raw arguments
  or declares a flag of that name itself. `console::verbosity()` reports the
  level, `console::line_at` and `console::error_at` write only at or above a
  level, and `--quiet` silences a command's lines while the error of a failed
  command still prints.
- **Console prompts.** `console::ask_with_default`, `console::secret`,
  `console::select`, `console::select_keyed` and `console::multiselect` read
  one line each, from a terminal or a pipe; `secret` does not echo on a
  terminal and is never captured, and a menu refuses an answer that is no
  option by naming the options.
- **Answers for menus in tests.** `ConsoleTest::expects_choice(question,
  answer, options)` answers a menu and fails the command when the menu offers
  other options.
- **Progress bars.** `console::Progress` and `console::progress(label, items,
  f)` redraw a terminal line, and write one plain line such as `Sync 3/3`
  where the output is not a terminal.
- **Console forms.** `console::form()` chains `text`, `secret`, `confirm` and
  `select` steps and returns every answer by name from `submit()`.
- **Up-front console test expectations.** `ConsoleTest::expects_output(line)`
  expects exact lines in order, `expects_output_to_contain(text)` and
  `doesnt_expect_output_to_contain(text)` search one write at a time on both
  streams, and `expects_confirmation(question, answer)` answers a `confirm`
  with yes or no.
- **Exit codes of a command's own.** `FrameworkError::exit(code)` ends a
  console command with `code`, printed and reported nowhere, and
  `FrameworkError::exit_code()` reads the code the console binary ends with;
  `ConsoleRun::assert_exit_code(code)` and `assert_not_exit_code(code)` assert
  it, and exit code `0` is a success.
- **`MaintenanceModeEnabled`.** `down` dispatches the event after it records
  maintenance mode, on a first `down` and on an update alike.
- **Prerendered maintenance pages.** `down --render <view>` renders the Tera
  template at `resources/views/<view>` with `retry_after` and serves the
  result; a template that cannot be read or rendered fails `down` before
  maintenance mode starts.
- **Retry dates.** `down --retry` takes a date as well as seconds and sends it
  as `Retry-After` in the RFC 7231 form; a value that is neither is refused.
- **Tasks limited to environments.** `TaskBuilder::environments` keeps a task
  to the named environments at every tick.
- **Tasks in maintenance mode.** While the application is down, `schedule:run`
  and `schedule:work` skip every task that does not ask
  `TaskBuilder::even_in_maintenance_mode`; a maintenance state that cannot be
  read counts as down.
- **Day splicing on expressions.** `CronExpression::with_days_of_week`
  replaces the day-of-week field and keeps the others.
- **Loaded migrations.** `Application::load_migrations_from(list)` adds a list
  that `migrate`, `migrate:status`, `migrate:rollback`, `migrate:fresh`,
  `schema:dump` and the migration on boot run after the application's
  migrator, each migration name once.
- **Registered migrations.** A crate registers its own list with
  `suprnova::register_migrations!(owner, list)`, and every application that
  links the crate runs it.
- **One list for two-factor migrations.** `auth_flows::two_factor::migrations()`
  returns the four two-factor migrations in order.

- **Directories that may exist already.** `DiskExt::ensure_directory_exists`
  creates a directory unless it is there, and succeeds when it is.
- **Upload URLs from your own callback.**
  `Storage::build_temporary_upload_urls_using(disk, callback)` answers the
  disk's `temporary_upload_url` from the callback, which receives the path
  and the lifetime, ahead of the disk's own presigning; a read-through disk
  and an S3 disk answer from it too.
- **Asking a disk about upload URLs.** `Storage::provides_temporary_upload_urls`
  answers whether a disk has an upload URL callback or presigns writes.
- **Faked processes keep their argument list.** A recorded process keeps its
  arguments, `None` for a shell line, and its quoted command line;
  `assert_ran_args` and `assert_ran_command_line` compare them exactly, while
  `assert_ran` keeps matching the arguments joined by spaces.
- **One-side resizes.** `Image::resize_width_only` and `resize_height_only`
  set one side and keep the other at the size the image has at that point of
  the pipeline, on the `oxideav` and `magick` drivers alike.
- **Custom transformations with settings.** `register_transformation_with`
  registers a function that receives per-call settings of its own type, and
  `Image::transform_with(name, settings)` records a step that hands them to
  it. The image holds the settings and releases them with its last clone; a
  step whose settings are of another type fails the image with an error
  naming the transformation.
- **HEAD requests.** `Http::head(url)` sends `HEAD`.
- **Global HTTP middleware and options.** `Http::global_request_middleware`,
  `global_response_middleware` and `global_options` apply to every request
  created after them, and `Http::without_global_configuration` creates
  requests without any of them. Registered inside an `Http::fake` scope they
  belong to that scope.
- **Building the request URL.** `RequestBuilder::base_url` goes in front of a
  URL without a scheme, `query` merges pairs into the URL's query, and
  `url_parameters` expands `{name}` placeholders with each value
  percent-encoded, so a value cannot add a path segment, a query or a host.
- **Multipart uploads.** `RequestBuilder::attach(name, contents, filename)`
  sends the body as `multipart/form-data`.
- **A connect timeout per request.** `RequestBuilder::connect_timeout`
  replaces the shared client's 10 seconds for one request.
- **HTTP stubs that stay.** `Http::fake_url` answers every request whose URL
  matches a pattern, `Http::fake_using` asks a callback that may pass with
  `None`, and `Http::fake_sequence` answers in turn and then with its
  `when_empty` response, each with a `FakeResponse`.
- **Reading a recorded request.** `RecordedRequest::header`, `has_header`,
  `is_json`, `is_form` and `is_multipart` compare header names without regard
  to case.
- **Laravel's stray-request names.** `Http::prevent_stray_requests(on)` and
  `Http::preventing_stray_requests()` move and read the switch
  `fail_on_real_calls` moves, and `Http::allow_stray_requests(patterns)` lets
  a request inside a fake that no stub answers reach the network when its URL
  matches.

- **Vite tags for any page.** `Vite::tags(entries)`, `Vite::to_html()` and
  `InertiaConfig::vite_tags(entries)` render the build manifest's scripts,
  stylesheets and preloads for any number of entry points, each file once and
  every stylesheet before the first script, under the public root; a missing
  manifest is an error that names its path, and a missing entry one that
  names the entry.
- **Entry points beside `entry_point`.** `InertiaConfig::entry_points` adds
  entries, such as a stylesheet entry, that the Inertia document and
  `Vite::to_html()` load with the main one.
- **The hot file, readable.** `InertiaConfig::hot_file`, `Vite::hot_file`,
  `Vite::is_running_hot` and `Vite::dev_server_url` answer the hot file's
  path, whether it exists and the dev server URL it holds; production never
  reads it.
- **The document head.** `Head` resolves the title (with an inherited prefix
  or suffix), description, canonical URL and robots directives from the
  defaults, route groups and routes (`with_head`), run-time calls and error
  statuses (`Head::errors`), field by field; `Head::render_html` renders the
  escaped tags and `Head::to_array` returns them as data.
- **The head on Inertia pages.** Every Inertia response that a head layer
  sets something for shares the head as a `head` prop of keyed tags, left out
  of partial reloads and renamed with `Head::inertia`; the first visit writes
  the tags once, deduplicated against the SSR head, and `Head::inertia_globals`
  adds tags for the first visit only.
- **Head metadata beyond the title.** Open Graph values and media, X cards
  filled from the page, theme colors, application metadata and icons, `pwa`,
  resource hints, locale alternates, feeds, pagination links, custom meta and
  link tags, and JSON-LD schemas with breadcrumb and FAQ builders.
- **Precognition answers from any error bag.**
  `Precognition::after_validation(&request, errors)` answers a precognitive
  request with `204` or `422`, and passes an ordinary one or fails it with the
  ordinary validation error.
- **The Precognition selection in hooks.** `Precognition::should_validate(field)`
  answers whether a precognitive request listed the field while a form
  request's, a data object's or a multipart form's after-validation hooks run.
- **Fallible CSRF helpers.** `try_csrf_token()` and `try_csrf_field()` return
  an error that names the missing session.
- **Raw cookies.** `Cookie::raw(name, value)` writes its value without
  percent-encoding, and refuses a name that is not an RFC 6265 token or a value
  byte outside cookie-octet; `Cookie::is_raw` tells the two forms apart.
- **Shared view data.** `View::share`, `View::share_for_request` and
  `View::shared` hand values to every checked view through Askama's runtime
  values; a value shared for one request never reaches another request, the
  render cache included.
- **Inline Markdown.** `Str::inline_markdown` and
  `MarkdownRenderer::render_inline` render emphasis, code, links and line
  breaks with no paragraph around them, and keep block markers such as `#`
  as text; `Str::markdown` renders a whole document as a string.
- **Markdown input choices.** `MarkdownRenderer` gains
  `html_input(HtmlInput::Sanitize | Strip | Escape | Allow)`,
  `allow_unsafe_links` and `autolink`; a renderer that calls none of them
  renders as before.
- **Fluent strings.** `Str::of` returns a `Stringable` that chains the `Str`
  helpers, `markdown` and `inline_markdown`, and converts to and from
  `String`.
- **Purpose-bound string encryption.** `Stringable::encrypt`, `encrypt_for`,
  `decrypt` and `decrypt_for` seal and open a value through `Crypt` under a
  `CryptPurpose`.
- **Descending sort.** `Collection::sort_desc` orders `Ord` items from
  greatest to least and keeps equal items in their order.
- **Ordered key maps.** `Collection::map_with_keys` collects pairs into an
  `IndexMap` in the collection's order; a repeated key keeps its first
  position and its last value.
- **Dates from text.** `Date::parse`, `Date::parse_in` and `Date::raw_parse`
  read RFC 3339, dates, date-times, Unix seconds and named relative forms
  such as `tomorrow 09:30`, `+2 days` and `first day of next month`,
  reading the framework clock, and refuse other text with a
  `DateParseError` that names it.
- **Priority list controls.** `default_middleware_priority`,
  `set_middleware_priority`, `add_to_middleware_priority_before` and
  `add_to_middleware_priority_after` read, replace and insert into the
  middleware priority list.
- **Value pipelines.** `Pipeline::of(value)` sends any value through steps,
  with `through`, `pipe`, `pipe_all`, `finally`, `within_transaction`,
  `then` and `then_return`; a step is a function, an async closure, or a
  type that implements `PipelineStep`.
- **Appending several middleware.** The HTTP `Pipeline::pipe_all` appends
  middleware after those `through` set.
- **More catalog directories.** `Lang::add_path` merges a directory after
  `lang/` and `Lang::add_fallback_path` one before it; the translator the
  framework binds at boot reads every directory registered before then.
- **Namespaced translations.** `Lang::add_namespace` reads a package's
  catalogs as `namespace::key`, overridden by
  `lang/vendor/<namespace>/<locale>/`; the browser catalog holds them as
  `namespace__key`, and the starter kits' `t()` encodes keys the same way.
- **Translation sources.** `Lang::loader` answers the directories and
  namespaces the translator reads, and `FluentTranslator::from_sources`
  builds a translator from them.
- **Bindings chosen by environment.** `#[service]` takes
  `bind(Concrete, env = [...])` entries; at boot the first entry whose
  pattern matches the environment is bound, and `impl` when none does.
- **Renamed route parameters.** `#[route_param("name")]` on a handler
  argument reads the route parameter of that name, and an argument spelled
  `r#type` reads `type`.
- **Lazy singletons.** `App::singleton_lazy` and
  `App::singleton_lazy_if_absent`, and the same on `Container` and
  `TestContainer`, build a singleton on its first resolve and share it; a
  factory that resolves its own type gets an error.
- **AI-assisted development chapter.** The manual shows how an assistant
  reads it as Markdown and through `llms.txt`, how to install the Suprnova
  language server, and how to point an assistant at a project.

- **Configuration defaults that never overwrite.** `Config::register_default`
  registers a value only when none of its type is registered and answers
  whether it did; `Config::merge` merges a map of defaults under the
  registered one, the application's keys winning, through `MergeConfig`.
- **Environment detection that tells unset from named.**
  `Environment::detect_explicit` answers `None` when `APP_ENV` is unset.
- **Cache connections by name.** With `CACHE_DRIVER=redis` the store runs its
  commands on the Redis connection `REDIS_CACHE_CONNECTION` names, `cache`
  by default, and its locks on `REDIS_CACHE_LOCK_CONNECTION`, `default` by
  default; `CacheConfigBuilder::connection` and `lock_connection` name them in
  code, and `RedisCache::connect_named` builds the store on them.
- **Moving the cache to another connection.** `Cache::set_connection` moves
  the bound Redis store's later commands to another named connection, and
  answers an error for a store without one.
- **Cache hit and miss events.** `Cache::get`, `has` and `missing`, and every
  read built on them, dispatch `CacheHit` and `CacheMissed` with the store's
  name and the key; a hit that fetched the value carries it, and its `Debug`
  output leaves it out.
- **A lifetime read from the cached value.** `Cache::remember_with_ttl` takes
  the lifetime of a computed value from a closure over it: `None` stores it for
  the configured default, `Some(Duration::ZERO)` returns it unstored.
- **MySQL character set and collation.** On a MySQL or MariaDB URL,
  `DatabaseConfig` carries `charset` and `collation` from `DB_CHARSET` and
  `DB_COLLATION` (`utf8mb4` and `utf8mb4_unicode_ci`), a URL parameter winning,
  and every connection sends them with `SET NAMES`.
- **Table character set and collation.** `Schema::create` gives a new MySQL
  table the configured character set and collation, and
  `Blueprint::charset` and `Blueprint::collation` name its own.
- **The `Log` facade's level methods.** `Log::emergency` through `Log::debug`,
  a `*_with` form of each and `Log::log` write to the default channel through
  `tracing`, and a file or stack channel keeps their own level, `CRITICAL`
  included.
- **Logger context.** `Logger::with_context` and `without_context` return a
  logger whose writes carry a context, and `Logger` has a `*_with` form of
  every level.
- **Shared log context.** `Log::share_context` adds a context to every later
  write of the current request or job, with `Log::shared_context`,
  `Log::without_context` and `Log::flush_shared_context`.
- **Log listeners.** Every write that reaches a channel dispatches
  `MessageLogged`, and `Log::listen` registers a callback for each write.
- **Placeholders per channel.** `LogChannel::replace_placeholders(false)` keeps
  a channel's messages as templates, and a stack gives each channel its own
  form.
- **Log level names.** `LogLevel::parse` reads the eight PSR-3 names and
  `warn` and `trace`, and `LOG_LEVEL` accepts the PSR-3 names.
- **Test client default headers.** `TestClient::with_header` and
  `with_headers` send headers on every request the client builds, a
  request's own header winning, and `flush_headers` clears them.
- **`QUERY` requests in tests.** `TestClient::query_json` sends a `QUERY`
  request with a JSON body and the JSON content type and accept headers.
- **Acting as a user in tests.** `TestClient::acting_as` signs a user into
  the default guard for every request, and `acting_as_with_guard` into a
  named guard; an unregistered guard fails the request naming it.
- **No-content assertions.** `TestResponse::assert_no_content` passes only
  for an empty `204`, and `assert_no_content_status` for an empty response
  of another status.
- **Typed queued mailables in the mail fake.** `MailFake::queued_of::<M>()`
  and `queued_where::<M>(filter)` rebuild queued mailables as `M`, and
  `assert_queued_mailable::<M>` and `assert_not_queued_mailable::<M>` assert
  on them; a payload that does not rebuild fails the call, and the `try_*`
  forms return the error.
- **Fallible typed pushes in the queue fake.** `queue::testing::try_pushed::<J>()`
  returns the decode error that `pushed::<J>()` now panics with.
- **Workers on the queue fake.** `QueueFakeGuard::driver()` returns a driver
  a worker reserves the recorded jobs from, and `queue::testing::reserved::<J>()`
  and `try_reserved::<J>()` return each reservation typed.
- **Full-text search.** `where_full_text` and `or_where_full_text` on
  `DB::table` and the model builder render `MATCH ... AGAINST` on MySQL and
  MariaDB and `to_tsvector ... @@` on Postgres, with `FullTextOptions` for the
  mode, the language and query expansion; SQLite returns an error.
- **Full-text indexes.** `Blueprint::full_text` creates a `FULLTEXT` index on
  MySQL and MariaDB and a `GIN` index over `to_tsvector` on Postgres, with
  `.language(..)`, and `drop_full_text` drops it; SQLite refuses both.
- **Tests on the configured database.** `TestDatabase::refresh` migrates the
  database `DATABASE_URL` names once per test process and holds each test in a
  transaction rolled back when the helper drops; `refresh_lazily` does the same
  on the first query.
- **Migrations rolled back after a test.** `TestDatabase::migrate` runs the
  migrations on `DATABASE_URL`'s database and rolls back the ones it ran when
  the helper drops.
- **Seeding test databases.** `TestDatabase::seed` runs a named seeder and
  `seed_root` the root seeder before the test body.
- **`#[suprnova_test]` database keys.** `refresh` runs the test through
  `TestDatabase::refresh`, and `seed` or `seed = Path` seeds before the body.
- **A Web Push endpoint allowlist.** In 3.2.1, `EndpointPolicy` offered
  `Strict`, which refuses local and private destinations but passes any
  public host, and `AllowAny`, so a tampered subscription could still make
  the server POST to a public host of the attacker's choice.
  `EndpointPolicy::Allowlist` takes an `EndpointAllowlist` of push-service
  origins, `https://host` or `https://host:port`, where a leading `*.`
  label matches exactly one label, as `https://*.notify.windows.com` needs.
  It runs every `Strict` check and refuses an endpoint at any other origin
  before the host name is looked up, with the new
  `WebPushError::OriginNotAllowed`, which carries the origin and never the
  path of the endpoint and is not retryable. `WebPushChannel` sends under
  that policy, in place of its client's own, when `WEB_PUSH_ENDPOINT_ORIGINS`
  names one or more origins, and logs a refused endpoint as a subscription
  that cannot be used. `WebPushChannel::new` reads the variable and returns
  a `Result`: an entry that is not an origin fails it with an error that
  names the variable. `WebPushClient::send_with_policy` sends under a policy
  other than the client's own, and `EndpointPolicy` is no longer `Copy`.
  The Web Push chapter lists the origins of the Firefox, Chrome, Safari and
  Edge push services.

### Changed

- **Runtime threads have an 8 MiB stack.** `#[suprnova::main]` builds its
  Tokio runtime with `thread_stack_size` set to 8 MiB for the worker and
  blocking threads, the size Linux gives the main thread, in place of
  Tokio's 2 MiB default. In a debug build the frames the framework puts
  under a Live action (the server, the middleware, the session, the render
  cache and the Live engine) use about 1.75 MiB of a 2 MiB stack, so an
  action a little deeper, such as a password reset, overflowed it and
  aborted the server. The size is reserved address space; a thread uses
  memory only as its stack is touched.
- **Typed factory counts.** `count` and `times` make `make` and `create`
  return vectors while uncounted factories keep their single-model results.
- **Laravel boolean storage.** MySQL and SQLite boolean columns use
  `tinyint(1)` and retain false and true when you read their rows.
- **Default float precision.** Float columns use 53 binary digits on MySQL
  and Postgres, with explicit precision available through the column modifier.
- **Whole-second zoned timestamps.** Postgres uses `timestamp(0) with time zone`
  by default, and SQLite declares `datetime` for zoned timestamp columns.
- **Production seeding requires force.** `db:seed` returns an error in
  production unless you pass `--force`; `suprnova db:seed --force` passes
  the flag through to the console binary.
- **Console test assertions check every expectation.**
  `ConsoleRun::assert_successful` fails on a prepared question the command did
  not ask and on every unmet output expectation, which `unmet_expectations()`
  lists; a question the test did not expect fails `assert_successful`,
  `assert_failed` and the exit-code assertions, naming it, even when the
  command goes on, and `unexpected_questions()` lists it.
- **The console binary ends with the command's exit code.** A new project's
  `src/bin/console.rs` ends with `ExitCode::from(error.exit_code())`; an
  existing project replaces `Err(_) => ExitCode::FAILURE` with that arm to end
  with the code of `FrameworkError::exit`.
- **A wrong method answers 405.** A request whose path a route of another
  method matches answers `405` with `Allow` and Laravel's message in place of
  the 404, and an `OPTIONS` request answers `200` with `Allow`. Both run
  through the global middleware; a path no route matches keeps the 404 or the
  fallback.

- **Collection metadata belongs to the collection.** JSON:API collections
  keep their document metadata at the root without merging the first item's metadata.
- **Empty results have page one.** Length-aware pagination reports one last
  page and includes its page-one link when there are no matching rows.
- **Model ordering follows timestamp declarations.** `oldest` and `latest` use
  the model's declared creation column, including renamed timestamps.
- **Force destruction includes trashed rows.** `force_destroy` physically
  removes matching soft-deleted rows and counts each existing key once.
- **Model visibility applies to serde and appends.** Array, JSON, and serde
  outputs share the hidden and visible lists, including appended accessors.

- **`Storage::purge` takes the disk name.** The zero-argument `purge()` that
  dropped every disk is `purge_all()`; `purge(name)` drops one disk and reports
  whether it was registered.
- **Excerpts trim invisible characters.** Cut ends now remove Laravel's
  invisible character set, including zero-width spaces, while preserving
  characters inside the excerpt.
- **Redis prefixes typed keys.** Typed methods, scripts, blocking commands,
  and typed pipeline methods apply `REDIS_PREFIX`, defaulting to the app
  name's slug followed by `-database-`. Raw commands retain their arguments.
- **Redis events reach application listeners.** Enabled command and failure
  events now dispatch through `EventFacade`, alongside the existing Redis
  listeners. Pipeline and transaction commands stay outside these events.

- **Daily logs keep seven files by default.** The `daily` channel and
  `LogChannel::daily` keep 7 files unless `LOG_DAILY_DAYS` or `.days(...)`
  sets another count; 0 keeps every file.
- **Syslog names the application.** Datagrams use `APP_NAME` as the ident,
  with `suprnova` when unset, and keep each record's facility and severity.
- **Percentages round decimal ties half up.** Percentages now round
  `0.12345` at four fraction digits to `0.1235%`.
- **Special number spellings.** Number formats use `∞` and `NaN` for values
  without a finite decimal representation.
- **File and disk responses answer byte ranges.** A GET range receives
  `206` with the selected bytes and `Content-Range`; an unsatisfiable range
  receives `416`. Responses advertise `Accept-Ranges: bytes` and include
  the file's modification time as `Last-Modified`.
- **Production browser failures show a minimal HTML view.** With debug
  off, a browser's 5xx page shows its status without error details.
  Inertia visits keep the application error page and JSON clients keep
  their JSON response.
- **Debug frames show source and separate error traces.** Application
  frames include nearby source lines when the file is readable. Each
  recorded source error has its own trace.
- **The implicit default disk is local.** Without a default named in code
  or `FILESYSTEM_DISK`, `Storage::default_disk()` returns `local` or an
  error naming `local` and `FILESYSTEM_DISK` when it is not registered.
- **S3 accepts Laravel's AWS variables.** Bucket, region, credentials,
  public URL, endpoint and path-style settings read the AWS names when
  their S3 names are unset. Each explicit S3 value wins.
- **Nullable-user policies authorize guests.** A policy accepting
  `Option<&User>` receives `None` for a guest and decides whether the
  handler runs. Policies requiring a user keep the `401` response.
- **Handler authorization accepts enum abilities.** An enum variant
  implementing `Into<String>` reaches the same async gate as a string
  ability.
- **Merged validation hook errors.** Real form and multipart requests run both
  after-validation hooks after field rules and return their combined errors.
- **Classic form validation redirects.** A failed form that prefers HTML
  redirects back with errors and old text input flashed to the session.
- **Unsigned MySQL IDs by default.** `id()` and `foreign_id()` match Laravel's
  unsigned keys. `unsigned_ids = false` keeps signed IDs through
  `#[suprnova::main]` or `Schema::set_unsigned_ids(false)`.
- **Nullable default timestamps.** `timestamps()` creates nullable `created_at`
  and `updated_at` on every database. The scaffold documents the schema defaults
  and carries the signed-ID opt-out and model cast setting commented out.
- **Query conditions follow SQL precedence.** Every `or_` helper adds a
  flat `OR`, so `where(a).or_where(b).where(c)` is `a OR b AND c`.
  The grouped column helpers keep their parentheses, and model scopes
  still constrain the whole caller condition list.
- **Null equality values compile to `IS NULL`.** Both builders rewrite
  a null `where` or `or_where` comparison instead of binding it after `=`.
- **Joined builders update and delete matching rows.** Both builders
  preserve the join when writing the base table; model deletion still
  honors soft deletes. The model builder also exposes `update` and `delete`.
- **A clean model save skips the update.** Dirtiness comes from the instance's
  original values in memory, and a clean save runs no update, where 3.2.1 ran
  the update and fired `Updating` and `Updated` on every save. `Saving` and
  `Saved` still fire, while `Updating` and `Updated` fire only for a dirty
  save.
- **Pivot sync returns the changed ids.** `sync` and
  `sync_without_detaching` return `SyncChanges` with attached, detached and
  updated id lists instead of `()`.
- **Pivot sync updates per-id columns.** Both methods accept `(id, Attrs)`
  records and update existing rows only when their supplied columns change.
  Unchanged rows keep their pivot columns and timestamps.
- **Pivot filters constrain sync.** Both methods honor `where_pivot` and
  its companions for the current set, updates and detachments, leaving
  rows outside the filter untouched.
- **Pivot sync touches a configured parent.** A relation's `.touch_parent()`
  or a related model's inverse touch declaration enables the parent timestamp
  update, in the same transaction as the pivot changes.
- **Queue assertions filter unchained jobs.** `assert_pushed_without_chain`
  takes a closure, so a matching job must also carry no chain.
- **Queue counts and clearing accept a queue name.** You can select one queue
  on every driver; SQS uses `SQS_QUEUE` when you pass none.
- **SQS accepts FIFO queues.** Jobs carry a message group and deduplication
  ID, with `default` and a payload digest as defaults, and sends omit delays.
- **SQS overflow supports named cache stores.** `SQS_OVERFLOW_STORE` takes
  precedence over the disk, and clearing keeps other queues' payloads.
- **Processes remove inherited environment variables.** Passing `None` to
  `env` removes the variable before starting the program.
- **TTY processes require terminal input and output.** An error names the
  redirected stream; a terminal process captures no output.
- **Process diagnostics quote command arguments.** Results and errors use
  POSIX shell quoting while fake patterns keep the arguments joined by spaces.
- **Stopping a process accepts a signal.** The default sends terminate and
  waits 10 seconds before killing the process and its descendants.
- **Process fake handlers accept closures.** You can inspect the pending
  command, path, environment and input before returning a result.
- **Described process fakes replay mixed streams in order.** Each described
  output or error output line ends with one newline.
- **Process run-count assertions default to once.** `assert_ran_times` checks
  one run; `assert_ran_count` accepts an explicit count.

- **Precognition requires the route middleware.** A route must carry
  `Precognitive` for the header to count. Previously every form request
  answered the header; a route without the middleware now handles it as
  a real request.

- **Inertia DevTools recording is opt-in.** 3.2.1 had no Inertia DevTools. An
  application records requests and serves the entries endpoints only when it
  passes `.devtools(DevToolsConfig::new())` to its `InertiaConfig`; without
  the call nothing is recorded and no entries are served. The scaffold and
  dogfood application opt in. A configured instance records when `APP_ENV`
  names `local`, or as its `enabled(..)` says (DT-01).
- **The starter keeps an existing notes table.** The scaffold's notes
  migration, new in 4.0.0, checks for the table before creating it, like the
  users migration, so a project using an existing Laravel database keeps its
  own notes schema and rows (K21).

- **The built-in image driver's PNG, BMP and WebP codecs come from the
  eas4ai forks** of `oxideav-png`, `oxideav-bmp` and `oxideav-webp` while the
  upstream pull requests are open (OxideAV/oxideav-png #18 to #25, oxideav-bmp
  #11 to #17, oxideav-webp #35 to #43). The encoders copy less: a PNG is
  written into a buffer with room for the metadata added after it, so adding
  an orientation tag to a 512 x 512 noise PNG does not move its 1 MiB file a
  second time, and a BMP into a buffer reserved at the file's exact size;
  lossy WebP is encoded from the converted planes where they lie, and lossless
  WebP from the pixels, instead of from a copy of each. Lossless WebP chooses
  its transforms in one pass rather than by exhaustive search: a 1024 x 1024
  photo encodes in about half a second instead of 47.8 s in a release build,
  and processing a 64 x 64 image to lossless WebP allocates 0.76 MB in all
  instead of 1.23 GB. Its files are at most 8.7 percent larger. The forks
  carry three fixes of their own, each offered upstream (oxideav-png #26,
  oxideav-bmp #18 and #19): a PNG is decoded without inflating its `iCCP`
  profile or XMP packet, which `oxideav-png` 0.1.11 and later inflated, up to
  64 MiB each, before `IMAGE_MAX_ALLOC_BYTES` could count them (a crafted
  profile held 118,213,096 bytes under a 4 MiB budget); a BMP is decoded
  without a copy of its embedded profile (5,242,912 bytes allocated for a 1024
  x 1024 RGBA file with a 1 MiB profile, now 4,194,336); and a BMP with a
  profile is written by an encoder that borrows the profile. An RGBA PNG is
  also decoded without the second copy of its pixels the crate's RGBA entry
  made (1 MiB for a 512 x 512 image). The forks follow upstream master, which
  changes three kinds of output: an image decoded from a lossy WebP, whose
  colour conversion `oxideav-webp` 0.3 corrected to within one level of
  libwebp's (pixels move by up to 16 levels); a PNG with more than 1 MiB of
  filtered data, which `oxideav-png` 0.1.12 deflates in 1 MiB pieces, so its
  bytes can differ (a 1024 x 1024 noise PNG is 4,196,716 bytes instead of
  4,196,676); and lossless WebP with transparency, written in the simple
  lossless layout, its alpha declared in the `VP8L` header, rather than behind
  a `VP8X` header.
- **The project file is `suprnova.toml`, all lowercase.** `suprnova serve`
  reads its extra dev processes from `suprnova.toml`, and `live:add` keeps
  its records there. A project that holds a `Suprnova.toml` must rename it:
  until it does, `serve` and `live:add` refuse to run and name the rename.
- **`live:add --manifest` installs only from a signed library tree.** A
  third-party manifest now sits in a library tree, beside the
  `library.json` that names its namespace and key, and installs only with a
  valid signature. A manifest holds no `version`, and the shipped
  components' manifests dropped theirs. Each component directory's
  `.suprnova-installed.json` now keys its digests by the path from the
  project root, Rust files included; `live:add` reads a record in the
  earlier form and rewrites it.
- **Scaffolds ignore `live:add`'s lock and journal.** The `.gitignore` of a
  new project lists `/.suprnova-live.lock` and
  `/.suprnova-live-journal.json`; add both lines to an existing project's.
- **`RouteBinding` is the one binding trait**, shaped like Laravel's
  `UrlRoutable`: `route_key_name`, `route_key`, `route_field`,
  `resolve_route_binding`, `resolve_child_route_binding` and their
  soft-deletable forms. `AutoRouteBinding` is a second name for it, and
  `<T as AutoRouteBinding>::from_route_param(value)` keeps working. A type
  that implemented the old `AutoRouteBinding` by hand implements
  `RouteBinding` instead. The unused `route_binding!` macro and the old
  `RouteBinding` trait with `param_name` are gone.
- **A `#[handler]` inside an `impl` block names its type**, as
  `#[handler(Self = Posts)]`, so the startup checks can find it. Without
  it, such a handler is a compile error that names the fix.
- **Some string-pair `route()` calls need `.as_str()`.** `route()` and
  `try_route()` take bound values as well as strings, so the forms that
  compiled only because the old slice parameter set the pairs' type or
  coerced them no longer do: a name or value whose type the parameter
  inferred (`s.as_ref()`, `s.borrow()`, `Default::default()`), one that
  reaches `&str` through more than one dereference or through a type of
  the application's own (`&&&str`, `&Box<String>`), a container of pairs
  reached the same way (`&&&Vec<_>`, `&Box<Vec<_>>`, a `SmallVec`), an
  array whose pairs mix `&String` and `&str` values, an array of more than
  32 pairs holding `&String` values, and `route` used as a
  `fn(&str, &[(&str, &str)])` pointer. Write `.as_str()`, `&*` or
  `.as_slice()`, or a closure in place of the pointer. Every other
  string-pair call compiles as before.
- **A dotted resource name nests.** `Router::resource("users.posts", ...)`
  registers `/users/{user}/posts/{post}`, as Laravel's `Route::resource`
  does; it registered `/users.posts/{users.post}`.
- **A route key that does not parse answers 404.** A key that does not parse,
  or breaks a `unique_id` key's format, gets the body a missing row gets,
  naming the model and never the value. On 3.2.1 a key that did not parse
  answered 400 and repeated the value, and a key that broke a `unique_id`
  key's format was looked up as given and answered 404.
- **The bare `x::Model` form no longer binds a soft-deleted row** of a
  soft-deleting `#[model]`'s table unless the route calls `with_trashed()`.
- **Bound arguments are bound before every other argument**, after the
  route's middleware, so a missing row answers 404 before a form request is
  validated, whatever the declaration order.
- **The router refuses a route it cannot run, at startup.** A handler that
  reads a parameter its path does not declare, reads the request body
  twice, names a binding field that is not a parseable column of the bound
  model, scopes a child through a relation the parent does not declare, or
  uses a binder that cannot run is an error from the boot path. Two body
  readers were a compile error; they are now a startup error, except two
  `Request` arguments, still a compile error.
- **URLs carry the public root.** When `APP_URL` has a path or a trusted
  prefix arrives, `route()`, `try_route`, `route_with_params` and
  `try_route_with_params` return the root in front, so an application whose
  own routes begin with its `APP_URL` path gets that path twice. Signed URLs
  cover the root, so a link signed before an application gained a root stops
  verifying. `url::current` and `LiveAssetCatalog::url` include the root.
  `RenderKeyInput` has a public `root` field.
- **`Redirect::intended` ignores a stored network-path reference.** A
  stored intended URL that starts with `//`, `/\` or `\`, or that holds a
  control character, is ignored in favour of the fallback. Store an
  external destination as an absolute URL.
- **Cookies follow the root.** `SessionConfig.cookie_path` and the XSRF
  cookie path default to unset, which means the root of each request. When
  a request carries two cookies of one name, the framework reads the first.
- **Images are upright and carry no metadata.** Images are oriented by
  their EXIF tag on decode (`IMAGE_AUTO_ORIENT`, on by default), and
  processed output keeps only the ICC profile under both drivers: EXIF and
  GPS, XMP, IPTC, comments, text chunks and date chunks are stripped.
  Rotation corners and flattened transparency are white in JPEG and GIF,
  not black, and GIF output is converted to sRGB.
- **The image types changed shape.** `Transformation` and `ImageConfig`
  are `#[non_exhaustive]`: build an `ImageConfig` from `default()` or
  `from_env()` and set its fields, and give a match on `Transformation` a
  wildcard arm. `Transformation::Rotate(f32)` is `Rotate { degrees,
  background }`. `Image::store(disk, path)` is replaced by
  `store(directory, disk)`, which stores under a generated name and
  returns the path; `store_as(directory, name, disk)` takes a name.
- **The shipped migrations upgrade an existing application in place.**
  `failed_jobs`, `jobs`, `job_batches` and `sessions` move into Laravel's
  layouts, and `notifications`, `features`, `roles` and `permissions` into
  the layouts above, with every row. A queued, delayed or reserved job runs
  once, a failed job keeps its id, a batch keeps its counts, and no user is
  signed out. A `migrate` that stops part way resumes on the next run. The
  manual gives the migration that moves an earlier scaffold's `users`.
- **Workers check `failed_jobs` before they start.** `run_worker` returns
  `Result<(), FrameworkError>`. A worker whose failed-jobs store is the
  database store refuses to start on a table it cannot write, and
  `queue:work` then exits non-zero. Each failed job gets a fresh `uuid`,
  and its `connection` is `suprnova:<connection>`, so Laravel's
  `queue:retry` refuses it.
- **Laravel's `$2y$` hashes verify** through `Auth::attempt` and Magnetar
  for passwords of 72 bytes and longer, judged on their first 72 bytes as
  PHP does.
- **Suprnova never writes `users.remember_token`.** The scaffold's `User`
  drops `update_remember_token`, reads `id` as `u64` and its timestamps as
  `Option<DateTime<Utc>>`.
- **The RBAC, feature and notification entities follow Laravel's
  layouts.** `rbac::entity::Role` and `Permission` have `u64` ids and no
  `display_name`, and the earlier pivot entities are gone. `FeatureRow` and
  `StoredNotification` timestamps are `Option`. The
  `session::driver::database::sessions` entity is gone. The `down` of
  `CreateNotificationsTable`, `CreateFeaturesTable` and `CreateRbacTables`
  leaves the shared tables, so a rollback never drops rows Laravel wrote,
  and a new scaffold's `users` and `sessions` migrations leave their table
  on rollback too.
- **Schema-qualified table names.** On Postgres, `Schema::create`, `table`,
  `drop`, `drop_if_exists` and `rename` read `schema.table` as that table
  in that schema, and a `.` becomes `_` in index and foreign key names. On
  MySQL and SQLite a qualified name is refused with an error naming it.
- **The naive date-time casts read MySQL `TIMESTAMP` columns.**
- **Password hashing runs under one process-wide limit.** `hash_async`,
  `verify_async`, `hash_with_cost_async` and Magnetar's sign-in hashing
  each took a blocking-pool thread with no limit, so a burst of sign-ins
  could hold up to Tokio's 512 blocking threads at once, and an Argon2id
  hash under the framework's defaults holds 64 MiB: up to 32 GiB. They now
  share one limit, `HASH_MAX_CONCURRENCY`, which defaults to the host's
  available parallelism; work past it waits as a task holding no thread,
  so a burst holds at most the limit times one hash's memory. A hash keeps
  its place under the limit until it returns, even when its caller stops
  waiting. `0` or a value that is not a whole number is refused when the
  hashing configuration loads; a blank value is the setting left unset.
  The two dummy hashes Magnetar's verifier warms as it is built run under
  the limit too, instead of inline on the runtime worker that installs the
  engines (#146).
- **A WebSocket upgrade no longer waits behind the shutdown drain.** The
  registry of WebSocket handler tasks sat behind an async lock that the
  shutdown drain held for up to its 5 s deadline, so an upgrade in flight
  waited out the whole drain before its handler was registered. The
  registry is now a synchronous lock held only to reap finished handlers
  and register a new one, and the drain takes the set out under it and
  waits holding no lock, still up to 5 s before it aborts what runs. A
  handler registered while the drain waits is waited for in its turn and
  aborted with the rest at the deadline; one registered after the drain
  has closed the registry is not started (#149).
- **A streamed file is one blocking task, not one per chunk.** A file
  above 1 MiB, served by `HttpResponse::file`, `HttpResponse::download` or
  `StaticFiles`, spawned a blocking-pool task for every 64 KiB chunk, so a
  1 GiB download made 16,384 trips through the pool and queued behind
  every other blocking task at each one. One blocking task now reads the
  whole file in 256 KiB chunks and hands them to the response over a
  channel of four: one pool trip per file, a client that stops reading
  leaves at most five chunks read ahead, and a dropped response stops its
  reader. The bytes and `Content-Length` are unchanged, and a read error or
  a file that shrinks still ends the body short (#147).
- **The in-memory rate limiter keeps answering while it sweeps.** Its
  buckets sat behind one lock: every request locked the whole map and
  copied its key into a new `String` even when the key had a bucket, and
  the periodic sweep and `purge_inactive` held that lock across the whole
  map, so each sweep stalled every throttled request for a time that grows
  with the number of keys an attacker can rotate. The buckets now sit in a
  sharded map: a request locks only its key's shard, a key that has a
  bucket allocates nothing, and the sweep locks one shard at a time.
  During a sweep over 200,000 buckets (about 45 ms), no request on another
  key completed before; about 4,800 do now. Acceptance, rejection and
  retry-after answers are unchanged, and no request fails with "rate
  limiter poisoned" any more, since the shard locks do not poison (#148).
- **`Prop::match_on` replaces the match fields on each call** instead of
  adding to them, as Laravel's `matchOn` does. `.match_on("x").match_on("y")`
  emitted `matchPropsOn: ["posts.x", "posts.y"]` and now emits
  `["posts.y"]`; name several fields in one call with
  `.match_on(["x", "y"])`.
- **`until` on a once prop reads an integer as seconds from now**, as
  Laravel's `until(60)` does, where it read an absolute timestamp in
  milliseconds: `.until(60)` emitted `expiresAt: 60` and now emits the
  render time plus 60 seconds. Pass a `DateTime<Utc>` for a fixed
  deadline (`chrono::DateTime::from_timestamp_millis(ms)`). `fresh()` on
  `Prop` and `OnceOptions` takes a `bool`: write `.fresh(true)`.
- **Scroll props merge under the wrapper `data` by default**, as Laravel's
  `Inertia::scroll($value, $wrapper = 'data')` does: `.scroll("posts",
  metadata, paginator)` emitted `mergeProps: ["posts"]` and now emits
  `["posts.data"]`, where a paginator or resource keeps its rows.
  `.paginate` and `Inertia::paginate` ship bare rows and still merge at
  the prop's root; `Prop::scroll_at_root()` does the same for any other
  bare list. A scroll prop's `match_on` path is now relative to the prop,
  with no wrapper prefix: `.match_on("data.id")` on `posts` emits
  `posts.data.id`, where a wrapped prop used to prefix the wrapper itself
  and emit `posts.data.data.id`. A deferred scroll prop announces its bare
  key under `mergeProps` on the visit that withholds it and
  `{key}.{wrapper}` when the data arrives, where a wrapped one announced
  `{key}.{wrapper}` on both. The manual's two divergence entries for
  these are gone.
- **`sharedProps` lists `errors`, and a setting turns the list off.**
  Every response shares the validation errors, as Laravel's middleware
  does, so `sharedProps` now starts with `errors`: a page with nothing
  else shared carries `["errors"]` where it carried no `sharedProps`, and
  after a failed form `errors` reaches the client's instant-visit carry
  with the other shared keys. `InertiaConfig::expose_shared_props(false)`
  leaves `sharedProps` out of the page object, Laravel's
  `inertia.expose_shared_prop_keys`; it is on by default.
- **`suprnova new` ships a root template in place of `frontend/index.html`.**
  The server never served that file: Vite builds from the entry module, and
  the first visit was the framework's own document, titled `Suprnova` on
  every page. A new project has `templates/app.html`, declared as
  `AppDocument` with `#[inertia_root]` in `src/bootstrap.rs`, which renders
  every first visit through it and sets the project's name as the default
  title. The Dockerfile `suprnova docker:init` writes copies `templates/`
  into the stage that compiles the application, since Askama reads
  templates at compile time; it copied only `cmd/` and `src/`, so that
  build could not find a root template or a Live view.
- **`X-Inertia` counts as an Inertia visit for any value PHP reads as
  true.** A request was an Inertia visit only when `X-Inertia` was exactly
  `true`, so a client sending `X-Inertia: 1` received the HTML document
  where Laravel sends the JSON page object. `Request::is_inertia` and the
  `InertiaRequestExt` default now read the header as PHP's boolean cast
  does: every value but an empty one and `0` is an Inertia visit, and JSON
  responses still carry `X-Inertia: true`. Every middleware that asks
  `is_inertia` follows the same rule, and so does the development error
  page, which a visit sending `X-Inertia: 1` now gets in place of a JSON
  error (HD-01).
- **The Inertia asset version follows Laravel's order and is empty by
  default.** With no Vite manifest to hash, the page carried the version
  `1.0`; Laravel's carries an empty one. The version now resolves from the
  new `InertiaConfig::asset_url` setting when it is set (a hash of the URL,
  as Laravel's `app.asset_url`; it defaults to the `ASSET_URL` environment
  variable, and the builder's value wins), else from the manifest's hash,
  else to the empty string. An explicit `.version(...)` or
  `.version_with(...)` still wins. `MANIFEST_VERSION_FALLBACK` stays
  exported, but no resolver returns it now, and a client that holds `1.0`
  from before the upgrade is bounced once (MW-11).
- **The asset-version 409 names an absolute URL and the current
  version.** `InertiaVersionMiddleware` answered a stale Inertia `GET` with
  a root-relative `X-Inertia-Location` (`/users?page=3`) and no version, so
  the client forced a full reload even for a poll or a background prop
  load. The 409 now carries the request's absolute URL
  (`http://example.test/users?page=3`, scheme and host as
  `Request::scheme_and_http_host` reads them, a trusted proxy's forwarded
  host included) and `X-Inertia-Version` with the current version, as
  Laravel's `onVersionChange` does. It still answers before the handler
  runs, and a visit by another method still passes through.
  `InertiaResponse::version_conflict(url)`, the 409 a handler builds
  itself, now carries `X-Inertia-Version` with `Inertia::get_version()` too
  (MW-02, HD-10, R04).
- **Partial reload headers are parsed as Laravel parses them.**
  `X-Inertia-Partial-Data` and `X-Inertia-Partial-Except` were trimmed
  entry by entry, and an empty `X-Inertia-Partial-Data` was a list that
  matched nothing, so the client received no props at all. The lists are
  now split on `,` with empty segments dropped and nothing trimmed (`a, b`
  names `a` and ` b`), and a header that names nothing counts as absent:
  an empty `X-Inertia-Partial-Data` now returns every prop `except`
  allows, as Laravel's does. `X-Inertia-Reset` and
  `X-Inertia-Except-Once-Props` were trimmed too and now follow the same
  rule (HD-03).
- **Dotted partial-reload entries narrow literal values only, as
  Laravel's do.** `only: ['users.name']` narrowed every prop's resolved
  value, a resolver's and a `defer`, `optional`, `merge` or `once` prop's
  included, so the client received `{"users": {"name": "Ada"}}` where
  Laravel sends the whole `users`. Dotted `only` and `except` entries now
  walk literal values alone (a flag-free resolver under a dotted key
  counts, since Laravel calls it before the walk), and the walk is
  Laravel's: an entry whose path resolves to nothing yields `[]` instead of
  `{}`, a path walks into lists by index, and a scalar a deeper path
  reaches ships as it is instead of being dropped. The manual's divergence
  entry on narrowing is gone (PR-08, HD-04).
- **Optional and deferred props resolve on an except-only partial
  reload.** An `optional` or `defer` prop resolved on a partial reload only
  when `X-Inertia-Partial-Data` named it, so `router.reload({ except:
  ['stats'] })` returned none of them where Laravel returns every one it
  does not exclude. They now resolve whenever their key passes the only
  and except lists, a reload with `except` alone or neither list included;
  a standard visit still leaves them out (PR-07, PT-01).
- **`merge` and `once` instructions follow Laravel's partial-reload
  rule.** Any `only` entry that selected a prop also sent its instructions,
  so `only: ['items.data']` against a merge prop `items` told the client to
  append a value it had asked for in part, and a `.merge().once()` prop
  the client already held still sent a `mergeProps` entry beside its
  `onceProps` entry. `mergeProps` and `onceProps` entries now ship only
  when an `only` entry names the prop or an ancestor of it, so a deeper
  entry sends the whole prop with no instruction, and a held once prop
  that is not deferred sends its `onceProps` entry alone. A scroll prop
  keeps its `scrollProps` cursor in both cases (PR-12, PR-13).
- **The Inertia page `url` carries the query as Laravel normalises it.**
  `page.url` repeated the query as the request sent it, so
  `/s?b=2&a=1%20x` stayed `/s?b=2&a=1%20x` where Laravel's `fullUrl()`
  sends `/s?a=1%20x&b=2`, and the client's comparisons of page URLs
  differed between the two. The query is now parsed as PHP parses it,
  sorted by key and re-encoded per RFC 3986, as Symfony's
  `Request::normalizeQueryString` does: `+` becomes `%20`, reserved
  characters stay percent-encoded (`a=%2Fx` stays `a=%2Fx`), a bare key
  gains an `=`, a repeated key keeps its last value, and `a[]=x` becomes
  `a%5B0%5D=x`. The version 409's `X-Inertia-Location` carries the same
  query. A `url_resolver`'s URL is left as it returns it (RS-07).
- **An empty Inertia response redirects back as Laravel's does.** An empty
  `200` on an Inertia visit was answered with `303` to the session's
  previous URL or `/`, whatever the method, so a `POST` from `/form` with no
  previous URL landed on `/`. It now goes to the same-origin `Referer`, then
  the previous URL, then `/`, with `302`, and `303` only for `PUT`, `PATCH`
  and `DELETE`; a browser follows a `302` after `POST` with a `GET`, so the
  blanket `303` protected nothing (MW-03, R09).
- **A redirect with a fragment keeps it on an Inertia visit.** A redirect to
  `/page#section` reached the client as a plain `302`, and the fragment was
  lost inside the XHR that followed it. It now arrives as `409` with
  `X-Inertia-Redirect: /page#section`, which the client visits with the
  fragment intact, except on a prefetch, which `X-Moz`, `Purpose` or
  `Sec-Purpose: prefetch` marks (HD-12, HD-13, R06).
- **Inertia visits record the previous URL.** The session middleware skipped
  every Inertia visit, so after Inertia navigation `Redirect::back` and a
  failed validation landed on the last page loaded in full. An Inertia `GET`
  that matched a route now records its URL, unless it is a prefetch, a
  Precognition request or a partial reload of the component it rendered,
  and a browser prefetch no longer records one in the session middleware
  (MW-06, HD-13).
- **`errors` under `X-Inertia-Error-Bag` takes Laravel's shape.** With the
  header, a visit with no session errors got `{"<bag>": {}}` and a session
  `default` bag was dropped for `{"<bag>": {}}`. It is now `{}` with no
  errors, `{"<bag>": <default bag>}` with a default bag, and the named bags
  as they are otherwise (HD-08).
- **Inertia flash data lives in the session until a page shows it.**
  `App::flash` kept its value in the request: a request that answered plain
  JSON lost it, and one that redirected twice dropped it at the second hop.
  `App::flash`, `Inertia::flash` and `InertiaResponse::flash` now write the
  session entry `inertia.flash_data`, the next Inertia page emits it under
  `page.flash` and removes it, and every redirect keeps it for one more
  request (RF-17, MW-05).
- **`clearHistory` and `preserveFragment` survive any number of redirects.**
  `App::clear_history()` and `Redirect::preserve_fragment()` flashed a flag
  for one request, so a logout that redirected twice rendered the login page
  without `clearHistory: true` and left the previous user's encrypted
  history readable. The flags are now the session entries
  `inertia.clear_history` and `inertia.preserve_fragment`, which last until a
  page emits them; a flag an earlier release flashed is still read (RF-08,
  RF-09).
- **A dotted shared key nests when it is shared.** `App::inertia_share`
  stored `user.age` as a literal key and nested it at render, so
  `share("user", {"name": "A"})`, `share("user.age", 3)`, then
  `share("user", {"name": "B"})` rendered `{"name": "B", "age": 3}`. It now
  nests at share time as Laravel's `Arr::set` does, and renders
  `{"name": "B"}` (RF-02).
- **SSR exclusion patterns match as Laravel's `ExcludesPaths` does.**
  `ssr_exclude` matched the raw path with `*` stopping at `/`, so
  `admin/*` copied from a Laravel app excluded nothing (`/admin/users`
  starts with a slash) and `/admin/*` missed `/admin/users/edit`. Slashes at
  either end of a pattern are now ignored, `*` matches any characters
  including `/`, the path is decoded first, and each pattern is also tried
  against the full URL; `**` keeps working (RF-12).
- **`InertiaResponse::location` answers a hard navigation with a redirect.**
  It always answered `409` + `X-Inertia-Location`, which a browser that did
  not send `X-Inertia` cannot follow, so an OAuth or SSO bounce started
  outside the SPA dead-ended on a blank page. Under the Inertia middleware it
  now answers an Inertia visit with the `409` and anything else with a `302`
  + `Location`, or the `Redirect` it was given, as Laravel's does, on every
  route the server dispatches, the Inertia middleware installed or not;
  `location_for(&req, url)` stays for code outside a dispatched request
  (RF-16).
- **A component's script can no longer replace a built-in.** The `live:add`
  scan, new in 4.0.0, refuses a write to a member of a built-in object or
  function (`script-builtin`): `Object.keys = f`, `JSON.parse = f`,
  `Math.random = f`, and a write to a member of a parameter given a built-in
  member, as `function f(p) { p.call = g } f(Array.prototype.slice)` would
  change the `call` every other script borrows `slice` with. It refuses such a
  write in every form it refuses a write to a prototype's member (`=`, `??=`,
  `+=`, `++`, a destructuring or `for` loop target, `delete`), named directly,
  through the global object (`globalThis.Object.keys`, `window.JSON.parse`),
  or through a name that holds one: a variable, a parameter's default, or a
  parameter a call of its function by name hands one. A member read under a
  built-in method's name from a value the script did not make (`[].slice`, an
  element's `addEventListener`) counts as that method, and a method of
  `document`, `location` or `history` may not be assigned. A built-in is
  refused where the scan stops following it: passed to anything but a function
  the script calls by name or a browser API that only calls it back, put in an
  array or object, written to a member, destructured, returned, thrown or
  exported. That also names the built-in in
  `Object.defineProperty(Object, "keys", ...)` and
  `Reflect.set(Math, "random", f)`, whose calls other checks refuse too. The
  parameter form through a prototype's member is refused as
  `script-prototype`, as the variable form is. Calls, reads, comparisons,
  `map(Number)`, constants such as `Number.MAX_SAFE_INTEGER`, the page's own
  properties (`document.title`, `location.hash`) and writes to the script's
  own objects and functions stay admitted. Nineteen bypass fixtures pin it
  (`script-builtin-alias`, `script-builtin-compound`,
  `script-builtin-default-parameter`, `script-builtin-define-property`,
  `script-builtin-delete`, `script-builtin-destructured`,
  `script-builtin-export`, `script-builtin-function-member`,
  `script-builtin-globalthis`, `script-builtin-handed-back`,
  `script-builtin-inherited-method`, `script-builtin-math-random`,
  `script-builtin-namespace-member`, `script-builtin-page-method`,
  `script-builtin-parameter`, `script-builtin-reflect-set`,
  `script-builtin-window`, `script-prototype-member-alias` and
  `script-prototype-member-parameter`), and the `own-members` accepted fixture
  pins what stays admitted. A member read off a literal, an operator's result
  (`-1`, `"a" + b`), a constant that holds one, or a class that extends a
  built-in and does not declare that static is the built-in it inherits,
  whatever its name, so `(0).toPrecision`, `"".anchor`, `[].copyWithin` and
  `/x/.compile` are built-in methods though no list of the scan names them.
  `call`, `apply` and `bind`, through which every script borrows a built-in
  method, may be written only on a value the script made, which refuses
  `(0).toPrecision.call = f`, `Math.random().toPrecision.call = f` and an
  element's `requestFullscreen.call = f`. `getRootNode()` on any node is the
  page, as `ownerDocument` is, so `document.getRootNode().createElement = f`
  is refused, `Object(value)` is the value, and a method of the page whose
  name is never ordinary data (62 of them, from `createElement` and
  `querySelector` to `addEventListener` and `pushState`) may be assigned only
  on a value the script made, which also refuses it through a `parentNode`, an
  event's `currentTarget`, an array, a promise, a function that returns
  `document`, and `this` in a method the page calls as a listener. The window
  `window.open` returns is a global object too, so
  `window.open("/x").JSON.parse = f` is refused. Writing `call` on a value the
  scan cannot trace (`api.call = f` on a parameter, `this.state.call = c`) is
  refused as well, since the scan cannot tell it from a built-in method's.
  Eighteen more bypass fixtures pin these cases
  (`script-builtin-literal-number`, `script-builtin-literal-string`,
  `script-builtin-literal-template`, `script-builtin-literal-regexp`,
  `script-builtin-literal-array`, `script-builtin-literal-name`,
  `script-builtin-literal-held`, `script-builtin-class-static`,
  `script-builtin-borrowed-call`, `script-builtin-borrowed-call-element`,
  `script-builtin-root-node`, `script-builtin-root-node-this`,
  `script-builtin-object-of-page`, `script-builtin-page-method-held`,
  `script-builtin-page-method-parent-node`,
  `script-builtin-page-method-listener-this`, `script-builtin-opened-window`
  and `script-builtin-opened-window-name`), and the `ordinary-writes` accepted
  fixture pins what an ordinary component still writes: `textContent`,
  `value`, `classList`, `this.state.open`, `o.call` on its own object.

- **A handler panic reaches the Inertia error page.** The panic boundary wraps
  the whole middleware chain, so a panic unwound past the error-page
  middleware: an Inertia visit to a panicking handler got the JSON
  `{"message":"Internal Server Error"}` `500` and the client's "plain JSON
  response" modal, even with `error_page` set. The middleware now runs the
  chain inside it under the boundary's rule, so the same `500`, with the
  panic's error report, reaches the error callback, and with
  `error_page("Error")` the visit gets the `Error` page at status `500`. An
  API client still gets the JSON `500`. `Inertia::install` now registers the
  error-response middleware whatever the config says, where 3.2.1 registered
  it only when `error_page` was set, because the callback can be installed
  after it; with neither a callback nor an `error_page` it hands every request
  on and changes nothing.
- **SSR is on by default, behind bundle detection.** `SsrConfig::enabled`
  defaulted to `false`, so an application had to opt in to SSR, where
  Laravel's `inertia.ssr.enabled` is `true`. It is now `true`, with the
  worker at `http://127.0.0.1:13714`, and while `ensure_bundle_exists` is on
  (the default) a first visit is sent to the worker only when a bundle is
  found at `ssr_bundle_path` or at one of the six conventional paths
  (`frontend/bootstrap/ssr/ssr.js`, `app.js`, `ssr.mjs` and `app.mjs` there,
  then `public/js/ssr.js` and `public/js/app.js`). An application without a
  bundle renders on the client as before and never contacts the worker; one
  with a bundle at a conventional path gets SSR without configuration. Turn
  SSR off with `InertiaConfig::ssr_disabled()`, and the check off with
  `ssr_ensure_bundle_exists(false)` for a worker whose bundle this process
  cannot see (SS-03, SS-04).
- **A missing SSR bundle is no longer logged.** With a `bundle_path` set and
  no file there, every first visit wrote "SSR bundle not found" to stderr or
  the `on_ssr_error` hook. With SSR on by default that would reach the log
  of every application without a bundle on every first visit, so the visit
  now renders on the client quietly, as Laravel's gateway returns `null`;
  `ssr:start` reports a missing bundle. The `on_ssr_error` hook is for
  worker failures, and under `ssr_throw_on_error` such a visit now fails
  with Laravel's `SsrException` text, naming the component and, when the
  worker gave one, the source location: `SSR render failed for component
  [Dashboard]: window is not defined at resources/js/Pages/Dashboard.vue:12:5`
  (SS-04, SS-08).
- **`suprnova ssr:start` makes Laravel's checks before it starts a worker.**
  It checked that one bundle path existed and then ran `runtime bundle`
  whatever the application's SSR configuration said: it started a worker with
  SSR switched off, looked for no other bundle path, never checked the
  runtime, started a second worker beside a running one, and died of a
  `SIGTERM` that left its worker running. It now runs the application binary's
  `ssr:start`, which reads the installed Inertia configuration: it finds the
  bundle as the SSR dispatch does (the configured path, then the six
  conventional paths, warning when the configured one is missing and a
  conventional one runs), refuses a runtime it cannot find when
  `ssr_ensure_runtime_exists` is set, asks the worker at the configured URL to
  shut down first and refuses to start while that worker is still running,
  forwards Ctrl-C and `SIGTERM` to the worker as the signal received (a second
  one kills it), and reports each line of the worker's stderr as an error
  (CM-01).
- **`suprnova ssr:check` asks the SSR gateway's health check.** It probed
  `/health` with a client of its own, so its answer could differ from the
  health check the framework uses, and its messages and exit codes were
  its own (2 for a URL without a scheme). It now runs the application
  binary's `ssr:check`, which asks the installed SSR gateway's health check
  and prints Laravel's messages: `Inertia SSR server is running.`, `Inertia
  SSR server is not running.`, or `The SSR gateway does not support health
  checks.`, exiting 0 or 1 (CM-03, SS-10).
- **The CLI's `ssr:start`, `ssr:stop` and `ssr:check` run the application
  binary, and the CLI does not link the framework crate.** The CLI read its
  own SSR settings from `--bundle`, `--url`, `--timeout-ms` and the
  `SUPRNOVA_SSR_URL`, `SUPRNOVA_SSR_RUNTIME` and `SUPRNOVA_SSR_BUNDLE`
  variables, so it could start or check a worker other than the one the
  application's first visits dispatch to. Each command now runs
  `cargo run --bin <package> -- ssr:<command>` from the project directory, as
  `suprnova serve` runs the backend, with `--runtime` and `--graceful` passed
  through: the application's output reaches the CLI's stdout and stderr, and
  the CLI exits with its status, or 128 plus the signal number when a signal
  ended it. The application runs in a process group of its own, so a
  terminal's Ctrl-C reaches it once, through the CLI, which forwards each
  `SIGINT` and `SIGTERM` it receives to the application and each `SIGHUP`,
  `SIGQUIT`, `SIGTSTP` and `SIGCONT` to the application's process group,
  worker included, and stops with it at a `SIGTSTP`, so Ctrl-Z and `fg` stop
  and resume them together. The flags and the variables are gone: set the URL,
  the bundle, the runtime and the timeout with `InertiaConfig::ssr`,
  `ssr_bundle_path`, `ssr_runtime` and `ssr_timeout`. The CLI's manifest names
  the framework crate for its tests only, as in 3.2.1, since the application
  binary already has these commands (CM-01, CM-02, CM-03).
- **The starter kits declare `@inertiajs/core` and read `root` through the
  generated types.** In 3.2.1 a kit reached `@inertiajs/core` only because its
  adapter depends on it and npm hoists it, and no page had a `root` prop. Each
  kit's `package.json` now declares `@inertiajs/core` at `^3.8.0` beside its
  adapter, the generated `inertia-props.ts` augments that package, and every
  kit page that builds URLs from `root` reads it with a bare `usePage()`,
  typed by the augmentation. The `Error` page keeps its inline props, since no
  handler renders it with a struct. A project upgrading with its own
  `declare module '@inertiajs/core'` block, in a `.ts`, `.tsx`, `.mts` or
  `.cts` file under `frontend/src` such as `global.d.ts`, keeps it:
  `generate-types` and `serve` then write `inertia-props.ts` without the
  augmentation or its `import '@inertiajs/core'` and print a notice naming
  that file (`serve` once, not on every save), since two augmentations merge
  key by key and fail the type check on any key they set to different types.
  Delete the hand-written block and regenerate to get the generated
  augmentation, with `root` and the shared struct typed (T06).
- **`TestResponse::assert_inertia()` reads a first visit.** It refused any
  response without `X-Inertia: true`, so the HTML document a plain `GET` of
  a page route returns could only be asserted through
  `AssertableInertia::from_response` on an `HttpResponse`. It now reads the
  page from the document's `data-page` element as well, and
  `assert_inertia_with(callback)` runs a callback over the page and returns
  the response for chaining, as Laravel's `assertInertia(fn)` does. Both
  entry points find that element by its `type="application/json"` and
  `data-page` attributes in either order, with others between them or in
  single quotes, and skip the text of any other script. They looked for
  `<script type="application/json" data-page="` only, so the document of a
  server-rendered first visit, which Inertia 3.8's `buildSSRBody` writes as
  `<script data-page="app" type="application/json">`, failed with "no
  Inertia page object" (TS-01).
- **An image wildcard leaves SVG out.** A `MimeType` allowlist takes `type/*`
  wildcards, new in 4.0.0, and a wildcard admits every subtype of its type
  except `image/svg+xml`, since an SVG document is markup that can run script,
  as Laravel's `image` rule leaves SVG out unless asked. An SVG passes only
  when the allowlist names `image/svg+xml`, as in 3.2.1, whose entries matched
  the type exactly. `text/*` and `application/*` admit every subtype.
- **`has` and its kin read a polymorphic owner relation.** On a `MorphTo`,
  `has`, `or_has`, `has_count`, `doesnt_have` and `or_doesnt_have` rendered
  a probe that is always false, so `has` matched no row and `doesnt_have`
  matched every row. They now ask every owner type the relation declares,
  as Laravel's `has` routes a `MorphTo` to `hasMorph($relation, ['*'])`: a
  row has its owner when its type names a declared owner whose table holds
  its key under that owner's scopes, and `doesnt_have` keeps every other
  row, a null type or a type no owner answers to included. `has_count`
  compares the owner count, 0 or 1, with `=`, `<>`, `!=`, `<`, `<=`, `>` or
  `>=` and refuses any other operator. `where_has::<R, _>`,
  `where_doesnt_have` and their `or_` forms apply the closure to the owners
  of `R`'s type, as `where_has_morph` with that one type does.
- **`url::current` is the absolute URL without the query.** It returned the
  path and the query, such as `/posts?page=2`, where Laravel's `current()`
  returns the `APP_URL` origin, the root and the path. It now does the same;
  use `url::full` for the URL with its query. The framework's own redirects,
  the session's previous URL and signature verification still read the path
  and the query.
- **`Redirect::guest` stores a page to come back to.** It stored the
  request's own URL for every request, so a sign-in after a `POST` or a
  JSON call sent the browser back to a form submission or an API
  response. It now stores the request's own URL only for a `GET` that does
  not expect JSON, and the session's previous URL for any other request.
  It never reads the `Referer`.

- **Errors are reported through `Exceptions`.** A 5xx response, every failed
  attempt of a queued job, and a console command that returns an error now
  run your reportable callbacks before the `framework error` log line; a
  console command's error is logged as well as printed.
- **The frame that created an error shows where.** In a build without debug
  info, the development error page gives the innermost application frame the
  error's creation site as its location.

- **The numeric max message.** `#[validate(range(max = 10))]` reads `must not
  be greater than 10`, Laravel's wording; a string's `length(max = ...)` keeps
  its message.
- **`ImageFile` accepts Laravel's image types.** It accepts JPEG, PNG, GIF,
  BMP, WebP, AVIF, HEIC and HEIF and refuses every other type, TIFF, PSD, ICO
  and JPEG XL included; an SVG passes only a `MimeType` allowlist that names
  it.
- **Generated middleware passes the request on.** `make:middleware` writes a
  `handle` that returns `next(request).await`, as Laravel's stub does, in
  place of a body that printed request timing.

- **CSRF checks every method but GET, HEAD and OPTIONS.** `CsrfMiddleware`
  now checks `QUERY` and extension methods such as `PROPFIND` as it checks
  `POST`; a `QUERY` request without a token gets `419`.
- **Regenerating the session issues a new CSRF token.**
  `regenerate_session_id()` sets a new CSRF token beside the new id, so a
  token read before the regeneration gets `419` after it.
- **`Request::ajax()` compares exactly.** It is true only for
  `X-Requested-With: XMLHttpRequest`, not for another spelling.
- **`Request::host()` reads the host as Symfony does.** It lowercases the
  host, strips only a numeric port, and returns `None` for a host with a
  character no host has, so `http_host()`, `scheme_and_http_host()` and
  `url()` never carry such a host.
- **Deletion cookies follow the session configuration.** `Cookie::forget`,
  `without_cookie` and `without_cookies` take `Path`, `Domain` and
  `SameSite` from `SESSION_PATH`, `SESSION_DOMAIN` and `SESSION_SAME_SITE`,
  so the deletion cookie matches the cookie it deletes; an explicit path or
  domain given to `Cookie::forget_with` still wins.
- **Denial codes survive `authorize`.** `GateResponse::authorize` returns
  `FrameworkError::Denial` for a denial built with `with_code`, and
  `FrameworkError::code()` reads the code after `?`; a denial without a code
  maps as before.

- **Rate-limiter keys are cleaned as Laravel cleans them.**
  `RateLimiter::clean_rate_limiter_key`, and every counter method through it,
  applies PHP's `htmlentities` before it strips entity markers, so `café` and
  `cafe` count in one bucket and `a&b` is stored as `aab`.
- **Named limiters rename shared keys.** `RateLimiter::limiter` returns a
  callback that gives each limit sharing a key with another limit of the same
  result its fallback key, and `throttle:<name>` counts each limit under
  `<name>:<key>` from that result, so the middleware and a direct caller read
  the same buckets.
- **One rate-limit header pair.** The throttle middleware writes one
  `X-RateLimit-Limit` and `X-RateLimit-Remaining` pair, the limit with the
  fewest attempts left, and none when the handler's response already carries
  an equal or lower `X-RateLimit-Remaining`.
- **Refused requests are not counted.** A request the throttle middleware
  refuses leaves every bucket's count where it was; the decision still uses
  the atomic post-increment count.
- **`throttle:60,1` counts signed-in users by user.** The inline throttle keys
  a signed-in user by the user's identifier and a guest by address, each per
  path, so one user cannot buy a fresh budget from another address.

- **The verified gate answers each request.**
  `EnsureEmailVerifiedMiddleware::redirect_to` answers a request that expects
  JSON with `403` `Your email address is not verified.`, and sends any other
  request through `Redirect::guest`, so the intended URL is stored and
  `Redirect::intended` returns the user after verification. `new()` still
  answers `403` to every caller.
- **Verification refusals tell the two cases apart.** `EmailVerification::verify`
  answers `403` `This action is unauthorized.` for a live link of another
  account or one mailed to an address the account no longer has, and keeps
  `400` for an unknown, expired or used token.
- **Verifying a verified account keeps its time.** `verify` consumes the token
  and returns the user ID without a new stamp and without `EmailVerified`.
- **Checking a password writes nothing.** `validate_credentials` on
  `EloquentUserProvider` and `DatabaseUserProvider` verifies the password and
  writes nothing, as in 3.2.1, so `Auth::validate` and a guard's `validate`
  leave the hash as it is. The sign-in (`attempt`, `once` and
  `Auth::logout_other_devices`) rewrites an outdated hash, the one a database
  shared with Laravel needs included, through
  `UserProvider::rehash_password_if_required`, and a rewrite that fails fails
  the sign-in.
- **One attachment per name and bytes.** A message drops an attachment
  whose name and bytes equal an earlier one's, from the mailable's
  `attachments()` or the builder, on the send and the queued path; two
  attachments with one name and different bytes are both sent.
- **Notification mail without a subject.** An empty `MailRendering` subject
  is sent as the notification's name in title case (`InvoicePaid` gives
  `Invoice Paid`) instead of empty.
- **Unique queued listeners take the lock.** A `QueuedListener` whose job
  declares `unique_id` pushes through `Queue::push_unique`, so a second event
  while the lock is held pushes nothing and dispatches `UniqueJobSkipped`.
- **The after-commit decision follows an order.** A push waits for the
  commit by the first of its own override, the job's
  `after_commit_choice`, the connection's setting and `QUEUE_AFTER_COMMIT`,
  for `push`, `push_unique` and `bulk` alike, instead of the job's
  `after_commit` or `QUEUE_AFTER_COMMIT`.
- **`down` prints Laravel's lines.** It prints `Maintenance mode options
  updated.` when the application was already down, the bypass address as
  `You may bypass maintenance mode via [<APP_URL>/<secret>].`, and
  `Failed to enter maintenance mode: <error>.` on a failure.
- **Single-server tasks need a cache store.** A schedule with an
  `on_one_server()` task and no cache store bound refuses to start in every
  environment, and a tick with no store skips the task with an error log
  instead of running it on every server.
- **Day helpers keep the schedule.** `days`, `weekdays`, `weekends` and
  `sundays` to `saturdays` replace only the day-of-week field after a
  frequency, time or `cron` call, so `.hourly().mondays()` is `0 * * * 1`;
  alone they still run at midnight.
- **Hour-only and seconds times.** `at`, `try_at`, `daily_at` and
  `try_daily_at` read `9` as 09:00 and `09:30:00` as 09:30.
- **`migrate:status` prints its list.** It writes one line per migration with
  `Applied` or `Pending` to the standard output, where it wrote them to the
  log.

- **`make_directory` takes a path without its trailing slash.**
  `make_directory("a/b")` creates the directory as `"a/b/"` does; it used to
  fail on every disk. An empty path and a path that ends in `/` reach the
  backend unchanged.
- **No image driver receives a zero side.** `Image::resize`, `cover`,
  `resize_width` and `resize_height` record a side of 0 as 1, as Laravel
  clamps it; the `magick` driver failed on the `0x0` geometry.
- **`ImagePipeline` carries the settings of its custom steps.** The new
  `settings` field holds what `Image::transform_with` recorded, and a custom
  driver runs a custom step with `CustomTransformation::apply_with(pixels,
  &pipeline.settings)`. A struct literal of `ImagePipeline` ends with
  `..ImagePipeline::default()` or names the field.
- **A started fake process reveals its output a line at a time.** Each
  `output()` or `latest_output()` call reveals the next line, `output()`
  answering every line so far and `latest_output()` the new one; the error
  output works the same way, and `wait()` still returns the whole output.
- **The HTTP fake records a request as it is sent.** The recorded headers
  include the `Content-Type` a JSON, form or multipart body sets, the user
  agent, and the headers global middleware adds, and the recorded URL has its
  base URL, URL parameters and query applied.

- **Development pages load an existing build when no hot file exists.** In
  development the Vite tags point at the dev server only while the hot file
  exists, and at the manifest's files while it does not and a manifest exists.
  A frontend that declares no `@inertiajs/vite` and holds a manifest from an
  earlier build now loads that build instead of the dev server: declare
  `@inertiajs/vite`, as every starter kit does, or delete the stale build.
- **Database rules in hooks follow the Precognition selection.**
  `AsyncRule::check_async`, `Exists::check_value` and `Exists::check_each`
  (selected under `<field>.*`) skip a field a precognitive request did not
  list, so they neither query nor fail; errors a hook adds stay unfiltered.
- **The CSRF field turns autocomplete off.** `csrf_field()` renders
  `autocomplete="off"`, so a browser does not restore a stale token into it.
- **A default middleware priority.** The priority list starts as
  `Precognitive`, `SessionMiddleware`, `AuthMiddleware` and
  `ThrottleRequestsMiddleware`, so a route that lists `AuthMiddleware`
  before `SessionMiddleware` loads the session first, and a route-listed
  `Precognitive` runs before a global `SessionMiddleware`.
- **`lang/vendor` is not a locale.** The translator skips it as a locale
  directory; it holds overrides of namespaced catalogs.
- **`#[service(impl = ...)]` parses.** The named form beginning with `impl`
  was refused as a keyword; it now registers the implementation.

- **An unset `APP_ENV` is production.** A deployment that sets no `APP_ENV`
  now runs every production check: debug is off, `APP_KEY` is required, the
  SQLite fallback, a mail driver that delivers nothing, plaintext SMTP, the
  in-memory rate limiter, an unknown queue driver and the mock payment
  provider are refused, the Inertia shell needs its Vite manifest,
  `on_one_server` tasks need a shared cache, and `db:seed`,
  `migrate:fresh` and `suprnova migrate:fresh` ask for `--force`. No
  `.env.<environment>` file loads for an unset `APP_ENV`; `.env.local` still
  does. Set `APP_ENV=local` (the scaffold's `.env` does) to keep the old
  behaviour.
- **`CacheConfig` gained `connection` and `lock_connection`.** A
  `CacheConfig` struct literal names both fields, or spreads
  `..CacheConfig::default()`.
- **The Redis cache moves to the `cache` connection and `CACHE_PREFIX`.** The
  store runs on the `cache` connection's database (`REDIS_CACHE_DB`, 1 by
  default) and its keys are `REDIS_PREFIX`, then `CACHE_PREFIX` (the slug of
  `APP_NAME` and `-cache-`), then the key; `REDIS_PREFIX` no longer names the
  cache prefix, and `Cache::flush` deletes only keys under both prefixes. An
  upgraded deployment finds its Redis cache empty; `REDIS_CACHE_CONNECTION=default`,
  an empty `REDIS_PREFIX` and `CACHE_PREFIX` set to the old prefix
  (`suprnova_cache:` by default) keep the old keys.
- **MySQL tables default to `utf8mb4_unicode_ci`.** Tables created before the
  upgrade keep the server's default collation, and MySQL refuses to compare
  string columns of two collations; an application whose tables use the
  server's default keeps it by setting `DB_COLLATION` to that collation
  (`utf8mb4_0900_ai_ci` on MySQL 8).
- **File and stream log channels keep `LOG_LEVEL`'s bare level.** `single`,
  `daily`, `monthly`, `stderr`, `errorlog` and `syslog` keep only records at
  or above it, `debug` when it names none, and a bare level that is no level
  fails the boot.
- **`queue::testing::pushed::<J>()` fails on a payload that does not decode.**
  It panics, naming the job and the decode error, where 3.2.1 left the push
  out of the list, so neither the list, `assert_pushed` nor the new
  `assert_not_pushed` passes over a push it cannot read.
- **`Queue::reserved_jobs` under `Queue::fake()` answers the fake.** It lists
  the reservations workers made from the fake instead of reading the
  installed driver.
- **The server caps concurrent connections at 10000 by default.** In 3.2.1
  an unset or blank `SERVER_MAX_CONNECTIONS` left the number of concurrent
  connections unbounded, so a crowd of slow clients could use up the
  process's file descriptors. An unset or blank value now caps them at
  10000, the new `suprnova::config::providers::DEFAULT_MAX_CONNECTIONS`,
  and `ServerConfig::builder()` and `Server::new` start from the same cap.
  Zero or a value
  that does not parse still falls back to 10000 with a warning, and an
  explicit positive value is the cap. No value of the variable removes the
  cap: a server with no cap is a choice made in code, with
  `ServerConfig::builder().unbounded_connections()`. A deployment that
  holds more than 10000 connections at once sets `SERVER_MAX_CONNECTIONS`
  to its figure.
- **Zero tries is unlimited.** In 3.2.1 a job whose `Job::max_tries()`
  returned 0, or a push whose `EnvelopeOverrides::max_tries` was `Some(0)`,
  reached the worker with no attempt to spend and was dead-lettered before
  it ran. Zero now means unlimited, as Laravel's `$tries = 0` and the
  worker's `--tries=0` do: the envelope of a pushed, batched or chained job
  and of a queued notification carries `u32::MAX`, so the job is retried
  until it succeeds and is never dead-lettered for running out of attempts.
  An error named with `dont_retry` or `dont_retry_when`, a middleware such as
  `FailOnException`, a timeout under `fail_on_timeout` and a worker started
  with `--tries` still end it.

### Fixed

- **The full-stack Dockerfile copies the localization catalogs.** The
  Dockerfile `docker:init` writes for a Svelte, React or Vue project copies
  `lang/` into the runtime image, which 3.2.1's left out, so
  `Localization::bootstrap` finds the catalogs the pages' `lang` share and
  `__!` lookups read.
- **The Laravel parity map holds the Inertia adapter and client.**
  `feature-map/laravel/surface.jsonl` held laravel/framework alone, so no
  Inertia protocol row (HD-01, MW-06, RF-16 and the rest) could name its
  Laravel side, and the row ids in these notes were the only link between
  a row and what shipped. The map now also holds inertia-laravel 3.5.1, read
  through the same PHP reflection, and Inertia.js 3.8.0, read with
  TypeScript's parser: classes, facade methods, macros, Blade directives,
  config keys, every package export and each `X-Inertia*` header the client
  sends or reads, each record tagged with its package. The rows' parity
  decisions are in `feature-map/laravel/inertia-protocol-parity.jsonl` for
  `fmap parity-import`.
- **The error callback sees the error responses from outside the Inertia
  stack.** In 3.2.1, `InertiaConfig::error_page` decided only what passed
  through the error-response middleware `Inertia::install` registers. A
  middleware registered before `install` that answers without calling
  `next` - `CsrfMiddleware`'s `419`, `TimeoutMiddleware`'s `503`, an outer
  rate limiter's `429` - and a panic that only the server's boundary caught
  never reached it, so an Inertia visit got the plain-JSON modal for them. The
  server now runs the same decision after the whole stack, the panic boundary
  and the development error page, for every error response nothing inside the
  stack decided, at each of the three places it dispatches a request. A page
  decided there carries the shared registry and the shared providers, but no
  session data, no detected locale and none of the middleware hooks' shares,
  since every scope a middleware opened has closed. A JSON client's validation
  `422`, `{message, errors}`, was also kept from it: the error-response
  middleware sat inside the validation redirect and skipped every `422` with
  an `errors` object so it would not replace an Inertia visit's before the
  redirect back. It now sits outside the redirect, which turns an Inertia
  visit's `422` into the `303` first, and the `422` exclusion is gone; the
  default callback still keeps every `422`.
- **An error page placed outside the Inertia stack follows a fragment
  redirect.** In 3.2.1, with `error_page` set, `InertiaErrorPageMiddleware`
  passed a response carrying `X-Inertia-Location` through but not one carrying
  `X-Inertia-Redirect`: it read the empty body of the `409` that
  `InertiaResponse::redirect` builds as an error and sent the error page in
  its place, so the client never followed the redirect. In 4.0.0 that `409`
  also carries an Inertia visit's redirect to a `#fragment`. Inertia protocol
  responses (`X-Inertia`, `X-Inertia-Location`, `X-Inertia-Redirect`) are
  never handed to an error callback now, the default one included, wherever
  the middleware is registered.

- **A drop-in Inertia form with a file, and a `GET` filter form, read as the
  client shapes them.** The Inertia client sends a form that holds a file
  as `multipart/form-data` under bracketed and indexed names (`user[name]`,
  `photos[0]`), and a `GET` visit's data as `filters[status]=x&tags[]=a`.
  A form request answered `415` for the multipart body, and every reader
  matched names literally, so `filters[status]=x` arrived as one literal
  key and a field declared as `user.name` read nothing. Bracketed and
  indexed names in a url-encoded body, a multipart body and a query string
  now decode into nested data as PHP's `parse_str` reads them: objects,
  lists in index order, up to 64 levels deep. A form request and
  `Request::input` read a multipart body, an `UploadedFile` field takes a
  part that carries a file and runs its validators, and a field that fails
  is named by its dotted path (`user.name`, `photos.1`). A multipart body
  stays under the form request's `max_body_bytes` (8 MiB by default) and
  the multipart part ceiling (1,000 parts). A multipart body a middleware
  read first, as a body-keyed rate limit does, is parsed from the buffer
  where the reader answered `400` naming a framework bug.
- **JPEGs from the built-in driver show the right colours everywhere.** The
  `oxideav` driver wrote RGB samples behind a JFIF header, so libjpeg-based
  decoders, ImageMagick and most browsers among them, showed the wrong
  colours. It now writes standard JFIF YCbCr.
- **Redirects stay on the origin for a request-target that names another
  host.** `Redirect::refresh_for`, `Redirect::guest` and
  `Redirect::intended` no longer send the browser elsewhere when a request
  such as `GET //evil.example/x` or `GET /\evil.example` reaches a fallback
  route, and `url::full` stays on the `APP_URL` origin for it.
- **Images are no longer copied on their way through a driver.**
  `Image::from_bytes` hands the driver the caller's bytes, the built-in
  driver writes PNG and BMP from the pixels it holds, without the copies
  the codec registry's encoders made of every frame, and returns the
  buffer its encoder writes instead of a copy of it (when metadata needs
  more room than the encoder left, that buffer grows once), and the
  `magick` driver writes an image to ImageMagick's standard input
  without copying it first and adds the metadata a source keeps (PNG
  colour chunks, an orientation tag) to ImageMagick's output without
  copying that either.
  An ICC profile split across a JPEG's or GIF's segments is read for its
  header and length where it stands, and joined once, only when the
  output carries it or converts from it; a WebP's or BMP's profile is
  carried without a copy, and a profile is written into the output once.
  `IMAGE_MAX_ALLOC_BYTES` charges a profile for what is held: every
  inflate of a PNG's profile at its declared size, a check of its length
  included, the compressed copy PNG output makes, and the output's copy,
  but nothing for a profile that is dropped or lent without being
  inflated; a refusal names what it charged. Between two `magick` runs an
  RGB profile goes on as the chunk ImageMagick wrote.
- **Queue and failed-job table names with capitals or reserved words
  work.** The jobs driver and the failed-jobs store quote each part of the
  configured table name, as the migrations do.
- **`generate-types` reads `{post:slug}`** as the parameter `post` and no
  longer takes a leading bound argument for the form request.
- **The Inertia CRUD tutorial compiles**: its `inertia_response!` calls
  pass the request, and its handlers bind `Todo`.
- **Live upload and async routes follow the configured endpoint**, and the
  header bar's default brand link carries the root.
- **Batch settlement counts work on MySQL** against a `job_batches` table
  Laravel created: `job_batch_settlements`, new in 4.0.0, takes that table's
  collation, so a count never compares two collations.
- **On Postgres, a session write for a guest** binds `sessions.user_id` as a
  NULL that the `bigint` or `uuid` column of Laravel's `sessions` layout, new
  in 4.0.0, accepts.
- **A component's scripts import by relative path only.** The `live:add` scan
  refuses a static `import` of an absolute path such as `/acme-ui/x/x.js`,
  even to the component's own script, as it refuses a URL (`script-import`),
  since an absolute path breaks when the application serves under a path
  prefix. The refusal says the specifier must be a relative path (`./` or
  `../`) to a script of the component or of a component it depends on. A
  relative path with one `../` more than the component is deep
  (`../../../acme-ui/x/x.js` from `acme-ui/x/`) is refused for the same
  reason: the browser resolves it outside the prefix.
- **A component's script can no longer reach a built-in prototype through
  a computed key or a name.** The `live:add` scan refuses
  `Array.prototype.map = ...`, and also `Array["prototype"].polluted = 1` and
  `const p = Array.prototype; p.polluted = 1;`, each of which adds a property
  to every array on the page. A script may read a member of a prototype
  (`Array.prototype.slice.call(list)`) but not keep or pass on the prototype:
  the scan refuses it in every position where it is a value (an initializer,
  an assignment, an argument, a `return`, an array or object element, a
  default, a template substitution), under a computed key that traces to
  `prototype`, and from `getPrototypeOf` (`script-prototype`). A write to a
  prototype's member is refused in every form (`=`, `??=`, `+=`, `++`, a
  destructuring or `for` loop target, `delete`), as is a method called on the
  prototype itself (`Array.prototype.push(1)`), which runs with the prototype
  as `this`, and destructuring `prototype` out of an object
  (`const { prototype: p } = Array`). Twelve bypass fixtures pin it:
  `script-prototype-computed`, `script-prototype-template-key`,
  `script-prototype-alias`, `script-prototype-argument`,
  `script-prototype-getprototypeof`, `script-prototype-parameter`,
  `script-prototype-destructured`, `script-prototype-compound`,
  `script-prototype-destructuring-target`, `script-prototype-delete`,
  `script-prototype-receiver` and `script-prototype-destructured-key`.
- **A destructuring assignment's defaults, nested keys and shorthand
  targets are scanned.** The `live:add` script scan walks every key and
  default of a destructuring target at any depth, as it walks any value, so
  `eval`, a prototype or any other refused expression is refused in the
  default of `[a = eval("alert(1)")] = []` or `({ a = ... } = {})` and in the
  keys of a nested target, and a nested or shorthand key gets the property
  checks a top-level key gets (`({ constructor } = [])` is refused as
  `script-eval`). A shorthand target (`u` in `({ u } = o)`) is a target like
  any other: after it the scan does not trace `u` to the constant it held
  before, since the name holds a value the scan does not follow, and a name
  the script does not declare is a global write, so
  `({ location } = { location: "javascript:alert(1)" })` is refused
  (`script-url` for `location`, `script-global` otherwise). Four bypass
  fixtures pin it: `script-destructuring-default-eval`,
  `script-prototype-assignment-default`, `script-destructuring-shorthand-url`
  and `script-destructuring-shorthand-global`.
- **The script scan follows a value by the names it was written with.** To
  check a URL, a timer handler or a computed key, the `live:add` scan follows
  a name to its initializer, its assignments and the arguments of its
  function's calls, and each name in a followed value names the binding it had
  where it is written, not a name that shadows it where the value is used. So
  `const y = "https://evil.example/x"; const x = y;` followed by
  `function show() { const y = "/ok"; img.src = x; }` is refused
  (`script-url`), a timer cannot be handed a string that way, and a constant
  shadowed by a remote URL where it is used is not refused. The
  `script-trace-shadowed-initializer` fixture pins it.
- **The script scan sees the global object through an expression.** The
  `live:add` scan refuses `window.localStorage`, a global it does not admit,
  and its rules about the global object's members see through a sequence's
  last expression, a conditional's branches, a logical expression's sides and
  an assignment's value. So `(0, window).localStorage`,
  `(0, self)["localStorage"]` and `(0, globalThis).fetch = f`, which would
  replace a browser API, are refused as the bare form is (`script-global`),
  and `(flag ? window : self).localStorage` and
  `(w || globalThis).localStorage` name `localStorage` in their refusal. A
  write through such an expression does not make a global of the script's own.
  The `script-global-sequence` fixture pins it.
- **Writing a browser global no longer unlocks reading it.** A name a script
  writes on the global object does not become a global of its own that it
  could read back. So `try { window.localStorage = 1 } catch {}`, whose write
  throws into a `catch` that swallows it, does not make `window.localStorage`
  readable: the read, which would return the browser's storage, stays refused,
  and the `live:add` scan refuses the write too. The
  `script-global-write-unlocks-read` fixture pins it.
- **Magnetar's API documentation builds without the `two-factor`
  feature.** The doc comments on `LockoutFields::IDENTITY_IS_EMAIL` and
  `LockoutService::without_user_lock` linked
  `two_factor::lockout_identity`, which exists only with that feature, so
  rustdoc failed on two broken links under Magnetar's default features.
  They now name it as text, with the feature that provides it.
- **API documentation writes ranges in words.** The docs of
  `PhoneNumber::new`, `PaymentMethod::Card`'s `exp_month`,
  `Batch::progress` and `SseEvent::keep_alive` wrote their ranges with an
  en dash; they now read "8 to 15", "1 to 12", "0 to 100" and "15 to 30
  seconds".
- **A prop holding `<!--<script>` no longer breaks the first Inertia
  page.** The first visit's page JSON escaped `/` but left `<` and `>` raw
  inside its `<script>` element, so a prop such as `<!--<script>` put the
  HTML tokenizer into its escaped script state: the real `</script>` no
  longer closed the element, the mount element `<div id="app">` became
  script text, and jsdom found no `#app` and a page JSON it could not
  parse. `<` and `>` are now written as `\u003c` and `\u003e` beside the `/`
  escaping, in the same single buffer, as Laravel's `JSON_HEX_TAG` and
  Inertia 3.7.1 do (JE-01, H02).
- **An Inertia page that cannot be encoded answers an error.** A failure
  to encode the page object answered `200` with `{}` as the page, as JSON
  for an Inertia visit and inside the first visit's document, so the
  client mounted an empty page. It now answers `500` through
  `FrameworkError`, as Laravel's `JsonResponse` throws (JE-03). Encoding a
  `serde_json::Value` page does not fail today, so this closes a path
  rather than one seen in use.
- **An empty SSR answer renders on the client.** A worker answer of `{}`,
  or an object without a `body`, was inlined as an empty body, so the first
  visit's document had neither the page data element nor the mount element
  and the client could not start. An answer whose JSON is empty, `null`,
  `false` or not an object, that has no non-empty `body` string, or that is
  not JSON at all, now renders on the client from the page data, as
  Laravel returns `null` for it, and is not reported as a failure (SS-02).
- **SSR workers at `https` URLs are reached.** The SSR client was hyper's
  plain-HTTP connector, which refused an `https` URL, so a worker behind TLS
  was never contacted and every first visit fell back to the client. The
  client now speaks TLS through rustls, the stack the HTTP client facade
  uses, and keeps the 5 second whole-call timeout over headers and body,
  the 8 MiB response cap and the refusal of an oversized `Content-Length`
  (SS-14).
- **DevTools redacts a flattened key by its parts.** A multipart field keeps
  its flat name, so `user[password]=hunter2` is stored under that name, and a
  dotted prop path such as `auth.password` keeps its own `propValues` leaf
  beside the nested page value. A key is sensitive when the whole name, or any
  part of it split on `[`, `]` and `.`, names a redaction key, at any depth of
  the entry and in query parameter names alike, so both values are redacted; a
  longer word such as `passwords` is kept (DT-07, DT-08).
- **DevTools redacts the URLs in headers and bodies.** The query of every
  string that is a URL (it holds a `?` and starts with a scheme, `/` or `?`)
  is redacted wherever the entry holds it, not only under a `url` or
  `redirectLocation` key, so a response's `Location: /reset?token=abc` and
  `X-Inertia-Location`, a request's `Referer`, and a `redirect_to` field
  carrying `?token=` never reach the entry file as sent. In both header bags
  so is the whole value of `Location`, `X-Inertia-Location`, `Referer` and
  `Content-Location`, each `<...>` target of a `Link` and the target of a
  `Refresh`; a header that is not a URL is stored as sent (DT-07, DT-08).
- **A lost DevTools index no longer drops the entries it listed.** The index,
  `_meta.json`, is rebuilt from the entry files whenever it is missing, empty
  or not a JSON list, before a rewrite as well as a read, so the older entry
  files stay in the list and under the 24-hour prune and the per-tab limit.
  Each rewrite writes a new file and renames it over `_meta.json` under a lock
  on `_meta.lock`, so an interruption leaves the previous index in place,
  never an empty one (DT-07, DT-08).
- **A commented-out augmentation no longer hides the generated one.**
  `generate-types` and `serve` read a project's files as TypeScript tokens
  when they look for its own `declare module '@inertiajs/core'`, with `//` and
  `/* */` comments and the text of `'...'`, `"..."` and template literals set
  aside, so only a declaration in code counts. A `frontend/src/global.d.ts`
  holding only `// declare module '@inertiajs/core' {}` keeps the generated
  augmentation and its `import`, and a comment between `declare`, `module` and
  the name hides no real one (T02).
- **A DevTools entry and `Request::route_name` name the route that
  matched by its method.** The router kept one process-wide table from name to
  pattern, and a request's name was looked up by its pattern alone, so
  `GET /users` named `users.index` and `POST /users` named `users.store` both
  reported whichever name the table listed first, and an unnamed `PUT /users`
  reported one of them too. The router now records each name against the
  method and pattern it was given for, through `.name(..)`, a route group's
  names and a resource's names, and the server sets the matched route's name
  on the request, so each method reports its own and an unnamed one reports
  none. A request that never went through dispatch still falls back to the
  pattern lookup (DT-04). `MatchedRoute::name`, which a `Router::bind`
  resolver reads, reports the name the request carries too.
- **A hook-shared prop names a file and line.** `InertiaConfig::hooks` takes
  its caller's location through `#[track_caller]`, and every key the
  middleware hooks' `share` supplies names that call's file and line as its
  `shareSource`, a place the extension can open (DT-03).
- **A page whose document fails is recorded as the error the client
  got.** The render hands DevTools its page only once the response is built,
  after the JSON encoding, the SSR dispatch and the root template. When any of
  those steps fails, the entry records the `500` the client got and its body
  as a response with no page, no `component` and no prop values, never the
  page object or `propValues` the client did not receive (DT-03, DT-04).
- **Every render prop has a `renderSource`.** A render prop's source is the
  line below the render call that names its key. When no such line exists, as
  for a page rendered with `InertiaResponse::new("Home").with_data(props)`
  whose struct is defined in another file, or in a deployment without its Rust
  sources, the prop names the render call's own file and line (DT-03).
- **DevTools reads a request body as the handler would.** The recorder reads a
  request body up to the request body cap (8 MiB by default), with or without
  a declared length, so a long or chunked body is recorded; PAR-072 allows an
  omission for the response body only. A body over the cap records `too-large`
  and reaches the handler whole: unread when its length is declared, else as
  the bytes read and the rest of the stream, the new `BodyState::Partial`. A
  failed read records `unreadable` and leaves its error in the new
  `BodyState::Failed`, which the handler meets only when it reads the body
  (DT-02, DT-10).
- **A DevTools JSON request body is recorded whatever it parses to.** A parsed
  JSON body is present in the entry whatever its value, `{}`, `[]` and `null`
  included, one that does not parse is kept as its text, and only a body of 0
  bytes is `empty` (DT-02).
- **DevTools no longer reads an upload before its authorization.** The
  recorder does not read a multipart body itself: the multipart extractor
  hands DevTools a summary of what it parsed, after
  `MultipartRequestHooks::authorize` has passed the upload. An upload no
  extractor read records `not-read`, and one whose parse failed, such as one
  without its closing boundary, records `unparsed`, both with the declared
  length as `size`; the raw text, which redaction does not look into, is never
  stored. A name sent more than once, or one that ends in `[]`, is the list of
  its parts, so all three files of a `photos[]` field are recorded (DT-02,
  DT-10).
- **The DevTools id tag finds a closing body tag in any case.** The tag goes
  before the closing body tag, found in any case and with space before its
  `>`, so a first visit whose root template closes with `</BODY>` or
  `</Body >` carries it, and a document with none gets the tag at its end
  (DT-02).
- **A tagged first visit no longer carries the untagged page's length.** A
  `Content-Length` the handler set on its page is dropped when the tag is
  added, and the server sends the tagged document's length, since the untagged
  length on the longer document breaks the HTTP/1 framing in a release build
  and fails hyper's assertion in a debug build (DT-02, DT-10).
- **A console command whose boot fails is reported.** A failure before the
  handler runs reaches `Exceptions::report`: a bootstrap that panics, as
  `DB::init().await.expect(..)` panics when the database does not answer, and
  a framework boot that returns an error, such as a log channel nothing
  defines. The console dispatcher and the application binary's commands catch
  a panic in the bootstrap, report the failure, so the callbacks the bootstrap
  registered before it failed see it, and then print it and stop the
  supervisors, as Laravel's console kernel reports a failure of its bootstrap.
  The application binary's commands report their own errors as the console's
  do; a silent error is not reported (PAR-111).
- **`schedule:interrupt` boots the cache it writes its mark to.** The command,
  new in 4.0.0, boots the store `CACHE_DRIVER` names, after the MongoDB
  connections with `database-mongodb`, and keeps a store the bootstrap bound,
  so it writes its mark in a real process whose bootstrap binds no store
  (PAR-089).
- **A queue driver installed in the bootstrap survives the boot.** The
  server and the worker commands ran `queue::bootstrap_from_env` after the
  application's bootstrap, and it replaced the driver `Queue::set_driver`
  had installed with the one `QUEUE_DRIVER` names, so the manual's
  failover example did not hold. `bootstrap_from_env` now keeps a driver
  the application installed and does not read `QUEUE_DRIVER` then; it
  still registers the `QUEUE_CONNECTIONS` entries beside it, and still
  replaces a driver an earlier call installed. A test that boots the queue
  from the environment empties the slot first with the new
  `queue::testing::forget_driver` (PAR-017).

- **Every Live engine type a public signature names is named through
  `suprnova`.** `live::testing::request_cancellation_for_test` returned the
  Live engine's cancellation flag, `AdjustableTestClock` implemented the
  engine's clock trait with its clock error, and `StitchSlotDescriptor`,
  `LiveNestedSegment::into_segment`, the RenderCache stores, lease stores and
  instance record stores named engine types `suprnova` did not re-export, so
  an application could not write those types down. `suprnova::live` now
  re-exports `Clock`, `ClockError`, `ClockErrorKind`, `CancellationFlag`,
  `BuildId`, `ComponentName`, `ContentDigest`, `IslandSlot`, `RouteIdentity`,
  `DocumentMountKey` and `MountedDocumentPath`, and `suprnova::live::ledger`
  the instance record store contract (`InstanceRecordStore`,
  `InstanceRecordKey`, `PromotionRecordKey`, `StoredRecord`, `CasOutcome`,
  `LedgerError`, `LedgerErrorKind`). `suprnova::render_cache` re-exports
  `RenderCacheError`, `RenderCacheErrorKind`, `RenderKey`, `Segment`,
  `ShellIsland`, `SlotFailurePolicy`, `AuthorizationConsult`,
  `GenerationLedger`, `GenerationSet`, `LeaseStore` and `LeaseAttempt`, and
  `suprnova::render_cache::store` the L1 store contract (`RenderStore`,
  `PublicationFence`, `PublishOutcome`, `StoreInspection`, `StoredEntry`).
- **The Inertia DevTools gate's `GateEvaluated` event names the signed-in
  user.** The DevTools entry endpoints check their gate with the user as
  `Gate::inspect_current` and `#[authorize]` do, so the event carries the
  user's own type name and identifier, for a user type that registered no gate
  or hook too.
- **`where_relation` on a `MorphTo` relation matches the owners.**
  `where_relation`, `where_relation_op` and `or_where_relation` on a
  polymorphic owner relation built the generic probe, which has no table
  to read, so they matched no row. They now go through the morph engine,
  as `has` and `where_has` do: the condition runs against every owner
  type the relation declares, under each owner's own scopes, as Laravel's
  `whereRelation` reaches `hasMorph` through `whereHas` (PAR-121).
- **`cursor_paginate` keeps the query's order.** It replaced every ordering
  with the primary key, ascending, so a newest-first query such as `latest()`
  came back oldest first. Every ordering is now kept and carried in the
  cursor: a descending order walks downward, the primary key breaks ties, and
  a query with no order still walks the primary key ascending. An ordering the
  cursor cannot carry, such as `order_by_raw` alone, fails with a 400 error
  instead of being dropped, and so does an ordering on a joined table's
  column, such as `owners.id`. In a joined query the primary key that breaks
  ties names the model's table, and the query quotes the columns it orders by,
  as it quotes its other references to the model's table, so an ordering on a
  table whose name has capitals works on Postgres (PAR-080).
- **`#[model(timestamps = true)]` without the columns fails the build.**
  An explicit `timestamps = true`, or the bare `timestamps` flag, on a
  struct with neither `created_at` nor `updated_at` was accepted and
  managed no timestamps. It is now a compile error that names both
  columns, as `#[suprnova::document]` reports it. The default and
  `timestamps = false` compile as before (PAR-183).
- **An Inertia visit the fallback route answers records the previous
  URL.** An Inertia `GET` the fallback answered left the session's previous
  URL where it was, where Laravel's `shouldStoreCurrentUrl` reads a fallback
  route as a matched route. The fallback route's request now carries a
  fallback mark, `Request::is_fallback_route`, which the Inertia middleware
  reads beside the route pattern when it records a visit; the request still
  has no route pattern and no route name, so RenderCache, the debug page and
  DevTools see no routed match (PAR-048).
- **`Request::full_url` and `url::full` normalise their query as
  Laravel's `fullUrl` does.** They returned the query as it arrived,
  where Laravel's `fullUrl()` and `url()->full()` sort the pairs by key
  and re-encode them per RFC 3986 through Symfony's
  `normalizeQueryString`: `/s?b=2&a=1` is now `/s?a=1&b=2`, and a query
  that normalises to nothing leaves no `?`. `full_url_is`, the SSR
  exclusion patterns, the `InertiaVisit` a hook receives and the DevTools
  entry URL read the normalised URL, as Laravel's do. The previous URL a
  page load or an Inertia visit records is normalised too, as Laravel's
  `StartSession` and Inertia `storeCurrentUrl` store `fullUrl()`, so the
  session holds the query as the page `url` and the version 409's
  location spell it. `full_url_with_query` and signed URL checks keep the
  query as the client sent it (PAR-056).
- **`simple_paginate` takes a page name, and `cursor_paginate` records its
  cursor.** `Builder::simple_paginate_using(page_name, per_page)` reads
  the page from that query parameter and sets the paginator's
  `page_name`, so its URLs and the Inertia scroll metadata's `pageName`
  use it, as `paginate_using` does for the length-aware paginator. A
  `cursor_paginate` page keeps the cursor it was fetched with in
  `current_cursor`, which the scroll metadata reports as the current
  page (PAR-052).
- **A CLI built between two releases pins the framework commit it was
  built from.** `suprnova new` pinned a new project's `suprnova` dependency at
  `v<CLI version>` even when the CLI was built from a later commit, as on
  `main` between two releases, whose templates can use API the last tag lacks,
  so such a scaffold could fail `cargo check` until the next release. The
  CLI's build script now records the commit it is built from and whether the
  tag `v<version>` names that commit. Only then does the scaffold pin
  `tag = "v<version>"`. The script reads the tag from its own checkout, or,
  when the checkout has none, from an `origin` on the same machine, so a
  release installed with `cargo install --git --tag` pins the tag: Cargo's
  checkout carries no tags, and the script reads the release tag offline from
  Cargo's git database. An `origin` reached over the network is never asked.
  With the tag on another commit, or in a checkout with no tag information,
  such as a shallow clone, the scaffold pins `rev = "<commit hash>"`, which at
  the release names the same source as the tag. A build where git cannot
  answer pins the tag. `templates::framework_pin` returns the choice, and
  `templates::cargo_toml_pinned` and `templates::api::cargo_toml_pinned`
  render a manifest with a pin you give.
- **What the script scan learns from member writes does not depend on
  statement order.** A member a class writes on `this` is the instance's own,
  a name a script writes on an object of its own may be its method rather than
  a browser API's, and a write on the global object (`window[key] = value`) is
  refused under the name its key traces to. The `live:add` scan settles those
  names after its first walk has met every name and every call, so a computed
  key's name, a name the script defines further on and a function's later
  calls count wherever they stand: a script is admitted or refused in any
  statement order, and a read of a global name nothing wrote is refused.
  `eval`, `Worker` and every other property refused by name are refused in any
  order.
- **The script scan refuses every write to a member of the global
  object.** As REG-032 requires, the `live:add` scan refuses a write to a
  member of the global object, or of the window `window.open` returns
  (`script-global`), whatever the name, in every form of write, `delete`
  included, so a component cannot overwrite a name the application or the Live
  runtime keeps on `window`. That covers a capitalised name the browser does
  not define (`window.AcmeState = {}`, `globalThis["Acme" + "State"] = 1`),
  which does not become a global of the script's own, names the scan's lists
  do not hold (`window.onload = f`, `window.name = "x"`) and
  `delete window.fetch`, and a later read of the name is refused as a read of
  any global the scan does not admit is. A component keeps its state in its
  module scope. The shipped `combobox` no longer writes
  `globalThis.SuprnovaCombobox`: its script's function returns the
  stale-suppression decisions, and the fixture that evaluates the file takes
  them from the script's completion value.
- **`#[derive(MultipartRequest)]` reads indexed and bracketed part names.**
  The derive matched a part's name to `#[field(...)]` letter for letter, so
  the Inertia client's `photos[0]` and `photos[1]` never reached a
  `#[field("photos[]")]` list and `user[name]` never reached a field. A part
  now goes to the field its name addresses, read as a form request reads it
  (PAR-055): `photos[0]` and `photos[]` fill the list declared as `photos[]`
  or `photos`, in index order, and `user[name]` fills the field declared as
  `user.name`. A name sent exactly as declared still matches. A failure is
  named by the index the part was sent under (`photos.3`), and `max_count` and
  the file checks that run while the body streams apply to every part the
  field takes, whatever name it was sent under. Parts are read in the order
  they were sent, as PHP reads them: a later part sent under a parent name,
  such as `user` or a bare `photos`, replaces what `user.name` or `photos[]`
  held, and a later `user[name][first]` or `photos[0][caption]` makes
  `user.name` or that element an array, which fails as the wrong kind of
  value.
- **`suprnova generate-types` pairs a page built with the builder.** In 3.2.1
  `generate-types` wrote no `Pages` map, and a field a handler deferred or
  marked optional was written as required, though the first response leaves it
  out (PAR-068). The component named in the first call of a chain
  (`InertiaResponse::new`, `Inertia::paginate`, `Inertia::data`,
  `Inertia::try_data`) now pairs with the struct `.with_data(..)` gives
  anywhere in it, and a key the chain passes to `.defer(..)`,
  `.defer_with(..)` or `.optional(..)` after it gives the struct is optional
  in the struct's interface.
- **A database session read keeps a session another request refreshed.**
  `DatabaseSessionDriver::read` found a row idle past the lifetime and then
  deleted it by id alone, so a request that loaded and refreshed the same
  session between that read and the delete lost its write, and the next
  read found no session. The delete now matches the row only while its
  `last_activity` is still older than the lifetime, as the MongoDB driver's
  does; the read that saw it expired still answers no session (PAR-188).
- **The Laravel-database tests run each SQLite test on one connection.** The
  SQLite fixture of the Laravel-database tests holds one connection. sqlx
  returns a released connection to the pool on a spawned task, so with more
  than one connection a test that awaits every statement in turn can still
  spread the fixture, the migrator's `CREATE TABLE` and a model's first write
  over connections the runtime chooses, and run that write on a connection
  other than the one that created its table.
  `kit_scaffold_notes_belong_to_laravels_users_sqlite` checks that the fixture
  holds one (PAR-080).
- **The `Inertia` facade shares a once prop.** In 3.2.1 only
  `App::inertia_share_once` and `InertiaRegistry::share_once` registered a
  shared once prop, so Laravel's `Inertia::shareOnce($key, fn () => ...)` had
  no facade form (PAR-052). `Inertia::share_once(key, resolver)`, beside the
  facade's `share`, `share_many`, `share_data` and `share_provider`, makes the
  same registration and returns the same `SharedOnceProp`, which takes
  `as_key`, `until`, `fresh` and `once_with` as any once prop does.
- **The component allowlist refuses test fakes, app-wide hooks and
  installs.** The `live:add` scan of a component's Rust refuses `Http::fake`,
  `Queue::fake`, `Mail::fake`, `Storage::fake`, `Process::fake` and their
  siblings, `Http::global_options` and the global request and response
  middleware, `Queue::set_driver`, `Cache::set_connection`, the `install` of a
  service, and the test container and clock, whatever capability the facade's
  chapter grants, so a component granted `network` cannot rewrite every
  request the application makes or swap a driver for every caller (REG-030).
  The allowlist generator refuses them by name, and the embedded allowlist
  carries the refusal.
- **Every Live and Magnetar type a public signature leads to is named
  through `suprnova`.** A public signature of `suprnova`, or of an engine
  item it re-exports, names only types an application can write down; 330
  of them had no `suprnova` path. `suprnova::live` re-exports the 212 Live
  engine types those signatures lead to: the typed identities, input limits,
  upload inspection, finalize evidence and field policy, the host context,
  component hooks and child composition, snapshot schemas, model state and
  proposals, the update protocol, the asynchronous stream contracts and the
  mount failure, with the engine registry's error kind as
  `EngineRegistryErrorKind`; `suprnova::live::action` the action table, its
  dispatch and the registered emissions; `suprnova::live::metadata` the
  component, field, action, event and effect metadata;
  `suprnova::live::validation` `ValidationBagError` and
  `ValidationSelection`; and `suprnova::render_cache` the render key input
  and variance, `Generation`, `QueryUnknown`, `ResponseSignals` and the
  snapshot key ring. The 118 Magnetar types are re-exported under
  `suprnova::magnetar_integration`: the factor gate, sessions, schema,
  storage, password verifier and lockout, passkey ceremony, lifecycle event,
  first email proof and two-factor types, and with `magnetar-oauth` the
  OAuth ceremony, error and verified identity types, the broker error and
  Apple's ID token claims. The Live engine exports `ValidationBagError`,
  which `ErrorBag::from_issues` and `ValidationMessageId::parse` return.
- **Web Push refuses endpoints that resolve to private or local addresses.**
  In 3.2.1, `EndpointPolicy::Strict` checked the shape of a subscription
  endpoint (`https`, a host name in place of an IP address, and a list of
  local and cloud metadata names) but not where the name resolved, so an
  endpoint whose name resolved to `127.0.0.1`, a private network or a
  metadata service was sent to, and the transport looked the name up again
  when it connected, or handed it to a proxy set on the builder or named by
  `HTTPS_PROXY`, which resolved it itself. A client passed to
  `WebPushClient::with_client` sent under `Strict` once
  `allow_unconfined_redirects` was called. A `PushServiceRejected` also kept
  up to 8 KiB of the push service's response body, which `WebPushChannel`
  put in the error a `NotificationFailed` listener received. The strict
  policy now resolves the name and refuses the send with
  `WebPushError::RefusedDestination` when any answer is a loopback, private,
  link-local, multicast, unspecified, documentation, reserved or cloud
  metadata address; the error names the class (`AddressClass`), never the
  address, and a failed lookup returns the retryable `WebPushError::Lookup`.
  The transport `WebPushClient::new` and
  `WebPushClient::with_client_builder` build connects to an address that was
  checked, keeping the name for TLS and the `Host` header, and does not look
  the name up again; it sends through no proxy, so neither a proxy on the
  builder nor `HTTPS_PROXY` can resolve the name past the check. A strict
  send over a client passed to `with_client`, which resolves the name
  itself, returns the new `WebPushError::UnpinnedTransport` before anything
  is sent, until the caller accepts that by name with
  `WebPushClient::allow_unpinned_destinations`, which keeps the address
  check. `PushServiceRejected` carries the status and the `Retry-After` hint
  and no part of the body, whose first 200 bytes go to the debug log, and
  `WebPushChannel` names the status alone and logs a refused destination as
  a subscription that cannot be used.
- **The same-origin WebSocket policy compares the scheme.** In 3.2.1,
  `OriginPolicy::SameOrigin`, the default policy of a WebSocket route,
  compared the `Origin` host and port with the `Host` header and ignored the
  scheme, so a page at `http://app.example.com` could open a socket on the
  application served at `https://app.example.com`. It now compares the
  complete origin: the `Origin` scheme, host and port against the request's
  public scheme (`Request::scheme`, which reads `X-Forwarded-Proto` and
  `X-Forwarded-Ssl` from a trusted proxy only), its host (`Request::host`)
  and its port (`Request::port`, or 443 for `https` and 80 for `http`). It
  refuses the upgrade with `403` when the public scheme cannot be
  determined: a trusted proxy that sends neither header or names a scheme
  other than `http` or `https`, or either header from a peer that is not a
  trusted proxy. The check reads the request the handler receives, so a
  malformed handshake is now answered `400` before its origin is checked.
- **The dogfood application's password reset reports success only when both
  revocations succeed.** In 3.2.1, the dogfood application's
  `POST /auth/password/reset` called `PasswordReset::complete`, which
  discards the outcome of revoking the user's other sessions and remember-me
  tokens, and redirected to `/?reset=ok` once the password was written. It
  now calls `PasswordReset::complete_with_outcome`, as the scaffold's
  controller does, and redirects only when both revocations succeeded. A
  failed revocation is logged at error level with the user's id and answered
  with a `500` through the framework's error path; the password stays
  changed.
- **A password reset whose revocation fails queues a retry.** In 3.2.1,
  when the provider path of `PasswordReset::complete` or
  `PasswordReset::complete_with_outcome` could not revoke the user's other
  sessions or remember-me tokens, it logged a warning, reported the error in
  the outcome, and nothing tried again. The reset token was spent and the
  password changed, so a stolen session or remember-me cookie kept working.
  Both now push the new `RevokeUserCredentials` job for the user before they
  return. A queue worker runs it until both stores confirm the revocations,
  with no bound on the tries: the first retry after about 10 seconds and
  each later one twice as long, up to an hour between tries, with a
  60-second timeout per try. The job reaches `failed_jobs` only when the
  worker's `--tries` bounds it or a try returns an error that ends retries.
  It is idempotent, so running it again, from `queue:retry` or by hand, is
  always safe, and the framework registers it with the worker.
  `PasswordResetOutcome` has a `revocation_retry` field, a `RevocationRetry`
  that says whether the job was queued (`Queued`) or not needed
  (`NotNeeded`). When the push fails too, both return an error instead of
  the outcome: it says that the user's password changed, names each failed
  revocation with its error and the push's error, and asks for
  `RevokeUserCredentials::new("<id>")` to be queued once the queue works.
  The framework logs it at error level with the user's id, and that reset
  sends no `PasswordChangedMail` and dispatches no `PasswordResetCompleted`.
  An application can queue `RevokeUserCredentials` itself after any other
  credential change whose revocation failed. The dogfood application logs
  the queued retry with the user's id before it answers its error, and
  answers a failed push with its `500` too.
- **Static files and Live UI assets are read through the directory they
  were checked in.** In 3.2.1, `StaticFiles` checked a request's canonical
  path against its root and then opened the file by name, and opened an
  extensionless file a second time to sniff its type; the Live UI asset
  routes of `try_live_ui_assets()` and `try_live_ui_assets_for()` compared
  canonical paths and then read the file's size and its bytes by name. Someone able to rename entries under the
  served directory could swap a directory for a symbolic link between the
  check and the open, and the server sent a file from outside the root, or
  a script past the 1 MiB bound. Both now walk the path one directory at a
  time through held directory handles, opening every entry with
  `O_NOFOLLOW` as a local disk does, and take the type, the length and the
  bound from the handle they read the bytes from. `StaticFiles` still
  follows a symbolic link that stays inside its root, and either root may
  itself be a link. A link whose relative target climbs above the root is
  refused even when it leads back in, and `StaticFiles` answers 404 for a
  FIFO instead of holding the request open. On a platform without
  `openat` the two servers serve nothing, since no check by name holds there.
- **The `magick` driver names the coder it hands ImageMagick.** In 3.2.1
  the `magick` driver named the coder only for PNG, JPEG, WebP, GIF and
  BMP. It handed every other input to ImageMagick on a bare `-`, so
  ImageMagick chose the coder from the upload's bytes: an MVG or MSL
  document ran as a script, and the host's `policy.xml` was the only
  barrier. In 4.0.0 the driver also recognises HEIC and the other HEIF
  images, AVIF, TIFF and BigTIFF, PSD and PSB by their leading bytes, and
  reads them as `heic:-`, `avif:-`, `tiff:-`, `psd:-` and `psb:-`. It
  refuses any other input before ImageMagick starts, with a 4xx
  `FrameworkError` that says the format is not one Suprnova names, in
  `process`, `dimensions` and `dominant_color` alike. Autodetection is an
  opt-in by name: `IMAGE_MAGICK_AUTODETECT=true`, held as
  `ImageConfig::magick_autodetect`, hands unrecognised input to
  ImageMagick on a bare `-` as before. The `oxideav` driver is unchanged.
- **A request body that stops arriving is abandoned.** In 3.2.1 the
  server bounded only the request head (`SERVER_HEADER_READ_TIMEOUT`):
  every read of a request body waited for each piece with no deadline, so a
  client that sent complete headers and then sent the body a byte at a
  time, or stopped sending it, held its connection, and with
  `SERVER_MAX_CONNECTIONS` set a connection slot, for as long as it liked
  (HRD-001). Every read of a request body now waits at most
  `SERVER_BODY_READ_TIMEOUT` (default 30 seconds) for the next piece and
  `SERVER_BODY_TOTAL_TIMEOUT` (default 3600 seconds) for the whole body,
  counted from when the server read the request head: `body_bytes`, `json`,
  `form`, `input`, the form request and multipart extractors, the multipart
  parsers, the middleware that read a body before the handler, and a
  handler that reads the raw stream from `Request::into_parts` itself. A
  body that misses either deadline is abandoned: the read fails with
  `408 Request Timeout`, and the server closes the connection after the
  response. A body nothing reads, such as one a handler keeps while it
  waits on other work, is abandoned at the total deadline and its
  connection closed. Every `408` response carries `Connection: close`. Zero
  or a value that does not parse falls back to the default, as for the
  header deadline. `ServerConfig` has the fields `body_read_timeout` and
  `body_total_timeout`, which `ServerConfig::builder()` and `Server` set.
  `BodyState::Streaming` and `BodyState::Partial`, which
  `Request::into_parts` returns, hold the new `suprnova::http::TimedBody`,
  the body under its deadlines, where they held hyper's `Incoming`, and
  `collect_body_with_cap` and `collect_body` take either.
- **New projects install the timeout middleware.** In 3.2.1 no bootstrap
  `suprnova new` wrote installed `TimeoutMiddleware`, so in a new project a
  slow handler or a hung query held its connection until the client gave
  up. Every bootstrap now installs `TimeoutMiddleware::default()`, a
  30-second ceiling on the time to a response that answers `503`. The
  Inertia kits install it after `Inertia::install` and the Live kit after
  its error page, both after `SessionMiddleware` and before
  `CsrfMiddleware`, so the `503` renders as the error page in the visitor's
  session and locale and the deadline bounds the CSRF body read. The API
  kit installs it first.
- **A session or remember-me cookie from before a password change stops
  working.** In 3.2.1, a password reset ended the user's other sessions and
  revoked their remember-me tokens at once, and nothing checked a session or
  a remember-me cookie against the password again: when the session store
  or the token table refused the revocation, a stolen session or cookie kept
  working until it expired. In 4.0.0, every sign-in issued through a user
  provider records the user's auth epoch: `Authenticatable::auth_epoch`, or,
  when the model returns none, a digest of the password hash
  `get_auth_password` returns. Every request that resolves the user from the
  session or a remember-me cookie compares it with the user's current one.
  On a mismatch, that guard's identity leaves the session, the remember-me
  row it holds is deleted and its cookie cleared, and the request continues
  as a guest's, so `AuthMiddleware` answers `401` or redirects to the login
  page; the framework logs the user id and dispatches no `Logout` event.
  Each `remember_tokens` row is bound to the epoch inside its hash, with no
  column added. A user whose model returns neither records no epoch and is
  not checked. `Auth::login_id`, `session::set_auth_user` and
  `TwoFactor::complete_challenge` ask no provider themselves, so the request
  that signs in reads the epoch through the default guard's provider before
  `SessionMiddleware` stores the session; when the provider fails that read,
  the sign-in is not stored and a warning is logged.
  `BasicAuthMiddleware::new()`, which in 3.2.1 let a session pass on its
  stored identity alone, now lets it pass only after the guard has resolved
  the user and compared the epoch, so a session from before the change gets
  the `401` challenge unless the request carries valid credentials. Each
  remember-me credential is bound to the epoch the guard's provider read for
  the sign-in, and a `SessionGuard` built by hand under a name the
  `AuthManager` does not know, which in 3.2.1 issued remember-me
  credentials, issues none: its login completes without a remembered session
  and logs a warning that names the guard. A remember-me cookie issued by 3.2.1
  carries no epoch: once its user has one, it fails verification once, its
  row is deleted and the cookie cleared. A session signed in by 3.2.1 is
  checked from the user's next sign-in. `Auth::logout_other_devices` binds
  the current session and remember-me cookie again when it rehashes the
  password. With the Magnetar engine installed, the default guard keeps
  Magnetar's own epoch check. No signature changed;
  `suprnova::auth::remember::issue` and `verify_and_rotate` now bind and
  check the default guard's epoch, and `verify_and_rotate` deletes a row
  whose verifier fails.
- **The `magick` driver runs ImageMagick under the framework's own policy.**
  In 3.2.1 every ImageMagick run read the host's `policy.xml` alone, so on a
  host with ImageMagick's default policy, which denies nothing, the script,
  network, text and Ghostscript coders and every delegate stayed open:
  PostScript or PDF on a bare `-` started Ghostscript. In 4.0.0 the driver
  writes a `policy.xml` of its own before each run, at
  `.config/ImageMagick/policy.xml` in a directory it makes once per process
  under the system's temporary directory, open to its owner alone; it checks
  the file byte for byte and writes it again when it differs. The policy
  denies the URL, HTTP, HTTPS, FTP, MVG, MSL, TEXT, LABEL, CAPTION, PANGO,
  SCREENSHOT, X, EPHEMERAL, PS, PS2, PS3, EPS, PDF and XPS coders, every
  delegate, and `@file` path reads, whether or not `IMAGE_MAGICK_AUTODETECT`
  is on; `MagickCliDriver::POLICY` holds its text. ImageMagick reads every
  `policy.xml` it finds and applies the last entry that matches, and it reads
  `$HOME/.config/ImageMagick` after `MAGICK_CONFIGURE_PATH`, its own
  configuration directory and `$XDG_CONFIG_HOME/ImageMagick`. So the driver
  starts it with `HOME` naming the policy directory, and with
  `MAGICK_CONFIGURE_PATH` naming the directory that holds the file first and
  last, around any `MAGICK_CONFIGURE_PATH` the operator set. The framework's
  policy is then the last ImageMagick reads, and it outranks every other
  policy on the host, the system, XDG and user files and an entry marked
  `stealth="true"` included, while the host's denials still apply. A
  `policy.xml` in the service account's own `~/.config/ImageMagick` no longer
  applies to the driver's runs. Before the first run of each process, for
  each binary and operator `MAGICK_CONFIGURE_PATH`, the driver checks that
  order under the same environment: `magick -list policy` must show the last
  entry that matches each denial denying and the framework's file as the
  last one read, and one MVG probe, a one-line MVG script read as `mvg:-`,
  must be refused by ImageMagick's security policy. A check that fails
  refuses every run, with or without `IMAGE_MAGICK_AUTODETECT`, with a 5xx
  `FrameworkError` that names the cause and the file, until the host is
  fixed and the process restarts. A listing or probe that cannot be had
  refuses the run, and the next run asks again. A directory the driver
  cannot make, or a policy file it cannot write and check byte for byte,
  refuses the run before ImageMagick starts, naming the path and the cause.

## 3.2.1 - 2026-10-05

### Fixed

- **A console binary builds in release again.** The console dispatcher
  awaited the application's bootstrap inline, so its whole state machine
  sat inside the dispatcher's, next to the process boot that 3.2.0 added
  there. A console `main` over a substantial bootstrap, the dogfood app's
  included, failed to compile in a release build with "queries overflow
  the depth limit!" while debug builds passed. The dispatcher now holds
  the bootstrap boxed, as `Application::run` holds its own.

## 3.2.0 - 2026-10-04

### Added

- **Second-factor attempt limits.** `TWO_FACTOR_MAX_ATTEMPTS` (default 5)
  and `TWO_FACTOR_LOCKOUT_MINUTES` (default 15, at most 43,200) set the
  sliding window in which second-factor failures lock an account's second
  factor; `TwoFactor::unlock` and Magnetar's `TwoFactorService::unlock` lift
  it. Password and second-factor lockouts count separately, so a password
  reset no longer lifts a second-factor lock. `Authenticatable::auth_epoch`
  lets a provider carry the epoch it read with the password hash through
  sign-in.
- **`Lang::reload`.** `Lang::reload().await` reloads the translation
  catalogs and, when their text changed, makes RenderCache pages built from
  the old translations miss; dev hot reload does the same. Call it from a
  deploy hook instead of `Translator::reload`, which left cached pages in
  the old language until their TTL.
- **Action directives pass arguments.** `live:click="remove(42)"` and
  `live:click="rename('draft', true)"` send literal arguments to the
  action's parameters in declared order; before, every action directive sent
  none, so an action with parameters could not be called from a template.
  Only literals are accepted (numbers, quoted strings, `true`, `false`,
  `null`), and `live:check` reports a wrong count or a literal of the wrong
  type at its line and column. The island root lists each action's parameter
  names in `data-suprnova-live-actions`.
- **OAuth identities carry the account's picture.** `OAuthIdentity` has
  `avatar_url`: the picture URL the provider reports, or none. Google fills
  it from `picture`, TikTok from `avatar_url`, Facebook from
  `picture.data.url` and X from `profile_image_url`; Apple reports none, and
  an empty value, or one of an unexpected shape, is none and never fails
  sign-in. Treat it as untrusted profile data, and check its scheme and
  length before you render, fetch or store it. A provider supplies it
  through `OAuthProvider::avatar_url`, which returns none unless the
  provider implements it, so a provider written before it compiles and signs
  in unchanged (#140).
- **An asynchronous multipart hook.** `MultipartRequestHooks` has
  `after_validation_async`, for checks that need the database before the
  handler runs. A multipart request runs `authorize` before it reads the
  body, then extraction with its field validation, `after_validation`,
  `after_validation_async` and the handler, each only after the one before
  succeeded. A hook that returns errors answers 422 with them, and an empty
  set of errors is success. An override needs `#[async_trait]` (#139).
- **Unsigned keys on every database.** A model field declared `u64` or
  `Option<u64>`, its key and foreign keys included, reads and writes on
  SQLite, Postgres and MySQL through the new `AsU64` and `AsOptionalU64`
  casts: the whole range on MySQL's unsigned columns, and `0` to `i64::MAX`
  on SQLite and Postgres, which store it signed. There a write of a larger
  value is refused before anything is sent, as a database error that names
  the column in the log, and a negative stored value fails to read the same
  way. A read by such a value answers what is true of every row: `find`
  returns none, so a model bound from a route answers 404, `find_many` skips
  the id, and a filter on the key or any narrower integer field matches as
  it would on MySQL. `DB::table` compares and writes such a value the same
  way. A `u64`-keyed model binds from a route, `chunk_by_id` and
  `lazy_by_id` walk the whole `u64` range on MySQL, and the built-in user
  providers sign in a user whose id is a `u64` (#137).
- **Settings that match Laravel's schema.** In a package's `Cargo.toml`,
  `[package.metadata.suprnova.model] datetime_cast = "native"` makes every
  `DateTime<Utc>` field of that package's models without a cast of its own,
  the managed timestamps included, use `AsNativeDateTime`, for a
  time-zone-aware column, and `"naive"` uses `AsNaiveDateTime`, for the
  time-zone-free columns Laravel creates on Postgres. In the binary's
  package, `[package.metadata.suprnova.schema] unsigned_ids = true` makes
  `id()` and `foreign_id()` create unsigned columns on MySQL in every
  migration the binary runs, and changes nothing on Postgres and SQLite;
  `#[suprnova::main]` installs it, and `Schema::use_unsigned_ids()` does the
  same for a program without it. An unknown key or value fails the build.
  New applications carry both settings commented out (#137).

### Changed

- **Empty form fields are null, and a repeated name keeps its last value.**
  In a `MultipartRequest` and in url-encoded `FormRequest`, `req.form()`,
  `req.input()` and `Request::query_into`, an empty field is now a key
  holding null, as Laravel's default `ConvertEmptyStringsToNull` leaves it:
  a required `String` fails, an `Option` is `None`, a `#[serde(default)]`
  field is null, and a map or `serde_json::Value` keeps the key, so it can
  tell a cleared field from one never sent. An empty value used to pass as
  `""` or fail to parse as a number. A `HashMap<String, String>` target now
  fails on an empty field; use `Option<String>` values or
  `serde_json::Value`. A list keeps a null element in its place: `None` in a
  `Vec<Option<T>>`, and `validation-required` under its index, such as
  `ids.1`, in a `Vec<T>`. `#[derive(MultipartRequest)]` accepts
  `Vec<Option<T>>`, and a list of files still leaves out an empty file
  input. A field name sent more than once keeps its last value, where
  multipart kept the first part (even an empty one) and url-encoded forms
  answered 422 for a duplicate field; names ending in `[]` still collect
  every value. A url-encoded or query `bool` reads `1`/`0`, `true`/`false`
  and `on`/`off` in any case, as a multipart one does; JSON stays strict
  `true`/`false`. A url-encoded, JSON or query field that is missing or does
  not parse answers as a validation failure naming every such field
  (`validation-required`, `validation-integer` and the like), where it was a
  bare 422 with no `errors`, so an Inertia form gets the usual redirect with
  each error under its input. CSRF checks the form's `_token` (its last
  value) before `X-CSRF-TOKEN` and `X-XSRF-TOKEN`, as Laravel orders them,
  and an empty or `0` value counts as absent; a form body larger than 64 KiB
  has its `_token` read up to the server's request body limit, where it used
  to fail CSRF. The requests and CSRF manuals list what still differs from
  Laravel.
- **The session, remember-me, auth-flow token and ceremony entities read
  whole rows on every column type.** Their time fields are the new public
  `suprnova::StoredDateTime`, which reads `DATETIME`, `TIMESTAMP`,
  `timestamp`, `timestamptz` and SQLite text, instead of `NaiveDateTime`,
  which failed on `TIMESTAMP` and `timestamptz`. Set them with `.into()` and
  read them with `.naive_utc()` or `.and_utc()`.
- **Magnetar rotations and second-factor lockouts.** Magnetar's `re_enroll`
  keeps the confirmed second factor gating sign-in until a code from the new
  secret confirms the rotation; the rotation waits in new `auth_two_factor`
  columns, `pending_secret` and `pending_recovery_codes`, which
  `default_schema::migrate` adds. `TwoFactorRow` gains those two fields, and
  a custom `TwoFactorStore` implements the new `confirm_rotation`. A
  second-factor lock or unlock never touches an `app_users` row
  (`LockoutFields::IDENTITY_IS_EMAIL`, `LockoutService::without_user_lock`),
  so an account registered as `two-factor:{id}` is never locked or unlocked
  by it. An account holds the framework's TOTP or a Magnetar second factor,
  never both: enrolling or confirming either answers 409 while the other
  exists, and disabling either one recovers an account that already has
  both. A custom host attaches `FrameworkTotpEnrollment` to its
  `TwoFactorService` through `with_other_second_factor`.
- **Live field and argument names must be ASCII and at most 128 bytes.**
  Such names used to panic at registration or fail later. A view-visible
  field may be named `component`; the view then reaches the component as
  `component_` (or the first of `component__`, `component___` that no field
  takes). A field or argument may be named like `suprnova_live_count`.
- **Cron steps count from the first value.** `*/N` in the day-of-month and
  month fields counts from 1, as cron and Laravel do, so `*/2` means odd
  days and schedules using it shift; the timezone display now agrees with
  the scheduler. Ranges with steps (`1-15/7`) and mixed lists parse.
- **Workflow steps are named by module path and function name**, so
  same-named steps in different modules are different steps. Runs recorded
  with bare names still replay.
- **`TestContainerGuard` can no longer be built directly**; use
  `TestContainer::fake()`. `dispatch_argv_with_init` boots the process and
  waits for queued listeners after the command; `dispatch_argv` does
  neither.
- **`save` and `update` refuse a model that was never inserted.** A replica,
  or a new model from `first_or_new` or `find_or_new`, still has its reset
  key, and `save` updated the row with key 0. It now returns an error naming
  `persist()`, which inserts the model and returns it with its new key.
  Laravel's `save` inserts such a model; `save` here takes `&self` and
  cannot hand the new key back, which the Eloquent manual explains.
- **The broadcast fanout no longer uses sea-streamer.**
  `SeaStreamerBroadcastHub` keeps its name and runs on the framework's own
  Redis client, and `sea-streamer` and `sea-streamer-redis` left the
  dependency tree. It supports `redis://`, `rediss://` and `memory://`, a
  stream shared by hubs in one process; `stdio://` is an alias for
  `memory://` and no longer reads or writes stdin and stdout. `kafka://` and
  `file://`, which were never compiled in, now give a clear error, and
  `new_loopback` behaves like `new`. An event published after the
  constructor returns always arrives. Stream entries keep their `msg` field,
  so hubs of the earlier version on the same stream interoperate during a
  rolling deploy.
- **New applications' session, remember-me and auth-flow token tables use
  `DATETIME` on MySQL**, so these columns stay writable past 2038-01-19.
  Postgres and SQLite are unchanged.
- **The features table holds times after 2038 on MySQL.** A new `features`
  table uses `DATETIME` on MySQL and MariaDB. Add
  `suprnova::features::migrations::FeatureTimestampsToDatetime` after
  `CreateFeaturesTable` in your migrator: it converts an existing
  `TIMESTAMP` table, keeping its UTC times and defaults, and does nothing on
  Postgres and SQLite.
- **Two-factor needs two new migrations.** Add
  `suprnova::auth_flows::two_factor::migration_attempts` (the
  `two_factor_attempts` table) and `migration_rotation` (the
  `two_factor_rotations` table) to your migrator. Without the first, every
  two-factor proof path answers 503 and names the migration; without the
  second, `TwoFactor::re_enroll` answers 503. A pending rotation keeps the
  confirmed secret gating sign-in until `confirm` promotes the new one,
  `enroll` cannot replace a pending rotation, and `disable` discards it.
  `enroll` answers 422 for a user id longer than 255 characters.
- **`Auth::password().register` returns a `Registration`**: `Created(user)`
  or `Accepted`, never the existing account. The
  `MagnetarPasswordAuthEngine::password_register` trait method returns it,
  and a custom engine gains `admit_host_sign_in` and `issue_host_session`,
  which refuse with 503 by default. The API starter answers every
  registration with one generic 202.
- **Magnetar's second-factor lockouts have their own table.** The default
  schema's migrate creates `auth_second_factor_lockouts`
  (`DefaultSecondFactorSchema`), and `TwoFactorService::new` takes a lockout
  service over it. `TwoFactorStore::set_confirmed` takes the enrollment
  snapshot that was checked, and the MySQL migration failures
  (`SwapFailure`, `MySqlMigrationFailure`) are boxed.
- **`Cache::tags_put` without a TTL applies `CACHE_DEFAULT_TTL`**, as
  `Cache::put` does. A tagged value that must never expire uses the new
  `Cache::tags_forever`.
- **`DiskExt::temporary_upload_url` returns a `TemporaryUploadUrl`** with
  `url`, `method` and `headers`, instead of a `String`. An S3 disk with
  server-side encryption signs headers such as
  `x-amz-server-side-encryption`, and an upload that did not send them was
  refused. Use `.url` and send `.headers` with the upload. Its `Debug`
  output redacts the signature and header values.
- **`Queue::bulk` honours debounce.** Every copy of a debounced job pushed
  through `Queue::bulk` used to run. A debounced burst now collapses onto
  its last job, and a job declaring both `debounce_for` and `unique_id` is
  refused, as `Queue::push` does. Laravel's `bulk` skips debounce; the
  queues manual explains the difference.
- **Multipart failures answer as validation errors under the field's input
  name.** A missing field, a text part that does not parse as its type or is
  not UTF-8, a part of the wrong kind, and a file a validator refuses (too
  large, not an image, a type `MimeType` does not allow) answer 422 with
  `errors` under the form input name, so the second file of a `files[]`
  field is `files.1`, and the Inertia validation middleware shows each error
  under its field. Before, a text part that did not parse answered 400, a
  file over `MaxSize` 413, and the others 422 without `errors`. The messages
  come from the validation catalog (`validation-required`,
  `validation-max-file` and the rest), so an application's
  `lang/<locale>/validation.ftl` overrides them. A file over `MaxSize` stops
  the body at the chunk that crossed the limit and leaves no temporary file.
  A field's `max_count` answers 413 with the other request-wide limits,
  instead of 422, and so does a text part longer than the in-memory spill
  threshold (2 MiB by default), instead of 400, as Laravel answers
  `post_max_size`. A file validator checks only the file parts its field
  takes: a text part sent where a file belongs fails as `validation-file`,
  and a later part for a field that holds one file is ignored without being
  read into memory or a temporary file. For a field that holds one value,
  its first part decides it, valid or not, so several failing parts report
  one error; an empty part does not decide a field that is not a `String`,
  so the next part of its name can. An `UploadValidator` returns
  `FrameworkError::invalid_upload` for a validation failure, and its other
  errors keep their status. A `bool` field accepts `1`, `0`, `true`,
  `false`, `on` and `off`. An empty part, which Inertia sends for `null`, is
  none for an optional field that is not a `String` and missing for a
  required one, and a part of the wrong kind sent to an optional or list
  field fails instead of being ignored. `MultipartValue`, which the
  streaming parsers return, has a new `NonUtf8Text` variant for a text part
  that is not UTF-8, so a `match` over it needs an arm for it (#139).
- **`#[model]` takes the key type from the key field.** Without `key_type`,
  the key type is the type of the field `primary_key` names; it was `i64`
  whatever the field said. A `key_type` that disagrees with that field fails
  to compile, naming both (#137).
- **`pluck`, `value` and the aggregates read every key type, and say why a
  value does not read.** `pluck`, `pluck_keyed`, `value`, `value_or_fail`,
  `sole_value`, `sum`, `min`, `max` and `DB::scalar` take any type that
  implements the new `ColumnValue` trait, which every type SeaORM reads
  already does, and `u64`, which they now read on SQLite and Postgres too. A
  generic caller bound by `TryGetable` needs `ColumnValue` instead. `avg`
  reads an `f64` or a `rust_decimal::Decimal` (the new `AvgValue` trait);
  another type no longer compiles. Postgres and MySQL average exactly, so a
  `Decimal` average is exact there. SQLite averages as a REAL, so there the
  `Decimal` holds the shortest decimal that round-trips SQLite's
  floating-point answer. `pluck`, `pluck_keyed` and `value` used to drop a
  row whose value did not decode, so `pluck::<u64>` returned an empty list;
  they still skip a NULL, and any other value that does not decode is an
  error naming the column (#137).
- **The combobox submits the chosen option's value.** A selection used to
  write the option's label into the one bound field, so the value each
  option carries never reached the server. `suprnova.combobox` now binds two
  fields: `name` is the chosen option's value, held by a hidden input that a
  selection fills and an edit of the text clears, and `<name>_query` is the
  typed text, which a remote listbox answers. The macro takes the island's
  value as `value`, and the script marks that option selected. Bind the
  query field where you bound `name` before, and read the choice from
  `name`.
- **Live's limits are settings sized for large pages.** Every limit Live
  applies is a `LIVE_*` key in the application's `.env` file or a
  `LiveConfig::builder()` method, and a value outside a key's range fails
  boot with an error that names the key. The browser runtime had smaller
  limits of its own: it refused an island render over 32 KiB and a morph
  past 10,000 nodes or one second while the server allowed 1 MiB, and an
  action whose island root passed 1 MiB failed. The bootstrap now writes
  every limit into the page's configuration element and the browser applies
  those values, so it never refuses what the server allows. Requests,
  responses and island HTML default to 16 MiB; a morph takes up to 1,000,000
  nodes and keys with no deadline; an upload sends 8 MiB chunks of a file up
  to 1 GiB; an open document holds and replays up to 4,096 asynchronous
  events; and a session streams to 64 open tabs, where it was 8. A replay
  log holds up to 4 MiB per subscription and 256 MiB across the process,
  dropping its oldest entries first, and a reconnect that needed a dropped
  entry renders fresh. A tripped limit's message names the limit, the
  measured and configured values and the key, in the browser console and in
  the server log. `suprnova live:inspect` prints every limit by its key, and
  the Live chapter lists them with their ranges. `live:check` and
  `live:inspect` speak tooling protocol 2 and fall back to protocol 1 with
  an application built before it.
- **Framework payments, features and RBAC models carry `DateTime<Utc>`
  timestamps.** The SeaORM `Model` of the six payments entities, of
  `features::entity`, and of the RBAC `Role` and `Permission` carries
  `DateTime<Utc>` (`Option<DateTime<Utc>>` for `canceled_at`, `paid_at` and
  `processed_at`) where it carried `String`, because their migrations create
  native timestamp columns. Code that read those fields as text needs the
  date-time type.
- **A mail message is checked on the dispatch path, and a refusal is a
  500.** `Mail::send`, `Mail::raw`, `Mail::html`, the queue worker and the
  notification mail channel check the message before `MessageSending` fires
  and before any transport sees it, including a transport bound with
  `Mail::set_transport` and the one behind `Mail::fake`. `Mail::queue` and
  `Mail::later` check it when they push. A refusal is an internal error, a
  500 with the detail in the log, where it was a 400 that echoed the
  address. Headers the message structure owns (`To`, `Cc`, `Bcc`, `From`,
  `Sender`, `Reply-To`, `Return-Path`, `Subject`, `Date`, `Message-ID`,
  `MIME-Version` and `Content-*`) are refused as caller headers. Postmark
  refuses a second tag, and SES refuses a tag or metadata it cannot carry,
  instead of dropping them. The address and header serializer is public as
  `suprnova::mail_wire` for transport authors.
- **The framework registers its own mail and notification jobs.** A worker
  dispatches `SendMailJob` and `SendNotificationJob` with no `register_job`
  line. Registering the same job type again is quiet; only a different type
  taking over a job name still warns.
- **A full Live instance ledger evicts instead of refusing mounts.** At
  `LIVE_LEDGER_MAX_INSTANCES`, a new mount or promotion removes the instance
  that expires soonest, preferring one with no claim in flight, and the
  evicted page's next action gets `refresh_required` and reloads fresh.
  Before, a full ledger refused every mount on the site until records
  expired, and anyone who could mount in a loop could keep everyone else
  out. `CapacityExceeded` now means only a record over a codec bound. A
  custom `InstanceRecordStore` implements two new methods,
  `soonest_expiring_instances` and `compare_and_remove`; the memory, SQL and
  Redis stores ship them.
- **Live form controls match the density of the suprnova.app forms.**
  Controls read at 14px through `--sn-density-control-font-size` (16px on a
  coarse pointer), fields are 40px tall, labels are 12px and sit 6px above
  their control, legends are 14px, and hints and errors are 12px. A textarea
  shows three rows and is at least two control heights tall.
  `--sn-density-field-gap` puts 12px between fields, checkboxes, switches
  and groups, and a group's options sit 8px apart. To pick it up in an
  application, run `live:add` again for `button`, `checkbox`, `combobox`,
  `datatable`, `date-picker`, `field`, `fieldset`, `input-otp`, `label`,
  `load-more`, `pagination`, `radio-group`, `switch`, `textarea` and
  `upload`.
- **Content negotiation treats `q=0` as a refusal.** `accepts`,
  `accepts_json`, `prefers`, `wants_json`, `expects_json` and
  `acceptable_content_types` leave out an `Accept` type weighted `q=0`, as
  RFC 9110 says, even beside `*/*`; the most specific matching range
  decides. Laravel lists such types as acceptable.
- **Vendor HTTP clients no longer follow redirects, and SQS overflow
  payloads move.** Pinecone and the HTTP mail drivers treat a 3xx as an
  error. SQS overflow payloads live under `sqs-payloads/<queue>-<digest>/`,
  so `SQS_OVERFLOW_FLUSH_ON_CLEAR` no longer deletes a same-named queue's
  payloads from another account, region or endpoint; payloads written before
  still read, but `clear` no longer sweeps them. Qdrant ids `"01"`, `"+1"`
  and non-canonical UUID spellings no longer map to the point of `"1"` or
  the canonical UUID, so items stored under such ids must be written again.
  A caller's version 5 UUID id is hashed like any other string, so it can
  never name a point a derived id holds; items stored under v5 UUID ids must
  be written again too. Resend tags go out as `tag_<i>` name and value
  pairs, and a tag Resend cannot carry is refused before sending.
  `DynNotification` gains `as_any`, with a default.
- **`build_docs` refuses chapters that would overwrite each other.** Two
  chapters with the same file name, or one named `catalog.md`, now fail with
  the new `ContentError::DuplicateChapterSlug` or
  `ContentError::ReservedChapterSlug`, naming the files, so an exhaustive
  `match` on `ContentError` needs the two arms. The same file listed twice
  is still allowed.
- **`IMAGE_MAX_ALLOC_BYTES` bounds the whole decode, and defaults to 1
  GiB.** It used to bound only the decoded RGBA size, so a decoder could
  allocate several times the limit while it worked. It now covers every
  buffer a decode and its source read hold, measured per format (the cost
  table is in `manual/images.md`), and the default rose from 256 MiB to 1
  GiB so a 48-megapixel photo in any 8-bit format still decodes. JPEGs
  decode through `zune-jpeg` (pinned at `0.5.16-rc2`, the first release that
  decodes every Huffman and arithmetic sampling correctly); lossless JPEGs
  still decode through `oxideav-mjpeg` and are refused by name above 67
  million samples.
- **Guard names, verification links and the default auth schema.** A guard
  name other than the default session or token guard may not contain `:` or
  be empty, because a non-default guard's principal is now `<guard>:<id>`,
  and a default-guard id that contains `:` is now the principal `:<id>` in
  Live gates, uploads, subscriptions and memberships, Pusher's `user_id` and
  the RenderCache key, so `admin:9` on the default guard is never guard
  `admin`'s user 9. Ids without `:` are unchanged. A token guard other than
  the default no longer copies its user into the default `Auth` view, so
  `Auth::has_user()` stays false for it. Email verification links issued
  before this change are refused and must be sent again. The default auth
  schema enforces one account per email with a unique index, so a migration
  over an `app_users` table that already holds duplicate emails stops with
  an error until they are merged. New, with defaults: `TokenGuard::named`,
  `UserProvider::verification_email`,
  `UserProvider::mark_email_verified_for` and
  `TwoFactorStore::withdraw_enrollment`.

### Fixed

- **Unsigned keys, relation min and max, and raw bindings on every engine.**
  `with_min` and `with_max` read 32- and 16-bit integer columns on Postgres,
  and dates, text and times on every database, without an error; `_min_of`
  and `_max_of` return `Some(None)` for a value that is not a number, and
  the new `<rel>_min_as::<T>()` and `<rel>_max_as::<T>()` read the value
  itself. `DB::table`, raw fragments and joined-table columns compare a
  `u64` above `i64::MAX` as the database does for the stored data, including
  a REAL held in an INTEGER column on SQLite, and `DB::table` writes store
  such a value exactly in numeric and text columns while integer columns,
  and NUMERIC columns on SQLite, refuse it. `attach`, `attach_with` (extras
  included), `detach` and `sync` bind pivot ids by their column's type: on
  Postgres and SQLite a `u64` above `i64::MAX` is refused, naming the
  column, before anything is sent; on MySQL `sync` no longer duplicates
  unsigned pivot ids, and `BelongsToMany` and `MorphToMany` `get()` load
  rows whose pivot column is unsigned, where they returned none. On
  Postgres, a raw fragment sent first with an integer and later with a value
  above `i64::MAX` no longer fails with "incorrect binary data format".
  Model `update_all` and `upsert` of such a value to a field that is neither
  an integer nor text follow the column, as `DB::table` writes do (#137).
- **Durations too long for a date are errors, not panics.** A workflow lease
  or retry backoff too long for a date is refused at boot:
  `WORKFLOW_LOCK_TIMEOUT_SECS` above 253402300799, or
  `WORKFLOW_RETRY_BACKOFF_SECS` times `WORKFLOW_MAX_ATTEMPTS` above it,
  stops the worker at start with an error naming the setting, and lease
  refreshes return an error for such a lease. `Queue::later` and its
  variants, a job's `delay()`, and requeues in the default, SQS and database
  drivers return an error naming the delay, where they panicked or, past a
  chrono duration's range, requeued with no delay at all.
- **A refused cookieless request stores no session.** `CsrfMiddleware` marks
  a new, untouched session for storage only when the response succeeds or
  redirects. An anonymous request that creates a session and is refused with
  401, or any other 4xx or 5xx, gets no `XSRF-TOKEN` and writes no session
  row, so it no longer turns into a 500 when the session store is
  unavailable; a session that was loaded or changed keeps its token. A
  cookieless JSON or `HEAD` bootstrap that succeeds still gets its token
  with its session. `SessionMiddleware` marks every session that
  `SessionStore::read` returns as loaded from the store, so a custom store
  that builds its sessions with `SessionData::new` no longer gets a write on
  each successful request through `CsrfMiddleware`.
- **Live uploads, private responses and tooling.** Finalized uploads free
  their pending slots when finalization commits, so a session no longer runs
  out of upload capacity until restart, and are reclaimed when they expire.
  A finalization that failed or stalled is reclaimed at expiry, and an app
  without a finalizer leaves uploads Ready instead of stuck in Finalizing.
  Cleanup deletes only temporary and uncommitted bytes; bytes finalization
  committed as output are never deleted. Every RenderCache response without
  shared-cache permission, public pages without `s-maxage` and zero-slot
  composites included, is `private, no-cache`. Making room for a file-store
  publication reads only the entries it evicts. A Live tooling timeout kills
  every process the helper started, and Ctrl+C still reaches the helper. A
  Live action with `validate = "arguments"` and a typed `#[validate(action =
  ...)]` hook compiles without a component-level `#[validate]` hook.
  Generated route helpers handle optional parameters (`{id?}`) as `route()`
  does, leaving an empty one out of the URL. Schema dump and load reach
  Postgres over a Unix socket named in the URL host
  (`postgres://%2Frun%2Fpostgresql/db`).
- **Scaffolded apps on MySQL 8.4 and Postgres, and dates past 2038.** The
  auth-flow token table's hash is `VARCHAR(64)`; MySQL 8.4 refused the
  UNIQUE key on the old `TEXT` column (error 1170), so a new app's migration
  stopped at the fourth step and the app could not boot. Run `migrate` again
  on an app that stopped there. The `--api` starter's `app_users` time
  columns are `timestamp with time zone` on Postgres and `DATETIME` on
  MySQL, which its `User` model and Magnetar read; an existing API app on
  Postgres converts them with the `ALTER TABLE` in the CLI chapter. The
  notifications and RenderCache ledger migrations create `DATETIME`, so
  writes keep working after 2038-01-19 on MySQL; tables created before keep
  `TIMESTAMP` and still work, and the new `NotificationTimestampsToDatetime`
  migration moves an existing MySQL or MariaDB `notifications` table to
  `DATETIME`, keeping its UTC times. A remember-me, auth-flow token or
  ceremony lifetime too large for a date is an error instead of a panic.
- **Generated routes and types, Inertia props and JSON:API.**
  `generate-types --routes` applies `group!` path and name prefixes, gives
  each repeated-handler alias its own helper, percent-encodes path values
  like `route()`, and uses serde's input keys in request interfaces; helpers
  for a second route of one handler get a new params interface name. An SSR
  exclusion glob such as `**/foo/*` matches where `**` spans a repeated
  literal. The redirect back for an empty Inertia response keeps the
  handler's cookies, security headers and error report. Replacing a lazy
  prop drops its `?include=` gate, a later dotted prop wins over an earlier
  lazy parent, and `App::inertia_shared("users.0.name")` reads into shared
  lists. A JSON-style `inertia_response!` prop that fails to serialize
  returns an error instead of panicking. JSON:API documents no longer repeat
  primary resources in `included`, an empty collection refuses unknown
  includes with 400, a requested include always returns an `included` array,
  and error pointers are escaped per RFC 6901. `i128` and `u128`
  route-parameter fields in Data DTOs extract instead of answering 422, and
  DTOs with route-parameter fields compile without a direct `url`
  dependency. Live route intents can target resource routes, and `route()`
  and `try_route()` fill a catch-all `{*rest}` by the name `rest`, keeping
  its slashes. Numeric `expect!` matchers fail on NaN and other unordered
  values. Schema dump and load accept every TLS parameter spelling the
  application's connection accepts and pass the Postgres password through
  `password=`. The `Idempotency::remember` example key includes the
  authenticated user. Live component names, views and action text that
  mention development crate names compile, action arguments named `target`
  or `request` no longer break generated code, and `#[session]` Live fields
  load from and persist to the visitor's session once the action's outcome
  is accepted (they need `SessionMiddleware`).
- **Workers, the console and process lifecycle.** Queue, schedule and
  workflow workers, the `queue:*` commands and console commands boot the
  `#[injectable]` and `#[service]` inventory, so a job or command that
  resolves an action no longer fails with `ServiceNotFound`. The console
  also boots the runtime drivers and `#[policy]` gates, warns on stderr and
  goes on when a driver cannot boot, and waits for queued listeners before
  it exits. Workers, the queue and maintenance commands and console commands
  cancel and drain the supervisors the bootstrap started before they exit,
  with the same 5-second grace as `serve`, and so does any command or
  console that fails after the bootstrap ran; `down`, `up` and
  `schedule:list` run the application's bootstrap hook, and the hook's docs
  name the migration commands that skip it. `schedule:work` stops on SIGTERM
  while an inline task runs, stopping a task still running after the
  30-second grace. A panicking `Terminable` hook no longer skips the hooks
  after it, and a graceful shutdown waits up to 5 seconds for hooks still
  running. `Context::get` and `Context::hidden_get` no longer deadlock when
  a custom `Deserialize` writes to the context. A `TestContainerGuard` or
  `TestQueryGuard` dropped on another thread clears only what it installed.
  Binding an `#[injectable]` by hand before boot no longer requires the
  dependencies only its generated constructor reads. `db:seed
  --class=<Name>` fails with not-found on an empty registry, and a poisoned
  registry fails instead of reporting nothing to run. A supervisor spawned
  during or after shutdown no longer starts outside the drain. A second
  `init_telemetry` while the first guard lives no longer takes over the
  global meter provider. `start_workflow!` accepts imported, re-exported,
  `crate::`, `self::` and `super::` paths, and `workflow:work` on a database
  other than Postgres exits with an error at startup instead of retrying
  forever.
- **Relations and soft deletes.** `destroy`, `delete_quietly`,
  `delete_or_fail` and trait-dispatched `delete` permanently deleted
  soft-delete rows; they now tombstone them, and `delete_or_fail` on an
  already trashed row is a 404. `with_count` and the `with_sum` family
  counted trashed rows and rows hidden by global scopes; they now cover
  exactly the rows `with` loads. `with([..])` and `with_count([..])` on one
  relation no longer panic, a count no longer makes `load_missing` skip the
  rows, and a failed or cancelled nested `load_missing` no longer erases
  relations already loaded. Relations declared with `lk = "..."` read and
  write by that column, and an `lk` naming no field is a compile error.
  Eager many-to-many honours `related_key`, a relation's `pivot_table`
  override is used when loading pivot context, and eager `HasManyThrough`
  skips rows reached through a trashed intermediate. Eager loads of a
  `with_tx(&tx)` or `on(name)` query run on that transaction or connection,
  `MassPrunable` deletes on the connection its dry run counted, and factory
  inserts of plain SeaORM rows join the surrounding `DB::transaction`.
  `with_min` and `with_max` of an integer column read on Postgres. `has`,
  `where_has` and `doesnt_have` work on models whose primary key is not
  `id`, and join a many-to-many on its declared `related_key`. Lazy
  `HasManyThrough` and `HasOneThrough` `get` and `count` apply the target
  model's global scopes, as eager loads do. A pivot model's own global
  scopes and soft-delete filter no longer drop attachments from many-to-many
  reads; as in Laravel, they apply when the pivot model is queried on its
  own. A soft `delete()` sets `updated_at` along with `deleted_at`, and
  `delete_or_fail` touches the owners named in `touches`, as `delete()`
  does. A `BelongsTo` declared without an owner key finds its owner by the
  owner model's primary key instead of `id`, in lazy and eager reads, counts
  and aggregates, `has` and owner touches. `has`, `where_has` and
  `doesnt_have` on a `MorphedByMany` relation work; they named a pivot
  column that does not exist. Every relation key default now comes from the
  models' primary keys, never a literal `id`: `HasManyThrough` and
  `HasOneThrough` without `second_local_key` join on the intermediate
  model's primary key, `MorphMany` and `MorphOne` report their parent key or
  the declared `lk`, and a `MorphTo` reports its targets' primary key,
  through the morph registry when the targets differ; `MorphTypeEntry` gains
  a `primary_key` field.
- **Magnetar hashing and sign-up races.** Magnetar password hashing runs on
  Tokio's blocking pool instead of stalling async workers. A magic-link or
  passkey sign-up that loses a race for a new email address answers as the
  existing account instead of failing.
- **RenderCache stays coherent under cancellation, races and flags.** A
  write that was cancelled at its generation advance, including a bulk
  write, `increment`, a soft delete, restore or force delete, could commit
  while cached pages stayed current; the write and its advance now share one
  transaction. An unrelated successful write no longer resumes serving pages
  whose invalidation failed: the missed invalidation is applied first, and
  an advance that lands clears only the failures recorded before it began,
  so a newer failure for the same tables keeps pages suspended until a later
  advance covers it. A process that wrote before installing RenderCache
  advances generations after the install. Pages rendered with a flag's
  compiled default refresh when the first rule for that flag is stored, and
  a page rendered during `set_flag` or `reload` no longer stays cached with
  the old answer. `DB::unprepared`, `DB::statement` and `statement_on` with
  a batch that begins with `SELECT` invalidate cached pages. Pages built
  from `EntityExt` or `QueryBuilder` reads, relation counts and aggregates,
  or through-relation loads refresh when those tables change, and lazy
  `HasManyThrough` `get`, `first` and `count` and `HasOneThrough` `get`
  refresh when an intermediate row changes. The payments webhook advances
  its mirror tables, and its receipt insert, retry error clear and failure
  record, in the transaction that writes them, so a request cancelled during
  COMMIT no longer leaves them committed but cached pages current. A write
  on a named connection that is dropped during its COMMIT suspends serving
  until a later advance repairs it. `RenderCache::advance_epoch` reaches the
  next request even with another request's authority read in flight. A
  rebuild that fails after the stale-on-error window closed returns its
  error instead of the expired entry, a node runs at most one background
  refresh per key and at most `RENDER_CACHE_MAX_BACKGROUND_REFRESHES` across
  keys (new, default 32 per CPU, 0 turns background refresh off; past it a
  stale hit serves the stored copy and starts nothing), a cancelled L1
  publish can no longer overwrite a newer entry, and L1 sweeps no longer
  scan the whole store. SQL Live record cleanup no longer deletes a fresh
  instance or reservation another node just created. Renewing an async
  subscription from an evicted position is refused, so the membership
  degrades instead of claiming continuity, and a degraded delivery lane
  replays what it missed from the subscription's log, or retires the
  transport when the log no longer holds it, instead of streaming on past
  the gap. A finalized direct-storage upload is retired through the
  application's direct upload provider when cleanup reclaims it. The Live
  tooling helper's timeout ends the call even when a process it started
  keeps its output open or the helper wrote a complete exchange and kept
  running.
- **Query builder, pagination and Eloquent.** Paginating, ordering and
  taking `first` of a union works on every engine, and `total` counts its
  rows; as in Laravel, ordering, limit and offset set before `union` apply
  to the first query and those set after it to the whole union. `count`,
  `sum`, `avg`, `min` and `max` work after `select(...)`, after an ordering,
  on a union and with `having`. `in_random_order` works on MySQL, and `skip`
  or `offset` without `limit` works on SQLite and MySQL. `chunk_by_id`,
  `lazy_by_id`, `cursor_paginate` and `Pagination::cursor` visit every row
  once whatever the query was ordered by, and apply an offset once. `chunk`,
  `chunk_map`, `each`, `chunk_by_id` and `lazy_by_id` honour the query's
  `limit` as a cap on the whole walk and its `offset` as a one-time skip, so
  `.limit(5).chunk_by_id(2, ..)` visits 5 rows instead of the whole table.
  `cursor_paginate` on a union pages the whole union. `count`, `sum` and
  `avg` return 0, and `min` and `max` return `None`, when an offset skips
  the aggregate's row or a grouped query has no rows, instead of failing
  with "aggregate query returned no row". `filter_json_contains` works on
  Postgres and MySQL with strings, objects and arrays. `create_or_first`
  inside a Postgres transaction returns the existing row, and a lost race
  creating a Live record no longer aborts the host's Postgres transaction.
  `Unique` and `Exists` inside `DB::transaction` see the transaction's own
  rows and no longer wait on its connection. `Collection::sort_by` and the
  by-value `Distinct` rule compare integers above 2^53 exactly. Index and
  foreign key names holding a backtick or double quote create and drop.
  `decrement(col, i64::MIN)` subtracts instead of panicking.
  `UniqueIdKind::Ulid.is_valid` rejects strings that overflow 128 bits.
  `QueryExecuted::to_raw_sql()` returns the SQL unchanged when a binding is
  missing or left over, and `QueryBuilder::count` and
  `Pagination::length_aware` report the `COUNT(*)` they ran to `DB::listen`
  and the query log. Inertia infinite scroll asks for the paginator's own
  page or cursor parameter. Concurrent `Schema::dump` calls to one path each
  write a whole file. `test_database!()` with no argument compiles and uses
  the crate's own `migrations::Migrator`.
- **Typed counts, union walks and decimal relation minimums.** Typed
  `QueryBuilder::count` keeps the whole count under a limit and returns 0
  past an offset, `exists` asks about the rows the limit and offset leave,
  and a `Pagination::length_aware` total counts every match, as Laravel
  does, and `DB::table(..).count()` keeps the limit and offset the same way.
  `QueryBuilder::offset(n).all()` and `first()` with no limit run on SQLite
  and MySQL instead of failing with a syntax error. `chunk_by_id`,
  `lazy_by_id`, `lazy` and `cursor` over a union visit each row once and
  finish; the cursor bounded only the first query, so the batches repeated
  forever. `<rel>_min_as::<Decimal>()` and `<rel>_max_as::<Decimal>()` read
  a `NUMERIC` or `DECIMAL` minimum or maximum exactly on Postgres and MySQL,
  and `::<String>()` reads its decimal text.
- **Overlapping drains of queued listeners wait for each other.** A
  second `EventFacade::drain_queued` running while another drain held a
  listener reported the dispatcher drained at once, so a console command
  could return, and a shutdown could finish, with a queued listener still
  running. It now waits for that listener, and counts it if its deadline
  passes.
- **Debounced jobs, queue events, log subscribers and process timeouts.**
  Overlapping debounced dispatches keep the one that armed last: each takes
  its place from an atomic counter in the cache, so a newer push is never
  dropped for an older `Queue::bulk`, and a stalled dispatch does not also
  run. When max wait runs out inside one `Queue::bulk`, the bulk's last job
  runs at once instead of being dropped as superseded. A debounce id ending
  in `:first_dispatched_at` no longer shares a cache key with another id's
  first-dispatch stamp, which failed that id's dispatches. `JobProcessed`
  fires whenever the job's pipeline returns without an error, as Laravel's
  worker fires it: after middleware deletes the job, then `JobAttempted`;
  after middleware releases it, before `JobReleased`; after a middleware
  failure without an error; and after a debounced dispatch is dropped as
  superseded, between `JobDebounced` and `JobAttempted`. The worker raises
  the rest of its lifecycle events in Laravel 13.27's order for every
  outcome too: `JobAttempted` after a retry and after a release by
  middleware; `JobExceptionOccurred` after `JobFailed` for an error or panic
  on the last attempt, for a job already out of attempts, and for
  `FailOnException`; `JobFailed` before `JobTimedOut`, with no
  `JobAttempted` after a timeout; and `JobProcessing` first for a job
  already out of attempts. Building a log subscriber with
  `logging::build_subscriber` changes nothing until it is used: each
  subscriber writes file lines in its own format, and building no longer
  resets the default channel, so a caller that relied on that calls
  `check_channels`. A process timeout's kill can no longer reach a process
  or group id that the owner reaped in the meantime.
- **Docs reading order, memory fanout streams and the image budget docs.** A
  docs chapter listed twice in the table of contents keeps one place in the
  previous and next chain, its first listing, and every catalog entry for it
  matches its JSON file. A `memory://` fanout stream is freed when its last
  hub drops instead of staying registered until the process exits. The
  `ImageConfig` docs give the real 1 GiB default for
  `IMAGE_MAX_ALLOC_BYTES`.
- **Rate-limit identities, RBAC races, email verification and second
  factors.** A request that names more than one identity in its query or
  body is also refused by, and counted against, each identity's own bucket.
  Creating a role or permission and granting one succeed when two requests
  make the same one at once, on every engine. Email verification stamps only
  the address the link was mailed to, even if the address changes while
  `verify` runs; a custom provider closes the remaining window by overriding
  `UserProvider::mark_email_verified_for`, as its docs explain.
  `session::destroy_all_for_user` destroys only the sessions of the default
  guard's user, so a password reset for web user 7 no longer signs out admin
  7, and the new `destroy_all_for_guard_user` does the same for another
  guard; every Live membership issued under a destroyed session now ends,
  whichever guard's user held it. On Postgres, a user id above `i64::MAX`
  binds by the column type of the table the lookup actually reads. A
  framework TOTP enrollment and a Magnetar enrollment that race each other
  leave the account with one second factor; in a tight race both answer 409
  and the user enrolls again.
- **Sessions and remember-me tokens restore on MySQL and MariaDB.** A
  scaffolded application's session, remember-me and auth-flow token time
  columns are `TIMESTAMP` there, and the framework read them as a type the
  MySQL driver decodes only from `DATETIME`. Every session read failed: a
  form POST answered 419 and the next page 500, the remember-me cookie never
  signed anyone back in, and verification and reset links could not be used.
  The notification inbox and the ceremony store failed the same way, and on
  Postgres each failed on a `timestamptz` column. They now read `DATETIME`,
  `TIMESTAMP`, `timestamp`, `timestamptz` and SQLite text, and existing
  tables need no migration. A notification whose `read_at` does not decode
  is an error instead of unread. On MySQL, an expiry past 2038-01-19
  03:14:07 UTC is stored as that moment.
- **A new application registers and signs in on every database.** The
  `users` table and `User` model that `suprnova new` writes disagreed on the
  time column type, so registering failed on MySQL 8.4, MariaDB and
  Postgres. The migration now uses `.date_time()` and the model names
  `AsNaiveDateTime`. An existing application gives its `User` the casts for
  its columns: the native casts on MySQL and MariaDB, the naive ones on
  Postgres. See Authentication, "The scaffolded User model".
- **Two-factor flows on every engine.** A framework login completed with
  `TwoFactor::complete_challenge` stays signed in under the Magnetar engine.
  The two-factor credentials table and the attempt-counter migration create
  on MySQL and MariaDB. Concurrent second-factor admissions no longer
  deadlock across users on MySQL. On Postgres, a correct Magnetar
  second-factor code, every ceremony state change, passkey registration and
  removal, and account unlinking answered 500; they work. A committed
  two-factor confirmation is reported as confirmed even when its attempt
  record cannot settle. A password reset keeps an encrypted column that
  changed while it ran, and stores the new hash verbatim whatever the
  model's mutators.
- **Cache, maintenance mode and read-through disks.**
  `Cache::remember_forever` and `Cache::sear` no longer expire after
  `CACHE_DEFAULT_TTL`, and `down` with `MAINTENANCE_DRIVER=cache` no longer
  ends by itself after it. On Redis, `Cache::flush` matches `REDIS_PREFIX`
  literally, so a prefix holding `*`, `?`, `[` or `\` no longer deletes
  other applications' keys or misses its own, and a value extended with
  `Cache::touch` is still removed by `Cache::flush_tags`. Tag indexes no
  longer grow without bound for tags written often and rarely flushed.
  Concurrent `down` runs with the file driver no longer publish a
  half-written down file. The production guard for `on_one_server()` checks
  the bound cache store instead of `CACHE_DRIVER`; a custom shared
  `CacheStore` overrides the new `locks_are_shared` to return `true`. The
  cached feature-flag evaluator sees an admin change made during a
  concurrent miss and holds at most 4096 entries. Read-through promotions
  stream into the primary instead of holding the object in memory,
  unpromoted reads fetch only their range, and a delete or move during a
  promotion is not undone, on the same node or another one: a promotion asks
  the fallback again just before it publishes and after, a cancelled read
  still finishes that check, and a withdrawal deletes only the exact version
  the promotion wrote, never a writer's newer object. An equal length no
  longer counts as proof that the fallback object is unchanged: a fallback
  without an ETag, version or modification time, such as the in-memory disk
  behind `Storage::fake()`, is checked by content, so a same-size overwrite
  is never promoted as the old bytes. On a primary without versioned deletes
  (local, memory, and unversioned S3, Azure Blob and GCS) the promotion
  keeps its copy and logs a warning instead, so a delete on another node
  that lands between the last check and the publish can leave that copy
  behind. Versioned and conditional reads reach the fallback, and a refused
  move keeps the fallback copy. Ranged reads stop at the requested range: a
  server that ignores `Range` can no longer make a small read buffer the
  whole object, and S3, Azure Blob and GCS refuse a response that is not the
  requested range before reading its body, open-ended ranges included.
- **Queues, events and processes.** Cancelling `Transaction::commit()` while
  its COMMIT was in flight could drop its `after_commit` callbacks and
  `push_after_commit_with_tx` jobs although the rows committed; they now
  always run. A queued listener that dispatches another queued event no
  longer hangs queued event dispatch, `drain_queued` waits for and counts
  listeners admitted while it drains, and `EventDispatcher::defer` buffers
  only its own dispatcher's events. A debounced dispatch claims its window
  only after its envelope is queued, so a failed or cancelled dispatch can
  no longer get queued work dropped as superseded, and `max_debounce_wait`
  longer than the debounce token's lifetime forces a run again. Batches on
  the `sync` driver finish and fire their callbacks, a batch whose dispatch
  failed part way fires `catch` and `finally` once its queued jobs settle,
  and two concurrent first batch dispatches no longer lose one batch's
  tracking. `JobAttempted` fires for jobs that fail or time out terminally.
  A cache error while `ThrottlesExceptions` clears its counter no longer
  fails a completed job, and one while it counts a failure no longer
  replaces the job's own error or turns a backoff release into a failed
  attempt. A cancelled memory-queue `pop`, delayed `nack` or `release` keeps
  the job. `FailoverQueueDriver` counts a driver registered under two labels
  once. An after-commit `push_unique` whose job fails to serialize releases
  its lease. A started process whose child left its group can no longer have
  its timeout, `stop()` or drop signal an unrelated process group.
- **A Fluent message named `NUMBER` or `DATETIME` keeps the function
  callable.** Such a message broke every `NUMBER(...)` or `DATETIME(...)`
  call in its catalog. The message keeps its key and the functions still
  format.
- **Presence channels and WebSocket upgrades.** A presence channel whose
  last member left stayed in memory, so parameterized presence channels grew
  with churn; empty channels are now removed. A connection aborted at
  shutdown or cancelled during a re-subscribe left its presence member
  visible and its forwarder tasks running; cleanup, `presence.left`
  included, now runs on every exit. Headers middleware adds to a successful
  WebSocket upgrade, such as a session `Set-Cookie`, now reach the client on
  the 101, and terminable middleware runs for upgrade responses with status
  101 or the refusing status. WebSocket route parameters are percent-decoded
  like HTTP ones, subprotocol negotiation echoes the client's own spelling
  as RFC 6455 requires, and `sse::last_event_id` returns Unicode event ids
  instead of `None`.
- **Each named middleware runs once per route.** A middleware group included
  by two sibling groups, an alias listed twice, or a middleware named both
  through a group and on the route itself ran twice per request, so a
  throttle there counted each request twice. A route now runs each named
  middleware once, identified by its alias and parsed arguments, at its
  first occurrence, as Laravel's `uniqueMiddleware` does. Middleware added
  by type with `.middleware(M)` is never dropped.
- **Gates, OAuth starts, CSRF bootstraps and registrations.** A gate
  callback that calls `Gate::define` no longer deadlocks the request. An
  OAuth start that is the browser's first request (JSON or POST) sets the
  session cookie, so the callback binds instead of answering 400. A
  cookieless JSON or HEAD request that receives `XSRF-TOKEN` also receives
  its session, so the next POST no longer gets 419. Two registrations racing
  for one email create one account.
- **Images decode correctly at the sizes the framework allows.** JPEGs above
  about 22 megapixels decoded on no driver; they now decode up to the
  budget. JPEG colours were off by about 6 levels, arithmetic-coded,
  odd-sized 4:2:0 and 4:2:2, 4:4:0 and 4:1:1 JPEGs decoded wrong or not at
  all, and small progressive JPEGs could fail. GIFs from ImageMagick and
  Pillow decode, and the GIFs the default driver writes open in other
  software. The `magick` driver processes and sizes only the first frame of
  an animation, as the default driver does, and reports a GIF's logical
  screen as its size.
- **Localization.** `Accept-Language` negotiation honours q-values:
  `en;q=0.1, fr` picks `fr`, and a language sent with `q=0` is never chosen.
  `DATETIME()` formats in the catalog's own locale. A catalog edit saved
  during a reload is picked up by the next one. `Lang::has` is false for a
  message that has only attributes, matching `Lang::get`. A Fluent term and
  a message with the same name both resolve on the server, as in the
  browser.
- **Logging.** A custom driver's failed write or flush, and a file channel
  that cannot flush (a full disk), are reported once on stderr instead of
  dropping lines silently. `LogChannel::stack([...]).level(...)` filters
  every channel the stack lists. A refused second `init_subscriber` or
  `init_telemetry` no longer changes the live file format or the default
  channel. `Log::forget_channel` after rotation reopens the file in every
  stack that lists the channel. A default stack with several stdout channels
  writes an event when any of them keeps its level. Nested spans that share
  a field name log the inner value in the message and the context.
- **Markdown heading ids are unique, and process output keeps its
  characters.** A heading titled like a numbered duplicate (`Overview 2`) no
  longer shares an anchor with a repeated `Overview`. Streamed process
  output no longer drops a character split across reads after an invalid
  byte, and `wait_until` sees a final incomplete character.
- **Payments, mail, notifications and queues.** `PhoneNumber` and
  `CountryCode` validate when deserialized, where invalid values were
  accepted and `digits()` could panic. `MailFake::assert_not_outgoing` fails
  when the mailable was sent, not only queued. The `file` mail driver never
  overwrites a preview written in the same millisecond. Tagged Resend mail
  is accepted by Resend. Notification mail renders from the notification
  itself, so `data()` no longer has to hold every field `to_mail` reads. An
  SQS overflow job whose first send went unanswered keeps its payload when
  the retries are refused, and when SQS took both an unanswered send and its
  retry, each message now carries its own payload copy, so acknowledging one
  no longer leaves the other unreadable. The Redis queue and the broadcast
  fanout work with `redis://user:password@...` and `rediss://` URLs, taking
  credentials, database and TLS from the URL.
- **Middleware, sessions, uploads and test helpers.** A middleware group
  reused by two sibling groups no longer fails with `CycleDetected`. A
  `RateLimiter` counter that expired in the middle of a hit gets its expiry
  back, where it could refuse every later request until cleared. Flash keys
  containing `_flash.new.` or `_flash.old.` survive the next request, and
  `SessionData::decrement(key, i64::MIN)` saturates instead of panicking. A
  form body sent as `Application/X-WWW-Form-Urlencoded` (any case) is read
  by `Request::input`, CSRF, Pusher channel auth and identity rate limits.
  `set_global_upload_spill_threshold(usize::MAX)`, the documented way to
  keep uploads in memory, no longer panics. The Inertia error page compares
  `Accept` qvalues to three decimals. A redirect on a route without a
  session keeps `App::flash` values for the current response.
  `TestResponse::assert_cookie` matches only cookie names, not attributes
  such as `Path` or `HttpOnly`.
- **A Live page with several islands on SSE keeps its updates.** When an
  island's first event arrived before its subscribe answer, the browser
  treated it as traffic for an unknown subscription, retired the shared
  stream and showed every island on the page as "Updates degraded". Such an
  event is now held, counted against `LIVE_ASYNC_MAX_QUEUED_EVENTS`, and
  applied once that exact answer arrives, or dropped if the subscribe is
  refused; the same holds for the replacement subscribe that follows a
  failed island. A WebSocket transport still fails closed, as before. A
  document whose held and queued events pass the limit now reports the
  breach with the limit's key and reconnects, instead of degrading every
  island.
- **Payment webhooks, feature flags and RBAC work on Postgres, MySQL and
  MariaDB.** Their models used a text cast for native timestamp columns, so
  every payment webhook answered 500, `set_flag` and the feature admin
  failed, and `Role` and `Permission` could not read a row the RBAC helpers
  wrote. They now read and write the native columns; text written on SQLite
  still reads back.
- **Job batches settle on Postgres.** The documented `job_batches` schema
  declares `INTEGER` columns, which Postgres stores as 32-bit, and the
  repository read them as 64-bit, so every settlement failed: the job ran
  again after each visibility timeout and the batch callbacks never fired.
  The repository reads either width, and the documented epoch columns are
  now `BIGINT`; tables created from the earlier schema keep working.
- **The MariaDB vector store works against a real server.** `similar` looked
  for the vector index in a form MariaDB never prints, so every call failed,
  and the table `ensure_table_sql` emits could not be created because its
  key was too long for a vector index. The id column is now
  `VARBINARY(254)`, which also compares ids byte for byte as the other
  drivers do.
- **Native JSON columns have their own cast.** The structured casts bind and
  read text, which Postgres refuses for `json` and `jsonb` and MySQL for
  `JSON`, although their documentation said those columns worked. The new
  `AsNativeJson<T>` and `AsOptionalNativeJson<T>` store any serde type as
  JSON. The `AsBool` documentation now names a `BIGINT` column and sends a
  native boolean column to a plain `bool` field.
- **SMTP mail goes out from the return path.** A return path reached SMTP
  only as a header, so bounces still went to the author; the envelope sender
  is now the return path.
- **Queued mail and queued notifications send.** Nothing registered their
  jobs with the worker and the manuals never said to, so every one failed as
  an unknown job and dead-lettered, and with the sync driver the push itself
  failed.
- **Queued and notification mail fire `MessageSending` and `MessageSent`.**
  Only a direct send fired them, so switching to `queue` or sending through
  a notification cut off audit and metrics listeners.
- **A Live primary button looks like the primary action.** A `type="button"`
  button with the default primary variant rendered as a secondary control,
  and so did dialog, sheet and drawer triggers.
- **`sum` and `avg` of an integer column read on Postgres and MySQL.**
  Postgres answers `numeric` and MySQL `DECIMAL` for them, which `sum` and
  `avg` could not read, so they failed there while passing on SQLite. They
  now read either: an integer sum exactly, refusing a fractional or
  out-of-range sum with an error that quotes it, and `sum::<f64>` of an
  integer column now reads on SQLite too. `with_sum` and `with_avg` stored
  `0.0` on Postgres and MySQL; they now hold the value, and a value that is
  not numeric is an error instead of a silent zero.
- **Facebook sign-in receives the email.** The Facebook provider requested a
  bare `/me`, for which the Graph API returns only `id` and `name`; it now
  names `id`, `name`, `email` and `picture`. X requests `profile_image_url`
  among its user fields (#140).
- **`live:check` finds unescaped output wherever a template writes it.** It
  read `|safe` from an expression's text and skipped `{% let %}`, so `{% let
  y = x|safe %}{{ y }}`, `x|safe|lower` and `escape("none")` passed. It now
  reads the parsed template and follows a raw value through `let` and `set`,
  macro arguments, macros called as expressions, caller content, inherited
  blocks and `super()`, loops, `if let`, let chains and `match`, to the
  place it is written. A filter outside Askama's builtins and the
  framework's, a Rust macro in an expression, and a dynamic value in an
  unquoted attribute, an `on*` attribute or `script` or `style` text are
  reported as unproved, so a view that passed before can now need a change.
- **`live:check` handles views with many conditionals.** It counted every
  combination of `if` blocks, so eight independent ones exceeded its limit;
  each conditional's branches are now checked once. Its limits are sized for
  real templates (4 MiB of source, 262,144 nodes) and configurable.
- **`live:check` reports the real column.** Directive and markup diagnostics
  reported column 1; they now point at the attribute or tag, in the template
  that wrote it.
- **An action can dispatch more than 128 events.** An action's outcome
  refused more than 128 flash messages, events or effects; it now takes as
  many as `LIVE_MAX_RESPONSE_ITEMS` allows, 65,536 by default.
- **Reordering a long keyed list morphs in linear time.** The morph looked
  up each keyed element in the list of moved elements, so reordering every
  row took time quadratic in the row count; 10,000 rows took about 67 ms and
  now take under 20 ms.

### Security

- **Input-only relationships stay out of JSON:API output.** A relationship
  marked `#[data(input_only, allow_include)]` was linked and includable in
  responses; it is now never sent.
- **The environment is written only where that is sound.** `Config::init`
  and `config::load_dotenv` refuse to write the process environment inside a
  Tokio runtime or after `#[suprnova::main]` loaded it, where another thread
  could read it mid-write. A failed load restores the real system values and
  registers no config.
- **Route bindings and pivot extras respect what models declare.**
  `RouteParam<Model>` ignored global scopes on models without
  `soft_deletes`, so a guessed id of another tenant's row bound to the
  handler; the binding now applies every global scope, and a hidden row is a
  404. `attach_with` wrote pivot extras past the pivot model's casts, so an
  `AsEncrypted` column was stored as plaintext and an `AsHashed` one
  unhashed; extras now go through the pivot's casts and mutators, and an
  extra that does not decode into its field is a validation error.
- **RenderCache never stores or reuses a personalized page as shared.** Work
  a handler joined beside an identity-bound island mount (`tokio::join!`)
  had its principal, session and table reads dropped from the stitched
  shell's report, so a personalized shell could be stored as public; those
  reads now count. `PrivateCached` responses send `Cache-Control: private,
  no-cache` instead of `private, max-age`, which let a browser show the
  previous account's page to the next account on the same browser. Oversized
  Redis hint payloads are dropped before they are copied or queued.
- **Redis credentials stay out of the boot log.** When Redis was unreachable
  at boot, the cache error held the whole `REDIS_URL`, password included,
  and `CacheConfig` and `CacheConfigBuilder` printed it when
  debug-formatted. The error now names only the host and port or socket
  path, and the configurations print the URL as `redis://<redacted>`.
- **Second-factor codes are rate limited and single use.**
  `TwoFactor::verify` and `consume_recovery_code` ignored the account
  lockout, so a caller with the password could guess TOTP codes without
  limit; both now refuse while the second factor is locked, and every
  framework login is refused before it spends a code. A confirmation code
  and a TOTP code straddling a timestep are accepted once, and `confirm`
  confirms only the secret whose code was checked, in the framework and in
  Magnetar. Second-factor failures are counted in a table that no password
  identity can reach, so a decoy account named after the second-factor key
  can neither clear nor lock it. A password reset during the password check
  cancels the sign-in or challenge. HTTP Basic once, `Auth::once` and
  `once_using_id` refuse an account with a Magnetar second factor, and
  Magnetar's password, magic link, passkey and OAuth sign-ins refuse an
  account with framework TOTP. A remembered framework login is refused
  before it issues a credential, and account flows write only the
  verified-at or password column.
- **Local disks stay inside their root.** On Unix, a directory inside a
  local disk root swapped for a symlink during an operation could redirect a
  read, write, copy, rename, delete, listing or publish outside the root.
  Every path is now resolved one component at a time without following
  symlinks, and each operation runs relative to the directory it resolved.
- **Cached feature flags stay per identity.** Two identities whose user and
  team strings joined to the same text could share a cached flag decision.
  The cache key now keeps each part separate.
- **Fanout URL errors no longer print credentials.** A broadcasting fanout
  URL that failed to parse was copied into the error message, password
  included. The error now names the problem without the URL.
- **A JSON login is rate limited by its address.** `identity_key` and
  `names_identity` ignored JSON bodies, so a JSON login was keyed on the
  caller's IP and a `?email=` decoy opened a fresh per-address bucket on
  each request. A top-level string field of a JSON object body now names the
  identity under the same query-versus-body rule as a form field.
- **An SVG allowlist accepts only SVG.** A `MimeType` allowlist naming
  `image/svg+xml` accepted any non-markup text declared as SVG, script
  included, and refused real SVG files. A part now passes only when its root
  element is `<svg>`; anything else declared as SVG fails as the wrong type.
- **A route uses the guard that authenticated it.** Behind a guard other
  than the default, the email-verified gate, the role and permission
  middleware, the Live principal and render-cache identity reads all used
  the default guard's user, so a verified or privileged default-guard user
  let another guard's user through, and a page built for one guard could be
  served from cache to a visitor without that sign-in. A second token guard
  over another provider answered with the first guard's user. Each now reads
  the user of the route's own guard through that guard's provider. Live
  gated actions, uploads and subscriptions, `EmailVerification::verify` and
  the Pusher user and presence endpoints do the same: behind
  `AuthMiddleware::for_guard(name)` they act for that guard's user, as
  `<guard>:<id>` (default-guard principals are unchanged), a named guard's
  logout ends that guard's Live memberships, and a stream with a
  `:principal` topic is refused behind a non-default guard.
- **Encoded cookie names cannot stand in for prefixed cookies.** A cookie
  named `%5F%5FHost-suprnova_session` resumed the `__Host-` session; a
  prefix that appears only after decoding is now dropped.
- **A verification link verifies only the address it was sent to.** Changing
  the account's email no longer lets an old link verify the new address.
- **Password reset checks the token before hashing.** A dead or made-up
  token made the server compute an Argon2id hash first, in the framework's
  reset flow and in Magnetar's `PasswordManagementService`.
- **A session that loses its Magnetar authority ends its Live memberships**
  on this node, so it stops receiving events.
- **An image cannot allocate past its decode budget.** A crafted PNG
  inflated past `IMAGE_MAX_ALLOC_BYTES`, a lossless WebP's prefix-code
  tables were unbounded, a JPEG could be measured at one frame header and
  decoded at another, and path and disk sources were read into memory before
  the size check. Each is now counted against the budget before the memory
  is taken.
- **A JPEG's Extended XMP cannot hold a core.** A JPEG whose Extended XMP
  segments would make the decoder's reassembly read more than
  `IMAGE_MAX_ALLOC_BYTES` is refused before decoding; 100,000 stalled
  segments used to hold a core for minutes.
- **The mock payment provider refuses unsigned webhooks outside
  development.** It accepted them when the application registered a
  production or staging `AppConfig` in code with `APP_ENV` unset; it now
  requires both the configured environment and `APP_ENV` to be local,
  development or testing.
- **Queued notification events carry only `data()`.** The queued
  `NotificationSending`, `NotificationSent` and `NotificationFailed` events
  carried the whole serialized notification, including fields kept out of
  `data()` such as reset tokens.
- **Vendor API keys stay with their vendor.** Pinecone and the HTTP mail
  drivers followed redirects, forwarding `Api-Key` and
  `x-postmark-server-token` to another origin. Web push transport errors no
  longer carry the subscription endpoint URL into logs and
  `NotificationFailed`.
- **CORS patterns anchor every alternative.** `allow_origin_patterns`
  anchored only the first and last alternative of a pattern such as `a|b`,
  so `https://app.example.evil.test` matched `https://app\.example|...` and
  got a credentialed allow. Every alternative must now match the whole
  origin.
- **Rate limits cannot be sidestepped.** On the Redis limiter, a
  shorter-window quota sharing a key with a longer one deleted the longer
  quota's history; history now lasts for the longest window used on the key,
  as the memory driver already did. An identity-keyed limit read the query
  string or the body, so `?email=decoy` or a blank `?email=` reached a body
  address under a fresh quota; both are now read, and a request that names
  two different addresses shares one `{prefix}:{field}-ambiguous` bucket.
- **`MimeType` sniffs before it trusts the header.** Script text, or markup
  hidden after 16 KiB of whitespace, passed an image allowlist on a spoofed
  `Content-Type`. The header now counts only for types without magic bytes,
  such as `text/csv`.
- **An Inertia validation redirect stays on the host.** A same-host
  `Referer` such as `https://app.test//evil.test/x` sent the redirect to
  another host; it now falls back to the previous URL.
- **Signed URLs sign the order of a repeated parameter.** Swapping the
  values of a repeated key (`?mode=a&mode=b` to `?mode=b&mode=a`) kept the
  signature valid while changing what the handler read. URLs minted before
  still verify.
- **Mail headers and recipients cannot be injected.** Postmark and Mailgun
  received recipient lists joined from unquoted display names, so a name
  such as `attacker@example.com, Victim` added a recipient, and SMTP and the
  file transport wrote header names carrying CR, LF or NUL verbatim. Every
  transport now builds addresses and headers through one validating
  serializer: an address is exactly one RFC 5322 address with its display
  name quoted when needed, a header name follows the RFC 5322 grammar and is
  at most 76 bytes, and a header value, the subject included, refuses
  control characters other than tab.

## 3.1.0 - 2026-10-03

### Added

- **Heap profiling.** With the framework's `heap-profiling` feature an
  application profiles its heap with dhat: the framework installs dhat's
  allocator, `#[suprnova::main]` starts the profiler, and a command that
  finishes or a server that shuts down gracefully writes `dhat-heap.json`,
  or the file `SUPRNOVA_HEAP_PROFILE` names, for DHAT's viewer, and prints
  the bytes allocated, the peak and the heap left at the end. Without the
  feature no dhat code is compiled. The workspace and new applications
  have a `profiling` Cargo profile, the release profile with debug
  symbols, and new applications a `heap-profiling` feature that turns on
  the framework's.
- **The in-memory cache sweeps its expired entries.** The cache the
  framework binds removes every entry whose time is up every
  `CACHE_SWEEP_INTERVAL` seconds (60 unless set; 0 turns it off), so keys
  written once and never read again no longer stay for the life of the
  process. `InMemoryCache::with_periodic_sweep` builds such a cache, and
  `CacheConfig::sweep_interval` sets the interval in code.
- **Schema dumps.** `suprnova schema:dump` writes the database's schema
  and its migration ledger to `database/schema/<engine>-schema.sql`, with
  `pg_dump`, `mysqldump` or `mariadb-dump`, or straight from SQLite.
  `migrate`, `migrate:fresh`, `serve` and `TestDatabase::fresh` load it
  into a database that has run no migration, then run only the newer
  migrations; `--schema-path` names another file. `--prune` deletes the
  migrations the dump records and keeps each name as a
  `PrunedMigration`, which fails with an error if a database ever needs
  to run it.
- **Strings and numbers.** `Str::slug`, `Str::mask`, `Str::limit`,
  `Str::limit_words` and `Str::excerpt` work in characters, never bytes.
  `Str::plural` and `Str::singular` follow the language of the current
  locale with doctrine/inflector's rules for English, French, Norwegian
  Bokmål, Portuguese, Spanish and Turkish, English for any other, and keep
  the word's case. `Lang::percentage` writes a percentage as the locale
  does, and `Lang::abbreviate` shortens a number to `1.23M` with the
  locale's digits.
- **A Redis facade.** `Redis::connection("default")` reaches `REDIS_URL`,
  and `Redis::define` names other connections in the bootstrap, or
  `Redis::define_client` with a client built elsewhere. A connection opens
  on its first command and opens again after the server drops it;
  `Redis::purge` and `Redis::connections` manage them. The common commands
  are typed methods (`get`, `set`, `incr`, `hgetall`, `lrange`, `zadd`,
  `scan` and the rest), `command` runs any other and returns a `RedisValue`,
  refusing, as pipelines and transactions do, those that would change the
  shared connection (`SUBSCRIBE`, `MULTI`, `SELECT`, `CLIENT REPLY` and the
  like), and `client()` gives the `redis` crate's connection, now
  re-exported as `suprnova::redis`. Reads are sent again after a lost
  connection, as `REDIS_COMMAND_RETRIES` says; writes never are. A
  subscription the server closes subscribes again. `rediss://` URLs connect
  over TLS, for the facade and for the cache, queue and rate limiter URLs;
  the framework installs rustls's `ring` provider unless the application
  installed one. `pipeline` sends its commands before reading a reply and
  `transaction` wraps them in `MULTI` and `EXEC`. `subscribe`, `psubscribe`
  and the blocking commands (`blpop`, `brpop`, `blmove`, `brpoplpush`,
  `bzpopmin`, `bzpopmax`) each run on a connection of their own. With
  `Redis::enable_events`, `Redis::listen` and `Redis::listen_for_failures`
  hear every command outside a pipeline or a transaction.
- **Log channels.** `LOG_CHANNEL` names the channel `tracing`'s events go
  to, still `stdout` unless set: `stderr` (or `errorlog`), `single`
  (`storage/logs/suprnova.log`), `daily` (a file a day, keeping
  `LOG_DAILY_DAYS`, 14), `monthly` (keeping 3), `syslog` (the local socket,
  `LOG_SYSLOG_FACILITY`), `null`, and `stack` (the channels `LOG_STACK`
  lists). `Log::define` adds a channel in the bootstrap and `Log::extend` a
  driver, through the `LogSink` trait. `Log::channel`, `Log::stack` and
  `Log::build` return a logger with Laravel's eight levels and a JSON
  context whose values fill `{key}` placeholders; a broken channel in a
  stack stops none of the others. File channels flush at once for errors,
  within a second otherwise, and on `Log::flush` and shutdown.
  `MAIL_LOG_CHANNEL` routes the `log` mail transport. A channel that does
  not exist fails boot. `logging::build_subscriber` builds the subscriber
  the server installs, for an application or a test that installs its own.
- **A Process facade.** `Process::command(["git", "status"])` runs a
  program with its arguments, each passed as it is through no shell, and
  `Process::shell("npm ci && npm run build")` runs a command line through
  the system shell, as Laravel runs a string command. `run` returns the exit
  code and the captured output; a nonzero exit is a failed result, and
  `throw` makes it an error. `path`, `env`, `input`, `quietly`, `tty`, an
  output callback, a timeout (60 seconds unless set) and an idle timeout
  are options. A timeout, an idle timeout, `stop`, or dropping a started
  process or the future of `run` kills the program with every process it
  started: its process group on Unix, its tree for a `tty` process and on
  Windows. A started process's timeouts hold whether or not anything waits
  on it. Results keep the raw bytes as well as the text. `start` returns the program running; `Process::pool()` runs
  processes side by side with an optional concurrency limit, and
  `Process::pipe()` feeds each output to the next input. `Process::fake()`
  stops every process in a test, answers by pattern, `describe` and
  sequence, and records each run for the assertions.
- **An SQS queue driver.** `QUEUE_DRIVER=sqs` queues jobs on Amazon SQS
  standard queues, configured by Laravel's variables: `SQS_PREFIX`,
  `SQS_QUEUE` and `SQS_SUFFIX` build the queue URL, `AWS_DEFAULT_REGION`
  (or `AWS_REGION`) names the region, and `AWS_ACCESS_KEY_ID` and
  `AWS_SECRET_ACCESS_KEY` sign the requests, or the default credential
  chain of AWS when they are not set. `SQS_ENDPOINT` points it at
  LocalStack or ElasticMQ, and `QUEUE_CONNECTIONS` and failover accept
  `sqs`. A job goes to the queue it names, and a worker receives from the
  queues `--queue` lists, or from `SQS_QUEUE`. A `nack` counts an attempt
  and a release does not, as on the other drivers, and a delay longer than
  the 15 minutes SQS allows still holds. With `SQS_OVERFLOW_ENABLED=true`, a
  job of 1 MiB or more is stored on a disk and SQS carries a pointer to it.
  The boot fails with no region, with a queue name and no `SQS_PREFIX`, and
  for a FIFO queue. A receive waits up to `SQS_WAIT_TIME_SECONDS` (default
  1) for a message, a throttled or failed request is tried up to three times,
  and `SqsConfig` with `SqsQueueDriver::new` builds a driver in code for a
  second connection. `SqsQueueDriver::call` sends any other SQS action. The
  driver is behind the `queue-sqs` feature, on by default.
- **A default disk.** `Storage::default_disk()` returns the disk
  `Storage::set_default_disk` names in code, or else `FILESYSTEM_DISK`.
  When the named disk is not registered once the bootstrap has run,
  `filesystem::bootstrap_from_env` fails and the server does not boot.
  With nothing named there is no default, and `default_disk()` returns an
  error that names `FILESYSTEM_DISK`. Calls that name their disk are
  unchanged. **What to check when you upgrade:** `FILESYSTEM_DISK` was not
  read before, so an application that carries `FILESYSTEM_DISK=local` from a
  Laravel `.env` now refuses to boot unless it registers a disk named
  `local`: register it, or remove the variable. An application that calls
  `filesystem::bootstrap_from_env` in its own bootstrap calls it after it
  registers its disks and sets the default.
- **A failed request's error report reaches `TestResponse`.** A
  response the framework builds from an error carries an `ErrorReport`
  in its in-process extensions: the error and each of its sources, or,
  for a panic the panic boundary caught, the panic message and the
  location it was raised at. That covers a `FrameworkError` a handler or
  middleware returns, a panic on an HTTP route or in a WebSocket
  upgrade's middleware, the 5xx the framework's session, session lock,
  throttle, rate limit, login throttle, timeout, and RenderCache
  middleware answer a failure with, and the 5xx of the payment webhook
  route and of the Live endpoints when the endpoint holds the error. The report never reaches a header or the body,
  so what a client receives is unchanged; with debug on, a 5xx body
  still carries `debug_message` as before. The new
  `TestResponse::from_response` builds from the response
  `handle_request` returns and keeps the report, and every failing
  assertion then ends with an `error report:` section, so a 500 says
  why it happened. `assert_inertia()` and the `AssertableInertia`
  assertions print it too, and the Inertia error page and validation
  redirect keep the report of the response they replace.
  `TestResponse::error_report` and
  `HttpResponse::error_report` expose it. The report belongs to its own
  response, so two requests in flight in one test process never mix
  their errors. To find a panic's location, the framework wraps the
  process panic hook once and calls the hook it replaced. This landed on
  main after the `v3.0.0` tag.
- **A development error page.** With debug on, a 5xx the framework
  built from an error or a caught panic, sent to a browser (an `Accept`
  that lists `text/html`) or an Inertia visit, becomes one HTML document
  with the same status: the error chain or the panic message and
  location, the stack frames recorded where the error was created, and
  the request's method, path, query, headers, matched route pattern and
  request id. The application's frames are shown; the frames of the
  framework, the async runtime, other dependencies and the standard
  library are collapsed behind a count. The `FrameworkError` and
  `AppError` constructors, the `From` conversions into `FrameworkError`,
  the `abort_with`, `abort_if` and `abort_unless` helpers and the
  `#[domain_error]` conversions are now `#[track_caller]`, so the page
  names the line that called them even in a build without debug info; a
  call from inside `Result::map_err` names that line of the toolchain,
  and the frames name the handler. Without debug info, the handler and
  middleware the framework's dispatch polls are the application's
  frames. The page redacts the `Authorization`, `Proxy-Authorization`,
  `Cookie` and `Set-Cookie` headers, every header and query parameter
  whose name contains `token`, `secret`, `password`, `key` or
  `signature`, every such parameter in any other shown value (a
  `Referer` or `X-Original-URI` that repeats the URL), and the password
  of a URL, and it never shows the request body, environment variables
  or configuration values. It loads nothing and runs no script, so it
  renders when the frontend build, the Vite manifest or Inertia is what
  failed, and it carries `Cache-Control: no-store` and a
  `Content-Security-Policy` that allows no script. For
  those responses it takes the place of the app's Inertia error page. A
  JSON client keeps the JSON body with `debug_message`, a 4xx and a 5xx
  built without an error are unchanged, and with debug off the framework
  records no frames, captures nothing about the request, and sends every
  response as before. This landed on main after the `v3.0.0` tag.
- **A Pusher-protocol broadcast driver.** `PusherBroadcastHub` publishes
  broadcasts through the REST API that Pusher Channels, Soketi and Laravel
  Reverb share, and still delivers them to in-process subscribers, so a
  `ws!` broadcasting route keeps working. `PusherConfig::from_env()` reads
  Laravel's `PUSHER_*` variables, and `from_env_prefix("REVERB")` reads
  Reverb's. `pusher_channel_auth` and `pusher_user_auth` answer Laravel
  Echo's authorization requests for private, presence and end-to-end
  encrypted channels. The new `Channel::visibility` picks each channel's
  Pusher name and defaults to private, so a channel that restricts
  `authorize` can never leak through a public Pusher channel. A name that
  would read as another channel's Pusher name, and an encrypted presence
  channel, are refused rather than published, and an invalid configuration
  fails when the hub is built. Publishing to an encrypted channel without a
  master key is an error, never a plaintext send. This landed on main after
  the `v3.0.0` tag (#130).
- **`InertiaProps` and `Data` follow serde's field names.** Both derives
  honor `#[serde(rename_all = "...")]` on the struct, and `rename`, `skip`,
  `skip_serializing` and `skip_deserializing` on a field, including the
  split `serialize = .., deserialize = ..` forms; any other serde attribute
  is a compile error. The names reach everything the client sees: Inertia
  props and partial reloads, the `?include=` allowlist, JSON:API members,
  request input, route-parameter injection, and `suprnova generate-types`.
  Validation errors of a `Data`, `#[derive(FormRequest)]` or `#[request]`
  struct are keyed by the input names at every nested level, so
  `Precognition-Validate-Only` matches what the client sent, and a message
  labels `unitPrice` as "unit price", as Laravel does. A raw identifier
  such as `r#type` is sent and read as `type`. A plain nested
  `#[derive(Deserialize, Validate)]` struct registers its names with the
  new `#[derive(suprnova::InputNames)]`. This landed on main after the
  `v3.0.0` tag (#124).
  Two consequences for existing code. A `#[serde(...)]` attribute on an
  `InertiaProps` or `Data` struct used to compile only next to another
  derive that registers `serde` (such as `schemars`), and did nothing
  there; it now takes effect, and an attribute the derive does not apply
  is a compile error. A localized validation message labels every key
  snake-cased, so a hand-written key `userID` reads "user i d", as in
  Laravel; snake_case keys read as before. A `#[json_resource]` struct may
  no longer send an attribute or relationship named `type` or `id`, which
  JSON:API reserves: a struct with a custom `id_field` and a field named
  `id`, or a field `r#type` (sent as `r#type` before), is now a compile
  error that asks for a `#[serde(rename = "...")]`.
- **The schema builder covers the rest of a Laravel migration.**
  `unsigned_id()` and `unsigned_foreign_id()` create Laravel's `BIGINT
  UNSIGNED` keys on MySQL, so a new table can point a foreign key at an
  existing Laravel table, and a model reads them with `key_type = "u64"`.
  New columns: `tiny_integer`, the `unsigned_` integers, `medium_text`,
  `long_text`, `enumeration` (Laravel's `enum`) and `remember_token`. New
  modifiers: `.unsigned()`, `.index()`, `.primary()`, `.precision(n)`,
  `.use_current()` and `.after(column)`. `t.primary(&[..])` makes a
  composite primary key, `t.foreign(column)` a foreign key on a column
  declared on its own, `.name(..)` names a key, and
  `drop_constrained_foreign_id` drops a key with its column. The actions have
  Laravel's shorthands, `cascade_on_delete()` and the rest. Where the
  databases differ the builder does what Laravel does: `unsigned` and
  `after` apply on MySQL only, and an enumeration is a string with a `CHECK`
  off MySQL. This landed on main after the `v3.0.0` tag (#122).
- **Native date-time columns for models.** `AsNativeDateTime` and
  `AsOptionalNativeDateTime` store a `DateTime<Utc>` in a column that keeps
  the zone (`timestamp with time zone` on Postgres, `TIMESTAMP` or
  `DATETIME` on MySQL); `AsNaiveDateTime` and `AsOptionalNaiveDateTime`
  store the UTC wall clock in one without a zone, the shape Laravel's
  `timestamps()` creates on Postgres. The schema builder gains Laravel's
  `timestamps_tz()`, `soft_deletes_tz()`, `datetimes()` and
  `soft_deletes_datetime()` to create them. Automatic timestamps, `touch()`,
  soft deletes and the touch of an owner all store through the declared
  cast, and query comparisons (`filter`, `where_between`, `where_date`,
  `update_all`, `where_has`) bind through it, so Postgres gets a native
  parameter. A model may declare `created_at` and `updated_at` as
  `Option<DateTime<Utc>>` for a table another application leaves NULL.
  `suprnova generate-types` now emits chrono's date and time types as
  `string` instead of `unknown`. This landed on main after the `v3.0.0` tag.
- **Laravel's `exists`, `accepted`, `digits`, `date_format`, date
  comparison, `prohibited`, `missing` and `exclude_if` rules.** `Exists`
  checks that a value names a row, scoped with `where_eq`; `check_value`
  binds a typed id, which Postgres needs for an integer column, and
  `check_each` checks every element of an array, one query per distinct
  value, with each failure under `field.<index>`. `Accepted`, `Digits`,
  `DateFormat` (chrono's format syntax, checked by a round trip like
  Laravel's),
  `After::new`, `AfterOrEqual::new`, `Before::new` and `BeforeOrEqual::new`
  (against a fixed date, `Now`, `Today`, `Tomorrow`, `Yesterday` or another
  field, with `.format(..)` for a field that is not ISO 8601), `Prohibited`,
  `Missing`, `ExcludeIf` and `ExcludeUnless` join the built-in rules.
  `validate!` now runs a row's rules in order, each expression evaluated
  once, and stops at an exclusion, as Laravel does. This landed on main
  after the `v3.0.0` tag.
- **A Data Object runs `validate!` and database rules.** The derive writes
  a Data Object's `FormRequest` impl, so it had no place for cross-field
  rules or for `Unique` and `Exists`. `#[data(after_validation = "fn")]`
  and `#[data(after_validation_async = "fn")]` name the functions that
  impl calls, and the impl a `from_route_param` field selects now runs the
  async stage too. That impl now calls the hooks through the trait, so an
  inherent `after_validation` method on such a Data Object, which it used
  to call by accident, no longer runs: name it with the attribute. The
  derive refuses both attributes on a struct that gets no `FormRequest`
  impl. This landed on main after the `v3.0.0` tag.
- **Joins and the remaining `where` helpers on both query builders.**
  `DB::table` and model queries gain `join`, `left_join`, `right_join` and
  `cross_join` with table aliases; closure conditions combining `on`,
  `or_on`, `where` and `or_where`; `join_sub` and `left_join_sub` against
  another builder; `where_exists` and `where_not_exists`; `where_any`,
  `where_all` and `where_none` with their `or_` forms; subqueries in
  `where_in` and `where_not_in`; the `or_where_*` family; and `reorder`.
  Every value stays bound and every identifier is quoted for the backend,
  so reports and exports no longer need raw SQL. A joined model query
  selects its own table's columns, so the joined table's `id` never
  overwrites the model's, and its soft-delete filter names its table.
  `DB::table` now quotes identifiers in every statement, so on Postgres a
  mixed-case name is case-sensitive, as in Laravel. An update or delete on
  a query with a join is refused rather than run without the join. This
  landed on main after the `v3.0.0` tag (#125, #128).
- **File and download responses.** `HttpResponse::file` shows a file
  inline, `HttpResponse::download` sends it as an attachment, and
  `HttpResponse::download_bytes` sends generated bytes; `Storage::response`
  and `Storage::download` do the same for a path on a named disk, through
  the disk's path guard. Files stream, the content type comes from the
  extension, a missing file answers 404 and a path the guard refuses 403.
  Every `Content-Disposition` follows RFC 6266, with an ASCII fallback
  transliterated as Laravel does and a `filename*` for the full name, so
  `Certificat·Joan Pérez.pdf` arrives intact and no name can inject a
  header. This landed on main after the `v3.0.0` tag (#126).
- **A configurable Inertia page lookup.** `inertia_response!` reads an
  optional `[package.metadata.suprnova.inertia]` table from the
  application's `Cargo.toml`: `pages_dir` moves the pages directory, and
  `page_file` maps a component name to its file with `{dir}`, `{name}` and
  the `lower`, `kebab` and `snake` filters. Angular and other layouts keep
  the compile-time page check, and a missing page names the exact path the
  macro looked for. Without the table nothing changes. This landed on main
  after the `v3.0.0` tag (#129).
- **The queue fake can let jobs through and records raw pushes.**
  `Queue::fake_except` and `QueueFakeGuard::except` record every job but
  the named ones, which reach the real queue. `Queue::push_raw` pushes an
  envelope's JSON form, and under the fake `raw_pushes` and `pushed_raw`
  read those pushes back. `assert_pushed_without_chain` fails for a job
  pushed with a chain. A chain whose first job `except` names runs on the
  real queue, and each later link is recorded unless `except` names it
  too. This landed on main after the `v3.0.0` tag.
- **Declarative authorization on handlers.** `#[authorize("update-post",
  post)]` on a `#[handler]` checks the gate against the model the route
  binds to `post`, and `#[authorize("create-post", Post)]` checks it
  against the type, for the user of the guard the route authenticated
  with. The check runs after route model binding and before
  the request body is read, so a forgotten `Gate::authorize` call can no
  longer leave a route open. Policies, async gates and the RBAC gate bridge
  all answer it. A guest gets 401, a denial 403, and `deny_as_not_found()`
  404. A parameter name the handler does not take fails to compile. This
  landed on main after the `v3.0.0` tag (#127).
- **Model changes after a save, `sync_without_detaching`, and after-commit
  callbacks.** A model reports what its last update changed
  (`was_changed`, `was_changed_any`, `get_changes`), and `get_original` and
  `get_raw_original` return the loaded values while its `updated` and
  `saved` observers run, as Laravel's do; once the save returns, the
  original is the saved row. An encrypted column counts as changed only
  when its decrypted value changed. `sync_without_detaching` attaches pivot rows
  without touching the existing ones. `DB::after_commit` runs a callback
  after the ambient `DB::transaction` commits, and never on rollback; a
  transaction started with `DB::begin_transaction` takes its own
  `tx.after_commit` and `Queue::push_after_commit_with_tx`, because ambient
  code is outside that transaction. This landed on main after the `v3.0.0`
  tag (#128).

### Changed

- **Less memory for the same work.** Model events are built only when a
  listener, a fake or a deferral will see them, so a query no longer
  copies every row it reads for a `Retrieved` event nobody hears. Eager
  loading reads each key from its field instead of serializing the whole
  row, and a runtime cast converts its column where it sits. The first
  Inertia page is written into one buffer, a file download reads each
  chunk straight into the bytes it sends, a body sent in several frames
  is held at its length, CORS path patterns are compiled once per
  configuration, and a broadcast's last channel takes the payload instead
  of a copy. A queue job receives its envelope's payload, the SQS driver
  parses a message once, sends a retried request's bytes without copying
  them and holds a reservation's body rather than a second envelope.
  `Context::push`, image transformations and encoding, filesystem
  `append` and `prepend`, `Collection::pluck`, the in-memory vector search,
  the feature-flag snapshot, Mailgun's form, composite render-cache shells
  and the docs builder each keep or copy less. A process result holds its
  output once when the output is valid UTF-8. In the Live engine a mount
  no longer copies its signed snapshot, action arguments are kept once,
  a full upload read returns the store's bytes, and the resource queue
  compacts in place. The Live browser runtime reads a server-sent event
  stream without copying what it already holds for every chunk, and an
  upload control response no longer allocates 16 KiB. Magnetar writes hex
  into one buffer, and its single-flight map holds a key only while a
  caller holds or waits on it. Every response, file, digest and snapshot
  is byte for byte what it was.
- **`CacheConfig` has a `sweep_interval` field.** Code that builds a
  `CacheConfig` as a struct literal has to set it, or use
  `CacheConfig::builder()`, which defaults it to 60.
- **`DynCast` has a `from_storage_json_owned` method** that converts a
  stored value the caller no longer needs. Its default calls
  `from_storage_json`; a cast whose in-memory value is the stored value
  returns it without copying.

### Fixed

- **A workflow step can take an integer argument.** `#[workflow_step]`
  handed the step's body to the workflow context in a closure that borrowed
  its arguments, and the context needs one it can keep, so a step taking a
  `Copy` argument such as `user_id: i64` failed to compile with E0373
  ("closure may outlive the current function"). The closure now takes its
  arguments by value.
- **Workers wait for their queued listeners.** `queue:work`,
  `schedule:work` and `workflow:work` now wait, up to ten seconds, for the
  queued event listeners still running when they stop, as the server
  does, and `schedule:run` does once its tasks have run; returning dropped
  them part way.
- **`Cache::bootstrap` keeps the cache store the application bound**, as
  the localization chapter says it does, instead of replacing it at boot.
- **The event dispatcher forgets its finished queued listeners** as it
  starts new ones; it kept every one until shutdown.
- **`DB::flush_query_log` releases the log's buffer** rather than keeping
  its capacity.
- **The in-memory vector search no longer panics on a NaN score**; such
  an item ranks below every other.
- **A `#[json_resource]` keeps its attributes in declaration order** when
  it drops a missing one; the last attribute used to move into its place.
- **The brute-force lockout map sweeps once each time it doubles.** With
  more than 1,024 current lockouts it swept on every new lockout.
- **The toast region lets go of toasts a morph removed**, which it timed
  and later dismissed for the life of the page, and resumes its timers
  when the focused toast is removed or the pointer has left it without the
  region hearing it.
- **The Live browser runtime reads a network chunk larger than one record**
  when the chunk holds only complete records; it ended the stream.
- **The Live chart follows the document's theme.** `render_chart` drew its
  SVG with charts-rs's light theme, a white background and fixed colors and
  font, so in a dark document the chart showed as a white box. The SVG now
  has a transparent background and no color or font of its own: its text,
  axis, grid and series carry classes that the chart component's
  stylesheet colors from `--sn-` tokens, and the chart's text takes the
  `--sn-font-sans` font. Series take the new `--sn-color-chart-1` to
  `--sn-color-chart-6` palette in order, defined for light and dark and
  mapped in the Tailwind preset, and a seventh series starts the palette
  again. An application that vendored the chart keeps its old stylesheet,
  which has no rule for these classes, so every series, axis and grid line
  draws in the text color. Run `suprnova live:add chart` to take the fix
  into it. This fix landed on main after the `v3.0.0` tag.
- **A cached render whose COMMIT fails answers 500 without a panic.** When
  a cache-miss render's handler ran and the database then refused the
  render transaction's COMMIT (a deferred constraint, a dropped
  connection), the render cache took the failure for a transaction that
  never opened: a debug build panicked, and the log said nothing about the
  commit. It now logs the database error under `suprnova::database` and
  answers the same 500, because the handler's writes rolled back and the
  rendered page would claim they landed. A render transaction that cannot
  open still renders uncached, as before. This fix landed on main after the
  `v3.0.0` tag.
- **A savepoint can be named with a reserved word.** `tx.savepoint("inner")`
  failed with a syntax error on PostgreSQL and MySQL, because the validated
  name went into the statement unquoted. Savepoint names are now quoted for
  the backend; they stay case-insensitive. This fix landed on main after the
  `v3.0.0` tag.
- **The sync queue driver runs a whole chain.** `SyncQueueDriver` ran a
  chain's first job and dropped every later link. It now runs the chain
  inline, link by link, as Laravel's sync queue does; a link that fails
  returns its error and the rest of the chain does not run. This fix
  landed on main after the `v3.0.0` tag.
- **`authorize_resource` checks the user of the route's guard.** On a route
  whose `AuthMiddleware` names a guard other than the default,
  `authorize_resource` checked the default guard's user instead of the one
  the route authenticated, so that user was refused. It now checks the
  route guard's user, as Laravel's `can` middleware does. This fix landed
  on main after the `v3.0.0` tag (#127).
- **A cached page that reads through a raw fragment is never served
  stale.** A `select_raw`, `where_raw`, `filter_raw` or `order_by_raw` on a
  model query can read a table the query doesn't name, but the render
  cache stored the page anyway, so a write to that table left it stale. A
  query carrying a raw fragment now keeps the page out of the cache, as raw
  `DB::select` does; the page is still served. A `select_raw` that is a
  bare number, such as `select_raw("1")`, doesn't count. This fix landed
  on main after the `v3.0.0` tag.
- **A destructured route parameter binds.** A handler parameter written
  `RouteParam(user): RouteParam<User>`, as the `RouteParam` docs show, looked
  up a route parameter named `param` and answered 400 to every request. It
  now reads the parameter its binding names, and a pattern with no single
  binding is a compile error. This fix landed on main after the `v3.0.0` tag.
- **SQLite rows keep computed columns.** An aggregate or `select_raw`
  expression came back missing from `DB::table` and `DB::select` rows on
  SQLite, because SQLite declares no type for a computed column. Such a
  column is now read by its value's runtime type. This fix landed on main
  after the `v3.0.0` tag.
- **A union arm keeps its soft-delete and scope filters.** A union of model
  queries rendered each arm's `WHERE` without its scopes, so soft-deleted
  rows came back. This fix landed on main after the `v3.0.0` tag.
- **A page cached from `where_has` sees writes to the related table.**
  `has`, `where_has`, `doesnt_have` and `where_relation` did not record the
  related or pivot table for the render cache, so a write there left the
  cached page stale. This fix landed on main after the `v3.0.0` tag.
- **The notifications table ships as a migration.** The manual said
  `suprnova migrate` creates it, but the schema was a SQL file only the
  framework's own tests loaded, so the database channel failed on its
  first write in a fresh app. Register
  `suprnova::notifications::migrations::CreateNotificationsTable` in your
  `Migrator`: it creates the same table and indexes, and running it over a
  table you created by hand from the old SQL file is safe on every engine.
  The SQL file is gone. This fix landed on main after the `v3.0.0` tag
  (#134).
- **Nullable JSON columns have casts.** `AsJson`, `AsArray`, `AsObject`,
  `AsCollection` and `AsArrayObject` store a non-null string, so
  `AsJson<Option<T>>` wrote the text `null` instead of SQL `NULL`, and a
  row whose column was `NULL` failed to load. `AsOptionalJson`,
  `AsOptionalArray`, `AsOptionalObject`, `AsOptionalCollection` and
  `AsOptionalArrayObject` map `None` to `NULL` and back, and store a value
  exactly as their non-optional cast does. This fix landed on main after
  the `v3.0.0` tag (#133).
- **`SESSION_TABLE` names the session table.** `SessionConfig::table_name`
  was read and then ignored: the database session driver always used
  `sessions`. The driver now reads and writes the configured table,
  `DatabaseSessionDriver::with_table` builds one over another table, and
  `Config::init` refuses a name that is not 1 to 63 ASCII letters, digits
  or underscores starting with a letter or underscore. What you have to
  change: an app that already set `SESSION_TABLE` now stores its sessions
  in that table, which its migration must create, and an empty
  `SESSION_TABLE` now fails boot. The driver also stops logging a session
  id when it skips a write, and the content of a stored payload it cannot
  parse. This fix landed on main after the `v3.0.0` tag (#132).
- **Re-running a framework migration no longer fails on an existing index.**
  The workflow and RenderCache migrations relied on `IF NOT EXISTS`, which
  MySQL and MariaDB drop from `CREATE INDEX`, and the payments, features and
  RBAC migrations created their indexes without it, so running one over
  tables that already existed failed with a duplicate index and blocked
  every migration after it. Each framework migration now creates an index
  only when it is missing, with the same columns and uniqueness as before.
  This fix landed on main after the `v3.0.0` tag (#136).
- **A `Data` object with a route-parameter field answers 422 for a body
  that does not fit.** Its extractor answered 400 where the default
  extractor answers 422 for the same malformed or unknown-key body. This
  fix landed on main after the `v3.0.0` tag.
- **A `Data` field may be named `key` or `map`.** The generated
  `Deserialize` named its locals after the fields, so such a field
  shadowed the visitor's own variables and the struct failed to compile.
  This fix landed on main after the `v3.0.0` tag.
- **`has`, `where_has` and `where_relation` work through a `BelongsTo`
  relation.** The existence query compared the related table's key with
  the foreign key as if the relation were a `HasMany`, so every existence
  query through a `BelongsTo` failed with an unknown column. It now joins
  the related row's owner key to the parent's foreign key. This fix landed
  on main after the `v3.0.0` tag.
- **A model declared beside `use sea_orm_migration::prelude::*` compiles.**
  That prelude brings `ExprTrait` into scope, whose `max` and `is_null`
  took over calls the `#[model]` macro emitted for relation counts and
  `MorphTo` relations. The macro now names those methods by path. This fix
  landed on main after the `v3.0.0` tag.
- **Persisting a replica stamps its timestamps.** `replicate` resets
  `created_at` and `updated_at` for the insert to fill, but `persist`
  wrote them as built: 1970-01-01, or NULL for an optional field. It now
  stamps a timestamp its builder left unset, as `create` does, and keeps
  one the builder set, so a factory can still backdate a row. This fix
  landed on main after the `v3.0.0` tag.
- **Touching an owner writes the owner's own date-time storage.** The
  `touches` cascade bound the time as RFC 3339 text whatever the owner's
  `updated_at` cast stored, which Postgres refuses for a native date-time
  column. It now stores the time through the owner's cast. This fix landed
  on main after the `v3.0.0` tag.
- **The temporal casts' documentation said Postgres accepts RFC 3339 text
  for a native column.** It refuses a text parameter for `timestamp` and
  `timestamp with time zone`; the module documentation now says so and
  points to the native casts. This fix landed on main after the `v3.0.0`
  tag.
- **`Unique` and `Exists` keep database errors out of the response.** A
  database rule that could not run returned the driver's error as its
  validation message, and a validation message is rendered into the 422
  body, so a client could read table names, column types and SQL. The rule
  now logs the cause under the `suprnova::validation` target and fails the
  field with `validation-unchecked`. This fix landed on main after the
  `v3.0.0` tag.
- **Precognition keeps the errors of an array's elements.** A
  `Precognition-Validate-Only` header naming `tag_ids` dropped the errors
  reported under `tag_ids.0`, `tag_ids.1` and so on, so a form validating
  the field saw success for an invalid array. A field now keeps the errors
  nested under it, and `tag_ids.*` matches the elements as Laravel's rule
  key does. This fix landed on main after the `v3.0.0` tag.
- **The date picker, upload, account menu and notification bell follow the
  theme.** Their stylesheets read `--sn-color-accent` and
  `--sn-color-on-accent`, which the token stylesheet never defined, so the
  selected day, the upload progress bar, the avatar and the unread count fell
  back to inherited colors and ignored every theme. The token stylesheet now
  defines both, from `--sn-color-primary` and `--sn-color-primary-contrast`,
  and the Tailwind preset maps them as `accent` and `on-accent`. An
  application that vendored these components with `live:add` needs no change:
  the framework serves the corrected stylesheet. This fix landed on main after
  the `v3.0.0` tag.
- **A first `live:model` edit on a public seed promotes it.** The browser
  runtime sends an immediate `live:model` edit on a public-seed island as a
  model synchronization with no action, and the action endpoint promoted a seed
  only for an action, so the first keystroke in such an island answered `500`.
  The endpoint now promotes the seed on that request, applies the proposals as
  it does on an instance, and runs no action. This fix landed on main after the
  `v3.0.0` tag.
- **The date picker's "Pick the parts" toggle no longer looks like a second
  field.** The base layer draws every `details` as a bordered surface for the
  collapsible, and the date picker's disclosure inherited it, so an empty box
  sat under the date input. The disclosure is now a plain toggle; the year,
  month and day strips keep their borders. Run `suprnova live:add date-picker`
  to take the fix into an application that vendored the component. This fix
  landed on main after the `v3.0.0` tag.
- **`suprnova generate-types` names and omits plain-struct keys the way serde
  does.** A struct a prop reaches that derives serde's `Serialize` sends the
  keys its `#[serde(...)]` attributes give it, but the generator declared every
  field under its Rust name. It now leaves out `skip` and `skip_serializing`
  fields, declares `skip_serializing_if` fields optional, names keys by
  `rename` and `rename_all` (and their `serialize = ...` forms), and drops the
  `r#` of a raw identifier. Other serde attributes, such as `flatten` and
  `transparent`, are still not read. A key that is not an identifier is now
  quoted, which also makes a raw identifier on a derived struct valid
  TypeScript (`"r#type"`, the key its derive sends). `#[derive(Data)]` and
  `#[derive(InertiaProps)]` structs keep their Rust names: their own
  `Serialize` never reads `#[serde(...)]`. This fix landed on main after the
  `v3.0.0` tag.

## 3.0.0 - 2026-09-29

### Added

- **`FrameworkError::Timeout` tells a passed deadline from a failure.**
  `WorkflowHandle::wait_with_timeout` documented a timeout error that did not
  exist and returned `FrameworkError::Internal`, so a caller could not tell a
  workflow that is still running from a failed status query. The variant
  carries the deadline and what was awaited, `FrameworkError::timeout(elapsed,
  message)` builds one, `is_timeout()` asks for it, and it renders as `504
  Gateway Timeout`. `wait_with_timeout` and `wait_with_options` return it when
  the deadline fires.
- **`Queue::fake()` and `Bus::fake()` install their fakes.** Every other
  facade had `fake()`; these two had only the free function
  `testing::install_fake()`. Both return the same guard, and the free
  functions stay.
- **Failed-job commands: `queue:failed`, `queue:retry`, `queue:forget`,
  `queue:flush` and `queue:prune-failed`.** The manual and the code's own docs
  sent operators to commands that did not exist; the failed-job store could
  only be reached from code. The application binary now has all five, and the
  `suprnova` CLI forwards them. `queue:failed` lists id, connection, queue,
  job, failure time and the first line of the error. `queue:retry` takes one
  or more ids, or `all`. `queue:flush` deletes every failed job, or with
  `--hours N` the ones older than that. `queue:prune-failed` is the same with
  `--hours` defaulting to 24. A command exits non-zero when an id names no
  failed job.
- **Queued mail and notifications can wait for the commit.**
  `Mailable::after_commit(&self)` and `Notification::after_commit(&self)`
  default to `false`. When one answers `true`, `Mail::queue`, `Mail::later`
  and `Notify::queue` inside `DB::transaction` push at the commit, and a
  rollback discards the push, as `Job::after_commit` already does for a job.
  `QUEUE_AFTER_COMMIT=true` turns the same behavior on for every push in the
  process, as the `after_commit` option of a Laravel queue connection does;
  `EnvelopeOverrides { after_commit: Some(false), .. }` still sends one push
  ahead of the commit.
- **Queue connections select a driver.** One process-global driver received
  every push, and a job's connection was only a name on the lifecycle events.
  `Queue::register_connection(name, driver)` now registers a named connection
  next to the default one that `Queue::set_driver` installs, and a push goes
  to the connection it resolves to: a per-push
  `EnvelopeOverrides::connection`, then a `Queue::route`, then
  `Job::connection()`, then the default. `Queue::push`, `push_with`, `later`,
  `bulk` and `push_unique` all resolve it, the jobs of a batch each go to
  their own connection, and a failed job is retried on the connection it
  failed on. `queue:work --connection <name>` and
  `queue::worker::run_worker_on` drain one connection, and the worker carries
  its name on its events and failed-job records. `queue:pause` and
  `queue:resume` take `--connection`. `Queue::connection(name)` returns a
  connection's driver and `Queue::connection_names()` lists the registered
  ones; `Queue::size()` and the other counts and listings read the default
  connection. While no connection is registered nothing changes: every push
  reaches the one driver, and a connection name is a label. Once one is
  registered, a push to a name that is neither registered nor the default's is
  an error and pushes nothing, and a push that waits for a commit is refused
  before the commit. A chain runs on the connection of its first job, because
  the worker enqueues the next link in the step that settles the one before
  it; `Queue::chain().dispatch()` refuses a chain whose links resolve to
  different connections. `QUEUE_CONNECTIONS=redis,database` registers one
  connection per entry from the environment, each named for its driver. One
  driver has one label: an entry that names the driver `QUEUE_DRIVER` selects
  is a second name for the default connection, so a pause or a
  `Queue::forward_on` set under either name reaches the whole queue, and an
  entry that would put a second connection over a Redis stream or a jobs table
  that is already in use is refused at boot.
- **`Context` travels with queued work.** A value added to `Context` during a
  request was gone when a queued job, a queued mail or notification, or a
  queued event listener ran. A push now takes a `ContextSnapshot` of the
  visible and hidden bags and stores it on the envelope, and the worker runs
  the job inside a scope restored from it. The snapshot is taken when the push
  is made, so a push that waits for a commit carries it too. The lifecycle
  events around the job, such as `JobProcessing`, `JobProcessed` and
  `JobFailed`, are dispatched in the same scope, so a listener reads what the
  job read and what the job added. Every link of a chain and every job of a
  batch gets the snapshot of the code that dispatched it, and a queued
  listener gets the snapshot of the dispatch. The work runs on a copy, so what
  a job adds reaches neither the request nor the next job, and every attempt
  starts from the snapshot. Under the sync driver the copy shadows the
  caller's context for the length of the job. The query bag does not travel,
  so a job run inline no longer reads the request's query parameters. A job
  queued while a request is served carries the request's id as `_request_id`,
  which the request middleware adds to the context; a push made outside a
  request with nothing in its context writes the envelope it wrote before.
  `Context::dehydrating` and `Context::hydrated` register callbacks for the
  two ends, as Laravel's hooks of those names do, with `Context::dehydrate`,
  `Context::hydrate` and `Context::restored` as the functions behind them.
  `Envelope` gains the public field `context`, so code that builds one with a
  struct literal has to name it; an envelope written before the field existed
  decodes without context. Hidden values reach the queue store and the
  failed-job store, because the job needs them. They do not reach a log: the
  envelope a worker logs when no failed-job store is bound carries no hidden
  context, and the `Debug` output of `ContextSnapshot` and `ContextStore`
  names hidden keys only, and that of `FailedJob` gives the size of the
  envelope and not its text.
- **`ThrottleRequestsMiddleware::default()`.** The plain `throttle` alias had
  no limit to register: every constructor asked for a limit, a window and a
  key prefix, and the manual registered the alias with a `default()` that did
  not exist. The default is 60 requests a minute, counted for each signed-in
  user and for each client IP when nobody is signed in, the shape of Laravel's
  default `api` limiter. The numbers are
  `ThrottleRequestsMiddleware::DEFAULT_MAX_ATTEMPTS` and
  `DEFAULT_DECAY_SECONDS`. The user's bucket follows the user across routes,
  and the address's bucket is shared by every route; `.prefix(...)` gives a
  group of routes a budget of its own.
- **`RateLimitMiddleware::ip_based(max_requests, window)`.** The per-IP limit
  that every login form and public API needs took a backend `Arc`, a
  `SlidingWindowConfig` and a hand-written key closure, and the manual used an
  `ip_based` that did not exist. It uses the rate limiter the application
  installed, the one `RATE_LIMIT_DRIVER` selects, looked up when a request
  arrives, so the middleware can be built where routes are registered. The key
  is the address `Request::ip()` resolves through the trusted proxies, and it
  names the limit as well, so two limits with different numbers share no
  bucket. A request with no address to resolve gets a bucket of its own.
  `on_backend_error`, `only_when` and `key_reads_body` chain onto it; when no
  limiter is installed the backend error policy decides.
- **Middleware by name on routes.** Aliases and groups could be registered and
  resolved, but no route took a name: every `.middleware(...)` wanted a type,
  and nothing parsed `throttle:60,1`. Routes, groups of routes and the macro
  builders now have `.middleware_named("auth")`, which takes an alias, an
  alias with arguments, or a group that adds every middleware of the group in
  order. The name is resolved when the route is registered, so a name that is
  not registered stops the boot and never a request;
  `.try_middleware_named(...)` returns the error.
  `register_middleware_alias_with_args(name, |arguments| ...)` registers an
  alias that reads the arguments after the colon, and a group may list such an
  alias. `try_resolve_middleware_alias` says why an alias gave no middleware.
  `ThrottleRequestsMiddleware::from_alias_args` is the factory for the
  `throttle` alias: `throttle`, `throttle:60`, `throttle:60,5`,
  `throttle:60,5,prefix` and `throttle:api` for a named limiter.
- **Route groups take a name prefix and a controller.** Every route in an
  `admin.` group had to spell its full name, and every handler its full path.
  `group!(...).name("admin.users.")` now puts the prefix in front of the name
  of every route in the group, and a group inside adds its own after it; a
  route without a name stays without one. `group!("/admin/users", controller =
  controllers::admin::users, { get!("/", index), post!("/", store) })` names
  the module the handlers live in, so a route names its handler by function
  alone. A handler written as a path is taken as it is written, and a group
  inside names its own controller. The path prefix stays the first argument of
  the macro.
- **Optional route parameters and parameter constraints.** `/posts/{id?}` now
  matches `/posts` and `/posts/42`, and the handler finds no `id` on the short
  form. Several optional parameters fill from the left, the colon spelling
  `/posts/:id?` works, and an optional parameter can only be followed by
  optional ones. The route's middleware and name apply to every form, and
  `route(...)` leaves an optional segment out when it has no value. A route
  can hold a parameter to a constraint: `.where_number("id")`, `.where_alpha`,
  `.where_alpha_numeric`, `.where_uuid`, `.where_ulid`, `.where_in("status",
  [...])` and `.where_pattern("year", "[0-9]{4}")`, on `Router` routes and on
  `get!`, `post!` and the other route macros, where a constraint may name a
  parameter of the group's prefix. A value the constraint refuses is a 404, as
  if the route had not matched, and neither the route's middleware nor its
  handler runs. On a `Router` route `.try_constrain(param, ParamConstraint)`
  returns the error a constraint on a parameter the route does not have gives;
  `.constrain` and the `where_*` spellings stop the boot on it. A pattern has
  to match the whole value, and `\d` matches the digits of every script, so
  write `[0-9]` for ASCII digits. A WebSocket route takes optional parameters
  as well. A pattern with an optional parameter and an empty segment, and a
  second route for one form of an optional route, are refused when they are
  registered.
- **Console commands can be tested for what they print and ask:
  `console::test`.** `dispatch_argv` returns a `Result` and nothing else, so a
  test could tell that a command ran and not what it said, and a command that
  asks a question waited on the standard input of the test runner.
  `console::test(["users:purge", "--days", "30"]).expects_question("Delete 12
  users?", "yes").run().await` runs the command through the dispatcher the
  console binary uses and returns a `ConsoleRun` with `output()`, `errors()`,
  `exit_code()`, `error()` and `unasked_questions()`, and with
  `assert_successful`, `assert_failed`, `assert_output_contains`,
  `assert_errors_contain` and `assert_every_question_was_asked`. Help, the
  version, parse errors and the error of a failed command are collected as
  well. A command prints with `console::line` and `console::error_line` and
  asks with `console::ask` and `console::confirm`; what it prints with
  `println!` a test cannot see. Questions have to come in the order the test
  gave them, and a question with no prepared answer fails the command. The
  framework's own commands, `db:seed` and `model:prune` among them, print
  through the console now, and `make:command` generates a command that does.
- **`Schedule::command("emails:send --force")` puts a console command on the
  schedule.** The schedule took a `Task` or a closure, so a command of the
  application, or a builtin such as `model:prune`, could only be scheduled by
  wrapping it by hand. `command` takes the line the way it is typed behind the
  name of the console binary, splits it into words the way a shell does, and
  returns the `TaskBuilder` every other task uses, so `daily()`,
  `without_overlapping()` and `on_one_server()` apply. The command runs in the
  scheduler's process. The line is checked when the schedule is built: a name
  no command has, arguments the command does not take, and a quote that is not
  closed stop the boot, and `try_command` returns the error. The task is named
  by its command line and described by the command's about text.
- **`suprnova db:seed` and `suprnova model:prune`.** The console binary has
  had both commands, and the manual shows them through the CLI, but the CLI
  forwarded `migrate` and its siblings and not these two, so the step after
  `suprnova migrate` was `cargo run --bin console -- db:seed`. `suprnova
  db:seed` runs every seeder, and `suprnova db:seed UserSeeder` or
  `--class=UserSeeder` runs one. `suprnova model:prune` takes `--model=<Name>`
  and `--pretend`. Both run the project's console binary, which checks the
  names.
- **`QdrantVectorDriver::from_env()` and `MariaDbVectorDriver::from_env()`.**
  Only the Pinecone driver read its configuration from the environment, so
  choosing the vector store by environment needed hand-written `std::env::var`
  code for the other two. The Qdrant driver reads `QDRANT_URL` and, when it is
  set, `QDRANT_API_KEY`. The MariaDB driver reads `MARIADB_URL`, and
  `DATABASE_URL` when that is not set and names a MariaDB or a MySQL database,
  which is the setup with one engine for rows and vectors. A `DATABASE_URL` of
  another engine is not taken. A `mysql://` URL is taken as well, because a
  MariaDB is written that way too. The Qdrant client is built without its
  version check, which connects and blocks while the application boots. A
  variable that is missing is named in the error at boot, and the error never
  shows a URL.
- **Storage configures an S3 disk from the environment.** Mail, the queue and
  the rate limiter read their configuration from `.env` when the server boots;
  storage read no variable, so an S3 or S3-compatible disk (MinIO, RustFS, R2,
  B2) existed only when the application built an `S3Config` by hand, and the
  `.env` the Docker guide shows configured nothing. When `S3_BUCKET` is set,
  the server now registers an S3 disk named `s3` from `S3_BUCKET`,
  `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY` and `S3_ROOT`.
  With no keys set the driver uses the default credential chain of AWS, and
  `AWS_REGION` is read when `S3_REGION` is not set. **What to check when you
  upgrade:** an application that already sets `S3_BUCKET` for a disk of its
  own gets the `s3` disk as well, and the server does not boot when the
  variables describe no usable disk: no region, or one key without the other.
  A disk the application registered under the name `s3` is left as it is, and
  the variables are not read then. `S3Config::from_env()` returns the same
  configuration for a disk with a name of your own, and
  `filesystem::bootstrap_from_env()` is the function the server calls; the
  console binary boots no driver of the environment, so an application whose
  commands use the disk calls it in its own bootstrap. There is still no
  default disk, and `FILESYSTEM_DISK` is not read.
- **`Storage::url(disk, path)` returns the public URL of a file.** Storage had
  presigned links that expire, `temporary_url` and `temporary_upload_url`, and
  nothing for a file that is meant to be public, so applications built those
  URLs by hand and repeated the base URL of the disk wherever they did. A disk
  gets its public base URL with `Storage::set_public_url("public",
  "https://cdn.example.com/files")`, or a path of the application's own host,
  `/storage`. `Storage::url("public", "avatars/7.png")` joins the two and
  writes every character of the path that a URL gives a meaning to as `%XX`,
  so `c++ notes.pdf` is `c%2B%2B%20notes.pdf`. A disk with no public base URL
  returns an error, so a private disk hands out no link that can be guessed,
  and a path with a `.` or `..` segment is refused. A base URL is refused when
  it has a user or a password, a query or a fragment, a backslash, a `.` or
  `..` segment, or another scheme than `http` and `https`, and the error does
  not repeat the URL. `S3_PUBLIC_URL` gives the disk of the environment its
  base. The function takes the name of the disk, because `Storage::disk`
  returns the `opendal` operator itself, which carries no name.
- **`DB::monitor(max)` and the `db:monitor` command dispatch `DatabaseBusy`.**
  The event was public, exported from the crate root and listed with the
  database events the framework fires, and no code dispatched it: an
  application that listened for it to alert on a database that runs out of
  connections waited for an event that never came. `DB::monitor(max)` asks the
  server of each connection, the default one and every named one, how many
  connections it has from every client, and dispatches `DatabaseBusy` for a
  server with `max` or more. PostgreSQL counts `pg_stat_activity`, and MySQL
  and MariaDB give `threads_connected`, the way Laravel's `db:monitor` asks.
  SQLite has no server and is never busy. The server does the counting, so the
  answer is the same from every process, and the check can run on the
  schedule: `schedule.command("db:monitor --max 80").every_minute()`. Nothing
  runs it by itself. `DB::connection_counts()` returns the numbers and
  `DbConnection::server_connections()` the number of one connection.
  `DbConnection::connections_in_use()` is the other number, the connections of
  this process's own pool that are out of it now.
- **`suprnova::fake` is the `fake` crate, for factories written by hand.** The
  crate root had `Dummy`, `Fake` and `Faker`, and everything else a factory
  uses, the fakers of `fake::faker` and `rand::Rng` for `fake_with_rng`, was
  reachable through the hidden `suprnova::__fake` alone, which the factories
  chapter showed as the supported path. An application that added `fake` to
  its own dependencies had to keep its version the one of the framework, or
  the traits did not line up. `use
  suprnova::fake::faker::internet::en::SafeEmail` and `use
  suprnova::fake::rand::Rng` now work. `__fake` stays for the code
  `#[derive(Factory)]` generates. `#[derive(Dummy)]` generates code that names
  the crate `::fake`, so in an application without `fake` among its
  dependencies the struct says where the crate is: `#[dummy(crate_name =
  "suprnova::fake")]`.
- **`WorkflowWorker::try_with_config(config)` and
  `workflow::assert_no_duplicates()`.** `WorkflowWorker::new()` refuses to
  start when two `#[workflow]` functions have one name. `with_config` skipped
  that check and told the caller to run `registry::assert_no_duplicates`, a
  function of a module that is hidden from the documentation and was exported
  nowhere, so a worker with a config of the application's own lost the check
  without a word. `try_with_config` checks the config and the registry and
  returns the error where `new()` panics, and `assert_no_duplicates` is
  exported from `suprnova::workflow`. `with_config` stays the constructor with
  no check, and says so. `new()` makes its checks through `try_with_config`,
  so the two cannot come apart.
- **`Crypt::decrypt_string_with_origin` and its siblings return where a value
  came from.** `DecryptOrigin`, `KeyOrigin` and `AadVersion` were public, and
  every function that returned one was hidden, so the two questions of a key
  rotation, does this value still need a previous key and does it still use
  the legacy label, were answered in log warnings alone.
  `Crypt::decrypt_string_with_origin`, `Crypt::decrypt_string_for_with_origin`
  and `Crypt::decrypt_with_origin` return the value and its `DecryptOrigin`,
  and `DecryptOrigin::needs_reencryption()` says whether the value is to be
  written again. With them the job that ends a rotation can be written: read
  every encrypted value, write again what needs it, and remove the previous
  key when nothing does. For tests, `crypto::testing::encrypt_string_under`
  and `encrypt_string_for_under` write a value under a key and a label of the
  test's choice; they are compiled with the `testing` feature and replace the
  hidden `_test_encrypt_with` names the manual pointed at. The three types are
  exported from the crate root. An error for a decrypted value that does not
  decode as JSON no longer quotes the value: it says which kind of mistake it
  was and at which line and column. That is the error of `Crypt::decrypt`, of
  a pagination cursor, and of the casts `AsEncryptedArray`,
  `AsEncryptedObject` and `AsEncryptedCollection`, whose error is a validation
  error and was shown to the client with the decrypted value in it.
- **Metric attributes have types.** `inc_with`, `record_with` and `set_with`
  took `&[(&'static str, &str)]` and sent every value as a text, so a status
  `404` matched no filter on a number and no range, and the attributes the
  semantic conventions type as a number or as yes and no arrived as the wrong
  type. A value is now anything that becomes an `AttrValue`: a text, a whole
  number, a number with a fraction, or a `bool`.
  `counter.inc_with(&[("http.response.status_code", 404)])` sends a number.
  Values of one type are written as they are, and values of several types are
  each made an `AttrValue`: `("route", AttrValue::from("/posts")), ("error",
  AttrValue::from(true))`. Every call that passes texts compiles as before. A
  `u64` or `usize` that no `i64` holds is sent as the largest `i64`. A text is
  also a reference to what holds one, `&String`, `&&str`, `&Box<str>`,
  `&Arc<str>`, `&Rc<str>` and `&Cow<str>`, as it was when the values were
  `&str`. Two calls have to be written another way: an empty list,
  `inc_with(&[])`, is `inc()`, and a value that is `.as_ref()` names its type,
  `.as_str()`. `AttrValue` is `#[non_exhaustive]`.
- **A WebSocket handler sends from another task: `WsSocket::sender()` and
  `WsSocket::split()`.** Every method of `WsSocket` takes `&mut self`, so
  while a handler waited in `recv` nothing could send on the connection, and a
  broadcast, a timer or a finished job had to go through a `select!` loop and
  a channel of the handler's own. `sender()` returns a `WsSender`: it clones,
  its `send_text`, `send_binary` and `close` take `&self`, and every clone
  sends on the same connection. `split()` takes the socket apart into a
  `WsSender` and a `WsReceiver`, and the `WsReceiver` is also a `Stream` of
  the messages. The connection does not wait for its senders: when the handler
  returns the connection closes, every later send returns an error,
  `is_closed()` returns `true` and `closed()` completes, so a task that keeps
  a sender learns when to stop. The receiving half has to be read, because the
  answer to the heartbeat's ping arrives there.
- **An upload policy says which rule it breaks: `UploadPolicy::validate()` and
  `UploadPolicyError`.** A Live upload field whose policy the engine refused
  failed the registration of its component with one closed error,
  `invalid_component_upload_metadata`, whichever of the rules was broken: a
  limit that was not set or was zero, a media type or an extension that was
  not in canonical form, a media type declared twice, a dimension of zero, a
  finalize action that was missing or was no name. `UploadPolicy::validate()`
  returns the rule as an `UploadPolicyError`, and the registration logs it as
  an error before it fails. The error of the registration is what it was, so
  nothing of a component reaches a browser through it.
- **A Live operation that fails inside the engine says why.** The engine
  answered every failure of one of its own parts with one reason for the
  browser, `ExecutionFailed` or `LedgerUnavailable`, and threw the error away,
  so a panic of a component, a clock that gave no time and a ledger that was
  full read the same in every log. The browser still gets that reason and
  nothing more. `RefreshRequiredExecution::cause()` returns an
  `ExecutionFailure`, a closed value that names the part that failed and the
  kind of its error: the action, the lifecycle, the ledger, the clock, the
  snapshot, the view, the composition, a port of the host. It is `None` for a
  refresh that is no failure, such as a stale revision. The framework writes
  one warning for each operation that ends with a cause, with the component,
  the reason and the cause. `MountError::cause()` returns a `MountFailure` in
  the same way for a mount, private or public, and `MountError::ledger_kind()`
  is the kind of the ledger when the ledger refused. Neither value holds a
  text, an identifier of an instance or anything of a request.
- **`load` and `load_missing` on one model.** Both were methods of a
  collection only, so code with one `Post` in hand wrapped it in a collection
  of one to load its comments, or ran the query of the relation by hand and
  lost the cache of the model. `post.load(["comments"]).await?` and
  `post.load_missing(["comments.user"]).await?` load into the model itself,
  through the loader of the collections: nested names, the one query for each
  relation and the transaction of the caller are the same. `load_missing` runs
  no query for a relation that the model has.
- **`PaddleProvider::archive_customer` archives a Paddle customer.** Paddle
  has no endpoint that deletes a customer, so `delete_customer` of the Paddle
  adapter returns `PaymentError::NotSupported`, and its message named a way
  that did nothing: an update with `metadata: {"status": "archived"}` writes a
  key named `status` into the custom data of the customer, and the customer
  stays active. `archive_customer(provider_customer_id)` sets the status of
  the customer to `archived` at Paddle. A customer that Paddle does not know
  is `PaymentError::NotFound`. The message of `delete_customer` names
  `PaddleProvider::archive_customer`. What you have to change: code that
  archived a customer through `metadata` calls `archive_customer`, and removes
  the `status` key from the metadata if it does not want it there.
- **A supported way to test a cached route:
  `render_cache::testing::RenderCacheProbe`, `RenderCacheConfig::with_clock`
  and `database::testing::StatementCounter`.** A test that has to prove that
  the render cache served a response had the hidden hooks of the framework's
  own tests and nothing else: `key_for_route_for_test`,
  `inspect_route_for_test`, `inspect_l1_for_test`, `clear_l0_for_test`,
  `with_clock_for_test`, `observe_statements_for_test`.
  `RenderCacheProbe::route(pattern)`, with `.params(..)` and `.at_epoch(..)`,
  gives the key the route derives (`key()`), the entry of each tier for that
  key (`l0()`, `l1()`), and `RenderCacheProbe::clear_l0()` empties the first
  tier and leaves the second as it is. The probe derives the key with the
  function the middleware uses, so you tell it each dimension the policy of
  the route varies on: `.login(id)` for `Principal`, `.tenant(id)` for
  `Tenant`, `.locale(tag)` for `Locale` (the current locale of the process
  when you leave it out) and `.host(host)` for `Host`; a route that varies on
  `Host` and a probe with no host is an error that names the dimension. `l0()`
  reads through `MemoryRenderStore::peek`, which does not count as a use, so a
  probe between two requests does not change what the first tier evicts next;
  `RenderCache::inspect` counts as a use. `RenderCacheConfig::with_clock`
  installs the clock the runtime reads, so a test moves an entry through its
  freshness bands without a sleep. `StatementCounter::install(&mut
  connection)` counts the prepared statements run through a connection, so a
  test shows that a request the cache served ran none; unprepared SQL and
  transaction control are not counted. All of it is compiled with the
  `testing` feature, and no function of it panics: an error names the route
  and never a login, a parameter or a key. What you have to change: a test
  that called `RenderCacheConfig::with_clock_for_test` calls `with_clock`. The
  other hooks stay for the framework's own tests, and are compiled with the
  `testing` feature only.
- **A binding that lives for one request: `App::scoped`.** The container had
  bindings for the process and overrides for a test, and nothing between them,
  so a service that belongs to one request, such as the database handle of the
  tenant or an API client bound to the request, was global and leaked between
  requests, or was built by hand in every handler. `App::scoped::<T>(factory)`
  and `App::bind_scoped` register a binding whose factory runs at most once in
  a scope, at the first `App::get`, and whose value is dropped when the scope
  ends. The framework opens a scope for each request, each WebSocket session,
  each attempt of a queued job, each attempt of a queued listener, each run of
  a scheduled task, a workflow or a supervisor, and each console command. An
  after-commit callback, a hook that runs after the response and the body of a
  streamed response share the scope of the request that registered them.
  `App::run_scoped(future)` opens a scope of your own,
  `App::in_current_scope(future)` carries the scope of the caller into a
  future that you spawn, and `App::spawn_scoped` does both steps. Outside a
  scope, `App::resolve` returns an error that names the type, and `App::get`
  logs a warning and returns `None`: a scoped binding never builds a value
  that lives for the process. A test override wins over a scoped binding. A
  factory is synchronous and runs once: a second task of the scope that asks
  for the value while it is built waits for it on its thread, and a cycle of
  scoped factories, in one task or across tasks, is an error.
- **The permissions of a user answer the gate: `rbac::register_gate_bridge`.**
  The roles and permissions of RBAC and the gate did not know each other, so
  `Gate::allows_async("edit posts", ..)` did not see a permission that the
  user holds, and an application had two systems of authorization side by
  side. `suprnova::rbac::register_gate_bridge::<User>()`, called once in the
  bootstrap, makes every permission that a user holds, directly or through a
  role, an ability of the gate. An ability that is no permission of the user
  goes on to the gate definitions and the policies, so the bridge allows and
  never denies. It reads the permissions of a user once for a request, through
  `GateBridgeMiddleware`, which the call installs as the first global
  middleware. A grant or a revocation made before the first check of a request
  is seen by that check; after it, from the next request on. A check inside
  `DB::transaction` reads for itself and keeps nothing, so a grant that is
  rolled back does not answer after the rollback. A unit of work that runs
  inside a request in a scope of its own, such as a job that the sync queue
  driver runs inline, reads for itself too. A read that fails is logged and
  allows nothing. The permissions answer the async forms of the gate,
  `allows_async`, `authorize_async` and `inspect_async`. The forms without
  `async` cannot wait for a database and skip them. `Gate::before_async` is
  the hook the bridge is built on, and an application can register hooks of
  its own with it. A `Some(false)` from an async hook denies on the async
  forms only: a hook that must deny on every form belongs in `Gate::before`.
  Without the call nothing changes.
- **An application registers guards of its own: `Auth::extend` and
  `Auth::via_request`.** `Guard` was a public trait, but the manager built
  guards from two drivers, session and token, so a guard for an API key, a
  client certificate or a single sign-on could be written and not registered,
  and `Auth::guard("api_key")` and the middleware that takes a guard name
  could not use it. `Auth::extend(driver, factory)` registers the factory of a
  driver, and `GuardConfig::custom(driver, provider)` declares a guard of it.
  The factory gets the name of the guard and its provider.
  `Auth::via_request(name, resolver)` is the short form for a guard that reads
  the request: the resolver gets the request and answers with the user, and
  the guard is declared with
  `GuardConfig::custom(AuthManager::via_request_driver(name), provider)`. The
  middleware for the guard runs the resolver once for a request. Outside that
  middleware the guard reports no user, as the token guard does. An error of a
  factory or of a resolver fails the request with 500 and is never a guest. A
  guard of the application is read-only through the manager:
  `Auth::stateful_guard` returns an error for it, and so do `Auth::logout`,
  `Auth::login_id` and `Auth::login_remember` when such a guard is the default
  guard, before they change anything. A guard of the application has no `:` in
  its name: resolving such a guard, or registering a resolver for it with
  `via_request`, is an error. A logout forgets the users that the guards of
  the application resolved in the request, so the request does not sign itself
  back in. Declared as the default guard, a guard of the application answers
  `Auth::user` and the unnamed `AuthMiddleware::new()`. The principal that the
  middleware attests for Live is `<guard>:<id>` for a guard of the
  application, so the same id under two guards is two principals; a session
  user attests its bare id. What you have to change:
  `AuthManager::via_request` returns a `Result`. `GuardDriver` has the variant
  `Custom(String)` and is no longer `Copy`, so code that copies a driver
  borrows it or clones it, and a `match` that names every variant has one more
  to name.
- **`suprnova::eloquent::prevent_lazy_loading(true)` refuses a relation read
  that runs one query for each row of a list.** A template that reads
  `post.author()` for each of 50 posts runs 51 queries, and nothing said so
  until the load of production. With the switch on, a relation read on a model
  that came out of a query that returned more than one row, when the relation
  was not loaded with `with(..)`, `load(..)` or `load_missing(..)`, runs no
  query and returns an error that names the model and the relation. A model
  from `find`, `first`, a `get` that returned one row, or `create` reads its
  relations as before, as in Laravel. `count()` of a relation is not refused.
  `handle_lazy_loading_violation(handler)` registers one handler for the
  process, which gets a `LazyLoadingViolation` with the names of the model and
  the relation; with a handler the read goes on, so a staging system can log
  the reads and keep serving. `clear_lazy_loading_violation_handler()` removes
  it, and `preventing_lazy_loading()` reads the switch. The switch is off by
  default, and with it off every read behaves as before. Turn it on in the
  bootstrap of the application outside production.
- **A test moves the clock the framework reads: `suprnova::clock::now()` and
  `suprnova::testing::TestClock`.** The framework read the wall clock with
  `chrono::Utc::now()` in about 170 places, and `tokio::time::pause` moves the
  timers of Tokio and not those reads, so a test of a signed URL that expires,
  a session that idles out, a scheduled task that is due, a window of a rate
  limit or a model that becomes prunable had to sleep. Every such read goes
  through `suprnova::clock::now()`, and so do the timestamps the `#[model]`
  macro writes, the due check of a scheduled task without a time zone and its
  one-run-a-minute gate, and the touched-at stamp of the session. Without the
  `testing` feature `now()` is `Utc::now()` and nothing else. With it,
  `TestClock::freeze()` and `TestClock::travel_to(at)` stop the clock of the
  current thread at a time you move with `advance` and `set`, until the guard
  is dropped, and `TestClock::scope(at, |clock| future)` holds a time across
  `.await` and on a multi-thread runtime; `clock.run(future)` carries it into
  a task you spawn. A clock of one test never reaches another test that runs
  beside it. Three reads keep the wall clock, because each is compared with a
  clock a test cannot move: the health endpoint, the retry time of a workflow
  run (compared with `NOW()` of the database), and the window of the
  `RateLimiter` facade (its cache key expires in real time). The in-memory
  driver of `RateLimitMiddleware` measures with `tokio::time::Instant`, which
  `tokio::time::pause` moves, and the Redis driver reads the clock. What you
  have to change: code of your own that reads the time for a decision reads
  `suprnova::clock::now()` when its tests should be able to move it.
- **`suprnova::schema::Schema` writes a migration without an identifier enum
  or `ColumnDef` chains.** A migration can build its tables with
  `Schema::create(manager, "posts", |t| { t.id(); t.string("title");
  t.timestamps(); })` and `Schema::table`, `Schema::drop`,
  `Schema::drop_if_exists`, `Schema::rename`, `Schema::has_table` and
  `Schema::has_column`. The layer builds SeaORM's `Table::create()`,
  `Table::alter()`, `Index` and `ForeignKey` statements and runs them on the
  `SchemaManager` the migration is given, so every statement runs on the
  migration's own connection and transaction, and a SeaORM migration and a
  `Schema` migration can sit in one `Migrator`. `Blueprint` has `id()` (a
  `BIGINT` auto-increment primary key), `foreign_id(name).constrained(table)`
  with `on_delete` and `on_update`, eighteen column types, the modifiers
  `nullable`, `default`, `unique` and `length`, `index` and `unique` over
  several columns, and in `Schema::table` also `rename_column`, `drop_column`,
  `drop_index` and `drop_foreign`. A column is `NOT NULL` unless it is
  `nullable()`. `timestamps()` and `soft_deletes()` create the `created_at`,
  `updated_at` and `deleted_at` columns as `VARCHAR(255)`, because
  `#[suprnova::model]` stores a `DateTime<Utc>` field as RFC 3339 text unless
  the field declares a cast; `timestamp_tz` with a native cast gives a native
  column. On SQLite, adding or dropping a foreign key on an existing table is
  an error that is returned before any statement of the call runs, and every
  other alteration runs as its own statement. The layer is not re-exported at
  the crate root, where `suprnova::Schema` is SeaORM's `Schema`.
  `make:migration` generates SeaORM migrations as before.

### Changed

- **Magnetar's `CeremonyStore` takes a named request for its atomic
  transition.** `transition_and_consume` and `transition_and_consume_exact`
  took six and seven positional strings, so a transposed selector or state
  compiled and acted on the wrong ceremony. Both take a `TransitionAndConsume
  { transition, expected, next, consume }` whose two ceremonies are
  `CeremonyRef { selector, kind }`, and the exact form takes the consume id as
  its second argument. A store that overrides either method changes its
  signature to match.
- **`delete_all` on a soft-delete model soft-deletes.** It issued `DELETE` on
  every model, so `Post::query().filter(...).delete_all()` permanently removed
  rows that a row-level `delete()` would have trashed. On a model declared
  with `soft_deletes` it now writes the tombstone, and `updated_at` when the
  model manages timestamps, and the rows stay readable through
  `with_trashed()`. `force_delete_all()` is the explicit hard delete.
  `Builder::without_global_scope::<S>()` and
  `Builder::without_global_scopes()` are supported chain methods.
- **`#[scopes]` refuses a scope written in the wrong form.** A method in a
  `#[scopes]` block that took `&mut Builder<User>`, named the model instead of
  `Self`, or returned nothing was left an ordinary method, and no scope
  reached the builder. It is now a compile error on the signature that names
  the accepted shape, `fn name(query: Builder<Self>, ...) -> Builder<Self>`. A
  method that handles no builder still passes through unchanged, and
  `#[not_scope]` marks a helper that does handle one.
- **`suprnova serve` runs the pending migrations once, when it starts, and no
  longer on every save.** The backend runs under a file watcher, and an
  application started with no subcommand migrates before it serves, so every
  save of a source file ran every pending migration against the developer's
  database, the draft of a migration saved a moment ago included. A migration
  that has run is not run again when its file changes, so the database kept
  the schema of the first draft. `serve` now runs `migrate` once before the
  backend starts and starts the watched backend with `serve --no-migrate`. The
  frontend and the processes of `Suprnova.toml` start first and do not wait
  for it. When a file under `src/migrations` changes after that, `serve` says
  that it was not run and that `suprnova migrate` runs it; with `--json` that
  is the new event `{"type":"migrations_changed","ts":...}`, and the run at
  the start shows as a process named `migrate`. `--migrate always` restores
  the old behaviour, and `--migrate never` or `--no-migrate` runs no migration
  at all. When the run at the start fails, the backend is left to migrate by
  itself for that session, as before: it does not serve until the migrations
  pass. A project with no `src/migrations` directory is left to migrate by
  itself as well.
- **`seed::clear()` is a supported function of the `testing` feature.** It was
  hidden from the documentation as an internal helper, and it is the only way
  for the tests of an application to reset the registry of the seeders, which
  is one for the process and which the guard of the test container does not
  reset. The manual told readers to call it and said in the same breath that
  it was hidden. It is documented now and compiled with the `testing` feature
  alone, which is a default feature, so a test suite needs no change. A build
  with `default-features = false` and without `testing` no longer has the
  function.
- **The paginators serialise to Laravel's JSON shape.** `LengthAwarePaginator`
  had `data`, the counters and `path`, and no URL of a page and no `links`;
  the simple paginator had `has_more`, and the cursor paginator had the
  cursors and no URL. A front end that was written for Laravel's paginator
  JSON, the pagination components of the Inertia starter kits among them,
  could not read them. The three now have the fields of Laravel's `toArray()`:
  `first_page_url`, `last_page_url`, `next_page_url`, `prev_page_url` and
  `links` on the paginator with a total, `current_page_url`, `first_page_url`,
  `next_page_url`, `prev_page_url`, `from` and `to` on the simple one, and
  `next_page_url` and `prev_page_url` on the cursor paginator. `links` has the
  window of pages and the labels of Laravel. A URL is the `path` and the page
  parameter, and a `path` with a query string keeps it. Every field that was
  there is still there, and `path` is still left out when it is not set.
  `LengthAwarePaginator::links()`, `next_page_url()` and `previous_page_url()`
  return the same values in Rust, and the other two paginators have their own.
  A page parameter that the `path` has already is replaced, so the URL of the
  current request can be given as the `path`, and a fragment of the `path`
  stays at the end of the URL.
- **A web push subscription that cannot be used is
  `WebPushError::InvalidSubscription`.** An endpoint that is no URL, that is
  not `https`, that names an address in place of a host, or that names a host
  that is no push service was `WebPushError::Internal`, with the text
  `internal:` in front. A key that is not what RFC 8291 asks for was
  `WebPushError::Encryption`: a `p256dh` or an `auth` that is no base64url or
  has the wrong length, a `p256dh` that is not in uncompressed form or is no
  point of the P-256 curve. Bad stored data read as a fault of the crate, and
  no caller could tell the two apart. The new variant says which rule refused
  the subscription and is not retryable. `WebPushChannel` handles it as it
  handles a subscription that is gone: it logs a warning and the dispatch
  succeeds, so a queue does not send the job again, with every channel that
  delivered before this one. A stored route that is no subscription at all is
  handled the same way. It was an internal error. No warning of the channel
  has the endpoint, because the path of an endpoint is the token that reaches
  the browser: a warning has the host and `endpoint_sha256`, the first 16
  hexadecimal digits of the SHA-256 of the stored endpoint, which finds the
  row. The warning for a subscription that is gone had the whole endpoint. The
  errors of the crate's own headers stay `Internal`, and a payload that is too
  large and a failure of the encryption stay `Encryption`. A `match` on
  `WebPushError` that names every variant has one more to name.
- **A database error on the payment webhook path keeps its type:
  `PaymentError::Database`.** The webhook route made a text of every database
  error, `PaymentError::Internal(format!("{e}"))`, in twenty-two places, so
  the code that decides what to do with a failed webhook could not ask whether
  the failure was a lost connection, which the next attempt cures, or a
  violated constraint, which none does. The new variant has the
  `sea_orm::DbErr` as its source, reachable with `error.source()` and
  `downcast_ref`, and `From<sea_orm::DbErr>` makes a statement end in `?`. The
  text of the error is what it was, and the route answers 503 for every
  database error as it did: the variant is what a later decision can be made
  on, and none is made yet. `Debug` prints the variant with the text of the
  database error and not with its `Debug`, which for a violated constraint
  names the values of the key. A `match` on `PaymentError` that names every
  variant has one more to name.
- **`suprnova::payments` names the types it exports.** The module had `pub use
  dto::*;`, the only glob export of the framework. It exported the modules of
  `dto` as well as the types, so every type had two public paths,
  `payments::StartSessionRequest` and
  `payments::session::StartSessionRequest`, and a type that was added to `dto`
  was public in `payments` without anybody deciding so. The twenty-five types
  are named now. The paths through the modules, `payments::session::` and its
  seven siblings, are gone: the modules are reached as
  `payments::dto::session`.
- **`Http::send` decides once whether an attempt is retried.** The loop had
  the decision twice, for a response with a status of the server and for an
  attempt that got no response: the same check of the policy, of the method
  and of the `retry_when` predicate, in two blocks that a change had to keep
  alike by hand. It is one function now, and the two outcomes are retried by
  one rule. What is retried and how long the request waits is what it was.
- **The parser of `#[model]` has no `#[allow(dead_code)]` left.** Sixteen
  suppressions on `ModelInput` and `RelationDecl` said that a later task would
  read the field. The tasks are done and the fields are read, so the
  suppressions hid nothing and would have hidden a field that a later change
  leaves unread. They are removed with the comments that named the tasks.
- **The dogfood application's `bootstrap.rs` imports what it uses.** Its
  import of the framework had a blanket `#[allow(unused_imports)]`, which hid
  that `singleton` was imported and never used, and would have hidden every
  later one. The suppression and the import are removed.
- **The `Data` derive has no module-wide
  `#![allow(clippy::collapsible_if)]`.** The attribute turned the lint off for
  the whole file with no reason given. It is removed, and the nested
  conditions it hid are written as one.
- **`mail::mailable_registry::render_outgoing` takes its values as a struct.**
  The function had fourteen arguments in a row, four of them `Vec<Address>`
  one after the other: the recipients, the copies, the blind copies and the
  reply addresses. Two of them in the wrong order compile, and the mail goes
  to the wrong list. It takes `any`, `mailable_name` and a
  `RenderOutgoingParams` now, whose fields are named. `RenderOutgoingParams`
  implements `Default`, so a caller names the fields it has. A caller of
  `render_outgoing` has to build the struct. The framework has one, the job
  that sends a queued mail.
- **`OutputFormat::WebP` is lossy and honours `quality`, and
  `OutputFormat::WebPLossless` is new.** WebP was always written lossless, so
  `.quality(80).format(OutputFormat::WebP)` gave the same file for every
  quality, and for a photo a larger file than the JPEG it replaced. `WebP` is
  lossy now, at the quality of the pipeline, which is 70 when none is set. The
  built-in driver writes it lossless in two cases, because the lossy form of
  WebP cannot hold the image: when a pixel is not fully opaque, and when a
  side is longer than 16383 px. `WebPLossless` is always lossless and ignores
  the quality. Both have the content type `image/webp` and the extension
  `webp`. The ImageMagick driver writes `WebP` lossy with its alpha channel,
  and passes `-define webp:lossless=true` for `WebPLossless`. What you have to
  change: a `match` on `OutputFormat` that names every variant, as a driver of
  your own has, needs an arm for `WebPLossless`. Code that needs the pixels of
  a WebP to be exact asks for `WebPLossless`. A WebP source that is resized
  and not converted is written as `WebP`, so an opaque one is written lossy.
- **`Subscription::update` changes the prices of a subscription on Stripe and
  on Paddle, and the Paddle adapter cancels at once when it is asked to.**
  `update` with `new_price_refs` returned `PaymentError::NotSupported` on both
  adapters, so a change of plan was a cancellation and a new subscription. The
  list is the set of prices the subscription has after the call: an item whose
  price is in the list keeps its id and its quantity, an item whose price is
  not in the list is removed, and a price that is new is added with the
  quantity 1, except in a swap: when the change removes exactly one item and
  adds exactly one price, the new price takes the quantity of the item it
  replaces, so ten seats of one plan become ten seats of the other. The
  adapter computes the change from a read of the subscription, and the change
  is not atomic: a change made at the provider between the read and the write
  can be undone (Paddle takes the whole list) or left in place (Stripe changes
  items one by one), and the returned subscription shows the result. An empty
  list, and a list that names a price twice, is `PaymentError::Validation`, on
  both adapters and on the mock. The new field
  `UpdateSubscriptionRequest::proration` takes a
  `suprnova::payments::Proration`: `ProrateNow` bills the difference at once,
  `ProrateAtRenewal` puts it on the next invoice, and `DoNotProrate` charges
  nothing for the change. `None` is `ProrateAtRenewal`. On Paddle, a change of
  prices in the same call as `cancel_at_period_end` or with an
  `idempotency_key` is `NotSupported`. `cancel(id, false)` of the Paddle
  adapter cancels the subscription at once, and `cancel(id, true)` cancels it
  at the end of the billing period; it cancelled at the end of the period for
  both. Every call of the Stripe and the Paddle adapter has a deadline of 30
  seconds. A read that gets no answer in that time is a
  `PaymentError::Provider` whose text ends in "timed out". A call that changes
  something is a `PaymentError::Provider` whose text says that the outcome is
  unknown: read the state at the provider before you send the call again. The
  text of an error that the Stripe or the Paddle adapter builds from an error
  of its SDK holds the operation and the kind and code of the provider's
  error, and never the provider's message, an id or a URL: a Stripe API error
  gives its type, its code and the HTTP status, a Paddle API error its type
  and code, and a transport error comes without the URL of the request. Stripe
  `void` of a payment that is already captured is a `Validation` error whose
  text does not name the payment. The `NotFound` errors of
  `MockPaymentProvider` carry no id. What you have to change: every struct
  literal of `UpdateSubscriptionRequest` names the new field, `proration:
  None` to keep the default. Code that called `cancel(id, false)` on Paddle
  and counted on a cancellation at the end of the period passes `true`. A test
  that read an id out of a `NotFound` error of the mock reads it from its own
  request.
- **A polymorphic relation takes a target with any key, loads nested
  relations, and can be touched.** Three limits of `MorphTo` are gone. The id
  of a morph relation was an `i64`, so a model with a `String`, UUID or ULID
  key could not be the target: the id is the value of the key of the target,
  and the `<name>_id` column of the child has the type of that key. All
  targets of one relation have keys of one type, and a relation that mixes
  them does not compile, nor does a child whose `<name>_id` field has another
  type. A parent's `MorphMany` or `MorphOne` is not checked against the
  child's `<name>_id`, so keep that field at the key type of every parent that
  owns it. The lazy read of a `MorphTo` finds the target by its key and
  applies no global scope of the target; the eager load runs the query of the
  target and applies its global scopes. A nested eager load through `MorphTo`,
  `with(["commentable.user"])`, returned an error: the loader groups the
  targets by their type and loads the rest of the path once for each type, and
  a target type that does not have the relation is an error that names the
  type and the relation, whether or not a row of that type was loaded.
  `#[model(touches = [...])]` took `BelongsTo` relations only: it takes the
  name of a `MorphTo` relation, and a save or a delete of the child writes the
  `updated_at` of its owner, inside the transaction of the write when there is
  one. An owner without timestamps is skipped, a soft-deleted owner is not
  touched, and a null `<name>_id` touches nothing. A `<name>_type` that names
  none of the targets is an error of the write: `create`, `save`, `update`,
  `delete` and `force_delete` (and their `_with_tx` forms) resolve every
  `MorphTo` owner of `touches` after the `Creating`, `Saving`, `Updating` and
  `Deleting` listeners have run and before the statement, from the values the
  statement writes, so a listener that rewrites `<name>_type` or `<name>_id`
  decides the owner, and an owner that cannot be resolved returns `Err` with
  no row written, no later event dispatched and no owner touched. An empty
  collection checks a dotted path of `Collection::load` and `load_missing`
  too. What you have to change: `MorphTo::morph_id` and the id in the
  `Unknown` variant of the generated enum are a `serde_json::Value`, so code
  that reads the id as an integer calls `as_i64()`. `<relation>_loaded()` of a
  `MorphTo` returns the generated enum.

### Fixed

- **Magnetar logs a lockout status failure before the sign-in fails closed.**
  The password plugin answered `503` when the lockout store could not report
  an identity's status and logged nothing, while the failed-attempt path
  beside it logged its error. The status path now logs `lockout status
  unavailable; failing closed` with the store's error; the response is
  unchanged.
- **Magnetar logs a failure to record a rejected two-factor attempt.**
  Re-enrollment, confirmation and recovery-code rotation discarded the error
  from the lockout store when they recorded a failed attempt, so a store fault
  during an attack left no trace. Each now logs a warning with the error; the
  rejection itself is unchanged.
- **Magnetar's Redis abuse limiter says why Redis failed.** Every client error
  became `shared abuse-limiter backend failed`, so a refused connection, a
  timeout and a script error read the same in the log of a limiter that fails
  sign-in closed. The message now ends with the Redis client's own description
  of the fault.
- **A stored session payload that fails to parse is logged.** The database
  session driver read a damaged payload as an empty session, which signs the
  visitor out, and logged nothing. It now logs a warning with the parse error
  and without the session id. A failed delete of an expired session row is
  logged as well.
- **A Live request that cannot be prepared says why in the log.** When the
  Live runtime could not be bound or a request could not be prepared, the
  server answered `500 Live request preparation failed` and logged nothing. It
  now logs the error with the route pattern and the stage, on the HTTP path
  and on the WebSocket upgrade path; the response is unchanged.
- **The NOWPayments adapter's HTTP failures name their cause.** A failed
  request, an unreadable response body and a body that is not JSON each became
  a fixed `PaymentError::Provider` message. Each now ends with the underlying
  error, down to the refused connection or elapsed deadline for a transport
  failure, and never includes the request URL, which carries the payment id.
- **A failed Live upload cleanup run is logged.** The background loop that
  retires expired uploads discarded the result of every run, so a store that
  kept failing left the uploads in place with nothing in the log. A failed run
  now logs a warning, and the loop retries on its next interval as before.
- **A model's cast storage aliases stay out of its rustdoc.** `#[model]` emits
  a `pub type __Suprnova_Cast_Storage_<field>` for each cast field, and each
  one appeared in the documentation of the application's own models. They are
  hidden now.
- **A factory insert fires the model's lifecycle events.** `Factory::create`
  and `create_many` inserted through SeaORM directly, so `creating`, `saving`,
  `created` and `saved` never fired and no observer saw a factory's rows. They
  now take the same insert `Model::create` takes: a `creating` observer can
  change the attributes or cancel the insert, and `created` runs for every
  row. `create_quietly()` and `create_many_quietly()` insert with the events
  muted. A model whose key is not auto-increment keeps the key its factory
  set.
- **`DATABASE_URL=mariadb://...` connects.** Only `mysql://` was recognised,
  so the scheme a MariaDB operator naturally writes failed at connect with no
  supporting driver. `mariadb://` is accepted for the primary connection,
  named connections and read replicas, the migrator, and
  `MariaDbVectorDriver::from_url`, and `DB::driver_title()` answers `MariaDB`
  for it. The vector driver's pool error no longer quotes the connection URL,
  which carries the password.
- **`QUEUE_DRIVER=sync` and `QUEUE_DRIVER=null` select their drivers.** Both
  drivers existed, but the environment bootstrap knew only `memory`, `redis`
  and `database`, so `sync` became an in-memory queue with a warning. A
  `QUEUE_DRIVER` that names no driver is now a boot error in production, where
  an in-memory queue taken by mistake loses every job at the next restart;
  elsewhere it still falls back to memory, and the warning lists the accepted
  names.
- **A chained job's `Job::delay()` applies.** A chain built each link's
  envelope with `available_at` set to now, so a job that declares a delay ran
  at once when it was a link of a chain, head or not. `ChainLink` now records
  the delay at build time, as it records the queue, and the link becomes
  available that long after it is reified: at dispatch for the head, and when
  the link before it completes for every other link. `ChainLink` gains the
  public field `delay_secs`, so code that builds one with a struct literal has
  to name it. Chain payloads written before the field existed decode as links
  with no delay.
- **Batches, chains and failed-job retries go through the queue fake.** Only
  the `Queue::push` family checked `Queue::fake()`.
  `Queue::batch().dispatch()` and `Queue::chain().dispatch()` went to the
  driver, so a faked test failed with "queue driver not initialized" when no
  driver was installed and pushed real jobs when one was.
  `Queue::retry_failed` and `Queue::retry_all_failed` did the same. All four
  record in the fake now and write to no driver. A batch is still stored in
  the batch repository, so the id the caller receives names a batch.
  `queue::testing` gains `batched()`, `assert_batched`, `assert_batch_count`,
  `assert_nothing_batched`, `chained()`, `assert_chained` and
  `assert_nothing_chained`, with the records `FakedBatch` and `FakedChain`.
  The jobs of a batch and the head of a chain are recorded as pushes too, so
  `assert_pushed` sees them.
- **The queue worker honors a retry hint.** A job that failed with
  `FrameworkError::RateLimited` carrying a `retry_after` was retried on its
  own backoff, so a queued web push that a push service refused with `429` and
  `Retry-After` went back to the service early, or waited far longer than it
  was asked to. The worker now releases such a job for the hinted time, capped
  at 24 hours (`queue::retry::RETRY_HINT_CEILING`). Every other failure keeps
  the job's backoff. `queue::retry::delay_after_failure` is the function the
  worker calls.
- **The middleware priority list orders the chain.**
  `append_middleware_priority` and `prepend_middleware_priority` recorded a
  list that nothing read, so middleware ran in the order it was registered
  whatever the list said, and an application that relied on the documented
  order could run authentication before the session was loaded. A chain is now
  put in the order of the list when it runs, for a matched route, the
  fallback, an unrouted request and a WebSocket upgrade alike. A middleware
  the list names moves in front of any middleware the list places after it.
  Every other middleware keeps its place, so one registered after
  `AuthMiddleware` still runs after it. The list orders global, group and
  route middleware together. It sees the middleware registered by type; a
  middleware boxed by hand with `into_boxed` and added with
  `.middleware_boxed(...)` keeps its place. An empty list costs one read per
  request.
- **`#[derive(Command)]` without a `description` keeps clap's own about
  text.** The derive called `.about("")` when `#[console(description =
  "...")]` was left out, which replaced the about text clap had taken from the
  struct's doc comment or from `#[command(about = "...")]`. A command
  described the way clap users describe one showed an empty line in the
  console's list of commands. The derive now sets the about text only when a
  `description` is given, and a `description` still overrides the doc comment.
  `CommandEntry::about()` returns the text the help shows, whichever of the
  three it came from; `CommandEntry::description` stays the attribute's text
  and is empty when the attribute has none.
- **`suprnova schedule:list --timezone=<zone>` is accepted.** The
  application's own `schedule:list` has taken `--timezone` since the flag
  shipped, and the manual shows it through the CLI, but the CLI's subcommand
  took no arguments and ended with `unexpected argument '--timezone'` and exit
  code 2. The CLI now takes the flag and hands it to the application, which
  checks the zone name.
- **The scaffolded `src/tasks/mod.rs` shows a task that compiles.** Its
  example implemented a `ScheduledTask` trait with `name` and `schedule`
  methods. The trait is `Task`, its only method is `handle`, and the name and
  the times a task runs at are set where it is registered. Every new project
  received the wrong example, and copying it gave an unresolved import. The
  comment now shows what `make:task` generates, with the registration in
  `src/schedule.rs`.
- **A render cache policy that varies on `FeatureVersion`, `ConfigVersion` or
  `Application(name)` is refused when it is registered.** Nothing gives these
  three dimensions a value, so a route that declared one could not build its
  key and every request for it went past the cache, while the route looked
  cached in the code. `try_render_cache` and `try_render_cache_group` now
  return an error that names the route or the group and the dimension, for a
  full policy and for a patch that brings the dimension in, so the application
  stops at boot. The other six dimensions register as before. This refuses one
  arrangement that cached before: a group whose policy declared one of the
  three, with a patch on every route that replaced the dimensions. The group
  is refused now, and the dimension is to be taken out of its policy.
- **Telemetry is exported, each signal to its own path, and a signal can have
  an endpoint of its own.** With the `otel` feature the OTLP exporters had no
  HTTP client: each one failed to build with `no http client specified`, no
  trace, metric or log left the process, and the error was logged before a log
  subscriber existed, so nothing showed it. The exporters have the blocking
  `reqwest` client now, and an exporter that cannot be built is reported after
  the subscriber is installed. `init_telemetry` also gave the base
  `OTEL_EXPORTER_OTLP_ENDPOINT` to the exporter of each signal, and the
  exporter uses an endpoint it is given in code as it is written, so the URL
  of every signal was the root of the collector, where a collector has
  nothing, and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`,
  `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` and `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`
  had no effect. Each signal is now sent to its own path under the base,
  `/v1/traces`, `/v1/metrics` and `/v1/logs`, and a signal with a variable of
  its own is sent to that URL as it is written, as the OTLP specification
  says. Traces can go to one collector and metrics to another. The base
  endpoint is still what turns telemetry on. `OtelConfig` has the three
  endpoints as fields, `traces_endpoint`, `metrics_endpoint` and
  `logs_endpoint`, which `from_env` reads, so code that builds an `OtelConfig`
  with every field named has three more to name. A signal whose endpoint is no
  URL is left out and reported, and the other signals are exported; the report
  never has the endpoint in it, which can carry a password or a token. A base
  endpoint that was given a path of a signal to make up for the missing one,
  such as `http://collector:4318/v1/traces`, is to be the base again: the path
  is added to it. An endpoint is a URL with the scheme `http` or `https` and a
  host: a blank base endpoint does not turn telemetry on, and a signal whose
  endpoint is a path alone is left out and reported, where it was built and
  sent nothing. `OTEL_EXPORTER_OTLP_COMPRESSION=gzip` works; `zstd` is not
  compiled in and leaves the signals out, with the reason in the log. What the
  exporters log about their own requests is printed and not exported, so a
  process at debug level does not send lines about its own sending without
  end.
- **The session middleware does not panic on a poisoned lock.** The session,
  the cookies that wait for the response, the remember tokens that wait to be
  revoked and the list of the fresh Magnetar sessions were locked with
  `.lock().unwrap()` in thirty places, which panics when an earlier panic left
  the lock poisoned. The list of the fresh sessions is shared with the
  clean-up task that runs after the request, so a panic in one request could
  end the clean-up of it. The locks are taken with a function that goes on
  with the value of a poisoned lock. The three lists are changed by code of
  the framework alone, which cannot panic between two writes, so they are
  whole after any panic. The session is changed by closures of the
  application: when a closure of `session_mut` panics and a Live action or a
  listener catches the panic, the request goes on and can read the session,
  but the middleware does not store it. It retires a Magnetar session that the
  request issued, takes back a remember cookie that the promotion of a second
  factor issued, answers 500, and the stored session stays as it was, which is
  what such a request did before. The policy of the framework for locks is
  that a poisoned lock is an error or is recovered, and never a panic.
- **`generate-routes` finds a form request by every name it is declared
  with.** The command read the source for `#[derive(FormRequest)]` and for the
  helper attribute `#[form_request(..)]`. An application writes neither: the
  crate root exports the derive as `FormRequestDerive`, because `FormRequest`
  is the trait there, and the short form is the attribute `#[request]`. A
  struct with one of those was left out of the generated routes, so its
  request type was missing in the TypeScript, and no message said so. The
  command reads `#[request]`, `#[derive(FormRequestDerive)]` and
  `#[derive(FormRequest)]`, each bare or behind `suprnova::`, and the helper
  attribute. `generate-types` read `InertiaProps` and `Data` in both forms
  already, and the three detectors ask one function.
- **`chunk_by_id` and `lazy_by_id` walk a table whose key is no `i64`.** The
  cursor of the walk was an `i64`, so a model with a `String` key, or with
  `unique_id = "uuid"`, `"uuid_v4"` or `"ulid"`, got the first batch and then
  an error. The closure had run on that batch by then, and a table that fits
  in one batch never gave the error. The cursor is the value of the key as the
  model has it, so an integer key and a string key both walk, in the order of
  the key. For a key with no order in time, a UUID v4, a row that is inserted
  during the walk with a key below the cursor is not seen by that walk. A key
  that cannot be a cursor is refused before the first query and before the
  closure sees a row: a composite key, and a key column that is no integer and
  no text, such as a native `uuid::Uuid`, a timestamp or a decimal. `lazy()`
  and `cursor()` walk through `lazy_by_id`, so both hold for them. What you
  have to change: a walk over a model with such a key returned `Ok` when the
  table fit in one batch, and returns the error now. Use `chunk()` for it.

### Security

- **Global scopes can no longer be bypassed by a trashed view, a chained
  opt-out, or an `or_where`.** Scopes were applied when `Model::query()` built
  the builder, which left three holes. `with_trashed()` and `only_trashed()`
  started from a bare builder and ran with no global scope, so on a model with
  a tenant scope they returned every tenant's rows. `query().or_where(...)`
  folded into the scope's own term and read `(tenant_id = ? OR ...)`, and on a
  soft-delete model `(deleted_at IS NULL OR ...)`. And
  `query().without_global_scope::<S>()` compiled and did nothing. The
  soft-delete filter and the registered scopes are now folded in when the
  query runs: the statement is `<scopes> AND <your terms>` with an `OR` group
  as one atom, the trashed views lift only the soft-delete filter, and an
  opt-out lands wherever it is chained. `update_all`, `delete_all` and
  `increment_each` resolve the same way, so a mass write reaches only the rows
  a read would return. A scope that reads per-request state reads it when the
  query runs.
- **Behind a proxy, `Request::ip()` is the address the proxy saw, and no
  longer one the client wrote.** A proxy adds the address it saw to the right
  end of `X-Forwarded-For` and leaves what was there, and `ip()` returned the
  left end. Behind nginx, Traefik, HAProxy or a cloud load balancer, a client
  that sent the header itself chose the address the application saw: a new
  rate-limit bucket with every request, and the address of a payment provider
  for a webhook that checks `remote_addr`. `ip()` now reads the header from
  the right and returns the first address that is no trusted proxy. It reads
  every line of the header as one list, reads an entry with a port
  (`203.0.113.5:54321`, `[2001:db8::5]:443`) as its address, and ends at an
  entry it cannot read, where the answer is the proxy that wrote that entry.
  `X-Real-IP` is read only when the request has no `X-Forwarded-For` at all.
  **What to check when you upgrade:** every proxy between the client and the
  application has to be in `APP_TRUSTED_PROXIES`, not the last one alone. A
  proxy that is not listed is taken for the client, and all of its clients
  share one address; that includes the address a load balancer adds behind the
  client's, as the external Application Load Balancer of Google Cloud does.
  `APP_TRUSTED_PROXIES` takes ranges in CIDR form for that,
  `10.0.0.5,173.245.48.0/20,2400:cb00::/32`, which is how the edge of a
  content delivery network is listed; in code it is
  `TrustedProxiesConfig::and_networks` with `ProxyNetwork`. A range must hold
  proxies and nothing else, because a client that connects from a trusted
  address is believed like a proxy, and the range of every address
  (`0.0.0.0/0`) is refused. A proxy that writes `X-Real-IP` alone has to
  remove the `X-Forwarded-For` of the client. An IPv4 address that is written
  as an IPv6 one (`::ffff:10.0.0.5`) is the IPv4 address, in the headers and
  for the peer. `Request::ips()` still returns the whole chain and is a
  record, nothing to decide by.
- **A cap on the WebSocket connections one client address holds open:
  `RateLimitMiddleware::connections_per_ip(n)`.** The only limit on open
  connections was the server-wide `SERVER_MAX_CONNECTIONS`, one number for
  every client together, so a single address that opened WebSockets and kept
  them could use all of it and lock every other client out of HTTP and
  WebSocket alike. The broadcasting and WebSocket chapters showed
  `connections_per_ip` on the `ws!` route; it did not exist. The middleware
  answers `429 Too Many Requests` when the address already holds `n` sockets.
  A socket is counted until its session ends, close frame or none, and an
  upgrade that a later middleware refuses gives its place back at once. The
  address is the one `Request::ip()` resolves through the trusted proxies; an
  IPv6 address is counted with its /64 network, because one client holds a
  whole /64. The counts are kept per process; a clone shares them, so one cap
  can guard several routes, and `open_for(address)` reads a count. On a route
  that is no WebSocket route the cap counts the requests being handled at one
  time and does not cover a streamed response.
  `Request::hold_for_connection(guard)` is the part other middleware can use:
  it keeps a guard alive until the socket of an upgrade ends, where a guard
  the middleware holds itself is dropped at the handshake.
- **Magnetar does not quote decrypted state in an error.** Four places decrypt
  the state of a ceremony or of a device session and decode it, and the error
  for state of another shape was the message of the JSON decoder, which quotes
  the value it could not read. That state holds challenges, session grants and
  tokens, and two of the errors are shown to the client. The error has the
  kind of the mistake and its position now, and nothing of the content. It can
  happen where a deployment changes the shape of the state while a ceremony is
  under way.
- **An encrypted cookie opens under its own name and in no other way.**
  Release 1.3.0 bound the name of a cookie into its encryption and kept a
  fallback that still opened a value written without the name, to be removed
  in 1.4.0, which was never released. While the fallback was there, such a
  value opened in every cookie, so the binding protected nothing against it.
  The fallback is removed for cookies. It stays for the other purposes, where
  it opens stored values that do not expire as a cookie does: read those with
  `decrypt_string_for_with_origin` and write them again. What you have to
  change: `Cookie::read_encrypted(wire)` is removed, use
  `Cookie::read_encrypted_for(name, wire)`. `Crypt::encrypt_string` and
  `Crypt::encrypt` with `CryptPurpose::Cookie` return an error, use
  `Cookie::encrypted(name, value)` or `Crypt::encrypt_string_for`.
  `Crypt::decrypt_string`, `decrypt_string_with_origin`, `decrypt` and
  `decrypt_with_origin` with `CryptPurpose::Cookie` return an error, use
  `Cookie::read_encrypted_for` or `Crypt::decrypt_string_for`. A cookie that
  was written before 1.3.0, or with `encrypt_string`, does not open any more.
  For the session cookie and the remember cookie the user signs in again, and
  for the maintenance bypass the operator visits the secret URL again. No
  request fails for it.

## 2.1.0 - 2026-09-18

### Added

- **Live ships the foundations of its component library.** A token stylesheet
  with a base layer arrives as the `ui-styles` runtime artifact when a
  document opts in with `with_suprnova_ui()`; every rule sits in the
  `suprnova-ui` cascade layer and every visual value is a `--sn-` token with
  light and dark values, so the skin is removable with nothing breaking.
  `live:add` installs a component as one directory under
  `templates/suprnova-ui/` from its manifest, keeps files you edited, and
  accepts a third-party manifest under its own root; the framework serves the
  vendored stylesheet and script at `/suprnova-ui/<component>/<file>`. The
  form family ships as Askama macros the checker now expands, so a library
  view passes `live:check` like any other. The `suprnova.` namespace is
  reserved to the library and the registry refuses it from any other crate.
- **The Live component library gains its overlay family.** Tooltip, collapsible
  and accordion, popover, a single-level dropdown menu, dialog, sheet, and
  drawer install with `live:add` beside the form family. Each owns its open
  state through the native primitive (`details`, the `popover` attribute,
  `dialog`) before any script, makes no Live request to open or close, returns
  focus to its trigger on close, and keeps its open state across a morph under
  a stable key with `live:preserve.self`.
- **The Live component library gains its feedback and navigation families.**
  Alert, skeleton, spinner, progress, empty state, toast region and flash
  region; header bar, footer, sidebar, breadcrumbs, tabs, pagination and load
  more install with `live:add` beside the form and overlay families. Feedback
  presents state the server or runtime holds: an alert's role follows its
  variant with a non-color cue, loading presentation is bound through
  `live:loading` and shows on the runtime's own timing, progress is the native
  element with a label and readout, the empty state's reason is server state,
  and a toast announces once without taking focus while a critical error also
  renders as an alert. Navigation keeps route semantics: anchors with real
  URLs, `aria-current` from the server, an explicit local or route mode for
  tabs and pagination, Live pagination reflected with `history.replaceState`
  and no history entry, and load more as a keyed append from a button. The
  `live_key` view filter lands with them: a `live:key` inside a `{% for %}`
  loop passes through it, and it enforces at render time the key rule the
  checker enforces on literal keys.
- **The Live component library gains its data display family, and with it
  the built-in set is complete.** Separator, scroll area, aspect image, card,
  badge, avatar and avatar group, list group, description list and stat card
  install with `live:add` beside the earlier families; every one keeps
  document order and native semantics, and every status carries text. The
  chart renders on the server through `charts-rs`: `render_chart` in
  `suprnova::live::charts` draws bar or line marks from bounded typed series
  as trusted SVG, and the macro places a summary and a data table beside it,
  so no charting script reaches the browser. The datatable is a native table
  with one island per table whose sort, filter and page are `#[url]` fields
  reflected into a shareable URL after every action.
- **The Live component library gains its live-native family, the last one.**
  The upload widget renders the shipped upload protocol's states from the
  runtime's progress root and claims nothing durable before the finalizing
  action; the live feed and notification bell carry the runtime's stream
  status announcements, so a degraded, reconnecting or closed stream says
  so; the account menu is a details disclosure with a CSRF-protected
  sign-out form and a documented stitch slot under RenderCache. The
  custom-element tier, input OTP, date picker and combobox, enhances native
  controls it never replaces: each `sn-` element is a light-DOM
  `HTMLElement` defined by its own vendored file and holds no form value, so
  the form submits the same value with the script blocked. The combobox
  refuses a listbox rendered for an older query.
- **Session blocking serializes the requests that carry one session.**
  `SESSION_BLOCK=true`, or `SessionConfig::block(SessionBlock::default())`,
  makes the session middleware hold a cache lock for the session from load
  to write, and `block_session` on a route or group enables it for those
  routes alone. Both bounds are yours, the hold and the wait, and a request
  that waits past the bound answers `503` with `Retry-After`. Without it,
  two concurrent requests on one session wrote back last-writer-wins, so a
  flash set by a redirect could be lost to a request that started earlier.

### Changed

- **Live's supported browser baseline is Chrome and Edge 114, Firefox 128, and
  Safari 17.** The floor rises from Chrome and Edge 111 and Safari 16.4 to the
  first releases that ship the native `popover` attribute the component
  library's overlays own their open state with. The compatibility matrix's
  minimum slots move with it; Firefox stays at 128.

### Fixed

- **A template's `live:key` reaches the Live runtime.** The checker validated
  `live:key` and the manual named it, but the browser runtime's morph
  identity, morph controls and preservation scopes read only the engine's
  `data-suprnova-live-key`, so a keyed control written as the checker
  requires had no effect and every library component wrote the key twice.
  The runtime now reads `live:key`, keeps the engine spelling for the roots
  it renders, refuses an element carrying both with different values, and
  the components write `live:key` alone. The form gallery's save form also
  gained the `.prevent` modifier it lacked, so a Live submit no longer
  reloads the page from the form's own query.
- **A Live form holding an empty number input or an unselected select
  submits.** The runtime read such a control's null value as a mismatch with
  itself and refused the whole submit, so the action never ran and the
  browser submitted the form natively. The search input's model binding also
  used a debounce the runtime does not accept; it now uses 250 ms.
- **`live:check` checks every element a view renders.** A view that called a
  macro splicing `caller()` with an empty call block, as the validation summary
  is called, rendered no content after that call to the checker, so the
  component proved clean while the rest of the view went unchecked. The empty
  call is now empty content, and a view that renders nothing fails the check.
  Fixing it exposed errors the dogfood form gallery had hidden.
- **A declared model debounce is 100, 250, or 500 milliseconds.**
  `#[model(debounce = N)]` accepted 1 to 60000 ms, but the directive grammar
  the checker and the browser runtime share lists three durations, so any
  other value could never be bound by a template; it now fails to compile.
  `live:error` also accepts an action as its target, as a validation summary
  names one, matching what the runtime resolves.
- **A Live form of more than seven model fields submits.** The browser runtime
  refused any request carrying more than eight operations or model proposals,
  and any response with more than sixteen validation entries or eight events,
  though the framework's server accepts 128 of each; the refused submit never
  left the browser and was reported as a network failure. The browser now
  admits the server's counts, `live:check` refuses a `live:submit` form of
  more than 127 model fields, and a request refused for a limit is reported as
  a resource limit that shows the action's error feedback.
- **The combobox stays responsive and shows what the server answered.** Text
  that no option matched froze the page, because the element's observer
  watched attributes its own render rewrote even when nothing changed. The
  element also filtered the server's options by substring, hiding results a
  server search matched another way, such as an accent-insensitive or code
  match. It now writes only what changed, shows every option while the
  listbox answers the input's current text, keeps an answer to older text
  hidden, and filters by the typed text only for a fixed list, which
  `remote=false` selects.
- **A library custom element binds once however a morph moves it.** The
  combobox, input OTP, date picker, and password input bound their listeners
  on every connection, and the dialog, sheet, and drawer guarded on an
  attribute a morph removes, so a moved element answered one click twice and
  the password reveal toggled back at once. Every element now binds per
  connection, releases its listeners and observers when it leaves the
  document, and keeps them across an atomic move.
- **A toast holds while the pointer is anywhere on it or focus is inside it.**
  The region resumed its timers when the pointer left any child element, so
  moving from a toast's text to its padding let it time out under the
  pointer, and a toast could hide while its dismiss button had focus.
- **Nested tabs act on their own tabs.** A local tabs instance selected every
  tab below it and handled the events of a nested instance, so a click on an
  inner tab hid the outer panel.
- **The tooltip bubble stays open while the pointer moves onto it.** The
  bubble ignored the pointer, so it hid as the pointer left the trigger and
  its text could not be read or selected.
- **The select's dropdown indicator follows the text color.** It was a
  data-URI SVG, whose `currentColor` does not inherit the document's color, so
  it drew black on the dark scheme's surface.
- **The form controls show the island's values.** No form macro took a value,
  so a number input mounted at 1 rendered empty and a submit that changed
  nothing proposed an empty value. Each value control now takes `value=`,
  `checked=`, or `selected=`, radio and checkbox group inputs are keyed by
  value so a choice the user has not sent survives a re-render, and
  `authority=` marks the render that must replace what the user typed.
- **A checkbox group proposes the list of checked values.** The runtime read
  every checkbox as a boolean, so a group whose boxes disagreed could not be
  submitted. A checkbox group of any size, and any field that more than one
  checkbox binds, now proposes the checked values in document order; a single
  checkbox stays a boolean.
- **A model proposal its field cannot decode is a validation error on that
  field.** A proposal such as null for a `u64` field or a boolean for a list
  field was dropped silently: the action ran and the response carried no
  validation. The field now reports the error through `live:error` and keeps
  its value, and the action does not run.
- **The checker, the `live_key` filter, and the runtime accept one key
  alphabet.** The checker and the filter accepted a key beginning with `_`,
  `-`, `.`, or `:`, which the runtime refuses, so the island's first morph
  failed. A key now begins with an ASCII letter or digit everywhere, and
  `live:check` holds the element ids inside an island to the rule the runtime
  checks, refusing an invalid id (`invalid_element_id`) and a repeated one
  (`duplicate_element_id`), a literal id inside a loop included.
- **`live_key_digest` keys any value.** `live_key` fails the island's render
  for a value outside the key alphabet, so a row keyed by an email address
  failed the island for every viewer. The new filter turns any value into a
  stable key, one value always yielding the same key.
- **`live:check` checks a loop or match binding as that binding.** Inside a
  macro body, a name that a `for`, a `match` arm, or an `if let` bound was
  checked as the macro parameter of the same name, so a literal argument
  proved a directive that the loop's own values render.
- **`render_chart` returns an error for a value beyond 1e9.** The renderer's
  axis arithmetic overflowed and panicked from about 1e12; a value whose
  magnitude exceeds 1e9 is now an input error.
- **An application that cannot read its vendored components refuses to
  start.** `try_live_ui_assets()` reads `templates/suprnova-ui/` under the
  application base path on each request, so an application started
  elsewhere, such as from a container image that holds only the binary,
  answered 404 for every component stylesheet and script and started
  cleanly. Installing the route now fails and names the directory.
- **`live:add` replaces a file you never edited.** It compared bytes only, so
  after a library update it kept every installed file and reported it edited
  locally. It now records each file's digest beside the component and
  replaces a file whose bytes still match the record; a file you edited, or
  one no record vouches for, is kept and reported.
- **`live:add --manifest` refuses a file that is a symbolic link.** Each
  third-party file was read through links, so a component could install the
  bytes of any readable file as a template. A named file must be a regular
  file inside the manifest's directory.
- **A model edit that a render replaced is sent when it is typed again.** The
  browser compared each edit with the value it last proposed, so after a
  refused value and a render that replaced it, such as a reset, typing the same
  value again sent nothing: the control showed it with no error while the
  island held another value. The render an island applies is now the baseline
  the next edit is compared with, and a field's dirty state compares with the
  value that render gave its control.
- **A tooltip can be dismissed where it is shown.** A bubble that covers
  content could be dismissed only by moving the pointer or focus away, which
  WCAG 2.2 success criterion 1.4.13 does not accept. Escape now hides it with
  neither moved, and the next hover or focus of that trigger shows it again.
  The bubble still shows with no script in the page; the new `sn-tooltip`
  element carries the dismissal alone, and `live:add tooltip` installs it.

## 2.0.2 - 2026-09-14

### Changed

- **The Live endpoints carry no version segment.** `/__live/v1/action`,
  `/__live/v1/upload`, `/__live/v1/assets/*`, and the `/__live/v1/async/*`
  family now live at the same paths without `/v1`: `/__live/action`,
  `/__live/upload`, `/__live/assets/*`, `/__live/async/*`. Suprnova's version
  is the git tag and the browser runtime ships in lockstep with the framework,
  so a second version inside the URL space promised an evolution path that
  would never be used. Applications are unaffected: the framework registers
  these routes and the runtime builds every URL, and hand-written references
  to `/__live/` paths were never supported.

### Fixed

- **Every issuance the Live per-scope limit admits answers with a subscription
  that connects.** Concurrent issuances of one scope in the same millisecond
  mint identical descriptors, and the host's credential store kept only the
  last secret minted for a descriptor, so the earlier requests answered 403
  `async_authority_invalid` from the connect that issuance performs. About one
  issuance in five hundred also answered 503 `async_unavailable`, because the
  claims it published while its envelope context was built shared one slot
  with every concurrent issuance. A descriptor now keeps every unconsumed
  secret until each is consumed or expires, and the claims under construction
  are keyed by subscription id.

### Security

- **The lockfile takes the rustls TLS 1.3 handshake fix.** `rustls` 0.23.45
  replaces 0.23.40, which accepted TLS 1.3 handshake messages across
  encryption level boundaries (RUSTSEC-2026-0285, published on the release
  day); `aws-lc-rs` and `rustls-webpki` move with it. Every HTTPS client in
  the framework, from the HTTP facade to the Qdrant and payment adapters,
  resolves the fixed release.
- **A Live stream ends with the session that opened it.** An asynchronous
  membership was re-authorized against its Gate before every delivery but
  never against its session: a browser that logged out, or whose session was
  revoked, kept receiving events until the stream itself closed. Destroying a
  session on a node now retires every membership it opened there at once, for
  a plain logout, session invalidation, id regeneration, and "log out
  everywhere" alike, and delivery re-checks each membership's session against
  the session store at most once per ten seconds, so a session destroyed on
  another node stops receiving events within that interval.
- **A request's `Cache-Control` directives are honored by RenderCache.** A
  request carrying `no-cache` was answered from storage with `Age`, and a cold
  request carrying `no-store` seeded the cache for the next request.
  `no-store` now bypasses lookup and publication alike, and `no-cache` skips
  the lookup so the request is answered by a fresh render. Found by the
  2026-09-13 adversarial audit (ASTRA-13).
- **A render without a snapshot is never published.** When the snapshot
  transaction could not open, RenderCache rendered without a read view and
  still published if the generation reread agreed, so a render that
  interleaved with a concurrent multi-row write could store a mix of two
  database states. Such a render is now served but not stored (decline reason
  `snapshot_unavailable`), and its rebuild lease is released. Found by the
  2026-09-13 adversarial audit (ASTRA-08).
- **A cached response replays its `Content-Encoding`.** A pre-compressed body
  was stored without its content coding, so a hit served gzip bytes as plain
  text. The coding is stored with the body and replayed on every hit. Found by
  the 2026-09-13 adversarial audit (ASTRA-04).
- **A HEAD request never seeds the GET representation.** A cold HEAD on a
  route that renders nothing for HEAD stored an empty body under the key every
  GET shares, so later GETs answered zero bytes. A HEAD miss is now served as
  rendered and not stored (decline reason `head_render`). Found by the
  2026-09-13 adversarial audit (ASTRA-03).
- **The Live per-scope subscription limit holds under concurrency.** Issuance
  counted a scope's subscriptions, released the lock, awaited the authorizer,
  and inserted afterwards, so a burst of concurrent requests could all pass
  the count and all be admitted once authorization returned, well past the
  advertised limit of 512 per scope. The slot is now reserved under the same
  lock as the count, released on every error path, and handed to the record
  when it lands. Found by the 2026-09-13 adversarial audit (ASTRA-07).
- **A Live subscription stops receiving events once its Gate denies.** An
  existing asynchronous membership kept receiving newly published events after
  the stream's authorization Gate was redefined to deny the principal, because
  delivery compared the subscription's own retained authorization memo with
  itself. New subscriptions were correctly refused; the old stream was not.
  The runtime now records the principal a subscription was issued to, asks the
  Gate again before every delivery, and retires a membership the Gate no
  longer allows. Found by the 2026-09-13 adversarial audit (ASTRA-01).
- **A Live action declaring `transaction = "required"` is refused at
  registration.** The host's transaction port is a documented no-op, so the
  policy promised atomicity it never provided: each write committed on its own
  and nothing rolled back when a later stage failed. `LiveRegistry` now fails
  with `RegistryErrorKind::RequiredTransactionUnsupported` for such a
  component until the port installs a real ambient transaction; actions
  without the policy register as before. Found by the 2026-09-13 adversarial
  audit (ASTRA-05).
- **A cached route's named-connection reads stay on their connection.** A
  RenderCache miss renders inside a snapshot transaction on the primary
  database, and query routing preferred that transaction over a query's own
  `on("name")` or a model's declared connection, so opting a route into the
  cache changed which database its code read from. A tenant or auxiliary
  database read could return the primary's row, fail on a table the primary
  lacks, or publish the wrong content under a valid key. Reads bound for
  another connection now run there even inside an ambient transaction, and a
  render that read outside its snapshot is served but not stored (decline
  reason `foreign_connection_read`). Found by the 2026-09-13 adversarial audit
  (ASTRA-06).
- **A data write and its RenderCache invalidation commit together.** On the
  autocommit path, a model save, a query-builder write, or a raw statement
  landed its row first and advanced the dependency generations in a second
  transaction afterwards. When that second transaction failed, the row was
  durable, the API returned an error, and every cached page that depended on
  the row kept passing its coherence check and serving the pre-write content:
  a visibility, entitlement, or deletion change could stay invisible until the
  next successful invalidation. Every write terminal now runs the row write
  and its advancement inside one transaction opened for the purpose, so both
  commit or neither does. A ledger table that vanishes after RenderCache
  decided it was present now fails the write instead of being skipped with a
  warning. A write bound for a named connection, whose ledger lives on the
  primary, keeps its separate advancement; if that advancement fails, the
  process stops serving stored entries until one succeeds. Found by the
  2026-09-13 adversarial audit (ASTRA-10).
- **A handler's `Vary` contract is enforced before RenderCache stores.** A
  handler that varied its body on a request header of its own and said so with
  `Vary` was stored under a key built from the route policy alone, so the
  first variant's body was served to every other variant, with the `Vary`
  header missing from the hit. Wherever that header selected user, device, or
  experiment-specific content, one request's content reached another's.
  RenderCache now parses the response's `Vary` before publication and declines
  to store when it names `*` or a field the policy does not declare as a key
  dimension (decline reason `vary_undeclared`). Found by the 2026-09-13
  adversarial audit (ASTRA-09).
- **A handler's `Cache-Control: no-store` is honored by RenderCache.** A route
  opted into the cache stored a response whose handler said `no-store` and
  replayed it under the policy's own `public, max-age=60, s-maxage=60`, so a
  handler's "do not store" was ignored on the server and rewritten for every
  browser and proxy downstream. The eligibility check now reads the response's
  `Cache-Control` and declines storage on the `no-store` token (decline reason
  `no_store_directive`), and the declined response goes out exactly as the
  handler built it. Found by the 2026-09-13 adversarial audit (ASTRA-02).
- **A per-response CSP nonce is never replayed from the cache.** A public page
  that minted a nonce on every render and named it in
  `Content-Security-Policy` was stored as an ordinary complete entry, so every
  later hit carried the first render's nonce in both the header and the inline
  script. A nonce is the authorization token for inline script in one
  response; replaying it made that token readable to anyone who could fetch
  the page. RenderCache now declines to store such a response (decline reason
  `nonce_source_policy`); a hash-based policy caches as before, and stitched
  Live documents keep issuing a fresh nonce per hit. Found by the 2026-09-13
  adversarial audit (ASTRA-12).
- **A cached response keeps its isolation and execution headers.** RenderCache
  stored a response's `Content-Disposition`, `Cross-Origin-Opener-Policy`,
  `Cross-Origin-Embedder-Policy`, `Cross-Origin-Resource-Policy`,
  `Permissions-Policy`, and `X-Frame-Options` nowhere, so a cache hit served
  the same bytes without them. An HTML export that downloaded as an attachment
  on the first request rendered inline under the application's origin on the
  second, where any markup it carried ran with same-origin authority. The six
  headers now replay byte for byte from the stored representation. Found by
  the 2026-09-13 adversarial audit (ASTRA-11).
- **The lockfile sheds one unsound and three yanked dependency releases.**
  `event-listener` 5.4.2 replaces 5.4.1, whose stack-allocated listener was
  unconditionally `Send`/`Sync` and let a `!Send` tag cross threads in safe
  code (RUSTSEC-2026-0221); Suprnova's dependencies only use untagged events,
  so the unsound path was never exercised here. `spin` 0.9.9 and 0.10.1 and
  `chacha20` 0.10.2 replace releases their publishers had yanked, and
  `concurrent-queue` leaves the tree entirely.

## 2.0.1 - 2026-09-12

### Fixed

- **A `redis://` URL with a database index selects that database everywhere.**
  The queue driver and the fanout broadcast hub each carry a sea-streamer
  producer beside their direct redis connections, and sea-streamer does not
  read the logical database from the URL's path - so a queue pointed at
  `redis://host:6379/3` pushed jobs into database `0` while its consumer half
  waited on database `3`, and the fanout hub operated on `0` outright. Both
  now carry the index across explicitly, with the same parsing rule the redis
  client applies. A URL without a path keeps selecting database `0`, so
  nothing changes for the common form.
- **`suprnova generate-types` ends its output with one newline.** The blank
  line that separates one interface from the next was also written after the
  last one, so a project that enforces `git diff --check` failed with `new
  blank line at EOF` on a file it could not correct by hand: the next
  regeneration wrote the blank line straight back. Only the end of the file
  changes; the blank lines between declarations stay.

- **A scaffolded login or registration form shows its validation errors.**
  The generated auth controller declared an `errors` prop on `LoginProps`
  and `RegisterProps` and sent it as `None`. The framework seeds `errors` on
  every Inertia page from the session-flashed validation bag, and an
  explicit prop of the same name replaces that seed, so the page received
  `errors: null` and invalid credentials returned to a form that displayed
  nothing. Both props are now empty, the Login and Register pages of all
  three frontends read `useForm().errors`, and the scaffold's
  `inertia-props.ts` is the byte-exact output of `suprnova generate-types`
  for the scaffold's controllers, so a project's first regeneration no
  longer rewrites a file nobody edited.

- **A scaffolded application serves its built frontend.** The generated
  `routes.rs` registered no static-file fallback, so once Vite's dev server
  was not running every `/assets/*` URL in the HTML shell answered `404`,
  including inside the production image the scaffold's `Dockerfile` builds.
  `routes.rs` now ends with `fallback!(StaticFiles::public().handler())`:
  declared routes still win, dotfiles such as
  `public/assets/.vite/manifest.json` and path traversal are refused, and
  an unknown URL still renders the Inertia `Error` page.

- **A scaffolded application verifies email addresses and resets
  passwords.** Registration created and signed in the user without sending
  verification mail, and no route offered email verification or password
  recovery, although the generated `User` already implemented
  `MustVerifyEmail` and `CanResetPassword` and the `auth_flow_tokens`
  migration already shipped. Registration now mails a verification link
  through `EmailVerification::send_link` and continues to `/verify-email`,
  which shows the notice, resends the link, and consumes it on
  `/verify-email/verify` for the signed-in owner only. `/forgot-password`
  mails a reset link to a verified address (an unknown or unverified
  address gets the same answer and no mail) and `/reset-password` rotates
  the password through `PasswordReset::complete_with_outcome`, refusing to
  finish while the account's other sessions or remember-me tokens could
  not be revoked. The Vue, React and Svelte starters ship the
  `ForgotPassword`, `ResetPassword` and `VerifyEmail` pages and a "Forgot
  your password?" link on the login page. Links are built with `url::to`,
  so `APP_URL` must name the address users reach the application at, and
  registration needs a working mail transport: the `.env` the scaffold
  writes points `MAIL_DRIVER=smtp` at a local catcher on port 1025 (the
  Mailpit that `suprnova docker:compose --with-mailpit` adds), or set
  `MAIL_DRIVER=log` to print each message, link included, to the server log.

- **A fresh Svelte scaffold builds against `@inertiajs/svelte` 3.7.** The
  generated `main.ts` declared an `async setup`, and `@inertiajs/svelte` 3.7
  types `setup` as returning `SvelteRenderResult | void`, so a project
  scaffolded today (the template asks for `^3.6.1`, which now resolves to
  3.7.1) failed `svelte-check` inside `npm run build` before a single page
  had been written. `setup` is synchronous now and chains the translation
  catalog load onto the mount, so the ordering the template describes is
  unchanged.

### Documentation

- **The six locale mirrors of the 2.0.0 chapters follow the manual's own
  conventions.** The chapters translated since 1.3.7 wrapped Japanese and
  Simplified Chinese prose mid-sentence (1,653 line breaks that rendered as
  stray spaces), rendered 59 terms differently from the rest of their
  locale, translated 9 repeated headings a second way, and left 2 quotes
  unpaired. All of that is aligned with the older chapters, so a reader of
  any locale sees one vocabulary and unbroken sentences across the manual.

### Upgrading

- **These are scaffold fixes; an application generated with 2.0.0 keeps
  its generated files.** Upgrading the framework crate changes nothing in
  `src/` or `frontend/`. To pick the fixes up in an existing project, make
  the same edits by hand: drop the `errors` field from `LoginProps` and
  `RegisterProps` and read `useForm().errors` in the pages; add
  `fallback!(StaticFiles::public().handler())` as the last entry of
  `routes!`; and copy the `email_verification` and `password_reset`
  controllers, their routes, and the three auth pages from a project
  generated with 2.0.1. The `generate-types` output changes only at the
  end of the file.

## 2.0.0 - 2026-09-10

### Security

- **A bearer token and a web session are now separate identities.** The
  request-scoped user cache kept one current-user slot that everything wrote
  to and everything read from, so a browser session hydrated by
  `SessionMiddleware` satisfied a `TokenGuard` on the same request, and a user
  resolved for the web guard was handed back to code that had asked for the
  API guard. Bearer credentials now carry their own provenance in that cache:
  `BearerTokenMiddleware` records the identifier it validated in a bearer slot
  of its own, `TokenGuard` resolves and caches the full user there, and only
  something that arrived through a bearer credential can satisfy a token
  guard. Session guards are cached per guard name in the same place, so
  `Auth::guard("admin").user()` and `Auth::guard("web").user()` in one request
  no longer resolve to whichever of them ran first. The generic slots remain
  as a compatibility view for the static `Auth` facade, mirrored from the
  configured default guard alone, so `Auth::id()`, `Auth::check()` and
  `AuthMiddleware` behave exactly as they did for an application with one
  guard and for a token-only request that never installs a session.

- **A named guard keeps its own principal, its own remember-me credential, and
  its own revocation.** Logging in through `Auth::guard("admin")` wrote the
  identifier into the same session key the default guard uses, so two guards
  in one application shared one principal and signing out of either signed out
  of both. In the persisted session each guard now owns its entry under the
  `_auth_guards` map, and the remember-me cookie carries a guard-tagged carrier
  (`suprnova.remember.v1:` followed by the guard name and the credential) so a
  cookie issued for one guard cannot re-authenticate another. A cookie without
  that prefix is read as the default guard's, which is exactly what a cookie
  issued by an earlier release is, so nobody is signed out by the upgrade; a
  carrier naming a version this build does not understand is refused rather
  than guessed at. Revocation follows the same boundary: signing out, and the
  middleware's own rotation path, retire the exact selector the owning guard
  issued rather than every credential the user holds.

- **`BasicAuthMiddleware` no longer accepts a stale session slot as proof.**
  Its non-stateless form skipped the `Authorization` header whenever
  `Auth::check()` was true, and `Auth::check()` reads the request-scoped
  current-user slot, which anything earlier in the chain could have populated.
  It now asks for the persisted session principal of the guard it was
  configured with, and refuses outright when that guard is absent or is not a
  stateful guard, so a request is admitted without credentials only when a
  real session row says who it belongs to. The stateless form always re-read
  the header and is unchanged.

- **Remember-me credentials rotate as one atomic replacement.** Rotation used
  to remove the accepted credential and insert its successor as two writes: a
  failure between them consumed a valid credential and left the visitor with
  no way back in, and a crash left both rows live. The default schema now
  replaces one exact, still-valid row with its prepared successor in a single
  operation, and a store that cannot make the conditional removal and the
  replacement insert atomic fails closed rather than performing them
  separately. Selector matching is exact, so a credential is never retired by
  a prefix collision, and a synchronous identity transition inside a handler
  queues the exact credential it invalidated for revocation at the end of the
  request instead of leaving it live.

- **Two-factor admission is serialized, and a lockout write that fails takes
  the request down with it.** Two workers proving the same code could each
  read the attempt counter before either wrote it, so a brute-force budget
  admitted more attempts than it allowed. Verification now reserves attempt
  capacity inside the same serialized store operation that admits the
  attempt, returning both the reservation and any finalized-failure state
  observed in that one decision; a ceremony that cannot commit cancels its
  prepared proof, and the cancel path's default fails closed so an existing
  verifier implementation cannot silently leak reserved capacity. A lockout
  counter write that errors is no longer swallowed: the attempt is refused.
  Promoting a session that is waiting on a second factor is one atomic
  migration, and the bearer credential is suppressed before the storage call
  is awaited, so a timeout or a backend failure can never leave a credential
  attached to a session the framework did not commit.

- **Session rotation fails closed.** Rotating a session id destroys the old
  row and writes a new one. A destroy that errored was logged and stepped
  over, which left the previous authenticated row replayable by anyone
  holding the old cookie. The middleware now returns before writing the
  replacement and before issuing the new id, and expires the browser's old
  credential on the way out. Separately, the cookie that carries a fresh or
  rotated session is built before the row is committed: a cookie that cannot
  be constructed used to leave a session in the store that no browser could
  ever present, and now leaves nothing behind at all.

- **A session that outlives its user stops authorizing, and revoking a user's
  sessions reaches the named guards.** `AuthMiddleware` treated the presence
  of a persisted identifier as proof of an identity, so a deleted or
  soft-deleted user kept passing every guarded route until the session
  expired. It now resolves the user through the provider and clears the stale
  slot when the provider finds nothing; an application with no user provider
  bound at all keeps the identifier-only fast path, recognized by its own
  error rather than by matching message text, and every other provider
  failure is an error rather than a pass. `destroy_all_for_user` matched only
  the indexed `user_id` column, which is null for a session authenticated
  through a named guard alone, so those sessions survived a
  "sign out everywhere". It now compares the guard identities inside each
  surviving payload as well.

- **Device-authorization ceremonies transition atomically and are validated
  before consumption.** Approving a device code read the ceremony, then
  consumed it, then wrote the grant, so a replacement issued under the same
  selector between the read and the consume could be consumed instead of the
  record that was actually approved. The store contract now binds the
  consuming transaction to the exact record a prior read observed, and
  transitions one ceremony while consuming another in a single atomic step.
  Both methods default to failing closed, so an external store implementation
  stays source-compatible without silently getting the weaker behaviour.

- **A provider-token refresh whose outcome is unknown is fenced, not
  retried.** A linked-account refresh that started and then lost its answer
  left an ordinary claim that expired on schedule, so a second worker
  refreshed the same grant and one of the two results was discarded, taking a
  single-use refresh token with it. Starting an exchange now replaces the
  claim's owner with a reserved exchange owner while preserving the original
  deadline, so followers can tell a live exchange from an abandoned one, and
  a store must never reclaim a row whose owner is in that reserved namespace.
  Stores that do not implement the fence fail closed.

- **Web Push refuses to send through a transport that might follow a
  redirect.** `EndpointPolicy::Strict` validates the subscription endpoint
  URL, but validation only ever covered the initial URL: a client that
  follows redirects turns a validated endpoint into a `3xx` to anywhere, and
  reqwest follows redirects by default. A client this crate builds now has
  redirects forcibly disabled, and the new
  `WebPushClient::with_client_builder` applies every option a caller wants
  (proxy, TLS pinning, timeouts) while overriding the redirect policy.
  `WebPushClient::with_client`, which takes an already-built client whose
  redirect policy cannot be inspected, now refuses to send under `Strict`
  with `WebPushError::UnconfinedRedirects`, before encryption and before any
  request. `WebPushClient::allow_unconfined_redirects` is the explicit opt-out
  for a caller who knows their client is safe.

- **A signed URL is bound to the exact path it was signed for.** Signing and
  verification both trimmed a trailing slash before hashing, which made
  `/orders/1` and `/orders/1/` one signature, and made a proxy that appends a
  slash indistinguishable from a client that edits the path. The path is now
  hashed exactly as it appears, so a signature covers one path and one path
  only.

- **A cache key can no longer address a lock or a tag index.** Redis lock,
  tag, and key-tag records lived under a NUL sentinel after the configured
  prefix, and a caller-supplied key beginning with that sentinel landed in
  the same space, so a `Cache::forget` could release a distributed lock
  somebody else was holding. Values and each internal record type now carry
  distinct namespace components ahead of the caller's key, so the two spaces
  cannot meet. An ordinary key is stored exactly where it was before, so
  nothing already cached is orphaned. The in-memory driver got the same
  separation.

- **Payment webhooks reject what they cannot identify and classify duplicates
  by the database, not by message text.** A provider event with a missing,
  non-string, or whitespace-only identifier used to enter the shared
  idempotency namespace under a blank key, where it collided with every other
  such event; it is now rejected before any state is written. A concurrent
  duplicate is recognized from SeaORM's structured unique-violation code
  rather than from human-readable error text an unrelated failure can also
  contain, and only a re-read of a committed `processed_at` is acknowledged
  as one, so a mirror-write failure stays retryable. Stripe's signature
  timestamp is compared with an unsigned absolute difference, so an extreme
  `t=` value returns a signature error instead of overflowing, and a negative
  configured tolerance accepts only an exact match. The webhook route
  preserves the typed status of a body it refused, so an over-cap body is
  still a `413` rather than a flattened `400`.

- **A non-idempotent HTTP request is no longer replayed after a transport
  error.** The retry policy already required the explicit
  `retry_non_idempotent` opt-in before replaying a `POST` or `PATCH` that
  answered `5xx`, but the transport-error branch beside it did not check,
  so a request whose connection dropped after the server had accepted it was
  sent again. Both branches now apply the same rule.

- **Session lifetimes cannot overflow into mass expiry.** `SESSION_LIFETIME`
  and `SESSION_REMEMBER_LIFETIME` are minutes multiplied by sixty and then
  added to a stored timestamp in date arithmetic that panics on overflow, so
  an oversized value either aborted the process or wrapped into a deadline in
  the past that expired every session at once. Both are clamped to
  `MAX_SESSION_LIFETIME_MINUTES` before the multiplication, the database
  driver caps the same way for a configuration built in code, and a garbage
  collection cutoff that cannot be represented is skipped rather than sent to
  the database, which is the difference between collecting nothing and
  collecting everything.

- **Machine-to-machine cache identities are unambiguous.** The token broker's
  cache key concatenated the provider, the client, and the normalized scope
  set, so two different requests whose components happened to run together
  into the same string shared one cached token. The key is now a versioned
  domain with length-prefixed components, which no combination of inputs can
  make collide.

- **An idempotency lease is proven still held before its result is reported as
  fenced.** The lease refreshed periodically while the body ran, and a
  transient refresh error was treated as loss, while a body that finished
  between two refreshes was reported as fenced without anyone asking whether
  the lock was still there. A transient refresh error is now retried and only
  gives up after several consecutive failures, and one final owner-scoped
  refresh must succeed after the body completes before the outcome is
  reported as fenced; an error in that last check answers `FreshUnfenced`,
  because ownership is then unknown.

- **The encryption key ring is validated and installed before application
  bootstrap.** `Crypt` was initialized by `Server::from_config`, so anything
  that ran earlier - the bootstrap callback, a console command, a queue worker
  entry point that never builds a server - either found no key ring or built
  its own. `#[suprnova::main]` now loads the environment and then validates
  and installs the ring, in that order, before your bootstrap runs. Validation
  runs on every boot even after the ring is installed, so a production process
  with a missing or malformed `APP_KEY` still fails closed, while the
  process-wide key stays immutable. Laravel's `APP_PREVIOUS_KEYS` is accepted
  as an alias for `APP_KEY_PREVIOUS`; when both are set and disagree, the
  Suprnova name wins and the duplicate is named in a warning.

- **The archived `proc-macro-error2` crate is replaced by its maintained
  successor.** It was archived on 2026-06-07, is flagged unmaintained in
  RUSTSEC-2026-0173, and made every build warn that a future Rust release
  will reject it (E0365). `validator_derive` 0.20.1 moves to
  `proc-macro-error3` 3.1.1 and `sea-bae` 0.2.2 drops the dependency, so
  neither the advisory nor the warning appears any more. This landed on
  main after the `v2.0.0` tag; the tagged `Cargo.lock` still resolves
  `proc-macro-error2`.

### Added

- **Suprnova Live is part of the framework.** `suprnova::live` is a
  server-driven interaction engine: a component is a Rust struct whose state
  lives on the server, whose view is a checked Askama template, and whose
  actions run over a signed protocol from a small browser runtime that morphs
  the re-rendered HTML in place. There is no client-side state model to keep
  in sync, no build tool to install to use the shipped runtime, and no inline
  JavaScript in your documents. The engine ships as an internal crate the
  framework depends on unconditionally, so nothing has to be enabled; the
  browser half is published as `@suprnova/live` and its exact reviewed bytes
  are served by the framework itself. `manual/live.md` is the
  application-facing chapter, and a project created by `suprnova new` is Live
  ready out of the box: it writes `src/live/mod.rs` with an empty registry and
  a `routes()` function, binds the registry in `bootstrap.rs`, and installs
  the routes from `cmd/main.rs`.

- **Components are declared with `#[derive(LiveComponent)]` and `#[live]`.**
  The derive names the component and its view
  (`#[live(name = "app.counter", view = "live/counter.html")]`); the `#[live]`
  attribute on the `impl` block marks the methods the browser may invoke. A
  `#[public]` field is rendered and carried in the signed snapshot, a
  `#[model]` field additionally accepts browser proposals through
  `live:model`, and an `#[action]` method is the only entry point a request
  can reach, receiving validated arguments and returning typed outcomes such
  as a redirect or a flash. Every field type must implement `Default`; a fresh
  island starts from those defaults unless a mount hook says otherwise.
  Components are registered explicitly through `LiveRegistry::builder`, and
  the registry is immutable once the runtime assembles - a duplicate name or
  view, or a component whose actions need validation with no validation port
  bound, fails registration with a typed `RegistryError`.

- **`suprnova::view` is a checked server-rendered view contract for ordinary
  routes as well as Live components.** `#[suprnova::view(path = "...")]`
  declares a template, `TrustedHtml` is the one audited type a template may
  emit unescaped, and the `trusted_html` filter is how it gets there;
  `#[suprnova::view_filter]` declares a checked custom filter. Askama is the
  substrate, but handlers depend on the framework's own contracts rather than
  on the template engine's modules, and `TemplateFailure` is a closed,
  redacted failure set (`MissingData`, `InvalidData`, `Failed`) rather than
  the engine's own error text.

- **The `live:` directive grammar is closed and proved against your
  components.** A view binds behaviour with `live:click`, `live:submit`,
  `live:model`, `live:upload`, `live:key`, `live:loading` and the rest of the
  documented set - never an inline expression language, and never a
  server-returned script. `suprnova live:check` builds your application and
  runs the integrated checker over every registered view: an unknown action,
  an unknown model field, a raw `safe` filter, or an accessibility violation
  fails with the file, line, and column. `--allow-unproved` accepts the
  dynamic structures the checker deliberately makes no claim about.

- **`Router::try_live()` installs the reserved Live namespace once.** It
  registers `/__live/v1/action`, `/__live/v1/upload`, the
  `/__live/v1/async/*` control routes and WebSocket handshake, and the
  immutable `/__live/v1/assets/*` routes, and startup fails if an application
  route could claim `/__live`. `Router::try_live_with` takes a
  `LiveRouteGuard` whose middleware chain is applied to the action, upload,
  and asynchronous control routes and to the WebSocket upgrade, which is how
  an application attaches its own authentication, tenancy, and rate limiting;
  asset routes stay unguarded. Every reserved request carries a strict policy:
  session, origin, CSRF, principal, tenant, and rate-limit facts must all have
  been recorded by real middleware, and an asynchronous route that cannot see
  the complete set is refused rather than opening an anonymous transport.

- **A Live request proves its own origin, and using Live relaxes nothing
  else.** The shipped runtime sends the Live media type and the browser's own
  `Sec-Fetch-Site` header and carries no session token, so `CsrfMiddleware`
  verifies that proof for a Live operation on its own, whatever origin policy
  the application configured, and falls back to token validation for a
  cross-site or header-less request. Ordinary routes keep the configured
  policy, so an application no longer has to widen `OriginPolicy` for the
  whole application to let Live work. `AuthMiddleware::optional()` is the new
  guard form this needs: it records a principal when one exists and lets an
  anonymous request continue, so anonymous visitors can act on a public seed
  while an identity-bound island still refuses a request without principal
  evidence.

- **Documents place islands through `LiveDocument`.** A document route builds
  one from the request, mounts each island with `LiveMount`, and emits the
  bootstrap markup exactly once. `LiveMount::public_seed` declares an island
  any visitor may render, whose state is a reusable seed promoted to a real
  instance on the visitor's first action; `LiveMount::identity_bound` declares
  an island that belongs to the current session and principal, so its document
  route must authenticate. `LiveDocument::bootstrap` emits the inert
  configuration element and the ordered script tags with integrity attributes
  for the ESM or the classic strategy, adds the upload and asynchronous roles
  when a mounted component needs them and the Stimulus bridge on request, and
  rejects a second bootstrap or a mount after bootstrap.
  `Router::try_live_mount` registers a mount, and `Router::try_live_document`
  declares a document route with no startup mounts.

- **The framework serves the exact reviewed browser artifacts.** The ten
  deterministic build outputs are embedded and validated against their
  manifest on first use, failing closed on any drift in digest, length, file
  name, role, capability, or version, and are served from
  `/__live/v1/assets/<identity>/<file>` for `GET` and `HEAD` with immutable
  caching, strong digest validators, conditional requests, `nosniff`, and
  closed misses. Documents contain no inline executable code, so a strict
  `script-src 'self'` policy holds. `suprnova live:assets --out <dir>`
  publishes the same bytes to a CDN or a static directory atomically, treats
  an identical publication as up to date, and refuses to replace a directory
  whose bytes differ unless you pass `--replace`.

- **Live components accept file uploads under a declared, checked policy.** An
  `#[upload(policy = ...)]` attribute on a `#[model]` field declares maximum
  file count, declared and aggregate byte budgets, accepted media types, and
  replacement behaviour through `UploadPolicy::builder`, and the view binds it
  with `<input type="file" live:upload="avatar">`. The runtime creates,
  transfers, and completes the upload through `/__live/v1/upload`; the bytes
  wait in quarantine until the declared finalize action runs, when the
  framework hands them to the application's `UploadFinalizer`, alongside an
  optional `UploadScanner` and `UploadApplicationValidator`. Every control is
  authorized through the gate as
  `live:<component>.upload.<field>.<Control>` for each of `Create`,
  `Reacquire`, `Status`, `Queue`, `BeginTransfer`, `PutChunk`, `Complete`,
  `Accept`, `BeginFinalize`, `CommitFinalize`, `Cancel`, `Reject`, `Expire`,
  and `Fail`. Every request revalidates the current mount, principal, session,
  tenant, component, field, and document scope, a per-handle lock serializes
  chunk, completion, cancellation, action, finalization, and cleanup races,
  and chunk bodies reserve the shared in-flight budget before buffering.
  `Router::try_live_upload_reacquisition` declares an
  application-owned path outside the reserved namespace where a browser that
  lost its transfer grant can get a fresh one, answering only the session and
  principal that created the upload.

- **Islands update asynchronously over SSE, WebSocket, or polling.** A
  component declares the streams it listens to in the `#[live]` attribute
  (`streams(stream(name = "activity", topics("activity"),
  events(ActivityPosted)))`), the framework signs a bounded subscription
  descriptor for the visitor, and the browser runtime opens a native transport
  and falls back to polling when it cannot. Subscribing is authorized through
  the gate ability `live:<component>.stream.<name>`; the application publishes
  through `suprnova::live::LiveStreams`, with `refresh` telling subscribed
  islands to fresh-render and `event::<T>` delivering a typed payload to the
  island's registered handlers. Fanout, hop count, and per-document delivery
  are all bounded. Polling is an ordinary fresh render, so state catches up
  but event payloads published while a transport was unavailable are not
  replayed, which the runtime reports as a degraded stream rather than a
  current one.

- **The browser runtime is a strict TypeScript package that ships in core and
  optional bundles.** `@suprnova/live` bootstraps once per document, discovers
  islands, parses the closed directive grammar, gives each island bounded work
  and truthful pending and failed state, applies a response only after a
  successful morph through a pinned private Idiomorph adapter, and preserves
  focus, form state, controllers, scroll, and history across morphs and native
  navigations. Optional `uploads`, `async`, and `stimulus` bundles attach
  through a typed feature port, in ESM and classic forms; Stimulus is never
  bundled into core. There is no `eval`, no `new Function`, no
  server-returned script, and no inline expression language anywhere in it.

- **Four CLI commands cover the Live workflow.** `suprnova live:make <name>`
  scaffolds a component in `src/live/`, its view in `templates/live/`, and its
  registration in the `registry()` builder, declares the module, validates
  every target and refuses traversal and symlinks before writing, writes
  atomically, never overwrites, rolls back every file a failed run had
  written, and can report a dry run. `suprnova live:check`,
  `suprnova live:inspect`, and `suprnova live:assets` are thin clients of a
  hidden framework console command and a bounded, versioned JSON-lines
  protocol, so the CLI keeps no framework or engine dependency and fails
  closed with no writes on anything unsupported, stale, truncated, oversized,
  or unexpected. `live:inspect` reports the bound registry, configuration
  limits, installed upload capabilities, assembled runtime services, and the
  asset identity as presence booleans and counts, never state or secrets.

- **`suprnova::live::testing` prepares a router's runtime and mount catalog
  for in-process tests.** `prepare_live_router_for_test` gives a test the same
  runtime the server assembles, so a test can decode an island's snapshot from
  its `data-suprnova-live-snapshot` attribute, post an action with a real
  session cookie and `Sec-Fetch-Site: same-origin`, and assert on the accepted
  render through the application's real global middleware stack.

- **RenderCache stores a proven-safe copy of a route's response and serves the
  next matching request without running the handler.** It is opt-in per route
  and per group, it never changes what an application can do, and a route it
  declines still renders and serves correctly. `Router::try_render_cache`
  opts one already-registered route pattern in and
  `Router::try_render_cache_group` opts every route under a path prefix in;
  `RenderCache::install(router, RenderCacheConfig::from_env())` finishes the
  wiring after every middleware registration that establishes request-scoped
  locale, session, or identity. `RENDER_CACHE_ENABLED=false` is a real off
  switch at install time: a disabled configuration returns the router
  untouched, probes nothing, registers nothing, and leaves the process gate
  shut.

- **A cache policy states a representation class, a freshness policy, and how
  the response may be shared.** `RenderCachePolicy::builder` takes a
  `RepresentationClass` running widest to narrowest - `PublicShared`,
  `PublicShellStitched`, `PrivateCached`, `Uncacheable` - and
  `FreshnessPolicy::new(fresh_ms, stale_servable_ms, stale_on_error_ms)` sets
  how long a representation is fresh and then how far past that edge a stored
  copy may be served while a background rebuild runs or after a foreground
  rebuild failed. `SharedCachePolicy` controls what a shared cache in front of
  the application is told. A route inside a cached group can narrow its
  enclosing policy with a `PolicyPatch` instead of restating it, and may only
  make it narrower; pulling one route out of a cached group is a patch that
  sets the class to `Uncacheable`.

- **Variance is declared, never guessed.** A cached representation varies by
  route pattern, path parameters, and application build unless a policy says
  otherwise. `QueryPolicy::declared([...])` names the query parameters that
  distinguish representations, and any other query parameter on a request
  bypasses the cache for that request rather than being silently ignored.
  `.vary(VarianceDimension::Locale | ::Host | ::Tenant | ::Principal)`
  partitions by the negotiated locale, the request host, the current tenant,
  or the signed-in visitor, the last two as opaque key material; a
  `PrivateCached` route that declares neither `Principal` nor `Tenant` fails
  to build at all. `Media` and `Encoding` are declared together with their own
  closed set through `.vary_media(NegotiatedPolicy::declared([...],
  default)?)` and `.vary_encoding(...)`: the middleware negotiates the
  request's `Accept` or `Accept-Encoding` against that set per RFC 9110, with
  the highest quality winning, equal quality keeping the header's own
  left-to-right order, a wildcard compared as a literal token rather than
  expanded, and a `q=0`, out-of-range, or unparsable quality excluding a
  candidate rather than defaulting it. An absent, unmatched, or unparsable
  header resolves to the declared default and never panics. Both the render
  key and the `Vary` header take their value from that one resolution, so they
  cannot disagree.

- **A served hit is a real HTTP response with real validators.** It carries
  `ETag` as a strong validator a client can send back as `If-None-Match` for a
  `304`, plus `Cache-Control`, `Vary`, and `Age` in whole seconds since
  publication, which is the quickest local sign that a response came out of
  the store rather than out of a handler. A response served past its fresh
  interval additionally carries `Warning: 110 - "Response is Stale"`.
  Conditional requests and `HEAD` are answered from the stored entry.

- **Cached output is proved current against the database, not assumed.** A
  request-scoped collector attributes every read a handler makes to the thing
  it read: a model, a table, a configuration value, a feature flag, an
  authorization decision, an identity axis. Every supported write path on the
  other side advances the generation of what it changed, in the caller's own
  transaction where there is one - the ORM's model and bulk writes, the query
  builder facade, raw table writes, the payments hydration path, feature flag
  writes, and the RBAC role and permission statements including the new
  revocations. A hit reproves the generations it depends on before serving,
  either by rereading the ledger under `CoherenceMode::Authority` or against a
  validation lease under `CoherenceMode::Lease`, so nothing a write has
  invalidated can be served as current. `RenderCache::bump_permission_version`
  is the one invalidation an application calls by hand, from the code path
  that changes what a signed-in user may do; it advances a persisted
  generation every principal-keyed render observes, survives a restart, and
  joins the transaction the role change runs in.

- **Authorization, feature flags, and global scopes participate honestly.** A
  gate decision is judged by the identity axis its evaluation actually
  consulted, so a tenant-only consult needs only `Tenant` declared while
  anything that resolved principal material, or resolved nothing nameable at
  all, needs `Principal`. An RBAC-gated route caches and a permission grant or
  revocation rebuilds it, because the five role and permission tables are
  observed rather than treated as an unknown. A feature flag read observes a
  `Feature` generation whenever the snapshot holds that flag at any scope key,
  `set_flag` advances it, and a flag reload advances it for every flag its own
  diff found changed. An Eloquent `GlobalScope` declares
  `ScopeDependency::Constant` or keeps the conservative `PerRequest` default,
  and a per-request scope whose filter read nothing the collector can name is
  recorded as an undeclared read and narrows the render to `Uncacheable`
  rather than silently caching a tenant filter away.
  `suprnova::live::current_tenant()` is the instrumented accessor a gate body
  or a scope reaches for.

- **The write side is open in every process that writes through the ORM.** A
  queue worker, a scheduled task, or a console command writes through the same
  ORM the server does and never calls `RenderCache::install`, so its writes
  used to advance no generation and pages depending on them kept being served
  stale. The write side is now a process-wide tri-state probed at most once,
  never inside a caller's transaction, so every writing process advances the
  same generations the server does while an application with the cache
  disabled still issues no RenderCache SQL at all.

- **Three deployment profiles decide where entries and rebuild leadership
  live.** `RENDER_CACHE_PROFILE` selects `embedded` (a per-process file tier
  under `RENDER_CACHE_L1_DIR`, in-process leadership), `database` (entries in
  `suprnova_render_entries`, leases in `suprnova_render_leases`, Live instance
  records in `suprnova_live_instances` and `suprnova_live_promotions`), or
  `redis` (a Redis hash per key, plus a per-key publication token counter).
  `RENDER_CACHE_L1` and `RENDER_CACHE_COORDINATOR` override either half
  independently, so a deployment that wants its entries in the database and
  its leases in process says exactly that. Generation truth does not move: the
  database-backed ledger is the authority at every profile, which is what lets
  Redis lose everything it holds without anything stale being proved current.
  The full table is `RENDER_CACHE_ENABLED`, `RENDER_CACHE_PROFILE`,
  `RENDER_CACHE_L1`, `RENDER_CACHE_COORDINATOR`, `RENDER_CACHE_L0_ENTRIES`,
  `RENDER_CACHE_L0_BYTES`, `RENDER_CACHE_L1_DIR`, `RENDER_CACHE_L1_BYTES`,
  `RENDER_CACHE_REDIS_URL`, `RENDER_CACHE_REDIS_PREFIX`,
  `RENDER_CACHE_LEASE_MS`, `RENDER_CACHE_MAX_WAITERS`, `RENDER_CACHE_HINTS`,
  `RENDER_CACHE_FAILURE`, and `APP_BUILD_ID`. A closed-set variable given a
  value outside its set fails the boot with a message naming the variable and
  never repeating the value, because an environment value can carry a secret.
  The Live instance ledger has its own `LIVE_LEDGER_DRIVER`, `LIVE_REDIS_URL`,
  and `LIVE_REDIS_PREFIX`, and both installs fail closed at boot on a missing
  tier migration or an endpoint nothing answers.

- **A Live document can be cached as a shared shell with per-visitor
  islands.** A route declaring `RepresentationClass::PublicShellStitched`
  stores the shell once as a composite entry cut from the slots
  `LiveDocument::mount` captured, and on a hit the middleware attaches the
  prepared entry and still calls the route chain, so the route's own guard and
  tenant middleware decide the request before the Live completion middleware
  re-mounts every slot under authority derived for that request alone. A
  capture that is not exactly usable - a slot not found exactly once, a
  document digest that does not match - declines publication and stores
  nothing. The bounds are 32 slots, 64 nonce holes, 193 graph segments, and
  4,096 bytes each for slot parameters and fallbacks. Because every assembly
  is a distinct representation, no composite response answers `304` or honours
  `If-None-Match`, and a slotted assembly is sent
  `Cache-Control: private, no-store` while a zero-slot one keeps its class's
  private `max-age`.

- **A stored composite can name another stored entry as one of its
  segments.** `LiveNestedSegment` is the typed declaration and
  `Router::try_live_nested_segment` registers it. The inner entry keeps its
  own key and its own version, so it is invalidated, republished, and fenced
  on its own terms rather than the includer's, and each segment declares what
  happens when it cannot be resolved: fail the document, omit it, or serve a
  bounded fallback. Nesting is bounded to three levels and sixteen nested
  segments, a cycle is reported as a cycle even when it would also overrun the
  depth, and the assembled length is checked against the body bound before a
  single byte is copied. Publication is refused for a composite naming an
  inner segment of a wider representation class, one with a longer freshness
  window, a transitive cycle, a graph past the depth bound, or a
  `PrivateCached` inner segment that could never resolve. On a hit an
  identity-bound inner segment is reauthorized for the requesting visitor; one
  declared identity-free skips that, which is proven identity freedom rather
  than a weakening of it.

- **Nodes can tell each other that a generation just moved.**
  `RENDER_CACHE_HINTS` turns on a Redis pub/sub channel carrying the
  dependency digests an advance just touched, defaulting to on for the `redis`
  profile and off for the other two, riding the same
  `RENDER_CACHE_REDIS_URL` and `RENDER_CACHE_REDIS_PREFIX` as the cache
  itself. A hint's only power is to make a node revalidate earlier than its
  own lease would have: it can never extend or create a lease, prove an entry
  current, bypass the ledger read a hit still makes, or touch the authority
  epoch, which is why the channel is unauthenticated by design and why an
  unreachable hint endpoint does not refuse the boot the way an unreachable
  cache tier does. A hint carries no instant, so no clock-skew assumption
  between nodes is needed. A deployment with hints off, one whose channel is
  dead, and one that never had them serve the same entries and admit the same
  rebuilds; only the moment of revalidation differs.

- **Two console commands and nine telemetry counters are the operating
  surface.** `render-cache:inspect <key>` reports one stored entry's
  representation class, `body_bytes`, other metadata, and the current
  authority epoch, and it reads this process's in-process tier and nothing
  else, so on a shared profile it answers "what this node has in memory"
  rather than "what the deployment has stored". `render-cache:epoch-advance`
  is the emergency invalidation: it advances the authority epoch, which is
  baked into every lookup key, so stored entries go out of reach with nothing
  to enumerate and nothing to delete, and on the node that runs it the effect
  is immediate. Neither ever prints a stored body or a raw dependency
  identity, which is asserted rather than merely stated. The counters are
  `suprnova.render_cache.lookups`, `.hits`, `.publications`, `.rebuilds`,
  `.stitch.assemblies`, `.stitch.slots`, `.stitch.nested`, `.hints`, and
  `.epoch_rewinds`, all with closed low-cardinality attributes that never name
  a route, a key, a digest, a tier, or a provider.

- **A declined lookup says exactly which contract refused it.**
  `outcome="declined"` on the lookup counter now carries a `reason` attribute
  from a closed set of thirty-eight labels, computed from a typed value at the
  branch that actually declined rather than reconstructed from the response
  afterwards. They are grouped by contract: eligibility (`policy_uncacheable`,
  `method`, `status`, `streaming`, `sets_cookie`, `unsafe_header_name`),
  observation (`observation_overflowed`, `ledger_read_failed`,
  `handler_not_begun`), classification, key mismatch, Live document, and
  composite build. Every label is documented in the operations chapter, and a
  test asserts that rather than trusting the prose. `reason` is emitted only
  beside `outcome="declined"`; a hit and a miss carry none.

- **An authority epoch that goes backwards is detected, refused, and lifted
  past.** A database restore can move the epoch to a value the deployment has
  already used, which would let entries published under the old higher value
  be proved current again. An entry or a lease stamped above the authority is
  now refused at any age, before any dependency comparison, and the node that
  detects it lifts the ledger epoch past the stamp, drops its lease, clears
  its in-process tier, and increments
  `suprnova.render_cache.epoch_rewinds`.

- **NOWPayments joins Stripe and Paddle as a payment adapter.** The
  `suprnova-payments-nowpayments` crate creates hosted invoices, verifies
  payment notifications, and reads payment status with the merchant API key,
  and registers as `nowpayments` in the ordinary provider registry through
  `NowPaymentsProvider::from_env()`. It reads `NOWPAYMENTS_ENVIRONMENT`
  (`sandbox` or `production`, defaulting to `sandbox`; an unknown or blank
  value fails configuration), `NOWPAYMENTS_API_KEY`, `NOWPAYMENTS_IPN_SECRET`,
  and `NOWPAYMENTS_IPN_CALLBACK_URL`, and refuses blank credentials before any
  HTTP request. Its webhook endpoint is
  `POST /webhooks/payments/nowpayments` through the shared `webhook_routes`,
  and it needs the exact public HTTPS callback URL and request bodies that
  reach the adapter unchanged. `manual/payments-nowpayments.md` is the
  chapter.

- **RBAC has the revoking counterpart of every granting helper.** The surface
  exported the granting and checking halves of an access-control API and
  nothing that took access away, so removing an administrator's role meant
  composing statements against join tables whose semantics you had to infer -
  during an incident, which is when you reach for revocation.
  `remove_permission_from_role`, `remove_role_from_model` and
  `remove_permission_from_model` are the free functions, each with the
  `_on_guard` pairing the granting side already had, and `HasRoles::remove_role`
  and `HasRoles::remove_permission_to` pair at the call site. A name that
  exists on no such guard is an error, so a typo or a call aimed at the wrong
  guard is loud; an assignment the model or role does not hold is a no-op
  returning `Ok`, so a retry of a revocation that already landed is safe. Each
  call removes exactly the one assignment it names, with no bulk sweep, and
  every statement resolves its executor through the ambient transaction first,
  so a grant-and-revoke bundle inside `DB::transaction` commits or rolls back
  as one unit. Revocation is source-specific and does not contradict
  `has_permission_for_model`, which resolves a direct grant before a
  role-inherited one: taking a role away leaves a permission the model also
  holds directly still answering true, and the rustdoc names the second call
  that ends effective access.

- **An application can build its router asynchronously.**
  `Application::try_routes_async` takes a closure returning a future, and
  `Server::try_from_config_with_routes_async` is the asynchronous twin of
  `try_from_config_with_routes` that hosts it, sharing the same prologue and
  epilogue. It exists because `RenderCache::install` has to probe for the
  generation ledger's tables before it can assemble a runtime, and the route
  closure is the only place with both a container and a router - neither boot
  hook has one. `routes`, `try_routes`, and `try_routes_async` write the same
  slot, so the last one called is the one the server builds.

- **The Magnetar integration exposes what a partially completed sign-in
  actually returned.** `SignInOutcome` is public, so a magic-link, OAuth, or
  passkey callback that resolves to `SignInOutcome::FactorRequired` can be
  handled rather than being reported as a failure: the framework session is
  not bound, and the selector it carries can be completed through the retained
  host engine. `FactorAuth` and `MagnetarFactorAuthEngine` are the types that
  hold that continuation, and `install_magnetar_oauth_engine` and
  `install_magnetar_oauth_engine_with_factor` install an OAuth engine with or
  without one. Magnetar bootstrap failures now name what is missing instead of
  reporting a generic install error.

- **The queue driver contract reports whether it can honour a queue-name
  filter.** `QueueFilterCapability` (`Supported`, `Unsupported`, `Unknown`)
  is what `QueueDriver::queue_filter_capability` returns; the default is `Unknown`,
  not `Unsupported`, so a third-party driver that already overrides `pop_from`
  keeps working unchanged, and a decorator may reject a known `Unsupported`
  connection before polling but must let an `Unknown` driver answer for
  itself. `TerminalCallbackClaim` is the metadata a worker gets back when it
  atomically claims a finished batch's terminal callbacks, carrying the
  durable completion time and any cancellation visible in the same critical
  section, so the callback decision cannot be made from a snapshot that went
  stale before ownership was elected.

- **`Schedule::try_add` is the fallible sibling of `Schedule::add`.** Task
  name identifies a task in direct lookup and in the distributed keys used by
  `TaskBuilder::on_one_server` and `TaskBuilder::without_overlapping`, so one
  name cannot identify two registered entries and a schedule that registered
  the same name twice had two tasks contending for one lock. Names are now
  exact, case-sensitive, and unique: `add` panics on a duplicate and the
  existing task is retained, while `try_add` returns the error for code that
  would rather handle it.

- **Session lifetime bounds and the session migration error are public.**
  `MAX_SESSION_LIFETIME_SECS` and `MAX_SESSION_LIFETIME_MINUTES` are the
  clamps the environment parsing and the database driver apply, and
  `SessionMigrationError` is exported so a custom `SessionStore` can name the
  failure it returns.

- **Scaffolded projects are built in a production shape by construction.** The
  generated `Cargo.toml` depends on the framework with default features off
  and the nine non-`testing` defaults listed explicitly (`filesystem`,
  `database-sqlite`, `database-postgres`, `database-mysql`, `vector-mariadb`,
  `web-push`, `localization`, `magnetar-oauth`, `media`), and re-adds
  `features = ["testing"]` as a dev-dependency. Cargo's resolver pulls a
  dev-dependency's features into `cargo test` and other `--tests` builds only,
  so `cargo build --bin app` never compiles a test seam into a shipped binary,
  and `cargo test` is unchanged. `manual/deployment.md` documents the shape
  for an existing application to adopt.

- **The default cache build id comes from the application, not the
  framework.** `#[suprnova::main]` records the application crate's own
  `CARGO_PKG_VERSION` immediately after loading the environment, and
  `RenderCacheConfig::from_env` resolves `build_id` through an explicit
  `APP_BUILD_ID`, then that recorded application version, then this framework
  crate's own version only for a binary that never expanded
  `#[suprnova::main]`. `RenderCacheConfig::with_build_id` overrides whatever
  `from_env` chose, for an application that derives its own per-deploy
  identifier in code. Set `APP_BUILD_ID` explicitly once per deploy: it is
  mixed into every lookup key, and a package version rarely changes when you
  ship a template, a translation, or a handler fix.


### Changed

- **A worker on the failover queue connection now drains every connection,
  not just the primary.** `FailoverQueueDriver` documented the Laravel
  consequence it inherited: writes fell through the list, reads did not, so
  whatever failed over to a fallback sat there until somebody ran a second
  worker against that fallback directly. `pop` and `pop_from` now rotate their
  starting connection and then scan the whole list sequentially - rotation so
  a recovered, continuously busy primary cannot starve work that landed on a
  fallback, sequential so one call cannot reserve several jobs and hand back
  one. Each reservation is issued a fresh aggregate token that the driver maps
  back to the connection that really owns it, because inner tokens are not
  globally unique and two backends can legitimately mint the same UUID; an
  expired or unknown aggregate token is treated as stale rather than sent to
  an arbitrary connection. Counters and all three listings aggregate every
  configured connection in configured order and `clear` attempts every one, so
  what an operator inspects is the backlog this driver can actually consume.
  A driver declares whether it can honour a queue-name filter through
  `QueueDriver::queue_filter_capability`, which defaults to `Unknown` so an
  existing third-party driver is unaffected.

- **The minimum workflow lease is two seconds, and the first heartbeat fires
  immediately.** The heartbeat refreshes at `max(lock_timeout / 2, 1s)`, so a
  one-second lease was due for its first refresh at or after its own expiry:
  any claim latency or scheduling jitter opened a window another worker could
  walk through while the first was already running effects. The heartbeat's
  first tick is no longer skipped, which closes the claim-to-first-refresh
  window, and admission awaits an owned refresh before any user code runs, not
  only inside a step. `WORKFLOW_LOCK_TIMEOUT_SECS` below two is clamped with a
  warning that says why, and a configuration built in code that carries a
  shorter lease fails validation.

- **A payment provider without customer records can decline transaction-mirror
  hydration.** `WebhookHandler::mirrors_payment_transactions` defaults to
  `true`, so every existing provider behaves as it did; a provider that
  returns `false` still has its verified events persisted and deduplicated in
  the webhook audit log, refunds included, but no transaction mirror is
  fabricated for orders the application owns and must reconcile against
  authenticated provider state. `try_extract_payment_snapshot` is the fallible
  form of `extract_payment_snapshot` the hydration path uses: returning `Err`
  leaves the webhook pending so the provider retries it, while `Ok(None)` is
  reserved for an event that genuinely cannot supply a complete snapshot. Both
  are provided methods, so an existing driver compiles and behaves unchanged.

- **A Paddle `transaction.billed` is no longer read as money collected.** An
  issued invoice does not confirm collection, and treating it as a settlement
  marked orders paid that had not been. Approved refund and dispute
  adjustments are classified as adjustments rather than transactions, with
  their currency taken from `data.currency_code` and their settle time from
  the latest captured payment attempt where one is available; only
  `WebhookHandler::parse_event` classifies them, because the decision needs
  the payload's own action and approval status. The adapter also preserves the
  merchant correlation it was given through checkout instead of substituting a
  customer identifier that Paddle.js does not accept as a customer auth token,
  encodes non-string custom data as JSON strings consistently across customer
  and checkout requests, and gives its HTTP client the request deadline the
  pinned SDK does not set.

- **The framework crate carries three new modules and two new hard
  dependencies.** `suprnova::live`, `suprnova::render_cache`, and
  `suprnova::view` are unconditional, not feature-gated, so the framework now
  depends on the internal `suprnova-live` engine crate and on `askama` in
  every build. Neither module does anything until an application opts in:
  `Router::try_live()` is what installs Live's reserved routes, and
  `RenderCache::install` with a policy is what makes the cache do anything at
  all.

### Fixed

- **A batch job is not acknowledged until its accounting is durable.** The
  worker acknowledged a successful batch member and then wrote the batch
  bookkeeping, so a failure between the two left a batch permanently short one
  settlement and its completion callbacks never fired. The reservation is now
  held until every accounting write succeeds; a rejected or uncertain write
  leaves it intact so visibility expiry redelivers the job, and the
  repository's `(batch_id, job_id)` uniqueness makes the replay safe even when
  the first write took effect and only its response was lost. The batch
  repository is separately installable and may address a different database,
  which is why this cannot simply share the queue settlement's transaction.

- **A batch's terminal callbacks are elected exactly once.** Two jobs
  finishing the last two entries of a batch could both observe a pending count
  of zero and both run the completion callbacks. Settlement rows are now the
  source of truth and their parent batch row is locked before insertion, so
  concurrent jobs for one batch form a total order and exactly one final
  settlement observes zero - through row locks on PostgreSQL and MySQL, and
  through the writer lock the serialized transaction takes on SQLite. Claiming
  the callback bundle returns the durable completion time and any cancellation
  visible in that same critical section, so a worker cannot choose `then` from
  a snapshot that went stale before ownership was elected, and a non-empty
  batch whose pending count reached zero is sealed against positive growth. A
  cancellation already visible after an uncertain response is not restamped on
  redelivery. Envelope-construction failures collected while building a
  pending batch are surfaced at dispatch, which rejects the whole batch before
  any repository or driver mutation, instead of being swallowed by an
  infallible fluent builder.

- **The Redis queue driver fences every terminal operation against the
  delivery it was issued for.** `ack`, `nack`, `release`, and `settle` now
  compare the stream entry's consumer owner and delivery count with the
  generation captured by `pop`, and one Redis script applies any successor
  publication and the `XACK` together, so a delayed response that makes the
  caller retry finds the generation gone and the retry becomes a no-op instead
  of a duplicate publish. Because `nack` is inherently two commands (`XADD`
  then `XACK`), each reservation retains a per-token lifecycle that stays
  addressable through every failed operation and is removed only after the
  acknowledgement succeeds, so a retry resumes at the step that failed rather
  than republishing. The driver's at-least-once contract and the requirement
  that handlers be idempotent are now stated in the module documentation
  rather than implied. Consumer identities are isolated per process, so two
  workers cannot claim each other's pending entries.

- **A database queue reservation lasts as long as it was asked to.**
  `reserved_until` stores whole seconds and readers compare it with the
  floored current time, so the current fractional second was silently taken
  off every lease and a subsecond timeout could round to nothing. The absolute
  expiry instant is now rounded up.

- **Workflow step writes are fenced, an exhausted attempt budget terminalizes,
  and MySQL date columns match the entities that read them.** A step write
  from a worker that had already lost its claim could land on top of the
  worker that now owns the workflow; writes now carry the claim's fencing
  token. A row whose attempt budget is already exhausted could neither be
  claimed nor left pending forever: the claim statement now terminalizes at
  most one such row per poll, with disjoint cleanup and claim predicates so a
  large abandoned backlog cannot turn one worker poll into an unbounded write.
  The early workflow migrations declared MySQL date columns as `TIMESTAMP`
  while the public entities use `chrono::NaiveDateTime`, whose MySQL storage
  type is `DATETIME`; `NormalizeWorkflowDateTimesForMysql` is an additive
  migration that converts them and is a no-op on PostgreSQL and SQLite.

- **Cancelling a task no longer abandons a transaction's deferred effects.**
  An aborted `DB::transaction` rolls its database work back when SeaORM drops
  the transaction, but nothing rolled back a deferred queue push or released a
  held uniqueness lock for it, and an after-commit callback that was already
  running when the abort landed was dropped mid-effect. Callbacks now run as
  awaited child tasks, in registration order, so one already in flight
  survives its caller's cancellation, and the unstarted remainder is diverted
  to a detached task that either runs the after-commit list (the transaction
  did commit) or compensates (it did not). A panicking callback surfaces as an
  error instead of skipping the callbacks behind it, and a `COMMIT` the
  database refuses after the closure has already taken the request is handled
  rather than panicking.

- **Cross-disk copies and read-through caching clean up after a cancelled
  task.** A mid-stream failure already discarded the partial destination
  object, but a cancellation returns no error at all, so the writer was simply
  dropped and a truncated object or a staged multipart upload was left behind.
  The destination writer is now owned by a guard across the transfer: an error
  settles inline with the same abort and delete as before, while a
  cancellation diverts that cleanup to a detached task, and the cleanup itself
  runs to completion even if the awaiting task is cancelled during it. Cleanup
  never targets a published object, because another writer may have won the
  condition. Local filesystem work is kept alive until it finishes, since
  dropping a Tokio filesystem future does not stop the blocking work it has
  already submitted.

- **Two throttle clauses that hashed to the same storage identity no longer
  share one counter.** A rate-limit rule with several finite clauses could
  collide, so one clause's hits counted against another's budget. Colliding
  clauses now reserve deterministic, unambiguous counter and timer identities,
  computed once so the gate, the deferred hit, and the response headers all
  use the same key, and legacy keys are kept where no collision exists.

- **A sliding-window sweep no longer erases history a longer quota still
  needs.** The in-memory limiter dropped a bucket whose last hit was older
  than the window it was asked about, which discarded the record enforcing an
  already-observed longer quota on the same key. A bucket is now retained
  until its last recorded hit is older than both the supplied window and the
  longest quota window observed for it. A decrement below the minimum amount
  is handled rather than under-counting.

- **The in-memory cache driver rejects an increment against a non-integer
  value.** Redis `INCRBY` and `DECRBY` refuse a live non-integer and leave its
  value and TTL alone; the memory driver overwrote it, so the same code
  behaved differently against the two backends. It now parses before
  inserting and leaves the entry untouched on error. Separately, Redis `add`
  installs a missing untagged value and clears stale tag metadata in one
  script, so a newer tagged overwrite can no longer land between the
  conditional write and the cleanup that follows it.

- **Inertia one-shot session data survives a failed response.**
  `SessionMiddleware` ages `_flash.new.*` into `_flash.old.*` before the
  handler runs, so a response that failed while being constructed left those
  values to be deleted by the next request's aging pass - the user lost the
  validation errors or the flash message that explained what went wrong. A
  request-scoped guard now reflashes them on every uncommitted exit,
  cancellation included, and removes them only after the complete response has
  been built.

- **Fanout broadcasting waits for the backend to say it wrote.**
  `SeaProducer::send` only enqueues, and the returned future is what reports
  the actual backend write, so a delivery was reported as sent when it had
  only been queued. Every send in a pass is now polled for its receipt under
  one deadline, which also stops an unavailable broker from holding an
  application request open indefinitely. Membership heartbeats hold the read
  guard until every snapshot heartbeat is enqueued, so a concurrent untrack
  cannot be overtaken by a stale heartbeat.

- **`suprnova generate-types` never leaves a stale or truncated artifact
  behind.** A scan that ended early used to overwrite the output with whatever
  it had, so a transient parse failure silently deleted type definitions the
  application still used. File generation now refuses to overwrite an artifact
  after an incomplete scan, writes atomically through a collision-free sibling
  temporary file with bounded retries, and skips the write entirely when the
  contents are unchanged. An output symlink keeps its previous behaviour: the
  resolved target is replaced atomically and the link stays in place; a
  changed read-only destination is rejected.

- **Two `suprnova` command failures are reported instead of swallowed.**
  `suprnova new` reports a failed `git init` rather than presenting a project
  as fully created, and `suprnova workflow:install` validates the migration
  path before creating any directory, so an invalid path fails without leaving
  a half-made tree behind.

- **A savepoint and its deferred-effect registry agree on identity.** The
  savepoint statement and the registry mark used the caller's original
  spelling, but names are case-insensitive and PostgreSQL additionally aliases
  names sharing their first 63 ASCII bytes, so `ROLLBACK TO` could unwind a
  savepoint whose deferred effects the registry had filed under a different
  key. Both now share one validated, backend-canonical identity. The accepted
  64-byte API limit is unchanged.

- **`suprnova <command> --help` prints help instead of running the command.**
  The CLI declared its own `help` flag and consulted it only when no
  subcommand had been given, so every other `--help` printed the banner and
  then executed the command anyway. `suprnova migrate:fresh --help` dropped
  every table in the database, and the guard that would have stopped it
  refuses only in production while `APP_ENV` defaults to `local`. Clap now
  owns `-h` and `--help` on the top level and on every subcommand, in either
  argument order, and the curated banner is still what the top level prints.
  A test enumerates the subcommands from clap itself, so a subcommand added
  later is covered without anyone remembering to add it.

- **A scaffolded frontend no longer pins the CSRF token it read at boot.**
  The generated Vue, Svelte, and React entry points read
  `<meta name="csrf-token">` once at module load and attached that value to
  every Inertia visit. Logging in rotates the session, the captured token
  goes stale, and the next state-changing visit - typically the logout - was
  refused with `419 CSRF token mismatch`. Every generated application shipped
  with it. The hook is gone: the Inertia client reads the `XSRF-TOKEN` cookie
  `CsrfMiddleware` sets and echoes it back in `X-XSRF-TOKEN` itself, once per
  request, so the value that travels is the one the browser holds at that
  moment. Server-side verification is unchanged and both header names are
  still accepted. The manual chapter and the `suprnova::csrf` module
  documentation named the old hook as the thing to do; both now name it as
  the thing to avoid.

- **A scaffolded application's XSRF cookie is usable over local HTTP.**
  `CsrfMiddleware::new()` defaults the JS-readable `XSRF-TOKEN` cookie to
  `Secure`, while the generated `env.example` sets `SESSION_SECURE=false` for
  development, so a browser would neither store nor return the cookie over
  `http://localhost` and every state-changing request in development was
  refused with `419`. The generated bootstrap now passes its `SessionConfig`
  to `CsrfMiddleware::with_session_config`, which copies the session cookie's
  `Secure`, `SameSite`, `Domain`, `Path`, and lifetime onto the XSRF cookie
  so the two cannot drift apart. Nothing is weakened: token validation, the
  default origin policy, and the production guards are unchanged.

- **`suprnova make:command` appears on the help screen.** The command
  scaffolds a console command into `src/commands/` and had no line on the
  curated screen, so the only way to learn it existed was to read the source.
  The screen is now checked against the subcommand list clap reports, in both
  directions, so neither a missing line nor a line naming no command can
  survive.

### Upgrading

- **Most applications need no code change.** Live and RenderCache are both
  opt-in: `suprnova::live` does nothing until a router calls
  `Router::try_live()`, and `suprnova::render_cache` does nothing until a
  route is opted in and `RenderCache::install` is called. Everything else in
  this release is a fix to behaviour you already had. The version is 2.0.0
  because the framework's surface grew by two whole subsystems and because of
  the specific behaviour changes listed below, not because the ordinary
  application API was rearranged: no public item in the framework crate, the
  macro crate, or the payment, Magnetar, and Web Push adapter crates was
  removed or renamed.

- **Rebuild times and dependency footprint go up.** The framework now depends
  on the internal `suprnova-live` engine crate and on `askama` in every build,
  because `suprnova::live`, `suprnova::render_cache`, and `suprnova::view` are
  unconditional modules rather than features. There is nothing to enable and
  nothing to disable.

- **An application that never uses RenderCache pays one schema probe per
  process.** `RENDER_CACHE_ENABLED` defaults to `true`, so the first ORM write
  a process makes outside a transaction asks once whether the RenderCache
  migration is present; finding it absent, that process is closed for the rest
  of its life and issues no further RenderCache SQL. Set
  `RENDER_CACHE_ENABLED=false` to skip even that one statement. The probe
  never runs on a caller's transaction, so it cannot poison a write you are
  making.

- **Anyone building a `WebPushClient` from an already-built `reqwest::Client`
  must act.** `WebPushClient::with_client` now refuses to send under the
  default `EndpointPolicy::Strict` and returns
  `WebPushError::UnconfinedRedirects`, because an already-built client's
  redirect policy cannot be inspected and reqwest follows redirects by
  default. Move to `WebPushClient::with_client_builder`, which honours every
  transport option you were setting (proxy, TLS, timeouts) and forces
  redirects off, or call `WebPushClient::allow_unconfined_redirects` if you
  know your client is safe. `WebPushClient::new` is unaffected.

- **Signed URLs issued before the upgrade that carry a trailing slash stop
  verifying.** Signing and verification both used to trim a trailing slash
  before hashing; both now hash the path exactly. A URL signed as
  `/orders/1` still verifies at `/orders/1`, and only at `/orders/1` - a proxy
  that appends a slash now produces `SignatureVerdict::Invalid`. If a proxy or
  a framework in front of your application normalizes paths by adding a
  slash, sign the URL the way the request will arrive.

- **A schedule with two tasks of the same name now fails at registration.**
  `Schedule::add` panics on a duplicate, keeping the task already registered.
  Rename one of them, or switch to `Schedule::try_add` and handle the error.
  Names are exact and case-sensitive.

- **A workflow lease shorter than two seconds is clamped or refused.**
  `WORKFLOW_LOCK_TIMEOUT_SECS` below `2` is clamped to `2` with a warning
  naming the reason; a `WorkflowConfig` built in code with a shorter lease
  fails `validate`. If you were running a one-second lease deliberately, the
  heartbeat could not refresh it before it expired.

- **A MySQL application using workflows should add one migration.**
  `suprnova::workflow::migrations::NormalizeWorkflowDateTimesForMysql`
  converts the `workflows` and `workflow_steps` date columns from `TIMESTAMP`
  to `DATETIME`, which is what `chrono::NaiveDateTime` actually stores. It is
  additive, and a no-op on PostgreSQL and SQLite. MySQL may rebuild and lock
  both tables while applying it, so schedule it accordingly. A project created
  by `suprnova new` gets it wired automatically.

- **`AuthMiddleware` now resolves the user on every guarded request.** It used
  to accept the presence of a persisted identifier. The behaviour change is
  that a session belonging to a deleted or soft-deleted user stops
  authorizing. The cost is smaller than it looks: the resolved user is cached
  for the rest of the request, so a handler that already called `Auth::user()`
  pays nothing extra and the lookup has simply moved from the handler to the
  middleware. Only a guarded request whose handler never resolved the user
  gains a provider lookup it did not make before. An application with no user
  provider bound keeps the identifier-only path unchanged.
  `BasicAuthMiddleware` in its non-stateless
  form now requires the guard it names to exist and to be a stateful guard.

- **`destroy_all_for_user` costs more and revokes more.** It now reads the
  surviving session rows and compares the guard identities inside each
  payload, in addition to the indexed `user_id` match, so it reaches sessions
  authenticated through a named guard alone. Revocation is rare enough that
  correctness was chosen over index use; if you call it on a hot path, that is
  worth knowing.

- **A `POST` or `PATCH` retried after a transport error now needs
  `retry_non_idempotent`.** The `5xx` branch already required it; the
  transport-error branch did not. If you were relying on a dropped connection
  being retried for a non-idempotent request, opt in explicitly.

- **A production process with a missing or malformed `APP_KEY` now fails at
  `#[suprnova::main]`, not at `Server::from_config`.** That includes a console
  binary or a worker entry point that never builds a server. Local,
  development, and testing environments still generate a transient key and
  warn. `APP_PREVIOUS_KEYS` is accepted as an alias for `APP_KEY_PREVIOUS`;
  if both are set with different values, the Suprnova name wins and the
  duplicate is named in a warning you should act on.

- **A worker pointed at a `failover` queue connection now drains every
  connection in the list.** If you were running a second worker against a
  fallback connection directly - which the 1.3.3 notes told you to do - that
  worker and the failover worker will both be draining it. Remove the extra
  worker, or keep it and accept the competition. Counters and listings now
  aggregate every connection, so a dashboard reading `pending_size` on the
  failover connection will report a larger number than it did.

- **Custom store and driver implementations get fail-closed defaults, never
  weakened behaviour.** Magnetar's provider-token, ceremony, and remember
  stores gained methods for the atomic operations described above; each has a
  default that refuses rather than performing the operation non-atomically, so
  an external implementation still compiles but will report failure until it
  implements the method. `WebhookHandler::mirrors_payment_transactions` and
  `try_extract_payment_snapshot`, `QueueDriver::queue_filter_capability`, and
  `GlobalScope::dependency` all have defaults that preserve the previous
  behaviour exactly.

- **To adopt Live**, bind a registry during bootstrap with
  `App::singleton(crate::live::registry().expect("Live component registry"))`,
  install the reserved routes with `Router::try_live_with` and a guard
  carrying your `AuthMiddleware`,
  `LiveTenantMiddleware`, and `RateLimitMiddleware`, and register
  `CsrfMiddleware::new()` globally - Live verifies its own origin proof, so
  you do not need to widen `OriginPolicy` for the whole application, and if
  you widened it for something else, narrow it back. Use
  `AuthMiddleware::optional()` on the Live guard if you want anonymous
  visitors to act on public seeds; `AuthMiddleware::new()` answers `401` for
  every anonymous request before any engine work. Then run
  `suprnova live:make` and `suprnova live:check`. `manual/live.md` has the
  complete walkthrough.

- **To adopt RenderCache**, add
  `suprnova::render_cache::migration::Migration` to your `Migrator` (and
  `suprnova::render_cache::migration::TierMigration` as well if you run the
  `database` or `redis` profile), opt routes and groups in with
  `Router::try_render_cache` and `Router::try_render_cache_group`, and finish
  with `RenderCache::install`. Because `install` is asynchronous - it probes
  for the ledger's tables before assembling a runtime - the router has to be
  built through `Application::try_routes_async` rather than `try_routes`. The
  install has to come after every middleware that establishes request-scoped
  locale, session, or identity, and after every route and group has been opted
  in. A shared profile refuses to boot without its tier migration or with an
  endpoint nothing answers, which is deliberate.

- **Set `APP_BUILD_ID` once per deploy.** It is mixed into every RenderCache
  lookup key, so changing it is what stops a new build from serving entries
  the previous one published. Its default is your application crate's package
  version, which does not change when you ship a template, a translation, or a
  handler fix. A commit id works: `APP_BUILD_ID=$(git rev-parse --short HEAD)`.

- **Consider moving your `Cargo.toml` to the production build shape.** Declare
  `suprnova` with `default-features = false` plus the nine non-`testing`
  defaults you use, and re-add `features = ["testing"]` under
  `[dev-dependencies]`. Cargo pulls a dev-dependency's features into
  `cargo test` and other `--tests` builds only, so your shipped binaries stop
  carrying test seams while `cargo test` keeps working unchanged. A project
  created by `suprnova new` is already in this shape;
  `manual/deployment.md` documents it for an existing one.

- **If you consumed the standalone `@suprnova/live` runtime or wrote your own
  subscription host, the registered-event descriptor changed.**
  `DESCRIPTOR_SCHEMA_VERSION` moved from 1 to 2 and the descriptor's
  registered-event fields are now `maximum_hops`, `maximum_fanout`, and
  `payload_contract` rather than `maximumHops`, `maximumFanout`, and
  `payloadContract` - they were the only camelCase keys in a public JSON
  contract that is snake_case everywhere else. A descriptor signed at schema
  version 1 is refused with `SubscriptionErrorKind::InvalidDescriptor` rather
  than being read with three absent fields. Nothing in a 1.3.7 Suprnova
  application consumed this contract, so for most readers there is nothing to
  do.

## 1.3.7 - 2026-08-26

### Added

- **Where the Inertia error page middleware sits is now yours to choose, and documented.** `Inertia::install` registers `InertiaErrorPageMiddleware` innermost of the Inertia layer, so it covers the handler, the route middleware, and everything you register after that call - which is why the scaffold puts `CsrfMiddleware` below it. It does not cover anything registered *above* the call, because a middleware that answers without calling `next` hands its response to nothing registered inside it. The case that bites is a lapsed session posting a form: `CsrfMiddleware` registered above the install answers `419` with `{"message":"CSRF token mismatch."}` and the user gets the Inertia crash modal on the one flow they are most likely to hit; an outer rate limiter's `429` and an auth guard's `401` are the same. Registering the middleware yourself, further out, already worked in 1.3.6 - the type was public and registration is idempotent per type, so an earlier registration kept its place - but nothing said so and nothing in `install` acknowledged it, which made it an accident rather than a contract. It is a contract now: register `InertiaErrorPageMiddleware::new("Error")` after `SessionMiddleware` and `LocaleMiddleware` and before the middleware whose rejections it should cover, and `install` checks for it, logs at `debug`, and skips its own. The component you named at that registration is the one rendered, so you name the page once and `.error_page(...)` on the config becomes optional - it is still what makes `install` register a middleware for an app that does not place one itself. The two ordering rules are documented on the type and in the manual.

### Fixed

- **An SSR page has one `<title>`, and it is the page's own.** The HTML shell wrote its `default_title` and then the SSR worker's head verbatim, so every page rendering a title through Inertia's `Head` component produced a document with two `<title>` elements and the framework's generic one first. First is the one the browser tab, the crawler and the link preview read, so the real title never showed. A worker head carrying a title now replaces the shell's title rather than joining it - both `default_title` and a per-response `InertiaResponse::title(...)` stand down; a head without one leaves the shell's title exactly where it was.
- **The document declares the language it is written in.** The shell hardcoded `<html lang="en">`, so a reader switched to Japanese got Japanese prose in a document claiming to be English - a screen reader picks its voice from that attribute and a search engine takes it as the page's language signal. It now carries the locale in effect for the request: what `LocaleMiddleware` detected, then a `Lang::set_locale` override, then the configured `APP_LOCALE`, in the same BCP 47 form `Locale` renders (`pt-BR`, `zh-Hans`). This holds for the error page too, which is rendered on the way out and was the case that surfaced it. Without the `localization` feature the shell keeps `en`.

### Upgrading

- Nothing is required. Both fixes apply to every Inertia app on upgrade, and `Inertia::install` behaves exactly as it did for an app that does not register the error-page middleware itself.
- An app that spliced `<html lang="...">` into the finished document with a middleware of its own can delete it - the shell does it now, from the same locale that middleware was reading.
- An app whose `CsrfMiddleware`, rate limiter, or auth guard is registered **before** `Inertia::install` should register `InertiaErrorPageMiddleware::new("Error")` after `LocaleMiddleware` and before that middleware, so its rejections render the error page instead of reaching the client as raw JSON. `install` then skips adding its own, and the component you named at the registration is the one rendered, so `.error_page("Error")` on the config is optional - keep it or drop it. The scaffolded `bootstrap.rs` registers CSRF after the install, so a project generated by `suprnova new` needs no change.
- An app that renders its own `<title>` through Inertia's `Head` component under SSR will see the shell's title stop appearing in the document - both `InertiaConfig::default_title` and a per-response `InertiaResponse::title(...)`. That is the fix: the page's own title is the document's only one. If you were relying on the shell's title as a prefix or suffix, move it into the `Head` component where the rest of the title lives.

## 1.3.6 - 2026-08-26

### Added

- **Framework errors can render your own Inertia page instead of the client's crash modal.** A user without a permission clicked a nav link into a guarded route and got Inertia's "All Inertia requests must receive a valid Inertia response, however a plain JSON response was received" screen: the `403` carried the framework's JSON error body and no `X-Inertia` header, so the client refused it. The same held for an unrouted `404`, a rate-limited `429`, and a failing handler's `500`. Name a page component with `InertiaConfig::error_page("Error")` and those responses render that page at their original status, with `status`, `message`, and - when the error carried one - `request_id` props. Every header the error response set survives the swap except the ones that only described the body being replaced (`Content-*`, `Transfer-Encoding`) or governed how it could be stored (`Cache-Control`, `Expires`, `Age`, `ETag`, `Last-Modified`), so `Retry-After` on a `429`, `WWW-Authenticate` on a `401`, `Vary`, and `Set-Cookie` all still reach the client. The page sets `Cache-Control: no-cache, private` for itself: it carries your shared props, so it must never be stored by a shared cache and served to a different visitor, whatever the response it replaced permitted. An Inertia visit gets the JSON page object; a hard navigation gets the full HTML shell, so pasting the URL into the address bar works too. Everything with an owner is left alone: validation `422`s still redirect back to the form, `X-Inertia-Location` bounces and responses that already are Inertia pages pass through, and a client whose `Accept` prefers JSON keeps the exact body it got before. `suprnova new` scaffolds `frontend/src/pages/Error.*` and sets `.error_page("Error")`, so new projects are covered without doing anything.

### Fixed

- **A local disk no longer refuses a legitimate path because another task touched it.** The path guard resolved each component of a path with two probes and combined them into one verdict, so ordinary concurrent activity could be read as a symlink escape: a component that `canonicalize` had just reported missing, and that another task then created as an ordinary file, came back as `PermissionDenied` naming a symlink that was never there. It bit hardest where writers contend by design - a losing `write_with(..).if_not_exists(true)` racer got that refusal instead of `ConditionNotMatch` whenever the winner published the key between the two probes, which under a loaded test suite was roughly a third of runs. Each component is now classified from a single pass, `symlink_metadata` first: nothing there is free space, an ordinary file or directory is resolved and confined as before, and only a symlink that still cannot be resolved is refused. A component that vanishes mid-classification is looked at once more rather than refused. Every symlink refusal is unchanged.

### Upgrading

- Nothing changes for an existing app until it opts in. `InertiaConfig::error_page` defaults to `None`, and `Inertia::install` registers the error-page middleware only when a component is named, so error responses keep their exact bodies. To adopt it, add a page component named `Error` beside your others (it receives `status`, `message`, and an optional `request_id`) and chain `.error_page("Error")` onto the `InertiaConfig` you pass to `Inertia::install`. A handler that **panics** stays out of scope: the panic net wraps the whole middleware chain, so its synthesized `500` is built after every middleware has unwound. Return `Err(...)` rather than panicking and the error page covers it. Note that the gate is the body's **shape**, not its author: at an error status, an empty body, a JSON object whose `message` is a string, and the router's own `404 Not Found` text are rewritten no matter which middleware built them, and only `message` and `request_id` survive into the props. A response that must keep its own JSON body should key its text as something other than `message`, or set `X-Inertia: true` on itself. And register `LocaleMiddleware` **before** `Inertia::install`: the error page is rendered on the way out, after every middleware registered inside the Inertia layer has returned, so a locale scope opened inside it is already gone and every error page would render in the app's default locale. The scaffolded `bootstrap.rs` now does this, and the same reasoning applies to any request-scoped middleware of your own whose state the page's shared props read.

## 1.3.5 - 2026-08-26

### Changed

- **Every changelog section reads in all six manual translations.** The de, es,
  fr, ja, pt-BR and zh-Hans manuals used to carry the 1.3.0 to 1.3.2 sections in
  English behind a translator's note, and older sections with stray English
  lines; every section from 1.3.5 back to 0.1.0 is now translated, and the
  notes are gone.

### Fixed

- **Local-filesystem disks publish every object in one step.** `Storage::register_fs` and `register_fs_with` now stage `disk.write(...)`, `disk.writer(...)`, and `disk.copy(...)` as a temp file under `<root>/.suprnova-atomic/` and publish it onto the target with a single `rename(2)`, so none of them is ever observable at a partial length. Before this, the driver opened the target with `create + truncate` and streamed into it in place: a concurrent reader got an empty or half-written object for the whole duration of the write, and a crash mid-write left a truncated object at the live path. `abort()` on a writer now discards the staged file instead of failing with `Unsupported`.
- **`write_with(..).if_not_exists(true)` is a true exclusive create on a local disk.** It is published with `link(2)`, which fails atomically in the kernel when the target exists, so exactly one of any number of racing callers succeeds and every other one gets `ConditionNotMatch` having written nothing. A staged write published by a plain rename would have degraded the condition to a check followed by an overwrite, silently discarding all but the last writer - which is the opposite of what the primitive is reached for.
- **An `append` that creates the object is still an append.** Appends are the one in-place operation on a local disk, and that now holds for the first one too, so two writers appending to the same missing object both land instead of one staging its own copy and overwriting the other.

- **`suprnova serve` no longer rebuilds a project nobody has touched, and
  neither does `suprnova generate-types --watch`.** Both watchers classified a
  filesystem event by its path alone, and the generator reads every `.rs` file
  under the same `src/` tree they are watching - so on Linux, where the kernel
  reports those reads, each regeneration scheduled the next one. A freshly
  scaffolded project regenerated its types and restarted its backend every half
  second, forever, without a single source edit. Only events that mean the bytes
  on disk actually changed count now. `generate-types --watch` also had no
  debounce at all, so it acted on the first file of a burst rather than the last;
  it now shares `serve`'s 500 ms trailing edge, and both watchers share one
  implementation so the next fix cannot land in only one of them. The generator
  compares before it writes, so a regeneration whose output is byte-identical
  leaves the file, and its mtime, alone.

- **The backend watcher is scoped to the paths the server is built from.**
  `cargo watch` ran with no `-w`, so it watched the whole non-gitignored project:
  saving a Svelte component, or regenerating
  `frontend/src/types/inertia-props.ts`, rebuilt the framework and restarted the
  server. It now watches `src/`, `cmd/`, `Cargo.toml`, `Cargo.lock`, `.env`, and
  `lang/` - the build inputs plus the two trees read once at boot - each included
  only when it exists, since cargo-watch refuses a `-w` path that does not.
  `cmd/` is where the full-stack scaffold keeps the server binary's `main.rs`.
  The invocation also passes `--no-vcs-ignores`, because cargo-watch applies
  `.gitignore` to explicitly named `-w` roots and the scaffold ignores `.env`,
  which would otherwise leave `-w .env` watching nothing; `-w` has already
  narrowed the surface, so the flag cannot widen it. Frontend edits and generated
  `.ts` files no longer restart the backend.

- **`serde_json::Value` generates as `JsonValue` instead of `unknown`.** It used to
  degrade to `unknown` and warn that it "isn't a struct this project defines",
  advice that is wrong for a JSON document - and the scaffold's own login and
  register pages tripped it twice on every regeneration, so every fresh project
  warned out of the box. It now emits a recursive `JsonValue` alias, declared once
  at the top of the generated file and only when something references it. A bare
  `Value` maps there too, unless the project defines a `Value` struct of its own.

- **Neither `generate-types` nor `serve` reports a file it did not write as
  generated.** Because a pass now writes only when the emitted content differs,
  `Generated <path>` was a claim about the filesystem that was false on every
  rerun of an unchanged project. `generate-types` says `<path> is up to date`
  instead, in one-shot and `--watch` alike, and `serve`'s startup pass says
  `N type(s) up to date → <path>`, keeping the count. `serve`'s file watcher
  now stays silent on a regeneration that wrote nothing, in text and under
  `--json` both: a `types_regenerated` event means the generated file on disk is
  different now, so silence after a save tells you your edit did not change any
  prop shape.

### Upgrading

- **`.suprnova-atomic` is reserved at the root of every local disk.** The staging directory has to live inside the root - a sibling of the root can be on a different filesystem when the root is a mount point, and every rename would fail with `EXDEV` - so the name is reserved rather than merely conventional. Any path whose first component is `.suprnova-atomic` is now refused with a permission error (read, write, delete, stat, list alike), as is any path that resolves into the directory through a symlink, and the entry is filtered out of `files`, `directories`, `all_files`, and `all_directories`. If a disk root already contains a `.suprnova-atomic` entry of your own, it is no longer reachable through that disk: move it aside before upgrading. A regular file of that name is refused at registration with a message saying so, rather than failing later inside the driver. The name is exported as `suprnova::ATOMIC_STAGING_DIR` so backup and sync tooling can exclude it.
- **Publishing by rename replaces the target's inode.** Rewriting an object on a local disk no longer preserves its mode, owner, or hard links, and a reader holding an open descriptor keeps the old content instead of seeing the new bytes. That is the standard cost of atomic publishing, but it is a behavior change if you were relying on either.
- **A conditional write needs a filesystem with hard links.** `if_not_exists` is published with `link(2)`, which is unsupported on FAT, exFAT, and some network filesystems. There it fails outright rather than falling back to a check followed by an overwrite, because a fallback would hand you an exclusivity guarantee that does not hold. Nothing else on the disk is affected.
- **A first `append` that fails leaves an empty object.** An append is the one operation that is not published in a single step, so the object is created before the bytes land; a failed or aborted first append leaves it behind, exactly as an append onto an existing object always has.
- **A dangling symlink in the disk root is refused, not overwritten.** A path whose symlink target does not exist can no longer be written, appended to, copied onto, moved onto, or deleted through the disk. `1.3.4` replaced such a link with a regular file; the guard cannot prove where an unresolvable link leads, and creating through one creates the link's target anywhere on the host, so it now refuses. Remove the link outside the disk if you meant to write there.
- **Nothing sweeps the staging directory.** It holds in-flight temp files plus whatever a process that died mid-publish left behind, so a host in a crash loop grows it without bound. Emptying it while nothing is writing to the disk is safe; excluding it from backups is recommended.

## 1.3.4 - 2026-08-25

### Added

- **Read-through disks take a `copy` flag and resolve `copy` / `rename` across the fallback.** Set `copy: false` on `ReadThroughConfig` to serve fallback hits without writing them through, which turns the disk into a transparent overlay and narrows each fetch to the range you asked for. `copy` and `rename` now stream a source that lives only on the fallback across to the primary destination; a `rename` also deletes the fallback source, so a later read cannot resurrect the moved object. Conditions carry across that streaming path: `if_not_exists` still refuses an existing destination, a copy's source version selects which object the fallback hands over, and a copy's `if_match` is refused with `Unsupported` rather than silently dropped. A transfer that fails partway removes only a destination it created, so it cannot destroy an object that was already there.
- **Debounced jobs and debounced queued listeners.** `Job::debounce_for()` collapses
  a burst of dispatches into one run, one window after the most recent one, carrying
  the newest payload. It is the mirror of `push_unique`, which keeps the first
  dispatch and suppresses the rest. `Job::max_debounce_wait()` stops a continuous
  burst from deferring the work forever, and `Job::debounce_id(&self)` scopes the
  window per entity so twenty updates to one order collapse without touching
  another order's. `Queue::push_debounced(job, DebounceOptions)` sets the window at
  the call site, and `DebouncedListener::new(window, build).keyed_by(...)` debounces
  an event listener with the key derived from the event - a plain `QueuedListener`
  already honors a window the job itself declares. Every dispatch is still enqueued;
  the collapse is settled at the worker, which acknowledges a superseded envelope
  and emits `JobDebounced`. Debouncing fails open: an expired or evicted window runs
  the job rather than dropping it. Each actual run starts a fresh maximum-wait
  window, so a burst always measures its maximum wait from its own first dispatch
  rather than inheriting the previous burst's. A job cannot declare both
  `debounce_for` and `unique_id`, and chains and batches refuse a debounced job -
  a superseded link would strand the rest of its chain, and a superseded batch job
  would leave the batch's pending count above zero forever. The envelope carries two
  additive fields for this and stays byte-identical on the wire for every
  non-debounced push.

- **`Storage::register_read_through` composes two disks into a read-through disk.** Reads and metadata resolve against the primary first and fall back to the second disk; anything found on the fallback is written through to the primary, so a store migration completes under real traffic. Writes and listings stay on the primary, and a delete removes the object from both disks. Set `throw_on_promotion_failure` when a failed promotion must surface instead of degrading to a fallback read. A promotion is published atomically, so no reader can see a half-written object, and it carries the fallback object's content type, cache control, content disposition, content encoding, and user metadata across. A versioned or conditional read is passed through with its condition intact and served without being promoted.
- **`Queue::forward` redirects a whole queue by name.** Where `Queue::route` is
  keyed by job type, `Queue::forward("default", "high")` is keyed by queue name -
  the lever for retiring a pool, absorbing a backlog, or moving work off a pool you
  are about to take down, without touching a single job or route. It applies on
  both sides: new pushes that resolved to `default` land on `high`, *and* a worker
  started with `--queue=default` drains `high`, so the destination cannot collect
  work nobody claims. Forwarding `default` catches jobs that named no queue. A
  forward is a single lookup, never a chain, so a swap (`a -> b` with `b -> a`
  also registered) or a longer rotation is a coherent pool exchange rather than
  a loop - exactly like Laravel, whose resolver is the same single lookup.
  Pausing is still evaluated on the names a worker was started with, so
  `Queue::pause(&connection, "default")` stops that worker even while `default` is
  forwarded. `Queue::forward_on(from, to, connection)` restricts a forward to one
  connection name, compared against this process's connection name rather than a
  job's declared connection, so both halves of the redirect gate on the same
  value. `Queue::forward_for(from)` reads a forward back, and `Queue::try_forward`
  is the fallible sibling. The inspection calls (`Queue::pending_jobs` and its
  siblings) deliberately do not follow a forward, so a backlog left behind on a
  forwarded queue stays visible.

- **Read-shaped Redis commands retry a transient failure instead of surfacing it.**
  The connection manager already reconnected in the background, but the command
  that hit the dead socket still failed your call. `GET`, `EXISTS`, the `SCAN`
  and `SSCAN` pages behind `Cache::flush` / `Cache::flush_tags`, the queue
  driver's `XLEN` / `ZCARD` / `XPENDING` reads, and the rate limiter's
  `Retry-After` computation now retry once after a short pause.
  `REDIS_COMMAND_RETRIES` adds further retries on top, clamped at 10. Budget the
  retry in seconds rather than milliseconds: the second attempt waits for the
  replacement connection, so it costs the driver's whole connect and response
  budget, and a timed-out command counts as transient as well as a dropped one.
  Writes never retry at any setting: a transient error means the connection
  failed, not that the server refused the command, so repeating a `SET`, an
  `INCR`, a lock acquisition, a rate-limit hit, or a queue pop could run it
  twice. Error messages are unchanged, so anything matching on them keeps working.
- **A paused worker now tells you it is paused.** `queue:work` prints one line per
  transition - `2026-08-25 14:03:11 Queue billing PAUSED`, and `RESUMED` on the way
  back - and the worker emits `WorkerQueuePaused` / `WorkerQueueResumed` so you can
  route the same signal into your own alerting. These are the worker-side pair; the
  existing `QueuePaused` / `QueueResumed` fire in whichever process ran
  `queue:pause`, which is never the worker, so until now a worker that went quiet
  because somebody paused its queue was indistinguishable from a hung one. Each
  event fires once per transition, not once per poll. Their `queue` field is
  optional: a worker started without `--queue` drains everything and has no queue
  names to report under `pause_all`, so it reports `None` rather than inventing a
  name a listener could match on.
- **`?include=` paths are capped at five segments, and `max_relationship_depth` moves the ceiling.** A cyclic relationship graph turns `?include=author.posts.author.posts...` into fan-out a client controls, bounded only by the query string. Paths are now truncated while they parse; call `suprnova::max_relationship_depth(n)` in `bootstrap::register()` to change the limit, or pass `0` to turn includes off.
- **`Gt`, `Gte`, `Lt`, and `Lte` compare a field against a number or against another field.** `CompareWith` names the operand and the measure in one value: `Number` for a literal, `NumericField` for a numeric sibling, and `LengthField` for a sibling compared by character count. An operand the rule cannot measure fails the field instead of panicking.
- **Three membership rules join the built-in set: `InArray`, `Contains`, and `DoesntContain`.** `InArray` checks a value against another field's list, and you pass the list directly instead of naming the field in a rule string. `Contains` and `DoesntContain` run over a JSON array and match a parameter only against a string element, so `1` and `"1"` stay distinct.
- **The database pool now has liveness knobs.** `DB_IDLE_TIMEOUT`, `DB_MAX_LIFETIME`, `DB_ACQUIRE_TIMEOUT`, `DB_TEST_BEFORE_ACQUIRE`, and `DB_PING_AFTER_IDLE` control when the pool closes, recycles, and pings a connection, with matching `DatabaseConfig::builder()` setters. Each is unset by default, so an existing deployment's pool behaves exactly as it did. Use them when a NAT gateway or firewall drops idle connections: sqlx exposes no libpq `keepalives_*` equivalent, so pool recycling is the mechanism.
- **`db:seed <Class>` reports its progress.** A targeted run prints a `RUNNING` line before the seeder and an elapsed-milliseconds `DONE` line after it. A bare `db:seed` stays silent. The formatter, `suprnova::two_column_detail`, is available to your own `#[command]` handlers.
- **Many-to-many relations now filter on pivot columns.** `where_pivot`, `where_pivot_op`, `where_pivot_in`, `where_pivot_not_in`, `where_pivot_null`, `where_pivot_not_null`, `where_pivot_between`, `where_pivot_not_between`, `where_pivot_group`, and their `or_` twins constrain `get`, `first`, and `count` on `BelongsToMany`, `MorphToMany`, and `MorphedByMany`. `where_pivot_group` takes a closure and renders one parenthesised group, so it stays atomic inside a following `or_where_pivot`. Pivot filters apply to reads only: `attach`, `attach_with`, `detach`, and `sync` return an error while one is set, and eager loading does not carry them.
- **`where_binary` compares column values byte for byte.** The family (`where_binary`, `or_where_binary`, `where_not_binary`, `or_where_not_binary`) ships on `Builder<M>`, and `where_binary` and `where_not_binary` ship on `DB::table(...)`. MySQL and MariaDB emit `= binary`; Postgres and SQLite return an error when the query renders, rather than falling back to a collation-dependent match.
- **`Builder::try_to_sql_with_bindings_for` renders SQL for a dialect without panicking.** It is the fallible sibling of `to_sql_with_bindings_for`, for the cases where a builder legitimately cannot render for a backend.
- **`Model::refresh_for_update` reloads a row under a `FOR UPDATE` lock.** Call it inside a transaction when you need the row's current state and the exclusive lock in one statement. SQLite has no row-level locking, so the lock clause is a no-op there.
- **`Builder::or_where_key` and `Builder::or_where_key_not` add primary-key filters as a disjunction.** Both fold into the preceding `WHERE` clause the same way `or_where` does, and both ship `or_filter_key` and `or_filter_key_not` aliases.
- **`Builder::in_order_of` sorts rows into an explicit sequence.** Pass a column and the values in the order you want them; rows whose value is not in the list sort last. The values bind as parameters, so they are safe to take from request data.

### Fixed

- **The maintenance bypass cookie now expires on the server.** The 12-hour TTL was a `max-age` the browser enforced, so a captured cookie kept working until you rotated the secret. The encrypted payload now carries the deadline, and every request re-checks it.
- **`suprnova serve` runs a frontend-less project.** A project scaffolded with `suprnova new --api` has no `frontend/` directory, and `serve` rejected it as "No frontend directory found. Are you in a Suprnova project directory?" unless you passed `--backend-only`. It now skips the Vite pane and the TypeScript generation that feeds it, and serves the backend. `--frontend-only` still fails on such a project, with a message that says why.

### Upgrading

- **Bypass cookies issued before this release stop working.** The cookie's payload changed from the bare secret to a sealed `{ secret, expires_at }` object, and a payload with no deadline is refused. Visit the secret URL once after upgrading to get a new cookie. Nothing else changes: `down`, `up`, `--secret`, and `--with-secret` all behave as before.
- **An include path longer than five segments now returns its first five relationships instead of all of them.** Nothing outside a resource's allowlist was ever reachable, so no response gains data; a deep path loses its tail. One status code changes with it: a path whose over-deep tail names a relationship the resource does not allow is truncated before anything validates it, so it now returns `200` with the segments that survived where the full path used to return `400` - adjust any client or test asserting on that rejection. Raise the ceiling with `suprnova::max_relationship_depth(n)` if your API documents paths longer than that.
- **`DatabaseConfig` gained five public fields.** Code that builds one with a struct literal no longer compiles. Use `DatabaseConfig::from_env()` or `DatabaseConfig::builder()`, both of which fill the new fields with the defaults that preserve today's pool behavior.

## 1.3.3 - 2026-08-25

### Added

- **Failover queue connection.** `FailoverQueueDriver` wraps an ordered list of
  connections: a push the first one refuses is retried on the next, and so on
  down the list. Wire it from env with `QUEUE_DRIVER=failover` plus
  `QUEUE_FAILOVER_CONNECTIONS=redis,database` (each entry reads its own
  driver's variables, so a `database` entry still needs `DB::init()` first and
  still brings its failed-jobs store), or build it directly with
  `FailoverQueueDriver::new(vec![(label, driver), ...])`. Only writes fall
  through: `push` and `bulk_push` walk the list, while `pop`, `pop_from`,
  `ack`, `nack`, `release`, `settle`, `clear`, all four counters and all three
  inspection listings delegate to the first connection and no other, because a
  reservation token is meaningful only to the driver that issued it. The
  operational consequence is documented rather than papered over: a worker on
  the failover connection drains the primary only, so whatever failed over to a
  fallback needs its own worker. `bulk_push` pushes each envelope separately
  rather than forwarding a batch, which both preserves each envelope's own
  `available_at` (Laravel #60950) and keeps a batch the primary half-accepted
  from being re-pushed wholesale onto the fallback. A refusal dispatches
  `queue::events::QueueFailedOver { connection, job_name, exception }`,
  edge-triggered: a connection reports itself once when it enters failure and
  stays quiet until a later push succeeds on it and re-arms it, so an outage
  produces one alert instead of one per dispatch. When every connection
  refuses, the push returns the last connection's error. An empty connection
  list, a missing or blank `QUEUE_FAILOVER_CONNECTIONS`, a nested `failover`
  entry, and an entry naming a driver that doesn't exist are all boot errors -
  the warn-and-fall-back-to-memory behaviour stays on `QUEUE_DRIVER` itself,
  where a typo can't splice an ephemeral backend into a durable chain.
- **Queue inspection API.** `Queue::pending_jobs(queue)` / `delayed_jobs` /
  `reserved_jobs` list the actual envelopes behind the existing
  `pending_size`/`delayed_size`/`reserved_size` counters, as `InspectedJob`
  DTOs (`id`, `queue`, `name`, `attempts`, `payload`, `created_at`) - mirrors
  Laravel's `InspectedJob`. A single `Option<&str>` queue filter collapses
  Laravel's `pendingJobs($queue)` / `allPendingJobs()` pair (and the
  `delayedJobs`/`reservedJobs` equivalents) into one call each. The
  `QueueDriver` trait default is an honest `Err` - not Laravel's
  Beanstalkd/SQS empty-collection default, which reads as "nothing queued"
  even when there plainly is - so a driver that has not implemented
  inspection says so; `sync`/`null` override with `Ok(vec![])` because for
  them that really is the truth. The memory, database, and Redis drivers all
  implement the full listing: the memory driver's delayed storage moved from
  a bare `DelayQueue<Envelope>` (which cannot be iterated) to a
  `DelayQueue<Uuid>` plus an id-keyed map; the database driver reuses the
  size counters' exact predicates plus `ORDER BY available_at`, and a row
  whose `envelope_json` fails to decode is still listed (`id: None`,
  `payload: {"unparseable": true}`) rather than dropped, so one poison row
  can't blind an operator to the rest of the queue; Redis's `reserved_jobs`
  is scoped to this consumer's in-process reservations (documented), and
  `pending_jobs` scans the stream via `XRANGE` in batches. `Queue::fake()`
  gained matching `pending_jobs()`/`delayed_jobs()` helpers, projecting
  recorded pushes with `attempts` always `0` and `created_at` always `None`.
- **After-commit dispatch.** `Job::after_commit()` holds a push until the
  surrounding `DB::transaction` commits, so a worker on another process can
  never pop an envelope that describes rows the transaction has not made
  durable yet. The whole push waits, not just the driver write: the envelope
  build, `JobQueueing` and `JobQueued` all happen at commit time, so no
  listener is ever told about a job a rollback then discards. A rollback
  discards the push entirely; outside a transaction the push happens
  immediately, which is what lets a job type declare the opt-in without every
  dispatch site knowing whether its code path is transactional. Per dispatch,
  `EnvelopeOverrides::after_commit` outranks the job: `Some(true)` (with the
  shorthand `Queue::push_after_commit(job)`) defers a job that did not opt in,
  and `Some(false)` is Laravel's `beforeCommit()`. A deferred `Queue::push`
  re-resolves `Job::delay()` against the commit rather than the push, while
  `Queue::push_later` / `later` / `later_with` carry the caller's absolute
  timestamp through unchanged. `Queue::push_unique` takes its dedupe lock
  immediately even when the envelope is deferred, so a duplicate inside the
  same transaction is still suppressed, and a rollback releases that lock
  owner-scoped. `Queue::bulk` defers as a unit. `Queue::fake()` records a push
  immediately, deferral and all, matching Laravel's `Bus::fake`. Manual
  `DB::begin_transaction` never defers - it installs no ambient transaction, so
  there is no commit to hang a callback on. Every ending that leaves the commit
  unlanded compensates identically, including a `COMMIT` the database refuses
  and a leaked `TxHandle` that blocks one, and `Transaction::rollback_to` counts
  as one for the scope it unwinds: a push deferred inside a savepoint is
  discarded when that savepoint rolls back and its lock is released right then,
  while anything registered before the savepoint is untouched. Queued mail,
  notifications, batches and chains do not defer yet.
- **Unique-until-processing jobs.** `Job::unique_until_processing()` releases the
  uniqueness lock when processing begins - after the job's middleware pass,
  immediately before the handler runs - instead of holding it for the full
  `unique_for` window, which is what you want when the lock exists to coalesce
  queued duplicates rather than to serialize execution. A job that a middleware
  releases back onto the queue keeps its lock, because it has not started
  processing; a job a middleware deletes or dead-letters gives its lock up.
  Release is owner-scoped: `Queue::push_unique` records the cache lock's owner
  token on the envelope (`Envelope::unique_lock_owner`, an additive field that
  leaves the frozen wire format byte-identical for every non-unique push), and
  the worker releases with that token, so a redelivered attempt can never
  force-release a lock a newer dispatch now holds. The supporting idempotency
  surface is public too: `Idempotency::commit_on_success_owned` hands the body
  the lock owner and returns it, and `Idempotency::release_owned(key, owner)`
  releases owner-scoped, reporting `Ok(false)` rather than an error when the
  lock is absent or held by somebody else. Plain `unique_id` jobs are unchanged
  and still let the `unique_for` TTL be the dedupe window.
- **`Gate::default_denial_response` customizes the default shape of a bare denial.** Mirrors
  Laravel's `Gate::defaultDenialResponse($response)`. Set once - typically in
  `bootstrap::register()` - it reshapes exactly two outcomes: a bare `false` (a bool gate -
  `Gate::define` / `Gate::define_async`, including a `#[policy]` method returning `bool` - or a
  `before`/`after` hook that decided `false`) and an evaluation nothing else decided at all (an
  undefined ability with no hook opinion either). All of those used to collapse to a bare
  `Response::deny()` (a 403); now they surface as whatever `Response` the default carries, e.g.
  `Response::deny_as_not_found()` for a 404 that hides a resource's existence application-wide
  instead of gate by gate. The default applies to bare `false` only - a gate registered with
  `define_with` / `define_async_with` already returned the `Response` it wanted, and that always
  passes through `Gate::inspect` untouched, matching Laravel's own rule that the default never
  substitutes for a returned `Response` object. A default shaped as `Response::allow()` is
  rejected (logged, ignored) rather than silently inverting every bool gate to allowed - see
  `Gate::default_denial_response`'s doc comment for the one place this deliberately diverges from
  Laravel, which has no such guard.
- **The `Password` validation rule family ships, including the Have I Been Pwned
  `uncompromised()` check.** `Password::min(n)` plus the strength builders
  (`.max()`, `.letters()`, `.mixed_case()`, `.numbers()`, `.symbols()`) port
  Laravel's `Password` rule regexes verbatim - a plain space satisfies
  `.symbols()`, matching Laravel's `\p{Z}` separator class. `.uncompromised()`
  (or `.uncompromised_with_threshold(n)`) checks the password against Have I
  Been Pwned's k-anonymity range API: only the first 5 characters of the
  password's SHA-1 hash ever leave the process, and a network failure,
  timeout, or non-2xx response fails open rather than blocking signups,
  exactly like Laravel's `NotPwnedVerifier`. Because that check is an HTTP
  round trip, `Password` is the one built-in rule implementing both `Rule`
  (strength only, for sync `validate!` rows) and `AsyncRule` (strength, then
  the HIBP check, for `after_validation_async`) - calling the sync path on a
  `Password` configured with `uncompromised()` is a loud, developer-facing
  error rather than a silent skip. `Password::defaults_with(...)` sets the
  process-wide default `Password::defaults()` returns. New `HIBP_TIMEOUT_SECS`
  env var (default 30s). `Http::fake_response_text(...)` is the new raw-body
  sibling of `fake_response(...)` for tests against `text/plain` upstream
  APIs like HIBP's.
- **A scheduled task can now name the timezone its cron expression is read
  in, and `schedule:list` can render the whole schedule in any zone.**
  `.timezone(chrono_tz::Tz)` pins one task, `.try_timezone("Area/City")` is
  the fallible sibling for a zone name that only exists at runtime, and
  `Schedule::timezone(tz)` sets a default for every task registered after
  it. Nothing changes for a task that pins no zone: it is still evaluated
  against the process's local zone. A pinned zone affects due-ness only -
  the scheduler still ticks once per process minute and the same-minute
  dedup gate is untouched. Note that a zone observing daylight saving makes
  some wall-clock minutes happen twice and others not at all, so a task
  pinned to such a minute can run twice or be skipped; the scheduling
  chapter carries the full warning. `schedule:list` gained a `--timezone`
  option and two columns: the zone a printed expression is written in, and
  the next minute the task fires. A pinned task's expression is rewritten
  into the listing's zone, splitting into several lines when it straddles
  midnight there, and is left exactly as written when a faithful rewrite is
  impossible - across a daylight-saving transition, when a day rollover
  would have to move a restricted day-of-month and day-of-week together, or
  when it would have to decide how long February is. `chrono_tz::Tz` is
  re-exported from the crate root, so consuming apps do not add `chrono-tz`
  to their own `Cargo.toml`.
- **A Laravel-shaped image subsystem, in `suprnova::media` behind the default-on
  `media` feature.**
  `Image::from_bytes/from_path/from_disk/from_upload/from_stream` builds a lazy
  pipeline - `resize`, `scale`, `crop`, `cover`, `contain`, `rotate` at any
  angle, `flip_vertically`/`flip_horizontally`, `blur`, `sharpen`, `grayscale`,
  `to_format`, `quality` - finished with `to_bytes`, `to_response`, `save`,
  `store`, `dimensions`, `mime_type`, or `dominant_color`. Reads and writes
  PNG, JPEG, WebP, GIF, and BMP; AVIF output is deferred until the in-house
  AV1 encoder publishes, at which point it is one new `OutputFormat` variant
  and no other change. Like Laravel's `gd`/`imagick` split there are two
  drivers: `IMAGE_DRIVER=oxideav` (the default) runs on the pure-Rust
  [OxideAV](https://github.com/OxideAV) codec family with no native library
  and nothing to install, and `IMAGE_DRIVER=magick` shells out to a
  host-installed ImageMagick 7 for wider input support including HEIC.
  Decode limits (`IMAGE_MAX_DIMENSION`, `IMAGE_MAX_ALLOC_BYTES`) are checked
  against the input's own header before anything is allocated - including the
  inner bitstream of an extended WebP, whose advisory canvas size cannot be
  used to smuggle a larger frame past the gate - and all pixel work runs on a
  blocking thread. The `magick` driver pins the input coder by name rather
  than letting ImageMagick pick one from the bytes, and bounds every
  invocation with `IMAGE_MAGICK_TIMEOUT_SECS`. `ImageDriver` is the trait
  boundary for anything else. The module is named `media` because the
  OxideAV-backed audio and video surfaces will live beside it.
  [Images](images.md)
- **The WebP gate carries one fixed, non-configurable bound.** A WebP declares
  its real decoded size in its innermost bitstream chunk, so the framework
  walks the container to find it; that walk visits at most 4096 chunks per
  level and follows two levels of nesting, and a file past either is refused
  rather than measured. Reporting a number from an unfinished walk would be a
  gate that enough filler chunks could step around. No `IMAGE_MAX_*` variable
  affects it and the error says as much. A 300-frame animation is unaffected;
  a 4100-frame one is refused. [Images](images.md#one-bound-is-not-configurable)

- **OAuth can now be installed without replacing an application's existing
  password and session authority.** `MagnetarOAuthOnlyConfig` and
  `init_magnetar_oauth_only` install the default ceremony and provider engine
  while leaving the password and passkey slots empty. Applications with an
  existing `users` table can call `verify_oauth_identity`, map the verified
  provider subject themselves, and establish their normal framework session.

### Changed

- **`DB::transaction` can now return `Err` after a successful commit**, when an
  after-commit callback fails: the message reads `after-commit callback failed
  (the transaction itself committed): …`, the closure's return value is lost and
  its writes are not. `DB::transaction_with_attempts` never retries that error,
  however deadlock-shaped the callback's own message reads - re-running a closure
  whose writes are already durable would apply them twice.
- **New validation catalog key: `validation-password-unverifiable`.** A custom
  `UncompromisedVerifier` that returns `Err` no longer puts its own error text
  in the 422 body verbatim. That text is logged at `error` instead, and the
  response carries this key, rendering as "The { $field } could not be checked
  against known data leaks. Please try again." - the check did not run, which is
  not the same as the password being bad, and infrastructure detail does not
  belong in a client response. An app shipping its own validation catalog has to
  add the key, or its users see the built-in English fallback.
- **The `Image` upload validator is now `ImageFile`.** `suprnova::Image` is the
  new image-manipulation pipeline type, matching `Illuminate\Image\Image`,
  and the magic-byte upload rule takes the name Laravel gives the same rule
  class, `Illuminate\Validation\Rules\ImageFile`. Migration is one line per
  use site: `UploadedFile<(Image, MaxSize<N>)>` becomes
  `UploadedFile<(ImageFile, MaxSize<N>)>`. Pre-1.0 churn absorbed by the
  git-tag distribution model.

### Removed

- **The unused direct `image` dependency is gone.** It had been a base
  dependency with zero use sites anywhere in the workspace, pulling JPEG, PNG,
  WebP, and GIF codecs in for nothing; dropping it removes `gif`, `image-webp`,
  `zune-jpeg`, `color_quant`, and `weezl` from the tree. The crate itself still
  appears transitively, with only its `png` feature, behind `totp-rs`'s
  QR-code rendering. The new image subsystem is built on the OxideAV crates
  behind the `media` feature instead.

### Fixed

- **Installing OAuth no longer forces provider-backed applications into
  Magnetar web-binding validation.** The full `init_magnetar` path remains
  atomic and unchanged. The OAuth-only path reserves the engine slots during
  construction, publishes only OAuth, and fails rather than mixing two
  authentication authorities.

### Upgrading

- **`Image` is a different type now; the upload validator is `ImageFile`.**
  Source-breaking for anyone using the magic-byte upload rule. Rename it at
  every use site: `UploadedFile<(Image, MaxSize<N>)>` becomes
  `UploadedFile<(ImageFile, MaxSize<N>)>`. `suprnova::Image` still resolves, but
  it is now the image-manipulation pipeline type, so a missed rename fails to
  compile rather than changing behaviour silently.
- **`EnvelopeOverrides` gained a public `after_commit: Option<bool>` field.**
  Every construction in this repo and in the scaffolded templates uses
  `..Default::default()`, which needs no change. Code that builds an
  `EnvelopeOverrides` with an exhaustive struct literal has to name the new
  field; `after_commit: None` keeps today's behaviour, which is to defer to
  `Job::after_commit()`. Nothing else changes: `after_commit()` defaults to
  `false`, so no existing job starts waiting for a commit it did not before.
- **`Envelope` gained a public `unique_lock_owner: Option<String>` field.** The
  wire format is unchanged - the field is `#[serde(default)]` and skipped when
  `None`, so envelopes round-trip byte-identically in both directions and
  `schema_version` stays at 2 - but any code that builds an `Envelope` with a
  struct literal now has to name it. Add `unique_lock_owner: None` unless you
  are deliberately carrying a uniqueness lock across the push. Code that only
  reads envelopes, or builds them through `Queue::push` and its siblings, needs
  no change.

- Use `init_magnetar_oauth_only` instead of `init_magnetar` when the application
  already owns users, passwords, framework sessions, and remember-me state.
  OAuth-only callbacks use `verify_oauth_identity`; full Magnetar applications
  continue to use `complete`.

## 1.3.2 - 2026-08-25

### Added

- **OAuth providers can now be registered through `MagnetarConfig::oauth`.** Suprnova re-exports the `OAuthProvider` contract, all five first-party provider and configuration types, and the HTTP, revocation, abuse-limiter, authorization, and auto-link types an application needs. Custom providers no longer require a direct `suprnova-magnetar` dependency or a hand-retained `MagnetarHostEngine`.

- **A production OAuth transport and framework limiter adapter now ship at the crate root.** `ReqwestOAuthTransport` implements token, userinfo, and revocation I/O with redirects disabled by default, a 30-second timeout, a default `User-Agent`, and a 1 MiB response cap. `FrameworkAbuseLimiter` reuses the configured `RateLimiterDriver`; apps no longer hand-write either adapter.

### Fixed

- **`init_magnetar` now publishes OAuth with password and passkey services as one reserved installation.** The OAuth service is built before publication, and all three engine slots remain hidden while the reservation is active. A failed or duplicate OAuth configuration cannot leave password and passkey state visible without the configured OAuth registry.

- **Custom providers can supply userinfo headers.** `OAuthProvider::userinfo_headers` is merged with the host-owned bearer header, enabling requirements such as GitHub's `User-Agent` and media-type `Accept` headers without allowing a provider to replace `Authorization`.

### Upgrading

- **The Magnetar cutover in `4faaa933` removed Torii's OAuth installation path without wiring its replacement into the default initializer.** The old workaround required constructing a custom host engine, calling `oauth_service`, and installing the adapter separately. Replace that workaround with `MagnetarConfig::from_sea_orm(database).oauth(oauth_config)` and one `init_magnetar` call.

- **GitHub community providers must handle verified email explicitly.** GitHub `/user` usually omits non-public email, while the verified primary address requires `/user/emails`. Return `email: None` to use the email-completion ceremony, or point `userinfo_endpoint` at a host adapter that combines both responses; never treat a public but unverified address as ownership.

## 1.3.1 - 2026-08-24

### Fixed

- **Provider-backed applications can reset verified users again.** When no Magnetar engine is installed, `PasswordReset` uses an explicitly reset-capable `UserProvider` and framework `auth_flow_tokens` for already verified accounts. `EloquentUserProvider<M>` opts in when `M` implements `MustVerifyEmail + CanResetPassword`; no `app_users` migration is required.
- **The published framework line now contains both post-release repair sets.** The translated 1.3.0 changelog layout and headings, CJK wrapping, localized anchors, glossary terms, and prose punctuation are reconciled instead of split across divergent local and remote branches.
- **Post-tag CLI and Magnetar hardening is included.** Development-process cleanup uses the completed process-group fallback, and the local qualification contracts cover the released refs and plugin-SDK SQLite lanes.

### Security

- **The provider fallback never treats password reset as first mailbox proof.** Unknown and unverified addresses receive the same no-mail response. Install Magnetar when an unverified account must prove mailbox ownership through reset so credential cleanup, auth-epoch advancement, and revocation remain atomic. Provider fallback completion reports framework session and remember revocation failures through `PasswordResetOutcome`.

### Upgrading

- **Move every `v1.3.0` Git dependency to `v1.3.1`.** Applications with their own `users` table keep their configured `UserProvider`; they do not initialize the default `app_users` engine merely to reset an already verified account. Applications that use Magnetar credentials or unverified-account first proof continue to initialize Magnetar.


## 1.3.0 - 2026-08-24

### Security

- **Magnetar now fences credential and session mutations to the authenticated
  actor and account auth epoch.** Password, passkey, linked-account,
  two-factor, opaque-session, JWT, remember, OAuth, and device-authorization
  writes reject stale or revoked actors. The first successful password-reset,
  magic-link, or OAuth verified-email proof on an unverified account advances
  the epoch and atomically removes provisional credentials, sessions, remember
  state, and squatter TOTP enrollment. Verified accounts preserve legitimate
  credentials during password reset. Email verification requires the
  authenticated token owner, and OAuth never auto-links an unverified existing
  account from email alone.

- **A protocol-relative `_previous.url` can no longer produce an off-origin open redirect through
  `Redirect::back()`, on either the write side or the read side.** `SessionMiddleware` no longer
  persists a protocol-relative current URL: the write goes through the identical sanitizer
  `InertiaValidationRedirectMiddleware` uses for its `Referer` check, and a request path shaped
  like `//host` (or carrying an ASCII control byte) is never recorded - without this, an app's
  `fallback!` route (the standard Inertia/SPA app-shell pattern, where any unmatched path answers
  `200`) could have `GET //evil.test/anything` persist that path verbatim. `SessionData::previous_url()`
  now applies the same check on every **read**, too, so a session cookie that survived an upgrade
  from a release before this fix - already carrying a raw, unsanitized value no write in the
  current process ever produced - self-heals to "nothing recorded" instead of being trusted.
  Together, neither an old poisoned cookie nor a new malicious request can hand `Redirect::back()`,
  `Redirect::refresh()`, or `url::previous()` an off-origin `Location`. When a value fails either
  check it's treated as absent rather than replaced with a synthesized one, so a genuinely good
  previous URL is never clobbered.
- **The Inertia validation-redirect bridge's `Referer` check closed two more same-origin bypasses.**
  `InertiaValidationRedirectMiddleware`'s `303` target only rejected a `Referer` starting with the
  literal `//` or `/\` prefix - a value like `Referer: /<TAB>/evil.test` slipped through, because
  the WHATWG URL parser strips ASCII tab and newline from the whole string before comparing
  origins, so a browser reads that as `//evil.test` and follows the `303` off-origin. The check now
  rejects any ASCII control byte (C0 or DEL) anywhere in the candidate, not only within the two
  named prefixes. Separately, the last-resort fallback - the failing request's own path, used when
  neither `Referer` nor the session's previous URL is usable - was never sanitized: an origin-form
  HTTP request-target is syntactically free to start with `//`, so a raw client or a
  non-normalizing proxy could turn the "safe last resort" into an off-origin redirect too. Both
  legs now share one root-relative check, falling back to `/` if even the request's own path fails
  it.
- **Cookie ciphertext is now bound to its logical cookie name with contexted v2 AAD.** `Cookie::encrypted` /
  `Cookie::read_encrypted_for` stop a value minted for one cookie slot from decrypting in another slot,
  while the logical-name binding keeps a later `__Host-` / `__Secure-` wire-prefix flip safe. The
  version-less compatibility window tries v2 across the whole key ring, then v1 across the whole ring,
  so existing cookies survive the rollout; the v1 fallback preserves the old replay weakness until its
  scheduled 1.4.0 removal.
- **Session and remember-me cookie prefixes are validated at boot and enforced at render time.**
  `SESSION_COOKIE_PREFIX=__Host-` requires `Secure`, `Path=/`, and no `Domain`; `__Secure-` requires
  `Secure`. Invalid boot combinations fail before serving, and the renderer rewrites invalid prefixed
  headers instead of letting browsers discard them silently.

### Added

- **Suprnova authentication now runs on the internal Magnetar engine.** The
  framework-owned `Auth` facade preserves existing password, magic-link,
  passkey, OAuth, bearer, lockout, session, and two-factor call sites while
  removing the Torii dependency. The default engine installs password/session
  and passkey adapters atomically, stores lifecycle delivery leases in the
  application database, and shares the application's canonical `i64`
  `app_users` identities.
- **A shape-aware authentication migration runner now covers Torii, Suprnova
  web, and Suprnova API sources.** Dry runs bind a stable plan id to durable
  row and schema fingerprints plus destination identity decisions. Apply uses
  transactional imports, retry ledgers, shape-owned cleanup, and collision
  refusal. MySQL uses a write-barrier-protected shadow swap with pre-copy
  journals, row and schema parity, resumable renames, and cleanup-preserving
  restore.
- **`MAIL_DRIVER=file` writes one RFC 5322 `.eml` per message** to `MAIL_FILE_PATH` (default
  `storage_path("mail")`; a relative value anchors at the application base directory, not the process
  CWD), so local mail can be opened in a mail client instead of read out of a log line. The
  file carries the same header superset SMTP emits, including `X-Priority`, `Importance`, `X-Tag`,
  `X-Metadata-*`, and `Return-Path`. Like `log` and `memory`, it does not deliver: a production boot
  refuses it unless `MAIL_ALLOW_NON_DELIVERING_IN_PRODUCTION=true`.
- **`FrameworkError::External` carries the error it wraps.** `FrameworkError::from_external(e)` and
  `FrameworkError::from_external_with("saving user", e)` keep the original error reachable as a
  `std::error::Error` source instead of melting it into a string. `FrameworkError::external_source()`
  returns it for downcasting - use that rather than `source()`, which yields the shared `Arc` handle.
  Both constructors map to HTTP 500.
- **5xx logs now render the full error source chain.** `render_error_chain` walks `source()` and is
  wired into the framework-error log line, the `ErrorOccurred` event payload, and the `debug_message`
  field emitted under `APP_DEBUG=true`. Client-facing response bodies are unchanged and 5xx bodies
  stay sanitised.
- **`InertiaResponse::scroll_wrapped` / `scroll_with_wrapped` / `try_scroll_wrapped`.** Nest a scroll
  prop's merge instruction under `<key>.<wrap_key>` instead of the bare key - `mergeProps:
  ["users.data"]` rather than `["users"]` - for a value that's itself an envelope (`{ data: [...], meta:
  {...} }`). Laravel's `ScrollProp` wraps under `"data"` unconditionally; Suprnova's built-in paginators
  hand back a bare row array, so this is opt-in rather than a default every caller has to work around.
  New `ProvidesScrollMetadata` trait (`page_name` / `previous_page` / `next_page` / `current_page`, with
  a default `scroll_metadata()`) mirrors Laravel's interface of the same name for a paginator this crate
  doesn't know about; `LengthAwarePaginator`, `Paginator`, and `CursorPaginator` now implement it instead
  of building `ScrollMetadata` by hand. A scroll prop's `.match_on(...)` fields now also emit into
  `matchPropsOn`, matching Laravel's `resolveMergeMatchingKeys` (`Response.php:641-652`), which folds a
  `ScrollProp`'s `matchesOn()` in the same as any other merge prop - the match entry keys off wherever the
  prop actually merges, `<key>` unwrapped or `<key>.<wrap_key>` under `.scroll_wrap(...)`.
- **`Prop::merge_with_path`, multi-field `match_on`, and resolver-backed merge props.**
  `Prop::merge_with_path(path)` merges a nested field inside a prop's value instead of the whole
  prop - `Prop::eager(v).merge().merge_with_path("data")` emits `mergeProps: ["<key>.data"]`, and a
  path-merging prop never also merges its root; `.deep_merge()` ignores it, since a deep merge
  already recurses into every field. `Prop::match_on` now takes one field or several in one call
  (`match_on(["id", "slug"])`) on top of the `match_on("id").match_on("slug")` chaining `Prop`
  composition already supports. `InertiaResponse::merge_lazy` / `merge_lazy_with` add the
  resolver-backed siblings of `.merge` / `.merge_with`, matching Laravel's
  `Inertia::merge(fn () => ...)`.
- **Partial-reload `only`/`except` understand dot notation.** `X-Inertia-Partial-Data: user.name`
  narrows the `user` prop to `{ name: ... }` instead of requiring the whole value or nothing;
  `X-Inertia-Partial-Except: user.email` prunes just that field, leaving the rest of `user` in place.
  `except` wins on a path both headers name, a bare entry still means the whole prop, and an unknown
  or type-mismatched nested path drops silently without touching its siblings. `Always` props are
  unaffected - they always ship whole.
- **Dot-key prop nesting.** `.with("user.name", value)` (and any other prop-attaching method, eager or
  resolved) now nests into `props.user` instead of shipping a literal `"user.name"` key, matching
  Laravel's `Arr::set`-based `resolveArrayableProperties` unpacking. Two calls sharing a prefix -
  `.with("user.name", …)` then `.with("user.age", …)` - accumulate into one object; a key with no dot is
  unaffected. `App::inertia_share*` shared-registry keys nest the same way on the wire. The unpacking
  only ever touches top-level prop *keys* - it never recurses into a prop's value, so a validation
  `errors` bag keeps whatever dotted field names it carries internally.
- **`App::inertia_shared(key)` / `App::flush_inertia_shared()`.** Laravel's `Inertia::getShared` /
  `Inertia::flushShared`, reading and clearing the static share registry (`App::inertia_share` / `_lazy`
  / `_once`). `inertia_shared` supports the same dot notation as `inertia_share` for the read side; it
  returns `None` for a lazy or once share (there's no request to resolve one against) and for an
  unregistered key. `flush_inertia_shared` clears only the static registry - a trait provider registered
  via `App::register_inertia_shared` is untouched, matching Laravel (there's no per-request state there
  to flush).
- **`InertiaResponse::always_with(key, resolver)`.** The async-resolver sibling of `.always(key, value)`,
  for an always-included prop expensive enough to be worth resolving lazily - Laravel's
  `Inertia::always(fn () => …)` (`AlwaysProp` accepts any value, closures included).
- **`InertiaSharedData::share` now receives the page component name**, so a provider can vary its output
  by page - Laravel's `RenderContext`. See Upgrading.
- **Inertia prop composition.** A `Prop` now carries orthogonal flags instead of being one of nine
  closed variants, so a single prop can be deferred *and* mergeable, mergeable *and* cached, or
  optional *and* cached - the combinations the Inertia 3 protocol expects and a closed enum could
  not spell. Build one with `Prop::eager` / `Prop::lazy` / `Prop::from_resolver` / `Prop::absent`,
  chain `.always()`, `.optional()`, `.defer()`, `.group()`, `.rescue()`, `.merge()`, `.prepend()`,
  `.deep_merge()`, `.match_on()`, `.once()`, `.as_key()`, `.until()`, `.fresh()`, `.scroll()`, and
  attach it with the new `InertiaResponse::prop(key, prop)`. A `defer().merge()` prop is announced
  under `deferredProps` on the first render and arrives under `mergeProps` on the follow-up request.
  New `MergeMode` and `Visibility` types describe the flags; every existing builder shortcut
  (`.with`, `.always`, `.lazy`, `.optional`, `.defer`, `.merge*`, `.once*`) is unchanged.
- **Queue pause / resume.** `Queue::pause(connection, queue)` / `resume` / `pause_all()` /
  `resume_all()` / `is_paused(connection, queue)` / `paused_queues(connection, &queues)`, backed by
  `Cache` the same way the restart signal is - `resume_all` does not clear a per-queue pause,
  matching Laravel. The worker's claim gate sits right before every pop, so an in-flight job always
  finishes; a global pause short-circuits `--queue=...` filtering the same way Laravel's
  `pausedQueues` does, and a per-queue pause only takes effect on a worker started with an explicit
  `--queue=...` list. New CLI commands `queue:pause [queue] [--all]` / `queue:resume [queue] [--all]`
  (alias `queue:continue`), plus `QUEUE_PAUSABLE=false` for an operator to disable the feature -
  an unpausable worker ignores pause signals, and `queue:pause` itself refuses to run. New events:
  `QueuePaused` / `QueueResumed` / `QueuesPaused` / `QueuesResumed`.
- **`suprnova::testing::TestResponse`** - a fluent, Laravel-`TestResponse`-shaped wrapper over the
  `(status, headers, body)` triple every HTTP test harness already produces: `assert_status`,
  `assert_ok`, `assert_redirect`, `assert_json`, `assert_json_path`, `assert_json_count`,
  `assert_see`, `assert_header`, `assert_cookie`, and (given `.with_session_store(...)`)
  `assert_session_has`. Every assertion returns `&Self` and panics on failure, the same contract as
  `expect!`. Nothing about how a test drives a request has to change.
- **`suprnova new` scaffolds an SSR entry.** Every starter (Svelte, React, Vue) now ships
  `frontend/src/ssr.{ts,tsx}` and a `build:ssr` npm script (`vite build --ssr`), wired to its own
  output directory (`frontend/bootstrap/ssr/`) so the SSR bundle never collides with the client
  build in `public/assets/`.
- **`InertiaConfig::ssr_bundle_path(path)` / `.ssr_ensure_bundle_exists(bool)`.** The SSR gateway
  can now check the built bundle exists on disk before dispatching a render, mirroring Laravel's
  `ensure_bundle_exists` config - a worker that was never started, or a bundle that was never
  built, fails fast instead of paying `ssr_timeout` on a connection that was never going to
  succeed. Opt in with `.ssr_bundle_path(...)`; unlike Laravel's `BundleDetector` the path is never
  auto-detected, so existing SSR configs (and tests) that don't set one are unaffected.
- **Validation failures on an Inertia visit now redirect back instead of returning `422` JSON.**
  `Inertia::install` registers a fourth middleware, `InertiaValidationRedirectMiddleware`, which
  turns a validation `422` on an `X-Inertia` request into a `303` to the form page with the errors
  flashed - so `useForm().errors` fills in with no handler code. The Inertia client treats any
  response without an `X-Inertia` header as non-Inertia and shows its error modal, so the old `422`
  could never reach `form.errors`. Non-Inertia requests keep the `422` envelope, Precognition
  dry-runs are untouched, and `X-Inertia-Error-Bag` scopes the flashed bag. The redirect target is
  the same-origin `Referer`, then the session's previous URL, then the request's own path run
  through that same sanitizer, falling back to `/` if even that fails it - never trusted verbatim.
- **`InertiaConfig::with_all_errors(bool)`** - keep every validation message per field instead of
  collapsing to the first. Mirrors Laravel's `Inertia\Middleware::$withAllErrors`.
- **`suprnova::testing::AssertableInertia`** - fluent, Laravel-`AssertableInertia`-shaped assertions
  over an Inertia page object, parsed from either an `X-Inertia` JSON response or a hard-navigation
  HTML shell's embedded `<script data-page="app">` element: `component`, `url`, `version`, `prop`,
  `has`, `missing`, `where_`, `count`, `has_flash`. Build one from an `HttpResponse` with
  `AssertableInertia::from_response`, or from a `TestResponse` with the new
  `TestResponse::assert_inertia()`. `reload_only`, `reload_except`, and `load_deferred_props` replay
  a partial reload against a caller-supplied `with_reload(...)` closure - Suprnova's HTTP tests cross
  a real socket, so there's no single in-process test client to hardcode against.
- **`Cookie::queue`/`queued`/`unqueue`/`expire`.** A task-local cookie jar - Laravel's `CookieJar` -
  lets any code queue a cookie for the next outgoing response without holding an `HttpResponse` to
  attach it to: an event listener, a container-bound service, middleware ahead of the handler.
  Backed by the same per-request slot `Auth::login_remember` already uses to carry the remember-me
  cookie past the handler boundary; `SessionMiddleware` drains it onto the response next to the
  session cookie. `Cookie::expire(name, path, domain)` queues a deletion cookie built with
  `Cookie::forget_with`. Requires `SessionMiddleware` in the route's middleware chain - outside it,
  all four calls are a silent no-op, matching `App::flash`'s behavior outside a flash scope.
- **`HttpResponse::event_stream(stream, end)` and `HttpResponse::stream_json(stream)`.** Laravel's
  `ResponseFactory::eventStream` / `streamJson`, and the exact wire shapes
  `@laravel/stream-{react,vue,svelte}`'s `useEventStream` / `useJsonStream` expect. `event_stream`
  frames a `Stream<Item = sse::StreamedEvent>` as `event: update` per item unless the item names its
  own event, JSON-encodes any non-string payload, and appends a configurable terminal frame
  (`EndSignal::default()` is `data: </stream>`; `EndSignal::None` omits it). `stream_json` streams
  any `Stream<Item = impl Serialize>` as one incrementally-flushed JSON array. Both are built on the
  existing `sse`/`stream_bytes` body pipeline, so they share its cancellation and panic-isolation
  behavior with the rest of the framework.
- **`suprnova serve` respawns a crashed dev process instead of tearing the whole session down.**
  Exponential backoff between attempts - 200ms, doubling on each consecutive crash, capped at 5s,
  resetting to the floor once a process has stayed up 30s. `--no-restart` opts out and restores the
  previous behaviour. `--restart-tries <N>` (default `5`, matching Laravel's `--restart-tries=5`)
  gives up retrying a process after that many consecutive crashes instead of retrying forever,
  printing an actionable message and leaving the other processes - and the session itself - running.
  `--timestamps` prefixes every forwarded line with `HH:MM:SS`. A new `Suprnova.toml`
  `[[serve.process]]` array lets a project declare its own dev processes - Laravel's
  `DevCommands::register` - to run alongside the backend and frontend, each with its own `[name]`
  prefix and an optional color; an unknown key or a blank `name`/`command` in an entry is now a hard
  parse error instead of silently ignored or a later opaque spawn failure. `--json` emits one JSON
  object per line (NDJSON) on stdout instead - process start, output, exit, restart-scheduled,
  restart-succeeded, gave-up, types-regenerated, and shutdown events, including the file watcher's
  own regeneration notices and the `Ctrl+C` handler's shutdown notice, both of which now stay off
  stdout under `--json` too - for scripting and log pipelines; combining it with `--timestamps` is
  harmless but redundant, since every event already carries its own timestamp.
- **`RequestBuilder::retry_when(predicate)`.** A predicate consulted before every retry the
  built-in policy (`.retry(...)` / `.retry_non_idempotent(...)`) would otherwise make, receiving a
  `RetryContext { attempt, method, url, outcome: RetryOutcome::TransportError | Status(u16) }`. It
  composes with the policy rather than replacing it: `false` vetoes a retry the policy would have
  made; it can never force one past `max_attempts` or one the policy wouldn't otherwise attempt
  (a 4xx status, or a non-idempotent method without `retry_non_idempotent`).
- **`#[model(touches = [...])]` now actually touches.** After a child is created, saved, updated, or
  deleted, each `BelongsTo` owner named in the list gets one
  `UPDATE <owner> SET updated_at = ? WHERE <key> = ?`, on the same executor as the write that
  triggered it - so inside a `DB::transaction` the touch joins that transaction and rolls back with
  it. An owner whose model has `timestamps = false` is skipped, not written and not an error
  (Laravel 13.25 closed the same gap). Owners reached through a `NULL` foreign key, and soft-deleted
  owners, are skipped too. A `touches` entry that doesn't name a declared `BelongsTo` relation is now
  a compile error; polymorphic owners are not supported yet.
- **`without_touching_on::<M, _, _>(fut)`** - Laravel's `Model::withoutTouchingOn([M::class], $cb)`.
  Suppresses both `m.touch()` and any owner cascade targeting `M`, while owners of other types keep
  bumping. Scopes nest, and the existing `without_touching` now suppresses the owner cascade as well
  as direct `touch()` calls.
- **`Model::touch_owners()` / `touch_owners_with_tx(tx)`** - Laravel's `touchOwners()`, for when you
  wrote the child row through a path the framework doesn't own.
- **Value-shaped validation rules: `ArrayKeys` and `Distinct`.** A new `ValueRule` trait
  (`passes(&self, value: &serde_json::Value)`) sits alongside `Rule`, sharing the same
  keyed-message contract. `rules::ArrayKeys(&[...])` rejects a JSON object carrying any key
  outside the allowed list (Laravel's `array:keys`, #60918); `rules::Distinct { ignore_case,
  strict }` rejects a JSON array with a repeated element (Laravel's `distinct`). `validate!` rows
  accept either kind of rule in the same field list - dispatch is automatic, chosen by which trait
  the rule implements, not by new row syntax.
- **`Job::delay()`** - jobs can declare a default delay (`fn delay() -> Option<Duration>`, default
  `None`), honored by `Queue::push` and `Queue::bulk`: `available_at` becomes `now + delay` instead
  of `now`. An explicit call-site delay still wins - `Queue::push_later(job, at)` and
  `Queue::later(delay, job)` use the caller's timestamp verbatim and never consult `Job::delay()`.
- **`Notification::{queue, timeout, fail_on_timeout, max_tries, backoff}`.** A queued notification
  (`Notify::queue`) now carries its own queue-tuning defaults onto every per-channel
  `SendNotificationJob` push via the `EnvelopeOverrides` primitive `Mail::on_queue` uses -
  `fail_on_timeout(&self) == true` dead-letters on the first timeout instead of retrying, matching
  Laravel's `#[FailOnTimeout]` notification attribute (#61072). All five default to
  `SendNotificationJob`'s existing `Job` defaults, so a notification that overrides nothing is
  unaffected.
- **`Mail::on_queue` / `Mail::on_connection` + `Queue::push_with`/`later_with`.** A queued mailable
  now routes itself with `Mail::to(..).on_queue("emails").queue(mailable)`, or defaults via
  `Mailable::queue(&self)`. Both outrank any `Queue::route` registered for the job and the job's own
  `Job::queue()`/`Job::connection()` - the new `EnvelopeOverrides` primitive behind them
  (`Queue::push_with(job, overrides)` / `Queue::later_with(delay, job, overrides)`) also covers
  timeout, fail-on-timeout, max-tries, and backoff for one push. `MailFake`'s queued snapshots now
  carry the resolved `queue`, with `queued_on(...)` / `assert_queued_on(name, queue)` to assert it.
- **`Application::http_bootstrap(f)`** - an HTTP-only boot hook. It runs after `bootstrap` and only
  on the `serve` / `web:run` path, so the queue, schedule, and workflow workers and the console
  binary never run it. Worker and console container images no longer need a built frontend manifest
  to boot: `Inertia::install` fails closed in production when it is missing, and that check now only
  runs on a process that actually serves HTTP.
- **`Router::inertia(path, component, props)`** - Laravel's `Route::inertia`, for a static page
  whose handler would be one line. Registers `GET` (HEAD falls through to it) and returns a
  `RouteBuilder`, so the route can be named and given middleware. `Router::view` is retained as an
  alias.
- **SES v2 send options.** The SES transport now emits `TenantName`, `ConfigurationSetName`, and
  `ListManagementOptions` on `SendEmail`. Each has a transport-level default
  (`SesMailTransport::tenant_name` / `configuration_set_name` / `list_management`) and a
  per-message header override (`X-SES-TENANT-NAME`, `X-SES-CONFIGURATION-SET`,
  `X-SES-LIST-MANAGEMENT-OPTIONS`), with the header winning. The headers are consumed when the
  request is built and never rendered into the message.
- **`without_cookies` on every response builder.** `HttpResponse`, `Response` (via `ResponseExt`),
  `Redirect`, and `RedirectRouteBuilder` all expire a list of cookies in one call, and `Redirect`
  /`RedirectRouteBuilder` gained the single-name `without_cookie` they were missing. New
  `Cookie::forget_with(name, path, domain)` builds a deletion cookie scoped to the path and domain
  the original was set with - a plain `forget` never clears a cookie set outside `/`.
- **`Queue::fake()` stamps an envelope id on every captured push.** `pushed_with_id::<J>()` returns
  `(job, id)` pairs, and the fake now dispatches the same `JobQueueing` / `JobQueued` pair a real
  driver push does - carrying that id - so a test can correlate a captured push with what its
  listeners saw. Existing fake helpers are unchanged.
- **`UniqueJobSkipped` queue event.** `Queue::push_unique` now dispatches
  `queue::events::UniqueJobSkipped { job_name, unique_id, connection }` when it suppresses a
  duplicate, so a dedupe is observable instead of silent. The call's return value is unchanged
  (`Ok(false)`).
- **`model_keys()` on the query builder and on collections.** `User::query().model_keys().await?`
  returns every matching row's primary key without hydrating a single model, projecting the
  table-qualified key (`users.id`) so the query survives a join. `Collection::model_keys()` is the
  already-hydrated counterpart. `#[suprnova::model]` now also declares the key's Rust type as
  `EloquentModel::Key`, so both return the type `key_type` names rather than a caller-chosen
  turbofish.

### Fixed

- **PostgreSQL soft deletes now use backend-aware placeholders, and generated timestamp writes
  honor declared casts.** `delete()` and `restore()` render PostgreSQL ordinal placeholders instead
  of MySQL and SQLite `?` placeholders. Generated create, update, save, touch, and soft-delete
  writes also convert timestamps through each field's declared `Cast` storage type, so native
  `TIMESTAMPTZ` columns no longer receive text values. Thanks to
  [@i-am-v-alexander-v](https://github.com/i-am-v-alexander-v) for reporting both defects and
  submitting a fix in [PR #3](https://github.com/eas4ai/suprnova/pull/3).
- **Default workspace and Magnetar gate runs no longer require live PostgreSQL or MySQL services.**
  Backend-specific behavior suites are explicit, ignored qualification tests that still fail when
  deliberately invoked without their configured database. Reachability-only tests and permanent
  gate environment requirements were removed, so unrelated changes don't pay for external database
  setup on every verification run.

- **`PartialFilter::narrow` is now `pub`.** Its four sibling predicates (`should_include`,
  `should_include_eager`, `should_include_optional`, and the type itself) were already public, but the
  narrowing pass that makes `should_include_eager`'s `true` answer correct - trimming a resolved value
  down to the dotted paths an `only`/`except` entry actually asked for - was `pub(crate)`. A caller
  building custom partial-reload handling on top of `PartialFilter` had no public way to reproduce that
  narrowing and would ship a value whole under a dotted `only` entry even though `should_include_eager`
  reported the key as included.
- **`MailFake`'s `QueuedSnapshot` can now assert on `.on_connection(...)`.** `Queue::fake()` gained
  `assert_pushed_on_connection` in Wave 3 alongside `assert_pushed_on_queue`; `Mail::fake()` only got the
  queue half, so a mailable queued with a connection override was resolved and applied to the real
  dispatch but unassertable through the fake. New `QueuedSnapshot::connection`, `MailFake::queued_on_connection`,
  and `MailFake::assert_queued_on_connection` close the gap, mirroring `assert_queued_on`'s shape.
- **A dotted shared prop was unreachable by a bare `only` entry.** `App::inertia_share("auth.user", …)`
  followed by `router.reload({ only: ['auth'] })` returned `props: {"errors":{}}` - the share vanished
  outright. The registry stores `auth.user` as one literal key and the `Arr::set` unpacking pass only
  nests it after every prop has resolved, so the partial-reload gate saw the still-flat key and matched
  it against neither `auth` nor anything else. `only`/`except` entries are now symmetric: an entry may
  name a prop's key exactly, a path *inside* it (`user.name`, which narrows), or an **ancestor** of it
  (`auth` against the key `auth.user`, which ships the prop whole, because the caller asked for the whole
  root). A bare `except: ['auth']` drops every prop key beneath it the same way `Arr::forget` drops the
  whole subtree in Laravel's already-nested bag. The prefix must end on a segment boundary, so an
  unrelated `authAgent.user` prop is untouched by either list. Laravel never hits this because
  `Inertia::share` runs `Arr::set` at share time; Suprnova's registry cannot, since a lazy share has no
  value to nest until the request resolves it.
- **A `#[data(lazy(deferred))]` field bypassed the `?include=` allowlist.** The owner-tagged resolution
  path in `resolve_props` selected props with `Prop::is_lazy()`, which is false for anything carrying a
  flag - and a deferred field is `Visibility::Deferred`. The field therefore resolved off the ordinary
  prop path, where no include-set check exists, and shipped to any client that sent the deferred
  follow-up regardless of whether the request opted the field in. `Prop::resolve_with_owner` now gates
  every resolver-backed owner-tagged prop, flags or not, and `resolve_props` runs that gate ahead of
  every other block: a field outside `?include=` is dropped whole (no value, no `deferredProps`
  announcement), and a field named by `?include=` but off the DTO's allowlist raises its `400` before
  `X-Inertia-Partial-Data` can absorb it. Not a regression - the pre-Wave-4 code gated on the `Prop::Lazy`
  enum variant, which a `Prop::Defer` also failed - but a real hole either way.
- **`deferredProps` was re-announced on a matched partial reload.** A partial that named one deferred key
  still advertised every *other* deferred key back to the client, which then fetched them again, and
  again on the next partial. Laravel's `resolveDeferredProps` returns `[]` the moment the request is
  partial, before it inspects a single prop (`Response.php:661-663`); the block is now dropped whole on
  any matched partial. A partial reload aimed at a different component is a standard visit for this gate,
  as for every other, so its announcements are unaffected.
- **The `errors` bag filtered differently depending on where the errors came from.** The session-flashed
  bag is seeded ahead of the resolve loop and no partial-reload filter could reach it, while a handler's
  own `.with("errors", …)` went through the ordinary gates - so `only: ['errors.email']` shipped the whole
  seeded bag but a one-field handler bag, and `only: ['users']` replaced the handler's bag with the seeded
  one instead of leaving the key alone. Both paths now treat `errors` as always-visible, matching
  Laravel's middleware, which shares it as `Inertia::always(...)` and re-injects the raw value through
  `resolveAlways` after the `only`/`except` rebuild. This is the shape the client needs: it folds a
  partial response in with `{...current.props, ...response.props}`, so an empty `errors` object wipes
  messages already on screen where an unfiltered one leaves them correct. An explicit visibility flag on
  the key still wins, so `.prop("errors", Prop::eager(…).optional())` behaves optionally.
- **`Queue::fake()` can now observe per-push `EnvelopeOverrides`.** A job pushed through
  `Queue::push_with`/`Queue::later_with` was indistinguishable from a plain `Queue::push` under
  the fake - `FakePush` carried only the payload and `available_at`, so the override never left
  the facade and nothing could assert a test dispatched to the right queue or connection. New
  `queue::testing::pushed_with_overrides::<J>() -> Vec<(J, EnvelopeOverrides)>` returns each
  captured push paired with what it declared; `assert_pushed_on_queue::<J>(queue)` and
  `assert_pushed_on_connection::<J>(connection)` cover the common single-field case, mirroring
  `MailFake::assert_queued_on`. Every other entry point (`push`, `push_later`, `bulk`,
  `push_unique`, the chain/batch dispatchers) still takes no overrides and records
  `EnvelopeOverrides::default()`, so a plain push reads under the fake exactly as "no override
  declared."
- **An SSR worker that stalled mid-response body could hang a render forever.** `SsrConfig::timeout`
  bounded only the wait for response headers; once headers arrived, reading the body had no
  timeout of its own, so a worker that accepted the connection, sent headers, then stopped sending
  data left the request hanging past the configured timeout instead of falling back to CSR (or
  erroring, under `ssr_throw_on_error`). Both phases now share one deadline, so the configured
  timeout bounds the whole SSR call, as its own doc already promised.
- **Queued cookies - including the remember-me cookie `Auth::login_remember` sets - were silently
  dropped on three internal fail-closed paths in `SessionMiddleware`.** A session read failure, a
  session write failure, and a session-cookie encryption failure each returned a synthesized `500`
  directly, bypassing the pending-cookie drain that runs at the end of `handle`. Anything queued via
  `Cookie::queue` that request - including a remember-me token row already committed to the
  database - never reached the client as a `Set-Cookie` header. All three paths now drain pending
  cookies before returning, the same as a handler-returned error or a redirect. This does not cover
  an uncaught panic, matching Laravel's own queued cookies being lost to one.
- **`Queue::push_unique` now honors `Job::delay()`, matching `Queue::push`, `Queue::push_with`, and
  `Queue::bulk`.** It previously computed `available_at` from `Utc::now()` directly, so a job that
  declared a default delay (`fn delay() -> Option<Duration>`) dispatched immediately when pushed
  through `push_unique` instead of after that delay. `Queue::push_unique_later` and
  `Queue::later_unique` are unaffected - they already take an explicit timestamp or delay from the
  caller and never consult `Job::delay()`, the same rule `push_later`/`later` follow.

### Changed

- **The current development branch uses SeaORM 2.0 and requires Rust 1.94.0.** Suprnova preserves
  its Eloquent, `#[model]`, migration, and database-facade source shapes. Applications that call
  SeaORM directly must import `ExprTrait` for SeaQuery expression methods and use explicit
  `*_raw` connection methods for prebuilt `Statement` values. SeaQuery is now 1.0, and the direct
  MariaDB vector driver uses SQLx 0.9. Existing databases require no application data migration;
  fresh PostgreSQL schemas retain serial-backed primary keys.
- **Three more unused dependencies removed.** `pretty_assertions` and `qrcode` leave the framework
  crate (`totp-rs` already carries the `qr` feature, so QR provisioning for two-factor enrolment is
  unaffected), and `notify-debouncer-mini` leaves the CLI (`notify` itself stays - the `serve` and
  `generate-types` watchers use it directly). All three were confirmed unused by `cargo-udeps` plus
  a source-wide search that covers doc tests.
- **`suprnova-macros` no longer depends on `serde` or `serde_derive_internals`.** Neither was used: the
  `::serde::Serialize` paths the macros emit resolve in the downstream crate, not in the macro crate
  itself. No effect on generated code.
- **`MergeStrategy`'s `match_on` now carries more than one field name.** `Append`, `Prepend`, and `Deep`
  each widen from `match_on: Option<String>` to `match_on: Option<Vec<String>>`, so
  `InertiaResponse::merge_with` / `merge_lazy_with` can dedupe on several fields the same way
  `.prop(key, Prop::eager(v).match_on([...]))` already could - before this, the response-builder
  shortcuts were strictly less expressive than building a `Prop` directly. See Upgrading.
- **Scroll props now emit Laravel-identical `reset` and merge semantics.** `scrollProps[key].reset` is
  `true` exactly when the client named `key` in `X-Inertia-Reset`, matching Laravel's
  `resolveScrollProps` - not `true` on every visit lacking an `X-Inertia-Infinite-Scroll-Merge-Intent`
  header, as before. A scroll prop now also carries merge metadata unconditionally, defaulting to
  append: a fresh visit (no headers at all) emits `reset: false` plus a `mergeProps` entry, where it
  previously emitted `reset: true` and no merge metadata. A key in `X-Inertia-Reset` is excluded from
  `mergeProps` / `prependProps` for that response, the same exclusion a regular merge prop already had.
- **`ssr:check` now verifies the SSR worker's `GET /health` route answers 2xx**, rather than only
  confirming that something accepted a TCP connection. Every `@inertiajs/{vue3,react,svelte}/server`
  worker answers `/health` out of the box, so this needed no change on the worker side - matches
  Laravel's `Inertia\Ssr\HttpGateway::isHealthy()`.
- **The Inertia `errors` prop now carries one string per field, not an array.** A session-flashed
  validation bag renders as `{ email: "The email field is required." }` rather than
  `{ email: ["The email field is required."] }`, matching Laravel's default and Inertia's own
  `ErrorValue = string`. `InertiaConfig::with_all_errors(true)` restores the array shape. An
  `errors` prop a handler sets itself is passed through untouched, and the session flash
  (`Redirect::with_errors`, `session.pull_errors_flash()`) still stores arrays - only the rendered
  page prop changes.
- **`Model::TOUCHES` moved from an inherent const to `EloquentModel`.** The parent-touch cascade
  lives on a `Model` trait default, and a trait default can't read an inherent const.
  `Comment::TOUCHES` still resolves - it now needs `use suprnova::EloquentModel;` in scope. Models
  without a `touches` attribute get the trait's empty default.
- **`RelationEntry` gained `related_updated_at_column`.** Anything constructing a `RelationEntry` by
  hand needs the extra field; nothing in-tree does, the macro emits them all.
- **`Router::view` now rejects props that aren't a JSON object.** It previously ignored them
  silently, registering a route that rendered an empty prop bag with no diagnostic. `null` is still
  accepted as "no props"; `Router::try_inertia` is the fallible form.
- **The Inertia asset version now defaults to a hash of the Vite build manifest** instead of the
  literal `"1.0"`, so a deploy invalidates long-lived clients without anyone remembering to bump a
  string. `InertiaConfig::manifest_path(...)` re-points the resolver with it; an explicit
  `.version(...)` / `.version_with(...)` still wins. With no manifest on disk - local development -
  the version falls back to `"1.0"`, which is what every app saw before, so nothing changes until
  you build. New `VersionResolver::from_manifest(path)` exposes the resolver directly.

### Deprecated

- **`Cookie::read_encrypted` is now the v1-only legacy reader.** Code that mints with
  `Cookie::encrypted` and reads with `read_encrypted` fails at runtime on the first value written
  after this release; switch to `read_encrypted_for(name, wire)`. The un-contexted
  `CryptPurpose::Cookie` entry points are also superseded. Both removals are scheduled for 1.4.0.

### Upgrading
- **Cookie decrypt warnings now have two independent axes.** A `KeyOrigin::Previous(index)` warning means
  re-encrypt the value under the current `APP_KEY` and remove that previous key only after the rotation
  tail is gone; an `AadVersion::Legacy` warning means re-issue the cookie through the name-bound API
  before the 1.4.0 fallback removal. A value can report both.
- **`SESSION_COOKIE_PREFIX` is opt-in.** Deploy `__Host-` only with HTTPS, `SESSION_SECURE=true`,
  `SESSION_PATH=/`, and no `SESSION_DOMAIN`; local HTTP scaffolds leave it empty. `CsrfMiddleware`'s
  `with_session_config` keeps the literal `XSRF-TOKEN` name; use
  `.xsrf_cookie_name("__Host-XSRF-TOKEN")` when a client is configured for that separate name.
- **`DecryptOrigin` is now a two-axis `#[non_exhaustive]` struct.** Read its `key` and `aad` fields
  independently and keep a wildcard-compatible match strategy for the `KeyOrigin` /
  `AadVersion` enums.
- **`SessionConfig` and `CookieOptions` are now `#[non_exhaustive]`.** Struct literals and functional
  record updates in application code must move to `Type::default()` followed by public-field
  assignments or builder methods.

- **`FrameworkError` is now `#[non_exhaustive]`.** A `match` on it in your own code needs a wildcard
  arm. This is the last release in which adding a variant would have been a breaking change.
- **`MergeStrategy::Append`/`Prepend`/`Deep`'s `match_on` field is now `Option<Vec<String>>`, not
  `Option<String>`.** A call site constructing the struct-literal form directly - `MergeStrategy::Append
  { match_on: Some("id".into()) }` - no longer compiles; wrap the field name in a `Vec`:
  `Some(vec!["id".into()])`. `match_on: None` is unaffected and needs no change.
- **A matched partial reload no longer emits `deferredProps`.** Code reading `page.deferredProps`
  off a partial-reload response - a custom deferred-loading component, a test snapshot, an
  end-to-end assertion - will now find the key absent where it used to list the deferred props the
  request did not name. Read the announcements off the initial (non-partial) visit, which is where
  Laravel puts them and where the official client reads them.
- **A bare `except` entry now drops dotted prop keys beneath it.** `X-Inertia-Partial-Except: auth`
  previously left a prop registered under `auth.user` in the response, because the gate compared
  whole keys. It is dropped now. If a page relied on a bare `except` entry pruning only the exact
  key, name the exact key (`except: ['auth.user']`) or narrow with a dotted path instead.
- **`errors` ignores `only`/`except`.** A partial reload that filtered a handler-supplied
  `.with("errors", …)` prop out, or narrowed it with a dotted entry, now ships it whole. Tests
  asserting a sliced or empty `errors` object on a partial reload need updating. To keep the bag
  out of a response deliberately, flag it - `.prop("errors", Prop::eager(…).optional())` - rather
  than relying on the partial-reload lists.
- **`Prop::resolve_with_owner` gates flagged props too.** It previously resolved any prop that was
  not `Prop::is_lazy()` - an eager value *or* a resolver carrying a flag - without consulting the
  include set. It now gates every resolver-backed prop and only lets an already-materialized value
  through ungated. A `#[data(lazy(deferred))]` field consequently needs `?include=<field>` on the
  request before it resolves or is announced, the same as every other lazy flavor. Add the field to
  the request's `?include=` list, or drop the `lazy(...)` attribute if it was never meant to be
  opt-in.
- **Scroll prop `reset` no longer follows the merge-intent header.** Code that reads
  `page.scrollProps[key].reset` directly - a custom infinite-scroll component, a test snapshot - will
  see `reset: false` (plus a `mergeProps` entry) on a plain revisit that used to read `reset: true` and
  carry no merge metadata. The official `<InfiniteScroll>` component behaves differently only on a
  plain revisit: it listens for `reset` on every `router` `success` event, not only an explicit
  `router.reload()`, so a normal revisit no longer clears its accumulated state unless the server
  actually named the key in `X-Inertia-Reset`, which matches Laravel. Send `X-Inertia-Reset: <key>`
  explicitly wherever the old "any non-append/prepend visit resets" behavior was relied upon.
- **`Prop::match_on` takes `impl MatchOnFields`, not `impl Into<String>`.** The new bound is what
  lets one call name several fields (`match_on(["id", "slug"])`), and its impl list is deliberately
  closed - `&str`, `String`, `[T; N]`, and `Vec<T>` only. A blanket impl over `IntoIterator` is not
  available: coherence rejects it against the `&str` and `String` impls, since nothing stops those
  types from gaining an `IntoIterator` impl later. Three argument types that compiled before no
  longer do: `&String`,
  `Cow<'_, str>`, and `Box<str>`. Pass a `&str` at the call site instead - `match_on(name.as_str())`
  for a `&String`, `match_on(name.as_ref())` for a `Cow<'_, str>`, `match_on(&*name)` for a
  `Box<str>`.
- **A dotted `only`/`except` entry now narrows its top-level prop instead of excluding it
  entirely.** Before this fix, `X-Inertia-Partial-Data: user.name` made `should_include_eager`
  look for an exact-match `"user"` entry, found none, and silently dropped the whole `user` prop -
  a client asking for one field of `user` got nothing. Any frontend page component that happened to
  rely on that gap (treating a dotted `router.reload({ only: [...] })` as equivalent to omitting the
  key) now receives `{ user: { name: ... } }` instead. No code changes are required - this is what
  the Inertia v3 protocol already specifies the request/response contract to mean. The same fix
  applies to `should_include_optional`, and its effect is operationally bigger: a dotted `only` entry
  (`permissions.read`) now counts as an explicit request for an `Optional` or `Defer` prop's
  top-level key, which previously required a bare entry (`permissions`) to trigger at all. A request
  that used to skip that prop's resolver entirely now runs it - if the resolver hits a database or an
  external service, a client already sending dotted partial-reload requests starts issuing that work
  on requests that previously did none. Watch resolver call volume after upgrading if your app has
  `Optional`/`Defer` props with dotted partial-reload traffic.
- **`InertiaSharedData::share` now takes the page component name.** Add a `component: &str` parameter
  after `req`:
  ```diff
  -async fn share(&self, req: &dyn InertiaRequestExt) -> Result<IndexMap<String, Prop>, FrameworkError>
  +async fn share(&self, req: &dyn InertiaRequestExt, component: &str) -> Result<IndexMap<String, Prop>, FrameworkError>
  ```
  Ignore it (`_component`) if your provider doesn't need to vary by page - Laravel's `RenderContext`
  carries the same pairing (`component`, `request`) for `ProvidesInertiaProperties::toInertiaProperties`.
- **`Prop` is a struct, not an enum.** Its variants are gone; construct and read props through
  methods:
  - `Prop::Eager(v)` -> `Prop::eager(v)`
  - `Prop::EagerNone` -> `Prop::absent()`
  - `Prop::Always(v)` -> `Prop::eager(v).always()`
  - `Prop::Lazy(r)` -> `Prop::from_resolver(r)` (`Prop::lazy(closure)` is unchanged)
  - `Prop::Optional(r)` -> `Prop::from_resolver(r).optional()`
  - `match prop { Prop::Eager(v) => … }` -> `prop.as_value()`
  - `matches!(prop, Prop::Lazy(_))` -> `prop.is_lazy()`; `matches!(prop, Prop::EagerNone)` ->
    `prop.is_absent()`
  The `DeferConfig`, `MergeConfig`, `OnceConfig`, and `ScrollConfig` payload structs are removed -
  their fields are flags on `Prop` now. `Prop::is_deferred()` is renamed `Prop::has_resolver()`,
  which is what it always meant. `DeferOptions`, `OnceOptions`, `MergeStrategy`, `ScrollMetadata`,
  and every `InertiaResponse` builder method are unchanged, so an app that only uses the response
  builder needs no edits. Apps that build props by hand - typically an `InertiaSharedData`
  implementation - need the renames above.

- **This fix protects sessions you already have, not only requests from here on.** Upgrading alone
  is enough: a session cookie written by an earlier release can carry a `_previous.url` that was
  never sanitized, and `SessionData::previous_url()` now discards it on read the first time that
  session is used post-upgrade, rather than trusting it because it's already stored. You don't need
  to invalidate existing sessions, migrate the session table, or force a re-login. A request whose
  path looks protocol-relative (`//host`) also no longer updates the recorded previous URL going
  forward - if your app's `fallback!` route (or any 200-answering route reachable on an unusual
  path) ever legitimately relied on such a path becoming the `Redirect::back()` target, it won't
  anymore. Either way, the previous, safe value in the session is left in place instead (or
  `Redirect::back(fallback)`'s own fallback wins, if nothing safe was ever recorded). No code change
  is needed unless you were depending on the exact edge case this closes, which was already an
  open-redirect risk.
- **Drop the `[0]` from every `errors.<field>` binding in your pages.** With the new default shape
  `errors.email` is a string, so `errors.email[0]` renders its first character instead of the
  message. Change the TypeScript type from `string[]` to `string` at the same time. If you would
  rather not touch your pages, set `InertiaConfig::with_all_errors(true)` on the config you pass to
  `Inertia::install` and add the `errorValueType: string[]` module augmentation for
  `@inertiajs/core`. The starter frontends ship the new shape.
- **A handler that hand-rolled the redirect-back after a validation failure can delete it.** The
  bridge is automatic now; a handler that still redirects itself keeps working, because the
  middleware only acts on a `422` that carries a populated `errors` object.
- **A crashed `suprnova serve` child now respawns instead of ending the session.** If you relied on
  a crash stopping `suprnova serve` outright (a CI smoke check, a script that treats exit as
  "something's wrong"), pass `--no-restart` to restore that behaviour exactly. Retries are also
  bounded by default: a process that crashes 5 times in a row stops being retried (raise the limit
  with `--restart-tries`, or use `--no-restart` for the original one-crash-and-done behaviour).
- **`Model::TOUCHES` is no longer an inherent const.** Code that read `Comment::TOUCHES` directly
  needs `use suprnova::EloquentModel;` (or `suprnova::eloquent::EloquentModel`) in scope - the const
  moved there so the parent-touch cascade, a `Model` trait default, can read it. A `grep -rn TOUCHES`
  over your app finds every call site; most apps have none, since the const previously did nothing
  at runtime.
- **`RelationEntry` gained a field.** Only code that constructs a `RelationEntry` by hand needs a
  change - add `related_updated_at_column` to the literal. The macro-generated relation registrations
  the framework ships already emit it, so an ordinary app doing nothing but declaring relations
  through `#[suprnova::model]` is unaffected.
- **`Router::view` with non-object props now panics at boot.** It previously registered silently
  with an empty prop bag; `view` delegates to `Router::inertia`, which requires an object (or
  `null`) and panics otherwise. If a `view` call might carry non-object props, switch to
  `Router::try_inertia` and handle the `Err` - otherwise nothing changes for you.
- **The Inertia version manifest default can change your version string the moment a build
  exists.** An app or test that hardcodes `X-Inertia-Version: 1.0` keeps working only until a Vite
  manifest shows up on disk; once one does, the version becomes the manifest hash instead. If you
  need the old constant, read it from `VersionResolver::from_manifest(path)` yourself or pin
  `.version(...)` explicitly. Expect the first deploy after upgrading to force one full-page reload
  cycle for already-connected clients - one-time, and the point of the change. The no-manifest
  fallback value is exported as `suprnova::MANIFEST_VERSION_FALLBACK`, so you never need to
  hardcode `"1.0"` again.
- **Move `Inertia::install` and `global_middleware!` registration out of `bootstrap::register`.**
  Put them in a new function and pass it to `.http_bootstrap(...)` instead - the scaffold's new
  shape is a sync `register_http_stack()` called as
  `.http_bootstrap(|| async { bootstrap::register_http_stack() })`. Apps that skip this keep today's
  behavior, worker-boot failure on a missing frontend manifest included.

## 1.2.4 - 2026-08-18

### Security

- **The maintenance-mode bypass secret is compared in constant time.**
  `MaintenanceMiddleware` matched the secret URL with a plain string
  compare, which returns at the first differing byte. Because the secret is
  a bearer credential carried in the request path, that timing difference
  told an attacker how long a prefix they had guessed correctly. The
  compare now runs over the full byte length via `subtle::ConstantTimeEq`,
  short-circuiting only on a length mismatch - the same shape as the
  bypass-cookie compare next to it.

- **`rules::Url` now rejects script URIs.** The rule accepted any scheme
  `url::Url` could parse, `javascript:` and `vbscript:` included, so a
  validated URL could still be a script-execution sink when rendered into
  an `href`. It now applies Laravel's `url` rule shape
  (`Illuminate\Support\Str::isUrl`'s `^(PROTOCOLS)://HOST` pattern): the
  scheme must be on Laravel's allowlist, be followed by `://`, **and** be
  followed by a non-empty host - Laravel's host group has no `?`, so an
  absent or empty host never matches even with a listed scheme. The scheme
  list and the `://`-plus-host requirement are Laravel's verbatim; the host
  itself is parsed by the `url` crate rather than Laravel's regex, so a few
  edge cases still differ - an out-of-range port is rejected here and
  accepted there, and IDN hosts normalise differently. New
  `Url::protocols(&[...])` mirrors Laravel's `url:http,https`; `HttpUrl`
  is now literal sugar for it and keeps its own message. **Behaviour
  change:** a URL with an unlisted scheme that used to validate now
  fails - name the scheme with `Url::protocols(&["myapp"])` if you meant
  to accept it. Two more behaviour changes: `mailto:`, `data:`, and
  `tel:` are on Laravel's allowlist by name but don't carry an authority
  component, so they now fail; and `file:///etc/passwd`-style paths -
  `scheme://` with nothing between the last two slashes - now fail too,
  since an empty string isn't a host either. Both follow from Laravel's
  own `://`-plus-host rule.

- **Inertia responses now advertise `Vary: X-Inertia` everywhere.** The
  header was set only on the page-object responses themselves. Redirects,
  404s, 422s, and static responses carried none, so a shared cache keyed on
  the URL alone could serve the JSON page object to a hard browser
  navigation, or the HTML shell to an Inertia XHR. The new
  `InertiaHeadersMiddleware` - registered by `Inertia::install` as the
  outermost of the three - sets it on every response, and turns an empty
  `200` on an Inertia visit into a `303` back rather than a response the
  client rejects as non-Inertia. `InertiaVersionMiddleware` now re-flashes
  the session before its `409`, so a flashed error survives the client's
  follow-up full-page GET.

- **Three Inertia response fixes.** `InertiaResponse::location_for(&req, url)`
  returns `409` + `X-Inertia-Location` for an Inertia XHR and a plain `302` + `Location` for a hard navigation, so an OAuth or SSO bounce entered
  outside the SPA no longer dead-ends on a body-less `409`. The existing
  `location(url)` keeps its always-`409` shape. New `App::clear_history()`
  flashes the history-clear flag into the session so it survives the logout
  redirect and lands on the page that actually renders - the per-response
  `.clear_history()` marked only the redirect the browser throws away,
  leaving the previous session's encrypted history decryptable. And a
  `once` prop is now skipped only on a full Inertia visit: an explicit
  `router.reload({ only: ['stats'] })` re-resolves it instead of returning
  nothing.

- **The SES transport now sends custom message headers.**
  `Mail::to(..).header("List-Unsubscribe", ...)` and `Mailable::headers()` were
  dropped silently under `MAIL_DRIVER=ses`: the `Content.Simple` request body
  had no `Headers` field and the raw-MIME builder never read
  `OutgoingMessage::headers`, even though every other transport forwards them.
  Both SES paths now carry them - `Headers` as SES v2's `{Name, Value}` list,
  raw MIME as real header lines - so unsubscribe links, threading headers and
  routing hints survive a driver swap. Header names are validated up front on
  both paths - CR, LF and NUL (the injection bytes, as the Mailgun transport
  already refuses) and anything that is not a valid RFC 5322 field name
  (spaces, colons, non-ASCII) - so attaching a file never changes whether a
  message is accepted.

### Fixed

- **Nested validation failures now reach the 422 body.** `#[validate(nested)]`
  failures on a nested struct or on an element of a validated `Vec<T>` were
  dropped between the validator and the response: the request was correctly
  rejected with 422, but the `errors` map came back empty, so no message
  rendered and the client could not tell which field was at fault. Nested
  failures are now flattened into Laravel's dotted notation -
  `address.street`, `items.1.name`, `order.items.2.sku` - alongside the
  top-level ones.

- **The Inertia page object's `url` keeps the query string.** `page.url` was
  the request path only, so the client recorded `/users` for a visit to
  `/users?page=2&sort=name`. Every back/forward navigation and every
  `router.reload()` then replayed the page without its pagination cursor,
  sort, or filters. It is now path plus query - the same derivation
  `InertiaVersionMiddleware` already used for `X-Inertia-Location`, so by
  default the two agree byte for byte. New
  `InertiaConfig::url_resolver(...)` overrides how the *page object* names
  the page (Laravel's `Inertia::resolveUrlUsing`); the version bounce keeps
  naming the URL that arrived, because that is the URL the browser has to
  fetch.

- **`Inertia::install` now applies its config to every response.** The
  config handed to `Inertia::install` was read for three fields and then
  dropped, so every `InertiaResponse` built without an explicit
  `.with_config(...)` rendered from `InertiaConfig::default()`. An app
  scaffolded with `--frontend react` served the Svelte entry point and no
  React refresh preamble unless `SUPRNOVA_FRONTEND` was set in the
  environment; SSR enabled on the config never reached a response; and the
  page object's asset version came from a different config than the
  version middleware's resolver. The installed config is now retained on
  the container's Inertia registry and is what `InertiaResponse::new`
  starts from. Per-response `.with_config(...)` still overrides, apps that
  never call `Inertia::install` are unchanged, and a failed (fail-closed)
  install retains nothing. As a side effect the production Vite manifest
  is now parsed once per process rather than once per response.

- **Scaffolded apps now install the Inertia protocol middlewares.** The
  `bootstrap.rs` written by `suprnova new` registered the session, locale,
  CSRF and include middlewares but never called `Inertia::install`, so a
  generated app had neither `InertiaVersionMiddleware` nor
  `Inertia303Middleware`: a browser still running the previous bundle was
  never told to reload after a deploy, and a `PUT`/`PATCH`/`DELETE` that
  redirected stayed on a `302` the client could follow with the original
  verb. The call now lands after `SessionMiddleware` - where the version
  middleware's session re-flash works - with a named `INERTIA_VERSION`
  constant to bump when assets change, and it pins the frontend the
  project was generated with (`.frontend(Frontend::React)` for
  `--frontend react`), so the HTML shell loads that framework's Vite entry
  point instead of falling back to Svelte's. The generated `.env` now sets
  `SUPRNOVA_FRONTEND` to match. The `--api` starter is unchanged; it has
  no frontend.

- **`Queue::push_unique` no longer reports a queued job as skipped.** The
  return value was computed with `matches!(outcome, Idempotent::Fresh(()))`,
  which folded `Idempotent::FreshUnfenced` into `false` - the outcome where
  the envelope *was* pushed but the dedupe lease was lost mid-push. Callers
  branching on that boolean were told a job that was about to run had been
  suppressed as a duplicate. All three outcomes are now matched exhaustively:
  a lost lease returns `true` with a `warn` naming the job and its unique
  key, and only a real duplicate returns `false`. `push_unique_later` and
  `later_unique` share the path and are fixed with it.

### Changed

- **Parity baseline moved to Laravel 13.25.0.** The 13.23.0, 13.24.0 and
  13.25.0 release notes were traced item by item to the framework's own
  surface. Everything that reached a Suprnova code path is either fixed in
  this release or has a row in [`manual/parity.md`](parity.md) marked
  `not yet` or `by design no`.

### Upgrading

Two changes can alter a running app without any code change on your side.

- **Settings on the config you pass to `Inertia::install` now take effect.**
  They were read for three fields and dropped. If your install config sets
  `.ssr(...)`, SSR is now on: start the worker (`suprnova ssr:start`) before
  deploying, or drop the `.ssr(...)` call. `.entry_point`,
  `.assets_base_url`, `.default_title` and `.encrypt_history(...)` set there
  also reach the page now.

- **`rules::Url` rejects more.** Values that used to pass and no longer do:
  any scheme outside Laravel's allowlist, `javascript:` and `vbscript:`
  among them; `mailto:`, `data:` and `tel:`, which are on the allowlist but
  carry no `://` host; and `scheme://` with an empty host, such as
  `file:///path`. If you meant to accept a scheme, name it:
  `Url::protocols(&["myapp"])`.

## 1.2.3 - 2026-08-16

### Fixed

- **Datetime casts now read database-native `CURRENT_TIMESTAMP` text.**
  `AsDateTime`, `AsImmutableDateTime`, and `AsOptionalDateTime` continue to
  write canonical RFC-3339, while reads also accept PostgreSQL's
  timezone-bearing text and timezone-free SQLite/MySQL text. Timezone-free
  values are interpreted as UTC, matching the framework's UTC timestamp
  contract.

## 1.2.2 - 2026-08-14

### Fixed

- **Nullable non-text values now work across attribute-based writes on
  PostgreSQL.** Typed `Builder::update_all` and `Builder::upsert`, model-less
  `DB::table().insert/update`, and many-to-many pivot extras render explicit
  JSON nulls as SQL `NULL` while continuing to bind every non-null value. This
  preserves the target column's type instead of sending a text-typed null
  parameter that PostgreSQL rejects for bigint, integer, boolean, timestamp,
  and other non-text columns. Multi-row upserts now also reject missing or
  extra columns instead of silently converting a malformed row shape to null.
  Automatic many-to-many pivot timestamps are bound as typed UTC datetimes
  instead of text.

### Security

- **The release gate now distinguishes dormant lockfile metadata from compiled
  dependencies across the whole workspace.** Cargo records rust_decimal's
  unused optional rkyv 0.7 compatibility dependency in `Cargo.lock`; the gate
  now proves that neither rkyv nor its derive crate is reachable from any
  workspace member, feature, target, or dependency edge. The corresponding
  RustSec exception is owned, expires on 2026-11-14, and must be removed when
  rust_decimal no longer records that legacy optional dependency.

## 1.2.1 - 2026-08-09

### Changed

- **Suprnova moved to the `eas4ai` GitHub organization.** Repository URLs in
  package metadata, documentation, dependency examples, and scaffold templates
  now use `github.com/eas4ai`. New projects also use the monitored
  `shawn@eas4ai.com` author email. This release made no runtime behavior
  changes.

## 1.2.0 - 2026-08-05

### Added

- **The manual ships in seven languages.** `manual/es/`, `manual/fr/`,
  `manual/de/`, `manual/pt-BR/`, `manual/ja/` and `manual/zh-Hans/` each
  carry the full 104-chapter manual - every chapter, the table of
  contents, and this changelog - translated from the English source.
  English remains canonical: chapter structure, code blocks, identifiers,
  CLI commands and environment variables are held byte-identical to the
  source, so a translated chapter can never disagree with the English
  about what the framework does, only say it in the reader's language.

  The translations were produced and reviewed for suprnova.app, which
  renders this manual as its `/docs`. Every section carries a review
  ledger there: verdicts are recorded against content hashes of both the
  English and the translation, two independent reviewers must pass the
  exact bytes for a section to count as approved, and per-locale
  glossaries pin the terminology rulings (which terms stay English,
  which take the native word, and why). Corrections are welcome in
  either repo - a fix here reaches the site on its next sync.

## 1.1.0 - 2026-08-02

### Added

- **Per-locale fallback chains.** `LocalizationConfig` gains `parents`
  (`APP_LOCALE_PARENTS`, comma-separated `child=parent` pairs, or the
  chainable `.parent(child, parent)` builder): a locale can inherit from a
  configured sibling before falling further back to the global
  `fallback_locale` - `pt-PT` from `pt-BR`, `en-AU` from `en-GB`, and so
  on, transitively. `Lang::get`/`try_get`/`get_with`/`try_get_with`/`has`
  all walk the chain, current locale first, so this works for any
  `Translator` driver, not just the bundled one. A malformed pair, an
  invalid locale, a child named twice, or a cycle (including a locale
  naming itself as its own parent) fails loudly at config load rather
  than degrading at request time.

  Served catalogs stay chain-flattened ahead of time: `FluentTranslator`
  now builds each locale's `/_suprnova/lang/<locale>.ftl` catalog as a
  fold - the embedded framework catalog at the bottom for `en`/`en-*`
  locales, then the locale's configured parent chain, then its own
  `*.ftl` files - so a chained locale is still one self-contained file
  the browser fetches once, with no client-side chain awareness needed.
  Flattening covers configured parents only; the terminal
  `fallback_locale` is still a `Lang`-facade-level fallback, not baked
  into the served bytes.

  This makes delta-style catalogs practical: a `lang/pt-PT/` directory
  can hold only the handful of strings that actually differ from
  `lang/pt-BR/`, rather than a full duplicate catalog. The merge that
  makes it possible works at the Fluent AST level - a child's value
  replaces the parent's, attributes merge by name (an override that
  doesn't mention an attribute no longer loses it), select expressions
  replace whole (CLDR plural categories are locale-dependent, so
  variant-by-variant merging isn't coherent), and child-only entries
  append. See `manual/localization.md`'s new "Fallback chains" section
  for the full contract.

### Changed

- **`LocalizationConfig` gained the `parents` field.** `from_env()` and
  the builder are unaffected; a literal struct constructor (tests
  building a `LocalizationConfig` by hand) needs one more field.
- **Served catalog text is now serializer-normalized for every locale**,
  and intra-locale multi-file merging (several `.ftl` files in one
  locale directory) now goes through the same AST-level merge as parent
  chains rather than simple bundle-overriding. Resolved translations are
  unchanged except for the two strict improvements below; the
  underlying bytes rotate regardless - `ETag`/`?v=<hash>` rotates once
  on upgrade. The improvements: an override no longer silently drops
  the attributes it doesn't mention, and an attributes-only override no
  longer strips the message's own value (previously an error or a
  fallback resolution; it now resolves to the earlier override's
  value).

## 1.0.0 - 2026-08-02

### Added

- **Localization.** Message catalogs in `lang/<locale>/*.ftl`
  ([Fluent](https://projectfluent.org)), a `Lang` facade with the
  `__!("key", name: value)` macro, per-request locale detection
  (`LocaleMiddleware`: session → cookie → `Accept-Language` →
  `APP_LOCALE`), and locale-aware formatting for numbers, currency,
  dates, times, lists, and relative times over ICU4X. `manual/localization.md`
  is the chapter.

  The built-in validation rules stop hardcoding English. Each returns a
  keyed message (`validation-min` plus its arguments and an English
  fallback), translated once at the serialization boundary - so a Spanish
  app gets Spanish validation errors by dropping in
  `lang/es/validation.ftl`, with no rule wrapping and no forked copy of
  the framework's messages. Field names humanize through a `field-<name>`
  lookup. `Rule::passes` (and `ContextualRule` / `AsyncRule`) now return
  `Result<(), ValidationMessage>`; a custom rule's `Err("…".into())` body
  still compiles and still renders verbatim, but the signature in your
  `impl` needs the new type.

  The browser gets the same bytes the server resolved: the merged catalog
  is served at `/_suprnova/lang/<locale>.ftl` with an ETag and an
  immutable `?v=<hash>` form, the three starter kits parse it with
  `@fluent/bundle`, and `suprnova generate-types` emits a `MessageKey`
  union so renaming a message points the TypeScript compiler at every
  call site.

  Fluent rather than Laravel-style PHP arrays because one format has to
  serve both the server and the browser, and because CLDR plural
  categories are what gets Russian, Polish, and Arabic right -
  `trans_choice`'s integer ranges cannot, which is why there is no
  `trans_choice` here. Behind a default-on `localization` feature;
  `--no-default-features` still compiles and still validates, using the
  embedded English fallbacks.

- **`IntoInertiaScroll` for `Paginator`.** The trait was implemented for
  `LengthAwarePaginator` and `CursorPaginator` but not for the simple
  paginator, so `simple_paginate` results could not feed
  `Inertia::paginate` at all - despite `simple.rs`'s own module docs
  pointing at it as the URL-generation path. That left offset-paginated
  Inertia collections with a choice between a `COUNT(*)` per request and
  hand-rolling the scroll metadata. `next_page` comes from the
  `LIMIT n+1` overflow probe rather than a computed last page, there
  being no total to compute one from.

### Fixed

- **`suprnova generate-types` emitted a different file on every run.**
  The topological sort seeded its work queue by iterating a `HashMap`,
  and Rust randomises hash iteration order per process, so consecutive
  runs ordered the same interfaces differently. The output is a
  checked-in artifact, so every run produced a diff - and a generated
  file that churns for no reason is one people stop regenerating, after
  which it quietly stops describing the Rust it claims to. The directory
  walk is sorted too, so the output no longer depends on filesystem
  order either. Two runs of the same source are now byte-identical.

- **`topological_sort` did the opposite of its doc comment**, emitting
  dependents before dependencies. Harmless - a TypeScript interface may
  reference one declared later in the same file - so the comment is
  corrected rather than the order, which would have reshuffled a tracked
  file for no benefit.

## 0.9.1 - 2026-08-01

Three defects, all found by running the dogfood app under a containerised
harness rather than by reading the code. Every one of them is invisible to
a test suite that never stops a process the way production stops it.

They compound in a specific order: a rolling deploy SIGKILLs a worker
mid-job (the first), and that job then takes a reclaim path that never
counted the attempt (the second).

### Fixed

- **`schedule:work`, `queue:work` and `workflow:work` ignored SIGTERM.**
  Each selected on `tokio::signal::ctrl_c()` alone, which installs a
  SIGINT handler - so SIGTERM had no handler anywhere in the process, and
  SIGTERM is what `docker stop`, Coolify, systemd and Kubernetes send. All
  three already had a careful bounded drain behind that `select!`; none of
  it had ever executed under a supervisor. Measured before the fix: a
  `docker stop` on a `queue:work` container burned its whole 40s grace
  window and exited 137 with the in-flight job destroyed. As PID 1 - which
  is what a container runs - the kernel discards an unhandled SIGTERM
  outright, so the process did not die badly; it did not die at all until
  SIGKILL. `Server::run` already handled both signals correctly and its
  listener is now shared, which also closes a missed-signal window in the
  scheduler's loop.

- **A job that killed its worker could never be dead-lettered.** A job
  whose *handler* fails is nacked and its attempt counted, so it
  dead-letters after `max_tries`. A job that *kills its worker* - OOM,
  abort, segfault, or the SIGKILL above - settles nothing; its reservation
  merely lapses, and every driver used to redeliver it byte-identical.
  Such a job is immortal: it kills each worker that claims it, comes back
  unchanged, and kills the next one, for as long as anything restarts
  workers. All three drivers now charge the attempt where they learn a
  worker died, because swapping `QUEUE_DRIVER` must not change whether a
  poison job can be stopped. `attempts` now means "deliveries to a worker"
  rather than "handler failures" - documented in `manual/queues.md`,
  because a worker lost for unrelated reasons burns an attempt too.

- **…and the exhausted job is now dead-lettered before it is dispatched.**
  Counting the attempt was necessary and not sufficient. Every
  dead-letter decision lived in the worker's settlement path, which
  assumes the handler returns - so it never ran for exactly the jobs that
  could not return. With the driver fix alone the counter climbed
  (measured: 0 → 1 → 2 across three killed workers) and nothing acted on
  it. The budget is now spent before the handler runs. Caught only by
  re-running the container experiment after the first fix looked correct.

- **The daemons had no tracing subscriber.** `serve` gets one from
  `init_telemetry`; `queue:work`, `schedule:work`, `schedule:run` and
  `workflow:work` come through a different boot path and got nothing, so
  every `tracing::` line they emit went nowhere and `LOG_LEVEL` was inert
  for them. That is most of what they have to say - a worker
  dead-lettering a job, a scheduler skipping a tick it lost, a lock it
  could not release. In a container the only visible output was the
  startup banner, and the process looked idle while doing all of it. Two
  of the defects in this release were invisible until this was fixed.

- **A dead-letter with no failed-jobs store bound was a silent deletion.**
  The persist step sat inside `if let Some(store) = ..`, so with no store
  the arm did not match and execution fell through to the ack - quieter
  than the failure path directly above it, which at least leaves the
  reservation intact. An absent store was treated as more successful than
  a broken one. It now logs the full envelope at ERROR, because that is
  what `queue:retry` re-pushes: the difference between work recoverable by
  hand and work that ceased to exist.

- **`QUEUE_DRIVER=database` now binds a failed-jobs store.** `failed_jobs`
  is part of that driver's contract - `queue:retry` reads it and
  `Queue::retry_failed` cannot work without it - but `bootstrap_from_env`
  wired the driver and left the store unset, so a database-backed queue
  dead-lettered into nothing unless the app bound one by hand. Configurable
  via `QUEUE_FAILED_DB_TABLE`. Only for this driver: `memory` is ephemeral
  by construction and `redis` has no table to write to.

- **Redis reclaim latency now follows `--visibility-timeout`.** The flag
  sets XAUTOCLAIM's idle threshold, but a separate clock governs how often
  a consumer looks, and the driver left it at sea-streamer's 30s default -
  so `--visibility-timeout 5` really meant "up to 35 seconds". The
  interval now tracks the configured timeout, clamped to 1s..=30s so a
  short timeout cannot become an XAUTOCLAIM storm and a long one can only
  make reclaim faster than before.

### Added

- **`TaskBuilder::on_one_server()` / `on_one_server_for(ttl)`** - run a
  scheduled task exactly once per due tick across replicas. Without it
  nothing elects a leader for a tick: each `schedule:work` process
  evaluates the schedule independently, and three replicas were measured
  running every due task three times, every minute, with no variance. A
  nightly billing job on three replicas billed every customer three times.

  `without_overlapping()` does not cover this and cannot: its lock is
  keyed on the task and released when the handler returns, so a fast task
  frees it before a second replica looks. `on_one_server` keys on the task
  *and the tick* and holds the lock past the handler, letting it expire on
  TTL. The two compose.

  Opt-in, matching Laravel. Diverges from Laravel in failing closed: the
  election is only as shared as the cache behind it, so a production boot
  with `CACHE_DRIVER=memory` and a single-server task is refused, naming
  the offending tasks, with `SCHEDULE_ALLOW_MEMORY_LOCK_IN_PRODUCTION=true`
  for deployments that genuinely run one scheduler.

### Changed

- `manual/deployment.md` no longer says "run exactly one `schedule:work`
  process" as the only option, and gains a **Stopping cleanly** section
  covering the drain windows per subsystem, how to size a platform's
  termination grace above them, and why PID 1 makes a missing signal
  handler worse than it sounds.

## 0.9.0 - 2026-07-31

### Security

- **Auth issuance could only be throttled per caller, never per
  recipient.** An address-keyed limit answers "is one client noisy"; it
  cannot answer "is one mailbox being flooded". An attacker spread across
  a botnet or a single IPv6 `/64` stayed under every per-IP budget while
  filling one victim's inbox with password-reset mail, and nothing in the
  framework could express the limit that would have stopped it - a key
  function could read the path, headers, and query string, but not a
  form-encoded body, so the address was invisible on exactly the route
  that carries it.

  `identity_key` keys a bucket on the account being acted on. It reads the
  query string first and then a buffered form body, so one key function
  covers both shapes; the value is trimmed and lowercased, because
  `Alice@Example.com` reaches the same mailbox as `alice@example.com` and
  a limit bypassed by holding down shift is not a limit; and it is hashed,
  because a rate-limit backend is frequently a shared Redis with weaker
  access control than the primary database.

  Two new middleware builders support it. `key_reads_body(cap)` buffers
  the body before keying - opt-in, because buffering is work an
  unauthenticated caller gets to make you do, and a body over the cap is
  refused with 413 rather than passed through unkeyed. `only_when(pred)`
  skips a limiter entirely for requests it has nothing to say about,
  which is what keeps a stacked per-recipient budget from silently
  becoming the binding limit on routes that name no recipient.

  The dogfood app now stacks both on its issuance group: 10 per 5 minutes
  per address, 3 per 15 minutes per recipient.

A review of Torii's session, password, OAuth, and passkey paths turned up
eight defects, all fixed in the pinned fork (`suprnova-torii-rs` `968b0be`).

- **Expired sessions could be refreshed back to life.** The SeaORM session
  repository's `refresh` had no expiry predicate and unconditionally extended
  `expires_at`, and `OpaqueSessionProvider::refresh_session` skipped the
  `is_expired()` check that `get_session` performs. A token held past its
  expiry could be renewed indefinitely. Fixed at both layers. Not reachable
  through Suprnova's own surface - neither `Torii` nor the framework exposes
  session refresh - but it is public API of both crates.
- **The login form leaked which accounts exist, by timing.** Authentication
  returned as soon as the email missed, skipping Argon2 entirely: measured at
  54µs for an unknown address against 719ms for a wrong password, a ~13,000x
  gap readable over a network. Both failure paths now verify against a dummy
  hash so they cost the same. This one *was* reachable through Suprnova's
  password login.
- **The JWT `iss` claim was written but never verified.** Algorithm pinning
  was already correct - `alg: none` and HS/RS confusion were never possible -
  but the issuer was decoration, so two services sharing a signing key would
  accept each other's sessions. Now enforced when an issuer is configured.
- **A single-use PKCE verifier could be claimed twice.** Consumption was a
  read followed by a delete, so two OAuth callbacks for the same `csrf_state`
  could both read it before either delete landed. Now claimed in one
  operation - `DELETE ... RETURNING` on Postgres, a primary-key delete whose
  affected-row count picks the winner on SeaORM.
- **Expired sessions were listed as active.** `find_by_user_id` had no expiry
  filter, and expired rows survive until cleanup runs, so a "devices you're
  signed in on" screen offered users dead sessions to revoke while saying
  nothing about the live one.
- **A passkey lookup was named `authenticate`.** Torii's
  `PasskeyService::authenticate_credential` took a credential ID and returned
  the owning user, and `PasskeyAuth::authenticate` minted a session from it.
  Torii stores passkeys - it carries no WebAuthn dependency and cannot verify
  an assertion, so the only thing those calls proved was that the caller knew
  a credential ID: a value the browser sends in the clear and
  `allowCredentials` hands to anyone who can start a ceremony. Renamed to
  `find_user_by_credential` and `create_session_for_verified_credential`, both
  documenting that verification is the caller's job. Not reachable through
  Suprnova, which drives `webauthn-rs` itself (see
  `torii_integration::passkey`) and reaches Torii only for credential storage.
- **A WebAuthn challenge was replayable for its whole TTL.** Neither backend
  consumed a challenge on read, and the SeaORM `get_challenge` also ignored
  `expires_at` entirely, returning expired challenges as live. Reads now
  exclude expired rows on both backends, and a new `take_challenge` claims one
  exactly once - the same delete-decides-the-winner shape as the PKCE fix.

### Breaking

- **Azure Blob Storage and Google Cloud Storage moved behind the new
  `filesystem-azure` and `filesystem-gcs` features.** `Storage::register_azblob`,
  `register_azblob_with`, `register_gcs`, `register_gcs_with`, `AzBlobConfig`
  and `GcsConfig` no longer exist unless you enable the matching feature. If
  you use either backend, add it to your dependency:

  ```toml
  suprnova = { git = "…", tag = "v…", features = ["filesystem-gcs"] }
  ```

  You get a compile error naming the missing item, not a runtime failure.

  Both opendal service crates pull `rsa`, which carries RUSTSEC-2023-0071
  (the Marvin timing attack) with no fixed release upstream. They were the
  only crates enabling `reqsign-core/jwt`, the feature `reqsign-core`'s
  optional `rsa` sits behind, so gating them severs all three opendal paths
  to it at once. `rsa` is now *avoidable*: `--no-default-features --features
  filesystem,database-postgres` resolves without it and still has the
  storage subsystem. Previously no feature combination could shed it while
  keeping storage at all.

  A stock default build still carries `rsa` - `database-mysql` is a default
  feature and `sqlx-mysql 0.8.6` depends on it non-optionally - so the audit
  exception stays open. S3 is deliberately **not** gated: `reqsign-aws-v4`
  takes `reqsign-core` without `jwt`, so the S3 driver never contributed a
  path, and gating it would break the most-used cloud backend while removing
  nothing.

### Added

- **`suprnova --version`**, with `-v` as well as clap's default `-V`. Asking a
  CLI its version with the flag every other CLI uses should not print a usage
  error.

### Fixed

- **Two Redis operations had no upper bound.** The cache's tag flush read a
  tag's whole member set with `SMEMBERS` and deleted key by key, so a tag with
  a large membership stalled the connection and a concurrent write could be
  lost between the read and the delete; tags are now generation-based, flushed
  atomically, and scanned with a bounded `SSCAN`. The delayed-queue promotion
  pass moved every due job in one unbounded `ZRANGEBYSCORE`, so a backlog that
  came due together produced a single enormous script; it now promotes in
  batches.
- **Two shutdown drains waited forever.** `schedule:work` on Ctrl-C and the
  workflow worker after cancellation both awaited every in-flight task with no
  deadline, so one task that never returned held the process open until
  `SIGKILL` - an operator sees a daemon that "doesn't stop". Both now wait a
  bounded grace, then abort what remains and report the count.
- **The release version-pin sweep only recognised one of the two pin
  syntaxes**, so every file carrying a `cargo install --tag vX.Y.Z` line and
  no dependency snippet was never discovered. `suprnova-cli/README.md` had
  been telling readers to install v0.6.0 for three releases; `manual/cli.md`
  and `manual/cli-new.md` sat at v0.7.2; `manual/installation.md` carried
  both forms and had one bumped while the other froze. Discovery and rewrite
  now read from one pattern table, and a file's rules are derived from its
  content.
- **`cargo doc` failed for any build with `filesystem` but without
  `testing`** - seven `Storage::fake` intra-doc links could not resolve, and
  `lib.rs` denies broken links. `testing` is a default feature, so no gate
  step had ever built that combination; `check-feature-matrix.sh` now does.
- **Torii's migrations could not be replayed over their own schema**, so a
  database holding it without the `torii_migrations` tracking table - restored
  from a dump that skipped it, or migrated by hand - could not be brought under
  management. Every `Table::create()` carried `.if_not_exists()`; none of the 19
  `Index::create()` calls did, nor did the `ADD COLUMN locked_at` alter, so
  replay sailed through the tables and died on the first `CREATE INDEX`. Fixed
  in the pinned fork (`suprnova-torii-rs` `a0f956d`) via `has_index` /
  `has_column` rather than `IF NOT EXISTS`, which sea-query silently drops for
  MySQL - the syntactic fix would have left a default-featured build broken.
- **A failed Torii migration aborted the process instead of returning an
  error.** `SeaORMStorage::migrate` unwrapped the migrator and returned
  `Ok(())` unconditionally, so `init_torii`'s mapping of the failure into a
  `FrameworkError` was unreachable code.
- **An app's own `users` table silently suppressed Torii's**, because
  `.if_not_exists()` cannot tell "already mine" from "already somebody
  else's". The migration reported success and authentication failed later on
  a missing column - the reason the `--api` starter names its table
  `app_users`. Torii's migration now warns at migrate time when an existing
  `users` table lacks columns it requires, naming the columns and the remedy.
  It stays a warning rather than a hard failure so existing deployments keep
  booting.
- **The Railway and DigitalOcean deployment guides pointed the platform
  health check at a path that could probe Postgres.** Both platforms restart
  the container when that check fails, so following the advice turned a
  database blip into a restart loop across every replica. Both now use
  `/_suprnova/health/live`, with the database probed by hand from the
  console. The legacy paths still resolve; nothing already deployed needs
  changing.

## 0.8.0 - 2026-07-30

Remediation of an external red-team audit. The audit returned 19 P1
findings and a NO-GO verdict for 1.0; this release closes **all nineteen**,
plus a number of defects found while fixing them that the audit had not
named.

Several fixes deliberately turn a silent misconfiguration into a refused
boot. Read **Upgrading** before deploying - a production app that has been
running happily may not start.

### Upgrading

Three configurations that used to boot with a warning (or in silence) now
fail closed in production. Each error names the variable that unblocks it,
and each has an explicit override for the deployment where the risk is
genuinely absent.

- **A non-delivering mail driver.** `MAIL_DRIVER` unset, `log`, `memory`,
  or an unrecognised value all resolved to a transport that renders mail
  and discards it - so password resets reported success while nothing was
  sent. Override: `MAIL_ALLOW_NON_DELIVERING_IN_PRODUCTION=true`.
- **Cleartext SMTP.** Three of the four credential combinations landed on
  an unencrypted transport, and the both-unset case logged a warning and
  sent anyway. Override: `MAIL_ALLOW_INSECURE_SMTP_IN_PRODUCTION=true`.
- **The in-memory rate limiter.** Its buckets live in one process's heap,
  so behind N replicas every quota is really N× and each deploy resets
  them. Point `RATE_LIMIT_DRIVER` at `redis`, or set
  `RATE_LIMIT_ALLOW_MEMORY_IN_PRODUCTION=true` if you genuinely run one
  process. An *unrecognised* driver value fails for the same reason,
  because it fell back to memory - `RATE_LIMIT_DRIVER=Redis`, capitalised,
  is the case most likely to reach production because it looks configured.

Development, testing and staging are unchanged in all three cases. Staging
is deliberately not gated: hard-failing it pushes teams to set the
override globally, which disarms the check where it matters.

Two behaviour changes that are not boot failures:

- **`fill` and `first_or_new` reject malformed values.** A value that
  cannot decode into its field's type used to become that field's
  `Default` and return `Ok` - `fill(attrs!{ age: "abc" })` set `age = 0`
  and reported success. It now returns a `ValidationError` naming the
  field, and leaves the model untouched. Unknown columns are still skipped
  silently (Laravel parity), and numeric widening still works.
- **`/_suprnova/health?db=true` no longer returns the driver error.** The
  detail moves to the log; the body keeps `"database": "error"`. Debug
  builds still include it. Dashboards parsing `status` / `database` are
  unaffected.
- **`url::signature_has_not_expired` now requires a valid signature**, and
  is deprecated. It used to answer `true` for a forged URL - a bad
  signature is not "expired", because it never had an expiry to miss - so
  any handler guarding on it alone accepted forgeries. It is now identical
  to `has_valid_signature`. If you were using it to tell *expired* from
  *invalid* (to render "request a fresh link" rather than a 403), switch to
  `url::signature_verdict`, which returns all three states. This diverges
  from Laravel's `URL::signatureHasNotExpired`, deliberately.

Two additions that need something from you only if you opt in:

- **`QueueDriver` gained `settle` and `release`**, both with default
  implementations, so existing driver impls keep compiling unchanged.
  Implement `settle` if your backend can commit a follow-up write and an
  acknowledgement in one transaction; implement `release` if it can requeue
  a reserved message in place.
- **Batch accounting can now be durable.** `DatabaseBatchRepository` needs
  two new tables, `job_batches` and `job_batch_settlements` - add them to
  your migrations, as with `jobs` and `failed_jobs`. The schema is in
  `manual/queues.md`. Nothing changes if you stay on
  `MemoryBatchRepository`.

### Security

- **Slowloris (SEC-07).** hyper's header-read timeout was documented as
  30s but inert - it only arms when a timer is installed on the connection
  builder, and none was. A client could hold a connection, and a
  `SERVER_MAX_CONNECTIONS` permit, indefinitely. Now armed and
  configurable via `SERVER_HEADER_READ_TIMEOUT`.
- **Multipart uploads (SEC-05).** The cap applied to individual part
  payloads but not to the raw stream, so a body could exceed the limit in
  aggregate. Now capped at the stream.
- **Webhook HMAC with an empty key (SEC-08).** Both payment adapters
  accepted a blank secret, which verifies anything. Refused on both.
- **Paddle signature parsing (P2-11).** An odd-length or non-hex
  `paddle-signature` reached the pinned SDK and panicked inside it. Now
  validated first: a malformed signature is a 401.
- **Passkey enrolment and reset tokens (SEC-01, SEC-02).** Anonymous
  enrolment against an existing email, non-owner enrolment, and owner
  enrolment without recent reauth are each refused with distinct statuses.
  A password login now stamps the reauth window.
- **`dev:tls` (SEC-10).** A project could choose the CA the command
  trusts.
- **Generated Docker Compose (P2-12).** Published Postgres and Redis on
  all interfaces with credentials committed in this repository. Now bound
  to loopback with per-scaffold generated passwords, `.env` written 0600,
  and symlinked targets refused.
- **Health endpoint (P2-01, CI-05).** It decided whether to query the
  database with `query.contains("db=true")` - a substring test, so
  `?nodb=true` ran the probe too. Now parsed properly. The 503 no longer
  embeds the driver error, which named hosts, ports, schemas and versions.
- **Credential issuance throttling (P2-02).** The four auth-issuance
  routes in the reference app carried no rate limit at all, and the one
  route that did keyed its bucket on the raw `x-forwarded-for` header -
  which any client can vary per request to get a fresh bucket. Both fixed;
  the issuance budget is shared across the four routes so rotating between
  them does not multiply it.
- **A redelivered chain step re-pushed its successor under a new id
  (DATA-02b, partial).** Settlement pushes the next chain link *before*
  acking, deliberately: acking first means a crash in that window loses
  the chain permanently, and a duplicate is recoverable where silent loss
  is not. But the successor's envelope got a fresh `Uuid::new_v4()` on
  every push, so the duplicate produced by that trade was
  indistinguishable from a legitimate new step - to the driver, to an
  outbox, and to the handler.

  That last one is the real cost. The framework's delivery contract is
  at-least-once and its answer to duplicates is "handlers must be
  idempotent" - but a handler keyed on `env.id`, the only identifier it
  receives, could not satisfy that contract for a chained job, because the
  duplicate arrived under a new id every time. The contract was
  unsatisfiable by construction.

  The successor's id is now a UUIDv5 derived from its predecessor's, which
  is stable across that predecessor's own redeliveries. A redelivered step
  re-pushes the id it pushed before. No schema change, no new field, no
  new dependency.

  This makes the duplicate **detectable**, which is the primitive the rest
  of DATA-02b was missing. It does not make the push atomic with the ack
  (that needs the outbox), and nothing yet rejects the duplicate on the way
  in. Both remain open.
- **Signed URLs verified one URL and executed another (SEC-04).** The
  canonical form collapsed query pairs into a map, so a repeated key kept
  only its **last** value - while `Request::query_param` returned the
  **first**. A legitimately signed `?user=victim` could therefore be
  replayed as `?user=attacker&user=victim` with the original signature
  untouched: verification canonicalised over `victim` and passed, and the
  handler acted on `attacker`.

  The canonical form now carries every pair, sorted by `(key, value)`, so
  the signature covers the exact multiset of parameters - adding,
  removing, or substituting any value breaks the HMAC. A repeated
  `signature` or `expires` is refused outright, since two of either leaves
  no non-arbitrary answer to which one governs.

  `Request::query_param` now resolves a repeated key to its last value,
  matching `query_params` and `Context::query_param`; it was the only one
  of the three that disagreed, and that disagreement was the other half of
  the defect. **Existing signed links keep working** - with no repeated
  keys the payload bytes are unchanged, which a test pins, because a
  canonical-form change that silently invalidated every outstanding
  password-reset link would be worse than the bug.

  Six regression tests, including both attack orderings, a legitimately
  repeated key that must still sign and verify, and the reordering
  guarantee. *Not* changed: `signature_has_not_expired` still reports a
  forged signature as "not expired". That is Laravel's behaviour, was
  settled deliberately as a documentation fix, and has its own test
  pinning it against a well-meaning "correction".
- **RBAC under Postgres.** Verified against a real Postgres rather than
  SQLite alone.
- **Four RustSec advisories eliminated, not renewed.** The Pinecone driver
  was rewritten against Pinecone's REST API, dropping `pinecone-sdk 0.1.2` -
  whose newest release dates from 2024-09-06 - and with it
  `tonic 0.11 → rustls 0.22 → rustls-webpki 0.102` and
  RUSTSEC-2026-0049 / -0098 / -0099 / -0104. All four were fixed upstream
  in `rustls-webpki >= 0.103.13`, which this workspace already resolved
  for its other TLS users; one abandoned crate held the tree on the
  vulnerable line. `.cargo/audit.toml` is down from five ignores to one.
  See **Changed** for what this means for the driver's API.
- **Audit exceptions now expire.** Every entry in `.cargo/audit.toml`
  carries an `OWNER` and an `EXPIRES` date, and `scripts/check-audit.sh`
  fails the release gate on a missing owner, a missing or unparseable
  date, or a lapsed one. `cargo audit` has no notion of an expiring
  ignore, so one added "temporarily" stayed until somebody re-read the
  file. The remaining entry (RUSTSEC-2023-0071, `rsa`, which has no fixed
  release at all) is owned and dated.
- **Reachability claims are checked, not asserted.**
  `scripts/check-feature-matrix.sh` resolves real dependency trees and
  asserts that no build - including `--all-features`, which is what
  `cargo audit` actually reads - contains `pinecone-sdk`,
  `rustls-webpki 0.102.x` or `tonic 0.11.x`. An exception justified by a
  comment nothing verifies stops being true the first time someone adds a
  dependency.

### Fixed

- **Every release on a database-backed queue was silently a no-op.**
  `JobOutcome::Released` - a busy `WithoutOverlapping` lock, a rate-limiter
  backoff - was implemented as "push a copy, then ack the original". The
  envelope id is the `jobs` table's primary key, so the copy collided with
  the row still holding the live reservation and the push failed with
  `UNIQUE constraint failed: jobs.id`. The worker then correctly declined
  to ack, so the requested delay was never applied, no `JobReleased` event
  fired, and the job simply parked until visibility expiry redelivered it.
  Releases are now one driver call, done in place.
- **A partial batch dispatch orphaned the jobs it had already queued
  (DATA-02).** When a `driver.push` failed mid-loop,
  `PendingBatch::dispatch` deleted the batch row - but the envelopes
  already in the queue were still stamped with that batch id, so each of
  them settled against a batch that no longer existed, returning
  `Err(batch not found)` on every delivery, forever. The batch is now
  settled instead: undispatched jobs are recorded as failures and the batch
  is cancelled, so the queued ones settle normally and the terminal
  callbacks still fire.
- **Nothing tested that `url::has_valid_signature` rejects a forged URL.**
  Found while verifying the SEC-04 fix: the entire framework suite passed
  with the primary signed-URL guard rewritten to accept any signature.
- **A scaffolded app could not migrate its database or build its image
  (REL-01b).** Neither scaffold declared `default-run`, so all nine CLI
  wrappers that shell out to `cargo run` failed on a fresh project. The
  generated Dockerfile had five independent defects - a missing lockfile
  COPY, `npm ci` without a lock, a cache stage stubbing one of two
  declared binaries, a frontend build copied from a path vite never
  creates, and a missing `frontend/src/pages` copy that
  `inertia_response!` validates at compile time. A stock scaffold's image
  could not build.
- **`docker:init` emitted one Dockerfile for every project type.** On an
  `--api` project its first instruction, `COPY frontend/package.json`,
  failed outright. API projects now get a frontend-free Dockerfile.
- **SQL placeholders (DATA-01).** Rendered per backend rather than
  assuming one dialect.
- **Queue settlement (DATA-02a, P2-06c).** Follow-ups settle before the
  reservation is acked, and a lock-release error no longer converts an
  already-succeeded job into a retry.
- **A cancelled batch fired `Catch`, never `Then`.**
- **`Builder::clone` silently dropped the eager-load plan (P2-09a).**
  `User::query().with("posts")` cloned anywhere - pagination, `count()`,
  any scope that clones - returned rows with no relations and no error.
- **Presence rosters lost members (P2-08).** The roster was snapshotted
  before subscribing, so anyone joining in that window appeared in
  neither, permanently.
- **Pinecone serialised every index acquisition (P2-14).** The write lock
  was held across two network round trips, and `tokio`'s fair `RwLock`
  meant one cold index stalled every warm one.
- **The type watcher discarded bursts (P2-13).** Leading-edge debounce
  regenerated on the first file of a burst and dropped the rest with no
  trailing run, so the last save never took effect.
- **`ssr:check` could hang, and tried one address (P2-13).** DNS ran
  outside the timeout entirely, and only the first resolved address was
  tried - so a host with an AAAA record and no IPv6 route reported the
  worker down while it was listening on v4.
- **`suprnova serve` installed `cargo-watch` unpinned (P2-13).** Now
  `--locked` with a major-version bound.
- **The release bumper rewrote five READMEs and nothing else.** Four
  manual chapters and a public doc comment pinned tags that no release
  ever updated - the doc comment was two releases stale. Discovery now
  replaces the hand-maintained list, and the smoke test greps the bumped
  tree independently rather than trusting the bumper's own verify step.
- **`db:sync` treated the database schema as trusted input (CLI-01).**
- **`migrate:fresh` is gated behind `--force` plus a typed confirmation
  (CLI-02)**, in the app binary as well as the CLI.
- **The `log` mail driver now logs the whole message**, as Laravel does,
  and no longer writes bearer links to the log in production.

### Added

- **Atomic terminal settlement (`QueueDriver::settle`, DATA-02).** The
  chain successor and the acknowledgement now commit together on
  `DatabaseQueueDriver`, closing the window where a crash between them
  either lost the rest of a chain or ran its next step twice. The
  reservation-keyed delete doubles as a fence: a worker whose visibility
  expired mid-run commits nothing and reports `Settled::Stale`, so it
  cannot enqueue work for a message another consumer now owns. Drivers that
  cannot do this answer `Settled::Unsupported` and keep the documented
  push-before-ack ordering.
- **`DatabaseBatchRepository` (DATA-02).** Batch accounting survives a
  restart, and `pending_jobs`/`failed_jobs` are derived from settlement
  rows keyed `(batch_id, job_id)` rather than stored and decremented - so a
  redelivered job cannot drive a batch to "finished" while its other jobs
  are still running, and the guard holds across processes rather than
  within one.
- **`/_suprnova/health/live` and `/_suprnova/health/ready`.** Liveness
  touches nothing; readiness probes dependencies. Wiring a database check
  into a liveness probe turns a database blip into a rolling restart of
  every replica, which the single previous endpoint invited.
  `/_suprnova/health` keeps working exactly as documented.
- **`SERVER_HEALTH_READINESS_TOKEN`.** Optional shared secret for the
  readiness probe, compared in constant time. Without it, readiness
  answers 404 - indistinguishable from an unrouted path, because it *is*
  the router's own 404. Unset by default so existing probes keep working.
- **`MAIL_SMTP_ENCRYPTION`** - `starttls` | `tls` | `none`, with `ssl` and
  `null` accepted as Laravel-compatible aliases. Unset derives from the
  credentials, reproducing the previous behaviour exactly. This also makes
  implicit TLS on port 465 reachable: the transport supported it, but no
  combination of environment variables could select it.
- **`SERVER_MAX_CONNECTIONS` and `SERVER_HEADER_READ_TIMEOUT`** documented
  in `manual/env-vars.md`, where they had been missing entirely.

### Changed

The audit's own conclusion was that the gate passed in 470s and caught
none of the 19 P1s. Most of this release's test work is aimed at that.

- **Postgres runs in the gate.** Twelve tests across six files had never
  executed. Two of them turned out to aim `DROP TABLE` at whatever
  Postgres was on `localhost:5432` by default, and neither had ever
  initialised `Crypt`, so both failed the first time they ran.
- **Scaffold assertions read the bytes a user receives**, after
  substitution, rather than the template source. Found an API project
  shipping a doc comment naming a database literally `{package_name}`, and
  a `.env.example` advertising five mail keys the framework never reads.
- **Queue fault injection.** ACK loss, redelivery, lease lapse and partial
  dispatch are driven by a decorator that fails a named operation on a
  named call, so every case is deterministic rather than a sleep race.
- **Payment adapters have negative tests.** Stripe's `verify()` had never
  been exercised with a *valid* signature, so every rejection path that
  depends on reaching the HMAC comparison was unproven.
- **The Pinecone driver speaks REST.** *Breaking, behind the
  off-by-default `vector-pinecone` feature.* Motivation is under
  **Security**; the surface changes are:
  - `client()` is gone - there is no `PineconeClient` any more. Replacing
    it are `control_plane_get`, `control_plane_post` and `data_plane_post`,
    which reach *any* Pinecone endpoint with your own request and response
    types over the driver's authenticated, host-resolved transport. That
    is strictly more reach than the old trapdoor had.
  - `json_to_metadata` → `metadata_from_json`, and metadata is now
    `serde_json::Map` rather than `prost_types::Struct`. `decode_match_fields`
    → `decode_match`, taking a `PineconeMatch`. `namespace()` returns
    `&str`.
  - New: `with_control_plane`, `with_api_version`, `with_index_host`
    (pins a known host and skips the control-plane round trip),
    `index_host`, and the `PineconeVector` / `PineconeMatch` wire types.
  - `from_env` still reads `PINECONE_API_KEY` and
    `PINECONE_CONTROLLER_HOST`, and now also `PINECONE_API_VERSION`.
  - The REST API version is pinned, not floated - `2025-04`, the version
    the driver's request and response shapes were written against.
  - Nothing serializes any more. The old driver cached one `Index` per
    name behind a `tokio::Mutex` because `pinecone-sdk` exposed it only
    behind `&mut self`; the new one caches a host string and shares
    `reqwest`'s connection pool.
  - A host learned from the control plane is always contacted over
    `https`, whatever scheme the response carries.
  - `Debug` is implemented by hand with the API key redacted, so a
    `#[derive(Debug)]` on a struct holding a driver can't print it.
- **Wire-contract tests for Pinecone.** The live integration tests need a
  `PINECONE_API_KEY` and so cannot run in the gate - which left a REST
  rewrite's field names (`topK`, `includeMetadata`, `vectorCount`) resting
  on nothing. Thirteen tests now drive the driver against a local
  `wiremock` fake and assert the exact method, path, headers and JSON body
  it puts on the wire, plus that a non-2xx is never decoded as a result
  and that an error message never carries the API key. They pin the driver
  to Pinecone's *documented* contract; only the `#[ignore]`d tests can
  confirm the documentation matches the live service.

## 0.7.2 - 2026-07-28

### Fixed

- **`generate-types` resolves nested prop structs without derives.** 0.7.1's
  generator degraded any prop field whose type didn't derive
  `InertiaProps`/`Data` to `unknown` - so re-running the generator (or the
  `suprnova serve` watcher) over a project with a committed types file
  replaced real interfaces like `Array<AdminArticleRow>` with `unknown` and
  broke type-checking across the app. Plain structs defined anywhere in
  `src/` now resolve to their real interfaces, transitively from the prop
  roots; `unknown` (with a warning) is reserved for types the project
  genuinely doesn't define - external crate types, enums, tuple structs.

### Changed

- **`routes.ts` generation is opt-in.** `generate-types` no longer drops
  `frontend/src/types/routes.ts` into every project unasked; pass
  `--routes` to generate it.

- **Frontend starter dependencies refreshed.** New scaffolds from
  `suprnova new` now pin current versions: Vite ^8.1.5, Tailwind CSS ^4.3.3,
  Svelte ^5.56.8 (vite-plugin-svelte ^7.2.0, svelte-check ^4.7.4),
  React ^19.2.8 (plugin-react ^6.0.4), Vue ^3.5.40 (plugin-vue ^6.0.8,
  vue-tsc ^3.3.8), and `@types/node` ^24 (the Node 24 LTS types line).
  TypeScript stays at ^6.0.3 deliberately: it is the latest 6.x, and
  svelte-check's peer range (`^5 || ^6`) does not yet admit TypeScript 7.
  All three starters were verified end to end (`npm install` +
  `npm run build`) against the refreshed set.

## 0.7.1 - 2026-07-27

A defect-fix pass over 0.7.0's queue routing, from a full post-release review.

### Fixed

- **Chained jobs no longer lose their declared queue.** `ChainLink` captured a
  job's `max_tries`, `timeout`, and `backoff` at chain-build time but not its
  `Job::queue()`, so a job that landed on its declared queue when pushed
  directly landed on `default` when dispatched as part of a chain - the "job"
  tier of the route → job → default resolution order silently vanished for
  chains. The declared queue is now captured on the link and resolved exactly
  like a direct push. Chain payloads written before this release decode
  unchanged (`serde(default)`), and a link with no declared queue serializes
  byte-identically to what 0.7.0 wrote.
- **Failed-job records carry the queue the job died on.** The worker's
  dead-letter path hardcoded `queue = "default"` into every `FailedJob`
  record, so failures of a routed job were invisible to an operator filtering
  the failed store by the pool that owns them. The record now carries the
  envelope's queue (`default` for unrouted jobs).
- **The 0.7.0 upgrade note understated the `jobs` migration.** It read
  "unfiltered workers are unaffected and need no migration", but
  `DatabaseQueueDriver::push` names the `queue` column in its `INSERT`
  whether or not the job is routed - a 0.7.0 binary against an un-migrated
  table fails **every push**, filtered or not. The 0.7.0 section below and
  `manual/queues.md` are corrected: on the database driver the `ALTER TABLE`
  is required for every deployment, and it must run before binaries roll
  (older binaries list their columns explicitly, so migrating first is safe).

- **README no longer advertises a `#[job]` macro.** No such macro exists -
  jobs implement the `Job` trait. The queues row now describes the real
  surface, including 0.7.0's queue routing.

### Changed

- **The release path now bumps README version references.**
  `bump-workspace-version.py` rewrites the README's pinned install tag, the
  distribution-model example, and the MSRV line atomically with the
  manifests, and a reworded README that stops matching a pattern fails the
  release loudly. The README had advertised v0.6.0 since v0.7.0 shipped
  because nothing in the release path touched it.
- **Connection routing is documented as name-resolution only.**
  `Job::connection()` and the connection field of `Queue::route` resolve the
  connection *name* carried on the `JobQueueing` / `JobQueued` lifecycle
  events; a single process-global driver still receives every push, so they
  do not select a different driver. The rustdoc and `manual/queues.md`
  previously implied driver selection that does not exist. The queue
  dimension is unaffected - it is honored end to end. Per-connection drivers
  remain future work.
- `ChainLink` gained a public `queue: Option<String>` field, which breaks
  struct-literal construction of chain links. Links built through
  `ChainLink::from_job` - the normal path - are unaffected.

### Upgrading

Coming from ≤ 0.6.x on the database queue driver, apply the 0.7.0 migration
below **before** rolling binaries; it is required for every deployment on
that driver, not just ones using `--queue`. 0.7.1 itself needs no migration.

## 0.7.0 - 2026-07-26

### Security

- **Upgraded `ammonia` to 4.1.4 (RUSTSEC-2026-0213).** Versions through 4.1.3
  allow XSS via SVG `animate` and `set` animation tags. `ammonia` is the
  sanitizer at the end of Suprnova's markdown pipeline
  (`comrak` → `syntect` → `ammonia`), so any app rendering user-supplied
  Markdown through `content` was exposed. The advisory was published
  2026-07-21 - after v0.6.5 shipped - so **every release up to and including
  v0.6.5 is affected**. Upgrading the framework is the fix; no application
  code changes are required.

### Added

- **Queue routing.** Jobs can be dispatched to a specific queue and connection,
  and workers can be dedicated to specific queues - the Laravel 13
  `Queue::route(...)` surface, typed. A job states its own home with
  `Job::queue()` / `Job::connection()`; an operator overrides it centrally with
  `Queue::route::<SendInvoice>(Some("redis"), Some("billing"))` in
  `bootstrap::register()`, without editing the job. Resolution is route, then
  job, then global default, and a `None` field in a route defers rather than
  clearing. `queue:work --queue=billing,default` drains only those queues.
  Unrouted jobs belong to `default`, so they are never stranded. Chained jobs
  resolve routes by name, since a chain link stores its job erased.
- **`QueueDriver::pop_from`.** Filtering pop, with a default implementation that
  **rejects** a filter it cannot honor rather than silently draining every
  queue - a worker told to drain `billing` that quietly drains everything is
  indistinguishable from a working deployment until the wrong pool eats the
  wrong jobs. The memory and database drivers filter natively. Custom drivers
  keep compiling and inherit the loud default.
- **Documented the `jobs` table schema.** `manual/queues.md` now carries the DDL
  `DatabaseQueueDriver` actually expects, which was previously only discoverable
  by reading the driver's SQL.
- **Documented Inertia's `serverHead` option.** Server-driven `<head>` elements
  (Inertia 3.5.0) need no framework support: the client reads them from an
  ordinary prop, so any handler can already supply them. See
  `manual/frontend-inertia-responses.md`.

### Changed

- `Envelope` gained a `queue: Option<String>` field. It is `serde(default)` and
  skipped when absent, so an unrouted envelope serializes byte-identically to
  what previous versions wrote - the frozen wire-format test passes unchanged,
  there is no `schema_version` bump, and mixed-version fleets interoperate
  during a rolling upgrade.
- `WorkerConfig` gained a `queues: Vec<String>` field (empty = drain everything,
  the previous behaviour).
- Removed `ROADMAP.md`. Its design principles live in `manual/introduction.md`,
  the working agreement in `manual/contributions.md`, and the deployment and
  scale-out material in `manual/deployment.md`; the shipped/planned checklists
  had gone stale. `README.md`'s pointer to it for "the relationship to upstream"
  was already dangling - that attribution lives in `LICENSE`.
- Scaffold frontends now pin `@inertiajs/{svelte,react,vue3}` at `^3.6.1`
  (from `^3.4.0`). The 3.4.0 → 3.6.1 range is client-side only - audited against
  the upstream changelog and the `Page` contract in `packages/core/src/types.ts`,
  every `X-Inertia-*` header the 3.6.1 client sends was already handled.
- `scripts/release.sh` now publishes the GitHub release itself, with notes taken
  from the version's `CHANGELOG.md` section. Previously this was a manual
  "next step" that got skipped, which is why v0.5.10 and v0.6.1-v0.6.3 are
  tag-only and the Releases page sat on a stale version. Preflight runs before
  the gate so a missing `gh` or changelog section fails in seconds, and
  publishing is skipped automatically unless `origin` is GitHub.

### Upgrading

Existing `jobs` tables on the database queue driver **must** add the new
column - `push` names it in its `INSERT` whether or not the job is routed, so
an un-migrated table fails every push. Migrate first, then roll binaries
(older binaries list their columns explicitly and ignore the new one, so that
order is safe):

```sql
ALTER TABLE jobs ADD COLUMN queue TEXT NULL;
CREATE INDEX idx_jobs_queue ON jobs(queue);
```

*(Corrected in 0.7.1 - this note originally claimed unfiltered deployments
needed no migration.)*

## 0.6.5 - 2026-07-21

### Added

- **Hosted one-off Checkout in the Stripe adapter.** `Checkout::start_session`
  with `SessionMode::OneOff` and non-empty `price_refs` now creates a hosted
  Checkout Session (`mode=payment`, one line item per price ref,
  `allow_promotion_codes=true`) and returns
  `SessionPayload::StripeCheckoutRedirect`. The `amount_hint`-only Elements
  path is unchanged; the two shapes are picked per request.
- **Stripe Managed Payments (merchant-of-record) support.**
  `StripeProvider::with_managed_payments(true)` - or
  `STRIPE_MANAGED_PAYMENTS=true` in `from_env()` - sends
  `managed_payments[enabled]=true` on hosted one-off session creation. Off by
  default; the field is omitted entirely so non-enrolled accounts are
  unaffected.
- **`Checkout::session_status`.** New trait method (default:
  `PaymentError::NotSupported`) reporting a session's provider-side state as
  the new neutral `CheckoutSessionState` (`Open` /
  `Complete { paid, payment_ref, amount_total }` / `Expired`). The Stripe impl
  maps `GET /v1/checkout/sessions/{id}`; `payment_ref` carries the session's
  PaymentIntent id for mirror-table correlation. This is the server-side
  verification primitive for redirect return pages and reconciliation sweeps.
- **`Promotions` capability trait.** `create_promotion_code` mints a
  customer-restricted, optionally expiring, redemption-capped code off a
  pre-created coupon. Queried via the new
  `PaymentProvider::as_promotions()` (default `None`). Implemented for Stripe
  (`POST /v1/promotion_codes`) and the mock.
- **`MockPaymentProvider` upgrades for the above.** Records every
  `start_session` request (`recorded_sessions()`), scripts `session_status`
  per session id (`script_session_status()` - unscripted known sessions
  report `Open`, unknown ids `NotFound`), and implements `Promotions` with
  recorded requests (`recorded_promotion_requests()`).

## 0.6.4 - 2026-07-17

### Fixed

- **Eloquent aggregates decode consistently across database backends.** Generated
  `count`, `sum`, `avg`, `min`, and `max` expressions now use one stable internal
  result alias. PostgreSQL no longer returns false zeroes or `None` because its
  driver labels aggregate columns differently from SQLite, and missing-column or
  incompatible-type errors now propagate instead of being silently defaulted.
- **Mass deletes cannot use caller-supplied table expressions.** Executable
  delete SQL always derives its target from the model's validated static
  `M::TABLE`. The legacy public renderer argument remains source-compatible but
  cannot redirect or inject the delete target.

## 0.6.3 - 2026-07-15

### Added

- **Typed raw reads can stay on a transaction's pinned connection.**
  `Transaction::backend()` exposes the active backend and
  `Transaction::query_all(Statement)` executes typed aggregate or custom SQL
  through the transaction while preserving `QueryExecuted` instrumentation.
  Applications no longer need a pool-level query or private executor access
  when a lock-scoped decision depends on computed result columns.

## 0.6.2 - 2026-07-15

### Fixed

- **Bound raw predicates are backend-neutral.** Eloquent `filter_raw` and
  `where_raw` now accept portable `?` bind markers on every database backend;
  PostgreSQL rendering rebases them to monotonic `$N` positions across prior
  predicates, relationship subqueries, HAVING clauses, and UNION arms. Existing
  numbered PostgreSQL fragments are normalized by their local marker order,
  while mixed styles and bind-count mismatches fail validation before I/O.
  The SQL-aware scanner preserves question marks inside quoted strings,
  identifiers, comments, and dollar-quoted bodies; `??` emits a literal
  question-mark operator in a bound raw fragment.

## 0.6.1 - 2026-07-15

### Added

- **Observable supervised session cleanup.** `SessionMiddleware::install`
  uses the configurable `SESSION_GC_INTERVAL` cadence (one hour by default),
  while `session_gc_metrics()` exposes process-local run, success, failure,
  removed-row, and last-result timestamps for protected operations surfaces.
- **Bounded sliding-session touches.** `SESSION_TOUCH_INTERVAL` controls the
  minimum activity-write cadence (five minutes by default) and is capped at
  half the session lifetime so active sessions cannot expire between touches.

### Fixed

- **State-free requests no longer create durable sessions.** Requests without
  a valid session cookie perform no session-store read or write and receive no
  session cookie unless handling creates state. Existing clean sessions avoid
  unconditional upserts and cookie churn, legacy cookies migrate on their next
  request, and cookies whose backing rows have expired are cleared without
  recreating empty sessions.

## 0.6.0 - 2026-07-10

### Added

- **Opt-in framework subsystems with backward-compatible defaults.** Filesystem
  storage, SQLite/Postgres/MySQL database drivers, the MariaDB vector driver,
  and Web Push now have explicit Cargo features. Existing default builds retain
  all of these capabilities, while `default-features = false` consumers can
  select zero drivers or only the storage/database/vector/push surface they use.
  The executable feature matrix verifies zero-driver, individual-driver,
  Nation X minimal, default, and all-feature profiles.
- **Raw P-256 VAPID private-key import.** `VapidKey::from_bytes` accepts a
  validated 32-byte big-endian P-256 scalar alongside the existing PKCS#8 PEM
  import/export path.

### Changed

- **VAPID JWTs are signed directly with P-256.** Web Push now serializes the
  RFC 8292 ES256 header/claims and signs them with `p256`, removing the generic
  JWT dependency while preserving generated keys, PEM round trips, public-key
  encoding, and the 24-hour lifetime bound.
- **Security dependency refresh.** Updated vulnerable framework dependencies,
  including bcrypt and ammonia, and narrowed Comrak's enabled features while
  retaining syntax highlighting.
- **Rust 1.91.1 is the release MSRV.** Every workspace package declares the
  same `rust-version`, generated Dockerfiles pin the matching builder image,
  and the full release gate compiles the supported filesystem profile with the
  exact Rust 1.91.1 toolchain.
- **OpenDAL 0.58 security pin.** The filesystem feature pins
  `eas4ai/opendal` commit
  `88717391eb72c9839d3f8e79fccad9f22fc3a1b4`, a minimal fork based exactly on
  official Apache OpenDAL commit
  `ae99a3b016e354a1b2bb2baf0c70f9f9e134970a`. The fork changes only the
  Reqsign declarations used by OpenDAL core plus S3, GCS, and Azure Blob so
  downstream consumers resolve official Apache Reqsign commit
  `b49cd2996b9d2d9944e84481f8835ff55b188b97` and `quick-xml` 0.41.0. A fork is
  required because a dependency repository's root Cargo patches do not
  propagate to consumers; the published graph could otherwise restore
  vulnerable `quick-xml` 0.38/0.40.

### Fixed

- **Atomic release version metadata.** The release bump now updates
  `workspace.package.version` and every versioned internal path dependency in
  one validated operation, stages every affected manifest, and proves a
  temporary `0.6.0` workspace with `cargo check --workspace` before release.
  Release versions are validated as strict SemVer 2.0, including the numeric
  prerelease leading-zero rule. Version-agnostic disposable bare-remote smokes
  derive a later patch release from both the current source and an already
  `0.6.0` source, reject staged/unstaged/untracked release trees before the
  gate, prove atomic commit/tag publication rolls both refs back when a tag is
  rejected, and prove the normal release sequence without touching the real
  remote. Release versions must increase by SemVer precedence, including
  prerelease transitions. Smoke build artifacts always stay inside their
  temporary workspace, ignoring any caller `CARGO_TARGET_DIR`.
- **Rustdoc covers every supported feature boundary.** The OAuth module links
  to public `OAuthAuth::complete`, and the executable matrix builds zero-driver,
  default, and all-feature rustdoc with no dependencies.
- **Filesystem stream validation is session-scoped.** Local filesystem writers,
  listers, and copiers resolve and confine their paths once before first I/O
  instead of once per chunk/item, while activated close/abort operations always
  reach the backend for cleanup. Existing traversal and symlink confinement
  remain enforced for a trusted filesystem; canonicalize-then-open checks do
  not eliminate races against a principal concurrently mutating the tree.

### Security

- **The release gate fails closed.** `release.sh` delegates to the canonical
  full gate before editing manifests or creating commits/tags; that gate always
  runs `cargo audit`, treats a missing `cargo-audit` binary as an error, and
  stops on any audit failure. It also builds and audits an isolated downstream
  filesystem consumer, asserting exact OpenDAL/Reqsign source revisions and no
  `quick-xml` below 0.41. No new advisory ignores were added.

## 0.5.10 - 2026-07-03

### Fixed

- **`generate-types` no longer drops self-referencing structs.** A struct with a
  field that references its own type (a tree node with `children: Vec<Self>`,
  e.g. a threaded-comment view) created a self-edge in the type-dependency
  graph, pinning its in-degree above zero so Kahn's topological sort never
  emitted it - leaving every interface that referenced it with a dangling type
  name that failed `svelte-check`/`tsc`. Self-edges are now stripped before
  sorting, and any structs trapped in a reference cycle (mutual recursion) are
  emitted in arbitrary order rather than dropped, since TS interfaces may
  reference one another regardless of declaration order.

## 0.5.9 - 2026-07-01

### Added

- **`MAIL_FROM_NAME` - optional display name on auth-flow emails.** The
  email-verification, password-reset, and password-changed mailables now render
  their `From` header as `"Name <address>"` when `MAIL_FROM_NAME` is set (read
  at send time so it survives the queue's serde round-trip). `MAIL_FROM` stays a
  bare address; leaving `MAIL_FROM_NAME` unset or blank keeps the previous
  bare-address behavior. No change to any call site - the mailables read the env
  var themselves.

## 0.5.8 - 2026-06-30

### Fixed

- **`generate-types` route helpers are always valid TypeScript.** When several
  routes in a module share one handler (e.g. a `static_files::serve` whitelist
  mapping many favicon/asset URLs), the first kept the handler name and the rest
  got a key derived from the route path - but the path was only partly
  sanitized (`/ { } -` → `_`), so a file extension leaked a `.` into the key:
  `favicon_16x16.png: (...) => ...`. That is member access, not a property name,
  so `tsc`/`svelte-check` rejected the generated `routes.ts`. Derived keys are
  now sanitized to legal identifiers - every non-alphanumeric character becomes
  `_` and a leading digit is prefixed - so `favicon-16x16.png` → `favicon_16x16_png`
  and `2fa.json` → `_2fa_json`. Unique handler names are untouched.

## 0.5.7 - 2026-06-30

### Fixed

- **`generate-types` no longer emits dangling type references.** A prop field
  whose type is a struct that doesn't derive `InertiaProps`/`Data` (or an
  external type the generator can't see) was emitted as a bare identifier - e.g.
  `user: UserInfo` - producing TypeScript that fails `tsc`/`svelte-check`
  because that interface is never written. Such references now degrade to
  `unknown` (`user: unknown`; `Vec<T>` → `Array<unknown>`; `Option<T>` →
  `unknown | null`), so generated output always type-checks, and
  `generate-types` prints a warning naming the unresolved type and the field
  that references it, with the fix (derive `InertiaProps`/`Data` on it).
  Generic parameters and resolved nested InertiaProps/Data types are
  unaffected.

## 0.5.6 - 2026-06-29

### Changed

- **Sign in with Apple: RS256 JWKS verification.** Bump `suprnova-apple-rs` to
  v0.3.1 - Apple ID tokens are now verified against Apple's published JWKS
  (RS256) instead of being trusted structurally.

## 0.5.5 - 2026-06-28

### Added

- **`MagicLink` token purpose.** New `MagicLink` variant on the auth-flow
  `TokenPurpose` enum, for passwordless magic-link sign-in tokens.

## 0.5.4 - 2026-06-28

### Changed

- **Composable OAuth completion.** Split the generic OAuth completion into
  `verify_oauth_identity` (verify + resolve the identity) and a thin `complete`,
  so apps can verify an OAuth identity without triggering the full
  session-completion side effects.

## 0.5.3 - 2026-06-28

### Fixed

- **Correct workspace version metadata.** v0.5.2 was tagged and pushed before
  its `Cargo.toml` version bump was staged, so the pushed v0.5.2 tag still reads
  `version = "0.5.1"`. v0.5.3 re-cuts the release with the correct workspace
  version - no code change (the v0.5.2 OAuth split is unaffected).

## 0.5.2 - 2026-06-28

### Changed

- **Composable Apple completion.** Split Apple Sign-In completion into
  `verify_apple_identity` + a thin `complete_apple`, mirroring the generic OAuth
  split. (Note: the pushed v0.5.2 tag carries a stale `0.5.1` version field -
  fixed in v0.5.3.)

## 0.5.1 - 2026-06-28

### Changed

- **Renamed Apple crate.** Repoint the Apple dependency to the renamed
  `suprnova-apple-rs` repository.

## 0.5.0 - 2026-06-28

### Added

- **Sign in with Apple.** OAuth token exchange + ID-token verification + user
  upsert for Apple; Apple well-known endpoints and the `form_post` response
  mode; Apple-specific fields on `OAuthProviderConfig`; `AppleKeyPair`
  re-exported so apps configure Apple Sign-In without a direct `apple`
  dependency.

### Fixed

- Omit PKCE parameters from the Apple authorize URL (Apple rejects the request
  when they are present).

### Dependencies

- Consume the `torii` magic-auth fix; add `apple-rs` v0.3.0.

## 0.4.1 - 2026-06-26

### Performance

- Pre-size `MiddlewareChain` to eliminate per-request `Vec` reallocations.

### Fixed

- Make the maintenance down-file path collision-proof under parallel test runs.

### Docs

- Compile-check the framework's doc examples (`ignore` → `no_run`); reconcile
  the distribution notes with the tagged GitHub Releases; ignore the whole
  `docs/` tree.

## 0.4.0 - 2026-06-22

### Changed

- **Distribution is git-tracked; you don't pin to tags.** Scaffolded apps
  depend on `suprnova = { git = "…/suprnova.git" }` and track the default
  branch; pull updates with `cargo update -p suprnova`. Versions are published
  as tagged GitHub Releases (`v0.4.0`, …) for the changelog, but `Cargo.lock`
  already pins the exact resolved commit - so builds stay reproducible without
  hand-pinning a `tag` or `rev`. The installation docs no longer present
  commit-pinning as the update path.

## 0.3.0 - 2026-06-21

### Added

- **Query instrumentation for Eloquent reads** - `Builder::get`, `Model::find`,
  `find_many`, and `all` now emit `QueryExecuted`, so model SELECTs and
  eager-load queries surface in `DB::listen` and the in-memory query log
  alongside writes and raw queries. Adds the instrumented
  `ExecutorChoice::statement_all` read terminal.
- **Resource-route authorization** - `ResourceRoutes::authorize_resource::<U, R>()`
  attaches the conventional ability check to every generated resource route as
  per-route middleware (Laravel `authorizeResource` parity). The action→ability
  map is `index`/`show` → `view`, `create`/`store` → `create`,
  `edit`/`update` → `update`, `destroy` → `delete`. One call gates the whole
  seven-action surface instead of relying on every controller body to remember
  a `Gate::authorize`.
- **Atomic rate-limit hit** - `RateLimiter::hit_and_check(key, max, decay)`
  increments a fixed window and tests it in a single round-trip, returning
  whether the bucket is now over its limit (`i64::MAX` means unlimited).
- **Constant-time comparison helper** - `constant_time_eq(a, b)` (subtle-backed)
  for webhook signature verification; `WebhookHandler::verify` docs now mandate
  constant-time digest comparison.
- **Inertia client to 3.4.0** - the Svelte/React/Vue scaffolds now pin
  `@inertiajs/{svelte,react,vue3}` at `^3.4.0` (from `3.1.1`), picking up
  `router.poll` modes, dynamic `usePoll`, `Inertia.once`, the InfiniteScroll
  cancel fix, and awaited Form `onSuccess`. The server already emits the full
  3.4.0 page-object and header surface (once-props, the prepend/deep-merge
  scroll family, `matchPropsOn`, rescued/shared props), so this is a
  client-currency bump with no protocol change.
- **Optional connection cap** - `SERVER_MAX_CONNECTIONS` (and the programmatic
  `Server::max_connections(n)`) bounds concurrently active connections with a
  semaphore on the accept loop, applying back-pressure at the TCP level. Unset -
  or `0` - leaves connections unbounded (the default, unchanged). A backstop to
  pair with a reverse proxy and `LimitNOFILE`, not a replacement for upstream
  rate limiting.
- **Opt out of redirect-following** - `RequestBuilder::no_redirects()` routes a
  request through a non-following HTTP client so a `3xx` is returned as-is
  instead of chased. Use it when the request URL is influenced by untrusted
  input, to close a redirect-based SSRF vector (a hostile endpoint redirecting
  toward an internal or cloud-metadata host). The default client still follows
  redirects, matching general-client convention.

### Security

- **Resource routes** fail closed on the authorization registry's type-erased
  downcast instead of panicking, and `authorize_resource` denials /
  unauthenticated requests are refused before the handler runs.
- **Rate limiter** closes a fixed-window check-then-hit race by incrementing and
  comparing atomically (`hit_and_check`).
- **Queue `RateLimited` middleware** now admits jobs through that atomic
  `hit_and_check` instead of a separate `too_many_attempts` + `hit` pair, so
  concurrent workers can no longer all pass the budget check before any of them
  increments and over-admit past `max_attempts`.
- **Upload validators** (`mimetypes` / `mime`) content-sniff the uploaded bytes
  instead of trusting the client-supplied `Content-Type`.
- **Filesystem path guard** canonicalizes paths to catch symlink traversal out
  of the storage root, beyond the prior lexical `../` / absolute / UNC checks.
- **Auth** closes a passwordless-login timing oracle - a matched-but-passwordless
  account given a password now runs a fixed-cost verify, across both the Eloquent
  and database user providers - and `dummy_verify` drives the configured hasher so
  the unmatched-user path is constant-time.
- **Eloquent** validates column identifiers on the `pluck` / `value` /
  `pluck_keyed` / `sole_value` and `sum` / `avg` / `min` / `max` projection
  paths.
- **Payments** - the mock provider's verifier fails closed outside a development
  environment, and webhook source IPs resolve through `TrustedProxiesConfig`
  (`req.ip()`) rather than a raw `X-Forwarded-For` header.
- **Filesystem path guard** now walks to the nearest *existing* ancestor when a
  write target doesn't exist yet, closing a symlink escape where a planted
  intermediate symlink with a missing immediate parent slipped past the guard.
- **`DB::init_with`** validates the environment before connecting (matching
  `DB::init`), so the dev SQLite fallback can no longer boot silently in
  production through that entry point.
- **Static-file serving** rejects dotfiles (`.env`, `.git/config`, `.htpasswd`,
  any leading-`.` segment), not just `.`/`..` traversal.
- **Payment webhooks** serialize concurrent retries of the same unprocessed
  event with a `FOR UPDATE` lock + re-check, and treat mirror-table unique
  violations as benign already-applied; `payments_subscription_items` gains a
  `UNIQUE(subscription_id, provider_item_id)`.
- **RBAC** defaults the model discriminator to the fully-qualified type name, so
  two authenticatable types sharing a leaf name can no longer inherit each
  other's roles/permissions.
- **`invalidate_session()`** rotates the session id (not just flushes), closing a
  session-fixation gap; the queue `WithoutOverlapping` middleware releases its
  cache lock even when the job panics.
- **Mail providers** cap error-response body reads (8 KiB), matching the
  web-push client, so a hostile endpoint can't drive sender memory.
- **Web push** disables HTTP redirect-following on the default client, so an
  attacker-influenced push endpoint can no longer `3xx`-redirect a notification
  POST toward an internal or cloud-metadata host (SSRF). A redirect now surfaces
  as a rejected push rather than a silently followed request.
- **Stripe adapter** `Debug` redacts the webhook signing secret *and* prints a
  placeholder for the `stripe::Client` (which carries the API secret key in its
  auth header), so neither secret can reach logs through a `{:?}` of
  `StripeProvider`, regardless of the upstream client's own `Debug`.
- **Stripe adapter** `from_env` rejects present-but-blank credentials, failing
  closed instead of constructing a client with an empty (and therefore forgeable)
  webhook HMAC secret.
- **OAuth email verification** fails closed for unrecognised providers: a
  userinfo payload carrying an `email` but no `email_verified` flag is no longer
  treated as verified. An unknown provider must now assert `email_verified: true`
  or expose a verified-emails endpoint, closing an account-link/takeover vector
  for apps that key accounts on email. Google (explicit-`true`-only) and GitHub
  (verified-by-the-`/user`-contract) are unchanged.

### Fixed

- **Nested eager loading** (`with(["posts.comments"])`) is now a constant number
  of queries - the tail segment loads in one batched IN query across all
  parents instead of one query per parent (N+1).
- **`where_has`/`where_doesnt_have`** qualify closure columns with the target
  table, so a column present on both pivot and target no longer produces an
  ambiguous-column error on many-to-many relations.
- **Soft-delete `delete`/`force_delete`/`touch` and factory `persist`** honor a
  model's `#[model(connection = "…")]` routing (matching `restore` and the
  other write paths) instead of falling back to the primary pool.
- **JSON:API `Maybe::Missing`** uses a non-collidable wire sentinel, so user
  data shaped like `{"__missing__": true}` is no longer silently stripped.
- **Queued notifications** honor `should_send` (per-channel veto) and
  `after_sending`, re-checked on the worker - previously only the synchronous
  path did.
- **Released jobs** push the retry copy before acking the original, so a transient
  driver push error no longer drops the job.
- **Paddle adjustment (refund) webhooks** key the mirror update off the referenced
  transaction id and read amounts from `data.totals`, instead of inserting a
  zero-amount row under the adjustment id.
- **SQLite URLs** carrying a query string (`sqlite://db.sqlite?mode=rwc`) build a
  valid single-query connection URL and a clean on-disk filename.
- **HTTP** clamps `Accept` `q`-values to `[0,1]` and enforces a `FormRequest`'s
  `max_body_bytes` even when the body was pre-buffered; **WebSocket** config
  rejects `max_missed_pings < 2` (1 closed every connection on its first ping).
- **Cron** day-of-month and day-of-week use OR semantics when both are restricted
  (Vixie/POSIX parity); Markdown `plain_text`/excerpts preserve intentional
  spaced punctuation; `CachedEvaluator` bounds its cache growth;
  `SupervisorRegistry::start_all` no longer double-spawns on a second call; the
  test container recovers in place from a poisoned lock.
- **Supervisor restart backoff** resets to the 100 ms floor after a run that
  stays up at least the 60 s cap, so a daemon that ran healthily for a long
  stretch and then exits restarts promptly instead of inheriting backoff that
  climbed during an earlier failure burst. A crash loop whose runs never reach
  the threshold still ramps to the cap, so the reset never masks a flapping
  supervisor.
- Corrected stale docs on `filter_op` (operators are allowlist-validated), signed
  URLs (not byte-compatible with Laravel's default absolute signatures),
  `UniqueIdKind::is_valid` (a caller helper, not auto-wired into `find`), and the
  identifier length cap (128, not 64).

### Documentation

- Documented resource-route authorization (`authorize_resource`) in the routing
  and authorization chapters, and the atomic `hit_and_check` counter in the
  rate-limiting chapter.

## 0.2.0 - 2026-06-21

Adds role-based access control, a Markdown content / docs-rendering pipeline, and
native static-file serving.

### Added

- **Tier-2 RBAC** - `HasRoles` trait; roles + permissions with a
  `role_has_permissions` join; `PermissionMiddleware` / `RoleMiddleware` (both
  fail-closed / default-deny); the `CreateRbacTables` migration; and
  `create_role` / `create_permission` / `give_permission_to_role` helpers.
- **Content rendering** - Markdown rendering and a docs-build pipeline:
  `MarkdownRenderer`, `build_docs`, `DocsCatalog` / `DocsChapter`, heading
  extraction and `slugify_heading`. Rendered HTML is sanitized
  (comrak + syntect + ammonia).
- **Native static-file serving** - `StaticFiles::public()` fallback handler for
  serving a `public/` directory at the web root, replacing hand-rolled per-asset
  whitelist controllers in apps.

### Fixed

- Freshly generated apps inherit a framework-level `time = 0.3.47` compatibility
  pin, avoiding Rust 1.96 coherence conflicts from `time 0.3.48` in fresh
  scaffold dependency resolutions.

### Documentation

- Documented the two shipped starter kits - **Nebula** (Breeze-tier auth) and
  **Pulsar** (product site + community) - across the manual, README, and roadmap;
  restructured the roadmap around the shipped surface; and reconciled version
  references throughout the docs.

## 0.1.0 - 2026-06-10

The initial Suprnova release. Suprnova is a Laravel-inspired web
framework for Rust, forked from Kit and taken in its own direction.
Today's parity target is Laravel 13.x.

This release uses the git distribution model: framework consumers depend
on `suprnova = { git = "https://github.com/eas4ai/suprnova.git" }`,
and the CLI installs with `cargo install --git`.

### Added

#### HTTP, routing, and middleware

- `Router` with route groups, prefixes, parameter constraints, named routes
- Compile-time-validated route registration via the `routes!` macro
- Resource routing (`Router::resource`) producing the seven standard routes
- Signed URLs (`url::signed_route` / `url::temporary_signed_route` free
  functions, plus `Redirect::signed_route` / `Redirect::temporary_signed_route`)
- Redirect helpers - `Redirect::to`, `Redirect::back`, `Redirect::route`,
  `Redirect::with_input`, `Redirect::with_errors`, `with_flash`
- Middleware trait with global, group, and per-route layers
- Built-in middleware - CORS, CSRF, session, request timeout,
  request ID, throttle / login throttle, signed-URL verify,
  authenticated, email-verified, brute-force
- Abort helpers (`abort`, `abort_unless`, `abort_if`)
- `suprnova::handle_request(...)` - public adapter to serve a single
  hyper request against a router + middleware chain

#### Inertia.js frontend bridge

- `#[derive(InertiaProps)]` with TypeScript type emission
- `inertia_response!` macro with compile-time component validation
- Three first-class starter frontends - **Svelte 5** (runes-on),
  **React 19**, **Vue 3.5** - all on Inertia 3.1.1 + Vite 8 + Tailwind v4
- Partial reloads (`only` / `except`), deferred props, persistent
  layout, encrypted history, scroll preservation
- `Inertia::paginate(component, key, paginator)` for paginator → Inertia
  prop wiring

#### Eloquent-style ORM (over SeaORM)

- `#[suprnova::model]` attribute macro that emits a SeaORM entity and
  the user-facing Eloquent struct in one shot
- Full `Model` trait - `create`, `find`, `find_or_fail`, `find_many`,
  `all`, `query`, `save`, `update`, `delete`, `force_delete`, `refresh`,
  `fresh`, `replicate`, `replicate_into`, `increment`/`decrement`,
  `destroy`, `is`/`is_not`, `to_array`/`to_json`
- Fillable / guarded mass-assignment with `Attrs` envelope
- 22 attribute casts - booleans, integers, floats, dates, enums,
  hashed, encrypted, JSON, collections, money, datetime with timezone
- Accessors / mutators via `#[suprnova::model]`
- Auto-timestamps (`created_at`, `updated_at`)
- Soft deletes (`deleted_at`) with `force_delete`, `restore`, `trashed`,
  `only_trashed`, `with_trashed`
- Eleven relation kinds - `HasOne`, `HasMany`, `BelongsTo`,
  `BelongsToMany`, `HasOneThrough`, `HasManyThrough`, `MorphOne`,
  `MorphMany`, `MorphTo`, `MorphToMany`, `MorphedByMany`
- Per-family morph enums + morph registry with `APP_KEY_PREVIOUS` rotation
- Eager loading via `.with(...)`, `.with_count(...)`, `.load_missing(...)`
- Correlated EXISTS engine for `has` / `where_has`
- Sixteen lifecycle events (retrieving, retrieved, creating, created,
  updating, updated, saving, saved, deleting, deleted, restoring,
  restored, force-deleting, force-deleted, replicating, trashed)
- `Observer<M>` trait with per-method auto-registration via inventory
- Local scopes via `#[scopes(M)]`, global scopes via `GlobalScope`
- `Collection<M>` Laravel surface - `pluck`, `key_by`, `group_by`,
  `where_in`, `first_where`, `contains_where`, `partition`, etc.
- Three paginators - `paginate` (length-aware), `simple_paginate`,
  `cursor_paginate` - all serializing to Laravel-shape JSON
- `chunk` / `lazy` / `cursor` for bulk-row iteration without OOM
- `lock_for_update` / `shared_lock` row-level locking
- `DB::table(...)` query builder with `DynamicRow` for ad-hoc queries
- `DB::transaction(...)` with savepoints, retry-on-deadlock,
  multi-connection read/write split
- `DB::listen(...)` + `QueryExecuted` / `TransactionBegan` /
  `TransactionCommitted` / `TransactionRolledBack` events
- `Prunable` trait + `model:prune` console command
- `dump` / `dd` query-helper methods
- `#[model(unique_id="...")]` for UUID / ULID primary keys

#### Auth

- `Authenticatable` trait + `EloquentUserProvider<M>`
- `Auth::attempt`, `Auth::login`, `Auth::user`, `Auth::user_or_fail`,
  `Auth::user_as<T>`, `Auth::logout`, `Auth::check`
- Multiple named guards (web session, API token)
- Email verification flow - `EmailVerification`,
  `EnsureEmailVerifiedMiddleware`, signed verification URLs,
  `EmailVerificationMail`
- Password reset flow - `PasswordReset`, throttled tokens,
  `PasswordChangedMail`, `PasswordResetLinkSent` event
- Two-factor TOTP - enroll, verify, recovery codes, replay protection
- Brute-force / login throttle - IP + identifier keyed,
  `LoginThrottleMiddleware`
- Remember-me cookies with stable opaque tokens
- Six auth events - `LoginAttempted`, `LoggedIn`, `Authenticated`,
  `LoggedOut`, `PasswordResetLinkSent`, `EmailVerified`
- Browser sessions backed by the Torii fork at
  `github.com/eas4ai/suprnova-torii-rs`

#### Authorization

- `Gate` facade - `define`, `allows`, `denies`, `authorize`, `any`,
  `none`, `check` (sync + async variants)
- `#[policy(Model)]` macro for policy registration
- Resource-route auto-authorization

#### Payments

- Provider-agnostic five-trait surface - `Checkout`, `Payment`,
  `Subscription`, `CustomerStore`, `WebhookHandler`
- `PaymentProvider` umbrella trait + capability-querying via `as_payment()`
- DB mirror - `customers`, `subscriptions`, `subscription_items`,
  `payments`, `refunds`, `payment_webhook_events` (UNIQUE for idempotency)
- Flow-tagged `SessionPayload` enum (one-shot vs subscription)
- Two reference adapters as workspace crates -
  `suprnova-payments-stripe` (gateway, full `Payment` impl),
  `suprnova-payments-paddle` (Merchant of Record, no `Payment` impl)
- Mock provider for tests

#### Queue, jobs, batches, chains

- `Job` trait - `handle`, `max_tries`, `backoff`, `timeout`,
  `fail_on_timeout`
- `Queue::push`, `Queue::push_later`, `Queue::push_unique`,
  `Queue::push_unique_later`
- Drivers - `sync`, `null`, `redis`, `database`
- `JobMiddleware` trait - six built-in middleware
- Batches and chains - `Queue::batch(jobs).dispatch()`, fluent chain
  builder, cancellation, progress tracking
- Failed-jobs store with replay
- Worker with graceful shutdown, configurable concurrency, panic
  recovery via `catch_unwind`, settlement metrics
- Twelve queue events covering queueing, processing, failure, release,
  worker lifecycle

#### Broadcasting and WebSockets

- `ws!()` macro + `Router::ws` for typed WebSocket endpoints
- `WsSocket` Sink/Stream split
- Auto-restart supervisors via `Supervisor` trait
- `BroadcastHub` with `Channel`, `Private`, `Presence` channels
- JSON-envelope protocol, presence join/leave/here, configurable
  presence TTL with crash recovery
- `Broadcastable` bridge to `EventDispatcher`
- Close-on-no-pong heartbeat with configurable WS_TASKS drain
- Per-route WebSocket middleware
- 1 MiB / 64 KiB safer defaults + `WsConfig::generous()` factory
- Origin policy + 1011 close-on-protocol-violation

#### Notifications and mail

- `Notification` trait + `Notify::send(recipient, notification).await`
- Mailable + Markdown template rendering
- Database / mail / broadcast / web-push channels
- VAPID signing + RFC 8291 ECE payload encryption (via
  `suprnova-web-push`)
- VAPID subject validation, retry-after parsing, 8 KiB rejection-body cap
- Notifiable trait for recipient typing

#### Events

- Typed event dispatcher - `EventFacade::dispatch`,
  `EventFacade::listen<E, L>`, `EventFacade::forget`
- Cancellable saving/updating events (return `EventResult::cancel`)
- Queueable listeners

#### Filesystem

- `Storage::disk("name")` with multi-driver support - local, S3,
  Azure, GCS via OpenDAL
- Move, copy, exists, size, mime, last-modified, prepend/append
- Streaming uploads and downloads

#### Cache

- `Cache::store("name")` + driver registration
- Drivers - memory, redis (with bounded connect-timeout), database, file
- `remember`, `forever`, `tags`, atomic increment/decrement, locks

#### Vector DB

- `VectorDriver` trait with four drivers - in-memory, Qdrant
  (UUID-5 ID mapping), Pinecone (native string IDs), MariaDB native
  `VECTOR(N)` + HNSW indexes (11.7+)
- Cosine / dot / euclidean distance

#### Console binary and CLI

- Per-project `console` binary - Rust analogue of `php artisan`,
  runs user-defined commands via `#[suprnova::console::command]`
- `#[derive(Command)]` for typed arguments
- `suprnova` CLI - `new`, `serve`, `migrate`, `db:sync`,
  `generate-types`, `key:generate`, `make:{controller,middleware,action,error,inertia,migration,task,command}`,
  `db:seed`, `model:prune`
- `--version` flag
- Scaffold templates for backend + API starters across three frontends

#### Feature flags

- `DatabaseEvaluator` with snapshot loading
- `CachedEvaluator` with TTL
- `FeatureMiddleware` extractor
- Admin CRUD surface
- `FeatureSync` trait for sub-second propagation across processes

#### Schedule

- Cron expression parser
- `Schedule::task(...)` with composable predicates
- Single-server locks, overlap prevention, dispatch tracking
- `schedule:run` console command

#### Validation

- `validator` 0.20 integration
- `#[request]` + `#[derive(FormRequest)]` macros
- `#[form_request(max_body_bytes = N)]` per-form size cap
- `#[form_request(custom_hooks)]` opt-out for user-written
  `impl FormRequest`
- Lifecycle hooks - `authorize`, `after_validation`,
  `after_validation_async`

#### Database drivers

- SeaORM-backed support for SQLite, Postgres, MySQL, MariaDB
- URL-based driver detection
- Migration system + `migrate`, `migrate:rollback`, `migrate:status`,
  `migrate:fresh`, `migrate:refresh`

#### HTTP client

- `Http` facade - `get` / `post` / `put` / `patch` / `delete`
  returning a `RequestBuilder`; `.send().await` produces a
  `ClientResponse`
- rustls TLS, 30s default timeout, `suprnova/<version>` user-agent
- `json` / `form` / `body` / `header` / `bearer_token` / `basic_auth`
  / `timeout` chainable methods
- `RequestBuilder::retry(max_attempts, base_backoff)` - exponential
  backoff for transient failures and 5xx; respects `Retry-After`
- `Http::fake(|| async { ... }).await` test guard with
  `fake_response(method, url_substring, status, body)` +
  `assert_sent` / `assert_not_sent`

#### Encryption

- `Crypt` static facade + `EncryptionKey` (`crypto::*`); AES-256-GCM
  with 12-byte random nonces
- `encrypt_string` / `decrypt_string` / `encrypt<T>` / `decrypt<T>`
- `CryptPurpose` AAD binding preventing cross-protocol replay
- `APP_KEY_PREVIOUS` rotation
- `suprnova key:generate` CLI command for minting fresh keys

#### Testing

- `#[suprnova_test]` async test macro
- `TestDatabase::fresh::<Migrator>()` with parallel-safe instances
- `TestContainer::bind` for per-test mocks
- HTTP test helpers - `Test::get`, `Test::post`, JSON / form / multipart
- Queue / Mail / Notification / Event fakes
- `assert_emitted`, `assert_dispatched`, `assert_dispatched_times`

### Changed

- Auth verification and password-reset flows now operate through the
  configured user provider instead of Torii internals.
- Generated apps must implement `get_auth_password`; scaffolded examples
  now fail loudly instead of allowing login to always fail silently.
- The local release gate is wired into `scripts/release.sh`, and the repo
  includes an enforced pre-push hook for fmt, clippy, tests, docs, and
  feature builds.
- Scaffolded dev-port documentation moved to the current backend/frontend
  defaults (`8765` / `5765`), with `dev:tls` and `--with-portless`
  documented.
- `MAIL_FROM` is validated before verification or reset tokens are issued,
  avoiding orphaned auth-flow rows when mail configuration is invalid.

### Fixed

- React scaffold template drift from the released starter.
- Root route groups no longer generate duplicate `//` paths.
- Literal-path redirects now dispatch through the intended routing path.
- Broadcasting fanout tests now handle `track` / `untrack` results.
- The mail log driver emits the rendered text body, so verification and
  password-reset links surface in local development logs.
- Password-reset coverage pins session and remember-me revocation behavior.

### Notes

- **Distribution model**: git-based end-to-end.
  `suprnova = { git = "https://github.com/eas4ai/suprnova.git" }`;
  CLI via `cargo install --git`. Nothing is published to crates.io.


---

<!-- /docs/contributions -->

# Contribution Guide

Suprnova is open-source under the MIT License, and the most valuable
contribution is a **good report**. The project does not accept pull
requests: the framework is maintainer-authored end to end, and every
change lands through the maintainers so the whole surface keeps one
shape. That's a deliberate, permanent posture - not a pre-1.0 phase.

MIT means you never need permission to take the code further yourself:
**fork freely**. A fork that grows in its own direction is a healthy
outcome, not a rivalry.

What that means in practice:

- **Bug reports** - welcome, via
  [GitHub issues](https://github.com/eas4ai/suprnova/issues).
- **Feature requests** - welcome, via issues. Describe the use case, not
  the implementation; there's often a planned shape already (usually the
  Laravel equivalent).
- **Doc bugs** - welcome, via issues. If a chapter says an API exists and
  you can't find it, that's a doc bug - say which chapter and what you
  expected.
- **Security issues** - privately, by email (see below). Never as public
  issues.
- **Pull requests** - not accepted. PRs are closed with a pointer to
  this chapter; open an issue instead so the fix can land upstream, or
  fork and carry the change yourself.

## Filing a bug report that gets fixed fast

The gold standard is a reproduction from a fresh scaffold:

```bash
suprnova new repro-app --frontend vue --no-interaction
# …smallest change that shows the bug…
```

Include:

1. **What you did** - the commands and the code, trimmed to the minimum
2. **What you expected** - one sentence
3. **What happened instead** - the actual output or error, pasted verbatim
4. **Versions** - the framework tag (`suprnova --version`, or the `tag =`
   in your `Cargo.toml`) and your Rust version (`rustc --version`)

A failing test is even better than prose. If you can express the bug as a
test against the framework, paste it into the issue - it will usually
become the regression test the fix lands with.

## Building from source (to investigate a report)

You don't need this to *file* an issue, but reproducing against the
workspace often sharpens a report:

```bash
git clone https://github.com/eas4ai/suprnova.git
cd suprnova
cargo check --workspace          # type-check everything
cargo test --workspace           # run the full suite (~3400 tests)
```

The workspace layout: `framework/` (the `suprnova` crate),
`suprnova-cli/` (the `suprnova` binary), `suprnova-macros/` (proc
macros), `app/` (internal dogfood app), `crates/` (payments and web-push
adapters), and `manual/` (this manual).

## The bar the code is held to

Not contributor rules - but knowing the standard helps you calibrate
reports (a panic from library code, a missing failure-mode test, or an
API that forces `unwrap()` is always report-worthy):

- **Full implementations only.** No TODOs, no partial scaffolds. A fix
  lands with the regression test that pins it.
- **Public-surface code returns `Result`, doesn't panic.** Where a
  Laravel-style infallible name ships, a `try_*` sibling ships with it.
- **No `unsafe` outside environment bootstrap.** The framework has exactly
  two `unsafe` blocks in non-test code, both in
  `config/env.rs::load_dotenv`, both wrapping `std::env::set_var` /
  `remove_var` - which became `unsafe` in edition 2024 - and both carrying
  a SAFETY note for the boot-time single-thread invariant they rely on.
  Everything else is test-only. New `unsafe` anywhere else needs a written
  justification in review, and `unsafe` in a driver, handler, or macro
  expansion will not be accepted.
- **`cargo fmt` and plain clippy are canonical; review and fix warnings without blanket denial.**

See [Error Model](error-model.md) for the full error contract.

## Security

Report security issues privately to
**shawn@eas4ai.com** (the project maintainer). We'll
acknowledge within a few days, work the fix on a private branch, and
coordinate disclosure with you.

Do not file security issues as public GitHub issues until a fix has
shipped.

### Dependency advisories

`cargo audit` runs in the release gate. If an advisory has no fix
available and the vulnerable code is not reachable in a default build, it
can be added to the audit ignore list - but every entry needs three
things, and the gate fails without them:

```toml
# OWNER: name <email>
# EXPIRES: YYYY-MM-DD
"RUSTSEC-XXXX-XXXX",
```

- an **owner**, so the exception belongs to somebody;
- an **expiry**, after which the gate refuses to run until the entry is
  renewed with a stated reason or deleted;
- a **written reachability argument** - which path pulls it in, and why a
  default build does not link it.

Reachability claims are checked, not trusted. If your argument is "this
is behind an off-by-default feature", the release gate resolves the
real dependency trees and asserts the crate is absent from the default
one and present in the opted-in one. An exception whose justification
nothing verifies quietly stops being true the first time someone adds a
dependency.

An ignore is a decision to ship a known issue. It should read like one.

## License

MIT, with attribution to the upstream
[Kit project](https://github.com/dayemsiddiqui/kit) we forked from.


# Getting Started

---

<!-- /docs/introduction -->

# Introduction

Suprnova is a web framework for Rust that gives you Laravel's developer
experience on top of Tokio. You write controllers and Eloquent-style models;
the framework gives you concurrency, type safety, and a single-binary deploy.

```rust
use suprnova::{Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    let id = req.param("id").unwrap_or("0");
    json_response!({ "id": id, "name": "Alice" })
}
```

```rust
use suprnova::{model, Model};

#[model(table = "users")]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

// Then anywhere:
let user = User::find(42).await?;
let admins = User::query().db_where("role", "admin").get().await?;
let alice = User::create(attrs!{ name: "Alice", email: "alice@x.com" }).await?;
```

If you wrote that in Laravel last week, the Rust version above will feel
identical - same chain shape, same method names, same defaults. The
difference is what happens underneath: Tokio instead of FPM, one binary
instead of a PHP runtime, compile-time type checks on every column.

## Why Suprnova exists

Laravel solved the productivity problem for backend web development. The
patterns work. After ten years of refinement, very little gets in your way
when you're building a real product. But PHP's request-per-process model
keeps two things out of reach: cheap long-lived connections (WebSockets,
SSE, server-pushed notifications without polling) and trivial concurrent
I/O inside one request handler.

Rust gives you both for free with Tokio. The problem is that the Rust web
ecosystem makes you build the productivity layer yourself: pick an HTTP
crate, pick an ORM, pick a migration tool, pick a queue, wire it all
together, design your own conventions. Each app reinvents what Laravel
already standardised.

Suprnova is what happens when you copy Laravel's conventions onto Tokio.
You get:

- **Same surface** - `routes!`, `Auth::user()`, `Cache::remember`,
  `Mail::send`, `Queue::push`, `Storage::disk("s3")`, `Notify::send`,
  `Schedule::call`, `Gate::allows`, the Eloquent query builder, soft deletes,
  factories, observers, broadcasting, all of it
- **Different engine** - async-everywhere, long-lived connections as
  first-class citizens, single statically-linked binary, no preforking, no
  opcache, no FPM
- **Type safety** - your models, routes, and event payloads are checked at
  compile time; broken refactors don't reach staging
- **A real frontend story** - Inertia.js bridges to Svelte 5, React 19, or
  Vue 3.5 starters, no separate API to maintain

## Design principles

These are the principles the framework's authors hold themselves to.
They explain why a chapter says what it says.

**1. Parity comes from the Laravel changelog.** When Laravel ships a
feature, Suprnova tracks it. The baseline is Laravel 13.x and every
shipped subsystem has been audited against it. The
[Laravel Parity Map](parity.md) is the explicit feature-by-feature table.

**2. Diverge intentionally where Rust makes things better.** Where Laravel
made a PHP-shaped choice we don't have to make in Rust, Suprnova picks
the Rust-shaped one and says so. The biggest example is concurrency:
WebSockets, broadcasting, background workers, and HTTP/2 server-push
are first-class, not bolted on. Where you'll see this called out in a
chapter, look for **"Why Suprnova diverges"** boxes.

**3. No gatekeeping.** Laravel restricts some features to one backend
(e.g. vector search via Postgres `pgvector`). Suprnova treats backends
as drivers chosen by configuration - `CACHE_DRIVER=redis`,
`MAIL_DRIVER=ses`, `QUEUE_DRIVER=sqs` - and vector search runs on Qdrant,
Pinecone, MariaDB or in memory, each registered with `Vector::register`.
You pick the right tool; we don't pick for you.

**4. Suprnova is the API surface.** Internally we use SeaORM, hyper, Tokio,
serde, sqlx, validator, lettre, and dozens more. None of that should
appear in your code. You depend on `suprnova::*`. We re-export everything
you'll touch - including SeaORM's `Entity`, `Column`, `ActiveModel`,
`QueryFilter`, etc. - under the framework root. The escape hatch
(`use suprnova::sea_orm;`) exists for the rare case the curated surface
doesn't cover, but you should almost never need it.

## What's in the box

A non-exhaustive map. The full list is in [`documentation.md`](documentation.md).

| Area | What ships |
|---|---|
| **HTTP** | `routes!` macro, controllers, middleware, requests, responses, route model binding, signed URLs, resource routing, redirect helpers, CORS, CSRF, idempotency keys, timeout, rate limiting, structured errors with panic recovery |
| **Database** | SeaORM under the hood, multi-driver (Postgres, MySQL, MariaDB, SQLite), migrations, seeders, query builder, transactions with savepoints, multi-connection read/write split |
| **Eloquent** | `#[suprnova::model]` macro, all 11 relation kinds, eager loading, soft deletes, prunable, scopes (local + global), 16 lifecycle events, observers, 31 built-in casts, accessors/mutators, three paginators, chunk/lazy/cursor iteration, collections, replication |
| **Auth** | Framework guards, middleware, providers, and browser sessions; Magnetar-backed password, passkey, magic-link, OAuth, bearer-session, lockout, remember, auth-epoch, and migration engines; provider-backed email verification; framework TOTP compatibility facade; policy macros and gates |
| **Frontend** | Inertia v3 bridge, Svelte 5 / React 19 / Vue 3.5 starter templates, typed `#[derive(InertiaProps)]`, partial reloads, automatic TypeScript type generation |
| **Background** | Queue with memory/sync/redis/database/null drivers, batches, chains, job middleware, failed-job store, `#[command]`/`#[derive(Command)]` console binary, `Task` trait scheduler, `#[workflow]` long-running stateful work, `Supervisor` trait with panic-catch auto-restart, command bus, event dispatcher |
| **Realtime** | `ws!()` macro for typed WebSocket handlers, broadcasting channels (public, private, presence), Redis stream fanout, server-sent events, web push (VAPID) |
| **Cache & Storage** | Memory and Redis cache drivers; atomic operations; tagged cache; cache locks; filesystem with fs/memory/s3/azblob/gcs drivers; path-traversal protection; vector storage with multiple backends |
| **Mail & Notify** | `Mailable` trait, SMTP/SES/Mailgun/Postmark/SendGrid/Resend drivers, RFC 5322 file previews, in-memory/log transports, and `Notifiable` with mail/database/broadcast/webpush channels |
| **Validation & Data** | `#[derive(Validate)]`, form requests, async validation, `#[derive(Data)]` for partial-reload include sets, `#[json_resource]` on `Data` for JSON:API |
| **Payments** | Generic provider surface (gateway/MoR/redirect-flow), reference adapters for Stripe and Paddle, mirror tables with webhook idempotency, Inertia checkout components |
| **Feature flags** | Database evaluator, cached evaluator with TTL, feature middleware, sub-second propagation via sync trait |
| **Testing** | `#[suprnova_test]`, `expect!`, `TestDatabase`, fakes for every external surface (Mail, Notify, Queue, Bus, Events, Storage, Http) |
| **CLI** | `suprnova new` scaffolder (Svelte/React/Vue), `serve` dev runner, `migrate*`, `db:sync`, `db:seed`, `make:*` generators, `model:prune`, console binary per project |

## Production readiness

The framework is production-grade in scope and tested. As of the
current HEAD:

- Every Laravel 13.x surface across the 30 documented domains is shipped
- Every issue raised by independent code review has been resolved
- The workspace test suite passes on every change
- Every public API in `framework/src/lib.rs` is documented - an
  undocumented public item fails the build

As of **v1.0.0** the public API is stable: apps pin a release tag
(`tag = "v<version>"` - the tag is the release; there is no crates.io
publish), and a breaking change lands only behind a version bump whose
[CHANGELOG](changelog.md) section says so.

## Pick a reading path

| You are… | Start with |
|---|---|
| A Laravel developer | [From Laravel](from-laravel.md) |
| A Rust developer who's used Axum/Actix/Rocket | [From Rust Web](from-rust-web.md) |
| Both, or neither, and just want to build | [Installation](installation.md) → [Quickstart](quickstart.md) |
| Looking for a specific feature | [`documentation.md`](documentation.md) (the master TOC) |
| Wondering "does Suprnova have X?" | [Laravel Parity Map](parity.md) |


---

<!-- /docs/from-laravel -->

# From Laravel

If you've shipped Laravel apps, you already know 80% of Suprnova. This
chapter maps your habits to the Rust equivalent so you can get productive
fast. We'll show the patterns you reach for daily, the patterns that change
shape, and the few things Rust gives you for free that PHP can't.

## TL;DR side-by-side

| You wrote in Laravel | You write in Suprnova |
|---|---|
| `composer create laravel/laravel my-app` | `suprnova new my-app --frontend svelte` |
| `php artisan serve` | `suprnova serve` |
| `php artisan migrate` | `suprnova migrate` |
| `php artisan make:controller PostController` | `suprnova make:controller post` |
| `Route::get('/posts/{id}', [PostController::class, 'show'])` | `get!("/posts/{id}", controllers::post::show)` (in `routes!`) |
| `class Post extends Model` | `#[suprnova::model] struct Post { … }` |
| `Post::find($id)` | `Post::find(id).await?` |
| `Post::where('status', 'published')->get()` | `Post::query().db_where("status", "published").get().await?` |
| `Auth::user()` | `Auth::user().await?` |
| `Cache::remember('key', 60, fn() => …)` | `Cache::remember("key", Some(Duration::from_secs(60)), \|\| async { … }).await?` |
| `Queue::push(new SendEmail($user))` | `Queue::push(SendEmail { user_id }).await?` |
| `Mail::to($u)->send(new Welcome($u))` | `Mail::to(&u.email).send(WelcomeMail { user: u }).await?` |
| `Storage::disk('s3')->put($path, $bytes)` | `Storage::disk("s3")?.put(&path, bytes).await?` |
| `Notification::send($u, new Invoice($i))` | `Notify::send(&u, &InvoiceNotification { invoice }).await?` |
| `Gate::allows('update', $post)` | `Gate::allows::<PostPolicy, _>("update", &user, &post).await?` |
| `request()->validate([...])` | `#[handler]` extracts an `#[derive(Data, Validate)]` arg directly |
| `event(new OrderShipped($order))` | `EventFacade::dispatch(OrderShipped { order }).await?` |
| `Bus::dispatch(new ProcessFoo($x))` | `Bus::dispatch(ProcessFoo { x }).await?` |
| `php artisan schedule:list` | `suprnova schedule:list` |
| `php artisan tinker` | (no REPL - write a one-off `cargo run` script or test) |
| `composer require league/csv` | `cargo add csv` |

## The mental model shift

### Async, everywhere

The biggest change: every database call, HTTP call, file I/O, cache call,
queue push - anything that crosses a boundary - is `async` and you call
it with `.await?`. Once you've done it for a few hours, it disappears
into the rhythm. Until then, the compiler will point at every spot you
forgot.

```rust
// Laravel
$user = User::find($id);
$user->subscribe($plan);
Mail::to($user)->send(new Welcome($user));

// Suprnova
let user = User::find(id).await?;
user.subscribe(&plan).await?;
Mail::to(&user.email).send(WelcomeMail { user }).await?;
```

`?` is Rust's "early return on error". A handler returns
`Result<HttpResponse, HttpResponse>` (aliased as `Response`), so a `?`
on a DB error short-circuits into your error converter and the client
gets a proper 500 (or 4xx, depending on the error kind). You almost
never have to write a `try/catch` - `?` does it.

### Compile-time models

Where Eloquent reads your DB schema at runtime, Suprnova reads it at
compile time:

```rust
#[suprnova::model(table = "posts")]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub body: String,
    pub published_at: Option<chrono::DateTime<chrono::Utc>>,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

That's it - that struct IS the Eloquent model. You get
`Post::find`, `Post::query()`, `Post::create`, `post.update(...)`,
`post.delete()`, soft deletes (with `#[model(soft_deletes)]`),
timestamps, observers, the works. The macro generates a SeaORM
`Entity`, `Model`, `ActiveModel`, and `Column` enum, and impls the
Suprnova `Model` trait - but you depend on `Post`, not any of those.

If you rename a column in a migration, the struct doesn't match the
DB schema anymore - and depending on your config, either the compiler
catches it at build time or the type-coerced cast fails on first
query. Either way you find out before staging, not after.

### Single binary

There's no PHP-FPM, no nginx config reading `index.php`, no `composer
install` on deploy. `cargo build --release` gives you one statically
linked binary. `scp` it to a server, `systemd` it, done. Or build a
container - `FROM scratch` works.

We have [deployment recipes](deployment.md) for Railway, Digital
Ocean, and Hetzner. The common shape: build the binary, ship the
binary, set env vars, run.

## Mapping the framework

### Routes

`routes!` plays the role of `routes/web.php` and `routes/api.php`
combined.

```rust
use suprnova::{routes, get, post, put, delete};
use crate::controllers;

routes! {
    get!("/", controllers::home::index).name("home"),

    // Route group with shared prefix + middleware
    group("/admin")
        .middleware(crate::middleware::admin())
        .routes(routes! {
            get!("/users", controllers::admin::users::index).name("admin.users"),
            post!("/users", controllers::admin::users::store),
            put!("/users/{id}", controllers::admin::users::update),
            delete!("/users/{id}", controllers::admin::users::destroy),
        }),

    // Resource routing (Laravel's Route::resource)
    resource!("posts", controllers::post),
}
```

Full reference: [Routing](routing.md). Differences worth knowing:

- Group middleware is **flattened** into each route's middleware list
  at register time (not run as a separate chain layer) - this means
  there's no extra runtime cost for grouping.
- Both Laravel's `{id}` and Rails-style `:id` syntax work; they're
  normalised internally.
- Named routes resolve via `route("posts.show", &[("id", "42")])` and
  there's a signed-URL variant for time-limited links.

### Controllers

A controller is just a free function returning `Response`:

```rust
use suprnova::{Request, Response, json_response, HttpResponse};
use crate::models::Post;

pub async fn show(req: Request) -> Response {
    let id = req.param("id").unwrap_or("0").parse::<i64>()?;
    let post = Post::find_or_fail(id).await?;
    json_response!({ "post": post })
}
```

You can also use the `#[handler]` macro to extract typed args (route
params, query, body, the request itself, container services) at the
signature:

```rust
use suprnova::handler;

#[handler]
pub async fn show(post: Post) -> Response {
    // Route model binding ran automatically; `post` is the loaded row.
    json_response!({ "post": post })
}
```

As in Laravel, the type hint is the signal: every `#[suprnova::model]`
struct implements `RouteBinding`, so `post: Post` binds from `{post}`,
and a type that does not implement it is read as a form request. If the
row doesn't exist, the binding returns a 404 before your code runs - same
behaviour as Laravel's implicit binding. Unlike Laravel, a value that
does not parse as the key's type is a 404 too, and a route whose handler
reads a parameter its path does not declare stops the server at startup.
See [Route model binding](routing.md#route-model-binding).

Action structs (single-method "invokable" controllers, Laravel-style) are
supported too: see [Actions](actions.md).

### Eloquent

The dual-API query builder takes either Laravel names or Rust-idiomatic
names - both work, pick whichever reads cleanly at the call site.

```rust
// Laravel surface
let active = User::query()
    .db_where("status", "active")
    .order_by_desc("created_at")
    .limit(20)
    .get()
    .await?;

// Rust surface (identical result)
let active = User::query()
    .filter("status", "active")
    .order_by_desc("created_at")
    .take(20)
    .get()
    .await?;
```

`db_where` is the Laravel-side name (the bare `where` collides with the
Rust keyword). `filter` is the Rust-idiomatic alias. Both exist; both
do the same thing. For non-equality operators, reach for `db_where_op`
(or its `filter_op` alias): `.db_where_op("status", "!=", "archived")`.
See the [Eloquent reference](eloquent.md) - it's the longest chapter
for a reason, the surface is wide.

### Auth

```rust
use suprnova::{Auth, Credentials};

// In a handler:
let user = Auth::user().await?;   // Option<Arc<dyn Authenticatable>>
let id = user.as_ref().map(|u| u.get_auth_identifier());

// Logging in (e.g. inside your login controller):
let creds = Credentials::password("alice@x.com", "secret");
Auth::attempt(&creds, false).await?;

// Logging out:
Auth::logout().await?;
```

`Auth::attempt` validates credentials through the default stateful guard and
its configured `UserProvider`; this is the path used by the generated
full-stack scaffold. Password reset also supports already verified users through
an explicitly reset-capable provider such as `EloquentUserProvider`; install
Magnetar when reset must serve as atomic first mailbox proof. `Auth::password()`,
`BruteForce`, passkeys, magic links, OAuth, bearer sessions, and Magnetar
session management require the installed Magnetar engine. Email verification
and the compatibility `TwoFactor` facade remain framework-owned. See
[Authentication](authentication.md), [Auth flows](auth-flows.md), and
[OAuth and passwordless login](oauth.md).

### Migrations

`make:migration` generates SeaORM migrators. The shape will look familiar even
if the syntax is new:

```rust
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager.create_table(
            Table::create()
                .table(Alias::new("posts"))
                .if_not_exists()
                .col(ColumnDef::new(Alias::new("id")).big_integer().primary_key().auto_increment())
                .col(ColumnDef::new(Alias::new("title")).string().not_null())
                .col(ColumnDef::new(Alias::new("body")).text().not_null())
                .to_owned()
        ).await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager.drop_table(Table::drop().table(Alias::new("posts")).to_owned()).await
    }
}
```

`suprnova make:migration create_posts_table` scaffolds the file.
`suprnova migrate`, `migrate:rollback`, `migrate:status`, `migrate:fresh`
all do what you'd expect. `suprnova db:sync` runs migrations and
regenerates the SeaORM entities the macro layer compiles against.

Suprnova also has a `Schema` builder that reads like Laravel's `Blueprint`.
The `up` of the posts migration above reads:

```rust
use sea_orm_migration::prelude::*;
use suprnova::schema::Schema;

async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    Schema::create(manager, "posts", |t| {
        t.id();
        t.string("title");
        t.text("body");
        t.timestamps();
    })
    .await
}
```

The function takes the migration's `manager` instead of a global facade, and
`t` plays the part of `$table`. `timestamps()` creates string columns, and
there is no `change()`. See [The schema builder](migrations.md#the-schema-builder)
and [Migrations](migrations.md).

### Queues and scheduling

```rust
use suprnova::{FrameworkError, Job, Queue, async_trait};
use serde::{Deserialize, Serialize};

// Define a job - the data lives on the struct, the contract lives on
// `impl Job`.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct SendWelcomeEmail {
    pub user_id: i64,
}

#[async_trait]
impl Job for SendWelcomeEmail {
    fn job_name() -> &'static str {
        "SendWelcomeEmail"
    }

    async fn handle(self) -> Result<(), FrameworkError> {
        let user = User::find_or_fail(self.user_id).await?;
        Mail::to(&user.email).send(WelcomeMail { user }).await?;
        Ok(())
    }
}

// Push it onto the queue:
Queue::push(SendWelcomeEmail { user_id: user.id }).await?;

// Or with a delay:
Queue::later(
    std::time::Duration::from_secs(60),
    SendWelcomeEmail { user_id },
).await?;
```

Workers run with `cargo run -- queue:work`. Drivers include
memory and sync (in-process, for tests), database, redis, and null.
Batches, chains, unique jobs, retries, backoff, middleware, failed-job
store - all there. See [Queues](queues.md).

Scheduling uses the `Task` trait and the per-project scheduler binary:

```rust
use suprnova::{Task, TaskResult, async_trait};

pub struct DailyDigest;

#[async_trait]
impl Task for DailyDigest {
    async fn handle(&self) -> TaskResult {
        // …
        Ok(())
    }
}

// Register inside bootstrap (e.g. via Schedule::call / .task / .add):
//   schedule.add(schedule.task(DailyDigest).daily().at("03:00").name("daily-digest"));
```

See [Task Scheduling](scheduling.md).

### Mail, notifications, broadcasting

These follow Laravel one-to-one. `Mailable` is a derive macro;
`Notifiable` is a trait on your User model; channels are
`mail`/`database`/`broadcast`/`webpush`; broadcasting supports
public, private, and presence channels. See [Mail](mail.md),
[Notifications](notifications.md), [Broadcasting](broadcasting.md).

### Frontend

There's no Blade. Instead, the frontend is a real SPA via Inertia.js,
and you pass typed props from Rust:

```rust
use suprnova::{inertia_response, InertiaProps, Request, Response};

#[derive(InertiaProps, serde::Serialize)]
pub struct ShowProps {
    pub post: Post,
    pub comments: Vec<Comment>,
}

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id").unwrap_or("0").parse().unwrap_or(0);
    let post = Post::find_or_fail(id).await?;
    let comments = post.comments().get().await?;
    inertia_response!(&req, "Posts/Show", ShowProps { post, comments })
}
```

`Posts/Show` is a Svelte component (or React, or Vue - your starter
picks). TypeScript types for the props are generated automatically from
the `InertiaProps` derive - run `suprnova generate-types` after adding a
new prop struct and the frontend gets typed bindings.

If you've used Inertia in Laravel via `inertia()`, this is the same
thing - just typed end-to-end. See the [Frontend overview](frontend.md).

## Things that change shape

A few things move differently in Suprnova. None of them are blockers,
but they're worth knowing up front.

### No service providers

Laravel has dozens of service providers registering bindings, observers,
view composers, etc. Suprnova has **one** bootstrap function in your
app's `bootstrap.rs`. You register everything there, in order. It's not
elegant but it's transparent - you can see in 30 lines exactly what
your app boots.

```rust
// bootstrap.rs
use std::sync::Arc;

pub async fn register() {
    suprnova::App::bind::<dyn MyService>(Arc::new(MyServiceImpl::new()));
    suprnova::EventFacade::listen::<OrderShipped, _>(Arc::new(SendShipmentNotification)).await;
    crate::observers::register();
}
```

The [Container](container.md) and [Bootstrap](bootstrap.md) chapters
have the detail.

### Configuration is typed

Where Laravel uses `config('app.timezone')` returning whatever-the-array-says,
Suprnova has typed config structs:

```rust
let cfg = suprnova::Config::get::<AppConfig>()?;
let tz = &cfg.timezone;   // &str, not mixed
```

You can register your own typed config sections. See [Configuration](configuration.md).

### No facades-as-aliases

Laravel facades like `DB::` are class-aliases configured in `config/app.php`.
Suprnova facades are real modules at the crate root:

```rust
use suprnova::{Auth, Cache, DB, Event, Gate, Mail, Notify, Queue, Schedule, Storage};
```

Same surface, no global aliasing needed.

### Compile times are real

Rust compile times are not PHP. A clean build of a fresh Suprnova app
takes 1-2 minutes; incremental builds during development are a few
seconds. The dev workflow is the same - `suprnova serve` watches for
changes and rebuilds - but you'll feel it the first time you change a
macro and recompile a downstream crate. Caching pays for itself fast.

### The borrow checker exists

Most controllers and handlers never touch a lifetime annotation - the
framework's signatures hide them. When the borrow checker yells at you,
it's usually because you tried to hold a reference across an `.await`
that crossed a mutex or held a DB transaction across an awaited call
that needed exclusive access. The errors are clear and the fixes are
usually `.clone()` or restructure-into-smaller-scopes.

### No `tinker` REPL

There isn't a REPL. The closest equivalent is a one-off `cargo run`
script in `examples/`, or a `#[suprnova_test]` test that exercises the
thing you're debugging. Most of what you'd do in tinker (poke at a
model, fire a notification, dispatch a job) is a 5-line test.

## Where Laravel chapters land

Quick lookup if you know what you're after but not where it lives:

| Laravel topic | Suprnova chapter |
|---|---|
| Lifecycle | [Request Lifecycle](lifecycle.md) |
| Service Container | [Service Container](container.md) |
| Service Providers | [Application Bootstrap](bootstrap.md) |
| Facades | [Service Container](container.md) |
| Routing | [Routing](routing.md) |
| Middleware | [Middleware](middleware.md) |
| CSRF Protection | [CSRF Protection](csrf.md) |
| Controllers | [Controllers](controllers.md) |
| Requests | [Requests](requests.md) |
| Responses | [Responses](responses.md) |
| URL Generation | [URL Generation](urls.md) |
| Session | [Session](session.md) |
| Validation | [Validation](validation.md) |
| Error Handling | [Error Handling](errors.md) |
| Logging | [Logging](logging.md) |
| Artisan Console | [Console](console.md) + [CLI Reference](cli.md) |
| Broadcasting | [Broadcasting](broadcasting.md) |
| Cache | [Cache](cache.md) |
| Events | [Events](events.md) |
| File Storage | [File Storage](filesystem.md) |
| HTTP Client | [HTTP Client](http-client.md) |
| Localization | [Localization](localization.md) - Fluent `.ftl` catalogs, not PHP arrays |
| Mail | [Mail](mail.md) |
| Notifications | [Notifications](notifications.md) |
| Queues | [Queues](queues.md) |
| Rate Limiting | [Rate Limiting](rate-limiting.md) |
| Task Scheduling | [Task Scheduling](scheduling.md) |
| Authentication | [Authentication](authentication.md) |
| Authorization | [Authorization](authorization.md) |
| Email Verification | [Auth Flows](auth-flows.md) |
| Password Reset | [Auth Flows](auth-flows.md) |
| Encryption | [Encryption](encryption.md) |
| Hashing | [Hashing](hashing.md) |
| Database | [Database](database.md) |
| Query Builder | [Query Builder](queries.md) |
| Pagination | [Pagination](pagination.md) |
| Migrations | [Migrations](migrations.md) |
| Seeding | [Seeding](seeding.md) |
| Eloquent | [Eloquent](eloquent.md) |
| Eloquent: Relationships | [Relationships](eloquent-relationships.md) |
| Eloquent: Collections | [Collections](eloquent-collections.md) |
| Eloquent: Mutators / Casts | [Mutators & Casts](eloquent-mutators.md) |
| Eloquent: API Resources | [API Resources](eloquent-resources.md) |
| Eloquent: Serialization | [Serialization](eloquent-serialization.md) |
| Eloquent: Factories | [Factories](eloquent-factories.md) |
| Testing | [Testing](testing.md) |
| HTTP Tests | [HTTP Tests](http-tests.md) |
| Database Testing | [Database Tests](database-testing.md) |
| Mocking | [Mocking & Fakes](mocking.md) |
| Cashier (Stripe) | [Payments: Stripe](payments-stripe.md) |
| Cashier (Paddle) | [Payments: Paddle](payments-paddle.md) |
| Sanctum / Passport | Magnetar bearer sessions through `BearerTokenMiddleware`; no separate Sanctum or Passport API |
| Horizon | Queue inspection is built into the framework; no Horizon dashboard |
| Telescope / Pulse | not built |

Things Laravel has that Suprnova doesn't:

- Telescope / Pulse dashboards. Basic [observability](observability.md) ships.
- Sanctum / Passport package APIs. Magnetar bearer sessions and
  `BearerTokenMiddleware` provide token authentication, but not Laravel's token
  management surface.
- Horizon's dashboard. Queue inspection is built into the framework.
- Blade - by design; Inertia is the frontend story
- `trans_choice` - [Localization](localization.md) ships, but plurals are
  selected inside the message by CLDR category rather than by the
  `[1,19]`-style integer ranges `trans_choice` takes

## Next

- [Installation](installation.md) - get a project running
- [Quickstart](quickstart.md) - build a tiny app in 5 minutes
- [Routing](routing.md) - the natural next chapter from here

Or jump anywhere via [`documentation.md`](documentation.md).


---

<!-- /docs/from-rust-web -->

# From Rust Web

You've shipped Rust services on Axum, Actix, Rocket, or hand-rolled hyper.
You know the language and the runtime. What does Suprnova actually buy
you?

**The productivity layer.** Routing, controllers, an ORM, migrations,
queues, scheduling, auth, mail, notifications, broadcasting, cache,
storage, validation, and a typed frontend bridge - all wired together,
all using the same conventions, all production-ready. You write
controllers and models; you don't pick the layout.

If you've already built one or two real apps in Axum, you know how much
of that effort was wiring rather than features. Suprnova is the wiring,
done once, opinionated where opinion matters, pluggable where it
doesn't.

## The 30-second TL;DR

```bash
suprnova new myapp --frontend svelte    # scaffolds backend + SPA + Vite
cd myapp
suprnova db:sync                        # runs migrations, regenerates entities
suprnova serve                          # backend + Vite dev server
```

You now have:

- A hyper server with HTTP/1.1 and HTTP/2, WebSocket upgrade, graceful shutdown
- A SeaORM-backed Eloquent layer with relations, eager loading, soft deletes
- Inertia.js bridging Rust → Svelte 5 with typed `#[derive(InertiaProps)]`
- Auth with framework guards and middleware plus Magnetar-backed password,
  passkey, magic-link, OAuth, bearer-session, lockout, and remember engines
- A queue with memory/sync/redis/database/null drivers
- A cron scheduler driven by the `Task` trait
- A console binary per project for `cargo run --bin console <cmd>`
- Cache, storage (fs/s3/azblob/gcs), mail (SMTP + 5 providers: SES, Mailgun, Postmark, SendGrid, Resend), web push
- Broadcasting over a pluggable hub (in memory by default, Redis streams across processes)
- Validation, CSRF, CORS, rate limiting, idempotency, request timeouts, structured errors

And one statically linked binary at the end of `cargo build --release`.

## What's underneath

| Concern | Crate |
|---|---|
| HTTP server | `hyper` + tower-ish middleware (own implementation) |
| Async runtime | `tokio` |
| Router | `matchit` |
| ORM | `sea-orm` (re-exported as `suprnova::sea_orm`) |
| Migrations | `sea-orm-migration` |
| Database drivers | `sqlx` (postgres / mysql / mariadb / sqlite) |
| Serialization | `serde` / `serde_json` |
| Validation | `validator` |
| Browser sessions | Framework `SessionMiddleware` and pluggable session stores |
| Authentication engines | `suprnova-magnetar` behind framework-owned facades |
| Templating | `tera` (for mail bodies; frontend is Inertia) |
| Crypto | `aes-gcm`, `argon2`, `bcrypt` |
| WebSockets | `hyper-tungstenite` |
| Streaming | `redis` streams (broadcasting fanout backend) |
| OAuth | Magnetar provider registry and ceremony engine |
| Tracing | `tracing` + `tracing-subscriber` |

You won't typically reach for any of these directly - Suprnova
re-exports what you need. SeaORM is the deepest passthrough: `Entity`,
`Column`, `ActiveModel`, `ConnectionTrait`, the query builder, the
migration prelude. The escape hatch is `use suprnova::sea_orm;` if you
need something the curated surface doesn't cover.

## What Suprnova adds over raw Axum

Axum is excellent. So is Actix. So is Rocket. The reason Suprnova exists
isn't that those frameworks are bad - it's that every team building a
real product on them ends up re-implementing the same productivity
layer. Suprnova ships that layer:

| Capability | Hand-roll on Axum | In Suprnova |
|---|---|---|
| Routing macros that scale to hundreds of routes | Builder API, can get noisy | `routes!` macro with grouping, prefixes, middleware, naming |
| Route model binding (path value → loaded model) | Custom extractor per type | `#[handler]` binds `post: Post` from `{post}` automatically |
| Eloquent-style chainable query builder | Use SeaORM directly | `Post::query().db_where(...).order_by(...).get().await?` |
| Soft deletes, observers, lifecycle events | Build per-model | `#[model(soft_deletes)] + impl Observer<Post>` |
| Migrations + entity generation | Wire sea-orm-cli + scripts | `suprnova db:sync` runs migrations and regenerates entities |
| Auth (sessions, providers, guards) | Stitch tower-sessions + own logic | `Auth::attempt`, `Auth::user`, `.middleware(AuthMiddleware)` per route |
| Email verification, password reset, 2FA, brute-force | Hand-build all four | All built in, configurable, idempotent |
| Background queue | Pick a driver, write workers | `Queue::push` + `cargo run -- queue:work` |
| Cron scheduling | Write a tokio task with `tokio_cron_scheduler` | `impl Task` + `Schedule::task(...).daily().at("03:00")` |
| Inertia bridge | Build extractors + a JS adapter | `inertia_response!(&req, "Page", props)` |
| Typed frontend props (Rust → TS) | Write a generator | `#[derive(InertiaProps)]` + `suprnova generate-types` |
| Broadcasting (public / private / presence channels) | Wire a streaming backend + auth | `BroadcastHub` + `Channel`/`PrivateChannel`/`PresenceChannel` traits |
| Mail with multiple providers | Pick one, write your own abstraction | `Mail::driver("ses")` etc., uniform `Mailable` API |
| WebPush | Read the spec, build a notifier | `WebPushChannel` ships, VAPID baked in |
| Validation + form requests | Use `validator` + custom extractor | `#[derive(Data, Validate)]` form requests, async validation |
| JSON:API resources | Hand-format responses | `#[derive(Data)]` + `#[json_resource]` |
| Rate limiting with fail-open/closed policy | Build it | `RateLimiter` + `BackendErrorPolicy` |
| Idempotency keys | Build it | `Idempotency::remember(key, ttl, body)` with Stripe-style replay |
| CSRF (with Laravel-style glob exclusions) | Build it | `CsrfMiddleware` with `except` + `except_method` |
| Structured errors with sanitised 5xx | Build it | `FrameworkError` / `HttpError` trait, panic recovery |
| Container with task-local → thread-local → global scopes | Write your own | `App::bind` / `singleton` / `factory` with proper isolation |
| Health endpoint, request id, structured logging | Glue together | All on by default |

The trade-off is opinions: Suprnova picks a layout, picks a default
driver, picks a naming convention. You can deviate (drivers are pluggable,
config is overridable, the container lets you swap services), but the
defaults are designed to be the right choice for "build a product
quickly".

## Familiar Rust patterns

You'll recognise the shapes:

```rust
// A handler returns `Result<HttpResponse, HttpResponse>` (aliased Response).
pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id").unwrap_or("0").parse().unwrap_or(0);
    let post = Post::find_or_fail(id).await?;
    Ok(HttpResponse::json(serde_json::json!({ "post": post })))
}

// Middleware is a trait, not a closure:
#[async_trait]
impl Middleware for RequireAdmin {
    async fn handle(&self, req: Request, next: Next) -> Response {
        let user = Auth::user_as::<User>().await?
            .ok_or_else(|| HttpResponse::text("Unauthorized").status(401))?;
        if !user.is_admin {
            return Err(HttpResponse::text("Forbidden").status(403));
        }
        next(req).await
    }
}

// Background work is the `Job` trait - `handle(self)` runs the job:
#[async_trait]
impl Job for SendWelcomeEmail {
    fn job_name() -> &'static str { "SendWelcomeEmail" }

    async fn handle(self) -> Result<(), FrameworkError> {
        let user = User::find_or_fail(self.user_id).await?;
        Mail::to(&user.email).send(WelcomeMail { user }).await?;
        Ok(())
    }
}
```

If you're used to Tower middleware: Suprnova middleware is conceptually
the same (a wrapper around `next`), but uses an own trait (not Tower's
`Service`) because tower's combinator types get nasty when you start
nesting application-specific extractors. The shape is simpler; the
mental model is the same.

If you've used Axum's extractor pattern: Suprnova's `#[handler]` macro
plays the same role, but resolves through the service container rather
than via traits, which lets it inject app services as well as request
data. Route model binding (`post: Post` from `{post}`) is built in.

If you've used `sqlx` directly: Suprnova's ORM sits over SeaORM, which
sits over sqlx. You can drop to raw SQL via `DB::select(...)` /
`DB::select_one(...)` or use `DB::table("name")` for chainable dynamic
queries; you can drop straight to SeaORM for things the Eloquent
surface doesn't cover (e.g. raw `Statement` queries with custom result
mapping). The [Eloquent chapter](eloquent.md) covers the escape hatches.

## What's the productivity delta?

Pick a feature you've built before in raw Axum. Suprnova ships it as a
chapter:

- **"I built an auth system once and it took two weeks."** →
  [Authentication](authentication.md) + [Auth Flows](auth-flows.md). Set
  the migration, configure the guard, you're done.
- **"I wrote my own queue worker with retry/backoff."** →
  [Queues](queues.md). `Queue::push` + `cargo run -- queue:work`.
- **"I wired WebSockets with hyper-tungstenite once."** →
  [WebSockets](websockets.md). The `ws!()` macro types the handler;
  the upgrade, ping/pong heartbeat, close-frame handshake, and
  back-pressure are taken care of.
- **"I built an Inertia adapter from scratch."** →
  [Inertia](frontend.md). `inertia_response!(&req, "Page", props)`, with
  `InertiaProps` generating the TS types.
- **"I built a per-tenant rate limiter."** →
  [Rate Limiting](rate-limiting.md). Configurable key, configurable
  fail-open vs fail-closed policy, fail-closed returns 503.
- **"I implemented Stripe webhook signature verification + replay protection."** →
  [Payments: Stripe](payments-stripe.md). Built into the adapter,
  webhooks go into a mirror table with UNIQUE idempotency.

What you'd build by hand in two weeks, you import in one line.

## What you'll still recognise as "yours"

A few things stay close to raw Rust because the language gives you
something better than a framework abstraction:

- **Concurrency primitives.** `tokio::spawn`, `Arc`, `Mutex`, channels -
  use them. The framework doesn't wrap them.
- **Error types.** You define your domain errors. Implement the
  `HttpError` trait on them to get a proper status code + message in
  the wire response. The framework's `FrameworkError` and `AppError`
  are escape hatches for cross-cutting + ad-hoc errors respectively.
- **Custom drivers.** Cache, queue, mail, broadcasting, vector, payments -
  every "driver registry" subsystem accepts custom drivers. Implement
  the trait, register it in `bootstrap.rs`, done.
- **Raw SQL when you want it.** `DB::select(...)`, `DB::table(...).get()`
  for dynamic rows, or drop fully to SeaORM. The ORM gets out of the way.
- **Your own tower middleware?** Suprnova doesn't ship a Tower
  adapter - middleware here is `impl Middleware`, not `tower::Service`.
  If you need to bring a Tower-only crate, you'd adapt it by hand.
  In practice, the built-in middleware system covers almost everything
  you'd reach for. See [Middleware](middleware.md).

## What you give up

Honesty matters more than marketing:

- **Conventions.** Models live here, controllers there, migrations
  there, observers there. The scaffolder picks. You can fight it; you
  probably shouldn't. The conventions are Laravel's, audited and
  battle-tested.
- **Some flexibility in how the request flows.** The middleware chain
  has a fixed outermost order (request-id → globals → route middleware
  → handler). You can insert middleware anywhere in that, but you
  can't move the request-id or panic-recovery layers - they're
  invariants.
- **The PHP-shaped corners.** Where Laravel does something because PHP,
  Suprnova does the Rust-shaped thing instead - but we tell you when.
  Look for **"Why Suprnova diverges"** callouts in chapters.

## Why "Laravel-inspired" should matter to you even if you've never written PHP

The Rust web ecosystem is roughly where the PHP one was around 2009. The
crates exist; the patterns don't. Suprnova ports an extremely refined
set of patterns from a framework that has had 10+ years of production
pressure shaping it. You get patterns that already survived contact with
reality.

The cost is that Suprnova *is opinionated*. If you want a minimal
"pick-your-own-everything" framework, Axum is right there and it's
excellent. If you want a "framework that decides things so you can
focus on the product", that's Suprnova.

## Next steps

- [Installation](installation.md) - `suprnova new`, what gets scaffolded
- [Quickstart](quickstart.md) - build a tiny app in 5 minutes
- [Request Lifecycle](lifecycle.md) - how a request flows, what runs where
- [Service Container](container.md) - how services are bound and resolved
- [Eloquent](eloquent.md) - the longest chapter; the surface is wide

Or jump anywhere via [`documentation.md`](documentation.md).


---

<!-- /docs/installation -->

# Installation

This chapter gets you from "no Suprnova on this machine" to a running
scaffolded project. If you're already there, jump to the
[Quickstart](quickstart.md).

## Requirements

- **Rust 1.94.0+** for current `main` (the workspace uses the 2024 edition).
  Tagged releases have the same Rust 1.94.0 floor. Install via
  [rustup](https://rustup.rs/):
  ```bash
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```
- **Node.js 20+** and **npm** (or pnpm/yarn/bun) for the frontend
  toolchain. Suprnova uses Vite 8 and your starter ships TypeScript +
  Tailwind v4. Install via [nodejs.org](https://nodejs.org/) or your
  package manager.
- **A database client library** that matches the driver you want to use:
  - SQLite - no extras needed; sqlite is bundled
  - PostgreSQL - `libpq` on most systems (often pre-installed)
  - MySQL or MariaDB - `libmariadb` / `libmysqlclient` on most systems

You don't have to choose a database now. The default scaffolder picks
SQLite so a fresh app runs with zero setup.

Current `main` uses SeaORM 2.0, SeaQuery 1.0, and SQLx 0.9. Applications that
call SeaORM directly must import `ExprTrait` for SeaQuery expression methods
and call explicit `*_raw` connection methods for prebuilt `Statement` values.
The dependency upgrade requires no application data migration.

## Install the CLI

Suprnova is distributed as a Cargo project, and the CLI installer pulls
the framework from git rather than crates.io (see [Distribution
model](#distribution-model) below). The command installs the current tagged release:

```bash
cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.6.2 suprnova-cli
```

This compiles the `suprnova` binary and drops it into `~/.cargo/bin`.
Confirm it worked:

```bash
suprnova --version
```

You should see `suprnova 0.x.x`.

If `suprnova` isn't found, your `~/.cargo/bin` isn't on `PATH`. Add this
to your shell config:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

## Create a project

`suprnova new` scaffolds a complete project - backend + chosen frontend + Vite config + auth migrations + sample routes. It's interactive by
default:

```bash
suprnova new my-app
```

The wizard asks for, in order:

1. **Project name** - skipped when you pass it as the argument (`my-app`)
2. **Description** - used in `Cargo.toml`
3. **Author** - used in `Cargo.toml`; defaults to your git `user.name`
4. **Frontend framework** - one of `svelte` (default), `react`, `vue`

If you want to skip the prompts (CI, scripted setup), pass
`--no-interaction` and pick a frontend explicitly:

```bash
suprnova new my-app --frontend svelte --no-interaction
```

`--no-interaction` accepts the defaults for description ("A web
application built with Suprnova") and author (empty). To set those,
edit the generated `Cargo.toml` after scaffolding.

The three frontend choices each ship their own runes-on/Svelte-5,
React-19, or Vue-3.5 starter. All three use Inertia v3 + Vite 8 +
Tailwind v4 and pre-wire a Login/Register/Dashboard flow with
session-based auth.

Suprnova also ships a slimmer **API starter** for service backends with
no SPA:

```bash
suprnova new my-api --api
```

The API starter has no frontend or Inertia layer. It initializes Magnetar on
the application database, installs `BearerTokenMiddleware`, and scaffolds
password registration and login against `app_users`.

## First run

```bash
cd my-app

# Run migrations (users, sessions, etc.)
suprnova migrate

# Install frontend dependencies
npm install              # in the project root

# Start the backend + Vite together
suprnova serve
```

`suprnova serve` runs the backend on `http://127.0.0.1:8765` and Vite
on `http://127.0.0.1:5765`. Open the backend URL: the page it serves
loads its scripts and styles from the Vite dev server, so you never
need to visit Vite yourself.

You should see the welcome page. Then visit `/register` to make an
account and `/login` to log in.

## What got scaffolded

```
my-app/
├── Cargo.toml          # crate manifest, two [[bin]] targets
├── .env                # local config (DB URL, app key, ports)
├── .env.example        # template for ops/CI
├── .gitignore
├── cmd/
│   └── main.rs         # the binary entry; calls Application::new().run()
├── src/
│   ├── lib.rs          # module wiring
│   ├── bootstrap.rs    # service registration (the Suprnova analogue of providers)
│   ├── routes.rs       # the routes! macro tree
│   ├── bin/
│   │   └── console.rs  # `cargo run --bin console <subcommand>`
│   ├── actions/        # single-method invokable controllers
│   ├── commands/       # `#[command]`-annotated handlers
│   ├── config/         # typed config sections (database, mail)
│   ├── controllers/    # home, auth, dashboard
│   │   ├── notes.rs    # notes list, detail and creation
│   │   └── profile.rs  # display-name updates
│   ├── middleware/     # logging, authenticate
│   ├── migrations/     # SeaORM migrators (users, sessions, etc.)
│   │   └── m20240101_000005_create_notes_table.rs
│   ├── props/          # typed flash data
│   └── models/         # `#[suprnova::model]` structs (user)
│       └── note.rs     # notes owned by a user
├── templates/
│   └── app.html        # the Inertia root document (`AppDocument` in bootstrap.rs)
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── src/
│       ├── main.{tsx,ts}
│       ├── app.css
│       ├── layouts/    # persistent application and guest layouts
│       ├── components/ # shared navigation, titles and flash toasts
│       ├── pages/
│       │   ├── Home, Dashboard
│       │   ├── Notes/  # Index and Show
│       │   └── auth/{Login,Register}
│       └── types/
│           └── inertia-props.ts
└── public/
    └── assets/         # Vite production build output
```

The full directory tour is in [Directory Structure](structure.md).

## Updating the CLI

The CLI lives in your `~/.cargo/bin`. To update to the latest:

```bash
cargo install --force --git https://github.com/eas4ai/suprnova.git --tag v4.6.2 suprnova-cli
```

`--force` makes Cargo overwrite the existing binary.

## Updating your app's framework version

A scaffolded app depends on the `suprnova` framework crate via a git
dependency in `Cargo.toml`:

```toml
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2" }
```

A CLI pins the release tag when that tag names the commit the CLI was
built from. The build reads the tag from its own checkout, or, when the
checkout has no such tag, from the checkout's `origin` if `origin` is a
repository on the same machine. That covers the install command above:
`cargo install --git ... --tag v<version>` builds from a Cargo checkout
that carries no tags, so the build reads the release tag from Cargo's git
database on disk, without the network. Any other CLI pins its commit
instead, as `rev = "<commit hash>"`:

- A CLI built from `main` between two releases pins its commit because its
  templates can use framework API that the last release tag does not have
  yet. The scaffold needs the framework from the same commit.
- A CLI built from a checkout where git can read no release tag offline,
  such as a shallow clone or a clone of `main` made without tags, pins its
  commit even at the release. The release commit's hash names the same
  source as the tag.

Replace `rev` with a release `tag` when you move to a release.

To pull the latest framework changes:

```bash
cargo update -p suprnova
```

The git dependency tracks the named release tag. Update the tag in
`Cargo.toml`, then run `cargo update -p suprnova`; your `Cargo.lock` records the
exact commit it resolved, so builds stay reproducible between updates -
there's no need to hand-pin a `rev` in `Cargo.toml`.

## Distribution model

Suprnova is distributed through git, not crates.io - both the framework
and the CLI install from GitHub. Each version is published as a tagged
GitHub Release (e.g. `v2.1.0`), and the tag is what your app depends on:
a scaffolded `Cargo.toml` pins `tag = "v4.6.2"` when the CLI was installed
from that release, or the commit the CLI was built from otherwise (see
above), and `Cargo.lock` records the exact commit, so builds are
reproducible until you choose to move. Updating is deliberate, never incidental - bump the tag and
run `cargo update -p suprnova`; the section on updating your app's
framework version walks through it.

## Editor setup

A few VS Code extensions make the experience smoother:

- **rust-analyzer** - the Rust language server
- **Svelte for VS Code** (or React/Vue if you chose those)
- **Tailwind CSS IntelliSense**
- **Even Better TOML**

`rust-analyzer` will index the project on first open; expect 1-2
minutes the first time, then incremental.

## Next

- [Quickstart](quickstart.md) - build a tiny app in 5 minutes
- [Directory Structure](structure.md) - what's in each file the
  scaffolder generated
- [Configuration](configuration.md) - the `.env` and typed config story
- [Routing](routing.md) - add your first route


---

<!-- /docs/quickstart -->

# Quickstart

We're going to build a tiny "links" app - a single page that lists
URLs with titles, plus an API endpoint to post new ones. It exercises
routing, controllers, an Eloquent model, a migration, and an Inertia
page. If you can build this, you can build anything Suprnova does.

This assumes you've followed [Installation](installation.md) and have
the `suprnova` CLI on your `PATH`.

## 1. Scaffold

```bash
suprnova new links --frontend svelte --no-interaction
cd links
suprnova migrate
npm install
suprnova serve
```

Open `http://127.0.0.1:8765`. You should see the welcome page. Stop
the server (`Ctrl+C`) - we're going to add a feature.

## 2. Create the model and migration

There is no dedicated `make:model` command - models are regenerated
from the schema by `db:sync --regenerate-models` once the migration
runs. Start with the migration:

```bash
suprnova make:migration create_links_table
```

Open the new migration file under `src/migrations/`:

```rust
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager.create_table(
            Table::create()
                .table(Alias::new("links"))
                .if_not_exists()
                .col(ColumnDef::new(Alias::new("id"))
                    .big_integer().primary_key().auto_increment().not_null())
                .col(ColumnDef::new(Alias::new("title")).string().not_null())
                .col(ColumnDef::new(Alias::new("url")).string().not_null())
                .col(ColumnDef::new(Alias::new("created_at"))
                    .timestamp_with_time_zone().not_null().default(Expr::current_timestamp()))
                .col(ColumnDef::new(Alias::new("updated_at"))
                    .timestamp_with_time_zone().not_null().default(Expr::current_timestamp()))
                .to_owned()
        ).await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager.drop_table(Table::drop().table(Alias::new("links")).to_owned()).await
    }
}
```

Create the model by hand at `src/models/link.rs`:

```rust
use chrono::{DateTime, Utc};
use suprnova::{model, Model};

#[model(table = "links")]
pub struct Link {
    pub id: i64,
    pub title: String,
    pub url: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
```

Add `pub mod link;` to `src/models/mod.rs` so the new module is
reachable, then apply the migration and regenerate entities:

```bash
suprnova db:sync
```

`db:sync` runs pending migrations and regenerates SeaORM entities. The
combined step is the dev-loop default; in production you use plain
`suprnova migrate`.

## 3. Add a controller

`src/controllers/link.rs`:

```rust
use suprnova::{
    Data, InertiaProps, Model, Request, Response,
    handler, inertia_response, json_response,
};
use validator::Validate;
use crate::models::Link;

#[derive(InertiaProps)]
pub struct IndexProps {
    pub links: Vec<Link>,
}

pub async fn index(req: Request) -> Response {
    let links = Link::query().order_by_desc("created_at").get().await?;
    inertia_response!(&req, "Links/Index", IndexProps { links: links.into_vec() })
}

#[derive(Data, Validate)]
pub struct CreateLink {
    #[validate(length(min = 1, max = 200))]
    pub title: String,
    #[validate(url)]
    pub url: String,
}

#[handler]
pub async fn store(input: CreateLink) -> Response {
    let link = Link::create(suprnova::attrs! {
        title: input.title,
        url: input.url,
    }).await?;
    json_response!({ "link": link })
}
```

Register the controller module in `src/controllers/mod.rs`:

```rust
pub mod link;
```

## 4. Wire the routes

`src/routes.rs`:

```rust
use suprnova::{get, post, routes};
use crate::controllers;

routes! {
    get!("/", controllers::home::index).name("home"),

    // Links
    get!("/links", controllers::link::index).name("links.index"),
    post!("/links", controllers::link::store).name("links.store"),
}
```

## 5. Build the Inertia page

Create `frontend/src/pages/Links/Index.svelte` (for the Svelte starter):

```svelte
<script lang="ts">
    import { router } from '@inertiajs/svelte';

    let { links } = $props<{
        links: { id: number; title: string; url: string }[]
    }>();

    let title = $state('');
    let url = $state('');

    function submit(e: SubmitEvent) {
        e.preventDefault();
        router.post('/links', { title, url }, {
            onSuccess: () => { title = ''; url = ''; },
        });
    }
</script>

<div class="mx-auto max-w-2xl p-8">
    <h1 class="text-2xl font-bold">Links</h1>

    <form onsubmit={submit} class="mt-4 flex gap-2">
        <input bind:value={title} placeholder="Title"
               class="flex-1 rounded border p-2" />
        <input bind:value={url} placeholder="https://..."
               class="flex-1 rounded border p-2" />
        <button class="rounded bg-blue-600 px-4 py-2 text-white">Add</button>
    </form>

    <ul class="mt-8 space-y-2">
        {#each links as link}
            <li class="rounded border p-3">
                <a href={link.url} target="_blank"
                   class="text-blue-600 hover:underline">
                    {link.title}
                </a>
                <p class="text-sm text-gray-500">{link.url}</p>
            </li>
        {/each}
    </ul>
</div>
```

(Equivalent React and Vue starters give you the same shape with their
own templating - the Inertia bridge is identical.)

## 6. See it work

```bash
suprnova serve
```

Visit `http://127.0.0.1:8765/links`. Add a couple of links via the form.
They post to `/links`, the controller writes to the `links` table, and
the Inertia request re-fetches the index props. No JSON marshalling
glue - `InertiaProps` derived the wire format for you.

## What just happened

You touched eight files. Here's what they actually mean:

| File | Layer | Role |
|---|---|---|
| `src/migrations/m_create_links_table.rs` | Schema | Defines the `links` table |
| `src/models/link.rs` | Domain | One struct, four lines, full Eloquent model |
| `src/controllers/link.rs` | HTTP | Two handlers: `index` (page) and `store` (create) |
| `src/routes.rs` | Router | Wires URLs to handlers via `routes!` |
| `src/controllers/mod.rs` | Wiring | Re-exports the new controller module |
| `frontend/src/pages/Links/Index.svelte` | Frontend | The page Inertia renders |
| (existing) `bootstrap.rs` | Boot | Where you'd register observers/services for this feature |
| (existing) `.env` | Config | DB URL, ports, secrets |

That's the standard rhythm: migration → model → controller →
route → frontend page. Every feature, no matter how big, decomposes
into those steps.

## What to read next

You've done a full vertical slice. The next things you'll reach for:

- [Routing](routing.md) - grouping, middleware, named routes, signed
  URLs, resource routing
- [Validation](validation.md) - what `#[derive(Validate)]` gives you
- [Eloquent](eloquent.md) - relationships, scopes, observers, soft
  deletes, the full query builder surface
- [Inertia + Frontend](frontend.md) - partial reloads, typed props,
  TypeScript type generation
- [Authentication](authentication.md) - the auth scaffolding the
  starter shipped
- [Console](console.md) - `cargo run --bin console <subcommand>` and
  writing your own commands

Or browse [`documentation.md`](documentation.md) for the full TOC.


---

<!-- /docs/development -->

# Development

The day-to-day Suprnova loop is one command: `suprnova serve`. It runs
the Rust backend, the Vite frontend, and a TypeScript-types regenerator
in a single process, each watching the right files. This chapter covers
the dev server, how the hot-reload pieces fit together, and the
commands you'll reach for daily. For first-time setup see
[Installation](installation.md); for the directory tour see
[Directory Structure](structure.md).

## The dev server

From a scaffolded project's root:

```bash
suprnova serve
```

The CLI prints two URLs and then a continuous stream of prefixed
output from each child process:

```
Backend  http://127.0.0.1:8765
Frontend http://127.0.0.1:5765

[backend]  Compiling links v0.1.0
[backend]  Finished `dev` profile [unoptimized + debuginfo] target(s) in 4.21s
[backend]  Running `target/debug/links`
[frontend] VITE v6.0.1  ready in 312 ms
[frontend]   ➜  Local:   http://localhost:5765/
[types]    Watching for Rust file changes to regenerate types
```

You hit the backend URL (`127.0.0.1:8765`). Vite serves your JS/CSS
through Inertia's dev integration - you don't visit `:5765` directly.
Press `Ctrl+C` once and the CLI shuts both children down cleanly.

### Flags

| Flag | Default | What it does |
|---|---|---|
| `-p`, `--port <N>` | `8765` | Backend port |
| `--frontend-port <N>` | `5765` | Vite port |
| `--backend-only` | off | Skip the Vite child (API-only work) |
| `--frontend-only` | off | Skip the backend child (component work against a running backend elsewhere) |
| `--skip-types` | off | Skip the TypeScript-type generator + its watcher |

The same ports can be set in `.env` via `SERVER_PORT` and `VITE_PORT`.
A flag on the command line wins over `.env`.

### What it pre-flights

Before spawning anything, `suprnova serve`:

1. **Checks you're in a project.** Aborts with a clear error if there's
   no `Cargo.toml` (or no `frontend/` when running the frontend).
2. **Generates TypeScript types once.** Scans `src/` for
   `#[derive(InertiaProps)]` and writes
   `frontend/src/types/inertia-props.ts`. Skipped by `--skip-types` or
   `--frontend-only`.
3. **Installs `cargo-watch` if missing.** First run on a new machine
   runs `cargo install cargo-watch` for you, then continues.
4. **Runs `npm install` if `frontend/node_modules` is missing.** No
   manual install step on a fresh clone.

## Hot reload

Three watchers run concurrently inside `suprnova serve`:

- **`cargo watch -x 'run --bin <pkg>'`** drives the backend. Any `.rs`
  change under the project triggers a recompile and an in-process
  restart. Compile errors print to the `[backend]` stream and the
  previous binary stays up until the next successful build.
- **Vite** drives the frontend. Component, style, and asset edits
  hot-module-replace into the open browser tab without a full reload.
- **`notify`-based type watcher** reruns the InertiaProps scanner
  whenever a `.rs` file changes. It debounces at 500ms so a burst of
  saves regenerates `inertia-props.ts` once. Output appears under the
  `[types]` prefix.

That third one is the bit you don't have to think about: rename a field
on a `#[derive(InertiaProps)]` struct and the matching TypeScript
interface follows on the next save. The Svelte/React/Vue page picks
the new type up immediately. No `suprnova generate-types` invocation
needed during normal dev.

### Why Suprnova diverges

Most Rust web stacks make hot reload your problem - pick your own
file watcher, write your own restart wrapper, run Vite in a separate
terminal. Most Laravel stacks make TypeScript types your problem -
declare them in two places (PHP and TS) and keep them in sync.
`suprnova serve` runs both watchers, plus the type generator that
keeps your frontend types honest, as one supervised process. The
Tokio runtime makes "many things at once" cheap enough that a dev
loop can spend it freely.

## Day-to-day commands

The handful you'll run hourly:

```bash
suprnova serve                    # start dev (backend + Vite + type watcher)
suprnova make:controller orders   # scaffold a controller
suprnova make:migration add_idx   # scaffold a migration
suprnova db:sync                  # run migrations, regenerate SeaORM entities
suprnova migrate:status           # see what's applied
suprnova migrate:fresh            # drop tables + re-run from scratch
suprnova key:generate --show      # rotate APP_KEY
cargo run --bin console <cmd>     # any `#[command]`-annotated console handler
cargo test                        # run the test suite
```

`db:sync` is the dev shortcut for "migration + entity regen in one
step." In production you use plain `suprnova migrate` because you
don't want regeneration to happen on a release box. The full generator
surface is in [Code Generators](cli-generators.md) and the migration
verbs are in [Migrations](migrations.md).

## Debugging

### Logging

Suprnova uses `tracing` end-to-end. Filter what gets printed with
`LOG_LEVEL` (the same syntax as `tracing-subscriber`'s `EnvFilter`):

```bash
# Verbose framework output
LOG_LEVEL=debug suprnova serve

# Quiet hyper but verbose your crate
LOG_LEVEL=info,my_app=debug,hyper=warn suprnova serve
```

Output format is controlled by `LOG_FORMAT` (`pretty` for human-readable,
`json` for machine-parseable). The dev default is `pretty`. See
[Observability](observability.md) for the full logging surface.

### SQL queries

Turn on per-query logging with one env var:

```env
DB_LOGGING=true
```

This routes every SeaORM query through `tracing` at `info` so you can
see exactly what's executing. Leave it off in production unless you're
chasing a specific slow query - the volume gets noisy fast.

### Backtraces

Standard Rust:

```bash
RUST_BACKTRACE=1 suprnova serve
```

A panic in a handler is caught and turned into a structured 500
response; the backtrace lands in your logs without taking the server
down. See [Error Model](error-model.md) for how that contract works.

## Tests in the loop

```bash
cargo test                        # whole workspace
cargo test -p my_app              # just your app crate
cargo test some_test_name         # filter by name
cargo test -- --nocapture         # show println!/tracing output
```

Test execution is plain Cargo. The framework-side helpers
(`#[suprnova_test]`, `TestDatabase`, `expect!`, fakes for Mail/Queue/
Storage/etc.) are documented in [Testing](testing.md) and
[Database Testing](database-testing.md). They run under the same
`cargo test` you already know.

## Working with the SSR worker

If your app uses Inertia server-side rendering, you'll want the SSR
worker alongside `suprnova serve` during dev:

```bash
# Terminal 1
suprnova serve

# Terminal 2
suprnova ssr:start
```

`suprnova ssr:start` runs the application binary's `ssr:start`, which
reads the Inertia configuration your app installed and runs the bundled
SSR worker under Node, Bun, or Deno (`--runtime`), after it stops a worker
that is still running. `suprnova ssr:check` and `suprnova ssr:stop` run
the application binary's `ssr:check`, which checks that a running worker
answers its health check, and its `ssr:stop`, which stops it - see
[Console](console.md#ssr-commands). The SSR setup is documented under the
frontend chapter - see [Frontend](frontend.md).

## When something looks wrong

A short triage list for the most common dev-loop hiccups:

- **Port already in use.** Another `suprnova serve` is still up, or a
  prior backend wedged. `lsof -i :8765` to find it, or just pass
  `--port 8001`.
- **`cargo-watch` keeps recompiling.** Some editor is rewriting files
  on save (formatters, linters with autofix). Disable on-save format
  for the project, or list the paths it rewrites in a `.ignore` file at
  the project root (gitignore syntax). cargo-watch always honors
  `.ignore`; `suprnova serve` turns off `.gitignore` filtering when the
  project has a `.env`, so `.gitignore` alone may not be enough.
- **TypeScript types not updating.** Either `--skip-types` was passed,
  or the watcher tripped over a `.rs` parse error. Look at the
  `[types]` lines - it prints a warning and continues rather than
  failing the whole serve.
- **Vite errors but the backend is fine.** Run `npm install` in
  `frontend/` once (the CLI does this on first serve, but if you
  blow away `node_modules` it won't redo it until that directory is
  missing again on a fresh start).

Anything else, the [Errors](errors.md) chapter covers deeper triage
patterns.

## Next

- [Installation](installation.md) - first-time setup of the CLI and a
  project
- [Quickstart](quickstart.md) - build a tiny app end-to-end
- [Directory Structure](structure.md) - what each directory holds
- [Code Generators](cli-generators.md) - every `make:*` command
- [Testing](testing.md) - `#[suprnova_test]`, fakes, and the test
  database


---

<!-- /docs/ai-assisted-development -->

# AI-Assisted Development

A coding assistant such as Claude Code, Codex, Cursor or GitHub Copilot
writes better Suprnova code when it reads the Suprnova manual instead of
guessing from Laravel or from older Rust web frameworks. This chapter
shows you how to give an assistant the manual as plain text, how to
install the Suprnova language server, and how to point an assistant at
your project.

## Read the manual as Markdown

[suprnova.app](https://suprnova.app) serves every manual page twice: as
HTML for you, and as its Markdown source for an assistant. Add `.md` to
a page's address to get the source, with no page layout and no scripts:

```bash
curl https://suprnova.app/docs/routing.md
```

The HTML page names its Markdown form in a
`<link rel="alternate" type="text/markdown">` tag, so an assistant that
fetches the HTML can find it.

Two more files follow the [llms.txt](https://llmstxt.org) convention:

- `https://suprnova.app/llms.txt` is an index: a short summary of
  Suprnova, then a link to the Markdown form of every chapter, grouped as
  the manual's table of contents groups them.
- `https://suprnova.app/llms-full.txt` is the whole manual in one
  document, every chapter inlined in table-of-contents order. It is large
  (about 2 MB), so give it to an assistant that can hold it, or let the
  assistant fetch the chapters it needs from `llms.txt`.

Tell your assistant where they are. For example, in a conversation:

```text
Read https://suprnova.app/llms.txt, then fetch the chapters you need as
Markdown before you change routing or models in this project.
```

The manual is also in the framework's repository as plain Markdown, under
`manual/`. An assistant that has the repository checked out can read the
files directly.

## Install the language server

The [Suprnova LSP](https://github.com/eas4ai/suprnova-lsp) is a language
server for Suprnova applications. It reads the API that `#[model]`
generates from rustdoc JSON, so hover, completion and type inference work
on generated methods such as `Post::query()`, and it finds your
application's models on its own. It runs without rust-analyzer. An
assistant that drives your editor, such as Copilot or Cursor, sees the
same completions you do.

To install it in VS Code:

1. Open the [releases page](https://github.com/eas4ai/suprnova-lsp/releases)
   and download the `.vsix` file for your platform, such as
   `suprnova-lsp-0.3.0-linux-x64.vsix`. Each one bundles its server.
2. In VS Code, run the **Extensions: Install from VSIX...** command and
   choose the file, or run
   `code --install-extension suprnova-lsp-0.3.0-linux-x64.vsix`.
3. Reload VS Code.

The extension ID is `eas4ai.suprnova-lsp`, and its settings start with
`suprnova-lsp.`. It exports the model API again when your code changes,
which needs the nightly Rust toolchain its settings name. The releases
are pre-releases. Each release also carries the server alone, as a
`.tar.gz` file for each platform, for editors other than VS Code.

## Point an assistant at your project

An assistant works best when it knows how your project is built and how
you check a change. Most assistants read an instruction file at the root
of the project: `AGENTS.md` for Codex and several others, `CLAUDE.md` for
Claude Code. Suprnova does not generate one; write it yourself and keep it
short. For an application made with `suprnova new`, it can say:

```markdown
# Working on this project

This is a Suprnova application: a Laravel-shaped Rust web framework.
Read https://suprnova.app/llms.txt and fetch the chapters you need as
Markdown before you change a subsystem. Do not assume Laravel or Axum APIs.

- Models are `#[suprnova::model]` structs in `src/models/`; migrations are
  hand-written SeaORM migrations in `src/migrations/`.
- Routes are in `src/routes.rs`; handlers use `#[handler]`.
- After changing an `InertiaProps` struct, run `suprnova generate-types`.
- Check a change with `cargo check`, then `cargo test`.
- Create files with `suprnova make:controller`, `make:migration` and the
  other `make:*` commands rather than by hand.
```

Name the commands your project uses. The [CLI reference](cli.md) lists
every `suprnova` command, and [Testing](testing.md) shows how the tests of
an application run.

### Why Suprnova diverges

Laravel's AI chapter is built around **Laravel Boost**, an MCP server
installed with Composer that gives an assistant tools to inspect a running
Laravel application, a documentation search API, and generated guideline
files. Boost is Laravel tooling, for PHP applications, and Suprnova does
not ship a port of it. In its place, Suprnova offers the manual as
Markdown at `/docs/<chapter>.md`, the `llms.txt` and `llms-full.txt`
files, and the Suprnova LSP for editor-level knowledge of your models.
The instruction file that Boost generates is one you write yourself.

## Next

- [Development](development.md) - the local workflow an assistant runs
  commands in
- [CLI reference](cli.md) - every `suprnova` command, for your
  instruction file
- [Testing](testing.md) - how to check a change before you accept it


---

<!-- /docs/configuration -->

# Configuration

Suprnova reads configuration from environment variables (loaded from
`.env` in development, the process environment in production) and
exposes them to your code in two shapes:

1. **Direct env access** - `env::env`, `env_required`, `env_optional`
   for one-off lookups
2. **Typed config structs** - `Config::register` / `Config::get` for
   anything you read more than once, with strong typing

The framework reads a handful of env vars itself (`APP_KEY`,
`APP_ENV`, `DATABASE_URL`, etc.); the rest are yours.

## The `.env` file

`suprnova new` writes a starter `.env` with the values your app needs
to boot:

```env
APP_NAME="my-app"
APP_ENV=local                # local, development, staging, production, testing, …
APP_DEBUG=true               # detailed error pages + verbose logs
APP_URL=http://localhost:8765

# 32-byte AES-256 key (URL-safe base64, no padding). Encrypts session
# cookies, pagination cursors, and anything via `suprnova::Crypt`.
# Generated at scaffold time. Rotate with `suprnova key:generate`.
APP_KEY=<32-byte base64>

SERVER_HOST=127.0.0.1
SERVER_PORT=8765
VITE_PORT=5765

# Database - SQLite by default; swap to postgres://user:pass@host/db
DATABASE_URL=sqlite://./database.db
DB_MAX_CONNECTIONS=10
DB_MIN_CONNECTIONS=1
DB_CONNECT_TIMEOUT=30
DB_LOGGING=false

# Session
SESSION_LIFETIME=120         # minutes
SESSION_COOKIE=suprnova_session
SESSION_SECURE=false         # set true in production (HTTPS only)
# SESSION_PATH=/             # unset: the public root of each request
SESSION_SAME_SITE=Lax

# Mail - defaults to `log` driver (writes outgoing mail to the
# tracing log, good for dev). Set MAIL_DRIVER to one of
# smtp / ses / mailgun / postmark / sendgrid / resend / log / memory
# for production.
MAIL_DRIVER=log
# SMTP credentials (only read when MAIL_DRIVER=smtp):
MAIL_SMTP_HOST=127.0.0.1
MAIL_SMTP_PORT=587
MAIL_SMTP_USER=
MAIL_SMTP_PASS=
# starttls | tls | none. Left blank it derives from the credentials
# above - starttls with them, none without. Production refuses to boot
# unencrypted; see the Mail chapter.
MAIL_SMTP_ENCRYPTION=
```

A sibling `.env.example` ships the same keys with placeholder values -
commit it; do not commit `.env`. The default `.gitignore` excludes
`.env` already.

## How `.env` loading works

At boot, the framework:

1. Loads `.env` from the project root.
2. Detects the environment from `APP_ENV`, set in the process or in
   `.env` (case-insensitive, `prod`/`dev`/`stage`/`stg`/`test` are also
   recognised). **An unset `APP_ENV` is production**, as in Laravel.
3. Loads `.env.local` on top, if it exists.
4. If `APP_ENV` is set and a per-environment file exists
   (`.env.staging`, `.env.production`), loads it and then
   `.env.<environment>.local` on top - their values override `.env`. With
   `APP_ENV` unset no per-environment file loads, as Laravel's loader
   picks one only for a named environment.
5. Real process environment variables override all of them (this is what
   container orchestration relies on).

The order in one line: **process env > `.env.<environment>.local` >
`.env.<environment>` > `.env.local` > `.env`**.

```rust
use suprnova::Config;

// With the scaffold's APP_ENV=local:
let env = Config::environment();           // Environment::Local
let is_prod = Config::is_production();     // false
```

A process that sets no `APP_ENV` runs as production: debug is off, and
every production check runs, among them the `APP_KEY` refusal, the SQLite
fallback refusal, the Inertia manifest check, and the refusal of a mail
driver that delivers nothing, of the in-memory rate limiter, of an unknown
queue driver and of the mock payment provider. `db:seed` and
`migrate:fresh` ask for `--force`. The scaffold's `.env` sets
`APP_ENV=local`, so a new project runs as before; a deployment names its
environment or gets production. `Environment::detect_explicit()` answers
`None` when `APP_ENV` is unset, for code that needs to tell the two
apart.

In a CI run with `APP_ENV=testing`, the framework loads `.env.testing`
on top of `.env` so you can override DB URLs and disable mail drivers
without touching the dev `.env`.

`#[suprnova::main]` does this loading before it builds the Tokio
runtime, because writing the process environment is only sound while no
other thread can read it. `Config::init` and `config::load_dotenv`, the
functions it calls, refuse to run where they cannot be sound: they
return an error, and write nothing, when you call them from inside a
Tokio runtime, or again after `#[suprnova::main]` loaded the environment
and started its runtime threads. To load a changed `.env`, restart the
process. A file that fails to load leaves the process environment as it
was: the real process variables still win over what any file set before
the failure, and `Config::init` registers no config.

## Direct env access

For one-off reads of strings, numbers, bools - anything implementing
`std::str::FromStr` - use the `env::*` family:

```rust
use suprnova::config::{env, env_required, env_optional};

let port: u16 = env("SERVER_PORT", 8765);                    // with default
let url: String = env_required("APP_URL");                   // panics if missing - boot-only
let smtp_host: Option<String> = env_optional("MAIL_HOST");   // None if missing
```

- `env(key, default)` - type-coerced read with fallback
- `env_required(key)` - panics if the key is missing or fails to
  parse. Only use this at boot time (in `bootstrap()` or `config::register()`)
  where a missing required value should crash the process immediately
- `env_optional(key)` - returns `Option<T>`; `None` for missing or
  unparseable values

Each unique key is also logged once on first read, so you can audit
exactly which env vars your app touches.

## Typed config structs

For anything your app reads more than once, define a typed struct
and register it. The pattern is:

```rust
// src/config/database.rs
use suprnova::Config;
use suprnova::config::{env, env_required, env_optional};

#[derive(Clone, Debug)]
pub struct DatabaseConfig {
    pub url: String,
    pub max_connections: u32,
    pub min_connections: u32,
    pub connect_timeout_secs: u32,
    pub logging: bool,
}

pub fn register() {
    Config::register(DatabaseConfig {
        url: env_required("DATABASE_URL"),
        max_connections: env("DB_MAX_CONNECTIONS", 10),
        min_connections: env("DB_MIN_CONNECTIONS", 1),
        connect_timeout_secs: env("DB_CONNECT_TIMEOUT", 30),
        logging: env("DB_LOGGING", false),
    });
}
```

Then read it anywhere with one line:

```rust
let db = Config::get::<DatabaseConfig>().expect("DB config registered at boot");
println!("Pool size: {}", db.max_connections);
```

The registry is keyed by `TypeId`, so each struct is stored once.
Calling `Config::register` again with the same type replaces the
previous entry - convenient for tests.

### Defaults a crate registers

A crate that ships its own configuration registers it without
overwriting what the application set, whichever runs first.
`Config::register_default` registers a value only when none of its type
is registered, and answers whether it did:

```rust
use suprnova::Config;

#[derive(Clone)]
pub struct BillingConfig {
    pub currency: String,
}

// The application's config::register runs first...
Config::register(BillingConfig { currency: "EUR".into() });
// ...and the billing crate's defaults change nothing.
let registered = Config::register_default(BillingConfig { currency: "USD".into() });
assert!(!registered);
```

`Config::merge` is Laravel's `mergeConfigFrom`: it merges a map of
defaults under the registered map of the same type, keeping every key the
application set and adding the keys only the defaults have. With nothing
registered it registers the defaults.

```rust
use std::collections::BTreeMap;
use suprnova::Config;

Config::register(BTreeMap::from([("disk".to_string(), "s3".to_string())]));
Config::merge(BTreeMap::from([
    ("disk".to_string(), "local".to_string()),
    ("root".to_string(), "storage/app".to_string()),
]));
// disk = s3, root = storage/app
```

`Config::merge` takes `HashMap<String, V>`, `BTreeMap<String, V>` and
`serde_json::Map<String, Value>`. For a struct of your own, implement
`MergeConfig`, whose `merge_defaults(&mut self, defaults)` decides which
fields the defaults fill. Both calls check and write under one lock of the
registry, so two crates registering at the same time cannot both win.

### Why Suprnova diverges

Laravel's configuration is one tree of arrays, so `mergeConfigFrom`
merges by key. Suprnova's is a registry of typed values, one per type: the
merge applies to map-shaped values, and to any type that says how it
merges through `MergeConfig`. Like Laravel's `array_merge`, the merge is
shallow: a key the application set keeps its whole value.

### Wiring registration into your app

The scaffold's `cmd/main.rs` includes a `.config(…)` step in the
fluent boot pipeline:

```rust
use suprnova::Application;

#[suprnova::main]
async fn main() {
    Application::new()
        .config(my_app::config::register)   // ← this calls your registration
        .bootstrap(my_app::bootstrap::register)
        .routes(my_app::routes::register)
        .migrations::<my_app::migrations::Migrator>()
        .run()
        .await
}
```

`my_app::config::register` typically delegates to each section module:

```rust
// src/config/mod.rs
pub mod database;
pub mod mail;

pub fn register() {
    database::register();
    mail::register();
}
```

### Deserialising whole structs from env

For larger configs, you can deserialise directly from env vars via
`serde`. Suprnova exposes two helpers:

```rust
use suprnova::Config;

#[derive(Clone, Debug, serde::Deserialize)]
pub struct ServerConfig {
    pub host: String,
    pub port: u16,
}

// Reads SERVER_HOST / SERVER_PORT from the environment
let cfg = Config::resolve_prefixed::<ServerConfig>("SERVER_")?;
```

- `Config::resolve::<T>()` - deserialise from all process env vars
- `Config::resolve_prefixed::<T>("PREFIX_")` - deserialise only
  vars with the given prefix (the prefix is stripped before
  deserialisation)

Both return `Result<T, FrameworkError>` so a missing required field
surfaces as a `FrameworkError::Internal` carrying the envy diagnostic
instead of a panic.

## Environment-specific config

The `Environment` enum covers the standard set:

| Variant | Recognised `APP_ENV` values |
|---|---|
| `Local` | `local` |
| `Development` | `development`, `dev` |
| `Staging` | `staging`, `stage`, `stg` |
| `Production` | `production`, `prod`, or `APP_ENV` unset |
| `Testing` | `testing`, `test` |
| `Custom(String)` | anything else (preserves your casing, used for `.env.<custom>` lookup) |

Common branches:

```rust
use suprnova::{Config, Environment};

if Config::is_production() {
    // strict cookies, real mail driver, etc.
}

if Config::is_debug() {
    // verbose error pages, query logging
}

match Config::environment() {
    Environment::Production => { /* … */ },
    Environment::Staging    => { /* … */ },
    _ => { /* dev/test path */ },
}
```

`is_debug()` returns `true` when `APP_DEBUG=true` is set explicitly,
or - when `APP_DEBUG` is unset - when the detected environment is
`Local`, `Development`, or `Testing`. Production (an unset `APP_ENV`
included), staging, and any unrecognised custom environment default to
`false`. Keep it off in
production; it controls error-page detail and a few internal defaults.

### `APP_KEY` is required in non-development

In production (any `APP_ENV` other than `local`/`development`/
`testing`, and an unset one), Suprnova requires `APP_KEY` to be set to a valid 32-byte
URL-safe base64 string. Booting without it fails closed with a
descriptive error message - there is no silent fallback.

If you don't have an `APP_KEY` yet:

```bash
suprnova key:generate          # prints the key with a hint reminding you to add it to .env
suprnova key:generate --show   # prints only the key, suitable for `APP_KEY=$(suprnova key:generate --show)`
```

Neither form edits `.env` for you - copy the printed key into your
`.env` (or your secrets manager) yourself.

For key rotation (where old encrypted data must still decrypt during
the migration window), see [Encryption](encryption.md#key-rotation---the-keyring).

## Configuration in tests

In tests, register config in the test setup rather than relying on
`.env`:

```rust
use suprnova::suprnova_test;

#[suprnova_test]
async fn test_with_custom_db() {
    suprnova::Config::register(DatabaseConfig {
        url: "sqlite::memory:".to_string(),
        max_connections: 1,
        min_connections: 1,
        connect_timeout_secs: 5,
        logging: false,
    });

    // … your test
}
```

The `#[suprnova_test]` attribute also sets up isolated container
state so concurrent tests don't see each other's bindings - see
[Testing](testing.md).

## Common env vars Suprnova reads

A non-exhaustive list - these are vars the framework itself looks at.
Your app reads more on top.

| Var | Default | What it does |
|---|---|---|
| `APP_NAME` | `"app"` | Logged at boot, used in some default error messages |
| `APP_ENV` | `production` | Drives `Environment::detect` and `.env.<suffix>` lookup; unset means production and loads no `.env.<suffix>` |
| `APP_DEBUG` | env-aware (`false` in production) | Verbose error pages + extra logging |
| `APP_URL` | `http://localhost:8765` | Base URL for absolute URL generation, signed URLs |
| `APP_KEY` | none (required in prod) | AES-256 key for `Crypt`, sessions, cursors |
| `APP_KEY_PREVIOUS` | none | Comma-separated previous keys for rotation (max 8) |
| `SERVER_HOST` | `127.0.0.1` | Bind address |
| `SERVER_PORT` | `8765` | Bind port |
| `DATABASE_URL` | none | Required if your app uses the database |
| `DB_MAX_CONNECTIONS` | `10` | sqlx pool max |
| `DB_MIN_CONNECTIONS` | `1` | sqlx pool min |
| `DB_CONNECT_TIMEOUT` | `30` (seconds) | sqlx pool connect timeout |
| `SESSION_LIFETIME` | `120` (minutes) | Session expiry |
| `SESSION_TOUCH_INTERVAL` | `300` (seconds) | Minimum sliding-expiry write cadence |
| `SESSION_GC_INTERVAL` | `3600` (seconds) | Supervised expired-session cleanup cadence |
| `SESSION_COOKIE` | `suprnova_session` | Cookie name |
| `SESSION_SECURE` | `true` | Set `Secure` cookie flag. Override to `false` for local-HTTP development. |
| `SESSION_SAME_SITE` | `Lax` | `Strict`, `Lax`, or `None` |
| `MAIL_DRIVER` | `log` | One of `smtp`, `ses`, `mailgun`, `postmark`, `sendgrid`, `resend`, `log`, `memory` |
| `CACHE_DRIVER` | `memory` | One of `memory`, `redis`, `database` |
| `QUEUE_DRIVER` | `memory` | One of `memory`, `sync`, `null`, `redis`, `database`, `sqs`, `failover`. An unknown value is a boot error in production; elsewhere it logs a warning and uses `memory` |
| `RATE_LIMIT_DRIVER` | `memory` | One of `memory`, `redis` |
| `LOG_FORMAT` | env-aware (`pretty` in dev/local, `json` in production) | `pretty` or `json` |
| `LOG_LEVEL` | `info` | A `tracing` filter directive; the eight PSR-3 names (`warning`, `notice`, `critical` and the rest) are accepted, and its bare level is the lowest level the file and stream channels keep |

The full audited list lives in [Environment Variables](env-vars.md).

## Next

- [Application Bootstrap](bootstrap.md) - where typed config registration
  is called from
- [Service Container](container.md) - how registered config is read
  alongside bound services
- [Environment Variables](env-vars.md) - the full reference list
- [Deployment](deployment.md) - production env setup


---

<!-- /docs/structure -->

# Directory Structure

When you run `suprnova new my-app --frontend svelte`, the scaffolder
gives you this:

```
my-app/
├── Cargo.toml                      # crate manifest + dependencies, two [[bin]] targets
├── .env                            # local config - DB URL, app key, ports
├── .env.example                    # template for ops/CI
├── .gitignore                      # excludes target/, .env, node_modules/, public/assets/
├── cmd/
│   └── main.rs                     # the binary entry; calls Application::new().run()
├── src/
│   ├── lib.rs                      # module wiring (`pub mod controllers;` etc.)
│   ├── bootstrap.rs                # registers services, observers, listeners - the
│   │                               # Suprnova analogue of Laravel's service providers
│   ├── routes.rs                   # the `routes!` macro tree - every URL the app serves
│   ├── bin/
│   │   └── console.rs              # `cargo run --bin console <subcommand>` entry -
│   │                               # the Suprnova analogue of `php artisan`
│   ├── actions/
│   │   ├── mod.rs
│   │   └── example_action.rs       # one-method invokable controllers
│   ├── commands/
│   │   └── mod.rs                  # `#[command]`-annotated handlers register here
│   ├── config/
│   │   ├── mod.rs
│   │   ├── database.rs             # typed DB config (driver, URL, pool)
│   │   └── mail.rs                 # typed mail config
│   ├── controllers/
│   │   ├── mod.rs
│   │   ├── home.rs                 # GET / handler
│   │   ├── auth.rs                 # login / register (mails a verification link) / logout
│   │   ├── email_verification.rs   # verify-email notice, resend, and the mailed link
│   │   ├── password_reset.rs       # forgot-password and reset-password
│   │   └── dashboard.rs            # requires auth; example protected route
│   ├── middleware/
│   │   ├── mod.rs
│   │   ├── logging.rs              # request/response logging
│   │   └── authenticate.rs         # session-based auth guard
│   ├── migrations/
│   │   ├── mod.rs
│   │   ├── m_*_create_users_table.rs
│   │   ├── m_*_create_sessions_table.rs
│   │   ├── m_*_create_remember_tokens_table.rs
│   │   ├── m_*_create_auth_flow_tokens_table.rs
│   │   ├── m_*_create_workflows_table.rs
│   │   └── m_*_create_workflow_steps_table.rs
│   └── models/
│       ├── mod.rs
│       └── user.rs                 # `#[suprnova::model]` User model
├── templates/
│   └── app.html                    # the Inertia root document every first visit
│                                   # renders into, `AppDocument` in bootstrap.rs
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── src/
│       ├── main.{tsx,ts}           # Inertia client setup (per-framework)
│       ├── app.css                 # global styles + Tailwind
│       ├── pages/
│       │   ├── Home.{tsx,svelte,vue}
│       │   ├── Dashboard.{tsx,svelte,vue}
│       │   └── auth/
│       │       ├── Login.{tsx,svelte,vue}
│       │       ├── Register.{tsx,svelte,vue}
│       │       ├── ForgotPassword.{tsx,svelte,vue}
│       │       ├── ResetPassword.{tsx,svelte,vue}
│       │       └── VerifyEmail.{tsx,svelte,vue}
│       └── types/
│           └── inertia-props.ts    # auto-generated from #[derive(InertiaProps)]
└── public/
    └── assets/                     # Vite production build output lands here
```

Svelte adds `frontend/svelte.config.js` and `frontend/src/app.d.ts`.
Vue adds `frontend/src/shims-vue.d.ts`.

The API starter (`suprnova new my-api --api`) is slimmer: no
`frontend/`, no auth controllers, and `cmd/main.rs` is replaced by
`src/main.rs`.

## What each directory is for

### `cmd/main.rs`

The binary entry point. A short file - typically 10-20 lines - that
calls the standard boot pipeline:

```rust
use suprnova::Application;
use my_app::{bootstrap, config, migrations, routes};

#[suprnova::main]
async fn main() {
    Application::new()
        .config(config::register_all)
        .bootstrap(bootstrap::register)
        .routes(routes::register)
        .migrations::<migrations::Migrator>()
        .run()
        .await;
}
```

`Application::run()` parses the binary's CLI (`serve` / `web:run` /
`migrate*` / `schedule:*` / `workflow:work` / `queue:work`), loads
`.env`, runs your config function, then dispatches the subcommand. The
serve path also runs your bootstrap function and starts the HTTP
server.

You almost never edit `cmd/main.rs` after the initial scaffold.

### `src/lib.rs`

A flat module declaration file:

```rust
pub mod actions;
pub mod bootstrap;
pub mod commands;
pub mod config;
pub mod controllers;
pub mod middleware;
pub mod migrations;
pub mod models;
pub mod routes;
```

This is what makes `crate::controllers::home::index` reachable from
`routes.rs`.

### `src/bootstrap.rs`

The single function that wires your app. You register service container
bindings, observers, event listeners, custom middleware, and any other
boot-time setup here. It's the analogue of Laravel's `AppServiceProvider`,
`EventServiceProvider`, `BroadcastServiceProvider`, etc., all in one
file:

```rust
use std::sync::Arc;
use suprnova::App;

pub async fn register() {
    // Bind a service into the container
    App::bind::<dyn MyService>(Arc::new(MyServiceImpl::new()));

    // Register an Eloquent observer
    crate::models::user::register_observer();

    // Listen for events
    suprnova::EventFacade::listen::<OrderShipped, _>(Arc::new(SendShipmentNotification)).await;
}
```

`register()` runs once per process, after the config loader but before
`serve` accepts the first request. Workers (`queue:work`,
`schedule:run`, `workflow:work`) reuse the same bootstrap so they see
the same services. See [Application Bootstrap](bootstrap.md).

### `src/routes.rs`

Your URL surface. The `routes!` macro at module top-level expands into
a `pub fn register() -> Router` that `cmd/main.rs` hands to
`Application::routes(...)`:

```rust
use suprnova::{get, post, put, delete, routes};
use crate::{controllers, middleware};

routes! {
    get!("/", controllers::home::index).name("home"),

    // Auth (registered + protected)
    get!("/login", controllers::auth::show_login).name("login.show"),
    post!("/login", controllers::auth::login).name("login.attempt"),
    post!("/logout", controllers::auth::logout).name("logout"),
    get!("/register", controllers::auth::show_register).name("register.show"),
    post!("/register", controllers::auth::register).name("register"),

    // Dashboard requires authenticate middleware
    get!("/dashboard", controllers::dashboard::index)
        .middleware(middleware::authenticate::auth())
        .name("dashboard"),
}
```

See [Routing](routing.md).

### `src/bin/console.rs`

Your per-project console binary. Runs as `cargo run --bin console
<subcommand>` and dispatches the framework's `db:seed` built-in plus
every `#[command]`-annotated handler (or `#[derive(Command)]` typed
struct) in `src/commands/` - both forms register through inventory at
compile time:

```bash
cargo run --bin console db:seed           # framework built-in
cargo run --bin console report:daily      # your custom command
```

The long-running workers (`queue:work`, `schedule:run`,
`schedule:work`, `workflow:work`) live on the main app binary
because `Application::run()` dispatches them - call them as
`cargo run -- queue:work` (or via `suprnova schedule:run` /
`suprnova workflow:work` if you prefer the umbrella CLI).

See [Console](console.md).

### `src/commands/`

Where your console handlers live. Two flavours: a typed struct with
clap-derived args and `impl TypedCommand`, or a raw `#[command]` on an
`async fn(Vec<String>) -> Result<(), FrameworkError>`. The scaffolder
generates the typed form:

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "report:daily", description = "Generate the daily report")]
pub struct DailyReport {
    #[arg(long, default_value_t = false)]
    pub dry_run: bool,
}

#[async_trait]
impl TypedCommand for DailyReport {
    async fn run(self) -> Result<(), FrameworkError> {
        // …
        Ok(())
    }
}
```

`suprnova make:command report-daily` scaffolds the file and adds it to
`src/commands/mod.rs`. See [Console](console.md).

### `src/config/`

Typed configuration structs. The scaffold ships `database.rs` and
`mail.rs`; add your own for any subsystem your app cares about. Each
config struct reads its values from the environment, and
`config::register_all()` registers them with the framework:

```rust
use suprnova::{env, env_required};

#[derive(Clone, Debug)]
pub struct AnalyticsConfig {
    pub api_key: String,
    pub max_batch: u32,
}

impl AnalyticsConfig {
    pub fn from_env() -> Self {
        Self {
            api_key: env_required::<String>("ANALYTICS_API_KEY"),
            max_batch: env("ANALYTICS_MAX_BATCH", 100u32),
        }
    }
}
```

Wire it in `config/mod.rs`:

```rust
use suprnova::Config;

pub fn register_all() {
    Config::register(AnalyticsConfig::from_env());
}
```

See [Configuration](configuration.md).

### `src/controllers/`

HTTP handler functions. One module per resource. Each `pub async fn`
that takes a `Request` and returns a `Response` is callable from a
route.

### `src/middleware/`

Middleware implementations. The scaffold ships `logging` and
`authenticate`; you add your own here as `pub struct Foo` with
`impl Middleware for Foo`. Register them globally in `bootstrap.rs`
or apply per-route via `.middleware(…)` in the `routes!` tree. See
[Middleware](middleware.md).

### `src/migrations/`

SeaORM migrators. The scaffold ships a handful for the auth + workflow
tables. `suprnova make:migration <name>` adds a new one. `suprnova
migrate`, `migrate:rollback`, `migrate:status`, `migrate:fresh`,
`db:sync` all operate on this directory. See [Migrations](migrations.md).

### `src/models/`

Your Eloquent models. One file per model, each a `#[suprnova::model]`
struct. The scaffold ships `user.rs`; add new models by writing a new
file by hand or running `suprnova db:sync --regenerate-models` after a
schema migration. See [Eloquent](eloquent.md).

### `src/actions/`

Single-method invokable controllers. Optional pattern - use them when
a controller would have exactly one method and you'd rather call it
"Action" than wrap it. The scaffold ships an example you can delete or
adapt. See [Actions](actions.md).

### `templates/`

Askama templates, which the Rust build reads at compile time. The scaffold
ships `app.html`, the Inertia root document every first visit renders
into: the place for your favicon, fonts and meta tags around the parts the
framework hands it (`title`, `head`, `body`, `lang`). `src/bootstrap.rs`
declares it and installs it on the Inertia config:

```rust
use suprnova::{Inertia, InertiaConfig, InertiaRootTemplate};

#[suprnova::inertia_root(path = "app.html")]
pub struct AppDocument;

pub fn register_http_stack() {
    Inertia::install(
        &InertiaConfig::new().root_template(InertiaRootTemplate::of::<AppDocument>()),
    )
    .expect("Inertia install failed (production needs a built frontend manifest)");
}
```

`suprnova live:make` adds Live component views under `templates/live/`.
See [Inertia Responses](frontend-inertia-responses.md#the-root-template).

### `frontend/`

The Vite + Inertia SPA. This is a normal frontend project - `package.json`,
`vite.config.ts`, `tsconfig.json`, source under `src/`. Vite builds from
the entry module `src/main.{tsx,ts}`, which holds the Inertia client
setup; the page components live in `src/pages/`, and the first-load HTML
comes from `templates/app.html`. TypeScript types for your Rust
`#[derive(InertiaProps)]` props are regenerated into
`src/types/inertia-props.ts` by `suprnova generate-types`.

See [Frontend](frontend.md).

### `public/assets/`

Where Vite drops the production build (`npm run build`). The generated
`routes.rs` ends with `fallback!(StaticFiles::public().handler())`, so the
Suprnova server serves this directory as static assets at `/assets/*` in
production. Dotfiles under `public/`, such as `.vite/manifest.json`, are
never served. A symbolic link under `public/` is followed only while it
stays inside `public/`, and the server opens each file through the
directories it checked, so a directory replaced by a link while a request
is in flight cannot redirect the request. `public/` itself may be a link.

`StaticFiles::fingerprint(pattern)` selects the filename-stem expression for
one-year immutable caching. The default matches Vite hashes. Keep this expression
in sync with `PageBudget::fingerprint_pattern`. See [Page Budget](page-budget.md).

## Directories you'll add as the app grows

The scaffold gives you the minimum - enough to ship the welcome flow
and a protected dashboard. Real apps grow more subsystems. Common
additions:

| Directory | When you add it |
|---|---|
| `src/jobs/` | First time you `Queue::push(SomeJob)`. See [Queues](queues.md). |
| `src/listeners/` | First time you `Event::listen`. See [Events](events.md). |
| `src/observers/` | First time you implement `Observer<MyModel>`. See [Eloquent](eloquent.md#observers-and-lifecycle-events). |
| `src/notifications/` | First time you implement a `Notification`. See [Notifications](notifications.md). |
| `src/mail/` | First time you implement a `Mailable`. See [Mail](mail.md). |
| `src/policies/` | First time you write a `#[policy]`. See [Authorization](authorization.md). |
| `src/factories/` | First time you write a `Factory<Model>` for tests. See [Eloquent Factories](eloquent-factories.md). |
| `src/seeders/` | First time you write a `Seeder` for `db:seed`. See [Seeding](seeding.md). |
| `src/events/` | First time you `impl Event` for your own event type. See [Events](events.md). |
| `src/broadcasting/` | First time you define a private/presence `Channel`. See [Broadcasting](broadcasting.md). |
| `src/ws/` | First time you write a `ws!()` handler. See [WebSockets](websockets.md). |
| `src/supervisors/` | First time you implement a long-running `Supervisor`. See [Supervisors](supervisors.md). |
| `src/payments/` | First time you wire up Stripe/Paddle for your app. See [Payments](payments.md). |
| `src/props/` | When you want to keep `#[derive(InertiaProps)]` structs separate from controllers. |
| `resources/views/` | First time you add a Tera template for mail bodies. |
| `storage/` | First time you write files to the local filesystem disk (see [File Storage](filesystem.md)). |
| `tests/` | First time you write an integration test. |

You don't have to ask permission - `mkdir src/jobs` and add
`pub mod jobs;` to `src/lib.rs`, and you're done. The framework
doesn't enforce the directory names; the conventions exist so other
Suprnova developers can find things quickly.

## The dogfood `app/` in this repo

If you're reading this from inside the Suprnova repo itself, you'll
see an `app/` directory at the root that uses every framework feature
together. That's our internal test bed - it exercises payments,
broadcasting, web push, workflows, supervisors, etc. all at once. It's
NOT a clean reference for a new app; the scaffold output above is
deliberately smaller and easier to learn from. Read `app/` once you
want to see a maximal example of how the pieces compose.

## Next

- [Configuration](configuration.md) - how `.env` becomes typed config
- [Application Bootstrap](bootstrap.md) - what `bootstrap.rs` actually
  does
- [Routing](routing.md) - your first route
- [Service Container](container.md) - how `App::bind` and `App::get`
  work


---

<!-- /docs/frontend -->

# Frontend Overview

Suprnova bridges Rust handlers to a single-page frontend via
[Inertia.js](https://inertiajs.com/) 3.8.0. You write controllers in Rust
and pages in Svelte, React, or Vue; the framework moves typed props
between them without a separate HTTP API in the middle.

## Three first-class starters

`suprnova new <name>` scaffolds a working project. The `--frontend` flag
picks the SPA layer:

```bash
suprnova new my-app                       # Svelte 5 (default)
suprnova new my-app --frontend svelte     # Svelte 5
suprnova new my-app --frontend react      # React 19
suprnova new my-app --frontend vue        # Vue 3.5
```

All three scaffolds share the same stack:

| Layer | Version |
|---|---|
| Inertia client adapter | `@inertiajs/{svelte,react,vue3}` 3.8.0 |
| Inertia Vite plugin | `@inertiajs/vite` 3.8.0 |
| Build tool | Vite 8 |
| Styling | Tailwind v4 (`@tailwindcss/vite`) |
| TypeScript | strict mode |

The choice is per-project. There is no "primary" framework on the
server side - `inertia_response!` resolves whichever extension your
chosen scaffold uses (`.svelte`, `.tsx`, `.vue`), and `App::inertia_share`,
partial reloads, and TypeScript prop generation all behave identically
across the three.

## Architecture

```
                       Browser
   +-------------------------------------------------+
   |               SPA (Svelte / React / Vue)        |
   |   +---------------+ +---------------+           |
   |   | Home.svelte   | | Users/Show.tsx|  ...      |
   |   +-------+-------+ +-------+-------+           |
   |           |  typed props from Rust struct       |
   |   +-------v-------------------------------+     |
   |   |        Inertia client adapter         |     |
   +---+------------------+------------------+--+----+
                          |
                          |   HTTP (JSON on XHR, HTML on first load)
                          v
   +-------------------------------------------------+
   |                  Suprnova server                |
   |   +------------------------------------------+  |
   |   |          Controllers / handlers          |  |
   |   |   inertia_response!(&req, "Home",        |  |
   |   |                     HomeProps { ... })   |  |
   |   +------------------------------------------+  |
   +-------------------------------------------------+
```

The first request returns an HTML shell with the initial page object as
JSON in a `<script type="application/json" data-page="app">` element, the
sibling just before the empty `<div id="app">` mount node - where the
Inertia 3 client reads it. Subsequent visits go through `<Link>` /
`router.visit`, send `X-Inertia: true`, and get back a JSON page object -
the adapter swaps the component without a full reload.

## A complete page round-trip

The controller defines its props as a Rust struct, derives
`InertiaProps`, and hands the value to the `inertia_response!` macro:

```rust
use suprnova::{InertiaProps, Request, Response, inertia_response};

#[derive(InertiaProps)]
pub struct HomeProps {
    pub title: String,
    pub message: String,
}

pub async fn index(req: Request) -> Response {
    inertia_response!(&req, "Home", HomeProps {
        title: "Welcome".into(),
        message: "Hello from Suprnova!".into(),
    })
}
```

The props are sent under the names serde's attributes give them:
`#[serde(rename_all = "camelCase")]` on the struct sends a `current_user`
field as `currentUser`, and `#[serde(rename = "..")]`, `#[serde(skip)]` and
`#[serde(skip_serializing)]` work on a field. Props are only serialized, so
the derive reads the serialize side, and leaves a `deserialize` half and
`skip_deserializing` to a `Deserialize` derive on the same struct. It
refuses any other serde attribute, and two props under one key.

A few things the macro does for you. First, it validates at compile
time that the page component file actually exists under
`frontend/src/pages/Home.{svelte,tsx,jsx,vue}` - typos surface as a
build error, not a 404 in the browser. Second, it serializes the
`HomeProps` struct, unfolds it into one prop per top-level key so
partial reloads can filter, and resolves any lazy or deferred props
against `&req` before returning. The macro evaluates to a
`Result<HttpResponse, FrameworkError>`, which the `Response` return type
accepts directly.

The matching Svelte page (the default scaffold):

```svelte
<!-- frontend/src/pages/Home.svelte -->
<script lang="ts">
  import type { HomeProps } from '../types/inertia-props'

  let { title, message }: HomeProps = $props()
</script>

<div class="font-sans p-8 max-w-xl mx-auto">
  <h1 class="text-3xl font-bold">{title}</h1>
  <p class="mt-2">{message}</p>
</div>
```

For the React and Vue equivalents see [Page Components](frontend-pages.md).

## Generating TypeScript types

Every `#[derive(InertiaProps)]` struct in your `src/` becomes a
TypeScript interface in `frontend/src/types/inertia-props.ts`:

```bash
suprnova generate-types
```

Pass `--routes` and the same command also emits
`frontend/src/types/routes.ts` - type-safe URL + method pairs scraped
from your `routes!` macro that work directly with Inertia v2+ APIs. The full type-mapping table and
route-helper shape live in [TypeScript Types](frontend-typescript-types.md).

## Shared data

Anything that should appear on every page (the authenticated user, the
current locale, app metadata) is registered once at boot and merged into
every Inertia response:

```rust
// In bootstrap.rs
App::inertia_share("appName", "Suprnova");
App::inertia_share("appVersion", env!("CARGO_PKG_VERSION"));

// Async / per-request shared data goes through the trait.
App::register_inertia_shared(Arc::new(AppSharedData));
```

The flavours, in order of precedence (later wins at the same key):

| API | When the value materializes |
|---|---|
| `App::inertia_share(k, v)` | Sync, set once at boot |
| `App::inertia_share_lazy(k, \|\| async { ... })` | Per response, recomputed |
| `App::inertia_share_once(k, \|\| async { ... })` | Per response, then client-cached |
| `App::inertia_registry().share_provider(provider)` | Per response, expanded with the page and the request; any number |
| `App::register_inertia_shared(Arc::new(impl))` | Per request, sees `&req` |

Per-page props attached on the response builder always overwrite shared
data at the same key.

The `Inertia` facade takes every form Laravel's `Inertia::share` does - a
key and a value, a map, a `#[derive(Data)]` object or a provider - and reads
shared data back with `get_shared`:

```rust
use suprnova::Inertia;

Inertia::share("appName", "Suprnova")?;
Inertia::share("user.locale", "es")?;              // nests: user = { locale: "es" }
Inertia::share_many([("plan", "pro"), ("region", "eu")])?;
Inertia::share_data(SiteMeta { name: "Suprnova".into(), build: 7 })?;
Inertia::share_provider(TenantShare);              // a ProvidesInertiaProperties value

Inertia::get_shared("user.locale", serde_json::Value::Null); // "es"
Inertia::get_shared("missing", 7);                            // 7
Inertia::get_shared_all();                                    // every shared value, nested
```

A dotted key nests when it is shared, as Laravel's `Arr::set` does, so a
later `share("user", ...)` replaces the whole `user` object, child included.
`App::inertia_share` shares the same way. A Data object shares its eager
fields; its lazy fields stay out, since a shared prop has no `?include=`
gate. `share_provider` takes a `ProvidesInertiaProperties` value, the same
registration as `InertiaRegistry::share_provider`: any number of providers,
each expanded once per render with a `RenderContext` of the request and the
component, and `App::flush_inertia_shared` clears them with the other shares.
`App::register_inertia_shared` is the one-slot async provider
(`InertiaSharedData`) and stays beside it. `get_shared` reads what is
registered without resolving it, so a lazy share reads as the default.

The framework ships `RootShare`, a provider that gives every page the
public root as the `root` prop: the empty string at the host root,
`/billing` behind a reverse proxy that serves the application under
`/billing`. A page that builds its URLs from it, such as
`` form.post(`${root}/login`) ``, runs from one build at `/` and under a
prefix. An application registers one provider, so `RootShare` carries
another one and shares its props too:

```rust
App::register_inertia_shared(Arc::new(RootShare::around(Arc::new(LocaleShare))));
```

A scaffolded application registers it this way, builds its pages' URLs
from `root`, and builds its frontend with Vite's relative `base: './'`, so
code-split chunks load from wherever the entry script was served. For the
proxy setup, see [Serving under a path prefix](deployment.md#serving-under-a-path-prefix).

## Partial reloads and lazy props

The same `InertiaResponse` builder exposes Inertia v3's full prop
toolkit - eager, lazy, optional, deferred, merge, once - and Suprnova
honors the v3 partial-reload headers (`X-Inertia-Partial-Data`,
`X-Inertia-Partial-Except`, `X-Inertia-Reset`,
`X-Inertia-Except-Once-Props`) automatically. The example below
attaches three props with different evaluation rules:

```rust
use suprnova::{InertiaResponse, FrameworkError, Request, Response};

pub async fn dashboard(req: Request) -> Response {
    let resp = InertiaResponse::new("Dashboard")
        .with("title", "Dashboard")
        .lazy("recent_orders", || async {
            Ok::<_, FrameworkError>(load_recent_orders().await?)
        })
        .defer("notifications", || async {
            Ok::<_, FrameworkError>(load_notifications().await?)
        })
        .resolve(&req)
        .await?;
    Ok(resp)
}
```

`inertia_response!` covers the eager-props case; everything past that
goes through the builder. The full surface - `optional`, `merge`,
`once`, `scroll`, `flash`, `paginate`, SSR, version mismatch, history
encryption - is documented in
[Inertia Responses](frontend-inertia-responses.md).

## Bootstrap

A scaffolded app installs the five protocol middlewares in one call
inside `bootstrap.rs`:

```rust
use suprnova::{Inertia, InertiaConfig};

Inertia::install(&InertiaConfig::new().version(env!("CARGO_PKG_VERSION")))
    .expect("Inertia install failed");
```

`install` returns `Result` - it fails closed if `InertiaConfig` resolves to
production mode (the default under `APP_ENV=production`) but no Vite
manifest can be found, rather than silently falling back to a legacy
asset path. See [Development vs production](#development-vs-production)
below.

That registers, in order: `InertiaHeadersMiddleware` (sets `Vary: X-Inertia`
on every response and turns an empty `200` on an Inertia visit into a
redirect back), `InertiaVersionMiddleware` (emits 409 + `X-Inertia-Location` on
asset-version mismatch so stale clients reload), `Inertia303Middleware`
(rewrites 302 → 303 on Inertia `PUT`, `PATCH` and `DELETE` visits so the
follow-up is unambiguously a GET), `InertiaErrorPageMiddleware` (hands the framework's
own error responses to your error callback or the configured error page,
and changes nothing without either), and
`InertiaValidationRedirectMiddleware` (turns a `422` on an Inertia visit
into a `303` back to the form page with the errors flashed).
`InertiaVersionMiddleware` and `Inertia303Middleware` used to require
separate registration; `Inertia::install` makes all five the default. See [Inertia Responses](frontend-inertia-responses.md#bootstrap-inertiainstall)
for the full registration order and what each middleware closes.

With `.devtools(DevToolsConfig::new())`, `install` also registers the
recorder of the Inertia DevTools browser extension when `APP_ENV=local`.
It sits outermost in the Inertia layer, stores an entry for each request
and answers the
extension's `/_inertia/devtools/entries` endpoints. See
[Inertia DevTools](frontend-inertia-devtools.md) to switch it on elsewhere,
gate it, or turn it off.

## Development vs production

In development, the Vite dev server runs alongside the backend and
serves HMR-enabled assets:

```bash
suprnova serve
```

This boots the Rust server and `vite` together. The HTML shell loads
modules from `http://localhost:5765`.

For production, build the frontend once and point the backend at the
hashed manifest under `public/assets/`:

```bash
cd frontend && npm run build
APP_ENV=production suprnova serve --backend-only
```

`InertiaConfig::default()` derives production vs. development mode from
`APP_ENV` (via `Environment::detect().is_production()`) - `APP_ENV=production`
is what makes the HTML shell load built assets instead of the Vite dev
server. `Inertia::install` then fails boot loudly if it can't find a
manifest to back that decision, rather than silently falling back to a
stale hardcoded path.

Suprnova reads `public/assets/.vite/manifest.json` to resolve hashed
entry points plus any transitive imports for `modulepreload`. SSR is
optional - opt in by pointing `InertiaConfig::ssr(...)` at a running
`@inertiajs/{vue3,react,svelte}/server` worker. `suprnova new` scaffolds
an SSR entry point and build script for every starter, and the
`ssr:start`, `ssr:stop`, and `ssr:check` commands of the application
binary and of the `suprnova` CLI run, stop, and check the worker;
see [Inertia Responses](frontend-inertia-responses.md#ssr) for the full
setup, including the bundle-existence check and CSR fallback behavior.

### Why Suprnova diverges

Three intentional departures from how a typical Inertia setup looks
elsewhere:

- **Compile-time component validation.** The `inertia_response!` macro
  walks `frontend/src/pages/` at build time and refuses to expand if
  the component file is missing, suggesting the closest match. You
  cannot ship a controller that points at a deleted page.
- **Typed props as the source of truth.** Page props are Rust structs
  with `#[derive(InertiaProps)]`. `suprnova generate-types` reads them
  and writes TypeScript interfaces - the frontend types are derived
  from the backend, not maintained in parallel.
- **Svelte as the default.** Inertia's documentation reaches for Vue and
  React first; the Suprnova scaffolder defaults to Svelte 5 (runes-on).
  React 19 and Vue 3.5 are first-class, not afterthoughts - same
  protocol, same prop pipeline, same generator output.

## Working with a coding assistant

A coding assistant that learned Inertia from Laravel projects carries
assumptions that are wrong here. Laravel's own guideline set for assistants
(the Inertia section of Laravel Boost) covers this ground for a PHP project;
this is the Suprnova version. Paste it, or point the assistant at this
chapter, before it touches a page:

- **Pages live in `frontend/src/pages/`**, one component per file. A handler
  renders one with `inertia_response!` or `InertiaResponse::new`, never with
  a server template. The first visit's document is `templates/app.html`, the
  root template, and the page is never written into it.
- **Props are typed on the server.** Each page has a `#[derive(InertiaProps)]`
  struct, and `suprnova generate-types` (or `suprnova serve`, which runs it
  on change) writes `frontend/src/types/inertia-props.ts`. After a Rust field
  changes, regenerate and let the TypeScript compiler name every component to
  update. The generated file is never edited by hand.
- **Every Inertia 3 feature is available**: deferred props, infinite scroll,
  merging props, polling, prefetching, once props and flash data, and the
  Inertia 3 additions, standalone HTTP requests (`useHttp`), optimistic
  updates with rollback, layout props (`useLayoutProps`), instant visits and
  SSR through the Vite plugin. The server side of each is a method on the
  `InertiaResponse` builder; [Inertia Responses](frontend-inertia-responses.md)
  lists them. Prop types (`optional`, `defer`, `merge`) take dot-notation
  paths, and a dotted partial reload narrows literal values only.
- **Names that moved.** Inertia 3 removed `Inertia::lazy()`: use
  `.optional()` for a prop skipped on the first visit. Suprnova's `.lazy()` is
  a plain callable prop that resolves on every visit that selects it (see the
  divergence callout in Inertia Responses). On the client, Axios is gone and
  the built-in XHR client with interceptors replaces it, `router.cancel()` is
  `router.cancelAll()`, the `invalid` event is `httpException` and `exception`
  is `networkError`, and the `future` configuration namespace no longer
  exists.
- **Deferred props need an empty state.** The page renders before they
  arrive, so a component that shows one carries a skeleton or a placeholder
  for the gap.
- **Tests drive the server in process.** A test calls `handle_request` and
  reads the page object with `AssertableInertia`, from a JSON visit or from
  the first-load HTML ([HTTP Tests](http-tests.md#testing-inertia-responses)).
  A page change lands with such a test.
- **Check the version.** An assistant's training data describes Inertia 1 and
  2 as often as 3. Have it read the Inertia 3 documentation and this manual
  for anything protocol-level rather than recall it.

## Next

- [Page Components](frontend-pages.md)
- [Inertia Responses](frontend-inertia-responses.md)
- [Inertia DevTools](frontend-inertia-devtools.md)
- [TypeScript Types](frontend-typescript-types.md)
- [Routing](routing.md)
- [Controllers](controllers.md)


---

<!-- /docs/starter-kits -->

# Starter Kits

Starter kits are ready-made Suprnova applications you fork and ship. Each one
wires the controllers, routes, migrations, frontend pages, and tests for a
complete product surface - so you start from a running app, not an empty
scaffold.

Three kits ship, modelled on Laravel's lineage. Pick the one closest to
what you're building and customise from there.

## Nebula - authentication (Breeze-tier)

**Repo: [github.com/eas4ai/Nebula](https://github.com/eas4ai/Nebula)**

The minimal full-auth kit - Suprnova's Breeze equivalent. Everything you need
for accounts and nothing you don't:

- Registration with email verification
- Login with remember-me
- Password reset with anti-enumeration responses
- Profile management - update email and password, delete account
- A branded Inertia 3 + Svelte 5 frontend (dark by default), with the
  logged-in user menu wired

Nebula ships two test suites: facade-level auth logic, and a wire-level HTTP
suite that drives real routes, sessions, CSRF round-trips, and the
guest / auth / verified gates over a loopback socket.

Reach for Nebula when you want a clean account-management foundation to build
your own product on top of.

## Pulsar - product site & community

**Repo: [github.com/eas4ai/Pulsar](https://github.com/eas4ai/Pulsar)**

A complete developer-tool / SaaS company site on Vue 3.5 + Vuetify. Everything
in Nebula's auth story, plus the surfaces a real product site needs:

- Marketing landing page and a user dashboard
- A Markdown documentation pipeline (`docs:build`) with search and a generated
  table of contents
- A blog / articles system with an RSS feed
- Public member profiles
- Taxonomy - topics, tags, and categories
- Role-based access control: roles, permissions, and gates
- Admin and moderation surfaces for content and members

Pulsar is the source kit for downstream products such as `suprnova.app`. Reach
for it when you're shipping a product site with docs, a blog, and a member
community - not just authentication.

## Directory starter - listings, moderation, and paid publication

**Repo: [github.com/eas4ai/suprnova-directory-starter](https://github.com/eas4ai/suprnova-directory-starter)**

A free, MIT-licensed directory on Vue 3.5: owners submit listings, moderators
review them, visitors search them, and publication is free or paid through
Stripe and Paddle. Everything in Nebula's auth story, plus:

- Directory discovery - searchable listings, category filters, pagination,
  and public detail pages
- Owner submissions and moderation - drafts, revision history, approval,
  rejection, resubmission, and suspension
- Free and paid publication - Stripe and Paddle, configurable plans, separate
  test and live settings, authenticated webhooks, and payment recovery
- Editorial publishing - article drafts, previews, categories, tags, and RSS
- Administration - permission-based roles, account suspension, audit
  history, and an admin overview
- SEO - site defaults and per-content overrides, server-rendered metadata,
  sitemaps, redirects, a 404 report, and Markdown versions of public pages
- Media and notifications, colour presets with a remembered light or dark
  preference, demo content, and documented backup and restore workflows

Reach for the directory starter when the product is a directory or a
marketplace of listings, with or without paid placement.

## Which kit?

| You want… | Start with |
|---|---|
| Accounts and a place to build | **Nebula** |
| A full product site - landing, docs, blog, community, RBAC | **Pulsar** |
| A directory or marketplace of listings, free or paid | **Directory starter** |
| Server-rendered pages with no Bun toolchain | `suprnova new my-app --frontend live` |
| An API-only backend (token auth, no frontend) | `suprnova new my-api --api` |

All three kits track the framework as a git dependency and run on the same stack you
already know - see each repo's README for setup. More kits are planned; watch
the [releases](https://github.com/eas4ai/suprnova/releases) or open an
issue if there's one you want.

## What the default scaffold gives you

If neither kit fits, `suprnova new my-app --frontend svelte` (or `react`, or
`vue`) already ships a working authentication flow - login, register, logout,
email verification, password reset, session authentication with the
`authenticate` middleware, CSRF protection, and a protected `/dashboard`
route - on any of the three frontends (Svelte 5,
React 19, Vue 3.5) with Tailwind v4 and Inertia v3, or on the
[Live starter kit](#the-live-starter-kit), which needs no Bun toolchain. See
[Installation](installation.md) for the scaffold output and
[Quickstart](quickstart.md) for the first-five-minutes walkthrough.

Behind the authentication group, the scaffold ships the server side of the
kit pages, all of it over the signed-in user's own data:

- A `notes` table and a `Note` model (`src/models/note.rs`) that belongs to
  a user, with `Note::owned_by(user_id)` as the one way the handlers read
  notes.
- `GET /dashboard`, which sends `stats` deferred (the user's note count
  and the notes written today) and `recent_notes` optional (the user's
  five newest notes).
- `GET /notes`, which lists the user's notes 10 at a time with
  `cursor_paginate` through `Inertia::paginate`, filtered by the `search`
  query parameter in title or body without regard to case, and sends
  `search` back to the page.
- `GET /notes/{id}`, which shows one of the user's notes and answers `404`
  for a note of another user or an id that doesn't exist.
- `POST /notes`, which validates `title` (1 to 255 characters) and `body`
  (at most 10000 characters), writes the note, flashes a toast, and returns
  to the page the form was posted from, preserving its search query, with
  `/notes` as the fallback.
- `POST /profile/name`, a JSON handler for the dashboard's name form that
  answers `200` with `{"user": {...}}` or `422` with the framework's
  validation body.

Every page receives the signed-in user, or `null` for a guest, under the
shared `auth` prop: `bootstrap.rs` shares it with `App::inertia_share_lazy`,
which reads the request's session for each response that sends it, and
`SharedData` in `src/props/shared.rs`, marked `#[inertia_props(shared)]`,
adds `auth` to the generated `SharedProps`. A layout reads
`usePage().props.auth.user`.

Sign-in, registration, a reset-link request, a password reset, email
verification, a verification resend, sign-out, and a saved note each flash a
`Toast` (`src/props/flash.rs`) under the key `toast`. The `Flash` struct
beside it holds that toast and is marked `#[inertia_props(flash)]`, so
`suprnova generate-types` names it as Inertia's `flashDataType` and
`page.flash.toast` is typed in every page.

The routes carry the names Laravel's kits give them: `dashboard`,
`notes.index`, `notes.show`, `notes.store`, `profile.name`, `login`,
`register`, `password.request`, `password.email`, `password.reset`,
`password.update`, `verification.notice`, `verification.send`,
`verification.verify`, and `logout`.

The dashboard handler shows how each prop travels:

```rust
#[handler]
pub async fn index(req: Request) -> Response {
    let user = Auth::user_as::<User>()
        .await?
        .ok_or(FrameworkError::Unauthorized)?;
    let user_id = user.id;

    Ok(InertiaResponse::new("Dashboard")
        .defer("stats", move || note_stats(user_id))
        .optional("recent_notes", move || recent_notes(user_id))
        .resolve(&req)
        .await?)
}
```

### Live note updates

The Inertia kits also keep the dashboard's `stats` current when a note is
saved or deleted. Their Live registry declares a private topic family,
`live::authorize()` defines its audience, bootstrap calls it and connects
model hooks, and the dashboard props bind `stats` to it:

```rust
// src/live/mod.rs
let registry = LiveRegistry::builder().topic_family("notes")?.build();

pub fn authorize() {
    Gate::define::<String, String>("live:topic.notes", |principal, instance| {
        instance == &format!("notes.{principal}")
    });
}

// src/bootstrap.rs
crate::live::authorize();
App::singleton(registry);
LiveTopics::resolve()?
    .on_model_scoped::<Note>("notes", |note| note.user_id.to_string(), &["stats"])?;

// src/controllers/dashboard.rs
#[derive(InertiaProps)]
#[inertia(live(topic = "notes", only = ["stats"]))]
pub struct DashboardProps {
    pub stats: Stats,
    pub recent_notes: Vec<NoteSummary>,
}

InertiaResponse::live::<DashboardProps>("Dashboard")
    .scope("notes", user_id)
    .load_with(move |response| async move {
        Ok(response
            .defer("stats", move || note_stats(user_id))
            .optional("recent_notes", move || recent_notes(user_id)))
    })
    .await?
    .resolve(&req)
    .await?;
```

Each frontend mounts its small `useLive()` adapter on `Dashboard`. A signal
asks Inertia to reload only `stats`; the controller recalculates it over the
signed-in user's own notes. Only the owner receives the instance signal or its cursor. The signal carries
no note values. The baseline is captured before the loader runs. `usePoll`
remains as the fallback when the browser cannot keep a push transport open.
See [Live topic bindings](frontend-pages.md#live-topic-bindings) for the page
contract and [Topic signals](live.md#topic-signals) for publication rules.

### Why Suprnova diverges

Laravel's Inertia kits do not include topic bindings. Suprnova's kits register
the note topic and install each frontend's adapter. They keep `usePoll` so
the dashboard updates when push delivery is unavailable.

The Svelte kit's pages show Inertia 3.8's client components at work:

- `layouts/AppLayout.svelte` and `layouts/GuestLayout.svelte` frame every
  page through `createInertiaApp`'s `layout` option and stay mounted across
  visits. They carry the `Link` navigation, the signed-in user's name and a
  sign-out `Link` (or sign-in and register links for a visitor), and the
  toast a handler flashes, which `components/FlashToast.svelte` reads from
  `page.flash`.
- `Dashboard` loads the note counts with `Deferred`, refreshes them from the
  `notes` Live topic, and keeps `usePoll` as a fallback. It loads the recent
  notes with `WhenVisible` once they scroll into view and sets the layout's
  heading with `setLayoutProps`. Its display-name form posts JSON through
  `useHttp` and shows the new name before the server answers.
- `Notes/Index` creates a note with the `Form` component, keeps its search
  box with `useRemember`, loads more notes with `InfiniteScroll`, and opens
  a note with a prefetched, instant `Link` to `Notes/Show`.
- The pages under `auth/` submit through the `Form` component, and every
  page titles its tab with the kit's `components/Head.svelte`.

For the code, see [Page Components](frontend-pages.md).
The React starter (`--frontend react`) runs on Inertia 3.8 through the
`@inertiajs/vite` plugin and shows the client side of each feature on a
page you can copy. `Dashboard` renders `stats` with `Deferred`, refreshes it
from the `notes` Live topic with `usePoll` as a fallback, loads
`recent_notes` with `WhenVisible`, and changes your display name through
`useHttp` with an optimistic update. `Notes/Index`
creates a note with `Form`, remembers its search with `useRemember`,
scrolls your notes with `InfiniteScroll`, and opens one with an instant,
prefetched `Link`; `Notes/Show` renders it. `Login`, `Register`,
`ForgotPassword`, `ResetPassword`, and `VerifyEmail` submit through `Form`.
Every page sets its title with `Head`, and the pages render inside a
guest layout (the `auth/` pages) or an application layout (the rest). Both
show the flash toast and, from the shared `auth` prop, the signed-in
user's name and a sign-out link or the sign-in and register links. See [Page Components](frontend-pages.md) for the
code.
The Vue kit (`--frontend vue`) runs on Inertia 3.8 and its Vite plugin, and
each page shows part of the client at work:

- `Dashboard.vue` loads the note counts as a deferred prop with `Deferred`,
  refreshes them from the `notes` Live topic with `usePoll` as a fallback,
  loads the recent notes with `WhenVisible`, and saves the display name
  through `useHttp` with an optimistic update.
- `Notes/Index.vue` creates a note with `Form`, remembers its search with
  `useRemember`, scrolls the signed-in user's notes with `InfiniteScroll`, and
  opens a note as an instant visit from a prefetching `Link`.
- `Notes/Show.vue` shows one of the signed-in user's notes.
- The five pages under `auth/` submit through `Form`.
- `layouts/AppLayout.vue` and `layouts/GuestLayout.vue`, applied through the
  `layout` option, carry the navigation, the flash toast from
  `components/FlashToast.vue`, and the account links from
  `components/AccountLinks.vue`: the signed-in user's name and a sign-out
  button, or the sign-in and register links for a guest. Every page titles
  its tab with `Head`.

### Static publication

All three Inertia kits install `src/lib/static/index.ts` through
`createInertiaApp`'s `http` option. Their adapters share the same
`src/lib/static/core.ts`. Without publication metadata the original
Inertia XHR transport runs unchanged.

A published document supplies its asset version in
`<meta name="suprnova-static-version" content="...">` and its concrete
public page paths in the JSON script `suprnova-static-pages`. Navigation
between those pages reads the versioned JSON object the map names. The
browser history keeps the page's canonical URL. A different asset version
reloads that canonical document. A full visit to a path absent from the map
reaches its canonical origin URL, where a marked public page can be published
on its first visit.

Partial reloads, polling, deferred props, once props, queries and mutations
use the original route with `?__suprnova_origin=1`. Existing query values
are kept. This URL bypasses publication, and both the request and response
carry `Cache-Control: no-store`. Flash and validation errors are accepted
from this private origin response; a published object containing either
falls back to the origin.

Before a mutation from a published document, the client obtains the
same-origin `XSRF-TOKEN` cookie from a private origin request if it is
missing. Inertia's XHR client reads the current cookie for every request
and sends it as `X-XSRF-TOKEN`, including after a sign-in rotates it. No
session token is embedded in a published document.

### Agents in the Inertia kits

The React, Vue and Svelte kits serve [agents](agents.md) from the first
`cargo run`: the MCP endpoint at `/mcp`, the OAuth server an MCP client signs
its user in through, and agent accounts under auth.md. `src/agents.rs` turns
them on, and `cmd/main.rs` serves the routes through `agents::serve`. The
kit replaces the framework's three default pages with its own, rendered by
`src/controllers/agents.rs` in the kit's frontend:

The browser helpers use the community's `webmcp-types` 0.1.10 definitions,
pinned in `devDependencies`, to check their registrations and annotations.

| Page | Route | What the user does there |
|---|---|---|
| `Agents/Approve` | `GET /oauth/approve` | Allows or denies an MCP client. The page names the client, its host, every permission it asks for and the address the user returns to. |
| `Agents/Claim` | `GET /agent/claim` | Lets an agent act for them, with the code the agent gave them. A wrong code comes back as the field's error with the attempts left. |
| `Agents/Connected` | `GET /connected-agents` | Sees and revokes every app and agent that acts for them. The app layout links it as **Agents**. |

The paths of the first two are the framework's defaults, so a link a client
or an agent holds opens the same page with or without the kit. A guest who
opens either one signs in and comes back: the sign-in page keeps a
`return_to` that is a path on this application, and a registration in the
same session keeps it too. A `return_to` that a browser would read as
another site, such as `//evil.example`, is ignored, and the user goes to the
dashboard.

The pages read and record what the user decides through `AgentApprovals`,
`AgentClaims` and `ConnectedAgents`, which act for the signed-in user only.
Approving a client needs a signed-in user, as the dashboard does. Claiming
an agent needs the address the agent named, verified: the claim page tells
an unverified user to verify first. A few rules hold on every page:

- Each route runs `ConsentPageHeaders`, so another site can't frame the
  page, and no cache or referrer keeps the authorization id or the claim's
  attempt token. The rest of the security headers policy, its nonce among
  it, stays as `SecurityHeaders` sets it.
- The global CSRF middleware checks every form.
- A decision leaves for the client by a location visit
  (`Inertia::location`), which the browser follows itself. A redirect that
  answers the form would be blocked by the policy's `form-action 'self'`.
- No page offers a tool, and no consent route declares one, so an agent in
  the browser can never approve a client or claim itself. A form tool marks
  the form it submits with the `Suprnova-Form-Tool` header, and the pages
  refuse it with a 403, so even a form tool an application adds to one of
  them cannot approve or claim.
- Text a client, an agent or the user chose sits in `<bdi>`, and no page
  renders raw HTML or loads a URL the client chose.

`suprnova new` writes a signing key for agent auth into `.env`, as
`AGENT_AUTH_KEY_ID` and `AGENT_AUTH_PRIVATE_KEY`. The application doesn't
start without one. Every other environment needs its own key, so a deploy
that doesn't copy `.env`, such as the production image, sets both
variables. `cargo run -- agents:key` prints a new pair. For rotation, see
[Keys and operations](agents.md#keys-and-operations).

The kit ships two [tools](agents.md#tools) on the signed-in user's own
notes, so the MCP endpoint has something to list from the first run.
`src/controllers/note_tools.rs` defines them, and `src/agents.rs` declares
their scopes with [`tool_scopes!`](agents.md#declare-scopes), in
`agents::scope`:

| Tool | Route | Scope | What it does |
|---|---|---|---|
| `search_notes` | `GET /notes/search` | `notes:read`, "Read your notes" | Finds the user's notes by the words in their titles and text, best match first, or lists the newest. It takes `query`, up to 200 characters, and `limit`, 1 to 50 and 10 when left out. |
| `create_note` | `POST /notes/tools` | `notes:write`, "Write notes for you" | Writes a note for the user, with the notes form's rules: a `title` of 1 to 255 characters and an optional `body` of up to 10000. It answers the note. |

Both tools accept users and agents, and each call acts for one user: the
one signed in, the one who approved the client, or the one who claimed the
agent. A client's token holds the scopes the user allowed on the approval
page, which shows each scope by its description. An agent holds both scopes
once a user claims it, and none before: an agent no user has claimed gets a
403 with `insufficient_scope`. `search_notes` is marked `read_only` and
`untrusted_content`, because it hands back note text, which the user wrote
and an agent must not take as instructions.

The notes page offers both tools to an agent in the user's browser, through
`.with_tools(["search_notes", "create_note"])` on its route. It is the only
page that offers a tool, and a guest is never offered either. After
`create_note`,
the page reloads its props, so the list shows the new note.
`frontend/src/types/tool-schemas.ts` carries both inputs, as
`SearchNotesInput` and `CreateNoteInput`.

To call the tools from Claude Code, run the project with `suprnova serve`
and add its endpoint, over the Streamable HTTP transport, at the URL
`APP_URL` names in `.env`:

```bash
claude mcp add my-app --transport http http://localhost:8765/mcp
```

Claude Code connects without a token and lists both notes tools. Calling
one answers 401, and Claude Code reports that the server needs you to sign
in; run `/mcp` to sign in. The client gets its token from the kit's OAuth
server: it registers, sends you to the approval page to allow the scopes it
asks for, and from then on lists the tools those scopes reach. A token with
`notes:read` alone sees `search_notes` and not `create_note`. See
[Users who approve a client](agents.md#users-who-approve-a-client).

### Why Suprnova diverges

Laravel's starter kits ship a dashboard with placeholder content and no list
page. Suprnova's scaffold lists the signed-in user's own notes, so deferred
and optional props, cursor scrolling, a JSON form, and flashed toasts each
have a working server to talk to. No handler lists accounts: a directory of
users would show every member the name and email of every other member.

## The API kit

For API-only services, `suprnova new my-api --api` initializes Magnetar,
installs bearer-session middleware, and scaffolds password registration and
login against the canonical `app_users` table without a frontend.

### Agents in the API kit

`suprnova new my-api --api` serves agents from `src/agents.rs`: the MCP
endpoint at `/mcp`, the OAuth server that MCP clients sign users in through,
and agent accounts under auth.md. For what each of these does, see
[Agents](agents.md). The kit has no frontend, so it serves the framework's
own pages, which are plain HTML with no script:

| Page | Path | What the signed-in user does there |
|---|---|---|
| Approval | `/oauth/approve` | Allows or denies an MCP client |
| Claim | `/agent/claim` | Enters the code an agent gives them |
| Connected agents | `/oauth/connected` | Sees and revokes the clients and agents that act for them |

`src/agents.rs` names each path once, as a constant, and gives the same
constants to the OAuth server, agent auth, the sign-in page and the session.

#### The consent sign-in

A person approves a client or claims an agent in a browser, so these pages
act for the user of a browser session. The kit signs a browser in at
`/login` (`src/controllers/sign_in.rs`) for them:

1. A guest who opens the approval or claim page is sent to
   `/login?return_to=...`.
2. The guest signs in with their email address and password, through
   `Auth::password()`.
3. The page continues to the address in `return_to`. Only a path on this
   application is kept: an address such as `//evil.example` or
   `https://evil.example` sends the user to `/oauth/connected` instead.

The page is fixed markup with one value in it, the session's CSRF token. Its
routes carry `ConsentPageHeaders`, so it is never framed, cached, or sent as
a referrer, and its form posts through the route's `CsrfMiddleware`. An
account with a second factor is told that the page does not offer one, and
stays signed out. To let those users approve clients, add the factor
challenge to the page.

#### Email verification

A claim needs the user's email address verified, so the kit verifies it with
a link, through `Auth::email_verification()`
(`src/controllers/email_verification.rs`):

1. Registration mails a new account the link, once. Registering an address
   that already has an account mails nothing. `POST /api/auth/register`
   takes six requests a minute from one client address, and answers `429`
   past that.
2. A signed-in client asks for a new link with
   `POST /api/email/verification-notification`. It answers `202` when it
   mails one, and `204` when the address is already verified. The route
   takes six requests a minute, and one address gets at most three links
   an hour, the registration's included; past either it answers `429`.
3. The link opens `/email/verify?token=...` in a browser. A guest is sent
   to `/login` and comes back, and the page then verifies the address of
   the user signed in there.

The link works once and expires after 24 hours. It verifies only for the
account's own user: anyone can register another person's address with a
password of their own, and a link that verified whoever opened it would
verify that account. It also proves only the address it was mailed to: once
the account's address is another, the page answers `409` and verifies
nothing, and the user asks for a new link. Verifying with one link spends
the account's other links. Verifying changes no credential and starts no
session. The mail comes from `MAIL_FROM`, and names the application as
`APP_NAME`.

A new API project's `.env` mails as the other kits' does: through a local
SMTP catcher on port 1025 (maildev, mailpit or mailhog), from
`hello@example.com`. Set a real relay and sender for production, which
refuses an unencrypted connection. When the link cannot be mailed,
registration still answers `202` and logs the failure, and the resend
route answers `500`.

#### Sessions on the consent pages only

`bootstrap.rs` registers `agents::ConsentSession`, which runs the session
middleware on these paths and no others:

- `/login`, the sign-in page, and its form.
- `/logout`, where the sign-out form posts.
- `/oauth/authorize`, `/oauth/approve` and `/oauth/authorizations/{id}`,
  where a user approves a client.
- `/oauth/connected` and the revoke forms under it.
- `/agent/claim` and its form.
- `/email/verify`, the page the verification link opens.

Every other route serves a client of the JSON API, an MCP client, or an
agent, which sign in with a bearer token: `/api/*`, `/mcp`, the
`/.well-known/*` documents, the token, registration and revocation
endpoints, and agent auth's JSON routes. None of them starts a session or
sets a cookie, so no client or agent can create a session row per request,
and the JSON sign-in at `POST /api/auth/login` returns a token and nothing
else. The migrator creates the `sessions` table, and the session settings
are the `SESSION_*` variables in [Environment variables](env-vars.md), with
two exceptions. A consent session ends after 15 minutes without a request
(`agents::CONSENT_SESSION_IDLE`), and its cookie has no expiry, so the
browser drops it when it closes. The kit adds no global CSRF middleware, so
the JSON API still takes no token.

A signed-in user ends the session at once with the **Sign out** form, which
posts to `/logout` with the session's CSRF token. The form is on the email
verification page, the page a signed-in user sees: `/login` sends a user who
is already signed in straight on. Signing out ends the session, and the next
approval or claim asks for a sign-in again.

`bootstrap.rs` also registers a `DatabaseUserProvider` over `app_users`, so
`Auth::user()` finds the user a bearer token or a consent page's session
signed in.

#### Connected agents over JSON

A client of the JSON API lists and revokes the same connections as the
connected-agents page. The routes sit behind `AuthMiddleware` beside the
user directory, and act for the user of the bearer token from
`POST /api/auth/login`:

| Route | Answer |
|---|---|
| `GET /api/connected-agents` | `200` with `{"clients": [...], "agents": [...]}`, each newest first |
| `DELETE /api/connected-agents/clients/{grant}` | `204`, or `404` with `{"message": "No such connected app."}` |
| `DELETE /api/connected-agents/agents/{registration}` | `204`, or `404` with `{"message": "No such connected agent."}` |

```bash
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  http://localhost:8765/api/connected-agents
```

An id that belongs to another user answers `404`. An MCP access token is
not a sign-in to this API, so it gets `401` here. Revoking takes `DELETE`,
never `POST`: a plain form on another site can send `POST`, and the JSON
API runs no CSRF check. For the fields of each entry, see
[Connected agents](agents.md#connected-agents).

#### The signing key in production

`suprnova new` writes a signing key for agent auth into `.env` as
`AGENT_AUTH_KEY_ID` and `AGENT_AUTH_PRIVATE_KEY`. A deploy that does not
copy `.env` must set both variables, and the application does not start
without them. To print a new pair, run `cargo run -- agents:key`. Outside
the local and testing environments, also set `APP_URL`: it is the OAuth
server's issuer. For more about keys, see
[Keys and operations](agents.md#keys-and-operations).

#### Why the kit ships no browser helpers

The Inertia kits ship browser helpers that offer a page's tools to an agent
in the browser (see [Tools in the browser](agents.md#tools-in-the-browser)).
The API kit has no pages of its own to offer tools on, so it ships none. An
application that adds a frontend adds the helpers with it.

## The Live starter kit

`suprnova new my-app --frontend live` scaffolds the same application as the
Inertia kits without a frontend build: no `frontend/` directory, no
`package.json`, and no Bun toolchain. Every page is a server-rendered
[Live](live.md) document. The application serves the Live browser runtime
under `/__live/assets/` and the library components' stylesheets and scripts
under `/suprnova-ui/`, so the backend is the only process you run.

The kit keeps the backend the Inertia kits share: the `users` and `notes`
tables and models, `Note::owned_by(user_id)` as the one way to read notes,
the account flows through `Auth`, `PasswordReset`, and
`EmailVerification`, and the route names. Pages render and act through Live
instead of Inertia:

| Page | Route | Layout | Live components |
|---|---|---|---|
| Welcome | `/` | application | none |
| Sign in | `/login` | guest | `LoginForm` |
| Register | `/register` | guest | `RegisterForm` |
| Forgot password | `/forgot-password` | guest | `ForgotPasswordForm` |
| Reset password | `/reset-password` | guest | `ResetPasswordForm` |
| Verify email | `/verify-email` | guest | `VerifyEmail` |
| Dashboard | `/dashboard` | application | `NoteStats`, `ProfileName` |
| Notes | `/notes` | application | `NoteForm`, `NoteList` |
| A note | `/notes/{id}` | application | none |
| Error | any failed request | application | none |

The forms on the guest pages are public seeds, which any visitor can use.
Every other island is identity-bound: it belongs to the signed-in user, and
its route sits behind the `auth` middleware.

### Files

The kit adds these files to the shared backend:

- `src/controllers/` - one controller per page. Each opens the request's
  `LiveDocument`, mounts the page's islands from `live::mounts()`, and
  renders the page's view.
- `src/views/mod.rs` - the view structs and `Frame`, the part both layouts
  read: the title, the Live bootstrap tags, the signed-in user, the CSRF
  token of the sign-out form, and the toast.
- `templates/live/layouts/` - `guest.html` for the account pages and
  `app.html` for the rest, with the header bar, the account menu, and the
  toast region. `head.html` holds the bootstrap tags and the stylesheet
  links both layouts include.
- `templates/live/pages/` - one template per page. Each starts with
  `{% extends "live/layouts/app.html" %}` or the guest layout.
- `src/live/` and `templates/live/*.html` - the Live components and their
  views, registered in `src/live/mod.rs`.
- `templates/suprnova-ui/` - the library components the views import,
  installed the way `suprnova live:add` installs them and recorded in
  `suprnova.toml`, so a later `live:add` keeps them current.
- `src/flash.rs` - the `Toast` a finished flow shows on the next page.
- `src/controllers/errors.rs` - the `ErrorPage` middleware, which renders
  every framework error response as the error page in the application
  layout, keeping the response's status, its other headers and its error
  report. A client that expects JSON keeps the JSON body, and in debug mode
  a `5xx` keeps the development error page.
- `src/controllers/profile.rs` - `POST /profile/name`, the JSON endpoint
  the Inertia kits ship for the display name; the dashboard's island saves
  it through Live.
- `public/css/app.css` - the page layout, written with the same `--sn-`
  tokens the library uses.

### What each component does

- `LoginForm`, `RegisterForm`, `ForgotPasswordForm`, and
  `ResetPasswordForm` check their fields with the same rules as the Inertia
  kits' form requests and show each message under its field. An action
  that succeeds signs the user in, mails a link, or rotates the password,
  then sends the browser to the next page with a toast.
- `VerifyEmail` names the address the link went to and mails a new link on
  request.
- `NoteStats` shows the user's note count, the notes written today, and the
  five newest notes. It subscribes to the stream `notes/:principal`, which
  Live fills with the user's own id. Saving a note publishes a refresh on
  that topic, so every dashboard the user has open renders again without a
  page load, over server-sent events or a WebSocket, and through polling
  when neither connects. Its **Refresh** button renders it again on
  request.
- `ProfileName` changes the display name and reloads the dashboard, so the
  navigation shows the new name.
- `NoteForm` checks the title (1 to 255 characters) and the text (at most
  10000 characters), saves the note, and reloads the list with a toast.
- `NoteList` filters the notes by title and text. The applied search is
  bound to the `?search=` query: each search puts it in the address bar
  without a history entry, and the page mounts the list from it, so a
  reloaded or shared URL shows the same list. **Load more** adds 10 notes
  at a time.

A finished flow keeps its `Toast` in the session, and the next document
takes it with `Toast::take()`, which removes it. The toast is an ordinary
session value rather than a session flash, because a flash ages on every
request of the session, the Live requests included. Saving a note makes
your open dashboards refresh, and that refresh would age a flashed toast
away before the redirect lands. The kit also turns session blocking on
(`SESSION_BLOCK=true` in `.env`), so the requests of one session run one
at a time and a refresh cannot write over the toast a save just kept.

### Agents in the Live kit

The kit serves the MCP endpoint, the OAuth server that MCP clients sign
users in through, and agent accounts under auth.md, all from
`src/agents.rs` (see [Agents](agents.md)). Three pages of its own let the
person decide what acts for them:

| Page | Route | What it shows |
|---|---|---|
| Approve an app | `/oauth/approve` | The client, its host, each permission it asks for and where the user returns, with **Allow** and **Deny** |
| Claim an agent | `/agent/claim` | The agent that asks to act as the user, the account it would act for, and a form that takes the code the agent gave them |
| Connected agents | `/connected-agents` | Every MCP client and agent that acts for the signed-in user, each with a **Revoke** button |

The header and the account menu link the connected-agents page. The paths
are the framework's defaults, so a link a client or an agent holds opens the
same page with or without the kit.

These pages are plain server-rendered documents with native forms, not
Live documents. They mount no island and load no Live runtime, so no agent
in the browser is offered a tool that approves or claims: consent comes
from the person. Each form posts the session's CSRF token.
`src/controllers/agents.rs` reads and records each decision with
`AgentApprovals`, `AgentClaims` and `ConnectedAgents`, which act for the
signed-in user only. Another user's authorization reads as ended, and
their grants as unknown.

A guest who opens the approval or the claim page signs in and comes back
to it. A guest who registers instead comes back too, in the same browser
session. The address is not carried across email verification, and the
claim page asks an unverified address to verify first. A Live action can
only redirect to a named route, so the sign-in and registration forms
continue through `/login/continue` (`login.continue`), which follows the
address the session holds. A `return_to` that names another host is
ignored.

The routes run `ConsentPageHeaders`. No page or refusal here is framed,
cached or named in a referrer, since their addresses carry the
authorization id or the claim's attempt token. The kit's other security
headers stay, nonce policy included. That policy carries
`form-action 'self'`, under which a browser blocks a redirect that answers
a form post on another origin. So **Allow** and **Deny** answer with a page
that sends the browser on to the client's redirect URI by a meta refresh,
with a link beside it. Every name, host and address a client, an agent or
the user chose sits in `<bdi>`, and no page shows a logo or links a page
the client chose.

`suprnova new` writes a signing key for agent auth into `.env`:
`AGENT_AUTH_KEY_ID` and `AGENT_AUTH_PRIVATE_KEY`. The application does not
start without them. `.dockerignore` keeps `.env` out of the image, so every
deployed environment sets both itself, each with a key of its own, and
names its public URL in `APP_URL`, which is the OAuth server's issuer. This
command prints a new pair and writes nothing:

```bash
cargo run -- agents:key
```

`tests/documents.rs` renders the connected-agents page and the approval
page's refusal. A test process loads no `.env`, so the test calls
`suprnova::testing::install_test_agent_auth_key()` for a key made for the
process, and registers an `AppConfig` with a URL of its own. See
[Agents](agents.md#keys-and-operations) for rotating the key.

Like the Inertia kits, the kit ships two [tools](agents.md#tools) on the
signed-in user's own notes, from the same `src/controllers/note_tools.rs`,
with their scopes declared by [`tool_scopes!`](agents.md#declare-scopes) in
`src/agents.rs`:

| Tool | Route | Scope | What it does |
|---|---|---|---|
| `search_notes` | `GET /notes/search` | `notes:read`, "Read your notes" | Finds the user's notes by the words in their titles and text, best match first, or lists the newest. It takes `query`, up to 200 characters, and `limit`, 1 to 50 and 10 when left out. |
| `create_note` | `POST /notes/tools` | `notes:write`, "Write notes for you" | Writes a note for the user, with the note form's rules: a `title` of 1 to 255 characters and an optional `body` of up to 10000. It answers the note. |

Each call acts for one user: the one signed in, the one who approved the
client, or the one who claimed the agent. A client's token holds the scopes
the user allowed on the approval page, and an agent holds both once a user
claims it and none before, so an agent no user has claimed gets a 403 with
`insufficient_scope`. `search_notes` is marked `read_only` and
`untrusted_content`, because the note text it hands back is the user's, not
instructions for an agent.

The notes page is the one page that offers tools: its route names both with
`.with_tools(["search_notes", "create_note"])`, and the document's head
carries them in its `suprnova-agent-tools` element, which the Live runtime
registers with WebMCP. A guest is never offered either. After
`create_note`, the runtime renders the page's islands again, so the list
shows the new note.

To call the tools from Claude Code, run the project with `suprnova serve`
and add its endpoint, over the Streamable HTTP transport, at the URL
`APP_URL` names in `.env`:

```bash
claude mcp add my-app --transport http http://localhost:8765/mcp
```

Claude Code connects without a token and lists both notes tools. Calling
one answers 401, and Claude Code reports that the server needs you to sign
in; run `/mcp` to sign in. The client gets its token from the kit's OAuth
server: it registers, sends you to the approval page to allow the scopes it
asks for, and from then on lists the tools those scopes reach. See
[Users who approve a client](agents.md#users-who-approve-a-client).

### Add a page

To add a page, give it a route, a view, and a controller:

1. Add the route to `src/routes.rs`, in the authenticated group if the page
   needs a user.
2. Add the view struct to `src/views/mod.rs`, and its template to
   `templates/live/pages/`, starting with the layout it extends.
3. Write the controller. Open the request's `LiveDocument`, mount the
   page's islands, then build the `Frame`, which emits the bootstrap tags
   after the last mount, and render the view.
4. Declare the page in `live::routes()` in `src/live/mod.rs`: with
   `.try_live_document("/path")?` when it mounts no island, or with a
   `LiveMount` in `Mounts` and `.try_live_mount(&mounts.name)?` for each
   island.

An `/about` page with no island looks like this:

```rust
// src/views/mod.rs
#[suprnova::view(path = "live/pages/about.html")]
pub struct AboutPage {
    pub frame: Frame,
}

// src/controllers/about.rs
use suprnova::live::LiveDocument;
use suprnova::{FrameworkError, HttpResponse, Request, Response, handler};

use crate::views::{self, AboutPage, Frame, Nav};

#[handler]
pub async fn show(req: Request) -> Response {
    Ok(page(&req).await?)
}

async fn page(req: &Request) -> Result<HttpResponse, FrameworkError> {
    let mut document = LiveDocument::from_request(req)?;
    let frame = Frame::live(&mut document, "About", Nav::None).await?;
    views::render(document, "live/pages/about.html", &AboutPage { frame })
}
```

```html
{% extends "live/layouts/app.html" %}
{% block content %}
<h1 class="kit-page-title">About</h1>
{% endblock %}
```

### Add a component

1. Run `suprnova live:make Invoices`. It writes `src/live/invoices.rs` and
   `templates/live/invoices.html` and registers the component.
2. Add a `LiveMount` for it to `Mounts` in `src/live/mod.rs`:
   `LiveMount::identity_bound` when it belongs to the signed-in user, or
   `LiveMount::public_seed` when any visitor may use it. Seal it in
   `live::routes()` with `.try_live_mount(&mounts.invoices)?`, and mount it
   from the page's controller.
3. To use another library component in its view, run
   `suprnova live:add <name>` and link the component's stylesheet in
   `templates/live/layouts/head.html`.
4. Run `suprnova live:check` to prove every view against its component.

### Why Suprnova diverges

Laravel's Livewire starter kit renders Blade views with Livewire
components, and still builds its assets with Vite. The Live kit has no
build step: the framework serves the Live runtime, and the component
library ships as files the scaffold installs into your project, which you
own and edit like any other view.

## Contributing a starter kit

Built something reusable on top of Suprnova and want to upstream it as a
canonical kit? See [Contributions](contributions.md). We're happy to take a
real implementation and round it into a generic kit.

The React, Vue, Svelte and Live scaffolds also ship `tests/page_budget.rs`. It audits
`/`, `/login`, `/register`, `/forgot-password` and `/reset-password` through the
application router and middleware. It creates an isolated test database and
sets the test environment in a child process before runtime threads start.
The Inertia tests audit the router `cmd/main.rs` serves, Live routes and
RenderCache included, follow built assets when a Vite manifest exists and run
before the frontend build on a fresh scaffold. The Live test boots its
component registry and runtime and audits its served styles and scripts. See [Page Budget](page-budget.md).

```bash
cargo test --test page_budget
```

The repository checks the generated tests and origin asset policy in
`suprnova-cli/tests/kit_budget.rs`; an ignored test there scaffolds each kit
and runs its page budget test. The dogfood application has its own
`app/tests/page_budget.rs` test over its public entry pages.

Every kit is held to the browser suite in `suprnova-cli/tests/kit_browser/`.
Run `cargo test -p suprnova-cli --test kit_browser -- --ignored --test-threads=1`
from the repository root. The harness scaffolds all three kits, builds one
backend against the in-tree framework, builds each frontend, and runs the
same Chromium assertions over each served application. It uses the existing
Playwright browser cache; it does not install browsers. Failed runs print
the kit name, the browser output, the server log, and the retained artifact
directory.

The Live kit is held to `suprnova-cli/tests/kit_live.rs` and to
`live_kit_compiles_and_renders` in `suprnova-cli/tests/scaffold_snapshot.rs`,
which builds a fresh Live scaffold against the in-tree framework, starts it,
and requests its pages:
`cargo test -p suprnova-cli --test scaffold_snapshot -- --ignored live_`.

## Next

Define page subscriptions with [Live topic bindings](frontend-pages.md#live-topic-bindings).
Register shared topics and model changes with [Live](live.md#topic-signals).


---

<!-- /docs/deployment -->

# Deployment Overview

A Suprnova app compiles to a single self-contained binary that owns
the web server, the migration runner, the scheduler, and the queue
worker. Deploying is "copy the binary, set four environment variables,
run it." This chapter covers what those four variables are, what the
binary's subcommands do in production, and how the built-in health
endpoint integrates with a platform's liveness probe. Platform-specific
walkthroughs follow in [Railway](deployment-railway.md),
[Digital Ocean](deployment-digital-ocean.md), and
[Hetzner](deployment-hetzner.md).

## The single binary

Your app builds to one binary with a clap subcommand surface:

```bash
./app                       # serve (default) - auto-migrate, then HTTP
./app serve                 # explicit serve, with auto-migrate
./app serve --no-migrate    # serve without running migrations
./app web:run               # alias for serve

./app migrate               # apply pending migrations and exit
./app migrate:status        # show migration status
./app migrate:rollback [N]  # roll back the last N migrations (default 1)
./app migrate:fresh         # drop all tables, then re-migrate - in production
                            # this needs --force AND a typed confirmation on an
                            # interactive terminal; see cli-migrations.md

./app schedule:work         # scheduler daemon - wakes every minute
./app schedule:run          # run due tasks once and exit
./app schedule:list         # print every registered task
./app queue:work            # queue worker daemon
./app workflow:work         # workflow worker daemon

./app down [--secret …] [--retry …] [--except …] [--message …]
./app up                    # leave maintenance mode
```

One binary means one Docker image, one CI artifact, one deployment to
verify. The same image runs the web service, the scheduler, the queue
worker, and the workflow worker - you start a different subcommand
for each.

## Four production environment variables

Suprnova fails closed on boot if the production environment is
misconfigured. The minimum set to deploy:

| Variable | What it does | Failure mode |
|---|---|---|
| `APP_ENV` | Selects the environment (`production`, `staging`, etc.). | Defaults to `local` if unset - your app runs in dev mode in prod. |
| `APP_KEY` | 32-byte AES-256 base64 key for `Crypt`, sessions, cookies, and pagination cursors. | Boot returns a typed error and exits non-zero when `APP_ENV` is not local/dev/test and `APP_KEY` is missing or malformed. |
| `APP_URL` | Canonical absolute URL of your app (`https://app.example.com`). | Defaults to `http://localhost:8765`; signed URLs, redirects, mail links, and absolute Inertia URLs all use this. |
| `DATABASE_URL` | Connection URL for your relational database. | Boot refuses to start when `APP_ENV` is `production` or `staging` and `DATABASE_URL` is unset - the dev SQLite fallback is rejected explicitly. |

Generate `APP_KEY` once with the CLI:

```bash
suprnova key:generate           # writes APP_KEY=… into ./.env
suprnova key:generate --show    # prints the key for $(…)
```

For key rotation, see [Encryption](encryption.md) -
`APP_KEY_PREVIOUS` (or the Laravel-compatible `APP_PREVIOUS_KEYS`)
takes a comma-separated list of older keys for decrypt-only fallback.

Beyond the four required vars, common production knobs:

| Variable | Default | Notes |
|---|---|---|
| `SERVER_HOST` | `127.0.0.1` | Use `0.0.0.0` in containers. |
| `SERVER_PORT` | `8765` | Match your platform's expected port. |
| `APP_DEBUG` | env-derived | `false` in production/staging/custom envs. Set explicitly if you want loud errors in staging. |
| `SERVER_MAX_BODY_SIZE` | per-handler default | Process-wide request body cap. |
| `SERVER_MAX_CONNECTIONS` | `10000` | Cap on concurrent active TCP connections. See below. |
| `SERVER_HEALTH_READINESS_TOKEN` | unset (readiness is public) | Shared secret required to reach the readiness probe. See [Health check](#health-check). |
| `DB_MAX_CONNECTIONS` | `10` | Pool size. |
| `REDIS_URL` | unset | Required if you've configured the Redis cache/queue/session drivers. |

The full table lives in [Environment Variables](env-vars.md).

## Recommended database: MariaDB

Suprnova supports SQLite, PostgreSQL, MySQL, and MariaDB as first-class
relational backends. The recommendation is environment-specific:

- **Development.** SQLite. The scaffolder writes
  `DATABASE_URL=sqlite://./database.db` so `suprnova serve` works
  with zero database setup.
- **Production.** MariaDB. It collapses what would otherwise be three
  separate services (relational + vector + KV cache) onto one engine,
  with system-versioned tables for audit if you need them.

```bash
# .env.production
DATABASE_URL=mysql://app_user:secret@db.internal:3306/app_production
```

Use the `mysql://` or the `mariadb://` scheme. Both select the MySQL family
driver, which handles MariaDB natively. The framework accepts `mariadb://`
for the primary connection, named connections, read replicas, the migrator
and `MariaDbVectorDriver::from_url`. `DB::driver_title()` returns `MariaDB`
for a `mariadb://` URL and `MySQL` for a `mysql://` URL, because the URL is
the only thing that tells them apart. Suprnova's `MariaDbVectorDriver`
(`VECTOR(N)` + HNSW) hooks in directly for vector workloads.

```bash
DATABASE_URL=mariadb://app_user:secret@db.internal:3306/app_production
```

The other relational backends are first-class too:

```bash
# PostgreSQL
DATABASE_URL=postgres://app_user:secret@db.internal:5432/app_production

# MySQL
DATABASE_URL=mysql://app_user:secret@db.internal:3306/app_production

# SQLite (for tiny single-instance deploys)
DATABASE_URL=sqlite:///var/lib/myapp/data.db
```

### Why Suprnova diverges

Laravel's defaults nudge new projects toward PostgreSQL because PHP +
PostgreSQL is the well-trodden path. Suprnova picks the database that
gives the cleanest single-engine production posture for a Rust app.
MariaDB's `VECTOR(N)` (11.7+), Dynamic Columns, and system-versioned
tables mean a small-to-mid product can ship search, KV, and audit
without bolting on Redis, OpenSearch, or pgvector. PostgreSQL stays
fully supported - the framework's test matrix runs against all three
relational backends - but our deployment docs lead with the engine
that minimises moving parts. See
[Vector Storage](vector.md) and [Database](database.md) for the
backend-specific surfaces.

## Building a production image

The scaffolder ships a generator for a multi-stage Dockerfile:

```bash
suprnova docker:init
```

This writes a `Dockerfile` with three stages:

1. **Frontend build** - `node:20-alpine`, runs `npm ci && npm run build`
   against your `frontend/` Inertia app (Svelte 5, React 19, or Vue 3.5
   per your scaffold choice).
2. **Backend build** - `rust:1.94.0-slim-bookworm`, compiles your crate in
   release mode with dependency caching.
3. **Runtime** - `debian:bookworm-slim`, copies the compiled binary,
   the Vite output, and your schema dumps (`database/schema`), installs
   the database client the `DB_CLIENT` build argument names
   (`postgresql-client` unless you change it), runs as a non-root
   `appuser`, exposes port 8765, and runs `CMD ["./app"]` (the
   auto-migrating server). The client lets the server load a schema dump
   into a new, empty database; see
   [Squashing migrations](migrations.md#squashing-migrations).

Current `main` also upgrades the database stack to SeaORM 2.0, SeaQuery 1.0,
and SQLx 0.9. Direct SeaORM code must import `ExprTrait` for expression methods
and use explicit `*_raw` methods for prebuilt `Statement` values. Existing
application data requires no migration.

Build and run locally to verify before pushing:

```bash
docker build -t myapp .

# With an env file
docker run --rm -p 8765:8765 --env-file .env.production myapp

# Or with explicit vars (the four required ones)
docker run --rm -p 8765:8765 \
  -e APP_ENV=production \
  -e APP_KEY=$APP_KEY \
  -e APP_URL=https://app.example.com \
  -e DATABASE_URL=mysql://user:pass@host:3306/app \
  myapp
```

Never commit `.env.production` (or any file containing `APP_KEY` or
`DATABASE_URL`) to your repo. Use your platform's secrets store and
read the values at deploy time.

## Production build shape

The binary the Dockerfile builds never carries the framework's `testing`
feature - the encryption-key installers, storage fakes, and RenderCache
test hooks that a test suite needs are compiled out. Your scaffolded
`Cargo.toml` (and the dogfood app in the Suprnova repository itself) takes
this shape by construction with two dependency entries:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", default-features = false, features = [
    "filesystem", "database-sqlite", "database-postgres", "database-mysql",
    "vector-mariadb", "vector-pgvector", "web-push", "localization", "magnetar-oauth",
    "media",
    "queue-sqs",
    "reporting-sentry",
    "search-media",
    "agents",
] }

[dev-dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", features = ["testing"] }
```

The production entry turns default features off and lists the fourteen that
stay on (every default except `testing`). The dev-dependency turns
`testing` back on - Cargo's feature resolver only pulls in a
dev-dependency's features for `cargo test` and other `--tests` builds, so
`cargo build --bin app` (or `--bin console`) never sees it. `testing` is a
dev-dependency feature only: nothing in your own `src/` or `cmd/` should
turn it on for a binary target.

The framework repository proves this holds with a small crate whose only
job is to fail to compile: it references every framework item gated
behind `testing` by path, and the release gate checks that referencing
them without the feature is a compile error while referencing them with
it succeeds.

## Migrations on boot

The default `./app` (and explicit `./app serve`) command applies any
pending migrations before binding the socket. The two practical
implications:

- **Safe with multiple instances.** SeaORM's migration runner takes a
  database-level advisory lock; the slowest pod waits, the others
  proceed once it's done. You do not need a separate "migrate-then-deploy"
  step for routine release rolls.
- **Failed migration = failed deploy.** If a migration errors, the
  process exits non-zero before the server binds. The platform's
  health probe (see below) reports the pod unhealthy, and the rollout
  halts. Fix forward by shipping a corrective migration in the next
  release.

For CI pipelines that want to gate the deploy on a successful migration
before any pod accepts traffic, run migrations in a one-shot:

```bash
docker run --rm myapp ./app migrate
# … then roll the actual deploy
docker run myapp ./app serve --no-migrate
```

`--no-migrate` skips the auto-migrate phase but still boots the server
normally.

## Workers as separate services

The scheduler, queue, and workflow systems each have their own daemon
subcommand. In production, run them as separate processes against the
same image, sharing the same environment:

```bash
docker run myapp ./app schedule:work    # one instance - see below
docker run myapp ./app queue:work       # scale to N instances
docker run myapp ./app workflow:work    # scale to N instances
```

Two rules to internalise:

- **Either run exactly one `schedule:work` process, or mark your tasks
  `.on_one_server()`.** Scheduler replicas do not coordinate by default:
  each evaluates the schedule independently, so three replicas run every
  due task three times. `replicas: 1` is the simple answer;
  `.on_one_server()` elects one replica per tick against a shared cache
  and is what you want if the scheduler has to be highly available. See
  [Scheduling](scheduling.md#running-on-one-server).
- **Queue and workflow workers scale horizontally.** Both pull work
  from a shared store and use visibility timeouts or row-level locks
  to coordinate; adding pods adds throughput. `./app queue:work
  --max-jobs N` makes the worker exit after N jobs so a supervisor can
  rotate the process - useful for release-on-restart deploys.

See [Queues](queues.md), [Scheduling](scheduling.md), and
[Workflows](workflows.md) for the per-subsystem detail.

## Stopping cleanly

Every long-running Suprnova process - the server and all three daemons -
drains on **SIGTERM** as well as SIGINT. SIGTERM is what `docker stop`,
Coolify, systemd and Kubernetes send; SIGINT is what Ctrl-C sends. Both
take the same path: stop accepting new work, finish what is in flight
within a bounded grace, exit `0`.

The grace windows are per-subsystem and bounded on purpose - one slow
client or one long task must not be able to keep a process alive
indefinitely:

| Process | Waits for | Grace |
|---|---|---|
| `serve` | in-flight HTTP connections | 5s |
| `queue:work` | the in-flight job to settle | until the job returns |
| `schedule:work` | `.run_in_background()` tasks | 30s |
| `workflow:work` | in-flight workflow steps | until they return |

Each of them then waits up to ten more seconds for the queued event
listeners still running, so a listener a job or a request started is
not cut off; so does `schedule:run` once its tasks have run. See
[Events](events.md#draining-on-shutdown).

**Size your platform's termination grace above these.** Docker defaults
to 10 seconds, Kubernetes to 30. If the platform's window is shorter than
the work takes, it sends SIGKILL and you are back to losing in-flight
jobs:

```yaml
# docker compose
services:
  worker:
    command: ["app", "queue:work"]
    stop_grace_period: 60s
```

```yaml
# kubernetes
spec:
  terminationGracePeriodSeconds: 60
```

**A job killed mid-flight is not lost, but it does cost an attempt.** Its
reservation lapses and another worker reclaims it, charging one attempt
so a job that reliably kills its worker can still be dead-lettered rather
than cycling forever. See [Queues](queues.md#what-counts-as-an-attempt).

**PID 1 is a real constraint.** A container entrypoint runs as PID 1, and
the kernel does not apply default signal dispositions to PID 1 - a
process with no SIGTERM handler does not die on SIGTERM, it ignores it
until the platform gives up and sends SIGKILL. Suprnova installs the
handler, so `CMD ["app", "queue:work"]` is fine as written and no `tini`
shim is required.

## Health check

Suprnova exposes three built-in health paths. The `_suprnova/` prefix is
reserved so your own routes can never collide with them.

| Path | Touches | Use for |
|---|---|---|
| `/_suprnova/health/live` | nothing | Liveness. Answers 200 for as long as the process can serve a request. |
| `/_suprnova/health/ready` | the database | Readiness. 503 when a dependency is unreachable. |
| `/_suprnova/health` | nothing, or the database with `?db=true` | The original endpoint. Behaves as either of the above. |

```bash
curl http://localhost:8765/_suprnova/health/live
# 200 {"status":"ok","timestamp":"2026-05-30T12:34:56+00:00"}

curl http://localhost:8765/_suprnova/health/ready
# Healthy:  200 {"status":"ok","timestamp":"…","database":"connected"}
# Degraded: 503 {"status":"degraded","timestamp":"…","database":"error"}
```

`/_suprnova/health` and `/_suprnova/health?db=true` keep working exactly
as before, and nothing you have already deployed needs changing - the
[Hetzner guide](deployment-hetzner.md) still names them for one-off
checks, and so may your own specs. The named paths are clearer, so
prefer them in new configuration; the [Railway](deployment-railway.md),
[DigitalOcean](deployment-digital-ocean.md) and [Docker](cli-docker.md)
guides use them.

### Use the right probe for the right question

Point liveness at `/live` and readiness at `/ready`. The distinction
matters more than it looks: a failed **liveness** probe restarts the pod,
while a failed **readiness** probe only pulls it out of the load
balancer. Wire a database check into liveness and a database blip
restarts every replica you have - at the exact moment the database can
least afford a thundering herd of reconnects.

```yaml
livenessProbe:
  httpGet:
    path: /_suprnova/health/live
    port: 8765
readinessProbe:
  httpGet:
    path: /_suprnova/health/ready
    port: 8765
```

The endpoint short-circuits before the middleware chain so it stays
responsive even if a middleware deadlocks or the request id middleware
is rejecting traffic.

### Degraded responses do not carry driver detail

The 503 body reports `"database":"error"` and nothing more. The driver's
own message - which names hosts, ports, database and schema names and
server versions, and for some configuration errors the connection URL -
goes to the log at `error!` level, where an operator can read it and a
stranger cannot. In debug builds it is also included in the body as
`database_error`, so local debugging is unaffected.

### Closing readiness off

Readiness runs a database round trip for whoever asks. If the endpoint is
internet-reachable, set a shared secret:

```bash
SERVER_HEALTH_READINESS_TOKEN=<a long random string>
```

Probes must then send it as a header:

```bash
curl -H "X-Suprnova-Health-Token: $SERVER_HEALTH_READINESS_TOKEN" \
  http://localhost:8765/_suprnova/health/ready
```

```yaml
readinessProbe:
  httpGet:
    path: /_suprnova/health/ready
    port: 8765
    httpHeaders:
      - name: X-Suprnova-Health-Token
        value: <the same value>
```

Without the header, readiness answers **404** - the same response as any
path that does not exist, so the endpoint is invisible rather than merely
closed. Liveness stays public either way, so you do not have to put the
secret in every manifest to keep your restart-on-hang signal.

Unset is the default, and readiness is public. That is deliberate: the
configurations this manual and the scaffolder generate all call
`?db=true` without a header, and defaulting to closed would break them.

## Maintenance mode

To roll a destructive migration or quiesce traffic for an incident:

```bash
./app down --secret abc123 \
           --retry 60 \
           --message "Deploying - back in a few minutes" \
           --except /webhooks/stripe

./app up
```

`down` writes a maintenance marker the middleware reads on every
request. Requests get a 503 (configurable via `--status`) with the
provided message, except for paths in `--except` and any request that
includes the secret. `up` removes the marker.

The secret is a bearer credential: anyone who visits `/<secret>` is issued
a bypass cookie good for 12 hours. The deadline is sealed inside the
encrypted cookie and re-checked on every request, so a captured cookie
stops working on time even if the browser ignores its `max-age`. A cookie
whose deadline is further out than one TTL is refused, with a short
allowance for clock differences between hosts. Both the URL match and the
cookie's secret comparison run in constant time, so response timing does
not tell a prober how long a prefix they guessed correctly. Prefer
`--with-secret`, which mints one for you (16 random bytes, 32 hex
characters) and prints the bypass URL, over picking a memorable string for
`--secret` - and treat it like any other credential in your incident
notes.

`down` prints what it did, in Laravel's words:

```text
Application is now in maintenance mode.
You may bypass maintenance mode via [https://example.com/abc123].
```

A `down` while the application is already down updates the options and
prints `Maintenance mode options updated.` instead. The bypass address is
`APP_URL` followed by the secret. When `down` cannot record maintenance
mode, it prints `Failed to enter maintenance mode: <error>.` and exits
with a failing status.

`--retry` takes a number of seconds or a date. A date is sent as the
`Retry-After` header in the RFC 7231 form, so a client reads when to come
back:

```bash
./app down --retry "Sat, 01 Jan 2033 00:00:00 GMT"
./app down --retry 2033-01-01T00:00:00Z     # the same header
```

`--render <view>` renders the Tera template at
`resources/views/<view>` once, when you run `down`, and serves the result
as the maintenance page. The template reads `retry_after`: the seconds or
the date of `--retry`, and empty without one. A template that cannot be
read or rendered fails `down` before maintenance mode starts, so a typo
never takes the site down with a broken page. `--render` and `--message`
exclude each other.

```html
<!-- resources/views/errors/503.html -->
<h1>Back soon</h1>
<p>Try again after {{ retry_after }}.</p>
```

```bash
./app down --render errors/503.html --retry 600
```

After it records maintenance mode, `down` dispatches the
`MaintenanceModeEnabled` event, which carries no data. Listen for it to
tell a status page or the people on call:

```rust
use suprnova::{EventFacade, FrameworkError, Listener, MaintenanceModeEnabled, async_trait};
use std::sync::Arc;

struct TellTheStatusPage;

#[async_trait]
impl Listener<MaintenanceModeEnabled> for TellTheStatusPage {
    async fn handle(&self, _event: &MaintenanceModeEnabled) -> Result<(), FrameworkError> {
        // Post to the status page here.
        Ok(())
    }
}

// In bootstrap::register():
pub async fn register() {
    EventFacade::listen::<MaintenanceModeEnabled, _>(Arc::new(TellTheStatusPage)).await;
}
```

A listener that fails is logged, and `down` still reports the state it
recorded: maintenance mode is on either way. Scheduled tasks skip their
runs while the application is down, unless they ask
`even_in_maintenance_mode()`; see [Scheduling](scheduling.md).

### Why Suprnova diverges

Laravel drops a `--retry` value that is neither a number nor a date it
can parse, and sends no `Retry-After`. Suprnova refuses it, so the header
you asked for is the one clients get. Laravel renders `--render` with a
Blade view; Suprnova renders a Tera template with `retry_after` in its
context.

## Serving under a path prefix

A reverse proxy can serve the application under a path, such as
`https://example.org/billing`, and strip that path before it forwards the
request. The application then receives `/invoices/7` for the browser's
`/billing/invoices/7`. Routes still match on the path the application
receives, so you don't change a single route. Every URL the framework hands
the browser has to carry the stripped path again, and the proxy tells the
framework what it is with the `X-Forwarded-Prefix` header.

This nginx location serves an application listening on port 8000 under
`/billing`:

```nginx
location /billing/ {
    proxy_pass http://127.0.0.1:8000/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /billing;
}
```

The trailing slash on `proxy_pass` is what strips `/billing`. Caddy does the
same with `handle_path`:

```text
example.org {
    handle_path /billing/* {
        reverse_proxy 127.0.0.1:8000 {
            header_up X-Forwarded-Prefix /billing
        }
    }
}
```

Then trust the proxy, and give `APP_URL` the prefix too:

```bash
APP_TRUSTED_PROXIES=127.0.0.1
APP_URL=https://example.org/billing
```

### The trust rule

The framework reads `X-Forwarded-Prefix` under the rule every other
forwarded header follows: only when the TCP peer is listed in
`APP_TRUSTED_PROXIES`. From any other peer the header is ignored. The proxy
sets or clears `X-Forwarded-Prefix` on every request it forwards, as it does
for `X-Forwarded-For`. A proxy that passes a client's header on as it came
lets the client choose the root of every URL the application builds.

A trusted value counts only when it is a clean path: ASCII letters, digits,
`-`, `.`, `_`, `~` and `/`, starting with `/`, not ending with `/`, and with
no empty, `.` or `..` segment. A header sent on two lines is ignored whole. A
trusted `/` means the application is at the host root, and an empty value is
ignored. An ignored value leaves the root to `APP_URL`.

### The public root

The public root is the trusted prefix when the request carries one,
otherwise the path in `APP_URL`, which is also the root outside a request:
in console commands, queued jobs and mail. A trusted prefix replaces the
`APP_URL` path, so the two never add up to `/billing/billing`. At the host
root the root is empty.

The framework puts the root in front of every URL it builds for the
browser: `route()` and the signed URLs, `url::to`, `url::current`,
`Request::url`, every redirect, the Inertia page URL and its Vite tags, Live's
endpoints and assets, the localization catalog, pagination links and a
`Storage::url` with a root-relative base. A path that already carries the
root, such as the output of `route()`, keeps it once.

A template writes the root with `url::root()`, which returns `/billing`
under the prefix and the empty string at the host root:

```html
<link rel="stylesheet" href="{{ suprnova::url::root() }}/suprnova-ui/button/button.css">
```

An Inertia frontend gets the root as the `root` prop, which `RootShare`
shares with every page. A scaffolded application registers it, and its pages
post to `` `${root}/login` ``, so the same frontend build runs at `/` and
under `/billing`.

Mail and job links are built outside a request, where no header arrives. A
deployment whose mail and job links must work behind a header-only prefix
sets the prefix in `APP_URL` as well, as the example above does.

### Cookies

When the application sets no cookie path, the session, XSRF, remember-me and
maintenance bypass cookies take the root of each request as their `Path`, so
two applications under `/a` and `/b` on one host keep separate sessions. A
`__Host-` cookie keeps `Path=/`, as the browser requires. Two applications
that share a host and both use `__Host-` cookies need distinct cookie names,
set with `SESSION_COOKIE`.

When a browser sends two cookies of one name, the framework reads the first.
The browser lists the cookie with the longer path first, so after you move an
application under a prefix, a session cookie left over at `Path=/` cannot
shadow the one scoped to the root.

### Routes that begin with the prefix

The framework tells a path that carries the root from an application path by
its first segment. An application whose own routes begin with its
deployment prefix, such as a `/billing` route group behind a proxy that
serves `/billing`, can't be told apart, so don't give an application routes
that begin with the prefix. Let the proxy strip it instead.

### Why Suprnova diverges

- **A trailing slash is ignored, not trimmed.** Symfony trims a trailing
  slash from `X-Forwarded-Prefix`. Suprnova ignores a value that ends with
  `/`, so each root has one spelling and two spellings never mean two cache
  keys or two cookie paths. Send `/billing`, not `/billing/`.
- **The relative `route()` carries the root.** Laravel's
  `route($name, $parameters, false)` strips the base URL. Suprnova's
  `route()` is relative and keeps the root, so a redirect or a link built
  from it works behind the prefix.
- **The `APP_URL` path is the root when no prefix header arrives.** Laravel
  reads the root from the request alone. Suprnova falls back to the path in
  `APP_URL`, so console commands, jobs and mail build the same URLs as a
  request does.

## Scaling

### Web

Horizontal scaling is the default story: every pod runs `./app`,
shares `DATABASE_URL`, and connects to the same Redis (if you've
configured Redis-backed cache/queue/session). Auto-migration is safe
because of the advisory lock above. Sticky sessions are not required -
session state lives in your session driver (database or Redis),
not in process memory.

### Workers

- **Scheduler.** Exactly one instance, always.
- **Queue.** Scale horizontally. If you've split work across multiple
  named queues, run a worker per queue (or pass driver-specific queue
  filters - see [Queues](queues.md)).
- **Workflow.** Scale horizontally; row-level claim/heartbeat
  coordinates the workers.

## Connection cap (`SERVER_MAX_CONNECTIONS`)

The server caps concurrent TCP connections at 10000 by default. The
header and body deadlines bound how long each connection lasts; the cap
bounds how many there are, so a crowd of slow clients cannot use up the
process's file descriptors. In most deployments a reverse proxy (nginx,
Caddy, Traefik) or the platform's load balancer provides the first line
of defence, and the cap is the backstop inside the process. To change
it, set `SERVER_MAX_CONNECTIONS`:

```bash
# .env.production - cap concurrent connections at 1024
SERVER_MAX_CONNECTIONS=1024
```

When the cap is reached the **accept loop blocks** (back-pressure at the
TCP level) until an existing connection closes; the pending handshake
remains in the kernel's accept backlog. The permit is held for the full
lifetime of each connection and released the moment the connection ends,
so slots turn over promptly.

Rules of thumb:

- **Unset (default = 10000).** Suits most deployments. Raise it if the
  process holds more long-lived connections (WebSocket, SSE) than that at
  peak.
- **Set to a concrete value** to size the cap to your traffic. A typical
  starting point is 2 × your expected peak concurrent users, adjusted
  upward for long-lived connections (WebSocket, SSE).
- **Pair with `LimitNOFILE`** (systemd) or `ulimit -n` so the OS
  file-descriptor limit doesn't become the surprise cap. Each HTTP
  connection costs one file descriptor; add your database pool size and
  a few dozen for OS housekeeping. Many systems start at 1024, below the
  default cap, so raise the limit or lower the cap to fit.
- **This is a backstop, not a replacement for upstream rate limiting.**
  `SERVER_MAX_CONNECTIONS` stops runaway accumulation; your reverse
  proxy or `rate_limit` middleware should handle per-client or per-IP
  throttling.

A blank value is the same as unset. A zero or unparseable value logs a
warning and falls back to 10000 rather than removing the cap, so a typo
neither stops the server from starting nor leaves it without a cap.

No value of `SERVER_MAX_CONNECTIONS` removes the cap. A server with no cap
is a choice made in code. Make it only when a reverse proxy or the
platform already limits connections and the file-descriptor limit is set
to match:

```rust
use suprnova::{Config, ServerConfig};

Config::register(ServerConfig::builder().unbounded_connections().build());
```

## Heap profiling

To see where a deployment's memory goes, build it with the framework's
`heap-profiling` feature. The framework then installs [dhat]'s
allocator for the whole process, and `#[suprnova::main]` starts its
profiler before anything else runs. A new application has the feature
already, passed through to the framework:

```toml
[features]
heap-profiling = ["suprnova/heap-profiling"]
```

Build it with the `profiling` profile, the release profile with debug
symbols, so the profile's stacks name your functions:

```bash
cargo build --profile profiling --features heap-profiling
SUPRNOVA_HEAP_PROFILE=/tmp/heap.json ./target/profiling/app serve
```

When the process ends normally - a command that finishes, or a server
or worker you stop with SIGTERM or Ctrl-C - it writes the profile and
prints the totals:

```text
dhat: Total:     533,023,630 bytes in 1,144,769 blocks
dhat: At t-gmax: 949,716 bytes in 4,412 blocks
dhat: At t-end:  492,592 bytes in 2,417 blocks
```

The total is everything the process allocated, `t-gmax` the heap at
its peak, and `t-end` what was still allocated when it ended. Open the
file in DHAT's viewer (`dh_view.html`) to see which call stacks
allocated what. Without `SUPRNOVA_HEAP_PROFILE` the file is
`dhat-heap.json` in the working directory.

A profile is written only when the process ends normally: a process
that is killed, or that calls `std::process::exit`, writes none. The
profiler records a backtrace for every allocation, so the process runs
slower while it measures; build a profiling binary for the
investigation, not for production. An application with its own
`#[global_allocator]` cannot turn the feature on, since a process has
only one allocator.

The `profiling` profile on its own also suits a sampling profiler such
as `samply` or `perf`.

[dhat]: https://docs.rs/dhat

## Per-platform walkthroughs

The recipe above ports to every modern PaaS or VPS. The next three
chapters walk you through the specifics:

| Platform | Style | Walkthrough |
|---|---|---|
| Railway | PaaS with auto-deploy from git | [Deploy to Railway](deployment-railway.md) |
| Digital Ocean | App Platform (PaaS) or Droplets (VPS) | [Deploy to Digital Ocean](deployment-digital-ocean.md) |
| Hetzner | VPS with systemd + Caddy | [Deploy to Hetzner](deployment-hetzner.md) |

## Next

- [Environment Variables](env-vars.md) - every env var the framework reads
- [Encryption](encryption.md) - `APP_KEY`, key rotation, what's encrypted
- [Configuration](configuration.md) - typed config sections built on top of env
- [Database](database.md) - driver selection, pool tuning, multi-connection split
- [Queues](queues.md) - worker scaling and queue drivers


# Architecture Concepts

---

<!-- /docs/lifecycle -->

# Request Lifecycle

What actually happens between the TCP packet hitting the socket and
your handler returning a `Response`? Six files. Trace them once and
the framework's shape clicks into place.

## The path

```mermaid
flowchart TD
    bind["bind socket - server.rs"]
    accept["hyper accepts - HTTP/1.1 · h2 · WebSocket"]
    handle["handle_request<br/>WS upgrade? · health endpoint? · task-locals"]
    inner["handle_request_inner<br/>match_route · build the chain"]
    chain["execute_chain_safely<br/>panic boundary · middleware · handler"]
    resp(["HttpResponse on the wire"])

    bind --> accept --> handle --> inner --> chain --> resp
```

## 1. Boot - `app.rs`

A scaffolded app's `main()` builds an `Application` fluently and runs
it:

```rust
Application::new()
    .config(my_app::config::register)
    .bootstrap(my_app::bootstrap::bootstrap)
    .http_bootstrap(|| async { my_app::bootstrap::register_http_stack() })
    .routes(my_app::routes::register)
    .migrations::<my_app::migrations::Migrator>()
    .run()
    .await
```

`Application::run()` parses the binary's CLI (clap):

- `serve` - start the HTTP server
- `web:run` - alias for serve
- `migrate` / `migrate:rollback` / `migrate:status` / `migrate:fresh`
- `schedule:run` / `schedule:work` / `schedule:list`
- `workflow:work`
- `queue:work`
- `down` / `up` - toggle maintenance mode

`db:sync` and `db:seed` live on the framework-wide `suprnova` CLI
binary (`suprnova-cli`) and the per-app `cmd/console` binary
respectively - not on the `Application::run()` switch.

`.env` is already loaded by this point. `#[suprnova::main]` loads it
*before* building the Tokio runtime, because writing to the process
environment is only sound while the process is single-threaded - see
[Bootstrap](bootstrap.md#suprnovamain-not-tokiomain). `Application::run`
refuses to boot if that step was skipped.

For `serve`, it then:

1. Verifies the environment was loaded from a single-threaded context
2. Drains the `#[policy]` inventory into the authorization system
3. Calls your `config_fn` (typed config registration)
4. Runs migrations
5. Calls your `bootstrap_fn` (service registration, observers, listeners)
6. Calls your `http_bootstrap_fn` (global middleware, `Inertia::install`)
7. Builds the `Router` from `routes_fn`
8. Hands the router to `Server::from_config(...)`
9. Calls `server.run()`

Every other subcommand, and the console binary, runs one shared boot
after the steps before migrations: your `bootstrap_fn`, then the log
channels, the container's `#[injectable]` and `#[service]` inventory,
the `#[policy]` gates, and the runtime drivers the command uses. So a
worker, a `queue:*` command, `down`, and a console command see the same
configured services and bound container values as the server - but
they never call `http_bootstrap_fn`. Only `serve` / `web:run` does. See
[Application Bootstrap](bootstrap.md) for why: `Inertia::install` fails
closed when the built frontend manifest is missing, and a worker or
console image is expected to ship without one. The migration commands
run no `bootstrap_fn`, as `serve` runs its migrations before it.

## 2. Server boot - `server.rs`

`Server::from_config` does two things that matter for safety:

- Runs `App::init()` + `App::boot_services()` - initialises the
  container's task-local layer and resolves boot-time dependencies
- **Fails closed** when `APP_KEY` is required (any non-development
  environment) but missing/malformed - returns `Err`, and `app.rs`
  prints a remediation message and exits non-zero instead of panicking

`server.run()` then:

1. Boots telemetry (`tracing` subscriber, log format)
2. Loads encryption keys (`APP_KEY` + `APP_KEY_PREVIOUS`)
3. Boots the runtime drivers **in this exact order**: Cache → Queue →
   RateLimit → Mail. Non-server subcommands also call
   `bootstrap_runtime_drivers` so workers see the same drivers
4. Binds the TCP socket
5. Serves over hyper with `.with_upgrades()` (so WebSocket upgrades work)

The driver boot order is intentional - Queue may depend on Cache
(for unique-job locks), RateLimit may use Cache, Mail may dispatch
via Queue.

## 3. Request entry - `handle_request`

Every request lands in `handle_request(router, registry, req)`.
**This is also the in-process request surface integration tests
drive without opening a socket.** It's re-exported as
`suprnova::handle_request`.

```rust
pub async fn handle_request(
    router: Arc<Router>,
    middleware_registry: Arc<MiddlewareRegistry>,
    req: hyper::Request<hyper::body::Incoming>,
) -> hyper::Response<ServerBody>;
```

A peer-aware variant, `handle_request_with_peer`, takes the same
arguments plus an `Option<std::net::IpAddr>` - the production accept
loop uses it; in-process callers use `handle_request` and the request's
proxy headers (or `None`) determine `Request::ip()`.

Inside, it:

1. Checks for a WebSocket upgrade via `router.match_ws(...)` - if it
   matches a `ws!()` route, hands off to the WS handler
2. Special-cases the built-in health endpoints - `GET /_suprnova/health`,
   `/_suprnova/health/live`, `/_suprnova/health/ready`. A readiness probe
   that fails the `SERVER_HEALTH_READINESS_TOKEN` check is deliberately
   *not* special-cased: it falls through to routing and 404s like any
   unrouted path, so the endpoint is invisible rather than merely closed
3. Installs per-request task-locals (flash bag, SSR-disable flag)
4. Dispatches into `handle_request_inner`

## 4. Routing + chain assembly - `handle_request_inner`

This is where the middleware chain composes. The router yields a
`(pattern, handler, params)` triple, and the `MiddlewareChain` is
assembled in this fixed order:

```
[0] RequestIdMiddleware (always outermost)
[1] global middleware in registration order
[2] route middleware (keyed by (method, matched pattern))
[3] handler
```

Three things to notice:

- **Pattern, not path.** Route middleware is keyed by the matched
  pattern (`"/posts/{id}"`), not the raw path (`/posts/42`). Group
  middleware on parameterised routes actually fires.
- **No match still runs the chain.** If the router doesn't match any
  route, the chain (RequestId + globals) still runs and terminates in
  a registered fallback or a static 404. CORS preflight (OPTIONS rarely
  matches a route), logging, and request-id all reach unrouted traffic.
- **Group middleware is flattened, not stacked.** Group middleware is
  copied into each grouped route's middleware list at register time -
  it isn't a separate runtime layer. Introspection can't tell group
  from route middleware apart.

## 5. Panic boundary - `execute_chain_safely`

The chain runs inside `AssertUnwindSafe(...).catch_unwind()`. **A panic
in any middleware or the handler is caught**, logged with method+path,
and converted through the same `FrameworkError → HttpResponse` path
as a returned 5xx:

- Sanitised body: `{"message": "Internal Server Error"}`
- `request_id` injected so you can correlate with the log
- `ErrorOccurred` event dispatched so listeners (Sentry, your alert
  pipeline) see the failure
- The panic payload **never leaks into the response body**

This is a safety net, not a contract. Public APIs in your code should
return `Result`, not rely on `catch_unwind`. The boundary exists to
keep a buggy handler from killing the worker thread or leaking a stack
trace to the client - it isn't licence to `.unwrap()` everywhere.

## 6. Chain composition - `middleware/chain.rs`

`MiddlewareChain::execute` nests the handler as the innermost `Next`,
then wraps each middleware last-to-first (`.rev()`), so **the
first-added middleware runs first** (outside-in). An empty chain calls
the handler directly:

```
register order:   [Auth, CSRF, Throttle, handler]
runtime order:    Auth → CSRF → Throttle → handler → (back out)
```

If middleware short-circuits (returns `Err(response)`), the chain
unwinds immediately and the response goes back out through the
already-executed middleware in reverse.

## The `Response` contract

`http::Response` is **`Result<HttpResponse, HttpResponse>`** - both
arms carry an `HttpResponse`. Handlers and `Middleware::handle` return
`Response`:

- `Ok(resp)` is success
- `Err(resp)` short-circuits - for example, a 401 straight from auth
  middleware. The runtime collapses both with
  `result.unwrap_or_else(|e| e)`, so an `Err` is a response, not a
  crash.
- `?` propagates any error that converts to `HttpResponse`. Every
  `FrameworkError`, `AppError`, `ValidationErrors`, and your own
  `HttpError` impls do - so handler bodies read top-to-bottom and
  bubble failures to the converter.

The error converter (`From<FrameworkError> for HttpResponse`)
sanitises 5xx bodies and never leaks detail to the wire. The detail
stays in the structured log.

See [Error Handling](errors.md) and [Error Model](error-model.md) for
the full picture.

## Per-request state

Two layers of per-request state, both task-local:

- **Flash bag** - `req.flash()` returns the session flash; values stored
  here survive one redirect and then disappear
- **SSR-disable flag** - Inertia uses this to short-circuit
  server-side rendering in test contexts

Both are installed by `handle_request` before the chain runs and
torn down when the response leaves. Custom per-request state goes
through the `Context` system - see [Context](context.md).

## Workers reuse the same lifecycle

Background workers (`queue:work`, `workflow:work`, `schedule:run`) go
through:

1. The same boot path (`Config::init`, your `bootstrap()` function,
   then the container's services, the policies, and the runtime
   drivers) - **not** `http_bootstrap()`; that hook is server-only,
   which is what lets a worker image boot without a built frontend
   manifest
2. Their own loop that pulls work and runs handlers with the **same
   panic boundary** (`execute_chain_safely` equivalent for each worker
   type)
3. Graceful shutdown on `SIGTERM` / `SIGINT` - in-flight work finishes,
   no new work starts

This means an observer registered in `bootstrap()` fires for inserts
from a queue worker exactly as it would for inserts from an HTTP
handler.

## Production safety guarantees

A short list of invariants the lifecycle establishes:

- **`APP_KEY` is required in non-development environments.** Boot fails
  closed, exits non-zero, no encrypted-data corruption.
- **Panics in handler or middleware never reach the client.** The
  panic-boundary returns a sanitised 500 and dispatches `ErrorOccurred`.
- **5xx bodies are always sanitised.** Detail goes to the log, not the
  wire.
- **Poisoned locks never abort the process.** Two sanctioned patterns:
  per-request paths route poison into a `FrameworkError::Internal`
  carrying a `"<context> lock poisoned"` message (and the request
  gets a 500); hot-path registries that must stay up recover in place
  with `.unwrap_or_else(|e| e.into_inner())`. See
  [Lock Policy](lock-policy.md).
- **Driver backend failures are an explicit fail-open or fail-closed
  choice.** Rate-limit, cache, session each pick a policy at the call
  site - `BackendErrorPolicy::FailClosed` returns 503; `FailOpen`
  lets the request through. There is no implicit default. See
  [Rate Limiting](rate-limiting.md).
- **WebSocket upgrades go through the same router.** The same
  `match_ws` lookup uses the same `(method, pattern)` indexing as
  HTTP routes; you can apply per-route WS middleware exactly like
  HTTP middleware.
- **The shutdown signal is never starved by the connection cap.**
  Waiting for a free connection slot (`SERVER_MAX_CONNECTIONS`, 10000
  by default) races the shutdown signal rather than blocking the accept
  loop, so a server whose slots are all held by long-lived WebSocket
  sessions still drains on `SIGTERM` instead of being SIGKILLed at the
  end of the orchestrator's grace period.
- **Every drain aborts what it abandons.** HTTP connections, WebSocket
  handlers, post-response `Terminable` hooks, and supervisors each get
  a bounded grace window and are then aborted and awaited - including
  a supervisor's inner task, so
  cancellation reaches the body and not just the restart wrapper.
  Nothing keeps running past its drain to emit telemetry after the
  flush.

## What this means for your code

A few takeaways for day-to-day handler writing:

- **Return `Response`, propagate with `?`.** Don't `match err` unless
  you need the bare `HttpResponse`.
- **Implement `HttpError` on your domain error types.** They'll
  convert automatically. See [Error Handling](errors.md).
- **Don't rely on the panic boundary.** It catches genuine bugs and
  prevents process crashes; library code should still return `Result`.
- **Middleware order matters and is fixed in three layers** -
  request-id outermost, globals next, route middleware innermost
  before the handler.
- **Workers and handlers share `bootstrap`, not `http_bootstrap`.**
  Anything you register in `bootstrap` is visible to both; global
  middleware and `Inertia::install` belong in `http_bootstrap` and
  only run for the server.

## Where each step lives

| Step | File |
|---|---|
| Boot | `framework/src/app.rs` |
| Server lifecycle | `framework/src/server.rs` |
| `handle_request` (entry) | `framework/src/server.rs` (re-exported as `suprnova::handle_request`) |
| `handle_request_inner` (routing + chain) | `framework/src/server.rs` |
| `execute_chain_safely` (panic boundary) | `framework/src/server.rs` |
| `MiddlewareChain::execute` (composition) | `framework/src/middleware/chain.rs` |
| Router matching | `framework/src/routing/router.rs` |

You shouldn't need to read these to use the framework, but if a bug
surprises you, the trail is short.

## Next

- [Service Container](container.md) - how `App::*` resolves services
- [Application Bootstrap](bootstrap.md) - what `bootstrap.rs` does
- [Middleware](middleware.md) - writing your own middleware
- [Error Model](error-model.md) - `FrameworkError`, `HttpError`,
  panic recovery in detail
- [Routing](routing.md) - what `routes!` actually expands into


---

<!-- /docs/container -->

# Service Container

The container is where Suprnova holds your application's services -
the DB connection pool, the mail driver, your `Arc<MyService>`. You
bind values into it at boot time and resolve them in handlers and
workers. It's the Suprnova equivalent of Laravel's service container,
with one important difference: lookup is task-local first, so tests
running concurrently don't see each other's bindings.

## The two pieces

| Type | Role |
|---|---|
| `Container` | The underlying registry: holds bindings, factories, and singletons |
| `App` | The global facade you actually call - `App::bind`, `App::get`, etc. |

You almost always call `App::*` rather than constructing a
`Container` directly. The container is plumbing; the `App` facade
is the API.

## Lookup order

Every `App::get` / `App::make` call checks **three layers** in order:

```
        task-local
            │
            ▼  (miss)
       thread-local
            │
            ▼  (miss)
          global
            │
            ▼  (miss)
          None
```

The first two layers hold test overrides. The third holds your
application's bindings. This matters because:

- **Tests use task-local or thread-local** - `let _g = TestContainer::fake();`
  followed by `TestContainer::bind(...)` binds inside one thread
  without touching the global container, so parallel tests don't
  bleed services into each other. The guard clears the test
  container when it drops. `TestContainer::scope` does the same for one
  async task, and survives a move between worker threads.
- **App-wide services go through global** - bound once at boot,
  resolved everywhere. `App::bind`, `App::singleton`, `App::factory`
  and `App::scoped` all write to this layer.
- **A test override wins** - if a test binds a type in the first two
  layers, that binding answers, whatever the global layer holds for
  the same type.

A scoped binding sits in the global layer, but its value does not. The
container builds the value inside the scope of the current unit of
work. See [Scoped bindings](#appscoped-and-appbind_scoped---one-value-per-unit-of-work).

You rarely think about which layer a binding lives in - `App::get`
finds it wherever it lives. The model only matters when something
behaves unexpectedly under concurrency, and then the
[Testing](testing.md) chapter has the detail.

## Binding a value

These are the ways to put something into the container, depending on
what you have:

### `App::singleton(value)` - owned, cloned at lookup

For any `T: Any + Send + Sync + 'static` value that should live
forever. The `Clone` bound is on the *getter* (`App::get`), not the
binding - the value is stored once inside an `Arc` and cloned out of
that `Arc` on each `get`:

```rust
use suprnova::App;

App::singleton(MyConfig {
    timeout_secs: 30,
    retries: 3,
});

let cfg = App::get::<MyConfig>().expect("registered at boot");
println!("{}", cfg.timeout_secs);
```

The value is stored once; `App::get::<MyConfig>()` returns a clone.
Use this for plain config-shaped data that's cheap to clone.

### `App::bind(Arc<T>)` - for traits and shared services

For trait objects or anything you want behind an `Arc`:

```rust
use std::sync::Arc;
use suprnova::App;

let store: Arc<dyn KeyValueStore> = Arc::new(RedisStore::connect(url)?);
App::bind(store);

let store = App::make::<dyn KeyValueStore>().expect("bound at boot");
store.put("hello", b"world").await?;
```

`App::make::<T>()` returns the `Arc<T>` clone (cheap atomic refcount
bump). Use this for any service shared across threads, especially
trait objects.

### `App::factory(|| { … })` - built on every resolution

When each resolution should build a new value:

```rust
App::factory(|| {
    HttpClient::builder()
        .timeout(Duration::from_secs(30))
        .build()
        .expect("http client config is hand-rolled and known-good")
});
```

`App::factory` registers a *concrete-type* factory (`Fn() -> T`);
`App::bind_factory` registers a *trait-object* factory
(`Fn() -> Arc<T>`). Neither closure returns `Result` - handle
construction failure inside the closure (panic at boot, or build a
sentinel value) or use a regular `App::singleton` / `App::bind` after
constructing the value yourself with `?`. Both invoke the closure
outside any container lock, so a factory that re-enters the container
won't deadlock and an expensive constructor won't block other bindings.

### `App::singleton_lazy(|| { … })` - built on first use, then shared

When one value should serve the whole process, but building it is
costly or reads other bindings, register a lazy singleton. Its factory
runs at the first resolution, and every resolution after it shares that
value, as Laravel's `singleton` builds its concrete on first resolve:

```rust
use std::sync::Arc;
use suprnova::App;

// Nothing is built at boot.
App::singleton_lazy(|| Arc::new(SearchIndex::open("/var/lib/search")) as Arc<dyn Search>);

// The first resolution builds it; later ones share the same `Arc`.
let search = App::make::<dyn Search>().expect("registered at boot");
```

The value can be a concrete type, resolved with `App::get` or
`App::resolve`, or an `Arc<dyn Trait>`, resolved with `App::make` or
`App::resolve_make`. `App::singleton_lazy_if_absent` registers only when
nothing is bound for the type yet and answers whether it did, as
Laravel's `singletonIf` does; a binding already there stays, and its
factory never runs.

The factory runs with no container lock held, so it can resolve other
bindings. Threads that resolve the type while it is being built wait for
the value, so the factory runs once. A factory that resolves its own
type, directly or through other lazy singletons, gets an error that
names the type instead of waiting for a value it is still building. A
factory that panics leaves the value unbuilt, so the next resolution
runs it again. `Container::singleton_lazy` and
`TestContainer::singleton_lazy` do the same on their containers.

### `App::scoped` and `App::bind_scoped` - one value per unit of work

Some services belong to one request, and the next request must not
see them: the database handle of the current tenant, or an API client
bound to the caller. A singleton is one value for the whole process,
so it would leak between requests. A factory builds a new value on
every resolution, so it can't share one handle across a request.

A scoped binding sits between the two. You register a factory once.
The container runs it **at most once in a scope**, at the first
resolution, and returns the same value on every later resolution in
that scope. When the scope ends, the container drops the value. If
nothing resolves the binding in a scope, the factory never runs.

`App::scoped` registers a concrete-type factory (`Fn() -> T`). Resolve
it with `App::get` or `App::resolve`, which clone the value, so
register an `Arc<T>` when callers must share one instance.
`App::bind_scoped` registers a trait-object factory (`Fn() -> Arc<T>`).
Resolve it with `App::make` or `App::resolve_make`:

```rust
use std::sync::Arc;
use suprnova::{App, Context, FrameworkError};

// In bootstrap: the factory reads the tenant from the request's context.
App::scoped(|| {
    let tenant: String = Context::get("tenant_id").unwrap_or_default();
    Arc::new(TenantDb::connect_for(&tenant))
});

// Trait-object form, resolved with `App::make`:
App::bind_scoped::<dyn ApiClient, _>(|| {
    Arc::new(TenantApiClient::for_current_tenant()) as Arc<dyn ApiClient>
});

// In a handler or a service it calls: built on the first call, reused
// on the next, dropped when the request ends.
async fn load_orders() -> Result<Vec<Order>, FrameworkError> {
    let db = App::resolve::<Arc<TenantDb>>()?;
    db.orders().await
}
```

The factory runs with no container lock held, so it can resolve other
bindings, scoped ones included. If two tasks that share a scope resolve
the same binding at the same moment, the factory runs once. The second
task waits for the value on its own thread, which blocks that thread.
A factory must therefore be quick and must not block on I/O.

A cycle of scoped factories is an error. A factory that resolves its own
type, directly or through other scoped factories, gets an error instead of
recursing or waiting without end. This holds in one task and across the
tasks of one scope.

#### Which units of work get a scope

The framework opens a scope for each unit of work that it runs. A
unit of work has values of its own, so a job never sees the values of
the request that dispatched it.

| Unit of work | Scope |
|---|---|
| HTTP request, including a WebSocket upgrade request | One per request |
| WebSocket session | One per session, separate from the upgrade request |
| Attempt of a queued job | One per attempt, so a retry starts fresh |
| Queued event listener | One per attempt of the listener |
| Scheduled task run | One per run |
| Workflow run | One per claimed run. The steps of the run share it |
| Supervisor run | One per run, so a restart starts fresh |
| Console command | One per command |

Three kinds of work belong to a request but run after it. They share the
scope of the request, and the scope ends after they finish:

- An after-commit callback (see [Database](database.md)).
- A hook that runs after the response, such as a terminable middleware
  (see [Middleware](middleware.md)).
- The body of a streamed response, such as `HttpResponse::sse`,
  `stream_bytes` or `stream_json`. The stream resolves the scoped values of
  its request, and the body keeps the scope until it ends or is dropped.

#### Scopes in your own code

A task that you start with a bare `tokio::spawn` has no scope, even when
you spawn it from a request. Three helpers on `App` cover the cases:

- `App::run_scoped(future)` runs a future in a new scope of its own and
  returns its output. Use it for work the framework does not run, such
  as your own worker loop or a test. Inside another scope it opens a
  nested scope that does not see the outer values.
- `App::in_current_scope(future)` wraps a future so that it runs in the
  scope of the caller. The container captures the scope when you call
  it, so you can pass the result to any spawn helper.
- `App::spawn_scoped(future)` is `App::in_current_scope` followed by
  `tokio::spawn`.

A spawned task shares the values of the scope, so a binding that the task
resolves first is the value the request sees afterward. The scope ends
when the last future that holds it ends. Outside a scope, `in_current_scope`
and `spawn_scoped` behave like the plain future and `tokio::spawn`.

```rust
use suprnova::App;

// Inside a handler: the task sees the request's `dyn AuditLog`.
let handle = App::spawn_scoped(async {
    if let Some(log) = App::make::<dyn AuditLog>() {
        log.record("export finished");
    }
});

// Only the container scope follows the task. To carry the request id too,
// hand the wrapped future to `spawn_with_request_id`:
let handle = suprnova::spawn_with_request_id(App::in_current_scope(async {
    // ...
}));
```

#### Outside a scope

A scoped binding never builds a value that lives for the process. If
you resolve one where no scope is active:

- `App::resolve` and `App::resolve_make` return an error. Its message
  names the type and says that the binding is scoped.
- `App::get` and `App::make` log a warning and return `None`.

#### Order of resolution

The container looks up a type in this order:

1. A test override in the task-local layer.
2. A test override in the thread-local layer.
3. The global layer. A scoped binding resolves in the current scope.

A test override wins over a scoped binding of the same type. A type has
one registration in the global layer, so the last call wins: a
`singleton`, `factory` or `scoped` call for a type replaces an earlier
one for the same type.

### `App::*_if_absent(value)` - boot-order-friendly registration

Sometimes a default service is registered by a service crate, and the
app wants to override it only when present. The `_if_absent` variants
let you register a default that won't clobber an existing binding:

```rust
// Inside a starter or library crate:
App::singleton_if_absent(DefaultMailDriver::new());

// In your app's bootstrap.rs:
App::singleton(MyCustomMailDriver::new());  // wins because it ran later
```

`bind_if_absent`, `singleton_if_absent`, and the factory variants all
return `bool` - `true` if they actually inserted, `false` if there
was already a binding.

Boot registers every `#[injectable]` this way, so an instance you bind
by hand in `bootstrap.rs` is kept. Boot doesn't run the generated
constructor of a type that is already bound, either: a dependency that
only that constructor reads doesn't have to be registered.

### `#[service]` - registered at boot, chosen by environment

`#[service(impl = Concrete)]` on a trait registers `Concrete::default()`
when the application boots, unless the application bound the trait
first. `bind(Concrete, env = [...])` entries choose the implementation by
environment, as Laravel's `#[Bind]` attribute with `environments` does:

```rust
use suprnova::service;

#[service(
    impl = SmtpMailer,
    bind(LogMailer, env = ["local", "testing"]),
    bind(SandboxMailer, env = ["staging*"]),
)]
pub trait Mailer {
    fn send(&self, to: &str, body: &str);
}
```

At boot, the first entry with a pattern that matches
`Config::environment()` (`local`, `development`, `staging`, `production`,
`testing`, or a custom `APP_ENV`) is bound, and `impl` when no entry
matches. `*` matches any run of characters, and every other character
matches itself, case included. A trait with `bind` entries and no `impl`
stays unbound when no entry matches. See [Macros](macros.md#service).

## Resolving a value

Two read methods, plus their `Result`-returning siblings:

```rust
// Clone the bound value out:
let cfg: MyConfig = App::get::<MyConfig>().expect("bound at boot");

// Clone the Arc:
let store: Arc<dyn KeyValueStore> = App::make().expect("bound at boot");

// Same but Result, for the `?` idiom in fallible paths:
let cfg = App::resolve::<MyConfig>()?;
let store = App::resolve_make::<dyn KeyValueStore>()?;
```

`resolve` and `resolve_make` return
`Result<_, FrameworkError>` (specifically the `ServiceNotFound`
variant when the lookup misses) - useful in handler paths where a
missing service should surface as a 500 with a proper log, not a panic.
A [scoped binding](#appscoped-and-appbind_scoped---one-value-per-unit-of-work)
that cannot resolve is a different error: `resolve` returns
`FrameworkError::Internal`, and `get` and `make` log a warning and
return `None`. So is a lazy singleton whose factory resolves its own
type.

Membership checks (rarely needed):

```rust
if App::has::<MyConfig>() { … }
if App::has_binding::<dyn KeyValueStore>() { … }
```

## Where binding happens

The standard place is `src/bootstrap.rs` - one function that runs
once at boot:

```rust
use std::sync::Arc;
use suprnova::App;
use crate::services::{MyService, RealEmailGateway};

pub async fn register() {
    // Plain singletons
    App::singleton(MyAppConfig {
        max_uploads_per_user: 100,
    });

    // Trait-object services
    let gateway: Arc<dyn EmailGateway> = Arc::new(RealEmailGateway::new());
    App::bind(gateway);

    // A factory: a new client on every resolution
    App::bind_factory::<dyn HttpClient, _>(|| {
        Arc::new(ReqwestClient::with_timeout(30))
    });

    // A lazy singleton: built on first use, then shared
    App::singleton_lazy(|| Arc::new(SearchIndex::open("/var/lib/search")) as Arc<dyn Search>);
}
```

The function name `register` matches the scaffold default (`src/bootstrap.rs::register`); the return type is `()`, not `Result`. Bind errors that happen during boot (e.g. driver connect failures) should propagate via the driver/service constructor, not from `register` itself - see [Application Bootstrap](bootstrap.md) for the full boot wiring.

The framework also calls into the container itself during boot:

- Your `bootstrap_fn` runs first, so a binding you install by hand is
  in place before the inventory boots
- `App::init()` then initialises the registry, and
  `App::boot_services()` registers the `#[injectable]` and `#[service]`
  inventory around your bindings
- The runtime drivers come up last

The server, the workers, the `queue:*` commands, `down` and `up`, and
the console binary all boot in this order.

See [Application Bootstrap](bootstrap.md) for the full boot order.

## Inertia shared data

The container is also where Inertia shared data lives. Three
convenience APIs make that explicit:

```rust
use suprnova::App;

// Eager value - serialised once and reused for every Inertia response.
App::inertia_share("appName", "Suprnova");

// Lazy value - resolver runs per response. Use for per-request data
// that needs async work.
App::inertia_share_lazy("locale", || async {
    Ok::<_, suprnova::FrameworkError>(detect_locale().await)
});

// Push a single flash entry onto the per-request flash bag.
App::flash("message", "Saved!");
```

These read from `Container::inertia()` which returns
`&Arc<InertiaRegistry>` - you can interact with it directly if you
need lower-level access. See [Inertia / Frontend](frontend.md) for
how the shared data ends up in the page response.

## Why three layers?

The task-local → thread-local → global cascade exists for one
reason: **isolation under concurrency**. Two things benefit:

**Per-test isolation.** A test that binds a fake mail driver should
not see a fake bound by a sibling test. `TestContainer::fake()`
returns a thread-local guard, and `TestContainer::bind` /
`TestContainer::singleton` route writes into the active scope.
Parallel tests stay hermetic:

```rust
use std::sync::Arc;
use suprnova::container::testing::TestContainer;
use suprnova::suprnova_test;

#[suprnova_test]
async fn one_test_binds_a_fake() {
    let _guard = TestContainer::fake();
    TestContainer::bind::<dyn Mailer>(Arc::new(FakeMailer::new()));

    // … this test uses FakeMailer
    // a sibling test running in parallel doesn't see it
}
```

For multi-thread tokio runtimes - where the future may migrate between
worker threads - use `TestContainer::scope(async { ... })` instead;
that installs a task-local override that survives the migration.

**Override-at-boot.** Application code can override defaults registered
by library crates. The `_if_absent` variants and the layered lookup
combine to give library crates clean default-registration without
fighting application overrides.

The layers do not isolate requests from each other. A binding in the
global layer is one value for the whole process. To keep a value
inside one request, use a [scoped binding](#appscoped-and-appbind_scoped---one-value-per-unit-of-work).

## Common patterns

### Bind a struct holding the DB pool

You almost never do this directly - the framework binds the DB pool
itself. But if you have your own subsystem with an expensive
shared resource:

```rust
let pool = MyResourcePool::connect(url).await?;
App::bind(Arc::new(pool));

// later:
let pool = App::resolve_make::<MyResourcePool>()?;
let conn = pool.checkout().await?;
```

`App::make` returns `Option<Arc<T>>` and pairs with `.expect(...)`; `App::resolve_make` returns `Result<Arc<T>, FrameworkError::ServiceNotFound>` and pairs with `?` in fallible code. Use the one that matches your caller's error story.

### Swap a default for a fake in tests

```rust
use std::sync::Arc;
use suprnova::container::testing::TestContainer;
use suprnova::suprnova_test;

#[suprnova_test]
async fn order_dispatches_email() {
    let fake = Arc::new(FakeEmailGateway::new());
    let fake_for_assert = Arc::clone(&fake);

    let _guard = TestContainer::fake();
    TestContainer::bind::<dyn EmailGateway>(fake);

    place_order(123).await.expect("place_order succeeds");

    assert_eq!(fake_for_assert.sent_count(), 1);
}
```

### Lazy expensive construction

```rust
// Builds the embedding model on the first resolution, not at boot, and
// shares it afterwards.
App::singleton_lazy(|| {
    Arc::new(
        OnnxEmbedding::load_from_disk("/models/all-mini-lm.onnx")
            .expect("embedding model must load"),
    ) as Arc<dyn EmbeddingModel>
});
```

For fallible construction that needs to surface a structured error to
the operator, build the value yourself in `bootstrap()` with `?` and
call `App::bind(...)` once it's ready.

## Why Suprnova diverges

Laravel's container has one global scope - bindings are global, and
isolating between tests requires `setUp` / `tearDown` discipline plus
the framework's per-test database transaction. PHP's request-per-process
model makes this safe-by-accident: a fresh process per request means
the container is reset every time.

Rust's process model is the opposite - one process serves many
concurrent requests on many threads. A global-only container would
mean a test in one thread can see a fake bound by another, or a
request could see another request's per-request data. Suprnova
answers both problems:

- The three-layer cascade keeps tests apart: a task-local layer and a
  thread-local layer hold test overrides, and the global layer holds
  app-wide services.
- Scoped bindings keep requests apart. `App::scoped` is the Suprnova
  form of Laravel Octane's `scoped()` binding: the container builds
  the value once for one unit of work and drops it when that unit ends.

- `#[service]`'s environment entries are chosen once, at boot. Laravel
  reads a `#[Bind]` attribute each time it builds the class; a
  Suprnova binding is installed when the application boots and stays.

The container API is the same as Laravel's; the lookup machinery
is different because the runtime is different.

## Next

- [Application Bootstrap](bootstrap.md) - where the binding code goes
- [Configuration](configuration.md) - typed config registration
  alongside services
- [Testing](testing.md) - `TestContainer::fake` and `#[suprnova_test]`
- [Lock Policy](lock-policy.md) - why poisoned-lock recovery matters
  in a container-backed application


---

<!-- /docs/bootstrap -->

# Application Bootstrap

`bootstrap.rs` is the one place where your application wires itself up
at startup. Container bindings, event listeners, observers, supervisors,
global middleware - anything that should exist before the first request
hits the server (or the first job pops off the queue) is registered
here. There is no service-provider scaffold to assemble.

There are two hooks, not one. `register` is process-wide: every
subcommand runs it, including `queue:work`, `schedule:work`,
`workflow:work`, the `queue:*` commands, `schedule:list`, `down` and
`up`, and your console binary, not only the server. The migration
commands are the one exception (see "Where bootstrap sits in the boot
order" below). Register the database connection, container bindings,
event listeners, observers, supervisors, and worker job registration
there. `register_http_stack`,
wired through `.http_bootstrap`, runs only on the server path (`serve` /
`web:run`) - global middleware and `Inertia::install` belong there. The
"Where bootstrap sits in the boot order" section below explains why the
split exists.

## The shape

A scaffolded app's entry point builds an [`Application`](lifecycle.md)
fluently and runs it. Bootstrap is two methods on the builder:

```rust
// cmd/main.rs
use app::{bootstrap, config, migrations, routes};
use suprnova::Application;

#[suprnova::main]
async fn main() {
    Application::new()
        .config(config::register_all)
        .bootstrap(bootstrap::register)
        .http_bootstrap(|| async { bootstrap::register_http_stack() })
        .routes(routes::register)
        .migrations::<migrations::Migrator>()
        .run()
        .await;
}
```

### `#[suprnova::main]`, not `#[tokio::main]`

The attribute is not cosmetic, and swapping it back breaks the boot with
a message explaining why.

Loading `.env` writes to the process environment, and `set_var` is sound
only while the process is single-threaded. `#[tokio::main]` builds the
runtime *around* the whole of `main`, so every worker thread already
exists before your first statement runs - and any of them can call
`getenv` indirectly through DNS resolution, time formatting, or a C
dependency. The race is silent when it goes wrong, which is the worst
property a race can have.

`#[suprnova::main]` keeps the same `async fn main` you would write
anyway, and simply reorders two things: it loads the environment, then
builds the runtime, then runs your body on it. It accepts the same
`flavor` and `worker_threads` arguments as `#[tokio::main]`.

If `Application::run` finds the environment was never loaded from a
single-threaded context, it refuses to boot rather than warning - an app
that starts "fine" under `#[tokio::main]` is precisely the one that
corrupts an unrelated environment read weeks later.

The framework calls your `bootstrap_fn` once during the boot sequence,
after the environment is loaded and before the router is built. The
container's `#[injectable]` and `#[service]` inventory and the runtime
drivers (Cache, Queue, RateLimit, Mail) come up after it, so a binding
you install by hand wins over the inventory default, and
`QUEUE_DRIVER=database` finds the connection your bootstrap opened. The
same call runs for background workers (`queue:work`, `workflow:work`,
`schedule:work`) and the console binary, so an observer or listener
registered here fires identically for an insert from a queue job and an
insert from an HTTP handler. `http_bootstrap_fn` runs immediately after `bootstrap_fn`, but
only on the server path - background workers and the console binary
never call it. [Lifecycle](lifecycle.md) walks the full sequence.

Both functions' signatures are fixed by `Application::bootstrap` and
`Application::http_bootstrap`:

```rust
// src/bootstrap.rs
pub async fn register() {
    // database, bindings, observers, listeners, supervisors, worker job registration
}

pub fn register_http_stack() {
    // global middleware, Inertia::install
}
```

`register` returns `()`; `register_http_stack` is synchronous, not
`async` - both are wired as async closures at the call site
(`.http_bootstrap(|| async { bootstrap::register_http_stack() })`)
because a plain function pointer can also serve as a test harness
entry point without pulling `async` into the test. Fallible setup uses
`.expect("…")` with a message that explains the remediation - boot is
the right time to fail loudly. The example app's call is
`DB::init().await.expect("Failed to connect to database");` so a
missing `DATABASE_URL` aborts the process at boot with the actual
error printed, instead of surfacing as a confusing "connection
refused" on the first request.

## What goes in bootstrap

A real `bootstrap` function does a small number of distinct things. The
subsections below describe bootstrap responsibilities available to an
application; the example app exercises most, but not all, of them. For current
default Magnetar initialization, use the API scaffold's `src/bootstrap.rs`
template as the working reference.

### Database connection

```rust
use suprnova::DB;

pub async fn register() {
    DB::init().await.expect("Failed to connect to database");
}
```

`DB::init` reads `DatabaseConfig` (registered by your `config_fn`) and
opens the pool. The connection is stored in the [container](container.md)
as a singleton - `DB::connection()` / `DB::get()` resolves it
anywhere. `DB::init_with(config)` is the test-and-tooling escape
hatch when you want to point at something other than the env-derived
URL.

### Magnetar authentication engine

Applications using the built-in password, passkey, magic-link, bearer,
lockout, remember, or OAuth facades initialize Magnetar after the database and
`APP_KEY` are ready:

```rust
use suprnova::{DB, MagnetarConfig, PasskeyConfig, init_magnetar};

pub async fn register() {
    DB::init().await.expect("Failed to connect to database");

    let database = DB::connection().expect("DB not initialized");
    let config = MagnetarConfig::from_sea_orm(database.inner().clone())
        .passkey_config(PasskeyConfig {
            rp_id: "app.example.com".to_string(),
            rp_origin: "https://app.example.com".to_string(),
        });

    init_magnetar(config)
        .await
        .expect("Failed to initialize Magnetar");
}
```

The default `MagnetarConfig` binds application identities to the canonical
`app_users` table. The generated full-stack scaffold uses a `users` model and
does not initialize Magnetar, so do not add the default initializer unchanged
to that scaffold. Use the API scaffold's `app_users` model, or construct a
custom `MagnetarHostEngine` and `AuthSchema` binding for your existing `users`
table. Keep the framework `UserProvider` and Magnetar host binding on the same
application identity. The API scaffold, not `app/src/bootstrap.rs`, is the
current working reference for default `MagnetarConfig` initialization.

Magnetar is process-wide because queue workers, schedulers, HTTP handlers, and
session middleware use the same credential and session stores. Put
`init_magnetar` in `register`, not `register_http_stack`. The installer is
one-shot and fails if another engine is already installed.

The API scaffold reads `PASSKEY_RP_ID` and `PASSKEY_RP_ORIGIN` in application
bootstrap. Those names are scaffold conventions rather than framework-owned
environment variables.

### Global middleware

Global middleware is HTTP-only, so it belongs in `register_http_stack`,
not `register`:

```rust
use suprnova::{global_middleware, SessionMiddleware, SessionConfig, TimeoutMiddleware};
use crate::middleware;

pub fn register_http_stack() {
    global_middleware!(middleware::LoggingMiddleware);
    global_middleware!(TimeoutMiddleware::default());
    global_middleware!(SessionMiddleware::new(SessionConfig::from_env()));
}
```

`global_middleware!` registers a layer that runs on every request,
including unrouted ones (404s, OPTIONS preflight). The order you
register in is the order the chain runs - outside-in. The framework
slots its own `RequestIdMiddleware` outermost; everything you add sits
inside it. [Middleware](middleware.md) explains the full chain shape,
including the per-route layer.

### Container bindings

The container takes whatever you put in it; the macros are sugar over
the [`App`](container.md) facade.

```rust
use std::sync::Arc;
use suprnova::{App, bind, singleton, factory};
use crate::providers::DatabaseUserProvider;

pub async fn register() {
    // Trait → singleton (wraps in Arc):
    bind!(dyn UserProvider, DatabaseUserProvider);

    // Concrete singleton:
    singleton!(MyConfig { max_uploads_per_user: 100 });

    // Factory (constructed per resolve):
    factory!(|| RequestLogger::new());

    // Or call the facade directly for finer control:
    let hub: Arc<dyn BroadcastHub> = Arc::new(InMemoryBroadcastHub::new());
    App::bind::<dyn BroadcastHub>(hub);
}
```

Trait-object bindings are the most common shape - bind an interface,
let handlers and tests substitute the implementation. The
[Container](container.md) chapter has the full binding API including
`bind_factory!`, the `_if_absent` variants, and the three-layer
lookup model.

### Event listeners and observers

The dispatcher is alive as soon as bootstrap runs - listeners
registered here see every subsequent dispatch.

```rust
use std::sync::Arc;
use suprnova::EventFacade;
use crate::events::UserRegistered;
use crate::listeners::SendWelcomeEmailListener;

pub async fn register() {
    EventFacade::listen::<UserRegistered, _>(
        Arc::new(SendWelcomeEmailListener),
    ).await;
}
```

Eloquent observers (`#[suprnova::observer(M)]`) collect themselves via
`inventory::submit!` at compile time. One call drains the inventory
into the dispatcher:

```rust
suprnova::eloquent::observers::bootstrap_observers()
    .await
    .expect("observer install failed");
```

The call is idempotent - re-running bootstrap (a worker that boots a
second time) does not double-register the listener adapters.
[Events](events.md) covers dispatch and listener authoring;
[Eloquent](eloquent.md) covers observers.

### Supervisors

Long-running background tasks declared via the `Supervisor` trait and
`inventory::submit!` start through one call:

```rust
use suprnova::SupervisorRegistry;

pub async fn register() {
    SupervisorRegistry::start_all().await;
}
```

Each supervisor runs in its own restart-loop task with a panic
boundary; a panicked supervisor is logged and restarted, not allowed
to take the process down. See [Supervisors](supervisors.md) for the
trait and the restart policy.

### Worker job registration

Queue jobs and mailables that workers need to dispatch by name register
themselves at boot:

```rust
use suprnova::queue::worker::register_job;

pub async fn register() {
    register_job::<crate::jobs::welcome_log::WelcomeLog>();

    suprnova::mail::register_mailable_factory::<crate::mail::welcome::WelcomeEmail>()
        .expect("register at boot");
    register_job::<suprnova::mail::send_job::SendMailJob>();
}
```

Without this, the worker has no way to map a queued envelope back to
the type that handles it.

## The post-boot hook: `booted()`

Bootstrap *registers*; `booted()` *resolves*. The builder takes a
second callback that fires after the server has finished its own
service boot but before it begins accepting connections. Use it when
you need to read something the framework itself bound during boot:

```rust
Application::new()
    .config(config::register_all)
    .bootstrap(bootstrap::register)
    .http_bootstrap(|| async { bootstrap::register_http_stack() })
    .routes(routes::register)
    .booted(|| {
        let cfg: MyConfig = suprnova::App::get().unwrap();
        tracing::info!(?cfg, "services booted");
    })
    .run()
    .await;
```

`booted` is synchronous and runs after `Server::from_config` - drivers
are up, encryption keys are loaded, your bindings exist. Most apps do
not need this hook; reach for it when a one-shot post-boot side effect
needs to see a fully-constructed container.

## A complete `bootstrap.rs`

This representative composition is not a verbatim excerpt from the example
app. It keeps process-wide registration in `register` and HTTP-only setup in
`register_http_stack`. Magnetar initialization is shown separately above
because its application-user schema must match the framework user provider.

```rust
//! Application bootstrap - register services, listeners, global
//! middleware, and the Inertia layer.

use std::sync::Arc;
use std::time::Duration;

use suprnova::broadcasting::{BroadcastHub, ChannelRegistry, InMemoryBroadcastHub};
use suprnova::features::{FeatureMiddleware, bootstrap_database_cached};
use suprnova::queue::worker::register_job;
use suprnova::{
    App, DB, EloquentUserProvider, EventFacade, FrameworkError, Inertia,
    InertiaConfig, SessionConfig, SessionMiddleware, Storage, SupervisorRegistry,
    UserProvider, bind, global_middleware,
};

use crate::broadcasting::ChatChannel;
use crate::events::UserRegistered;
use crate::listeners::SendWelcomeEmailListener;
use crate::middleware;
use crate::models::users::User;

pub async fn register() {
    // ── Database
    DB::init().await.expect("Failed to connect to database");

    // ── Auth provider
    bind!(dyn UserProvider, EloquentUserProvider::<User>::new());


    // ── Broadcasting hub + channel registry
    let hub: Arc<dyn BroadcastHub> = Arc::new(InMemoryBroadcastHub::new());
    App::bind::<dyn BroadcastHub>(Arc::clone(&hub));

    let mut registry = ChannelRegistry::new();
    registry.register(ChatChannel);
    App::singleton(Arc::new(registry));

    // ── Event listeners + bridges
    EventFacade::listen::<UserRegistered, _>(
        Arc::new(SendWelcomeEmailListener),
    ).await;
    EventFacade::broadcast::<UserRegistered>(Arc::clone(&hub)).await;

    // ── Storage disks (env-gated S3 in production)
    Storage::register_fs("public", "./storage/public")
        .expect("register public disk");

    // ── Worker job registration
    register_job::<crate::jobs::welcome_log::WelcomeLog>();
    suprnova::mail::register_mailable_factory::<crate::mail::welcome::WelcomeEmail>()
        .expect("register at boot");
    register_job::<suprnova::mail::send_job::SendMailJob>();

    // ── Observers + supervisors
    suprnova::eloquent::observers::bootstrap_observers()
        .await
        .expect("observer install failed");
    SupervisorRegistry::start_all().await;

    // ── Feature flags
    bootstrap_database_cached(Duration::from_secs(60))
        .await
        .expect("feature-flag chain wired");
}

pub fn register_http_stack() {
    // ── Global middleware (outside-in in registration order)
    global_middleware!(middleware::LoggingMiddleware);
    global_middleware!(suprnova::TimeoutMiddleware::default());
    global_middleware!(SessionMiddleware::new(SessionConfig::from_env()));

    // ── Inertia protocol layer (no version pin: the default hashes the
    // Vite build manifest, so a frontend build bumps the asset version
    // on its own - see "Version detection" in frontend-inertia-responses.md)
    Inertia::install(&InertiaConfig::new()).expect("Inertia install failed");

    global_middleware!(FeatureMiddleware::new());
}
```

Notice the rhythm: each block does one thing, calls one or two APIs,
and either succeeds or fails with a clear message. Nothing here is
clever; the functions are long because the app has a lot of moving
parts, not because the bootstrap pattern is complicated.

## When to bootstrap vs `#[injectable]`

`#[injectable]` is a macro that auto-registers a singleton in the
container's `inventory` at compile time. It is the right choice for
services that need nothing more than their `#[inject]` dependencies to
construct:

```rust
use suprnova::injectable;

#[injectable]
pub struct UserService;

#[injectable]
pub struct OrderService {
    #[inject]
    user_service: UserService,
}
```

These resolve themselves; bootstrap does not need to touch them.

Bootstrap is the right place when construction needs anything else -
an environment variable, a constructed config struct, a `dyn Trait`
binding, a runtime decision, an async setup call, or registration of
something that is not itself a service (a listener, an observer, a
queue job mapping, a global middleware layer).

| Use `#[injectable]` for | Use `bootstrap` for |
|---|---|
| Concrete singletons with no runtime config | Anything `dyn Trait` |
| Services constructed from other injectables | Anything async at boot |
| Default DI graph | Environment-driven values |
| | Event listeners, observers, supervisors |
| | Global middleware |
| | Worker job + mailable registration |

You can mix freely. `#[injectable]` services are visible in the
container by the time `bootstrap` runs, so a binding in bootstrap can
read them.

## Where bootstrap sits in the boot order

The full sequence (excerpted from [Lifecycle](lifecycle.md)):

1. `Config::init(".")` - load `.env`, detect environment
2. `init_policies()` - drain the `#[policy]` inventory
3. Your `config_fn` runs (typed config registration)
4. Migrations run (auto-migrate on `serve`)
5. **Your `bootstrap_fn` runs** ← `bootstrap::register`
6. **Your `http_bootstrap_fn` runs, server path only** ← `bootstrap::register_http_stack`
7. Routes assembled from your `routes_fn`
8. `Server::from_config` boots drivers + container
9. Your `booted_fn`s fire
10. Server begins accepting connections

Every other subcommand, and the console binary, runs one shared boot
in place of steps 6 to 10: your `bootstrap_fn`, then the log channels,
the container's `#[injectable]` and `#[service]` inventory, the
`#[policy]` gates, and the drivers the command uses. The workers, the
`queue:*` commands, `schedule:run`, and the console binary boot every
runtime driver. `down` and `up` boot only the drivers maintenance mode
reads, so a queue backend that is down cannot stop the command you run
during that outage. `schedule:list` boots no driver. None of them runs
step 6, since only `serve` / `web:run` runs `http_bootstrap_fn`. That
is what lets a listener, an observer, or an injectable action you
register reach worker code paths exactly as it reaches HTTP handlers,
while `register_http_stack`'s global middleware and `Inertia::install`
stay off processes that never serve HTTP.

The migration commands (`migrate`, `migrate:*`, `schema:dump`) run no
`bootstrap_fn`, the same way `serve` runs its migrations at step 4,
before it. A fresh database has to be migratable even when your
bootstrap reads a table the migrations create. Override a path that
the migrations read (`use_database_path`) in your `config_fn`, which
every subcommand runs first.

### Why Suprnova diverges

Laravel runs every service provider's `register()` and `boot()` for
`artisan` commands and queue workers too, not only for HTTP requests -
and gets away with it because its Vite integration resolves asset URLs
lazily, at render time, from whatever the `@vite` Blade directive is
asked to render. A worker that never renders a view never touches the
manifest, so a missing build simply never comes up.

Suprnova's `Inertia::install` resolves the manifest once, at boot, and
fails closed in production when it is missing - by design, so a
misconfigured deployment cannot serve asset URLs pointing at a Vite dev
server nobody runs. That design choice is exactly what breaks a worker
or console image that (correctly) ships no `public/assets`: the failure
Laravel defers to request time, Suprnova would otherwise hit at process
start, on every subcommand. Splitting the boot surface into `bootstrap`
and `http_bootstrap` keeps the fail-closed check, but only where it
belongs - the server path that will actually render an Inertia page.

Laravel also splits boot itself across multiple service providers:
each provider implements `register()` and `boot()`, they're collected
in `config/app.php`, and Laravel walks them in two passes (all
`register`, then all `boot`) so a service can depend on another
provider's bindings without ordering ceremony in user code. The
provider class gives you a unit of organisation when an app
accumulates dozens of distinct subsystems.

Suprnova collapses that to two functions - `register` and
`register_http_stack` - rather than a `register`/`boot` pair per
provider. The reasons:

- **The two-pass `register`/`boot` split solves an ordering problem
  Rust does not have.** `#[injectable]` and the container's
  `bootstrap_singletons` already resolve dependency graphs without
  user-visible ordering. Bindings register inline; the lookup machinery
  handles the rest.
- **Two functions are easier to read than ten.** A new contributor
  opens `bootstrap.rs` and sees every binding, every listener, every
  observer, every middleware layer in one of two places. Provider-style
  fragmentation hides what the app actually does.
- **Inventory-style auto-registration covers the rest.** Observers,
  supervisors, scheduled tasks, policies, and queue handlers all
  collect themselves at compile time via `inventory::submit!`.
  Bootstrap drains the inventories with single calls
  (`bootstrap_observers`, `SupervisorRegistry::start_all`) rather than
  enumerating each.

Where Laravel earns the provider split is library distribution: a
crate that ships its own bindings would want a registration entry
point that an app can opt into without editing its own bootstrap.
Suprnova's analogue is a public `pub async fn register()` in the
crate's root and a one-line call from the app's `bootstrap`. The
ergonomic cost is one line; the readability gain is everything in
one place.

Laravel's `php artisan migrate` registers and boots every provider
before it migrates, as every `artisan` command does. Suprnova's
migration commands run no `bootstrap_fn`. A Laravel provider rarely
reads a table at boot, because its services resolve lazily; a
Suprnova bootstrap does real work when it runs, and the documented
feature-flag setup, `bootstrap_database_cached`, reads the `features`
table there. Booting first would make `migrate` fail on the fresh
database it exists to create. A migration that needs data access uses
the connection its `SchemaManager` hands it.

## Next

- [Lifecycle](lifecycle.md) - full boot order and where `bootstrap_fn` fires
- [Container](container.md) - `App::bind` / `App::singleton` /
  `App::factory` and the three-layer lookup
- [Configuration](configuration.md) - typed config registration that
  runs before bootstrap
- [Middleware](middleware.md) - chain composition for layers
  registered with `global_middleware!`
- [Events](events.md) - the dispatcher that listeners and observers
  plug into


---

<!-- /docs/macros -->

# Macros

Suprnova ships about three dozen macros, every one of them re-exported
from `suprnova::*`. They're the joints where the framework meets your
code - `routes!` builds the router, `#[handler]` adapts a function
into one, `#[suprnova::model]` turns a struct into an Eloquent model,
`#[derive(Data)]` produces a typed Inertia payload. This chapter is
the index. Each macro gets a one-paragraph description, a minimal
example, and a pointer to the chapter that uses it for real work.

A few principles that hold across the whole surface:

- **Macros emit fully-qualified paths.** Generated code writes
  `::suprnova::…` so the macros work whether or not you've imported
  the underlying types.
- **Heavy use of `inventory::submit!`.** Models, commands, policies,
  observers, payment providers, and more register themselves at
  compile time and the framework drains the registry at boot. You
  almost never wire registration by hand.
- **Compile-time validation where it pays.** `inertia_response!`
  checks that the named component file exists. `redirect!` checks
  that the named route exists. `routes!` rejects paths that don't
  start with `/`. Errors that can be caught at build time are.

## Routing

| Macro | Returns | What it does |
|---|---|---|
| `routes!` | `pub fn register() -> Router` | Top-level list of routes - exports a `register()` your `app.rs` calls |
| `get!` / `post!` / `put!` / `delete!` / `patch!` / `head!` / `options!` / `any!` | `RouteDefBuilder<H>` | One HTTP route - chainable `.name(...)` / `.middleware(...)` |
| `group!` | `GroupDef` | Prefix + middleware applied to a child list of routes |
| `fallback!` | `FallbackDefBuilder<H>` | Custom 404 handler when no route matches |
| `ws!` | `WsRouteDef` | One WebSocket route - chainable `.middleware(...)` / `.config(...)` |

```rust
use suprnova::{routes, get, post, ws, group};
use crate::{controllers, middleware::AuthMiddleware, ws::ChatHandler};

routes! {
    get!("/", controllers::home::index).name("home"),
    get!("/users/{id}", controllers::user::show).name("users.show"),
    post!("/users", controllers::user::store).name("users.store"),

    group!("/admin", {
        get!("/dashboard", controllers::admin::dashboard),
    }).middleware(AuthMiddleware),

    ws!("/ws/chat", ChatHandler),
}
```

The route-path string is checked at compile time - `validate_route_path`
rejects anything that doesn't start with `/`. Route names registered
via `.name("…")` are also checked for uniqueness at boot through
`register_route_name`. See [Routing](routing.md) for the full
expansion and [WebSockets](websockets.md) for `ws!`.

## Handlers and requests

### `#[handler]`

Rewrites a controller function so it can extract typed parameters
(via `FromRequest`) directly from the incoming request - instead of
manually pulling fields off `Request`, you declare what the handler
needs and the macro wires it up.

```rust
use suprnova::{handler, Response, json_response, request};

#[request]
pub struct CreateUserRequest {
    #[validate(email)]
    pub email: String,

    #[validate(length(min = 8))]
    pub password: String,
}

#[handler]
pub async fn store(form: CreateUserRequest) -> Response {
    // `form` is already validated - 422 returned automatically on failure
    json_response!({ "email": form.email })
}
```

A `Request`-shaped first parameter is still accepted as the
identity case. See [Controllers](controllers.md).

An argument that reads the path reads the route parameter named after
it: `id: i64` reads `{id}`, and a raw identifier drops its `r#`, so
`r#type: String` reads `{type}`. You name another parameter with
`#[route_param("name")]`, as Laravel's `#[RouteParameter('name')]` does:

```rust
use suprnova::{handler, json_response, Response};

// GET /posts/{post}
#[handler]
pub async fn show(#[route_param("post")] id: i64) -> Response {
    json_response!({ "id": id })
}
```

The router's startup check reads the renamed parameter, so a path that
does not declare `{post}` is refused before the first request.
`#[authorize]` still names the argument by its own name (`id` here).

### `#[request]` and `#[derive(FormRequest)]`

`#[request]` is the recommended way to declare a validated request
type. It auto-derives `Deserialize`, `Validate`, and `FormRequest`,
so the struct works with both `application/json` and
`application/x-www-form-urlencoded` bodies.

`#[derive(FormRequestDerive)]` is the underlying derive if you want
to opt out of the attribute (you'll need to derive `Deserialize` and
`Validate` yourself). The attribute is what we recommend; the derive
exists for the edge case. See [Requests](requests.md) and
[Validation](validation.md).

### `#[derive(MultipartRequest)]`

Strongly-typed extractor for `multipart/form-data` - bind text fields
and uploaded files in one struct, with per-field type-level validators.

```rust
use suprnova::{MultipartRequest};
use suprnova::{ImageFile, MaxSize, UploadedFile};

#[derive(MultipartRequest)]
pub struct AvatarUpload {
    #[field("avatar")]
    pub avatar: UploadedFile<(ImageFile, MaxSize<5_242_880>)>,

    #[field("caption")]
    pub caption: Option<String>,
}
```

Built-in validators (`ImageFile`, `MimeAllowlist<…>`, `MaxSize<…>`,
`MimeType<…>`) compose via tuples. See [Requests](requests.md).

## Responses

### `json_response!` and `text_response!`

The two short-form response macros. Both wrap `HttpResponse::*` in
`Ok(...)` so they slot straight into a handler's return position:

```rust
use suprnova::{handler, json_response, text_response, Response};

#[handler]
pub async fn health() -> Response {
    json_response!({ "status": "ok" })
}

#[handler]
pub async fn robots() -> Response {
    text_response!("User-agent: *\nDisallow:")
}
```

See [Responses](responses.md).

### `inertia_response!`

Builds an Inertia page response, validating at compile time that the
named component file (`.svelte` / `.tsx` / `.jsx` / `.vue`) exists in
`frontend/src/pages/`, or wherever the crate's `Cargo.toml` points the
lookup (see [Another page layout](frontend-pages.md#another-page-layout)).
If you misspell the component name, the build fails with suggestions:

```rust
use suprnova::{handler, inertia_response, InertiaProps, Request, Response};

#[derive(InertiaProps)]
struct HomeProps {
    title: String,
    user_count: i64,
}

#[handler]
pub async fn index(req: Request) -> Response {
    inertia_response!(&req, "Home", HomeProps {
        title: "Welcome".into(),
        user_count: 42,
    })
}
```

`#[derive(InertiaProps)]` generates the `Serialize` impl the response
shape needs. See [Inertia Responses](frontend-inertia-responses.md).

### `redirect!`

Type-safe redirect to a named route - the route name is verified at
compile time against the names registered through `routes!`:

```rust
use suprnova::redirect;

// Compiles only if "users.show" is a registered route name
let resp = redirect!("users.show").with("id", "42").into();
```

See [URL Generation](urls.md).

## Eloquent

### `#[suprnova::model]`

Turns a plain struct into a full Eloquent model: generates SeaORM
`Entity`, `Model`, `ActiveModel`, `Column`, `Relation` stubs, plus
all the trait impls Eloquent needs. Also `inventory::submit!`s a
`ModelEntry` so the framework can enumerate every model at boot.

```rust
use suprnova::model;

#[model(table = "users")]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

Attribute keys include `table`, `primary_key`, `key_type`,
`auto_increment`, `connection`, `fillable`, `guarded`, `casts`,
`timestamps`, `soft_deletes`, `appends`, `hidden`, `visible`,
`mutators`, `touches`, and `unique_id` (for UUID/ULID PKs). See
[Eloquent](eloquent.md).

### `#[suprnova::scopes(Model)]`

Walks an `impl Model { … }` block and turns every method whose
signature matches `fn name(query: Builder<Self>[, args…]) -> Builder<Self>`
into a scope - generating both `Model::scope_name(args)` and a
chainable `.scope_name(args)` on `Builder<Model>`.

```rust
use suprnova::{scopes, Builder};

#[suprnova::scopes(User)]
impl User {
    pub fn active(query: Builder<Self>) -> Builder<Self> {
        query.filter("active", true)
    }

    pub fn popular(query: Builder<Self>, threshold: i64) -> Builder<Self> {
        query.filter_op("followers_count", ">", threshold)
    }

    // Not a scope - passes through unchanged
    pub fn display_name(&self) -> String { self.name.clone() }
}

// Both call sites compile:
// User::active().popular(500).get().await?;
// User::query().filter_op("id", ">", 0).active().get().await?;
```

The chainable form requires the generated trait
`HasScope_<scope>_<Model>` in scope when called from a different
module. See [Eloquent](eloquent.md).

### `#[suprnova::observer(Model)]`

Wires an `impl Observer<M>` block into the lifecycle-event system -
each of the 16 overridden methods becomes a registered listener,
submitted to inventory and drained at boot.

```rust
use async_trait::async_trait;
use suprnova::eloquent::observers::Observer;
use suprnova::eloquent::events::EventResult;
use suprnova::eloquent::attrs::Attrs;
use suprnova::FrameworkError;

pub struct AuditObserver;

#[suprnova::observer(User)]
#[async_trait]
impl Observer<User> for AuditObserver {
    async fn creating(&self, attrs: &mut Attrs) -> EventResult {
        if attrs.get("email").is_none() {
            return EventResult::cancel("email is required");
        }
        EventResult::ok()
    }

    async fn created(&self, user: &User) -> Result<(), FrameworkError> {
        tracing::info!(user.id = user.id, "user created");
        Ok(())
    }
}
```

**Required attribute ordering: `#[suprnova::observer(M)]` must come
before `#[async_trait]`.** Attribute macros expand outside-in - if
`async_trait` runs first, it rewrites every `async fn` into a
desugared shape and the observer macro's name-match against the 16
trait method names silently finds nothing. See [Events](events.md).

### `#[suprnova::accessor]` and `#[suprnova::mutator]`

Function-level markers on `impl Model { … }` methods that hook into
the model's `to_json()` / `fill()` paths. Reference the field name
in `#[model(appends = […])]` (accessor) or `#[model(mutators = […])]`
(mutator) for the macro to wire them up.

```rust
#[suprnova::model(appends = ["full_name"], mutators = ["password"])]
pub struct User {
    pub id: i64,
    pub first_name: String,
    pub last_name: String,
    pub password: String,
}

impl User {
    #[suprnova::accessor]
    pub fn full_name(&self) -> String {
        format!("{} {}", self.first_name, self.last_name)
    }

    #[suprnova::mutator]
    pub fn set_password(
        &mut self,
        value: serde_json::Value,
    ) -> Result<(), suprnova::FrameworkError> {
        let raw: String = serde_json::from_value(value)
            .map_err(|e| suprnova::FrameworkError::validation("password", format!("{e}")))?;
        self.password = bcrypt(raw);
        Ok(())
    }
}
```

See [Mutators & Casts](eloquent-mutators.md).

### `#[suprnova::prunable]`

Wraps a `Prunable` (or `MassPrunable`) impl and submits a `PrunerEntry`
into the registry that `model:prune` walks at runtime:

```rust
use async_trait::async_trait;
use chrono::{Duration, Utc};
use suprnova::eloquent::Prunable;

#[suprnova::prunable]
#[async_trait]
impl Prunable for Session {
    fn prunable() -> suprnova::Builder<Self> {
        Self::query().filter_op(
            "expires_at",
            "<",
            (Utc::now() - Duration::days(30)).to_rfc3339(),
        )
    }
}
```

See [Eloquent](eloquent.md).

### `attrs!`

Builds an ordered `Attrs` map (`IndexMap<&'static str, serde_json::Value>`)
for `Model::create` / `Model::update` / `Model::fill`:

```rust
use suprnova::attrs;

let user = User::create(attrs! {
    name: "Alice",
    email: "alice@example.com",
    age: 32,
}).await?;
```

See [Eloquent](eloquent.md).

### `casts!`

Builds a per-query cast map you can pass to `Builder::with_casts`:

```rust
use suprnova::{casts, AsDate, AsJson};

let map = casts! {
    birthday = AsDate,
    metadata = AsJson<serde_json::Value>,
};
let rows = User::query().with_casts(map).get().await?;
```

See [Mutators & Casts](eloquent-mutators.md).

### `#[derive(RouteBinding)]`

Binds a unit-only enum from a route parameter. Each variant binds from
its `#[route(value = "...")]`, or else from its name in snake case, and
any other value answers 404:

```rust
#[derive(suprnova::RouteBinding)]
pub enum Status {
    Draft,                    // "draft"
    #[route(value = "live")]
    Published,                // "live"
}
```

A `#[suprnova::model]` struct needs no derive: the model macro implements
`RouteBinding` itself. See [Route model binding](routing.md#route-model-binding).

### `resource!` and `api_resource!`

Register a resource whose actions are the `#[handler]` functions of one
module, found by action name. `only = [...]` or `except = [...]` selects
actions; a selected action whose function is missing fails to compile:

```rust
routes! {
    resource!("posts", controllers::posts),
    api_resource!("tags", controllers::tags, only = [index, show]),
}
```

See [Resource routing](routing.md#resource-routing).

## Data and Inertia

### `#[derive(Data)]`

The composite derive for typed payloads. Produces a `Serialize` impl
that respects `#[data(input_only)]` fields, plus a `Deserialize` impl
that rejects payloads attempting to set `#[data(output_only)]` fields.
Pair with `#[json_resource("type")]` for JSON:API output via the
`Resource` chapter.

```rust
use suprnova::{Data, Validate};

#[derive(Data, Validate)]
struct UserDto {
    pub id: i64,
    pub name: String,

    #[data(input_only)]
    #[validate(length(min = 8))]
    pub password: String,

    #[data(output_only)]
    pub computed_handle: String,

    #[data(allow_include)]
    pub posts: Vec<PostDto>,
}
```

`#[data(allow_include)]` registers the field in the partial-reload
include allowlist via `inventory::submit!`. See
[Data Objects](data.md) and [API Resources](eloquent-resources.md).

### `#[derive(InertiaProps)]`

Generates the `Serialize` impl `inertia_response!` needs. Plain marker
derive - most apps reach for `#[derive(Data)]` instead because it gives
you partial-reload includes for free.

```rust
use suprnova::InertiaProps;

#[derive(InertiaProps)]
struct DashboardProps {
    title: String,
    user: User,
}
```

See [Inertia Responses](frontend-inertia-responses.md).

### `when_loaded!`

Emits a `Prop::lazy(…)` only when a named relation has been
eager-loaded on the entity; otherwise emits `Prop::absent()` so the
prop is skipped from the response entirely:

```rust
use suprnova::when_loaded;

let songs_prop = when_loaded!(&artist, "songs", || async {
    serde_json::to_value(&artist.songs).unwrap()
});
```

See [Data Objects](data.md).

## Dependency injection

### `#[service]`

Adds `Send + Sync + 'static` to a trait so it slots into the container:

```rust
use suprnova::service;

#[service]
pub trait HttpClient {
    async fn get(&self, url: &str) -> Result<String, FrameworkError>;
}

// App::bind::<dyn HttpClient>(Arc::new(RealHttpClient::new()));
// let client = App::make::<dyn HttpClient>()?;
```

`#[service(impl = Concrete)]` also registers `Concrete::default()` at
boot, and `fake = Fake` adds `<dyn Trait>::fake()` for tests.
`bind(Concrete, env = [...])` entries choose the implementation by
environment, as Laravel's `#[Bind]` attribute with `environments` does:
the first entry with a pattern that matches the environment is bound,
`*` matching any run of characters, and `impl` when none matches.

```rust
#[service(impl = SmtpMailer, bind(LogMailer, env = ["local", "testing"]))]
pub trait Mailer {
    fn send(&self, to: &str, body: &str);
}
```

See [Service Container](container.md).

### `#[injectable]`

Auto-registers a concrete type as a singleton. Derives `Default` +
`Clone` and submits a registration that runs at boot:

```rust
use suprnova::injectable;

#[injectable]
pub struct AppState {
    pub counter: u32,
}

// let state: AppState = App::get().unwrap();
```

See [Service Container](container.md).

## Errors

### `#[domain_error]`

Defines a domain error that implements `Display`, `Error`, `HttpError`,
and `From<T> for FrameworkError` - so it short-circuits a handler via
`?`:

```rust
use suprnova::domain_error;

#[domain_error(status = 404, message = "User not found")]
pub struct UserNotFoundError {
    pub user_id: i32,
}

pub async fn get_user(id: i32) -> Result<User, FrameworkError> {
    let user = User::find(id).await?
        .ok_or_else(|| UserNotFoundError { user_id: id })?;
    Ok(user)
}
```

See [Error Handling](errors.md).

## Console and background work

### `#[command]`

Marks an `async fn(Vec<String>) -> Result<(), FrameworkError>` as a
console command. Submits a `CommandEntry` so `dispatch_argv` finds it
when the per-project console binary runs:

```rust
use suprnova::{command, FrameworkError};

#[command(name = "db:seed", description = "Run all registered seeders")]
async fn db_seed(_args: Vec<String>) -> Result<(), FrameworkError> {
    suprnova::seed::run_all().await
}
```

See [Console](console.md).

### `#[derive(Command)]`

The typed-args alternative. Goes on top of `#[derive(clap::Parser)]`,
reads `#[console(...)]` for metadata, and emits the runner that calls
your `TypedCommand::run`:

```rust
use async_trait::async_trait;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(clap::Parser, Command)]
#[console(name = "greet", description = "Greet someone")]
pub struct Greet {
    #[arg(short, long)]
    name: Option<String>,
    #[arg(long)]
    loud: bool,
}

#[async_trait]
impl TypedCommand for Greet {
    async fn run(self) -> Result<(), FrameworkError> {
        let target = self.name.unwrap_or_else(|| "world".into());
        println!("{}", if self.loud { format!("HELLO {target}!") } else { format!("Hello {target}") });
        Ok(())
    }
}
```

See [Console](console.md).

### `#[workflow]` and `#[workflow_step]`

`#[workflow]` registers an async fn as a durable workflow - runnable
state, retriable steps, persisted history. Each `#[workflow_step]`
inside the body is a checkpoint the runtime can resume from after a
crash or restart.

```rust
use suprnova::{workflow, workflow_step, FrameworkError};

#[workflow]
async fn onboard_user(user_id: i64) -> Result<(), FrameworkError> {
    send_welcome_email(user_id).await?;
    enable_default_features(user_id).await?;
    Ok(())
}

#[workflow_step]
async fn send_welcome_email(user_id: i64) -> Result<(), FrameworkError> {
    // …
    Ok(())
}
```

### `start_workflow!`

Kicks off a workflow by path, serialising the args into the workflow
runtime's envelope shape:

```rust
use suprnova::start_workflow;

let handle = start_workflow!(crate::workflows::onboard_user, 42).await?;
```

See [Workflows](workflows.md).

### `schedule_task!`

Sugar around `TaskBuilder::from_async` so a closure schedules cleanly
alongside trait-based `Task` impls:

```rust
use suprnova::{schedule_task, FrameworkError};

let task = schedule_task!(|| async {
    println!("ticking");
    Ok::<(), FrameworkError>(())
})
    .every_minute()
    .name("tick");
```

See [Task Scheduling](scheduling.md).

## Authorization

### `#[policy(UserType, ResourceType)]`

Wraps an `impl Policy` block and registers each method as a named
gate action. The gate name combines the method name with the
lowercased resource type - `fn view(...)` on `Comment` becomes
`"view-comment"`:

```rust
use suprnova::policy;

struct CommentPolicy;

#[policy(User, Comment)]
impl CommentPolicy {
    fn view(_user: &User, _comment: &Comment) -> bool { true }
    fn update(user: &User, comment: &Comment) -> bool {
        comment.author_id == user.id
    }
}
```

`Server::run` calls `authorization::init_policies()` automatically.
See [Authorization](authorization.md).

## Notifications and mail

### `#[derive(NotificationMailable)]`

Auto-generates `to_mail` from a `#[mail(...)]` attribute - inline or
file-backed Tera templates for subject, HTML body, and text body.
Compile-time checks: subject required, at least one body present,
exclusive html/html_template, `from_name` requires `from`:

```rust
use serde::{Serialize, Deserialize};
use suprnova::NotificationMailable;

#[derive(Serialize, Deserialize, NotificationMailable)]
#[mail(
    subject = "Your order shipped - tracking {{ tracking }}",
    html    = "<p>Tracking: <code>{{ tracking }}</code></p>",
    text    = "Tracking: {{ tracking }}",
    from    = "orders@suprnova.dev",
)]
pub struct OrderShipped { pub tracking: String }
```

The notification trait itself is hand-implemented - there is no
`#[derive(Notification)]`. See [Notifications](notifications.md) and
[Mail](mail.md).

## Validation

### `validate!`

Sync, declarative validation entry point. Each row pairs a field name
with one or more `Rule` (or `ContextualRule`) values, with `?:` for
"present-only validate" and `?=>` for conditionally-required optional
fields:

```rust
use suprnova::{validate, ValidationErrors};
use suprnova::rules::*;

fn validate_form(self_ref: &SignupForm) -> Result<(), ValidationErrors> {
    validate! { self_ref =>
        email   => Required, Email;
        password => Required, Min(8);
        bio     ?: Max(500);
        card_number ?=> RequiredIf { other: "billing_type", value: "card" } => with ctx;
    }
}
```

`Validate` is re-exported from the `validator` crate - `#[validate(...)]`
attributes (e.g. `#[validate(email)]`) come from `validator` and run
through `FormRequest`'s sync path. Use `validate!` when you need
contextual / cross-field rules, async rules, or rules from the
`suprnova::rules` palette. See [Validation](validation.md).

## Factories

### `#[derive(Factory)]`

Generates a sibling `<Model>Factory` marker and a `Factory` impl that
produces models via `fake::Faker`. The model must implement
`fake::Dummy<fake::Faker>` - typically via `#[derive(Dummy)]`:

```rust
use suprnova::{Dummy, Factory};

#[derive(Dummy, Factory)]
pub struct User {
    pub id: i32,
    pub name: String,
    pub email: String,
}

// UserFactory exists:
let users = UserFactory::new().count(10).make_many();
```

See [Factories](eloquent-factories.md).

## Testing

### `#[suprnova_test]`

Wraps an `async fn` test with an in-memory SQLite database (running
`crate::migrations::Migrator` by default), invokes `App::init()` and
`App::boot_services()`, and runs the body under `#[tokio::test]`.
Parallel tests stay hermetic through the container's per-thread
layer - bind test-specific services through `TestContainer::fake`
(not `App::bind`) so each thread sees its own fakes:

```rust
use suprnova::suprnova_test;
use suprnova::testing::TestDatabase;

#[suprnova_test]
async fn creates_a_user(db: TestDatabase) {
    let user = User::create(attrs! { name: "A", email: "a@x.com" }).await.unwrap();
    assert!(user.id > 0);
}
```

A custom migrator goes via `#[suprnova_test(migrator = MyMigrator)]`.
See [Testing](testing.md).

### `test_database!`

The one-line `TestDatabase` constructor for tests that don't take the
`db` parameter through `#[suprnova_test]`:

```rust
let db = test_database!();
let db = test_database!(my_crate::CustomMigrator);
```

### `describe!`, `test!`, `expect!`

Jest-style grouping + fluent assertions. `describe!` is a module,
`test!` produces a `#[test]` (sync or async, with or without a
`TestDatabase` parameter), and `expect!` wraps a value for chained
assertions with file/line context on failure:

```rust
use suprnova::{describe, test, expect};

describe!("CreateUserAction", {
    test!("creates a user", async fn(db: TestDatabase) {
        let user = CreateUserAction::new()
            .execute("test@example.com").await.unwrap();
        expect!(user.email).to_equal("test@example.com".to_string());
    });
});
```

See [Testing](testing.md).

## Middleware

### `global_middleware!`

Registers a middleware that runs on every request, in registration
order, before any route-specific middleware. Idempotent per type:

```rust
use suprnova::global_middleware;
use crate::middleware;

pub fn register() {
    global_middleware!(middleware::LoggingMiddleware);
    global_middleware!(middleware::CorsMiddleware);
}
```

Must run before `Server::from_config` / `Server::new` - the server
snapshots the global registry at build time. See
[Middleware](middleware.md).

## Pitfalls

A short list of failure modes that are easy to hit and easy to fix.

### Attribute ordering - `#[observer]` must come before `#[async_trait]`

```rust
// CORRECT
#[suprnova::observer(User)]
#[async_trait]
impl Observer<User> for AuditObserver { … }

// WRONG - silently emits zero listeners
#[async_trait]
#[suprnova::observer(User)]
impl Observer<User> for AuditObserver { … }
```

Attribute macros expand outside-in. `async_trait` rewrites every
`async fn` into a desugared `Pin<Box<dyn Future>>` shape. If it runs
first, the observer macro can no longer match by method name and
emits nothing. The same outside-in rule applies whenever you stack
multiple macros - put the Suprnova attribute outermost when in doubt.

### The inherent-impl trap

An inherent `impl` method **cannot** shadow a trait's default method
through trait dispatch. If you write a macro (or hand-write code)
that defines `fn save(&self)` on a model as an inherent method,
calls that go through the `Model` trait (`some_model.save()` where
the call site only knows it as `&dyn Model`) will pick the trait
default - not your inherent override.

Fix: emit a trait-method override, never an inherent method, when the
generated behaviour must participate in trait dispatch. This is why
the framework's macros (notably `#[suprnova::model]`) write to the
trait impl. If you're hand-rolling Eloquent extensions, do the same.

### `global_middleware!` only takes effect before `Server::from_config`

The server snapshots the global registry when it's built. Calling
`global_middleware!(M)` after `Server::from_config(...)` does not
retroactively apply to that server. Register every global middleware
in `bootstrap()`, before `Application::run()` reaches the serve step.

### `redirect!` and `inertia_response!` are build-time checks

Both macros refuse to compile if the named target doesn't exist -
that's the point. If a refactor removes a route or component name,
every call site that mentions it breaks the build, which is exactly
what you want. If the build error surprises you, search for the
string literal in your `routes!` block / pages directory before
"fixing" the macro call.

### `?:` skips on `None`; `?=>` runs even on `None`

In `validate!` rows, `?:` only runs rules when the field is `Some`.
A presence-conditional rule like `RequiredIf` on a `?:` row therefore
can never fail an absent field. Use `?=>` (which treats absence as
`""`) for the require-when-X case.

### `#[derive(Validate)]` is from the `validator` crate, not Suprnova

Suprnova re-exports `validator::Validate` so you don't take a direct
dep on `validator`. The `#[validate(...)]` attributes come from
`validator`. Suprnova's own `validate!` macro is the runtime
cross-field / contextual entry point; the two complement each other
but live in different namespaces.

## Why Suprnova diverges

Laravel discovers routes, commands, mail templates, model classes,
factories, observers, and policies at runtime - through reflection,
filesystem scanning, and string-based dispatch. PHP makes that cheap
(autoloading + opcache amortise the cost), and the developer
experience is excellent: drop a file in the right directory and it
shows up.

That model doesn't fit Rust. We don't have runtime reflection on
trait impls, runtime is a single statically-linked binary, and
filesystem scans at boot are a worse fit for a process model where
each binary serves millions of requests.

So Suprnova does the same job at compile time. Routes are validated,
component names are checked against the pages directory, mail
templates are embedded via `include_str!`, route names are checked
for uniqueness through inventory, models register themselves in an
inventory the framework drains at boot, commands the same. The
developer experience is similar - drop a file, add a `#[command]`
or `#[suprnova::model]`, run the binary - but the wiring happens
before `main` instead of at the first request.

The trade is that misspellings, missing components, and broken
references are build errors instead of runtime errors, and there's
zero per-request reflection cost.

## Next

- [Routing](routing.md) - full `routes!` expansion, naming, model binding
- [Controllers](controllers.md) - `#[handler]` and `#[request]` together
- [Eloquent](eloquent.md) - `#[suprnova::model]` and friends in context
- [Validation](validation.md) - `validate!`, contextual rules, async rules
- [Console](console.md) - `#[command]` and `#[derive(Command)]` end to end
- [Testing](testing.md) - `#[suprnova_test]`, `expect!`, fakes


---

<!-- /docs/error-model -->

# Error Model

This chapter is the model underneath Suprnova's error handling - the
types, the conversion contract, and the safety guarantees the framework
gives you for free. For day-to-day handler patterns (`?`, returning
errors, building custom domain errors) see [Error Handling](errors.md);
this chapter explains *why* those patterns work the way they do.

If you remember one thing from this page: **errors in Suprnova are
values, not exceptions**. Every error eventually becomes an
`HttpResponse` via a single, total conversion. There is no global
exception handler because there is no global exception.

## The shape

Suprnova's error model has five moving parts:

| Type | Role |
|---|---|
| `Response = Result<HttpResponse, HttpResponse>` | The contract every handler satisfies - both arms are already responses |
| `FrameworkError` | The framework's canonical error enum; every internal error path produces one |
| `AppError` | Ad-hoc domain error for inline use without a dedicated type |
| `HttpError` (trait) | What your own typed domain errors implement to get a status + message |
| `ValidationErrors` | The Laravel/Inertia-shaped error bag for per-field failures |

`FrameworkError` and the framework's concrete error types use `From`
implementations. A hand-written `HttpError` must be mapped with
`FrameworkError::from_http_error` before `?`; there is no blanket
`From<T: HttpError>` implementation. The middleware chain converts errors
at the request boundary, and the panic handler converts an unwind.
Ordinary errors then share the common body renderer and 5xx sanitisation
rule.

## `Response` is `Result<HttpResponse, HttpResponse>`

Every handler returns this:

```rust
pub type Response = Result<HttpResponse, HttpResponse>;
```

Both arms carry the same payload type, which is the whole point. When
the middleware chain finishes executing your handler it collapses the
result with one line:

```rust
result.unwrap_or_else(|e| e)
```

The framework does not need to know whether your handler "succeeded"
or "failed" - both arms are already rendered HTTP responses. The
distinction exists only so `?` can do its job:

```rust
use suprnova::{Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    // `?` short-circuits on Err. Each conversion below produces an
    // HttpResponse via a From impl - the chain collapses both arms.
    let id: i64 = req.param("id")?.parse().map_err(|_| {
        suprnova::FrameworkError::param_parse("id", "i64")
    })?;
    let user = User::find_or_fail(id).await?;  // 404 if missing
    Ok(json_response!({ "user": user }))
}
```

That single contract - every error path produces an `HttpResponse`
through `From` - is the core of the model. Everything else in this
chapter is what the various `From` impls actually do.

### Why Suprnova diverges

Laravel throws exceptions and routes them through a global `Handler`
class registered in `app/Exceptions/Handler.php`. The framework
catches everything, asks the handler "what do I render?", and emits
the response. PHP's unwinding-exception model makes this natural.

Rust has no unwinding exceptions in user code. Suprnova's equivalent
is the `From<FrameworkError> for HttpResponse` impl plus `Exceptions`.
The conversion renders the response; `Exceptions` runs callbacks and sends
unhandled failures through the configured `Reporter`. The built-in Sentry
protocol driver reaches Rustrak, Sentry and GlitchTip. `ErrorOccurred`
remains an application event for 5xx responses. See
[Error Reporting](error-reporting.md) for configuration and scrubbing.

## `FrameworkError` - the canonical enum

Every error path inside the framework - extractors, route binding,
the container, validation, the database layer, storage - produces a
`FrameworkError`. It's an enum with seventeen variants, each tagged
with its HTTP status:

```rust
pub enum FrameworkError {
    ServiceNotFound { type_name: &'static str },        // 500
    ParamError { param_name: String },                   // 400
    ValidationError { field: String, message: String },  // 422
    Database(String),                                    // 500
    Internal { message: String },                        // 500
    Domain { message: String, status_code: u16 },        // *
    Validation(ValidationErrors),                        // 422
    Unauthorized,                                        // 403
    Denial { message: String, status_code: u16, code: String }, // the denial's status, 403 by default
    ModelNotFound { model_name: String },                // 404
    ParamParse { param: String, expected_type: &'static str }, // 400
    UnsupportedMediaType,                                // 415
    PrecognitionSuccess,                                 // 204
    PrecognitionFailure(ValidationErrors),               // 422
    AlreadyReported,                                     // CLI-only
    RateLimited { retry_after: Option<Duration>, message: String }, // 429
    Timeout { elapsed: Duration, message: String },      // 504
    External { message: String, source: Arc<dyn Error + Send + Sync> }, // 500
}
```

You rarely match on the variant. You construct one through a
convenience constructor and let `?` do the rest:

```rust
use std::time::Duration;
use suprnova::FrameworkError;

// All of these produce a FrameworkError with the right status:
FrameworkError::not_found("User");                    // → ModelNotFound, 404
FrameworkError::bad_request("Bad input");             // → Domain, 400
FrameworkError::param("user_id");                     // → ParamError, 400
FrameworkError::param_parse("user_id", "i64");        // → ParamParse, 400
FrameworkError::validation("email", "required");      // → ValidationError, 422
FrameworkError::domain("Conflict", 409);              // → Domain, 409
FrameworkError::internal("disk full");                // → Internal, 500
FrameworkError::database("timeout");                  // → Database, 500
FrameworkError::timeout(Duration::from_secs(30), "waiting for the export"); // → Timeout, 504
```

There are no `unauthorized()` or `forbidden()` constructors on
`FrameworkError` - `Unauthorized` is a fixed variant carrying the
Laravel "This action is unauthorized." message at 403, and 401 cases
go through `AppError::unauthorized` (next section). Note: the variant
is named `Unauthorized` but the status is 403 because it models
Laravel's authorization rejection, not HTTP authentication.

### Automatic conversion

`FrameworkError` implements `From<sea_orm::DbErr>` and
`From<opendal::Error>` so database and storage errors flow through `?`
without a wrap:

```rust
use suprnova::{DB, FrameworkError};
use sea_orm::ActiveModelTrait;

pub async fn create_user(new_user: ActiveModel) -> Result<Model, FrameworkError> {
    // Both `?` calls here convert into FrameworkError automatically:
    // - DB::get returns Result<_, FrameworkError>
    // - insert returns Result<_, DbErr>, which has From<DbErr> for FrameworkError
    let user = new_user.insert(&*DB::get()?).await?;
    Ok(user)
}
```

If your code returns `Result<_, FrameworkError>`, every common error
your dependencies produce already converts into it. The
controller's `?` does no work beyond converting one error type into
another.

### Wrapping context

When you need to re-raise an error with operation context, use
`.context()`:

```rust
db.insert(user).await
    .map_err(FrameworkError::from)
    .map_err(|e| e.context("creating new user"))?;
```

The message becomes `"creating new user: <original>"`. The variant is
preserved where it matters - `Validation`, `ValidationError`,
`PrecognitionFailure`, `PrecognitionSuccess`, `Unauthorized`, `Denial`,
`ModelNotFound`, `ParamParse`, `UnsupportedMediaType`,
`AlreadyReported`, `RateLimited`, `Timeout`, and `External` keep their structure
so the response renderer still emits the correct shape (and, for
`External`, so the wrapped source survives). Plain message-carrying
variants (`Internal`, `Database`, `Domain`) flatten into a `Domain`
with the prefixed message.

### Wrapping a foreign error

Every other variant stringifies what it wraps. `from_external_with` keeps the original error
reachable, so logs can render the whole chain and code can still ask what actually failed:

```rust
use suprnova::FrameworkError;

let row = sqlx_like_query()
    .await
    .map_err(|e| FrameworkError::from_external_with("verify query failed", e))?;
```

`from_external(e)` is the same thing with the error's own `Display` as the message. Both map to
HTTP 500.

To inspect the original, use `external_source()` rather than `source()`:

```rust
if let Some(src) = err.external_source() {
    if let Some(db) = src.downcast_ref::<sea_orm::DbErr>() {
        // decide whether this is worth retrying
    }
}
```

`std::error::Error::source()` hands back the shared `Arc` handle, not the wrapped error, so
downcasting through it returns `None`. `external_source()` dereferences the handle first.

The framework renders the full chain into the 5xx log line and into the `debug_message` field it
adds when `APP_DEBUG=true`, so a wrapped error's text is never lost.

### Preserving rate-limit hints

`RateLimited` exists so a downstream `Retry-After` hint survives the trip through the error
system as a `Duration` instead of collapsing into message text:

```rust
use std::time::Duration;
use suprnova::FrameworkError;

let err = FrameworkError::rate_limited(
    Some(Duration::from_secs(30)),
    "push provider rejected the batch",
);

assert_eq!(err.retry_after(), Some(Duration::from_secs(30)));
assert_eq!(err.status_code(), 429);
```

`retry_after()` returns `None` for every other variant and for throttles that arrived without a
hint. The variant renders as HTTP 429, and `.context(...)` preserves it rather than flattening to
`Domain`, so the duration is never stripped by adding operation context.

### Telling a passed deadline from a failure

`Timeout` says that a deadline passed before the awaited work finished. It
carries the deadline as `elapsed` and what was awaited as `message`. The
workflow wait returns it: `WorkflowHandle::wait_with_timeout` and
`wait_with_options` end with `FrameworkError::Timeout` when the workflow is
still pending or running at the deadline (see
[Workflows](workflows.md#waiting-on-results)). A failed status query is a
different error, so a caller can match the two apart:

```rust
use std::time::Duration;
use suprnova::FrameworkError;

let err = FrameworkError::timeout(Duration::from_secs(30), "waiting for the export");

assert!(err.is_timeout());
assert_eq!(err.status_code(), 504);
assert_eq!(err.to_string(), "Timed out after 30s: waiting for the export");
```

The error does not cancel the work. It renders as HTTP 504, and like every
5xx the client sees the generic `Internal Server Error` message while the
detail goes to the logs. `.context(...)` preserves the variant, so a caller
further up can still match on it.

## `AppError` - ad-hoc domain errors

For one-off errors where you don't want to define a dedicated type,
use `AppError`. It implements `HttpError` and has a `From` into
`FrameworkError`, so `?` works directly:

```rust
use suprnova::{AppError, Request, Response, json_response};

pub async fn transfer(req: Request) -> Response {
    let amount: i64 = req.param("amount")?.parse()
        .map_err(|_| AppError::bad_request("amount must be a number"))?;

    if amount <= 0 {
        return Err(AppError::unprocessable("amount must be positive").into());
    }

    if amount > 1_000_000 {
        return Err(AppError::forbidden("amount exceeds daily limit").into());
    }

    Ok(json_response!({ "transferred": amount }))
}
```

The constructors map cleanly onto Laravel's `abort($status, $msg)`
shape:

| `AppError::*` | Status |
|---|---|
| `bad_request(msg)` | 400 |
| `unauthorized(msg)` | 401 |
| `forbidden(msg)` | 403 |
| `not_found(msg)` | 404 |
| `conflict(msg)` | 409 |
| `unprocessable(msg)` | 422 |
| `new(msg)` | 500 |
| `.status(code)` | any |

Note `AppError::unauthorized` is **401** (HTTP authentication missing),
while `FrameworkError::Unauthorized` is **403** (authorization denied,
matching Laravel's policy rejection). They mean different things; pick
the one that matches the failure.

## `HttpError` - custom typed errors

When the same domain error appears in many places, model it as a
type. Implement `HttpError` and the conversion is yours:

```rust
use suprnova::HttpError;

#[derive(Debug)]
pub struct InsufficientFunds {
    pub available: i64,
    pub requested: i64,
}

impl std::fmt::Display for InsufficientFunds {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Insufficient funds: have {}, need {}",
            self.available, self.requested)
    }
}

impl std::error::Error for InsufficientFunds {}

impl HttpError for InsufficientFunds {
    fn status_code(&self) -> u16 { 402 }
    fn error_message(&self) -> String {
        format!("Need {} units, only {} available.",
            self.requested, self.available)
    }
}
```

`HttpError` has two methods, both with defaults:

```rust
pub trait HttpError: std::error::Error + Send + Sync + 'static {
    fn status_code(&self) -> u16 { 500 }
    fn error_message(&self) -> String { self.to_string() }
}
```

### Bridging to `?`

A naive `impl<T: HttpError> From<T> for FrameworkError` would conflict
with the existing `From<AppError>` impl (because `AppError` itself
implements `HttpError`). Suprnova resolves the orphan-rule problem
with an explicit bridge constructor instead:

```rust
use suprnova::{FrameworkError, HttpError};

pub async fn debit(account: &mut Account, amount: i64) -> Result<(), FrameworkError> {
    account.withdraw(amount)
        .map_err(FrameworkError::from_http_error)?;
    Ok(())
}
```

The status code and message are taken from `HttpError::status_code`
and `HttpError::error_message` and stored in a `FrameworkError::Domain`
variant. The response renderer then follows the normal `Domain` path.

### `#[domain_error]` for boilerplate-free types

If you want the typed-error pattern without writing the `Display`,
`Error`, and `HttpError` impls by hand, use the `#[domain_error]`
attribute macro:

```rust
use suprnova::domain_error;

#[domain_error(status = 404, message = "User not found")]
pub struct UserNotFoundError;

#[domain_error(status = 402, message = "Insufficient funds")]
pub struct InsufficientFundsError {
    pub available: i64,
    pub requested: i64,
}
```

`#[domain_error]` generates the full impl set *including*
`From<YourError> for FrameworkError`, so `?` works directly with no
bridge call:

```rust
pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;
    let user = User::find(id).await?
        .ok_or_else(|| FrameworkError::from(UserNotFoundError))?;
    Ok(json_response!({ "user": user }))
}
```

The three tiers of custom error story - `AppError` for inline,
`#[domain_error]` for typed-with-macro, hand-rolled `HttpError` for
full control - give you the right tool at every level of formality.

## `ValidationErrors` - the Laravel-shaped error bag

When a request fails validation, Suprnova emits the same JSON shape
Laravel and Inertia front-ends expect:

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "email": ["The email field must be a valid email address."],
        "password": ["The password must be at least 8 characters."]
    },
    "request_id": "8f9e1a2b-c3d4-..."
}
```

You usually don't build this by hand - `#[derive(Validate)]` on a
form request and the `validator` crate behind it produces a
`validator::ValidationErrors` which Suprnova converts via
`ValidationErrors::from_validator`. But the type is public when you
need it:

```rust
use suprnova::{FrameworkError, ValidationErrors};

pub async fn after_validation(payload: &Signup) -> Result<(), FrameworkError> {
    let mut errs = ValidationErrors::new();

    if payload.email.ends_with("@example.com") {
        errs.add("email", "example.com addresses are not allowed");
    }
    if payload.password == payload.email {
        errs.add("password", "password must not match email");
    }

    errs.into_result().map_err(FrameworkError::Validation)
}
```

`add_to_bag` scopes errors under a named bag (Laravel's
`withErrors($errors, 'profile')` shape) by prepending the bag name
with a `.` separator:

```rust
let mut errs = ValidationErrors::new();
errs.add_to_bag("profile", "bio", "must be under 280 characters");
errs.add_to_bag("billing", "card", "expired");
// errors map: { "profile.bio": [...], "billing.card": [...] }
```

`retain_fields` keeps only the listed entries - used internally by
Precognition's `Precognition-Validate-Only` header so the server runs
full validation but reports errors only for the fields the client
asked about.

## The conversion contract

When a `FrameworkError` reaches an HTTP boundary it goes through
`From<FrameworkError> for HttpResponse`. Three things happen, in
order:

1. **Status routing**. The variant's `status_code()` is read once.
2. **Logging + observability**. 5xx fires `tracing::error!` and
   dispatches `ErrorOccurred`; 4xx fires `tracing::warn!`. Both carry
   the request id when one is in scope.
3. **Body rendering**. A JSON body in the Laravel shape, sanitised
   for 5xx.

### The ordinary body shape

Ordinary error responses that reach the common renderer follow this JSON
skeleton:

```json
{
    "message": "<human readable>",
    "errors": { "field": ["msg", ...] },
    "request_id": "<uuid>" | null,
    "debug_message": "<dev only>"
}
```

- `message` is always present on these ordinary responses.
- `errors` only appears for validation-style errors
  (`Validation`, `ValidationError`) - both render the same shape so
  consumers parse one path.
- `request_id` appears on these ordinary responses (`null` when outside a
  request scope, such as during early boot or in tests with no request
  context).
- `debug_message` only appears for 5xx when `APP_DEBUG=true`. It is
  strictly additive - production clients must not key on it. With
  debug on, a browser or an Inertia visit gets the
  [development error page](#the-development-error-page) in place of
  this body.

Three special variants return before request-id injection:

- `PrecognitionSuccess` is a bodyless 204 response.
- `PrecognitionFailure` contains the validation body plus Precognition
  headers.
- An accidentally HTTP-rendered `AlreadyReported` sentinel is a generic
  500 response containing only `message`.

### The 5xx sanitisation rule

This is the safety guarantee worth memorising. For any error with
status ≥ 500 that reaches the common renderer, the JSON body's
`message` is replaced with the literal string:

```json
{ "message": "Internal Server Error", "request_id": "..." }
```

The raw error detail does **not** leak to the response body. It goes
to:

- the `tracing::error!` log entry, with the request id and status
- the `ErrorOccurred` event, which any listener can pick up

When `APP_DEBUG=true` (false by default outside `local`/`dev`/`test`),
the response also carries a `debug_message` field with the raw detail -
but `message` stays generic in both modes, so frontends and clients
can't accidentally couple to dev-only data. A browser or an Inertia visit
gets the [development error page](#the-development-error-page) instead,
which shows the same detail as HTML.

This is the contract that lets you call `FrameworkError::internal("db
connection refused: password mismatch on user 'app_rw'")` without
leaking the password to the wire. The `message` you pass is for
operators reading logs; the `message` the client sees is `"Internal
Server Error"`.

For 4xx errors, the caller-facing message is preserved - `404 User
not found`, `400 Missing required parameter: user_id`. These are
domain errors the client needs to act on, not internal failures.

### Where the contract lives

The whole conversion is one function - `impl
From<FrameworkError> for HttpResponse` in
`framework/src/http/response.rs`. Read it once and you've read the
entire error rendering surface of Suprnova. There is no other path.

## The panic boundary

A panic in a middleware or handler would otherwise propagate up the
per-connection task and tear down the hyper service mid-response,
leaving the client with a TCP reset and no HTTP response. Suprnova
catches it.

`execute_chain_safely` in `framework/src/server.rs` wraps the
middleware chain in `AssertUnwindSafe(...).catch_unwind().await`. On
a panic it:

1. Extracts the panic payload (handles `&'static str` and `String`
   payloads; anything else surfaces as `"panic with non-string
   payload"`).
2. Logs `tracing::error!` with the request method, path, and id.
3. Constructs `FrameworkError::internal(format!("request handler
   panicked: {msg}"))` and routes it through the *same*
   `From<FrameworkError> for HttpResponse` conversion every other 5xx
   uses.
4. Echoes the request id back as `X-Request-Id`.

The panic payload stays in the log entry; the client gets the
sanitised `{"message": "Internal Server Error"}` body. With debug on, a
browser or an Inertia visit gets the
[development error page](#the-development-error-page) instead, with the
panic message and the line that panicked. Observability
listeners that fire on `ErrorOccurred` for returned 5xx errors also
fire on panics - there is no separate panic-event surface to wire up.

The same panic-recovery pattern is used by:

- WebSocket handlers (`framework/src/server.rs`)
- Scheduled tasks (`framework/src/schedule/mod.rs`)
- Workflows (`framework/src/workflow/mod.rs`)
- The `Supervisor` trait (broadcasting)

A panic in one of these subsystems is logged and either translated to
an error state or auto-restarted; it does not bring down the worker
task.

## The development error page

With debug mode on, a failed request is hard to read as a
`debug_message` string in a browser tab. So for a browser or an Inertia
visit, Suprnova replaces a 5xx built from a failure with the development
error page: one HTML document that shows what failed, where, and on
which request.

### When it renders

The server replaces a response with the page when all of these hold:

- `Config::is_debug()` returns `true`: `APP_DEBUG=true`, or `APP_DEBUG`
  unset in the `local`, `development`, or `testing` environment.
- The status is 500 or above.
- The response carries an `ErrorReport`: a `FrameworkError` became the
  response, the panic boundary caught a panic, or one of the framework's
  middleware answered a failure with a 5xx.
- The request is an Inertia visit (`X-Inertia: true`), or its `Accept`
  header lists `text/html`.

Everything else stays as it is. A 4xx keeps its body, and so does a 5xx
your handler built itself without an error. A client whose `Accept`
header doesn't list `text/html` (`application/json`, `*/*`, or no
`Accept` at all) and isn't an Inertia visit keeps the JSON body with
`debug_message`. With debug off, you receive a minimal HTML view for a
5xx when your request accepts `text/html` and is not an Inertia visit. You
see its status without error details or frames. Your Inertia visits keep
the application error page, and your JSON requests keep their JSON body.
No frames or request details are recorded for this production view.

The page is built in the server, after the panic boundary, so it covers
panics as well as returned errors. For these responses it takes the
place of the app's Inertia error page. It keeps the status, the error
report, `Set-Cookie`, `X-Request-Id`, and the other headers that describe
the request, and it replaces the ones that described the old body.

To see it, run the app with `APP_DEBUG=true` and open a route that fails
in a browser. From a terminal, ask for HTML:

```bash
curl -H 'Accept: text/html' http://localhost:8000/invoices/42
```

### What it shows

- The type of what failed, above the headline, as Laravel's page shows
  the exception class. An error built with `FrameworkError::from_external`
  or `from_external_with` is named by the type it wraps, as
  `std::any::type_name` spells it: `std::io::error::Error` for an
  `std::io::Error`. Any other `FrameworkError` is named by its variant,
  such as `FrameworkError::ModelNotFound`, and a panic is named `panic`.
  `ErrorReport::type_name()` returns the same name.
- The error chain, one line per source, or the panic message and the
  `file:line:column` where the panic was raised.
- The site that created the error: the line of the call to a
  `FrameworkError` or `AppError` constructor, or of a `?` that converts
  the error.
- The stack frames recorded at that site. Your application's frames are
  listed: your handlers and middleware, and the code they call. Each run
  of frames from the framework, the async runtime, other dependencies,
  and the standard library is collapsed behind a count. You see the
  source line and a few nearby lines for every application frame whose
  source file is readable. Each source error with recorded frames has
  its own trace.
- The request: the method, the path, the query parameters, the headers,
  the matched route pattern, and the request id.

Frames are recorded for an error created on the request's own task by a
`FrameworkError` or `AppError` constructor or by a `From` conversion,
which includes `?`. An error built as a struct literal, or created on a
task the request spawned, has no frames, and the page says so.

The constructors and conversions are `#[track_caller]`, so the site is
the line that called them, even in a build without debug info. A call
made inside a function that is not `#[track_caller]` reports that
function's line instead: with `.map_err(FrameworkError::from)?`, the site
is a line of `Result::map_err` in the Rust toolchain, and the frames show
the handler that called it. A build without debug info names each
frame's function but not its line. The frame that created the error is
the exception: it shows the creation site as its location.

### Open a frame in your editor

Set `APP_EDITOR` and every frame with a location links to its line in
your editor, as Laravel's `app.editor` does:

```bash
APP_EDITOR=vscode
```

- A name Laravel knows uses that editor's URL format. `vscode` links to
  `vscode://file/{file}:{line}` and `phpstorm` to
  `phpstorm://open?file={file}&line={line}`. The other names are
  `antigravity`, `atom`, `cursor`, `emacs`, `fleet`, `idea`, `kiro`,
  `macvim`, `neovim`, `netbeans`, `nova`, `sublime`, `textmate`, `trae`,
  `vscode-insiders`, `vscode-insiders-remote`, `vscode-remote`,
  `vscodium`, `windsurf`, `xdebug`, and `zed`.
- A value that holds `{file}` is a template:
  `APP_EDITOR=myeditor://{file}#{line}`.
- Any other value `name` links to `name://open?file={file}&line={line}`.

`{file}` is the absolute path of the frame's file. A relative location
is resolved the way the page finds source lines: from the working
directory first. `{line}` is the frame's line. Without `APP_EDITOR`, no
frame carries a link.

### What it never shows

- The values of the `Authorization`, `Proxy-Authorization`, `Cookie`, and
  `Set-Cookie` headers, and of every header and query parameter whose
  name contains `token`, `secret`, `password`, `key`, or `signature` in
  any letter case. Each value reads `[redacted]`.
- The value of every such parameter anywhere else in the text the page
  shows: in a `Referer` or an `X-Original-URI` header that repeats the
  request's URL, `/reset?token=...` reads `/reset?token=[redacted]`.
- The password of a URL with credentials:
  `postgres://app:hunter2@db/app` reads `postgres://app:[redacted]@db/app`.
- The request body, environment variables, and configuration values.
  The page never reads them.

### What it loads

Nothing. The page is one HTML document with an inline style sheet and no
JavaScript. It requests no script, style sheet, font, image, or frame,
so it renders when the frontend build, the Vite manifest, Inertia, or the
view layer is what failed. Every value it shows is HTML-escaped. The
response carries `Cache-Control: no-store` and a
`Content-Security-Policy` of `default-src 'none'; style-src
'unsafe-inline'; base-uri 'none'; form-action 'none'`, which allows no
script.

### Why Suprnova diverges

Laravel's exception page shows the request body, lists the SQL queries
the request ran, and runs a bundled JavaScript app that adds a "copy as
Markdown" button. Suprnova's page differs on all three:

- It never shows the request body. A body often holds the passwords,
  tokens, and personal data the header redaction exists to protect, and
  a development server on a shared network or behind a tunnel shows the
  page to whoever triggers the error.
- It runs no script and loads nothing, so it renders in the situations
  where a developer needs it most: a broken frontend build, a missing
  Vite manifest, or a failure inside Inertia.
- It lists no queries. SQL debugging is separate work, outside this
  page.

## Hooking observability with `ErrorOccurred`

`ErrorOccurred` is a built-in event the framework dispatches on every
5xx response (including the ones synthesised from panics):

```rust
pub struct ErrorOccurred {
    pub error_message: String,
    pub status_code: u16,
    pub request_id: Option<String>,
}
```

Listen for it the same way you listen for any event:

```rust
use std::sync::Arc;
use suprnova::{ErrorOccurred, EventFacade, FrameworkError, Listener};

pub struct SentryReporter;

#[suprnova::async_trait]
impl Listener<ErrorOccurred> for SentryReporter {
    async fn handle(&self, evt: &ErrorOccurred) -> Result<(), FrameworkError> {
        sentry::capture_message(&evt.error_message, sentry::Level::Error);
        Ok(())
    }
}

// In bootstrap.rs:
EventFacade::listen::<ErrorOccurred, _>(Arc::new(SentryReporter)).await;
```

This is the Suprnova equivalent of Laravel's `report()` callback on
the global exception handler. The event arrives with the original
unsanitised `error_message` (the body the client sees is still
sanitised), the status code, and the correlatable request id.

### Rendering the full chain: `render_error_chain`

`thiserror`'s generated `Display` prints only an error's own message,
so a `FrameworkError::External`'s wrapped `source` is invisible unless
something walks the chain. `render_error_chain` does that walk and
joins the result with `": "`, the same separator `.context()` uses -
the framework calls it before building `error_message` above and
before the matching 5xx log line, which is why a wrapped error doesn't
lose its cause in either place.

Reach for it yourself when a listener or a log sink needs the same
full-chain rendering, for example re-wrapping `error_message` before
forwarding it to a sink that only takes a flat string:

```rust
use suprnova::render_error_chain;

let chain = render_error_chain(&err);
// "loading users: connection refused (os error 111)"
```

## Abort helpers

Three free functions short-circuit a handler at a given status. They
mirror Laravel's `abort` / `abort_if` / `abort_unless`:

```rust
use suprnova::{abort_with, abort_if, abort_unless, Auth, Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    abort_unless(Auth::check(), 401, "must be logged in")?;
    abort_if(req.param("id")? == "0", 404, "User not found")?;
    abort_with(503, "scheduled maintenance")?;
    Ok(json_response!({ "ok": true }))
}
```

Each returns `Result<(), FrameworkError>`. Use them with `?`. The
underlying error is `FrameworkError::Domain { message, status_code }`,
so it renders through the same body shape and sanitisation rules as
every other error. Out-of-range status codes are coerced to 500 by
the response renderer's status validation; you don't need to defend
against bad input at the call site.

## The CLI sentinel: `AlreadyReported`

One variant of `FrameworkError` has no HTTP meaning. `AlreadyReported`
is constructed via `FrameworkError::silent()` and used by the console
dispatcher when clap has already formatted and printed its own
argument-parse error. The binary's `main` translates the sentinel to
a non-zero exit code without `eprintln`, so users never see two error
messages for the same failure.

If `AlreadyReported` ever reaches an HTTP response converter, it
indicates a request handler accidentally returned `silent()`. The
converter logs a loud `tracing::error!` identifying the leak and
returns a generic 500 containing only
`{"message": "Internal Server Error"}`. The variant has no business in
the request path, and the loud log makes the bug observable instead of
silent.

You don't normally see this variant; it's documented here because the
enum is `HTTP-flavoured` and the otherwise-unexplained variant would
puzzle anyone reading the source.

## Safety guarantees, in summary

The contract Suprnova gives you:

- **Total conversion**. Every `FrameworkError` produces an
  `HttpResponse`. There is no error path that crashes the server or
  drops the connection silently.
- **Sanitised 5xx**. The common renderer replaces the wire `message` for
  any 5xx with `Internal Server Error`; raw detail flows to logs and
  `ErrorOccurred`. An accidentally HTTP-rendered `AlreadyReported`
  sentinel returns the same generic message without `request_id`.
- **Optional debug visibility**. `APP_DEBUG=true` adds a
  `debug_message` field for ordinary 5xx responses, never `message`.
  Production clients cannot accidentally couple to dev-only data. A
  browser or an Inertia visit gets the development error page instead,
  which redacts credentials and never shows the request body,
  environment variables, or configuration values.
- **Correlatable request ids**. Every ordinary error body that reaches the
  common renderer carries the request id (or `null` when no request scope
  exists); the same id appears in the log line and the `ErrorOccurred`
  event. The three early-return variants described above bypass this field.
- **Panic recovery**. Panics in handlers and middleware are caught,
  logged, and routed through the same `From` impl as returned errors.
  No connection drop, no observability gap.
- **One common shape for ordinary errors**. Validation errors, parameter
  errors, panics, custom domain errors, and storage failures that reach the
  common renderer use the same JSON skeleton. The three special variants
  documented above have distinct wire shapes.

## Where each piece lives

| Piece | File |
|---|---|
| `FrameworkError`, `AppError`, `HttpError`, `ValidationErrors` | `framework/src/error.rs` |
| `render_error_chain` | `framework/src/error.rs` |
| `From<FrameworkError> for HttpResponse` (conversion + sanitisation) | `framework/src/http/response.rs` |
| `abort`, `abort_if`, `abort_unless` | `framework/src/http/abort.rs` |
| `execute_chain_safely` (panic boundary) | `framework/src/server.rs` |
| The development error page | `framework/src/error/debug_page.rs` |
| Stack frame recording and classification | `framework/src/error/frames.rs` |
| `ErrorOccurred` event | `framework/src/events/builtins.rs` |
| `#[domain_error]` macro | `suprnova-macros/src/domain_error.rs` |

## Next

- [Error Reporting](error-reporting.md) - tracker drivers, helpers and scrubbing
- [Error Handling](errors.md) - the practical handler patterns that
  use this model
- [Request Lifecycle](lifecycle.md) - where in the request flow the
  error conversion runs
- [Validation](validation.md) - `#[derive(Validate)]`, form requests,
  and how `ValidationErrors` gets populated
- [Responses](responses.md) - `HttpResponse` builders, headers,
  cookies, streaming
- [Events](events.md) - listening to `ErrorOccurred` and other
  built-in events


---

<!-- /docs/lock-policy -->

# Lock Policy

Suprnova is a single long-lived Tokio process, not a fleet of short-lived
PHP workers. Every process-global registry, singleton, and shared cache
you bind at boot outlives every request that touches it. That changes one
small but consequential thing about how you reach for `std::sync::Mutex`
and `std::sync::RwLock`: a panic while holding a guard *poisons the lock*
for the rest of the process's life, and the next caller has to decide
what to do about it. This chapter is the project-wide policy for that
decision - two sanctioned patterns, when to pick which, and why you
should never reach for a raw `.lock().unwrap()` in framework or
application code.

## Why this chapter exists

In Laravel you never thought about poisoned locks because there were
none. PHP is shared-nothing: a fatal error tears down one request's
process, the next request starts in a fresh one, no in-memory state
survives to corrupt. Suprnova runs the opposite way. The process boots
once, registries get populated, and they stay alive for the entire
lifetime of the binary. A handler that panics while holding a write
guard on a process-global `RwLock` leaves that lock *poisoned* - every
subsequent `.read()` and `.write()` returns `Err(PoisonError)` forever,
unless someone explicitly recovers it.

The default Rust idiom - `.lock().unwrap()` - converts that `Err` into a
panic. Which then becomes another poisoned lock somewhere up the stack.
Which then takes down the next subsystem that touches it. One bad request
cascades into a half-dead process.

The policy below prevents that cascade.

> **Scope.** This applies to `std::sync::Mutex` and `std::sync::RwLock`,
> which carry poison state. The async cousins in `tokio::sync` (`Mutex`,
> `RwLock`, `Semaphore`) do *not* poison - a panic while holding a
> `tokio::sync::Mutex` guard drops the guard cleanly and the next
> `.lock().await` succeeds. If your hot path is async and you don't
> need to acquire the guard from a sync context (a `Drop` impl, a
> framework callback, a CLI subcommand), prefer the Tokio variants and
> the question goes away.

## The two sanctioned patterns

Every place in the framework that holds a `std::sync` lock uses one of
exactly two patterns. Pick the same way in your own code.

### Pattern 1 - Map poison to a returned error

When the caller already returns `Result<_, E>` and one more `?` doesn't
change its shape, surface the poison as an error and let the request
fail cleanly. The framework uses internal `pub(crate)` helpers
(`lock::read`, `lock::write`, `lock::lock`) that map a poisoned guard
to `FrameworkError::internal("<context> lock poisoned")`, embedding a
caller-supplied label so logs can tell which subsystem poisoned without
every call site wrapping the error itself.

The pattern those helpers encode is short enough to write inline in your
application code:

```rust
use std::collections::HashMap;
use std::sync::RwLock;
use suprnova::FrameworkError;

static FEATURE_FLAGS: RwLock<HashMap<String, bool>> = RwLock::new(HashMap::new());

pub fn enable(flag: &str) -> Result<(), FrameworkError> {
    let mut guard = FEATURE_FLAGS
        .write()
        .map_err(|_| FrameworkError::internal("feature flags lock poisoned"))?;
    guard.insert(flag.to_string(), true);
    Ok(())
}

pub fn is_enabled(flag: &str) -> Result<bool, FrameworkError> {
    let guard = FEATURE_FLAGS
        .read()
        .map_err(|_| FrameworkError::internal("feature flags lock poisoned"))?;
    Ok(guard.get(flag).copied().unwrap_or(false))
}
```

Inside a handler, `is_enabled(...)?` collapses through the same
`FrameworkError → HttpResponse` path every other framework error uses:
the client gets a sanitised 500 with `{"message": "Internal Server
Error"}`, the structured log captures the labelled poison message, the
request id is preserved end-to-end, and the rest of the process keeps
serving traffic. See the [Errors](errors.md) chapter for the full
conversion path.

Use this pattern when:

- The caller already returns `Result` (most fallible operations do).
- A poisoned lock represents a real, unrecoverable failure of the
  subsystem - there is no sane "partial truth" to fall back to.
- You want operators to *see* the poison in logs the next time the
  subsystem is touched. The labelled message is your forensic crumb.

The framework's notifications dispatcher, mail transport, mailable
registry, db event listeners, and named connection registry all use this
pattern. A panic in any one of them surfaces as a 500 on the next
request that hits the registry; everything else keeps running.

### Pattern 2 - Recover in place with `into_inner()`

When the caller's signature is *not* fallible (a `bool` lookup, a hot
routing check, a path the request lifecycle relies on) or when the
shared state is structurally safe to use after a partial write,
recover the guard and continue:

```rust
use std::collections::HashMap;
use std::sync::RwLock;

static ALLOWED_INCLUDES: RwLock<HashMap<&'static str, Vec<&'static str>>> =
    RwLock::new(HashMap::new());

pub fn allows(dto: &str, field: &str) -> bool {
    ALLOWED_INCLUDES
        .read()
        .unwrap_or_else(|e| e.into_inner())
        .get(dto)
        .map(|fields| fields.contains(&field))
        .unwrap_or(false)
}

pub fn register(dto: &'static str, fields: &'static [&'static str]) {
    let mut guard = ALLOWED_INCLUDES
        .write()
        .unwrap_or_else(|e| e.into_inner());
    guard.insert(dto, fields.to_vec());
}
```

`PoisonError::into_inner()` returns the guard despite the poison.
Subsequent reads and writes proceed normally - the lock stays poisoned
for `is_poisoned()` queries, but data flow is restored.

The framework has an internal `pub(crate)` helper for this half,
`lock::recover`, which takes a `Mutex` and goes on with the value when the
lock is poisoned. It is for a value that is whole after any panic: a list
that code of the framework pushes to and drains, or a value that code of
the framework replaces as one. The session middleware takes the locks of
its pending cookies, its remember tokens that wait to be revoked and its
list of fresh Magnetar sessions this way. The clean-up task that runs after
the request shares the list of fresh sessions, so a lock that refused after
a panic would end the clean-up.

The value must be whole because every code path that runs under the guard
is code of the framework. A closure of your application that runs under
the guard can panic between two of its writes. Where such a closure runs,
the code that goes on with the value must not keep what it finds. The
session is the example, and [Session](session.md) describes what the
middleware does with it.

The framework uses this pattern in `data::registry` (the include-set
allowlist read on every JSON:API response), `auth::manager` (the named
auth-provider map), `app::paths` (the resolved-paths cache), the
testing fakes for mail and events, the loaded-env-keys map in
config, and the session middleware's pending lists. Every one is a place
where either no caller has a `Result` to return, or the state is append-only and structurally safe to keep using.

Use this pattern when:

- The caller's signature is plain (`bool`, `&str`, a clone of a stored
  value) and changing it to `Result` would force every caller - sometimes
  every framework subsystem - to bubble.
- The shared state can tolerate a partial write. Append-only maps and
  caches are the typical shape: the worst case is a missing or stale
  entry, which the caller already handles (default-deny, fall back to
  primary, recompute).
- The hot path runs often enough that returning an error on every
  subsequent request would be operationally worse than degrading.

## How to choose between them

The decision rule, in one sentence: **if the worst case of using
post-poison state is a wrong answer with consequences, map to an error;
if it's a missing or stale entry the caller already handles, recover
in place.**

Walk it through:

1. **Is the caller's signature `Result<_, E>`?** If no, you have to
   recover in place - adding `Result` to a `bool` is usually a
   project-wide refactor and not worth it for a poison edge.
2. **If a half-written value were observed, would the application
   make a wrong decision with real-world consequences?** Charging a
   wrong customer, allowing an unauthorised include, granting access
   to the wrong tenant - that's "yes, map to an error." Returning
   `false` to "is this name registered?" and falling back to the
   primary pool - that's "no, recover in place."
3. **Is the state append-only or naturally idempotent on re-registration?**
   If yes, recover-in-place is safe. If a write is a state-machine
   transition that depends on the prior value, prefer map-to-error so
   you don't compound a corruption.

When in doubt, map to an error. A request returning 500 is a loud
signal you can fix; silent wrong answers are not.

## Never reach for `.lock().unwrap()`

The forbidden shape:

```rust
// NEVER - one panic anywhere in the call graph below
// this line poisons the lock and every subsequent caller
// turns the poison into another panic.
let mut guard = SOMETHING.lock().unwrap();
```

`.expect("…")` is the same thing with a nicer message. Both convert a
poisoned-lock `Err` into a panic that the request-lifecycle's
`AssertUnwindSafe(...).catch_unwind()` net catches and converts to a
500 - that net is a *last line of defence*, not licence to skip the
decision above. Public framework APIs and application code must pick
one of the two sanctioned patterns.

The two exceptions where `.unwrap()` is acceptable on a `std::sync`
lock:

- **Test setup that *wants* to assert poisoning was reached** -
  `framework/src/lock.rs`'s own poison-induction helper uses
  `.unwrap()` inside the panicking thread on purpose.
- **The error path of a poisoning operation that already failed** - by
  the time you're inside `poison_rw(...)`'s thread, the panic *is* the
  point.

If you're not in one of those, pick a pattern from the section above.

## What if my function returns `bool`?

This is the situation `ConnectionRegistry::has` lives in. It's a
`bool` lookup on the hot path of the executor's read-replica routing,
called inline as `if ConnectionRegistry::has("read_replica").await { … }`.
Widening it to `Result<bool, FrameworkError>` would force every caller
in the executor to `?`-bubble, propagating an internal-error code path
into routing decisions that just want a yes/no.

The recover-in-place pattern handles this - return `false` and let the
caller's fallback logic kick in (here, the executor drops back to the
primary pool, which is the safe behaviour anyway). To make sure
operators still see the condition, emit a one-shot `tracing::warn!` the
first time poison is observed:

```rust
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::RwLock;
use std::collections::HashMap;

static REGISTRY: RwLock<HashMap<String, ()>> = RwLock::new(HashMap::new());
static POISON_WARNED: AtomicBool = AtomicBool::new(false);

pub fn has(name: &str) -> bool {
    match REGISTRY.read() {
        Ok(g) => g.contains_key(name),
        Err(_) => {
            // Race-safe: only the first observer logs.
            if !POISON_WARNED.swap(true, Ordering::SeqCst) {
                tracing::warn!(
                    target: "myapp::registry",
                    "registry lock poisoned - `has({name})` degrading to false",
                );
            }
            false
        }
    }
}
```

The `swap`-based gate matters: `RwLock` poison is sticky, so without
the gate every subsequent call would re-fire the warning and flood your
logs. With the gate, you get exactly one warn per process per registry,
and a corresponding `Result`-returning getter (`get`, `register`) on
the same registry will surface the poison the next time anything
*actually needs* the lookup to succeed. That gives operators both
signals: an early "something is wrong" warn, and a hard 500 the moment
a request truly depended on the registry.

## What the framework already protects

You don't have to apply this policy to any state the framework owns -
it's already in place. Concretely:

- The named connection registry (`ConnectionRegistry::register`, `get`,
  `has`) maps poison to `FrameworkError::internal` on the writes and
  `Result`-returning reads; `has` degrades to `false` with the
  warn-once gate.
- The notifications dispatcher and factory registry, mailable registry,
  mail transport, mail memory capture, and DB event listeners all
  return `FrameworkError::internal` on poison.
- The `data::registry` include allowlist, `auth::manager` provider
  map, `app::paths`, the loaded-env-keys cache, and the in-memory
  testing fakes all recover in place.

Where you intersect those subsystems through their public API
(`Notification::send`, `Mail::send`, `Auth::user`, `DB::connection`,
the JSON:API response path), a poisoned framework lock surfaces as a
clean 500 - never a panic at your call site.

## Why Suprnova diverges

Laravel doesn't have a lock policy because it doesn't have long-lived
shared state. Each PHP request gets its own process, its own memory,
its own copies of every singleton. There's no in-memory registry to
poison and no concept of "the next request" inheriting damage from
the previous one - the runtime guarantees a clean slate.

Suprnova is built on Tokio, which gives you exactly the long-lived
shared state that PHP rules out. Cheap WebSockets, in-memory caches,
connection pools you don't pay to rebuild - all of these need
process-global registries that outlive any single request. That
capability is the whole point of moving to Rust for this style of app
(see the [introduction](introduction.md) for the framework's full
motivation). The cost of having it is that you now have to think
about what happens when a panicked thread leaves shared state in a
guarded condition, because there *is* shared state to leave.

The two-pattern policy is the smallest answer that keeps the
capability and removes the cost. Recover in place where the state is
safe to keep using; map to an error where you'd rather have a clean
500 than a wrong answer. Both options leave the rest of the process
serving traffic. Neither leaves a panicked unwrap waiting to take
down the subsystem above.

This is the same shape as the [fail-open vs fail-closed
decision](rate-limiting.md) the framework applies to unreachable cache
and rate-limit backends: an explicit policy choice at the call site,
not a default. Async-everywhere gives you long-lived state; the
framework gives you the playbook for keeping it honest.

## Next

- [Errors](errors.md) - how `FrameworkError::internal` becomes the
  sanitised 500 the client receives, with the labelled poison message
  preserved in your structured log.
- [Container](container.md) - where the process-global registries this
  policy protects actually live, and why task-local/thread-local
  scoping keeps tests from inheriting each other's bindings.
- [Lifecycle](lifecycle.md) - the panic boundary
  (`execute_chain_safely`) that catches the *last-resort* unwrap and
  converts it to a 500, so you understand exactly what the safety net
  does and why it isn't an excuse to skip the policy above.
- [Rate Limiting](rate-limiting.md) - the parallel `BackendErrorPolicy`
  story for backends that can be *unreachable* rather than poisoned;
  same explicit-choice principle, different failure mode.
- [Testing](testing.md) - how `TestContainer::fake` and the
  thread-local container layer keep parallel tests from polluting each
  other's registries, which is the test-time complement to the
  poison-handling story.


# The Basics

---

<!-- /docs/routing -->

# Routing

Routing is how Suprnova turns an inbound HTTP request into a handler call.
You declare your routes in `src/routes.rs` using the `routes!` macro (or
build a `Router` by hand), then `Server::from_config` takes that router
and runs it for the life of the process. Same shape as Laravel's
`routes/web.php`, with Rust types instead of facades.

```rust
// src/routes.rs
use suprnova::{routes, get, post, put, delete};
use crate::controllers;

routes! {
    get!("/", controllers::home::index).name("home"),
    get!("/users", controllers::users::index).name("users.index"),
    get!("/users/{id}", controllers::users::show).name("users.show"),
    post!("/users", controllers::users::store).name("users.store"),
    put!("/users/{id}", controllers::users::update).name("users.update"),
    delete!("/users/{id}", controllers::users::destroy).name("users.destroy"),
}
```

The macro expands to `pub fn register() -> Router { ... }`. Call it from
your bootstrap and hand the result to the server.

## HTTP verbs

One macro per verb. All seven take a path-then-handler pair and return a
builder you can chain `.name(...)` and `.middleware(...)` onto.

| Macro | Method | Use for |
|---|---|---|
| `get!`     | GET     | Read endpoints, static pages |
| `post!`    | POST    | Create resources |
| `put!`     | PUT     | Full replacement updates |
| `patch!`   | PATCH   | Partial updates (RFC 5789) |
| `delete!`  | DELETE  | Destroy |
| `head!`    | HEAD    | Headers-only probes (HEAD falls back to the GET registry per RFC 9110 § 9.3.2 when not explicitly registered) |
| `query!`   | QUERY   | Send a read query in the request body |
| `options!` | OPTIONS | Capability discovery, `Accept-Patch`. CORS preflight is answered by `CorsMiddleware` before the router, so you usually don't need this one |

```rust
use suprnova::{routes, get, post, patch, delete};

routes! {
    get!("/articles", controllers::articles::index),
    post!("/articles", controllers::articles::store),
    patch!("/articles/{id}", controllers::articles::update),
    delete!("/articles/{id}", controllers::articles::destroy),
}
```

Every verb macro checks at compile time that the path starts with `/` -
a missing leading slash fails the build, not a request.

### Multi-method and `any!`

You register `QUERY` with `query!(path, handler)` or `Router::query`.
You use `Router::try_query` when route registration can fail.
You also use `query` inside fluent groups and `query!` inside `group!`.
You read its body with the same request accessors you use for other methods.

You use `any!` to register one handler for GET, POST, PUT, PATCH, DELETE,
HEAD, OPTIONS and QUERY. You use it for endpoints that accept every supported method.

```rust
use suprnova::{routes, any};

routes! {
    any!("/webhooks/inbound", controllers::webhooks::inbound)
        .name("webhooks.inbound")
        .middleware(SignatureCheck),
}
```

When you only want a subset of verbs sharing one handler, reach for the
builder API and `Router::methods`:

```rust
use suprnova::Router;
use hyper::Method;

let router = Router::new()
    .methods(&[Method::PUT, Method::PATCH], "/posts/{id}", update_post)
    .name("posts.update")
    .middleware(AuthMiddleware);
```

`.name(...)` and `.middleware(...)` fan across every verb the route was
registered against, so reverse-lookup yields the same URL whichever
method the caller looks up.

### WebSocket routes

`ws!` registers a long-lived upgrade handler. The macro is part of the
same `routes!` body - covered in detail by [WebSockets](websockets.md).

## Route parameters

Dynamic segments use curly braces (`{id}`). For familiarity Suprnova also
accepts Express/Rails-style colons (`:id`) and normalises them to braces
before handing the pattern to `matchit`.

```rust
routes! {
    get!("/users/{id}", controllers::users::show),       // matchit-native
    get!("/users/:id", controllers::users::show),        // Express/Rails - same thing
    get!("/posts/{post_id}/comments/{comment_id}", controllers::comments::show),
}
```

The colon is only treated as a parameter opener at the start of a path
segment, so literal colons mid-segment survive untouched
(`/files/note:draft` stays a literal route, not `/files/{draft}`).

Read parameters off the request inside a handler:

```rust
use suprnova::{Request, Response, HttpResponse};

pub async fn show(req: Request) -> Response {
    let user_id = req.param("id").unwrap_or("0");
    Ok(HttpResponse::text(format!("User ID: {}", user_id)))
}
```

For typed extraction without the `unwrap_or` dance, see route model
binding below or `#[handler]` in [Controllers](controllers.md).

### Naming the parameter an argument reads

A `#[handler]` argument reads the route parameter named after it, so
`id: i64` reads `{id}` and `post: Post` binds from `{post}`. A raw
identifier drops its `r#`: `r#type: String` reads `{type}`, a name Rust
reserves as a keyword. To read a parameter under another name, put
`#[route_param("name")]` on the argument, as Laravel's
`#[RouteParameter('name')]` does:

```rust
use suprnova::{handler, text, Response};

// GET /posts/{post}
#[handler]
pub async fn show(#[route_param("post")] id: i64) -> Response {
    text(format!("post {id}"))
}

// GET /items/{type}
#[handler]
pub async fn by_type(r#type: String) -> Response {
    text(r#type)
}
```

`#[route_param]` works on a path value, an optional one and a bound
model alike. The [startup checks](#startup-checks) read the renamed
parameter, so `show` on `/posts/{id}` is refused before the first
request. `#[authorize]` still names the argument by its own name:
`#[authorize("view", id)]` above.

### Optional parameters

End a parameter name with `?` to make the segment optional. `/posts/{id?}`
matches `/posts` and `/posts/42`:

```rust
routes! {
    get!("/posts/{id?}", controllers::posts::show),
    get!("/archive/{year?}/{month?}", controllers::posts::archive),
}
```

On the short form the request has no `id`, and `req.param("id")` returns
`Err(ParamError)`. Read it with `req.param("id").ok()` when you want an
`Option`. The colon spelling takes the `?` too: `/posts/:id?`.

- **Optional parameters fill from the left.** In
  `/archive/{year?}/{month?}` the router matches `/archive`,
  `/archive/2026` and `/archive/2026/05`. It never matches a month
  without a year.
- **Only optional parameters may follow an optional one.**
  `/posts/{id?}/comments` is refused when you register it, because the
  router could not tell a request that leaves `id` out from one that fills
  it. So is an optional parameter that is only part of a segment
  (`/a/pre-{x?}`), and a pattern with an optional parameter and an empty
  segment, such as a trailing slash.
- **Middleware, name and constraints apply to every form.** The route's
  middleware runs on `/posts` as it does on `/posts/42`.
- **A second route for one form of an optional route is refused.**
  `/posts/{id?}` and a separate `/posts` route, or a separate
  `/posts/{id}` route, collide when you register them.
- **A WebSocket route takes optional parameters as well.**
- **`route(...)` leaves an optional segment out when it has no value.**
  `route("archive", &[])` returns `/archive`. A value for a later parameter
  with none for an earlier one is a missing parameter: `try_route` returns
  `RouteUrlError::MissingParams`.

### Parameter constraints

A constraint holds a parameter to the values it may take. The router checks
it after the path has matched. A value the constraint refuses is a `404`, as
if the route had not matched, and neither the route's middleware nor its
handler runs. Chain a constraint onto a route:

```rust
use suprnova::{get, routes};

routes! {
    get!("/posts/{id}", controllers::posts::show).where_number("id"),
    get!("/reports/{year}", controllers::reports::show)
        .where_pattern("year", "[0-9]{4}"),
    get!("/posts/{id}/{status}", controllers::posts::by_status)
        .where_uuid("id")
        .where_in("status", ["draft", "published"]),
}
```

The same methods are on the `Router` builder, where they apply to the route
you just registered:

```rust
use suprnova::Router;

let router = Router::new()
    .get("/posts/{id}", show).where_number("id")
    .get("/archive/{year?}/{month?}", archive)
    .where_pattern("year", "[0-9]{4}")
    .where_in("month", ["01", "02", "03"]);
```

| Method | The parameter must be |
|---|---|
| `where_number(param)` | One or more ASCII digits. |
| `where_alpha(param)` | One or more ASCII letters. |
| `where_alpha_numeric(param)` | One or more ASCII letters and digits. |
| `where_uuid(param)` | A UUID in its hyphenated form, in either case. |
| `where_ulid(param)` | A ULID: 26 characters of Crockford base 32. |
| `where_in(param, values)` | One of `values`, compared exactly. |
| `where_pattern(param, expression)` | A value that the regular expression matches from its first character to its last. |

There is no `where!` macro. The constraints are methods on the route.

- **A pattern has to match the whole value.** `where_pattern("id", "[0-9]+")`
  refuses `12a`, as it does in Laravel.
- **`\d` and `\w` match every script.** They match the digits and letters
  of all scripts, where Laravel's match ASCII alone. Write `[0-9]` for the
  ASCII digits, or use `where_number`.
- **A constraint skips a parameter the request left out.** An optional
  parameter is checked only when it is there.
- **A constraint holds for the method you set it on.** A constraint on a
  `GET` route does not apply to a `POST` route with the same pattern. An
  `any!` route and a route with several methods hold every method they
  cover.
- **A group's constraint may name a parameter of the group's prefix.** In
  `group!("/teams/{team}", { get!("/members", h).where_number("team") })`,
  `team` is a parameter of the prefix.
- **A constraint on a parameter the route does not have stops the boot.**
  It would never be checked, and the route would look guarded while it is
  not. `where_pattern` also panics on an expression that is not a regular
  expression.

Every route builder also has `.constrain(param, ParamConstraint)`, which the
`where_*` methods call. A `Router` route has `.try_constrain(param,
constraint)`, which returns `Result<_, FrameworkError>` where `constrain`
panics. `ParamConstraint::pattern(expression)` returns a `Result` for an
expression that is not a regular expression, and `ParamConstraint::one_of`
builds the list form.

## Route model binding

A handler argument binds from the route parameter its name names whenever
its type implements `RouteBinding`. Every `#[suprnova::model]` struct does,
so naming the model is enough:

```rust
use suprnova::{handler, json_response, Response};
use crate::models::Post;

// Route: GET /posts/{post}
#[handler]
pub async fn show(post: Post) -> Response {
    json_response!({ "title": post.title })
}
```

`#[handler]` reads `{post}`, and the router looks the row up through
`Post::query()` before the handler runs. Global scopes, the soft-delete
filter, and the model's `#[model(connection = "...")]` apply, as they do
to every query of the model. The value is parsed as the key's type, and a
`unique_id` key's value must also be a well-formed identifier. A value
that does not parse and a value that matches no row both answer a 404
whose body names the model, `{"message": "Post not found"}`, without the
value.

The argument's name must match the placeholder (`/posts/{post}`, not
`/posts/{id}`). Primitives (`id: i64`, `slug: String`) stay path values
read through `FromParam`, and any other type stays a form request. Mix
them freely; one argument at most reads the request body:

```rust
// Route: PUT /posts/{post}/comments/{comment}
#[handler]
pub async fn update(form: UpdateComment, post: Post, comment: Comment) -> Response {
    // post and comment are bound; form is validated.
    json_response!({ "post_id": post.id, "comment_id": comment.id })
}
```

The router binds every bound argument, in path order, after the route's
middleware and before the handler. A missing row is a 404 before the form
is read, even with the form declared first. An `Option<Post>` argument
binds `None` when its optional parameter, `{post?}`, is absent.

### Binding by another column

A `{name:column}` segment registers the parameter `name` and binds it by
`column`. `req.param("post")`, `where_alpha("post")` and `route()` all use
the name:

```rust
routes! {
    get!("/posts/{post:slug}", controllers::posts::show).name("posts.show"),
}
```

`{post:slug?}` is the optional form. To bind a model by another column on
every route, set its route key:

```rust
#[model(table = "posts", route_key = "slug")]
pub struct Post {
    pub id: i64,
    pub slug: String,
    pub title: String,
}
```

The build fails when `route_key` names no column of the model.

### Scoped bindings

When two bound parameters follow each other, the first is the parent of
the second. A child whose segment names a column is looked up through the
parent's relation named by the child in the plural, as `Str::plural` forms
it, so a row the parent does not own answers 404:

```rust
#[model(table = "users", relations = { posts: HasMany<Post> })]
pub struct User {
    pub id: i64,
    pub name: String,
}

// GET /users/{user}/posts/{post:slug}: only the user's own posts bind.
#[handler]
pub async fn show(user: User, post: Post) -> Response {
    json_response!({ "author": user.name, "title": post.title })
}
```

`scope_bindings()` on a route or a group scopes children without a field
too, and `without_scoped_bindings()` turns scoping off. A child bound by
`bind()` is never scoped. Every relation kind with one child type works,
`BelongsToMany` and `HasManyThrough` included; a `MorphTo` cannot scope a
child.

### Custom resolution

A model can replace its binding. `#[model(custom_route_binding)]` leaves
`RouteBinding` to you, and the default lookup stays callable:

```rust
#[model(table = "tags", custom_route_binding)]
pub struct Tag {
    pub id: i64,
    pub name: String,
}

#[suprnova::async_trait]
impl suprnova::RouteBinding for Tag {
    fn route_key_name() -> &'static str {
        "name"
    }
    fn route_key(&self) -> String {
        self.name.clone()
    }
    async fn resolve_route_binding(
        value: &str,
        _field: Option<&str>,
    ) -> Result<Option<Self>, suprnova::FrameworkError> {
        suprnova::database::resolve_model_route_binding::<Self>(
            &value.to_lowercase(),
            Some("name"),
            false,
        )
        .await
    }
}
```

Any other type that implements `RouteBinding` binds the same way. To pass
it to `route()`, implement `RouteValue` with `suprnova::bound_route_value`.
A type that is a scoped parent finds its children in
`resolve_child_route_binding` and says so from `route_binding_info()`
with `.with_children(ChildBindings::Custom)`; without that, a route that
scopes a child under it is refused at startup.

The router binds a parameter name on every route, those registered before
the call and those after. `bind` takes the raw value and the matched route
and wins over the type's own binding; `model` binds by the route key and
calls its fallback when no row matches. A `-` in the name reads as `_`:

```rust
let router = Router::new()
    .bind("user", |value: String, _route| async move {
        User::query().filter("name", value).first().await
    })
    .model::<Team, _, _>("team", |_value| async { Ok(Team::default()) })
    .get("/users/{user}/teams/{team}", controllers::teams::show);
```

### Soft-deleted rows

A soft-deleted row binds only on a route that calls `with_trashed()`.
There, every binding goes through the soft-deletable lookups, scoped
children and the bare SeaORM form included:

```rust
let router = Router::new()
    .get("/admin/posts/{post}", controllers::admin::posts::show)
    .with_trashed();
```

### Missing rows

`missing(handler)` on a route, a group or a resource answers instead of
the 404 when a binding finds no row, finds no row its parent owns, or gets
a value that does not parse. The handler receives the request:

```rust
let router = Router::new()
    .get("/posts/{post}", controllers::posts::show)
    .missing(|_req| async { suprnova::redirect_to("/posts").into() });
```

A `#[handler]` function works as the `missing()` handler too, and its
bound arguments bind under the route's settings, as the route's handler's
do. On `/users/{user}/posts/{post}` it can take `user: User` and gets the
user the route bound. A scoped child it takes without its parent is still
looked up through the parent the route's handler binds (see
[Startup checks](#startup-checks)), so it never gets a row the route
refused. A bound argument of its own that finds nothing, such as the post
that missed, answers 404 instead of calling it again.

A `#[handler]` function that the route's handler or a middleware calls
with the request, and that returns another type than `Response`, cannot
return the `missing()` response. It fails with the 404 error instead. When
its caller, the route's handler or that middleware, returns a 404, the
handler's own or one the caller built in its place, the route answers with
the `missing()` response at that point, and every middleware outside the
caller sees it on its way out, as it sees the route's own `missing()`
response. A caller that returns anything else has recovered, and its
response stands.

### Enums

A unit-only enum derives `RouteBinding`. Each variant binds from its
`#[route(value = "...")]`, or else from its name in snake case, matched
exactly. Any other value answers 404, and never reaches `missing()`:

```rust
#[derive(suprnova::RouteBinding)]
pub enum Category {
    Fruits,                // /categories/fruits
    PantryStaples,         // /categories/pantry_staples
    #[route(value = "veg")]
    Vegetables,            // /categories/veg
}

#[handler]
pub async fn show(category: Category) -> Response {
    suprnova::http::text(suprnova::RouteBinding::route_key(&category))
}
```

### Startup checks

`#[handler]` records every argument of a handler: the parameter it reads,
its type, and whether it binds, reads a path value, or reads the body.
Before the first request, the router checks every route against its
record and refuses to start, naming the route and the parameter, when:

- An argument reads a parameter the path does not declare, such as
  `/users/{user}` with `id: i64`.
- A binding field names no column of the model, or a column whose type
  cannot be parsed from a path segment.
- A scoped child needs a relation the parent does not declare, one of
  another type, or a `MorphTo`.
- A binder returns another type than the argument it binds, or covers a
  parameter the handler reads without binding.
- A handler reads the request body twice.

The fallback and every `missing()` handler are checked too, each against
the path of the route it answers. `Server::from_config` returns the
refusal as an error. A router driven through `handle_request` in a test
runs the same checks before its first request and answers every request
with a 500 when they fail, a request the fallback would answer included;
`router.prepare_bindings()` returns the error itself. A closure handler
and a generic `#[handler]` function carry no record and are not checked
at startup. A closure binds nothing itself. A generic handler, a
`missing()` handler, and a `#[handler]` function that a closure route,
middleware or another handler calls with the request, bind their
arguments of a concrete type that implements `RouteBinding` as any
handler's do: in path order, by the route's binding fields, scoped,
through the router's binders, with `with_trashed()` and `missing()`. The
route plans them at the handler's first request and keeps the plan. A
binding field, a scoped child, or a binder that covers a parameter the
handler reads without binding, which the checks above would refuse,
answers that request with a 500 instead of binding. A generic handler's
generic arguments read the body.

When such a handler takes a scoped child without its parent, the child
is still found through the parent, bound the way the route's own handler
binds it:

- When the route's handler is a recorded `#[handler]` or a generic one
  that binds the parent, the child is looked up through that parent, so
  a row the parent does not own answers 404.
- When the route's handler binds no parent (a closure, a function that is
  not a `#[handler]`, or a handler that takes the child alone), nothing
  scopes the child, as for any handler whose parent is not bound.
- When the router cannot see how the route's handler binds the parent (a
  generic `#[handler]` it cannot find by its path, such as one declared
  inside a function, one that binds the parent as `RouteParam<T>` with
  `T` its type parameter, or a function pointer), the request answers a
  500 that names the route, the handler, the child and the parent, and
  says to take the parent too. It never looks the child up unscoped.

A handler inside an `impl` block names its type,
`#[handler(Self = Posts)]`, and is checked as a free handler is; see
[Handlers inside an `impl` block](controllers.md#handlers-inside-an-impl-block).

### Older binding forms

Two older forms keep working. `RouteParam<Post>` binds as `Post` does. A
SeaORM row whose entity implements `EntityExt` binds by its primary key
through `EntityExt::find_by_pk`, with no global scope and on the default
connection; its 404 names the entity's module:

```rust
impl suprnova::database::EntityExt for post::Entity {}

#[handler]
pub async fn show(post: post::Model) -> Response {
    json_response!({ "title": post.title })
}
```

Bind the `#[model]` struct in new code: its lookup applies the model's
scopes and connection.

### Binding is identity, not authorization

Route model binding answers "does this row exist?" - it does **not**
answer "is the current user allowed to see this row?". A bare bound
handler lets any authenticated user view any post by guessing
`/posts/N`. Authorize against the bound model with
`#[authorize("view", post)]` or `Gate::authorize` - see
[Authorization](authorization.md).

### Opting out

Take the key as a path value and query yourself:

```rust
use suprnova::{handler, json_response, FrameworkError, Model, Response};
use crate::models::User;

#[handler]
pub async fn show(id: i64) -> Response {
    let user = User::find(id)
        .await?
        .ok_or(FrameworkError::model_not_found("User"))?;
    json_response!({ "id": user.id, "name": user.name })
}
```

### Why Suprnova diverges

- **A value is parsed before the query.** Laravel passes the raw value to
  the query, so MySQL reads `7abc` as `7` and binds row 7, and Postgres
  raises an error. Here a value that does not parse as the column's type,
  or breaks a `unique_id` key's format, answers the same 404 a missing row
  does.
- **The 404 never repeats the value.** Laravel's message carries the
  requested value; Suprnova's names the model alone.
- **An enum binds by name.** Rust enums carry no backing value, so a
  variant without `#[route(value = "...")]` binds from its name in snake
  case.
- **A renamed argument names its parameter with an attribute.** Laravel's
  `#[RouteParameter('name')]` reads the parameter's value into an
  argument; `#[route_param("name")]` does the same and also binds a model
  from it, and the startup checks read the name it gives.
- **Mistakes stop the server at startup.** Laravel finds a missing
  relationship at request time, as a 500, and injects an empty model for
  an argument the route does not declare. Suprnova refuses those routes,
  and the other mistakes the startup checks list, before the first
  request.

## Named routes

Names give you stable identifiers for URL generation. Attach one with
`.name(...)`:

```rust
routes! {
    get!("/", controllers::home::index).name("home"),
    get!("/users", controllers::users::index).name("users.index"),
    get!("/users/{id}", controllers::users::show).name("users.show"),
    post!("/users", controllers::users::store).name("users.store"),
}
```

Names follow the Laravel convention `<resource>.<action>` -
`users.show`, `posts.destroy`, `admin.dashboard`. Look them up with the
top-level `route(name, &[...])` helper:

```rust
use suprnova::route;

let home = route("home", &[]);
//   Some("/")

let profile = route("users.show", &[("id", "123")]);
//   Some("/users/123")

// A bound value fills its parameter with its route key, or with the
// column a `{post:slug}` parameter names.
let post_url = route("posts.show", &post);
//   Some("/posts/hello-world")
```

`route` returns `Option<String>` and percent-encodes parameter values
into path-safe form (so `("slug", "a/b")` becomes `/posts/a%2Fb` -
matchit-safe and round-trips through `req.param("slug")`). A catch-all
segment such as `/files/{*rest}` takes its value under the name the
handler reads it by, `rest`, and keeps its slashes:
`route("files.show", &[("rest", "docs/a b.txt")])` returns
`/files/docs/a%20b.txt`. For redirect
targets and email links use the strict sibling `suprnova::routing::try_route`,
which returns `Result<String, RouteUrlError>` and refuses to emit a URL
containing an unfilled `{placeholder}` segment. See
[URL Generation](urls.md) for the full URL surface (signed URLs,
absolute URLs, `Redirect::route`).

Route names are globally unique and process-global. Registering the same
name to two different paths panics at boot - silent shadowing was a
security-shaped bug because redirects would route to whichever
registration happened to win. Use `RouteBuilder::try_name` (or
`suprnova::routing::try_register_route_name`) for the fallible variant.

`route_has(&[...])` tells you whether names are registered, as Laravel's
`Route::has` does. It is true only when every name in the list is:

```rust
use suprnova::route_has;

if route_has(&["login", "register"]) {
    // link to both pages
}
```

One unregistered name makes it false. An empty list is true.

## Per-route middleware

Chain `.middleware(M)` on any route builder:

```rust
use suprnova::{routes, get, post};
use crate::middleware::{AuthMiddleware, AdminMiddleware};

routes! {
    // Public
    get!("/", controllers::home::index).name("home"),

    // Protected
    get!("/dashboard", controllers::dashboard::index)
        .name("dashboard")
        .middleware(AuthMiddleware),

    // Multiple middleware compose left-to-right (outermost first)
    get!("/admin", controllers::admin::index)
        .middleware(AuthMiddleware)
        .middleware(AdminMiddleware),
}
```

`.middleware_named("auth")` adds the middleware that a registered alias
stands for. `.middleware_named("throttle:60,1")` gives the alias its
arguments, and a name can stand for a group of middleware. See
[Middleware](middleware.md#named-aliases-and-groups).

Route-local middleware runs after any global middleware
(`Server::with_middleware`) and any group middleware that wraps the
route. The middleware map is keyed by `(method, path)`, so attaching
auth to `POST /api/posts` never bleeds onto a public `GET /api/posts`
on the same path. For the middleware contract and writing your own, see
[Middleware](middleware.md).

A route leaves out a middleware its group gives it with
`.without_middleware::<M>()` or `.without_middleware_named("auth")`, as
Laravel's `withoutMiddleware` does. The global middleware stays. See
[Leaving middleware out](middleware.md#leaving-middleware-out).

## Route groups

`group!` factors out a shared path prefix and/or shared middleware:

```rust
use suprnova::{routes, get, post, group};
use crate::middleware::{AuthMiddleware, ApiMiddleware};

routes! {
    get!("/", controllers::home::index).name("home"),

    // Shared /api prefix + middleware
    group!("/api", {
        get!("/users", controllers::api::users::index).name("api.users.index"),
        post!("/users", controllers::api::users::store).name("api.users.store"),
        get!("/users/{id}", controllers::api::users::show).name("api.users.show"),
    }).middleware(ApiMiddleware),

    // Admin area
    group!("/admin", {
        get!("/dashboard", controllers::admin::dashboard).name("admin.dashboard"),
        get!("/settings", controllers::admin::settings).name("admin.settings"),
    }).middleware(AuthMiddleware),
}
```

A group prefix is concatenated with each route path. A route at `/`
inside a group resolves to the group prefix exactly
(`group!("/users", { get!("/", index) })` → `GET /users`).

### Group name prefix

`.name(prefix)` puts a prefix in front of the name of every route in the
group. Mirrors Laravel's `Route::name('admin.')->group(...)`. Each route
then names itself by the part the group leaves out:

```rust
routes! {
    group!("/admin/users", {
        get!("/", controllers::admin::users::index).name("index"),   // admin.users.index
        get!("/{id}", controllers::admin::users::show).name("show"), // admin.users.show
        get!("/export", controllers::admin::users::export),          // no name
    }).name("admin.users."),
}
```

The route is known by its full name, `route("admin.users.index", &[])`, and
not by `index`. Three rules:

- **The prefix is used as you write it.** End it with the separator your
  names use, here the dot.
- **A group inside adds its own prefix after this one.** With
  `.name("admin.")` outside and `.name("users.")` inside, a route named
  `index` is `admin.users.index`. A group with no prefix of its own passes
  the outer one on.
- **A route without a name stays without one.** The prefix names nothing by
  itself.

The name prefix is on `group!`. The `Router::group(...)` builder has no
name prefix.

### Group controller

A group can name the module its handlers live in. Write `controller =` after
the path prefix, and a route names its handler by function alone:

```rust
routes! {
    group!("/admin/users", controller = controllers::admin::users, {
        get!("/", index).name("index"),
        post!("/", store).name("store"),
        get!("/{id}", show).name("show"),
    }).name("admin.users."),
}
```

This is the same as writing `controllers::admin::users::index` in each
route. The path prefix stays the first argument of the macro. Two rules:

- **The controller applies to a handler written as one bare name.** A
  handler written as a path, `get!("/health", controllers::health::check)`,
  is used as written. That lets a route reach a handler in another module.
- **A group inside names its own controller.** A nested `group!` is added as
  written, so it takes its own `controller =`, or none.

`.name(...)` and `.middleware(...)` chain onto the group in the same way
with or without `controller =`.

### Nested groups

Groups nest to any depth. Prefixes concatenate; middleware inherits from
parent to child:

```rust
routes! {
    group!("/api", {
        get!("/health", controllers::api::health),

        group!("/v1", {
            get!("/users", controllers::api::v1::users),

            group!("/admin", {
                get!("/stats", controllers::admin::stats),
            }).middleware(AdminMiddleware),
        }),
    }).middleware(AuthMiddleware),
}
```

| Route | Effective path | Middleware chain |
|---|---|---|
| `/api/health` | `/api/health` | `AuthMiddleware` |
| `/api/v1/users` | `/api/v1/users` | `AuthMiddleware` |
| `/api/v1/admin/stats` | `/api/v1/admin/stats` | `AuthMiddleware` → `AdminMiddleware` |

For a single route inside a nested group, the execution order is
**outermost middleware first**: parent group → child group → route-local.
Per-route `.middleware(...)` runs innermost.

## Fallback route

`fallback!` registers a handler that runs when no other route matches.
Use it for custom 404 pages.

```rust
use suprnova::{routes, get, fallback};

routes! {
    get!("/", controllers::home::index),

    fallback!(controllers::errors::not_found),
}
```

```rust
// src/controllers/errors.rs
use suprnova::{Request, Response, HttpResponse};

pub async fn not_found(req: Request) -> Response {
    Ok(HttpResponse::text(format!("Page not found: {}", req.path()))
        .status(404))
}
```

Fallback supports its own middleware chain (`fallback!(handler).middleware(M)`).
If no fallback is registered, the framework returns a plain-text
`404 Not Found`.

### When only the method is wrong

A path that a route of another method matches is not a 404. As Laravel
does, the router checks the other methods (`GET`, `HEAD`, `POST`, `PUT`,
`PATCH`, `DELETE`, `OPTIONS`, `QUERY`) and answers with the ones that
match:

```rust
routes! {
    get!("/posts/{id}", controllers::posts::show),
}
```

| Request | Answer |
|---|---|
| `DELETE /posts/1` | `405`, `Allow: GET, HEAD`, and the error body `{"message": "The DELETE method is not supported for route posts/1. Supported methods: GET, HEAD.", "request_id": "..."}` |
| `OPTIONS /posts/1` | `200` with an empty body and `Allow: GET,HEAD` |
| `DELETE /nothing/here` | the fallback, or the `404` |

`Allow` lists the methods in the order above. `HEAD` stands beside `GET`
because a `GET` route answers `HEAD`. A route whose
[constraints](#parameter-constraints) refuse the path is not counted, so
`DELETE /posts/abc` is still a `404` when `{id}` must be a number. The
fallback only answers a path that no route of any method matches.

Both answers run through the global middleware, as the `404` does. The
CORS middleware therefore still answers a preflight `OPTIONS` request
before the router's `200` is reached.

## Resource routing

For a standard 7-action REST surface, implement `ResourceController` and
register the resource through the `Router` builder, or name a module of
`#[handler]` functions with `resource!` (see [Actions that bind](#actions-that-bind)).
Laravel parity for `Route::resource()` and `Route::apiResource()`.

```rust
use suprnova::{Router, ResourceController, ResourceAction, Request, Response, HttpResponse};
use std::pin::Pin;
use std::future::Future;

struct PostsCtl;

impl ResourceController for PostsCtl {
    fn index(&self, _req: Request) -> Pin<Box<dyn Future<Output = Response> + Send>> {
        Box::pin(async { Ok(HttpResponse::text("list")) })
    }
    fn show(&self, _req: Request) -> Pin<Box<dyn Future<Output = Response> + Send>> {
        Box::pin(async { Ok(HttpResponse::text("one")) })
    }
    // store / update / destroy / create / edit default to 404.
}

let router: Router = Router::new()
    .resource("posts", PostsCtl)
    .into();
```

Methods you don't override return 404. Use `api_resource` to drop
`create` and `edit` - the two routes that exist only to render forms.

### Default routes and names

| Verb | Path | Trait method | Name |
|---|---|---|---|
| GET    | `/posts`             | `index`   | `posts.index`   |
| GET    | `/posts/create`      | `create`  | `posts.create`  |
| POST   | `/posts`             | `store`   | `posts.store`   |
| GET    | `/posts/{post}`      | `show`    | `posts.show`    |
| GET    | `/posts/{post}/edit` | `edit`    | `posts.edit`    |
| PUT    | `/posts/{post}`      | `update`  | `posts.update`  |
| DELETE | `/posts/{post}`      | `destroy` | `posts.destroy` |

The path parameter defaults to the singular of the resource name -
`posts` → `{post}`, `categories` → `{category}`. Irregular plurals get
the literal last segment; override with `.parameter(...)`.

### Restricting and renaming

```rust
use suprnova::{Router, ResourceAction};

Router::new()
    .resource("posts", PostsCtl)
    .only(&[ResourceAction::Index, ResourceAction::Show])      // pin to two verbs
    .names([("index", "posts.list")])                          // rename a default
    .parameter("post_id")                                      // {post} → {post_id}
    .into();
```

Rust-side aliases that read better in some call sites: `.keep(...)` for
`.only(...)`, `.drop(...)` for `.except(...)`, `.rename(...)` for
`.names(...)`.

### Actions that bind

A `ResourceController` action takes the request. For actions that take
bound arguments, name a module of `#[handler]` functions with `resource!`
instead; each action is the function of its name:

```rust
use suprnova::{routes, resource, api_resource};

// controllers::posts::{index, create, store, show, edit, update, destroy}
routes! {
    resource!("posts", controllers::posts),
    resource!("photos", controllers::photos, only = [index, show]),
    api_resource!("tags", controllers::tags, except = [destroy]),
}
```

```rust
// src/controllers/posts.rs
#[handler]
pub async fn show(post: Post) -> Response {
    json_response!({ "title": post.title })
}
```

`only = [...]` and `except = [...]` go inside the macro: an action the
selection keeps whose function the module does not define fails to
compile, and an action it leaves out needs no function. The builder takes
`.names(...)`, `.parameter(...)`, `.parameters(...)`, `.unnamed()` and
`.authorize_resource::<U, R>()` as the controller form does.

### Nested resources

A dotted name nests one resource in another. `users.posts` registers
`/users/{user}/posts` and `/users/{user}/posts/{post}`, named
`users.posts.index` through `users.posts.destroy`:

```rust
routes! {
    resource!("users.posts", controllers::user_posts)
        .parameters([("users", "author")])   // /users/{author}/posts/{post}
        .scoped([("post", "slug")])          // /users/{author}/posts/{post:slug}
        .with_trashed(&[])                   // show, edit and update bind trashed rows
        .missing(|_req| async { suprnova::redirect_to("/posts").into() }),
}
```

`parameters` renames a segment's parameter. `scoped` gives parameters a
binding field and scopes every nested parameter to its parent; an empty
list scopes without fields. `with_trashed` binds soft-deleted rows on the
actions it names, `show`, `edit` and `update` when it names none.
`missing` answers for every route of the resource when a binding finds
nothing. The controller form takes the same four.

### Controller middleware

A controller declares the middleware its actions run: a `ResourceController`
in its `middleware` method, and a module named by `resource!` in a
`pub fn middleware()`. See
[Controller middleware](controllers.md#controller-middleware).

`.middleware(ControllerMiddleware)` on the registration scopes one more the
same way, with `only` and `except`. It is Laravel's `middlewareFor`:

```rust
use suprnova::routing::{ControllerMiddleware, ResourceAction};

Router::new()
    .resource("posts", PostsCtl)
    .middleware(ControllerMiddleware::named("auth").except(&[ResourceAction::Index]))
    .middleware(ControllerMiddleware::new(AuditMiddleware).only(&[ResourceAction::Destroy]))
    .into();
```

`resource!` takes the same `.middleware(...)`. On every route of the
resource the middleware runs in this order:

1. the middleware of the group around the resource;
2. the middleware given with `.middleware(...)` here;
3. the middleware the controller declares;
4. the check of `authorize_resource`, which needs the user the middleware
   before it authenticated.

A name that no alias or group carries fails the registration:
`try_register` returns the error, and `register` panics at boot.

### Resources inside a group

`resource!` is an item of `group!`, as Laravel's `Route::resource` is
inside `Route::group`. The resource takes the group's prefix, name prefix,
middleware, session block and binding settings:

```rust
routes! {
    group!("/admin", {
        resource!("posts", controllers::admin::posts),
    })
    .middleware_named("auth")
    .name("admin."),
}
```

This registers `/admin/posts` through `/admin/posts/{post}/edit`, named
`admin.posts.index` through `admin.posts.destroy`, each running `auth`
before the controller's own middleware. The `Router::group(...)` builder
and the controller form, `Router::resource`, register no resources inside
a group.

### Bulk registration

```rust
Router::new()
    .resources([
        ("posts",    Box::new(PostsCtl)    as Box<dyn ResourceController>),
        ("comments", Box::new(CommentsCtl) as Box<dyn ResourceController>),
    ])
    .api_resources([("authors", Box::new(AuthorsCtl) as Box<dyn ResourceController>)]);
```

### Authorizing the whole resource

`authorize_resource::<U, R>()` attaches the conventional ability check to
every generated route as per-route middleware - Laravel's
`authorizeResource` parity. Without it, a resource surface is ungated
unless every controller body remembers to call `Gate::authorize`; a single
forgotten `destroy` ships an ungated delete.

```rust
use suprnova::{Router, Gate};

// Abilities are keyed on (ability, user type, resource marker type).
Gate::define::<User, Post>("view",   |u, _p| u.is_member);
Gate::define::<User, Post>("create", |u, _p| u.is_author);
Gate::define::<User, Post>("update", |u, _p| u.is_author);
Gate::define::<User, Post>("delete", |u, _p| u.is_admin);

let router: Router = Router::new()
    .resource("posts", PostsCtl)
    .authorize_resource::<User, Post>()
    .into();
```

The action → ability mapping mirrors Laravel:

| Action(s) | Ability |
|---|---|
| `index`, `show`     | `view`   |
| `create`, `store`   | `create` |
| `edit`, `update`    | `update` |
| `destroy`           | `delete` |

`PATCH` shares the `update` action, so it is gated identically to `PUT`. A
denied ability short-circuits with `403` before the handler runs, and an
unauthenticated request fails closed. The resource marker `R` only needs
`Default` - the gate discriminates on its *type*, the way Laravel
discriminates on the model class. See the [authorization chapter](authorization.md)
for defining the abilities themselves.

## Router-level redirects and views

Three sugar methods on `Router` cover route declarations that don't need
a handler function:

```rust
use suprnova::Router;
use serde_json::json;

let router = Router::new()
    // Static redirect: GET /old-pricing → 302 /pricing
    .redirect("/old-pricing", "/pricing", 302)
    // 301 sibling
    .permanent_redirect("/legacy", "/new")
    // Inertia static page: GET /about renders the About component
    .inertia("/about", "About", json!({ "team_size": 4 }))
    .name("about");
```

`Router::inertia` is Suprnova's `Route::inertia($uri, $component,
$props)`. It registers `GET`; a `HEAD` request falls through to it and
has its body stripped at the server boundary, so there's nothing extra
to register. It returns a `RouteBuilder`, so `.name(...)` and
`.middleware(...)` chain off it like any other route.

Props must be a JSON object, or `null` for none. Anything else -
an array, a string - is a registration error, not a silently empty prop
bag. `try_inertia` is the fallible form.

`Router::view` is the same method under its older name; it returns
`Router` rather than `RouteBuilder`, so a route declared with it can't
be named. Prefer `inertia`.

### Why Suprnova diverges

Laravel's `Route::view` renders a Blade template; Suprnova renders an
Inertia component, because the framework's templating system is Inertia,
not Blade. One consequence: the component name is a runtime string here,
so it doesn't get the compile-time page-component check that the
`inertia_response!` macro performs. Write the handler out with
`inertia_response!` when you want a typo in a component name to fail the
build rather than the request.

For redirect *responses* (not route declarations) - `Redirect::route`,
`Redirect::back`, `Redirect::intended`, signed redirects - see
[URL Generation](urls.md) and [Responses](responses.md).

## Signed URLs

HMAC-signed routes are routing-adjacent (you mint a URL against a named
route, then verify the signature on the inbound request). They're
covered in full by [URL Generation](urls.md); the short version:

```rust
use suprnova::url;

let reset = url::signed_route("password.reset", &[("user", "42")])?;
// /password/reset/42?signature=...

let expires_at = chrono::Utc::now().timestamp() + 3600;
let verify = url::temporary_signed_route("verify.email", &[("user", "42")], expires_at)?;
// /verify/email/42?expires=1748803600&signature=...
```

Verify inside a handler with `url::has_valid_signature(&request)` (boolean)
or `url::signature_verdict(&request)` (the three-way
`Valid`/`Expired`/`Invalid` split, so you can render a "request a fresh
link" page instead of a generic 403).

## Fallible registration

Route registration runs once at boot, so a duplicate or malformed route
is treated as a programmer error: the plain helpers (`Router::get`,
`post`, `put`, `delete`, `ws`, `RouteBuilder::name`, the
`GroupBuilder` → `Router` `From` conversion) **panic** to fail loudly at
startup. That's the right default for routes declared in source.

When patterns or names come from a fallible source - dynamic config, a
plugin system, a test that deliberately registers conflicting routes -
use the `try_*` siblings. They return `Result<_, FrameworkError>`
(naming the offending method, path, or conflicting name) instead of
panicking:

| Panicking | Fallible sibling | Returns |
|---|---|---|
| `Router::get` / `post` / `put` / `patch` / `delete` / `head` / `options` | `try_get` / `try_post` / `try_put` / `try_patch` / `try_delete` / `try_head` / `try_options` | `Result<RouteBuilder, FrameworkError>` |
| `Router::ws` (and every `ws_*` variant) | `try_ws` (and every `try_ws_*`) | `Result<Router, FrameworkError>` |
| `RouteBuilder::name` | `try_name` | `Result<Router, FrameworkError>` |
| `GroupBuilder` → `Router` via `.into()` | `GroupBuilder::try_finalize` | `Result<Router, FrameworkError>` |
| `ResourceRoutes::register` | `try_register` | `Result<Router, FrameworkError>` |

```rust
use suprnova::{FrameworkError, Router};

// `path` comes from dynamic config; a malformed or duplicate pattern
// is recoverable, not a startup panic.
fn register_dynamic(router: Router, path: &str) -> Result<Router, FrameworkError> {
    Ok(router.try_get(path, health)?.into())
}
```

A duplicate group route is recoverable the same way - because `From`
cannot be fallible, the fallible counterpart of `.into()` is the
inherent `try_finalize` method:

```rust
let router: Router = Router::new()
    .group("/api", |r| r.get("/users", list).post("/users", create))
    .try_finalize()?;
```

The panicking helpers stay as ergonomic escape hatches; the `try_*`
siblings are purely additive.

## Why Suprnova diverges

**Dual path-parameter syntax.** Laravel uses `{param}`; Express uses
`:param`. Suprnova accepts both and normalises `:param` to `{param}`
before the path reaches `matchit`. Both styles compose with everything
else - groups, model binding, signed URLs. The reason isn't
indecisiveness; it's that we can't predict which background you bring,
and routing syntax is too high-frequency a friction point to make people
relearn.

**Two co-equal APIs: macro and builder.** Laravel ships one DSL
(`Route::get(...)`). Suprnova ships the declarative `routes! { ... }`
macro AND the chainable `Router::new().get(...).name(...)` builder.
They produce identical registrations. The macro reads better for
top-level route tables; the builder reads better when you're composing
routers dynamically (plugins, generated routes, tests). Pick whichever
fits the call site - there's no canonical answer because both shapes
are first-class.

**The fallback answers every method.** Laravel registers its fallback as
a `GET` route that matches any path, so a `POST` to an unknown path there
is a `405` that lists `GET, HEAD`. Suprnova's fallback is not a route of
any method: it answers a path no route matches, whatever the method, and
the `405` is for paths your own routes match.

**Boot-time panics, not silent shadowing.** A duplicate route name or
pattern collision panics at startup. Laravel's array-keyed registries
silently let the later registration win, which is fine when your routes
file is the only registrar but unsafe once plugins or generated routes
enter the picture. `try_*` siblings are the escape hatch when fallibility
is what you actually want.

## Next

- [Controllers](controllers.md) - `#[handler]`, form requests, returning JSON/Inertia
- [Middleware](middleware.md) - the `Middleware` trait, ordering, building your own
- [URL Generation](urls.md) - named-route URLs, signed URLs, redirects, `RouteUrlError`
- [Authorization](authorization.md) - gates and policies for bound models
- [WebSockets](websockets.md) - `ws!`, the `WebSocketHandler` trait, per-route config


---

<!-- /docs/middleware -->

# Middleware

Middleware wraps a request handler. It runs before the handler sees the
request and again after the handler returns a response, so it's the
place to put cross-cutting work - auth, logging, CORS, throttling,
timing, transforming the request or response. Suprnova's surface is the
same one Laravel users already know: a `handle(request, next)` method
that decides whether to forward the request, short-circuit it, or
mutate the response on the way back out.

## The trait

A middleware is a struct that implements `Middleware`:

```rust
use suprnova::{async_trait, HttpResponse, Middleware, Next, Request, Response};

pub struct LoggingMiddleware;

#[async_trait]
impl Middleware for LoggingMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        // Pre-processing: runs before the handler.
        println!("--> {} {}", request.method(), request.path());

        // Forward to the next middleware (or the handler if this is
        // the last layer).
        let response = next(request).await;

        // Post-processing: runs after the handler returns.
        println!("<-- complete");

        response
    }
}
```

`handle` has three things to do, and you only have to do one of them
on any given request:

- **Forward.** Call `next(request).await` to pass control to the next
  layer. The returned `Response` is what every layer above will see.
- **Short-circuit.** Return `Err(HttpResponse::...)` without calling
  `next`. The framework collapses both arms of `Response`
  (`Result<HttpResponse, HttpResponse>`) into a single response - an
  `Err` is a response, not a crash. See [Error Model](error-model.md).
- **Mutate.** Modify the request before forwarding, or modify the
  response after.

`Next` is `Arc<dyn Fn(Request) -> MiddlewareFuture + Send + Sync>` -
treat it like an async function from `Request` to `Response`.

## Generating a stub

The CLI scaffolds a working middleware file:

```bash
suprnova make:middleware Auth         # → src/middleware/auth.rs (AuthMiddleware)
suprnova make:middleware RateLimit    # → src/middleware/rate_limit.rs
suprnova make:middleware CorsMiddleware  # "Middleware" suffix is fine, same result
```

The generated file isn't a TODO stub - it's a real middleware that
times the wrapped request and logs the inbound/outbound events with
the per-request id installed by `RequestIdMiddleware`. Replace the
body with whatever you actually need.

## Registering middleware

Three places to install it, depending on scope:

### Global

Runs on every request, in registration order. Use the
`global_middleware!` macro inside `bootstrap()`:

```rust
// src/bootstrap.rs
use suprnova::{global_middleware, FrameworkError};
use crate::middleware;

pub async fn bootstrap() -> Result<(), FrameworkError> {
    global_middleware!(middleware::LoggingMiddleware);
    global_middleware!(middleware::CorsMiddleware);
    Ok(())
}
```

`global_middleware!(M)` expands to `register_global_middleware(M)`.
Registration is **idempotent per concrete type** - registering the same
struct twice keeps the first registration and emits a debug log. That
makes re-running boot (tests, hot-reload, multiple `Server` instances
in a process) safe. To install several copies of the same behaviour
with different config, wrap each in a distinct newtype.

### Per route

Chain `.middleware(M)` on a route definition from the `routes!` macro:

```rust
// src/routes.rs
use suprnova::{routes, get};
use crate::{controllers, middleware::AuthMiddleware};

routes! {
    get!("/", controllers::home::index).name("home"),
    get!("/public", controllers::home::public),

    get!("/protected", controllers::dashboard::index)
        .middleware(AuthMiddleware),
    get!("/admin", controllers::admin::index)
        .middleware(AuthMiddleware),
}
```

`.middleware_named("auth")` applies a middleware by its registered name
instead of its type. See [Named aliases and groups](#named-aliases-and-groups).

### Per group

Apply middleware to every route in a `group(...)` block:

```rust
use suprnova::Router;
use crate::middleware::{ApiMiddleware, AuthMiddleware};
use crate::controllers::{user, admin};

Router::new()
    // Public routes - no middleware.
    .get("/", home_handler)
    .get("/login", login_handler)

    // Every route under /api carries ApiMiddleware.
    .group("/api", |r| {
        r.get("/users", user::index)
         .post("/users", user::store)
         .get("/users/{id}", user::show)
    })
    .middleware(ApiMiddleware)

    // Admin routes share auth.
    .group("/admin", |r| {
        r.get("/dashboard", admin::dashboard)
         .get("/settings", admin::settings)
    })
    .middleware(AuthMiddleware);
```

A resource controller can also declare the middleware of its own actions.
See [Controller middleware](controllers.md#controller-middleware).

### Leaving middleware out

A route leaves out a middleware its group gives it, as Laravel's
`withoutMiddleware` does. Name the middleware by type or by alias:

```rust
use suprnova::{routes, get, post, group};
use crate::middleware::EnsureJson;

routes! {
    group!("/api", {
        get!("/posts", controllers::posts::index),
        // The health check answers plain text, so it leaves EnsureJson out.
        get!("/health", controllers::health::check).without_middleware::<EnsureJson>(),
        // The webhook carries no session, so it leaves the alias out.
        post!("/webhook", controllers::webhooks::receive).without_middleware_named("auth"),
    })
    .middleware(EnsureJson)
    .middleware_named("auth"),
}
```

`/api/posts` still runs both. The two forms match differently:

| Call | Leaves out |
|---|---|
| `.without_middleware::<M>()` | Every middleware of type `M`, added by type or through an alias. |
| `.without_middleware_named("auth")` | The middleware resolved from the alias `auth`. |
| `.without_middleware_named("throttle:60,1")` | The middleware resolved from `throttle:60,1` only. `throttle:30,1` stays. |
| `.without_middleware_named("api")` | Every middleware of the group `api`. |

A few rules hold for both:

- **The order of the calls does not matter.** The route leaves the
  middleware out whether the group adds it before or after the call.
- **The global middleware stays.** It is not route middleware, as in
  Laravel, where `withoutMiddleware` removes route middleware only.
- **Only this route changes.** Its sibling routes in the group keep the
  middleware.

The methods are on `get!` and its siblings, `any!`, and the routes of
`Router::get` and its siblings. A name that no alias or group carries
makes `.without_middleware_named` panic at boot, as `.middleware_named`
does; `.try_without_middleware_named(name)` returns the error instead.

## Execution order

At runtime the chain runs outside-in:

```
Request  →  RequestId  →  globals  →  group MW  →  route MW  →  handler
                                                                  │
Response ←  RequestId  ←  globals  ←  group MW  ←  route MW  ←  handler
```

The first middleware added runs first, unless the
[middleware priority list](#middleware-priority) moves a middleware it
names. On the way back out, the order
reverses - `MiddlewareChain::execute` nests each layer's post-processing
inside the previous one.

If a middleware short-circuits with `Err(response)`, the chain unwinds
immediately: every layer ABOVE the short-circuit still sees the response
on the way back out, but layers BELOW (closer to the handler) do not run.

### Group middleware is flattened, not stacked

This one matters and is worth calling out. **Route-group middleware is
not a separate runtime layer.** When `GroupBuilder::try_finalize` runs,
it copies the group's middleware into each grouped route's
`(method, pattern)` middleware list. By execution time, group middleware
is indistinguishable from middleware attached directly to the route.

Two consequences:

- Runtime ordering is still correct (group middleware runs before route
  middleware because it's registered first), but **introspection cannot
  tell group from route middleware apart**.
- Middleware keyed by the matched pattern (`"/posts/{id}"`), not the
  raw path (`/posts/42`), so group middleware on parameterised routes
  fires reliably.

See `framework/src/routing/group.rs` for the flattening pass and
`framework/src/middleware/chain.rs` for the execution loop.

## Short-circuiting

Return early to block a request before it reaches the handler:

```rust
use suprnova::{async_trait, HttpResponse, Middleware, Next, Request, Response};

pub struct RequireApiKey;

#[async_trait]
impl Middleware for RequireApiKey {
    async fn handle(&self, request: Request, next: Next) -> Response {
        if request.header("X-Api-Key").is_none() {
            return Err(HttpResponse::text("Unauthorized").status(401));
        }
        next(request).await
    }
}
```

The chain collapses `Result<HttpResponse, HttpResponse>` to a single
response, so `Err(...)` is just a response with a different role. The
layers above this middleware still observe it on the way out and can
post-process it.

## Panic safety

`MiddlewareChain::execute` does NOT catch panics - a panic in any
middleware or in the handler unwinds straight out, like any other async
function. The request-path safety net lives one level up at the server
boundary in `execute_chain_safely`, which wraps the chain in
`catch_unwind` and converts a panic into a sanitised 500 with the
request id, dispatching `ErrorOccurred` for any observability listener.
See [Request Lifecycle](lifecycle.md) for the full panic-recovery flow.

This split is deliberate: standardised panic handling happens exactly
once, where the request lifecycle owns it, rather than being duplicated
inside the layer-agnostic primitive. A consumer driving a chain outside
that boundary is responsible for its own `catch_unwind`.

## Built-in middleware

A non-exhaustive map. Each ships ready to install - most need a config
struct, none need scaffolding.

| Middleware | Purpose |
|---|---|
| `RequestIdMiddleware` | Always-outermost layer; assigns a UUID per request and tags it through logs + `X-Request-Id` |
| `TimeoutMiddleware` | Bounds time-to-response; returns 503 when exceeded (see below) |
| `CorsMiddleware` | Handles CORS preflight + decorates cross-origin responses (see below) |
| `CsrfMiddleware` | Cookie-double-submit CSRF protection with configurable `OriginPolicy` |
| `RateLimitMiddleware` / `ThrottleRequestsMiddleware` | Token-bucket and sliding-window throttling; see [Rate Limiting](rate-limiting.md) |
| `SessionMiddleware` | Loads/persists the session over cookies; powers `req.session()` |
| `AuthMiddleware` / `GuestMiddleware` / `BearerTokenMiddleware` | Guard membership checks; see [Authentication](authentication.md) |
| `LoginThrottleMiddleware` / `EnsureEmailVerifiedMiddleware` / `TwoFactorChallengeMiddleware` | Auth-flow gates; see [Auth Flows](auth-flows.md) |
| `MaintenanceMiddleware` | Returns 503 when the cache or filesystem maintenance flag is set |
| `InertiaHeadersMiddleware` / `InertiaVersionMiddleware` / `Inertia303Middleware` / `InertiaValidationRedirectMiddleware` / `EncryptHistoryMiddleware` | Inertia protocol: `Vary: X-Inertia` on every response and empty-200 redirect back; asset-version 409 bounce; 302→303 on `PUT`, `PATCH` and `DELETE` redirects; a 422 on an Inertia visit becomes a 303 back with the errors flashed; history encryption. `Inertia::install` registers the first four; `EncryptHistoryMiddleware` is opt-in separately. See [Inertia Responses](frontend-inertia-responses.md#bootstrap-inertiainstall) |
| `IncludeMiddleware` | Per-field include sets for `#[derive(Data)]` partial reloads |

### Request timeouts

`TimeoutMiddleware` bounds how long a handler may take to *produce* a
response. A slow handler or a hung database query can otherwise hold
a connection open indefinitely; the timeout returns
`503 Service Unavailable` once the deadline is exceeded.

```rust
// src/bootstrap.rs - 30-second ceiling on every HTTP route.
use suprnova::{global_middleware, TimeoutMiddleware};

global_middleware!(TimeoutMiddleware::default()); // DEFAULT_TIMEOUT = 30s
```

```rust
// Tighten a single endpoint to 5 seconds.
use suprnova::{Router, TimeoutMiddleware};

Router::new()
    .get("/report", heavy_report_handler)
    .middleware(TimeoutMiddleware::seconds(5));
```

`TimeoutMiddleware::new(Duration)` accepts any duration;
`TimeoutMiddleware::seconds(n)` is shorthand for whole seconds.

Global middleware runs **outside** route middleware, so a global timeout
is an outer ceiling and a per-route timeout can only make a specific
route *stricter* - the shorter deadline fires first. To let one route
run longer than the global default, raise the global value or scope the
global middleware to a route group that excludes that endpoint.

Streaming responses (`HttpResponse::sse(...)`,
`HttpResponse::stream_bytes(...)`) are naturally exempt: the handler
returns immediately with a lazy body that hyper drains after the
middleware chain completes. WebSocket upgrades are also skipped
explicitly. See [Timeouts](timeout.md) for cancel-safety semantics.

### CORS

`CorsMiddleware` adds the `Access-Control-*` headers a browser needs to
let a cross-origin page read your responses, and answers the preflight
`OPTIONS` request browsers send before non-simple cross-origin calls.
Same-origin apps (the default Inertia setup) don't need it - it matters
only when a browser on a *different* origin calls your API.

CORS must be installed **globally** so preflights reach it (a preflight
never matches a route, so a per-route CORS middleware would never see
one). There is intentionally no permissive default - pick an origin
policy explicitly:

```rust
// src/bootstrap.rs
use suprnova::{global_middleware, CorsConfig, CorsMiddleware};

global_middleware!(CorsMiddleware::new(
    CorsConfig::allow_origins(["https://app.example", "https://admin.example"])
        .allow_credentials(true)
        .max_age(std::time::Duration::from_secs(600)),
));
```

`CorsConfig::any_origin()` opts into `Access-Control-Allow-Origin: *`
explicitly. Builder methods: `.methods([...])`, `.allow_headers([...])`
/ `.allow_any_headers()`, `.expose_headers([...])`, `.paths([...])`
(scope CORS to URL patterns), `.allow_origin_patterns([regex...])`,
`.skip_when(|req| bool)`, `.allow_credentials(bool)`,
`.max_age(Duration)`. Laravel-named aliases ship alongside (e.g.
`.supports_credentials`, `.allowed_methods`) so a Laravel config maps
directly.

`Access-Control-Allow-Origin: *` is invalid together with credentials -
the browser rejects it. When `.allow_credentials(true)` is set, the
middleware always echoes the specific request `Origin` instead of `*`,
so the invalid combination can never be emitted. Non-wildcard responses
also get `Vary: Origin` so shared caches stay correct. See
[CORS](cors.md).

## Pipeline - Laravel's `Illuminate\Pipeline\Pipeline`

`Pipeline` is the Suprnova analogue of Laravel's pipeline class - a
fluent builder over `MiddlewareChain` that mirrors the `send / through /
pipe / then / then_return / finally_with` shape Laravel users already
know. Useful when you want to assemble a middleware chain outside the
request lifecycle (a job, a CLI command, a one-off integration test):

```rust
use suprnova::{Pipeline, Request};

let response = Pipeline::new()
    .send(request)
    .through([AuthMiddleware, LoggingMiddleware])
    .pipe(CorsMiddleware::new(cors_config))
    .finally_with(|| tracing::info!("pipeline complete"))
    .then(|req| async move { handler(req).await })
    .await;
```

Rust-side aliases ship alongside the Laravel names: `with_request` for
`send`, `with_middleware` for `through`, `push` for `pipe`, `on_finally`
for `finally_with`, `execute` for `then`. Use whichever reads better in
your codebase.

| Pipeline method | Laravel | Rust alias | Purpose |
|---|---|---|---|
| `send(request)` | `send($passable)` | `with_request(request)` | Set the request being threaded through |
| `through(iter)` | `through($pipes)` | `with_middleware(iter)` | Replace the pipe list |
| `through_boxed(iter)` | - | - | Replace the pipe list with pre-boxed middleware |
| `pipe(M)` | `pipe($pipes)` | `push(M)` | Append a single middleware |
| `pipe_boxed(M)` | - | - | Append a pre-boxed middleware |
| `then(destination)` | `then($destination)` | `execute(destination)` | Run the chain with the destination handler |
| `then_with(req, dst)` | - | - | Override the passable inline |
| `then_return()` | `thenReturn()` | - | Run the chain, return a 204 No Content |
| `finally_with(F)` | `finally($callback)` | `on_finally(F)` | Run after the destination resolves |
| `pipe_all(iter)` | `pipe([$pipes])` | - | Append several middleware, keeping the list `through` set |

### Sending any value through steps

Laravel's pipeline sends any value, not only a request. `Pipeline::of(value)`
does the same: it returns a pipeline over a value of any type, whose steps
receive the value and the rest of the pipeline. A step passes the value on
with `next(value).await`, and stops the pipeline by answering an error:

```rust
use suprnova::{FrameworkError, Pipeline};
use suprnova::middleware::{PipelineFuture, PipelineNext};

fn add_tax(total: i64, next: PipelineNext<i64>) -> PipelineFuture<i64> {
    next(total * 120 / 100)
}

fn refuse_negative(total: i64, next: PipelineNext<i64>) -> PipelineFuture<i64> {
    if total < 0 {
        return Box::pin(async { Err(FrameworkError::internal("negative total")) });
    }
    next(total)
}

let total = Pipeline::of(1_000)
    .through([refuse_negative, add_tax])
    .then_return()
    .await?;
assert_eq!(total, 1_200);
```

A step is anything that implements `PipelineStep`: a function of the shape
above, an `async fn (value, next) -> Result<_, FrameworkError>`, an
`async move` closure, or a type with a `handle` method when the step holds
settings. A closure names the types of its parameters:

```rust
let total = Pipeline::of(10)
    .pipe(|total: i64, next: PipelineNext<i64>| async move { next(total + 5).await })
    .then_return()
    .await?;
```

| Method | Laravel | Purpose |
|---|---|---|
| `Pipeline::of(value)` | `send($passable)` | Start a pipeline over `value` |
| `through(steps)` | `through($pipes)` | Set the steps, replacing earlier ones |
| `pipe(step)` | `pipe($pipe)` | Append one step |
| `pipe_all(steps)` | `pipe([$pipes])` | Append several steps, in order |
| `finally(f)` | `finally($callback)` | Run `f` when the pipeline ends, failed or not |
| `within_transaction()` | `withinTransaction()` | Run the steps and the destination in one database transaction |
| `then(destination)` | `then($destination)` | Run the steps around the destination and answer its result |
| `then_return()` | `thenReturn()` | Run the steps and answer the value |

`then` lets the destination answer another type, and each step sees that
result on the way back:

```rust
let receipt: String = Pipeline::of(1_000)
    .pipe(add_tax)
    .then(|total| async move { Ok(format!("total: {total}")) })
    .await?;
```

With `within_transaction()`, an error from any step or the destination
rolls back every database write they made, as
[`DB::transaction`](database.md) does. `finally` runs after the
transaction ends, and also when the pipeline's future is dropped before
it finishes.

## Terminable middleware - post-response hooks

Terminable middleware runs *after* the response has been sent to the
client. Use it for slow IO that doesn't need to block the response:
session persistence, audit logging, metrics flushes.

Suprnova ships this as a dedicated `Terminable` trait separate from
`Middleware`, so the request-path and termination-path stay clearly
typed. A type can implement one, the other, or both:

```rust
use suprnova::{Terminable, TerminationSnapshot, register_terminable, async_trait};

pub struct AuditLogTerminator;

#[async_trait]
impl Terminable for AuditLogTerminator {
    async fn terminate(&self, snapshot: &TerminationSnapshot) {
        tracing::info!(
            method = %snapshot.method,
            path = %snapshot.path,
            status = snapshot.status,
            "request handled",
        );
    }
}

// In bootstrap.rs
register_terminable(AuditLogTerminator);
```

The server iterates registered terminables in registration order after
every response (4xx and 5xx included) and awaits each one. A WebSocket
upgrade counts as a response: its terminables see status 101, or the
status that refused the upgrade. `terminate` returns nothing, because the
response has already left the building and there's nobody left to
surface an error to. A hook that panics is logged via `tracing::error!`,
and the hooks registered after it still run. A graceful shutdown waits up
to five seconds for the hooks still running, after the connections drain,
and aborts the rest.

Registration is idempotent per concrete type. `registered_terminables()`,
`terminable_count()`, and `has_terminable::<T>()` provide introspection
for tests and boot-time diagnostics.

## Named aliases and groups

For consumers that prefer string-keyed middleware (Laravel's
`middlewareAliases` / `middlewareGroups`), Suprnova ships a
process-global alias + group registry. A route names the middleware it
wants with `.middleware_named(...)`:

```rust
use suprnova::middleware::{
    register_middleware_alias, register_middleware_alias_with_args,
    register_middleware_group, resolve_middleware_group,
};
use suprnova::rate_limit::ThrottleRequestsMiddleware;
use suprnova::Router;

// Aliases are factory closures - invoked fresh per resolution, so each
// route registration produces an independent middleware instance.
register_middleware_alias("auth", || AuthMiddleware::new());

// An alias that reads arguments takes a factory of `&[&str]`.
register_middleware_alias_with_args("throttle", ThrottleRequestsMiddleware::from_alias_args);

// Groups bundle aliases. Nested groups are supported.
register_middleware_group("api", ["auth".into(), "throttle".into()]);

// A route names an alias, an alias with arguments, or a group.
let router = Router::new()
    .get("/reports", reports_handler)
    .middleware_named("auth")
    .middleware_named("throttle:60,1");

// Or resolve a group into a Vec<BoxedMiddleware> yourself.
let api_mws = resolve_middleware_group("api")?;
```

`.middleware_named(name)` is on every builder that has `.middleware(M)`:
a route from `Router::get` and its siblings, `Router::group(...)`, and the
route builders and `group!` of the `routes!` macro. The name is one of:

| Name | Middleware it adds |
|---|---|
| `auth` | The alias `auth`. |
| `throttle:60,1` | The alias `throttle`, called with the arguments `["60", "1"]`. Arguments follow the colon, separated by commas, and spaces around a name or an argument are trimmed. |
| `api` | Every middleware of the group `api`, in order, each once. A group wins over an alias of the same name. |

A route runs each named middleware once, where it first appears, as
Laravel's `uniqueMiddleware` does across group and route middleware. When
two nested groups both include a third, a group names the same alias
twice, or a route names an alias a group already gave it, the repeat is
dropped, so a `throttle:60,1` reached twice counts one hit per request.
Group middleware comes before the route's own, so a repeat keeps the
group's place. The alias and its arguments identify the middleware:
`throttle:60,1` and `throttle: 60, 1` are one, `throttle:30,1` is
another. Middleware added by type, with `.middleware(M)`, has no alias
and is never dropped.

A route resolves the name when it is registered, which is at boot. A name
that no alias or group carries, an alias that takes no arguments but is
given some, and an alias whose factory refuses its arguments all make
`.middleware_named` panic, so a typo never becomes a route that serves
without its middleware. `.try_middleware_named(name)` returns
`Result<_, FrameworkError>` instead of panicking. Register every alias
before the routes that name it.

`register_middleware_alias` registers an alias that takes no arguments.
`register_middleware_alias_with_args` registers one whose factory reads
them. The factory receives `["60", "1"]` for `throttle:60,1` and an empty
slice for the bare `throttle`. An alias is one kind or the other: a later
registration replaces the earlier one whichever kind it was.

`ThrottleRequestsMiddleware::from_alias_args` reads the arguments the way
Laravel reads `throttle:60,1`. See
[Rate Limiting](rate-limiting.md#named-aliases) for the forms it accepts.

`resolve_middleware_group` returns `Err(MiddlewareResolveError)` on:

- `UnknownGroup(name)` - the named group was never registered;
- `UnknownAlias { group, missing }` - a group entry isn't a known alias;
- `UnknownNestedGroup { group, missing }` - a nested group reference
  fails to resolve;
- `CycleDetected { group }` - the group definition is recursive.

Registration of an alias or group is **last-wins** for the same name,
mirroring Laravel's reassignable kernel array.

## Middleware priority

The priority list is the Suprnova analogue of Laravel's
`Kernel::$middlewarePriority`: a process-global list of middleware types
that gives order-dependent middleware a safe order when global, group and
route registrations interleave. `MiddlewareChain::execute` applies it each
time a chain runs, so the order holds for a matched route, the fallback,
an unrouted request and a WebSocket upgrade alike.

The list starts with the framework's order-dependent middleware, the four
entries of Laravel's list that have a Suprnova type, in Laravel's order:

1. `Precognitive`
2. `SessionMiddleware`
3. `AuthMiddleware`
4. `ThrottleRequestsMiddleware`

`default_middleware_priority()` answers that list. So a route that lists
`AuthMiddleware` before `SessionMiddleware` still loads the session first,
and a signed-in user is not refused:

```rust
use suprnova::{AuthMiddleware, Router, SessionMiddleware};

// The session runs first, whatever order the route lists them in.
let router = Router::new()
    .get("/account", account)
    .middleware(AuthMiddleware::new())
    .middleware(SessionMiddleware::new(session_config));
```

`BasicAuthMiddleware` and `BearerTokenMiddleware` are not in the default
list. Each checks a credential itself, so a throttle you list before one
of them keeps counting failed guesses against it, as Laravel's list leaves
out its basic-auth middleware. An `AuthMiddleware` is in the list, so it
moves in front of a `ThrottleRequestsMiddleware` you list first. That
includes an `AuthMiddleware` whose guard is an `Auth::via_request`
resolver, which checks a credential, as Laravel's `Authenticate` moves
with a `viaRequest` guard. To keep a throttle in front of such a guard,
replace the list with `set_middleware_priority`, putting
`ThrottleRequestsMiddleware` before `AuthMiddleware` or leaving it out.

You change the list at boot:

```rust
use std::any::TypeId;
use suprnova::middleware::{
    add_to_middleware_priority_after, add_to_middleware_priority_before,
    append_middleware_priority, set_middleware_priority,
};

// Replace the whole list, as Laravel's `->priority([...])` does.
set_middleware_priority([
    TypeId::of::<SessionMiddleware>(),
    TypeId::of::<AuthMiddleware>(),
]);

// Insert relative to an entry, as `addToMiddlewarePriorityBefore` and
// `addToMiddlewarePriorityAfter` do.
add_to_middleware_priority_before::<AuthMiddleware, TenantMiddleware>();
add_to_middleware_priority_after::<AuthMiddleware, AuditMiddleware>();

// Add at either end.
append_middleware_priority::<CacheHeaders>();
```

`add_to_middleware_priority_before::<Existing, M>()` puts `M` just before
`Existing`, and `add_to_middleware_priority_after` just after it. When
`Existing` is not in the list, `M` is appended. When `M` is already in the
list, nothing changes. `append_middleware_priority` puts a type at the end
of the list and `prepend_middleware_priority` puts it in front of every
type the list holds; adding a type the list already holds does nothing.
`set_middleware_priority([])` empties the list, which leaves every chain in
registration order.

### What moves

Only a middleware that the list names can move, and it only moves toward
the front of the chain. When a listed middleware stands behind a
middleware that the list places after it, it moves to just before that
one. Everything else keeps its place relative to its neighbours.

So a middleware the list does not name keeps its place behind the
middleware it was registered after. If you register `CacheHeaders` after
`AuthMiddleware`, `CacheHeaders` still runs after `AuthMiddleware`, even
when the list moves `SessionMiddleware` in front of `AuthMiddleware`.

An empty list leaves the chain in registration order.

The list orders global and route middleware together. A route-listed
`Precognitive` therefore runs before a global `SessionMiddleware`, so a
precognitive request is marked before the session starts, as in Laravel.

### What the list sees

The list orders middleware by type, so it sees the middleware you
register by type:

- `.middleware(M)` on a route or a group;
- `global_middleware!(M)` and `register_global_middleware(M)`;
- an alias, through `.middleware_named(...)` or a group.

`into_boxed(M)` retains the type and framework metadata. Adding that box
with `.middleware_boxed(...)` follows the same priority order and boot
checks as `.middleware(M)`. A raw closure built by hand still has no known
type and keeps its place.

RenderCache keeps security headers and Inertia protocol middleware outside
its publication boundary, including when the priority list is empty. The
asset-version check runs before cache lookup. Cacheable page transport
headers run after publication and keep the assembled response private.

`middleware_priority()` returns a snapshot of the current `Vec<TypeId>`
for diagnostics.

## Registry introspection

Beyond `register_global_middleware`, the registry exposes:

| Surface | Laravel | Purpose |
|---|---|---|
| `prepend_global_middleware(M)` | `prependMiddleware` | Insert at the front of the chain |
| `has_global_middleware::<M>()` | `hasMiddleware` | Whether type `M` is registered |
| `global_middleware_count()` | - | Number of globals currently registered |
| `MiddlewareRegistry::from_global()` | - | Snapshot the global registry into a per-server registry |
| `MiddlewareRegistry::prepend(M)` | - | Builder-style prepend on a registry instance |
| `MiddlewareRegistry::append_boxed(M)` | - | Append a pre-boxed middleware |
| `MiddlewareRegistry::prepend_boxed(M)` | - | Prepend a pre-boxed middleware |
| `MiddlewareRegistry::len()` / `is_empty()` | - | Builder introspection |

`MiddlewareRegistry::from_global()` snapshots the global registry at
call time. Register every global middleware BEFORE constructing the
server - a `global_middleware!` call made AFTER the server is built
does not retroactively apply, so a running server's middleware stack
cannot shift underneath it.

## File layout

A typical layout once you have a few middlewares:

```
src/
├── middleware/
│   ├── mod.rs          # mod + pub use
│   ├── auth.rs         # AuthMiddleware
│   ├── logging.rs      # LoggingMiddleware
│   └── audit.rs        # AuditLogTerminator
├── bootstrap.rs        # global_middleware! + register_terminable
├── routes.rs           # .middleware(M) per-route
└── main.rs
```

`make:middleware` keeps `src/middleware/mod.rs` in sync - it appends
the new `mod foo;` declaration and the matching `pub use foo::FooMiddleware;`
re-export when the file is generated.

## Why Suprnova diverges

Laravel registers middleware classes in `app/Http/Kernel.php` and
resolves them through the container, which performs reflection on
constructor type-hints to inject dependencies. PHP's request-per-process
model means the kernel is rebuilt every request, so the cost of
reflective resolution is paid once per request and disappears between
requests.

Suprnova's process model is one binary serving many concurrent requests
across many threads. Building a fresh chain per request would force a
synchronisation point on the global middleware list and re-allocate
`Arc<dyn Middleware>` for every layer on every request. Instead:

- Global middleware is registered into a `OnceLock<RwLock<Vec<...>>>`
  at boot, keyed by `TypeId` for idempotent registration.
- `MiddlewareRegistry::from_global()` snapshots the global list once at
  server construction; the per-request chain reuses that snapshot.
- The chain itself is composed by nesting `Arc<dyn Fn>` closures, so
  per-request work is one `Arc::clone` per layer rather than a fresh
  allocation.

The priority list orders global middleware too. Laravel's
`$middlewarePriority` sorts the middleware of a route and leaves the
global stack as registered; Suprnova sorts the whole chain, so a route's
`Precognitive` moves in front of a global `SessionMiddleware`.

Leaving middleware out by name diverges too. Laravel resolves an alias
to its class and compares class names, so `withoutMiddleware('json')`
also removes `EnsureJson::class` added by class. Suprnova compares the
alias and its arguments as written, and `.without_middleware::<M>()` is
the form that removes a type however it was added. A name that no alias
or group carries stops the boot, where Laravel ignores it.

The user-facing surface - `handle(request, next)`, the `global_middleware!`
macro, named aliases, priority lists, terminable hooks - is the same
one a Laravel developer reaches for. The machinery underneath swaps
PHP's per-request rebuild for a Rust-shaped snapshot-at-boot model so
the framework can serve concurrent requests without contending on the
registry.

## Next

- [Request Lifecycle](lifecycle.md) - where the chain runs and how
  panics are caught at the server boundary
- [Error Model](error-model.md) - what `Result<HttpResponse, HttpResponse>`
  actually means and how short-circuits collapse
- [Timeouts](timeout.md) - `TimeoutMiddleware` cancel-safety in detail
- [CORS](cors.md) - preflight handling, origin patterns, path scoping
- [Rate Limiting](rate-limiting.md) - `RateLimitMiddleware` /
  `ThrottleRequestsMiddleware` and `BackendErrorPolicy`
- [Routing](routing.md) - what `routes!`, `Router`, and `group(...)`
  expand into


---

<!-- /docs/csrf -->

# CSRF

`CsrfMiddleware` validates a per-session token on every request whose
method is not `GET`, `HEAD` or `OPTIONS`. It mirrors Laravel 13's
`PreventRequestForgery` - same token sources, same `XSRF-TOKEN` cookie
convention, same `Sec-Fetch-Site` origin verification, same 419 token
mismatch / 403 origin mismatch split - implemented on top of Suprnova's
session middleware.

## Install it globally

CSRF runs after the session middleware (it needs the session's CSRF
token to compare against). In `bootstrap.rs`:

```rust
use suprnova::{global_middleware, CsrfMiddleware, SessionConfig, SessionMiddleware};

pub async fn register() {
    let session_config = SessionConfig::from_env();
    global_middleware!(SessionMiddleware::new(session_config));
    global_middleware!(CsrfMiddleware::new());
}
```

`SessionMiddleware::new(SessionConfig)` takes the config; the default
constructor wires up the database-backed `DatabaseSessionDriver`
internally. Use `SessionMiddleware::with_store(config, store)` to plug
in a custom `SessionStore`.

`CsrfMiddleware` must come **after** `SessionMiddleware` in registration
order - global middleware runs outside-in, so the session is loaded
before CSRF reads its token.

## How a request flows

```mermaid
flowchart TD
    state{"reading method?<br/>GET / HEAD / OPTIONS"}
    excluded{"excluded path?<br/>.except / .except_method"}
    origin{"origin policy passes?<br/>Sec-Fetch-Site"}
    session{"session has a token?"}
    form{"form or JSON body with a _token value?"}
    header{"X-CSRF-TOKEN value?"}
    xsrf{"X-XSRF-TOKEN value?"}
    check{"token matches the session's?"}
    fast["fast path: run handler,<br/>attach XSRF-TOKEN cookie"]
    run["run handler"]
    deny403["403"]
    deny419["419"]

    state -- "yes" --> fast
    state -- "no" --> excluded
    excluded -- "yes" --> fast
    excluded -- "no" --> origin
    origin -- "passes" --> run
    origin -- "fails · OriginOnly mode" --> deny403
    origin -- "fall through · other modes" --> session
    session -- "no" --> deny419
    session -- "yes" --> form
    form -- "yes" --> check
    form -- "no" --> header
    header -- "yes" --> check
    header -- "no" --> xsrf
    xsrf -- "yes" --> check
    xsrf -- "no" --> deny419
    check -- "yes" --> run
    check -- "no" --> deny419
```

GET, HEAD, and OPTIONS are never token-checked, but they still hit the
bottom of the middleware so the `XSRF-TOKEN` cookie attaches to the
response. That's how SPA clients first acquire the cookie. A response marked
for shared caching (`Cache-Control: public` or an `s-maxage`) gets no
`XSRF-TOKEN` while the session is unchanged, because a CDN could replay it to
other visitors; see [sessions](session.md#how-a-request-sees-the-session).

Every other method is checked, as Laravel's `isReading` decides:
`POST`, `PUT`, `PATCH` and `DELETE`, and also `QUERY` and extension
methods such as WebDAV's `PROPFIND`. A `QUERY` request to a `query!` route
therefore sends its token like a `POST` does. A method the middleware does
not know is not known to be safe, so it is checked.

## Token sources, in priority order

The middleware takes the token from the first of three places that has a
value, in Laravel's order (`getTokenFromRequest`):

1. **`_token` in the body** - the `_token` field of an
   `application/x-www-form-urlencoded` post from a traditional HTML form,
   or the top-level `_token` string of a JSON body (any `Content-Type`
   that names `/json` or `+json`, as Laravel's `isJson` reads it). A name
   sent twice counts by its last value.
2. **`X-CSRF-TOKEN` header** - what a hand-written request sends after
   reading the `<meta name="csrf-token">` tag.
3. **`X-XSRF-TOKEN` header** - Laravel / Axios / Angular convention:
   JavaScript reads the `XSRF-TOKEN` cookie and echoes its value here.
   This is the one the scaffolded SPA entry points use.

The first source with a value is the token, and the others aren't read: a
form whose `_token` is wrong fails even beside a right header, and a
right `_token` passes whatever header came with it. A source counts as
having no value as PHP's `?:` reads one: absent, empty, `0`, or a JSON
value that is falsy in PHP (`null`, `false`, `0.0`, `[]`, `{}`). A JSON
`_token` that is present but not a string, such as `123`, `true`, or a
non-empty array, is kept and the request is refused with a `419`, without
reading the headers. A JSON body that does not parse holds no token, and the
headers decide.

```ts
await fetch('/posts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ _token: token, title: 'Hello' }),
});
```

To read `_token`, the middleware buffers a form-urlencoded body up to the
server's request body limit (8 MiB unless you set another with
`set_global_max_request_body_bytes`), the size the handler reads it to. A
larger body answers `413`, as Laravel's `ValidatePostSize` answers one
before the token check. The downstream handler still sees the full form
bag - the buffering is transparent, so `_token` stays in the parsed form
for any handler that wants to look at it.

A JSON body is read up to the same limit and kept for the handler, which
still reads all of it. A JSON body over the limit is left to the handler,
whose own cap can be larger (`#[form_request(max_body_bytes = ...)]`), and
holds no token, so it has to send its token in a header.

### Why Suprnova diverges

Laravel reads `_token` from all request input: the query string and a
multipart body as well as a form or JSON body. Suprnova reads it from a
form-urlencoded or JSON body only. A token in the query string leaks into
server logs, browser history and `Referer` headers. A multipart body
streams its files to the handler as they arrive, so it would have to be
read whole before the handler. Those clients send the token in a header.

## The frontend side

The scaffolded Svelte, React, and Vue entry points carry no CSRF wiring at
all, and that is deliberate. The Inertia client the scaffold installs
(`@inertiajs/svelte`, `@inertiajs/react`, `@inertiajs/vue3`, all pinned
`^3.8.0`) reads the `XSRF-TOKEN` cookie `CsrfMiddleware` attached to the
previous response and sets the `X-XSRF-TOKEN` header itself, once per
visit. The value that travels is whatever the browser holds at that
moment, so a login or a logout that rotates the session's token is
followed by a visit carrying the new one.

Do not read `<meta name="csrf-token">` once at module load and pin it into
a `router.on('before', ...)` hook. That freezes the token as it stood when
the page booted; the first rotation strands the frozen copy and the next
state-changing visit is refused with a 419.

The `<meta name="csrf-token">` tag is injected into the Inertia base
view automatically by `framework/src/inertia/response.rs` - you don't
need to add it yourself in a generated project. Every Inertia response
carries the current session's token in the page shell, which is where a
hand-written request reads it from.

Inertia's `useForm` runs through the same visit pipeline, so the client
sets the same header on its submissions:

```tsx
import { useForm } from '@inertiajs/react';

const form = useForm({ title: '', content: '' });
form.post('/posts');
```

For a raw `fetch` call, read the token off the meta tag yourself:

```ts
const token = document
  .querySelector('meta[name="csrf-token"]')
  ?.getAttribute('content') ?? '';

await fetch('/api/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-TOKEN': token,
  },
  body: JSON.stringify({ /* ... */ }),
});
```

## The `XSRF-TOKEN` cookie

On every response - read or write - `CsrfMiddleware` attaches an
`XSRF-TOKEN` cookie containing the current session's token, with one
exception described below. This is
the Laravel-Axios convention: the SPA library reads the cookie via
JavaScript and echoes it as `X-XSRF-TOKEN` on the next state-changing
request, completing the round-trip without ever touching a meta tag.

The token belongs to the session, so a response that hands it out also
keeps the session: when the request started a new session and the response
is a success (2xx) or a redirect (3xx), `CsrfMiddleware` marks the session
for storage, and `SessionMiddleware` sends its cookie with the response. A
cookieless SPA that calls a JSON or `HEAD` endpoint first gets a token its
next unsafe request can use.

The exception is a refused or failed response to a request that started a
new session and changed nothing in it: a 401 from an auth gate, a 403, a
404, or a 500. That response carries no `XSRF-TOKEN` and stores no session.
The caller was turned away, a token without its stored session would only
earn a 419, and an anonymous probe of a route that refuses it costs no
session write and does not fail when the session store is unavailable. A
request that arrived with a stored session always gets its token.

The cookie is **not** `HttpOnly` - it has to be readable from JS. The
value is therefore stored as plaintext (no encryption round-trip),
because the JS-side value must match what the middleware compares
server-side. Laravel encrypts the cookie via `EncryptCookies` running
in front of `PreventRequestForgery`; Suprnova ships it plaintext and
documents the divergence - same wire behaviour from the client's
perspective.

### Cookie attributes

Defaults match `SessionConfig::default()`: the public root of each request
as the `Path` (`/` at the host root, `/billing` behind a trusted
`X-Forwarded-Prefix: /billing`, and `/` for a `__Host-` name), `Secure`,
`SameSite=Lax`, `Max-Age=7200` (2 hours), no `Domain`. Override per
builder:

```rust
use std::time::Duration;
use suprnova::{CsrfMiddleware, http::SameSite};

CsrfMiddleware::new()
    .xsrf_cookie_path("/app")
    .xsrf_cookie_domain(".example.com")
    .xsrf_cookie_secure(false)             // for local HTTP dev
    .xsrf_cookie_same_site(SameSite::Strict)
    .xsrf_cookie_lifetime(Duration::from_secs(15 * 60));
```

### Sync from `SessionConfig`

If you override `SESSION_PATH` / `SESSION_DOMAIN` / `SESSION_SECURE` /
`SESSION_SAME_SITE` / `SESSION_LIFETIME` in `.env`, the session cookie
respects those overrides - but the XSRF cookie's defaults wouldn't,
which silently desynchronises the two. The fix is a one-call alignment:

```rust
let session_config = SessionConfig::from_env();
let csrf = CsrfMiddleware::new().with_session_config(&session_config);
global_middleware!(SessionMiddleware::new(session_config));
global_middleware!(csrf);
```

`with_session_config` copies `cookie_path`, `cookie_domain`,
`cookie_secure`, `lifetime`, and parses `cookie_same_site` with the
same case-insensitive matrix the session middleware uses (`"strict"` →
`Strict`, `"none"` → `None`, anything else → `Lax`).

`with_session_config` deliberately does **not** copy
`SessionConfig::cookie_prefix`. The session and remember-me cookies use the
wire prefix, but Axios and similar clients commonly look up the literal
`XSRF-TOKEN` name (`xsrfCookieName` in Axios). Prefixing it as a side effect
would make the browser and client disagree about where the token lives.

If the client is configured for a prefixed XSRF cookie, opt into that name
explicitly:

```rust
let csrf = CsrfMiddleware::new().xsrf_cookie_name("__Host-XSRF-TOKEN");
```

The cookie renderer then supplies `Secure`, `Path=/`, and no `Domain` for the
`__Host-` name. The session prefix remains an independent setting; configure
both deliberately when both cookies need host locking.

### Disable it

For a pure server-rendered app where you only ever issue the token via
`{{ csrf_meta_tag() }}` (no SPA round-tripping), drop the cookie:

```rust
global_middleware!(CsrfMiddleware::new().without_xsrf_cookie());
```

## Excluding routes

Webhook endpoints, OAuth callbacks, and other external integrations
can't carry a CSRF token. Exempt them with `.except(...)`:

```rust
global_middleware!(
    CsrfMiddleware::new()
        .except(vec!["/webhooks/*", "/api/external/*"])
);
```

Each entry is a Laravel-style glob (`Str::is` semantics): `*` matches
any run of characters, including `/`.

| Pattern | Matches |
|---|---|
| `"/login"` | only `/login` |
| `"/webhooks/*"` | `/webhooks/stripe`, `/webhooks/github/events`, … |
| `"/api/*/internal"` | `/api/v1/internal`, `/api/v2/internal` |
| `"*/healthz"` | any path with `/healthz` somewhere |

Leading slashes normalise - `"webhooks/*"` and `"/webhooks/*"` behave
identically. Bare `/healthz` (no prefix segment) does **not** match
`"*/healthz"`, matching Laravel's `Str::is` exactly.

### Per-method exemptions

Sometimes a webhook prefix legitimately handles both unauthenticated
`POST` callbacks (which can't carry a token) and authenticated `DELETE`
admin requests (which can and should). Use `.except_method`:

```rust
global_middleware!(
    CsrfMiddleware::new()
        // Stripe POST callbacks bypass CSRF…
        .except_method("POST", "/webhooks/stripe/*")
        // …but DELETEs against the same prefix still require a token.
);
```

The method comparison is case-insensitive. `.except(...)` rules apply
to every method; `.except_method(...)` rules only fire for the verb
they name.

## Origin verification

Modern browsers set `Sec-Fetch-Site` on every fetch over HTTPS. A
matching value tells you the request came from the same origin
(or the same registrable domain) without any token round-trip.
`CsrfMiddleware` can consult this header in addition to - or instead of -
the token check.

`OriginPolicy` is the value type that picks which mode runs:

| Variant | Behaviour |
|---|---|
| `Disabled` (default) | Ignore `Sec-Fetch-Site`. Only token validation runs. |
| `SameOriginOnly` | `same-origin` passes; anything else falls through to token validation. |
| `AllowSameSite` | `same-origin` and `same-site` pass; anything else falls through. |
| `OriginOnly` | `Sec-Fetch-Site` is the **only** gate. Token check is skipped. A miss is a **403** (not 419). |

Two convenience builders cover the common cases:

```rust
CsrfMiddleware::new().allow_same_site();   // OriginPolicy::AllowSameSite
CsrfMiddleware::new().origin_only();       // OriginPolicy::OriginOnly
```

Use `.with_origin_policy(OriginPolicy::SameOriginOnly)` for the
no-`allow-same-site` middle option.

**HTTPS caveat:** browsers only emit `Sec-Fetch-Site` over HTTPS. An
app running plain HTTP can't use `origin_only()` - every state-changing
request will 403 because the header is missing.

`origin_only()` also disables the `XSRF-TOKEN` cookie automatically -
there's no token round-trip to feed, so shipping the cookie is dead
weight.

### 419 vs 403

| Status | What failed |
|---|---|
| **419** | Token check (Laravel's `TokenMismatchException`) - missing session token, missing request token, or wrong request token |
| **403** | Origin check under `OriginOnly` mode (Laravel's `OriginMismatchException`) |

Clients can tell the two failure modes apart by status alone. A 419
generally means "reload the page and retry"; a 403 from origin
verification means the request didn't come from a trusted origin and
retrying won't help.

## Helper functions

Three free functions read or render the current session's token. They
return empty / `None` when no session is active (the middleware will
reject the request before a handler runs in that case, so a missing
token outside a request scope is benign).

```rust
use suprnova::csrf::{csrf_token, csrf_meta_tag, csrf_field};

let token: Option<String> = csrf_token();
let meta: String = csrf_meta_tag();
// → <meta name="csrf-token" content="...">
let field: String = csrf_field();
// → <input type="hidden" name="_token" value="..." autocomplete="off">
```

The field carries `autocomplete="off"`, as Laravel's `csrf_field` does.
Without it, a browser can restore the token a page held before into the
field after a back navigation or a reload, and that token is stale once
the session rotates it.

The Inertia base view already calls `csrf_meta_tag()` for you - use
`csrf_field()` when rendering a traditional HTML form from a Tera /
Askama / minijinja template, and `csrf_token()` when you need the raw
value for something custom.

When a page must not render without a token, use the `try_*` siblings.
They return an error that names the missing session, where Laravel's
`csrf_token` throws `Application session store not set.`:

```rust
use suprnova::{FrameworkError, try_csrf_field, try_csrf_token};

fn signup_form() -> Result<String, FrameworkError> {
    let field = try_csrf_field()?;
    Ok(format!("<form method=\"post\">{field}<button>Sign up</button></form>"))
}

fn token_header() -> Result<(String, String), FrameworkError> {
    Ok(("X-CSRF-TOKEN".to_string(), try_csrf_token()?))
}
```

### Why Suprnova diverges

Laravel's `csrf_token()` throws outside a session. Suprnova's
`csrf_token()` returns `None` and `csrf_field()` the empty string there,
so a template rendered outside a request does not fail. `try_csrf_token()`
and `try_csrf_field()` give you Laravel's failure as a `Result`, because
public Suprnova functions return errors rather than panic.

## Constant-time comparison

Token comparison goes through `subtle::ConstantTimeEq`, a reviewed
constant-time equality primitive, rather than a hand-rolled XOR loop.
Suprnova tokens are fixed-length (40 lowercase alphanumeric
characters), so an unequal-length comparison short-circuits as a
structural reject - a length mismatch can only come from a malformed
or wrong-class token, not from an attacker probing for a same-length
timing oracle.

## Token regeneration

The session middleware regenerates the CSRF token on login and logout
to prevent session fixation. `regenerate_session_id()` issues a new token
too, as Laravel's `Session::regenerate` does, so a token read before the
regeneration is refused after it. If you need to force a new token outside
those flows (e.g. after a sensitive privilege change), call
`regenerate_csrf_token()`:

```rust
use suprnova::regenerate_csrf_token;

if let Some(new_token) = regenerate_csrf_token() {
    // Token rotated; the SPA's next request must echo this value.
}
```

Returns `None` if no session is active.

## Handling 419 on the client

When a session expires mid-session and the next state-changing request
fires, the server returns 419. The standard pattern is to reload the
page so the SPA picks up a fresh meta tag and cookie:

```ts
axios.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 419) {
      window.location.reload();
    }
    return Promise.reject(error);
  },
);
```

Inertia visits already follow redirects, so a controller that
`redirect`s after a session refresh (e.g. through a login flow) lands
the user back on the page with a working token.

## Testing

Tests drive the same `handle_request` pipeline production uses - see
[HTTP Tests](http-tests.md) for the full setup. The cleanest pattern
for a CSRF-guarded endpoint is to run the request through the same
two-hop dance a real SPA performs:

1. **`GET` something first** under the same TCP loopback listener.
   The session middleware mints a session cookie; `CsrfMiddleware`
   attaches the `XSRF-TOKEN` cookie on the way out.
2. **`POST` the actual route**, sending the session cookie back so
   the same session loads, and echoing the captured `XSRF-TOKEN`
   value in `X-XSRF-TOKEN`.

That's the production round-trip with no special test surface - the
middleware can't tell the test client apart from a browser. The
framework's own CSRF middleware tests exercise this end-to-end via
hyper loopback; the harness lives in
`framework/src/csrf/middleware.rs`'s `tests` module and is the
reference shape for higher-level integration tests.

## Security guarantees

- **Per-session tokens.** Each session has its own 40-character random
  token; logout rotates it.
- **CSPRNG-backed.** Tokens come from the same generator as session IDs
  (`rand::Rng::random_range` over an alphanumeric charset, seeded by
  the OS's CSPRNG).
- **Constant-time comparison.** `subtle::ConstantTimeEq` for the body
  of the comparison; structural length-mismatch shortcut for the
  unequal-length case.
- **Login / logout rotation.** Session regeneration generates a new
  token, defeating session fixation.
- **SameSite cookies.** Combined with the `XSRF-TOKEN` cookie's
  `SameSite=Lax` default for defence in depth.
- **419 not 500 on missing session.** A missing session is a
  client-side condition (no cookie / expired session), not a server
  misconfiguration - Laravel returns 419 in the same case, and so do we.

## Laravel parity matrix

| Laravel | Suprnova |
|---|---|
| `VerifyCsrfToken` / `PreventRequestForgery` middleware | `CsrfMiddleware` |
| `csrf_token()` helper | `suprnova::csrf::csrf_token()`; `try_csrf_token()` for the error outside a session |
| `csrf_field()` Blade helper, with `autocomplete="off"` | `suprnova::csrf::csrf_field()`, the same markup; `try_csrf_field()` for the error outside a session |
| `<meta name="csrf-token">` (Blade `@csrf` for forms) | `suprnova::csrf::csrf_meta_tag()` + auto-injected by Inertia base view |
| `$except = ['stripe/*']` | `.except(["stripe/*"])` |
| Glob `*` (mid / leading / trailing) | Same - full `Str::is` semantics |
| `XSRF-TOKEN` cookie + `X-XSRF-TOKEN` header round-trip | Same convention |
| `isReading`: `GET`, `HEAD`, `OPTIONS` pass unchecked | Same: every other method is checked, `QUERY` and extension methods included |
| `getTokenFromRequest`: `_token`, then `X-CSRF-TOKEN`, then `X-XSRF-TOKEN` | Same order, the first with a value decides |
| `_token` read from any input: query string, JSON, multipart, form | **Diverged:** a form-urlencoded or JSON body only |
| `Session::regenerate` regenerates the token | Same: `regenerate_session_id()` issues a new token |
| `XSRF-TOKEN` on every response, the session always saved | **Diverged:** a refused or failed response (4xx/5xx) to a request without a stored session gets no token and stores no session |
| `$addHttpCookie = false` | `.without_xsrf_cookie()` |
| `PreventRequestForgery::allowSameSite(true)` | `.allow_same_site()` |
| `PreventRequestForgery::useOriginOnly(true)` | `.origin_only()` |
| `TokenMismatchException` (419) | 419 `{"message": "CSRF token mismatch."}` |
| `OriginMismatchException` (403) | 403 `{"message": "Origin mismatch."}` |
| `EncryptCookies` encrypts `XSRF-TOKEN` | **Diverged:** plaintext (JS-readable; same wire shape for clients) |
| `config('session.*')` drives cookie attrs | `.with_session_config(&SessionConfig)` |

## Next

- [Sessions](session.md) - how `SessionMiddleware` populates the token
  the CSRF middleware compares
- [CORS](cors.md) - the other global middleware most apps install
  alongside CSRF
- [Middleware](middleware.md) - registration order, the global stack,
  writing your own
- [HTTP Tests](http-tests.md) - driving `handle_request` end-to-end,
  including CSRF-guarded routes
- [Authentication](authentication.md) - login / logout flows that
  rotate the session and its CSRF token


---

<!-- /docs/cors -->

# CORS

`CorsMiddleware` answers preflight `OPTIONS` requests and decorates
ordinary cross-origin responses with `Access-Control-Allow-*` headers.
You install it once in `bootstrap()` when a browser on a different
origin calls your API - public APIs, an SPA hosted on a different
domain, a mobile webview, or a separately-hosted docs site. Same-origin
apps (Inertia served from the same host as the backend, the Suprnova
default) don't need CORS at all. The middleware mirrors Laravel's
`HandleCors` and `config/cors.php`, but as a typed builder on
`CorsConfig`.

## Install it globally

```rust,ignore
use std::time::Duration;
use suprnova::{global_middleware, CorsConfig, CorsMiddleware};

pub fn register() {
    global_middleware!(CorsMiddleware::new(
        CorsConfig::allow_origins(["https://app.example"])
            .allow_credentials(true)
            .max_age(Duration::from_secs(600)),
    ));
}
```

A preflight is an `OPTIONS` request with an `Access-Control-Request-Method`
header. The router has no `OPTIONS` routes, so a preflight never *matches*
a route - but Suprnova's server runs the global middleware chain on
unmatched requests (terminating in a 404), so a globally-installed
`CorsMiddleware` sees the preflight and short-circuits it with `204`
before the 404 is ever produced. **This is why CORS must be installed
globally, not per-route.**

## Choosing an origin policy

There is intentionally no `Default` for `CorsConfig`. A reflexively
permissive policy is a security footgun, so you must pick:

| Builder | Behavior |
| --- | --- |
| `CorsConfig::allow_origins([...])` | Fixed allow-list. Origin is echoed back only when it exactly matches one entry. |
| `CorsConfig::any_origin()` | Wildcard `*`. With credentials enabled, the middleware echoes the specific request origin instead of `*` (the `*` + credentials combination is invalid per the Fetch spec). |
| `.allow_origin_patterns([...])` | Regex patterns added on top of the literal list. Useful for dynamic subdomains. |

```rust,ignore
CorsConfig::allow_origins(["https://app.example"])
    .allow_origin_patterns([r"^https://[a-z0-9-]+\.staging\.example$"])
```

Patterns are anchored automatically - each one is wrapped as
`^(?:pattern)$`, so it must match the whole origin. A partial match against
a redirect URL like `https://evil.com/?u=https://app.example` cannot leak
through, and every alternative of `https://app\.example|https://admin\.example`
is anchored on both sides, so `https://app.example.evil.test` is refused.

Invalid regex panics at config time (boot), not at request time - surface
the config bug loud rather than fail-open silently.

`allowed_origins_patterns` (Laravel-named alias) is also available.

## Scoping which paths get CORS

Laravel's `cors.php` config has a `paths` array (`['api/*',
'sanctum/csrf-cookie']`) that limits CORS application to specific URL
patterns. Suprnova mirrors this:

```rust,ignore
CorsConfig::allow_origins(["https://app.example"])
    .paths(["api/*", "sanctum/csrf-cookie"])
```

With no `paths` set, CORS runs on every request (Suprnova's default -
since the middleware is opt-in by registration). With at least one
pattern set, only matching requests get CORS treatment (both preflights
**and** actual-response decoration); everything else flows through
untouched.

Patterns use Laravel's `Str::is` semantics: `*` is a multi-segment
wildcard greedy across `/`. Leading `/` is normalized so `"api/*"` and
`"/api/*"` are equivalent.

```rust,ignore
"api/*"             // matches /api/users, /api/users/42
"api/*/posts"       // matches /api/v2/posts, /api/v1/posts
"sanctum/csrf-cookie" // exact-match literal
"*"                 // matches everything
```

## Skip via predicate

For request-shape predicates that don't fit a path pattern (skip based on
a header, only run CORS in production, skip during health checks), use
`skip_when`:

```rust,ignore
CorsConfig::any_origin()
    .skip_when(|req| req.header("X-Internal-Call").is_some())
    .skip_when(|req| req.path() == "/healthz")
```

Mirrors Laravel's `HandleCors::skipWhen(Closure)` but lives on the policy
rather than as global mutable state. Multiple `skip_when` callbacks can
be registered; any one returning `true` skips CORS.

## Methods, headers, exposed headers

```rust,ignore
CorsConfig::allow_origins(["https://app.example"])
    .methods(["GET", "POST", "DELETE"])           // default = GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD
    .allow_headers(["Content-Type", "X-CSRF-TOKEN"])  // restrict; default = reflect request
    .allow_any_headers()                          // explicit "reflect whatever was requested"
    .expose_headers(["X-Total-Count", "Link"])    // headers JS may read on the response
```

Laravel-named aliases (so `cors.php` users find what they expect):

- `allowed_methods(...)` ≡ `methods(...)`
- `allowed_headers(...)` ≡ `allow_headers(...)`
- `exposed_headers(...)` ≡ `expose_headers(...)`
- `allowed_origins_patterns(...)` ≡ `allow_origin_patterns(...)`
- `supports_credentials(...)` ≡ `allow_credentials(...)`

## Credentials and `*`

Per the Fetch spec, `Access-Control-Allow-Origin: *` is invalid together
with credentials - the browser rejects the response. With an explicit
origin list (`allow_origins([...])`) plus `allow_credentials(true)`,
the middleware echoes the specific request `Origin` rather than `*`,
and the policy works as expected.

**`any_origin() + allow_credentials(true)` panics at build time.** The
combination is a complete bypass of origin allowlisting: any attacker
page can make credentialed cross-origin requests and read responses.
Rather than emit the wrong header at runtime, the policy constructor
fails loud so the misconfiguration never reaches a running deployment.
Use an explicit allowlist instead:

```rust,ignore
// CORRECT - explicit allowlist with credentials.
CorsConfig::allow_origins(["https://app.example"]).allow_credentials(true)
// → on request with Origin: https://app.example
// → response: Access-Control-Allow-Origin: https://app.example
//             Access-Control-Allow-Credentials: true

// REJECTED at build time - panics with a remediation message.
// CorsConfig::any_origin().allow_credentials(true)
```

## Max-age

```rust,ignore
.max_age(Duration::from_secs(600))   // typed
.max_age_secs(600)                   // Laravel-style integer-seconds
```

`Access-Control-Max-Age` tells the browser how long it may cache the
preflight result. Higher = fewer preflight round-trips, slower policy
changes propagate.

## What the middleware actually emits

### Preflight (`OPTIONS` + `Access-Control-Request-Method`)

If the origin is allowed:

```
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Credentials: true        // when credentials enabled
Access-Control-Allow-Methods: GET, POST, ...
Access-Control-Allow-Headers: <reflected or fixed>
Access-Control-Max-Age: 600                   // when set
Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers
```

If the origin is disallowed: bare `204` + `Vary` (no `Access-Control-*`).
The browser's missing-header check produces the CORS error - matching
the `tower-http` convention.

### Actual cross-origin response

When the request has an `Origin` header and the origin is allowed:

```
Access-Control-Allow-Origin: <origin or *>
Access-Control-Allow-Credentials: true        // when enabled
Access-Control-Expose-Headers: X-Total, Link  // when configured
Vary: Origin                                  // only when not "*"
```

A `*` ACAO is identical for every origin, so no `Vary` is needed; a
specific origin varies per-origin so shared caches must key on it.

## Testing CORS handlers

CORS is browser-side enforced - the server still runs the handler even
when the origin is disallowed; it just doesn't decorate the response.
That's the testable behavior:

```rust,ignore
let (status, headers, body) = request_with_origin(
    "/api/data",
    "https://app.example",
).await;
assert_eq!(status, 200);
assert_eq!(
    headers.get("access-control-allow-origin"),
    Some(&"https://app.example".to_string()),
);
```

For a disallowed origin, the handler runs and the body comes back, but
the absence of `Access-Control-Allow-Origin` is what blocks the browser
from reading it.

## Laravel parity matrix

| Laravel `cors.php` | Suprnova builder |
| --- | --- |
| `paths` | `.paths([...])` |
| `allowed_methods` | `.methods([...])` / `.allowed_methods([...])` |
| `allowed_origins` | `CorsConfig::allow_origins([...])` |
| `allowed_origins_patterns` | `.allow_origin_patterns([...])` / `.allowed_origins_patterns([...])` |
| `allowed_headers` | `.allow_headers([...])` / `.allowed_headers([...])` |
| `exposed_headers` | `.expose_headers([...])` / `.exposed_headers([...])` |
| `max_age` | `.max_age(Duration)` / `.max_age_secs(u64)` |
| `supports_credentials` | `.allow_credentials(bool)` / `.supports_credentials(bool)` |
| `HandleCors::skipWhen(closure)` | `.skip_when(\|req\| ...)` |

The middleware is registered globally rather than the Laravel-style
"automatically installed for `paths`" - Suprnova's middleware chain is
explicit, see [Middleware](middleware.md) for the design.

### Why Suprnova diverges

Laravel's `HandleCors` is auto-attached to the kernel and reads its
policy from `config/cors.php`. The shape works for PHP because the
config array is the one place a request-per-process framework can
share configuration without re-evaluating it per request. Suprnova
exposes the same options as a typed `CorsConfig` builder you register
explicitly with `global_middleware!`, which keeps the middleware
chain visible in `bootstrap()` and lets the compiler enforce the
allowlist-vs-wildcard choice (no `Default` for `CorsConfig`, so you
can't accidentally ship `Access-Control-Allow-Origin: *` because you
forgot to fill in a config value).

The other divergence is that preflights reach the middleware even on
unrouted paths. Laravel routes `OPTIONS` through its router so the
preflight matches an `OPTIONS` route (auto-registered for each REST
route). Suprnova's router has no `OPTIONS` routes; instead the server
runs the global middleware chain on unmatched requests before
returning 404, so a globally-installed `CorsMiddleware` short-circuits
the preflight with `204` before the not-found path is taken. That's
why CORS *must* be installed globally - a per-route registration
would never see the preflight.

## Next

- [Middleware](middleware.md) - the trait, the chain, global vs
  per-route registration, terminable hooks
- [CSRF](csrf.md) - the other global middleware most apps install
  alongside CORS
- [Routing](routing.md) - how routes are matched (and why preflights
  don't match), plus the no-fallback path the global chain runs on
- [Request Lifecycle](lifecycle.md) - where CORS sits in the chain
  relative to session, CSRF, and the handler
- [Configuration](configuration.md) - typed config patterns for
  middleware that need environment-driven settings


---

<!-- /docs/security-headers -->

# Security Headers

`SecurityHeaders` adds browser security policy to responses through Suprnova's
own middleware chain. New projects in every kit, including API projects, register the balanced preset.
Existing applications opt in by registering the middleware; upgrading alone
does not change their responses.

## Register the middleware

Register it first in the HTTP bootstrap, before logging, `Inertia::install`,
error pages and RenderCache. The framework also sorts `SecurityHeaders` to the
outermost application position regardless of registration order or middleware priority.
Use typed registration: `global_middleware!`, `MiddlewareRegistry::append` or
`prepend`, or `Server::middleware`. Those APIs retain the type that ordering
and the server error boundary need; a manually erased middleware closure
does not retain that information. The built-in request-id scope stays outside
the application stack. Typed registration also retains a copy of the configured
policy beside the middleware's identity. The server reads that copy from its
own registry snapshot for health and catalogue responses and the WebSocket
response boundary. These paths need no application middleware execution and
keep the same configured policy across panic recovery.
Route and group security overrides run immediately inside it, before RenderCache
lookup. The response returns through security headers last, so cache hits and
error pages retain their policy.

```rust,ignore
use suprnova::{FrameworkError, SecurityHeaders, global_middleware};

pub fn try_register_http_stack() -> Result<(), FrameworkError> {
    global_middleware!(SecurityHeaders::from_env()?);
    // Register the remaining HTTP middleware here.
    Ok(())
}
```

The scaffold keeps a `register_http_stack()` wrapper for the application's
HTTP bootstrap hook. It calls `try_register_http_stack()` and fails at boot if
configuration is invalid. The fallible sibling also returns Inertia install errors. A server-substituted error page keeps the other
security headers and supplies its own CSP, which allows no script.

## Choose a preset

Use `SecurityHeaders::strict()`, `SecurityHeaders::balanced()` or
`SecurityHeaders::relaxed()` for programmatic configuration. `from_env()` reads
the variables below and defaults to balanced. `SecurityHeaders::off()` supplies
no headers.

| Header | Strict | Balanced | Relaxed |
|---|---|---|---|
| `Content-Security-Policy` | Strict policy below | Balanced policy below | Omitted |
| `Strict-Transport-Security` | `max-age=63072000; includeSubDomains` | `max-age=31536000` | `max-age=31536000` |
| `X-Frame-Options` | `DENY` | `SAMEORIGIN` | `SAMEORIGIN` |
| `X-Content-Type-Options` | `nosniff` | `nosniff` | `nosniff` |
| `Referrer-Policy` | `no-referrer` | `strict-origin-when-cross-origin` | `strict-origin-when-cross-origin` |
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=(), usb=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=(), display-capture=()` | Strict's list without `payment=()` | Omitted |
| `Cross-Origin-Opener-Policy` | `same-origin` | `same-origin-allow-popups` | Omitted |
| `Cross-Origin-Embedder-Policy` | `require-corp` | Omitted | Omitted |
| `Cross-Origin-Resource-Policy` | `same-origin` | `same-site` | Omitted |

Strict's CSP is:

```text
default-src 'self'; script-src 'nonce-N' 'strict-dynamic'; style-src 'self' 'nonce-N'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'
```

Balanced's CSP is:

```text
default-src 'self'; script-src 'self' 'nonce-N'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; font-src 'self' data: https:; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'
```

`N` represents the fresh request nonce. Balanced runs script files from the
application's own origin, such as the Live components' scripts under
`/suprnova-ui/`, and any script that carries the nonce. An inline script an
attacker injects carries no nonce and is blocked. Strict adds
`'strict-dynamic'` and drops `'self'`, so under strict every script tag needs
the nonce, the Live components' tags included. Balanced permits inline style
attributes because components and kits use them. Adding a nonce to `style-src`
would disable that permission. Strict requires authorized style elements and
does not permit inline style attributes.

In `APP_ENV=local` or `development`, the framework also permits the configured
Vite dev server in `script-src`, `style-src`, `font-src` and `img-src`, and
its origin and HMR websocket in `connect-src`. The stylesheet links come from
the dev server, and so do the fonts and images they point at. It reads the same configuration as the Inertia Vite integration,
so `suprnova serve` works with the balanced policy.

## Configure headers

The `header` builder changes or removes an individual header. Header names and
values are validated and errors return `FrameworkError`:

```rust,ignore
use suprnova::{FrameworkError, SecurityHeaders};

fn policy() -> Result<SecurityHeaders, FrameworkError> {
    SecurityHeaders::balanced()
        .header("referrer-policy", Some("same-origin"))?
        .header("cross-origin-opener-policy", None)
}
```

Use `.content_security_policy(Some(policy))` to set a typed
`ContentSecurityPolicy`, or `.content_security_policy(None)` to remove it.
`ContentSecurityPolicy::strict()` and `::balanced()` provide the built-in
policies; `ContentSecurityPolicy::new(template)?` validates a custom policy.
The `{nonce}` placeholder expands to the request nonce:

```rust,ignore
use suprnova::{ContentSecurityPolicy, FrameworkError, SecurityHeaders};

fn custom_policy() -> Result<SecurityHeaders, FrameworkError> {
    let csp = ContentSecurityPolicy::new(
        "default-src 'self'; script-src 'nonce-{nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'",
    )?;
    Ok(SecurityHeaders::balanced().content_security_policy(Some(csp)))
}
```

A header already set on the response wins. This preserves the policy on
Live's transport and upload responses and any policy a handler supplies.

### Add a source to the policy

To let the page reach another origin, add that origin to one directive of the
policy you already have, rather than writing a whole policy.
`.csp_source(directive, source)` adds one source and keeps the preset that
`SECURITY_HEADERS` selected, its report-only mode and its reporting origins:

```rust,ignore
use suprnova::{FrameworkError, SecurityHeaders};

fn policy() -> Result<SecurityHeaders, FrameworkError> {
    SecurityHeaders::from_env()?
        .csp_source("connect-src", "https://plausible.io")?
        .csp_source("img-src", "https://images.example.com")
}
```

With the balanced preset, the first call turns `connect-src 'self'` into
`connect-src 'self' https://plausible.io` and changes nothing else. The source
is added to the enforcing policy and to a report-only policy alike, so a
policy under test does not report the connection the enforcing one allows.
The relaxed and off presets send no policy, and the call leaves them as they
are.

A directive the policy leaves out starts from the sources it falls back to,
so adding one source narrows nothing. The strict preset has no `frame-src`,
so `.csp_source("frame-src", "https://www.youtube-nocookie.com")` writes
`frame-src 'self' https://www.youtube-nocookie.com`, the `default-src` sources
plus the new one. A directive with no fallback in the policy, such as
`form-action` in a policy without it, already allows every source and is
unchanged.

`ContentSecurityPolicy::with_source(directive, source)` does the same to one
policy value. Both return an error for a directive that takes no sources,
such as `sandbox`, and for a source that is not one expression: an empty
value, whitespace, a `;` or `,`, two sources in one call, `'none'`, or a nonce
other than `'nonce-{nonce}'`. They do not check the expression's grammar
beyond that. Call
`.csp_source` after `.content_security_policy(...)` or a `header(...)` call
that sets a policy, since those replace the policy and its added sources.

## Environment and reporting

| Variable | Default | Values |
|---|---|---|
| `SECURITY_HEADERS` | `balanced` | `strict`, `balanced`, `relaxed`, `off` |
| `SECURITY_HEADERS_CSP_REPORT_ONLY` | `false` | Boolean |
| `SECURITY_HEADERS_CSP_REPORT_TO` | Unset | A reporting endpoint URL |
| `SECURITY_HEADERS_HSTS_PRELOAD` | `false` | Boolean |

`SecurityHeaders::from_env()` returns an error naming a variable when its
value is invalid. See [Environment Variables](env-vars.md).

Report-only mode sends `Content-Security-Policy-Report-Only` in place of
`Content-Security-Policy`. It reports violations without enforcing that CSP.
Enable it while checking a policy against your application:

```env
SECURITY_HEADERS=balanced
SECURITY_HEADERS_CSP_REPORT_ONLY=true
SECURITY_HEADERS_CSP_REPORT_TO=https://reports.example.com/csp
SECURITY_HEADERS_HSTS_PRELOAD=false
```

A reporting URL adds a CSP `report-to` directive and a `Reporting-Endpoints`
header identifying its destination. Your application or reporting service
must accept the browser's violation reports. Programmatic equivalents are
`.report_only(true)` and `.report_to(Some("https://reports.example.com/csp"))?`.
Pass `None` to `report_to` to remove the destination.

The enforcing and report-only headers are independent policies. To keep an
enforcing policy while testing another, add the reporting policy by name:

```rust,ignore
let headers = suprnova::SecurityHeaders::strict().header(
    "Content-Security-Policy-Report-Only",
    Some("default-src 'self'; script-src 'nonce-{nonce}'; object-src 'none'"),
)?;
```

Both policies use the same request nonce. A nonce is generated when either
policy needs one, and each nonce policy is emitted only for HTML. Setting or
removing either header by name changes only that header. `.report_only(true)`
moves the preset's policy to report-only; `.report_only(false)` moves it back.
The typed `.content_security_policy(...)` builder updates the policy in that
selected mode.

## HSTS and HTTPS

`Strict-Transport-Security` is sent only when `Request::secure()` is true and
never in the local environment. Behind a TLS-terminating proxy, configure
`APP_TRUSTED_PROXIES` so the framework can trust its forwarded scheme. An
untrusted client's forwarded header cannot turn on HSTS.

The strict preset includes subdomains; balanced and relaxed do not. Preload is
opt-in through `SECURITY_HEADERS_HSTS_PRELOAD=true` or `.hsts_preload(true)`.
Choose it only when the domain and its subdomains meet the browser preload
requirements. Setting the token does not submit the domain to a preload list.

## Read and use the nonce

For a nonce policy, the middleware generates 128 random bits encoded as
unpadded base64url before it calls the handler. Each request gets a different
value. Read it through `request.csp_nonce()` or `CspNonce::current()`:

```rust,ignore
use suprnova::{CspNonce, Request};

fn request_nonce(request: &Request) -> Option<String> {
    request.csp_nonce().or_else(CspNonce::current)
}
```

Tokio does not inherit task-local values automatically. Capture the nonce scope
before spawning work that renders request assets:

```rust,ignore
let task = tokio::spawn(suprnova::CspNonce::propagate(async {
    suprnova::CspNonce::current()
}));
let nonce = task.await?;
```

The request task's context makes `CspNonce::current()` available to view and
head rendering code that holds no request. Without a nonce policy it returns
`None`. A JSON or other non-HTML response gets the other configured security
headers and no nonce-bearing CSP.

The framework stamps its executable scripts and script or style links:

- Inertia's default document and application root template `head` part include
  `<meta property="csp-nonce" nonce="...">`. Vite reads this element; each
  scaffold entry passes its nonce to `createInertiaApp` for injected styles.
- Vite's development preamble, scripts, modulepreload links and stylesheets
  carry it, including `Vite::tags` and `Vite::to_html` outside Inertia.
- `Head` stamps scripts and `preload`, `modulepreload` and `stylesheet` links.
  Preconnect, DNS-prefetch and prefetch hints need no nonce.
- Live's bootstrap uses it when the caller has not selected a nonce with
  `LiveBootstrapOptions::with_nonce`. Its scripts, modulepreload, preload and
  stylesheet links carry it.

Inertia page data and Live configuration use non-executing JSON elements and
need no nonce. Without a nonce policy, framework markup keeps its previous
bytes.

### Add an application script

An [Inertia root template](frontend-inertia-responses.md) receives `nonce` as
`Option<&str>`. Match it before writing a script. Askama escapes the attribute
value:

```html
{% if let Some(nonce) = nonce %}
<script nonce="{{ nonce }}" src="https://js.stripe.com/v3/"></script>
{% endif %}
```

The same shape authorizes an analytics tag or a script you host yourself. An
Askama view outside Inertia can receive `CspNonce::current()` as a field. Copy
the nonce only from the current request.

The nonce lets the script run. What the script then loads still meets the
rest of the policy, and the balanced policy's `default-src 'self'` blocks
another origin's frames, API calls and the scripts it loads itself. Stripe.js,
for example, also needs its own origin, its frames and its API. Add them to
the policy with `.csp_source`:

```rust,ignore
let headers = suprnova::SecurityHeaders::from_env()?
    .csp_source("script-src", "https://js.stripe.com")?
    .csp_source("connect-src", "https://api.stripe.com")?
    .csp_source("frame-src", "https://js.stripe.com")?
    .csp_source("frame-src", "https://hooks.stripe.com")?;
```

Balanced leaves `payment` out of `Permissions-Policy`, so Stripe's Apple Pay
and Google Pay buttons work, and sends `Cross-Origin-Opener-Policy:
same-origin-allow-popups`, so a popup sign-in or checkout window can report
back to the page. Strict turns both off.

To permit another origin's scripts without a nonce on each tag, add the origin
to `script-src`. Under strict this does not work: `'strict-dynamic'` makes
supporting browsers ignore origin allowlists, so give the tag the nonce
instead. For example:

```rust,ignore
let headers = suprnova::SecurityHeaders::balanced()
    .csp_source("script-src", "https://analytics.example.com")?;
```

A nonce authorizes a script to execute. It does not make its contents trusted.
Choose external scripts with the same care as application dependencies.

## Override a route or group

Attach `SecurityHeadersOverride` as ordinary route or group middleware. It
records changes for the outer global middleware to apply.

Building an override can fail, because `header` validates the name and value,
and `routes!` cannot return that error: it defines `pub fn register() ->
Router` from its list. Build the overrides in a function that returns a
`Result`, and register their routes on top of the router `register()` builds:

```rust,ignore
// src/routes.rs
use suprnova::{FrameworkError, Router, SecurityHeadersOverride, get, group, routes};

use crate::controllers;

// The routes that need no override.
routes! {
    get!("/", controllers::home::index),
}

/// Every route, with the two that carry an override.
pub fn try_register() -> Result<Router, FrameworkError> {
    let route_policy = SecurityHeadersOverride::new()
        .header("referrer-policy", Some("no-referrer"))?;
    let group_policy = SecurityHeadersOverride::new()
        .header("cross-origin-resource-policy", None)?;
    let router = get!("/report", controllers::reports::show)
        .middleware(route_policy)
        .register(register());
    Ok(group!("/shared", {
        get!("/image", controllers::images::show),
    })
    .middleware(group_policy)
    .register(router))
}
```

Then call `routes::try_register()` where `cmd/main.rs` calls
`routes::register()`. In a scaffolded project that is the routes hook, which
already returns a `Result`:

```rust,ignore
// cmd/main.rs
.try_routes_async(|| async {
    live::routes_with_render_cache(agents::serve(routes::try_register()?)?).await
})
```

An application without the Live routes passes the function itself to
`Application::try_routes(routes::try_register)`.

Use `.content_security_policy(None)` on the override to turn off the policy
in the global builder's selected mode for that route or group. Use the named
header API to control the enforcing and report-only policies independently:

```rust,ignore
let route_policy = suprnova::SecurityHeadersOverride::new()
    .header("Content-Security-Policy-Report-Only", None)?;
```

This removes only the report-only policy. An inherited enforcing CSP keeps its
nonce. Removing the enforcing header likewise leaves a report-only policy
and its nonce intact. A route override can change or turn off any middleware header;
a header the handler already set still wins. Review frame permissions together:
`X-Frame-Options` and CSP's `frame-ancestors` should describe the same access.

## WebMCP and Permissions-Policy

WebMCP, the browser API through which [agents](agents.md) call a page's
tools, is gated by the `tools` permission. The WebMCP specification makes
`tools` a policy-controlled feature whose default allowlist is `'self'`, and
`document.modelContext.registerTool()` rejects with `NotAllowedError` in a
document that may not use it. Chrome's origin trial follows the same rule.

No preset names `tools` in its `Permissions-Policy`, so the default applies
under every preset: the application's own pages, and frames of the same
origin, register tools. A frame from another origin does not, unless the page
that embeds it delegates the permission. Nothing needs to change for WebMCP
to work on your own pages.

To let one of your tool pages run inside an iframe on another site, two
things must hold:

1. The embedding page delegates the permission on its iframe:

   ```html
   <iframe src="https://app.example.com/orders" allow="tools"></iframe>
   ```

   If the embedding page sends a `Permissions-Policy` header that names
   `tools`, its allowlist must also include your origin, for example
   `tools=(self "https://app.example.com")`.

2. Your page lets that site frame it. Strict sends `X-Frame-Options: DENY`
   and `frame-ancestors 'none'`, and balanced sends `SAMEORIGIN` and
   `frame-ancestors 'self'`, so both refuse a frame from another origin. Add
   the embedding origin to `frame-ancestors` and drop `X-Frame-Options`, which
   cannot name another origin:

   ```rust,ignore
   use suprnova::{FrameworkError, SecurityHeaders};

   fn headers() -> Result<SecurityHeaders, FrameworkError> {
       SecurityHeaders::balanced()
           .csp_source("frame-ancestors", "https://portal.example.com")?
           .header("x-frame-options", None)
   }
   ```

   To open only some routes to framing, give them a `SecurityHeadersOverride`
   with their own policy instead, as [Override a route or
   group](#override-a-route-or-group) shows.

The framework's OAuth approval, connected-agents and claim pages always refuse
to be framed, whatever the preset.

To turn WebMCP off for the whole application, add `tools=()` to the preset's
list:

```rust,ignore
let headers = suprnova::SecurityHeaders::balanced().header(
    "permissions-policy",
    Some("camera=(), microphone=(), geolocation=(), usb=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=(), display-capture=(), tools=()"),
)?;
```

### The Origin Trial

Chrome runs WebMCP for real users as an origin trial from Chrome 149. Register
your origin for the trial and set `WEBMCP_ORIGIN_TRIAL_TOKEN` to the token it
issues. For several tokens, such as separate Chrome and Edge tokens, set a
comma-separated list. Every HTML response carries one header, with the tokens
joined by `, `:

```text
Origin-Trial: <chrome-token>, <edge-token>
```

The server adds the header as each response leaves, after all middleware, so
error pages, static `.html` files and plain views carry it, as Inertia and
Live pages do. JSON, redirects, assets and tool answers do not, because only a
document enables a trial. A response that already carries the same token keeps
it once. The header does not depend on `SecurityHeaders`: it is sent whether or
not the middleware is registered. A value that is not base64 stops boot,
naming the variable and the bad entry's position, never its value. Tokens are
trimmed and empty entries are skipped; an empty list sends nothing. The
[Origin Trials developer guide](https://github.com/GoogleChrome/OriginTrials/blob/gh-pages/developer-guide.md#15-can-i-provide-multiple-tokens-on-a-page)
allows comma-separated tokens in one header. A test registers a
token with `Config::register(WebMcpConfig::new().with_origin_trial_token(token)?)`.

## Cache nonce pages

A Complete page under a nonce CSP renders on every request. RenderCache never
stores that complete rendering, since replaying it would reuse a nonce. A
stitched Live document can be cached: each hit fills its nonce holes and
nonce-bearing headers with the current request's nonce, so body and CSP agree.
After a nonce policy is enabled, an entry published without it must render
again and replace the stored entry before replay. A stitched page with no
nonce-bearing content can then replay as Complete; it still records that it
was published under the nonce policy.
See [RenderCache](render-cache.md).

### Why Suprnova diverges

Laravel ships `FrameGuard` for `X-Frame-Options` and `Vite::useCspNonce` for asset
tags, but no CSP, HSTS or policy middleware. Applications use packages such as
`spatie/laravel-csp`. Suprnova includes `SecurityHeaders` so its own Inertia,
Live and RenderCache writers share one per-request nonce and its scaffolds
start with a browser policy.

The origin trusts a forwarded HTTPS scheme only from the proxies named in
`APP_TRUSTED_PROXIES`; `APP_TRUSTED_PROXIES` is empty by default, so a deployment
behind a TLS-terminating proxy must list it or HSTS is never sent.

## Next

- [Middleware](middleware.md) covers global order and route middleware.
- [Inertia Responses](frontend-inertia-responses.md) covers application root documents.
- [Environment Variables](env-vars.md) lists every configuration setting.
- [Agents](agents.md) covers the tools WebMCP registers.

## Public Inertia publication

Opt public pages into hash CSP explicitly with
`SecurityHeaders::balanced().hash_public_pages()`. Private responses keep their
fresh nonce policy. During a public render the framework emits no nonce
attributes and hashes only executable inline scripts in the trusted Inertia
document. JSON data scripts, external scripts, comments and inert template
content supply no hashes. Middleware that injects an inline script later cannot
add that script to the policy.

Mark a registered GET route with
`router.public_page::<AboutProps>("/about", "About")?`, or mark a prefix with
`public_page_group("/docs")` and declare each component with
`Inertia::public_page::<DocsProps>("/docs", "Docs")?`. The props type must derive
`InertiaProps` with `#[inertia(cacheable)]` and public fields. Per-request fields
refuse publication. A RenderCache policy alone does not mark a page public.

List named public shares with `Inertia::public_shared(&["app"])?`. Public renders
skip the session. Shared providers, `auth`, errors, flash and credential shares
refuse publication without being evaluated. An unlisted named share, a session read in the handler or a
nonce policy refuses that route with its path and cause. The listener keeps
serving even when a route refuses publication. The HTML and page JSON come from
the same resolved page, so publishing both does not run a lazy resolver twice.

Public hash mode removes nonces and `unsafe-inline` from `script-src`,
`script-src-elem` and `script-src-attr`. An empty attribute policy becomes
`script-src-attr 'none'`. Inline event handlers do not gain permission from the
hashes of inline script elements. A script inside SVG or MathML refuses
publication because foreign-content executable text follows different rules.


---

<!-- /docs/controllers -->

# Controllers

A Suprnova controller is just an async function. It takes whatever it
needs from the request - typed path parameters, a loaded model, a
validated form - and returns a `Response`. There is no controller base
class. There is no service-locator wiring file. The function is the
unit, and the `#[handler]` attribute glues it to the routing macros.

```rust
use suprnova::{handler, json_response, Response};
use crate::models::User;

// GET /users/{user}
#[handler]
pub async fn show(user: User) -> Response {
    json_response!({
        "id": user.id,
        "name": user.name,
        "email": user.email,
    })
}
```

That handler's signature does three things at once: declares the route
parameter (`user`), pulls the row out of the database, and 404s if the
row isn't there. None of it is written by hand. `#[handler]` reads the
argument types and generates the extraction.

## Generating a controller

```bash
suprnova make:controller User
```

This writes `src/controllers/user.rs` with a single `invoke` stub and
adds `pub mod user;` to `src/controllers/mod.rs`. The stub is the
minimum-viable handler:

```rust
//! User controller

use suprnova::{handler, json_response, Request, Response};

#[handler]
pub async fn invoke(_req: Request) -> Response {
    json_response!({
        "controller": "User"
    })
}
```

Add as many functions to the file as you want - Suprnova doesn't track
controller "classes", just functions. Many apps split by resource
(`controllers::user::{index, show, store, update, destroy}`), but
nothing in the framework enforces it.

The name is converted to `snake_case` for the filename: `OrderItem`
becomes `order_item.rs`.

## The `#[handler]` attribute

The macro generates the matching extractor for each parameter. Four
categories:

| Parameter type | Extracted via | Failure mode |
|---|---|---|
| `Request` | passes the request through unchanged | - |
| `i32`, `i64`, `u32`, `u64`, `usize`, `String` | `FromParam` - parses the route param of the same name | 400 on parse failure, 400 on missing |
| `T: RouteBinding` (every `#[suprnova::model]` struct) | binds the route param of the same name, matching the model's route key | 404 if the value does not parse or matches no row |
| Anything else (`T: FromRequest`) | calls `T::from_request(req)` - typically a `#[derive(FormRequest)]` validator | whatever `from_request` returns; 422 for validation errors |

The macro tells a path value and `Request` by their spelling. For any
other type the generated code chooses at compile time: a type that
implements `RouteBinding` binds, and any other reads the body. A generic
argument always reads the body.

The router binds every bound argument first, in path order, after the
route's middleware and before the handler, so a missing row is a 404
before the form is read. The other arguments are extracted in
declaration order. If any extraction fails, the error short-circuits via
`?` and the handler body never runs. A handler with `#[authorize]` changes
the order; see [Authorization](#authorization). One argument at most may
read the request body; the router refuses a handler with two at startup.

### Path parameters

```rust
// Route: get!("/users/{id}", controllers::user::show)
#[handler]
pub async fn show(id: i64) -> Response {
    json_response!({ "user_id": id })
}

// Route: get!("/posts/{post_id}/comments/{comment_id}", show_comment)
#[handler]
pub async fn show_comment(post_id: i64, comment_id: i64) -> Response {
    json_response!({
        "post_id": post_id,
        "comment_id": comment_id,
    })
}
```

The argument name must match the route placeholder: `{id}` requires
`id: …`. The argument type is parsed via `FromParam`. Bad input
(`/users/abc` against `id: i64`) returns 400 with a message naming
the parameter and target type.

### Route model binding

Every `#[suprnova::model]` struct implements `RouteBinding`. Declare the
model as an argument and the router loads it:

```rust
use suprnova::{handler, json_response, Response};
use crate::models::User;

// Route: get!("/users/{user}", controllers::user::show)
#[handler]
pub async fn show(user: User) -> Response {
    json_response!({
        "id": user.id,
        "name": user.name,
        "email": user.email,
    })
}
```

The route placeholder name (`{user}`) and the argument name (`user`)
must match; the router refuses a route whose handler reads a parameter
its path does not declare. The value is parsed as the model's route key
and looked up through `User::query()`, so global scopes and the
soft-delete filter apply. A value that does not parse or matches no row
answers 404. For binding fields, scoped children, custom resolution and
enums, see [Route model binding](routing.md#route-model-binding).

### Form requests

Anything that implements `FromRequest` plugs in the same way. The
common case is a `#[derive(FormRequest)]` struct that validates the
request body and surfaces a 422 with field-keyed errors on failure:

```rust
use suprnova::{attrs, handler, json_response, Response};
use crate::models::User;
use crate::requests::UpdateUserRequest;

// Route: put!("/users/{user}", controllers::user::update)
#[handler]
pub async fn update(user: User, form: UpdateUserRequest) -> Response {
    let id = user.id;
    user.update(attrs! { name: form.name, email: form.email }).await?;
    json_response!({ "updated": id })
}
```

See [Form Requests](requests.md) for the validator derive and the
full validation pipeline.

### When you want the raw `Request`

If you'd rather extract things by hand - or you need a header, a
cookie, a query string - take `Request` directly:

```rust
use suprnova::{handler, json_response, Request, Response};

#[handler]
pub async fn show(req: Request) -> Response {
    let id = req.param("id")?;             // route param, 400 on miss
    let ua = req.header("User-Agent");      // Option<&str>
    let page: u32 = req.query_param("page") // Option<String>
        .and_then(|s| s.parse().ok())
        .unwrap_or(1);

    json_response!({ "id": id, "ua": ua, "page": page })
}
```

You can mix and match: `pub async fn nested(category_id: i64, product: Product, req: Request)` is a valid signature. The macro extracts each argument by its own rule.

### Authorization

`#[authorize]` declares the gate check a handler needs. The check runs
after the route parameters are bound and before the request body is read,
so a denied request never reaches validation or the handler body:

```rust
use suprnova::{authorize, handler, json_response, Response};
use crate::models::Post;
use crate::requests::UpdatePostRequest;

// Route: put!("/posts/{post}", controllers::post::update)
#[handler]
#[authorize("update-post", post)]
pub async fn update(post: Post, form: UpdatePostRequest) -> Response {
    json_response!({ "updated": post.id, "title": form.title })
}
```

A guest gets 401, a denial 403, and a policy that denies as not found 404.
On a handler with `#[authorize]`, the route-bound arguments and the path
values come first, then the checks run, then the macro extracts the form
request or `Request`, whatever order the signature lists them in. For the type form,
several attributes on one handler, and the full rules, see
[Authorize a handler](authorization.md#authorize-a-handler).

### Handlers inside an `impl` block

To group a controller's handlers on a type, put them in an `impl` block and
name the type in the attribute, `#[handler(Self = Posts)]`:

```rust
use suprnova::{handler, json_response, Response};
use crate::models::Post;

pub struct Posts;

impl Posts {
    // Route: get!("/posts/{post}", controllers::Posts::show)
    #[handler(Self = Posts)]
    pub async fn show(post: Post) -> Response {
        json_response!({ "id": post.id, "title": post.title })
    }
}
```

The handler takes every argument a free handler takes, `#[authorize]`
included, and the router checks it at startup as it checks a free one. A
handler in an `impl` block has no `self` argument. Without `Self = Posts`,
the build fails and says to add it. If the attribute names another type
than the block's, the build fails too.

The attribute needs the type because `#[handler]` records each handler
for the router's startup checks, and that record is generated outside the
function, where `Self` does not name the block's type.

## The `Response` contract

`Response` is an alias for `Result<HttpResponse, HttpResponse>`. Both
arms carry the same payload type, which is why `?` works everywhere.
The middleware chain collapses the result with one line at the
boundary:

```rust
result.unwrap_or_else(|e| e)
```

This is the same contract every `?` propagation point relies on.
Errors get converted via `From<FrameworkError> for HttpResponse`
before they reach the chain - see [Error Model](error-model.md) for
the full picture.

The body of a handler reads top-to-bottom and uses `?` to bail:

```rust
use suprnova::{handler, json_response, Response};
use crate::models::User;

#[handler]
pub async fn show(id: i64) -> Response {
    let user = User::find_or_fail(id).await?;
    let invoices = user.invoices().get().await?;
    json_response!({ "user": user, "invoices": invoices })
}
```

If `find_or_fail` returns `Err`, the function exits with a 404. If
`invoices().get()` errors, you get a 500. No `match` statements, no
exception handlers.

## Creating responses

Three macros and a builder cover the common cases:

```rust
use suprnova::{handler, json_response, text_response, HttpResponse, Response, ResponseExt};

#[handler]
pub async fn json_handler() -> Response {
    json_response!({
        "users": [
            {"id": 1, "name": "John"},
            {"id": 2, "name": "Jane"},
        ]
    })
}

#[handler]
pub async fn health() -> Response {
    text_response!("OK")
}

#[handler]
pub async fn store() -> Response {
    // Built-in chainable status / headers via ResponseExt.
    json_response!({ "id": 1, "created": true }).status(201)
}

#[handler]
pub async fn page() -> Response {
    Ok(HttpResponse::html("<h1>Hello</h1>"))
}
```

`json_response!`, `text_response!`, and `HttpResponse::*` all produce
the same `Response` type. The `ResponseExt` trait adds `.status(...)`,
`.header(...)`, `.cookie(...)`, and `.with_headers(...)` so you can
chain configuration onto a macro result.

For everything else - file downloads, streaming bodies, Inertia
responses, redirects - see [Responses](responses.md).

## Redirects

`redirect!("route.name")` validates the route exists at compile time
and returns a builder you can chain configuration onto:

```rust
use suprnova::{handler, redirect, Response};

#[handler]
pub async fn store() -> Response {
    // Create the user…
    redirect!("users.index").into()
}

#[handler]
pub async fn update(id: i64) -> Response {
    redirect!("users.show")
        .with("id", id.to_string())
        .into()
}

#[handler]
pub async fn search() -> Response {
    redirect!("users.index")
        .query("page", "1")
        .query("sort", "name")
        .into()
}
```

`.with(key, value)` fills a route placeholder; `.query(key, value)`
appends a query string parameter; `.flash(key, value)` writes to the
session flash bag for the next request. `.into()` converts the
builder to a `Response`.

If the named route doesn't exist, the macro fails the compile with
a list of available route names - typos surface before staging.

## Container-injected services

Resolve services from the container with `App::resolve` (concrete
types) or `App::resolve_make` (trait objects). Both return
`Result<_, FrameworkError>` so they compose with `?`:

```rust
use suprnova::{handler, json_response, App, Response};
use crate::services::UserService;

#[handler]
pub async fn index() -> Response {
    let user_service = App::resolve::<UserService>()?;
    let users = user_service.list_all().await?;
    json_response!({ "users": users })
}
```

If you're binding actions with `#[injectable]`, this is how a
controller calls them. See [Actions](actions.md) for the action
shape, and [Service Container](container.md) for the full container
surface - binding, factories, the task-local / thread-local /
global lookup cascade.

## A worked RESTful controller

```rust
// src/controllers/user.rs
use suprnova::{attrs, handler, json_response, redirect, Response, ResponseExt};
use crate::models::User;
use crate::requests::{StoreUserRequest, UpdateUserRequest};

// GET /users
#[handler]
pub async fn index() -> Response {
    let users = User::all().await?;
    json_response!({ "users": users })
}

// GET /users/{user}
#[handler]
pub async fn show(user: User) -> Response {
    json_response!({ "user": user })
}

// POST /users
#[handler]
pub async fn store(form: StoreUserRequest) -> Response {
    let user = User::create(attrs! {
        name: form.name,
        email: form.email,
    }).await?;
    json_response!({ "user": user }).status(201)
}

// PUT /users/{user}
#[handler]
pub async fn update(user: User, form: UpdateUserRequest) -> Response {
    let id = user.id;
    user.update(attrs! {
        name: form.name,
        email: form.email,
    }).await?;
    json_response!({ "updated": id })
}

// DELETE /users/{user}
#[handler]
pub async fn destroy(user: User) -> Response {
    user.delete().await?;
    redirect!("users.index").into()
}
```

Register them with the `routes!` macro:

```rust
// src/routes.rs
use suprnova::{delete, get, post, put, routes};
use crate::controllers;

routes! {
    get!("/users",           controllers::user::index   ).name("users.index"),
    get!("/users/{user}",    controllers::user::show    ).name("users.show"),
    post!("/users",          controllers::user::store   ).name("users.store"),
    put!("/users/{user}",    controllers::user::update  ).name("users.update"),
    delete!("/users/{user}", controllers::user::destroy ).name("users.destroy"),
}
```

The route placeholder `{user}` matches the argument name `user: User`, which is how the framework knows which path segment loads the model.

## Controller middleware

A resource controller can declare the middleware its actions run, as
Laravel's `HasMiddleware` does. Each entry is a `ControllerMiddleware`:
a middleware value, or the name of an alias or group, scoped to some
actions with `only` or `except`.

For a module you register with `resource!`, declare a
`pub fn middleware()`:

```rust
// src/controllers/posts.rs
use suprnova::routing::{ControllerMiddleware, ResourceAction};
use crate::middleware::AuditMiddleware;

pub fn middleware() -> Vec<ControllerMiddleware> {
    vec![
        // Every action but index and show requires a signed-in user.
        ControllerMiddleware::named("auth")
            .except(&[ResourceAction::Index, ResourceAction::Show]),
        // An alias with arguments, on store only.
        ControllerMiddleware::named("throttle:10,1").only(&[ResourceAction::Store]),
        // A middleware value, on destroy only.
        ControllerMiddleware::new(AuditMiddleware).only(&[ResourceAction::Destroy]),
    ]
}

// index, create, store, show, edit, update and destroy follow, as
// #[handler] functions.
```

`resource!("posts", controllers::posts)` finds the function and runs each
middleware on the actions it is scoped to. A module without the function
runs none. For a `ResourceController`, override its `middleware` method:

```rust
use suprnova::routing::{ControllerMiddleware, ResourceAction, ResourceController};

impl ResourceController for PostsController {
    fn middleware(&self) -> Vec<ControllerMiddleware> {
        vec![ControllerMiddleware::named("auth").only(&[ResourceAction::Store])]
    }
    // the actions...
}
```

The scoping rules are Laravel's:

- An action runs the middleware when `only` lists it, or `only` was never
  called, and `except` does not list it. `only(&[])` therefore runs it on
  no action.
- `update` covers `PUT` and `PATCH` alike.
- The middleware runs after the middleware of the group around the
  resource and after the middleware you give the resource when you
  register it, as Laravel's `gatherMiddleware` appends the controller's
  middleware last. A name a group already gave the route runs once, in
  the group's place.

Suprnova resolves each name when the resource registers, which is at
boot. A name that no alias or group carries fails the registration:
`try_register` returns the error, and `register` panics. To scope
middleware to some actions at the registration site instead, see
[Resource routing](routing.md#controller-middleware).

## The `Request` API

The methods you'll reach for most often when taking `Request` directly:

| Method | Returns | Notes |
|---|---|---|
| `method()` | `&hyper::Method` | HTTP method |
| `path()` | `&str` | URL path |
| `param(name)` | `Result<&str, ParamError>` | route param; `?` to bail |
| `params()` | `&HashMap<String, String>` | all route params |
| `query()` | `Option<&str>` | raw query string |
| `query_param(key)` | `Option<String>` | single query string value |
| `query_params()` | `HashMap<String, String>` | all query params |
| `query_into::<T>()` | `Result<T, FrameworkError>` | typed deserialize |
| `header(name)` | `Option<&str>` | single header |
| `headers()` | `&hyper::HeaderMap` | full header map |
| `has_header(name)` | `bool` | presence check |
| `bearer_token()` | `Option<String>` | parsed `Authorization: Bearer …` |
| `cookie(name)` | `Option<String>` | single cookie value |
| `cookies()` | `HashMap<String, String>` | all cookies |
| `ip()` | `Option<String>` | client IP: the peer, or the client a trusted proxy names in `X-Forwarded-For` |
| `secure()` | `bool` | HTTPS detection (incl. proxies) |
| `is_method(m)` | `bool` | case-insensitive |
| `is_inertia()` | `bool` | Inertia XHR header |
| `ajax()` | `bool` | `X-Requested-With: XMLHttpRequest` |
| `expects_json()` / `wants_json()` | `bool` | Accept-header inspection |
| `route_name()` | `Option<String>` | matched route's `.name(...)` |
| `json::<T>()` | `Result<T, FrameworkError>` | parse body as JSON (consumes) |
| `form::<T>()` | `Result<T, FrameworkError>` | parse as form-urlencoded |
| `input::<T>()` | `Result<T, FrameworkError>` | content-type-dispatched parse |

This is a Laravel-shaped surface - every method here mirrors a method
on Laravel's `Request` class.

## File layout

Convention:

```
src/
├── controllers/
│   ├── mod.rs          # pub mod home; pub mod user; ...
│   ├── home.rs
│   ├── user.rs
│   └── api/
│       ├── mod.rs
│       └── user.rs
├── routes.rs           # routes! { ... }
└── main.rs
```

Nothing in the framework enforces this layout - controllers can live
anywhere reachable from `routes.rs`. The convention exists because
it's what scaffolding emits and because routes/controllers are the
natural pair.

## Why Suprnova diverges

Laravel controllers are classes that extend `Illuminate\Routing\Controller`.
Methods are called on instances the container resolves per-request,
which is where constructor-injection happens. The pattern is fine on
PHP - `new`-on-every-request is cheap when the entire process tears
down after the response.

In Rust, that pattern would mean either (a) allocating a controller
struct per request, which costs an `Arc` clone you don't need, or (b)
re-implementing dependency injection through a base class hierarchy
that doesn't pay for itself.

Suprnova picks the simpler model: a controller is a free async
function, and "dependencies" are either container resolutions
(`App::resolve::<Service>()?`) or extraction-typed arguments
(`form: UpdateUserRequest`). Constructor injection happens at the
`#[injectable]` boundary in [Actions](actions.md), where it belongs.
The handler stays a pure function from request to response, which
makes it trivial to test in isolation: build a `Request`, call the
function, assert on the result.

Controller middleware follows from that. Laravel reads
`HasMiddleware::middleware()` from the class of the route's action. A
Suprnova controller is a module, so a resource reads the module's
`pub fn middleware()`, or the `middleware` method of a
`ResourceController`. Only a resource reads it: a function you route by
itself with `get!` or inside `group!(..., controller = ...)` takes the
middleware its route and group give it. Suprnova also resolves every
named middleware at boot, where Laravel resolves it on the request, so a
misspelt name stops the server from starting instead of failing a
request.

## Next

- [Routing](routing.md) - what `routes!`, `get!`, `post!`, and `.name()` expand into
- [Form Requests](requests.md) - typed validation via `#[derive(FormRequest)]`
- [Responses](responses.md) - JSON, HTML, files, streams, Inertia pages, redirects
- [Service Container](container.md) - what `App::resolve` actually does
- [Actions](actions.md) - where business logic lives outside the controller
- [Error Model](error-model.md) - how `?` turns `FrameworkError` into a response


---

<!-- /docs/requests -->

# Requests

Suprnova handlers receive a `Request` - the wire-level HTTP request - or
a typed form-request struct that parses, validates, and authorizes the
body before your code runs. Both paths live on the same `#[handler]`
macro; you pick the shape per route. This chapter covers both, plus the
multipart upload extractor and the raw accessors you reach for in
middleware.

## Typed form requests

The `#[request]` attribute marks a struct as a `FormRequest`. The macro
adds `serde::Deserialize` and `validator::Validate` derives and emits an
`impl FormRequest` so the `#[handler]` macro knows to extract and
validate it on the way in:

```rust
use suprnova::request;

#[request]
pub struct CreateUserRequest {
    #[validate(email(message = "Please provide a valid email address"))]
    pub email: String,

    #[validate(length(min = 8, message = "Password must be at least 8 characters"))]
    pub password: String,

    #[validate(length(min = 1, max = 100, message = "Name is required"))]
    pub name: String,
}
```

A handler that names this type as its parameter is handed an
already-validated value:

```rust
use suprnova::{handler, json_response, Response};
use crate::requests::CreateUserRequest;

#[handler]
pub async fn store(form: CreateUserRequest) -> Response {
    // `form` is validated - this code only runs if every rule passed.
    json_response!({ "email": form.email, "name": form.name })
}
```

A handler that names `Request` instead gets the raw request through
unchanged:

```rust
use suprnova::{handler, json_response, Request, Response};

#[handler]
pub async fn index(req: Request) -> Response {
    json_response!({ "path": req.path() })
}
```

Both are extractors - the `#[handler]` macro looks up
`FromRequest::from_request` for every parameter type, and any struct
that implements `FormRequest` gets a blanket `FromRequest` impl for
free.

## Validation rules

Validation runs through the `validator` crate. Common rules:

### String validations

```rust
#[request]
pub struct ExampleRequest {
    // Required (non-empty)
    #[validate(length(min = 1, message = "This field is required"))]
    pub name: String,

    // Email format
    #[validate(email(message = "Invalid email address"))]
    pub email: String,

    // URL format
    #[validate(url(message = "Invalid URL"))]
    pub website: String,

    // Length constraints
    #[validate(length(min = 8, max = 100))]
    pub password: String,

    // Regex pattern - PHONE_REGEX must be a `static` or `const`
    // visible from the validator's expansion point. Declare it once,
    // typically in the same module:
    #[validate(regex(path = "PHONE_REGEX", message = "Invalid phone number"))]
    pub phone: String,
}

use std::sync::LazyLock;
use regex::Regex;

// validator 0.20 implements `AsRegex` for `std::sync::LazyLock<Regex>`
// but not for `once_cell::sync::Lazy<Regex>` - use the std type so the
// derive's `#[validate(regex(path = "..."))]` expansion typechecks.
static PHONE_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"^\+?[0-9\s\-()]{7,20}$").unwrap());
```

### Numeric validations

```rust
#[request]
pub struct ProductRequest {
    // Range validation - literals must match the field type. `f64`
    // takes `0.0` / `10000.0`, not the integer-literal `0` / `10000`.
    #[validate(range(min = 0.0, max = 10000.0, message = "Price must be between 0 and 10000"))]
    pub price: f64,

    // Minimum value
    #[validate(range(min = 1))]
    pub quantity: i32,

    // Maximum value
    #[validate(range(max = 100))]
    pub discount_percent: i32,
}
```

### Nested and collection validations

```rust
use serde::Deserialize;

#[derive(Deserialize, Validate)]
pub struct Address {
    #[validate(length(min = 1))]
    pub street: String,

    #[validate(length(min = 1))]
    pub city: String,
}

#[request]
pub struct OrderRequest {
    // Nested struct validation
    #[validate(nested)]
    pub shipping_address: Address,

    // Collection length
    #[validate(length(min = 1, message = "At least one item required"))]
    pub items: Vec<String>,
}
```

### Common validation attributes

| Attribute | Description | Example |
|-----------|-------------|---------|
| `email` | Valid email format | `#[validate(email)]` |
| `url` | Valid URL format | `#[validate(url)]` |
| `length` | String/collection length | `#[validate(length(min = 1, max = 100))]` |
| `range` | Numeric range | `#[validate(range(min = 0, max = 100))]` |
| `regex` | Regex pattern match | `#[validate(regex(path = "PATTERN"))]` |
| `contains` | String contains substring | `#[validate(contains(pattern = "@"))]` |
| `does_not_contain` | String doesn't contain | `#[validate(does_not_contain(pattern = "admin"))]` |
| `nested` | Validate nested struct | `#[validate(nested)]` |

## Validation error responses

When validation fails, Suprnova returns a 422 response with the
Laravel / Inertia-compatible error bag:

```json
HTTP 422 Unprocessable Entity

{
    "message": "Please provide a valid email address (and 1 more error)",
    "errors": {
        "email": ["Please provide a valid email address"],
        "password": ["Password must be at least 8 characters"]
    }
}
```

The `errors` shape matches what `@inertiajs/*` clients read from
`usePage().props.errors` directly.
The `message` summarises the first error and the count of the rest.
See [Precognition](precognition.md) for the same body during live validation.

### Nested fields

A `#[validate(nested)]` failure is reported under a dotted key naming the
full path, the same notation Laravel uses. A nested struct contributes
`parent.field`; an element of a validated `Vec<T>` contributes
`parent.<index>.field`:

```json
{
    "message": "Validation failed for field 'shipping_address.street' (and 1 more error)",
    "errors": {
        "shipping_address.street": ["Validation failed for field 'shipping_address.street'"],
        "items.1.name": ["Validation failed for field 'items.1.name'"]
    }
}
```

Index `1` is the second element - the first element passed and is absent
from the bag. Bind the key straight through on the client:
`form.errors['items.1.name']`. A form body or a multipart body sends the
same fields under bracketed names, `shipping_address[street]` and
`items[1][name]`, which read into the same structs and fail under the same
dotted keys; see [nested names and lists](#nested-names-and-lists).

### Renamed fields

The error keys are the names the client sent. When serde renames a field
(`#[serde(rename_all = "camelCase")]` on the struct, or `rename` on a
field), a failure on `unit_price` is reported as `unitPrice`. The same names
drive `Precognition-Validate-Only`, where a Rust name matches nothing, and a
localized message reads the name snake-cased, "unit price", as Laravel's
does. A hook names fields by their Rust names, as `validate!` does, and its
errors are keyed by the input names too.

A nested object is renamed at its own level when its type registers its
names. A form request does. A plain struct nested in one derives
`suprnova::InputNames` for it:

```rust
#[derive(Deserialize, Validate, suprnova::InputNames)]
#[serde(rename_all = "camelCase")]
pub struct LineItem {
    #[validate(range(min = 1))]
    pub unit_price: i64,
}
```

An error on the second item's price is then keyed `lineItems.1.unitPrice`.
Without the derive the nested part keeps the Rust name,
`lineItems.1.unit_price`. A generic nested type, and a field serde
`flatten`s, keep Rust names too, as do the serde attributes the derives do
not read (`from`, `try_from`, `transparent`).

## Complete example

A user registration endpoint, end to end.

**Define the request:**

```rust
// src/requests/create_user.rs
use suprnova::request;

#[request]
pub struct CreateUserRequest {
    #[validate(email(message = "Please provide a valid email address"))]
    pub email: String,

    #[validate(length(min = 8, message = "Password must be at least 8 characters"))]
    pub password: String,

    #[validate(length(min = 2, max = 50, message = "Name must be between 2 and 50 characters"))]
    pub name: String,
}
```

**Create the controller:**

```rust
// src/controllers/user.rs
use suprnova::{handler, json_response, Request, Response, ResponseExt};
use crate::requests::CreateUserRequest;

#[handler]
pub async fn index(_req: Request) -> Response {
    json_response!({ "users": [] })
}

#[handler]
pub async fn store(form: CreateUserRequest) -> Response {
    // Validation passed - create the user
    // In a real app, you'd save to database here

    json_response!({
        "user": {
            "email": form.email,
            "name": form.name
        },
        "message": "User created successfully"
    })
    .status(201)
}
```

**Register the routes:**

```rust
// src/routes.rs
use suprnova::{get, post, routes};
use crate::controllers;

routes! {
    get!("/users", controllers::user::index).name("users.index"),
    post!("/users", controllers::user::store).name("users.store"),
}
```

## Authorization and cross-field hooks

You use four lifecycle hooks on `FormRequest`: `prepare_for_validation`,
`authorize`, `after_validation`, and `after_validation_async`. Both the `#[request]`
attribute and the `#[derive(FormRequestDerive)]` form emit a default
`impl FormRequest` for you. To override any hook, add the
`#[form_request(custom_hooks)]` opt-out to suppress the default impl,
then write your own. (This mirrors the `#[multipart(custom_hooks)]`
pattern.)

```rust
use suprnova::{FormRequest, FormRequestDerive, Request};
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate, FormRequestDerive)]
#[form_request(custom_hooks)]
pub struct DeleteUserRequest {
    pub user_id: i64,
}

impl FormRequest for DeleteUserRequest {
    fn authorize(req: &Request) -> bool {
        // Return false to short-circuit with 403 Forbidden before the
        // body is read.
        req.header("X-Admin-Token").is_some()
    }
}
```

The opt-out also works under the `#[request]` attribute form - useful
when you want the attribute's auto-derives but need to override hooks:

```rust
use suprnova::{FormRequest, Request, request};

#[request]
#[form_request(custom_hooks)]
pub struct DeleteUserRequestAttr {
    pub user_id: i64,
}

impl FormRequest for DeleteUserRequestAttr {
    fn authorize(req: &Request) -> bool {
        req.header("X-Admin-Token").is_some()
    }
}
```

When `authorize` returns `false`, extraction returns
`FrameworkError::Unauthorized` and renders:

```json
HTTP 403 Forbidden

{ "message": "This action is unauthorized." }
```

`after_validation` is the synchronous cross-field hook - use it for
rules like "password and confirmation must match". `after_validation_async`
is the asynchronous counterpart and is where database-backed rules
(e.g. the built-in `Unique`) participate in automatic validation. Both
run after the derived rules on a real request, even when those rules report
errors. You get one merged error bag from the rules and both hooks. An
empty error bag counts as success. For marked Precognition requests, you
keep the stage rules described in [Precognition](precognition.md).

You prepare input before authorization with `prepare_for_validation`:

```rust,ignore
fn prepare_for_validation(req: &mut Request) -> Result<(), suprnova::FrameworkError> {
    req.transform_input("email", |text| text.to_ascii_lowercase());
    Ok(())
}
```

You register a transformation without reading the body. The parser applies
it after authorization, before validation. Your JSON names use dotted
paths; your form and multipart names use the submitted field name. You
return an error to stop preparation before authorization or a body read.

For a classic form whose `Accept` prefers `text/html` without `X-Inertia`,
you get a `302` redirect back with `errors.default` and old input flashed
to the session. You read old text with `session.get_old_input(key)` on the
next request. You keep `422` errors for JSON and the Inertia middleware's
`303` redirect for Inertia visits.

```rust
use suprnova::{FormRequest, FormRequestDerive, ValidationErrors};
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate, FormRequestDerive)]
#[form_request(custom_hooks)]
pub struct UpdatePasswordRequest {
    #[validate(length(min = 8))]
    pub new_password: String,
    pub confirmation: String,
}

impl FormRequest for UpdatePasswordRequest {
    fn after_validation(&self) -> Result<(), ValidationErrors> {
        if self.new_password != self.confirmation {
            let mut errs = ValidationErrors::new();
            errs.add("confirmation", "passwords do not match");
            return Err(errs);
        }
        Ok(())
    }
}
```

### Body size caps

The per-struct `#[form_request(max_body_bytes = N)]` attribute
overrides the process-global 8 MiB cap on a single FormRequest:

```rust
use suprnova::FormRequestDerive;
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate, FormRequestDerive)]
#[form_request(max_body_bytes = 64 * 1024 * 1024)] // 64 MiB
pub struct ImportPayload {
    pub rows: Vec<Row>,
}

#[derive(Deserialize, Validate)]
pub struct Row { /* ... */ }
```

`Content-Length` is parsed up front and the request is rejected with
HTTP 413 *before* a body byte is read when the declared size exceeds
the cap; clients that lie about `Content-Length` still trip the
streaming byte counter during read.

### Body read deadlines

The server bounds how long a request body takes to arrive, as it bounds
how long the request head takes. Every read of the body follows two
deadlines: `body_bytes`, `json`, `form`, `input`, the form request and
multipart extractors, the multipart parsers, the middleware that read a
body before the handler, such as CSRF, and a handler that reads the raw
stream itself.

- The per-frame deadline, `SERVER_BODY_READ_TIMEOUT` (default 30 seconds),
  is the longest the server waits for the next piece of the body.
- The total deadline, `SERVER_BODY_TOTAL_TIMEOUT` (default 3600 seconds,
  one hour), is the longest the whole body may take, counted from when the
  server read the request head. It is a backstop that ends a body that
  keeps arriving a byte at a time inside every per-frame wait, and is long
  enough for a large upload over a slow link.

A body that misses either deadline is abandoned: the read fails with an
HTTP `408 Request Timeout` error, which the request answers like any other
error, and the server closes the connection after the response. A `408`
response always carries `Connection: close`. Zero or a value that doesn't
parse falls back to the default, so neither deadline can be turned off.

The deadlines bind the body, not the method that reads it. A handler that
takes the body with `Request::into_parts` gets a
`BodyState::Streaming(TimedBody)`, and each frame it awaits waits under the
same deadlines and fails with the same `408` when it misses one. The
error of a `TimedBody` frame is a `FrameworkError`, so `?` returns it.
`http_body_util::BodyExt` reads the frames:

```rust
use http_body_util::BodyExt;
use suprnova::http::BodyState;
use suprnova::{handler, FrameworkError, HttpResponse, Request, Response};

#[handler]
pub async fn count_bytes(req: Request) -> Response {
    let (_, body) = req.into_parts();
    let BodyState::Streaming(mut body) = body else {
        return Err(FrameworkError::internal("the body was already read").into());
    };
    let mut read = 0;
    while let Some(frame) = body.frame().await {
        // A frame that misses a deadline is the `408`.
        let frame = frame?;
        read += frame.data_ref().map_or(0, |data| data.len());
    }
    Ok(HttpResponse::text(read.to_string()))
}
```

A body nobody reads is abandoned too. If a handler keeps the request and
never reads the body, the server closes the connection at the total
deadline, without a response. A handler that does other work before it
reads the body must finish reading it within the total deadline, or the
connection closes the same way.

A streamed upload stays within the per-frame deadline as long as the
client keeps sending; a client that sends nothing for 30 seconds is cut
off. To accept uploads from clients that pause longer, or uploads that
take more than an hour, raise the deadlines in the environment:

```bash
SERVER_BODY_READ_TIMEOUT=60
SERVER_BODY_TOTAL_TIMEOUT=7200
```

Or set them on the server configuration, which is how a test sets short
ones:

```rust
use std::time::Duration;
use suprnova::{Config, ServerConfig};

Config::register(
    ServerConfig::builder()
        .body_read_timeout(Duration::from_secs(60))
        .body_total_timeout(Duration::from_secs(7200))
        .build(),
);
```

A global [`TimeoutMiddleware`](timeout.md) also bounds a body read inside
the middleware chain, since the read is part of the handler's work. For a
route that takes long uploads, raise that timeout as well as the body
deadlines.

## Content type detection

`FormRequest::extract` looks only at the `Content-Type` header:

- `application/x-www-form-urlencoded` → parsed as a form, as described in
  [empty values, repeated names, and fields that don't parse](#empty-values-repeated-names-and-fields-that-dont-parse)
- `multipart/form-data` → the parts parsed as a form by the same rules, each
  file part filling an `UploadedFile` field, as described in
  [files in a form request](#files-in-a-form-request)
- `application/json` or any `application/*+json` suffix → parsed via `serde_json`
- Anything else (including a missing header) → rejected with HTTP 415
  Unsupported Media Type, before the body is read

For an upload that checks each file while the body streams in, see
[file uploads](#file-uploads-multipartrequest) below.

## Empty values, repeated names, and fields that don't parse

A form can't send `null`. An HTML form sends an empty input as `name=`, and
Inertia sends a `null` value as an empty field when it posts `FormData`.
Laravel's default `ConvertEmptyStringsToNull` middleware reads the empty
value as `null`. A form-urlencoded `FormRequest` and a `MultipartRequest`
read it the same way:

- An `Option` field is `None`, an `Option<String>` included.
- A required field is missing, a `String` included, so the request fails
  with a `422`.
- A list keeps the `null` in its place. An element of a `Vec<Option<T>>` is
  `None`. An element of a `Vec<T>`, which has no place for `null`, is
  missing, and is reported under its index, such as `ids.1`.

The name itself stays, holding `null`, so a cleared field is told apart from
one never sent. Read into a `serde_json::Value` or a map, `name=Ada&bio=`
gives `{"name": "Ada", "bio": null}`, and a `#[serde(flatten)]` map sees
`bio` too. A `#[serde(default)]` field that arrives empty is `null`, not its
default: the default is for a field the form left out.

A `bool` field reads what forms send, in a url-encoded body, a query
string and a multipart body alike: `1` and `0`, as Inertia sends them,
`true` and `false`, and `on` and `off`, as an HTML checkbox sends them, the
words in any case.

A name sent more than once keeps its last value, as PHP does. The body
`title=&title=Holiday` gives `Holiday`, and `title=Holiday&title=` gives
`null`. A name with brackets is nested data, as the next section describes:
`tags[]=rust&tags[]=web` fills a `tags: Vec<String>` field. `req.form()`,
the form-urlencoded branch of `req.input()`, and `req.query_into()` read by
the same rules.

A field that is missing, or whose value doesn't parse as its type, answers
the way a failing rule does: a `422` whose `errors` names every such field
under its input name, with the catalog message for its type. An Inertia
form gets the usual redirect back with those errors in `props.errors`. A
JSON body reads the same way, nested fields included, and a JSON `null`
where a value is required counts as missing.

| Failure | Catalog key |
|---|---|
| A required field missing, empty, or JSON `null` | `validation-required` |
| A value that isn't an integer, a number, or a `bool` for such a field | `validation-integer`, `validation-numeric`, `validation-boolean` |
| A JSON value that isn't a string for a `String` field, or a list where one value belongs | `validation-string` |
| Any other value that doesn't fit, such as an unknown enum variant | `validation-format` |

`title=&count=abc` posted to a struct with `title: String` and `count: u32`
answers with both:

```json
{
    "message": "The title field is required. (and 1 more error)",
    "errors": {
        "title": ["The title field is required."],
        "count": ["The count field must be an integer."]
    }
}
```

A body that isn't JSON at all, or a field a struct denies with
`#[serde(deny_unknown_fields)]`, is no field's failure: it answers `422`
with a message that words it.

```rust
use suprnova::{handler, json_response, request, Response};

#[request]
pub struct UpdateProfile {
    pub name: String,
    pub bio: Option<String>,
}

#[handler]
pub async fn update(form: UpdateProfile) -> Response {
    // `name=Ada&bio=` arrives with `bio` as `None`, and `name=&bio=Hi`
    // fails with a `422` before this code runs.
    json_response!({ "name": form.name, "has_bio": form.bio.is_some() })
}
```

### Why Suprnova diverges

- A JSON body keeps `""` as an empty string. JSON has its own `null`, and
  Inertia sends a `null` value as one, so an empty string in JSON is text
  the client chose. To require text there, validate `length(min = 1)`.
  Laravel converts a JSON `""` to `null` too.
- Text isn't trimmed. Laravel's `TrimStrings` middleware runs before
  `ConvertEmptyStringsToNull`, so a value of spaces is `null` in Laravel and
  text in Suprnova.
- A JSON body reads a `bool` as JSON `true` or `false` only. Laravel's
  `boolean` rule also takes `1`, `0`, `"1"` and `"0"` there. A JSON client
  sends a JSON boolean, which a `bool` field reads as it is.
- A `MultipartRequest` field that holds one file takes the first file part
  of its name, where PHP keeps the last. The extractor checks a file while
  the body streams, before it knows whether a later part of the same name
  follows, so it decides on the first one.
- On a real request, the `#[validate(...)]` rules run only once every
  field parses, so a request with a field that doesn't parse hears about
  the parse failures alone. Laravel checks every rule at once. A struct can't be built while a
  field has no value of its type, and the rules run on the struct.
- A JSON object nested in the body, or a nested object in a form
  (`shipping_address[street]`), reports its first missing field, and a
  field after that object is checked once the object reads. Missing fields
  at the top of the body are all reported at once.
- [Precognition](precognition.md) parses and validates only the listed
  fields, through every validation stage. An unlisted field that does not
  parse does not block the listed fields' answer. The typed struct is
  built only for the real request.

## Nested names and lists

A form sends nested data under names with brackets, and Laravel reads them
as nested arrays. The Inertia client writes such names when it puts a `GET`
visit's data in the query string and when it sends a form that holds a file
as `multipart/form-data`, and an HTML form can name its inputs the same way.
A form request, `req.input()`, `req.form()` and `req.query_into()` read them
as PHP's `parse_str` does, in a url-encoded body, a multipart body and a
query string alike:

- `user[name]=Ada` is the member `name` of `user`. It fills a nested struct
  field, and a `serde_json::Value` reads it as `{"user": {"name": "Ada"}}`.
- `tags[]=a&tags[]=b` is a list, in the order sent.
- `photos[1]=b&photos[0]=a` is a list in index order, `["a", "b"]`. A gap
  leaves no hole: `ids[5]=x&ids[1]=y` gives `["y", "x"]`.
- A key that isn't an integer makes an object, so `filters[status]=x` and
  `filters[sort]=name` fill a `filters` struct.
- Names nest to any depth up to 64 levels: `items[0][name]` is the `name` of
  the first item. A name nested deeper is dropped, with what was read under
  its first part, as PHP drops it.
- An empty value is `null` at every depth, as at the top.

The `OrderRequest` above reads this body, and a filter page reads its query
the same way:

```text
shipping_address[street]=1+Main+St&shipping_address[city]=Springfield&items[]=a&items[]=b
```

```rust
use serde::Deserialize;
use suprnova::{handler, json_response, Request, Response};

#[derive(Deserialize)]
struct Filters {
    status: Option<String>,
    sort: Option<String>,
}

#[derive(Deserialize)]
struct Listing {
    filters: Option<Filters>,
    #[serde(default)]
    tags: Vec<String>,
}

#[handler]
pub async fn index(req: Request) -> Response {
    // GET /items?filters[status]=open&tags[]=rust&tags[]=web
    let listing: Listing = req.query_into()?;
    let status = listing.filters.and_then(|filters| filters.status);
    json_response!({ "status": status, "tags": listing.tags })
}
```

A field that fails is named by its path with dots, as Laravel names it:
`items[3]=x` read into `items: Vec<u32>` fails as `items.3`, and a missing
`shipping_address[city]` as `shipping_address.city`. The client binds these
keys as they are: `form.errors['items.3']`.

`req.query_params()` and `req.query_param(...)` read the query's pairs as
sent, so a bracketed name is one key there: `req.query_param("filters[status]")`.

## Reading the body directly

For one-off endpoints or middleware that doesn't want a full
`FormRequest`, the `Request` type itself reads the body in three flavors -
each consumes `self` because the body can be read at most once:

```rust
use serde::Deserialize;
use suprnova::{handler, json_response, Request, Response};

#[derive(Deserialize)]
struct LoginForm { username: String, password: String }

#[handler]
pub async fn login(req: Request) -> Response {
    // Pick the parser explicitly.
    let form: LoginForm = req.form().await?;
    json_response!({ "user": form.username })
}

#[handler]
pub async fn webhook(req: Request) -> Response {
    // Same shape, JSON wire.
    let payload: serde_json::Value = req.json().await?;
    json_response!({ "received": payload })
}

#[handler]
pub async fn ingest(req: Request) -> Response {
    // Auto-pick based on Content-Type - JSON unless
    // `application/x-www-form-urlencoded` is explicit.
    let value: serde_json::Value = req.input().await?;
    json_response!({ "value": value })
}
```

For raw access, `req.body_bytes().await` returns the buffered `Bytes`
plus the `RequestParts` metadata (route params and content type). Use
`body_bytes_with_cap(n)` to override the global 8 MiB cap on a
case-by-case basis.

## Resolving services alongside the form

Validated form requests compose with the [service container](container.md).
Use `App::resolve::<T>()` (or `App::get::<T>()`) inside the handler:

```rust
use suprnova::{handler, json_response, Response, App};
use crate::requests::CreateUserRequest;
use crate::services::UserService;

#[handler]
pub async fn store(form: CreateUserRequest) -> Response {
    let user_service = App::resolve::<UserService>()?;
    let user = user_service.create_user(&form.email, &form.name).await?;
    json_response!({ "user": user })
}
```

## Files in a form request

The Inertia client sends a form that holds a file as `multipart/form-data`:
a list of files under `photos[0]`, `photos[1]` (or `photos[]` when the
application asks for brackets), and nested fields under names such as
`user[name]`. A form request reads that body. Text parts read as a
url-encoded body reads, and a part with a file name fills an
`UploadedFile<V>` field, where `V` is a validator, or a tuple of them, from
`suprnova::http::upload::validators`:

```rust
use suprnova::http::upload::UploadedFile;
use suprnova::http::upload::validators::{ImageFile, MaxSize};
use suprnova::{handler, json_response, request, Response};

#[request]
pub struct StoreAlbum {
    #[validate(length(min = 1))]
    pub title: String,
    pub photos: Vec<UploadedFile<(ImageFile, MaxSize<5_242_880>)>>,
    pub cover: Option<UploadedFile<ImageFile>>,
}

#[handler]
pub async fn store(form: StoreAlbum) -> Response {
    // Each photo is in memory or in a temp file depending on its size.
    json_response!({ "title": form.title, "photos": form.photos.len() })
}
```

- An empty part, which is how Inertia sends a `null` file, and an empty
  file input both leave an `Option<UploadedFile>` `None` and a required
  `UploadedFile` missing.
- A file its validators refuse fails under its input name, `photos.1` for
  the second photo, with the validator's message. Text where a file belongs
  fails with `validation-file`, and a file where text belongs with
  `validation-string`.
- `req.input()` reads a multipart body the same way. A `serde_json::Value`
  holds `null` where a file was sent, as Laravel's `input()` reads a file
  field.
- An `UploadedFile` reads only from a multipart body. In a JSON body the
  field fails with a `422`.

The body is capped at the form request's `max_body_bytes`, as every body it
reads is, and the parts take the part ceiling and the in-memory limit of
the multipart settings below: a file part above the limit goes to a temp
file, and a text part above it answers `413`. The validators run once the
whole body is read. `#[derive(MultipartRequest)]`, below, checks each file
while it streams in, and stops reading at the byte that breaks a `MaxSize`.

## File uploads (`MultipartRequest`)

`multipart/form-data` is its own extractor - `#[derive(MultipartRequest)]`
streams the body part by part, spilling large file parts to a temp file
above the configured threshold so a 200 MiB upload never sits fully in
RAM. Each field carries a `#[field("name")]` annotation that names the
wire field; file fields use `UploadedFile<V>` where `V` is a validator
(or a tuple of validators) from `suprnova::http::upload::validators`.

```rust
use suprnova::{handler, json_response, MultipartRequest, Response};
use suprnova::http::upload::UploadedFile;
use suprnova::http::upload::validators::{ImageFile, MaxSize};

#[derive(MultipartRequest)]
pub struct AvatarUpload {
    #[field("avatar")]
    pub avatar: UploadedFile<(ImageFile, MaxSize<5_242_880>)>, // 5 MiB cap
    #[field("caption")]
    pub caption: Option<String>,
}

#[handler]
pub async fn upload_avatar(form: AvatarUpload) -> Response {
    // `avatar` is in memory or in a temp file depending on size.
    // `.bytes()` reads either; `.store_as(...)` streams to a disk.
    let bytes = form.avatar.bytes().await?;
    json_response!({ "size": bytes.len(), "caption": form.caption })
}
```

Field shapes:

| Declaration | Wire shape |
|---|---|
| `UploadedFile<V>` | required file |
| `Option<UploadedFile<V>>` | optional file |
| `Vec<UploadedFile<V>>` | array uploads (`photos[]`) |
| `String` / `u32` / any `FromStr` | text field (required) |
| `Option<String>` / `Option<T: FromStr>` | optional text field |
| `Vec<String>` / `Vec<T: FromStr>` | repeated text fields |
| `Vec<Option<String>>` / `Vec<Option<T: FromStr>>` | repeated text fields, an empty one as `None` |

A part reaches a field by its name, read as a form request reads
[nested names and lists](#nested-names-and-lists). The Inertia client sends
a list of files with indexes, `photos[0]` and `photos[1]`, and a nested
field with brackets, `user[name]`:

- `photos[0]` and `photos[]` fill the `Vec` field declared as `photos[]`
  (or `photos`), in index order. `[]` appends after the highest index the
  list holds, and a later part at an index replaces an earlier one, as PHP
  keeps it.
- `user[name]` fills the field declared as `user.name`, the name a form
  request's rules use.
- A part sent under the exact name in `#[field(...)]` reaches that field,
  whatever the name holds.
- Parts are read in the order they were sent, as PHP reads them: a later
  part sent under a parent name, such as `user` or a bare `photos`, replaces
  what `user.name` or `photos[]` held, and a later `user[name][first]` or
  `photos[0][caption]` makes `user.name` or that element an array, which
  fails as the wrong kind of value.

```rust
use suprnova::MultipartRequest;
use suprnova::http::upload::UploadedFile;

#[derive(MultipartRequest)]
pub struct Trip {
    #[field("user.name")]
    pub name: String,
    #[field("photos[]")]
    pub photos: Vec<UploadedFile>,
}
```

A text field is read through its type's `FromStr`, except a `bool`, which
takes what forms send: `1` and `0`, as Inertia sends them, `true` and
`false`, and `on` and `off`, as an HTML checkbox sends them, the words in any
case. An unchecked checkbox sends nothing, so declare it `Option<bool>` and
read a missing value as `false` with `unwrap_or(false)`.

An empty text part is `null`, as
[empty values, repeated names, and fields that don't parse](#empty-values-repeated-names-and-fields-that-dont-parse)
describes: an `Option` field is `None`, a required field reports
`validation-required`, and an empty element is `None` in a
`Vec<Option<T>>` and reports `validation-required` under its index in a
`Vec<T>`. A `String` field is no exception. A `Vec<UploadedFile<V>>` field
still leaves out an empty file input or a `null` file, which is how a
client leaves a file out.

A text field that holds one value, rather than a `Vec`, takes the last part
sent for it. Only that part is parsed, so an earlier part that doesn't parse
reports nothing, and a last part that doesn't parse reports one error.

Built-in validators in `suprnova::http::upload::validators`:

- `MaxSize<N>` - stops reading the body at the chunk that takes the file
  past `N` bytes.
- `ImageFile` - accepts the image types Laravel's `image` rule accepts,
  detected from the file's magic bytes: JPEG, PNG, GIF, BMP, WebP, AVIF,
  HEIC and HEIF. Every other type is refused, other images included: TIFF,
  PSD, ICO and JPEG XL. SVG is refused too, because it is markup that can
  carry script; to accept it on purpose, use a `MimeType<L>` allowlist that
  names `image/svg+xml`, as Laravel accepts it only through
  `image:allow_svg`. (Named after Laravel's own rule; the plain `Image`
  name belongs to the image-manipulation pipeline - see
  [Images](images.md).)
- `Dimensions<D>` - checks an image's width and height against Laravel's
  `dimensions` constraints, taken from your own `DimensionLimits` type:
  `min_width`, `max_width`, `min_height`, `max_height`, `width`, `height`
  and `ratio`. Each is an associated function that returns `None` unless
  you override it. The size is read from the image header, for the types
  `ImageFile` accepts, without decoding the image. The header can sit
  anywhere in the file: the extractor reads it as the file streams in, and
  passes over a JPEG's metadata (a camera's EXIF block and thumbnail, for
  example) and an AVIF or HEIC file's leading boxes without keeping them.
  A file whose size cannot be read is refused too: another type, an SVG, a
  corrupt header, or a file that ends before its header does.
- `MimeType<L>` - accepts a fixed allowlist provided by your own
  `MimeAllowlist` type. An entry such as `image/*` admits every subtype of
  its type except `image/svg+xml`: an SVG passes only when your allowlist
  names `image/svg+xml`, alone or beside `image/*`.
  The type is detected from the file's magic bytes.
  The client's `Content-Type` counts only for bytes that carry no magic
  (`text/csv`, `application/json`), never for a type that has some: bytes
  that aren't a PNG don't pass as `image/png` whatever the header claims.
  Markup and script text is refused before the header is read. SVG is the
  exception, being markup: an allowlist that names `image/svg+xml` accepts
  a file whose root element is `<svg>` (after an optional XML declaration,
  comments and doctype), and refuses any other text declared as SVG. An
  SVG can carry script, so serve uploaded ones as attachments or from
  another origin.
- `()` - no-op; `UploadedFile<()>` accepts any bytes.

Validators compose as tuples: `(ImageFile, MaxSize<5_242_880>)` runs both,
short-circuiting on the first failure. Put `ImageFile` before
`Dimensions<D>`, so a file that is not an image reports `validation-image`:

```rust
use suprnova::{DimensionLimits, Dimensions, ImageFile, MaxSize, MultipartRequest, UploadedFile};

/// A square avatar, at most 1000 pixels wide.
#[derive(Default)]
pub struct Avatar;

impl DimensionLimits for Avatar {
    fn max_width() -> Option<u32> {
        Some(1000)
    }
    fn ratio() -> Option<f64> {
        Some(1.0)
    }
}

#[derive(MultipartRequest)]
pub struct ProfilePhoto {
    #[field("avatar")]
    pub avatar: UploadedFile<(ImageFile, Dimensions<Avatar>, MaxSize<2_097_152>)>,
}
```

`ratio` is the width divided by the height, so write `Some(3.0 / 2.0)`
for Laravel's `ratio=3/2`. An image passes when its own ratio is within
Laravel's tolerance of about one pixel.

### Validation errors

A failure that belongs to one field answers `422` with Laravel's
`{ "message", "errors" }` body, the message under the field's form input
name. The name is the one in `#[field(...)]`, with a trailing `[]`
replaced by the element's index: the one its name gives, or its place
among the parts appended with `[]`, counted from zero. A PDF sent as
`photos[3]` to `#[field("photos[]")]` reports under `photos.3`, and one
sent as the second `photos[]` under `photos.1`. For an Inertia form,
`InertiaValidationRedirectMiddleware` turns that `422` into a redirect back
with the errors, and the form shows each one under its field.

Every failing field is reported at once. Each message comes from the
validation catalog by its key:

| Failure | Catalog key |
|---|---|
| A required field is missing | `validation-required` |
| Text that doesn't parse as an integer, a float or a `bool` field | `validation-integer`, `validation-numeric`, `validation-boolean` |
| Text that doesn't parse as any other type | `validation-format` |
| Bytes that aren't UTF-8 for a `String` field | `validation-string` |
| A text part where a file belongs | `validation-file` |
| A file part where text belongs | `validation-string` |
| A file over `MaxSize<N>`, the limit in kilobytes as Laravel words it | `validation-max-file` |
| A file `ImageFile` refuses | `validation-image` |
| A file `Dimensions<D>` refuses, or whose size it cannot read | `validation-dimensions` |
| A file `MimeType<L>` refuses, with the allowed types | `validation-mimetypes` |

A text part whose bytes aren't UTF-8, as a page served in a legacy
encoding can send, doesn't parse as any type: a `String` field reports
`validation-string`, and any other field the key its type reports for text
that doesn't parse.

To change a message, define its key in your own catalog:

```ftl
# lang/en/validation.ftl
validation-image = Choose a picture for { $field }.
```

A file input left empty arrives as a file part with no file name and no
bytes, and Inertia sends a `null` file as an empty text part. Both count as
a missing file: an optional field is `None`, and a required one reports
`validation-required`. A field that holds one file takes the first part
sent for it that isn't one of these, and ignores every later part for it
without checking it. Text where a file belongs is never checked as a file:
it reports `validation-file`, however long it is.

A file that fails while the body streams, as one over `MaxSize<N>` does,
stops the read after the chunk that crossed the limit. The hooks and the
handler don't run, and every temp file the request wrote is removed.

#### Custom validators

Implement `UploadValidator` to check a file yourself. Return
`FrameworkError::invalid_upload` with a keyed message for a file that is
invalid input, so it reports under the field's name like the built-ins.
Return any other error for a failure to check the file; that error keeps
its own status.

```rust
use suprnova::http::upload::validators::UploadValidator;
use suprnova::{FrameworkError, ValidationMessage};

#[derive(Default)]
pub struct PdfOnly;

impl UploadValidator for PdfOnly {
    fn validate_final(
        &self,
        sniff: &[u8],
        _size: u64,
        _content_type: Option<&str>,
    ) -> Result<(), FrameworkError> {
        if !sniff.starts_with(b"%PDF-") {
            return Err(FrameworkError::invalid_upload(
                ValidationMessage::keyed("validation-pdf").fallback("The file must be a PDF."),
            ));
        }
        Ok(())
    }
}
```

`validate_final` sees the first 16 KiB of the file in `sniff`. The
extractor calls `validate_received`, whose default runs `validate_final`.
Override `validate_received` instead when you need what the extractor read
from the whole file: its `ReceivedPart` carries the `sniff`, the `size`,
the declared `content_type`, and the `image_size` that `Dimensions<D>`
checks.

### Per-field caps and array bounds

The byte cap on the total body is global (25 MiB by default for
multipart, configurable via
`suprnova::http::upload::set_global_max_multipart_body_bytes`). Per-field
caps prevent abuse where a body of many small parts grows
`Vec<UploadedFile<_>>` unbounded within the byte budget:

```rust
#[derive(MultipartRequest)]
pub struct Gallery {
    #[field("photos", max_count = 8)]
    pub photos: Vec<UploadedFile<MaxSize<1_048_576>>>,
}
```

The (`max_count` + 1)-th part for that field returns HTTP `413` before
allocating, so the extra part never reaches `Vec` growth. Every part the
field takes counts, whatever name it was sent under: `photos[]`, `photos[3]`
and a repeated index alike. The four limits
on the whole request - the body's byte cap, the part ceiling, a field's
`max_count`, and the in-memory limit on a text part - all answer `413`
without reading the body further. Form text must fit in memory, so a text
part longer than the spill threshold (2 MiB by default, set with
`suprnova::http::upload::set_global_upload_spill_threshold`) bounds the
request the way the byte cap does, as PHP's `post_max_size` does for
Laravel. When one chunk crosses the byte cap and a file's `MaxSize`
together, the `413` wins.

### Why Suprnova diverges

Laravel checks an array's size with `array|max:N`, a validation rule that
runs after PHP has buffered the whole request, so too many files is a `422`.
`max_count` bounds the request while it streams, before the extra part is
read, so it refuses the request the way the byte cap does.

Laravel's `mimetypes:image/*` rule admits a file detected as
`image/svg+xml`, because the wildcard matches any `image/` type. `MimeType`
leaves SVG out of `image/*`, as Laravel's `image` rule leaves it out unless
you pass `allow_svg`. An SVG is markup that can run script, so you name
`image/svg+xml` to accept one.

Laravel's `dimensions` passes an SVG without checking it. `Dimensions<D>`
refuses one, because an SVG has no pixel size to check. The limits are
functions of a type rather than a rule string, because a validator is
built with `Default` inside the derive and takes no arguments.

### Authorize and after-validation hooks

`MultipartRequest` mirrors `FormRequest`'s hooks via the
`MultipartRequestHooks` trait. By default the derive emits an empty
impl; opt in to your own with `#[multipart(custom_hooks)]`:

```rust
use suprnova::{AsyncRule, MultipartRequest, Request, Unique, ValidationErrors, async_trait};
use suprnova::http::upload::{MultipartRequestHooks, UploadedFile};

#[derive(MultipartRequest)]
#[multipart(custom_hooks)]
pub struct NewAlbum {
    #[field("slug")]
    pub slug: String,
    #[field("photos[]")]
    pub photos: Vec<UploadedFile>,
}

#[async_trait]
impl MultipartRequestHooks for NewAlbum {
    fn authorize(req: &Request) -> bool {
        req.header("X-Admin-Token").is_some()
    }

    fn after_validation(&self) -> Result<(), ValidationErrors> {
        let mut errs = ValidationErrors::new();
        if self.photos.is_empty() {
            errs.add("photos", "Add at least one photo.");
        }
        errs.into_result()
    }

    async fn after_validation_async(&self) -> Result<(), ValidationErrors> {
        let mut errs = ValidationErrors::new();
        Unique::new("albums", "slug")
            .check_async(&self.slug, &mut errs, "slug")
            .await;
        errs.into_result()
    }
}
```

You run these stages in order:

1. `prepare_for_validation`, where you register `Request::transform_input`
   changes before authorization.
2. `authorize`, before any byte of the body is read. `false` answers `403`.
3. Extraction and field validation.
4. `after_validation`.
5. `after_validation_async`, where you use database checks such as `Unique`.
6. The handler, only when the merged error bag is empty.

You run both hooks for a real request with a constructed value, even when
field validation reports errors. You stop before hooks on a streaming
failure or when missing or malformed scalar input prevents construction.
A marked request keeps the [Precognition](precognition.md) stage rules.
You get a redirect with flashed errors and old text input for a classic
HTML form, as with a form request.

A hook's non-empty `ValidationErrors` answers `422` like a field failure;
an empty set counts as success. Hook errors use the same input names: an
error under a Rust field name, such as `photos.1` on the `photos` field,
reports under that field's `#[field(...)]` name. The impl needs
`#[async_trait]` only when it overrides `after_validation_async`.

### Streaming to storage

`UploadedFile::store_as` writes the part to a registered storage disk.
For disk-backed parts the path is fully streaming (64 KiB chunks via
`opendal::Operator::writer`); in-memory parts use a single write call.
Use the content-derived extension when the storage path is
content-addressed - the filename header is untrusted:

```rust
use suprnova::Storage;

let disk = Storage::disk("avatars")?;
let path = format!("{}.{}", user.id, form.avatar.extension_from_magic());
form.avatar.store_as(&disk, &path).await?;
```

See [Filesystem](filesystem.md) for the storage disk registry.

## File organization

The standard structure for requests:

```
src/
├── requests/
│   ├── mod.rs                 # Re-exports all requests
│   ├── create_user.rs         # CreateUserRequest
│   ├── update_user.rs         # UpdateUserRequest
│   └── create_post.rs         # CreatePostRequest
├── controllers/
│   └── user.rs                # Uses CreateUserRequest
└── routes.rs
```

**src/requests/mod.rs:**
```rust
pub mod create_user;
pub mod update_user;

pub use create_user::CreateUserRequest;
pub use update_user::UpdateUserRequest;
```

## End-to-end type safety with Inertia

Requests can also derive `InertiaProps` to generate TypeScript types, enabling end-to-end type safety from your Rust backend to your React frontend.

### Generating TypeScript types for requests

Add `InertiaProps` derive alongside `#[request]`:

```rust
use suprnova::{request, InertiaProps};

#[request]
#[derive(InertiaProps)]
pub struct CreateTodoRequest {
    #[validate(length(min = 1, message = "Title is required"))]
    pub title: String,

    #[validate(length(max = 500))]
    pub description: Option<String>,
}
```

Run type generation:

```bash
suprnova generate-types
```

This generates TypeScript types in `frontend/src/types/inertia-props.ts`:

```typescript
export interface CreateTodoRequest {
  title: string
  description: string | null
}
```

### Type-safe forms with Inertia

Use Inertia's `<Form>` component for the cleanest form handling:

```tsx
import { Form, usePage } from '@inertiajs/react'

export default function CreateTodo() {
  const { errors } = usePage().props

  return (
    <Form action="/todos" method="post">
      <input
        type="text"
        name="title"
        placeholder="Todo title"
      />
      {errors?.title && <span className="error">{errors.title}</span>}

      <textarea
        name="description"
        placeholder="Description (optional)"
      />

      <button type="submit">Create Todo</button>
    </Form>
  )
}
```

For more control, combine `<Form>` with the `useForm` hook and your generated types:

```tsx
import { Form, useForm } from '@inertiajs/react'
import type { CreateTodoRequest } from '../types/inertia-props'

export default function CreateTodo() {
  const { data, setData, errors, processing } = useForm<CreateTodoRequest>({
    title: '',
    description: null,
  })

  return (
    <Form action="/todos" method="post">
      {({ processing }) => (
        <>
          <input
            type="text"
            name="title"
            value={data.title}
            onChange={(e) => setData('title', e.target.value)}
            placeholder="Todo title"
          />
          {errors.title && <span className="error">{errors.title}</span>}

          <textarea
            name="description"
            value={data.description || ''}
            onChange={(e) => setData('description', e.target.value || null)}
            placeholder="Description (optional)"
          />

          <button type="submit" disabled={processing}>
            Create Todo
          </button>
        </>
      )}
    </Form>
  )
}
```

### What the derive buys you

- TypeScript catches field-name typos and type mismatches at compile
  time.
- IDE autocomplete reads the generated `.ts` directly.
- Rename a field in Rust, rerun `suprnova generate-types`, and the
  TypeScript surface follows.

See [TypeScript types](frontend-typescript-types.md) for the full
generation pipeline.

## Request accessors

Beyond the validated-form pattern above, the `Request` type carries Laravel-style accessors for inspecting the wire-level request - URL, headers, query string, content negotiation, route metadata, and client IP. These are useful in middleware, in handlers that want raw access alongside a `FormRequest`, and in any place where validated parsing isn't the right tool.

### URL and path

| Method | Returns | Notes |
|--------|---------|-------|
| `req.path()` | `&str` | Raw URI path. |
| `req.decoded_path()` | `String` | Path with percent-escapes resolved. |
| `req.segments()` | `Vec<String>` | Path split on `/`, empty segments dropped. |
| `req.segment(index, default)` | `Option<String>` | 1-based segment access. |
| `req.url()` | `String` | Scheme + host + path (no query string). |
| `req.full_url()` | `String` | URL + query string, its pairs sorted by key and re-encoded as Laravel's `fullUrl()` writes them. |
| `req.full_url_with_query(&[("k","v")])` | `String` | Append or override query keys. |
| `req.full_url_without_query(&["k"])` | `String` | Strip query keys. |

```rust
use suprnova::{handler, json_response, Request, Response};

#[handler]
pub async fn show(req: Request) -> Response {
    if req.is(&["admin/*"]) {
        // path matches the admin/* wildcard
    }
    json_response!({ "url": req.full_url() })
}
```

### Host, scheme, IP

| Method | Returns | Source order |
|--------|---------|--------------|
| `req.host()` | `Option<String>` | `X-Forwarded-Host` → `Host` → URI authority. Lowercased, numeric port stripped, `None` when invalid. |
| `req.http_host()` | `Option<String>` | Host plus port when non-default. |
| `req.scheme_and_http_host()` | `Option<String>` | `scheme://host:port`. |
| `req.scheme()` | `&'static str` | `"https"` when [`secure`] is true, else `"http"`. |
| `req.secure()` | `bool` | URI scheme → `X-Forwarded-Proto` → `X-Forwarded-Ssl: on`. |
| `req.ip()` | `Option<String>` | From a trusted proxy: `X-Forwarded-For`, read from the right, then `X-Real-IP` when there is no `X-Forwarded-For`. Otherwise the peer address. |
| `req.ips()` | `Vec<String>` | Every address the request names: `X-Forwarded-For` left to right, `X-Real-IP`, then the peer address. For logs only. |
| `req.user_agent()` | `Option<&str>` | `User-Agent` header. |
| `req.port()` | `Option<u16>` | Host header port → `X-Forwarded-Port` → URI port. |

`req.host()` reads the host as Symfony's `getHost` does. It lowercases the
host and strips a port only when the port is all digits:
`Host: Example.COM:8080` gives `example.com`, and `Host: example.com:abc`
gives `example.com:abc`. A host that holds anything but letters, digits,
`-`, `_`, `.`, `:` and the brackets of an IPv6 literal gives `None`, so
`Host: bad<host>` never reaches `http_host()`, `scheme_and_http_host()`,
`url()`, a redirect, or a cache key. Laravel throws a
`SuspiciousOperationException` for such a host; `req.host()` returns
`None`, and [`TrustHosts`](#trusted-hosts) answers the request `400`.

`req.ip()` is the address to key a limit on or to check against an
allowlist. It reads the proxy headers only when the TCP peer is a trusted
proxy, and it returns the peer address in every other case:

1. When the peer is not in the trusted proxies, `req.ip()` is the peer
   address. The headers are ignored, because any client can send them.
2. When the peer is a trusted proxy and the request has an
   `X-Forwarded-For` header, `req.ip()` reads the list **from the right**.
   It skips every entry that is a trusted proxy and returns the first
   entry that is not. A proxy adds the address it saw to the right end of
   the header, so the left end is what the client wrote and the client
   chooses it. The header may arrive as several lines. They count as one
   list, in order.
3. When the peer is a trusted proxy and the request has no
   `X-Forwarded-For`, `req.ip()` reads `X-Real-IP`. With both headers
   present, `X-Real-IP` is not read.
4. An entry that is not an address ends the walk, and `req.ip()` returns
   the proxy that wrote that entry. An entry with a port, such as
   `203.0.113.5:54321`, is read as its address.

Three rules keep this safe:

- **List every proxy of the chain.** A proxy that is not in the trusted
  proxies is taken for the client, and all of its clients share its
  address.
- **List proxies and nothing else.** `APP_TRUSTED_PROXIES` takes
  addresses and CIDR ranges, such as
  `10.0.0.5,173.245.48.0/20,2400:cb00::/32`. A client that connects from a
  listed range is believed like a proxy and chooses its own address. A
  range of `/0`, which is every address, is refused, and boot fails.
- **Let the proxy write the header.** A trusted proxy has to add to
  `X-Forwarded-For` or replace it. A proxy that passes the client's header
  on unchanged lets the client write all of it. A proxy that sets
  `X-Real-IP` has to remove any `X-Forwarded-For` from the request.

The `Forwarded` header of RFC 7239 is not read. See
[Rate Limiting](rate-limiting.md#the-client-address-behind-a-proxy) for
what this means for per-address limits and
[Environment Variables](env-vars.md#behind-a-reverse-proxy-set-app_trusted_proxies)
for the variable.

### Trusted hosts

The `Host` header is written by the client. When your application builds
an absolute URL from it, such as a password reset link, a forged host
sends that link to the attacker's site. `TrustHosts` is a middleware that
answers `400` with the message `Bad request.` to any request whose host
you do not serve. It mirrors Laravel's `TrustHosts`.

`TrustHosts::new()` trusts the host of `APP_URL` and its subdomains. With
`APP_URL=https://example.com`, a request for `example.com` or
`api.example.com` passes, and a request for `evil.test` gets `400`:

```rust
use suprnova::{global_middleware, TrustHosts};

pub async fn register() {
    global_middleware!(TrustHosts::new());
}
```

`TrustHosts::at(patterns, subdomains)` trusts the hosts that the regular
expressions in `patterns` match. When `subdomains` is `true`, it also
trusts the `APP_URL` host and its subdomains:

```rust
use suprnova::{global_middleware, FrameworkError, TrustHosts};

pub async fn register() -> Result<(), FrameworkError> {
    global_middleware!(TrustHosts::at([r"^example\.com$", r"^(.+\.)?example\.org$"], false)?);
    Ok(())
}
```

The middleware follows these rules:

- A pattern matches without regard to case, anywhere in the host. Anchor
  it with `^` and `$` to match the whole host.
- A request whose `req.host()` is `None` gets `400`.
- With no pattern at all, every valid host passes, as in Laravel. That
  happens with `TrustHosts::at` given an empty list and `false`, or with an
  `APP_URL` that has no host.
- In the local environment (`APP_ENV=local`, the default when `APP_ENV` is
  unset), every host passes, as Laravel's `shouldSpecifyTrustedHosts`
  allows. Set `APP_ENV` on every other deployment.
- Behind a trusted proxy the host comes from `X-Forwarded-Host`, so name
  the public host the browser asked for.

The middleware reads `APP_URL` and `APP_ENV` on each request, from the
registered `AppConfig` or from the environment.

#### Why Suprnova diverges

Laravel's `TrustHosts::at` stores the patterns and compiles them on each
request. `TrustHosts::at` compiles them once and returns a `Result`, so a
pattern that is not a valid regular expression fails at boot instead of
refusing every request.

### Headers and method

`req.is_precognitive()` is true after the `Precognitive` middleware marks
the request. `req.is_attempting_precognition()` reads the header alone,
so it can be true on a route without the middleware. Use the marked state
to skip side effects or change live-validation rules. See
[Precognition](precognition.md) for route opt-in and narrowed validation.

| Method | Returns |
|--------|---------|
| `req.has_header("X-Foo")` | `bool` |
| `req.bearer_token()` | `Option<String>` (last `Bearer ` substring, comma-trimmed) |
| `req.is_method("POST")` | `bool` (case-insensitive) |
| `req.ajax()` | `X-Requested-With: XMLHttpRequest`, compared exactly as Symfony's `isXmlHttpRequest` compares it |
| `req.pjax()` | Truthy `X-PJAX` header |
| `req.prefetch()` | `X-Moz`, `Purpose`, or `Sec-Purpose` = `prefetch` |

### Content negotiation

```rust
if req.is_json() { /* Content-Type carries /json or +json */ }
if req.expects_json() { /* AJAX without Accept narrowing, or Accept prefers JSON */ }
if req.wants_json() { /* Accept header tops with JSON */ }
if req.accepts_html() { /* Accept allows text/html */ }

let preferred = req.prefers(&["application/json", "text/html"]);
let acceptable = req.acceptable_content_types();
```

`accepts(&[ty])` matches both bare types and `application/<vendor>+json`-style suffixes. `accepts_any_content_type()` returns true when there is no Accept header or the top preference is `*/*`.

A type the header weights `q=0` is refused, as RFC 9110 defines it: `acceptable_content_types()` leaves it out, and `accepts`, `prefers`, `wants_json` and `expects_json` treat it as unwanted. The most specific matching range decides, so `Accept: */*, application/json;q=0` accepts HTML and refuses JSON. Laravel lists a `q=0` type as acceptable; Suprnova follows the RFC instead.

### Query string

```rust
let id: Option<String> = req.query_param("id");
let present: bool = req.has_query("id");
let map = req.query_params(); // HashMap<String, String>

// Typed query parse via serde
#[derive(serde::Deserialize)]
struct SearchQuery {
    q: String,
    page: Option<u32>,
    #[serde(default)]
    tags: Vec<String>,
}
let q: SearchQuery = req.query_into()?;
```

`query_into` reads the query as a form body reads: `?page=` leaves `page`
`None`, `?q=a&q=b` gives `b`, `?tags[]=a&tags[]=b` fills `tags`, and
`?filters[status]=x` fills a nested `filters` struct, as
[nested names and lists](#nested-names-and-lists) describes. A field
that is missing or doesn't parse answers as a form request's does: a `422`
whose `errors` names each such field with its catalog message, so an
Inertia visit is redirected back with them. A query that fails for another
reason answers `422` with a message.

### Route metadata

After the router dispatches a request, the matched pattern is recorded on the request:

```rust
if req.route_is(&["users.show", "users.*"]) {
    // we're inside the users.show or users.* route
}

let pattern = req.route_pattern(); // Some("/users/{id}")
let name = req.route_name();       // Some("users.show")
```

`route_is(&[...])` accepts `*` wildcards (Laravel's `Str::is` semantics).

## Aborting early

For early-exit error handling without the full `Response` envelope, the `abort_with` / `abort_if` / `abort_unless` helpers return a `FrameworkError` that renders through the standard `From<FrameworkError> for HttpResponse` pipeline. They compose with `?` directly:

```rust
use suprnova::{abort_if, abort_unless, abort_with, handler, json_response, Request, Response};

#[handler]
pub async fn show(req: Request) -> Response {
    let id = req.param("id")?;

    // 404 when the resource is missing.
    abort_if(id == "0", 404, "User not found")?;

    // 403 when the caller is unauthenticated.
    abort_unless(req.has_header("Authorization"), 403, "Login required")?;

    // Or raise a status unconditionally:
    if some_condition() {
        return Err(abort_with(418, "I'm a teapot").unwrap_err().into());
    }

    json_response!({ "id": id })
}
```

`abort_if` / `abort_unless` return `Ok(())` when the condition is false, so the `?` continues normally.

## Why Suprnova diverges

Laravel exposes a synchronous, merged input bag - `$req->input('field')`,
`$req->all()`, `$req->only(['a','b'])`, `$req->boolean('flag')` - pulled
from the query string and the parsed body together. Suprnova does not
ship that surface. The reason:

- Suprnova's body is consume-once and async. A synchronous `all()`
  would require buffering every body up front to satisfy a method that
  most handlers never call - the memory and DoS surface differs from
  PHP's per-request-process lifecycle.
- The typed alternative (`#[request]` + `FormRequest`) gives
  compile-time field names, validation, and content-type-aware parsing -
  exactly the safety net the untyped bag lacks.

For query / header / route inspection, reach for `query_param`,
`query_into`, `has_query`, `bearer_token`, and the header readers
above. For body-side access, define a `#[request]` struct or a
`#[derive(MultipartRequest)]` extractor.

## Next

- [Validation](validation.md) - the rule library behind `#[validate(...)]`
  and the shape of the 422 error bag
- [Responses](responses.md) - building `HttpResponse` values back from
  your handler, including streaming and redirects
- [Errors](errors.md) - handler patterns built on top of `Response`
  being `Result<HttpResponse, HttpResponse>`
- [Routing](routing.md) - registering routes and the `{id}` parameters
  `req.param("id")` reads
- [Authentication](authentication.md) - `Auth::user_as`, `Auth::attempt`,
  and the guards that resolve the current user from the request
- [Filesystem](filesystem.md) - registering the storage disks that
  `UploadedFile::store_as` writes to


---

<!-- /docs/responses -->

# Responses

Every Suprnova handler returns a `Response`, which is an alias for
`Result<HttpResponse, HttpResponse>`. The `Ok` arm carries the success
response, the `Err` arm carries an already-rendered error response, and
the `?` operator collapses any error type that has a `From` into
`HttpResponse` along the way. This chapter is the practical reference
for building the `Ok` side - the `HttpResponse` builders, the
`Redirect` builder, the cookie API, and the `abort_*` short-circuits.
For the error story see [Error Model](error-model.md) and
[Error Handling](errors.md).

## `HttpResponse` builders

`HttpResponse` is the wire-shaped response type. The constructors set
sensible defaults; the chainable setters override them.

### Body constructors

```rust
use suprnova::{HttpResponse, Response};
use serde_json::json;

pub async fn examples() -> Response {
    // text/plain
    let _ = HttpResponse::text("OK");

    // application/json (any serde_json::Value)
    let _ = HttpResponse::json(json!({ "ok": true }));

    // text/html; charset=utf-8
    let _ = HttpResponse::html("<h1>Hello</h1>");

    // text/markdown; charset=utf-8
    let _ = HttpResponse::markdown("# Hello");

    // Raw bytes with an explicit content type - used by JSON:API
    // serialization and any other non-JSON byte body.
    let _ = HttpResponse::bytes_body(b"PNG...".to_vec(), "image/png");

    Ok(HttpResponse::text("done"))
}
```

You send Markdown source with `HttpResponse::markdown(body)` or the
`markdown(body)` helper exported from `suprnova` and `suprnova::http`.
You receive a `200` response with `Content-Type: text/markdown; charset=utf-8`.
You keep the body exactly as supplied, including whitespace and an empty body.
You return `markdown("# Hi")` directly from a handler.

Two streaming constructors exist for long-lived responses:

- `HttpResponse::sse(stream)` - Server-Sent Events. Wraps a `Stream` of
  `SseEvent` values, sets the four required headers
  (`Content-Type: text/event-stream`, `Cache-Control: no-cache`,
  `Connection: keep-alive`, `X-Accel-Buffering: no`), and keeps the
  connection open until the producing stream ends. See
  [Server-Sent Events](sse.md).
- `HttpResponse::stream_bytes(stream)` - generic chunked response.
  Takes a `Stream<Item = Result<Bytes, Infallible>>`. The error type is
  `Infallible` by design: every producer in the framework turns its own
  errors into a terminal stream message before the stream ends, because
  there is no way to surface a transport-level error to the client
  mid-response.
- `HttpResponse::event_stream(stream, end)` - Laravel's `ResponseFactory::eventStream`.
  Wraps a `Stream` of `sse::StreamedEvent` values, framing each as `event: update` (or its
  own name) plus a configurable terminal frame. See [Server-Sent Events](sse.md).
- `HttpResponse::stream_json(stream)` - Laravel's `ResponseFactory::streamJson`. Wraps a
  `Stream` of any `Serialize` value and flushes it as one incrementally-built JSON array
  instead of buffering the whole collection first. See [Server-Sent Events](sse.md#event_stream-and-stream_json).

### Status, headers, cookies

Every builder returns `Self`, so chain freely:

```rust
use suprnova::{Cookie, HttpResponse, Response};
use serde_json::json;

pub async fn created() -> Response {
    Ok(HttpResponse::json(json!({ "id": 42 }))
        .status(201)
        .header("X-Resource-Id", "42")
        .cookie(Cookie::new("last_id", "42")))
}
```

| Method | Behavior |
|---|---|
| `.status(code)` | Set the HTTP status. Codes outside `100..=599` downgrade to 500 at the wire boundary with a warning log. |
| `.header(name, value)` | Append a header. Duplicates allowed (matches `Set-Cookie` semantics). |
| `.replace_header(name, value)` | Drop any prior occurrences and set one. |
| `.with_headers([(k, v), ...])` | Append many at once. Accepts any `IntoIterator<Item = (K, V)>`. |
| `.without_header(name)` | Remove every occurrence (case-insensitive). |
| `.header_value(name)` | Read back the first-set value. Useful in tests. |
| `.cookie(Cookie)` | Attach one cookie as `Set-Cookie`. |
| `.with_cookies([Cookie, ...])` | Attach many. |
| `.without_cookie(name)` | Schedule a deletion (equivalent to `Cookie::forget(name)`). |

The same chainable setters are available on a `Response` (the
`Result`) through the `ResponseExt` trait, so the macros stay
ergonomic:

```rust
use suprnova::{json_response, Cookie, Response, ResponseExt};

pub async fn list() -> Response {
    json_response!({ "ok": true })
        .status(200)
        .header("X-Total-Count", "42")
        .cookie(Cookie::new("last_query", "list"))
}
```

`ResponseExt` exposes `.status`, `.header`, `.with_headers`,
`.without_header`, `.cookie`, `.with_cookies`, and `.without_cookie`.

### Wire-boundary validation

`HttpResponse::into_hyper` runs two safety filters before handing the
response to hyper:

- **Status range.** Anything outside `100..=599` downgrades to 500 with
  a `tracing::warn!`. This catches `AppError::status(700)` typos at the
  boundary instead of letting non-conformant codes reach the wire.
- **Header CRLF injection.** Every header name and value is validated
  via hyper's own `HeaderName::try_from` / `HeaderValue::try_from`. Any
  rejected header is dropped with a warn log and the response is built
  without it. Attacker-controlled values that get reflected into a
  header (CORS allow-headers, `X-Forwarded-*`, custom debug headers)
  cannot split the response.

Both filters are silent in the success path - you only see them in
logs when something tried to slip through.

## File responses

You use four constructors to send a file. `file` and `download` read from the
filesystem, so they're `async` and return
`Result<HttpResponse, FrameworkError>`. A handler converts the error with
`.map_err(HttpResponse::from)`. `download_bytes` can't fail and returns an
`HttpResponse`.

| Constructor | Laravel | `Content-Disposition` |
|---|---|---|
| `HttpResponse::file(path, name).await` | `response()->file($path)` | `inline` |
| `HttpResponse::download(path, name).await` | `response()->download($path, $name)` | `attachment` |
| `HttpResponse::download_bytes(bytes, name, content_type)` | In-memory download | `attachment` |
| `HttpResponse::stream_download(stream, name, content_type)` | `response()->streamDownload(...)` | `attachment` |

```rust
use suprnova::{HttpResponse, Request, Response};

// Show a PDF in the browser under a friendlier name.
pub async fn certificate(_req: Request) -> Response {
    HttpResponse::file("storage/certificates/7f3e.pdf", Some("certificate.pdf"))
        .await
        .map_err(HttpResponse::from)
}

// Save a stored upload under the name the user gave it.
pub async fn attachment(_req: Request) -> Response {
    HttpResponse::download("storage/attachments/7f3e", Some("Informe Pérez.pdf"))
        .await
        .map_err(HttpResponse::from)
}

// Send a file you built in memory.
pub async fn export(_req: Request) -> Response {
    let csv = "id,name\n1,Joan\n".to_string();
    Ok(HttpResponse::download_bytes(
        csv,
        "users-2026-09-30.csv",
        "text/csv; charset=utf-8",
    ))
}
```

`file` and `download` behave the same way except for the disposition:

- The `Content-Type` comes from the file extension: `.pdf` is
  `application/pdf`, `.png` is `image/png`, and `.xlsx` is the
  spreadsheet type. An extension the table doesn't know gives
  `application/octet-stream`. The content is never inspected, so a file
  with an unknown extension is never served as HTML or SVG, whatever it
  holds.
- When `name` is `None`, the filename is the file's own name.
- A file of 1 MiB or less is read whole. A larger file is streamed in
  256 KiB chunks by one background task that reads at most five chunks
  ahead of the client, so a large download doesn't sit in memory, even
  when the client stops reading. Both carry a `Content-Length`.
- A missing path, or a path that is a directory, returns a `404` error
  whose message doesn't name the path. Any other read failure returns a
  `500` error with the generic server-error body; the path goes to the
  log.

`file` and `download` open the path you pass as-is. Don't build that path
from request input. To serve a file that a request names, use
`Storage::response` or `Storage::download` on a disk, which apply the
disk's path guard. For more information, see
[Serve a file from a disk](filesystem.md#serve-a-file-from-a-disk).

### Filenames and `Content-Disposition`

Every file response writes its header with
`ContentDisposition::header_value`, which follows RFC 6266:

```rust
use suprnova::ContentDisposition;

assert_eq!(
    ContentDisposition::Attachment.header_value("Certificat·Joan Pérez.pdf"),
    "attachment; filename=\"CertificatJoan Perez.pdf\"; \
     filename*=UTF-8''Certificat%C2%B7Joan%20P%C3%A9rez.pdf"
);
```

- The `filename` parameter is an ASCII fallback, transliterated the way
  Laravel's `Str::ascii` builds its fallback: `é` becomes `e` and `ß`
  becomes `ss`. A character whose spelling would put an unsafe character
  into a filename, such as `·` or `½`, is dropped. A character with no
  spelling at all becomes `_`, so the fallback is never empty. `%` and `/`
  become `_`, and a `"` or `\` is escaped inside the quotes.
- When the fallback can't carry the name exactly, a
  `filename*=UTF-8''...` parameter follows with the name percent-encoded.
  Current browsers use it, so the user sees `Certificat·Joan Pérez.pdf`.
- Control characters, including CR, LF, and NUL, become `_` before
  anything else. A filename can't end the header, start a new header, or
  add a parameter, so the original name of an upload is safe to pass.

You pass a `Stream<Item = Result<Bytes, Infallible>>` to
`HttpResponse::stream_download(stream, name, content_type)` to send an export
as you produce it. The first chunk reaches the body before the producer
finishes. You set cache headers with `.header("Cache-Control", "private")`.
An empty stream sends an empty download. A dropped producer ends the stream.

You pass extra headers and a disposition to
`HttpResponse::file_with(path, name, headers, disposition)` or
`HttpResponse::download_with(path, name, headers, disposition)`. You can
choose `ContentDisposition::Inline` or `ContentDisposition::Attachment`.
Your `Content-Type` and `Cache-Control` replace their defaults. The file's
length, range metadata and chosen disposition stay authoritative.

You receive `Last-Modified` from the file's modification time and
`Accept-Ranges: bytes`. A GET with `Range: bytes=0-9` returns `206` and
`Content-Range: bytes 0-9/<size>`. An unsatisfiable range returns `416`
with an empty body and `Content-Range: bytes */<size>`. You can also request
an open range or a suffix, such as `bytes=10-` or `bytes=-10`. These follow
[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-14).
Invalid ranges, multiple ranges, unsupported units and ranges on methods
other than GET receive the full response. You receive the full response for
an empty file without a `Range` header, and `416` for a GET with a `Range`
header. A mismatched `If-Range` receives the full response.

### Why Suprnova diverges

- Laravel's `response()->file()` sends no `Content-Disposition`. Suprnova
  sends `inline` with the filename, so a user who saves the file gets a
  sensible name.
- Laravel guesses the content type from the file content. Suprnova uses the
  extension only, because a sniffed type lets an upload be served as
  something the browser runs.
- In Laravel a missing file throws, which becomes a `500` error. Suprnova
  returns a `404` error that the handler can pass on.
- You choose a `Cache-Control` value for a file response. Suprnova keeps
  that value and does not add Symfony's `public` default.

## Response macros

Two `Response`-shaped macros exist for the common cases:

```rust
use suprnova::{json_response, text_response, Response};

pub async fn json_handler() -> Response {
    json_response!({ "users": [{ "id": 1, "name": "Alice" }] })
}

pub async fn text_handler() -> Response {
    text_response!("OK")
}
```

Both expand to `Ok(HttpResponse::...)`. Chain `ResponseExt` setters on
either to adjust status, headers, or cookies.

## Cookies

`Cookie::new(name, value)` produces a cookie with secure defaults -
`HttpOnly`, `Secure`, `SameSite=Lax`, `Path=/`. Override per cookie:

```rust
use suprnova::Cookie;
use std::time::Duration;

let session = Cookie::new("session_id", "abc123")
    .http_only(true)
    .secure(true)
    .same_site(suprnova::SameSite::Strict)
    .path("/")
    .domain("example.com")
    .max_age(Duration::from_secs(3600))
    .partitioned(true);
```

Four convenience constructors cover common patterns:

- `Cookie::forget(name)` - empty value, `Max-Age=0`, `Secure` and
  `HttpOnly`, with the `Path`, `Domain` and `SameSite` of the session
  configuration. Use this on logout to instruct the browser to drop the
  cookie.
- `Cookie::forget_with(name, path, domain)` - the scoped form. A browser
  only drops a cookie when the deletion cookie's `Path` and `Domain`
  match the ones it was set with, so a cookie set with `Path=/admin` or
  `Domain=.example.com` needs a deletion cookie with the same. An
  explicit path or domain wins. Pass `None` for either argument to take
  the session configuration's value.
- `Cookie::forever(name, value)` - five-year `Max-Age`.
- `Cookie::encrypted(name, plaintext)` - writes AES-256-GCM ciphertext
  whose AAD is bound to the cookie's logical name. Read it with
  `Cookie::read_encrypted_for(name, wire)` using the same name.
  The value opens under that name and in no other way: the value of
  another cookie does not open, and `read_encrypted_for` returns an
  error for it. Requires `APP_KEY` to be set at boot. See [Encryption](encryption.md).

A deletion cookie takes its defaults from the session configuration, as
Laravel's cookie jar takes them from `session.path`, `session.domain` and
`session.same_site`, so it matches the cookies your application sets with
the session's scope:

| Attribute | Value |
|---|---|
| `Path` | `SESSION_PATH`, or the public root of the request (`/` at the host root), or `/` for a cookie whose name starts with `__Host-` |
| `Domain` | `SESSION_DOMAIN`, or none |
| `SameSite` | `SESSION_SAME_SITE`, read as the session cookie reads it (`strict`, `none`, anything else `Lax`) |
| `Secure`, `HttpOnly` | Always set |

With `SESSION_PATH=/app`, `SESSION_DOMAIN=.example.com` and
`SESSION_SAME_SITE=strict`, `Cookie::forget("prefs")` sends
`prefs=; Path=/app; HttpOnly; Secure; SameSite=Strict; Domain=.example.com; Max-Age=0`.
Inside a request that `SessionMiddleware` serves, the configuration you
gave that middleware is the one read; elsewhere the `SESSION_*` variables
are. `without_cookie` and `without_cookies` build their deletion cookies
with `Cookie::forget`, so they follow the same rules.

Removing several cookies at once - the usual logout shape - is
`without_cookies`, available on `HttpResponse`, on `Response` through
`ResponseExt`, and on both redirect builders:

```rust
use suprnova::{HttpResponse, Redirect};

let _ = HttpResponse::text("bye").without_cookies(["session", "remember"]);
let _: suprnova::Response = Redirect::to("/login")
    .without_cookies(["session", "remember"])
    .into();
```

On a redirect the deletions ride the 302 itself, not the destination, so
the browser has already dropped them by the time it follows the
`Location`.

Header serialization percent-encodes every byte that isn't a valid
cookie-octet per RFC 6265, including all control characters. CRLF in
a cookie name or value gets encoded, not propagated - header injection
through cookies is closed at the serializer.

### Raw cookies

Another system sometimes reads a cookie and expects its bytes unchanged:
a token holding `:` or `/`, or a value that is already encoded.
`Cookie::new` percent-encodes those bytes, so a reader that does not
decode sees `%3A` where you wrote `:`. `Cookie::raw(name, value)` writes
the value as it is, as Laravel's `Cookie::make` does with `raw: true`:

```rust
use suprnova::{Cookie, FrameworkError, HttpResponse};

fn with_token() -> Result<HttpResponse, FrameworkError> {
    let cookie = Cookie::raw("token", "a:b/c")?;
    assert!(cookie.is_raw());
    assert!(cookie.to_header_value().starts_with("token=a:b/c;"));
    Ok(HttpResponse::text("ok").cookie(cookie))
}
```

The encoding is what keeps an ordinary value from injecting a header or
an attribute, so `Cookie::raw` checks its input instead. It returns an
error when the name is not an RFC 6265 token, or when the value holds a
byte outside cookie-octet: a space, `"`, `,`, `;`, `\`, a control byte
such as a carriage return, or a byte above `0x7E`. `Cookie::raw("t",
"x;Domain=evil")` is an error, not a second attribute. A raw cookie keeps
the defaults of `Cookie::new` (`HttpOnly`, `Secure`, `SameSite=Lax`,
`Path=/`), every builder call, and the `__Host-` and `__Secure-` rules.

The read side cannot tell which cookies were written raw. A request
carries only names and values, so `parse_cookies` decodes every value,
as PHP decodes `$_COOKIE` for Laravel. A raw value that holds `%`
followed by two hex digits reads back decoded: `Cookie::raw("t",
"100%25")` reads back as `100%`.

### Queueing a cookie for later

Sometimes code that isn't building the response still needs to set a
cookie - a listener reacting to an event, a piece of middleware that
runs ahead of the handler, an `App::bind` service with no `HttpResponse`
in scope. `Cookie::queue` is Laravel's `Cookie::queue()`: it stashes the
cookie in a per-request jar that `SessionMiddleware` drains onto the
outgoing response, right after the session cookie.

```rust
use suprnova::Cookie;

Cookie::queue(Cookie::new("theme", "dark"));

// Look up what's queued.
let queued = Cookie::queued("theme");

// Remove it before the response goes out.
Cookie::unqueue("theme");

// Queue a deletion instead of a value - composes with `forget_with`.
Cookie::expire("theme", Some("/app"), None);
```

The jar is task-local and freshly empty for every request - nothing
queued on one request is visible on the next, and a value queued but
never drained (no `SessionMiddleware` in the route's chain) is dropped
rather than panicking. Queued cookies attach to whatever the handler
returns, including a redirect: a handler that queues a cookie and then
returns `Redirect::to(...)` still carries the `Set-Cookie` header on
the 3xx response. They also attach to a 500 that `SessionMiddleware`
builds itself for an internal failure partway through the request - an
existing session that can't be read, a session write that fails, or
session-cookie encryption failing - because a queued cookie can already
represent a side effect committed elsewhere (a remember-me token row
already written, for instance), so the response reporting the failure
still carries it. They do **not** survive a panic - `SessionMiddleware`'s
draining code runs after the handler returns normally, and a caught
panic is converted to a 500 outside the whole middleware chain, the
same point where Laravel's own queued cookies are lost to an uncaught
exception.

### Why Suprnova diverges

Laravel's `CookieJar` keys the queue by name *and* path, so two cookies
with the same name at different paths can be queued independently.
Suprnova keys the jar by name only: queuing a second cookie under a
name already queued replaces the first rather than adding a second
`Set-Cookie` line for it. That covers the common case - one call site
owns a given cookie name - without the extra path-keyed lookup
Laravel's version needs.

## Redirects

`Redirect` covers the full Laravel redirector surface. Every variant
implements `From<Redirect> for Response`, so the idiomatic form is
`Redirect::...().into()`.

### Targets

```rust
use suprnova::{Redirect, redirect_to};

// Explicit URL or path
let _ = Redirect::to("/dashboard");

// Same thing, slightly shorter free function
let _ = redirect_to("/dashboard");

// Named route (returns RedirectRouteBuilder)
let _ = Redirect::route("users.show").with("id", "42");

// Explicit external URL - same as `to`, but the name signals
// "this is going off-site" for open-redirect audits
let _ = Redirect::away("https://external.example.com");

// Refresh the page (reads previous URL from the session; falls back
// to "/" if no session scope is active)
let _ = Redirect::refresh();

// Same, but taking an explicit Request when no scope is active
// let _ = Redirect::refresh_for(&request);

// Session previous_url, with fallback when no session is in scope
let _ = Redirect::back("/login");

// Session-stored intended URL, consumed on read, with fallback
let _ = Redirect::intended("/home");

// Guest redirect: stores the URL to come back to as "intended" and
// sends the user to a login page
// let _ = Redirect::guest(&request, "/login");
```

`Redirect::back`, `Redirect::intended`, `Redirect::guest`, and
`Redirect::refresh` all integrate with the session. Without a session
scope they fall through to their defaults silently - handy for
partial test setups. See [Session](session.md).

`Redirect::back`'s target - the session's recorded previous URL - is
never trusted verbatim. The session middleware only records a
root-relative, same-origin URL in the first place (a path starting
with `//` or `/\`, or carrying an ASCII control byte anywhere in it, is
never stored), and the same check runs again on every read, so `back`
can't be steered off-origin either by a request that reaches your app
with an unusual path or by a session cookie written before this guard
existed. See [Session](session.md#other-operations) for the full rule.

`Redirect::guest` stores the URL that `Redirect::intended` sends the user
to after sign-in, as Laravel's `redirect()->guest()` does:

- A `GET` that does not expect JSON stores its own public root, path and
  query, such as `/billing/invoices?page=2`. That is a page you can send
  the user back to.
- Any other request - a `POST`, a `DELETE`, or a `GET` that expects JSON
  (`Request::expects_json`) - stores the session's previous URL, the page
  the user was on. Sending the browser back to a form submission or an
  API call after sign-in would replay it as a `GET` or show raw JSON.
  With no previous URL recorded, nothing is stored.

`guest` never reads the `Referer` header, which the client sets; Laravel
falls back to it through `url()->previous()`. Both sources pass the same
same-site check `back` uses, and when nothing is stored, `guest` removes
any intended URL already in the session, so `intended` goes to its
fallback rather than to a stale page.

### Named-route validation

The `redirect!` proc-macro validates the route name at compile time
and expands to `Redirect::route(name)`:

```rust
use suprnova::{redirect, Response};

pub async fn store() -> Response {
    // Compile fails if "users.index" is not a registered route name;
    // the error message lists available routes and suggests close matches.
    redirect!("users.index").into()
}
```

### Status codes

```rust
use suprnova::Redirect;

let _ = Redirect::to("/x").permanent();      // 301
let _ = Redirect::to("/x").status(303);      // 303, 307, 308, ...
```

The default is 302.

### Flash data

Redirect builders carry their own flash bag. On conversion to a
`Response` the bag drains into the live session, surviving exactly
one more request:

```rust
use suprnova::Redirect;

let _ = Redirect::back("/users/new")
    .with("status", "User created")            // single key/value
    .with_input([                              // repopulate form
        ("email", "shawn@example.com"),
        ("name", "Shawn"),
    ])
    .with_errors([                             // default error bag
        ("email", "Must be unique"),
    ])
    .with_errors_bag("login", [                // named error bag
        ("password", "Required"),
    ]);
```

The receiving page reads these back through `session.get(...)` (for
`with`), `session.get_old_input(...)` (for `with_input`), and the
bag map drained by `session.pull_errors_flash()` (for
`with_errors` / `with_errors_bag`). The Inertia layer consumes the
errors-flash automatically - every Inertia response's `errors` prop
is seeded from the session, so `Redirect::back().with_errors(...)`
surfaces messages on the destination without extra wiring. The
`X-Inertia-Error-Bag` request header scopes the prop under a named
bag for multi-form pages.

Note that on `RedirectRouteBuilder` (what `Redirect::route` and
`redirect!` return), `.with(key, value)` sets a **route parameter**,
not a flash entry - use `.flash(key, value)` there:

```rust
use suprnova::redirect;

let _ = redirect!("users.show")
    .with("id", "42")                          // route param
    .flash("status", "Updated");               // session flash
```

### Cookies, headers, fragments

```rust
use suprnova::{Cookie, Redirect};

let _ = Redirect::route("billing.show")
    .with_cookies([Cookie::new("welcome", "yes")])
    .with_headers([("X-Trace", "abc")])
    .with_fragment("invoices")                 // append #invoices
    .without_fragment();                       // OR strip any prior fragment
```

`with_fragment` accepts the fragment with or without a leading `#`.
Calling `with_fragment` after `without_fragment` re-attaches one.

### Preserve fragment across the redirect

For Inertia apps where the destination should preserve the
*originating* URL hash, use `preserve_fragment`:

```rust
use suprnova::Redirect;

let _ = Redirect::route("dashboard.index").preserve_fragment();
```

On conversion this flashes `_inertia.preserve_fragment = true` into
the session; the next Inertia response reads the flag and emits
`preserveFragment: true` in its page object. No session scope - flag
silently dropped.

### Signed redirects

Two builders wrap the URL-signing surface for one-shot redirects to
named routes (password reset, email verification, download links):

```rust
use suprnova::Redirect;

let r = Redirect::signed_route("downloads.show", &[("id", "42")])?;
let r = Redirect::temporary_signed_route(
    "downloads.show",
    &[("id", "42")],
    1_700_000_000, // expires_at_epoch_seconds
)?;
```

Both return `Result<Redirect, FrameworkError>` - `?`-propagate the
error since `Redirect` converts to a `Response` cleanly. See
[URLs](urls.md) for the signing surface.

### Storing the intended URL

`Redirect::set_intended_url` writes the session's intended target
without performing a redirect - typically called from auth middleware
before redirecting to `/login`, so a later `Redirect::intended` can
recover the originally-requested URL:

```rust
suprnova::Redirect::set_intended_url("/admin/users");
```

`Redirect::intended` follows three kinds of stored value: a path that
starts with a single `/`, an absolute `http` or `https` URL, and a relative
reference such as `?tab=2`. It ignores anything else and redirects to its
fallback instead:

- a value that starts with `//`, `/\` or `\`;
- a value with surrounding whitespace, a control character or a
  backslash;
- another scheme, such as `javascript:` or `mailto:`.

A browser trims whitespace, reads `\` as `/` and reads `//host/x` as
another host, so each of these could leave the application.
`Redirect::intended_url()` reads the same value by the same rules without
consuming it.

To send a user to another site after sign-in, store the absolute URL
(`https://example.com/x`). Check an address that comes from a query, such
as a `return_to` parameter, with `url::same_origin_path` before you store
it. Otherwise anyone can write a link that sends your users to another
site after they sign in:

```rust
if let Some(path) = request
    .query_param("return_to")
    .and_then(|candidate| suprnova::url::same_origin_path(&candidate))
{
    suprnova::Redirect::set_intended_url(path);
}
```

## Aborting from a handler

Three free functions short-circuit a handler at a given status. They
return `Result<(), FrameworkError>`; combine with `?`:

```rust
use suprnova::{abort_if, abort_unless, abort_with, json_response, Request, Response};

pub async fn show(req: Request) -> Response {
    abort_unless(Auth::user().await?.is_some(), 401, "must be logged in")?;
    abort_if(req.param("id")? == "0", 404, "User not found")?;
    abort_with(503, "scheduled maintenance")?;
    json_response!({ "ok": true })
}
```

The underlying error is `FrameworkError::Domain { message, status_code }`,
so it renders through the same JSON envelope and 5xx sanitisation rules
as every other error path. Out-of-range status codes are coerced to
500 by the response renderer. See [Error Model](error-model.md) for
the full conversion contract.

## Returning errors directly

Because `Response` is `Result<HttpResponse, HttpResponse>`, you can
return an `Err` arm directly - useful when the response shape is
already a specific JSON body and you want it on the wire as-is:

```rust
use suprnova::{HttpResponse, Response};
use serde_json::json;

pub async fn legacy_lookup() -> Response {
    Err(HttpResponse::json(json!({
        "error": "deprecated endpoint",
    })).status(410))
}
```

For anything richer - typed domain errors, validation, observability -
use the [Error Model](error-model.md) surface (`AppError`,
`FrameworkError`, `#[domain_error]`).

## Quick reference

| Need | Use |
|---|---|
| JSON response | `HttpResponse::json(v)` or `json_response!({...})` |
| Text response | `HttpResponse::text(s)` or `text_response!(s)` |
| HTML response | `HttpResponse::html(s)` |
| Raw bytes + content-type | `HttpResponse::bytes_body(b, "image/png")` |
| Server-Sent Events | `HttpResponse::sse(stream)` - see [SSE](sse.md) |
| Chunked stream | `HttpResponse::stream_bytes(stream)` |
| Show a file inline | `HttpResponse::file(path, name).await` |
| Download a file | `HttpResponse::download(path, name).await` |
| Download generated bytes | `HttpResponse::download_bytes(bytes, name, content_type)` |
| Download generated chunks | `HttpResponse::stream_download(stream, name, content_type)` |
| Serve a file from a disk | `Storage::response(disk, path, name).await` / `Storage::download(disk, path, name).await` |
| `Content-Disposition` value | `ContentDisposition::Attachment.header_value(name)` |
| Set status | `.status(code)` |
| Add header | `.header(k, v)` / `.with_headers([...])` |
| Remove header | `.without_header(name)` |
| Attach cookie | `.cookie(c)` / `.with_cookies([...])` |
| Forget cookie | `.without_cookie(name)` / `.without_cookies([...])` |
| Forget a path/domain-scoped cookie | `Cookie::forget_with(name, Some("/admin"), Some("example.com"))` |
| Queue a cookie for the next response | `Cookie::queue(c)` |
| Look up a queued cookie | `Cookie::queued(name)` |
| Remove a cookie from the queue | `Cookie::unqueue(name)` |
| Queue a deletion cookie | `Cookie::expire(name, path, domain)` |
| Simple redirect | `Redirect::to(path).into()` or `redirect_to(path).into()` |
| Named-route redirect | `redirect!("name").into()` or `Redirect::route("name")` |
| Back redirect | `Redirect::back(fallback)` |
| Intended redirect | `Redirect::intended(default)` |
| Guest redirect (stash intended) | `Redirect::guest(&req, login)` |
| Set intended target | `Redirect::set_intended_url(url)` |
| External URL | `Redirect::away(url)` |
| Refresh current page | `Redirect::refresh()` / `Redirect::refresh_for(&req)` |
| Signed-route redirect | `Redirect::signed_route(name, &[(k, v)])?` |
| Route param on redirect | `.with("key", "value")` |
| Query param on redirect | `.query("key", "value")` |
| Flash data | `.with(key, value)` (or `.flash` on `RedirectRouteBuilder`) |
| Flash input | `.with_input([(k, v), ...])` |
| Flash errors | `.with_errors([(k, msg), ...])` |
| Named error bag | `.with_errors_bag(bag, [(k, msg)])` |
| Append fragment | `.with_fragment("section")` |
| Strip fragment | `.without_fragment()` |
| Preserve fragment (Inertia) | `.preserve_fragment()` |
| Permanent redirect | `.permanent()` (301) |
| Custom redirect status | `.status(303)` |
| Abort early | `abort_with(code, msg)?`, `abort_if(cond, code, msg)?`, `abort_unless(cond, code, msg)?` |

## Next

- [Error Model](error-model.md) - `FrameworkError`, `AppError`,
  `HttpError`, and the single conversion that renders every error to
  an `HttpResponse`
- [Error Handling](errors.md) - practical handler patterns for `?`,
  `AppError`, and custom domain errors
- [Server-Sent Events](sse.md) - building and consuming `sse(...)`
  responses
- [Filesystem & Storage](filesystem.md) - disks, and serving a file from
  one with `Storage::response` and `Storage::download`
- [URLs](urls.md) - signed URLs, named-route resolution, the
  surface behind `Redirect::signed_route`
- [Session](session.md) - flash data, intended URLs, the bag
  `Redirect::with`/`with_input`/`with_errors` writes into


---

<!-- /docs/urls -->

# URL Generation

URLs are how your app references itself - every redirect, every email link,
every Inertia `<Link>` href, every signed download has to come from
somewhere. Hard-coding paths makes refactors painful and route renames
unsafe. Suprnova ships a small `url::` namespace and a sibling
`route()` helper that take a name plus parameters and give you back a
string, with percent-encoding handled, signature minting available, and
verification that matches Laravel's wire format byte-for-byte.

This chapter is the reference for the URL-generation surface. The
[Routing](routing.md) chapter covers how to declare routes and name them;
this one covers what you do with those names afterwards.

```rust
use suprnova::{route, url};

// Lookup by name → URL
let profile = route("users.show", &[("id", "42")]).unwrap();
//   "/users/42"

// Absolute URL against APP_URL
let absolute = url::to("/dashboard");
//   "https://app.test/dashboard"

// Signed link for password reset
let link = url::signed_route("password.reset", &[("token", reset_token)])?;
//   "/password/reset/xyz?signature=ab12..."

// Verify on the inbound request
if url::has_valid_signature(&request)? {
    // act on it
}
```

Everything in this chapter is re-exported under `suprnova::url::*` and
`suprnova::route` so consumer code never has to reach into the routing
module directly.

## Named routes

A name is a string label attached to a route at registration time. Once a
name exists, `route(name, params)` resolves it back to a URL pattern and
substitutes the parameters. Names live in a single process-global
registry - there is one `name → path` table per running binary, not one
per `Router`.

```rust
use suprnova::{routes, get, post};

routes! {
    get!("/", controllers::home::index).name("home"),
    get!("/users/{id}", controllers::users::show).name("users.show"),
    post!("/users", controllers::users::store).name("users.store"),
}
```

The `.name(...)` call registers `"users.show" → "/users/{id}"`. From
that point on, anywhere in the process can resolve the name:

```rust
use suprnova::route;

let url = route("users.show", &[("id", "42")]);
// Some("/users/42")

let missing = route("does.not.exist", &[]);
// None
```

Behind a reverse proxy that serves the application under a path prefix,
`route()` puts the public root in front of the path: under
`X-Forwarded-Prefix: /billing` from a trusted proxy, the call above returns
`Some("/billing/users/42")`. At the host root the output is unchanged. A
redirect or URL builder given this output keeps the root once. For the
proxy setup, see [Serving under a path prefix](deployment.md#serving-under-a-path-prefix).

Re-registering the same `(name, path)` pair is idempotent - useful when
route registration runs more than once during boot. Registering a name
under a *different* path panics; that collision is a security-shaped
bug because helpers like `Redirect::route` would silently target
whichever side won the race.

### Bound values

A parameter takes a string, a number, or a bound value. A bound value is
a value whose type implements `RouteValue`: a `#[model]` row, a
`#[derive(RouteBinding)]` enum, and a `RouteParam<T>` do. A bound value
fills a `{post}` parameter with its route key and a `{post:slug}`
parameter with its `slug` column, encoded as any value is:

```rust
use suprnova::route;

// get!("/posts/{post:slug}", ...).name("posts.show")
let url = route("posts.show", &post);
// Some("/posts/hello-world")

// One value fills the route's first parameter. Name the values to fill
// several, mixing strings and bound values:
let url = route("users.posts.show", (("user", &user), ("post", &post)));
// Some("/users/7/posts/hello-world")
let url = route("users.posts.show", (("user", "7"), ("post", "hello-world")));
```

A type that implements `RouteBinding` by hand, and a bare SeaORM model
whose entity implements `EntityExt`, become bound values with one call to
`bound_route_value`:

```rust
impl suprnova::RouteValue for Region {
    fn route_value(&self, field: Option<&str>) -> Option<String> {
        suprnova::bound_route_value(self, field)
    }
}
```

Every call written with `&[("name", "value")]` pairs keeps working and
builds the same URL, except the forms below. They compiled only because
the parameter used to be a `&[(&str, &str)]` slice, which set the type of
the pairs or converted them to it:

- A name or value whose type the parameter inferred: `s.as_ref()`,
  `s.borrow()`, `Default::default()`.
- A name or value that reaches `&str` through more than one dereference,
  or through a type of the application's own: `&&&str`, `&Box<String>`.
- A container of pairs reached the same way: `&&&Vec<_>`,
  `&Box<Vec<_>>`, a `SmallVec`.
- An array whose pairs mix `&String` and `&str` values, such as
  `&[("id", &id), ("tab", "posts")]`.
- An array of more than 32 pairs that holds `&String` values.
- `route` used as a `fn(&str, &[(&str, &str)]) -> Option<String>` pointer.

Write a name or value with `.as_str()` or `&*`, and a container with
`.as_slice()` or `&*`. In place of the pointer, write a closure:

```rust
use suprnova::route;

let url = route("users.show", &[("id", id.as_str()), ("tab", "posts")]);
// `boxed_id` is a `Box<String>`, `pairs` a `SmallVec<[(&str, &str); 4]>`.
let url = route("users.show", &[("id", &*boxed_id)]);
let url = route("users.show", pairs.as_slice());

let build: fn(&str, &[(&str, &str)]) -> Option<String> =
    |name, params| route(name, params);
```

### The public root

`url::root()` returns the public root on its own: `/billing` behind a
trusted `X-Forwarded-Prefix: /billing`, the path in `APP_URL` when no
trusted prefix arrives, and the empty string at the host root, never with
a trailing slash. It is the way a
template writes a root-relative link that `route()` does not build, such as
a component stylesheet:

```html
<link rel="stylesheet" href="{{ suprnova::url::root() }}/suprnova-ui/button/button.css">
```

The root followed by a path that starts with `/` is a link that works at
every root. `url::root()` carries no capability, so a third-party
component's view may call it too, in exactly this form.

### The lookup helpers

| Function | Returns | When the route is missing |
|---|---|---|
| `route(name, params)` | `Option<String>` | `None` |
| `route_with_params(name, params_map)` | `Option<String>` | `None` |
| `try_route(name, params)` | `Result<String, RouteUrlError>` | `Err(NameNotFound)` |
| `try_route_with_params(name, params_map)` | `Result<String, RouteUrlError>` | `Err(NameNotFound)` |

The lenient `route` / `route_with_params` pair leaves any unfilled
`{placeholder}` segment verbatim in the output - fine for debug logs,
unsafe to ship to a browser. The strict `try_route` / `try_route_with_params`
pair returns `RouteUrlError::MissingParams { name, missing }` listing the
unfilled placeholders so the caller can fail loudly instead of redirecting
a user to `/users/{id}`.

```rust
use suprnova::routing::{try_route, RouteUrlError};

match try_route("users.show", &[]) {
    Ok(url) => /* safe to redirect */,
    Err(RouteUrlError::MissingParams { name, missing }) => {
        // missing == vec!["id"]
        return Err(FrameworkError::internal(
            format!("cannot build URL for {name}: missing {missing:?}"),
        ));
    }
    Err(RouteUrlError::NameNotFound(name)) => {
        return Err(FrameworkError::internal(format!("unknown route: {name}")));
    }
}
```

`Redirect::route` uses `try_route_with_params` under the hood for exactly
this reason - a redirect with a raw `{id}` in the `Location` header would
be worse than failing.

### Percent-encoding is automatic

Parameter values are encoded per RFC 3986 path-segment rules before they
are substituted in. That covers the gen-delims and sub-delims
(`/ ? # [ ] @ ! $ & ' ( ) * + , ; =`), control characters, space, and
`%` itself. Unreserved characters (`A-Z a-z 0-9 - _ . ~`) pass through
unchanged.

```rust
use suprnova::route;

// A slug containing a slash is contained in one segment:
route("posts.show", &[("slug", "hello/world")]);
// Some("/posts/hello%2Fworld")

// Path traversal attempts can't escape the segment:
route("users.show", &[("id", "../../etc/passwd")]);
// Some("/users/..%2F..%2Fetc%2Fpasswd")

// Real Unicode passes through untouched:
route("users.show", &[("id", "user-é-42")]);
// Some("/users/user-%C3%A9-42")
```

The matching side preserves this round-trip - a request to
`/posts/hello%2Fworld` matches the `/posts/{slug}` route and a handler
reading `req.param("slug")` sees `"hello/world"`, decoded. Encode at the
boundary, decode at the boundary; never see the raw bytes in handler code.

### Reverse lookup

When you have a matched route pattern and want the registered name -
e.g. for logging or for `Request::route_is("users.show")` checks - use
`route_name_for_pattern`:

```rust
use suprnova::routing::route_name_for_pattern;

let name = route_name_for_pattern("/users/{id}");
// Some("users.show")
```

This is an O(n) scan over the name registry. n is the number of
registered names; even at four-digit route counts the cost is negligible
compared to the surrounding request lifecycle. The function is exposed
for tooling and middleware - `Request::route_is` already calls it for
you when you compare against a named route in a handler.

## Absolute URLs

For everything else - building emails, sharing URLs, sending Open Graph
metadata - you want an absolute URL with the right scheme and host.
`url::to` joins a path to `APP_URL`:

```rust
use suprnova::url;

// In env: APP_URL=https://app.example.com
let url = url::to("/about");
// "https://app.example.com/about"

// Already-absolute URLs pass through unchanged:
let cdn = url::to("https://cdn.example/asset.js");
// "https://cdn.example/asset.js"

let proto_relative = url::to("//cdn.example/asset.js");
// "//cdn.example/asset.js"
```

The host, scheme, and port all come from `APP_URL`. If `APP_URL` is
`http://localhost:8765`, then `url::to("/foo")` yields
`"http://localhost:8765/foo"`. The trailing slash on `APP_URL` is
normalised away so you never end up with `https://host//path`.

The path between the host and your path is the public root: the path in
`APP_URL`, or a trusted `X-Forwarded-Prefix` of the request being handled,
which replaces it. With `APP_URL=https://example.org/billing`,
`url::to("/foo")` yields `"https://example.org/billing/foo"`, and
`url::to("/billing/foo")` yields the same URL, because a path that already
carries the root keeps it once.

### Forcing HTTPS

`url::secure(path)` builds the same absolute URL but upgrades the scheme
to `https://` even if `APP_URL` is `http://`:

```rust
use suprnova::url;

// In env: APP_URL=http://app.example.com
url::secure("/login");
// "https://app.example.com/login"
```

In production you typically set `APP_URL` to your HTTPS host once and
never call `secure` directly - the upgrade is for environments where
local development runs over HTTP but a specific link must be HTTPS
(e.g. a callback URL embedded in a payment session).

`url::secure_with(path, segments)` appends each segment to the path
before the upgrade, as Laravel's `url()->secure($path, $parameters)`
does. Each segment is percent-encoded as one path segment, with the
encoding `route()` uses for a parameter, so a value with a space or a
slash stays one segment:

```rust
use suprnova::url;

// In env: APP_URL=http://app.example.com
url::secure_with("users", &["a b", "7"]);
// "https://app.example.com/users/a%20b/7"

url::secure_with("/files", &["2026/report.pdf"]);
// "https://app.example.com/files/2026%2Freport.pdf"
```

The segments go before any query or fragment in `path`. Laravel drops
the segments when `path` is already an absolute URL; `secure_with`
appends them there too.

### Reading the current URL

Inside a handler, the request itself is the source of truth:

```rust
use suprnova::url;

// In env: APP_URL=https://app.test, request: GET /posts/42?expand=author
async fn breadcrumbs(req: Request) -> Response {
    let here = url::current(&req);       // "https://app.test/posts/42"
    let full = url::full(&req);          // "https://app.test/posts/42?expand=author"
    let back = url::previous("/");       // session-recorded previous URL
    let from = url::previous_path("/");  // "/posts" after a previous "/posts/?page=2"
    // ...
}
```

| Helper | Returns | Source |
|---|---|---|
| `url::current(&req)` | absolute URL of this request, without the query | `APP_URL` origin + public root + path |
| `url::full(&req)` | absolute URL of this request, with the query | `APP_URL` origin + public root + path + query, its pairs sorted by key and re-encoded (`/posts?b=2&a=1` gives `?a=1&b=2`) |
| `url::previous(fallback)` | previous URL recorded by the session middleware | `_previous.url` in the session, or `fallback` |
| `url::previous_path(fallback)` | the path of `previous(fallback)` | `previous(fallback)` without query, root or trailing slash |

`current` and `full` take the scheme, host and port from `APP_URL`, never
from the `Host` header, so a client cannot change the origin they return.
Both carry the public root: behind a trusted `X-Forwarded-Prefix: /billing`,
`current` for `/invoices` returns `https://app.test/billing/invoices`.

`previous_path` is the value to compare with a route's path, because a
route's path carries neither the root nor the query. Under the root
`/billing`, a previous URL of `/billing/invoices/?page=2` gives
`/invoices`. When nothing is left, such as for the root itself, you get
`/`. With no previous URL recorded, the same is done to `fallback`.

`previous` is what backs `Redirect::back` - the session middleware
records the URL of every successful HTML GET so a form `POST` can bounce
back to the page that submitted it. Inertia partials, JSON-API requests
(`Accept: application/json` without `text/html`), and non-2xx/3xx
responses are skipped so you never bounce back to an intermediate
endpoint the user never saw. The middleware also refuses to record a
URL that isn't root-relative and same-origin: a request path shaped
like `//host` or `/\host` (both of which a browser reads as
protocol-relative, not a path) or carrying an ASCII control byte
anywhere in it (a `TAB` or newline that a browser's URL parser strips
before comparing origins, turning what looks like a safe path into one
of the two forms above) is never stored - and the same check runs
again on every read, so a value stored by an older release keeps
failing it too, rather than being trusted only because it's already in
the session. Either way, `previous` and `Redirect::back` can't be
steered off-origin by an unusual request path reaching your app, past
or present.

## Signed URLs

Signed URLs let you mint a URL that proves it came from your server,
without storing the URL anywhere. The signature is HMAC-SHA256 over the
canonical form of the URL using your `APP_KEY`; the server recomputes
the HMAC on the inbound request and accepts only matching signatures.

Reach for signed URLs when:

- **Email-delivered links** - password reset, email verification,
  invite-by-email, magic-link login. The URL has to survive a round trip
  through an inbox without being storable as opaque state.
- **Ephemeral downloads** - "your CSV export is ready" links that expire
  in 24 hours, signed S3 alternatives where you want the URL to remain
  on your domain.
- **Webhooks pointing back at you** - third-party callbacks that should
  refuse forged calls without requiring a database lookup per request.

```rust
use suprnova::url;
use chrono::Utc;

// Permanent signed URL - never expires.
let link = url::signed_route(
    "password.reset",
    &[("user", user_id), ("token", token)],
)?;
// "/password/reset/42/xyz?signature=ab12cd34..."

// Temporary signed URL - expires one hour from now.
let expires_at = Utc::now().timestamp() + 3600;
let link = url::temporary_signed_route(
    "verify.email",
    &[("user", user_id)],
    expires_at,
)?;
// "/verify/email/42?expires=1748803600&signature=def012..."
```

Note that `expires_at_epoch_seconds` is an **absolute UNIX timestamp**,
not a duration. Compute it at the call site:

```rust
let one_hour_from_now = chrono::Utc::now().timestamp() + 3600;
let one_day_from_now  = chrono::Utc::now().timestamp() + 86_400;
```

That keeps the helper signature small and lets you reuse the same
function for both relative-from-now and explicit-absolute deadlines.

### Verifying

On the inbound side, you verify the signature against the live request:

```rust
use suprnova::{url, AppError, FrameworkError, Request, Response, HttpResponse};

pub async fn reset(req: Request) -> Response {
    reset_inner(req).await.map_err(HttpResponse::from)
}

async fn reset_inner(req: Request) -> Result<HttpResponse, FrameworkError> {
    if !url::has_valid_signature(&req)? {
        return Err(AppError::forbidden("Invalid or expired link").into());
    }
    // Signature is good and not expired - proceed.
    let user_id = req.param("user").unwrap();
    // ...
    Ok(HttpResponse::text("ok"))
}
```

The signature covers the public root as well as the path, because the
browser sends both back: a link signed behind a `/billing` prefix verifies
behind it, and not under another root or at the host root. Moving an
application under a prefix therefore ends the links signed before the move.

`has_valid_signature` returns `true` only when the HMAC matches AND the
URL is not expired. For the three-way distinction between *invalid*,
*expired*, and *valid*, use `signature_verdict`:

```rust
use suprnova::{url, AppError, FrameworkError, HttpResponse, Request, Response};
use suprnova::routing::SignatureVerdict;

pub async fn reset(req: Request) -> Response {
    reset_inner(req).await.map_err(HttpResponse::from)
}

async fn reset_inner(req: Request) -> Result<HttpResponse, FrameworkError> {
    match url::signature_verdict(&req)? {
        SignatureVerdict::Valid => {
            // Proceed.
        }
        SignatureVerdict::Expired => {
            // Bounce the user to a page that explains the link expired
            // and offers to send a fresh one.
            return Ok(HttpResponse::new()
                .status(302)
                .header("Location", "/password/reset-expired"));
        }
        SignatureVerdict::Invalid => {
            // Render a generic 403 - don't leak whether the signature
            // was malformed, missing, or just wrong.
            return Err(AppError::forbidden("Invalid link").into());
        }
    }
    // ...
    Ok(HttpResponse::text("ok"))
}
```

`signature_has_not_expired(&req)` is deprecated and now answers exactly
what `has_valid_signature` answers. Reach for `signature_verdict` above
instead; a URL with no `expires` query parameter is "never expired" by
definition, in Suprnova as in Laravel.

### Protecting a route with the signature middleware

`ValidateSignature` puts the check on the route, so a handler cannot
forget it. A request with a valid signature reaches the handler. Every
other request - a missing, wrong, or expired signature alike - gets `403`
with the message `Invalid signature.` in the framework's usual JSON error
body, as Laravel's `InvalidSignatureException` answers:

```rust
use suprnova::routing::ValidateSignature;
use suprnova::Router;

let router = Router::new()
    .get("/verify/email/{user}", controllers::verify::email)
    .middleware(ValidateSignature::new())
    .name("verify.email");
```

To name it as Laravel does, register the `signed` alias once at boot.
`signed:relative` reads `relative` first, then the parameters to ignore:

```rust
use suprnova::middleware::register_middleware_alias_with_args;
use suprnova::routing::ValidateSignature;

register_middleware_alias_with_args("signed", ValidateSignature::from_alias_args);

// .middleware_named("signed")
// .middleware_named("signed:relative,utm_source")
```

Suprnova signs the public root, the path and the sorted query of every
URL, never the scheme or the host. `ValidateSignature::new()` and
`ValidateSignature::relative(ignore)` therefore verify the same text;
`relative` exists so a route written for Laravel's `signed:relative`
keeps its meaning. One answer for all three failures keeps the response
from telling a prober what failed. When you want to tell an expired link
from a forged one, match on `signature_verdict` in the handler instead.

### Ignoring parameters added after signing

A mail client or a campaign tool can append a parameter, such as
`utm_source`, to a signed link. That parameter is not part of the text the
signature covers, so the link stops verifying. Name the parameters to
leave out of the verified text:

```rust
use suprnova::routing::ValidateSignature;
use suprnova::url;

// On one route.
let middleware = ValidateSignature::new().ignore(["utm_source"]);

// For every ValidateSignature in the application, at boot.
ValidateSignature::except(["utm_campaign"]);

// In a handler, without the middleware.
if url::has_valid_signature_ignoring(&req, &["utm_source"])? {
    // act on it
}
```

Every pair of an ignored parameter is left out, repeats included. The
path, the root and every other parameter stay covered, so a changed
signed value still fails. `signature` and `expires` cannot be ignored: a
repeated `signature` or `expires` is still refused, and the expiry is
still checked. Treat the value of an ignored parameter as unsigned client
input. `ValidateSignature::except` applies to the middleware only, as
Laravel's `$neverValidate` does; `has_valid_signature_ignoring` leaves out
exactly the names you pass.

### Why Suprnova diverges

Laravel's `URL::signatureHasNotExpired($request)` is literally
"not expired", so a **forged** signature comes back `true` - it never had
an expiry to miss. Suprnova's used to match that. It doesn't any more: the
helper requires a valid signature first.

The reason is that `expires` is attacker-supplied until the HMAC says
otherwise, so no answer derived from it means anything before the signature
checks out - and a function whose name reads like a guard was letting every
forged URL through anything that called it alone.

Requiring validity collapses it into `has_valid_signature`, which is why it
carries a deprecation rather than a behaviour flag. That collapse is not a
loss: under a three-state verdict there is no "not expired" a single `bool`
can report honestly except `Valid`. If you want to tell *expired* from
*invalid* - to say "request a fresh link" instead of "forbidden" - that is
what `signature_verdict` is for, and it says it in the type.

### Signing arbitrary URLs

If the URL you want to sign doesn't come from a registered named route -
a callback URL handed to you by a third party, a path constructed
dynamically at runtime - use `signed_url` directly:

```rust
use suprnova::url;

let callback = url::signed_url(
    "/webhooks/stripe/callback?order=42",
    Some(chrono::Utc::now().timestamp() + 600),  // 10-minute expiry
)?;
```

Pass `None` for the expiration to mint a permanent signature. The verify
side is the same - `has_valid_signature(&req)` doesn't care whether the
URL was minted from a named route or from a raw path.

### Wire format

Two URLs that differ only by the order of their query parameters
produce identical signatures because the canonical form sorts query pairs
by key before hashing. That matters because clients sometimes reorder
query parameters in transit (proxies, link previewers, mobile email
apps), and a signed URL that breaks under reordering would be unusable.
The values of one repeated key are the exception: their order is signed,
because it decides what a handler reads.

| Component | Value |
|---|---|
| Algorithm | HMAC-SHA256 |
| Key | Active `APP_KEY` raw bytes |
| Payload | `path?<sorted-query>` (omit `?` when no params) |
| Sort order | By key, stable - every pair, repeats included in their original order |
| Encoding | Hex-encoded 64-character digest |
| Comparison | Constant-time via `subtle::ConstantTimeEq` |
| Reserved keys | `signature`, `expires` |

**Repeated keys are signed, not collapsed.** `?tag=a&tag=b` carries both
values into the payload, in that order, so none can be added, removed,
substituted, or swapped without breaking the signature. The order matters
because `query_param` returns a repeated key's last value: if
`?mode=a&mode=b` and `?mode=b&mode=a` shared a signature, a client could
swap them and change what the handler acts on. The signer keeps the order
you pass. A URL signed by an earlier version, which sorted repeated values
by value, still verifies.

This is worth stating because the alternative bites hard. An earlier
version canonicalised into a map, which kept only the last value for a
repeated key. `Request::query_param` returned the *first*. So a
legitimately signed `?user=victim` could be replayed as
`?user=attacker&user=victim` with the original signature: verification
saw `victim` and passed, and the handler acted on `attacker`. Signed and
executed were different URLs. All three query accessors - `query_param`,
`query_params`, and `Context::query_param` - now resolve a repeated key
to its last value, and the canonical form loses nothing.

A repeated `signature` or `expires` is refused outright. Those are
control parameters; two of either leaves no non-arbitrary answer to
"which one governs?", and the verifier should not be the component
guessing.

The HMAC payload excludes any pre-existing `signature` query parameter
(so signing-over-signing is a no-op) and re-emits a fresh `expires` value
from the call arguments. A client that strips or rewrites the `expires`
breaks the signature; a client that strips the `signature` fails as
`Invalid`. Both fail closed.

The fragment (`#section`) is stripped from the canonical form because
browsers never transmit fragments back to the server. Signing over a
fragment would invalidate every link the moment a client appended an
anchor - `?signature=...#docs` would not verify on the server side.

### Reserved query parameters

`signature` and `expires` are reserved query-parameter names. A route
that legitimately expects a query parameter called `signature` or
`expires` would collide with the signed-URL machinery, and the verifier
would mis-attribute the value. Either rename the parameter or wrap the
route's incoming parameters under a different namespace.

```rust
// Bad - `signature` collides with the reserved name.
get!("/api/check", check)  // takes ?signature=hash

// Good - namespace it.
get!("/api/check", check)  // takes ?body_signature=hash
```

The constants are exposed for symmetry with the Laravel wire format:

```rust
use suprnova::routing::{SIGNATURE_KEY, EXPIRES_KEY};
// SIGNATURE_KEY == "signature"
// EXPIRES_KEY   == "expires"
```

### Key rotation

Signed URLs use the same `APP_KEY` that powers `Crypt::encrypt` and
session-cookie integrity. Rotating `APP_KEY` invalidates every
previously-minted signature in flight - an in-flight password-reset
email becomes a 403 the next time the user clicks it.

For most applications that is the correct behaviour. If you need
graceful rotation with overlap (so old links keep working through a
deployment window), use `APP_KEY_PREVIOUS` to carry the prior key
forward; the keyring tries every installed key on verification. See the
[Hashing](hashing.md) chapter for the full keyring story.

## Errors and edge cases

A handful of failure modes are worth knowing about:

- **`route(name, ...)` returns `None`** when the name is not registered.
  This is the lenient surface - silent failure is intentional so calling
  code can fall back to a default. Use `try_route` for a loud failure.
- **`try_route` returns `Err(NameNotFound)`** for an unknown name and
  `Err(MissingParams { name, missing })` when a required `{placeholder}`
  has no matching value.
- **`url::signed_route` and friends return `FrameworkError`** when the
  encryption key isn't installed (e.g. you forgot `APP_KEY` in `.env`).
  This fails at boot in production because `Crypt::init` runs during
  `Server::from_config`; the error path here exists to surface
  misconfiguration loudly instead of producing unverifiable links.
- **`has_valid_signature` returns `Ok(false)`**, not `Err`, for an
  invalid or expired signature. The `FrameworkError` variant is reserved
  for "the server can't even check" failures (missing key).
- **A signed URL with a tampered `expires`** verifies as `Invalid`, not
  `Expired`. The HMAC payload includes the `expires` value, so changing
  it breaks the signature first.

```rust
use suprnova::{routing::SignatureVerdict, url};

// All of these are Invalid, not Expired:
url::signature_verdict(&req)?;  // signature query param missing
url::signature_verdict(&req)?;  // signature is non-hex junk
url::signature_verdict(&req)?;  // path was tampered (/orders/1 → /orders/2)
url::signature_verdict(&req)?;  // any query param value was tampered
url::signature_verdict(&req)?;  // expires value was tampered

// This is Expired:
url::signature_verdict(&req)?;  // valid HMAC, but now > expires
```

## Why Suprnova diverges

Laravel's `URL` facade carries `asset()`, `secureAsset()`, `assetFrom()`,
and `action()`. Suprnova ships none of them - for deliberate reasons.

**Assets**. Suprnova's frontend story is Vite plus the filesystem disks
([Filesystem](filesystem.md)), not a stand-alone asset helper. Vite's
`@vite('resources/app.ts')` directive (or the Inertia adapter's equivalent)
emits the correct hashed URLs in production and the dev-server URL in
development. Building a parallel `URL::asset()` channel would split the
asset story across two systems that have to agree about hashing,
versioning, and which manifest is authoritative. The Vite side already
won that responsibility.

**Action routing**. Laravel's `action('UserController@show', ['id' => 1])`
relies on PHP class-string routing - controllers are classes with
methods, and the framework can reverse-look-up an `action` string. Rust
handlers are free functions. The closest analogue is named routes, and
`route("users.show", &[("id", "1")])` is already the right interface.
Re-introducing action-string routing on top of Rust handler types would
add nothing real over named routes.

**`URL::forceScheme()` / `URL::forceRootUrl()`**. Laravel exposes these
for tests and for sites behind reverse proxies that don't pass
`X-Forwarded-Proto`. Suprnova handles both cases by configuration:
`APP_URL` carries the canonical host, scheme and path. Behind a proxy,
the request accessors read `X-Forwarded-Proto`, `-Host`, `-Port` and
`-Prefix` from the addresses listed in `APP_TRUSTED_PROXIES`, and the URL
helpers build on them; the request's own path is left as it arrived, so
routes match it. There's nothing for `forceScheme` to override - `APP_URL`
already says what the scheme is. For a proxy that serves the application
under a path, see [Serving under a path prefix](deployment.md#serving-under-a-path-prefix).

What does land here is the user-facing shape consumers reach for, with
the same Laravel-shaped names where they translate cleanly. The trim is
intentional, not an oversight.

## Next

- [Routing](routing.md) - declaring routes, naming them, route groups,
  resource routing, and the full per-method matching surface
- [Responses](responses.md) - `Redirect::route`, `Redirect::signed_route`,
  `Redirect::back`, and the rest of the redirect helper family that
  consumes URL generation
- [Hashing](hashing.md) - `APP_KEY` lifecycle, key rotation, and the
  shared keyring that backs URL signing alongside encryption
- [Auth flows](auth-flows.md) - the production users of signed URLs:
  password reset, email verification, and remember-me cookies
- [Requests](requests.md) - `Request::path`, `Request::query`,
  `Request::route_is`, and the reverse side of every helper in this
  chapter


---

<!-- /docs/session -->

# Sessions

The session is the per-user key/value bag that survives across requests
on the same browser. Suprnova ships a database-backed driver out of the
box, wires it in via `SessionMiddleware`, and exposes the active session
through two free functions - `session()` for reads, `session_mut()` for
writes. Use it whenever a value should outlive one request but not be
something the URL or a JWT should carry.

## How a request sees the session

`SessionMiddleware` runs on every request and does five things in order:

1. Reads the session id and last successful activity-touch timestamp from
   the `suprnova_session` cookie (AES-256-GCM encrypted, bound to the cookie
   name). Tampered, undecryptable, or malformed cookies are treated as absent,
   and so is a value that another cookie wrote.
2. Loads `SessionData` from the store only when a valid cookie names a
   session. Cookieless requests start with a clean in-memory session and do
   not issue a guaranteed database miss. A cookie whose row no longer exists
   is cleared without recreating an empty row. A store read error logs
   `warn!` and lets a state-free request continue, but a handler mutation
   then fails closed rather than overwrite unknown stored state.
3. Ages flash data: `_flash.old.*` is dropped, `_flash.new.*` is
   renamed to `_flash.old.*`. After this step, anything the previous
   request flashed is readable; anything this request flashes will be
   readable next time.
4. Binds the session into a task-local slot for the duration of the
   handler. `session()` and `session_mut()` look the slot up.
5. After the handler returns, persists dirty session state or a bounded
   sliding-expiry touch, attaches a replacement encrypted cookie only after
   a successful write, and drains pending out-of-band cookies (for example,
   a freshly rotated remember-me cookie). A clean cookieless request does no
   session-store I/O and receives no session cookie.

Step 5 has one safety guarantee worth pulling out: **if the session
was modified this request and the store write fails, the response is
replaced with a 500.** Returning the handler's success would mean
handing the client a cookie for state the database never recorded -
the next request would load an empty session and the mutation
(login, CSRF rotation, flash) would silently vanish. Read-only
requests that fail only on a due `last_activity` touch log `warn!`, keep the
existing cookie, and pass through.

A response marked for shared caching, with `Cache-Control: public` or an
`s-maxage`, is never sent with a cookie. A CDN or a caching proxy may store
such a response with its `Set-Cookie` lines and replay them to every later
visitor, which would hand one reader's session to everyone. While the request
leaves the session unchanged, the session and CSRF middleware leave their
cookies off: the reader already holds them, and a session the request created
without writing to it is not stored. When a cookie must reach the reader, such
as a new or rotated session from a sign-in, a rotated remember-me cookie or one
your handler set, the cookies stay and the response goes out
`Cache-Control: private, no-store` instead, with a warning in the log. The same
happens to a page that embeds the CSRF token through `csrf_field()`,
`csrf_meta_tag()`, the Inertia root template or a Live mount: the token belongs
to its reader, so the page is sent private and its session is stored, and a
form on it submits on the first try.

### Why Suprnova diverges

Laravel's `StartSession` and `VerifyCsrfToken` attach their cookies to every
response, whatever its `Cache-Control` says. Suprnova keeps them off responses
a shared cache may store, so marking a favicon or a sitemap `public` cannot
leak a session.

## Reading the session

```rust
use suprnova::session::session;

if let Some(s) = session() {
    let user_id: Option<String> = s.get("preferred_username");
    if s.has("cart") {
        // ...
    }
    if s.missing("locale") {
        // first visit
    }
}
```

`session()` clones the current `SessionData`. Returns `None` outside a
request scope (a unit test that didn't install the middleware, a CLI
subcommand). For a typed value, `get::<T>` deserializes from the
underlying JSON; on a missing key or wrong type, you get `None` and no
panic.

## Writing the session

`session_mut` takes a closure that receives `&mut SessionData`:

```rust
use suprnova::session::session_mut;

session_mut(|s| {
    s.put("locale", "en");
    s.put("preferences", serde_json::json!({
        "theme": "dark",
        "notifications": true,
    }));
    s.forget("legacy_key");
});
```

The closure is sync - guards on the underlying lock drop before any
`.await`, so this composes inside async handlers without holding the
lock across suspensions. Anything you serialize must implement
`Serialize`; deserialization on `get` requires `DeserializeOwned`.

The closure form (rather than returning a guard) is deliberate. Futures
in Tokio can resume on a different worker thread than the one they
started on, so the session has to live in a `task_local!` slot and be
borrowed through a scope-bound critical section. The `|s|` shape makes
that boundary explicit and stops you accidentally holding a mutex guard
across an `.await`.

### When the closure panics

A panic in a `session_mut` closure can leave the session between two of
its writes. Most panics end the request, and nothing else happens. Some
boundaries below the middleware catch the panic and let the request go on:
a Live action, or a listener that runs inside the request.

In that case `session()` and `session_mut()` keep working, so the code that
answers for the panic can still read the session. The middleware does not
store the session. It answers `500`, keeps the stored session as it was
before the request, and logs an error. Cookies that the request queued are
still sent with the `500`.

Keep the closure free of code that can panic, and do the fallible work
before you call `session_mut`.

## Flash data

Flash values are visible for **one** subsequent request, then disappear.
The usual pattern: a controller writes a flash, returns a redirect, the
next page renders the flash.

```rust
use suprnova::session::session_mut;

session_mut(|s| s.flash("status", "Profile updated."));
```

On the next request:

```rust
use suprnova::session::session_mut;

let status: Option<String> = session_mut(|s| s.get_flash("status"));
```

`get_flash` removes the value as it returns it. For the read-without-
consume variant use `get::<String>("_flash.old.status")`, but the
consuming form is what controllers usually want.

The full flash surface from Laravel is available:

- `flash(key, value)` - write for next request
- `now(key, value)` - write for the current request only
- `reflash()` - re-flash everything currently visible for one more turn
- `keep(&["k1", "k2"])` - re-flash a specific subset
- `flash_input(map)` / `old_input()` / `get_old_input(key)` - the
  form-input bag used by `Redirect::with_input` / `old()` helpers

## Regenerate and invalidate

After a credential change (login, password reset, 2FA pass) you rotate
the session id so a fixated id from before the change is no longer
valid:

```rust
use suprnova::session::{regenerate_session_id, regenerate_csrf_token};

regenerate_session_id();        // new id and new CSRF token, same data
regenerate_csrf_token();        // new CSRF token, same id and data
```

`regenerate_session_id()` also issues a new CSRF token, as Laravel's
`Session::regenerate` does. A token that a page read before the
regeneration is refused with `419` after it, so a page planted with the
old session cannot submit with the new one. Send the new token from the
`XSRF-TOKEN` cookie that the response carries, or from the
`<meta name="csrf-token">` tag of the next page. `SessionMiddleware`
destroys the old session row when it stores the new one.

To clear the session entirely (logout):

```rust
use suprnova::session::invalidate_session;

invalidate_session();           // clears data + mints fresh CSRF token
```

For a security event that needs to revoke every session for a user
(password reset elsewhere, account recovery, admin force-logout):

```rust
use suprnova::session::destroy_all_for_user;

let rows = destroy_all_for_user("user-42").await?;
tracing::info!(revoked = rows, "all sessions destroyed");
```

`destroy_all_for_user` destroys the sessions in which the default guard is
signed in as that id. A session in which only another guard holds the same
id belongs to another user, admin `7` and not web user `7`, so it stays. For
another guard's user, name the guard:

```rust
use suprnova::session::destroy_all_for_guard_user;

let rows = destroy_all_for_guard_user("admin", "7").await?;
```

Each destroyed session goes whole, with every guard's sign-in in it. Every
Live membership issued under it ends on this node too, whichever guard's
user it was issued to, and so does every membership of the destroyed user.

Both functions resolve the `SessionStore` registered by
`SessionMiddleware::new` or `with_store` and call `destroy_guard_sessions` on
that configured store. They fall back to a fresh `DatabaseSessionDriver`
only when no session store was registered, such as in a test or embedder
that never constructed the middleware. A custom store implements
`destroy_guard_sessions`, using `SessionData::is_signed_in_as`, and returns
the ids it destroyed so Live can end what they opened. Without it, the
default guard's destroy falls back to the store's `destroy_for_user` and
names no session, so only the destroyed user's own memberships end; another
guard's destroy is an error.

### Why Suprnova diverges

Laravel has no call that destroys a user's sessions. A password change ends
them lazily: `AuthenticateSession` compares the password hash it stored in
each session with the default guard's user's current one, and flushes the
session on a mismatch. Suprnova does both. `destroy_all_for_user` keeps
Laravel's scope, the default guard's user and the whole session, but ends
the sessions at once, so a stolen session does not survive until its next
request. And every request that resolves a user compares the
[auth epoch](authentication.md#auth-epochs) its sign-in recorded with the
user's current one, so a session or remember-me credential issued under an
earlier password is refused even when the eager revocation failed.

## Authentication helpers

`auth_user_id()` returns the currently-authenticated user id (consulting
request-scoped auth state first, falling back to the persisted session
field):

```rust
use suprnova::session::{auth_user_id, is_authenticated};

if is_authenticated() {
    let uid = auth_user_id().expect("just checked");
    // ...
}
```

You normally drive auth through the [Auth](authentication.md) facade -
`Auth::login`, `Auth::logout`, `Auth::user()`. The session helpers are
the low-level layer those facades sit on; reach for them when you need
to inspect the raw session or when implementing your own guard.

## Other operations

The `SessionData` API mirrors Laravel's `Store` surface:

| Method | What it does |
|---|---|
| `get::<T>(key)` | typed read |
| `put(key, value)` | typed write |
| `forget(key)` | remove a single key |
| `forget_many(&[..])` | remove many keys |
| `flush()` | clear all data (keeps id) |
| `has(key)` / `missing(key)` | presence check |
| `has_any(&[..])` / `has_all(&[..])` | bulk presence |
| `all()` | borrow the underlying map |
| `only(&[..])` / `except(&[..])` | filtered clones |
| `pull::<T>(key)` | get-and-forget in one shot |
| `push(key, value)` | append to an array value |
| `increment(key, n)` / `decrement(key, n)` | integer counters |
| `remember::<T>(key, \|\| default())` | get-or-compute-and-put |
| `replace(&[(k, v), ..])` | flush then bulk put |
| `put_many(&[(k, v), ..])` | merge bulk put |
| `previous_url()` / `set_previous_url(url)` | what `Redirect::back` reads |
| `password_confirmed()` / `password_confirmed_at()` | "user confirmed password just now" timestamp |

Reach for these inside `session_mut` for mutating ops, `session()`
for reads. The `previous_url` slot is populated automatically by the
middleware on successful GET HTML responses, so `redirect()->back()`
works without you doing anything. The middleware only records a
root-relative, same-origin URL: a request path that starts with `//`
or `/\` (both read as protocol-relative by a browser) or that carries
an ASCII control byte anywhere in it (a `TAB` or newline lets a value
that only looks root-relative turn into one of those two forms once a
browser's URL parser strips it) is never stored. `previous_url()`
re-checks the same rule on every read too, so a value written by an
older release, before that write-time guard existed, reads back as
absent instead of being trusted. Either way, `Redirect::back()`,
`Redirect::refresh()`, and `url::previous()` can never resolve to a
`Location` outside your app from a value this slot held.

## Configuration

Configure sessions via environment variables - `SessionConfig::from_env`
reads them at boot:

```env
# Where sessions are kept: database (default) or mongodb. mongodb needs
# the database-mongodb feature; Config::init refuses any other value.
SESSION_DRIVER=database

# Lifetime in minutes. Drives both the row TTL and the cookie Max-Age.
SESSION_LIFETIME=120

# Minimum seconds between sliding-expiry writes (default 5 minutes).
# Runtime enforcement caps this below the session lifetime.
SESSION_TOUCH_INTERVAL=300

# Supervised expired-row collection cadence in seconds (default 1 hour).
SESSION_GC_INTERVAL=3600

# Cookie name on the client.
SESSION_COOKIE=suprnova_session

# Cookie attributes
SESSION_SECURE=true          # require HTTPS; DEFAULT IS true
SESSION_PATH=/                # optional; unset = the public root of each request
SESSION_DOMAIN=.example.com  # optional; unset = host-only
SESSION_SAME_SITE=Lax        # Lax | Strict | None
SESSION_COOKIE_PREFIX=       # empty | __Secure- | __Host-
SESSION_PARTITIONED=false    # CHIPS opt-in
SESSION_EXPIRE_ON_CLOSE=false # true → omit Max-Age, browser drops on close

# Table the database driver reads and writes (default sessions), and the
# collection the mongodb driver does.
# Config::init refuses a name that is not 1 to 63 ASCII letters, digits,
# or underscores starting with a letter or underscore.
SESSION_TABLE=sessions

# Named connection for the session store (optional). The mongodb driver
# reads it as the name of a MongoDB connection.
SESSION_CONNECTION=sessions

# Remember-me token/cookie lifetime in minutes (default 30 days)
REMEMBER_LIFETIME=43200
```

A few defaults worth flagging:

- **`SESSION_SECURE` defaults to `true`.** Sessions sent over plain
  HTTP would be a credential-leak hazard, so the secure flag is on by
  default. For local development over HTTP, set `SESSION_SECURE=false`
  in your local `.env`.
- **`HttpOnly` is always on.** There is no knob to disable it -
  exposing the session cookie to JavaScript forfeits the primary XSS
  protection and there is no legitimate modern reason to want it.
- **`SameSite` defaults to `Lax`.** `Strict` blocks the session on
  most cross-site GET navigations (including back-links from email);
  `Lax` is the usual right answer.

### Cookie-name prefix hardening

`SESSION_COOKIE_PREFIX=__Host-` makes the browser host-lock the session and
remember-me cookies. A `__Host-` cookie must be `Secure`, use `Path=/`, and
omit `Domain`; a `__Secure-` cookie must be `Secure`. Suprnova enforces these
rules at render time from the final cookie name, so builder order and queued
cookies receive the same protection.

`Config::init` validates the prefix, `SESSION_DOMAIN`, and `SESSION_PATH` at
boot and fails before serving when the combination is invalid. Render-time
enforcement still forces `Secure` for either prefix and rewrites a `__Host-`
path to `/`; it drops a `Domain` on `__Host-` and logs a warning because that
narrows the requested scope. The browser silently drops an invalid prefixed
cookie, so check the boot diagnostic before deployment.

The browser applies the prefix rules to the cookie name it stores, so a
name such as `%5F%5FHost-suprnova_session` escapes them, and a sibling
subdomain can set it. Suprnova ignores a cookie whose `__Host-` or
`__Secure-` prefix appears only after percent-decoding its name, so it never
answers for `__Host-suprnova_session` or `__Secure-suprnova_session`. A
cookie sent under its literal name also wins over any encoded alias of that
name.

For local HTTP development, leave the prefix empty and set
`SESSION_SECURE=false` only in the local environment. For production, deploy
HTTPS, keep `SESSION_SECURE=true`, use `SESSION_COOKIE_PREFIX=__Host-`, keep
`SESSION_PATH=/`, and leave `SESSION_DOMAIN` unset.

Deployment checklist:

1. Confirm the public origin is HTTPS, including health checks and the first
   redirect.
2. Set `SESSION_COOKIE_PREFIX=__Host-`, `SESSION_SECURE=true`, and
   `SESSION_PATH=/`.
3. Remove `SESSION_DOMAIN`; the boot validator rejects it with `__Host-`.
4. Inspect the first `Set-Cookie` response for `__Host-suprnova_session`,
   `Secure`, and `Path=/`, with no `Domain`.

### Why Suprnova diverges

Laravel does not expose a first-class cookie-prefix knob in its session
configuration. Suprnova makes the prefix a configuration value with boot
validation because the failure mode is browser-silent: an invalid cookie is
discarded before application code can report a session failure.
For programmatic config use the fluent builder:

```rust
use std::time::Duration;
use suprnova::SessionConfig;

let config = SessionConfig::new()
    .lifetime(Duration::from_secs(60 * 60))      // 1 hour
    .touch_interval(Duration::from_secs(5 * 60))
    .gc_interval(Duration::from_secs(60 * 60))
    .cookie_name("myapp_session")
    .secure(true)
    .domain(".example.com")
    .remember_lifetime(Duration::from_secs(30 * 24 * 60 * 60));
```

`SessionConfig` is `#[non_exhaustive]`; use a default and assign the public
field when programmatic configuration needs a prefix:

```rust
use suprnova::{CookiePrefix, SessionConfig};

let mut config = SessionConfig::default();
config.cookie_prefix = CookiePrefix::Host;
```

## Wiring it up

`SessionMiddleware` is installed as a global middleware in your app's
bootstrap. The middleware ordering matters: session must come before
[CSRF](csrf.md), since CSRF reads the per-session token.

```rust
use std::sync::Arc;
use suprnova::{global_middleware, CsrfMiddleware, SessionConfig, SessionMiddleware};

pub async fn bootstrap() {
    let config = SessionConfig::from_env();

    // `install` registers the configured GC supervisor as well.
    // Use `SessionMiddleware::new(config)` if you'd rather schedule GC
    // yourself via `Schedule`.
    global_middleware!(SessionMiddleware::install(config).await);

    global_middleware!(CsrfMiddleware::new());
}
```

`SessionMiddleware::install` registers a [supervised](supervisors.md)
gc task that calls `gc()` at `SESSION_GC_INTERVAL` (once an hour by
default). The variant
`install_with_gc(config, interval).await` takes a custom interval;
`new(config)` skips the gc task (useful if you'd rather call `gc()`
from a [Schedule](scheduling.md) entry). The supervised task
participates in the framework's shutdown drain, so the gc loop exits
cleanly on `Ctrl-C` / `SIGTERM` instead of being force-aborted.

Protected operations endpoints can expose collector state without querying
the sessions table:

```rust
use suprnova::session::session_gc_metrics;

let metrics = session_gc_metrics();
tracing::info!(
    runs = metrics.runs,
    failures = metrics.failures,
    removed_rows = metrics.removed_rows,
    last_success = metrics.last_success_unix_seconds,
    "session collector status"
);
```

`SessionMiddleware::new` and `install` build the store
`SessionConfig::driver` names: the database driver by default, or, for
`SESSION_DRIVER=mongodb`, `MongoSessionDriver` over the `sessions`
collection. See [MongoDB: Session](mongodb.md#session).

To use another store - for tests, or for a Redis-backed driver
you write yourself - implement `SessionStore` and pass it via
`with_store`:

```rust
use std::sync::Arc;
use suprnova::{SessionConfig, SessionMiddleware, SessionStore};

let store: Arc<dyn SessionStore> = Arc::new(MyRedisStore::new());
let mw = SessionMiddleware::with_store(SessionConfig::from_env(), store);
```

`read` can build the session it returns with `SessionData::new`.
`SessionMiddleware` marks every session `read` returns as loaded from the
store (`SessionData::loaded_from_store`), so a stored session that a request
does not change is not written again. In `write`, the flag is `true` when the
row existed at read time; a store can use it to refuse to recreate a row that
was deleted in between, as the database driver does.

## Session blocking

Two requests that carry one session cookie load the same row, and without
coordination the one that writes last wins: a flash the first request set
can be gone before any later request reads it. That happens whenever a page
fires several requests at once, such as Live islands connecting while a
redirect lands. Session blocking serializes them. With it enabled, the
session middleware takes a lock for the session id through the
[cache](cache.md) lock driver before it loads the session, holds it through
your handler and the write, and releases it after, so the second request
loads what the first one persisted.

It is off by default. Enable it for the whole application from the
environment or in code, or for one route or group with `block_session`:

```env
SESSION_BLOCK=true
SESSION_BLOCK_LOCK_SECONDS=10   # how long one request holds the lock
SESSION_BLOCK_WAIT_SECONDS=10   # how long a request waits to take it
```

```rust
use std::time::Duration;
use suprnova::{global_middleware, Router, SessionBlock, SessionConfig, SessionMiddleware};

let config = SessionConfig::from_env().block(SessionBlock::default());
global_middleware!(SessionMiddleware::install(config).await);

// One route holds the lock for a minute; the rest of the app keeps the default.
let router: Router = Router::new()
    .post("/orders", place_order)
    .block_session(SessionBlock::new(Duration::from_secs(60), Duration::from_secs(10)))
    .into();
```

Both bounds are deliberate. The hold is the lock's TTL: a handler that runs
past it loses the lock, later requests stop queueing behind it, and the
middleware logs a warning so you raise the bound. The wait is how long a
request queues before it answers `503 Service Unavailable` with
`Retry-After: 1` instead of holding a connection open. A route-level block
takes precedence over the global one. A request without a session cookie
names no row two requests could race over, so it never waits and never
touches the cache. Blocking uses the cache store the framework boots from
`CACHE_DRIVER`: the in-memory driver serializes requests within one
process, and a deployment with several nodes needs Redis for the lock to
hold across them.

### Why Suprnova diverges

Laravel's `block()` throws a `LockTimeoutException` when the wait runs out,
which surfaces as a 500. Suprnova answers `503` with `Retry-After`, because
a request that lost the race for its own session is a transient condition
the client can retry, not a fault in the server.

## The sessions table

The default driver reads the `sessions` table of the Laravel 13 skeleton,
so a Suprnova application runs on a database Laravel created:

| Column | Type | Notes |
|---|---|---|
| `id` | VARCHAR PK | 40-char lowercase alphanumeric session id |
| `user_id` | nullable big integer, indexed | the signed-in user; `uuid` or `CHAR(26)` for a UUID or ULID user key |
| `ip_address` | VARCHAR(45) NULL | left NULL by Suprnova |
| `user_agent` | TEXT NULL | left NULL by Suprnova |
| `payload` | LONGTEXT | base64-encoded JSON: the session data, the CSRF token as `_token` |
| `last_activity` | INTEGER, indexed | epoch seconds of the last access; drives expiry and GC |

The framework ships the migration. List it in your `Migrator` with the key
type of your user model:

```rust
use suprnova::session::migrations::{CreateSessionsTable, SessionUserKey};

// in Migrator::migrations(), after the users table:
Box::new(CreateSessionsTable::new(SessionUserKey::Integer)),
```

`SessionUserKey::Uuid` and `SessionUserKey::Ulid` create the column
`foreignUuid` and `foreignUlid` create. A table Laravel created is left as
it is. A table in the layout earlier Suprnova scaffolds created
(`csrf_token`, a date-time `last_activity`, JSON `payload`) is moved into
this layout with its rows, so nobody is signed out. Session garbage
collection only deletes rows Suprnova wrote, so a Laravel application's
sessions in the same table expire on Laravel's own schedule. See
[Running on a Laravel Database](laravel-database.md).

To keep sessions under another name, set `SESSION_TABLE` (for example
`SESSION_TABLE=app_sessions`). `CreateSessionsTable` creates the table
under that name, and `suprnova::session::migrations::create_sessions_table`
creates one under any name you pass it.

The driver never creates the table itself. Code that builds the driver
directly passes the name to
`DatabaseSessionDriver::with_table(lifetime, "app_sessions")?`, which
applies the same naming rule as `Config::init`.

### Why Suprnova diverges

Two places where Laravel made a PHP-shaped choice that Tokio lets us
make differently:

**Garbage collection.** Laravel runs a 2/100 lottery on every request:
each request has a 2% chance of triggering session GC inline. It works
on PHP because every request spawns a fresh process anyway. On Tokio
we have long-lived workers, so `SessionMiddleware::install` registers
one [supervised](supervisors.md) task that calls `gc()` on a fixed
interval. No per-request overhead, no probabilistic surprise - explicit
scheduling instead of a lottery, and the supervisor restart loop
catches panics so a single bad gc doesn't kill the daemon.

**Closure-form `session_mut`.** Laravel hands you `$request->session()`
and lets you call methods on it. We don't, because handlers in Suprnova
are futures and a future can resume on a different worker thread than
it started on. The session lives in a Tokio `task_local!` slot, which
means borrowed access has to happen inside a scope. The closure form
makes that scope explicit and statically prevents the mistake of
holding a mutex guard across `.await`.

**Fail-closed on dirty writes.** A failed bounded activity touch logs
`warn!` and lets the request through with its existing cookie (the
user-visible state is intact). A failed write of a *modified* session - login,
flash, CSRF rotation - returns 500. Silently handing the client a
cookie for state the store never recorded would make a "successful"
login vanish on the very next request; better to surface the failure
loudly.

## Next

- [Authentication](authentication.md) - `Auth::login`, guards, the user provider chain
- [Auth Flows](auth-flows.md) - password reset, 2FA, brute-force throttling, remember-me
- [CSRF](csrf.md) - how the session's CSRF token gets checked on writes
- [Middleware](middleware.md) - writing your own middleware that reads or writes the session
- [Request Lifecycle](lifecycle.md) - where `SessionMiddleware` sits in the chain


---

<!-- /docs/validation -->

# Validation

Suprnova validates request input on two complementary tracks:

1. **Derive validation** - `#[validate(...)]` attributes on a `FormRequest`
   struct, run automatically by `extract()`. This is the everyday path and
   is covered in [Requests](requests.md). It handles per-field
   rules (`email`, `length`, `range`, …) declaratively.
2. **Rule objects + the `validate!` macro** - plain values implementing
   [`Rule`](#rule-objects) / `ContextualRule` / `AsyncRule`, composed
   imperatively. Reach for these when you need cross-field logic, rules
   that touch the database, or rules you want to store and pass around.

The two tracks accumulate into the same
[`ValidationErrors`](error-model.md) bag and render the same
Laravel/Inertia `{ "message", "errors": { field: [...] } }` shape (HTTP
422).

## Rule objects

A rule is a value implementing one of four traits:

| Trait | Shape | Use |
|-------|-------|-----|
| `Rule` | `passes(&self, value: &str)` | pure check on one value |
| `ValueRule` | `passes(&self, value: &serde_json::Value)` | check on a JSON-shaped value (array/object) |
| `ContextualRule` | `passes(&self, value, ctx)` | check that reads sibling fields |
| `AsyncRule` | `async passes(&self, value)` | check that `.await`s (DB, HTTP) |

Built-in `Rule`s: `Required`, `Email`, `Min`, `Max`, `Between`, `In`,
`NotIn`, `InArray`, `Integer`, `Numeric`, `Boolean`, `Alpha`, `AlphaNum`,
`AlphaDash`, `Url`, `UrlProtocols`, `HttpUrl`, `Uuid`, `Digits`,
`DateFormat`, [`Accepted`, `Prohibited`, `Missing`](#accepted-prohibited-and-missing),
[`RequiredIf::when`](#requiring-a-field-on-a-condition),
[`Password`](#password-strength) (strength checks only). Built-in
`ValueRule`s: `ArrayKeys`, `Distinct`, `Contains`, `DoesntContain`, and
`Accepted`, `Prohibited` and `Missing` again for JSON fields.
Built-in `ContextualRule`s: `RequiredIf`, `RequiredWith`,
`RequiredUnless`, `Same`, `Different`, `Confirmed`, `Gt`, `Gte`, `Lt`,
`Lte`, the [date rules](#date-rules) `After`, `AfterOrEqual`, `Before` and
`BeforeOrEqual`, and [`ExcludeIf` and `ExcludeUnless`](#excluding-a-field).
Built-in `AsyncRule`s: [`Unique`](#the-unique-rule),
[`Exists`](#the-exists-rule) and [`Password`](#password-strength) (strength
plus its `uncompromised()` HIBP check - the one built-in rule implementing
both `Rule` and `AsyncRule`).

```rust
use suprnova::{Rule, rules::Email};

Email.passes("user@example.com")?; // Ok(())
```

> **Note:** `Numeric` accepts a **finite** number - `NaN`, `inf`, and magnitudes that
> overflow to infinity are rejected, even though Rust's parser would accept
> the strings.

### URL schemes

`Url` accepts a value that parses as a URL, whose scheme is on Laravel's
allowlist - the same list `Illuminate\Support\Str::isUrl` uses - is
followed by `://`, **and** is followed in turn by a non-empty host,
matching Laravel's `^(PROTOCOLS)://HOST` pattern in shape (Laravel's
host group has no `?` - an absent or empty host never matches). The
scheme list and the `://`-plus-host requirement are Laravel's verbatim;
the host is parsed by the `url` crate rather than Laravel's regex, so an
out-of-range port is rejected here that Laravel would accept. All three
have to hold: `mailto:`, `tel:`, and `data:` are on the allowlist by name
but carry no authority component at all, so `Url` rejects them; and
`file:///etc/passwd` fails for the third reason - it has `://`, but
nothing sits between the third and fourth `/`, and nothing isn't a host.
`javascript:` and `vbscript:` are rejected outright; they aren't on the
allowlist at all.

`ftp://host/x` and `ssh://host` - real hosts, just not web schemes - still
pass, so `Url` is not a "this is a web page" check, and it says nothing
about where the URL resolves. Rejecting `javascript:` makes a validated
value safe to put in an `href`, not safe to fetch. A webhook or callback
target still needs `HttpUrl` (or your own scheme + SSRF checks); `Url`
alone doesn't cover that.

For a narrower set, name the schemes you want:

```rust
use suprnova::{Rule, rules::Url};

// Laravel's `url:http,https`
Url::protocols(&["https"]).passes("https://example.com")?;   // Ok
Url::protocols(&["https"]).passes("http://example.com");     // Err

// The same thing, under a name
use suprnova::rules::HttpUrl;
HttpUrl.passes("https://example.com")?;
```

`Url::protocols(...)` **replaces** the allowlist rather than narrowing it,
so an app can accept its own deep-link scheme (`myapp://…`) without the
framework having an opinion about it - the `://`-plus-host requirement
still applies to that custom scheme too. Use `HttpUrl` (or
`Url::protocols(&["https"])`) for callback, webhook, and avatar inputs -
a webhook target that resolves to `ftp://internal-host/` still parses as
a `Url`, and an `ftp:` target is not a webhook target.

### Password strength

`Password` checks length and character-class strength, plus an optional
Have I Been Pwned `uncompromised()` check - Laravel's `Password` rule
object, ported. Build it with `Password::min(n)` and chain the strength
builders:

```rust
use suprnova::{Password, Rule};

let rule = Password::min(8).letters().mixed_case().numbers().symbols();
Rule::passes(&rule, "Str0ng! Pass")?; // Ok(())
Rule::passes(&rule, "weak");          // Err - too short, no digit, no symbol
```

| Builder | Requires | Laravel regex |
|---|---|---|
| `.min(n)` (via `Password::min`) | at least `n` characters (floors at 1) | length check |
| `.max(n)` | at most `n` characters | length check |
| `.letters()` | at least one Unicode letter | `/\pL/u` |
| `.mixed_case()` | an uppercase and a lowercase letter, either order | `/(\p{Ll}+.*\p{Lu})\|(\p{Lu}+.*\p{Ll})/u` |
| `.numbers()` | at least one Unicode digit | `/\pN/u` |
| `.symbols()` | at least one separator, symbol, or punctuation character - **a plain space counts** | `/\p{Z}\|\p{S}\|\p{P}/u` |

`Password::defaults_with(|| Password::min(12).letters().mixed_case().numbers())`,
called once from `bootstrap::register()`, sets the process-wide default
`Password::defaults()` returns everywhere else - Laravel's
`Password::defaults(fn () => ...)`. A second call is ignored (with a
`tracing::warn!`) rather than silently replacing the first app's chosen
policy.

#### `uncompromised()` - because strength alone isn't enough

`.uncompromised()` (or `.uncompromised_with_threshold(n)`) adds a check
against the Have I Been Pwned breach corpus, using its k-anonymity range
API: only the **first 5 characters** of the password's uppercase SHA-1
hash ever leave the process - `GET
https://api.pwnedpasswords.com/range/{prefix}` - and the match against
the full hash happens locally, against the `SUFFIX:COUNT` lines the API
returns for that prefix. The service never sees the password, or even
its full hash. The threshold comparison is strict (`count > threshold`),
so the default `uncompromised()` (threshold `0`) fails on any appearance
at all, and a network failure, timeout, or non-2xx response **fails
open** - the password is treated as clean rather than blocking every
signup during a Have I Been Pwned outage. This matches Laravel's
`NotPwnedVerifier` exactly.

Because that check is an HTTP round trip, `uncompromised()` needs
`AsyncRule`, not the sync `Rule` the strength checks alone can use. Wire
it through `after_validation_async`, the same recipe [`Unique`](#the-unique-rule)
uses:

```rust
use suprnova::{AsyncRule, FormRequest, Password, ValidationErrors, async_trait};
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate)]
pub struct Register {
    pub password: String,
}

#[async_trait]
impl FormRequest for Register {
    async fn after_validation_async(&self) -> Result<(), ValidationErrors> {
        let mut errs = ValidationErrors::new();
        Password::defaults()
            .uncompromised()
            .check_async(&self.password, &mut errs, "password")
            .await;
        errs.into_result()
    }
}
```

Calling the sync `Rule::passes` on a `Password` that has `uncompromised()`
set is a **loud error**, not a silent skip - a security check that
quietly does nothing is worse than one that never existed. The error
message names `after_validation_async` as the fix.

`HIBP_TIMEOUT_SECS` (default `30`) controls the request timeout - see
[Environment Variables](env-vars.md).

A custom verifier that returns `Err` is a different case from a failed check:
its error text is logged at `error` level and never reaches the client, and the
response carries the `validation-password-unverifiable` catalog key ("The
{ $field } could not be checked against known data leaks. Please try again.")
instead. Add that key if you ship your own validation catalog.

### Why Suprnova diverges: Password

- Laravel's `Password` collects every failed strength check into one
  array. Suprnova's `Rule` contract returns a single
  `ValidationMessage`, so `Rule::passes` reports the FIRST failing
  check, in the order min, max, mixed case, letters, symbols, numbers -
  fix one at a time rather than seeing the whole list up front.
- Laravel's sync validator can call `uncompromised()` directly; a PHP
  request is already inside an event loop that tolerates a blocking
  HTTP call. Suprnova's `Rule::passes` is synchronous by contract, so
  there is no safe place to run the HIBP request from it. Rather than
  silently skip the check - the one unacceptable outcome for a
  security-relevant rule - Suprnova's `Rule::passes` returns a loud,
  developer-facing error naming `after_validation_async` as the fix.
- `Password::defaults_with` takes a plain `fn` pointer, not a closure,
  so the configured default stays `Copy` and needs no heap allocation -
  a deliberate narrowing from Laravel's `Closure`.

### Writing your own rule

A custom rule is a unit (or data-carrying) struct with one impl. The
trait gives you `check()` for free - it pushes any failure message onto
a `ValidationErrors` bag under the named field - so the rule plugs
into `validate!` and the `after_validation` hooks unchanged:

```rust
use suprnova::{Rule, ValidationMessage};

pub struct StartsWith(pub &'static str);

impl Rule for StartsWith {
    fn passes(&self, value: &str) -> Result<(), ValidationMessage> {
        if value.starts_with(self.0) {
            Ok(())
        } else {
            Err(format!("must start with {}", self.0).into())
        }
    }
}

// Now usable everywhere:
StartsWith("acct_").passes("acct_1234")?;
// or, in a validate! row:
//   stripe_id => Required, StartsWith("acct_");
```

A `String` converts into a `ValidationMessage` that renders verbatim,
which is all a single-language app needs. To have the message translated
per locale, return a *keyed* message instead -
`ValidationMessage::keyed("validation-starts-with").arg("prefix", self.0).fallback(…)` -
and define the id in `lang/<locale>/validation.ftl`. See
[Localization](localization.md), which also covers overriding the
built-in rules' messages and the `field-<name>` naming convention.

For cross-field logic, implement [`ContextualRule`] instead - the
`passes` method gets a `&FormContext` (a `HashMap<String, String>` of
sibling field values) alongside the value under test. For
database-backed checks, implement [`AsyncRule`] and use it from
`after_validation_async`.

### Value-shaped rules

`Rule` only ever sees `&str`. Two built-ins need more structure than a
string carries, so they implement `ValueRule` instead, over
`&serde_json::Value`:

```rust
use suprnova::{ValueRule, rules::{ArrayKeys, Distinct}};

// Laravel's array:keys - reject keys outside the allowed set. Listed
// keys need not all be present; an empty allowed list is a programming
// error, reported as a keyless message.
ArrayKeys(&["name", "email"]).passes(&serde_json::json!({"name": "Ada"}))?;

// Laravel's distinct / distinct:ignore_case / distinct:strict.
Distinct { ignore_case: false, strict: false }
    .passes(&serde_json::json!(["a", "b", "c"]))?;
```

A field validated by a `ValueRule` must hold `serde_json::Value` itself
(or `Option<serde_json::Value>` for a `?:`/`?=>` row) - typically a
request field pulled straight from the JSON body. `validate!` rows
accept `Rule`s and `ValueRule`s in the same field list; which trait runs
is resolved by which one the rule's type implements, not by anything
you write in the row.

### Membership rules

Three rules answer "is this value in that list?", each over the shape it
needs:

```rust
use suprnova::{Rule, ValueRule, rules::{Contains, DoesntContain, InArray}};

// Laravel's in_array:allowed_roles.* - the value must appear in another
// field's list. Pass the list itself: a Vec<String> field and a &[&str]
// literal both work.
InArray(&form.allowed_roles).passes(&form.role)?;

// Laravel's contains:rust,web - the array must hold every listed value.
Contains(&["rust", "web"]).passes(&form.tags)?;

// Laravel's doesnt_contain:banned - the array must hold none of them.
DoesntContain(&["banned"]).passes(&form.tags)?;
```

Every comparison is exact. `InArray` compares strings with `==`, and
`Contains` and `DoesntContain` match a parameter against a JSON string
element only, so `["1"]` contains `"1"` and `[1]` does not. A value that
is not an array fails `Contains` and `DoesntContain` outright.

`Contains` and `DoesntContain` reject an empty parameter list as a keyless
construction error, the same way `ArrayKeys` does - a list with nothing in
it constrains nothing. An empty `InArray` haystack is different: a sibling
field can legitimately be empty at run time, so the value simply fails.

`InArray`'s failure message names no values, because its list comes out of
the request and a validation message is rendered into a response body.

### Comparison rules

`Gt`, `Gte`, `Lt`, and `Lte` compare a field against a number or against
another field. `CompareWith` names the operand and the measure together:

```rust
use suprnova::{ContextualRule, FormContext, rules::{CompareWith, Gt, Lte}};

let mut ctx = FormContext::new();
ctx.insert("max_price".to_string(), form.max_price.clone());

// Laravel's gt:0 - a literal operand, compared numerically.
Gt(CompareWith::Number(0.0)).passes(&form.price, &ctx)?;

// Laravel's lte:max_price - a sibling field, compared numerically.
Lte(CompareWith::NumericField("max_price")).passes(&form.price, &ctx)?;

// Laravel's gt:summary on two string fields - compared by character count.
Gt(CompareWith::LengthField("summary")).passes(&form.body, &ctx)?;
```

All four read sibling fields, so they are `ContextualRule`s and every
`validate!` row carries `=> with ctx` - including a row whose only operand
is a literal, where the context goes unread. Pass an empty `FormContext`
there.

Anything the rule cannot measure fails the field: a value that is not a
finite number under a numeric comparison, a sibling the form never sent, a
sibling that is not a number, or a non-finite literal such as `f64::NAN`.
None of those panics, and none of them passes.

### Digits

`Digits(n)` is Laravel's `digits:n`: exactly `n` ASCII digits. It is a
string rule on purpose - a PIN or a card number keeps its leading zeros
only as text.

```rust
use suprnova::{Rule, rules::Digits};

Digits(4).passes("0042")?; // Ok(())
```

### Date rules

`DateFormat` is Laravel's `date_format`. It takes a list of formats in
chrono's `strftime` syntax and passes a value that matches one of them.
Like Laravel's, the check formats the parsed date back and compares it with
the input, so `2026-9-30` does not match `%Y-%m-%d` and
`2026-02-31` matches nothing. A partial format such as `%Y-%m` or `%H:%M`
works too; the parts it leaves out come from 1970-01-01 at midnight, as in
PHP, so `02-29` does not match `%m-%d`.

`After`, `AfterOrEqual`, `Before` and `BeforeOrEqual` compare a date with a
`DateBound`: a fixed `Date` or `DateTime`, `Now`, `Today`, `Tomorrow`,
`Yesterday`, or another field. Build them with `new`, and add
`.format(...)` when the field is not ISO 8601 - Laravel's
`date_format:d/m/Y|after:today` pairing, which reads the value and a
sibling bound with that format.

```rust
use suprnova::{validate, FormContext, ValidationErrors};
use suprnova::rules::{After, AfterOrEqual, DateBound, DateFormat};

fn booking_rules(form: &Booking) -> Result<(), ValidationErrors> {
    let ctx: FormContext = [("starts_on".to_string(), form.starts_on.clone())].into();
    validate! { form =>
        // Laravel's date_format:Y-m-d|after_or_equal:today
        starts_on => DateFormat(&["%Y-%m-%d"]), AfterOrEqual::new(DateBound::Today) => with ctx;
        // Laravel's date_format:d/m/Y|after:starts_on
        ends_on => DateFormat(&["%d/%m/%Y"]),
            After::new(DateBound::Field("starts_on")).format("%d/%m/%Y") => with ctx;
    }
}
```

Without a format, a value is read as RFC 3339, as `YYYY-MM-DD HH:MM[:SS]`
with a space or a `T` (what a `datetime-local` input sends), or as a bare
`YYYY-MM-DD`, which stands for its midnight. An offset is converted to UTC;
a value without one is taken as UTC. Both sides are compared to the second,
as Laravel compares timestamps. A value, or a sibling, that is not a date
fails the field; a sibling the form did not send passes it, as in Laravel.
The relative bounds read the framework clock, so a test moves them with
`TestClock`.

### Accepted, prohibited, and missing

- `Accepted` - Laravel's `accepted`: `yes`, `on`, `1` or `true`. It also
  takes a `bool` field (`true` passes), an `Option<bool>` (an absent toggle
  fails) and a JSON `true` or `1`, so a terms toggle can stay typed on a
  Data Object.
- `Prohibited` - Laravel's `prohibited`: the field is empty. Blank text
  passes, and so do a JSON `null`, empty array and empty object.
- `Missing` - Laravel's `missing`: the field was not sent. A typed request
  has every field it declares, so "not sent" is an `Option` field that is
  `None`. Put `Missing` on a `?:` row: the row skips an absent field, and
  the rule fails anything that arrived, even an empty value.

```rust
validate! { self =>
    terms => Accepted;          // terms: bool
    honeypot => Prohibited;     // honeypot: String
    referral_code ?: Missing;   // referral_code: Option<String>
}
```

### Requiring a field on a condition

`RequiredIf::when(condition)` is Laravel's `Rule::requiredIf`. The
condition is a `bool`, or a closure that returns one each time the rule
checks a value. While the condition holds, the rule is `Required`, with the
`validation-required` message. When it does not hold, the rule passes every
value. The rule reads no other field, so it is a plain `Rule` and takes no
`=> with ctx`:

```rust
use suprnova::{validate, ValidationErrors, rules::RequiredIf};

fn after_validation(&self) -> Result<(), ValidationErrors> {
    let business = self.account_type == "business";
    validate! { self =>
        company_name ?=> RequiredIf::when(business);
        vat_number ?=> RequiredIf::when(|| business && self.country != "US");
    }
}
```

Put the rule on a `?=>` row when the field is an `Option`, so it can fail a
field the client did not send. To require a field when another field has a
given value, use `RequiredIf { other, value }` instead.

### Excluding a field

`ExcludeIf { other, value }` and `ExcludeUnless { other, value }` are
Laravel's `exclude_if` and `exclude_unless`. A `validate!` row runs its
rules in order, and while the exclusion holds, the rules after it do not
run - an error from a rule before it stands, as in Laravel. Put the
exclusion first to skip the whole row.

```rust
let ctx: FormContext = [("payment".to_string(), self.payment.clone())].into();
validate! { self =>
    card_number ?=> ExcludeUnless { other: "payment", value: "card" } => with ctx,
        Required, Digits(16);
}
```

### Why Suprnova diverges

Laravel's `date_format` takes PHP formats (`Y-m-d`); Suprnova's takes
chrono's (`%Y-%m-%d`), the syntax every other date API in a Rust
application already uses. Laravel reads `after:today` in the
application's time zone; Suprnova has no application time zone, so
`DateBound::Today` starts at midnight UTC.

Laravel also drops an excluded field from `validated()`, the array a
controller hands to `Model::create`. A typed request has no such bag: the
struct still holds whatever the client sent. When a handler must ignore an
excluded field, it asks the same rule with
`ExcludeIf { .. }.excludes(&ctx)`.

Laravel's `missing` tests whether a key is in the input array. A typed
request cannot see keys it does not declare - and a Data Object refuses an
undeclared key outright - so `Missing` works on a declared `Option` field
through the `?:` row.

Laravel's `distinct:strict` leans on PHP's coercing `==`. JSON values are
already typed, so Suprnova's `strict` only changes whether two *numbers*
with different internal representations (`1` vs `1.0`) count as equal -
it never makes a string and a number "the same," in either mode.

Laravel writes the other field into a rule string - `in_array:allowed_roles.*` -
and the validator globs it out of the request data at run time. Suprnova
has no rule-string parser: you hand `InArray` the list directly, and the
compiler checks the field exists.

Laravel 13.27 tightened `in`, `in_array`, and `doesnt_contain` to strict
comparison because PHP's `==` turned `"1abc"`, `true`, and `"0x1"` into
matches. Suprnova never had that hole - `In` and `NotIn` compare `&str`
with `==` - and the new rules match JSON values variant by variant. Laravel's
`contains` stayed loose; Suprnova's does not. The cost is that these rules
cannot check a numeric array: `Contains(&["1"])` does not match `[1]`.

Laravel's `gt` family picks its measure at run time: the number itself for
numerics, `count()` for arrays, kilobytes for files, and character length
for everything else, with the numeric branch gated on whether the field
also carries `numeric` or `integer`. Suprnova writes the measure into the
rule instead, because a rule here cannot see the other rules on its field
and sniffing the value's shape is the coercion habit these rules exist to
avoid. Two of Laravel's four measures have no counterpart at all: a rule
only ever receives a string, so an array-valued sibling cannot be read,
and uploads never reach the rule surface - the multipart parser caps their
size before a handler sees them.

## The `validate!` macro

`validate!` runs a chain of rules over the fields of a struct, accumulating
every failure into one `ValidationErrors`. It's the idiomatic home for the
synchronous cross-field hook, [`after_validation`](#cross-field-hooks).

```rust
use suprnova::{validate, ValidationErrors, rules::{Required, Email, Min, Max, RequiredIf}};

fn after_validation(&self) -> Result<(), ValidationErrors> {
    // Contextual rules read sibling values from a `FormContext` you build
    // - a map of field name to its string value.
    let mut ctx = std::collections::HashMap::new();
    ctx.insert("billing_type".to_string(), self.billing_type.clone());
    validate! { self =>
        email       => Required, Email;          // required-shape row
        bio         ?: Min(10), Max(500);        // optional: validate only if Some
        card_number ?=> RequiredIf {             // conditional-presence (see below)
            other: "billing_type",
            value: "card",
        } => with ctx;
    }
}
```

Each row is one of three shapes:

- **`field => Rule1, Rule2;`** - required-shape. Rules run on `&self.field`
  directly (for `String`, `i64`, or anything that derefs to the rule's
  expected borrow) - or, for a `ValueRule`, on a `serde_json::Value`
  field directly. Which trait each rule uses is inferred automatically.
- **`field ?: Rule1, Rule2;`** - optional. The field is `Option<T>`; rules
  run only when it is `Some`, and are **skipped entirely on `None`**. This
  is Laravel's "if present, validate" (`sometimes`) semantics.
- **`field ?=> Rule1, Rule2;`** - conditional-presence. Also for an
  `Option<String>` field, but rules run **even when `None`** (absence is
  treated as the empty string). This is the row for presence-conditional
  rules like `RequiredIf` that must be able to *fail an absent field* -
  the case `?:` cannot express because it skips on `None`.

A contextual rule is followed by `=> with $ctx` (an
`&HashMap<String, String>` of sibling values). The macro is **synchronous** -
for async rules use the [hook](#async-rules-in-requests) below.

> **Warning:** A common trap: writing `card_number ?: RequiredIf {...} => with ctx;`. On
> a `?:` row, `None` skips all rules, so `RequiredIf` can never fail an
> absent field. Use `?=>` for any rule that must fire on absence.

## Cross-field hooks

`FormRequest` runs two cross-field hooks after the derived per-field rules.
On a real request, `extract()` runs derived `validate()`, then
`after_validation`, then `after_validation_async`, and bails at the first
failing stage. On a marked request, [Precognition](precognition.md) narrows
the rules before every stage. An unlisted field's failure does not block
a listed field's asynchronous check. Errors a hook adds are never filtered.

```rust
use suprnova::{FormRequest, ValidationErrors};
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate)]
pub struct UpdatePassword {
    #[validate(length(min = 8))]
    pub new_password: String,
    pub confirmation: String,
}

impl FormRequest for UpdatePassword {
    fn after_validation(&self) -> Result<(), ValidationErrors> {
        let mut errs = ValidationErrors::new();
        if self.new_password != self.confirmation {
            errs.add("confirmation", "passwords do not match");
        }
        errs.into_result()
    }
}
```

> **Note:** Override hooks need a hand-written `impl FormRequest` - the `#[request]`
> attribute and `#[derive(FormRequest)]` generate their own (empty) impl, so
> they're for the common no-override case only.

### Async rules in requests

The `validate!` macro can't weave in `.await`, so database-backed rules run
in `after_validation_async` - the final validation stage, which `extract()`
calls automatically. This is where [`Unique`](#the-unique-rule) and any
custom `AsyncRule` participate in automatic request validation; no
per-handler plumbing required.

```rust
use suprnova::{FormRequest, ValidationErrors, Unique, async_trait};
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate)]
pub struct CreateUser {
    #[validate(email)]
    pub email: String,
}

#[async_trait]
impl FormRequest for CreateUser {
    async fn after_validation_async(&self) -> Result<(), ValidationErrors> {
        let mut errs = ValidationErrors::new();
        Unique::new("users", "email")
            .check_async(&self.email, &mut errs, "email")
            .await;
        errs.into_result()
    }
}
```

On a real request, the async stage runs only after the synchronous stages
pass, so a syntactically invalid email never reaches the database `Unique`
query. On a marked request, an unlisted malformed field does not prevent
the listed fields' asynchronous rules from running.

A Data Object's derive writes its `FormRequest` impl, so it names its
hooks instead of overriding them: `#[data(after_validation = "fn")]` and
`#[data(after_validation_async = "fn")]`. See
[Data Objects](data.md#validation-rules-and-database-checks).

## The `Unique` rule

`Unique` checks that a value does not already exist in a table. Build it
with `Unique::new(table, column)` and refine with the fluent API:

```rust
use suprnova::Unique;

// email must be unique, ignoring the row currently being edited
Unique::new("users", "email").ignore(current_user_id)

// email unique *per tenant*, compared case-insensitively
Unique::new("users", "email")
    .where_eq("tenant_id", tenant_id)
    .case_insensitive()
```

| Builder method | Effect |
|----------------|--------|
| `.ignore(id)` | exclude the row whose `id` equals `id` (edit-self case) |
| `.ignore_with_column(col, id)` | exclude on a non-`id` key column |
| `.where_eq(col, value)` | scope the check to rows where `col = value`; multiple calls AND together |
| `.case_insensitive()` | compare with `LOWER(col) = LOWER(?)` |

Table, column, the exclusion key, and every `where_eq` column are validated
against an identifier allowlist before they reach the SQL string; the value
under test and all scope values are bound parameters.

`Unique` and `Exists` read the primary connection. Inside a
`DB::transaction` they read through that transaction, so they see the rows
it has written and not yet committed, as every other query in the closure
does.

### Unique is advisory - the database constraint is the guarantee

`Unique` runs a `SELECT COUNT(*)` **before** the write, so it carries an
unavoidable time-of-check/time-of-use race: two concurrent requests can
both pass the check and then both insert. Laravel's `unique` rule has the
identical property. The **only** real guarantee is a `UNIQUE` constraint
(or unique index) on the column in your migration.

Use the three together:

1. **The advisory rule** - a fast, friendly "that email is taken" message
   before submit (and so Precognition can validate the field).
2. **The `UNIQUE` constraint** - the authoritative guard against the race.
3. **`FrameworkError::from_unique_violation`** - at the write site, map the
   constraint violation the loser of a race receives back to the same clean
   422, instead of leaking a 500:

```rust
use suprnova::FrameworkError;

// `users.email` has a UNIQUE constraint in the migration.
let user = new_user
    .insert(db)
    .await
    .map_err(|e| FrameworkError::from_unique_violation(
        "email",
        "That email address is already registered.",
        e,
    ))?;
```

`from_unique_violation` returns a 422 `Validation` error when the database
error is a unique-constraint violation, and passes any other error through
unchanged (MySQL, Postgres, and SQLite are all recognized).

## The `Exists` rule

`Exists` is Laravel's `exists`: the value must name a row. It shares
`Unique`'s identifier allowlist and binds every value.

```rust
use suprnova::{AsyncRule, Exists, ValidationErrors};

let mut errs = ValidationErrors::new();

// A text column, through the AsyncRule path.
Exists::new("countries", "code")
    .check_async(&self.country, &mut errs, "country")
    .await;

// An integer column: check the typed value.
Exists::new("teams", "id")
    .check_value(self.team_id, &mut errs, "team_id")
    .await;

// Laravel's 'tag_ids.*' => 'exists:tags,id', scoped to the team.
// Each failure lands under tag_ids.<index>.
Exists::new("tags", "id")
    .where_eq("team_id", self.team_id)
    .check_each(&self.tag_ids, &mut errs, "tag_ids")
    .await;
```

| Method | Effect |
|--------|--------|
| `.where_eq(col, value)` | only rows where `col = value` count; multiple calls AND together |
| `.check_async(&str, errs, field)` | check a text value (the `AsyncRule` path) |
| `.check_value(value, errs, field)` | check a typed value, bound as itself |
| `.check_each(&[T], errs, field)` | check every element, one query per distinct value, errors under `field.<index>` |

Check an integer id with `check_value`, not `check_async`: Postgres does
not compare a text parameter with an integer column, so the `&str` path
fails there. Bound an array's length with a synchronous rule
(`#[validate(length(max = 100))]`), which runs first, so a huge array never
reaches the database.

When a database rule cannot run - a dead connection, an identifier the
allowlist refuses, a type the database will not compare - the field fails
with `validation-unchecked` ("could not be checked"), and the cause goes to
the log under the `suprnova::validation` target. `Unique` does the same. A
validation message is rendered into the response, so it never carries the
database's own words. Like `Unique`, `Exists` reads before the
write; a foreign key constraint is the guarantee that the row is still
there when you insert.

## Async authorization

`FormRequest::authorize(&Request) -> bool` runs **before** the body is
parsed, so it can reject unauthorized requests without reading the payload.
It is synchronous by design: at that point the request still holds the
streaming body, so the hook cannot `.await`. Authorization that needs to
hit the database or an async policy belongs in one of these places, not in
`authorize`:

- **Middleware** - runs before `extract()`, is `async`, and short-circuits
  by returning `Err(response)` (see [Middleware](middleware.md)).
  The right place for "is this user allowed to reach this route at all".
- **The Gate** - call `Gate::allows_async` / `Gate::authorize_async` in the
  handler once you have the authenticated user and the resource (see
  [Authorization](authorization.md)).
- **`after_validation_async`** - for an authorization check that depends on
  the parsed request body, run it in the async hook alongside your other
  async rules.

## Inertia form submissions

A validation failure answers two audiences differently. A REST client
gets the `422` with `{ message, errors }`. An Inertia visit gets a `303`
back to the form page with the errors flashed into the session, because
the Inertia client shows an error modal for any response it does not
recognise as an Inertia response - a `422` would never populate
`form.errors`.

Nothing in the handler changes. On the destination page each field
carries its first message as a string:

```svelte
{#if errors?.email}
  <p class="text-red-600">{errors.email}</p>
{/if}
```

See [Inertia responses](frontend-inertia-responses.md#validation-failures)
for error bags, `with_all_errors`, and where the redirect points.

## Design notes

- **Partial validation.** A real request builds the typed `FormRequest`,
  so a field that may be absent on submit must be `Option<T>`.
  [Precognition](precognition.md) parses and validates only the listed
  fields before every stage. An unlisted malformed field does not block
  the answer. The struct is built only for the real request.
- **Rule messages.** Built-in rules return keyed messages
  (`validation-min` plus its arguments and an English fallback), resolved
  through the catalog at the serialization boundary. Translate or reword
  any of them by defining the same id in `lang/<locale>/validation.ftl` -
  no rule wrapping. See [Localization](localization.md).
- **Derive messages.** A `#[validate(...)]` failure reads the catalog id
  `validation-<code>`, where `<code>` is the validator crate's code with
  `_` as `-`. `#[validate(ip)]`, `ip(v4)` and `ip(v6)` all report `ip`, so
  they read `The address field must be a valid IP address.`, as Laravel's
  `ip` does. `range` with only a `max` reads `The quantity field must not
  be greater than 100.`, Laravel's numeric `max` message; a string's
  `length(max = ...)` keeps `must be at most 100 characters`.
- **`Min` / `Max` / `Between`** are string-length rules (counted in Unicode
  scalar values). For numeric bounds, validate with `#[validate(range(...))]`
  on the derive or a custom rule - the length rules are not value
  comparisons.

## Summary

| Task | API |
|------|-----|
| Per-field rules | `#[validate(...)]` on the `FormRequest` (see Requests) |
| Composed / cross-field rules | `validate! { self => ... }` |
| JSON-shaped rule (array/object) | `field => ArrayKeys(&[...]);` / `field => Distinct { .. };` |
| Optional "if present" | `field ?: Rule;` |
| Conditionally-required optional | `field ?=> Rule => with ctx;` |
| Required while a condition holds | `field ?=> RequiredIf::when(condition);` |
| Async / DB-backed rule | `after_validation_async` + `AsyncRule::check_async` |
| Uniqueness | `Unique::new(t, c)` + `UNIQUE` constraint + `from_unique_violation` |
| Existence | `Exists::new(t, c)` + a foreign key constraint |
| Hooks on a Data Object | `#[data(after_validation = "fn")]`, `#[data(after_validation_async = "fn")]` |
| Async authorization | middleware / `Gate::*_async` / `after_validation_async` |

## Next

- [Requests](requests.md) - the `#[request]` / `#[derive(FormRequest)]`
  surface, the everyday derived-validation path
- [Data Objects](data.md) - `#[derive(Data, Validate)]` for one struct
  that's both an inbound request and an outbound DTO
- [Error Model](error-model.md) - how `ValidationErrors` becomes the
  422 JSON body, alongside every other error path
- [Localization](localization.md) - translating rule messages, the
  `field-<name>` convention, and keyed `ValidationMessage`s
- [Authorization](authorization.md) - `Gate`, `Policy`, and where
  authorization belongs relative to validation
- [Middleware](middleware.md) - the right place for "is this request
  even allowed through" checks that need `.await`


---

<!-- /docs/precognition -->

# Precognition

Precognition lets you validate a draft with your server's rules before
you submit it. You use the same route for live validation and the real
request. You keep validation in [form requests](requests.md) and show
its errors in your frontend.

## Opt in to Precognition

Add `Precognitive` to a route or a route group. A route without this
middleware ignores the `Precognition` header and handles a real request.
This example validates an email and redirects to the form on the real
submit. Your kit's bootstrap supplies the Inertia middleware:

```rust
use suprnova::{
    InertiaResponse, Precognitive, Redirect, Request, Response,
    get, handler, post, request, routes,
};

#[request]
pub struct CreateUser {
    #[validate(email(message = "Enter a valid email address."))]
    pub email: String,
}

#[handler]
pub async fn create(req: Request) -> Response {
    Ok(InertiaResponse::new("Users/Create").resolve(&req).await?)
}

#[handler]
pub async fn store(_form: CreateUser) -> Response {
    Ok(Redirect::to("/users/create"))
}

routes! {
    get!("/users/create", create),
    post!("/users", store).middleware(Precognitive),
}
```

Send `Precognition: true` to ask for live validation. The middleware marks
the request before the later middleware and extractors run. Route
parameters and model bindings resolve, and form requests validate. The
handler body never runs, whether it is a closure or a controller method.

Every response from a route carrying `Precognitive` includes
`Precognition` in `Vary`. An existing `Vary` value is kept. Every response
to a marked request also carries `Precognition: true`, including a `401`,
`403`, `404`, `409` or `423` from later middleware or an extractor.
A passing live validation answers `204` with `Precognition-Success: true`.
A failing validation answers `422` with `{ message, errors }`.

Try the route with a running application:

```sh
curl -i http://127.0.0.1:8765/users \
  -H 'Content-Type: application/json' \
  -H 'Precognition: true' \
  -H 'Precognition-Validate-Only: email' \
  --data '{"email":"ada@example.com"}'
```

You receive `204` and the two Precognition headers. Send an invalid email
to see the `422` error bag. Omit `Precognition` to run `store`.

## Live validation with Inertia 3.8

Inertia 3.8 ships the Precognition client. If you use a Suprnova starter
kit, you install nothing extra. Import `useForm` from your Inertia adapter,
call `.withPrecognition('post', '/users')`, and call
`form.validate('email')` when the input loses focus. Submit normally with
`form.post('/users')`. Put the component in
`frontend/src/pages/Users/Create.vue`, `Create.tsx` or `Create.svelte`
for your adapter. Visit `/users/create`. Each example below posts to the
route above.

### Vue

```vue
<script setup lang="ts">
import { useForm } from '@inertiajs/vue3'

const form = useForm({ email: '' }).withPrecognition('post', '/users')
</script>

<template>
  <form @submit.prevent="form.post('/users')">
    <label for="email">Email</label>
    <input
      id="email"
      type="email"
      v-model="form.email"
      @blur="form.validate('email')"
    />
    <p v-if="form.errors.email">{{ form.errors.email }}</p>
    <p v-if="form.validating">Validating...</p>
    <button type="submit" :disabled="form.processing">Submit</button>
  </form>
</template>
```

### React

```tsx
import { useForm } from '@inertiajs/react'

export default function CreateUser() {
  const form = useForm({ email: '' }).withPrecognition('post', '/users')

  return (
    <form onSubmit={(event) => {
      event.preventDefault()
      form.post('/users')
    }}>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        value={form.data.email}
        onChange={(event) => form.setData('email', event.target.value)}
        onBlur={() => form.validate('email')}
      />
      {form.errors.email && <p>{form.errors.email}</p>}
      {form.validating && <p>Validating...</p>}
      <button type="submit" disabled={form.processing}>Submit</button>
    </form>
  )
}
```

### Svelte

```svelte
<script lang="ts">
  import { useForm } from '@inertiajs/svelte'

  const form = useForm({ email: '' }).withPrecognition('post', '/users')
</script>

<form onsubmit={(event) => {
  event.preventDefault()
  form.post('/users')
}}>
  <label for="email">Email</label>
  <input
    id="email"
    type="email"
    bind:value={form.email}
    onblur={() => form.validate('email')}
  />
  {#if form.errors.email}<p>{form.errors.email}</p>{/if}
  {#if form.validating}<p>Validating...</p>{/if}
  <button type="submit" disabled={form.processing}>Submit</button>
</form>
```

See [Inertia responses](frontend-inertia-responses.md) for pages and
redirects after the real submit.

## Client configuration

The client sends `Precognition: true`, `Accept: application/json` and
`Precognition-Validate-Only` with the field names it wants to validate,
joined with commas. The list can be empty when no field is touched.
The client debounces validation with a default timeout of 1500 ms.
Set your own timeout on any of the three forms:

```js
form.setValidationTimeout(500)
```

The client checks `Precognition: true` on success and error responses.
Without it, the client throws `Did not receive a Precognition response`.
Check that your target route carries `Precognitive`. This check happens
before status callbacks such as forbidden or not-found handling.

## Validating arrays and wildcards

`Precognition-Validate-Only` names fields exactly. A `*` matches one
non-empty path segment. `tags.*` covers `tags.3`, but `tags` does not.
`users.*.email` covers `users.2.email`, but not `users.2.profile.email`.
Use the input's name, including any serde rename:

```js
form.validate('users.*.email')
```

On a marked request, only the listed fields' rules run. The list narrows
the rules before validation, through the derived rules, the synchronous
hook and the asynchronous hook. An unlisted field that fails or does not
parse cannot prevent a listed field's database check from running.
Without the header, you validate all fields. An empty header validates
no fields and answers `204` when no hook adds an error.

Errors an after-validation hook adds are never filtered. Any such error
answers `422`, even if its field is outside the list. What the list
narrows is the checks a hook runs, as Laravel removes the rules of
unlisted fields before its validator runs.

## Database rules in hooks

While the after-validation hooks of a form request, a data object or a
multipart form run for a marked request that lists fields,
`Precognition::should_validate(field)` answers whether the field is
listed, by the same exact and wildcard match. Outside such a request it
answers `true`, so a real submit runs every check.

The built-in database rules ask it before they query. `check_async` (on
`Unique`, `Exists` and `Password`), `Exists::check_value` and
`Exists::check_each` skip a field the request did not list: no query
runs and no error is added. `check_each` is selected under the key
`<field>.*`, the key Laravel gives an array rule, so `tag_ids.*` in the
list runs it and `tag_ids` alone does not:

```rust
use suprnova::{AsyncRule, Exists, FormRequest, Precognition, Unique, ValidationErrors, async_trait};

#[derive(serde::Deserialize, validator::Validate, suprnova::FormRequestDerive)]
#[form_request(custom_hooks)]
pub struct Signup {
    #[validate(email)]
    pub email: String,
    pub tag_ids: Vec<i64>,
}

#[async_trait]
impl FormRequest for Signup {
    async fn after_validation_async(&self) -> Result<(), ValidationErrors> {
        let mut errors = ValidationErrors::new();
        // Skipped when the request lists fields and `email` is not one.
        Unique::new("users", "email")
            .check_async(&self.email, &mut errors, "email")
            .await;
        // Runs for `tag_ids.*`, not for `tag_ids`.
        Exists::new("tags", "id")
            .check_each(&self.tag_ids, &mut errors, "tag_ids")
            .await;
        // Your own per-field work asks the same question.
        if Precognition::should_validate("email") && self.email.ends_with("@example.invalid") {
            errors.add("email", "Use a real address.");
        }
        errors.into_result()
    }
}
```

A field is matched both as you name it in Rust and under the input name
serde renames it to. `Request::should_validate(field)` keeps its meaning
for middleware and custom rules that hold the request. See
[Validation](validation.md) for rule objects and cross-field hooks.

## Validation outside a form request

`Precognition::after_validation(&request, errors)` turns an error bag
you built yourself into the Precognition answer, as Laravel's
`Precognition::afterValidationHook` does for any validator. On a marked
request an empty bag answers `204` with `Precognition-Success: true` and
a non-empty one `422` with the bag. On another request an empty bag
returns `Ok(())` and the request goes on, and a non-empty one is the
ordinary validation error: a redirect back with the errors for an HTML
form, `422` otherwise.

```rust
use suprnova::{Middleware, Next, Precognition, Request, Response, ValidationErrors, async_trait};

pub struct RequireTeam;

#[async_trait]
impl Middleware for RequireTeam {
    async fn handle(&self, request: Request, next: Next) -> Response {
        let mut errors = ValidationErrors::new();
        if request.should_validate("team") && request.header("X-Team").is_none() {
            errors.add("team", "Choose a team.");
        }
        Precognition::after_validation(&request, errors)?;
        next(request).await
    }
}
```

Register it after `Precognitive`, so the request is marked. The bag is
used as you give it: check a field only when `request.should_validate`
answers `true` for it.

## Customizing rules for live validation

Use `Request::is_precognitive()` to ask whether the middleware marked
the request. Use `Request::is_attempting_precognition()` to ask whether
the header alone requests Precognition. On a route without `Precognitive`,
the second can be true while the first is false. Use the marked state
when you decide whether to skip a rule or a side effect.

`Request::validate_only()` exposes the parsed list on a marked request.
Outside a marked request, the selection is absent and every field is included.
`Request::should_validate(field)` applies the same exact and wildcard
match as the validator. Use it in middleware or a custom rule before
you run a field's own check. A handler can use it on the real request;
its body never runs on a marked one.

The client leaves files out of live validation by default. Declare a file
as optional in your form request, then require it on the real submit.
For example, this custom check requires an avatar only on a real request:

```rust
use suprnova::{ImageFile, Request, UploadedFile, ValidationErrors};

fn require_avatar(
    req: &Request,
    avatar: Option<&UploadedFile<ImageFile>>,
) -> Result<(), ValidationErrors> {
    let mut errors = ValidationErrors::new();
    if !req.is_precognitive() && avatar.is_none() {
        errors.add("avatar", "Choose an avatar.");
    }
    errors.into_result()
}
```

Pass the request and the parsed optional file to your custom check where
you validate uploads. Keep the file's image and size checks for any file
the client actually sends. A missing file during live validation does
not make the real submit's required-file rule optional.

## File uploads and query data

Call `form.validateFiles()` to include files in live validation. A
precognitive multipart request validates both its files and its fields
through the same form-request path as a JSON body. Your upload validators
still check any listed file. See [Requests](requests.md) for
`Option<UploadedFile<ImageFile>>`, file lists and size limits.

A precognitive `GET` or `DELETE` validates query parameters. A `key[]`
parameter reads as a list. A JSON-encoded object reads as an object.
For example, a marked `GET /users?email=` fails a required email rule;
the absence of a JSON body does not make it pass.

For inline validation, use `Request::validate::<T>()` with your form
request type. On a marked request it applies the same narrowing and
answers `204` or `422` with the Precognition headers. It does not return
the typed value and continue into a write. Put inline validation in
middleware when it must run on a marked request, since the handler body
is skipped.

## Managing side effects

Put writes, queued mail and other submit work in the handler body. The
framework runs extractors and stops before that body on a marked request.
Middleware still runs. After `Precognitive` marks the request, check
`is_precognitive()` in any later middleware before you count an interaction
or perform another side effect. Middleware outside it has not seen the mark.

Use `Precognition::precognitive` around a pre-check closure when you need
the same choice outside dispatch. The helper runs the closure. If the
closure bails with a response, it uses the precognition-specific response
on a marked request and the default response otherwise. If the closure
does not bail, it answers `204` with `Precognition-Success: true` on a
marked request and returns the closure's value on a real one.

A marked request does not save the session. It neither ages nor consumes
flash data and writes no session row. It also does not become the
previous URL, in either the session middleware or Inertia's previous-URL
store. Your next page still receives its toast, and redirecting back
still leads to the page you visited. See [Session](session.md).

## The 422 body

A failing live validation and a failing real JSON request use the same
error bag. `errors` maps each field to a list of messages. `message`
starts with the first error's message. It adds ` (and 1 more error)` for
one remaining error, or ` (and N more errors)` for more than one:

```json
{
  "message": "Enter a valid email address. (and 2 more errors)",
  "errors": {
    "email": ["Enter a valid email address."],
    "name": ["Enter your name."],
    "password": ["Use at least eight characters."]
  }
}
```

You localize the count suffix with `validation-summary-more` in your
request's locale catalog, with an English fallback when the message is missing.

With only one error, `message` has no count. Bind field errors to their
exact keys, including dotted array paths.

## Testing

Use `with_precognition()` on a test request to send `Precognition: true`.
Use `assert_successful_precognition()` on its response to assert both
`204` and `Precognition-Success: true`. This complete test also proves
the handler body does not run:

```rust
use std::sync::atomic::{AtomicUsize, Ordering};
use suprnova::testing::TestClient;
use suprnova::{
    MiddlewareRegistry, Precognitive, Response, handler, json_response,
    post, request, routes,
};

#[request]
pub struct EmailDraft {
    #[validate(email)]
    pub email: String,
}

static HANDLER_RUNS: AtomicUsize = AtomicUsize::new(0);

#[handler]
pub async fn store(form: EmailDraft) -> Response {
    HANDLER_RUNS.fetch_add(1, Ordering::SeqCst);
    json_response!({ "email": form.email })
}

routes! {
    post!("/users", store).middleware(Precognitive),
}

#[tokio::test]
async fn validates_without_running_the_handler() {
    let client = TestClient::new(register(), MiddlewareRegistry::new());

    client.post("/users")
        .with_precognition()
        .header("Precognition-Validate-Only", "email")
        .json(&serde_json::json!({ "email": "ada@example.com" }))
        .send().await
        .assert_successful_precognition();

    assert_eq!(HANDLER_RUNS.load(Ordering::SeqCst), 0);
}
```

See [HTTP tests](http-tests.md) for the client and its other assertions.

### Why Suprnova diverges

- **Header values ignore case.** You can send `Precognition: TRUE` or
  `true`. Laravel matches `true` exactly. This keeps the header read
  consistent with Suprnova's existing clients.
- **Field names are trimmed.** You can send
  `Precognition-Validate-Only: email, name`. Suprnova trims each name;
  Laravel splits on commas without trimming. Spaces around a listed
  name do not change the field you asked to validate.
- **Hooks narrow their database rules, not their errors.** Laravel
  removes the rules of unlisted fields from the rule set before its
  validator runs. Suprnova runs database rules from the after-validation
  hooks, so the hooks see the selection through
  `Precognition::should_validate` and the built-in database rules skip
  unlisted fields there. An error a hook adds itself is never filtered.
- **Form requests are typed.** The struct is built only for the real
  request. During live validation, the listed fields parse and validate
  without requiring values for every other field. A parse failure on an
  unlisted field does not block the listed fields' answer. Your real
  submit still needs every required field to parse before you receive
  the typed struct. During live validation, a field whose type parses a
  string itself (a date, an address) answers its own parse error when its
  value does not parse, even when you leave it unlisted.

## Next

- [Validation](validation.md) - rule objects and validation hooks
- [Requests](requests.md) - typed form requests, query data and uploads
- [Inertia responses](frontend-inertia-responses.md) - pages, redirects
  and errors after the real submit


---

<!-- /docs/errors -->

# Error Handling

This is the day-to-day patterns guide for writing fallible code in
Suprnova handlers, services, and middleware. For the underlying model -
the conversion contract, the panic boundary, the 5xx sanitisation
rule, the development error page, observability hooks - read
[Error Model](error-model.md). This chapter shows what to actually type.

The shape to remember:

- Handlers return `Response = Result<HttpResponse, HttpResponse>`.
- `?` performs one direct `From<E>` conversion into the handler's error
  type; Rust does not chain `DbErr -> FrameworkError -> HttpResponse`.
  In a `Response` handler, convert a SeaORM error explicitly. Code that
  already returns `Result<_, FrameworkError>` may use `.await?` directly.
- Three free helpers (`abort_with`, `abort_if`, `abort_unless`) let
  you short-circuit at a status code without naming an error type.

```rust
use sea_orm::EntityTrait;
use suprnova::{DB, FrameworkError, Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;
    let user = users::Entity::find_by_id(id)
        .one(&*DB::get()?)
        .await
        .map_err(FrameworkError::from)?
        .ok_or_else(|| FrameworkError::not_found("User"))?;
    json_response!({ "user": user })
}
```

The rest of the chapter is the catalogue of error producers - what
to construct, what status it returns, what shape the client sees.

## `?` is the conversion

Every `?` in a handler body performs one direct
`From<E> for HttpResponse` conversion. The framework provides direct
conversions for its handler-facing error types, but Rust does not chain
multiple `From` implementations. Convert an intermediate error explicitly
when it has no direct conversion to `HttpResponse`.

```rust
use suprnova::{DB, FrameworkError, Request, Response, json_response};
use sea_orm::EntityTrait;

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;

    let user = users::Entity::find_by_id(id)
        .one(&*DB::get()?)
        .await
        .map_err(FrameworkError::from)?
        .ok_or_else(|| FrameworkError::not_found("User"))?;

    json_response!({ "user": user })
}
```

Four conversions happen in that snippet:

1. `req.param("id")?` directly converts `ParamError` to an
   `HttpResponse` (400).
2. The parse error is explicitly mapped to `FrameworkError::ParamError`,
   which `?` then directly converts to an `HttpResponse` (400).
3. The SeaORM error is explicitly mapped from `DbErr` to
   `FrameworkError::Database`; `?` then directly converts that
   `FrameworkError` to an `HttpResponse` (500, sanitised on the wire).
4. `.ok_or_else(...)?` turns `None` into
   `FrameworkError::ModelNotFound`, which converts to an
   `HttpResponse` (404).

Each `?` uses one direct conversion. Code that returns
`Result<_, FrameworkError>` instead of `Response` may use `.await?` on
the SeaORM call because `DbErr` converts directly to `FrameworkError`.

Every one of those conversions ends in the framework's JSON error body -
`{ "message": …, "request_id": … }` at the matching status. That is the
right answer for an API client and the wrong one for an Inertia visit,
which needs a page. Name an
[error page](frontend-inertia-responses.md#error-pages) and an Inertia
app renders these errors as a real page while API clients keep the JSON
unchanged. With debug mode on, a 5xx reaches a browser or an Inertia
visit as the [development error page](#see-a-failure-in-the-browser)
instead.

## `AppError` - inline domain errors

Use `AppError` for one-off errors that don't deserve a dedicated type.
The constructors map onto Laravel's `abort($status, $msg)` shape:

| Constructor | Status |
|---|---|
| `AppError::new(msg)` | 500 |
| `AppError::bad_request(msg)` | 400 |
| `AppError::unauthorized(msg)` | 401 |
| `AppError::forbidden(msg)` | 403 |
| `AppError::not_found(msg)` | 404 |
| `AppError::conflict(msg)` | 409 |
| `AppError::unprocessable(msg)` | 422 |
| `AppError::new(msg).status(code)` | any |

`AppError` has a `From` into `FrameworkError`, so `?` works with no
ceremony:

```rust
use suprnova::{AppError, Request, Response, json_response};

pub async fn transfer(req: Request) -> Response {
    let amount: i64 = req.param("amount")?.parse()
        .map_err(|_| AppError::bad_request("amount must be a number"))?;

    if amount <= 0 {
        return Err(AppError::unprocessable("amount must be positive").into());
    }

    if amount > balance() {
        return Err(AppError::forbidden("amount exceeds daily limit").into());
    }

    json_response!({ "transferred": amount })
}
```

Note the asymmetry: `AppError::unauthorized` is **401** (missing
authentication credentials), while `FrameworkError::Unauthorized` is
**403** (policy denied an authenticated user). They mean different
things; pick the one that matches the failure.

## `FrameworkError` - the canonical enum

Internal extractors, the container, route binding, validation, the
database layer, and storage all produce `FrameworkError`. You usually
construct one through a convenience constructor and let `?` route it.

```rust
use suprnova::FrameworkError;

FrameworkError::not_found("User");                    // 404
FrameworkError::bad_request("Bad input");             // 400
FrameworkError::param("user_id");                     // 400
FrameworkError::param_parse("user_id", "i64");        // 400
FrameworkError::validation("email", "required");      // 422
FrameworkError::domain("Conflict", 409);              // 409 (any code)
FrameworkError::internal("disk full");                // 500
FrameworkError::database("timeout");                  // 500
FrameworkError::service_not_found::<MyService>();     // 500
FrameworkError::model_not_found("Post");              // 404
```

The full variant set, with implications for the response shape, is in
[Error Model](error-model.md). The constructors above cover every
common case; you reach for the variants directly only when matching on
an error you received.

### Automatic conversions

`FrameworkError` already converts from the error types your dependencies emit.
Both of these `?`s convert automatically:

```rust
use suprnova::{DB, FrameworkError};
use sea_orm::ActiveModelTrait;

pub async fn create_user(new_user: users::ActiveModel)
    -> Result<users::Model, FrameworkError>
{
    // DB::get returns Result<_, FrameworkError>.
    // .insert returns Result<_, DbErr>, with From<DbErr> for FrameworkError.
    let user = new_user.insert(&*DB::get()?).await?;
    Ok(user)
}
```

The framework also implements `From<opendal::Error>` for storage
operations and `From<ParamError>` for path-parameter extraction.

### Re-raising with context

When you want to annotate where an error came from without losing the
status code, use `.context()`:

```rust
db.insert(user).await
    .map_err(FrameworkError::from)
    .map_err(|e| e.context("creating new user"))?;
```

The message becomes `"creating new user: <original>"`. Structured
variants (`Validation`, `ValidationError`, `ModelNotFound`,
`ParamParse`, `PrecognitionFailure`, `PrecognitionSuccess`,
`Unauthorized`, `UnsupportedMediaType`, `AlreadyReported`,
`RateLimited`, `Timeout`, `External`) keep their variant so the response renderer
still emits the right shape (and, for `External`, so the wrapped
source survives); flat message-carrying variants (`Internal`,
`Database`, `Domain`) flatten into a `Domain` with the prefixed
message and the original status preserved.

### Turning duplicate-key errors into 422

The `Unique` validation rule runs a `SELECT COUNT(*)` before the
write, so it's advisory - two concurrent requests can both pass and
then both attempt the insert. The losing request gets a database
unique-constraint violation, which would otherwise leak as a 500.
`from_unique_violation` translates it into the same 422 the advisory
rule would have produced:

```rust
use suprnova::FrameworkError;

let user = new_user.insert(db).await.map_err(|e| {
    FrameworkError::from_unique_violation(
        "email",
        "That email address is already registered.",
        e,
    )
})?;
```

If the underlying `DbErr` isn't a unique-constraint violation it
passes through unchanged as a 500-class `Database` error. Backend
coverage is whatever SeaORM's `DbErr::sql_err` recognises - Postgres,
MySQL/MariaDB, and SQLite all map their duplicate-key errors through.

### Wrapping a foreign error

Every other variant stringifies what it wraps. `from_external_with` keeps the original error
reachable, so logs can render the whole chain and code can still ask what actually failed:

```rust
use suprnova::FrameworkError;

let row = sqlx_like_query()
    .await
    .map_err(|e| FrameworkError::from_external_with("verify query failed", e))?;
```

`from_external(e)` is the same thing with the error's own `Display` as the message. Both map to
HTTP 500.

To inspect the original, use `external_source()` rather than `source()`:

```rust
if let Some(src) = err.external_source() {
    if let Some(db) = src.downcast_ref::<sea_orm::DbErr>() {
        // decide whether this is worth retrying
    }
}
```

`std::error::Error::source()` hands back the shared `Arc` handle, not the wrapped error, so
downcasting through it returns `None`. `external_source()` dereferences the handle first.

The framework renders the full chain into the 5xx log line. When `APP_DEBUG=true`, it also shows
the chain on the [development error page](#see-a-failure-in-the-browser) for a browser or an
Inertia visit, and in the `debug_message` field of the JSON body for every other client, so a
wrapped error's text is never lost.

### Preserving rate-limit hints

When a downstream service throttles you and supplies a `Retry-After` hint, wrapping the failure
in `internal(...)` melts the duration into prose. `rate_limited` keeps it structured:

```rust
use std::time::Duration;
use suprnova::FrameworkError;

let err = FrameworkError::rate_limited(
    Some(Duration::from_secs(30)),
    "push provider rejected the batch",
);

assert_eq!(err.retry_after(), Some(Duration::from_secs(30)));
assert_eq!(err.status_code(), 429);
```

Queue retry policies, jitter scheduling, and the HTTP `Retry-After` response header all read the
hint back through `retry_after()`, which returns `None` for every other variant and for throttles
that came without one. `.context(...)` preserves the variant, so adding operation context does not
strip the duration.

### Telling a passed deadline from a failure

`FrameworkError::Timeout` means a deadline passed before the awaited work
finished. `FrameworkError::timeout(elapsed, message)` builds one, and
`is_timeout()` asks for it. It renders as `504 Gateway Timeout`, and the
client sees the generic 5xx message. The workflow wait returns it, so a
handler can tell a workflow that is still running from a failure:

```rust
use std::time::Duration;
use suprnova::FrameworkError;

let err = FrameworkError::timeout(Duration::from_secs(30), "waiting for the export");

assert!(err.is_timeout());
assert_eq!(err.status_code(), 504);
```

See [Error Model](error-model.md#telling-a-passed-deadline-from-a-failure) and
[Workflows](workflows.md#waiting-on-results).

## Custom domain errors

Three tiers, depending on how reusable the error needs to be.

### `#[domain_error]` for the typed case

Most reusable errors want a name, a fixed status, and a fixed message
template - no per-call message. The `#[domain_error]` attribute macro
generates `Display`, `std::error::Error`, `HttpError`, and `From` for
`FrameworkError` in one shot:

```rust
use suprnova::domain_error;

#[domain_error(status = 404, message = "User not found")]
pub struct UserNotFound;

#[domain_error(status = 402, message = "Insufficient funds")]
pub struct InsufficientFunds {
    pub available: i64,
    pub requested: i64,
}
```

Use them at the call site with `?`:

```rust
use crate::errors::user_not_found::UserNotFound;

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;

    let user = find_user(id).await
        .ok_or_else(|| FrameworkError::from(UserNotFound))?;

    json_response!({ "user": user })
}
```

The macro rejects malformed attributes loudly at compile time -
overflowed status codes (`status = 70_000`), wrong literal types
(`message = 42`), unknown keys - so you can't silently get the wrong
status because of a typo.

#### Scaffold one with the CLI

```bash
suprnova make:error UserNotFound
```

Writes `src/errors/user_not_found.rs` with a default `status = 500`
and an inferred sentence-cased message, and updates `src/errors/mod.rs`
to re-export it. Edit the `status` and `message` to taste.

### `HttpError` for the hand-rolled case

When a domain error needs runtime state in the message (e.g. the IDs
involved in the failure), implement `HttpError` directly. The trait
has two methods with sensible defaults:

```rust
use suprnova::HttpError;

#[derive(Debug)]
pub struct InsufficientFunds {
    pub available: i64,
    pub requested: i64,
}

impl std::fmt::Display for InsufficientFunds {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Insufficient funds: have {}, need {}",
            self.available, self.requested)
    }
}

impl std::error::Error for InsufficientFunds {}

impl HttpError for InsufficientFunds {
    fn status_code(&self) -> u16 { 402 }
    fn error_message(&self) -> String {
        format!("Need {} units, only {} available.",
            self.requested, self.available)
    }
}
```

To bridge a hand-rolled `HttpError` into `?`, call
`FrameworkError::from_http_error`. A blanket `From<T: HttpError> for
FrameworkError` would conflict with the existing `From<AppError>`
impl, so the bridge is an explicit constructor:

```rust
account.withdraw(amount)
    .map_err(FrameworkError::from_http_error)?;
```

### Error enums for one module's failures

When a service has several related failures, group them in an enum
and write one `From` for the whole enum:

```rust
use suprnova::FrameworkError;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum OrderError {
    #[error("Order {0} not found")]
    NotFound(i64),

    #[error("Insufficient stock for product {product_id}")]
    InsufficientStock { product_id: i64 },

    #[error("Payment failed: {0}")]
    PaymentFailed(String),

    #[error("Order already shipped")]
    AlreadyShipped,
}

impl From<OrderError> for FrameworkError {
    fn from(err: OrderError) -> Self {
        let status = match &err {
            OrderError::NotFound(_) => 404,
            OrderError::InsufficientStock { .. } => 422,
            OrderError::PaymentFailed(_) => 402,
            OrderError::AlreadyShipped => 409,
        };
        FrameworkError::Domain {
            message: err.to_string(),
            status_code: status,
        }
    }
}
```

Once the `From` exists, the enum threads through `?` the same as any
other error type.

## `abort_with` / `abort_if` / `abort_unless`

Three helpers short-circuit a handler at a status. They mirror
Laravel's `abort` / `abort_if` / `abort_unless`. (The free function is
exported as `abort_with` rather than `abort` to keep the latter
available as a method name on user types.)

```rust
use suprnova::{abort_if, abort_unless, abort_with, Request, Response, json_response};

pub async fn show(req: Request) -> Response {
    abort_unless(Auth::user().await?.is_some(), 401, "must be logged in")?;
    abort_if(req.param("id")? == "0", 404, "User not found")?;
    abort_with(503, "scheduled maintenance")?;

    json_response!({ "ok": true })
}
```

Each returns `Result<(), FrameworkError>`, so `?` does the work. The
underlying error is `FrameworkError::Domain { message, status_code }`,
which renders through the same body shape as every other error. Out-of-range
status codes are coerced to 500 by the response renderer; you don't need to
defend against bad input at the call site.

## `ValidationErrors` - the Laravel-shaped error bag

When validation fails - at `#[derive(Validate)]` time or in an
`after_validation` body - the framework emits the JSON shape Laravel
and Inertia front-ends expect:

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "email": ["The email field must be a valid email address."],
        "password": ["The password field must be at least 8 characters."]
    },
    "request_id": "8f9e1a2b-c3d4-..."
}
```

Most of the time you don't construct this directly - `#[derive(Validate)]`
runs and the framework converts `validator::ValidationErrors` for
you. When you need to add errors imperatively (cross-field rules, async
uniqueness checks that complement `Unique`), build a `ValidationErrors`
and return it:

```rust
use suprnova::{FrameworkError, ValidationErrors};

pub async fn after_validation(payload: &Signup) -> Result<(), FrameworkError> {
    let mut errs = ValidationErrors::new();

    if payload.email.ends_with("@example.com") {
        errs.add("email", "example.com addresses are not allowed");
    }
    if payload.password == payload.email {
        errs.add("password", "password must not match email");
    }

    errs.into_result().map_err(FrameworkError::Validation)
}
```

`add_to_bag` scopes a field under a named bag (Laravel's
`withErrors($errors, 'profile')` shape) by prepending the bag with a
`.` separator. Useful when one response carries errors from multiple
sub-forms that can't share a flat namespace:

```rust
let mut errs = ValidationErrors::new();
errs.add_to_bag("profile", "bio", "must be under 280 characters");
errs.add_to_bag("billing", "card", "expired");
// errors map: { "profile.bio": [...], "billing.card": [...] }
```

`from_validator(ve)` converts a `validator::ValidationErrors`;
`retain_fields(&keep)` returns a copy containing only the listed
entries (used by Precognition's `Precognition-Validate-Only` header
internally).

## Send errors to a tracker

Set `REPORTING_DSN` to send errors to Rustrak, Sentry or GlitchTip through
Suprnova's built-in `sentry` driver. The reporter also receives background
failures. You do not need an `ErrorOccurred` listener or a direct SDK call.
See [Error Reporting](error-reporting.md) for local Rustrak, drivers,
settings, scrubbing and browser reporting.

`ErrorOccurred` remains an application event for 5xx responses, including
responses built from panics. Its raw error message and request id can drive
application-specific listeners. The event is not scrubbed for export;
use the reporting driver when sending errors outside the application.

## Report errors with `Exceptions`

`Exceptions` is the place every error the framework does not answer
itself goes through, as Laravel's exception handler is. These errors are
reported:

- Every `FrameworkError` that becomes a 5xx response. `ErrorOccurred`
  still fires after it.
- Every error behind a 5xx response the framework builds itself: a
  session the store cannot write, a Live or WebSocket request the
  framework cannot prepare or answer, a rate limiter or render cache that
  fails closed, a readiness probe whose database check fails, and a
  payment webhook that fails.
- Every failed attempt of a queued job: a handler that returns `Err` or
  panics, an attempt that runs past its timeout, and an error
  `FailOnException` fails the job for.
- Every error a console command returns, and every failure of the boot
  before it runs: a `bootstrap` that panics, such as one whose
  `DB::init().await.expect(..)` finds no database, a log channel nothing
  defines, or a service the container cannot build. This covers the
  console binary's commands and the application binary's (`queue:work`,
  `schedule:interrupt`, `down` and the others). The callbacks your
  `bootstrap` registered before it failed see the failure.
- Scheduled task errors and caught panics, workflow step panics, supervisor
  failures, WebSocket session failures and rescued Inertia props.
- Every error you pass to `Exceptions::report` or the `report` helper.

A report runs your callbacks in the order you registered them. Then it
writes the `framework error` log line, with the status, the full source
chain, and the request id when there is one. When the framework builds a
5xx for a failure it has already logged, such as a rate limiter that fails
closed, you get that line, with its own fields, in place of the
`framework error` line, so each failure is logged once. A callback with
`stop()` prevents subsequent callbacks and the reporting driver from receiving
that error. An already-written log line is not removed.

Register callbacks once, in `bootstrap.rs`. The parameter type of the
closure decides which errors it receives:

```rust
use suprnova::{Exceptions, FrameworkError};

#[derive(Debug)]
pub struct PaymentDeclined(pub String);

impl std::fmt::Display for PaymentDeclined {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "payment declined: {}", self.0)
    }
}

impl std::error::Error for PaymentDeclined {}

pub fn register_reporting() {
    // Every reported error.
    Exceptions::reportable(|error: &FrameworkError| {
        eprintln!("reported: {error}");
    });

    // Only errors that wrap a `PaymentDeclined`. `stop()` keeps the
    // callbacks after this one, the default log line and the reporting
    // driver from running for those errors.
    Exceptions::reportable(|error: &PaymentDeclined| {
        eprintln!("billing alert: {error}");
    })
    .stop();
}
```

A callback that takes `&FrameworkError` receives every error. A callback
that takes another error type `E` receives an error whose wrapped source
is an `E`: the error you passed to `FrameworkError::from_external` or
`from_external_with`. Only that wrapped error is compared, not the errors
in its own `source()` chain. To act on a deeper cause, take
`&FrameworkError` and walk `std::error::Error::source` yourself.

To report an error your code handles, and still have it recorded, pass it
to `Exceptions::report`:

```rust
use suprnova::{Exceptions, FrameworkError};

fn read_settings() -> String {
    match std::fs::read_to_string("storage/settings.json") {
        Ok(settings) => settings,
        Err(e) => {
            Exceptions::report(&FrameworkError::from_external_with(
                "reading the settings failed; using the defaults",
                e,
            ));
            String::from("{}")
        }
    }
}
```

`Exceptions::dont_retry::<E>()` and `Exceptions::dont_retry_when` name
the errors that end a queued job's retries. See
[Queue](queues.md#errors-that-end-retries).

### Why Suprnova diverges

- A Laravel callback that returns `false` also stops reporting. A
  Suprnova callback returns nothing, so `stop()` is the only way to stop.
- An exception thrown from a Laravel callback ends the report. A
  Suprnova callback that panics is logged, and the report goes on to
  the next callback and the log line. A broken reporter cannot take a
  queue worker down.
- `Exceptions::report` takes a `FrameworkError`. Wrap a foreign error
  with `FrameworkError::from_external` first.

## See a failure in the browser

With debug mode on, a route that fails with a 5xx shows the development
error page in a browser instead of a JSON body. Debug mode is on when
`APP_DEBUG=true`, and when `APP_DEBUG` is unset in the `local`,
`development`, or `testing` environment.

```rust
use suprnova::{FrameworkError, HttpResponse, Request, Response};

pub async fn post_invoice(_req: Request) -> Response {
    write_ledger()?;
    HttpResponse::text("posted").ok()
}

fn write_ledger() -> Result<(), FrameworkError> {
    std::fs::write("storage/ledger.log", b"invoice 42\n")
        .map_err(|e| FrameworkError::from_external_with("writing the ledger failed", e))
}
```

When the write fails, a browser that opens the route gets a 500 page
that shows the following:

- The message `writing the ledger failed`, and the I/O error it wraps.
- The line in `write_ledger` that called `from_external_with`, and the
  stack frames of your code that led there. The frames of the framework,
  the async runtime, dependencies and the standard library are collapsed
  behind a count. You see the source line and a few lines around each
  application frame when its file is readable. You also see a separate
  trace for each source error that recorded frames.
- The request's method, path, query, headers, route pattern, and request
  id. Credentials and secret-named values are redacted, including the
  secret parameters of a URL in a header such as `Referer`.

An Inertia visit gets the same page, in place of your Inertia error
page. `curl`, and every other client whose `Accept` header does not list
`text/html`, still gets
`{"message": "Internal Server Error", "request_id": "...", "debug_message": "..."}`.
With debug off, you receive a minimal HTML error view for a 5xx when your
request accepts `text/html` and is not an Inertia visit. You see the
status with no error detail or frames. Your Inertia visits keep your app
error page, and your JSON requests keep their JSON body. The rules are in
[Error Model](error-model.md#the-development-error-page).

That minimal view also replaces a 5xx page you build on purpose, such as a
503 with a status link and your own `Content-Security-Policy`. To send
that page as you built it, mark it with `error_view()`:

```rust
use suprnova::{HttpResponse, Request, Response};

pub async fn maintenance(_req: Request) -> Response {
    Err(HttpResponse::html(include_str!("../views/maintenance.html"))
        .status(503)
        .header("retry-after", "120")
        .header("content-security-policy", "default-src 'none'; frame-ancestors 'none'")
        .error_view())
}
```

The framework takes the mark at its word, so mark only a response you
built yourself with no detail of any error in it. With debug on, the
development error page still replaces a marked response that carries an
error report.

### Why Suprnova diverges

Laravel's exception page also shows the request body and runs a script
for its "copy as Markdown" button. Suprnova's page does neither. A
request body can hold the passwords and tokens the page redacts
everywhere else, and a page that runs no script and loads nothing still
renders when your frontend build is what broke.

## Patterns you'll write a lot

### Parse a path parameter as a typed value

```rust
let id: i64 = req.param("id")?.parse()
    .map_err(|_| FrameworkError::param_parse("id", "i64"))?;
```

`ParamError` already converts to 400; `param_parse` is the parse-failure
equivalent and renders the same shape.

### Look up by ID, 404 on absent

```rust
let user = users::Entity::find_by_id(id)
    .one(&*DB::get()?)
    .await
    .map_err(FrameworkError::from)?
    .ok_or_else(|| FrameworkError::not_found("User"))?;
```

`map_err(FrameworkError::from)?` bridges the SeaORM `DbErr` through
`From<DbErr> for FrameworkError` and then through
`From<FrameworkError> for HttpResponse`. Rust does not auto-chain
`From` impls across two hops, so the explicit `.map_err` is required.

Or, with the Eloquent layer (which already wraps SeaORM and returns
`Result<_, FrameworkError>` directly):

```rust
use suprnova::Model;

let user = User::find_or_fail(id).await?;
```

`find_or_fail` is `find(id).ok_or(ModelNotFound)` packaged up.

### Authorize an action

```rust
let user = Auth::user().await?
    .ok_or_else(|| AppError::unauthorized("login required"))?;
abort_unless(post.owner_id == user.id() || user.is_admin(), 403,
    "you don't own this post")?;
```

`abort_unless` returns `Result<(), FrameworkError>`; the `?` collapses
it back into your handler's error arm.

### Service returning typed errors

```rust
use suprnova::{App, FrameworkError, injectable};

#[injectable]
pub struct UserService;

impl UserService {
    pub async fn find_by_email(&self, email: &str)
        -> Result<users::Model, FrameworkError>
    {
        users::Entity::find()
            .filter(users::Column::Email.eq(email))
            .one(&*DB::get()?)
            .await?
            .ok_or_else(|| FrameworkError::not_found("User"))
    }
}

// Call site:
pub async fn show(req: Request) -> Response {
    let email = req.param("email")?;
    let user = App::resolve::<UserService>()?
        .find_by_email(email)
        .await?;
    json_response!({ "user": user })
}
```

`App::resolve::<UserService>()?` returns `Result<Arc<UserService>,
FrameworkError>`. The chained `?` collapses both the resolve failure
and the lookup failure to a response.

## Cheat sheet

| You want… | Reach for |
|---|---|
| Inline error with a status | `AppError::bad_request("…")` and friends |
| Typed reusable error | `#[domain_error(status = …, message = "…")]` |
| Generated scaffold | `suprnova make:error UserNotFound` |
| Hand-rolled with runtime state | `impl HttpError for MyError` |
| Bridge hand-rolled into `?` | `FrameworkError::from_http_error(e)` |
| Short-circuit at a status | `abort_with` / `abort_if` / `abort_unless` |
| 404 on missing model | `FrameworkError::not_found("User")` / `Model::find_or_fail` |
| Parse-failure on path param | `FrameworkError::param_parse("id", "i64")` |
| Field-level validation error | `FrameworkError::validation("email", "…")` |
| Multi-field error bag | `ValidationErrors::new().add(…)` + `Validation(errs)` |
| Duplicate-key violation → 422 | `FrameworkError::from_unique_violation(field, msg, e)` |
| Annotate an existing error | `err.context("creating user")` |
| Observe every 5xx | Listen for `ErrorOccurred` |
| Run code for every reported error | `Exceptions::reportable(callback)` |
| Record an error you handled | `Exceptions::report(&err)` |
| See a 5xx in the browser while developing | `APP_DEBUG=true`, then open the route |
| Render errors as an Inertia page | `InertiaConfig::error_page("Error")` |

## Next

- [Error Reporting](error-reporting.md) - tracker drivers, helpers and scrubbing
- [Error Model](error-model.md) - variants, conversion contract,
  5xx sanitisation, panic boundary, development error page
- [Validation](validation.md) - `#[derive(Validate)]`, form requests,
  and `after_validation`
- [Responses](responses.md) - `HttpResponse` builders, status, headers
- [Events](events.md) - listening to `ErrorOccurred` and other
  built-in events
- [Queue](queues.md) - retries, and the errors that end them
- [Request Lifecycle](lifecycle.md) - where in the request flow the
  error conversion runs


---

<!-- /docs/error-reporting -->

# Error Reporting

Suprnova reports unhandled errors through `Reporter`. The built-in `sentry`
driver sends Sentry envelopes, so one DSN reaches Rustrak,
Sentry or GlitchTip. No listener or vendor SDK setup is needed in your app.
Without a DSN, the driver sends nothing.

## Start with local Rustrak

In a scaffolded application, generate the optional service:

```bash
suprnova docker:compose --with-rustrak
export RUSTRAK_CREATE_SUPERUSER="admin@example.com:$(openssl rand -hex 24)"
docker compose up -d
```

Save the initial account credentials before closing that shell. Open
`http://127.0.0.1:8080`, sign in, create a project and copy its DSN. Put that
DSN in your application's configuration:

```dotenv
REPORTING_DRIVER=sentry
REPORTING_DSN=http://your-project-key@127.0.0.1:8080/1
```

Replace the example key and project id with the DSN Rustrak shows. The
generated service pins `rustrak/rustrak-server:v0.16.4`, publishes port 8080
on loopback only, persists `/data` in `rustrak_data`, generates its own
`SESSION_SECRET_KEY` and sets `RUSTRAK_TELEMETRY=off`. `RUSTRAK_PORT` changes
the published port and `PUBLIC_URL` together. Keep the volume and session key
across restarts. `RUSTRAK_CREATE_SUPERUSER` creates an account only while the
database has no users; changing it later does not reset a password.

For an application that already has a Compose file, plain Docker works too:

```bash
export SESSION_SECRET_KEY="$(openssl rand -hex 32)"
export CREATE_SUPERUSER="admin@example.com:$(openssl rand -hex 24)"
docker run -d --name rustrak \
  -p 127.0.0.1:8080:8080 \
  -v rustrak_data:/data \
  -e SESSION_SECRET_KEY -e CREATE_SUPERUSER \
  -e PUBLIC_URL=http://127.0.0.1:8080 \
  -e RUSTRAK_TELEMETRY=off \
  rustrak/rustrak-server:v0.16.4
```

Save both generated values in your secret store before recreating the
container. This follows Rustrak's [installation instructions](https://rustrak.github.io/rustrak/getting-started/installation)
with a pinned image, a loopback port and telemetry disabled. The dashboard
and API are in that single container. Rustrak runs as a separate service;
Suprnova includes none of its GPL-3.0 server code.

## Choose a driver

| Driver | Behaviour |
|---|---|
| `sentry` | Sends to `REPORTING_DSN` in the background. The default; inert without a DSN. |
| `log` | Writes the scrubbed event to the application's logs. |
| `null` | Discards events. Useful when another process owns reporting. |

Environment configuration is loaded at application startup. To select a
driver in Rust instead, configure it during bootstrap:

```rust
use suprnova::{FrameworkError, Reporting, ReportingConfig, ReportingDriver};

pub fn register_reporting() -> Result<(), FrameworkError> {
    Reporting::configure(
        ReportingConfig::default()
            .driver(ReportingDriver::Sentry)
            .dsn("http://your-project-key@127.0.0.1:8080/1"),
    )?;
    Ok(())
}
```

`ReportingDriver::Log` and `ReportingDriver::Null` select the other drivers.
A custom backend implements `Reporter::report(ReportingEvent)` and
`Reporter::flush(Duration)`. `ReportingConfig::build()` returns an
`Arc<dyn Reporter>` for applications that need an independent reporter.
`Reporter::report_error(&FrameworkError)` uses that driver's capture path;
the Sentry driver queues symbol resolution instead of doing it on the caller.
`ReportingEvent::from_error` uses the active application's configuration.
For an independent reporter, pass its configuration when capturing the
event so the same privacy settings apply:

```rust
use suprnova::{FrameworkError, ReportingConfig, ReportingEvent};

pub fn report_independent_failure() -> Result<(), FrameworkError> {
    let config = ReportingConfig::default()
        .dsn("http://your-project-key@127.0.0.1:8080/1")
        .send_pii(false);
    let reporter = config.build()?;
    let error = FrameworkError::internal("independent task failed");
    reporter.report(ReportingEvent::from_error_with_config(&error, &config))?;
    Ok(())
}
```

The default `reporting-sentry` Cargo feature includes the official Rust
Sentry SDK. Applications that disable default features must enable it to
send to a Sentry-compatible tracker.

The builder also offers `.release(...)`, `.queue_capacity(usize)`,
`.timeout(Duration)` and `.duplicate_window(Duration)`. The sender defaults
to 128 pending events, a two-second network timeout and a one-second burst
deduplication window. These delivery limits are programmatic settings.

## Settings

| Setting | Default | Purpose |
|---|---|---|
| `REPORTING_DRIVER` | `sentry` | `sentry`, `log` or `null`. |
| `REPORTING_DSN` | unset | Server-side Sentry-protocol DSN. An unset DSN sends nothing. |
| `REPORTING_RELEASE` | application's package version | Identifies the deployed release. Set a version or commit hash in deployment. |
| `APP_ENV` | `production` | Names the deployment environment in events and transactions. |
| `REPORTING_SEND_PII` | `false` | Allows the user's email and IP address. The user id is included without this opt-in. |
| `REPORTING_LOGS` | `off` | Sends structured Sentry logs at or above the selected level. |
| `REPORTING_TRACES_SAMPLE_RATE` | `0` | Fraction of request and job transactions to send, from `0` to `1`. |
| `REPORTING_PUBLIC_DSN` | unset | Public browser DSN for Live and the security policy's tracker origin. |
| `VITE_REPORTING_DSN` | unset | Public browser DSN for Svelte, React and Vue starter builds, and a tracker origin the security policy allows. |

Logs and transactions use the same DSN as errors. Both are off by default;
error reporting alone does not opt in to either. For example:

```dotenv
REPORTING_LOGS=warn
REPORTING_TRACES_SAMPLE_RATE=0.1
REPORTING_RELEASE=2026.10.15-abc123
```

See [Environment Variables](env-vars.md) for parsing and the complete list.
The `#[suprnova::main]` entry point records your application's package
version for the release fallback. Applications with a custom entry point
can set `.release(...)` on the builder or call
`suprnova::boot::set_default_build_id(env!("CARGO_PKG_VERSION"))` at startup.

## Report an error you handle

The framework already reports unhandled 5xx errors, caught panics, queue
failures, console failures, scheduled tasks, workflow and supervisor
failures, WebSocket sessions and rescued Inertia props. A 4xx, validation
failure, authentication or authorization refusal, or silent error is not
reported. Use the helpers when your code handles a failure and continues:

```rust
use suprnova::{FrameworkError, report, report_if, report_unless, rescue};

pub async fn load_settings() -> Result<String, FrameworkError> {
    let error = FrameworkError::internal("optional settings unavailable");
    report(&error)?;
    report_if(false, &error)?;
    report_unless(true, &error)?;

    let settings = rescue(
        async {
            std::fs::read_to_string("storage/settings.json")
                .map_err(FrameworkError::from_external)
        },
        |_error| String::from("{}"),
    )
    .await;
    Ok(settings)
}
```

`rescue` reports an error before calling the fallback and returns the
fallback's value. A reporting failure does not prevent the fallback.
`Exceptions::report` remains available for existing applications.

## Control which errors leave the app

`Exceptions::reportable` callbacks run before the reporter. A callback's
`.stop()` prevents the reporter from sending that error. Register callbacks
and exclusions once in bootstrap, rather than on each request:

```rust
use suprnova::{Exceptions, FrameworkError};

pub fn register_exclusions() {
    Exceptions::dont_report::<std::io::Error>();
    Exceptions::dont_report_when(|error: &FrameworkError| error.is_silent());
    Exceptions::dont_report_duplicates();
}
```

Type exclusions match wrapped external errors. A predicate can use your
own application rule. `dont_report_duplicates` suppresses repeated reports
of the same error. The sender also coalesces bursts within a bounded window.

Events include the error type and chain, stack trace, known error or panic
location, release, environment and host name. Request events add the method,
route pattern, URL, headers, request id and user id. Recent log records from
the same request or job become breadcrumbs.

The reporter and debug page share scrubbing. Authorization, Cookie and
Set-Cookie headers, CSRF and session identifiers, passwords and fields whose
names contain password, token, secret, key or signature are removed. So are
model `hidden` fields, `SecretString` values and the context's hidden bag.
The reporter never sends request bodies. Keep secrets out of error text and
ordinary log messages as well.

The sender uses a bounded queue and a network timeout. Reporting enqueues
work without waiting on the tracker. A full queue or unreachable server
drops and counts events; it does not fail the request or job. The default
Sentry driver captures the reporting stack immediately and resolves its
symbols in the sender. While the resolver is busy, new captures are
dropped and counted to keep requests and panic hooks from waiting on it.
Server and daemon shutdown flush the queue within a deadline.
`Reporting::metrics()` returns queued, delivered, dropped and duplicate
counts without exposing event data or tracker credentials.

## Browser reports

Set the public DSN for the kit you use: `VITE_REPORTING_DSN` for a Svelte,
React or Vue starter, `REPORTING_PUBLIC_DSN` for Live. It is a browser
ingestion address; never put a tracker account password or API token there.

```dotenv
# Svelte, React or Vue
VITE_REPORTING_DSN=http://your-project-key@127.0.0.1:8080/1
# Live
REPORTING_PUBLIC_DSN=http://your-project-key@127.0.0.1:8080/1
```

Svelte, React and Vue starters load Sentry's browser package only when
`VITE_REPORTING_DSN` is set. They report uncaught errors, unhandled
rejections and framework render or hydration failures. The package loads in
its own chunk while the application mounts, so the first page does not wait
for it; an error raised before it is ready, such as a hydration failure on
the first render, is held (up to 32) and sent once it loads. Rebuild the
frontend after changing the Vite setting. With no value the reporter is not
loaded.

Live uses its built-in runtime reporter, configured by
`REPORTING_PUBLIC_DSN`, without a third-party script. It covers uncaught
errors, unhandled rejections and Live runtime failures.

`SecurityHeaders` allows the tracker origin of each public DSN it finds in
the environment, `REPORTING_PUBLIC_DSN` and `VITE_REPORTING_DSN`, in
`connect-src`, so the scaffold's own policy does not block the reports. A
value that is not a public DSN stops the application at boot with an error
naming the setting. The server reads `VITE_REPORTING_DSN` from the same
`.env` the build reads; a deployment that passes it to the build alone must
give the server the same value.

### Why Suprnova diverges

Laravel reports through log channels and uses `sentry/sentry-laravel` for
Sentry integration. Suprnova includes a `Reporter` trait and selectable
drivers so HTTP requests, background work and the starter kits use one
reporting path. Rust returns errors as values, so the helpers accept
`FrameworkError` and `rescue` accepts a future returning `Result`.

## Next

- [Error Handling](errors.md) covers returned errors and callbacks.
- [Error Model](error-model.md) explains conversion and response sanitisation.
- [Logging](logging.md) covers application log channels.
- [Security Headers](security-headers.md) covers CSP and browser connections.


---

<!-- /docs/logging -->

# Logging

Suprnova logs through [`tracing`](https://docs.rs/tracing) - every log
line is a structured event with fields, not a formatted string. A
subscriber is installed at boot that reads `LOG_LEVEL` and `LOG_FORMAT`
from the environment, emits pretty multi-line output in dev and one
JSON object per line in production, and propagates a per-request id
into every event a handler emits.

This chapter covers the log surface itself: the subscriber, the
formats, the levels, the channels the lines go to, and the request-id
correlation that makes a production log searchable. For the OpenTelemetry bridge and query
logging see [Observability](observability.md); for the request
`Context` bag that emitters can read alongside the id see
[Context](context.md).

## What gets logged where

`tracing`'s events go to the default channel, `stdout` unless `LOG_CHANNEL`
names another (see [Channels](#channels)). On `stdout`, two formats:

| Where | Format | When |
|---|---|---|
| `stdout` | `LogFormat::Pretty` - multi-line, coloured, human-friendly | dev (`APP_ENV` is `local`, `dev`, `testing`, …) |
| `stdout` | `LogFormat::Json` - one JSON object per line | production (`APP_ENV=production` / `prod`, or `APP_ENV` unset) |

The dev/prod default is computed from `APP_ENV` via
`Environment::detect()`. Override with `LOG_FORMAT=pretty` or
`LOG_FORMAT=json` to force one explicitly.

```env
# .env (dev)
LOG_LEVEL=info,sqlx=warn
LOG_FORMAT=pretty   # optional; this is the dev default

# .env.production
LOG_LEVEL=info,sqlx=warn,suprnova::queue=debug
LOG_FORMAT=json     # optional; this is the prod default
```

By default the framework writes to `stdout`. In a container, point the
runtime, the systemd journal or a log aggregator at it (`docker logs`,
`kubectl logs`, `journalctl -u my-app`, a Loki or Vector agent). Where
there is no platform to keep the logs, write them to files with a
[channel](#channels).

## Channels

A channel is where log lines go. `LOG_CHANNEL` names the default channel,
the one `tracing`'s events go to:

| Channel | Writes to |
|---|---|
| `stdout` | standard output, in the `LOG_FORMAT`; the default |
| `stderr` (also `errorlog`) | standard error |
| `single` | `storage/logs/suprnova.log`, appended to |
| `daily` | `storage/logs/suprnova-2026-10-02.log`, a file a day, keeping the newest `LOG_DAILY_DAYS` (7; 0 keeps every file) |
| `monthly` | `storage/logs/suprnova-2026-10.log`, a file a month, keeping the newest 3 |
| `syslog` | the local syslog socket, with the facility `LOG_SYSLOG_FACILITY` (`user`) and `APP_NAME` as the ident (`suprnova` unless set) |
| `null` | nowhere |
| `stack` | every channel `LOG_STACK` lists, `single` unless set |
| `custom` | the driver `LOG_CHANNEL_DRIVER` names, registered with `Log::extend` in the bootstrap |

```env
LOG_CHANNEL=stack
LOG_STACK=daily,stdout
LOG_DAILY_DAYS=30
```

A channel that does not exist stops the server and the workers at boot,
once the bootstrap has run, with an error that names it; so does a name in
`LOG_STACK`, a `LOG_SYSLOG_FACILITY` or a `LOG_DAILY_DAYS` that is wrong,
whichever channel is the default. Dates are those of the framework clock,
in UTC. File lines are text, one line a record, or JSON objects when
`LOG_FORMAT=json`, and carry the fields of the spans the event is in, the
request's `request_id` among them. A field an inner span shares a name with
replaces the outer span's, and an event's own field replaces both, in the
message's placeholders and in the context alike.

Define your own channels in the bootstrap, and reach any channel with
`Log`:

```rust
use serde_json::json;
use suprnova::{Log, LogChannel, LogLevel};

// bootstrap.rs
Log::define("audit", LogChannel::daily("storage/logs/audit.log").days(90));
Log::define("alerts", LogChannel::syslog().facility("local0").level(LogLevel::Error));

// anywhere
Log::channel("audit")?.info_with("user {id} signed in", json!({ "id": 42 }));
Log::stack(&["audit", "alerts"])?.critical("payments are failing");
Log::build(LogChannel::single("storage/logs/import.log"))?.notice("import done");
```

`Log::channel`, `Log::stack` and `Log::build` write to their channels
only; `tracing`'s events go to the default channel. A logger has
Laravel's eight levels, from `emergency` to `debug`, and the `*_with`
methods take a JSON context: each `{key}` in the message is replaced with
its value, and the context is written beside the message. A channel
`.level(...)` keeps only the records at that level or above. A stack's
`.level(...)` applies to every channel it lists, on top of each channel's
own, and a default stack that names `stdout` more than once writes an event
there when any of those channels keeps its level.

The built-in `single`, `daily`, `monthly`, `stderr`, `errorlog` and
`syslog` channels keep the records at or above the bare level of
`LOG_LEVEL` (see [Log levels](#log-levels)), `debug` when it names none,
as Laravel's channels take `env('LOG_LEVEL', 'debug')`. With
`LOG_LEVEL=error`, `Log::channel("errorlog")?.debug(..)` writes nothing.

A channel replaces each `{key}` placeholder with the context's value unless
you turn it off with `.replace_placeholders(false)`, for a reader that wants
the message template, such as a log service that groups records by it. A
stack gives each of its channels the form that channel chose:

```rust
Log::define("app", LogChannel::daily("storage/logs/app.log"));
Log::define("events", LogChannel::monthly("storage/logs/events.log").replace_placeholders(false));

// app.log gets "user 7 signed in", events.log gets "user {id} signed in".
Log::stack(&["app", "events"])?.info_with("user {id} signed in", json!({ "id": 7 }));
```

A stack writes each record to every channel it lists, and a channel that
cannot write, such as a file it cannot open, stops none of the others;
the failure is reported once on stderr, and the code that logged never
sees an error. That covers a driver's sink that returns an error from
`write` or `flush`, and buffered lines a file cannot flush, such as on a
full disk. `Log::channels()` lists the channels in use,
`Log::forget_channel(name)` closes one, which is resolved again on its
next use, reopening a file rotated away; every stack that lists it, the
default channel included, reopens it too. `Log::default_channel()` and
`Log::set_default_channel(name)` read and move the default.

`Log::extend` adds a driver for anything else, such as Slack or a log
service, with a `LogSink` that receives each `LogRecord`:

```rust
use std::sync::Arc;
use suprnova::{Log, LogChannel, LogRecord, LogSink};

struct Webhook;

impl LogSink for Webhook {
    fn write(&self, record: &LogRecord) -> std::io::Result<()> {
        // send record.level, record.message and record.context
        Ok(())
    }
}

Log::extend("webhook", |_channel| Ok(Arc::new(Webhook) as Arc<dyn LogSink>));
Log::define("ops", LogChannel::driver("webhook").option("url", "https://..."));
```

To use an extended driver as the built-in `custom` channel, register it in
the bootstrap and set:

```env
LOG_CHANNEL=custom
LOG_CHANNEL_DRIVER=webhook
```

You use `custom` without a `Log::define` call. Your application fails boot
if `LOG_CHANNEL_DRIVER` is missing or names a driver you do not register.

`MAIL_LOG_CHANNEL` names the channel the `log` mail transport writes to.

### Flushing

File channels buffer their lines. A record at `error` or above is written
out at once, the rest within a second, and everything on `Log::flush()`,
which the server, the workers and every console command call when they
end. A record written before a clean exit is never lost. A driver added
with `Log::extend` is flushed with the files.

## Writing through `Log`

`Log` has Laravel's level methods, which write to the default channel:
`Log::emergency`, `alert`, `critical`, `error`, `warning`, `notice`,
`info` and `debug`, a `*_with` form of each that takes a JSON context, and
`Log::log(level, message, context)`.

```rust
use serde_json::json;
use suprnova::{Log, LogLevel};

Log::critical("disk full");
Log::warning_with("payment {id} retried", json!({ "id": 7 }));
Log::log(LogLevel::Notice, "cache warmed", json!({ "keys": 120 }));
```

Each write is a `tracing` event, so `LOG_LEVEL` filters it and the
request's span stamps it as it does a `tracing` macro's. It keeps its own
level in a file or stack channel's record: `Log::critical` writes
`CRITICAL`, where `tracing` alone knows only `ERROR`. On standard output,
`tracing`'s formatter shows the `tracing` level with the PSR-3 level and
the context as the `suprnova.level` and `suprnova.context` fields.

### Context on every line

`Logger::with_context` returns a logger whose writes carry a context under
each call's own; `without_context` drops keys from it, or all of them:

```rust
let tenant = Log::channel("audit")?.with_context(json!({ "tenant": "acme" }));
tenant.info("export started");               // tenant=acme
tenant.info_with("export done", json!({ "rows": 1200 }));
let plain = tenant.without_context(Some(&["tenant"]));
```

`Log::share_context` adds a context to every later write of the current
request or queued job, on every channel, as Laravel's `shareContext` does:

```rust
// In a middleware, once the user is known.
Log::share_context(json!({ "user_id": 42 }));
```

The context lives in the request's [`Context`](context.md) scope, so one
request's context never reaches the lines of another running at the same
time, and outside a scope it shares nothing. `Log::shared_context()` reads
it, `Log::without_context(Some(&["user_id"]))` drops keys, and
`Log::flush_shared_context()` drops it all. A job the request dispatches
starts without it. A write carries the shared context, then the logger's,
then the call's own, a later key winning. On standard output a `tracing`
macro's line shows only its own fields, since `tracing`'s formatter writes
it; every other channel and every `Log` write carries the shared context.

### Listening to writes

Every write that reaches a channel, the `null` channel included, is
reported once as a `MessageLogged` event with its level, its message (with
its placeholders) and its context, as Laravel's `Logger` dispatches it.
`Log::listen` adds a callback that runs on the writing thread before the
write returns:

```rust
use suprnova::{Log, LogLevel, MessageLogged};

Log::listen(|event: &MessageLogged| {
    if event.level <= LogLevel::Error {
        // count it, forward it, keep it for the request's profile
    }
});
```

A listener added with `EventFacade::listen::<MessageLogged, _>` runs on a
task spawned on the current runtime, since logging is synchronous and the
dispatcher is not. A write made outside any runtime, on a plain
`std::thread` for example, sends its task to a small runtime that runs on
a thread of its own, so the listener hears that write too.
Under `EventFacade::fake()` the write is recorded before it returns. A
callback that panics or a listener that fails never fails the write, and
the lines the dispatcher and the listeners log while a `MessageLogged` is
being reported are not reported again. When nothing listens, a write
builds no event.

## Emitting events

Use the `tracing` macros in handlers, jobs, middleware, anywhere:

```rust
use suprnova::{json_response, session, Request, Response};
use tracing::{debug, info, warn, error, instrument};

pub async fn checkout(_req: Request) -> Response {
    let user_id: i64 = session()
        .and_then(|s| s.get::<i64>("user_id"))
        .unwrap_or(0);

    info!(user_id, "checkout starting");

    let order = place_order(user_id).await.map_err(|e| {
        error!(user_id, error = %e, "checkout failed");
        e
    })?;

    info!(user_id, order_id = order.id, total = order.total_cents, "checkout succeeded");

    json_response!(order)
}
```

Each field becomes a top-level key in JSON output and a coloured
`field=value` pair in pretty output. Prefer fields over interpolation -
they're searchable in JSON logs and the formatter handles type-aware
rendering.

To wrap a function in a span and stamp every event inside it with
shared fields, use `#[instrument]`:

```rust
#[instrument(skip(db), fields(user_id = %user_id))]
pub async fn load_dashboard(
    db: &suprnova::DatabaseConnection,
    user_id: i64,
) -> Result<Dashboard, FrameworkError> {
    info!("loading"); // automatically carries user_id from the span
    // … queries …
}
```

The same `#[instrument]` becomes an OpenTelemetry span when the `otel`
feature is enabled - see [Observability](observability.md#distributed-tracing-otel).

## Log levels

`LOG_LEVEL` is a [`tracing-subscriber` env-filter
directive](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html),
not a single level. The grammar is comma-separated `target=level`
pairs, where bare values set the default:

```env
LOG_LEVEL=info                                  # everything at info+
LOG_LEVEL=debug                                 # everything at debug+
LOG_LEVEL=info,sqlx=warn                        # info default, sqlx quieter
LOG_LEVEL=warn,suprnova::queue=debug,my_app=info  # warn default, two targets verbose
```

Targets are usually the emitting crate or module path
(`suprnova::queue`, `hyper::server`, `my_app::services::checkout`).
Find a target by reading the JSON log line - the `target` field on
every event is its filter key.

Levels in increasing verbosity: `error` < `warn` < `info` (default) <
`debug` < `trace`. Laravel's PSR-3 names work too, each read as its
nearest `tracing` level: `warning` as `warn`, `notice` as `info`, and
`critical`, `alert` and `emergency` as `error`, so `LOG_LEVEL=warning`
keeps errors and warnings.

The bare level, `info` in `info,sqlx=warn`, is also the lowest level the
built-in file and stream channels keep (see [Channels](#channels)), so
`LOG_LEVEL=notice` keeps `Log::notice` and drops `info` there. A bare level
that is none of the eight PSR-3 names, `warn` or `trace` stops the boot
with an error that names it, as Laravel's refuses one. The wire-format error response is always sanitised
to `{"message": "Internal Server Error"}` regardless of level - the
detail goes only to the structured log.

### Invalid target directives don't crash boot

A malformed target directive (e.g. `LOG_LEVEL=info,app=notalevel`) falls
back to `"info"` and writes a one-line warning to `stderr`:

```text
suprnova: invalid LOG_LEVEL directive "info,app=notalevel" (...); falling back to "info". Fix LOG_LEVEL to silence this.
```

This is `stderr` rather than `tracing::warn!` because the subscriber
hasn't been installed yet - a `warn!` would be silently dropped. Fix
the directive and the warning goes away.

## Pretty vs JSON output

The same `info!(user_id = 42, "saved")` renders differently per format.

**Pretty (dev):**

```text
  2026-05-30T22:14:08.221341Z  INFO request{request_id=78a9...} my_app::handlers::checkout: saved
    at src/handlers/checkout.rs:48
    in checkout
    in request with request_id: 78a9..., method: POST, path: /checkout
```

**JSON (prod):**

```json
{
  "timestamp": "2026-05-30T22:14:08.221341Z",
  "level": "INFO",
  "fields": { "message": "saved", "user_id": 42 },
  "target": "my_app::handlers::checkout",
  "span": { "name": "checkout" },
  "spans": [
    { "name": "request", "request_id": "78a9...", "method": "POST", "path": "/checkout" }
  ]
}
```

The JSON shape is what production aggregators (Datadog, Loki,
Honeycomb, CloudWatch, …) parse out of the box. `span.request_id` is
the correlation key - see below.

## Per-request id correlation

Every HTTP request gets a `RequestId` from `RequestIdMiddleware`, the
outermost middleware on every chain. The id is:

- **Reused** from a safe inbound `X-Request-Id` header (alphanumerics
  plus `- _ . :`, up to 128 bytes), or **freshly minted** as a UUID v4
  if absent / unsafe.
- **Echoed** back on the response as `X-Request-Id` (both 2xx and
  5xx variants).
- **Scoped** into a `request` `tracing` span so every event from any
  middleware, handler, or downstream library carries `request_id` in
  its `spans` array automatically.
- **Seeded** into the request `Context` bag as `_request_id`, so
  emitters that want the bare string (jobs, broadcast payloads, error
  reports) can read it by name.

Read it in code with `current_request_id()`:

```rust
use suprnova::current_request_id;
use tracing::info;

if let Some(id) = current_request_id() {
    info!(request_id = %id, "checkpoint reached");
}
```

`current_request_id()` returns `Option<RequestId>` because background
work (jobs, scheduled tasks, tests that didn't install the middleware)
runs outside any request scope.

### Background tasks: spawn with the id

`tokio::spawn` starts a fresh task with empty task-locals - a handler
that spawns side-effect work loses `current_request_id()` and its log
events become orphaned. Use `spawn_with_request_id` instead:

```rust
use suprnova::spawn_with_request_id;
use tracing::info;

pub async fn checkout(req: suprnova::Request) -> suprnova::Response {
    let order = place_order().await?;

    spawn_with_request_id(async move {
        // This task still observes current_request_id().
        // Its log events carry the same request_id as the handler's.
        info!(order_id = order.id, "post-checkout fanout running");
        send_receipt(order.id).await;
        update_analytics(order.id).await;
    });

    Ok(suprnova::HttpResponse::ok().json(&order))
}
```

The helper propagates both the `RequestId` task-local and the current
`tracing::Span`, so the spawned future's events nest under the same
`request` span in the log. Outside an active request scope it falls
through to a bare `tokio::spawn` - safe to use unconditionally.

Only the request id and tracing span follow the task - the request
`Context` bag deliberately does not, because background work isn't
serving the originating HTTP request.

## The subscriber

The framework installs a global `tracing` subscriber at boot from
`Server::run()`. You almost never call this yourself; it's documented
because tests, embedders, and unusual entry points sometimes need to.

```rust
use suprnova::{LogConfig, init_subscriber};

// Read LOG_LEVEL / LOG_FORMAT from the environment:
init_subscriber(LogConfig::from_env());

// Or programmatic:
init_subscriber(LogConfig {
    level: "info,sqlx=warn".to_string(),
    format: suprnova::LogFormat::Json,
});
```

`init_subscriber` is **idempotent**. A second call leaves the existing
subscriber in place, with its default channel and the format of its file
lines, and emits a `tracing::warn!` so an operator can see that the new
`LogConfig` was not applied. This is what lets tests
that each call `init_subscriber` not race each other - the first wins,
the rest are no-ops.

For the OTel-aware variant (the same `LogConfig`, plus
distributed-tracing export), use
[`init_telemetry`](observability.md#distributed-tracing-otel).

### The daemons

`queue:work`, `schedule:work`, `schedule:run` and `workflow:work` are
subcommands of your app binary and do not boot through `Server::run()`, so
they install their own subscriber on the way up. They read the same
`LOG_LEVEL` and `LOG_FORMAT` as the server, and you call nothing yourself:

```bash
LOG_LEVEL=info,suprnova::queue=debug cargo run --bin my-app -- queue:work

# …or, in a container, against the built binary:
LOG_LEVEL=info my-app queue:work
```

Before 0.9.1 that path installed nothing at all. Every `tracing::` line the
daemons emit went nowhere and `LOG_LEVEL` was inert for them, which in a
container left the startup banner as the only output - a worker
dead-lettering jobs, a scheduler skipping a tick it lost the election for,
and a lock it could not release all looked identical to an idle process. If
you are running a pinned build older than 0.9.1 and wondering why a worker
says nothing, that is why, and the fix is the upgrade rather than a
configuration change.

Most of what a worker has to say it says at `warn!` and `error!` - a job
exhausting its attempts, a dead-letter it could not persist, a lock it
could not release - so the default `info` level is enough to see trouble.
Drop to `debug` when you need the quieter decisions as well.

## Tests

Tests don't need to install a subscriber - the `#[suprnova_test]`
attribute and `TestContainer::fake` set up enough machinery for
handler events to flow. If you want to assert on log output, capture
via `tracing-subscriber`'s
[`tracing_subscriber::fmt::TestWriter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.TestWriter.html)
or a custom layer; the framework deliberately does not ship a "capture
all logs in this test" fake because the standard `tracing-subscriber`
test patterns work cleanly.

## Why Suprnova diverges

Laravel uses [Monolog](https://github.com/Seldaek/monolog) - message
strings with optional context arrays, log channels, and per-channel
handlers (file, syslog, Slack, …). PHP's request-per-process model
means a single global static logger is safe: each request gets its
own process and its own context.

Rust's process model is the opposite - one process serves many
concurrent requests on many threads. A global string-formatter would
race on context and require explicit `request_id` plumbing through
every call site. `tracing` solves both with structured fields and
task-local spans: no plumbing, fields stay typed, and correlation is
automatic because the request span is in scope for every event the
chain emits.

Laravel's channels are here as `Log`, with these differences. The
default channel is `stdout`, not a stack of files, because a container's
runtime keeps its logs, and it keeps every level the `LOG_LEVEL` filter
lets through, so a target directive more verbose than the bare level still
reaches it. Channels are configured from the environment and
`Log::define` in the bootstrap, not a config file. File channels buffer,
flushing at once for errors, within a second otherwise, and on shutdown,
where Monolog writes each record straight through. `Log::info` and the
other level methods write through `tracing`, so standard output shows
`tracing`'s level beside the PSR-3 one. Shared context belongs to the
request's or job's `Context` scope rather than the process, for the reason
above. And `MessageLogged` reaches the event dispatcher on a spawned task,
because a write cannot wait for an async listener.

## Next

- [Observability](observability.md) - OpenTelemetry, query log, the
  full operator surface
- [Context](context.md) - the per-request bag where `_request_id` and
  other contextual fields live
- [Error Handling](errors.md) - how the framework's panic boundary
  and 5xx path emit their own structured events
- [Environment Variables](env-vars.md) - `LOG_LEVEL`, `LOG_FORMAT`,
  `LOG_CHANNEL` and the channel variables


---

<!-- /docs/context -->

# Context

`Context` is Suprnova's per-request key/value bag. It's where you stash
data you want every downstream caller in the same request to see - a
request id, a tenant slug, a user role, an audit trail - without
threading the value through every function signature. It's the Suprnova
equivalent of Laravel's `Context` facade.

```rust
use suprnova::Context;

Context::add("tenant_id", "acme");
Context::push("breadcrumbs", "checkout/start");
Context::hidden_add("api_key", secret);

let tenant: Option<String> = Context::get("tenant_id");
let page: Option<String> = Context::query_param("page");
```

Reach for it when:

- A log line, queued job, or broadcast message needs request-scoped
  metadata (tenant id, correlation id, user role)
- A deeply-nested helper needs a value the handler already has, but
  the call chain shouldn't carry a parameter through every layer
- You want to read the current request's query string (`?page=3`,
  `?cursor=…`) from code that isn't a handler

`Context` is **not** for cross-request state. It's bound to the
current Tokio task and disappears when the request ends. The one
exception is work you queue: a job, a queued mail or notification, and a
queued event listener each receive a copy of the context of the code that
queued them - see [Queued work](#queued-work). For things that outlive a
request, use the [Service Container](container.md) or [Cache](cache.md).

## The two bags

Every active `Context` scope carries two key/value maps and one extra
slot:

| Bag | Read with | Appears in `Context::all()` |
|---|---|---|
| **Visible** | `Context::get` | Yes |
| **Hidden** | `Context::hidden_get` | No |
| **Query** | `Context::query_param` | No (separate snapshot of the URL's `?key=value` pairs) |

The split between visible and hidden is the whole point of having
two bags: log serialisers that dump `Context::all()` into structured
output won't leak data you intentionally hide. Put audit metadata in
the visible bag; put API keys, OAuth bearer tokens, and PII you don't
want in logs in the hidden bag.

The query bag is populated automatically by the framework's request
middleware from the URL's query string (see
[Pagination reads query params](#pagination-reads-query-params)
below). You usually only read it, never write it.

## The active scope

A `Context` scope is installed by the framework on every incoming
HTTP request, and by a queue worker around every attempt of a job.
Inside a handler, middleware, model observer, event listener, job, or
anything else reachable from those tasks, the scope is live and
`Context::*` reads and writes work without ceremony.

Outside a scope - early-boot code, a bare `tokio::spawn` that doesn't
inherit context, a unit test that doesn't install one - every
mutation is a **silent no-op** and every read returns `None`. The
contract is: no panic, ever, regardless of where you call from.

```rust
// In a handler - scope is active, everything works:
Context::add("user_id", 42i64);
let id: Option<i64> = Context::get("user_id");
assert_eq!(id, Some(42));

// Outside a scope - silent no-op + None:
Context::add("user_id", 42i64);            // discarded
let id: Option<i64> = Context::get("user_id");
assert_eq!(id, None);
```

The no-panic contract is deliberate. Library code that touches
`Context` (a custom log subscriber, an SDK extension) shouldn't need
to know whether it's running inside a request or at boot - it should
just call `Context::get` and treat `None` as "not available right now".

### Observability for silent operations

A truly silent no-op would hide bugs (middleware out of order,
context not propagated into a spawned task, accidental boot-time
read). The framework's mutating operations stay no-panic but emit a
`tracing::trace!` event on the `suprnova::context` target whenever
they discard:

```text
TRACE suprnova::context: Context mutation discarded: no active scope on this task op="add"
TRACE suprnova::context: Context mutation discarded: value failed to serialize op="push" key="bad"
TRACE suprnova::context: Context read returned None: value present but did not deserialize op="get" key="user_id" expected="String"
```

Three classes of event:

| Event | When it fires |
|---|---|
| `mutation discarded: no active scope` | `add`, `push`, `hidden_add`, `forget` called outside any scope |
| `mutation discarded: value failed to serialize` | `add`/`push`/`hidden_add` value's `Serialize` impl errored |
| `read returned None: value present but did not deserialize` | `get`/`hidden_get` found the key but the stored JSON doesn't match the requested `T` |

Plain absence - `get` on a key that was never set - stays silent so
"is this set?" probes don't flood logs. Enable
`RUST_LOG=suprnova::context=trace` when you suspect a propagation
bug; the silent no-op path becomes visible without changing how
production code behaves.

## Adding values

### `Context::add` - replace at a key

```rust
use suprnova::Context;

Context::add("user_id", 42i64);
Context::add("tenant", "acme");
Context::add("plan", PlanTier::Pro);     // any Serialize value
```

The key is `Into<String>`; the value is any `Serialize` type. The
value is converted to `serde_json::Value` once at write time and
stored that way. Subsequent `add` on the same key replaces.

### `Context::push` - append to a stack

```rust
Context::push("trail", "home");
Context::push("trail", "settings");
Context::push("trail", "billing");

let trail: Vec<String> = Context::get("trail").unwrap();
assert_eq!(trail, vec!["home", "settings", "billing"]);
```

`push` initialises an empty array on the first call and appends on
subsequent calls. If a scalar already exists at the key, it's
converted to a `[scalar, new_value]` array - `push` is forgiving
about prior `add`s on the same key.

### `Context::hidden_add` - write to the hidden bag

```rust
Context::hidden_add("api_key", os_env_secret);
Context::hidden_add("oauth_bearer", token);

// Visible bag dump (e.g. a JSON log emitter) doesn't see them:
let all = Context::all();
assert!(!all.contains_key("api_key"));

// But you can still read them deliberately:
let key: Option<String> = Context::hidden_get("api_key");
```

The hidden bag is keyed independently from the visible bag - a
`hidden_add("user_id", 99)` and an `add("user_id", "alice")` coexist
without collision. `Context::forget(key)` removes from both bags in
one call.

## Reading values

### `Context::get` - typed read from the visible bag

```rust
use suprnova::Context;

let user_id: Option<i64>       = Context::get("user_id");
let tenant:  Option<String>    = Context::get("tenant");
let trail:   Option<Vec<String>> = Context::get("trail");
```

`get` is generic over `T: DeserializeOwned`. The stored JSON value
is deserialised on every read. Returns `None` when:

- The key isn't set
- No scope is active on the current task
- The stored value doesn't deserialise to `T` (e.g. you stored an
  `i64` and asked for a `String`)

The last case emits a `tracing::trace!` so the wrong-type bug is
observable - `Context::get` looking like "the value isn't set" when
it's really "the value is the wrong shape" is the kind of bug that
costs an hour to find without a log line pointing at it.

### `Context::hidden_get` - typed read from the hidden bag

Same shape as `get`, reads the hidden bag. Same wrong-type tracing
behaviour.

### `Context::has` - existence check on the visible bag

```rust
if Context::has("user_id") {
    // …
}
```

`has` only checks the visible bag (use `hidden_get(...).is_some()`
if you need to probe the hidden bag).

### `Context::all` - snapshot of the visible bag

```rust
let snapshot: HashMap<String, serde_json::Value> = Context::all();
```

Returns an empty `HashMap` outside a scope. This is what a JSON log
emitter should call to inject request-scoped fields into every log
line - and why the hidden bag exists separately.

### `Context::forget` - remove a key from both bags

```rust
Context::forget("trail");          // removes from visible AND hidden
```

The dual-bag removal is intentional. If you stored related data in
both bags (e.g. `user_id` visible, `user_email` hidden), one
`forget` cleans up both.

## Reading query parameters

`Context::query_param` reads from the URL's `?key=value` pairs
captured at request entry. The request middleware parses the query
string once into the scope's query bag, then every downstream caller
can read individual params by name without re-parsing:

```rust
use suprnova::Context;

let page: Option<String>   = Context::query_param("page");
let cursor: Option<String> = Context::query_param("cursor");
let sort: Option<String>   = Context::query_param("sort");
```

Returns `None` when the parameter is missing or no scope is active.
Duplicate keys follow Laravel's last-wins semantics - the same value
you'd get from the request's parsed query map.

### Pagination reads query params

This is why the query bag exists. Eloquent's paginators read `?page=`
and `?cursor=` straight off `Context::query_param`, so a handler
that returns a paginator doesn't need to plumb the page number
through manually:

```rust
use suprnova::{json_response, Request, Response};
use crate::models::Post;

pub async fn index(_req: Request) -> Response {
    // Reads ?page=N from the request's URL via Context::query_param
    // - no req.query() boilerplate, no parameter threading.
    let posts = Post::query()
        .order_by_desc("created_at")
        .paginate(15)
        .await?;

    json_response!(posts)
}
```

Three paginator entry points use this:

- `Builder::paginate(per_page)` - reads `?page=`
- `Builder::simple_paginate(per_page)` - reads `?page=`
- `Builder::cursor_paginate(per_page)` - reads `?cursor=`

See [Pagination](pagination.md) for the full surface.

## Propagating into spawned tasks

`tokio::spawn` starts the child task with a fresh task-local
environment - the parent's `Context` scope does **not** flow in. A
bare `tokio::spawn` inside a request sees an empty `Context` and
every read returns `None`.

To carry the scope into a spawn, snapshot it with `Context::current()`
and re-enter it inside the child with `Context::scope`:

```rust
use suprnova::context::Context;

// Inside a request handler:
if let Some(store) = Context::current() {
    tokio::spawn(Context::scope(store, async move {
        // Now `Context::get`, `Context::query_param`, etc. see the
        // parent request's bag.
        let request_id: Option<String> = Context::get("_request_id");
        do_background_work(request_id).await;
    }));
}
```

The store returned by `Context::current()` shares the parent's
underlying maps via `Arc` - writes from the child are visible to the
parent for as long as the child holds the clone. This is exactly
what audit and logging spawns want: the child can stamp additional
keys (`Context::add("audit.completed", true)`) and the parent's
final log line sees them.

If you need an isolated snapshot (the child's writes shouldn't leak
back), build a fresh `ContextStore` and copy in just the keys you
need.

### Why bare `spawn` doesn't propagate

Tokio's task-locals (`tokio::task_local!`) are intentionally
task-scoped. Auto-inheriting across spawns would mean:

- Long-lived background tasks would pin parent context maps forever
- A panic in a child task could poison the parent's state
- The runtime would have to walk a parent pointer chain on every
  task-local read

The explicit `Context::current()` + `Context::scope` dance makes
propagation a deliberate decision instead of a hidden default.

## Queued work

A job runs after the request that queued it, often in another process.
Suprnova carries the `Context` across that gap for you. A push takes a
`ContextSnapshot` of the visible and hidden bags, the queue stores it on the
envelope, and the worker runs the job inside a scope restored from it:

```rust
use suprnova::{Context, Queue};

// In a handler:
Context::add("tenant_id", "acme");
Context::hidden_add("api_key", token);
Queue::push(SendInvoice { invoice_id: 7 }).await?;

// In SendInvoice::handle, on a worker:
let tenant: Option<String> = Context::get("tenant_id");
let key: Option<String> = Context::hidden_get("api_key");
```

The same holds for `Mail::queue`, `Mail::later`, `Notify::queue` and a queued
event listener. A chain and a batch give every job the snapshot of the code
that dispatched it.

Six rules describe what the job sees:

- **The job works on a copy.** What it adds reaches neither the request nor
  the next job. Every attempt of a job, and every retry, starts from the
  snapshot again.
- **The snapshot is taken at the push.** A push that waits for the commit of a
  `DB::transaction` carries the snapshot of the code that called it.
- **The query bag does not travel.** It describes the request that was being
  served, and the job is not that request. `Context::query_param` returns
  `None` in a job, including one that runs inline under the `sync` driver.
- **The request id always travels.** The request middleware adds
  `_request_id` to the visible bag, so a job queued while a request is served
  always carries it. Code outside a request, such as a console command or a
  scheduled task, carries only what it added itself. A push with nothing to
  carry writes no context.
- **Hidden values travel.** The job needs them, as it needs the rest of its
  payload. They reach the queue store and the failed-job store, so keep
  secrets out of the hidden bag unless the job needs them. They never reach a
  log: the envelope a worker logs when no failed-job store is bound has no
  hidden context, and the `Debug` output of a `ContextSnapshot` or a
  `ContextStore` lists hidden keys and never their values.
- **The lifecycle events run in the job's context.** `JobProcessing`,
  `JobProcessed`, `JobFailed` and the other worker events are dispatched in the
  same scope, so a listener reads what the job read and what the job added.

### Dehydrating and hydrated hooks

Two hooks run at the two ends of the trip. Register them once, at boot,
in `bootstrap::register()`:

```rust
use suprnova::Context;

// Runs on every snapshot taken for queued work, before it is stored.
Context::dehydrating(|snapshot| {
    snapshot.data.insert("locale".into(), serde_json::json!("fr"));
    snapshot.hidden.remove("session_token");
});

// Runs when a worker has restored a snapshot, before the job runs.
Context::hydrated(|snapshot| {
    if let Some(locale) = snapshot.data.get("locale") {
        Context::add("locale_restored", locale.clone());
    }
});
```

A `dehydrating` callback receives `&mut ContextSnapshot` and may add, change or
remove entries. Use it to carry a value that lives outside the context, such
as the request's locale, or to keep a value from leaving the process. It
changes the snapshot only, never the live context.

A `hydrated` callback receives `&ContextSnapshot` and runs inside the restored
scope, so the `Context` methods read and write the job's context. It runs once
for every attempt of a job.

`ContextSnapshot` has two public fields, `data` and `hidden`, both
`BTreeMap<String, serde_json::Value>`.

### The functions behind the hooks

You seldom call these yourself, but a custom worker or a test may need them:

| Function | Purpose |
|---|---|
| `Context::dehydrate()` | Snapshot the current context, after every `dehydrating` callback has run. Returns `None` when there is nothing to carry. |
| `Context::hydrate(Option<&ContextSnapshot>)` | Build the `ContextStore` that queued work runs in, and run every `hydrated` callback. Enter the store with `Context::scope`. |
| `Context::restored(Option<ContextSnapshot>, fut)` | Run `fut` inside a fresh scope that holds the snapshot: `hydrate`, then `scope`. |

The hooks are process-wide. A test that registers one removes it again with
`Context::test_clear_hooks()`, which removes every `dehydrating` and
`hydrated` callback. It is compiled under `cfg(test)` and the `testing`
feature.

## Tests

Inside `#[tokio::test]` or `#[suprnova_test]`, no `Context` scope is
installed by default. Most context-touching code under test handles
the "no scope" case gracefully (silent no-op + `None` reads), so
plain unit tests don't need any setup.

Two situations where the test needs help:

### When the code under test calls `query_param`

The pagination helpers read `?page=` via `Context::query_param`. A
unit test for "page 3 returns the right offset" needs `query_param`
to return `Some("3")`. Two ways:

**`test_query_guard` (recommended):**

```rust
use suprnova::Context;

#[tokio::test]
async fn paginate_reads_page_from_query() {
    let _q = Context::test_query_guard("page", "3");

    // Code under test now sees ?page=3
    assert_eq!(Context::query_param("page"), Some("3".into()));

    let posts = Post::query().paginate(15).await?;
    assert_eq!(posts.current_page(), 3);
}
// `_q` drops at end of scope - thread-local override is wiped.
```

`test_query_guard` returns an RAII guard. Even if the test body
panics, `Drop` runs and clears the thread-local override before the
OS thread is recycled. The guard is `#[must_use]` - binding it to
`_` clears immediately, which is almost never what you want.

**Bare `test_set_query` + `test_clear_query`:**

```rust
#[tokio::test]
async fn manual_pair() {
    Context::test_clear_query();        // wipe leak from any sibling
    Context::test_set_query("page", "5");

    // … assertions …

    Context::test_clear_query();
}
```

Use the guard form. The manual pair exists for cases where you need
multiple overrides set and cleared independently, but the
`#[must_use]` guard is harder to misuse.

Both APIs are gated by `#[cfg(any(test, feature = "testing"))]` -
they're compiled into test binaries and into release builds that
opt into the `testing` feature for integration test harnesses. They
do not exist in plain release builds.

### When the code under test reads or writes from a `Context` scope

Install one explicitly via `Context::scope`:

```rust
use suprnova::context::{Context, ContextStore};

#[tokio::test]
async fn handler_reads_tenant_id() {
    Context::scope(ContextStore::default(), async {
        Context::add("tenant_id", "acme");

        let resolved = my_helper_that_reads_tenant().await;
        assert_eq!(resolved, "acme");
    })
    .await;
}
```

Or seed a query bag at scope creation:

```rust
use std::collections::HashMap;
use suprnova::context::{Context, ContextStore};

#[tokio::test]
async fn handler_reads_query_from_scope() {
    let mut q = HashMap::new();
    q.insert("page".into(), "3".into());
    q.insert("sort".into(), "name".into());

    Context::scope(ContextStore::with_query(q), async {
        assert_eq!(Context::query_param("page"), Some("3".into()));
        assert_eq!(Context::query_param("sort"), Some("name".into()));
    })
    .await;
}
```

`ContextStore::with_query(HashMap)` is the same constructor the
request middleware uses, so a test exercising the same code path as
production sees the same shape of query bag.

### Why the thread-local override exists

The query-param override is a `thread_local!`, not a task-local.
That's deliberate: it lets tests install query params **without
wrapping every assertion in a `Context::scope` call**. The
combination is:

1. Reads check the thread-local override first
2. If no override, read the task-local `CONTEXT` scope's query bag
3. If no scope either, return `None`

The thread-local lookup costs effectively nothing in production
(the override is always empty outside test builds) and saves test
authors from boilerplate `Context::scope(...)` wrappers around every
paginate-related assertion.

## Common patterns

### Stamp the request id on every log

The framework already does this. The request middleware seeds
`_request_id` into the visible bag so downstream jobs, broadcasts,
and `Context::all()` log dumps can read the id by name. The same
middleware also opens a `tracing` span carrying the id as a span
field, which is what makes it show up on every log line emitted
inside the request - see [Logging](logging.md) for the subscriber
side. Reading the id from `Context` is the right path when you need
the value as a string (for example to plumb into an outbound HTTP
request as a correlation header):

```rust
let request_id: Option<String> = Context::get("_request_id");
```

### Carry tenant context into a queued job

The tenant id you add in a handler is there when the job runs. Add it once,
and push the job:

```rust
use suprnova::{Context, Queue};

// In a handler, or in the middleware that resolves the tenant:
Context::add("tenant_id", "acme");

Queue::push(SendInvoice { invoice_id }).await?;
```

`SendInvoice::handle` reads `Context::get::<String>("tenant_id")`, and so does
any logging or deeply-nested helper the job calls. The job needs no field for
the tenant and no scope of its own, because the worker installed one from the
snapshot.

This is also where `hidden_add` earns its keep - add an API key to the hidden
bag once in the handler, and every downstream HTTP call inside the job reads it
via `Context::hidden_get`. Remember that hidden values are stored with the
job, see [Queued work](#queued-work). See [Queues](queues.md#context-on-queued-work)
for the queue side.

### Audit trail across a request

```rust
Context::push("audit.steps", "validated_input");
// … more work …
Context::push("audit.steps", "charged_card");
// … more work …
Context::push("audit.steps", "sent_receipt");

// At response-time middleware:
let steps: Vec<String> = Context::get("audit.steps").unwrap_or_default();
tracing::info!(?steps, "request audit trail");
```

A response-time middleware that runs after the handler can dump the
audit trail in one log line, instead of every step's individual
debug line scattered across the request log.

### Hidden bag for SDK extension credentials

```rust
// At request entry, after auth:
Context::hidden_add("sdk.api_key", load_api_key_for(user_id));

// Deep inside an SDK call:
let key = Context::hidden_get::<String>("sdk.api_key")
    .ok_or_else(|| FrameworkError::param("api key not stashed"))?;
```

Logs that dump `Context::all()` don't show the key. The hidden bag
is the right place for any credential the handler needs to pass
deep into a call stack without exposing it to log surfaces.

## Why Suprnova diverges

Laravel's `Context` facade (introduced in Laravel 11) is the
inspiration - same method names, same visible/hidden split, same
"silent outside a request" contract. Two differences come from
Rust's runtime:

**Across the queue the context travels, across `tokio::spawn` it does
not.** Laravel's `Context` flows through queued jobs because Laravel
serialises the context bag into the job payload at dispatch time.
Suprnova does the same at the queue boundary: the envelope carries a
`ContextSnapshot`, and the worker restores it, with `Context::dehydrating`
and `Context::hydrated` as the hooks Laravel calls by the same names. A
task you start with `tokio::spawn` is different. Rust's async model has no
single "current request" that task-locals flow into, so `tokio::spawn`
starts fresh. Suprnova exposes the propagation primitive
(`Context::current()` + `Context::scope`) and lets you opt into it there,
instead of pretending tasks inherit context they don't.

**Wrong-type reads are observable.** `get::<T>` on a value stored
as a different type silently returns `None` in Laravel (it's PHP,
the types weren't enforced at write time anyway). In Suprnova the
read emits a `tracing::trace!` because the wrong-type case
indicates a real bug - the value was written somewhere, just not
with the type you're reading. The trace lets you find it in
instrumented runs without changing the no-panic contract.

The third divergence is mechanical: Suprnova's `Context` is built on
`tokio::task_local!`, so its lifetime is bound to the Tokio task,
not to any global state. Cross-thread reads see the scope of the
**task currently running on that thread**, not whatever scope was
installed last. This is what makes the same `Context` facade safe
to call from a thread pool, an actor, or a `spawn_blocking` body -
provided you propagate the scope into the spawn.

## Where it lives

| Topic | File |
|---|---|
| `Context` facade, `ContextStore` and `ContextSnapshot` | `framework/src/context/mod.rs` |
| Scope installation on HTTP request | `framework/src/logging/request_id.rs` |
| Snapshot on push, restore on the worker | `framework/src/queue/mod.rs`, `framework/src/queue/worker.rs` |
| `Context::query_param` callers (pagination) | `framework/src/eloquent/builder.rs` |
| Re-exports | `framework/src/lib.rs` (`pub use context::{Context, ContextSnapshot, ContextStore}`) |

## Next

- [Request Lifecycle](lifecycle.md) - where the `Context` scope is
  installed on every request
- [Service Container](container.md) - for cross-request state that
  outlives a single task
- [Queues](queues.md#context-on-queued-work) - how a job receives the
  context of the code that queued it
- [Logging](logging.md) - how `Context::all()` ends up in structured
  log lines
- [Pagination](pagination.md) - the main downstream reader of
  `Context::query_param`
- [Testing](testing.md) - `test_query_guard` and `Context::scope`
  patterns for unit tests


# Digging Deeper

---

<!-- /docs/actions -->

# Actions

An action in Suprnova is a struct with one job: hold a single piece of
business logic behind one method. It's the Rust analogue of Laravel's
single-action invokable controllers - `RegisterUser`, `PublishPost`,
`ChargeInvoice`. The action lives in `src/actions/`, carries the
`#[injectable]` attribute so the container can resolve it, and exposes
an `execute(...)` method that controllers (and jobs, and other actions)
call. There is no `#[action]` macro and no framework-side enforcement
of "one method" - the shape is a convention, and `#[injectable]` is the
machinery that makes the convention painless.

```rust
use suprnova::{injectable, FrameworkError};

#[injectable]
pub struct RegisterUserAction {
    // Inject dependencies as fields - see "Dependencies" below
}

impl RegisterUserAction {
    pub async fn execute(&self, email: &str) -> Result<String, FrameworkError> {
        tracing::info!(action = "RegisterUser", email, "executed");
        Ok(format!("registered: {email}"))
    }
}
```

Resolve it from a handler with `App::resolve::<RegisterUserAction>()?`
and you've split your domain logic away from the HTTP layer without
inventing a service-layer base class. That's the whole pattern.

## Generating an action

```bash
suprnova make:action RegisterUser
```

The CLI normalises the name to PascalCase, appends `Action` if the
suffix is missing, then snake-cases the filename. So:

| `make:action <Name>` | Struct name | File |
|---|---|---|
| `RegisterUser` | `RegisterUserAction` | `src/actions/register_user_action.rs` |
| `SendNotification` | `SendNotificationAction` | `src/actions/send_notification_action.rs` |
| `ProcessPayment` | `ProcessPaymentAction` | `src/actions/process_payment_action.rs` |
| `ChargeInvoiceAction` | `ChargeInvoiceAction` | `src/actions/charge_invoice_action.rs` |

The generator writes the file and adds a `pub mod register_user_action;`
line to `src/actions/mod.rs`. The emitted stub compiles immediately:

```rust
//! register_user_action action

use suprnova::{injectable, FrameworkError};

/// RegisterUserAction
///
/// Single-responsibility command resolved from the container. Inject any
/// dependencies as fields and the `#[injectable]` macro wires them at
/// resolve time.
#[injectable]
pub struct RegisterUserAction {
    // Add injected dependencies as fields here, e.g.
    // db: suprnova::DbConnection,
}

impl RegisterUserAction {
    /// Execute the action.
    pub async fn execute(&self) -> Result<String, FrameworkError> {
        Ok("RegisterUserAction executed".to_string())
    }
}
```

The signature - `async fn execute(&self) -> Result<_, FrameworkError>` -
is the production-safe shape: async, returning a `Result` that converts
through `?` straight into an `HttpResponse` at the call site. The body
is a placeholder; swap it for the real workflow.

## The `#[injectable]` attribute

`#[injectable]` is the only piece of framework machinery the action
pattern relies on. It expands into three things:

1. A `#[derive(Clone)]` on the struct (and `Default` when there are no
   `#[inject]` fields).
2. An `inventory::submit!` entry so boot can discover the type.
3. An auto-registration closure that `App::singleton_if_absent` runs
   once during `boot_services()`.

The macro's contract:

| Struct shape | Behaviour |
|---|---|
| Unit struct (`pub struct Foo;`) | Derives `Default + Clone`, registers `Default::default()` |
| Named fields, none `#[inject]` | Derives `Default + Clone`, registers `Default::default()` |
| Named fields with `#[inject]` | Derives `Clone` only; each `#[inject]` field is resolved from the container at boot, non-inject fields default |
| Tuple struct | Rejected at compile time - "use named fields instead" |

A resolved action is a clone of the stored singleton. The cost is one
`Clone` per `App::resolve::<Action>()?` call, which for a unit struct or
a struct of `Arc`-wrapped services is a handful of refcount bumps. Heavy
state belongs behind `Arc<dyn …>` services that the action injects, not
inside the action itself.

### `#[inject]` happens at boot, not per call

When the framework boots, `App::boot_services()` walks every
`#[injectable]` registration and runs them in a fixed-point retry loop.
Each entry tries to resolve its `#[inject]` fields from the container.
If a dependency hasn't been registered yet, the entry defers to the next
iteration. The loop runs until either every entry succeeds or no
progress is made - and on failure the framework returns a structured
error naming the unresolvable type or the cycle.

The practical consequence: **`App::resolve::<MyAction>()` clones the
already-constructed singleton**. It does not run `#[inject]` resolution
on every call. Anything injectable that an action depends on must itself
be registered before the action - either via its own `#[injectable]`
attribute, or by a manual `App::bind` / `App::singleton` in your
`bootstrap()` function. The retry loop handles inventory ordering for
you; it does not invent missing services.

## Using an action from a controller

The standard handler shape: resolve, execute, render.

```rust
use suprnova::{App, Request, Response, ResponseExt, json_response};

use crate::actions::register_user_action::RegisterUserAction;

pub async fn store(_req: Request) -> Response {
    let action = App::resolve::<RegisterUserAction>()?;
    let result = action.execute("alice@example.com").await?;

    json_response!({ "ok": true, "result": result }).status(201)
}
```

Both `?` points work because both error types convert into
`HttpResponse` via `From` impls - `App::resolve` returns
`Result<T, FrameworkError>` and the framework error converter handles
the rest. Missing service registration surfaces as a 500 with the
service name in the structured log, not a panic. See
[Error Model](error-model.md) for the full picture.

If you'd rather avoid the `?` on the resolve - for example in a path
that should hard-fail at boot time - `App::get::<RegisterUserAction>()`
returns `Option<T>` and you can `.expect("registered at boot")` to
fail loudly if you got the wiring wrong.

## Async actions that touch the database

This is the path most actions actually take - load or write through an
Eloquent model. Lift the body from your domain; the surface is the
same.

```rust
use suprnova::{attrs, injectable, FrameworkError, Model};

use crate::models::todos::Todo;

#[injectable]
pub struct CreateRandomTodoAction;

impl CreateRandomTodoAction {
    pub async fn execute(&self) -> Result<Todo, FrameworkError> {
        let n = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_millis()
            % 10000;

        Todo::create(attrs! {
            title: format!("Todo #{}", n),
            description: format!("created at {}", n),
            done: false,
        })
        .await
    }
}

#[injectable]
pub struct ListTodosAction;

impl ListTodosAction {
    pub async fn execute(&self) -> Result<Vec<Todo>, FrameworkError> {
        Ok(<Todo as suprnova::eloquent::Model>::all().await?.into_vec())
    }
}
```

`Todo::create(attrs!{...})` and `Todo::all()` come from the
`#[suprnova::model]` macro. See [Eloquent](eloquent.md) for the model
surface. Note that `Model::all()` returns a `Collection<Todo>` - the
example calls `.into_vec()` to hand the controller a plain `Vec`; you
can also return the `Collection` directly and let the serialiser render
it.

Wiring those into a controller:

```rust
use suprnova::{App, Request, Response, ResponseExt, json_response};

use crate::actions::todo_action::{CreateRandomTodoAction, ListTodosAction};

pub async fn create_random(_req: Request) -> Response {
    let action = App::resolve::<CreateRandomTodoAction>()?;
    let todo = action.execute().await?;
    json_response!({ "ok": true, "todo": todo }).status(201)
}

pub async fn list(_req: Request) -> Response {
    let action = App::resolve::<ListTodosAction>()?;
    let todos = action.execute().await?;
    json_response!({ "ok": true, "todos": todos })
}
```

Two `?` per handler; the controller stays a thin adapter between HTTP
and the domain.

## Dependencies via `#[inject]`

When an action needs collaborators - a mailer, a logger, a domain
service - declare them as fields and tag each with `#[inject]`:

```rust
use suprnova::{injectable, FrameworkError};

use crate::services::{MailerService, LoggerService};

#[injectable]
pub struct SendWelcomeEmailAction {
    #[inject]
    mailer: MailerService,
    #[inject]
    logger: LoggerService,
}

impl SendWelcomeEmailAction {
    pub async fn execute(&self, to: &str) -> Result<(), FrameworkError> {
        self.logger.info(&format!("welcome → {to}"));
        self.mailer.send_welcome(to).await
    }
}
```

Both `MailerService` and `LoggerService` must themselves be
container-registered before this action boots - either with their own
`#[injectable]` attribute, or by a `bootstrap()` call:

```rust
// In src/bootstrap.rs
App::singleton(MailerService::from_env()?);
App::singleton(LoggerService::default());
```

If either dependency is missing when boot runs the fixed-point loop,
boot returns an error naming the unresolved type and the framework
exits non-zero rather than starting with a half-wired container.

Non-`#[inject]` fields fall back to `Default::default()`, so you can
mix injected dependencies with plain state without writing a
constructor.

## When to use an action

The rule of thumb: an action exists when the same piece of work is (or
might be) triggered from more than one entry point. A registration flow
that runs from both an HTTP route and a queued job belongs in
`RegisterUserAction`. A one-off "render this index page" handler does
not need an action - keep it in the controller.

| Good fit | Example |
|---|---|
| Multi-step business operations | `RegisterUserAction`, `CheckoutAction` |
| Work shared between HTTP + queue | `IssueRefundAction` (dispatched both ways) |
| Logic worth testing without a request | `CalculateTotalsAction` |
| External integrations | `SendEmailAction`, `SyncInventoryAction` |
| Anything the controller would otherwise inline + duplicate | rule-of-three trigger |

Compared to a controller, an action is reusable, has no `Request`
binding, and is trivial to call from a test (`App::resolve` + `await`).
A controller stays an HTTP-aware boundary that knows how to translate
an action's result into a `Response`.

| Controller | Action |
|---|---|
| Handles one route | Reusable across routes, jobs, schedules |
| Knows about `Request` / `Response` | Knows about your domain types |
| Returns `Response` | Returns `Result<T, FrameworkError>` |
| Calls actions | Called by controllers (and others) |

## Actions, the bus, and queues

Actions are not the only place business logic can live - the
[Bus](bus.md) handles dispatched commands with typed outputs, and the
[Queue](queues.md) handles work that should run on a worker. Choose by
how the work is invoked:

| You want… | Reach for |
|---|---|
| Synchronous business logic, callable from a controller or a job | **Action** (`#[injectable]` + `execute`) |
| A typed command with a registered handler, callable via `Bus::dispatch` | [Bus](bus.md) |
| Durable, retried, off-task work | [Queue](queues.md) |

Mixing is fine: a `BusHandler` or a `Job` often just resolves an action
and calls its `execute`. The action holds the domain logic; the bus or
queue holds the dispatch metadata.

## File layout

What `make:action` emits, plus the room to group:

```
src/
├── actions/
│   ├── mod.rs                          // pub mod register_user_action;
│   ├── register_user_action.rs
│   ├── send_welcome_email_action.rs
│   └── billing/                        // group by domain when the dir grows
│       ├── mod.rs
│       ├── charge_invoice_action.rs
│       └── issue_refund_action.rs
├── controllers/
└── main.rs
```

Nothing in the framework requires this layout; the generator writes
into `src/actions/` because that's the convention. Move an action to
`src/billing/actions/` and it'll keep working - `#[injectable]` is
location-agnostic.

## Testing an action

Because an action is just a container-resolvable struct with an `async`
method, the test surface is `App::resolve` + `await`. The same
`TestDatabase` test fixture used elsewhere works here:

```rust
use suprnova::{describe, expect, test, App};
use suprnova::testing::TestDatabase;

use crate::actions::todo_action::ListTodosAction;
use crate::models::todos::Todo;

describe!("ListTodosAction", {
    test!("returns all todos", async fn(_db: TestDatabase) {
        Todo::create(suprnova::attrs! { title: "Test", description: "", done: false })
            .await
            .unwrap();

        let action = App::resolve::<ListTodosAction>().unwrap();
        let todos = action.execute().await.unwrap();

        expect!(todos).to_have_length(1);
    });
});
```

See [Testing](testing.md) for the full `describe!` / `test!` / `expect!`
surface and for `TestContainer::fake` when you want to inject a
fake-mailer or fake-gateway into an action under test.

## Why Suprnova diverges

Laravel single-action controllers - classes with a `__invoke` method
in `App\Actions\` - are constructed per request. The container
resolves the class, runs constructor injection, and the instance is
thrown away when the response leaves. PHP's process-per-request model
makes that essentially free.

Suprnova actions are container-resident singletons: built once at boot
with `#[inject]` fields resolved then, cloned out on every
`App::resolve`. The pattern fits Rust because cloning a struct of
`Arc`-wrapped services costs a few refcount bumps, while
constructing-and-discarding a struct on every request would force every
field through allocation. The Laravel-shaped convention - one struct,
one method, named for the operation - survives intact; the wiring under
it is shaped for Tokio.

The other intentional split: controllers stay free functions (see
[Controllers](controllers.md)), so the HTTP layer is a pure
request-to-response transform with no DI surface of its own.
Constructor-style injection happens at the `#[injectable]` boundary,
inside the action, where it belongs.

## Next

- [Controllers](controllers.md) - the HTTP-facing free functions that resolve and call actions
- [Service Container](container.md) - what `App::resolve`, `App::singleton`, and the three-layer lookup actually do
- [Bus](bus.md) - typed command dispatch when you want a registered handler instead of a resolved action
- [Testing](testing.md) - `App::resolve` + `TestContainer::fake` for hermetic action tests
- [Error Model](error-model.md) - how `?` on `App::resolve::<Action>()?` and `action.execute().await?` collapses into a clean response


---

<!-- /docs/console -->

# Console

Each Suprnova project ships with a `console` binary - the runtime command dispatcher for everything that needs the app's compiled types: database seeders, pruners, one-shot maintenance tasks, anything you'd build with Laravel's `php artisan`. Commands are either typed structs that `#[derive(Command)]` (built on top of `clap::Parser`) or async fns annotated with `#[command]`; the framework collects them via `inventory` at link time, so adding a new command is a single file with no central registry to edit. This is the Suprnova analogue of `php artisan` - same script, same process, same address space, exits when the handler returns.

## Quick Start

The recommended shape uses `#[derive(clap::Parser, Command)]` for typed args:

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "greet", description = "Print a friendly greeting")]
pub struct Greet {
    #[arg(short, long, default_value = "world")]
    pub name: String,

    #[arg(long, default_value_t = false)]
    pub loud: bool,
}

#[async_trait]
impl TypedCommand for Greet {
    async fn run(self) -> Result<(), FrameworkError> {
        let prefix = if self.loud { "HELLO" } else { "Hello" };
        suprnova::console::line(format!("{prefix}, {}!", self.name));
        Ok(())
    }
}
```

Drop that in `src/commands/greet.rs`, add `pub mod greet;` to `src/commands/mod.rs`, and run it:

```bash
cargo run --bin console -- greet
# Hello, world!
cargo run --bin console -- greet --name Alice --loud
# HELLO, Alice!
cargo run --bin console -- greet --help
# (clap-generated per-command help, including the typed flags)
```

No central registry to edit. `#[derive(Command)]` submits a `CommandEntry { name, description, clap_builder, handler }` via inventory; the console binary calls `suprnova::console::dispatch_argv_with_init(argv, init)`, which builds one clap parser tree from every registered entry, runs the bootstrap `init` closure only when a real subcommand matches, and routes the parsed `ArgMatches` to the right handler.

### The simpler path: raw `Vec<String>`

For trivial commands that don't need typed args, the `#[command]` attribute on an async fn works too:

```rust
use suprnova::{command, FrameworkError};

#[command(name = "ping", description = "Smoke test")]
pub async fn ping(_args: Vec<String>) -> Result<(), FrameworkError> {
    suprnova::console::line("pong");
    Ok(())
}
```

A command prints with `suprnova::console::line`, not `println!`. See [Printing and asking](#printing-and-asking).

Under the hood both paths land in the same `CommandEntry` registry; the raw shape just uses a clap subcommand with a `trailing_var_arg` to capture argv into the `Vec<String>`. Prefer the typed shape for any command with arguments - you get per-command `--help`, value parsing, default values, and short/long flag pairs without writing a parser by hand.

## The Console Binary

`suprnova new` scaffolds two binaries into every new project:

- **`<project>`** (`cmd/main.rs` or `src/main.rs`) - the HTTP server, started by `cargo run` or `suprnova serve`. Long-running; serves until killed.
- **`console`** (`src/bin/console.rs`) - the runtime command dispatcher. One-shot; exits when the handler returns.

The console binary's `main` is small and predictable:

```rust
use std::process::ExitCode;

#[suprnova::main(flavor = "current_thread")]
async fn main() -> ExitCode {
    // Surface this project's version via `--version` / `--help`.
    // env! resolves to the user's app version, not the framework's.
    suprnova::console::set_version(env!("CARGO_PKG_VERSION"));

    let argv: Vec<String> = std::env::args().collect();
    let result = suprnova::console::dispatch_argv_with_init(argv, || async {
        my_app::config::register_all();
        my_app::bootstrap::register().await;
    })
    .await;

    match result {
        Ok(()) => ExitCode::SUCCESS,
        // A command that returned `FrameworkError::exit(code)` ends with
        // its code; every other error ends with 1.
        Err(error) => ExitCode::from(error.exit_code()),
    }
}
```

Tokio runs in `current_thread` flavor - there's no work to parallelize across cores in a one-shot command, and the multi-threaded runtime's worker pool would just be overhead.

Two things to notice:

- **Bootstrap is lazy.** The closure passed to `dispatch_argv_with_init` only runs when clap matches a real registered subcommand. `console --help`, `console --version`, missing-subcommand, and parse-error paths all skip it - so `console --help` works on a fresh checkout that doesn't have `DATABASE_URL` set yet.
- **A command gets what a queued job gets.** After the closure, `dispatch_argv_with_init` boots the rest of the process the way `queue:work` does: the `#[injectable]` and `#[service]` inventory, the `#[policy]` gates, and the runtime drivers (Cache, Localization, the environment's disks, Queue, RateLimit, Mail). A command can resolve an injectable action, write the cache, or check a policy with no setup of its own. A driver whose backend does not come up is reported on stderr as a warning, and the command still runs: a one-off command often uses none of the drivers, and a mail driver missing its key must not block `db:seed`. A command that does use the broken driver fails when it reaches it. A queue worker refuses to start instead.
- **Supervisors and queued listeners finish.** After the command returns, the dispatcher cancels the supervisors your bootstrap started and gives them up to five seconds to exit, then waits up to ten seconds for the queued event listeners still running, so an event the command dispatches last is handled before the process exits.
- **A failed boot is reported.** When your bootstrap panics, before it returns its future or while it runs, or the framework's boot fails, the command doesn't run. The dispatcher reports the failure through `Exceptions::report`, so the callbacks your bootstrap registered before it failed see it, then writes it as `error: console bootstrap failed: <reason>` and returns it.
- **`main` doesn't print errors.** `dispatch_argv_with_init` owns all user-facing stderr - it writes the handler's error message as `error: <message>` (unless the error is silent, like a clap parse failure that clap already printed) and prints clap's own help / version / parse-error output. `main` is pure `Result → ExitCode` translation: `0` for `Ok`, and `error.exit_code()` for an error, which is the code a command chose with `FrameworkError::exit` and `1` for any other failure. Adding a redundant `eprintln!` would double-print.

A project scaffolded before 4.0.0 maps every error to `ExitCode::FAILURE`. To end with the code a command chose, replace `Err(_) => ExitCode::FAILURE` with `Err(error) => ExitCode::from(error.exit_code())` in `src/bin/console.rs`.

If you want a particular command to skip an expensive bootstrap step entirely, gate the step itself on an env var rather than threading a "lazy bootstrap" flag through the framework.

## Built-in Commands

The framework registers a small set of commands itself. Linking the framework into a project pulls them in automatically.

| Command       | What it does                              |
|---------------|-------------------------------------------|
| `db:seed`     | Run every registered `Seeder` in order. Accepts `--class=<Name>` (or a bare positional) to run a single named seeder, matching `php artisan db:seed --class=UserSeeder`. |
| `model:prune` | Walk the `PrunerEntry` registry and force-delete every row each registered `Prunable` / `MassPrunable` scope returns. `--model=<Name>` restricts to one type; `--pretend` reports rowcount without modifying any rows. |
| `db:monitor`  | Print how many connections the database server of each connection has. `--max=<n>` also dispatches `DatabaseBusy` for each server at or over that number. See [Database](database.md#busy-database---dbmonitor-and-dbmonitor). |
| `--help` / `-h` | List available commands; per-subcommand `--help` is built by clap from the typed args. |
| `--version`   | Print the version registered by `set_version` (typically your app's `CARGO_PKG_VERSION`). Omitted entirely if `set_version` was never called. |

`db:seed` runs whatever you've registered in `bootstrap::register()` with `suprnova::seed::register::<MySeeder>()`. On an empty registry a bare `db:seed` prints a warning and returns `Ok(())` - invoking `db:seed` before registering seeders is a benign user mistake, not a programmer error. A targeted run, `db:seed --class=<Name>`, fails with the not-found error when no seeder of that name is registered, whether or not other seeders are.

`db:seed` reports progress on a targeted run using
`suprnova::two_column_detail`, which renders a name, a dot leader, and a
status as one 80-column line. Your own commands can call it for the same
look.

> The worker daemons (`queue:work`, `schedule:run`, `schedule:work`, `schedule:list`, `workflow:work`) are **not** on the console binary. They live on the app/server binary's clap parser (the same binary that serves HTTP). The global `suprnova` CLI shells into `cargo run --quiet -- <name>` for those. See the [Asymmetry section](#asymmetry-with-suprnova-migrate) below.

## SSR commands

The application binary (the one `cmd/main.rs` builds, which also serves HTTP) runs the Inertia SSR server with three commands. Each one reads the Inertia configuration the application installed with `Inertia::install`, so it starts, stops, and checks the same worker that first visits dispatch to:

```bash
cargo run --bin <app> -- ssr:start                # run the worker in the foreground
cargo run --bin <app> -- ssr:start --runtime bun  # run it under another runtime
cargo run --bin <app> -- ssr:check                # exit 0 when the worker is healthy
cargo run --bin <app> -- ssr:stop --graceful      # exit 0 whether or not a worker runs
```

| Command | What it checks and does | Exit status |
|---------|-------------------------|-------------|
| `ssr:start [--runtime <runtime>]` | Refuses when SSR is not enabled, when no bundle is found, or when `ensure_runtime_exists` is set and the runtime can't be found. Then it asks a running worker to shut down, refuses when that worker is still running (it answered, or kept the connection open), and runs `<runtime> <bundle>` in the foreground. | 1 when it refuses, otherwise the status the worker exits with |
| `ssr:stop [--graceful]` | Sends `GET {url}/shutdown`. The worker exits without an answer, which counts as stopped. With `--graceful`, a worker that can't be connected to counts as not running. | 0 when the worker stopped, or with `--graceful` when none runs; 1 otherwise |
| `ssr:check` | Asks the SSR gateway's health check: `GET {url}/health` answering 2xx for the default HTTP gateway. | 0 when the worker is healthy; 1 when it isn't, or when the bound gateway has no health check |

`ssr:start` finds the bundle the way the SSR dispatch does: the configured `ssr_bundle_path` when that file exists, else the first conventional path that exists (`frontend/bootstrap/ssr/ssr.js`, `frontend/bootstrap/ssr/app.js`, `frontend/bootstrap/ssr/ssr.mjs`, `frontend/bootstrap/ssr/app.mjs`, `public/js/ssr.js`, `public/js/app.js`). When the configured file is missing and a conventional one exists, it prints a warning that names both and runs the conventional one. The runtime is `--runtime`, else `ssr_runtime` (`node` by default). With `ssr_ensure_runtime_exists(true)`, a runtime that names a path must be an executable file, and a bare name must be an executable in a `PATH` directory:

```rust
Inertia::install(
    &InertiaConfig::new()
        .ssr("http://127.0.0.1:13714")
        .ssr_bundle_path("frontend/bootstrap/ssr/ssr.js")
        .ssr_runtime("bun")
        .ssr_ensure_runtime_exists(true),
)?;
```

While the worker runs, `ssr:start` forwards its stdout as output and writes each line of its stderr to stderr, logging every line that isn't blank as an error. Ctrl-C (`SIGINT`) or `SIGTERM` to `ssr:start` is forwarded to the worker as the same signal, and a second one kills it. A worker that ends because of the forwarded signal counts as a success.

The three commands run the `bootstrap` hook and the `http_bootstrap` hook, because the scaffold installs Inertia in `http_bootstrap`. A production image that runs them therefore needs the built frontend manifest, as an image that serves does: `Inertia::install` fails closed in production without it. They bind no port and boot no runtime driver, so a queue or mail backend that is down can't stop them. When no Inertia configuration is installed, they fail with a message that names `Inertia::install`.

The `suprnova` CLI's `ssr:start`, `ssr:stop`, and `ssr:check` run these commands. From the project directory, each one runs the application binary the way `suprnova serve` runs the backend, and passes `--runtime` and `--graceful` through:

```bash
suprnova ssr:start --runtime bun  # cargo run --bin <app> -- ssr:start --runtime=bun
suprnova ssr:stop --graceful      # cargo run --bin <app> -- ssr:stop --graceful
suprnova ssr:check                # cargo run --bin <app> -- ssr:check
```

The CLI has no SSR configuration of its own, so the configuration the application installed decides the URL, the bundle, the runtime, and the checks. The application's output reaches the CLI's stdout and stderr. The application runs in a process group of its own, so a terminal's Ctrl-C, which goes to the CLI's process group, reaches the application once, through the CLI. The CLI forwards each `SIGINT` and `SIGTERM` it receives to the application, so a second one still kills the worker. It forwards `SIGHUP`, `SIGQUIT` (`Ctrl-\`), `SIGTSTP` (Ctrl-Z), and `SIGCONT` (`fg`) to the application's whole process group, the worker included, because the application's `ssr:start` doesn't handle them. At a `SIGTSTP` the CLI stops as well, so Ctrl-Z and `fg` stop and resume the CLI, the application, and the worker together. Under `stty tostop`, a terminal stops a process outside its foreground process group the first time it writes, so the application would stop at its first line of output: run the CLI's `ssr:start` from a terminal without that setting, or run the application's `ssr:start` directly with `cargo run --bin <app> -- ssr:start`. The CLI exits with the application's status, or with 128 plus the signal number when a signal ended the application. Outside a project, or with a `Cargo.toml` that names no package, the CLI fails and says why.

### Why Suprnova diverges

Laravel names these commands `inertia:start-ssr`, `inertia:stop-ssr`, and `inertia:check-ssr`. Suprnova keeps the `ssr:*` names the `suprnova` CLI already used. They live on the application binary, next to the worker daemons, because the console binary doesn't run the `http_bootstrap` hook that installs Inertia.

Laravel's `inertia:stop-ssr` waits for the worker without a time limit. `ssr:stop` gives up after the configured SSR timeout (`ssr_timeout`). With `--graceful`, only a worker that can't be connected to counts as not running: a worker that accepts the connection and never answers is still running, and the command fails.

## Defining Commands

Two macros, one registry. Pick whichever fits the command's shape.

### `#[derive(Command)]` - typed args (recommended)

Goes on top of `#[derive(clap::Parser)]`. The struct fields are the command's args; clap parses argv into the struct; the framework calls your `TypedCommand::run(self)`.

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "users:purge", description = "Purge users older than N days")]
pub struct UsersPurge {
    #[arg(long)]
    pub older_than_days: u32,

    #[arg(long, default_value_t = false)]
    pub dry_run: bool,
}

#[async_trait]
impl TypedCommand for UsersPurge {
    async fn run(self) -> Result<(), FrameworkError> {
        // self.older_than_days, self.dry_run - typed, validated by clap
        Ok(())
    }
}
```

Attributes:

| Attribute    | Required | Purpose                                       |
|--------------|----------|-----------------------------------------------|
| `#[console(name = "...")]` | yes | The invocation name on the CLI (`"users:purge"`, `"mail:send"`, `"greet"`). |
| `#[console(description = "...")]` | no | One-line description shown in top-level help. Without it, the command keeps the about text clap has for the struct: its doc comment, or `#[command(about = "...")]`. A `description` overrides both. |
| `#[arg(...)]` (clap) | n/a | Clap's own field attributes for short/long flags, defaults, value parsers, etc. |

You also get clap's auto-generated per-command help (`console users:purge --help`) for free.

A command can take its about text from the doc comment instead of the attribute:

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::{Command, FrameworkError, TypedCommand};

/// Rebuild the search index
#[derive(Parser, Command, Debug)]
#[console(name = "search:rebuild")]
pub struct SearchRebuild {}

#[async_trait]
impl TypedCommand for SearchRebuild {
    async fn run(self) -> Result<(), FrameworkError> {
        Ok(())
    }
}
```

`CommandEntry::about()` returns the text the help shows for a command, whichever of the three sources it came from, and `None` when the command has none. To list commands with their descriptions, read `about()`. `CommandEntry::description` holds only the text of the `description` attribute and is empty when the attribute is missing.

```rust
for entry in suprnova::console::list() {
    let about = entry.about().unwrap_or_default();
    suprnova::console::line(format!("{:<20} {about}", entry.name));
}
```

### `#[command]` - raw `Vec<String>` (simple cases)

For commands that take no arguments or only consume positionals as a list, the attribute on an async fn is enough:

```rust
use suprnova::{command, FrameworkError};

#[command(name = "cache:clear", description = "Drop every entry from the cache")]
pub async fn cache_clear(_args: Vec<String>) -> Result<(), FrameworkError> {
    suprnova::Cache::flush().await
}
```

The annotated function must be `async fn(Vec<String>) -> Result<(), FrameworkError>`. The macro preserves the original function, so you can also call it directly from Rust - useful for unit tests that don't want to thread argv strings through the dispatcher.

Names in both shapes support Laravel-style namespacing: `mail:send`, `queue:work`, `db:fresh`. The colon is purely cosmetic - it's a string the dispatcher matches against `argv[1]`.

## Printing and asking

Print with `suprnova::console::line` and `suprnova::console::error_line`, and ask with `suprnova::console::ask` and `suprnova::console::confirm`. In the console binary they use the standard streams. Under [`console::test`](#testing-a-command) they use a buffer and a list of prepared answers, so the same command body runs in both.

| Function | What it does |
|---|---|
| `line(text)` | Print one line on the standard output. Takes anything that implements `Display`. |
| `error_line(text)` | Print one line on the standard error: a warning, or a note that must stay out of piped output. |
| `ask(question) -> Result<String, FrameworkError>` | Print the question, wait on the standard input, and return the line typed, without its line ending. |
| `confirm(question, default) -> Result<bool, FrameworkError>` | Ask a yes or no question. `y` and `yes` are yes, `n` and `no` are no, in any case. An empty line is `default`, and the `[Y/n]` or `[y/N]` hint shows which one that is. |

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::console;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "users:purge", description = "Delete users older than N days")]
pub struct UsersPurge {
    #[arg(long)]
    pub older_than_days: u32,
}

#[async_trait]
impl TypedCommand for UsersPurge {
    async fn run(self) -> Result<(), FrameworkError> {
        let question = format!("Delete users older than {} days?", self.older_than_days);
        if !console::confirm(&question, false)? {
            console::line("nothing deleted");
            return Ok(());
        }
        console::line("deleted 12 users");
        Ok(())
    }
}
```

Three rules keep a command honest:

- `line` does not panic when the write fails. `println!` panics when the reader of a pipe has gone away, as in `console list | head`.
- `ask` and `confirm` return an error when the input ends before a line was read, which is what a command gets with no terminal and nothing piped in. The command stops instead of acting on an answer nobody gave. `confirm` also returns an error for an answer that is neither yes nor no.
- Return the error of a failed command. The console prints it as `error: <message>`, so printing it with `error_line` as well shows it twice.

`ask` blocks the thread while it waits on the standard input. That is right for a console command, which has nothing else to do until you answer, and wrong inside a server.

What a command prints with `println!` reaches the standard output of the process, and a test cannot read it. The framework's own commands, `db:seed` and `model:prune` among them, print through the console.

## Marked lines and verbosity

`console::error(text)`, `console::warn(text)` and `console::info(text)` print one line behind a mark: `ERROR` and `WARN` on the standard error, `INFO` on the standard output. On a terminal the mark is styled, white on red, black on yellow and white on blue. Where the stream is not a terminal, or where `NO_COLOR` is set to a non-empty value, the line is plain text, `ERROR boom`. A test always reads the plain text.

Every command accepts `-q` or `--quiet`, and `-v`, `-vv` or `-vvv` (also `--verbose`). Put the flags before the command name, `console -v users:purge`, or after it. A command that declares a flag of the same name keeps its own flag after its name. A raw `#[command]` gets everything after its name as typed, so give it the flags before its name.

| Flag | `console::verbosity()` |
|---|---|
| `-q`, `--quiet` | `Verbosity::Quiet` |
| none | `Verbosity::Normal` |
| `-v` | `Verbosity::Verbose` |
| `-vv` | `Verbosity::VeryVerbose` |
| `-vvv` | `Verbosity::Debug` |

`line`, `error_line`, `error`, `warn` and `info` write at `Normal`. `console::line_at(text, level)` and `console::error_at(text, level)` write only when the run asked for at least `level`. `--quiet` silences all of them. The error of a failed command still reaches the standard error, so a quiet run that fails says why.

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::console::{self, Verbosity};
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "orders:import", description = "Import the day's orders")]
pub struct OrdersImport {}

#[async_trait]
impl TypedCommand for OrdersImport {
    async fn run(self) -> Result<(), FrameworkError> {
        console::info("importing 3 files");
        console::line_at("reading orders-0001.csv", Verbosity::Verbose);
        console::warn("orders-0002.csv has no rows");
        console::error("orders-0003.csv is not UTF-8; skipped");
        Ok(())
    }
}
```

## Prompts

Beyond `ask` and `confirm`, the console offers the prompts Laravel Prompts gives a command. Each one reads one line from the standard input, a terminal and a pipe alike, so a script can pipe the answers in.

| Function | What it does |
|---|---|
| `ask_with_default(question, default)` | Ask, and return `default` for an empty answer. The hint shows it: `Name? [Ada]`. |
| `secret(question)` | Ask for a password or a token. A terminal does not echo the answer, and a test never captures it. Laravel Prompts calls this `password`. |
| `select(question, options, default)` | Show the options, numbered, and return the index of the chosen one. The answer is an option as it is written, or its number. |
| `select_keyed(question, options, default)` | Show `(key, label)` options and return the chosen key. The answer is a label or a key; `default` names a key. |
| `multiselect(question, options, defaults)` | Return the indexes of the chosen options, in the order of the options. The answer lists them separated by commas: `Member,Owner`. |
| `progress(label, items, f)` | Map each item through `f(item, &mut bar)` behind a progress bar, and return the results in order. |
| `Progress::new(label, total)` | A bar you drive yourself with `advance(steps)`, `label(text)`, `hint(text)` and `finish()`. |
| `form()` | Chain `text`, `secret`, `confirm` and `select` steps, each under a name, and read every answer by name from `submit()`. |

An answer that is not one of the options is an error that names every option, and the command stops. An empty answer to a menu takes its default, and is an error when it has none.

On a terminal, a progress bar redraws one line as the work advances. Where the output is not a terminal, such as a pipe, a log or a test, the bar writes one plain line when it finishes, `Sync 3/3`, and a quiet run writes nothing.

```rust
use async_trait::async_trait;
use clap::Parser;
use suprnova::console;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "users:invite", description = "Invite a user")]
pub struct UsersInvite {}

#[async_trait]
impl TypedCommand for UsersInvite {
    async fn run(self) -> Result<(), FrameworkError> {
        let answers = console::form()
            .text("email", "Email?")
            .select("role", "Role?", &["Member", "Owner"], Some(0))
            .secret("token", "API token?")
            .confirm("notify", "Send the invitation now?", true)
            .submit()?;
        let email = answers.text("email").unwrap_or_default();
        let role = answers.selected("role").unwrap_or_default();

        let sent = console::progress("Inviting", [email], |address, bar| {
            bar.hint(address);
            address.len()
        });
        console::info(format!("invited {} user(s) with role {role}", sent.len()));
        Ok(())
    }
}
```

`FormAnswers::text` reads a `text` or `secret` answer, `confirmed` a `confirm` answer, and `selected` a `select` answer. Two steps of one name are an error before anything is asked, since one answer would replace the other. The `Debug` output of the answers hides a secret.

### Why Suprnova diverges

Laravel Prompts draws its menus with the arrow keys and falls back to plain questions where there is no terminal. Suprnova's prompts read one line everywhere, so the same command runs the same way by hand, from a script, and under `console::test`. The hidden answer of `secret` uses the terminal's echo control from the `console` crate that `dialoguer` provides.

`--quiet` silences what a command writes through these functions and nothing else: the error of a failed command and clap's own messages stay. A raw `#[command]` takes `-v` after its name as an argument of its own, because it receives its arguments as typed.

## Testing a command

`suprnova::console::test(argv)` runs a command through the dispatcher the console binary uses and collects what it printed. `argv` is what you type after the name of the binary. `.expects_question(question, answer)` prepares an answer, the other `expects_*` methods state what the command must print, and `.run().await` returns a `ConsoleRun`.

```rust
use suprnova::console;

#[tokio::test]
async fn purge_asks_before_it_deletes() {
    let run = console::test(["users:purge", "--older-than-days", "30"])
        .expects_question("Delete users older than 30 days?", "yes")
        .run()
        .await;

    run.assert_successful().assert_every_question_was_asked();
    run.assert_output_contains("deleted 12 users");
}
```

The test binary has to link the module that holds your commands. Make sure the crate declares `pub mod commands;` in `src/lib.rs`, and reference the crate from the test. `console::test` runs no bootstrap: `dispatch_argv` has no init closure, so set up the database and the container in the test, as in [Testing](testing.md).

`ConsoleTest` takes these expectations before the run:

| Method | Expects |
|---|---|
| `expects_question(question, answer)` | The command asks `question`, and gets `answer`. |
| `expects_confirmation(question, answer)` | The command asks the `confirm` `question`, and gets yes for `true` and no for `false`. |
| `expects_choice(question, answer, options)` | The command shows the menu `question` with exactly `options`, and gets `answer`. |
| `expects_output(line)` | The command prints `line`, exactly, as a whole line. Several calls expect their lines in the order of the calls, with other lines allowed between them. |
| `expects_output_to_contain(text)` | One write of the command contains `text`. |
| `doesnt_expect_output_to_contain(text)` | No write of the command contains `text`. |

The output expectations look at the standard output and the standard error alike. A write is one `console::line`, one question, or one message of the console, and a match never spans two writes: `bo` and `om` printed apart don't contain `boom`. A write of several lines gives each of its lines to `expects_output`.

`ConsoleRun` has these methods:

| Method | Returns or asserts |
|---|---|
| `output()` | The standard output as a `&str`. Questions are part of it, one line each. |
| `errors()` | The standard error as a `&str`. The error of a failed command is in it, as `error: <message>`. |
| `exit_code()` | `0` when the command succeeded, the code a command chose with `FrameworkError::exit`, and `1` when it failed otherwise or its arguments did not parse. Help and the version end with `0`. |
| `error()` | The `FrameworkError` the run ended with, as an `Option`. |
| `unasked_questions()` | The questions with a prepared answer that the command did not ask, in the order you gave them. |
| `unexpected_questions()` | The questions the command asked that the test did not expect at that point. |
| `unmet_expectations()` | One sentence for each expectation the command did not meet. |
| `assert_successful()` | Assert that the run ended with exit code `0`, asked no unexpected question, and met every expectation. |
| `assert_failed()` | Assert that the run ended with an exit code other than `0`, and asked no unexpected question. |
| `assert_exit_code(code)`, `assert_not_exit_code(code)` | Assert that the run ended with `code`, or with any other code, and that it asked no unexpected question and met every expectation. |
| `assert_output_contains(text)`, `assert_errors_contain(text)` | Assert that a stream contains `text`. |
| `assert_every_question_was_asked()` | Assert that `unasked_questions()` is empty. |

The assert methods return `&Self`, so you can chain them. A failed assertion lists every problem of the run at once, with both streams.

```rust
use suprnova::console;

#[tokio::test]
async fn purge_reports_what_it_deleted() {
    console::test(["users:purge", "--older-than-days", "30"])
        .expects_confirmation("Delete users older than 30 days?", true)
        .expects_output("deleted 12 users")
        .doesnt_expect_output_to_contain("skipped")
        .run()
        .await
        .assert_successful();
}
```

A command ends with an exit code of its own by returning `FrameworkError::exit(code)`, as a Laravel command returns an integer from `handle`. The dispatcher prints nothing for it and doesn't report it, so write the reason first. `FrameworkError::exit(0)` is a success.

```rust
use suprnova::{FrameworkError, command, console};

#[command(name = "orders:check", description = "Fail when orders are late")]
pub async fn orders_check(_args: Vec<String>) -> Result<(), FrameworkError> {
    let late = 3;
    if late > 0 {
        console::error(format!("{late} orders are late"));
        return Err(FrameworkError::exit(2));
    }
    Ok(())
}

#[tokio::test]
async fn late_orders_end_with_exit_code_2() {
    console::test(["orders:check"])
        .expects_output_to_contain("3 orders are late")
        .run()
        .await
        .assert_exit_code(2);
}
```

Help, the version, parse errors and the error of a failed command are collected too, so `console::test(["--help"])` and an argument the command does not take are testable.

Answers are given in order. A question that comes out of order, or one with no prepared answer, makes `ask` return an error and the command fails. An answer that went to another question than the one it was written for would let a test pass while the command deleted something the test never agreed to. The run also keeps the question, so every assertion on how the run ended fails and names it, even when the command goes on past the error. For `confirm`, the question is the text without the `[y/N]` hint.

`assert_failed` checks no other expectation. A test of a refusal, such as a menu that offers other options, keeps the answer the command refused, and asserts the failure and the error message. `assert_not_exit_code(0)` checks every expectation.

A prompt of the [Prompts](#prompts) section takes its answer from `expects_question` as well. For a menu, `.expects_choice(question, answer, options)` also checks that the menu offers exactly `options`, in that order, and the command fails when it offers others, so the test notices when the choices change. The answer is typed as a person types it: an option's label, and for `multiselect` the labels separated by commas.

```rust
use suprnova::console;

#[tokio::test]
async fn invite_takes_the_answers_by_name() {
    let run = console::test(["users:invite"])
        .expects_question("Email?", "ada@example.com")
        .expects_choice("Role?", "Owner", ["Member", "Owner"])
        .expects_question("API token?", "t0k")
        .expects_question("Send the invitation now?", "yes")
        .run()
        .await;

    run.assert_successful().assert_every_question_was_asked();
    assert!(!run.output().contains("t0k"));
}
```

`console::test(["-q", "users:purge"])` runs the command quietly, and `console::verbosity()` inside it answers the level the flags asked for. The captured output is plain text: marks without styles, and a progress bar as its one finishing line.

The collection belongs to the task the command runs on. What a task that the command spawned prints is not collected.

### Why Suprnova diverges

Laravel collects the output of a command in `$this->artisan(...)` and checks it with `expectsOutput` and `expectsQuestion`. Suprnova follows the same shape, but commands are plain Rust functions, so nothing can hook `println!`. A command has to print through `console::line`, `console::error_line`, `console::ask` and `console::confirm` for a test to see it, and a test states its questions in the order the command asks them.

Laravel checks the expectations when the command finishes and fails the test at once. A `ConsoleRun` holds the result instead, and the assert method you call checks it: `assert_successful`, `assert_exit_code` and `assert_not_exit_code` check every expectation, and an unexpected question fails every assertion on the run. A Laravel command writes its error lines to its one output, so the output expectations here read the standard output and the standard error together. `expects_output` matches whole lines, where Laravel matches whole writes.

## `suprnova make:command`

The CLI generator drops a runnable stub. The generated file uses the **typed shape** (`#[derive(Parser, Command)]` + `impl TypedCommand`) - that's the recommended default, and it gives you per-command `--help` for free:

```bash
suprnova make:command cache:clear
# → src/commands/cache_clear.rs (pub struct CacheClear with #[console(name = "cache:clear")])
# → src/commands/mod.rs gets `pub mod cache_clear;` appended (created if missing)
```

The stub prints with `suprnova::console::line`, so a test can read it. It is runnable as-is - `cargo run --bin console -- cache:clear` will print a line that names the command and says it is not implemented, and return `Ok(())` so you can wire it in and iterate. Fill in fields on the struct for typed args and replace the body of `TypedCommand::run`.

Name normalization:

| Input          | File              | Command name   |
|----------------|-------------------|----------------|
| `greet`        | `greet.rs`        | `greet`        |
| `CleanCache`   | `clean_cache.rs`  | `clean-cache`  |
| `clean-cache`  | `clean_cache.rs`  | `clean-cache`  |
| `mail:send`    | `mail_send.rs`    | `mail:send`    |

If the input contains `:`, the colon namespace is preserved verbatim. Otherwise the Rust fn name is snake_case and the command name is kebab-case.

Make sure `pub mod commands;` is declared in `src/lib.rs` so the inventory submission is link-reachable from the console binary. The generator scaffolds this for new projects and emits a loud warning if it's missing; if you removed it, the new file's `inventory::submit!` block will compile but never end up in the registry.

### Why Suprnova diverges

A global binary can't statically load your app's seeders, factories, or `#[command]` async fns, so the work runs in your project's own binaries. The `suprnova` CLI forwards framework tasks (`migrate`, `db:seed`, `schedule:list`, and the rest) to them through `cargo run`, which compiles on first use. Your own `#[command]`s live in the project's `console` binary. Run it directly:

```bash
./target/debug/console db:seed
./target/release/console greet Alice
cargo run --bin console -- mail:send
```

Laravel solves the same problem with `php artisan` - a per-project script that boots the framework and dispatches to user-defined commands. PHP can do this dynamically because the framework code lives next to the user's at runtime. Rust's compile-and-link model rules that out, so we ship the dispatcher as a library (`suprnova::console::*`) and let each project link its own one-line `console` binary.

### Asymmetry with `suprnova migrate`

There are three distinct command-invocation paths in a Suprnova project, and the asymmetry is **structural** - don't try to unify them:

| Command surface                                   | Invocation                                              | Why                                                 |
|---------------------------------------------------|---------------------------------------------------------|-----------------------------------------------------|
| `suprnova new`, `suprnova make:*`, `suprnova serve`, `suprnova key:generate`, … | Global CLI binary (installed via `cargo install --git`) | File-only generators and scaffolders; don't need user code. |
| `suprnova migrate`, `suprnova migrate:status`, `suprnova schedule:run`, `suprnova schedule:work`, `suprnova schedule:list`, `suprnova workflow:work` | Global CLI shells into `cargo run --quiet -- <name>` against the app/server binary | Long-running daemons and schema work that the same `Application::run` clap parser owns. The server binary's `queue:work` lives here too - `cargo run --bin <app> -- queue:work`. |
| `console db:seed`, `console model:prune`, `console <your-command>` | Per-project `console` binary (`src/bin/console.rs`) | One-shot commands that need user types (seeders, commands, prunable models) compiled into the user's crate. |

`suprnova db:seed` and `suprnova model:prune` are forwards to the console binary: the CLI runs `cargo run --quiet --bin console -- <name>` and checks no name itself. See [CLI Overview](cli.md#database).

The split is intentional. The server binary already needs a clap parser to choose between `serve`, `migrate`, `queue:work`, etc.; daemons that share its lifecycle live there. The console binary exists for everything else - short-lived, user-defined, type-rich. New runtime commands belong in `#[command]` / `#[derive(Command)]` dispatched by the project's `console` binary.

## Best Practices

### Keep handlers small; reach for shared services through the container

A `#[command]` is the CLI-shaped wrapper; the business logic should live in an `Action`, a service, or a method on a model. The handler parses args, resolves the service from the container, and forwards. That keeps the same logic testable from a unit test, an HTTP route, and the console.

```rust
#[command(name = "users:purge")]
pub async fn users_purge(args: Vec<String>) -> Result<(), FrameworkError> {
    let action = App::resolve::<PurgeStaleUsers>()?;
    action.execute(parse(args)?).await
}
```

`App::resolve` returns `Result<T, FrameworkError::ServiceUnresolved(_)>` - the `?` flavor of `App::get` (which returns `Option`). See [Service Container](container.md) for the full surface.

### Use namespaces for related commands

Group with `:`: `mail:send`, `mail:retry`, `mail:queue:work`. The dispatcher treats it as opaque, but humans scan `mail:*` better than `send-mail`, `retry-mail`, `mail-queue-work`.

### Don't print structured data - return it

Console handlers print to stdout for human-readable output. If a downstream tool needs to consume the output, write a `console <name> --json` variant that emits machine-readable JSON to stdout and a status line to stderr. Don't make the human-readable path responsible for both audiences.

### Treat exit codes as the contract

A handler returns `Err(...)` and the binary's `main` translates it: `FrameworkError::exit(code)` ends with `code`, and every other error with `1`. Don't call `std::process::exit` from inside a handler. It skips the drain of supervisors and queued listeners, and a test can't read the code. Tooling such as CI gates and supervised workers reads only the exit code.

## Reference

| Symbol                                    | Purpose                                       |
|-------------------------------------------|-----------------------------------------------|
| `suprnova::Command` (derive)              | Register a `clap::Parser`-deriving struct as a typed console command. Pairs with `TypedCommand`. |
| `suprnova::TypedCommand` (trait)          | Trait with `async fn run(self) -> Result<(), FrameworkError>` - the body of a typed command. |
| `suprnova::command` (attribute)           | Register an async fn taking `Vec<String>` as a raw-args console command. |
| `suprnova::console::dispatch_argv(argv)`  | Build the clap parser tree from every registered entry, parse argv, route to the handler. No bootstrap and no framework boot - for tests and programmatic callers that set up the process themselves, so a fake they installed is kept. |
| `suprnova::console::dispatch_argv_with_init(argv, init)` | Same as `dispatch_argv` but runs the `init` closure, then the framework's process boot (services, policies, runtime drivers), between clap's argv parse and the matched handler, and waits for queued listeners after it. None of it fires unless a real subcommand matches - `--help` / `--version` / parse-error paths skip it. This is what the scaffolded `console` binary uses. |
| `suprnova::console::set_version(&'static str)` | Register the version string surfaced via `--version` and in `--help`. Call once at the start of `main`. First registration wins. |
| `suprnova::console::find(name)`           | Look up a registered command by exact name.   |
| `suprnova::two_column_detail(left, right)` | Render a name, a dot leader, and a status word as one 80-column progress line. Mirrors Laravel's `$this->components->twoColumnDetail(...)`. |
| `suprnova::console::list()`               | All registered commands, sorted by name.      |
| `suprnova::CommandEntry`                  | Inventory record: `{ name, description, clap_builder, handler }`. Submitted by both macros. `about()` returns the text the help shows. |
| `suprnova::console::line(text)`, `error_line(text)` | Print one line on the standard output or the standard error. A test reads them. |
| `suprnova::console::line_at(text, level)`, `error_at(text, level)` | Print one line when the run asked for at least `level`. |
| `suprnova::console::error(text)`, `warn(text)`, `info(text)` | Print one line marked `ERROR`, `WARN` or `INFO`, styled on a terminal. |
| `suprnova::console::verbosity()`, `Verbosity` | The level `-q` and `-v` to `-vvv` asked for: `Quiet`, `Normal`, `Verbose`, `VeryVerbose` or `Debug`. |
| `suprnova::console::ask(question)`, `confirm(question, default)` | Read an answer from the standard input, or from the answers a test prepared. |
| `suprnova::console::ask_with_default`, `secret`, `select`, `select_keyed`, `multiselect` | The prompts of [Prompts](#prompts). |
| `suprnova::console::Progress`, `progress(label, items, f)` | A progress bar, and a map behind one. |
| `suprnova::console::form()`, `Form`, `FormAnswers`, `FormValue` | Several prompts whose answers come back by name. |
| `suprnova::console::test(argv)`           | Prepare a run of the console for a test. Returns a `ConsoleTest`; `.expects_question(..)`, `.expects_confirmation(..)` and `.expects_choice(..)` prepare answers, `.expects_output(..)`, `.expects_output_to_contain(..)` and `.doesnt_expect_output_to_contain(..)` state the output, and `.run().await` returns a `ConsoleRun`. |
| `suprnova::CommandHandler`                | The handler fn-pointer type: `fn(&clap::ArgMatches) -> Pin<Box<dyn Future<...>>>`. |
| `FrameworkError::silent()` / `.is_silent()` | Construct / detect an error that the dispatcher will NOT print to stderr. Used internally to suppress double-prints when clap already wrote a parse error to the terminal. |
| `FrameworkError::exit(code)` / `.exit_code()` | End a command with exit code `code`, printed and reported nowhere / the code the console binary ends with for an error: the chosen code, or `1`. |

## Next

- [Application Bootstrap](bootstrap.md) - what runs inside the `dispatch_argv_with_init` closure
- [Service Container](container.md) - `App::resolve` vs `App::get`, and how a handler reaches shared services
- [Seeding](seeding.md) - what `db:seed` actually invokes
- [Eloquent](eloquent.md) - `Prunable`, `MassPrunable`, and how `model:prune` walks the registry
- [Scheduling](scheduling.md) - the asymmetry: scheduler daemons live on the app binary, not the console


---

<!-- /docs/broadcasting -->

# Broadcasting

Broadcasting is the server-to-client notification layer on top of
Suprnova's [WebSocket primitive](websockets.md). You dispatch a
`Broadcastable` event through `EventFacade`; the framework fans the
event's JSON envelope out to every WebSocket subscriber on the channels
the event names. You never manage individual connections - you manage
channel subscriptions, and the hub does the rest.

The `BroadcastHub` is the bus. The default `InMemoryBroadcastHub` runs
entirely in-process - perfect for single-replica deployments and the
test suite. Behind the `broadcasting-fanout` Cargo feature,
`SeaStreamerBroadcastHub` routes the same events through Redis
Streams so a publish in one process reaches subscribers in every other
process.

Everything from the [WebSocket](websockets.md) chapter still applies -
heartbeat pings, `max_missed_pings`, `WsConfig`, per-route middleware,
path parameters. Broadcasting just adds a wire protocol and a channel
registry on top.

## Quick start

Four files and the browser sees an event.

`src/channels/order_updates.rs`:

```rust
use async_trait::async_trait;
use suprnova::broadcasting::Channel;

pub struct OrderUpdates;

#[async_trait]
impl Channel for OrderUpdates {
    fn name(&self) -> &'static str { "order.updates" }
}
```

`src/events/order_placed.rs`:

```rust
use serde::{Deserialize, Serialize};
use suprnova::Event;
use suprnova::broadcasting::Broadcastable;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OrderPlaced {
    pub order_id: i64,
    pub user_id: i64,
}

impl Event for OrderPlaced {
    fn event_name() -> &'static str { "OrderPlaced" }
}

impl Broadcastable for OrderPlaced {
    fn broadcast_on(&self) -> Vec<String> {
        vec!["order.updates".into()]
    }
}
```

`src/bootstrap.rs`:

```rust
use std::sync::Arc;
use suprnova::broadcasting::{BroadcastHub, ChannelRegistry, InMemoryBroadcastHub};
use suprnova::container::App;
use suprnova::events::EventFacade;

pub async fn register() {
    // 1. Bind the hub behind the trait - handlers resolve it uniformly.
    let hub: Arc<dyn BroadcastHub> = Arc::new(InMemoryBroadcastHub::new());
    App::bind::<dyn BroadcastHub>(Arc::clone(&hub));

    // 2. Register every channel up front; the WS handler resolves by name.
    let mut registry = ChannelRegistry::new();
    registry.register(OrderUpdates);
    App::singleton(Arc::new(registry));

    // 3. Wire the event → hub bridge once per Broadcastable type.
    EventFacade::broadcast::<OrderPlaced>(Arc::clone(&hub)).await;
}
```

`src/routes.rs` - build a `BroadcastingWsHandler` per route by
resolving the bootstrapped hub and registry from the container:

```rust
use std::sync::Arc;
use suprnova::broadcasting::{
    BroadcastHub, BroadcastingWsHandler, ChannelRegistry, InMemoryBroadcastHub,
};
use suprnova::container::App;
use suprnova::{routes, ws, AuthMiddleware};

fn broadcasting_handler() -> BroadcastingWsHandler {
    // Container-first; fall back to a fresh in-process hub + empty registry
    // so unit tests that assemble the router without bootstrap still work.
    let hub: Arc<dyn BroadcastHub> = App::make::<dyn BroadcastHub>()
        .unwrap_or_else(|| Arc::new(InMemoryBroadcastHub::new()));
    let registry: Arc<ChannelRegistry> = App::get::<Arc<ChannelRegistry>>()
        .unwrap_or_else(|| Arc::new(ChannelRegistry::new()));
    BroadcastingWsHandler::new(hub, registry)
}

routes! {
    ws!("/ws/broadcast", broadcasting_handler())
        .middleware(AuthMiddleware::new()),
}
```

Connect and observe:

```bash
wscat -c ws://localhost:3000/ws/broadcast
> {"action":"connected","socket_id":"6f1a3c2e-…"}
> {"action":"subscribe","channel":"order.updates","data":{}}
< {"action":"subscribed","channel":"order.updates"}
```

Dispatch from any controller, worker, or scheduled task:

```rust
EventFacade::dispatch(OrderPlaced { order_id: 99, user_id: 42 }).await?;
```

```
< {"action":"event","channel":"order.updates","event":"OrderPlaced","data":{"order_id":99,"user_id":42}}
```

## Channels

A channel is a named subscription target. Clients subscribe by name; the
hub delivers events to every active subscriber on that name. The `Channel`
trait has asymmetric defaults that fail closed on writes and open on
reads - see [Why Suprnova diverges](#why-suprnova-diverges) below.

### Public channels

The default. Any client may subscribe.

```rust
use async_trait::async_trait;
use suprnova::broadcasting::Channel;

pub struct OrderUpdates;

#[async_trait]
impl Channel for OrderUpdates {
    fn name(&self) -> &'static str { "order.updates" }
    // authorize() defaults to true - open to all subscribers.
}
```

### Private channels

Override `authorize` to gate subscriptions. A rejected subscribe
produces an `error` frame with `reason: "unauthorized"`; no
`subscribed` frame is sent.

```rust
use async_trait::async_trait;
use serde_json::Value;
use suprnova::broadcasting::{Channel, ChannelParams, PrivateChannel};
use suprnova::http::Request;

pub struct PrivateChat;

#[async_trait]
impl Channel for PrivateChat {
    fn name(&self) -> &'static str { "chat.private" }

    async fn authorize(
        &self,
        _req: &Request,
        _params: &ChannelParams,
        data: &Value,
    ) -> bool {
        data["token"].as_str().map(|t| t == "valid").unwrap_or(false)
    }
}

impl PrivateChannel for PrivateChat {}
```

`data` is whatever the client sent in the subscribe frame's `data`
field - a bearer token, a signed channel-bind, anything
application-defined. `Request` is the original HTTP upgrade request
(headers and cookies are readable directly). `params` carries the
captured values from a parameterized name and is empty for fixed
names.

`PrivateChannel` is a marker trait. The framework does not check for
it at runtime - it is a type-level signal that the channel overrides
`authorize` and is intended for future tooling (a clippy lint, an
audit pass).

### Parameterized channels

Embed `{param}` segments in `name()` and one registration serves every
concrete subscription that matches the pattern - the same model as
Laravel's `Broadcast::channel('orders.{id}', …)`. Captured values reach
every hook as a `ChannelParams` map.

```rust
use async_trait::async_trait;
use serde_json::Value;
use suprnova::broadcasting::{Channel, ChannelParams, PrivateChannel};
use suprnova::http::Request;

pub struct OrderChannel;

#[async_trait]
impl Channel for OrderChannel {
    fn name(&self) -> &'static str { "orders.{id}" }

    async fn authorize(
        &self,
        _req: &Request,
        params: &ChannelParams,
        _data: &Value,
    ) -> bool {
        let order_id = params.get("id").unwrap_or_default();
        // Gate on the captured id - does the session user own this order?
        !order_id.is_empty()
    }
}

impl PrivateChannel for OrderChannel {}

// One registration serves orders.42, orders.99, orders.featured, …
registry.register(OrderChannel);
```

Each `{param}` binds exactly one dot-segment: `orders.{id}` matches
`orders.42` but not `orders` or `orders.42.line`. Resolution prefers an
exact fixed-name registration over any pattern (`orders.featured`
beats `orders.{id}` for that one name), then the most specific
pattern (most literal segments), with the lexicographically smallest
pattern as a deterministic tie-break.

### Presence channels

Presence channels track membership. When a client subscribes, the hub
delivers a `presence.here` snapshot to that client and broadcasts
`presence.joined` to every other subscriber. When a client leaves,
the hub broadcasts `presence.left`.

The two-part contract is easy to half-implement: you must both
override `Channel::presence_info` to return `Some(self)` AND
implement `PresenceChannel::member_info`. Forgetting `presence_info`
wires the channel as non-presence - subscribes work, but
`presence.joined` / `presence.here` / `presence.left` never fire.

```rust
use async_trait::async_trait;
use serde_json::{json, Value};
use suprnova::FrameworkError;
use suprnova::broadcasting::{Channel, ChannelParams, PresenceChannel};
use suprnova::http::Request;

pub struct PresenceLobby;

#[async_trait]
impl Channel for PresenceLobby {
    fn name(&self) -> &'static str { "presence.lobby" }

    // Required - without this override, PresenceChannel is wired but inert.
    fn presence_info(&self) -> Option<&dyn PresenceChannel> {
        Some(self)
    }
}

#[async_trait]
impl PresenceChannel for PresenceLobby {
    async fn member_info(
        &self,
        _req: &Request,
        _params: &ChannelParams,
    ) -> Result<Value, FrameworkError> {
        // Return what other subscribers need to identify this member -
        // typically a user id. Never include secrets or private PII.
        Ok(json!({ "user_id": 42, "display_name": "Alice" }))
    }
}
```

See [Presence](#presence) for the full event flow and the self-join
echo.

### Reserved names

Names starting with `__` are reserved for framework meta-channels
(`__presence__` carries cross-process presence replication). Calling
`registry.register(channel)` on a `__`-prefixed name panics at
registration so the mistake is caught at boot, not at runtime.

### Why Suprnova diverges

Laravel binds channel authorization to a `$user` callback parameter
because PHP injects the current authenticated user implicitly.
Suprnova's `authorize` instead takes the raw `Request`, the captured
`ChannelParams`, and an arbitrary `data: Value` - three orthogonal
inputs, all available, with no implicit context. You read the session
cookie or bearer token from `Request` and the routing-style params
from `ChannelParams`; the `data` payload is a free slot for tokens
the client provides at subscribe time.

The `Channel` trait's defaults are **asymmetric on purpose**:
`authorize` defaults to `true` (subscribe is public by default),
`authorize_publish` defaults to `false` (client-initiated publish is
denied by default). The dangerous action fails closed; the safe one
fails open. When in doubt, leave both alone.

## The Broadcastable trait

`Broadcastable: Event + Serialize` - every `Broadcastable` is also an
`Event`. Dispatch via `EventFacade::dispatch(event)` runs every
in-process listener AND pushes the JSON-serialized payload to every
WebSocket subscriber on the channels the event names.

```rust
use serde::{Deserialize, Serialize};
use suprnova::Event;
use suprnova::broadcasting::Broadcastable;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OrderPlaced {
    pub order_id: i64,
    pub user_id: i64,
}

impl Event for OrderPlaced {
    fn event_name() -> &'static str { "OrderPlaced" }
}

impl Broadcastable for OrderPlaced {
    fn broadcast_on(&self) -> Vec<String> {
        // One event, multiple channels. Each subscriber on each channel
        // receives the same envelope.
        vec![
            format!("user.{}.orders", self.user_id),
            "orders.global".into(),
        ]
    }
}
```

Wire the bridge once per Broadcastable type at boot:

```rust
EventFacade::broadcast::<OrderPlaced>(Arc::clone(&hub)).await;
```

After that, `EventFacade::dispatch(event).await?` is the entire send
side - no separate `publish` call.

By default the event is serialized via `serde_json::to_value(&event)`
and pushed to every subscriber. Channels with zero subscribers are
silently skipped on the in-process hub; the cross-process hub still
publishes them so other processes get a chance to deliver.

Four optional methods refine the default:

**`broadcast_event_name(&self) -> &'static str`** - override the wire
event name. Defaults to `Self::event_name()`. Use to decouple the
in-process event identity from the over-the-wire name.

**`broadcast_with(&self) -> Option<Value>`** - return `Some(value)` to
push a curated payload instead of the full event serialization
(Laravel's `broadcastWith()`). Omit secrets or reshape for the client
without changing the event type:

```rust
impl Broadcastable for AccountFunded {
    fn broadcast_on(&self) -> Vec<String> {
        vec![format!("account.{}", self.account_id)]
    }
    fn broadcast_with(&self) -> Option<serde_json::Value> {
        // Never put the balance on the wire - only the public id.
        Some(serde_json::json!({ "account_id": self.account_id }))
    }
}
```

**`broadcast_when(&self) -> bool`** - return `false` to dispatch the
event to in-process listeners but skip the WebSocket push (Laravel's
`broadcastWhen()`). Only the broadcast is gated; the rest of the
event pipeline runs unchanged:

```rust
impl Broadcastable for DraftSaved {
    fn broadcast_on(&self) -> Vec<String> { vec![format!("doc.{}", self.doc_id)] }
    fn broadcast_when(&self) -> bool { self.publish } // only broadcast on publish
}
```

**`broadcast_to_others(&self) -> bool`** - return `true` to exclude
the connection that triggered the broadcast (Laravel's `toOthers()`).
The framework assigns each broadcasting connection a `socket_id` on
connect (sent in the `connected` frame); the browser echoes it back
as the `X-Socket-ID` header on HTTP requests; a `broadcast_to_others`
event dispatched while handling that request skips the originating
connection. Off-request (a worker or job) or when no `X-Socket-ID`
is present, it degrades to broadcasting to everyone:

```rust
impl Broadcastable for MessagePosted {
    fn broadcast_on(&self) -> Vec<String> { vec![format!("chat.{}", self.room)] }
    fn broadcast_to_others(&self) -> bool { true } // the sender already has it
}
```

This is a per-event-type choice. For per-dispatch exclusion, publish
directly:

```rust
use suprnova::broadcasting::BroadcastEnvelope;

hub.publish(
    BroadcastEnvelope::new(channel, event, data).with_except(socket_id),
).await?;
```

`LiveTopics::changed` captures the same `X-Socket-ID` and the sender's session
id before registering its after-commit callback. A sessionless request uses its
authenticated principal. Both stay attached through deferred publication and
fanout. Live excludes a document only when its instance and its session or
principal match. A forged header cannot suppress another user's signal.
`changed_with_tx` also awaits this identity capture before registering its
callback. Rollback discards the change.
Queue job attempts start without an inherited socket id and publish to every
authorized transport. See [Topic signals](live.md#topic-signals) for the
transaction and model registration examples.

### Dispatch ordering with sibling listeners

`EventFacade::dispatch` is **fail-fast**: if a hub publish returns
`Err` (e.g. a broker disconnect on a cross-process hub), the
`BroadcastListener` returns `Err` and any sibling listeners registered
**after** it do not run. Two ways to handle this:

- Register the broadcast bridge AFTER in-process listeners whose side
  effects (DB writes, log emission) must run regardless of broadcast
  outcome.
- Switch to `EventFacade::dispatch_best_effort(event)` when every
  listener must run regardless of one returning `Err`.

In-memory hubs never return `Err` - only the cross-process variant
surfaces broker failures.

## The wire protocol

Every message over the broadcasting route is a UTF-8 JSON frame. Two
shapes: `ClientFrame` (client → server) and `ServerFrame` (server →
client).

### Client frames

| `action` | Required fields | Optional fields | Meaning |
|----------|-----------------|-----------------|---------|
| `subscribe` | `channel` | `data` | Subscribe to `channel`. `data` is forwarded to `Channel::authorize`. |
| `unsubscribe` | `channel` | | Detach from `channel`. |
| `publish` | `channel`, `event`, `data` | | Push an event to every subscriber on `channel`. Gated by `Channel::authorize_publish` AND requires a live subscription. |

Client-initiated `publish` is gated by **two** checks: the connection
MUST hold an authorized subscription to the target channel, AND
`Channel::authorize_publish` must return `true` (it defaults to
`false`). This mirrors the Pusher client-event contract - channels
that want client publishes opt in explicitly by overriding the hook.
Most server-side broadcasting channels never want client-initiated
events, and the default-deny shape matches that intent.

```json
{"action":"subscribe","channel":"chat.42","data":{"token":"abc"}}
{"action":"unsubscribe","channel":"chat.42"}
{"action":"publish","channel":"chat.42","event":"MessagePosted","data":{"text":"hi"}}
```

### Server frames

| `action` | Fields | Meaning |
|----------|--------|---------|
| `connected` | `socket_id` | Sent once, first. Echo `socket_id` as the `X-Socket-ID` HTTP header so server-side `broadcast_to_others` can exclude this connection. |
| `subscribed` | `channel` | Subscription accepted. |
| `unsubscribed` | `channel` | Unsubscription confirmed. |
| `event` | `channel`, `event`, `data` | An event was broadcast on `channel`. |
| `lagged` | `channel`, `skipped` | The subscriber fell behind the server's per-channel ring buffer and `skipped` envelopes were dropped on this connection. Client local state on `channel` is stale; refetch before processing further events. |
| `error` | `channel` (nullable), `reason` | The last action failed. `channel` is `null` for envelope-level errors not tied to a channel. |

```json
{"action":"connected","socket_id":"6f1a3c2e-…"}
{"action":"subscribed","channel":"chat.42"}
{"action":"unsubscribed","channel":"chat.42"}
{"action":"event","channel":"chat.42","event":"MessagePosted","data":{"text":"hi"}}
{"action":"lagged","channel":"chat.42","skipped":42}
{"action":"error","channel":"chat.42","reason":"unauthorized"}
{"action":"error","channel":null,"reason":"malformed envelope: …"}
```

#### About `lagged`

Every channel has a per-process ring buffer (256 envelopes). A
subscriber that doesn't drain fast enough - a slow client, a stuck
forwarder - falls behind, and the buffer overwrites the oldest
events. When that happens, the server sends one `lagged` frame
naming the channel and the count of dropped events, then continues
delivering subsequent frames normally. The gap is **not** recoverable
from the server side; the client must refetch or resync before
processing further events on that channel. Silently dropping events
would let bugs hide as "we lost a tick" rather than "the client's
state diverged from the server's".

#### Publish failures

When a client-initiated `publish` is accepted by `authorize_publish`
but the hub publish itself fails (broker disconnect on the
cross-process hub), the originating client receives an `error` frame
with `reason: "publish failed: …"` so it knows the event didn't
reach other processes. Other subscribers are not notified.

### Example session

```
S → C  {"action":"connected","socket_id":"6f1a3c2e-…"}
C → S  {"action":"subscribe","channel":"order.updates","data":{}}
S → C  {"action":"subscribed","channel":"order.updates"}

# Server dispatches OrderPlaced:
S → C  {"action":"event","channel":"order.updates","event":"OrderPlaced","data":{"order_id":99,"user_id":42}}

C → S  {"action":"subscribe","channel":"chat.private","data":{"token":"bad"}}
S → C  {"action":"error","channel":"chat.private","reason":"unauthorized"}

C → S  {"action":"unsubscribe","channel":"order.updates"}
S → C  {"action":"unsubscribed","channel":"order.updates"}
```

## Per-route middleware

Broadcasting routes support the same `.middleware(M)` chaining as plain
WebSocket routes:

```rust
ws!("/ws/broadcast", broadcasting_handler())
    .middleware(AuthMiddleware::new()),
```

A non-2xx response from any middleware short-circuits the upgrade -
the client receives the HTTP error response and no WebSocket
handshake happens. This is the right place to enforce transport-level
auth (session validity, origin checks, rate limits at connection
time) without duplicating the check inside every channel's
`authorize`.

Multiple middleware compose left-to-right:

```rust
ws!("/ws/broadcast", broadcasting_handler())
    .middleware(AuthMiddleware::new())
    .middleware(RateLimitMiddleware::connections_per_ip(100)),
```

`RateLimitMiddleware::connections_per_ip(100)` allows each client address 100 open connections on the route and answers the next upgrade with `429 Too Many Requests`. A connection counts until its session ends. The counts are per process, and an IPv6 address counts with its /64 network. See [Rate Limiting](rate-limiting.md#capping-open-connections-with-connections_per_ip).

The split is intentional: **transport-level** (who may open the
connection at all) lives in middleware; **channel-level** (who may
subscribe to which channel) lives in `Channel::authorize`.

### Per-route `WsConfig`

Override the process-wide WebSocket defaults per route. Chain
`.config(WsConfig { ... })` after the handler - before or after
`.middleware(M)` (order doesn't matter):

```rust
use std::time::Duration;
use suprnova::ws::WsConfig;

ws!("/ws/chat", broadcasting_handler())
    .config(WsConfig {
        ping_interval: Duration::from_secs(5),
        max_missed_pings: 1,
        ..Default::default()
    })
    .middleware(AuthMiddleware::new())
```

The five configurable fields and where each one matters:

| Field | Default | Use case |
|-------|---------|----------|
| `ping_interval` | 30s | Chat / presence: shorten to 5-10s to detect dead mobile connections quickly. Bulk-data streaming: lengthen to reduce overhead. |
| `max_missed_pings` | 2 | Set to `1` for chat where one missed Pong should close immediately. Set to `3+` for flaky mobile networks. Set to `usize::MAX` to disable close-on-no-pong. |
| `max_message_size` | 1 MiB | Public-endpoint-safe default. Start from `WsConfig::generous()` (64 MiB) for trusted internal feeds. |
| `max_frame_size` | 64 KiB | Sized for chat / notification frames with headroom. Start from `WsConfig::generous()` (16 MiB) for large unfragmented frames. |
| `origin_policy` | `SameOrigin` | Defaults reject cross-origin upgrades - the only CSRF protection a browser WS handshake has. Use `AllowList(vec![...])` for explicit cross-origin frontends, or `AllowAny` only for non-browser endpoints. |

When no `.config(...)` is provided, the route inherits
`WsConfig::default()`. Explicit per-route config always wins over the
default.

For routes serving trusted internal feeds (server-to-server fanout,
large binary transfers), start from the trusted-feed factory and
adjust as needed:

```rust
use suprnova::ws::WsConfig;
use std::time::Duration;

ws!("/ws/internal/firehose", FirehoseHandler::new())
    .config(WsConfig {
        ping_interval: Duration::from_secs(10),
        ..WsConfig::generous() // 64 MiB message / 16 MiB frame
    })
```

## Presence

When a client successfully subscribes to a presence channel the hub:

1. Calls `PresenceChannel::member_info` with the upgrade `Request` and
   the captured `ChannelParams` to collect the joining member's data.
2. Sends a `presence.here` event frame to the new subscriber with
   `data: { "members": [...] }` - a snapshot of all currently tracked
   members (excluding the newly joining one).
3. Publishes a `presence.joined` event with `data: <member_info>` to
   the channel. Every subscriber - including the new one via its own
   forwarder - receives it; clients filter the self-join by comparing
   the joining member's identity to their own.

When a subscriber disconnects or sends an unsubscribe frame, or its
connection is cancelled (the server aborts WebSocket connections that
outlast its shutdown drain):

4. The hub publishes a `presence.left` event with the departing
   member's data. Every remaining subscriber receives it.

All three frames arrive as `event` action frames with reserved
`event` names:

```json
{"action":"event","channel":"presence.lobby","event":"presence.here","data":{"members":[{"user_id":1},{"user_id":2}]}}
{"action":"event","channel":"presence.lobby","event":"presence.joined","data":{"user_id":3}}
{"action":"event","channel":"presence.lobby","event":"presence.left","data":{"user_id":3}}
```

Across processes, presence state is replicated via the reserved
`__presence__` meta-channel (see [Cross-process
fanout](#cross-process-fanout)). Track and untrack operations on any
process propagate to all subscribers; `list_members` returns the
merged view (local + remote). Dead processes whose `untrack_member`
never fired have their members pruned via TTL - default 60 s.

## Cross-process fanout

The default `InMemoryBroadcastHub` fans out only to subscribers on the
current process. For multi-replica deployments, enable the
`broadcasting-fanout` Cargo feature and swap in
`SeaStreamerBroadcastHub`:

`Cargo.toml`:

```toml
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", features = ["broadcasting-fanout"] }
```

`src/bootstrap.rs`:

```rust
use std::sync::Arc;
use suprnova::broadcasting::{BroadcastHub, ChannelRegistry};
use suprnova::broadcasting::fanout::SeaStreamerBroadcastHub;
use suprnova::container::App;

pub async fn register() {
    let hub: Arc<dyn BroadcastHub> = Arc::new(
        SeaStreamerBroadcastHub::new(
            "redis://broker:6379",   // streamer URI (backend chosen from scheme)
            "suprnova-broadcast",    // stream key (shared by every process in the cluster)
        )
        .await
        .expect("connect"),
    );
    App::bind::<dyn BroadcastHub>(Arc::clone(&hub));
    // ... rest of bootstrap unchanged
}
```

The constructor takes two arguments: the stream URI (selects the
backend by scheme) and the stream key (the stream name shared by every
process in the cluster: at most 249 ASCII letters, digits, `.`, `_` or
`-`). Use the same stream key on every replica or they won't see each
other's events.

`new_with_presence_ttl(uri, key, ttl)` overrides the default 60 s
presence TTL - useful for tests that need to exercise the
crash-recovery path quickly. `new_loopback(uri, key)` and
`new_loopback_with_presence_ttl` behave as `new` and
`new_with_presence_ttl`: every backend feeds a hub's own events back to
it, and the duplicate guard ensures each app event still delivers
exactly once locally.

### Backends

The backend is selected from the URI scheme:

| URI scheme | Backend | Production-ready | Notes |
|------------|---------|------------------|-------|
| `redis://`, `rediss://` | Redis Streams | **Yes** | `rediss://` uses TLS. The URL's `user:password@` and `/db` apply to every connection the hub opens, as they do for the queue's Redis driver. |
| `memory://` | An in-process stream | No - tests only | Connects the hubs of one process that name the same stream key. `stdio://` is accepted as an alias. |

A hub reads the stream from the entry that was last when it connected:
an event published after the constructor returns always reaches it, and
nothing published before is replayed. Entries carry the event in the
field `msg`, as they did when the hub went through sea-streamer, so
replicas of an earlier version on the same stream keep working during
a rolling deploy.

### Architecture

Each `publish(envelope)` does two things in parallel:

1. **Local fanout** - the inner `InMemoryBroadcastHub` delivers to
   subscribers on this process immediately. Local subscribers never
   wait on the network.
2. **Stream write** - the same envelope is serialized and appended to
   the stream (`XADD`) so every other process's consumer pump reads it
   (`XREAD`) and delivers it locally.

A duplicate-delivery guard prevents seeing each app-data event twice:
the hub instance has a random UUID, every envelope it produces carries
that UUID, and the consumer pump skips inbound envelopes whose
instance id matches the local hub's own. Presence meta-channel
messages are an exception - each hub needs its own events in the
cross-process view so the read path is unified.

Writes go through one writer task per hub, in the order they were
made, and each `publish` waits up to 5 s for its write to land. A write
whose caller stopped waiting is dropped instead of being written late.

### Inertia Live topic signals

[Live topic signals](live.md#topic-signals) use the same hub so an island and
an Inertia page see one ordered change stream. `BroadcastHub` exposes
topic operations in addition to application event fanout:

- `subscribe_live_topic(topic)` opens the typed signal feed.
- `live_topic_cursor(topic)` reads the current monotonic position.
- `live_topic_positions(topics)` reads generations and cursors together for
  every binding before the page loader runs. The cursor-only helpers remain
  available for callers that do not render a baseline.
- `publish_live_topic(topic, props, except, interval)` advances that position
  and publishes the change.

`except` is a `LiveTopicExclusion` with a document instance and the sender
identity. This routing metadata stays inside the trusted hub. The browser
receives a data-free Live payload:

```json
{
  "kind": "topic_change",
  "topic": "posts",
  "cursor": 42,
  "generation": 1792688181000,
  "props": ["posts", "post_count"]
}
```

There is no serialized model in the message. The receiver reloads the named
props from its ordinary authorized controller or fresh-renders its island.
An empty `props` array requests a full refresh for that binding.

The hub keeps the cursor and minimum spacing global for each topic. The
default `LIVE_TOPIC_SIGNAL_INTERVAL_MS=100` permits at most 10 signals per
second for one topic across the hub, not 10 from each publisher. Changes that
arrive inside the interval are held and their prop names are unioned; an empty
list dominates the union. Configure the same value in code with
`LiveConfig::builder().topic_signal_interval_ms(100)`.

`SeaStreamerBroadcastHub` stores the cursor and pending coalesced change in
Redis, so replicas share the ordering and rate bound. Its `memory://` backend
shares them between hubs with the same stream key inside one process for
tests. If the application binds no hub, Live uses `InMemoryBroadcastHub` and
topic signals reach this process only. A custom hub that keeps the trait's
default topic methods reports that topic fanout is unsupported instead of
silently acting as a process-local hub.

Family instances use the configured `LIVE_TOPIC_INSTANCE_RETENTION_SECS`
window, which defaults to 86400 seconds. Redis expires idle instance hashes;
its idle cursor/rate metadata uses that TTL. Publications and baseline reads
renew it. Pending work, its prop set and its schedule have no TTL. A pending
signal pins the authority hash until XADD succeeds; flush then restores the
idle TTL. If the pending hash is missing, the schedule retains enough routing
data to publish a full invalidation with the current generation and cursor.
Membership heartbeats keep a connected instance alive. In-memory hubs prune
only eligible idle instances through one shared sweep per second. Static topics
do not expire.
A generation identifies one lifetime of a topic instance's authority state.
Generations are unique and increasing within an authority and unique across
in-process restarts; across process restarts they differ except with negligible
probability. Memory uses a process-wide high-water mark and a random process
nonce, so clock reuse or rollback cannot repeat an in-process allocation.
Redis allocates from a persistent hub-wide counter in the script that creates
the hash. Clients compare generations for inequality only. See [Topic signals](live.md#topic-signals) for configuration
and cursor resets.

Topic traffic uses a reserved internal channel that ordinary `publish` calls
cannot spoof. The hub envelope's `except` socket id is preserved across
fanout. A write made by an Inertia visit can therefore skip the transport that
initiated it while other tabs and replicas receive the signal.

### Why Suprnova diverges

Laravel broadcasting does not own an Inertia invalidation cursor. Suprnova
stores that cursor beside the hub's topic publications so replicas agree on
the position and the rate bound. The signal still contains no model data.

### Cross-process presence

`SeaStreamerBroadcastHub` replicates presence state across processes
automatically. Each instance has a UUID `instance_id` at
construction; `track_member` / `untrack_member` publish
`PresenceEvent`s to the reserved `__presence__` meta-channel. Every
process maintains a `cross_process_view` updated by its consumer
task; `list_members` returns the merged view (local and remote
uniformly).

Liveness: each process re-publishes its members every `ttl / 6` (10 s
at the default 60 s TTL) as a heartbeat. Stale entries - members
whose `last_seen` exceeds the TTL - get pruned every `ttl / 2`. This
handles process crashes that didn't get to publish
`MemberRemoved`.

## Close-on-no-pong

Broadcasting routes participate in the same WebSocket heartbeat as
plain `ws!` routes. The framework sends a Ping every
`WsConfig::ping_interval` (default 30 s). If a connection fails to
respond with a Pong within `max_missed_pings` consecutive intervals
(default 2), the framework closes with code 1011.

```rust
use std::time::Duration;
use suprnova::ws::WsConfig;

let config = WsConfig {
    ping_interval: Duration::from_secs(15),
    max_missed_pings: 3,
    ..WsConfig::default()
};
```

Lowering `ping_interval` detects dead connections faster at the cost
of higher baseline traffic. `max_missed_pings: 1` closes after the
very first missed Pong - use this only when network glitches are
rare and you want the fastest possible dead-connection cleanup.
`max_missed_pings: usize::MAX` disables close-on-no-pong entirely.

## Production deployment

Broadcasting routes are upgraded HTTP connections on the same hyper
listener as your HTTP routes. TLS termination happens upstream,
exactly as described in [the WebSocket
chapter](websockets.md#production-deployment). The nginx and Caddy
configurations from that chapter apply unchanged - extend them to
cover the `/ws/broadcast` path.

Active WebSocket handler tasks (including broadcasting connections)
are tracked by the server and drained on
graceful shutdown, so in-flight event deliveries complete before the
process exits.

## Pusher, Soketi and Reverb

`PusherBroadcastHub` publishes your broadcasts through a Pusher-protocol
service: Pusher Channels, Soketi, or Laravel Reverb. Browsers then
subscribe with Laravel Echo and pusher-js instead of the JSON envelope
protocol above. Every publish still reaches the in-process hub first, so
a `ws!` broadcasting route in the same process keeps receiving events.

### Configure the connection

`PusherConfig::from_env()` reads the variables Laravel uses:

| Variable | Default | Meaning |
|---|---|---|
| `PUSHER_APP_ID` | required | The app id. |
| `PUSHER_APP_KEY` | required | The public app key. |
| `PUSHER_APP_SECRET` | required | The app secret. It signs every request. |
| `PUSHER_HOST` | unset | A self-hosted server (Soketi, Reverb). Unset means Pusher Channels. |
| `PUSHER_PORT` | 443 for `https`, 80 for `http` | The self-hosted server's port. |
| `PUSHER_SCHEME` | `https` | `http` or `https`, for a self-hosted server. |
| `PUSHER_APP_CLUSTER` | `mt1` | The Pusher Channels cluster. |
| `PUSHER_ENCRYPTION_MASTER_KEY_BASE64` | unset | 32 bytes, base64. Needed for encrypted channels. |
| `PUSHER_TIMEOUT_SECS` | 5 | How long one REST call may take. |

An optional variable that is set but empty counts as unset, as in
Laravel's `.env.example`. A missing required variable or an invalid value
is an error that names the variable and never quotes the value. For
Reverb's variable names, call `PusherConfig::from_env_prefix("REVERB")`,
which reads `REVERB_APP_ID`, `REVERB_HOST`, and so on. To build the
configuration in code, use `PusherConfig::new(app_id, key, secret)` and
its `host`, `port`, `scheme`, `cluster`, `timeout`, and
`encryption_master_key_base64` methods.

`PusherBroadcastHub::new` checks every value before the first publish:
the app id, key, and cluster must be letters, digits, `_`, or `-`; the
host must be a plain hostname or IP address, with no scheme, port, or
path; the secret must not be empty; and the timeout must be greater
than zero. A bad value fails at boot with an error that names the
field.

### Bind the hub

The hub and the authorization endpoints share one channel registry, so
they always agree on a channel's Pusher name:

```rust
use std::sync::Arc;
use suprnova::broadcasting::{BroadcastHub, ChannelRegistry};
use suprnova::container::App;
use suprnova::events::EventFacade;
use suprnova::{PusherBroadcastHub, PusherConfig};

pub async fn register() {
    let mut registry = ChannelRegistry::new();
    registry.register(OrderChannel);
    let registry = Arc::new(registry);
    App::singleton(Arc::clone(&registry));

    let config = PusherConfig::from_env().expect("PUSHER_* configuration");
    let hub = PusherBroadcastHub::new(config, Arc::clone(&registry)).expect("Pusher hub");

    // The authorization endpoints resolve this from the container.
    App::singleton(hub.auth());

    let hub: Arc<dyn BroadcastHub> = Arc::new(hub);
    App::bind::<dyn BroadcastHub>(Arc::clone(&hub));
    EventFacade::broadcast::<OrderShipped>(Arc::clone(&hub)).await;
}
```

`publish` returns an error when the service answers with a non-2xx
status or cannot be reached. The error names the status and up to 200
bytes of the answer, never the secret or the request signature.

### Query the service

The in-process hub knows only the members of this process. To ask the
service itself, which sees every connection to it, use the hub's
`PusherClient`, or build one with `PusherClient::new(config, registry)`.
It is the client Laravel's `Broadcast::pusher($config)` and
`PusherBroadcaster::getPusher` return:

```rust
use suprnova::{FrameworkError, PusherBroadcastHub};
use suprnova::broadcasting::BroadcastEnvelope;

async fn who_is_in_the_room(hub: &PusherBroadcastHub) -> Result<(), FrameworkError> {
    let client = hub.client();

    // GET /apps/{app_id}/channels/presence-room/users
    let user_ids: Vec<String> = client.presence_users("room").await?;

    // GET /apps/{app_id}/channels?filter_by_prefix=presence-&info=user_count
    let occupied = client.channels(Some("presence-"), &["user_count"]).await?;

    // GET /apps/{app_id}/channels/private-orders.42?info=subscription_count
    let order = client.channel("orders.42", &["subscription_count"]).await?;

    // One POST /apps/{app_id}/batch_events for both events.
    client
        .trigger_batch(&[
            BroadcastEnvelope::new("orders.42", "OrderShipped", serde_json::json!({ "id": 42 })),
            BroadcastEnvelope::new("news", "Posted", serde_json::json!({})),
        ])
        .await?;

    // POST /apps/{app_id}/users/42/terminate_connections
    client.terminate_user_connections("42").await?;

    // Any other signed GET, relative to /apps/{app_id}.
    let answer = client.get("/channels", &[("filter_by_prefix", "private-")]).await?;
    println!("{user_ids:?} {occupied} {order} {answer}");
    Ok(())
}
```

The client sends channel names through the registry's wire mapping, so
`presence_users("room")` asks about `presence-room` when the registry
holds `room` as a presence channel, and refuses a channel the registry
does not hold as one. `channels` sends its prefix as given, since a
prefix is a wire prefix and not a channel name. `channels`, `channel`,
and `get` return the service's JSON answer.

Every request carries Pusher's signature, with `body_md5` only for a
request that has a body. An error names the status and up to 200 bytes
of the answer, never the secret or a signature. `trigger_batch`
publishes to the service only, not to the in-process hub. Pusher
Channels takes at most 10 events per batch and answers a larger batch
with an error, which `trigger_batch` returns.

The hub's own `list_members` keeps answering from the in-process hub.
The endpoints come from Pusher's HTTP API documentation, which every
Pusher-protocol server follows.

### Mount the authorization routes

Echo asks your server to sign every private, presence, and encrypted
subscription. Mount the two endpoints where `SessionMiddleware` and
`CsrfMiddleware` run (the scaffold installs both globally), so the
endpoints see the logged-in user and refuse cross-site requests:

```rust
use suprnova::{post, pusher_channel_auth, pusher_user_auth, routes};

routes! {
    post!("/broadcasting/auth", pusher_channel_auth),
    post!("/broadcasting/user-auth", pusher_user_auth),
}
```

`pusher_channel_auth` resolves the channel in the registry and calls its
`authorize` with the other request fields as `data`. It answers:

- `200` with `auth`, plus `shared_secret` for an encrypted channel or
  `channel_data` for a presence channel.
- `403` with `{}` for a public name, an unknown channel, a name whose
  prefix does not match the channel's visibility, a name the driver
  refuses (see [Channel visibility](#channel-visibility)), a refused
  `authorize`, or a presence channel without a logged-in user.
- `422` when `socket_id` or `channel_name` is malformed.
- `500` when `PusherAuth` is not bound, when an encrypted channel is
  requested without a master key, or when `member_info` fails.

A presence member's `user_id` is the route's user, and its `user_info`
is the channel's `member_info`. `pusher_user_auth` signs `{"id": <the
route's user>}` for pusher-js user authentication and answers `403` for
a guest. The route's user is the user of the guard the last
`AuthMiddleware` checked: the bare id for the default guard, as
`Auth::id()` reports it, and `<guard>:<id>` behind
`AuthMiddleware::for_guard(..)` naming another guard. A default-guard id
that holds a `:` gets a leading `:`, so web user `admin:9` is `:admin:9`
and never admin `9`. A user of another guard in the same session never
stands in for it.

### Connect with Laravel Echo

```js
import Echo from 'laravel-echo';
import Pusher from 'pusher-js/with-encryption';

window.Pusher = Pusher;

const token = document
  .querySelector('meta[name="csrf-token"]')
  ?.getAttribute('content') ?? '';

const echo = new Echo({
  broadcaster: 'pusher',
  key: import.meta.env.VITE_PUSHER_APP_KEY,
  cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER ?? 'mt1',
  wsHost: import.meta.env.VITE_PUSHER_HOST
    ? import.meta.env.VITE_PUSHER_HOST
    : `ws-${import.meta.env.VITE_PUSHER_APP_CLUSTER}.pusher.com`,
  wsPort: import.meta.env.VITE_PUSHER_PORT ?? 80,
  wssPort: import.meta.env.VITE_PUSHER_PORT ?? 443,
  forceTLS: (import.meta.env.VITE_PUSHER_SCHEME ?? 'https') === 'https',
  enabledTransports: ['ws', 'wss'],
  authEndpoint: '/broadcasting/auth',
  auth: { headers: { 'X-CSRF-TOKEN': token } },
  userAuthentication: {
    endpoint: '/broadcasting/user-auth',
    headers: { 'X-CSRF-TOKEN': token },
  },
});

// Suprnova sends the bare event name, so listen with a leading dot.
echo.private('orders.42').listen('.OrderShipped', (event) => {
  console.log(event.order_id);
});
```

The connection options follow Laravel's own Echo stub, so one
configuration serves Pusher Channels, Soketi, and Reverb. Expose the
server values to Vite in `.env`, for example
`VITE_PUSHER_HOST="${PUSHER_HOST}"`, and the same for the key, cluster,
port, and scheme. With `VITE_PUSHER_HOST` unset, Echo connects to Pusher
Channels in your cluster. With it set, Echo connects to your Soketi or
Reverb server on `VITE_PUSHER_PORT`. Keep the `cluster` value in both
cases, as Laravel's stub does: pusher-js refuses options without one.

The token is read once, when Echo is created. A login or a logout rotates it (see [CSRF](csrf.md)), so
create the Echo instance again after either one. The plain
`pusher-js` build works too if you use no encrypted channels.

### Channel visibility

The in-process hub authorizes every subscribe through `authorize`. A
Pusher service decides by the channel's name instead, and a public
Pusher channel never reaches your server at all. `Channel::visibility`
chooses that name:

| Channel | Pusher name | Echo call |
|---|---|---|
| `presence_info()` returns `Some` | `presence-{name}` | `echo.join(name)` |
| `ChannelVisibility::Private` (the default) | `private-{name}` | `echo.private(name)` |
| `ChannelVisibility::Public` | `{name}` | `echo.channel(name)` |
| `ChannelVisibility::Encrypted` | `private-encrypted-{name}` | `echo.encryptedPrivate(name)` |

`Private` is the default so the driver fails closed: a channel whose
`authorize` restricts subscribers can never leak through a public Pusher
channel. Return `Public` only when anyone may read the channel, because
Pusher clients subscribe to it with no authorization at all and
`authorize` is never consulted:

```rust
use async_trait::async_trait;
use suprnova::broadcasting::{Channel, ChannelVisibility};

pub struct Announcements;

#[async_trait]
impl Channel for Announcements {
    fn name(&self) -> &'static str { "announcements" }

    fn visibility(&self) -> ChannelVisibility {
        ChannelVisibility::Public
    }
}
```

A presence channel is always `presence-`, whatever `visibility` returns.
The one exception is `Encrypted`: Pusher has no encrypted presence
channels, so the driver refuses a presence channel that returns it
instead of sending its events as plaintext.

Each Pusher name must belong to exactly one channel, so the driver also
refuses a name that would read as a different channel:

- A `Public` channel whose name starts with `private-` or `presence-`.
- A `Private` channel, or an unregistered name, that starts with
  `encrypted-`. It would read as the encrypted channel without that
  prefix, and authorizing that channel would hand out the key to its
  events.

The rule applies to the concrete name, so a pattern such as
`{slug}.orders` is refused for a slug that starts with `encrypted-`.
Publishing to a refused name returns an error after the in-process
delivery, and the authorization endpoint answers `403`.

### Encrypted channels

An `Encrypted` channel is end-to-end encrypted: the hub encrypts each
event's data with a key derived from the channel name and
`PUSHER_ENCRYPTION_MASTER_KEY_BASE64`, and the Pusher service only
relays ciphertext. The authorization answer carries that channel's
`shared_secret`, which pusher-js uses to decrypt. Generate a master key
with `openssl rand -base64 32`.

Publishing to an encrypted channel without a master key is an error. The
hub never falls back to sending plaintext. For the same reason, a
presence channel cannot be encrypted.

### Why Suprnova diverges

Laravel picks private or public per event: `broadcastOn()` returns a
`PrivateChannel` or a `Channel`, so one event can publish a channel's
data under a public name by mistake. Suprnova decides per channel,
through `Channel::visibility`, and the default is private. Every event on
a channel uses the same Pusher name, and a restricted channel cannot
leak through a public one.

## Broadcast notifications

A notification that lists `"broadcast"` in its channels reaches the hub
through the `BroadcastChannel`. The notification's `to_broadcast()`
message can send the publish through the queue with `on_queue` or
`on_connection`, and every delivery dispatches a
`BroadcastNotificationCreated` event. For the details, see
[Notifications](notifications.md#broadcast).

## Testing broadcasts

`RecordingBroadcastHub` is the Suprnova analogue of Laravel's
`Broadcast::fake()` - a `BroadcastHub` that records every published
envelope while still delivering to live subscribers. Bind it in
place of `InMemoryBroadcastHub` in a test and assert what was
broadcast without subscribing first:

```rust
use std::sync::Arc;
use suprnova::broadcasting::{BroadcastHub, RecordingBroadcastHub};
use suprnova::container::App;

#[tokio::test]
async fn shipping_an_order_broadcasts_to_the_user_channel() {
    let hub = Arc::new(RecordingBroadcastHub::new());
    App::bind::<dyn BroadcastHub>(Arc::clone(&hub) as Arc<dyn BroadcastHub>);

    // ... run code that publishes (directly, or via a dispatched Broadcastable) ...

    hub.assert_broadcast("orders.42", "OrderShipped");
    assert_eq!(hub.count(), 1);
}
```

| Helper                         | Asserts                                                  |
|--------------------------------|----------------------------------------------------------|
| `assert_broadcast(ch, ev)`     | at least one envelope on `ch` with event name `ev`       |
| `assert_nothing_broadcast()`   | nothing was published                                    |
| `broadcasts()`                 | `Vec<BroadcastEnvelope>` - every recorded envelope       |
| `count()`                      | total envelopes recorded                                 |

To assert that a `Broadcastable` *event* was dispatched at all
(rather than what reached the wire), `EventFacade::fake()` records
the event itself - see [Events](events.md#testing---eventfacadefake).

## Laravel parity reference

| Laravel | Suprnova |
|---------|----------|
| `Broadcast::channel('name', fn(...))` | `Channel` trait impl + `registry.register(...)` |
| `Broadcast::channel('orders.{id}', ...)` | `fn name() -> "orders.{id}"`, params in `ChannelParams` |
| `PrivateChannel` (interface) | `PrivateChannel` marker trait + override `authorize` |
| `PresenceChannel` (interface) | `PresenceChannel` + override `Channel::presence_info` |
| `ShouldBroadcast` (interface) | `Broadcastable` trait |
| `broadcastOn()` | `broadcast_on(&self) -> Vec<String>` |
| `broadcastAs()` | `broadcast_event_name(&self) -> &'static str` |
| `broadcastWith()` | `broadcast_with(&self) -> Option<Value>` |
| `broadcastWhen()` | `broadcast_when(&self) -> bool` |
| `toOthers()` | `broadcast_to_others(&self) -> bool` |
| `Broadcast::fake()` | `RecordingBroadcastHub` bound as `dyn BroadcastHub` |
| `assertBroadcasted` | `RecordingBroadcastHub::assert_broadcast(channel, event)` |
| Pusher / Reverb driver | `PusherBroadcastHub` (Pusher Channels, Soketi, Reverb); see [Pusher, Soketi and Reverb](#pusher-soketi-and-reverb) |
| `Broadcast::pusher($config)`, `PusherBroadcaster::getPusher()` | `PusherClient::new(config, registry)`, `PusherBroadcastHub::client()`; see [Query the service](#query-the-service) |
| `BroadcastNotificationCreated` | `suprnova::BroadcastNotificationCreated`; see [Broadcast notifications](#broadcast-notifications) |
| Ably driver | none; `InMemoryBroadcastHub` (single-process) or `SeaStreamerBroadcastHub` (cross-process over Redis Streams) |
| `/broadcasting/auth` | `pusher_channel_auth` and `pusher_user_auth`, mounted by hand |
| Echo client library | Laravel Echo with the `pusher` broadcaster against `PusherBroadcastHub`; for the in-process hub, wire the JSON envelope protocol from the browser by hand |

## Reference

| Symbol | Purpose |
|--------|---------|
| `suprnova::broadcasting::Channel` | Channel trait. Override `name()` (required), `authorize`, `authorize_publish`, `presence_info`. |
| `suprnova::broadcasting::ChannelParams` | Captured values from a parameterized `name()`. `get(key) -> Option<&str>`. Empty for fixed names. |
| `suprnova::broadcasting::PrivateChannel` | Marker trait on a `Channel` that overrides `authorize`. No required methods. |
| `suprnova::broadcasting::PresenceChannel` | `async fn member_info(req, params) -> Result<Value, FrameworkError>`. Requires `Channel::presence_info` override. |
| `suprnova::broadcasting::ChannelRegistry` | Holds every registered channel. Bound as `Arc<ChannelRegistry>` in the container; resolved by `BroadcastingWsHandler`. |
| `suprnova::broadcasting::Broadcastable` | Trait on `Event + Serialize`. Required: `broadcast_on()`. Optional: `broadcast_event_name`, `broadcast_with`, `broadcast_when`, `broadcast_to_others`. |
| `suprnova::broadcasting::BroadcastHub` | Hub trait. `subscribe`, `publish`, `subscriber_count`, presence track/untrack/list, and Live topic subscribe/cursor/publish. |
| `suprnova::broadcasting::InMemoryBroadcastHub` | Default in-process hub. No external dependencies. Ordinary publish rejects reserved framework channels. |
| `suprnova::broadcasting::RecordingBroadcastHub` | Test double. Records every publish; still delivers to live subscribers. |
| `suprnova::broadcasting::BroadcastEnvelope` | One published event: `channel`, `event`, `data`, `except`. `new(ch, ev, data)` builder; `.with_except(socket_id)` for per-dispatch exclusion. |
| `suprnova::broadcasting::LiveTopicSignal` | Data-free topic change: `topic`, `generation`, its `cursor`, and the prop names to refresh. |
| `suprnova::broadcasting::ClientFrame` / `ServerFrame` | The JSON-envelope wire types. `ServerFrame::Lagged { channel, skipped }` surfaces per-channel ring-buffer overflows. |
| `suprnova::broadcasting::BroadcastingWsHandler` | The framework's reusable `WebSocketHandler`. Constructor: `BroadcastingWsHandler::new(hub, registry)`. Pass to `ws!()`. |
| `suprnova::PusherBroadcastHub` | Pusher-protocol hub. `new(config, registry)`; `auth()` returns the `PusherAuth` to bind; `client()` returns its `PusherClient`. Also delivers to in-process subscribers. |
| `suprnova::PusherClient` | Pusher HTTP API client. `new(config, registry)`, `channels(prefix, info)`, `channel(name, info)`, `presence_users(name)`, `trigger_batch(envelopes)`, `terminate_user_connections(user_id)`, `get(path, params)`. |
| `suprnova::PusherConfig` / `PusherScheme` | Pusher connection settings. `from_env()`, `from_env_prefix(prefix)`, `new(app_id, key, secret)` plus builder methods. `Debug` redacts the secret and master key. |
| `suprnova::PusherAuth` | The signing state the authorization endpoints resolve from the container. |
| `suprnova::pusher_channel_auth` / `pusher_user_auth` | Echo's channel authorization and user authentication endpoints. |
| `suprnova::ChannelVisibility` | `Public`, `Private` (default), or `Encrypted`: a channel's name on a Pusher service. Returned by `Channel::visibility`. |
| `suprnova::broadcasting::fanout::SeaStreamerBroadcastHub` | Cross-process hub behind `broadcasting-fanout`. `new(uri, stream_key)`, `new_with_presence_ttl(uri, key, ttl)`, `new_loopback(uri, key)`. |
| `EventFacade::broadcast::<E>(hub)` | Register the event → hub bridge for `E`. Call once per `Broadcastable` at boot. |
| `EventFacade::dispatch(event)` | Fires in-process listeners AND publishes to the hub on every channel `E::broadcast_on()` returns. |
| `WsRouteDef::config(WsConfig)` | Per-route WS config override. Composes with `.middleware(M)` in either order. |
| `WsRouteDef::middleware(M)` | Per-route middleware chain. A non-2xx response short-circuits the upgrade. |
| `WsConfig::generous()` | Trusted-feed factory: 64 MiB message / 16 MiB frame, other fields unchanged. Do NOT use on public routes. |

## Next

- [WebSockets](websockets.md) - the underlying primitive, `WsSocket`, `OriginPolicy`
- [Events](events.md) - `EventFacade`, fail-fast vs best-effort dispatch
- [Server-Sent Events](sse.md) - one-way push without an Upgrade handshake
- [Notifications](notifications.md) - the `BroadcastChannel` notification driver
- [Web Push](web-push.md) - server-pushed notifications to offline users


---

<!-- /docs/cache -->

# Cache

Suprnova ships a Laravel-shape `Cache` facade backed by one of three
drivers - in-memory, Redis or MongoDB - picked explicitly at boot via
`CACHE_DRIVER`. The facade is a thin layer over a `CacheStore` trait, so
custom backends plug in the same way the built-ins do.

## The facade

```rust
use suprnova::Cache;
use std::time::Duration;

Cache::put("user:1", &user, Some(Duration::from_secs(3600))).await?;

let cached: Option<User> = Cache::get("user:1").await?;

if Cache::has("user:1").await? {
    // hit
}

Cache::forget("user:1").await?;
```

Every method serialises through `serde_json` at the facade boundary, so
any `T: Serialize + DeserializeOwned` round-trips. The trait under the
facade (`CacheStore`) only sees opaque JSON strings.

## Bootstrap

The cache is bound during `Server::run()`'s driver-bootstrap step (see
[Request Lifecycle](lifecycle.md)). `Cache::bootstrap` reads the
configured `CacheConfig` (or constructs one from env) and dispatches on
`CacheConfig::driver`:

- `Memory` - bind an `InMemoryCache` with the configured prefix and
  default TTL. Always succeeds.
- `Redis` - build a `RedisCache` on the [Redis](redis.md) facade's
  `cache` connection (or the one `REDIS_CACHE_CONNECTION` names) and bind
  it. The store sends one command while it is built, so the boot **fails
  closed** if that connection cannot answer. There is no silent downgrade
  to memory.
- `MongoDb` - with the `database-mongodb` feature, build a `MongoCache` on
  the default MongoDB connection and bind it. The boot fails when no
  MongoDB connection is registered. See [MongoDB: Cache](mongodb.md#cache).

Workers (`queue:work`, `schedule:run`, `workflow:work`) go through the
same bootstrap, so a job using `Cache::get` sees the same backend the
HTTP handler does.

### Why Suprnova diverges

Laravel's `cache.php` config picks a default store and Laravel will
quietly swap to `array` (in-process) when a misconfigured backend fails
in some code paths. That's a productive default for `php artisan tinker`
and a footgun in production - a single Redis miss silently changes the
guarantees of every tag flush and lock acquisition in the app.

Suprnova picks the opposite default. `CACHE_DRIVER=memory` is explicit
(and the default for `cargo run`), and `CACHE_DRIVER=redis` against an
unreachable Redis returns an error from `Server::from_config`. The
binary exits non-zero with a remediation message; supervisord/systemd
sees a boot failure instead of a half-working app.

## Configuration

| Env | Meaning | Default |
|---|---|---|
| `CACHE_DRIVER` | `memory`, `redis` or `mongodb` | `memory` |
| `CACHE_PREFIX` | Key prefix applied to every store operation | the slug of `APP_NAME`, then `-cache-` (`suprnova-cache-` without `APP_NAME`) |
| `REDIS_CACHE_CONNECTION` | The Redis connection the store's commands run on | `cache` |
| `REDIS_CACHE_LOCK_CONNECTION` | The Redis connection the store's locks run on | `default` |
| `CACHE_DEFAULT_TTL` | Default TTL in seconds for `Cache::put`, `Cache::remember`, and `Cache::tags_put` called with `None`; `0` means no default | `3600` |
| `CACHE_SWEEP_INTERVAL` | Seconds between sweeps of the in-memory cache's expired entries; `0` turns the sweep off | `60` |

Unset `CACHE_DRIVER` parses to `Memory`; any other value (case-
insensitive, trimmed) that isn't `memory`/`in-memory`/`inmemory`/`redis`/
`mongodb` returns an error at boot, and so does `mongodb` in a build without
the `database-mongodb` feature.

The Redis server, its database and the connection's own key prefix come
from the [Redis](redis.md) connections: `REDIS_URL`, `REDIS_CACHE_DB` for
the `cache` connection (database 1 unless you set it, even when
`REDIS_URL` names another), and `REDIS_PREFIX`.

You can also build the config programmatically when you don't want env
parsing:

```rust
use suprnova::{Config, CacheConfig, cache::CacheDriver};

Config::register(
    CacheConfig::builder()
        .driver(CacheDriver::Redis)
        .connection("cache")
        .lock_connection("default")
        .prefix("myapp:")
        .default_ttl(7200)
        .build(),
);
```

`CacheConfigBuilder::build` is deterministic - unset fields fall back
to `CacheConfig::default()` rather than re-reading env.

### The `forever` contract holds across backends

`Cache::forever`, `Cache::remember_forever` (and its alias `Cache::sear`),
and `Cache::tags_forever` bypass `CACHE_DEFAULT_TTL` entirely; the value
never expires regardless of the configured default.
`Cache::put(key, value, None)`, `Cache::remember(key, None, ..)`, and
`Cache::tags_put(tags, key, value, None)` do apply the default - that's the
point of having one.

The default-TTL resolution happens at the facade layer. Both `CacheStore`
backends honour `None` literally at the store boundary (no expiration),
which is why `forever` actually means forever on both memory and Redis.

## Reads, writes, deletes

```rust
use suprnova::Cache;
use std::time::Duration;

// Write with an explicit TTL
Cache::put("session:42", &session, Some(Duration::from_secs(1800))).await?;

// Write forever - bypasses CACHE_DEFAULT_TTL
Cache::forever("config:features", &features).await?;

// Read (None on miss or expired)
let session: Option<Session> = Cache::get("session:42").await?;

// Existence - true means present and not expired
if Cache::has("session:42").await? { /* … */ }

// Laravel-spelled negation
if Cache::missing("session:42").await? { /* warm */ }

// Read-and-delete in one call
let one_shot: Option<String> = Cache::pull("notice:welcome:42").await?;

// Returns true if the key existed and was removed
Cache::forget("session:42").await?;

// Wipe everything (prefix-scoped on both backends)
Cache::flush().await?;
```

On Redis, `flush` deletes the keys that start with the connection's
`REDIS_PREFIX` followed by `CACHE_PREFIX`, matched literally: a prefix with
glob characters such as `*`, `?`, or `[` matches only itself, and a key
under the connection prefix alone survives. When both prefixes are empty
the pattern matches every key in the connection's database, so `flush`
then empties the whole database.

`Cache::pull` is **not** atomic - it's a `get` followed by a `forget`,
same shape as Laravel's `Repository::pull`. For atomic dequeue use
`Cache::lock` (see below).

### Refresh a TTL without rewriting

```rust
let refreshed = Cache::touch("session:42", Duration::from_secs(1800)).await?;
```

`touch` returns `true` if the key existed and the TTL was extended,
`false` otherwise. The stored value is untouched, and so are its tags: a
touched tagged value is still removed by `flush_tags` after its original TTL
would have run out.

## Add - write-if-absent (atomic)

```rust
let won = Cache::add(
    "daily:winner",
    &user_id,
    Some(Duration::from_secs(86_400)),
).await?;
if won {
    send_winner_email(user_id).await?;
}
```

`Cache::add` writes only if the key is empty (or has expired). Returns
`true` on write, `false` on contention. **Atomic** on both built-in
backends:

- `InMemoryCache` holds a write-lock across the existence check + insert
- `RedisCache` uses `SET key value NX EX ttl` (or `NX` without `EX`)

Custom `CacheStore` implementations that don't override `add_raw` fall
back to a non-atomic check-then-put, matching Laravel's
`Repository::add` fallback for stores without a native `add`.

## Remember - get-or-compute

```rust
let user = Cache::remember(
    "user:1",
    Some(Duration::from_secs(3600)),
    || async { User::find(1).await },
).await?;

let cfg = Cache::remember_forever("config:app", || async {
    load_config_from_db().await
}).await?;
```

`remember` calls your closure only on miss, then stores the result. The
closure returns `Result<T, FrameworkError>`, so domain failures bubble
through `?` rather than poisoning the cache.

`Cache::sear(key, default)` is the Laravel-spelled alias for
`remember_forever`. Same body, same semantics - ships under both names
so migrated code reads the same way.

When the value knows how long it is good for, compute the lifetime from
it with `Cache::remember_with_ttl`, as Laravel's `remember` takes a
closure for its lifetime:

```rust
let token: Token = Cache::remember_with_ttl(
    "api:token",
    |token: &Token| Some(Duration::from_secs(token.expires_in)),
    || async { fetch_token().await },
).await?;
```

The lifetime closure runs only on a miss, after the value is computed.
`None` stores the value for `CACHE_DEFAULT_TTL`, as `remember`'s `None`
does, and `Some(Duration::ZERO)` returns the value without storing it.

### Remember is NOT stampede-safe

`remember` is a non-atomic `get`-then-`put` pair. N concurrent misses
for the same cold key run the closure N times and write N results. That
matches Laravel's `Repository::remember` exactly, and it's fine for the
common case (the closure is idempotent, the writes are identical).

It is not fine when:

- The closure is expensive (1s+ to compute or hits a slow upstream)
- The key is popular enough that a cold-cache event sends N requests at
  once at the backing store
- The closure has side effects beyond computing the value

For those, wrap with `Cache::lock`:

```rust
use suprnova::Cache;
use std::time::Duration;

let key = "rebuild:user:1";

if let Some(guard) = Cache::lock(key, Duration::from_secs(10)).await? {
    let user = Cache::remember(
        "user:1",
        Some(Duration::from_secs(3600)),
        || async { User::find(1).await },
    ).await?;
    guard.release().await?;
    return Ok(user);
}

// Lost the race - the winner is computing. Read whatever they wrote,
// or fall back to a stale value.
let user = Cache::get::<User>("user:1").await?
    .ok_or_else(|| FrameworkError::internal("cache miss after losing rebuild lock"))?;
```

## Locks

`Cache::lock` returns a `LockGuard` holding the ownership token. Locks
are advisory and cross-process when backed by Redis.

```rust
use suprnova::Cache;
use std::time::Duration;

if let Some(guard) = Cache::lock("job:42", Duration::from_secs(30)).await? {
    do_exclusive_work().await?;
    guard.release().await?;
}
// Some(guard) means we own it. None means another holder beat us.
```

The guard exposes:

| Method | Use for |
|---|---|
| `guard.token()` | Read the ownership token (Rust-side name) |
| `guard.owner()` | Same value, Laravel-spelled alias |
| `guard.refresh(ttl)` | Extend the TTL - returns `false` if we no longer own the lock |
| `guard.release()` | Release if we still own the lock - returns `false` if the token no longer matches |

There is intentionally **no `Drop` auto-release**. A Redis lock must be
acknowledged across process boundaries; auto-release on drop would
either silently steal a stolen lock back (wrong) or hide release
failures in destructor panics (worse). The release is explicit so
errors propagate.

`refresh` lets a long-running job extend its own lock to avoid a
self-inflicted timeout - see [Idempotency](idempotency.md) for the
in-tree consumer.

## Atomic counters

```rust
// Initialises to 0 if absent, then increments. Returns the new value.
let visits = Cache::increment("page:visits", 1).await?;

// Same shape for negative steps
let remaining = Cache::decrement("quota:remaining", 1).await?;

// Custom amount
let total = Cache::increment("stats:downloads", 10).await?;
```

Atomic on both built-in backends: `InMemoryCache` uses a write-locked
`HashMap::entry`; `RedisCache` uses `INCRBY`/`DECRBY`. The stored value
is a JSON-encoded integer, so `Cache::get::<i64>("page:visits")` round-
trips with the same key.

```rust
use suprnova::cache::ConditionalIncrement;

// Counts only while the counter is below 100; a full counter is left alone.
match Cache::increment_if_below("seats:taken", 1, 100).await? {
    ConditionalIncrement::Incremented(taken) => { /* seat number `taken` is yours */ }
    ConditionalIncrement::Unchanged(_) => { /* sold out, and nothing was counted */ }
}
```

`Cache::increment_if_below` adds to a counter only while it is below a
ceiling, reading a missing key as 0, so a caller can be refused without
being counted. The comparison and the write are one atomic step on both
built-in backends, under the write lock in `InMemoryCache` and in one
`EVAL` in `RedisCache`, so concurrent callers stepping by 1 never take the
counter past the ceiling; the [throttle middleware](rate-limiting.md#refused-requests)
counts with it. A custom `CacheStore` that doesn't override
`increment_if_below` gets a default that reads and then increments, which
isn't atomic; override it with your backend's atomic primitive.

## Tagged cache

Tags let you invalidate a whole family of related entries with one
call. The classic use case is per-resource caches that have to flush
together when the resource changes.

```rust
use suprnova::Cache;
use std::time::Duration;

// Store under one or more tags
Cache::tags_put(
    &["users", "user:1"],
    "user:1:profile",
    &profile,
    Some(Duration::from_secs(3600)),
).await?;

Cache::tags_put(
    &["users", "user:1"],
    "user:1:posts",
    &posts,
    Some(Duration::from_secs(600)),
).await?;

// Update path: drop every key tagged `user:1`
Cache::flush_tags(&["user:1"]).await?;
```

`tags_put` with a `None` TTL applies `CACHE_DEFAULT_TTL`, like `put`. To
store a tagged value that never expires, use `Cache::tags_forever`:

```rust
Cache::tags_forever(&["settings"], "settings:site", &settings).await?;
```

Tag membership is **per-entry**: each tagged write installs that
write's tag set as the entry's source of truth, replacing any prior
tags. Two consequences worth knowing:

- An untagged `Cache::put` over a previously tagged key **clears** the
  entry's tags. A subsequent `flush_tags` of the old tag will not
  delete the live untagged value.
- Overwriting `tags_put(&["a"], …)` with `tags_put(&["b"], …)` makes
  the entry respond only to `flush_tags(&["b"])`.

A tag's index of keys drops entries that can no longer be reached, so it
doesn't grow without bound for a tag that is written often but rarely
flushed. Flushing one tag removes the deleted keys from the indexes of their
other tags too. On the in-memory backend the periodic sweep removes expired
keys from the indexes. On Redis every tagged write checks a sample of the
tag's index and removes keys that expired, were forgotten, or were
overwritten without the tag, and `flush()` clears every index.

## Hit and miss events

`Cache::get` dispatches `CacheHit` when the key holds a value and
`CacheMissed` when it holds nothing, as Laravel's `Repository::get` does.
`Cache::has`, `Cache::missing` and every read built on them (`pull`,
`remember`, `remember_forever`, `sear`) dispatch the same, once per read.
Each event carries the store's name (`memory`, `redis`) and the key you
passed; `CacheHit` also carries the stored value when the read fetched it,
and `None` for `has` and `missing`, which only check presence. A stored
JSON `null` is a value: it is present, and its read is a hit.

```rust
use std::sync::Arc;
use suprnova::{CacheHit, EventFacade, FrameworkError, Listener};

struct TraceHits;

#[suprnova::async_trait]
impl Listener<CacheHit> for TraceHits {
    async fn handle(&self, event: &CacheHit) -> Result<(), FrameworkError> {
        tracing::debug!(store = %event.store, key = %event.key, "cache hit");
        Ok(())
    }
}

EventFacade::listen::<CacheHit, _>(Arc::new(TraceHits)).await;
```

A listener that fails is logged, and the read still answers. When no
listener and no events fake is installed the read builds no event. The
`Debug` output of a `CacheHit` leaves the value out, since a cached value
can be a token or a user's data.

## Redis connections

The Redis store runs on the [Redis](redis.md) facade's named connections,
as Laravel's `createRedisDriver` builds its store: its commands on the
`cache` connection, which reads `REDIS_CACHE_DB`, and its locks on the
`default` connection. `REDIS_CACHE_CONNECTION` and
`REDIS_CACHE_LOCK_CONNECTION` name others, or set them in code with
`CacheConfigBuilder::connection` and `lock_connection`.

Every key the store writes is the connection's `REDIS_PREFIX`, then
`CACHE_PREFIX`, then your key. With `APP_NAME=Shop`, `REDIS_PREFIX=shop-`
and `CACHE_PREFIX` unset, `Cache::put("k", ..)` writes `shop-shop-cache-k`.

`Cache::set_connection` moves the bound store's later commands to another
connection, as Laravel's `Cache::setConnection`; its locks stay where they
are. A store with no Redis connection, such as the memory store, answers an
error.

```rust
use suprnova::{Cache, Redis};

// In the bootstrap.
Redis::define("reports", "redis://127.0.0.1:6379/5")?;

// Later writes and reads go to database 5.
Cache::set_connection("reports")?;
Cache::put("report:today", &totals, None).await?;
```

`RedisCache::connect(&config)` still builds a store on `config.url` by
hand, with `config.prefix` as its whole key prefix. The bootstrap uses
`RedisCache::connect_named(&config)`, which builds it on the named
connections.

### Upgrading keeps the old keys only if you ask

Before this release the Redis store opened its own connection from
`REDIS_URL` and used `REDIS_PREFIX`, `suprnova_cache:` by default, as its
cache prefix. It now runs on the `cache` connection's database
(`REDIS_CACHE_DB`, 1 by default) under the new prefixes, so an upgraded
deployment finds its Redis cache empty. That is safe for a cache, which
refills as it is read. To keep the old keys, set:

```dotenv
REDIS_CACHE_CONNECTION=default
REDIS_PREFIX=
CACHE_PREFIX=suprnova_cache:
```

`REDIS_CACHE_CONNECTION=default` keeps the database `REDIS_URL` names, the
empty `REDIS_PREFIX` drops the connection prefix, and `CACHE_PREFIX` puts
back the old prefix (use the value you had in `REDIS_PREFIX`, if you set
one).

## Three backends

| Feature | `InMemoryCache` | `RedisCache` | `MongoCache` |
|---|---|---|---|
| Shared across processes | No | Yes | Yes |
| Persistence | No | Yes, if Redis is configured for it | Yes |
| Atomic `add` | Yes (write-lock) | Yes (`SET NX`) | Yes (an upsert that collides with a live entry) |
| Atomic `increment`/`decrement` | Yes (write-lock) | Yes (`INCRBY`/`DECRBY`) | Yes (`$inc` in one `findOneAndUpdate`) |
| Tagged cache | Yes | Yes | Yes (a tags array on the entry) |
| Locks | Yes | Yes (cross-process) | Yes (cross-process, `cache_locks`) |
| Sub-second TTL | Yes (`tokio::time::Instant`) | Yes (`PX`/`PEXPIRE`) | Yes (millisecond `expires_at`, TTL index) |
| Selected via | `CACHE_DRIVER=memory` (default) | `CACHE_DRIVER=redis` | `CACHE_DRIVER=mongodb` |

There is no SQL database cache driver - the three backends above are the
ones the framework ships. `MongoCache` needs the `database-mongodb`
feature; see [MongoDB: Cache](mongodb.md#cache). Custom backends can implement `CacheStore`
and bind into the container directly; see the test-injection pattern
below.

### In-memory expiration

`InMemoryCache` evicts expired entries **lazily on read**: `get_raw`,
`has`, and `add_raw` purge an entry the first time they observe it
expired. Re-accessed keys never accumulate corpses.

A key that expires and is never read again has no such trigger, so the
cache the framework binds also **sweeps**: every `CACHE_SWEEP_INTERVAL`
seconds, 60 unless you set it, it removes every expired entry. `0`
turns the sweep off. The sweep runs on a task that holds the cache
weakly and ends with it.

A cache you build yourself is swept only if you build it to be. Build it
inside the runtime, in your bootstrap for instance, since the sweep is a
task on it:

```rust
use std::time::Duration;
use suprnova::{CacheConfig, InMemoryCache};

let cache = InMemoryCache::with_periodic_sweep(&CacheConfig::default(), Duration::from_secs(30));
```

`InMemoryCache::new()` is not swept; call `purge_expired()`, which
returns the count of entries removed, when you want one. Redis handles
its own expiration server-side; the equivalent isn't needed there.

A `dyn CacheStore` that your bootstrap binds is kept: the framework's
boot binds its own store only when none is bound.

### Redis TTL precision

Every Redis TTL goes through `PX` / `PEXPIRE`, not `EX` / `EXPIRE`.
That avoids two pitfalls:

- Sub-second `Duration`s would truncate to `0 seconds` under `EX`,
  which Redis rejects (`SET … EX 0`) or, worse, interprets as
  "delete the key" (`EXPIRE key 0`).
- `Duration::ZERO` is clamped to 1 ms before the call, so neither
  rejection path is reachable from user code.

### Transient command retries

A dropped socket used to fail whatever `Cache::get` happened to be in flight.
The Redis connection manager reconnects on its own, but the command that hit
the dead socket still returns its error to you.

Read-shaped commands now retry once: `GET`, `EXISTS`, and the `SCAN` / `SSCAN`
pages behind `Cache::flush` and `Cache::flush_tags`. The queue driver's `XLEN`,
`ZCARD`, and `XPENDING` reads and the rate limiter's `Retry-After` computation
retry the same way. Set `REDIS_COMMAND_RETRIES` to add further retries on top
of the built-in one.

Budget the retry in seconds, not in the 50 ms pause that precedes it. Once a
connection has dropped, the next attempt waits for the replacement connection
before it can send anything, so it pays the driver's whole connect budget and
then its response timeout:

- The cache driver allows up to 3 connect retries, at most 500 ms apart, each
  capped by a 2 s connect timeout, with a 5 s response timeout.
- The queue and rate-limit drivers take the redis-rs defaults: up to 6 connect
  retries with an uncapped exponential delay starting at 100 ms, each capped by
  a 1 s connect timeout, with a 500 ms response timeout.

`REDIS_COMMAND_RETRIES` is clamped at 10, and that clamp bounds attempts, not
seconds: at the maximum a single read makes 12 attempts, which against a down
Redis is tens of seconds to minutes on one call. A timed-out command counts as
transient as well as a dropped one, so a merely slow Redis makes every wrapped
read issue up to that many commands rather than one. Raise the setting only
where the caller can afford to wait.

Writes never retry, at any setting. A transient error means the connection
failed, not that the server declined the command - the server may already have
run it - so retrying a `SET`, an `INCR`, a lock acquisition, a rate-limit hit,
or a queue pop risks a second execution. Those commands surface the failure to
you, and your retry decision is the informed one.

### Why Suprnova diverges

Laravel's `command_retries` config raises the retry budget for every Redis
command, because its `command()` method is a single choke point that knows
which command it is running and consults a 60-entry read-only allowlist.
Suprnova's drivers call typed commands directly, so the allowlist becomes a
per-call-site decision, and `REDIS_COMMAND_RETRIES` can only deepen the retries
for commands that are already safe to repeat. There is no setting that makes a
queue pop retry.

## Testing

Bind an `InMemoryCache` into the `TestContainer` and the facade
resolves it like any other store:

```rust
use std::sync::Arc;
use suprnova::{Cache, CacheStore, InMemoryCache};
use suprnova::container::testing::TestContainer;

#[tokio::test]
async fn cache_round_trips() {
    let _guard = TestContainer::fake();
    TestContainer::bind::<dyn CacheStore>(Arc::new(InMemoryCache::new()));

    Cache::put("k", &"v", None).await.unwrap();

    let v: Option<String> = Cache::get("k").await.unwrap();
    assert_eq!(v.as_deref(), Some("v"));
}
```

`TestContainer::bind` writes to the thread-local scope, so parallel
tests do not leak cache state into each other. See the
[Service Container](container.md) chapter for the three-layer lookup
model.

### Live-Redis suites

The framework's own Redis tests are `#[ignore]`d, so `cargo test` never needs a
server. Run them with `-- --ignored` and point them at an instance:

- `cache_redis_integration` reads `CACHE_REDIS_TEST_URL`, falling back to
  `REDIS_URL` and then to `redis://127.0.0.1:6379`. Every test scopes itself to
  a unique key prefix, so it is safe against a shared development Redis.
- `cache_redis_retry` covers the transient-command retry and requires
  `CACHE_REDIS_TEST_URL` explicitly, with no fallback. It issues
  `CLIENT KILL TYPE normal`, which disconnects every other client on the
  instance, so it must be given a throwaway server. With the variable unset it
  prints a skip line and passes without connecting.

## Patterns

A few recurring shapes worth naming:

```rust
// Hierarchical, colon-separated keys - same convention Laravel uses
Cache::put("users:1:profile", &profile, None).await?;
Cache::put("posts:123:comments:count", &count, None).await?;

// TTL by data volatility
Cache::put("stats:active", &count, Some(Duration::from_secs(60))).await?;
Cache::put("config:features", &features, Some(Duration::from_secs(3600))).await?;
Cache::forever("translations:en", &translations).await?;

// Cache-by-tag invalidation around a write
async fn update_user(id: i64, data: UserUpdate) -> Result<User, FrameworkError> {
    let user = User::update(id, data).await?;
    Cache::flush_tags(&[&format!("user:{}", id)]).await?;
    Ok(user)
}
```

## Next

- [Configuration](configuration.md) - how `Config::register` and env
  vars combine
- [Rate Limiting](rate-limiting.md) - the Laravel-shape `RateLimiter`
  facade is built on top of `Cache`
- [Idempotency](idempotency.md) - the request-dedupe middleware uses
  `Cache::lock` end-to-end
- [Service Container](container.md) - how `CacheStore` is bound and
  resolved
- [Error Model](error-model.md) - what `Cache::*` returns when Redis
  is unreachable mid-request


---

<!-- /docs/concurrency -->

# Concurrency

The `Concurrency` facade runs several slow tasks that don't depend on one
another at the same time, and gives you their results. It is Laravel's
`Concurrency` facade with tasks in place of closures, and Tokio tasks as
the default driver.

```rust
use suprnova::concurrency::Task;
use suprnova::{Concurrency, DB, FrameworkError, concurrent_task};

#[concurrent_task]
async fn count_rows(table: String) -> Result<u64, FrameworkError> {
    DB::table(table).count().await
}

let results = Concurrency::run([
    Task::new::<CountRows>("users".to_owned()),
    Task::new::<CountRows>("orders".to_owned()),
])
.await?;

let users: u64 = results[0].get()?;
let orders: u64 = results[1].get()?;
```

## Define a task

A task is an `async fn` marked `#[concurrent_task]`. It takes one input
and returns `Result<T, FrameworkError>`. Both the input and the output are
serde types, because the process driver sends them to another process. A
task without a parameter takes `()`:

```rust
use serde::{Deserialize, Serialize};
use suprnova::{FrameworkError, concurrent_task};

#[derive(Serialize, Deserialize)]
pub struct Export {
    pub account_id: u64,
    pub format: String,
}

#[concurrent_task]
pub async fn build_export(input: Export) -> Result<String, FrameworkError> {
    // ...
    Ok(format!("exports/{}.{}", input.account_id, input.format))
}

#[concurrent_task]
pub async fn warm_caches() -> Result<(), FrameworkError> {
    // ...
    Ok(())
}
```

The function stays as you wrote it, so you can still call it directly.
The macro adds a unit struct named after the function in UpperCamelCase,
`BuildExport` and `WarmCaches` here. You pass that struct to `Task::new`,
and the compiler checks the input against the function's parameter:

```rust
use suprnova::concurrency::Task;

let task = Task::new::<BuildExport>(Export {
    account_id: 7,
    format: "csv".to_owned(),
});
```

The macro also registers the task at compile time under a name: the
function's module path and name, such as `app::exports::build_export`. The
process driver sends that name to the console binary, which finds the same
function in its own registry. Two attributes change the defaults:

| Attribute | Effect |
|---|---|
| `name = "exports:build"` | registers the task under this name instead |
| `type_name = "ExportTask"` | names the struct this instead, when the UpperCamelCase name is taken, for example by the input type |

`Task::named(name, input)` builds a task from its registered name, for a
task that only the console binary links. Nothing checks its input until the
task runs. A name can't be empty or contain a control character, such as a
line break or a tab: `Task::named` keeps a refused name as an error that
fails the task when it runs, and `Task::try_named(name, input)` returns
that error at once.

## Run tasks

`Concurrency::run` takes the tasks, runs them at the same time, and returns
a `Vec<TaskResult>` in the order you gave the tasks, whatever order they
finish in. `TaskResult::get::<T>()` decodes a result as the task's output
type:

```rust
let results = Concurrency::run([
    Task::new::<BuildExport>(csv),
    Task::new::<WarmCaches>(()),
])
.await?;

let path: String = results[0].get()?;
```

Every task runs to its end before `run` returns, even when one of them
fails. `run` then returns the first failed task's error, in the order of
the tasks. A task that panics is an error that names it.

### Named results

`Concurrency::run_named` takes `(key, task)` pairs and returns an
`IndexMap<String, TaskResult>` with each result under its key, in the order
you gave them:

```rust
let results = Concurrency::run_named([
    ("users", Task::new::<CountRows>("users".to_owned())),
    ("orders", Task::new::<CountRows>("orders".to_owned())),
])
.await?;

let users: u64 = results["users"].get()?;
```

A key that names two tasks is an error, and no task runs.

### Task timeouts

`Concurrency::with_timeout` ends a task that runs longer than the duration
you give it. The task's error is a `FrameworkError::Timeout` that names
the task, so `error.is_timeout()` tells it from a failure of the task
itself:

```rust
use std::time::Duration;

let results = Concurrency::with_timeout(Duration::from_secs(30))
    .run([Task::new::<BuildExport>(csv)])
    .await?;
```

A zero duration means no timeout. Without a timeout, a task runs until it
finishes, on every driver.

## Drivers

A driver decides where the tasks run. Three drivers are built in:

| Driver | Runs each task | Use it for |
|---|---|---|
| `tokio` (default) | as a Tokio task in this process | most work: it's the cheapest |
| `process` | in a console process of its own | work that needs isolation: its own memory, and a timeout that kills it |
| `sync` | one after another, in the caller's task | tests that want concurrency out of the way |

`CONCURRENCY_DRIVER` names the default driver, and `tokio` is the default
when the variable is unset or empty. The variable is read on each call. To
pick a driver for one call, use `Concurrency::driver`:

```rust
let results = Concurrency::driver("process")
    .with_timeout(Duration::from_secs(60))
    .run([Task::new::<BuildExport>(csv)])
    .await?;
```

A name that no driver has is an error that names it.

On every driver, the input and output pass through JSON, the in-process
drivers included. A task that works under `sync` in a test then works
under `process` in production.

### The tokio driver

The `tokio` driver spawns each task on the runtime and waits for them all.
The tasks share the caller's container scope, so a scoped binding the
request resolved is the one the task sees. A timeout ends a task at its next
`.await`; a task that blocks its thread runs on until it yields.

### The process driver

The `process` driver starts the console binary once for each task, through
the [`Process` facade](processes.md), as Laravel starts an `artisan` process
for each closure. The binary runs the hidden `concurrency:run` command with
the task's name, reads the input as JSON from its standard input, runs the
task, and writes the outcome to its standard output. The command is
registered by the framework, so every console binary has it, and it stays
out of the console's help. The outcome line carries a random token that the
driver generates for each run, so text your application logs to standard
output can't pass for a task's result.

The driver starts the first of these that exists:

1. The command you set with `Concurrency::console_binary(path)`, or
   `Concurrency::console_command([program, args...])` for a console that
   another program starts.
2. The `console` binary in the same directory as the running executable.
   A Suprnova project builds `app` and `console` side by side, so the server
   finds its console there.
3. The running executable, which is right when the console binary itself
   runs the tasks.

```rust
use suprnova::Concurrency;

// In bootstrap::register(), when the image keeps the console elsewhere.
Concurrency::console_binary("/srv/app/bin/console")?;

// In development, through Cargo.
Concurrency::console_command(["cargo", "run", "--quiet", "--bin", "console", "--"])?;
```

A timeout kills the console process and every process it started. Both
binaries must register the task under the same name, which they do when the
task is in the application's library crate. A name that the console binary
doesn't register is an error that names the task. Starting a process costs
far more than spawning a Tokio task, so use this driver for heavy or risky
work, not for small queries.

### Your own driver

A driver implements `ConcurrencyDriver`, one method that runs the tasks
and returns one outcome for each, in order. `Task::run_in_process` runs a
task in this process, `Task::name` and `Task::input` give what a remote
worker needs, and `concurrency::timed_out` builds the timeout error.
Register the driver with `Concurrency::extend`:

```rust
use std::time::Duration;
use suprnova::concurrency::{Task, TaskResult};
use suprnova::{Concurrency, ConcurrencyDriver, FrameworkError, async_trait};

struct InlineDriver;

#[async_trait]
impl ConcurrencyDriver for InlineDriver {
    async fn run(
        &self,
        tasks: Vec<Task>,
        _timeout: Option<Duration>,
    ) -> Vec<Result<TaskResult, FrameworkError>> {
        let mut outcomes = Vec::new();
        for task in tasks {
            outcomes.push(task.run_in_process().await);
        }
        outcomes
    }
}

Concurrency::extend("inline", InlineDriver)?;
```

A driver added under `tokio`, `process`, or `sync` replaces the built-in
one.

## Defer tasks

`Concurrency::defer` runs tasks after the response has been sent, and
discards their results. Use it for work the user doesn't wait for, such
as reporting metrics:

```rust
use suprnova::concurrency::Task;
use suprnova::{Concurrency, HttpResponse, Request, Response};

async fn checkout(_request: Request) -> Response {
    // ...
    Concurrency::defer([
        Task::new::<ReportMetric>("checkout".to_owned()),
        Task::new::<WarmCaches>(()),
    ])
    .map_err(HttpResponse::from)?;

    Ok(HttpResponse::text("ordered"))
}
```

Inside a request, `defer` returns at once. The tasks start on the selected
driver after the response's last bytes have been written and flushed,
through the same mechanism as
[`Bus::dispatch_after_response`](bus.md). A task that fails is logged with
its name and error, and the response, already sent, isn't changed. `defer`
returns an error only when the driver doesn't exist.

Outside a request, in a console command or a worker, there is no response
to wait for. `defer` returns a `DeferredTasks` handle: awaiting it runs the
tasks and waits for them, and dropping it starts them on the runtime. A
process that ends right after the drop can end before the tasks finish, so
await the handle at the end of a console command:

```rust
Concurrency::defer([Task::new::<WarmCaches>(())])?.await;
```

In every request the framework serves, the in-memory test client
included, the tasks run after the response. A request with no response
writer in reach, such as one from the test client or a custom Hyper loop
that doesn't use `after_response_connection`, starts them when the
response's body ends instead of after its bytes flush. Only outside a
request does the handle run the tasks when you await it or drop it.
`DeferredTasks::after_response()` tells you which path the tasks took: it
returns `true` inside a request and `false` outside one.

## Testing

Set `CONCURRENCY_DRIVER=sync` in the test environment, or call
`Concurrency::driver("sync")`, to run tasks one after another in the test's
own task. The input and output still pass through JSON, so a task that
can't cross a process boundary fails in the test as well.

A test that uses the process driver needs a console binary that registers
its tasks. `Process::fake()` fakes the driver's console processes as it
fakes every other process.

A faked console process answers the way a real one does. The outcome is one
line on standard output: `suprnova-concurrency-result:`, the run's token, a
colon and `{"ok":<value>}` or `{"error":"<message>"}`, and the process exits
with code 0 for a success. The driver gives each console process its own
token in `SUPRNOVA_CONCURRENCY_TOKEN` and takes no outcome line without it,
so a fixed `Process::result(..)` can't answer a task. A closure reads the
token from the pending process:

```rust
use suprnova::{PendingProcess, Process};

fake.when("*concurrency:run*", |pending: &PendingProcess| {
    let token = pending
        .environment()
        .iter()
        .find(|(key, _)| key.as_str() == "SUPRNOVA_CONCURRENCY_TOKEN")
        .and_then(|(_, value)| value.clone())
        .unwrap_or_default();
    Process::result(format!("suprnova-concurrency-result:{token}:{{\"ok\":42}}\n"))
});
```

Most tests don't need the fake: the `sync` driver runs the task itself.

### Why Suprnova diverges

- **A task is a registered function, not a closure.** Laravel serializes
  closures with `laravel/serializable-closure`. A Rust closure can't be
  serialized, so a task is an `async fn` registered by name with serde input
  and output, and the console binary finds it by that name.
- **Tokio tasks are the default driver.** Laravel defaults to `process`
  because PHP has no threads in a request. Tokio runs tasks side by side in
  one process, so `process` is the driver you pick for isolation.
- **There is no `fork` driver.** The `process` driver is the isolating one.
- **A timeout applies on every driver, and there is none by default.**
  Laravel's timeout applies only to the `process` driver, and a process
  there gets the Process facade's 60-second default when you set none.
- **Named results come from `run_named`.** Laravel's `run` returns keys
  when you pass an associative array. Rust has no such array, so keyed
  tasks go through their own method, and a repeated key is an error.
- **Deferred tasks run without a request.** Laravel's `defer` waits for the
  end of the request or the command. Outside a request, the handle runs the
  tasks when you await it or drop it.

## Next

- [Processes](processes.md) - running other programs, which the process driver uses
- [Queues](queues.md) - running work in the background, with retries
- [Command Bus](bus.md) - dispatching a command after the response


---

<!-- /docs/data -->

# Data Objects

Suprnova's `#[derive(Data)]` lets you describe an inbound request shape, an outbound response shape, and a TypeScript export in **one struct**.

## Quick start

```rust
use suprnova::Data;
use suprnova::data::Field;
use validator::Validate;

#[derive(Data, Validate)]
pub struct UserDto {
    pub id: i64,

    #[validate(email)]
    pub email: String,

    pub name: String,

    #[data(input_only)]
    #[validate(length(min = 8))]
    pub password: String,

    #[data(output_only)]
    pub display_handle: String,

    pub bio: Field<String>,
}
```

`#[derive(Data)]` generates:
- `Serialize` (skipping `#[data(input_only)]` fields)
- `Deserialize` (rejecting `#[data(output_only)]` fields in the payload, defaulting them to `T::default()`)
- `FormRequest` with `authorize: true` by default - handlers can take the type directly as an extractor
- `IntoInertiaData` (the `Inertia::data(component, dto)` dispatch path)
- An `inventory::submit!` registration for any `#[data(allow_include)]` fields

Add `#[derive(Validate)]` separately so `#[validate(...)]` attributes stay visible at the field call site.

## Field attributes

| Attribute | Effect |
|---|---|
| `#[data(input_only)]` | Accepted on Deserialize, omitted from Serialize |
| `#[data(output_only)]` | Rejected on Deserialize (422), included in Serialize |
| `#[data(allow_include)]` | Field is `?include=`-eligible. **Default-deny**: any `?include=foo` request where `foo` isn't on the allowlist returns 400 |
| `#[data(lazy)]` | Field is a `Prop` resolved against the request's include-set; auto-registers as `allow_include` |
| `#[data(lazy(inertia))]` | Same as `lazy`, tagged for Inertia's partial-reload protocol |
| `#[data(lazy(deferred))]` | Tagged for Inertia's deferred-props protocol |
| `#[data(lazy(closure))]` | Always resolved on initial visit; lazy on partial reloads |
| `#[data(lazy(when_loaded))]` | Resolved only if the source entity has the relation preloaded |
| `#[data(from_route_param)]` | Field value comes from a path capture (e.g. `/users/{id}`). Default key = field name; pass `#[data(from_route_param("id"))]` to override |

## Struct attributes

| Attribute | Effect |
|---|---|
| `#[data(auto_lazy)]` | Every `Prop`-typed field is implicitly `#[data(lazy)]` |
| `#[data(authorize = "path::to::fn")]` | Route the generated `FormRequest::authorize` to a free function with signature `fn(req: &Request) -> bool`. The body parser, validator, Precognition support, and route-param injection still come from the derive |
| `#[data(after_validation = "path::to::fn")]` | Route the generated `FormRequest::after_validation` to `fn(dto: &Self) -> Result<(), ValidationErrors>`, where `validate!` rules run. See [Validation rules and database checks](#validation-rules-and-database-checks) |
| `#[data(after_validation_async = "path::to::fn")]` | Route `FormRequest::after_validation_async` to `async fn(dto: &Self) -> Result<(), ValidationErrors>`, where `Exists`, `Unique` and other async rules run |
| `#[data(allow_unknown_fields)]` | Accept payload keys that don't match any struct field. The default is **strict**: an unrecognised key fails the deserialize with `serde::de::Error::unknown_field(..)` and surfaces as a 422 through `FormRequest`. Opt into permissive only for response DTOs that read forward-compatible third-party payloads |

The earlier `#[data(custom_authorize)]` flag - which suppressed the whole `FormRequest` impl and forced you to reimplement body parsing, validation, and Precognition by hand - is gone. The macro emits a migration error if you try to use it. Use `#[data(authorize = "fn")]` instead.

## Field names and serde attributes

A Data Object writes its own `Serialize` and `Deserialize`, and it honors serde's naming attributes in them:

| Attribute | Effect |
|---|---|
| `#[serde(rename_all = "camelCase")]` on the struct | Every field's key follows the rule. Serde's rules are all accepted: `lowercase`, `UPPERCASE`, `PascalCase`, `camelCase`, `snake_case`, `SCREAMING_SNAKE_CASE`, `kebab-case`, `SCREAMING-KEBAB-CASE` |
| `#[serde(rename = "id")]` on a field | The field's key, winning over `rename_all` |
| `rename(serialize = "..", deserialize = "..")`, `rename_all(serialize = "..", deserialize = "..")` | A different name in the output than in the input |
| `#[serde(skip)]` | The field is neither sent nor read; it takes its `Default` |
| `#[serde(skip_serializing)]` / `#[serde(skip_deserializing)]` | Left out of the output, or out of the input |

```rust
#[derive(Data, Validate)]
#[serde(rename_all = "camelCase")]
pub struct OrderDto {
    #[validate(email)]
    pub customer_email: String,        // `customerEmail`
    #[validate(nested)]
    pub line_items: Vec<LineDto>,      // `lineItems`
    #[serde(rename = "ref")]
    pub reference: String,             // `ref`
}
```

The name is used everywhere the field meets the client:

- **Output** (the serialize name): the JSON body, Inertia props and partial reloads, the `?include=` allowlist of a lazy prop, and JSON:API attribute, relationship and include names.
- **Input** (the deserialize name): the request body, and so the strict unknown-field check, a required field's "missing field" error, and the key a [route parameter](#route-parameter-field-injection) is injected under. The route parameter itself keeps its own name, the Rust field name unless `from_route_param("..")` names one.
- **Validation errors** are keyed by the input name, so the error bag, the page and `Precognition-Validate-Only` all use the names the client sent; a Rust name in `Precognition-Validate-Only` matches nothing. A localized message labels the name snake-cased, as Laravel's does: `unitPrice` reads "unit price". A `validate!` row or a hook names a field by its Rust name, as `validate!` does; the error is keyed by the input name. A key that is already an input name passes through, unless it is also another field's Rust name.
- **Nested objects** are renamed at their own level when their type registers its names: a type that derives `Data`, `FormRequest` or `#[request]` does, and a plain `#[derive(Deserialize, Validate)]` struct does with `#[derive(suprnova::InputNames)]`. Without it, the nested part of the key keeps Rust names (`lineItems.1.unit_price`); so does a generic nested type. A field serde `flatten`s is reported under its own field name, a key the input does not have. A field the input cannot set (`output_only`, `skip_deserializing`) keeps its Rust name in an error key. With serde's `alias`, errors use the field's main name.

A raw identifier loses its `r#`, as it does with serde: `pub r#type: String` is sent as `type`.

Any other serde attribute on a Data Object fails to compile with an error that lists the supported ones: the derive would otherwise leave it silently unapplied. Two fields under the same key fail to compile too.

A `#[derive(FormRequest)]` or `#[request]` struct is deserialized by serde's own derive, which reads all of serde's attributes. Its validation errors are keyed by the input names in the same way.

## Validation rules and database checks

`#[validate(...)]` attributes cover the per-field checks. Everything else
in [Validation](validation.md) - `validate!` rows, cross-field rules like
`After::new(DateBound::Field(..))` or `ExcludeIf`, and database rules like
`Exists` - runs in the `FormRequest` hooks. The derive writes a Data
Object's `FormRequest` impl, so you name the functions it calls:

```rust
use suprnova::rules::{Accepted, After, DateBound, DateFormat};
use suprnova::{Data, Exists, FormContext, ValidationErrors, validate};
use validator::Validate;

#[derive(Data, Validate)]
#[data(after_validation = "booking_rules", after_validation_async = "booking_rows")]
pub struct BookingDto {
    pub room_id: i64,
    pub starts_on: String,
    pub ends_on: String,
    pub terms: bool,
}

fn booking_rules(dto: &BookingDto) -> Result<(), ValidationErrors> {
    let ctx: FormContext = [("starts_on".to_string(), dto.starts_on.clone())].into();
    validate! { dto =>
        starts_on => DateFormat(&["%Y-%m-%d"]);
        ends_on => DateFormat(&["%Y-%m-%d"]), After::new(DateBound::Field("starts_on")) => with ctx;
        terms => Accepted;
    }
}

async fn booking_rows(dto: &BookingDto) -> Result<(), ValidationErrors> {
    let mut errs = ValidationErrors::new();
    Exists::new("rooms", "id")
        .check_value(dto.room_id, &mut errs, "room_id")
        .await;
    errs.into_result()
}
```

The stages run in order and stop at the first that fails: the
`#[validate(...)]` attributes, then `after_validation`, then
`after_validation_async`. A malformed date therefore never reaches the
database. Precognition runs the same stages and reports the fields the
client asked about - asking about an array keeps the errors of its elements
(`tag_ids` keeps `tag_ids.3`). A Data Object with a `from_route_param` field
runs both hooks too.

A generic struct, or one with reference or lazy fields, gets no
`FormRequest` impl, so it would never run a hook; the derive refuses both
attributes on it.

## `Field<T>` - Absent / Null / Value

For PATCH endpoints where "absent from payload" must be distinguished from "explicit null":

```rust
use suprnova::data::Field;

match dto.bio {
    Field::Absent  => { /* don't touch this column */ },
    Field::Null    => { /* clear the column */ },
    Field::Value(text) => { /* set to text */ },
}
```

`Field::Absent` (default) is left out of a Data Object's output: the derive omits the key itself. In a plain struct that derives serde's `Serialize`, pair the field with `#[serde(default, skip_serializing_if = "Field::is_absent")]` for the same result; without `skip_serializing_if`, serde writes `Absent` as JSON `null`.

For three-way DB upserts: `dto.bio.into_option_or_null() -> Option<Option<T>>` maps `Absent → None`, `Null → Some(None)`, `Value(v) → Some(Some(v))`. Use this when "don't touch" and "set to NULL" need to be distinct downstream.

> **Caveat:** `Field<Option<T>>` is lossy - `Value(None)` and `Null` both serialize as JSON `null` and deserialize back to `Null`. For nullable inner types, prefer a flat `Field<T>` and let `Null` carry the "clear it" signal.

## `?include=` query string

The `IncludeMiddleware` parses the request's query string into a per-request `RequestIncludeSet`:

- `?include=foo,bar` - resolve lazy fields `foo` and `bar`.
- `?include[]=foo&include[]=bar` - array form, same result.
- `?exclude=`, `?only=`, `?except=` - Laravel-Data API parity.

Composition with `X-Inertia-Partial-Data` (Inertia's partial-reload header): the include-set + per-DTO allowlist runs **first** for owner-tagged lazy fields, so a request for a disallowed field returns 400 even if partial-data would have filtered it out. Partial-data is applied **after** as a final "only" filter on the resolved props.

Register `IncludeMiddleware` globally - typically between session and authorization in the middleware stack:

```text
SessionMiddleware → IncludeMiddleware → AuthMiddleware → handlers
```

### Programmatic include/exclude/only/except

`RequestIncludeSet` mirrors Laravel-Data's `IncludeableData` contract with chainable builders. Handlers, tests, and middleware can construct or override a set without poking the public fields directly:

```rust
use suprnova::data::RequestIncludeSet;

let set = RequestIncludeSet::default()
    .include(["author", "comments"])
    .exclude(["password"])
    .only(["id", "name"])
    .except(["secret"]);

assert!(set.is_visible("name"));   // on `only`, not in `except`
assert!(!set.is_visible("secret"));// `except` always wins
assert!(set.includes("author"));   // request for the `author` relation
```

| Method | Effect | Laravel equivalent |
|---|---|---|
| `.include(fields)` | append to the include list (lazy fields to resolve) | `Data::include(...$fields)` |
| `.exclude(fields)` | append to the exclude list (fields to drop) | `Data::exclude(...$fields)` |
| `.only(fields)` | initialise or extend the `only` allowlist | `Data::only(...$fields)` |
| `.except(fields)` | append to the except list (always-drop) | `Data::except(...$fields)` |
| `.include_when(cond, fields)` | append only when `cond == true` | `Data::includeWhen($field, $condition)` |
| `.exclude_when(cond, fields)` | append only when `cond == true` | `Data::excludeWhen($field, $condition)` |
| `.only_when(cond, fields)` | extend `only` only when `cond == true` | `Data::onlyWhen($field, $condition)` |
| `.except_when(cond, fields)` | append only when `cond == true` | `Data::exceptWhen($field, $condition)` |
| `.merge(other)` | union two sets (in-place layered overrides) | manual `array_merge` in PHP |
| `.includes(field)` | `field` (or `field.path`) in include list? | `relationLoaded()` analogue |
| `.is_excluded(field)` | `field` in exclude list? | reads exclude partial |
| `.is_excepted(field)` | `field` in except list? | reads except partial |
| `.is_only_listed(field)` | `field` allowed by `only` (or `only` unset)? | reads only partial |
| `.is_visible(field)` | full Laravel resolution order: except → exclude → only | `resolveResource` decision |

Builders take any `IntoIterator<Item = impl Into<String>>`, so arrays, vecs, and slices of `&str`/`String` all work. Strings are trimmed; empty entries are dropped (matching `from_query`).

Dot-paths in any list match the root segment when probed by bare name - `include=["author.posts"]` reports `set.includes("author") == true`, matching Laravel-Data's path resolution. The nested `posts` segment is consumed by `IncludeTree::from_include_set` for JSON:API compound documents.

### Handler-side override: `with_include_overrides`

To layer programmatic overrides on top of what the request's query string already declared (without losing the request's set), use `with_include_overrides`:

```rust
use suprnova::data::with_include_overrides;

async fn show_album(req: Request, user: User) -> Response {
    with_include_overrides(
        |set| set
            .include_when(user.is_admin(), ["audit_log"])
            .exclude_when(!user.is_admin(), ["price_cost"]),
        async move {
            // Inside this scope, the lazy-prop resolver and JSON:API
            // include resolver see the merged set.
            Inertia::data("Album/Show", album_dto).into_response()
        },
    ).await
}
```

The closure runs against a clone of the currently-bound set (or the empty default if no middleware has bound one). After the future completes, the original set is restored - this is a scoped override, not a mutation.

For tests, prefer `scope_include_set(set, future)` to install a fresh set without inheriting any ambient state.

## Generic structs

```rust
use serde::{Serialize, Deserialize};

#[derive(suprnova::Data)]
pub struct Paginated<T>
where
    T: Serialize + for<'de> Deserialize<'de>,
{
    pub items: Vec<T>,
    pub total: usize,

    #[data(allow_include)]
    pub meta: Option<serde_json::Value>,
}
```

The TypeScript extractor emits `export interface Paginated<T>` so frontend code can reuse the generic across instantiations.

The `?include=` allowlist is keyed on the fully-qualified type path (`concat!(module_path!(), "::", stringify!(Paginated))`), not on type-parameter instantiations. `Paginated<UserDto>` and `Paginated<ArticleDto>` declared in the same module share one allowlist - `allow_include` names a field, and field names don't depend on type parameters. Two different DTOs named `Paginated` in different modules each get their own allowlist; their keys don't collide.

Note: `FormRequest` is suppressed for generic structs because its trait bounds (`DeserializeOwned + Validate + Send`) can't be verified without knowing concrete type params. Provide your own impl if you need to extract a generic Data struct from a request.

## Route-parameter field injection

```rust
use suprnova::Data;
use validator::Validate;

#[derive(Data, Validate)]
pub struct UpdateUser {
    #[data(from_route_param("id"))]
    pub id: i64,

    #[validate(length(min = 1))]
    pub name: String,
}
```

For `PATCH /users/{id}` with body `{"name": "Ada"}`, the route-captured `id` is merged into the validated payload. **The path always wins over a body-supplied value** (prevents IDOR via body-tampering).

Bare `#[data(from_route_param)]` defaults to the field name. The macro classifies the field's last path segment at compile time and dispatches to a matching parser. Only the exact names listed below are recognised; everything else (including `i8`/`i16`/`isize`, `Uuid`, `DateTime`, custom newtypes) falls through to `pass_string` and lets the field's own `Deserialize` do the work.

| Field type | Parser |
|---|---|
| `i64` | `parse_i64` |
| `u64` | `parse_u64` |
| `i32` | `parse_i32` |
| `u32` | `parse_u32` |
| `i128` | `parse_i128` (validates then passes raw string through; field's `Deserialize` parses) |
| `u128` | `parse_u128` (same string-passthrough pattern) |
| `f64` | `parse_f64` (rejects non-finite values) |
| `f32` | `parse_f32` (rejects non-finite values) |
| `bool` | `parse_bool` (accepts only `"true"` / `"false"`) |
| Anything else | `pass_string` - raw string handed to the field's own `Deserialize` |
| `Option<T>` or `Field<T>` of any of the above | Same parser as `T`; missing route param leaves the field absent |

## Lazy props

```rust
use suprnova::Data;
use suprnova::inertia::Prop;

#[derive(Data)]
#[data(auto_lazy)]
pub struct AlbumDto {
    pub id: i64,
    pub songs: Prop,    // auto-registered as ?include=songs
    pub artist: Prop,   // auto-registered as ?include=artist
}
```

Explicit per-field flavor:

```rust
#[derive(Data)]
pub struct AlbumDto {
    pub id: i64,

    #[data(lazy(inertia))]
    pub songs: Prop,

    #[data(lazy(deferred))]
    pub lyrics: Prop,

    #[data(lazy(closure))]
    pub artist: Prop,
}
```

Every lazy flavor is gated the same way, `lazy(deferred)` included. A deferred field is opt-in twice over: `?include=lyrics` puts it in scope for the request, and Inertia's deferred-props protocol decides which round trip carries it. A field the request never included is dropped whole - no value, no `deferredProps` announcement - so the client is never sent after something this request has no claim on. A field named by `?include=` but missing from the allowlist returns 400 on the first visit, before `X-Inertia-Partial-Data` can quietly absorb the error.

Use `Inertia::data(component, dto)` to render - the derive generates an `IntoInertiaData` impl that consults the include-set and allowlist:

```rust
return Inertia::data("Album/Show", album_dto);
```

Note: lazy-bearing structs suppress `Serialize`, `Deserialize`, and `FormRequest` because `Prop` doesn't implement them. If a single endpoint needs both inbound parsing and lazy outbound, use two DTOs: one inbound (`#[derive(Data, Validate)]` plain) and one outbound (`#[derive(Data)]` with lazy fields).

## `when_loaded!` - relation-loaded conditional lazy

Mirrors Laravel-Data's `#[AutoWhenLoadedLazy]`. The user's `From<Entity>` impl decides whether the relation was preloaded:

```rust
use suprnova::{when_loaded, IsRelationLoaded};

impl From<&AlbumEntity> for AlbumDto {
    fn from(album: &AlbumEntity) -> Self {
        Self {
            id: album.id,
            songs: when_loaded!(album, "songs", || async {
                serde_json::json!(album.songs_relation()
                    .iter()
                    .map(SongDto::from)
                    .collect::<Vec<_>>())
            }),
            artist: Prop::eager(serde_json::json!(album.artist_name())),
            lyrics: Prop::lazy(|| async { /* ... */ }),
        }
    }
}
```

If the entity hasn't preloaded the named relation (per `IsRelationLoaded::is_relation_loaded`), `when_loaded!` returns `Prop::absent()` and the field is absent from the response.

SeaORM entities need a custom `IsRelationLoaded` impl that consults their loaded-relations state - there's no framework-supplied blanket impl because SeaORM's `ModelTrait` doesn't carry per-instance relation-loaded state (loaded relations live on query results, not the model struct itself).

## TypeScript export

`suprnova generate-types` emits TypeScript definitions for every `#[derive(Data)]` (and legacy `#[derive(InertiaProps)]`) struct. Behavior:

- `Field<T>` → `field?: T | null`
- chrono's `DateTime`, `NaiveDate`, `NaiveDateTime` and `NaiveTime` → `string`, the ISO 8601 text they serialize as
- `Prop` → `field?: T` (the lazy may-be-absent semantic; the `?` carries it, the type itself is plain)
- `#[data(input_only)]` → excluded from output type
- `#[data(output_only)]` → excluded from input type
- Generic struct → TypeScript generic interface (`export interface Paginated<T>`)
- When ANY field has `input_only` / `output_only` / `lazy`, or the input and the output name a field differently or skip it in one direction only, two interfaces are emitted: `<Name>` (output) and `<Name>Input` (input)
- A plain struct a prop reaches, one that derives serde's `Serialize`, follows serde's attributes: `#[serde(skip)]` and `skip_serializing` leave the field out, `skip_serializing_if` makes it optional (`field?: T`), and `rename` and `rename_all` (or their `serialize = ...` forms) name the key. Other serde attributes, such as `flatten` and `transparent`, are not read. A key that is not an identifier, such as `display-name`, is quoted
- `#[derive(Data)]` and `#[derive(InertiaProps)]` structs follow the serde attributes they honor (see [Field names and serde attributes](#field-names-and-serde-attributes)): `<Name>` declares the serialize names, `<Name>Input` the deserialize names

Generated types never leak Rust-only types (`Prop<...>` won't appear in the output `.d.ts`).

## Scaffolding

```bash
suprnova make:inertia UserDto --data
```

Emits a `#[derive(Data, Validate)]` skeleton instead of the legacy `#[derive(InertiaProps)]` template.

## Next

- [Validation](validation.md) - `#[derive(Validate)]`, async validators, and how `FormRequest` calls into them
- [Requests](requests.md) - the request extractor surface that `FormRequest` plugs into
- [Inertia Responses](frontend-inertia-responses.md) - the `Inertia::data` path and how lazy props become partial-reload-eligible
- [Eloquent Resources](eloquent-resources.md) - `#[derive(Data)]` with `#[json_resource]` for JSON:API outputs (sibling of `Data` for serialization-only payloads)
- [Error Model](error-model.md) - how `unknown_field` rejection becomes a 422 and how `FormRequest` failures travel back as `ValidationErrors`


---

<!-- /docs/events -->

# Events

Events are Suprnova's typed in-process pub/sub. Persisted domain history lives in
[Event sourcing](event-sourcing.md). A controller fires
`UserRegistered { user_id }`; one listener emails the user, another
writes an audit row, a third publishes a broadcast. All three see the
same payload, run in registration order, and have no compile-time
knowledge of each other.

The user-facing surface is the `EventFacade` struct (re-exported as
`suprnova::EventFacade`). The crate also re-exports the `Event` *trait*
as `suprnova::Event` - same name as Laravel's facade, but in Rust the
trait is the typed contract every payload implements. Behind the facade
is a single process-global `EventDispatcher` (held in a `OnceLock`):
registered listeners survive the request that registered them, and
dispatches either run inline or spawn into a bounded retrying task set.

## The basics

```rust
use suprnova::{EventFacade, Event, Listener, FrameworkError, async_trait};
use std::sync::Arc;

#[derive(Debug, Clone)]
pub struct UserRegistered {
    pub user_id: i64,
}

impl Event for UserRegistered {
    fn event_name() -> &'static str {
        "UserRegistered"
    }
}

pub struct SendWelcomeEmail;

#[async_trait]
impl Listener<UserRegistered> for SendWelcomeEmail {
    async fn handle(&self, e: &UserRegistered) -> Result<(), FrameworkError> {
        // send the email…
        let _ = e.user_id;
        Ok(())
    }
}

// In bootstrap.rs:
EventFacade::listen::<UserRegistered, SendWelcomeEmail>(Arc::new(SendWelcomeEmail)).await;

// In a controller:
EventFacade::dispatch(UserRegistered { user_id: 42 }).await?;
```

`Event` requires `Send + Sync + Clone + 'static + Debug` so a payload
can cross task boundaries (queued listeners) and the dispatcher can
log it. `Listener<E>` is `Send + Sync + 'static` so it can outlive the
registration call. There is no `#[derive(Event)]` - the trait has two
methods (`event_name` and the defaulted `queued`) so a hand-written
impl is two lines.

## Dispatch modes

| Method | Semantics |
|---|---|
| `EventFacade::dispatch(event)` | Synchronous, fail-fast - the first listener `Err` aborts the chain |
| `EventFacade::dispatch_best_effort(event)` | Synchronous, run-them-all - returns the first `Err` after every listener has run |
| `EventFacade::dispatch(event)` when `Event::queued() = true` | Each listener spawns as a bounded retrying task; the call returns after spawning |

Use `dispatch` (fail-fast) when a downstream side effect MUST observe
a successful upstream - most model lifecycle hooks fall here, so an
observer that vetoes a save can short-circuit. Use
`dispatch_best_effort` for fan-out where one failing listener should
not silence the rest - most observability events fall here.

Override the trait method to opt into queued delivery:

```rust
impl Event for ExpensiveAuditTrail {
    fn event_name() -> &'static str { "ExpensiveAuditTrail" }
    fn queued() -> bool { true }
}
```

Queued listeners are bounded by a process-wide semaphore. The default
ceiling is 256 concurrent tasks; override per dispatcher with
`EventDispatcher::with_concurrency(n)` or globally via the
`EVENT_MAX_CONCURRENCY` env var. Each task retries up to 3 attempts
with 100ms→2s jittered backoff before giving up - these are in-process
transient-fault retries, not the durable queue's minutes-long schedule.

At the ceiling, `dispatch` waits until a running listener finishes, so a
flood of events slows the code dispatching them instead of piling up
work. A queued listener that dispatches another queued event does not
wait: it holds a slot while it runs, and waiting for a second one could
leave every slot held by a listener waiting for another.

## Subscribers - bundle related registrations

When several listeners belong to one feature, a `Subscriber`
registers them as a unit. Mirrors Laravel's `EventServiceProvider`
subscriber pattern.

```rust
use suprnova::{EventFacade, EventDispatcher, Subscriber, async_trait};
use std::sync::Arc;

pub struct UserEventSubscriber {
    db: Arc<crate::Db>,
}

#[async_trait]
impl Subscriber for UserEventSubscriber {
    async fn subscribe(self: Arc<Self>, d: &EventDispatcher) {
        let db = self.db.clone();
        d.listen::<UserRegistered, _>(Arc::new(SendWelcomeEmail::new(db.clone()))).await;
        d.listen::<UserDeleted, _>(Arc::new(CleanupUserData::new(db.clone()))).await;
        d.listen::<UserPromoted, _>(Arc::new(NotifyAdmins::new(db))).await;
    }
}

// In bootstrap.rs - one line per subscriber instead of three per listener:
EventFacade::subscribe(Arc::new(UserEventSubscriber { db: db.clone() })).await;
```

`subscribe` takes `Arc<S>` so listeners that need to share state with
the subscriber can clone the `Arc` and capture it.

## Inspecting and removing listeners

```rust
if EventFacade::has_listeners::<UserRegistered>() {
    EventFacade::dispatch(UserRegistered { user_id: 42 }).await?;
}

let removed: usize = EventFacade::forget::<UserRegistered>();
```

`has_listeners::<E>()` mirrors Laravel's
`Event::hasListeners($eventName)`. `forget::<E>()` drops every
listener registered for that event type and returns the count
removed. Production code rarely needs `forget` - listener registration
is normally bootstrap-once - but hot-swap and test code reach for it.

Both methods return safe defaults when the listener registry lock is
poisoned (`false` and `0` respectively), with a `tracing::error!`
logged so the failure is observable.

## Push and flush

`push` captures an event in a per-event-name bucket without firing
it. `flush::<E>()` drains the bucket and dispatches everything in
capture order. Mirrors Laravel's `Event::push` / `Event::flush` pair.

```rust
// Inside a handler that does work in two phases:
EventFacade::push(UserRegistered { user_id: 42 }).await;
// … rendering, validation, more work …
EventFacade::flush::<UserRegistered>().await?;
```

Pushed events ignore the `defer` scope - they are already explicitly
deferred. `forget_pushed()` drops every pushed event without
dispatching, returning the count dropped. Mirrors
`Event::forgetPushed()`.

## defer - buffer every dispatch inside a callback

This buffers in-process dispatches. [Event sourcing](event-sourcing.md) covers
stored domain facts and projector replay.

`defer(only, async { … })` runs the callback with a task-local
buffer in scope. Every `dispatch` / `dispatch_best_effort` call made
inside the callback is captured and replayed after the callback
returns. Mirrors Laravel's `Event::defer($callback, ?$events)`.

The buffer belongs to the dispatcher that opened it. A dispatch on
another `EventDispatcher` inside the callback runs at once on that
dispatcher's listeners, as it would outside the callback.

```rust
let ((), flush_err) = EventFacade::defer::<_, ()>(None, async {
    do_work_part_one().await?;
    EventFacade::dispatch(WorkStarted).await?; // buffered
    do_work_part_two().await?;
    EventFacade::dispatch(WorkFinished).await?; // buffered
    Ok(())
})
.await?;
// At this point WorkStarted and WorkFinished have both fired in order.
// `flush_err` carries the first dispatch error from the replay (if any).
```

Pass `Some(&["EventOne", "EventTwo"])` to defer ONLY those event
names; everything else dispatches inline as usual. A callback error
short-circuits - buffered events are dropped, the error propagates.

The defer buffer is per-Tokio-task, so two concurrent `defer` calls
don't stomp on each other's state.

## Queued listeners - in-process vs durable

Two distinct "queued" tiers, and the naming matters:

| Need | Reach for |
|---|---|
| Listener should run off-task; OK to lose on crash | `Event::queued() = true` on the event trait |
| Listener work MUST survive a crash + restart | `QueuedListener<E, J>` (bridges event → durable job) |

`Event::queued() = true` makes the dispatcher spawn each listener as
its own Tokio task, bounded by a process semaphore, with bounded
retry (3 attempts, jittered backoff). The work runs on this process;
a crash drops in-flight listeners. The
[graceful-shutdown drain](#draining-on-shutdown) waits for in-flight
tasks up to a deadline.

`QueuedListener<E, J>` is a stock listener that builds a
[`Job`](queues.md) from each event and pushes it on the durable
queue. The event still fires synchronously; the listener just
enqueues - which is fast - so request latency stays low. The job
itself survives the crash because the queue is durable.

```rust
use suprnova::{EventFacade, QueuedListener};
use std::sync::Arc;

EventFacade::listen::<UserRegistered, _>(Arc::new(
    QueuedListener::<UserRegistered, SendWelcomeEmailJob>::new(|e| SendWelcomeEmailJob {
        user_id: e.user_id,
    }),
))
.await;
```

The `QueuedListener` only needs the event to be a regular synchronous
event - the durability lives in the queue, not the dispatcher.

### Unique queued listeners

When the listener's job declares `Job::unique_id`, the listener pushes it
with `Queue::push_unique`, so the unique lock is taken before the job is
queued, as Laravel's dispatcher takes it for a unique listener. A second
event while the lock is held pushes nothing, dispatches
`UniqueJobSkipped`, and the listener still answers `Ok(())`. A job that
also asks `Job::unique_until_processing` releases its lock when a worker
starts it, so the next event queues the job again:

```rust
#[async_trait]
impl Job for RebuildSearchIndex {
    fn job_name() -> &'static str { "RebuildSearchIndex" }
    fn unique_id(&self) -> Option<String> { Some("search-index".into()) }
    fn unique_until_processing() -> bool { true }
    async fn handle(self) -> Result<(), FrameworkError> { Ok(()) }
}

EventFacade::listen::<ProductUpdated, _>(Arc::new(
    QueuedListener::<ProductUpdated, RebuildSearchIndex>::new(|_| RebuildSearchIndex),
))
.await;
```

The unique lock lives in the cache, so bootstrap the cache first. A job
that declares both `unique_id` and `debounce_for` is still refused with an
error, as every push refuses it.

### Delaying a queued listener

`delay(duration)` makes each job available that long after the event,
and `delay_until(f)` at the moment `f` computes from the event. Either one
wins over the job's own `Job::delay`, and the later call replaces the
earlier one:

```rust
use std::time::Duration;

// Thirty seconds after each event.
QueuedListener::<OrderPlaced, SendReceipt>::new(|e| SendReceipt { order_id: e.order_id })
    .delay(Duration::from_secs(30));

// At the time the event names.
QueuedListener::<ReminderScheduled, SendReminder>::new(|e| SendReminder { id: e.id })
    .delay_until(|e| e.send_at);
```

`delay_until` takes a closure over the event rather than a date, because a
date fixed when you register the listener is in the past for every event a
long-running process handles later. Laravel's queued closure takes a date,
an interval, or seconds; the closure covers each of those. A moment
already past makes the job available at once.

### Debouncing a queued listener

A `QueuedListener` funnels through `Queue::push`, so a listener is debounced
the moment its **job** declares `Job::debounce_for` - nothing extra to wire, and
`Job::debounce_id` gives you a window per entity.

When the window belongs to the registration rather than to the job, use
`DebouncedListener` and derive the key from the event:

```rust
use std::sync::Arc;
use std::time::Duration;
use suprnova::events::{DebouncedListener, EventFacade};

EventFacade::listen::<OrderUpdated, _>(Arc::new(
    DebouncedListener::<OrderUpdated, ReindexOrder>::new(
        Duration::from_secs(30),
        |e| ReindexOrder { order_id: e.order_id },
    )
    .max_wait(Duration::from_secs(300))
    .keyed_by(|e| e.order_id.to_string()),
))
.await;
```

Four `OrderUpdated` events for order 55 enqueue four jobs and run one. See
[Queues](queues.md) for the full contract.

## Draining on shutdown

Queued in-process listeners spawn into a `JoinSet` tracked by the
dispatcher, which lets go of each one as it finishes. The server's
graceful shutdown, `queue:work`, `schedule:work` and `workflow:work`
when they stop, and `schedule:run` once its tasks have run, wait up to
ten seconds for the listeners still running:
returning from `main` would end them part way. A process of your own
calls `EventFacade::drain_queued(timeout)` to do the same:

```rust
let still_running = EventFacade::drain_queued(Duration::from_secs(30)).await;
if still_running > 0 {
    tracing::warn!(still_running, "queued listeners abandoned at shutdown");
}
```

Drain returns the count still running when the deadline elapsed (`0`
= fully drained). Stragglers past the deadline are aborted so
shutdown cannot hang. Stragglers include listeners dispatched while the
drain was waiting and listeners still waiting for a slot. Two drains can
run at once, such as your own and the process's at shutdown: each one
waits for every listener still running, counts it at its deadline, and
aborts only the listeners it took.

## Bridging events to broadcasting

`EventFacade::broadcast::<E>(hub)` wires a one-line bridge from a
dispatched event to a `BroadcastHub`. Any type that implements
`Broadcastable` and `Event` can be broadcast this way; listeners
receive the typed payload, and subscribers on the named channels
receive the broadcast envelope.

```rust
use suprnova::EventFacade;
use std::sync::Arc;

let hub: Arc<dyn suprnova::BroadcastHub> = Arc::new(broadcast_hub);
EventFacade::broadcast::<OrderShipped>(hub).await;

// Any later dispatch is also published to the channels declared
// by OrderShipped::broadcast_on():
EventFacade::dispatch(OrderShipped { order_id: 42, user_id: 99 }).await?;
```

See [Broadcasting](broadcasting.md) for the channel model
(public / private / presence) and the `Broadcastable` trait.

## Built-in events

The framework dispatches a fixed set of events from its own subsystems.
You opt in by registering listeners; if no listener is registered the
events are no-ops.

| Subsystem | Events | Dispatched by |
|---|---|---|
| Error handling | `ErrorOccurred` | Every 5xx response (returned `FrameworkError` or recovered panic) |
| Auth (guards) | `Auth\\Attempting`, `Auth\\Authenticated`, `Auth\\Login`, `Auth\\Logout`, `Auth\\Failed` | `StatefulGuard::attempt` / `login` / `logout` / `once` |
| Auth flows | `EmailVerified`, `PasswordResetLinkSent`, `PasswordResetCompleted`, `AccountLocked`, `AccountUnlocked`, `TwoFactorEnrolled`, `TwoFactorChallenged`, `TwoFactorChallengeFailed`, `TwoFactorDisabled` | `auth_flows::{EmailVerification, PasswordReset, BruteForce, TwoFactor}` |
| Database | `Database\\ConnectionEstablished`, `Database\\QueryExecuted`, `Database\\TransactionBeginning`, `Database\\TransactionCommitted`, `Database\\TransactionRolledBack`, `Database\\DatabaseBusy` | `DbConnection::connect`, every query, `DB::transaction`; `DatabaseBusy` by `DB::monitor` and the `db:monitor` command |
| Mail | `MessageSending`, `MessageSent` | `MailBuilder::send` before/after transport |
| Notifications | `NotificationSending`, `NotificationSent`, `NotificationFailed` | Each channel delivery |
| Queue (worker) | `queue::JobQueueing`, `JobQueued`, `JobProcessing`, `JobProcessed`, `JobAttempted`, `JobExceptionOccurred`, `JobFailed`, `JobReleased`, `JobReleasedAfterException`, `JobTimedOut`, `Looping`, `WorkerStarting`, `WorkerStopping`, `WorkerInterrupted`, `UniqueJobSkipped`, `QueuePaused`, `QueueResumed`, `QueuesPaused`, `QueuesResumed` | `Queue::push` / `Queue::push_unique` / `run_worker` / `Queue::pause` / `resume` / `pause_all` / `resume_all` |
| Features | `FeatureUpdated`, `FeatureDeleted` | `features::admin` CRUD |
| Eloquent (per model) | 16 lifecycle events - `Retrieved`, `Saving`, `Saved`, `Creating`, `Created`, `Updating`, `Updated`, `Deleting`, `Deleted`, `Restoring`, `Restored`, `ForceDeleting`, `ForceDeleted`, `Replicating`, `Pruning`, `Pruned` - emitted under each model's `events::` submodule | The `#[suprnova::model]` macro wires these into save/update/delete |

`ErrorOccurred` is the dedicated hook for shipping 5xx exceptions to
Sentry, Datadog, Slack, etc. The dispatch is best-effort and spawned,
so a broken Sentry listener cannot silence the rest, and response
conversion never blocks on it. See [Error Model](error-model.md) for
the full panic-recovery and conversion contract.

Model lifecycle events fire fail-fast: a `Saving` listener that
returns `EventResult::Cancel` (via the `CancellableListener` trait)
aborts the save. See [Eloquent observers and lifecycle events](eloquent.md).

## DB::listen - observing queries

For per-query observability you can register either a typed
`Listener<QueryExecuted>` through the dispatcher or, more commonly,
a `DB::listen` callback that mirrors Laravel's `DB::listen(function
($q) { ... })` signature:

```rust
use suprnova::DB;
use std::sync::Arc;

DB::listen(Arc::new(|q| {
    tracing::debug!(
        sql = %q.sql,
        time_ms = q.time.as_millis(),
        connection = %q.connection_name,
        "query"
    );
}));
```

The callback receives a `QueryExecuted` carrying the SQL, bindings,
wall-clock duration, connection name, the read/write classification,
and the final `Result` (so failed queries are observable too).
`QueryExecuted::to_raw_sql()` inlines bindings for log convenience -
debug-format, NOT SQL-safe.

Two re-entrancy and cost guarantees:

- **Re-entrancy guard.** A listener that itself issues a query won't
  re-fire `QueryExecuted` from that nested query - the dispatcher
  sets a task-local flag while a listener runs, and the executor
  skips emission inside that scope. A log-to-DB listener will not
  loop.
- **Zero overhead when nobody is listening.** The executor checks a
  combined `query_observation_active()` (any direct listener, any
  registered `Listener<QueryExecuted>`, OR query-log enabled) before
  building the event payload. When all three are off, the entire
  emission path is short-circuited.

## Testing - `EventFacade::fake()`

`EventFacade::fake()` swaps the global dispatcher with a recorder.
Dispatched events go into the recording instead of running listeners.
The fake holds a process-wide serializer for the lifetime of the
guard, so parallel `#[tokio::test]`s that use it run one at a time -
tests no longer need their own `serial_test` mutex.

```rust
use suprnova::events::{
    EventFacade, assert_dispatched, assert_dispatched_once, assert_dispatched_times,
    assert_nothing_dispatched, has_dispatched, dispatched, dispatched_events,
};

#[tokio::test]
async fn registration_dispatches_welcome_event() {
    let _guard = EventFacade::fake();

    register_user("ada@example.com").await.unwrap();

    assert_dispatched_once::<UserRegistered>();
    assert_dispatched::<UserRegistered>(|e| e.email == "ada@example.com");
}
```

| Helper | Asserts |
|---|---|
| `assert_dispatched::<E>(pred)` | at least one matching `E` was dispatched |
| `assert_dispatched_once::<E>()` | exactly one `E` was dispatched |
| `assert_dispatched_times::<E>(n)` | exactly `n` of `E` were dispatched |
| `assert_not_dispatched::<E>(pred)` | no matching `E` was dispatched |
| `assert_nothing_dispatched()` | NO events of any type were dispatched |
| `assert_listening::<E, L>()` | a listener `L` was registered for `E` |
| `has_dispatched::<E>()` | bool: any `E` recorded |
| `dispatched::<E>(pred)` | `Vec<E>` clones of matching events |
| `dispatched_count::<E>(pred)` | count of matching events |
| `dispatched_events()` | `HashMap<&'static str, usize>` of all dispatches |

### Selective faking

```rust
// Only fake these events; everything else dispatches normally.
let _guard = EventFacade::fake_only(&["UserRegistered", "UserDeleted"]);

// Fake every event EXCEPT these.
let _guard = EventFacade::fake_except(&["TelemetryEvent"]);
```

Mirrors Laravel's `Event::fake([…])` and `EventFake::except($events)`.

### Mute - discard events without recording

`EventFacade::muted(async { … })` runs the callback with a task-local
"silent dispatcher" flag set; every event dispatched inside is
discarded without recording or invoking listeners. The Suprnova
analogue of Laravel's `NullDispatcher`, scoped to a callback.

```rust
EventFacade::muted(async {
    // No listeners fire, no events recorded.
    run_bulk_import().await;
})
.await;
```

Unlike `fake()`, `muted` does NOT acquire the process serializer -
two muted scopes can run in parallel.

### `assert_listening` - verify a listener is wired up

Use to test bootstrap wiring without firing an event:

```rust
#[tokio::test]
async fn bootstrap_wires_welcome_listener() {
    let _guard = EventFacade::fake();
    bootstrap::register_listeners().await;
    suprnova::events::assert_listening::<UserRegistered, SendWelcomeEmail>();
}
```

The fake observes registrations via the dispatcher's `listen`
method, so the registration must happen INSIDE the fake's scope -
listeners registered before `EventFacade::fake()` are NOT seen by
`assert_listening`.

## Laravel parity reference

Every Laravel 13 `Event` facade and `EventFake` method that has a
typed-Rust equivalent ships under the closest matching name. Methods
Laravel exposes that don't fit typed Rust are omitted with a short
note.

| Laravel | Suprnova |
|---|---|
| `Event::dispatch($event)` | `EventFacade::dispatch(event).await` |
| `Event::dispatch($event)` (halt arg) | use `dispatch` (fail-fast on `Err`) |
| `Event::until($event)` | `dispatch` (typed: first `Err` halts) |
| `Event::listen($event, $listener)` | `EventFacade::listen::<E, L>(Arc::new(L))` |
| `Event::hasListeners($name)` | `EventFacade::has_listeners::<E>()` |
| `Event::forget($event)` | `EventFacade::forget::<E>()` |
| `Event::push($event)` | `EventFacade::push(event).await` |
| `Event::flush($event)` | `EventFacade::flush::<E>().await` |
| `Event::forgetPushed()` | `EventFacade::forget_pushed().await` |
| `Event::defer($callback, ?$events)` | `EventFacade::defer(only, async {…}).await` |
| `Event::subscribe($subscriber)` | `EventFacade::subscribe(Arc::new(S)).await` |
| `Event::fake()` | `EventFacade::fake()` (guard) |
| `Event::fake([$names])` | `EventFacade::fake_only(&["…"])` |
| `EventFake::except($names)` | `EventFacade::fake_except(&["…"])` |
| `EventFake::assertDispatched` | `assert_dispatched` |
| `EventFake::assertDispatchedOnce` | `assert_dispatched_once` |
| `EventFake::assertDispatchedTimes` | `assert_dispatched_times` |
| `EventFake::assertNotDispatched` | `assert_not_dispatched` |
| `EventFake::assertNothingDispatched` | `assert_nothing_dispatched` |
| `EventFake::assertListening` | `assert_listening` |
| `EventFake::hasDispatched` | `has_dispatched` |
| `EventFake::dispatched` | `dispatched` (returns `Vec<E>`) |
| `EventFake::dispatchedEvents` | `dispatched_events` (name → count map) |
| `NullDispatcher` | `EventFacade::muted(async {…}).await` |
| `Event::wildcards` (`User.*` patterns) | not shipped - use typed listeners, or the `Observer<M>` trait for per-model lifecycle hooks |
| `Event::subscribe` (string subscriber) | use the typed `Subscriber` trait |
| `DB::listen(function ($q) {…})` | `DB::listen(Arc::new(|q| {…}))` - same shape, takes `&QueryExecuted` |
| `ShouldBeUnique` / `ShouldBeUniqueUntilProcessing` on a queued listener | `QueuedListener` whose job declares `Job::unique_id` (and `Job::unique_until_processing`) |
| `QueuedClosure::delay($delay)`, a listener's `$delay` | `QueuedListener::delay(duration)`, `QueuedListener::delay_until(\|e\| ...)` |

### Why Suprnova diverges

Laravel's dispatcher leans on PHP's stringly-typed runtime: events
are class names passed as strings, listeners are class names looked
up via the container, and `Event::listen('User.*', ...)` works
because wildcards over class-name strings make sense in PHP. In
Rust, the equivalent of "this listener handles `User.*`" is "this
listener generic on `E: UserEvent`" - a trait, not a string match.
So Suprnova drops wildcards in favour of the type system, and the
result is that broken refactors become compile errors instead of
runtime mis-routes.

The other divergence is `defer`: Laravel's defer relies on the
request-per-process model to bound the deferral scope. Suprnova
serves many concurrent requests in one process, so the deferral
buffer is task-local. Two concurrent `defer` calls each get their
own buffer; the calls cannot stomp on each other, and there is no
hidden global state to leak.

## Where each piece lives

| Piece | File |
|---|---|
| `Event` trait, `Listener<E>`, `Subscriber` | `framework/src/events/mod.rs` |
| `EventDispatcher`, `EventFacade` (facade struct) | `framework/src/events/dispatcher.rs` |
| `ErrorOccurred` | `framework/src/events/builtins.rs` |
| `QueuedListener<E, J>`, `DebouncedListener<E, J>` | `framework/src/events/queued_listener.rs` |
| `assert_dispatched*`, `EventFakeGuard`, `muted` | `framework/src/events/testing.rs` |
| Built-in event payloads | `framework/src/{database,auth,auth_flows,mail,notifications,queue,features}/events.rs` |
| Per-model lifecycle events | macro-generated into each model's `events::` submodule |

## Next

- [Error Model](error-model.md) - `ErrorOccurred` and the 5xx
  conversion path
- [Queues](queues.md) - durable jobs, the crash-tolerant tier;
  `QueuedListener` bridges into this
- [Broadcasting](broadcasting.md) - wire dispatched events to
  WebSocket channels via `EventFacade::broadcast::<E>(hub)`
- [Eloquent](eloquent.md) - model lifecycle events and the
  `Observer<M>` trait
- [Database](database.md) - `DB::listen` and the
  `Database\\QueryExecuted` event


---

<!-- /docs/event-sourcing -->

# Event sourcing

Event sourcing keeps domain history as typed facts. Ordinary [events](events.md)
remain in-process messages. [Workflows](workflows.md) keep step outputs for
recovery. Neither requires an aggregate.

## Register the tables

Append the framework migration to your application migrator:

```rust
fn migrations() -> Vec<Box<dyn suprnova::sea_orm_migration::MigrationTrait>> {
    suprnova::event_sourcing::migrations()
}
```

`stored_events` has a global id, aggregate UUID, aggregate version, event version,
stable event type, JSON payload, JSON metadata and UTC recording time. A unique
constraint rejects a second fact at the same aggregate version. `snapshots` keeps
UUID, aggregate version, JSON state and capture time. SQLite, PostgreSQL and
MySQL/MariaDB use the same migration.

Rolling the framework migration back drops `stored_events`, `snapshots` and
`projector_checkpoints`, so back history up before a rollback.

## Record and rebuild an aggregate

The attribute registers a stable event name. Renaming the Rust struct preserves
stored history. Declare a new schema version when the payload changes.
Application and console startup validate every registered event name once. Two
Rust types declaring one name stop startup with both type names in the error.

```rust
use suprnova::{aggregate, domain_event, Aggregate, AggregateRoot, Fact, FrameworkError};
use suprnova::serde::{Deserialize, Serialize};

#[domain_event(name = "tally.added", version = 1)]
#[derive(Serialize, Deserialize)]
struct Added { amount: i64 }

#[aggregate]
#[derive(Clone, Default, Serialize, Deserialize)]
struct Tally { total: i64 }

impl AggregateRoot for Tally {
    const NAME: &'static str = "tally";
    fn apply(&mut self, fact: &Fact<'_>) -> Result<(), FrameworkError> {
        if let Some(added) = fact.decode::<Added>()? {
            self.total = self.total.checked_add(added.amount)
                .ok_or_else(|| FrameworkError::bad_request("tally total is too large"))?;
        }
        Ok(())
    }
}

async fn add() -> Result<(), FrameworkError> {
    let uuid = "7d200fce-d107-4a12-8b9b-7e642209aa01";
    let mut tally = Aggregate::<Tally>::retrieve(uuid).await?;
    tally.record(Added { amount: 1 }).await?;
    tally.persist().await?;
    let rebuilt = Aggregate::<Tally>::retrieve(uuid).await?;
    assert_eq!(rebuilt.state().total, tally.state().total);
    Ok(())
}
```

`AggregateRoot::apply` receives a `Fact` view with the stable event name, payload
schema version, aggregate version, payload and metadata. It excludes the storage
id and recording time, so recording and rebuilding receive identical values.
Projectors, reactors and event listings still receive `StoredEvent`, which exposes
this view through `fact()`.

`record` applies to a copy before accepting the fact. `persist` writes every
recorded fact in one transaction. A stale writer gets an error with the aggregate
UUID and the expected and observed versions, with HTTP status 409. Its recorded facts remain available.
Reload state and decide whether to issue the command again.

Persistence owns its transaction. Calling it from an outer `DB::transaction`
returns an internal error naming the aggregate. Storage failures remain database
errors. This prevents an outer rollback from leaving the in-memory
version ahead of durable history. An after-commit error can occur after the write
succeeds. The instance then records the committed version and clears its pending
facts, so retrying the instance cannot duplicate them. The instance reflects the
committed outcome as soon as COMMIT returns, before transaction listeners or
delivery callbacks. A cancelled persist settles on the next `record` or `persist`
call. These calls are async because they first await the owned transaction's
outcome. `is_settled()` remains false until that reconciliation completes.
Rollback retains pending facts and the prior durable version.

The wait uses the connection's `DatabaseConfig::outcome_settle_timeout` in seconds,
set with `.outcome_settle_timeout(seconds)` or `DB_OUTCOME_SETTLE_TIMEOUT` (default 30;
zero is rejected). This setting bounds the wait in seconds for the physical outcome
of a transaction whose caller was dropped during finalization; if the wait expires,
the outcome is reported as unknown. It never cancels or bounds a transaction, query
or commit. A timeout returns an internal error naming the aggregate and prevents
reuse. Retry settlement after the owned finalizer completes. Snapshots require a settled instance.
`recorded()` returns a copy of the pending facts at the time of the call.

## Snapshots

Capture state after persistence, then load it with the later facts:

```rust
async fn capture(uuid: &str) -> Result<(), FrameworkError> {
    let tally = Aggregate::<Tally>::retrieve(uuid).await?;
    tally.snapshot().await?;
    let with_snapshot = Aggregate::<Tally>::retrieve(uuid).await?;
    let full = Aggregate::<Tally>::retrieve_without_snapshot(uuid).await?;
    assert_eq!(with_snapshot.state().total, full.state().total);
    Ok(())
}
```

A snapshot at a version replaces an earlier capture of that version. Older
versions remain available. A capture with pending facts or no history fails.
Snapshots are application state, so changes to that state's serialization need
an application migration or removal of the affected snapshots before deployment.

## Upgrade payloads

An upgrade function receives the stored version and returns the current payload.
Unknown event names and unsupported versions fail with the event name.

```rust
use suprnova::{domain_event, FrameworkError};
use suprnova::serde::{Deserialize, Serialize};
use suprnova::serde_json::Value;

fn upgrade(version: i32, mut payload: Value) -> Result<Value, FrameworkError> {
    if version == 1 {
        payload["amount"] = payload["old_amount"].take();
    }
    Ok(payload)
}

#[domain_event(name = "counter.added", version = 2, upgrade = "upgrade")]
#[derive(Serialize, Deserialize)]
struct Addition { amount: i64 }
```

## Projectors and reactors

A projector builds a read model with ordinary ORM writes. It shares the event
transaction by default. Its reset clears only the state it owns.

```rust
use suprnova::{Projector, Reactor, Model, FrameworkError, StoredEvent, attrs};

#[suprnova::model(
    table = "tally_totals", key_type = "String", timestamps = false,
    fillable = ["id", "total"]
)]
struct Total { pub id: String, pub total: i64 }

#[suprnova::projector]
#[derive(Default)]
struct Totals;

#[suprnova::async_trait]
impl Projector for Totals {
    fn name(&self) -> &'static str { "tally.totals" }
    fn handles(&self, fact: &StoredEvent) -> bool {
        fact.event_type == "tally.added"
    }
    async fn project(&self, fact: &StoredEvent) -> Result<(), FrameworkError> {
        if let Some(added) = fact.decode::<Added>()? {
            match Total::find(fact.aggregate_uuid.clone()).await? {
                Some(mut row) => {
                    row.total = row.total.checked_add(added.amount)
                        .ok_or_else(|| FrameworkError::bad_request("projected total is too large"))?;
                    row.save().await?;
                }
                None => {
                    Total::create(attrs! { id: fact.aggregate_uuid.clone(), total: added.amount }).await?;
                }
            }
        }
        Ok(())
    }
    async fn reset(&self) -> Result<(), FrameworkError> {
        Total::query().delete_all().await?;
        Ok(())
    }
}

#[suprnova::reactor]
#[derive(Default)]
struct Announce;

#[suprnova::async_trait]
impl Reactor for Announce {
    fn name(&self) -> &'static str { "tally.announce" }
    async fn react(&self, fact: &StoredEvent) -> Result<(), FrameworkError> {
        if fact.decode::<Added>()?.is_some() {
            println!("Committed tally event {}", fact.id);
        }
        Ok(())
    }
}
```

Create `tally_totals` in an application migration before persisting:

```sql
CREATE TABLE tally_totals (id VARCHAR(36) PRIMARY KEY, total BIGINT NOT NULL);
```

The attributes register `Default` handlers through inventory. Names are stable
checkpoint identities. Names must be ASCII, at most 191 bytes and cannot start
with `__`. Leading or trailing whitespace and control characters are rejected,
so checkpoint names stay distinct on every engine. Duplicate handler names fail. Handlers run in name order.

A reactor runs after commit. It never runs during replay. Use the stored event id
as an idempotency key for external effects. A reactor failure reports an error
without undoing the committed history. Reactors are direct after-commit effects;
queue a separate job when delivery needs durable retries.

## Queued projectors

Queued projectors must not read synchronous projectors' read models. Build each
projection from its own state and stored facts. Live persistence completes
synchronous writes before queue delivery. Replay follows that order within each
page: synchronous handlers receive every fact first, then queued handlers receive
every fact. Replay pages need not match the original persistence batches.

Replace `#[suprnova::projector]` on `Totals` with
`#[suprnova::projector(queued)]`. Run a [queue worker](queues.md). Each persistence
queues a `QueuedProjector` wake-up after commit. The worker type is registered by
the framework and retries failures up to five attempts with the queue backoff.

The job reads the stored history after its checkpoint in pages of 256 facts.
Writes and checkpoint advancement share a transaction. A duplicate wake-up skips
facts at or below that checkpoint. Shuffled wake-ups still apply facts in global
id order. `handles` avoids queueing irrelevant facts.

A queue push can fail after the history commits. The durable facts remain the
recovery source. Requeue a catch-up wake-up after restoring the queue:

```rust
use suprnova::{EventStore, FrameworkError, Queue, QueuedProjector};
async fn catch_up() -> Result<(), FrameworkError> {
    let job = QueuedProjector::new("tally.totals", EventStore::last_position().await?)?;
    Queue::push(job).await?;
    Ok(())
}
```

The queue wake-up and the database commit are separate operations. A process
failure between them requires this catch-up or a projector replay. Monitor queue
push errors and run catch-up after recovering a failed writer.

## Replay

A full replay calls `replay_started`, resets each selected read model and its
checkpoint, reads ordered pages, then calls `replay_finished`. A failed replay
rolls back the reset, writes and checkpoints. A successful replay emits
`ReplayFinished` after commit. Reactors are excluded.

```rust
use suprnova::{EventReplay, FrameworkError};
async fn rebuild() -> Result<(), FrameworkError> {
    EventReplay::projectors(["tally.totals"]).page_size(128).run().await?;
    EventReplay::all().run().await?;
    Ok(())
}
```

`EventReplay` is also `suprnova::event_sourcing::Replay`. `from(position)` resumes
strictly after that global event id and does not reset state. Use a checkpoint
from a prior run when resuming. A repeated resume skips facts already committed.

Replay holds the append lock for its transaction. Live persistence and queued
projection wait until it completes. Use replay as maintenance work on large
histories. Reads remain bounded by the page size, from one to ten thousand facts.
ORM writes advance [RenderCache generations](render-cache-generations.md) inside
the same transaction. Suppressing notifications does not suppress invalidation.

## Live signals from projection writes and ordinary models

Declare a [Live](live.md) stream on the page's component. A component named
`app.tally` can use a stream named `changes` and the topic `tally`.
Its rendering hook reloads the read model after a refresh. The dogfood page at
`/live/event-tally` shows this flow.

Declare the private topic in the application registry and authorize its audience
before resolving the publisher. A signed-in principal can observe this shared tally:

```rust
use suprnova::{FrameworkError, Gate, live::LiveRegistry};

fn registry() -> Result<LiveRegistry, FrameworkError> {
    Gate::define::<String, String>("live:topic.tally", |principal, _| {
        !principal.is_empty()
    });
    Ok(LiveRegistry::builder().topic("tally")?.build())
}
```

Include the page's component registration in the same builder. Bind the registry
at bootstrap as described in [Live topic signals](live.md#topic-signals).

Register a normal saved listener to signal a model write:

```rust
use std::sync::Arc;
use suprnova::{EventFacade, FrameworkError, Listener, LiveTopics};

struct TotalChanged;
#[suprnova::async_trait]
impl Listener<total::events::Saved> for TotalChanged {
    async fn handle(&self, _: &total::events::Saved) -> Result<(), FrameworkError> {
        LiveTopics::resolve()?.changed("tally", &["total"]).await
    }
}
async fn bind_total() {
    EventFacade::listen::<total::events::Saved, _>(Arc::new(TotalChanged)).await;
}
```

The same listener works when a projector saves `Total` or when a controller saves
it directly. It does not need an aggregate, a stored event or the event store
migration. An explicit call also signals without a model event. For example,
notify after an ordinary bulk write:

```rust
async fn clear_total() -> Result<(), FrameworkError> {
    suprnova::DB::transaction(|_| Box::pin(async {
        Total::query().update_all(suprnova::attrs! { total: 0i64 }).await?;
        LiveTopics::resolve()?.changed("tally", &["total"]).await?;
        Ok(())
    })).await
}
```

`changed` waits for the owning transaction's commit and discards rolled-back
changes. Requests and job attempts coalesce changes per topic with the union of
prop names. `batch(future)` coalesces another explicit unit of work.
`suppress(|| future)` keeps one final union per touched topic through replay.
Replay resolves the application's publisher and uses this shared suppression
scope, including in a worker. Register its topics and abilities during bootstrap.
It preserves ORM cache invalidation and carries no model values to the browser.
Live streams reload their server view after a topic change.

Once replay commits, an owned task keeps its final topic unions in publication
order. Cancelling the caller stops waiting and does not discard those changes.
A caller that waits receives the first publication error after every remaining
topic is attempted.

A manual transaction is not ambient state. Await identity capture when registering
a change on its handle:

```rust
async fn signal_manual_write() -> Result<(), FrameworkError> {
    let topics = LiveTopics::resolve()?;
    let tx = suprnova::DB::begin_transaction().await?;
    topics.changed_with_tx(&tx, "tally", &["total"]).await?;
    tx.commit().await
}
```

## Console commands

Run these through the [console binary](console.md) from the application
directory after migrating its tables:

```sh
cargo run --bin console -- event-sourcing:replay
cargo run --bin console -- event-sourcing:replay --projector tally.totals
cargo run --bin console -- event-sourcing:replay --projector tally.totals --from 120
cargo run --bin console -- event-sourcing:events 7d200fce-d107-4a12-8b9b-7e642209aa01
cargo run --bin console -- event-sourcing:snapshot 7d200fce-d107-4a12-8b9b-7e642209aa01
```

`replay` defaults to all registered projectors. Repeat `--projector` to select
several. `--from` is an exclusive global event position. Omitting it performs a
full reset and replay. `events` prints JSON lines with the original payload,
metadata and schema version. `snapshot` finds the aggregate by its stable name
in history, reconstructs it and writes a snapshot. Unknown names and invalid
positions fail before replay changes a read model.

## The dogfood tally

The application registers the framework migration and two application tables:
`event_tally_totals` for the read model and `event_tally_activity` for the reactor.
Its aggregate is `app::event_sourcing::TallyState`, and its stable fact is
`dogfood.tally.added`. The demo UUID is
`a9c9bce3-8b35-4530-b215-14cbb0d46f01`.

Sign in and open `/live/event-tally` in two windows. **Add one** sends a protected
POST to `/live/event-tally/add`. The aggregate records a fact. The projector saves
the new total and calls `LiveTopics::changed("event-tally", &["total"])`. The
reactor records activity once per stored event. The private `event-tally` topic
requires a signed-in principal. Both pages subscribe to the Live stream, and a
topic change runs the component's rendering hook to read the new total.
The form uses an ordinary POST because aggregate persistence owns its transaction.

The example uses a Live page. It needs no Inertia live binding. Rebuild its read
model and inspect the same history with:

```sh
cargo run --bin console -- event-sourcing:replay --projector dogfood.tally-total
cargo run --bin console -- event-sourcing:events a9c9bce3-8b35-4530-b215-14cbb0d46f01
cargo run --bin console -- event-sourcing:snapshot a9c9bce3-8b35-4530-b215-14cbb0d46f01
```

Replay rebuilds the total and sends one final topic change. It leaves reactor
activity in place and never records that activity again.

### Why Suprnova diverges

Spatie's package finds event handlers and public aggregate state through PHP
reflection. Suprnova uses serde state, explicit `AggregateRoot::apply` and stable
names registered at link time. Every aggregate requires a UUID. Projectors share
the persistence transaction by default. This gives failed projections the same
rollback boundary as their facts. Snapshots contain the explicitly serialized
state rather than a reflection-selected set of public properties.

## Next

Read [Events](events.md) for in-process listeners and [Workflows](workflows.md)
for durable step recovery.


---

<!-- /docs/filesystem -->

# Filesystem & Storage

Suprnova's storage facade gives you a single, named-disk API over local
filesystems, in-memory backends, and the major object stores (S3, Azure Blob,
Google Cloud Storage). Under the hood it is built on
[`opendal`](https://docs.rs/opendal) - but the consumer surface is shaped to
match Laravel's `Storage::disk(...)` calls, so PHP muscle memory translates
straight across.

```rust,no_run
use suprnova::{DiskExt, Storage};

# async fn doc() -> Result<(), suprnova::FrameworkError> {
Storage::register_fs("local", "./storage")?;
let disk = Storage::disk("local")?;

disk.put("notes/hello.txt", b"hello world".to_vec()).await?;
let bytes = disk.get("notes/hello.txt").await?;
assert_eq!(bytes, b"hello world");
# Ok(())
# }
```

## Registering disks

Every disk is registered once at boot via `Storage::register_*` and looked up
by name through `Storage::disk(name)`. There is no "default backend" the
others degrade into - each driver is a peer.

| Constructor                          | Backend                       | Feature             |
|--------------------------------------|-------------------------------|---------------------|
| `Storage::register_fs(name, root)`   | Local filesystem              | `filesystem`        |
| `Storage::register_memory(name)`     | In-process memory (tests)     | `filesystem`        |
| `Storage::register_s3(name, cfg)`    | Amazon S3 or S3-compatible (e.g. RustFS, MinIO, R2, B2) | `filesystem`        |
| `Storage::register_azblob(name, cfg)`| Azure Blob Storage            | `filesystem-azure`  |
| `Storage::register_gcs(name, cfg)`   | Google Cloud Storage          | `filesystem-gcs`    |
| `Storage::register_read_through(name, cfg)` | Read-through composite | `filesystem` |

`filesystem` is on by default; the Azure and GCS features are not. Turn one
on in your `Cargo.toml`:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", features = ["filesystem-gcs"] }
```

Without the feature, `register_azblob` / `register_gcs` and their config
structs do not exist - you get a compile error naming the missing item, not
a runtime failure.

Every constructor has a `_with` variant that hands you the `suprnova::opendal::Operator`
just before it lands in the registry so you can install retry/timeout/logging
layers around it:

```rust,ignore
use std::time::Duration;
use suprnova::opendal::layers::{LoggingLayer, RetryLayer, TimeoutLayer};
use suprnova::Storage;

Storage::register_fs_with("local", "./storage", |op| {
    op.layer(RetryLayer::new().with_max_times(3))
      .layer(TimeoutLayer::new().with_timeout(Duration::from_secs(30)))
      .layer(LoggingLayer::default())
})?;
```

The cloud constructors (`register_s3`, `register_azblob`, `register_gcs`)
apply a `RetryLayer` (3 attempts) by default since transient throttling /
5xx errors are routine on object stores. Use the `_with` variants when you
need full control.

The full set of opendal layers wired in by Suprnova is `RetryLayer`,
`TimeoutLayer`, `LoggingLayer`, `TracingLayer` (bridges to OTel via
`tracing-opentelemetry` when the framework's `otel` feature is on), and
`PrometheusClientLayer` (exports histograms and counters into a
`prometheus_client::registry::Registry` you own). Layer order matters -
the outermost layer wraps everything inside it - and the idiomatic stack
is `RetryLayer → TimeoutLayer → LoggingLayer` so a timed-out attempt
still logs and a retry covers transport failures.

Re-registering the same name replaces the previous operator and emits a
`warn!` log - disks are meant to be registered once at boot, and an
accidental duplicate could swap a production disk for a memory one. The
replacement still happens; the warning just makes the swap audible.

### Why Suprnova diverges

Laravel's `config/filesystems.php` lists every disk driver and you pick one
at runtime; nothing is compiled out. Suprnova gates Azure and GCS behind
features because in Rust the choice has a dependency cost, and this one has
a security dimension: both opendal service crates pull `rsa`, which carries
[RUSTSEC-2023-0071](https://rustsec.org/advisories/RUSTSEC-2023-0071) (the
Marvin timing attack) with no fixed release upstream. Making them opt-in
means an app that stores files locally or on S3 never carries that crate.

S3 is deliberately *not* gated - its signer never depended on `rsa`, so
gating it would break the most-used cloud backend and remove nothing.

### Atomic local writes

On a local disk, every operation that publishes bytes at a path publishes them
in one step. `disk.write(...)`, `disk.writer(...)`, and `disk.copy(...)` all
land in `<root>/.suprnova-atomic/` first, are flushed and synced there, and are
then renamed onto the target; `disk.rename(...)` is already a single step. A
concurrent reader therefore sees either the previous object or the finished new
one and never a partial length, and a process that dies mid-write leaves the
target untouched rather than truncated at the live path.

`append` is the one in-place operation, because staging an append would mean
copying the whole object first. That holds for the append that *creates* the
object as much as for every append after it, so two writers appending to the
same new object both land. Being in place is also what an append costs you: one
that fails or is aborted leaves the object behind, empty or short, exactly as an
append onto an existing object always has.

A conditional write is published with `link(2)` rather than a rename, which
keeps it a real exclusive create rather than a check followed by an overwrite:

```rust,ignore
// Exactly one of any number of racing callers gets Ok here. Every other one
// gets an `ErrorKind::ConditionNotMatch` error and writes nothing.
disk.write_with("locks/import.json", body).if_not_exists(true).await?;
```

That publish needs a filesystem with hard links. On FAT, exFAT, and some network
filesystems `link(2)` is unsupported, and a conditional write fails there rather
than silently degrading into a check followed by an overwrite - which would hand
you an exclusivity guarantee that does not hold. Every other operation is
unaffected.

Publishing by rename replaces the object's inode. A rewrite therefore does not
preserve the previous file's mode, owner, or hard links, and a reader holding
an open descriptor keeps reading the old content instead of seeing the new
bytes. That is the usual trade for atomic publishing, but it is a change if you
were relying on either.

A path that reaches the disk through a symlink the guard cannot resolve - a
dangling one, whose target does not exist - is refused rather than treated as a
free name to create. Creating through such a link would create the link's
target, anywhere on the host, so the guard cannot tell a harmless dangling link
apart from an escape and refuses both.

The `.suprnova-atomic` name is reserved at the root of every local disk. Any
path whose first component is that name is refused with a permission error, and
so is any path that *resolves* into the directory through a symlink, so you
cannot read another writer's staging file, write into the directory, or delete
it. The entry is filtered out of `files`, `directories`, `all_files`, and
`all_directories`, so it never shows up as an object. The name is exported as
`suprnova::ATOMIC_STAGING_DIR` because backup and sync tooling needs it:
exclude the directory the way you would exclude a lock directory. It holds
in-flight temp files plus whatever a process that died mid-publish left behind,
and nothing sweeps those, so a host in a crash loop will grow it until someone
empties it - which is safe to do while nothing is writing.

### Path-traversal guard

Local filesystem disks have a `PathGuardLayer` applied before any user-supplied
layers. A request like `disk.write("../escaped.txt", ..)` is rejected before
it reaches the OS - no `..` component or absolute prefix can escape the disk
root. Object stores and the in-memory backend do not get the guard (a key
like `../foo` is just an ordinary key character on those backends).

After rejecting `..` and absolute components, the guard canonicalizes the
local disk root and the requested on-disk target. Existing targets resolve
every symlink component; for a path that does not exist yet, the guard walks
up to and canonicalizes the nearest existing ancestor. The operation is
rejected if that resolved path lies outside the canonical root, so an in-root
symlink observed during validation cannot redirect a read, write, list, copy,
or rename outside the disk.

A check followed by a syscall by pathname is a race. Someone who can rename
entries inside the root could swap a checked directory for a symlink after the
check and redirect the syscall. On Unix the local disk does not act by
pathname. Every operation resolves its path one directory at a time, holds each
directory open, and names the next component relative to it, opening each
directory and the final entry with `O_NOFOLLOW`. Symlinks inside the root are
still followed, but by that walk: a link whose target leaves the root is
refused, and a symlink swapped in after the walk looked at a component fails
the operation. A write is published with `renameat` or `linkat` relative to its
held parent directory, so a directory swapped mid-upload cannot carry the
upload out of the root. On other platforms the guard is a check followed by the
operation; use OS-level isolation or a dedicated filesystem there when other
principals can change the storage tree concurrently.

Streaming writers, listers, and copiers perform the resolved-path check once,
immediately before their first backend I/O, so each chunk or item does not
block on filesystem canonicalization. On Unix the directory-relative walk
still runs at publish time, which is what keeps a long upload confined.
Copier and writer aborts always forward cleanup to their backends, even before
activation or when validation can no longer complete.

## The Laravel-shape disk surface

`Storage::disk(name)` returns a `suprnova::opendal::Operator` directly so you
can use its full streaming surface (`writer`, `reader`, `presign_read`, `list`,
`stat`, ...). On top of that, the [`DiskExt`] trait - blanket-implemented on
`Operator` and re-exported as `suprnova::DiskExt` - adds every Laravel
convenience method you'd reach for through `Storage::disk('local')->...`.

Bring it into scope with `use suprnova::DiskExt;`.

### Existence checks

```rust,ignore
disk.exists("a.txt").await?;        // raw opendal
disk.missing("a.txt").await?;       // negation
disk.file_exists("a.txt").await?;   // file only (not a directory)
disk.file_missing("a.txt").await?;
disk.directory_exists("dir/").await?;
disk.directory_missing("dir/").await?;
```

### Reading and writing

| Laravel name | Rust-native equivalent | Note |
|--------------|------------------------|------|
| `get(path)`  | `read(path)`           | `get` returns `Vec<u8>`; `read` returns opendal's `Buffer`. |
| `put(path, contents)` | `write(path, contents)` | Both accept any `Into<Bytes>`. |
| `json::<T>(path)` | - | Reads + deserializes via serde_json. |
| `put_json(path, &value)` | - | Pretty-prints via serde_json. |
| `prepend(path, data)` | - | Joins with `\n`. Use `prepend_with_separator` for a custom join. |
| `append(path, data)`  | - | Joins with `\n`. Use `append_with_separator` for a custom join. |

`prepend` and `append` create the file if it does not yet exist, so they are
safe as the first write to a log file.

### Metadata

```rust,ignore
let bytes  = disk.size("a.bin").await?;          // u64
let when   = disk.last_modified("a.bin").await?; // Option<DateTime<Utc>>
let mime   = disk.mime_type("a.bin").await?;     // Option<String>
let digest = disk.checksum("a.bin", ChecksumAlgorithm::Sha256).await?;
```

`mime_type` first asks the backend - S3, Azure, and GCS pass the stored
`Content-Type` through. If the backend does not have one, it sniffs the first
16 KiB via the `infer` crate. `Ok(None)` is reserved for unrecognised binary
blobs.

`checksum` supports `Md5`, `Sha1`, and `Sha256` via [`ChecksumAlgorithm`].
MD5 and SHA-1 are included for parity with Laravel and object-store ETags;
choose SHA-256 for any new integrity check.

### Listing

```rust,ignore
let files = disk.files("docs", false).await?;     // top-level files
let all   = disk.all_files("docs").await?;        // recursive
let dirs  = disk.directories("docs", false).await?;
let all   = disk.all_directories("docs").await?;
```

All four return sorted `Vec<String>` so callers can rely on stable ordering
across backends. Directories are filtered out of `files`, and vice versa.
Directory paths are returned **without** a trailing slash (`"docs/sub"`) to
match Laravel's `Storage::directories()` output - opendal's underlying
`list` reports `"docs/sub/"` but we strip the slash for parity.

### Mutating directories and files

| Laravel name           | opendal native        |
|------------------------|-----------------------|
| `make_directory(path)` | `create_dir(path)`    |
| `ensure_directory_exists(path)` | `create_dir(path)` unless the directory exists |
| `delete_directory(p)`  | `delete_with(p).recursive(true)` |
| `move_to(from, to)`    | `rename(from, to)`    |

`make_directory` and `ensure_directory_exists` take a directory path with or
without its trailing slash, as Laravel does. opendal's `create_dir` accepts a
directory only when the path ends in `/`, so the two add the slash for you. An
empty path, the root, reaches `create_dir` unchanged. `ensure_directory_exists`
checks for the directory first and succeeds when it is already there, so you
can call it before every write into the directory:

```rust,ignore
disk.ensure_directory_exists("exports/2026").await?;
disk.put("exports/2026/report.csv", csv).await?;
```

`move_to` falls back to `copy + delete` if the backend doesn't support
rename, and to `read + write + delete` if it doesn't support copy either -
so it works against the in-memory driver used in tests as well as against
production backends.

### Pre-signed URLs

```rust,ignore
let read_url = disk.temporary_url("uploads/a.pdf", Duration::from_secs(900)).await?;
let upload = disk.temporary_upload_url("uploads/new.pdf", Duration::from_secs(900)).await?;
// upload.url, upload.method ("PUT"), upload.headers
```

`temporary_url` returns the URL as a `String`. `temporary_upload_url` returns
a `TemporaryUploadUrl` with the URL, the HTTP method, and the headers the
signature covers. Send the upload with that method and every one of those
headers: some backends refuse an upload without them. Azure Blob requires
`x-ms-blob-type`, and an S3 bucket set up for server-side encryption requires
its encryption headers. The value serializes to
`{ "url": .., "method": .., "headers": { .. } }`, so a handler can return it to
the browser as JSON, the shape Laravel's `temporaryUploadUrl` returns.

Both are backed by `Operator::presign_read` and `presign_write`, so they error
with an `Unsupported` message on backends that do not implement presigning
(the in-memory and local-filesystem drivers fall in this bucket; S3, Azure
Blob, and GCS support it).

#### Upload URLs from your own callback

A disk that does not presign can still hand out upload URLs. Give it a
callback with `Storage::build_temporary_upload_urls_using`, for example one
that points at a route of your application that takes the upload. The
callback receives the path and the lifetime and returns the
`TemporaryUploadUrl`:

```rust
use std::collections::BTreeMap;
use std::time::Duration;
use suprnova::{DiskExt, Storage, TemporaryUploadUrl};

# async fn doc() -> Result<(), suprnova::FrameworkError> {
Storage::register_fs("local", "./storage")?;
Storage::build_temporary_upload_urls_using("local", |path, lifetime| {
    Ok(TemporaryUploadUrl {
        url: format!(
            "https://example.com/uploads/{path}?expires={}",
            lifetime.as_secs()
        ),
        method: "PUT".to_owned(),
        headers: BTreeMap::new(),
    })
})?;

assert!(Storage::provides_temporary_upload_urls("local")?);
let upload = Storage::disk("local")?
    .temporary_upload_url("avatars/7.png", Duration::from_secs(300))
    .await?;
assert!(upload.url.starts_with("https://example.com/uploads/avatars/7.png"));
# Ok(())
# }
```

The callback comes first on every disk: a read-through disk and a disk that
presigns by itself, such as S3, answer from the callback too. Setting a
callback again replaces the one before, and the disk keeps its public URL.
Take the disk with `Storage::disk` after you set the callback: a handle you
took before keeps answering as it did. Registering the disk again drops the
callback.

`Storage::provides_temporary_upload_urls(disk)` tells you whether
`temporary_upload_url` can answer on a disk: it is `true` when the disk has a
callback or its backend presigns writes. A read-through disk answers for its
primary.

##### Why Suprnova diverges

Laravel's local and read-through disks ask the callback first, while its S3
disk keeps its own presigning and ignores the callback. Suprnova applies one
rule to every disk, so the callback you set is the one that answers.

### Public URLs

A pre-signed URL expires. For a file that is meant to be public, give the
disk a public base URL and ask `Storage::url` for the link.

```rust,ignore
use suprnova::Storage;

Storage::register_fs("public", "./storage/public")?;
Storage::set_public_url("public", "https://cdn.example.com/files")?;

let url = Storage::url("public", "avatars/7.png")?;
assert_eq!(url, "https://cdn.example.com/files/avatars/7.png");
```

`Storage::set_public_url(disk, base_url)` takes the name of a registered
disk and the place where the root of that disk is served from. The base URL
is an absolute URL or a path of your own host, such as `/storage`. A path
of your own host gets the public root in front, so behind a proxy that
serves the application under `/billing` the link is
`/billing/storage/avatars/7.png`; an absolute base is left as it is.
`Storage::url(disk, path)` joins the base URL and the path and returns a
`String`. It does not ask the disk, so it returns a URL for a file that
does not exist.

`Storage::url` takes the name of the disk, not the `Operator` that
`Storage::disk` returns, because the operator carries no name.

`Storage::url` writes each path segment so that it stays one segment. Every
character that a URL gives a meaning to becomes `%XX`, so `c++ notes.pdf`
is written `c%2B%2B%20notes.pdf`.

Both functions return an error in these cases:

- `set_public_url` is called for a disk that is not registered.
- The base URL has a scheme other than `http` or `https`, no host, a user or
  a password, a query or a fragment, a backslash, a `.` or `..` segment, or
  a space or control character. A path base must begin with one `/`, not
  two. The error does not repeat the URL, because a URL can carry a token.
- `url` is called for a disk with no public base URL. A private disk hands
  out no link that can be guessed. Use `temporary_url` for those files.
- The path is empty or has a `.` or `..` segment.

`Storage::url` doesn't serve the files. A local disk needs a route, such as
one that returns `Storage::response`, or a web server in front of its
directory. A bucket needs to be public or behind a CDN.

### Serve a file from a disk

`Storage::download(disk, path, name)` and `Storage::response(disk, path,
name)` return a file on a disk as an HTTP response. They match Laravel's
`Storage::disk($disk)->download($path, $name)` and
`Storage::disk($disk)->response($path, $name)`.

```rust
use suprnova::{HttpResponse, Request, Response, Storage};

// The browser saves the file.
pub async fn invoice(req: Request) -> Response {
    let number = req.param("number")?;
    Storage::download(
        "local",
        &format!("invoices/{number}.pdf"),
        Some("Factura Pérez.pdf"),
    )
    .await
    .map_err(HttpResponse::from)
}

// The browser shows the file.
pub async fn logo(_req: Request) -> Response {
    Storage::response("s3", "brand/logo.png", None)
        .await
        .map_err(HttpResponse::from)
}
```

Both read the file through the disk, so they work on every driver. A local
disk keeps its [path-traversal guard](#path-traversal-guard): a path such as
`../secret` is refused before anything is read. That makes these the forms
to use when a request names the file. S3, Azure Blob, GCS, and in-memory
disks have no local path, and they're read the same way.

The response follows the same rules as `HttpResponse::download` and
`HttpResponse::file`:

- `download` sends `Content-Disposition: attachment` and `response` sends
  `inline`. The filename is `name`, or the last segment of `path` when
  `name` is `None`. Non-ASCII names are written per RFC 6266, as described
  in [Filenames and `Content-Disposition`](responses.md#filenames-and-content-disposition).
- The `Content-Type` comes from the extension of `path`, or is
  `application/octet-stream` when the extension is unknown. A content type
  stored with the object is not used, because whoever uploaded the object
  chose it.
- A file of 1 MiB or less is read whole. A larger file is streamed from the
  disk in 64 KiB chunks. Both carry a `Content-Length`.

You receive `Last-Modified` when the disk reports a modification time, and
`Accept-Ranges: bytes`. Your GET range requests receive `206` with the
selected bytes and `Content-Range`, or `416` with `Content-Range: bytes
*/<size>` when the range is unsatisfiable. You read only the selected range
through the disk, so its path guard still applies.

You use `Storage::download_with(disk, path, name, headers, disposition)` or
`Storage::response_with(disk, path, name, headers, disposition)` to pass
extra headers and select `ContentDisposition::Inline` or
`ContentDisposition::Attachment`. Your `Content-Type` and `Cache-Control`
are kept. You cannot override the body's length or range metadata.

The errors map to these status codes:

| Case | Status |
|---|---|
| Nothing at `path`, or `path` is a directory | `404` |
| The disk refuses the path, such as `..` on a local disk | `403` |
| The disk isn't registered, or the read fails | `500` |

The `404` and `403` messages don't name the path.

## Cross-disk streaming copy

`copy_between_disks(src, src_path, dest, dest_path)` streams the source
object into the destination in 64 KiB chunks, regardless of the backend
pair. Source and destination can be backed by *any* opendal driver - local
filesystem to S3, S3 to Azure Blob, in-memory to GCS, and so on.

```rust,ignore
use suprnova::filesystem::streaming::copy_between_disks;

Storage::register_fs("local", "./storage")?;
Storage::register_memory("scratch");
let bytes = copy_between_disks("local", "uploads/big.bin", "scratch", "big.bin").await?;
```

You also call `Storage::copy_to_disk(source, source_path, destination,
destination_path).await?` or `Storage::move_to_disk` with those same arguments.
You pass a string name or an owned or borrowed `Operator` for either disk,
through `DiskReference`. You receive the transferred byte count as `u64`.
You keep the source after a copy. You delete it only after a move finishes
copying and closing the destination writer. You receive an error for a missing
disk, a failed read or write, or a failed source deletion. You keep both copies
when deletion fails. You cannot copy or move a file onto itself on the same
operator.

```rust,ignore
let archive = Storage::disk("archive")?;
Storage::copy_to_disk("local", "report.pdf", &archive, "copy.pdf").await?;
Storage::move_to_disk("local", "report.pdf", archive, "report.pdf").await?;
```

You abort the destination writer before a copy error propagates. The backend
cleans up its staged writes. On a backend that writes in place, you can still
see partial bytes; abort cannot restore the previous contents.

## Read-through disks

A read-through disk pairs a fast *primary* with a slower *fallback* and moves
objects from the second to the first as they are read. Point the primary at
the store you are migrating to and the fallback at the one you are migrating
from, and the working set crosses over under real traffic - no maintenance
window, no bulk copy of objects nobody asks for.

```rust,ignore
use suprnova::{ReadThroughConfig, S3Config, Storage};

Storage::register_s3("new-store", S3Config { bucket: "assets-2".into(), ..Default::default() })?;
Storage::register_s3("legacy-store", S3Config { bucket: "assets-1".into(), ..Default::default() })?;

Storage::register_read_through(
    "assets",
    ReadThroughConfig {
        primary: "new-store".into(),
        fallback: "legacy-store".into(),
        ..Default::default()
    },
)?;

let assets = Storage::disk("assets")?;
// Reads `logo.png` from `legacy-store` and writes it to `new-store` on the way
// out. Every later read is served by `new-store`.
let bytes = assets.read("logo.png").await?;
```

`Storage::disk("assets")` returns an ordinary `Operator`, so every method on
it and every `DiskExt` convenience works unchanged.

### Which disk answers which operation

| Operation | Disk |
|---|---|
| `read` | Primary if it holds the object, otherwise the fallback - and, unless `copy` is `false`, the fallback hit is promoted |
| `exists`, `size`, `last_modified`, `mime_type`, `stat` | Primary if it holds the object, otherwise the fallback |
| `write`, `make_directory` | Primary only |
| `files`, `directories`, `list` | Primary only - fallback entries are invisible to a listing |
| `delete` | Both, fallback first |
| `copy`, `rename` / `move_to` | Primary if it holds the source, otherwise streamed across from the fallback; a `rename` also deletes the fallback source |
| `temporary_url` | Primary if it holds the object, otherwise the fallback |
| `temporary_upload_url` | Primary only - an upload has to land where writes land; a callback from `Storage::build_temporary_upload_urls_using` answers ahead of the primary |

Listing is primary-only by design. A union listing would have to reconcile
paging and ordering across two backends, and it would report objects that a
later listing no longer returns once they are promoted. Use
`Storage::disk("legacy-store")` directly when you need to enumerate what is
left on the fallback.

Delete removes the object from both disks. If it only removed the primary
copy, the next read would promote the fallback copy straight back. The
consequence is that a read-through disk over a read-only fallback cannot
delete: the fallback delete fails and the error reaches you.

### When a promotion fails

By default a promotion failure is logged at `warn` and swallowed. You still
receive the bytes you asked for; the disk simply degrades to reading the
fallback every time until the primary is writable again. Set
`throw_on_promotion_failure: true` when a silent loss of promotion would hide
a fault you need to see - a migration you are trying to finish, for instance:

```rust,ignore
Storage::register_read_through(
    "assets",
    ReadThroughConfig {
        primary: "new-store".into(),
        fallback: "legacy-store".into(),
        throw_on_promotion_failure: true,
        ..Default::default()
    },
)?;
```

Registration rejects a configuration that cannot work: an empty `primary` or
`fallback`, a pair that names the same disk twice, a disk that names itself,
or a name that is not registered. Each returns a `FrameworkError` naming the
problem, and no disk is registered.

### Reading without promoting

Set `copy: false` to serve fallback hits without writing them through:

```rust,ignore
Storage::register_read_through(
    "assets",
    ReadThroughConfig {
        primary: "cache-store".into(),
        fallback: "origin-store".into(),
        copy: false,
        ..Default::default()
    },
)?;
```

The disk then reads like a transparent overlay: the primary answers what it
holds, the fallback answers everything else, and nothing moves between them.
Use it when the primary is a small cache you do not want a one-off read to
fill, or when the fallback is authoritative and the primary only ever holds
objects you put there deliberately.

The flag governs read-time promotion and nothing else. Writes, deletes,
metadata, listings, and the destinations of `copy` and `rename` all behave
exactly as they do with promotion on - so a `copy: false` disk still lands a
copied or moved object on the primary. Because nothing is written back, a
read with `copy: false` fetches only the range you asked for rather than the
whole object.

### Copying and moving across the fallback

`copy` and `rename` resolve the source against the primary first. When only
the fallback holds it, the object is streamed across in 64 KiB chunks and the
destination lands on the primary:

```rust,ignore
let assets = Storage::disk("assets")?;

// `logo.png` lives only on `legacy-store`. The copy streams it across and
// writes `branding/logo.png` to `new-store`; the legacy object stays put.
assets.copy("logo.png", "branding/logo.png").await?;

// A move does the same and then deletes the legacy source.
assets.rename("logo.png", "branding/logo.png").await?;
```

A move deletes the fallback source on both paths - whether the primary held
the source or not. Without that, the next read would promote the fallback
copy back and undo the move.

The two paths differ in when they delete it, and the difference is what a
failed move leaves behind:

- The primary held the source. The fallback copy goes first, before the
  rename. While the primary holds the path, the fallback's copy is unreachable
  through this disk, so removing it first changes nothing you can observe - and
  if the delete fails, nothing has moved yet. Retry the move. If instead the
  delete succeeded and the rename then failed, the fallback holds nothing for
  that path, the destination is unwritten, and the primary still holds the
  source - so a retry takes this same path and renames again. The failure costs
  the cold copy and nothing else.
- Only the fallback held it. The delete can only come after the destination is
  in place, so a move that fails on the delete leaves the destination written
  and the source still on the fallback. Retry the move; the source is now on
  the primary, so the retry takes the first path.

Either way a failed move is safe to retry, and the destination you end up with
is the object the move started from.

Conditions travel with the operation on the streaming path too. `if_not_exists`
becomes a conditional write, so a guarded copy or move still refuses an
existing destination rather than clobbering it, and a copy that names a source
version gets that version out of the fallback. A copy's `if_match` is the one
exception: it is a condition the backend applies inside its own copy, which is
the call this path cannot make, so it is refused with an `Unsupported` error
naming the condition rather than quietly ignored.

That makes conditions the one place where which disk holds the source shows
through. A local directory advertises `copy` and `rename` but neither of their
conditional forms, so `copy_with(a, b).if_not_exists(true)` succeeds when only
the fallback holds `a` (it becomes a conditional write) and is refused with
`Unsupported` when the primary holds it. Check the condition you need against
the primary driver rather than assuming it holds for every object on the disk.

A move the primary would refuse is refused before anything is deleted. A
primary with no `rename` at all, a guarded move onto a primary with no
conditional `rename`, and a guarded move onto a destination that already exists
all fail with the fallback source still in place - a move that never happens
must not cost you the cold copy.

If the stream fails partway, the writer is aborted and a destination the
transfer created is deleted before the error reaches you, so a failed transfer
is not observable as a truncated object. A destination that was already there
is left alone - a failed copy must not be the thing that destroys an object it
never wrote. A local-filesystem primary honors that too, because it stages the
transfer under `.suprnova-atomic/` and only renames on success; aborting the
writer removes the staged file, so a failed transfer leaves neither a partial
destination nor a leftover temp file.

### Versioned and conditional reads

A read that carries a version or an `If-Match`, `If-None-Match`,
`If-Modified-Since`, or `If-Unmodified-Since` condition is passed on with that
condition intact, so the answer means what you asked it to mean. Such a read
is served but never promoted: writing an old version or a validator-matched
body to the primary would publish it as the live object, and every later
plain read would get it.

Which disk answers one is decided the usual way. The first probe is an
ordinary existence check, so a read-through disk delegates a versioned or
conditional read to the primary whenever the primary holds the path at all;
it reaches the fallback only when the primary does not.

The primary also decides which of these a read-through disk accepts at all,
because the primary's reader is opened first. A versioned read against a
read-through disk whose primary is a local directory is rejected before it
reaches the fallback, since a local directory has no versions.

### Why Suprnova diverges

Laravel builds a read-through disk from a `config/filesystems.php` entry whose
`primary` and `fallback` keys accept either a disk name or an inline driver
config. Suprnova takes disk names only, because disks here are registered by
typed constructors rather than described by arrays - register the inner disk
first, then name it.

Laravel's promotion re-checks the primary after reading the fallback, which
makes a concurrent writer win. Suprnova keeps that check and publishes the
promotion atomically, which Laravel does not. On a local-filesystem primary
the bytes are staged at a temporary sibling and renamed into place; writing
them straight to the target would leave a growing, half-written file visible
for the length of the write, and a read-through disk routes readers by
exactly that existence check. On a primary without a rename - in-memory, S3,
Azure Blob, GCS - a write is already a single indivisible publish, so the
promotion writes the target directly, conditional on the object not already
existing so two concurrent readers do not both promote.

That condition is the part a staged promotion cannot have: the staging path is
unique, so a no-clobber condition on it would be vacuous, and the target is
published by a rename that overwrites. A read-through disk on a
local-filesystem primary therefore trades it away - a write that lands on the
primary in the moment between the promotion's last existence check and its
rename is overwritten by the promoted copy. On a primary without a rename the
condition holds and no such window exists.

The staging object is a real entry on the primary while it lasts, so a listing
taken mid-promotion can show a `.suprnova-promote-<id>.tmp` sibling. A read
that completes, fails, or gives up tries to remove its own sibling, and logs a
warning if that delete fails rather than failing the read. Nothing sweeps a
sibling left by a failed delete, a process that crashed, or a read future
cancelled mid-promotion: those have to be removed by hand.

A promoting read streams the cold object from the fallback into the primary,
then answers from the primary. Nothing holds the whole object in memory, but
the first read of a cold object waits for the whole transfer, even when it
asks for a small range. A read that is not promoted fetches only the range it
asked for: a read with `copy: false`, a versioned or conditional read, and the
rest of a read whose promotion failed. A chunked read does not retry a failed
promotion for every chunk. A fallback that answers a range with more bytes than
the range holds, the way a server that ignores `Range` does, fails the read
after one chunk instead of being read to the end. On S3, Azure Blob, and GCS
the service refuses such a response before reading its body, for an
open-ended range as well.

Laravel hands back the fallback's own stream when `copy` is `false` and
buffers through `php://temp` when it is `true`. Suprnova narrows the fallback
fetch to the requested range when nothing is promoted, and streams the
promotion instead of buffering it.

A delete or a move of a path that overlaps a promotion of the same path is not
undone by it, on one node or across several. Within one process, the promotion
publishes only if no delete or move of its path ran after it started fetching;
otherwise it discards its staged copy. Across processes nothing is shared, so
the storage decides: a delete and a move remove the fallback copy before the
primary copy, and a promotion checks the fallback again just before it
publishes and once more after. When the first check finds the object gone or
changed, the promotion discards its unpublished bytes. When the second one
does, the promotion withdraws the copy it published. A cancelled read still
finishes that check.

Each check compares the fallback object's ETag or version, or its
modification time and length. A length alone never counts: a same-size
overwrite keeps it. A fallback that reports none of the others - the
in-memory disk, and so `Storage::fake()` - is checked by content instead. The
promotion hashes the bytes it streams, and each check reads the object again
and compares hashes, so a promotion from such a fallback reads the object up
to three times. A modification time is only as fine as the fallback records
it, so a same-size overwrite within one tick of a local disk's clock reads as
unchanged.

A withdrawal never deletes a writer's object. It removes only the exact copy
the promotion wrote, and that needs a primary that names each write by version
and can delete one version, such as an S3 bucket with versioning enabled. On
any other primary - a local directory, memory, or an unversioned bucket - the
promotion keeps its copy and logs a warning, because OpenDAL has no delete
that checks what the path holds. Three limits remain. On those primaries, a
delete on another node that completes in the moment between the promotion's
last check and its publish can leave the promoted copy on the primary. Between
the publish and the check after it, a reader on another node can see the
object for a moment. A process that stops between the two leaves its copy on
the primary.

A versioned or conditional read reaches the fallback even when the primary
cannot express the version or condition. The primary's refusal applies only
when the primary holds the object.

Laravel's cross-fallback `copy` and `move` also buffer the source through
`php://temp`. Suprnova streams it in 64 KiB chunks instead, because the
fallback is where the large, rarely-touched objects live, and deletes a
half-written destination before returning the error. Two more differences
follow from OpenDAL. Deleting a path that is not there counts as success, so a
move clears the fallback source without first checking that it exists. And
OpenDAL carries conditions on `copy` and `rename` that Flysystem has no
equivalent for, so Suprnova has to decide what each one means when the source
is only on the fallback: `if_not_exists` and a copy's source version are
honored, and a copy's `if_match` is refused rather than dropped.

Before it deletes anything, a move checks that the primary accepts the
destination: a local primary's path guard refuses a destination outside its
root or inside its staging directory, and a refused move leaves both disks as
they were.

Laravel deletes the fallback source after the move on both paths. Suprnova
deletes it first when the primary holds the source, because the two orders
differ under a retry: the source is unreachable through the disk either way,
but deleting last means a move that lost its delete to a transient fault comes
back as a move whose source is now fallback-only, and streams the fallback's
stale copy over the destination the first attempt already wrote correctly.

## Registry hygiene

```rust,ignore
let removed = Storage::forget("local");  // bool: was any named disk present?
Storage::forget(["cache", "archive"]);
Storage::purge("uploads");               // drop one named disk
Storage::purge_all();                    // drop every disk
Storage::purge_all();                    // drop every disk
Storage::set("archive", ready_disk);     // store a ready-made Operator
let names = Storage::disks();            // Vec<String>, sorted
```

You pass one name, an array, a vector, or a slice to `forget` through
`DiskNames`. You receive `true` when at least one disk was removed, and `false`
for missing names or an empty list. You use `purge(name)` for Laravel's
named purge and `purge_all()` for every disk; Rust does not overload
functions by argument count, so the two forms carry two names. You store a
ready-made operator with `set`; you
replace the previous disk of that name and clear its old public URL. You keep
any operator handle you already obtained usable after removal or replacement.

These mirror Laravel's `FilesystemManager::forgetDisk` / `purge` and are
useful for configuration reloads and admin dashboards. They are not
test-only: production code occasionally needs to drop and re-register a
disk at runtime (e.g. after a secrets rotation).

## Testing

`Storage::fake()` returns a guard that:

1. Acquires a process-global mutex so concurrent `#[tokio::test]` cases do
   not race on the shared registry, and
2. Resets the registry on construction and on drop, leaving the suite in a
   clean state for whichever test runs next.

A `"default"` memory disk is pre-registered for convenience.

```rust,ignore
use suprnova::filesystem::testing::DiskAssertExt;
use suprnova::{DiskExt, Storage};

#[tokio::test]
async fn stores_and_asserts() {
    let _guard = Storage::fake();
    Storage::register_memory("uploads");
    let disk = Storage::disk("uploads").unwrap();

    disk.put("a.txt", b"hello".to_vec()).await.unwrap();

    disk.assert_exists("a.txt").await;
    disk.assert_contents("a.txt", b"hello").await;
    disk.assert_missing("not-here.txt").await;
    disk.assert_count("", 1, false).await;
    disk.assert_directory_empty("docs/").await;
}
```

The five assertion helpers - `assert_exists`, `assert_contents`,
`assert_missing`, `assert_count`, `assert_directory_empty` - are exposed via
the [`DiskAssertExt`] trait, gated on `#[cfg(any(test, feature = "testing"))]`
so production code cannot reach for them.

## Parity quick reference

| Laravel `Storage::disk(...)->...`     | Suprnova                                                 |
|---------------------------------------|----------------------------------------------------------|
| `exists($path)`                       | `disk.exists(path)`                                      |
| `missing($path)`                      | `disk.missing(path)`                                     |
| `fileExists($path)` / `fileMissing`   | `disk.file_exists(path)` / `file_missing(path)`          |
| `directoryExists($p)` / `directoryMissing` | `disk.directory_exists(p)` / `directory_missing(p)` |
| `get($path)`                          | `disk.get(path)` (`Vec<u8>`)                             |
| `json($path)`                         | `disk.json::<T>(path)`                                   |
| `put($path, $contents)`               | `disk.put(path, bytes)`                                  |
| `prepend($path, $data)`               | `disk.prepend(path, data)`                               |
| `append($path, $data)`                | `disk.append(path, data)`                                |
| `size($path)`                         | `disk.size(path)`                                        |
| `lastModified($path)`                 | `disk.last_modified(path)`                               |
| `mimeType($path)`                     | `disk.mime_type(path)`                                   |
| `checksum($path, ['checksum_algo' => 'sha256'])` | `disk.checksum(path, ChecksumAlgorithm::Sha256)` |
| `files($dir, $recursive)`             | `disk.files(dir, recursive)`                             |
| `allFiles($dir)`                      | `disk.all_files(dir)`                                    |
| `directories($dir, $recursive)`       | `disk.directories(dir, recursive)`                       |
| `allDirectories($dir)`                | `disk.all_directories(dir)`                              |
| `makeDirectory($path)`                | `disk.make_directory(path)`                              |
| `File::ensureDirectoryExists($path)`  | `disk.ensure_directory_exists(path)`                     |
| `deleteDirectory($path)`              | `disk.delete_directory(path)`                            |
| `move($from, $to)`                    | `disk.move_to(from, to)` (or opendal-native `rename`)    |
| `copy($from, $to)`                    | `disk.copy(from, to)` (opendal-native)                   |
| `delete($path)`                       | `disk.delete(path)` (opendal-native)                     |
| `temporaryUrl($path, $expiry)`        | `disk.temporary_url(path, expire)` (or opendal-native `presign_read`) |
| `temporaryUploadUrl($path, $expiry)`  | `disk.temporary_upload_url(path, expire)` (or opendal-native `presign_write`) |
| `buildTemporaryUploadUrlsUsing($cb)`  | `Storage::build_temporary_upload_urls_using(disk, callback)` |
| `providesTemporaryUploadUrls()`       | `Storage::provides_temporary_upload_urls(disk)`          |
| `download($path, $name)`              | `Storage::download(disk, path, name)`                    |
| `response($path, $name)`              | `Storage::response(disk, path, name)`                    |
| `Storage::fake()`                     | `Storage::fake()`                                        |
| `Storage::disk()->assertExists()`     | `disk.assert_exists(path).await`                         |
| `FilesystemManager::forgetDisk($n)`   | `Storage::forget(name)`                                  |
| `FilesystemManager::purge()`          | `Storage::purge(name)` and `Storage::purge_all()`                                       |

## Configuration

You register disks in two ways. In code, `bootstrap()` calls
`Storage::register_*` and you address a disk by name at the call site
(`Storage::disk("public")`). From the environment, the server registers one
S3 disk named `s3` when it boots, beside the queue, the rate limiter and the
mail transport.

### An S3 disk from the environment

You configure the `s3` disk with `S3_BUCKET` or its Laravel alias
`AWS_BUCKET`. The server registers it under `suprnova::ENV_S3_DISK` at boot.
When neither bucket is set, you get no environment disk. A blank value
counts as unset. Each `S3_` value wins over its AWS alias.

| Variable | Meaning |
|----------|---------|
| `S3_BUCKET`, `AWS_BUCKET` | The bucket. Without either there is no disk. |
| `S3_REGION` | The region. The driver needs one. When `S3_REGION` is not set, `AWS_DEFAULT_REGION` is read, then `AWS_REGION`. A service that is not AWS takes any name, such as `us-east-1` or `auto`. |
| `S3_ENDPOINT`, `AWS_ENDPOINT` | The endpoint of a service that is not AWS: MinIO, RustFS, R2, B2. |
| `S3_ACCESS_KEY`, `S3_SECRET_KEY` | The keys. You use `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` when the corresponding S3 name is unset. You set both effective keys or neither. |
| `S3_ROOT` | A prefix inside the bucket. Every path is under it. |
| `S3_PUBLIC_URL`, `AWS_URL` | The public base URL of the disk, as `Storage::set_public_url` takes it. See [Public URLs](#public-urls). |
| `S3_USE_PATH_STYLE_ENDPOINT`, `AWS_USE_PATH_STYLE_ENDPOINT` | You set `true` for endpoint/bucket paths or `false` for bucket hostnames. With neither set, you keep path-style URLs. An invalid value fails boot. |

With no keys set, the driver uses the default credential chain of AWS. That
chain reads `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, the profile and
the role of the instance.

```env
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=<access key>
S3_SECRET_KEY=<secret key>
S3_BUCKET=local
S3_REGION=us-east-1
S3_PUBLIC_URL=http://localhost:9000/local
```

```rust,ignore
use suprnova::{DiskExt, Storage};

let disk = Storage::disk("s3")?;
disk.put("reports/2026.pdf", bytes).await?;
```

The server does not boot when the variables describe no usable disk. The
cases are no region, one key without the other, a driver that refuses the
configuration, and an `S3_PUBLIC_URL` that is not a valid base URL. No error
repeats the value of a variable.

If your bootstrap already registered a disk named `s3`, that disk stays and
the variables are not read. Your registration is a decision, and a fault in
variables that describe nothing in use must not stop the boot.

To register the environment's disk under a name of your own, call
`S3Config::from_env()`. It returns `Ok(None)` when neither `S3_BUCKET` nor `AWS_BUCKET` is set.

```rust,ignore
use suprnova::{S3Config, Storage};

if let Some(config) = S3Config::from_env()? {
    Storage::register_s3("uploads", config)?;
}
```

The disk exists after the server has booted its drivers. A `booted` callback
runs before that, and the console binary boots no driver of the environment.
If a callback or a console command needs the disk, call
`suprnova::filesystem::bootstrap_from_env()?` at the end of your own
bootstrap, after you register your disks and set the default disk: it
checks the default disk too, so a call before the disk is registered
fails.

Each driver is a peer. Azure Blob and GCS disks have no environment
variables: register them in code.

### The default disk

`FILESYSTEM_DISK` names the application's default disk, and
`Storage::default_disk()` returns it. A name set in code with
`Storage::set_default_disk` wins over the variable, the way a disk the
bootstrap registers wins over the one the environment describes:

```rust
use suprnova::Storage;

// bootstrap.rs
Storage::register_fs("uploads", "storage/app/uploads")?;
Storage::set_default_disk("uploads"); // or FILESYSTEM_DISK=uploads

// anywhere after boot
Storage::default_disk()?.write("avatars/42.png", bytes).await?;
```

The boot checks the name once the bootstrap and the `s3` disk of the
environment are in place: a default disk that names no registered disk
stops the server with an error that names the disk and `FILESYSTEM_DISK`,
rather than failing the first upload. With neither setting present, you use
the registered `local` disk. When you have not registered `local`,
`Storage::default_disk()` returns an error naming `local` and
`FILESYSTEM_DISK`. A call that names its disk, `Storage::disk("s3")`, is
not affected.

#### Why Suprnova diverges

Laravel ships a `local` disk and defaults `FILESYSTEM_DISK` to it. Suprnova
registers no local disk on its own, so you register `local` in your
bootstrap to use the implicit default. You reach it through
`Storage::default_disk()` rather than `Storage::put`.

See [Configuration](configuration.md) for the wider rule on where the
framework reads from the environment.

## Next

- [Configuration](configuration.md) - what the framework reads from
  `.env`
- [Requests](requests.md) - file uploads land on a disk via
  `UploadedFile::store_as`
- [Responses](responses.md) - streaming bytes back out of a disk
- [Cache](cache.md) - the other named-driver registry, same shape
- [Testing](testing.md) - the wider fake-everything testing surface

[`DiskExt`]: https://docs.rs/suprnova/latest/suprnova/trait.DiskExt.html
[`DiskAssertExt`]: https://docs.rs/suprnova/latest/suprnova/filesystem/testing/trait.DiskAssertExt.html
[`ChecksumAlgorithm`]: https://docs.rs/suprnova/latest/suprnova/enum.ChecksumAlgorithm.html


---

<!-- /docs/http-client -->

# HTTP Client

The `Http` facade is the outbound side of HTTP - the Rust equivalent of
Laravel's `Http::` helper. You reach for it when your handler, job, or
scheduled task needs to call somebody else's API: a payment gateway, a
geocoder, a webhook target, a Slack message. Fluent builder, JSON in
and out, retries with jitter, deterministic test fakes that record what
you sent. The same surface you used in Laravel, with task-local
isolation so parallel tests don't see each other's fakes.

```rust
use suprnova::Http;
use serde_json::json;

let resp = Http::post("https://api.stripe.com/v1/charges")
    .bearer_token(secret_key)
    .json(&json!({ "amount": 1000, "currency": "usd" }))
    .send()
    .await?;

let body: serde_json::Value = resp.json().await?;
```

That's the shape: `Http::<verb>(url)` returns a `RequestBuilder`; you
chain configuration onto it; `.send().await` returns a
`ClientResponse`. The backing client is one shared `reqwest::Client`
with rustls TLS, a 30s default timeout, and a `suprnova/<version>` user
agent - built lazily on first call.

## The verbs

```rust
Http::get("https://api.example.com/users/42")
Http::post("https://api.example.com/users")
Http::put("https://api.example.com/users/42")
Http::patch("https://api.example.com/users/42")
Http::delete("https://api.example.com/users/42")
Http::head("https://api.example.com/users/42")
```

Every verb returns a `RequestBuilder`. The URL can be any
`impl Into<String>` - a `&str`, a `String`, or a `Cow<str>`. `head`
sends `HEAD`: the response has the status and headers a `GET` would
have, and no body.

## Building the URL

Three builder methods put the URL together when the request is sent:

```rust
let resp = Http::get("users/{id}/orders")
    .base_url("https://api.example.com/v2")
    .url_parameters([("id", user_id.as_str())])
    .query(&[("page", "2"), ("status", "open")])
    .send()
    .await?;
// GET https://api.example.com/v2/users/42/orders?page=2&status=open
```

- `.base_url(url)` goes in front of a URL that does not start with
  `http://` or `https://`, with one slash between the two. An absolute
  URL is sent as it is, so one client setup can still call another host.
- `.url_parameters(params)` expands each `{name}` in the URL. Every
  character of a value except letters, digits, `-`, `.`, `_` and `~` is
  percent-encoded, so `a/b` becomes `a%2Fb`: a value cannot add a path
  segment, a query, a fragment or a host. A placeholder that no value names
  stays as it is.
- `.query(params)` merges the pairs into the URL's query. A name the URL
  already has takes the new value, and the other names stay. The URL has
  to be absolute by then, base URL included, or `send()` returns an error.

`query` takes a slice of pairs, `&[("name", "value")]`, and
`url_parameters` takes an array of pairs or any iterator of them. Calling
either again adds more.

## Bodies

Four ways to attach a body. Each one replaces any previously-set body.

### JSON

```rust
use serde::Serialize;

#[derive(Serialize)]
struct CreateUser {
    name: String,
    email: String,
}

Http::post("https://api.example.com/users")
    .json(&CreateUser {
        name: "Ada".into(),
        email: "ada@example.com".into(),
    })
    .send()
    .await?;
```

`.json(&value)` accepts anything that implements `serde::Serialize`.
The wire `Content-Type` is set to `application/json` automatically.
If serialization fails (e.g. a map with a non-string key), the
builder records the error and `send()` surfaces it instead of
silently sending a `null` body.

### Form

```rust
Http::post("https://login.example.com/oauth/token")
    .form(&serde_json::json!({
        "grant_type": "client_credentials",
        "client_id": id,
        "client_secret": secret,
    }))
    .send()
    .await?;
```

`.form(&value)` serializes the value as `application/x-www-form-urlencoded`.
The value must serialize to a JSON object; the keys become form fields.
Same body-error semantics as `.json` - a serialization failure surfaces
through `send().await?`, never as a silent empty body.

### Raw bytes

```rust
use bytes::Bytes;

let payload: Bytes = compress(report)?;
Http::post("https://collector.example.com/ingest")
    .header("Content-Type", "application/octet-stream")
    .body(payload)
    .send()
    .await?;
```

`.body(bytes)` takes anything `impl Into<Bytes>`. You're responsible
for the `Content-Type` header - `.body` doesn't set one.

### Multipart

```rust
let avatar: Vec<u8> = std::fs::read("storage/avatar.png")?;
Http::post("https://api.example.com/profile")
    .attach("avatar", avatar, Some("avatar.png"))
    .attach("caption", "Me, in 2026", None)
    .send()
    .await?;
```

`.attach(name, contents, filename)` adds a part to a
`multipart/form-data` body: the bytes under the field `name`, with a file
name when you give one. Each call adds a part. The body is encoded when the
request is sent, with a random boundary in its `Content-Type`.

## Headers and auth

```rust
Http::get("https://api.example.com/private")
    .header("X-Request-Id", request_id)
    .header("Accept", "application/vnd.api+json")
    .bearer_token(api_key)
    .send()
    .await?;
```

`.header(name, value)` appends; the framework doesn't dedupe, so two
calls with the same name send two headers and reqwest joins them per
HTTP semantics. Two shortcuts for the common auth schemes:

- `.bearer_token(token)` - sets `Authorization: Bearer <token>`
- `.basic_auth(user, password)` - sets `Authorization: Basic <b64>`;
  `password` is `Option<&str>` so `.basic_auth("api-key", None)`
  encodes the `api-key:` form some providers want

## Timeouts

The shared client has a 30-second default timeout. Override per-request
when you need to:

```rust
use std::time::Duration;

Http::get("https://slow.example.com/report")
    .timeout(Duration::from_secs(120))
    .send()
    .await?;
```

`.timeout(dur)` sets the total time the request may take, connecting
included. The shared client also gives up on a connection after 10
seconds. `.connect_timeout(dur)` changes that for one request:

```rust
Http::get("https://flaky.example.com/health")
    .connect_timeout(Duration::from_secs(2))
    .timeout(Duration::from_secs(5))
    .send()
    .await?;
```

reqwest fixes the connect timeout when it builds a client, so each distinct
connect timeout gets a client of its own, built on first use and kept. Use a
few fixed values rather than one you compute per request.

## Redirects

The shared client follows redirects by default (up to reqwest's cap of
10) - the right behavior when you're calling a trusted endpoint that
answers `http → https` or hands you a CDN URL.

When the request URL is influenced by untrusted input, that default
becomes a server-side request forgery (SSRF) vector: a hostile endpoint
can answer with a `3xx` whose `Location` points at an internal service or
a cloud-metadata address (`http://169.254.169.254/…`), and a following
client would chase it. Disable redirect-following for those requests with
`.no_redirects()`:

```rust
let resp = Http::get(user_supplied_url)
    .no_redirects()
    .send()
    .await?;

// The 3xx is returned as-is instead of being followed - inspect it and
// reject rather than letting the client chase the Location header.
if (300..400).contains(&resp.status()) {
    return Err(AppError::bad_request("refusing to follow a redirect"));
}
```

`.no_redirects()` routes the request through a separate non-following
client; the default client - and every request that doesn't call it - is
unchanged. This is the general-client analogue of the redirect lockdown
the web-push sender already applies to attacker-controlled push endpoints.

## Global middleware and options

Some settings belong on every request: an `X-App` header, a token that
signs each call, a log line for each response. Register them once, at
boot:

```rust
use std::time::Duration;
use suprnova::{ClientResponse, Http, RequestBuilder};

Http::global_options(|request: RequestBuilder| {
    request.timeout(Duration::from_secs(10))
});
Http::global_request_middleware(|request: RequestBuilder| {
    request.header("X-App", "billing")
});
Http::global_response_middleware(|response: ClientResponse| {
    tracing::debug!(status = response.status(), "outbound response");
    response
});
```

- `Http::global_options(f)` runs `f` on every request as it is created, so
  what the request sets itself comes after and wins where a setting
  replaces, such as a timeout. Headers are appended, so a header set both
  ways is sent twice, the global one first. Calling it again replaces the
  options.
- `Http::global_request_middleware(f)` runs `f` on every request just
  before it is sent, once per `send()`. The request it receives has its
  final URL, which `request.url()` returns; `request.method()` returns the
  method.
- `Http::global_response_middleware(f)` runs `f` on every response before
  your code sees it, each attempt of a retried request included.

Middleware runs in the order you register it. A request takes the global
configuration in force when it is created. `Http::without_global_configuration`
creates requests without any of it:

```rust
let resp = Http::without_global_configuration(|| async {
    Http::get("https://status.example.com/ping").send().await
})
.await?;
```

Only the requests created on the current task inside the closure are left
out; other requests of the process keep their middleware. The mail and
vector drivers of the framework call their providers without the facade,
so global middleware never reaches them.

Registered inside an `Http::fake` scope, global middleware and options
belong to that scope and end with it, so tests running in parallel do not
see each other's. A request inside the scope takes the process-wide
configuration first, then the scope's.

## Retries

`Http` ships exponential-backoff retries with full jitter - the AWS
recipe, the same one Laravel uses. One rule decides every retry, for a
transport failure and for a received 5xx response alike. The two retry
modes differ in the methods they retry: `.retry(...)` retries `GET`, `PUT`
and `DELETE`, and `.retry_non_idempotent(...)` retries `POST` and `PATCH`
as well.

### `.retry(max_attempts, base_backoff)` - retries for idempotent methods

```rust
use std::time::Duration;

let resp = Http::get("https://flaky.example.com/health")
    .retry(4, Duration::from_millis(200))
    .send()
    .await?;
```

`max_attempts` includes the first try, so `retry(4, ...)` retries up
to three times after the initial attempt. The delay before attempt
`n+1` is a uniform random duration in `[0, base_backoff * 2^(n-1)]`,
capped at 30 seconds. Full jitter, not exponential-backoff-plus-fixed-
sleep, so many workers retrying the same outage don't synchronize into
a thundering herd.

`.retry()` retries only idempotent methods (`GET`, `PUT`, `DELETE`): a
transport failure (connect, timeout, DNS) or a 5xx status triggers another
attempt. 4xx and 2xx/3xx responses are returned as-is. After exhausting
retries, the last response or transport error is returned to the caller.

`POST` and `PATCH` are sent once, whatever the failure. A transport failure
on a write can mean the server committed it but the response was lost, so
retrying could apply it twice. Opt in with `.retry_non_idempotent(...)`
when the upstream is protected by an idempotency key.

### `.retry_non_idempotent(...)` - opt-in for POST/PATCH

```rust
Http::post("https://api.example.com/charges")
    .header("Idempotency-Key", idem_key)
    .retry_non_idempotent(3, Duration::from_millis(200))
    .send()
    .await?;
```

When you've supplied an idempotency key the upstream honors, or you've
otherwise made the request safe to replay, switch to
`.retry_non_idempotent(...)`. It retries `GET`, `PUT` and `DELETE` as
`.retry()` does, and it also retries `POST` and `PATCH`, after a transport
failure and after a 5xx response. It still returns 4xx and 2xx/3xx
responses as-is.

### Retry-After is honored on 503

For a `503 Service Unavailable`, the framework respects a `Retry-After`
header - in either delta-seconds (`Retry-After: 30`) or HTTP-date
(`Retry-After: Tue, 15 Nov 1994 08:12:31 GMT`) form. The actual wait
is the larger of the jittered backoff and the `Retry-After` hint,
still capped at 30 seconds. A hostile or misconfigured server returning
`Retry-After: 86400` won't park your task for a day.

### `.retry_when(predicate)` - narrow the policy further

```rust
use std::time::Duration;

let resp = Http::get("https://flaky.example.com/health")
    .retry(4, Duration::from_millis(200))
    .retry_when(|ctx| ctx.method == "GET")
    .send()
    .await?;
```

`retry_when` registers a predicate consulted before every retry the
policy above would otherwise make. It can veto an otherwise eligible
retry, but it cannot manufacture one. In particular, it cannot turn a
2xx, 3xx, or 4xx response into a retry, and it cannot make a received
5xx response retryable for `POST` or `PATCH` without
`.retry_non_idempotent(...)`. It is consulted for transport-error retries
and for 5xx retries by the same rule, and only for an attempt that the
policy would retry: not after the last attempt, and not for a `POST` or
`PATCH` under plain `.retry()`. Without a `.retry(...)` or
`.retry_non_idempotent(...)` policy, a lone `retry_when` has nothing to
veto.

The predicate receives `RetryContext { attempt, method, url, outcome }`,
where `outcome` is `RetryOutcome::TransportError` (send failed before a
response arrived) or `RetryOutcome::Status(n)` (an eligible 5xx
response).

## Reading the response

`ClientResponse` exposes status, headers, and three body-reading
methods. Each body method consumes the response.

```rust
let resp = Http::get("https://api.example.com/users/42").send().await?;

let status: u16 = resp.status();
let etag: Option<String> = resp.header("ETag");

// Pick one - each consumes the response.
let user: User = resp.json().await?;
// let text: String = resp.text().await?;
// let bytes: Bytes = resp.bytes().await?;
```

`.header(name)` is case-insensitive. `.json::<T>()` returns
`Result<T, FrameworkError>` and uses `serde_json` for decoding.
`.text()` enforces UTF-8 and surfaces a `FrameworkError` if the body
isn't valid UTF-8.

### Response body cap

A slow or hostile upstream can otherwise stream an unbounded body into
memory. To protect that, every buffered body read is capped - 25 MiB
by default. Override globally at boot:

```rust
use suprnova::Http;

// Once, somewhere in bootstrap.
Http::set_max_response_bytes(100 * 1024 * 1024); // 100 MiB
```

Or per-request when one call legitimately handles a larger payload:

```rust
let bytes = Http::get("https://example.com/big-export.json")
    .max_response_bytes(500 * 1024 * 1024) // 500 MiB
    .send()
    .await?
    .bytes()
    .await?;
```

A response that declares a `Content-Length` over the cap is rejected
before any body is read; the streaming loop also enforces the cap
against the actual bytes, in case `Content-Length` is absent or lies.

## Escape hatch - raw reqwest

The framework covers the common cases. When you need something we don't
expose - streaming bodies, redirect policy inspection, websocket
upgrades - call `.into_inner()` to unwrap the underlying
`reqwest::Response`:

```rust
let resp = Http::get("https://example.com/big-stream").send().await?;
let raw: reqwest::Response = resp.into_inner()?;
let mut stream = raw.bytes_stream();
while let Some(chunk) = stream.next().await {
    process(chunk?);
}
```

`into_inner()` returns `Err(FrameworkError::internal(...))` when called
on a fake response - there's no underlying `reqwest::Response` in that
case. The response-body cap also no longer applies once you take the
raw response; you own the read from there.

## Testing with `Http::fake`

This is the part you'll use every day. `Http::fake` runs your test body
inside a `tokio::task_local!` scope where every outbound call is
intercepted, captured, and answered with whatever you've queued.

```rust
use suprnova::{Http, fake_response, assert_sent};

#[tokio::test]
async fn creates_a_user_via_api() {
    Http::fake(|| async {
        fake_response(
            "POST",
            "/api/users",
            201,
            serde_json::json!({ "id": 42, "name": "Ada" }),
        );

        let resp = Http::post("https://example.com/api/users")
            .json(&serde_json::json!({ "name": "Ada" }))
            .send()
            .await
            .unwrap();

        assert_eq!(resp.status(), 201);
        let body: serde_json::Value = resp.json().await.unwrap();
        assert_eq!(body["id"], 42);

        assert_sent(|r| r.method == "POST" && r.url.contains("/api/users"));
    })
    .await;
}
```

### Matching canned responses

`fake_response(method, url_substring, status, body)` queues a canned
response. The first outbound request whose method matches
(case-insensitive) and whose URL contains `url_substring` consumes the
canned entry and returns that response. Use method `"*"` to match any
method.

Subsequent matching requests fall through to the next canned entry of
the same shape, or - if none match - return an empty `200 {}`. Queue
one canned response per expected call:

```rust
fake_response("GET", "/v1/customer", 200, json!({ "id": "cus_1" }));
fake_response("GET", "/v1/customer", 200, json!({ "id": "cus_2" }));
// Two GETs to /v1/customer get distinct responses; a third gets 200 {}.
```

### Stubs that stay

Three helpers register a stub that answers for as long as the fake lives.
Each answers with a `FakeResponse`: `FakeResponse::new(status)`,
`FakeResponse::json(status, value)` or `FakeResponse::text(status, body)`,
with `.header(name, value)` and `.body(bytes)` to add to it.

```rust
use suprnova::{FakeResponse, Http};

Http::fake(|| async {
    // Every matching URL, every time.
    Http::fake_url("api.example.com/users/*", FakeResponse::json(200, json!({ "id": 7 })));

    // Decide in code; `None` lets the next stub answer.
    Http::fake_using(|request| {
        request
            .has_header("X-Tenant", "acme")
            .then(|| FakeResponse::new(403))
    });

    // Answered in turn, then the `when_empty` response.
    Http::fake_sequence("api.example.com/jobs*")
        .push(FakeResponse::new(201))
        .push_status(202)
        .when_empty(FakeResponse::new(204));

    // ... code under test ...
})
.await;
```

In a URL pattern `*` matches any run of characters, and a leading `*` is
implied, so `api.example.com/users/*` matches
`https://api.example.com/users/7`. A sequence that runs out without a
`when_empty` response fails the request; `.dont_fail_when_empty()` answers
an empty `200` instead.

A request is answered by a `fake_response` entry that matches first, then
by the stubs in the order you registered them, then by the default
`200 {}`.

### Assertions

```rust
// Pass if at least one recorded request matches.
assert_sent(|r| r.method == "POST" && r.url.contains("/charges"));

// Pass if no recorded request matches.
assert_not_sent(|r| r.url.contains("/refunds"));
```

`RecordedRequest` exposes `method: String`, `url: String`,
`headers: Vec<(String, String)>`, and `body: Option<Vec<u8>>`. The URL is
the one the request is sent to, base URL, URL parameters and query
applied, and the headers are the ones it is sent with: yours, the ones
global middleware added, the `Content-Type` a JSON, form or multipart body
sets, and the user agent. Five helpers read them, names compared without
regard to case:

```rust
assert_sent(|r| {
    r.is_json()
        && r.has_header("X-App", "billing")
        && r.header("authorization").is_some_and(|v| v.starts_with("Bearer "))
});
assert_sent(|r| r.is_form() || r.is_multipart());
```

The predicate runs against every recorded request; assertion failures
print the recorded list with header values and bodies redacted (a
small allowlist of `Content-Type`, `Accept`, and `User-Agent` is shown
in full; everything else is `<redacted>`). That keeps bearer tokens
and webhook payloads out of CI logs even when an assertion blows up.

### Tests run in parallel safely

The fake state lives in a `tokio::task_local!` - every fake scope is
scoped to the task running the test, not the process. Two tests
running concurrently on different tasks each get their own
recorded-requests vec and their own canned-response queue. No shared
mutex, no test ordering, no `#[serial]`.

```rust
#[tokio::test]
async fn first_test() {
    Http::fake(|| async {
        fake_response("GET", "/a", 200, json!({"who": "first"}));
        let _ = Http::get("https://x.test/a").send().await.unwrap();
        assert_sent(|r| r.url.contains("/a"));
        // Sibling test's request to /b is invisible here.
    })
    .await;
}

#[tokio::test]
async fn second_test() {
    Http::fake(|| async {
        fake_response("GET", "/b", 200, json!({"who": "second"}));
        let _ = Http::get("https://x.test/b").send().await.unwrap();
        assert_sent(|r| r.url.contains("/b"));
    })
    .await;
}
```

## The spawned-task gotcha

`tokio::task_local!` is scoped to the current task. Work that goes
through `tokio::spawn` lands on a fresh task and does NOT inherit
the fake - by default, outbound calls from the spawned future hit the
real network. Two helpers address this.

### `Http::fail_on_real_calls()` and `FailOnRealCallsGuard`

Flips a process-global flag that turns any unmatched outbound call
into a `FrameworkError::internal(...)` instead of letting it hit the
network. This is Suprnova's analogue of Laravel's
`Http::preventStrayRequests()` - it catches the exact bug the gotcha
creates.

Use the RAII guard so the flag resets when the test ends, even on
panic:

```rust
use suprnova::FailOnRealCallsGuard;

#[tokio::test]
async fn no_test_makes_a_real_call() {
    let _guard = FailOnRealCallsGuard::install();

    // Any unfaked outbound HTTP call from anywhere inside this test
    // - including from a `tokio::spawn`-ed task - errors with a
    // message naming the URL. No network IO actually happens.
}
```

Nested guards compose correctly: the inner guard's `Drop` restores
the PREVIOUS state, not unconditionally "allowed". So an inner test
helper that installs its own guard inside an outer guarded scope
doesn't disarm the outer guard on the way out.

The flag is process-global by design. The point is catching a
`tokio::spawn`-ed future silently escaping a fake scope and pinging a
real third party from CI. A per-task flag would miss that.

Laravel's names move the same flag. `Http::prevent_stray_requests(true)`
arms it as `fail_on_real_calls()` does, `Http::prevent_stray_requests(false)`
releases it as `allow_real_calls()` does, and
`Http::preventing_stray_requests()` answers whether it is armed.

Inside a fake, `Http::allow_stray_requests(&patterns)` lets a request that
no stub answers reach the network when its URL matches one of the patterns,
even while stray requests are refused. Here `*` matches any run of
characters and no leading `*` is implied:

```rust
Http::prevent_stray_requests(true);

Http::fake(|| async {
    // The local test server answers for real; anything else must be faked.
    Http::allow_stray_requests(&["http://127.0.0.1:*"]);
    // ...
})
.await;

Http::prevent_stray_requests(false);
```

Such a request is still recorded, and goes out with its global middleware.

### `Http::spawn_with_fake_inheritance(future)`

When code under test legitimately spawns a task - a queue worker, a
background syncer, a sub-task - and you want its outbound calls to go
through the parent's fake, swap `tokio::spawn` for
`Http::spawn_with_fake_inheritance`:

```rust
Http::fake(|| async {
    fake_response("GET", "/child", 204, json!({}));

    let handle = Http::spawn_with_fake_inheritance(async {
        // Runs on a NEW task, but the parent's fake state is
        // re-installed in this task's task-local scope. The send
        // is intercepted; the response is the 204 above.
        Http::get("https://child.example.com/child").send().await
    });

    let response = handle.await.unwrap().unwrap();
    assert_eq!(response.status(), 204);

    // Recorded requests from the child show up here - the
    // Arc<Mutex<FakeState>> is shared, not snapshotted.
    assert_sent(|r| r.url.contains("/child"));
})
.await;
```

If no fake scope is active when you call
`spawn_with_fake_inheritance`, it's equivalent to `tokio::spawn` - the
child runs without any fake context. So you can use it
unconditionally in code that's sometimes tested with `Http::fake` and
sometimes not.

### Belt-and-braces in test setup

The two combine. A test that wants to be loudly safe pairs them:

```rust
#[tokio::test]
async fn pays_the_invoice() {
    let _guard = FailOnRealCallsGuard::install();

    Http::fake(|| async {
        fake_response("POST", "/v1/charges", 200, json!({ "id": "ch_1" }));

        // If a typo on the URL or method drifts away from the fake,
        // the request falls through to the guard, which errors out
        // with a message naming the URL - instead of silently
        // returning an empty 200 that hides the mismatch.
        pay_invoice(&invoice).await.unwrap();

        assert_sent(|r| r.url.contains("/v1/charges"));
    })
    .await;
}
```

Without the guard, an URL or method that drifts from the fake silently
falls through to a default `200 {}`, and your test passes despite the
production code calling a different endpoint. With the guard, you
fail loudly on the first mismatch.

## OpenTelemetry trace propagation

When the framework is built with the `otel` feature and a W3C
TraceContext propagator is installed, every outbound `Http::*` request
injects `traceparent` (and `tracestate` when non-empty) into its
headers - so downstream services can continue the trace. No
configuration on the call site; the propagator reads
`opentelemetry::Context::current()` at send time.

Without an active OTel context, no headers are injected and outbound
requests look exactly like they did before. See
[Observability](observability.md) for the propagator setup.

## Why Suprnova diverges

A few divergences from Laravel's `Http::` facade are worth calling
out.

**Task-local fakes instead of a process-global mock store.** Laravel's
`Http::fake()` mutates a process-wide registry; tests serialize on it,
or you accept that parallel runners can race. Suprnova's `Http::fake`
uses `tokio::task_local!` so two tests on two tasks each see their own
fake - no test ordering, no shared mutex. The price is that
`tokio::spawn`-ed work doesn't inherit the fake by default, which is
why `Http::spawn_with_fake_inheritance` and
`FailOnRealCallsGuard` exist. Together they give you the same
"can't accidentally hit production" guarantee that
`Http::preventStrayRequests()` does in Laravel, with stricter scoping.

**Retries default to refusing POST/PATCH.** Laravel's HTTP client
retries any method by default. Suprnova's `.retry(...)` sends `POST` and
`PATCH` once, after a transport failure and after a 5xx response alike.
Use `.retry_non_idempotent(...)` to opt into retries for those methods
only after making the write safe to replay, typically with an idempotency
key the upstream honors.

**Global configuration registered inside a fake belongs to the fake.**
Laravel's tests each get a fresh application, so a test's global
middleware ends with it. Suprnova's process outlives a test, so
`Http::global_*` called inside an `Http::fake` scope register for that
scope only, and `without_global_configuration` leaves out the requests of
the current task rather than emptying the process-wide lists while other
requests run.

**`query` merges into the URL's query.** Guzzle replaces the query string
of the URL with the `query` option. Suprnova keeps the URL's other names,
so `query` adds to a URL that already has one. `url_parameters` expands
only the simple `{name}` form of a URI template.

**Stubs take a `FakeResponse`, and use-once entries answer first.**
Laravel's `Http::fake([...])` takes a response, a status, a string or a
closure in one array. Suprnova has one helper for each:
`fake_url`, `fake_using` and `fake_sequence`. A `fake_response` entry, which
is used up as it answers, is asked before them.

**`retry_when` can only narrow, never widen.** Laravel's `retry()`
`$when` callback fully replaces the "should retry" decision, so it can
retry statuses the framework wouldn't otherwise touch (a 404, say).
Suprnova's `retry_when` only vetoes a retry `.retry(...)` or
`.retry_non_idempotent(...)` already decided to make. It is consulted
for every retry the policy would make, but cannot turn a 2xx, 3xx, or
4xx response into a retry or make a `POST` or `PATCH` eligible under plain
`.retry()`.

## Edge cases and small print

- **`Http::*` is closed.** We deliberately don't expose the
  underlying `reqwest::Client`. To grow the surface, add a method to
  the facade rather than reaching for `reqwest` directly - except via
  the documented `into_inner()` escape hatch on a real response.
- **The shared client is built once and lives forever.** Built lazily
  on first call to any `Http::*` verb, kept in a `OnceLock`. The
  rustls TLS stack and the 30s default timeout are baked in. A request
  with its own `connect_timeout` uses a client kept for that timeout.
- **JSON/form serialization failures fail loudly.** A
  `.json(&unserializable)` builder records the error and `send()`
  returns it as `FrameworkError::internal(...)`. The request never
  goes out - we don't degrade to a `null` body.
- **The 30s retry ceiling is hard.** The backoff math caps at 30
  seconds; the `Retry-After` interpretation caps at 30 seconds; no
  single retry sleep parks a task for longer.
- **Process-global cap is one-shot.** `Http::set_max_response_bytes`
  is a write to a process-global atomic - set it once at boot, then
  override per-request as needed. There's no "reset to default" call.

## Next

- [Mail](mail.md) - outbound email, which uses similar fake / driver
  patterns for tests
- [Notifications](notifications.md) - notification channels including
  web push, all share the same test-fake philosophy
- [Queues](queues.md) - jobs that make outbound HTTP calls, plus the
  `spawn_with_fake_inheritance` pattern for testing workers
- [Testing](testing.md) - `#[suprnova_test]`, `TestContainer`, and the
  rest of the fakes surface
- [Observability](observability.md) - OTel propagator setup that makes
  `traceparent` injection light up


---

<!-- /docs/images -->

# Images

Suprnova ships a Laravel-shaped image pipeline: build it in a handler,
chain the operations you want, and finish with a terminal that hands you
bytes, a response, or a stored file.

```rust
use suprnova::{Image, OutputFormat, Response, handler};

#[handler]
pub async fn thumbnail() -> Response {
    Ok(Image::from_path("storage/photos/hero.jpg")
        .cover(320, 320)
        .to_format(OutputFormat::WebP)
        .quality(80)
        .to_response()
        .await?)
}
```

That handler decodes the JPEG, fills a 320x320 box, crops the overflow
from the centre, encodes WebP, and returns a `200` with
`Content-Type: image/webp`.

The subsystem lives in `suprnova::media`, behind the default-on `media`
feature. Everything you normally reach for - `Image`, `OutputFormat`,
`ImageDriver`, `ImageConfig` - is re-exported flat at the crate root, so
`use suprnova::Image;` is the import you want. The module name is
plural-in-spirit on purpose: it is where the OxideAV-backed audio and
video surfaces will live too.

If you are upgrading, note that the upload validator that used to be
called `Image` is now `ImageFile`, which frees the plain name for this
pipeline type. That mirrors Laravel, where the validation rule is
`ImageFile` and the manipulation type is `Image`. See
[Requests](requests.md) for the validator.

## The pipeline is lazy

Constructing an `Image` reads nothing and decodes nothing. Operations
record themselves; the source is opened only when a terminal runs. So
this is free:

```rust
use suprnova::Image;

let pipeline = Image::from_disk("uploads", "avatars/42.png").resize(64, 64);
```

Nothing has touched the disk yet. `Image` is `Clone`, and a clone
re-runs the pipeline from its source rather than sharing a result.

Two constructors have to be eager, and say so in their docs:
`from_upload` (an upload's temp file does not outlive the request) and
`from_stream` (a stream can only be consumed once).

## Construction

| Constructor | Source | Eager? |
|---|---|---|
| `Image::from_bytes(bytes)` | anything `Into<Bytes>` | no |
| `Image::from_path(path)` | the filesystem | no |
| `Image::from_disk(disk, path)` | a `Storage` disk | no |
| `Image::from_upload(&file).await?` | an `UploadedFile` | yes |
| `Image::from_stream(stream).await?` | a `Stream<Item = io::Result<Bytes>>` | yes |

`from_stream` enforces `IMAGE_MAX_ALLOC_BYTES` *while* collecting, so an
endless stream is cut off rather than discovered after it has already
filled memory.

## Operations

| Method | Effect |
|---|---|
| `resize(w, h)` | Exact dimensions, aspect ratio ignored |
| `resize_width(w)` / `resize_height(h)` | One dimension, the other derived from the aspect ratio |
| `resize_width_only(w)` / `resize_height_only(h)` | One dimension, the other kept at its current size, so the aspect ratio changes (Laravel's `resize(width: ...)`) |
| `scale(w, h)` | Fit inside the box, preserving aspect ratio. **Never enlarges** |
| `scale_width(w)` / `scale_height(h)` | Scale down to at most one dimension. Never enlarges |
| `crop(w, h, x, y)` | Cut a rectangle out. Errors if it falls outside the image |
| `cover(w, h)` | Fill the box exactly, cropping the overflow from the centre |
| `contain(w, h)` | Fit inside the box, preserving aspect ratio. No padding |
| `rotate(degrees)` | Rotate clockwise by any angle, growing the canvas to fit |
| `rotate_with_background(degrees, color)` | Rotate, filling the exposed corners with a `Color` |
| `flip_vertically()` / `flip_horizontally()` | Mirror top to bottom, or left to right |
| `flip()` / `flop()` | Laravel's names for the same two mirrors |
| `orient()` | Apply the source's EXIF orientation here, if decoding did not |
| `transform(transformation)` | Add any `Transformation`, a custom one included |
| `transform_with(name, settings)` | Add a custom transformation and hand its function `settings` |
| `blur(amount)` | Gaussian blur, `0..=100`. `0` is a no-op |
| `sharpen(amount)` | Unsharp mask, `0..=100`. `0` is a no-op. `50` is the classic strength |
| `grayscale()` | Desaturate. Spelled the Laravel way |
| `to_format(format)` | Choose the output container: `Jpeg`, `Png`, `WebP`, `WebPLossless`, `Gif` or `Bmp` |
| `to_webp()`, `to_jpg()`, `to_jpeg()`, `to_png()`, `to_gif()`, `to_bmp()` | Shortcuts for `to_format` |
| `quality(q)` | Encode quality, clamped to `1..=100`, default `85` |
| `recompress_png(effort)` | Compress PNG losslessly after pixel operations |
| `optimize(format, q)` | `to_format(format).quality(q)` in one call |
| `using(driver)` | Process this image with the `oxideav` or `magick` driver (see [Backends](#backends)) |

The default departs from Laravel's 70 because quality below 85 blurs
images.

Values that would be nonsense are clamped rather than rejected:
`blur(500)` records `100`, `quality(0)` records `1`, and a side of `0`
given to `resize`, `cover` or a one-side resize records `1`, as Laravel's
`Image` clamps it, so no driver, a custom one included, receives a zero
side. A crop that falls outside the image is a real error, not a clamp,
because silently moving someone's crop box is worse than telling them.

The "only" resizes keep the other side at the size the image has at that
point of the pipeline, not the source's, so they compose with the steps
before them:

```rust
use suprnova::{FrameworkError, Image};

async fn banner_strip() -> Result<(u32, u32), FrameworkError> {
    // 40x20 -> 30x12 -> 10x12
    Image::from_path("storage/photos/banner.png")
        .resize(30, 12)
        .resize_width_only(10)
        .dimensions()
        .await
}
```

The new size meets the same decode limits as any resize target, under
either driver.

`rotate` takes arbitrary angles. A 90-degree multiple takes an exact
axis-aligned path with no resampling; anything else is bilinear, and the
canvas grows so no pixel is clipped.

The corners a rotation exposes are white when the output is JPEG or GIF,
which cannot hold transparency, and transparent when it is PNG, WebP or
BMP. `rotate_with_background` names the colour instead. JPEG and GIF
output also flattens any transparency in the image onto that colour, or
onto white when the pipeline does not rotate:

```rust
use suprnova::{Color, FrameworkError, Image};

async fn tilted() -> Result<Vec<u8>, FrameworkError> {
    Image::from_path("storage/photos/logo.png")
        .rotate_with_background(15.0, Color::from_hex("#1e293b")?)
        .to_jpg()
        .to_bytes()
        .await
}
```

`Color` is a typed value: `Color::rgb`, `Color::rgba`, `Color::WHITE`,
`Color::BLACK`, `Color::TRANSPARENT`, or `Color::from_hex` for a colour
that arrives as text (`rgb`, `rrggbb` or `rrggbbaa`, with or without
`#`). A string that is not a hex colour fails at `from_hex`, in your
code, rather than inside a driver.

## Orientation

A phone stores a photo's pixels as the sensor read them and records, in
the EXIF `Orientation` tag, how to turn them for display. Both drivers
apply the tag as they decode, as Laravel's do, so a portrait photo comes
out upright. All eight orientations are quarter turns and mirrors, so
applying one moves pixels and never resamples them.

The tag is read from a JPEG's last Exif `APP1` segment, wherever it sits
(a progressive JPEG can carry one between its scans), a PNG's `eXIf`
chunk, and a WebP's `EXIF` chunk. Reading it never inflates a compressed
chunk. Both drivers read the tag in these places, with the same reader,
and turn the image with a fixed quarter turn or mirror, so a file comes
out the same way under either. ImageMagick's own orientation sources, a
PNG's `Raw profile type exif` text chunk and its `orNT` chunk, are not
used. For a format the framework cannot read (HEIC, TIFF), the `magick`
driver leaves orientation to ImageMagick's `-auto-orient`.

Turning the image holds a second full-size plane beside the decoded one,
and the decode estimate counts it (see
[What a decode costs](#what-a-decode-costs)). `ImageDriver::dimensions`
reports a tagged source at its turned size, and `dominant_color` at its
average, without turning the pixels.

| Var | Default | Purpose |
|---|---|---|
| `IMAGE_AUTO_ORIENT` | `true` | Apply the EXIF orientation on decode. `false`, `0`, `no` or `off` turn it off |

With `IMAGE_AUTO_ORIENT=false` the pixels keep the sensor's orientation,
and the output keeps the `Orientation` tag, so a viewer can still turn
the image. `orient()` then applies the tag at the point in the pipeline
where you put it:

```rust
use suprnova::{FrameworkError, Image};

// With IMAGE_AUTO_ORIENT=false: crop in sensor coordinates, then turn.
async fn crop_then_turn() -> Result<Vec<u8>, FrameworkError> {
    Image::from_path("storage/photos/scan.jpg")
        .crop(1200, 800, 40, 40)
        .orient()
        .to_bytes()
        .await
}
```

When decoding has already oriented the image, `orient()` does nothing, so
an image is never turned twice.

## Metadata

Processed output keeps two things of the source's metadata and drops the
rest:

- **The ICC profile**, so the colours read the same. JPEG output carries
  it in `APP2` segments, PNG in an `iCCP` chunk, WebP in an `ICCP` chunk,
  and BMP in a V5 header. A PNG's `cHRM`, `gAMA`, `sRGB` and `cICP`
  chunks describe its colour too, and PNG output keeps them with the
  profile.
- **An `Orientation` tag**, alone in its own EXIF block, when orientation
  was not applied: `IMAGE_AUTO_ORIENT=false` with no `orient()` in the
  pipeline. Only JPEG, PNG and WebP can hold one.

Everything else goes: EXIF (and with it the GPS position), XMP, IPTC,
JPEG comments, PNG `tEXt`, `zTXt` and `iTXt` chunks, and the date and
time an encoder adds by itself, such as PNG's `tIME` chunk and
ImageMagick's `date:` text. A user's upload does not publish where it was
taken.

A profile must describe the pixels it travels with. GIF holds no profile
here, so GIF output has its colours converted from the profile to sRGB.
The default driver writes every format as RGB, so a grey profile no
longer describes its output: the pixels are converted from it to sRGB,
and the profile and its PNG colour chunks are dropped. The `magick`
driver keeps a grey profile on output it writes as grey.

A profile is carried only when its length is the size its own header
gives. A profile is a few kilobytes, but a PNG's is compressed, and a
small file can hold one that inflates a thousand times over. So the
driver reads the header first, and charges `IMAGE_MAX_ALLOC_BYTES` for
what it holds for the profile beside the pixels: the profile itself when
it has to join its pieces or inflate it, the compressed copy PNG output
makes of it, and the copy the output carries. Every inflate counts the
profile's inflated size, even one that only checks a PNG profile's
length. A profile that sits whole in the file is read where it stands,
and a JPEG's or a GIF's that the output drops costs nothing. A profile
whose copies do not fit is refused like any other decode over the limit.
The `magick` driver reads no more than the header of a source profile,
and checks the one ImageMagick writes without holding it, except a GIF's
RGB or grey profile, which it joins to convert the palette from.

A CMYK or Lab profile cannot describe RGB output, so it is dropped. The
default driver does not read CMYK JPEGs at all. Under `magick`,
ImageMagick converts CMYK pixels to RGB with its own formula, not through
the profile, so colours can shift.

## Custom transformations

A custom transformation is a function over decoded pixels that you
register by name, and both drivers run it at its place in the pipeline:

```rust
use suprnova::{FrameworkError, Image, ImagePixels, Transformation, register_transformation};

pub fn register() {
    // Invert every colour, keeping the alpha.
    register_transformation("invert", |mut pixels: ImagePixels| {
        for pixel in pixels.pixels_mut().chunks_mut(4) {
            for channel in &mut pixel[..3] {
                *channel = !*channel;
            }
        }
        Ok(pixels)
    });
}

async fn negative() -> Result<Vec<u8>, FrameworkError> {
    Image::from_path("storage/photos/hero.jpg")
        .resize(800, 600)
        .transform(Transformation::custom("invert"))
        .to_png()
        .to_bytes()
        .await
}
```

`ImagePixels` holds packed 8-bit RGBA, rows top to bottom. The function
receives the pixels as the steps before it left them and returns the
pixels the steps after it work on; to change the size, build a new
`ImagePixels` with `ImagePixels::new(width, height, bytes)`. The returned
size meets the same `IMAGE_MAX_DIMENSION` and `IMAGE_MAX_ALLOC_BYTES`
caps a resize does.

Register during bootstrap. Registering a name again replaces its
function. An image that names a transformation nothing is registered
under fails with an error that names it.

### Settings per call

A transformation that needs values per image, such as the block size of
a pixelate, takes them as settings. Register it with
`register_transformation_with`, naming the settings type in the function,
and record the step with `transform_with(name, settings)`:

```rust
use suprnova::{FrameworkError, Image, ImagePixels, register_transformation_with};

pub struct Pixelate {
    pub size: u32,
}

pub fn register() {
    register_transformation_with("pixelate", |mut pixels: ImagePixels, settings: &Pixelate| {
        let width = pixels.width() as usize;
        let height = pixels.height() as usize;
        let size = settings.size.max(1) as usize;
        let rgba = pixels.pixels_mut();
        for y in 0..height {
            for x in 0..width {
                // Each pixel takes the colour of the top-left pixel of its block.
                let block = ((y - y % size) * width + (x - x % size)) * 4;
                rgba.copy_within(block..block + 4, (y * width + x) * 4);
            }
        }
        Ok(pixels)
    });
}

async fn coarse(path: &str) -> Result<Vec<u8>, FrameworkError> {
    Image::from_path(path)
        .transform_with("pixelate", Pixelate { size: 8 })
        .to_png()
        .to_bytes()
        .await
}
```

The image holds the settings, not the step, so `Transformation` stays
`Copy`. Clones of the image share them, and they are released when the
last clone is dropped. A step whose settings are not the type the
transformation was registered with fails the image with an error that
names the transformation. So does a settings transformation recorded
with `transform(Transformation::custom(name))`, which carries no
settings, and a transformation registered with `register_transformation`
that is handed settings.

Under the `magick` driver a custom step runs in Rust between two
ImageMagick runs, which pass the image over stdout and stdin as a PNG
that keeps the ICC profile and, while orientation is still to be applied,
the EXIF. A pipeline with a custom step ends with the same profile and
orientation tag as one without. The step contributes no ImageMagick
argument, and its settings reach only your function.

## Terminals

Every terminal is `async`, consumes the `Image`, and runs the decode,
transform, and encode work on a blocking thread so it never stalls the
runtime. Source I/O happens before that hop, so a slow disk never
occupies a blocking worker.

| Terminal | Returns |
|---|---|
| `to_bytes()` | `Vec<u8>` of the encoded file |
| `to_response()` | An `HttpResponse` with the right `Content-Type` |
| `to_base64()` | The encoded file as standard, padded base64 |
| `to_data_uri()` | A `data:` URI: the media type and the base64 bytes |
| `save(path)` | Writes to the filesystem |
| `store(directory, disk)` | Writes to a `Storage` disk under a generated name, returning the path |
| `store_as(directory, name, disk)` | Writes to a `Storage` disk as `directory/name`, returning the path |
| `dimensions()` | `(width, height)` of the **processed** image |
| `width()` / `height()` | One side of `dimensions()` |
| `mime_type()` | The **processed** image's media type |
| `dominant_color()` | The average colour, as `#rrggbb` |

`dimensions()`, `mime_type()`, and `dominant_color()` all describe the
finished image, not the source - the same contract Laravel has. Asking
for the mime type still runs the pipeline, because reporting a type for
an image that cannot actually be produced is a lie the caller would only
discover later.

```rust
use suprnova::{FrameworkError, Image, OutputFormat};

async fn describe() -> Result<(), FrameworkError> {
    let banner = Image::from_path("hero.png").resize(1200, 400);

    // Reads (1200, 400), not the source's dimensions.
    let (width, height) = banner.clone().dimensions().await?;
    println!("{width}x{height}");

    let accent = banner.to_format(OutputFormat::Jpeg).dominant_color().await?;
    println!("{accent}");

    Ok(())
}
```

## Formats

Five formats are read and written: **PNG, JPEG, WebP, GIF, and
BMP**.

| Format | Reads | Writes | Quality knob |
|---|---|---|---|
| PNG | yes | yes | ignored (lossless) |
| JPEG | yes | yes | honoured |
| WebP (`OutputFormat::WebP`) | yes | yes | honoured (lossy; see below for the lossless cases) |
| WebP (`OutputFormat::WebPLossless`) | yes | yes | ignored (lossless) |
| GIF | yes | yes | ignored (palette) |
| BMP | yes | yes | ignored (lossless) |

AVIF is neither read nor written: there is no AVIF encoder crate with a
license compatible with Suprnova's. WebP is the modern-format path.

GIF output is palette-quantised to at most 256 colours with
Floyd-Steinberg dithering before encoding, so a photographic source
converts cleanly rather than erroring.

### WebP

`OutputFormat::WebP` is lossy and uses the quality of the pipeline, the
same dial JPEG has. The quality is `85` when you set none.
`OutputFormat::WebPLossless` is always lossless and ignores the quality.
Use it when the pixels of the file must be exact. Both variants have the
content type `image/webp` and the extension `webp`.

```rust
use suprnova::{FrameworkError, Image, OutputFormat};

async fn encode() -> Result<(), FrameworkError> {
    // Lossy at quality 80.
    let small = Image::from_path("storage/photos/hero.jpg")
        .to_format(OutputFormat::WebP)
        .quality(80)
        .to_bytes()
        .await?;

    // Lossless: the quality has no effect.
    let exact = Image::from_path("storage/photos/hero.jpg")
        .to_format(OutputFormat::WebPLossless)
        .to_bytes()
        .await?;

    Ok(())
}
```

The built-in driver writes `OutputFormat::WebP` lossless, and ignores the
quality, in two cases. In both the lossy form of WebP cannot hold the
image:

- A pixel is not fully opaque. The lossy encoder has no alpha channel,
  so a lossy file would lose the transparency.
- A side is longer than 16383 px, the largest side a lossy frame can
  have.

The ImageMagick driver writes `WebP` lossy at every quality, and keeps
the alpha channel. It writes `WebPLossless` lossless.

A WebP source that you resize and do not convert is written as `WebP`.
An opaque one is therefore written lossy.

Static publication prepares relative images, absolute images on the application's
public origin and raster data URLs. Third-party images are neither transcoded nor
published. Linked stylesheets are build outputs published byte for byte; their images
belong to the build, including small images Vite inlines below `assetsInlineLimit`.
Raster data URLs and same-origin raster `url(...)` references in document style
attributes or `<style>` elements refuse publication; move the image into an
`<img>`, a `<picture>` or a stylesheet file. See [Static publication](static-publication.md#prepare-images) for preparation
and refusal behavior.

### Lossless PNG recompression

Use `recompress_png` when an image must stay PNG. It has no quality
setting and keeps every pixel, transparency and indexed palettes. It
removes text, time and location metadata while keeping the ICC profile
and colour chunks. The returned PNG is no larger than its input.

- `PngEffort::Fast` uses oxipng's default level 2 for page budget audits.
- `PngEffort::Maximum` uses level 6 with Zopfli for PNGs kept during
  static publication. It takes more CPU time.

```rust
use std::path::Path;
use suprnova::{FrameworkError, Image, PngEffort};

async fn compress_icon() -> Result<(), FrameworkError> {
    Image::from_path("storage/icons/app.png")
        .to_png()
        .recompress_png(PngEffort::Maximum)
        .save(Path::new("storage/icons/app-small.png"))
        .await
}
```

The pipeline recompresses after all pixel operations, on a blocking
worker. Its final format must be PNG. Other formats return an error.
The synchronous `suprnova::recompress_png(&bytes, effort)` helper works
on existing PNG bytes without decoding through an image driver or
applying orientation. Async callers run that helper on a blocking worker.

### Why Suprnova diverges

Laravel has no equivalent lossless PNG recompression API. Suprnova uses
oxipng to reduce transfer size without lowering image quality.

## Storage

`from_disk`, `store` and `store_as` work against any registered `Storage`
disk, so a resize-and-restore round trip never touches local paths.

`store(directory, disk)` stores the result in `directory` under a
generated name: 40 random letters and digits and the output format's
extension. `store_as(directory, name, disk)` stores it as
`directory/name`. Both return the path they wrote, with the slashes at
the ends of `directory` and `name` trimmed. `disk` names a disk, and
`None` means the application's default disk (`FILESYSTEM_DISK`):

```rust
use suprnova::{FrameworkError, Image};

async fn make_web_copies() -> Result<(String, String), FrameworkError> {
    // For example "web/8f1Qx...Zt2.webp".
    let generated = Image::from_disk("uploads", "originals/42.png")
        .scale(1024, 1024)
        .to_webp()
        .store("web", Some("uploads"))
        .await?;

    // Exactly "web/42.png", on the default disk.
    let named = Image::from_disk("uploads", "originals/42.png")
        .scale(1024, 1024)
        .store_as("web", "42.png", None)
        .await?;

    Ok((generated, named))
}
```

There is no `store_publicly`: Suprnova sets visibility per disk, so
storing on a disk with a public base URL is what makes a file public.
See [File Storage](filesystem.md) for registering disks and their URLs.

## Decode limits

Decoding is where hostile input does damage: a few kilobytes can declare
a 40000x40000 canvas and ask a server to allocate six gigabytes for it.
Suprnova refuses that before allocating anything.

| Var | Default | Purpose |
|---|---|---|
| `IMAGE_MAX_DIMENSION` | `16384` | Cap on width and height in pixels |
| `IMAGE_MAX_ALLOC_BYTES` | `1073741824` (1 GiB) | Cap on the memory one decode may allocate, and on the size of the source file itself |
| `IMAGE_MAGICK_TIMEOUT_SECS` | `30` | Wall-clock ceiling on one ImageMagick invocation (`magick` driver only) |

The framework parses the input's own header - a few dozen bytes, no
allocation - reads the declared dimensions, and rejects oversized input
before a decoder is constructed. The same caps apply to resize targets,
because `resize(50_000, 50_000)` allocates just as much whether the
numbers came from an attacker or a typo.

A header can also declare a small image over data that asks for far
more, and the default driver bounds that too:

- PNG pixel data that inflates past the size its header declares is
  refused when the inflate reaches that size. A few kilobytes of
  compressed data can expand to gigabytes.
- Only the first frame of an animated GIF is decoded, because the
  pipeline only uses the first frame, and decoding stops the moment that
  frame is complete. A first frame larger than the GIF's logical screen
  is refused before it is decoded.
- A lossless WebP, or a WebP's lossless alpha plane, is read as far as
  its last prefix code before it decodes, and the tables those codes build
  count toward the limit. How many tables there are is written in the
  compressed data, not in a header: 160 KiB of codes can ask for 250 MB
  of tables for a 4x4 image. The read keeps no pixels and holds one
  group's tables at a time, at most about 17 KiB.
- A file or stored source is read no further than
  `IMAGE_MAX_ALLOC_BYTES`, even when the size its storage reports is
  wrong or missing, as it is for a pipe.
- A JPEG's Extended XMP segments are counted before it decodes. The JPEG
  decoder keeps every segment of an unfinished series and re-reads all of
  them after each marker, so the work grows with the square of the
  segment count: 100,000 one-byte segments, about 8 MB, ask for billions
  of comparisons. The default driver counts the bytes those passes would
  read and refuses the JPEG when that is over `IMAGE_MAX_ALLOC_BYTES`. A
  complete series, as cameras and editors write one, is far below it.

### What a decode costs

`IMAGE_MAX_ALLOC_BYTES` is the most memory one decode may allocate, not
only the size of the decoded image. Decoders hold more than the pixels
they return: an inflated PNG next to its unfiltered rows, a progressive
JPEG's coefficients, the canvases a GIF frame is composed on. So the
default driver works out, from the image's headers, how many bytes its
decode will allocate, and refuses the image when that is over the limit.
The refusal names the estimate:

```text
image exceeds configured decode limits: decoding this 8000x6000 image/png
needs about 1923381182 bytes, over the IMAGE_MAX_ALLOC_BYTES limit of 1073741824
```

As a guide, a decode needs about this many times width x height x 4
bytes:

| Format | Times |
|---|---|
| PNG, 8-bit | 1.3 (grey or palette) to 5 (incompressible RGBA) |
| PNG, 16-bit | 2.5 (grey) to 10 (incompressible RGBA). At the 1 GiB default, 16-bit RGBA tops out at about 27 megapixels and 16-bit RGB at about 36 |
| GIF | 1.0 to 1.1 |
| JPEG, sequential (baseline, extended, arithmetic) | 1.0 to 1.1 |
| JPEG, progressive, or one component a scan | 1.5 (grey) to 2.5 (4:4:4) |
| JPEG, lossless | 1.3 (grey) to 4 (RGB) |
| WebP | 1.4 to 2.4 |
| BMP | 1.0 (32-bit) to 1.75 (24-bit) |

An image that decoding turns by its EXIF orientation needs at least 2
times width x height x 4 bytes, the decoded plane and the turned one,
or the table's figure when that is more.

So the default 1 GiB decodes a 48-megapixel photo (8000x6000) in every
8-bit format, a progressive 4:4:4 JPEG and a PNG of incompressible RGBA
included, turned or not. 16-bit PNG holds more and tops out lower, as
the table says.
Raise `IMAGE_MAX_ALLOC_BYTES` if your users upload larger images, or
lower it on a small host.

A limit hit is a 4xx-shaped `FrameworkError::param`, because oversized
input is a client problem, not a server fault.

Out-of-range configuration clamps with a warning rather than failing
boot: `IMAGE_MAX_DIMENSION=0` would reject every image in the
application, which is not what anyone meant to configure.

### One bound is not configurable

A WebP declares its real decoded size in its innermost bitstream chunk,
not in the canvas header, so the framework walks the container to find
it. That walk stops after **4096 chunks per level** and follows nesting
**two levels deep**, and a file that exceeds either is refused outright
rather than measured.

It is refused rather than measured on purpose. Reporting a number from a
walk that did not reach the end of the file would be a gate that a large
enough pile of filler chunks could step around, so an unfinishable walk
has no answer to give.

Neither number is tunable, and no `IMAGE_MAX_*` variable affects them -
the error says so, rather than saying "configured", precisely so nobody
spends an afternoon raising `IMAGE_MAX_ALLOC_BYTES` and watching nothing
change. In practice only a deliberately hostile file gets near it: a
300-frame animation passes comfortably, and a 4100-frame one does not.

## Backends

Like Laravel, the image surface is two drivers, chosen with
`IMAGE_DRIVER`.

| Driver | Value | Needs | Reads |
|---|---|---|---|
| OxideAV | `oxideav` (default) | nothing | PNG, JPEG, WebP, GIF, BMP |
| ImageMagick | `magick` | ImageMagick 7 on the host | PNG, JPEG, WebP, GIF, BMP, HEIC, AVIF, TIFF, and PSD, as far as the host's delegates read them; other formats only with `IMAGE_MAGICK_AUTODETECT=true` |

`IMAGE_DRIVER` sets the driver for the whole process. One image can
choose its own with `using`, which changes the driver of that image and
its clones only:

```rust
use suprnova::{FrameworkError, Image, ImageDriverKind};

// HEIC goes to ImageMagick; every other image stays on the default.
async fn thumbnail(upload: Vec<u8>, is_heic: bool) -> Result<Vec<u8>, FrameworkError> {
    let image = Image::from_bytes(upload).cover(320, 320).to_jpg();
    let image = if is_heic {
        image.using(ImageDriverKind::Magick)
    } else {
        image
    };
    image.to_bytes().await
}
```

### `IMAGE_DRIVER=oxideav`

The default. Pure Rust, built on the [OxideAV](https://github.com/OxideAV)
codec family, with [zune-jpeg](https://github.com/etemesi254/zune-image)
decoding JPEG: no native library, nothing to install, nothing to
configure. It is the right choice for almost every application, and it
is what a scaffolded app gets.

It reads 8-bit JPEGs in every coding: baseline, progressive and
arithmetic, greyscale, YCbCr at 4:4:4, 4:2:2, 4:2:0, 4:4:0 or 4:1:1, RGB,
and lossless. CMYK and 12-bit JPEGs need the `magick` driver, and so does a
lossless JPEG of more than 67,108,864 samples (width x height x
components), which its decoder, oxideav-mjpeg, refuses.

### `IMAGE_DRIVER=magick`

Opt-in. Runs a host-installed ImageMagick 7 binary, piping the image in
over stdin and reading the result back over stdout. The driver writes the
image to no file. ImageMagick itself copies its stdin into its own
temporary directory before it decodes, and deletes the copy when it
exits. The one file the driver writes is its ImageMagick policy; see
[Policy](#policy). The binary name comes from `IMAGE_MAGICK_BINARY` and
defaults to `magick`; a missing binary is a clear error at first use, not
a silent fallback.

Choose it when you need input formats the pure-Rust driver does not
carry - HEIC being the common one. The cost is a host dependency: the
operator installs ImageMagick and its delegates, and owns their
licensing. The framework links nothing and compiles nothing native
either way.

Like the default driver, it works on the first frame of an animation
and drops the rest. A GIF's first frame is composed onto the GIF's
logical screen first, so both drivers produce the same image and report
the same size for it.

Arguments are always a fixed array handed straight to the process, never
a shell string, and every numeric argument is formatted from an
already-validated field. A rotation background is a typed `Color` that
the driver formats itself. The arguments that choose which metadata
ImageMagick keeps are fixed strings. A custom transformation adds no
argument: it runs on the pixels between two runs. There is no argument
position user input can reach.

Unless you opt into autodetection, the decoder is named on the command
line - `png:-` or `heic:-`, never a bare `-`. That matters: given a bare `-`, ImageMagick picks a
coder from the bytes it is handed, so a file whose magic says MVG or MSL
is read as a *script* regardless of what your application believed it
was accepting. A named coder makes a mislabelled file fail instead of
becoming something else.

Suprnova names the format from the input's leading bytes and hands
ImageMagick the matching coder:

| Input | Coder |
|---|---|
| PNG, JPEG, WebP, GIF, BMP | `png`, `jpeg`, `webp`, `gif`, `bmp` |
| HEIC, and other HEIF images | `heic` |
| AVIF | `avif` |
| TIFF and BigTIFF | `tiff` |
| Photoshop PSD and PSB | `psd`, `psb` |

The first five are the formats the default driver reads too. HEIC and
AVIF read only when the host's ImageMagick carries the libheif delegate,
and TIFF only with libtiff.

Input that matches none of these is refused before ImageMagick starts,
with a 4xx `FrameworkError` that says the format is not one Suprnova
names. An MVG or MSL document, and input that names a pseudo-coder such
as `url:`, never reaches ImageMagick.

**Autodetection is an opt-in, and it hands the coder choice back to
ImageMagick.** To read a format Suprnova does not name, such as PPM or
JPEG XL, set:

```env
IMAGE_MAGICK_AUTODETECT=true
```

Input the framework cannot name then goes to ImageMagick on a bare `-`,
and ImageMagick chooses the coder from its bytes, MVG and MSL included.
The framework's [policy](#policy) is then what keeps such an upload away
from the script, network, and Ghostscript coders, so turn autodetection
on only when you need it. The formats in the table keep their named
coder either way. Any value other than `true`, `1`, `yes`, or `on` leaves
autodetection off. `ImageConfig` carries the setting as its
`magick_autodetect` field, and `ImageConfig::magick_autodetect(true)`
sets it on a configuration you build. The default `oxideav` driver
ignores it.

#### Policy

Every ImageMagick run reads Suprnova's own security policy, whether or
not autodetection is on. Before each run, the driver writes the policy as
`.config/ImageMagick/policy.xml` inside a directory of its own, checks
that the file holds exactly the framework's text, and writes it again
when it does not. The driver then starts ImageMagick with `HOME` naming
that directory, and with `MAGICK_CONFIGURE_PATH` naming the directory
that holds the file first and last, around any value you set and the
service account's own ImageMagick directory (`$XDG_CONFIG_HOME/ImageMagick`,
else `$HOME/.config/ImageMagick`). The policy denies the following:

- The coders that fetch from the network: `URL`, `HTTP`, `HTTPS`, and
  `FTP`.
- ImageMagick's drawing and scripting languages: `MVG` and `MSL`.
- The coders that draw text, which read a file their input names:
  `TEXT`, `LABEL`, `CAPTION`, and `PANGO`.
- The coders that read the server's display: `SCREENSHOT` and `X`.
- `EPHEMERAL`, which deletes the file it reads.
- The formats ImageMagick hands to Ghostscript: `PS`, `PS2`, `PS3`,
  `EPS`, `PDF`, and `XPS`.
- Every delegate: the external programs, such as Ghostscript and
  Inkscape, that ImageMagick starts for a format.
- Indirect reads, where an argument that starts with `@` names a file to
  read in its place.

HEIC, AVIF, TIFF, and PSD read through ImageMagick's own coders and the
libraries it links, not through delegates, so they still read.
`MagickCliDriver::POLICY` holds the exact text.

The directory is `suprnova-magick-policy-<pid>-<random>` under the
system's temporary directory (`TMPDIR`, or `/tmp`). Each process makes
one. The directory, and the `.config` and `.config/ImageMagick`
directories inside it, are open to their owner alone. When the driver
can't make them, or can't write and check the file, it refuses the run
before ImageMagick starts, with a 5xx `FrameworkError` that names the path
and the cause, whether or not autodetection is on. When one of the three
is removed while the process runs, as a temporary-file cleaner removes
old ones, or is replaced by a link or opened to other users, the next run
makes a new directory. The directory stays after the process exits; it
holds one small file.

Suprnova's policy is the last one ImageMagick reads, so it outranks every
other policy on the host. ImageMagick reads every `policy.xml` it finds,
in this order: the directories in `MAGICK_CONFIGURE_PATH`, then its own
configuration directory, then `$XDG_CONFIG_HOME/ImageMagick`, then
`$HOME/.config/ImageMagick`. Where two entries match, the last one it
read wins. The driver's `HOME` is its policy directory, so Suprnova's
denials outrank a grant in any other file, including an entry marked
`stealth="true"`. Your own denials still apply. To add a policy of your
own, put it in a directory on `MAGICK_CONFIGURE_PATH`, in
`$XDG_CONFIG_HOME/ImageMagick`, or in the service account's own
`~/.config/ImageMagick`: the driver puts that directory on
`MAGICK_CONFIGURE_PATH` after your value, so a `policy.xml` or any other
ImageMagick configuration file there applies to its runs as it did
before, under Suprnova's policy.

The driver checks that order on the binary it runs. Before the first run
of each process, it starts the same binary as `magick -list policy`,
with the same environment its runs get, and reads the policy in effect
from the listing. It also runs one MVG probe, a one-line MVG script read
as `mvg:-` that the policy in effect must refuse. The check fails when
any of the following is true:

- The listing shows a file that ImageMagick read after Suprnova's policy.
  An entry in that file could outrank Suprnova's, so the check fails
  whatever the file holds.
- The last entry that matches a coder, a delegate, or an `@` read that
  Suprnova denies grants it, such as `rights="read|write" pattern="MVG"`
  or a grant on `pattern="*"`.
- A denied coder is missing from the listing, which means ImageMagick
  did not apply Suprnova's policy.
- The listing can't be read.
- ImageMagick's security policy doesn't refuse the MVG probe.

A check that fails refuses every run, with or without autodetection, with
a 5xx `FrameworkError` that names the cause and, where there is one, the
file. Fix the host, then restart the process. The driver checks once for
each binary and `MAGICK_CONFIGURE_PATH` value, and keeps the verdict for
the life of the process. The verdict is about the order the binary reads
its policy files in, which a change to a host's policy file doesn't move:
a grant added later is read before Suprnova's file and outranked like any
other. When `magick -list policy` fails, or the listing or the probe
can't be run at all, the run is refused, nothing is kept, and the next run
checks again.

Decode limits are enforced twice under this driver. For the five formats
the framework can parse, the header check above runs before the process
is spawned. For the other formats in the table, and for any input under
autodetection, a pre-parse is impossible, so every invocation carries
ImageMagick's own `-limit` flags derived from the same configuration,
including a wall-clock `-limit time`.

That flag is not the whole story, because ImageMagick enforces it with
its own resource monitor, and a process wedged inside a delegate before
that monitor engages never trips it. So Suprnova also holds its own
deadline: past `IMAGE_MAGICK_TIMEOUT_SECS` (plus a couple of seconds of
grace for IM's own limit to fire first) it kills the process group -
delegates included, not just the process it started - and stops waiting
on the pipes. A stalled delegate therefore cannot pin a worker thread.
Delegates that stay in the process group die with it; one that leaves the
group, or a host with no `kill` binary, can outlive the request - that
residual is what host process supervision is for.

A kill surfaces as a 5xx `FrameworkError::internal`, not a 4xx, even
though a request triggered it. Something wedged the image path badly
enough to need killing, which belongs in server-error monitoring where
an operator will see it - classifying it as a client error would file
away the one condition here worth paging on.

## Custom drivers

`ImageDriver` is the extension point: `&[u8]` in, `Vec<u8>` out, no
codec type crossing the boundary.

```rust
use suprnova::{FrameworkError, ImageDriver, ImagePipeline};

struct MyDriver;

impl ImageDriver for MyDriver {
    fn process(
        &self,
        contents: &[u8],
        pipeline: &ImagePipeline,
    ) -> Result<Vec<u8>, FrameworkError> {
        // Decode `contents`, replay `pipeline.transformations`, then encode
        // to `pipeline.format` at `pipeline.quality`. Give every
        // `OutputFormat` variant an arm, `WebPLossless` included: the
        // enum is not `#[non_exhaustive]`. `Transformation` is, so its
        // match ends in a wildcard arm that returns an error naming the
        // step. Run a `Transformation::Custom` step with
        // `apply_with(pixels, &pipeline.settings)`, which hands a step
        // recorded with `transform_with` its settings.
        todo!()
    }

    fn dimensions(&self, contents: &[u8]) -> Result<(u32, u32), FrameworkError> {
        todo!()
    }

    fn dominant_color(&self, contents: &[u8]) -> Result<String, FrameworkError> {
        todo!()
    }

    fn name(&self) -> &'static str {
        "mine"
    }
}
```

Install it during `bootstrap()`, before the first image is processed:

```rust
use suprnova::FrameworkError;

pub fn register() -> Result<(), FrameworkError> {
    suprnova::media::set_default_driver(Box::new(MyDriver))
}
```

A conforming driver enforces the configured `ImageConfig` limits before
allocating for a decode. The framework cannot do it on a driver's
behalf, because it never sees the decoded buffer.

`ImageConfig` is `#[non_exhaustive]`: start from
`ImageConfig::default()` or `ImageConfig::from_env()` and set the fields
you change, rather than writing a struct literal.

### Reaching more formats

If the built-in five are not enough, there are three routes, in rough
order of how much you take on:

1. **The built-in `magick` driver.** Set `IMAGE_DRIVER=magick`. It
   reads HEIC, AVIF, TIFF, and PSD through the host's ImageMagick
   delegates, and any other format they read once you opt into
   [autodetection](#image_drivermagick). There is no build dependency
   to manage.
2. **A custom driver around libvips**, for example via the
   [libvips-rust-bindings](https://github.com/olxgroup-oss/libvips-rust-bindings)
   crate (MIT). libvips is the engine behind Node's `sharp`, with a very
   wide format range - JPEG, JPEG XL, TIFF, PNG, WebP, HEIC, AVIF, PDF,
   SVG, GIF, and more, plus ImageMagick delegation - and strong
   streaming performance. It binds the libvips C library, so your app
   installs libvips at build and run time and owns that dependency,
   which is exactly why it belongs behind the trait rather than in the
   framework. One practical note: the binding's `VipsImage` is not
   thread safe, which the one-image-per-`process()`-call driver shape
   already accommodates.
3. **Any CLI tool**, wrapped the way the `magick` driver is: a fixed
   argument array handed to `std::process::Command`, image bytes over
   stdin and out over stdout, never a shell string.

Suprnova endorses the trait boundary, not any particular dependency
behind it. What sits back there is your call, and so is its licensing.

## Testing

The subsystem needs no fixtures on disk - it is its own fixture factory
once decode and encode round-trip:

```rust
use suprnova::{FrameworkError, Image, OutputFormat};

/// Grow a 1x1 byte-literal fixture into whatever size a test needs.
async fn fixture(source: &[u8]) -> Result<Vec<u8>, FrameworkError> {
    Image::from_bytes(source.to_vec())
        .resize(4, 2)
        .to_format(OutputFormat::Png)
        .to_bytes()
        .await
}
```

Tests that tighten the decode limits must be serialised: the limits are
process-global, so a parallel sibling would decode under the tightened
cap.

### Why Suprnova diverges

**No HEIC in the default driver, and the reason is patents.** HEVC, the
codec inside HEIC, is patent-encumbered - the Access Advance pool among
others. Suprnova installs no native libraries, so a built-in decoder
would have to be pure Rust and would carry that exposure directly, and
the one credible pure-Rust decoder is dual AGPL-3.0/commercial, which is
a per-application legal obligation rather than something an MIT
framework gets to default anybody into.

Both frameworks make HEIC a host-provisioning concern; Suprnova's
version just has one fewer moving part. Laravel's default driver, GD,
cannot read HEIC at all, and its Imagick path needs the libheif delegate
compiled into **both** the system ImageMagick binary and the PHP
`imagick` extension. In Suprnova the default driver does not read HEIC,
and `IMAGE_DRIVER=magick` reads it whenever the host's ImageMagick
carries the libheif delegate - no extension layer in between. So HEIC
ingestion works: install ImageMagick with libheif through your
package manager, and send HEIC uploads to it with
`using(ImageDriverKind::Magick)`, or set `IMAGE_DRIVER=magick` for every
image. The licensing sits where it belongs, with the host.

When the `oxideav` driver meets a HEIC file it says so by name, points
at this chapter, and names both ways forward, rather than returning a
generic "unsupported format".

**The `magick` driver names the coder.** Laravel's Imagick driver reads
an upload with Intervention Image, which hands Imagick the bytes without
a format, so ImageMagick chooses the coder from them and the host's
`policy.xml` decides whether an MVG or MSL script runs. Suprnova names
the coder for every format it recognises and refuses other bytes before
ImageMagick starts, so the barrier holds on a host whose policy is the
default. `IMAGE_MAGICK_AUTODETECT=true` gives you Laravel's coder choice
back. Laravel leaves ImageMagick's policy to the host; Suprnova runs
every invocation under a [policy](#policy) of its own as well, which
ImageMagick reads last, and checks that order before its first run, so
the script, network, and Ghostscript coders stay closed whatever the
host's policy grants.

**No base64 or URL constructors.** Laravel's `ImageManager` has
`->read($base64)` and `->read($url)`. `from_bytes` composes with
whatever produced the bytes, including the [HTTP client](http-client.md),
and keeping a URL fetch out of the image subsystem keeps its timeouts,
retries, and SSRF policy in one place instead of two.

**`from_stream` is eager, with a cap.** Laravel's contents are a lazy
closure. A stream cannot be replayed, so this one is drained at
construction, counting bytes against `IMAGE_MAX_ALLOC_BYTES` as it goes.

**`contain` does not pad.** It fits the image inside the box and stops
there; it does not letterbox onto a background. Compose it with a
background yourself if you need one.

**Metadata is stripped by default.** Laravel's Imagick driver keeps
every profile, the GPS position included, and its GD driver drops all of
them, the colour profile included. Suprnova keeps the ICC profile and
drops the rest, in both drivers, so a stored upload neither leaks where
it was taken nor shifts colour. Laravel also returns an upload's original
bytes when the pipeline changes nothing; Suprnova always re-encodes, so
every output is stripped.

**Rotation keeps transparency where the format holds it.** Laravel fills
exposed corners with white in every format. Suprnova fills them with
white for JPEG and GIF and leaves them transparent for PNG, WebP and BMP,
unless you name a colour.

**A custom transformation is a pixel function.** Laravel's
`transformUsing` adds a handler to one driver, written against that
driver's library. Suprnova's `register_transformation` takes a function
over decoded RGBA that both drivers run, so changing `IMAGE_DRIVER` never
drops a step, and no custom code reaches an ImageMagick argument.
Laravel's handler receives the transformation object with its fields;
here those fields are the settings `transform_with` records, which the
image holds so that a step stays plain `Copy` data.

**No `store_publicly`.** Visibility belongs to the disk in Suprnova, so
`store` and `store_as` on a public disk are the public variants.

**Resize uses bilinear resampling.** The backend's filter set ships
nearest-neighbour and bilinear; bilinear is its documented default for
natural images.

**Images are never serialisable.** Laravel throws on `__serialize` and
Suprnova simply does not implement it. Store the path or the disk key
and rebuild the pipeline.

## Next

- [File Storage](filesystem.md) for the disks `from_disk` and `store` read and write.
- [HTTP Responses](responses.md) for what `to_response()` hands back.
- [Environment Variables](env-vars.md) for the full list of image settings.


---

<!-- /docs/localization -->

# Localization

Localization in Suprnova is one module with four faces: message catalogs
on the server, validation errors that arrive already translated, the
*same* catalog bytes handed to the browser, and locale-aware number,
date, and list formatting. The message format is
[Fluent](https://projectfluent.org) - Mozilla's `.ftl`, the one Firefox
ships - and the whole subsystem is on by default behind the
`localization` feature.

The starter kits render plain English and ship no translations: no `lang/`
directory, browser wrapper, Fluent dependency or locale middleware. The
framework's localization remains available for applications that need it.

The shortest possible tour. Add catalogs and register
[`LocaleMiddleware`](#locale-detection), then use the messages:

```ftl
# lang/en/app.ftl
welcome = Welcome to { $app }!
```

```ftl
# lang/es/app.ftl
welcome = ¡Bienvenido a { $app }!
```

Use it from a handler:

```rust
use suprnova::{__, handler, HttpResponse, Request, Response};

#[handler]
pub async fn greet(_req: Request) -> Response {
    Ok(HttpResponse::text(__!("welcome", app: "Suprnova")))
}
```

A request with `Accept-Language: es` gets the Spanish string, because
`LocaleMiddleware` resolved the locale before your handler ran. Nothing
else in the handler changes - no locale parameter threaded through, no
`&Translator` in the signature.

## Why localization

Three reasons this is a framework concern rather than a crate you pick:

- **Validation messages are the framework's strings, not yours.** "The
  email field is required." is emitted deep inside `Rule::passes`, far
  from any code you own. Unless the framework carries a translation
  seam, a Spanish app ships English validation errors - or you wrap
  every rule by hand. Suprnova's built-in rules return *keyed* messages;
  you translate them by dropping a `.ftl` file in, and never touch the
  rules.
- **The browser needs the same strings.** An Inertia app renders half
  its text in Rust and half in Svelte/React/Vue. Two translation systems
  means two file formats, two review workflows, and two chances for the
  same sentence to drift. Suprnova serves the exact catalog the server
  resolved from `/_suprnova/lang/<locale>.ftl` for applications that add
  browser translation. For server-rendered pages, translate in Rust and
  pass the text in props so SSR and the browser render the same strings.
- **Plurals and formats are CLDR data, not string concatenation.**
  English has two plural categories, Russian and Polish four, Arabic six.
  A number is `1,234.56` in `en-US` and `1.234,56` in `de-DE`. Fluent selects on
  CLDR plural categories and ICU4X does the formatting, so neither is
  something you hand-roll per locale.

Turning the feature off (`--no-default-features`) is supported: the
localization module doesn't compile, and validation renders its embedded
English fallback strings. Nothing else changes shape.

## File layout

When you add translations, put catalogs under `lang/`, one directory per
locale. The kits do not create this tree:

```
myapp/
├── lang/
│   ├── en/
│   │   ├── app.ftl
│   │   └── validation.ftl
│   └── es/
│       ├── app.ftl
│       └── validation.ftl
├── src/
└── frontend/
```

The rules:

- **A directory name is a BCP-47 locale** - `en`, `en-GB`, `pt-BR`,
  `zh-Hans`. A directory whose name doesn't parse is skipped with a
  `warn!` rather than failing boot.
- **Every `.ftl` in a locale directory merges into one catalog**, in
  sorted filename order. Split by feature (`auth.ftl`, `billing.ftl`,
  `emails.ftl`) as much as you like - message ids are global within the
  locale, so `auth.ftl` and `billing.ftl` must not define the same id.
- **The framework's own English validation catalog loads first**, into
  every locale's bundle. Your files load over it, and a later definition
  wins. That is the whole override mechanism: define `validation-min` in
  `lang/es/validation.ftl` and the Spanish bundle uses yours.
- **The root is `lang_path()`** - `<APP_BASE_PATH>/lang`. Set
  `APP_BASE_PATH` when the binary runs from somewhere other than the
  project root (a systemd unit, a container with a different
  `WorkingDirectory`), or call `use_lang_path("…")` to move only the
  `lang` directory. See [Environment Variables](env-vars.md).
- **A missing `lang/` directory is not an error.** A fresh app must
  boot, so the translator comes up with the embedded English catalog and
  nothing else. A *malformed* `.ftl` is a different story: parse errors
  fail boot, naming the file and what the parser objected to, because a
  silently half-loaded catalog is worse than a stopped process.
- **In `local` and `development`, catalogs hot-reload.** Each request
  stats `lang/` and reparses only when something actually changed, so
  editing a `.ftl` shows up on the next refresh. Production never
  re-stats; catalogs are read once at boot. A deploy hook that ships new
  catalogs to a running process calls `Lang::reload().await`. Both reloads
  also make the [RenderCache](render-cache.md) entries rendered from the
  old text miss; `Translator::reload` alone swaps the catalogs and leaves
  those entries valid until they expire.
- **`lang/vendor/` is not a locale.** It holds your overrides of a
  package's namespaced catalogs, described below.

### Catalogs from other directories

A package, or a shared directory of translations, adds catalogs beside
`lang/` with three calls, made in your bootstrap before the server boots.
Each directory has the same layout as `lang/`: one subdirectory per
locale, holding `.ftl` files.

```rust
use suprnova::Lang;

pub async fn register() {
    // Merged after lang/: its message wins over yours.
    Lang::add_path("vendor/acme-billing/lang").expect("billing catalogs");
    // Merged before lang/: your message wins over its.
    Lang::add_fallback_path("shared/lang").expect("shared catalogs");
    // Read as `courier::key`, and overridden by lang/vendor/courier/.
    Lang::add_namespace("courier", "vendor/courier/lang").expect("courier catalogs");
}
```

- **`Lang::add_path(dir)`** adds a directory merged after `lang/`, as
  Laravel's `Lang::addPath` does. Several added paths merge in the order
  you add them, a later one's message winning.
- **`Lang::add_fallback_path(dir)`** adds a directory merged before
  `lang/`, so your message wins, as Laravel merges the JSON paths of
  `Lang::addJsonPath` before its own. Use it for a package's defaults.
- **`Lang::add_namespace(namespace, dir)`** registers a package's
  catalogs under a namespace, as Laravel's `Lang::addNamespace` does. You
  read them as `namespace::key`: `Lang::get("courier::bye")`. You override
  one with a file under `lang/vendor/<namespace>/<locale>/`, which wins
  over the package's. A namespace is a letter followed by letters, digits
  and `-`; one that is empty or holds `/`, `\`, `..` or a NUL byte, or any
  other character, is refused with an error.
- **`Lang::loader()`** answers the sources the translator reads: `lang/`
  and every path, fallback path and namespace added so far, as Laravel's
  `Lang::getLoader` does. The framework builds its translator from it at
  boot, so the sources you register before then reach it.

A source added after boot reaches the bound translator at once, which
rebuilds its catalogs; a malformed `.ftl` in it is an error and leaves the
catalogs as they were. Pages the [RenderCache](render-cache.md) already
holds keep their text until `Lang::reload().await` or their TTL. To build a
translator from sources yourself, call
`FluentTranslator::from_sources(sources, &config)` with a
`TranslationSources`; `FluentTranslator::from_dir(dir, &config)` still reads
one directory.

A Fluent message id cannot hold `::`, so a namespaced key is written
`namespace__key` in a catalog: the message `bye` of the namespace
`courier` is `courier__bye`, and its term `-brand` is `-courier__brand`.
The served catalog the browser fetches holds them in that form, and the
browser helper must encode `courier::bye` the same way before looking
the key up. Don't give your own messages ids of the form
`<namespace>__<key>`: they would collide with the namespace's.

### Why Suprnova diverges

- **Namespaced keys are encoded in the catalog.** Laravel keeps a
  namespace's lines apart and looks `courier::bye` up in them; Fluent ids
  cannot hold `::`, so here the namespace's messages join the locale's
  catalog as `courier__bye`, which is also what the browser fetches.
- **A namespace is an identifier.** Laravel accepts any string as a
  namespace; here it must be a letter followed by letters, digits and
  `-`, so it can be part of a Fluent id. Laravel checks a locale and a
  group before it builds a path from them; here the namespace is checked
  when you register it.
- **A fallback path holds `.ftl` catalogs.** Laravel's JSON paths hold
  `<locale>.json` files; `add_fallback_path` takes a directory with the
  same layout as `lang/`, merged at the same place in the order.

## FTL in five minutes

Fluent is a small format. This section is everything you need for a
typical app.

**Messages** are `id = value` pairs. Ids are kebab-case by convention
(the framework's own are), values run to end of line, and indented
continuation lines are joined:

```ftl
# A comment. Attached to the message below it.
sign-in = Sign in
password-hint =
    Use at least 12 characters. A passphrase of a few
    ordinary words beats a short string of symbols.
```

**Arguments** are `{ $name }` placeables. You supply them at call time;
missing arguments are an error, not an empty string (`Lang::get` then
falls through its chain - see [The `Lang` facade](#the-lang-facade)):

```ftl
greeting = Hello, { $name }!
invoice-line = { $qty } × { $item }
```

**Terms** start with `-`, are private to the catalog, and exist so a
brand name or a repeated phrase lives in one place:

```ftl
-product-name = Suprnova
about = About { -product-name }
footer = © 2026 { -product-name }. All rights reserved.
```

**Selectors** are Fluent's conditional. The selector value is matched
against variant keys; exactly one variant is marked default with `*`:

```ftl
cart-summary =
    { $count ->
        [0] Your cart is empty.
        [one] One item in your cart.
       *[other] { $count } items in your cart.
    }
```

`[0]` matches the literal number zero. `[one]` and `[other]` are **CLDR
plural categories**, resolved for the bundle's locale - which is where
Fluent earns its place. English has two categories; Russian has four,
and a Russian translator writes all four without you changing a line of
Rust:

```ftl
# lang/ru/app.ftl
unread-messages =
    { $count ->
        [one] У вас { $count } непрочитанное сообщение.
        [few] У вас { $count } непрочитанных сообщения.
        [many] У вас { $count } непрочитанных сообщений.
       *[other] У вас { $count } непрочитанного сообщения.
    }
```

CLDR assigns `1`, `21`, `31` to `one`; `2`-`4`, `22`-`24` to `few`;
`0`, `5`-`20`, `25`-`30` to `many`; and fractions to `other`. The same
`__!("unread-messages", count: 22)` call renders correctly in English,
Russian, Polish, and Arabic, because the category selection is data, not
code.

**Always put the `*` on `other`.** It is the one category CLDR defines
for every locale, so it is the only variant guaranteed to exist - and
the default is what an unmatched selector value falls through to,
including any non-integer count. Marking `*[many]` (or any other
category) as the default sends fractions to text written for whole
numbers.

> **Pass counts as numbers.** `__!("unread-messages", count: 3)` sends a
> JSON number and selects a plural category. `count: "3"` sends a
> string, which can only match a literal variant key - it will land on
> your `*[other]` default. This is the one FTL trap worth memorising.

**Functions** are called inside placeables. Two are registered:
`NUMBER()` (Fluent's builtin) and `DATETIME()` (Suprnova's):

```ftl
score = Your score is { NUMBER($points) } out of { NUMBER($total) }.
published = Published { DATETIME($when, dateStyle: "medium") }
```

See [Locale-aware formatting](#locale-aware-formatting) for both. A
message may share a function's name: `NUMBER = Number` keeps its key, and
`{ NUMBER($points) }` elsewhere still calls the function.

**One deliberate limitation:** Suprnova resolves flat message *values*
only. Fluent's attribute syntax (`login .placeholder = …`) parses but is
not addressable through `Lang::get`, so keep one id per string:
`login-placeholder`, not `login.placeholder`. Ids are a flat namespace
per locale - prefix them (`auth-login-title`, `billing-invoice-due`)
rather than reaching for a hierarchy the resolver doesn't have.

## The `Lang` facade

`Lang` is the server-side entry point. Every method reads the **current
locale**, which the middleware bound for this request.

| Method | Returns | Notes |
|---|---|---|
| `Lang::get(key)` | `String` | Infallible. Runs the fallback chain, then returns the key itself |
| `Lang::get_with(key, args)` | `String` | Same, with arguments |
| `Lang::try_get(key)` | `Result<String, FrameworkError>` | Errors instead of degrading |
| `Lang::try_get_with(key, args)` | `Result<String, FrameworkError>` | Same, with arguments |
| `Lang::has(key)` | `bool` | Whether the key resolves for the current locale, or anywhere along its fallback chain. A message with attributes and no value does not count |
| `Lang::locale()` | `Locale` | The current locale |
| `Lang::set_locale(locale)` | `()` | Change it for the rest of this request |
| `Lang::available_locales()` | `Vec<Locale>` | Every locale with a loaded catalog |
| `Lang::reload()` | `Result<bool, FrameworkError>` (async) | Re-reads the catalogs and invalidates the cached pages built from them; `true` when a catalog's text changed |

```rust
use suprnova::{Lang, Locale, TranslateArgs};

let subject = Lang::get("password-reset-subject");

let mut args = TranslateArgs::new();
args.insert("name".into(), serde_json::json!("Ada"));
args.insert("count".into(), serde_json::json!(3));
let body = Lang::get_with("unread-messages", args);

if Lang::has("beta-banner") {
    // Only some locales ship the banner copy.
}

let locales: Vec<String> = Lang::available_locales()
    .iter()
    .map(Locale::as_str)
    .collect();
```

`TranslateArgs` is an ordered map of `String` to `serde_json::Value`,
both re-exported from the crate root. Fluent arguments are strings and
numbers; other JSON shapes are stringified.

### The fallback chain

`Lang::get` never fails, and it never returns an empty string. In order:

1. The **current locale's** catalog.
2. Its **configured fallback parents** (see [Fallback
   chains](#fallback-chains)), walked transitively, if any are
   configured - `pt-PT` before `pt-BR` before whatever `pt-BR` itself
   names as a parent, and so on.
3. The **fallback locale's** catalog (`APP_FALLBACK_LOCALE`, default
   `en`), unless it already appeared earlier in this chain.
4. The **key itself**, plus one `tracing::warn!` per missing
   `(locale, key)` pair - once, not once per request, so a missing key
   in a hot path doesn't drown your logs.

Step 4 is why a missing translation renders `checkout-submit` in the
button instead of a blank button: a visibly wrong string is a bug report
waiting to happen, while an empty one is a mystery.

When you'd rather know than degrade, use the `try_*` siblings. They run
steps 1 through 3 and return `Err` instead of doing step 4:

```rust
use suprnova::Lang;

// A missing key here means a broken email - fail the job, don't send
// a message with a raw key in the subject line.
let subject = Lang::try_get("invoice-paid-subject")?;
```

### The `__!` macro

`__!` is the Laravel-muscle-memory shorthand. With no arguments it calls
`Lang::get`; with named arguments it builds a `TranslateArgs` and calls
`Lang::get_with`:

```rust
use suprnova::__;

let plain = __!("welcome-back");
let greeted = __!("greeting", name: "Ada");
let counted = __!("unread-messages", name: "Ada", count: 3);
```

Argument values are anything that converts into a
`serde_json::Value` - `&str`, `String`, integers, floats, `bool`. The
macro is exported at the crate root, so `suprnova::__!("welcome-back")`
works without the import when you'd rather not bring `__` into scope.

## Fallback chains

`APP_FALLBACK_LOCALE` is one global net under every locale. Sometimes
that's not enough: European Portuguese and Brazilian Portuguese share
nearly everything and diverge on a handful of words
(`ficheiro`/`arquivo`, `utilizador`/`usuário`, `tu`/`você`), and
maintaining two complete catalogs means every new string has to be
written twice. A **fallback parent** lets `pt-PT` inherit from `pt-BR`
before `pt-BR` falls further back to the global `fallback_locale` - so
`lang/pt-PT/` only has to hold the strings that are actually different.

### Configuring parents

One environment variable, comma-separated `child=parent` pairs:

```env
APP_LOCALE_PARENTS=pt-PT=pt-BR
```

Or the builder, one call per pair, chainable:

```rust
use suprnova::{Config, Locale, LocalizationConfig};

pub fn register_all() {
    let localization = LocalizationConfig::from_env()
        .expect("APP_LOCALE / APP_FALLBACK_LOCALE must be valid BCP-47")
        .parent(
            Locale::parse("pt-PT").expect("valid locale"),
            Locale::parse("pt-BR").expect("valid locale"),
        );

    Config::register(localization);
}
```

Both paths feed the same map (`LocalizationConfig::parents`), and both
are validated at boot, not at request time:

- A pair with no `=`, or an empty child or parent, is a malformed
  `APP_LOCALE_PARENTS` entry - boot fails naming the bad segment.
- A locale invalid as BCP-47 on either side of the pair fails the same
  way.
- Naming the same child twice is ambiguous config, not last-wins - boot
  fails naming the duplicate child.
- **A cycle fails boot.** The error spells out the cycle: two locales
  naming each other (`pt-PT=pt-BR,pt-BR=pt-PT`) produces
  `` `pt-PT` -> `pt-BR` -> `pt-PT` ``. A locale naming itself as its own
  parent (`pt-PT=pt-PT`) is the same case in miniature -
  `` `pt-PT` -> `pt-PT` ``. (Two code paths raise this error: parsing
  `APP_LOCALE_PARENTS` - so any app whose config goes through
  `LocalizationConfig::from_env()` fails at config load - and
  `FluentTranslator`'s catalog load, which catches a cyclic map built
  programmatically with `.parent(...)`. Only an app that builds its
  config entirely by hand *and* binds its own custom `Translator` in
  `bootstrap_fn` skips both; `Lang`'s walk is guarded independently and
  still terminates safely there, it just won't get the loud boot-time
  error.)

The builder's `.parent(child, parent)` is last-write-wins for a repeated
child - a later call overriding an earlier one is just a later
override, not the ambiguous-input case `APP_LOCALE_PARENTS` guards
against.

### Resolution order

A chain can be more than one hop long: `pt-PT` names `pt-BR` as its
parent, and `pt-BR` can in turn name a parent of its own.
`Lang::get` / `try_get` / `get_with` / `try_get_with` / `has` all walk
the whole thing, current locale first:

1. The **current locale's** catalog.
2. Its **configured parent**, then *that* locale's configured parent,
   transitively, until a locale with no configured parent is reached.
3. The global **`fallback_locale`** (`APP_FALLBACK_LOCALE`), unless it
   already appeared earlier in the chain - including the common case
   where it's just the current locale itself (the `en`/`en` default).

`Lang::get` / `Lang::get_with` fall through to the key itself if
nothing in the chain resolves it, exactly as [The fallback
chain](#the-fallback-chain) describes; `Lang::try_get` /
`Lang::try_get_with` return `Err`, and `Lang::has` returns `false`. This
walk runs inside the `Lang` facade itself, so it works for **any**
`Translator` - the bundled `FluentTranslator`, or a driver you write.

### A runnable example

```
myapp/
├── lang/
│   ├── pt-BR/
│   │   ├── app.ftl
│   │   └── validation.ftl
│   └── pt-PT/
│       └── app.ftl
├── src/
└── frontend/
```

```ftl
# lang/pt-BR/app.ftl
welcome = Bem-vindo ao { $app }!
file-label = Arquivo
```

```ftl
# lang/pt-PT/app.ftl
file-label = Ficheiro
```

```rust
use suprnova::__;

// A request that resolved to `pt-PT`.
assert_eq!(__!("file-label"), "Ficheiro");                    // pt-PT's own override
assert_eq!(
    __!("welcome", app: "Suprnova"),
    "Bem-vindo ao Suprnova!"                                  // inherited from pt-BR
);
```

`lang/pt-PT/` never defines `welcome` - it doesn't need to. `file-label`
is a genuine one-word difference between the two catalogs, so it's the
only id that gets a file.

### Served catalogs are flattened

The `/_suprnova/lang/pt-PT.ftl` endpoint (see [The catalog
endpoint](#the-catalog-endpoint)) never asks the browser to know that
`pt-BR` exists. `FluentTranslator` pre-merges the whole chain into one
resource per locale at load time - the embedded framework catalog at
the bottom for `en`/`en-*` locales, then the configured parent chain,
then the locale's own files - and serves *that*, already flattened.
Fetch `pt-PT.ftl` and the response carries `welcome` and `file-label`
both, in one request, with no client-side chain logic. `?v=<hash>`
still names one immutable resource; the hash simply now covers strings
pulled in from `pt-BR` too.

**Flattening covers configured parents only** - it never reaches past
them to `fallback_locale`. `pt-PT`'s served catalog includes `pt-BR`'s
strings because `pt-BR` is a *configured parent*; it does not include
`en`'s strings just because `en` happens to be the global fallback.
`LocaleShare`'s `fallback` field always names the terminal
`fallback_locale`, unaffected by any of this - it tells the frontend
where `Lang`'s facade-level walk would eventually land, not what's
already in the file it just fetched.

### Delta-file merge rules

A child catalog merges over its parent **at the Fluent AST level**, not
by textual concatenation and not by whole-message shadowing. The
override unit is the *pattern*, so:

- **A child value replaces the parent's value**, in the parent's
  position in the file.
- **A child entry with attributes but no value keeps the parent's
  value.** Retranslating `.placeholder` doesn't require repeating the
  message's own text.
- **Attributes merge by name.** A same-named child attribute replaces
  the parent's, in place; a child-only attribute appends after the
  parent's own. **Attributes the child doesn't mention survive from the
  parent** - overriding a message's value never silently drops its
  `.placeholder` or `.aria-label`.
- **Select expressions replace whole, never variant-by-variant.** A
  selector's variants are keyed to one locale's CLDR plural categories;
  because those categories are locale-dependent, splicing one variant
  from the parent and another from the child could produce a selector
  with no single locale's grammar behind it. A child that overrides a
  selector at all must supply every variant it wants.
- **Comments on an overridden entry stay the parent's.** The comment
  documents the id, and the override unit is the pattern, not the
  comment.
- **Child-only entries append at the end**, in the child's own order,
  comments included - an id `pt-BR` never defined is not an "override"
  of anything.

Terms (`-brand`) follow the identical rule, with one narrowing: a
term's value is never optional in Fluent syntax, so the
"attributes-but-no-value keeps the parent's value" case above applies
to messages only - a child term always supplies a value, and that
value always wins. Attribute merge-by-name, whole-pattern replacement
for the value, and parent-wins comments all apply to terms exactly as
to messages. Terms are tracked in their own namespace - overriding
`-brand` can never shadow a message also named `brand`, on the server
as in the browser.

### Why Suprnova diverges

Laravel 13 has exactly one fallback: the single global `fallback_locale`
config value, consulted when the current locale's array is missing a
key. There is no concept of one locale inheriting from a sibling locale -
`pt_PT.php` and `pt_BR.php` are two unrelated arrays, and a `pt_PT`
app either duplicates everything `pt_BR` already has translated, or
ships without it.

Suprnova's parent chains are the Rust-side extension: an intermediate
step between "this locale" and "the global fallback," configured
per-locale rather than once globally. The tradeoff we didn't want to
make is pushing that complexity onto the browser - a chain-aware
frontend would need to fetch `pt-PT.ftl`, discover it's incomplete,
fetch `pt-BR.ftl` too, and merge them client-side in JavaScript, using
rules that would have to exactly match the server's. Flattening at load
time instead means the served catalog is always one complete,
self-contained file - the same contract the frontend already had before
parent chains existed. A browser helper can parse it with
`@fluent/bundle` without loading parent catalogs separately.

## Locale detection

`LocaleMiddleware` resolves one locale per request and binds it for the
duration of the handler. The chain is config-driven and **first hit
wins**:

1. **Session** - the `locale` key in the session, if
   [session middleware](session.md) ran and the value names an available
   locale. This is where "user picked Español in settings" lives.
2. **Cookie** - the `locale` cookie. Survives logout, so a language
   choice made before signing in isn't lost.
3. **`Accept-Language`** - negotiated against `available_locales()` with
   `fluent-langneg`, honouring q-values. `fr-CH, es;q=0.8, en;q=0.5`
   against catalogs `en` + `es` resolves to `es`. The weights rank the
   languages, not their order in the header, so `en;q=0.1, es` also
   resolves to `es`, and a language sent with `q=0` is never chosen.
4. **`APP_LOCALE`** - the configured default, when nothing above hit.

A candidate that doesn't parse, or names a locale with no catalog, is
**skipped, not rejected**. A user with a stale `locale=zz` cookie sees
the default language, not a 500. A garbage `Accept-Language` header does
the same. Attacker-controlled input reaches this chain on every request;
it must never be able to do more than pick a language.

Wire it up in `bootstrap.rs`, **after** the session middleware, since
step 1 reads the session:

```rust
use suprnova::{global_middleware, LocaleMiddleware, SessionConfig, SessionMiddleware};

pub async fn register() {
    global_middleware!(SessionMiddleware::install(SessionConfig::from_env()).await);

    // Resolves the locale and binds it for the request.
    global_middleware!(LocaleMiddleware::from_env().expect("locale config"));
}
```

`LocaleMiddleware::from_env()` reads `LocalizationConfig::from_env()`;
`LocaleMiddleware::new(config)` takes one you built yourself. Starter
kits register neither `LocaleMiddleware` nor `LocaleShare`; add locale
detection when your application needs it.

Register it **before** `Inertia::install` as well, if the app names an
[Inertia error page](frontend-inertia-responses.md#error-pages). That
page is rendered by a middleware on the way out, after everything
registered inside it has returned - so a locale scope opened inside the
Inertia layer is already gone by then, and every error page would render
in the default locale. Session outside locale outside Inertia is the
order to use when you add localization.

Once it is wired, the Inertia document shell declares the active locale
itself: `<html lang="ja">` for a visitor negotiated to Japanese, in the
same BCP 47 form `Locale` renders (`pt-BR`, `zh-Hans`). Screen readers
take their voice from that attribute and search engines read it as the
page's language, so an app serving more than one language no longer needs
a middleware of its own to rewrite the finished document.

### Changing the locale mid-request

`Lang::set_locale` is Laravel's `App::setLocale` - it rewrites the
current request's locale from that point on:

```rust
use suprnova::session::session_mut;
use suprnova::{FrameworkError, Lang, Locale};

/// The user just switched languages in a settings form.
pub fn switch_language(choice: &str) -> Result<(), FrameworkError> {
    let locale = Locale::parse(choice)?;
    Lang::set_locale(locale);                       // this request
    session_mut(|s| s.put("locale", choice));       // every request after
    Ok(())
}
```

Note the two halves: `set_locale` affects *this* request (so the
redirect's flash message is already in Spanish), and the session write
is what the detection chain reads on the *next* one.

### Outside a request

Console commands, queue workers, and scheduled tasks have no request and
no middleware. There, `Lang::set_locale` writes a process-global
override that `Lang::locale()` consults before falling back to
`APP_LOCALE`:

```rust
use suprnova::{command, FrameworkError, Lang, Locale, Mail};

use crate::mail::Digest;
use crate::models::user::User;

#[command(name = "mail:digest", description = "Send the weekly digest")]
pub async fn send_digest(_args: Vec<String>) -> Result<(), FrameworkError> {
    for user in User::query().get().await? {
        // Each user's stored preference, for the duration of their email.
        Lang::set_locale(Locale::parse(&user.locale)?);
        Mail::to(&user.email).send(Digest::for_user(&user)).await?;
    }
    Ok(())
}
```

Because that override is process-wide rather than task-local, set it at
the top of each unit of work as above - don't rely on it being unchanged
across an `.await` that another task could interleave with.

## Configuration

Three environment variables. `APP_LOCALE` and `APP_FALLBACK_LOCALE` both
default to `en`; `APP_LOCALE_PARENTS` defaults to empty - no per-locale
overrides, only `fallback_locale` applies:

```env
APP_LOCALE=en
APP_FALLBACK_LOCALE=en
# APP_LOCALE_PARENTS=pt-PT=pt-BR
```

Everything else is code, on `LocalizationConfig`. It registers like every
other typed config - in your `config::register_all`, which runs before
boot:

```rust
// src/config/mod.rs
use suprnova::{Config, Detect, Locale, LocalizationConfig};

pub fn register_all() {
    let localization = LocalizationConfig::from_env()
        .expect("APP_LOCALE / APP_FALLBACK_LOCALE must be valid BCP-47")
        .default_locale(Locale::parse("es").expect("valid locale"))
        .use_isolating(true)                                // see the divergence note
        .detection(vec![Detect::Session, Detect::Header])   // ignore the cookie
        .session_key("preferred_locale")
        .cookie_name("lang")
        .parent(                                            // see Fallback chains
            Locale::parse("pt-PT").expect("valid locale"),
            Locale::parse("pt-BR").expect("valid locale"),
        );

    Config::register(localization);
}
```

- `default_locale` / `fallback_locale` - override `APP_LOCALE` and
  `APP_FALLBACK_LOCALE` from code. A malformed value in either place
  fails boot rather than silently becoming `en`.
- `use_isolating` - Unicode isolation marks around interpolations. Off
  by default; turn it on when you ship an RTL locale.
- `detection` - the chain, in order. Dropping `Detect::Cookie` means a
  language choice only lives in the session; dropping `Detect::Header`
  means the browser's preference is ignored entirely.
- `session_key` / `cookie_name` - rename the two lookups.
- `parents` - per-locale fallback parents (`child -> parent`), walked
  before `fallback_locale` when a key is missing from the child's
  catalog; same shape as `APP_LOCALE_PARENTS`. Add one with
  `.parent(child, parent)` - chainable, last write wins for a repeated
  child. See [Fallback chains](#fallback-chains) for the full contract
  (boot-time validation, resolution order, served-catalog flattening).

Boot binds an `Arc<dyn Translator>` in the container. If your app has
already bound one, the framework leaves it alone - which is how you
substitute a translator of your own without forking anything:

```rust
// src/bootstrap.rs
use std::sync::Arc;
use suprnova::{App, FluentTranslator, LocalizationConfig, Translator};

pub async fn register() {
    let config = LocalizationConfig::from_env().expect("locale config");
    let translator =
        FluentTranslator::from_dir("./catalogs", &config).expect("load catalogs");
    App::bind::<dyn Translator>(Arc::new(translator));
}
```

`Translator` is the extension seam: `translate`, `has`,
`available_locales`, `catalog`, `reload`. One driver ships
(`FluentTranslator`), and a new backend is a new driver - not a fork of
the surface.

## Translated validation messages

Every built-in rule returns a **keyed** message: a catalog key, the
arguments the message needs, and an English fallback. Translation
happens once, at the serialization boundary - `ValidationErrors::to_json`
and the Inertia error bag - never inside the rule. Rules stay pure, and
the whole subsystem compiles out.

The keys follow one convention:

| Shape | Example | Used for |
|---|---|---|
| `validation-<rule>` | `validation-min`, `validation-required-if` | One per built-in rule, kebab-cased |
| `field-<name>` | `field-email` | A human name for a field |
| `validation-invalid-data` | - | The top-level "The given data was invalid." banner |

To translate them, define the ids you care about in any `.ftl` file
under the target locale:

```ftl
# lang/es/validation.ftl
validation-invalid-data = Los datos proporcionados no son válidos.
validation-required = El campo { $field } es obligatorio.
validation-email = El campo { $field } debe ser una dirección de correo válida.
validation-min = El campo { $field } debe tener al menos { $min } caracteres.
validation-confirmed = La confirmación del campo { $field } no coincide.
```

`$field` is always available. Every rule's own parameters are passed
under the names they carry in the framework's English catalog -
`$min`, `$max`, `$other`, `$value` - and
`framework/src/localization/catalogs/en/validation.ftl` is the canonical
list of ids and arguments. Copy the ids you need out of it; you never
have to override all of them.

Overriding works per locale and per key. Defining `validation-min` in
`lang/en/validation.ftl` replaces the framework's English wording for
that one rule and leaves the rest alone.

### Field names

Interpolating a raw column name produces "The email_address field is
required." The `field-<name>` convention fixes that:

```ftl
# lang/en/validation.ftl
field-email_address = email address
field-dob = date of birth
```

Before rendering, the translator looks up `field-<name>` for the current
locale. A hit is passed as `$field`; a miss falls back to the field name
with underscores turned into spaces. So the file above is only needed
for the names that humanize badly.

### Custom rules

`Rule::passes` returns `Result<(), ValidationMessage>`. A keyed message
participates in translation:

```rust
use suprnova::{Rule, ValidationMessage};

pub struct StartsWith(pub &'static str);

impl Rule for StartsWith {
    fn passes(&self, value: &str) -> Result<(), ValidationMessage> {
        if value.starts_with(self.0) {
            Ok(())
        } else {
            Err(ValidationMessage::keyed("validation-starts-with")
                .arg("prefix", self.0)
                .fallback(format!("must start with {}", self.0)))
        }
    }
}
```

```ftl
# lang/en/validation.ftl
validation-starts-with = The { $field } field must start with { $prefix }.
```

A plain string still works, and is the right answer for a message that
will only ever exist in one language:

```rust
Err("must start with acct_".into())   // keyless: rendered verbatim
```

Keyless messages skip translation entirely, which is what keeps existing
custom rules compiling and behaving exactly as before.

### The derive flow

`#[derive(Validate)]` errors are keyed too. The `validator` crate's
error code becomes `validation-<code>` with underscores turned into
dashes, and every param the validator attaches becomes a message
argument - with two reserved exceptions, `value` and `other`, which are
always dropped. Both carry a field's actual *value* rather than
metadata about the rule: `value` is the echoed input under test, and
`other` (set by `must_match`, the canonical password-confirmation rule)
is the sibling field's value. Neither is ever handed to the catalog, so
no `.ftl` override - however it phrases `validation-must-match` - can
interpolate a submitted secret into a 422 response body. So a
`#[validate(email)]` failure resolves `validation-email` like the
hand-written rule does, and a locale that translates one translates
both.

## The frontend

The browser gets the same bytes the server resolved. Nothing is
re-translated, re-exported, or kept in sync by hand.

### The catalog endpoint

```
GET /_suprnova/lang/es.ftl              → 200 text/plain, ETag: "<hash>"
GET /_suprnova/lang/es.ftl?v=<hash>     → 200 + Cache-Control: public,
                                          max-age=31536000, immutable
GET /_suprnova/lang/es.ftl              → 304 when If-None-Match matches
GET /_suprnova/lang/zz.ftl              → 404 (no such catalog)
```

The body is the merged catalog for that locale - framework messages
first, then its configured fallback parent chain if any (see [Fallback
chains](#fallback-chains)), then your files in load order. `ETag` is the content hash. Ask
for a specific hash with `?v=` and the response is immutable-cacheable
forever, because that URL can only ever mean one thing; ask without it
and you get revalidation instead. Like `/_suprnova/health`, the path is
exempt from the middleware chain: it must answer before a locale has
been resolved, and it carries no user data.

### The shared prop

`LocaleShare` is an `InertiaSharedData` the framework ships. Registered
in `bootstrap.rs` (see [Locale detection](#locale-detection)), it adds
one prop to every Inertia page:

```json
{
  "lang": {
    "locale": "es",
    "fallback": "en",
    "catalog": {
      "url": "/_suprnova/lang/es.ftl?v=9f2c1ae4",
      "hash": "9f2c1ae4"
    }
  }
}
```

`catalog` is `null` when no translator is bound - the share never fails
a page render. Behind a reverse proxy that serves the application under a
path prefix, `catalog.url` starts with the public root, such as
`/billing/_suprnova/lang/es.ftl?v=9f2c1ae4`, so the wrapper fetches it
through the proxy as given.

### Translated frontend props

The kits ship no browser translation wrappers or `@fluent/bundle`
dependency. For a page rendered on the server, translate with `Lang::get`
in the handler and pass the text in props:

```ftl
# lang/en/app.ftl
greeting = Welcome to Suprnova
```

```rust
use suprnova::{handler, inertia_response, InertiaProps, Lang, Request, Response};

#[derive(InertiaProps)]
pub struct GreetingProps {
    pub heading: String,
}

#[handler]
pub async fn greeting(req: Request) -> Response {
    inertia_response!(&req, "Greeting", GreetingProps {
        heading: Lang::get("greeting"),
    })
}
```

Render `heading` as text in the component. The SSR worker and browser
receive the same prop, so their first renders agree without fetching a
catalog before hydration.

Loading a Fluent catalog in the browser through `LocaleShare` leaves
translations as raw keys during SSR: the worker has not loaded that
browser catalog. A page rendered on the server should not depend on it.
`LocaleShare` and the catalog endpoint remain available for applications
that choose browser translation and handle their own loading.

Number and date formatting on the client uses the browser's built-in
`Intl` - no ICU data is shipped to the browser.

### Typed message keys

`suprnova generate-types` parses `lang/<default locale>/*.ftl` and emits
a union of every message id alongside the page-props types:

```ts
// frontend/src/types/lang-keys.ts
// Generated by `suprnova generate-types` - do not edit.
export type MessageKey =
  | "validation-min"
  | "welcome"
```

An application helper can type `t(key: MessageKey, ...)`, giving the
same promise as [`inertia-props.ts`](frontend-typescript-types.md): rename a message
in Rust, regenerate, and the TypeScript compiler points at every call
site that still uses the old id. `suprnova serve` watches `lang/`
alongside `src/`, so the file regenerates as you edit catalogs.

A project with no `lang/` directory and no message ids gets **no
file** - an app that isn't localized sees no new artifact appear.

## Locale-aware formatting

You format values with `Lang` through ICU4X, using the current
locale, all with `try_*` siblings that return
`Result<String, FrameworkError>` instead of degrading:

```rust
use suprnova::chrono::NaiveDate;
use suprnova::{DateStyle, Lang, ListStyle, RelativeUnit, TimeStyle};

let dt = NaiveDate::from_ymd_opt(2026, 8, 1)
    .and_then(|d| d.and_hms_opt(14, 30, 0))
    .expect("valid datetime");

Lang::number(1_234_567.89);                          // en-US → 1,234,567.89
                                                     // de-DE → 1.234.567,89
Lang::currency(19.99, "USD");                        // en-US → $19.99
Lang::percentage(12.5, 1);                           // en → 12.5%, de → 12,5 %
Lang::abbreviate(1_230_000.0, 2);                    // en → 1.23M, de → 1,23M
Lang::date(&dt, DateStyle::Long);                    // en-US → August 1, 2026
Lang::time(&dt, TimeStyle::Short);                   // en-US → 2:30 PM
Lang::datetime(&dt, DateStyle::Medium, TimeStyle::Short);
Lang::list(&["Ada", "Grace", "Alan"], ListStyle::And); // → Ada, Grace, and Alan
Lang::relative(-3, RelativeUnit::Day);               // → 3 days ago
```

The style enums: `DateStyle { Full, Long, Medium, Short }`,
`TimeStyle { Medium, Short }`, `ListStyle { And, Or, Unit }`,
`RelativeUnit { Second, Minute, Hour, Day, Week, Month, Year }`.
`Lang::relative` takes a signed amount - negative is the past
("3 days ago"), positive the future ("in 3 days").

`Lang::percentage(value, precision)` takes the percentage itself, `10.0`
for ten percent, as Laravel's `Number::percentage` does. You round decimal
ties half up, so `Lang::percentage(0.12345, 4)` gives `0.1235%`.
You choose a locale without changing the current one with
`Lang::percentage_in(10.0, 0, "de")?`, which gives `10` followed by the
locale's no-break space and `%`.

You use `Lang::format(value, precision)` for fixed fraction digits and
`Lang::format_with_max_precision(value, precision, Some(max))` for at most
`max` digits with trailing zeros removed. The maximum takes precedence
over fixed precision. You apply the same control to percentages with
`Lang::percentage_with_max_precision(value, precision, Some(max))`.
Infinite values appear as `∞` or `-∞`; a value that is not a number appears
as `NaN`. You receive formatting errors through `try_format` and
`try_percentage_with_max_precision`.

You set the default for calls outside a request with `Lang::use_locale("de")?`.
A request locale still takes precedence. You run a synchronous closure in
a temporary locale with `Lang::with_locale("fr", || Lang::percentage(10.0, 0))?`.
The previous locale returns when the closure ends, including when it panics.
An invalid locale returns an error before the closure runs.

`Lang::abbreviate(value, precision)` divides by the largest of a thousand,
a million, a billion, a trillion, and a quadrillion the value reaches and
adds `K`, `M`, `B`, `T`, or `Q`, as Laravel's `Number::abbreviate` does;
the digits follow the locale, the suffixes do not, since the ICU4X
release the framework uses has no compact number format. As in Laravel,
rounding that reaches a thousand moves to the next unit, so
`Lang::abbreviate(999_999.0, 0)` is `1M`, not `1,000K`; a count of
quadrillions is itself abbreviated, so `3e18` is `3KQ`; and a value that
rounds to zero, such as `-0.004` with two digits, is `0.00`, with no
sign. Percentages drop that sign too.

> Exact output comes from the CLDR data baked into ICU4X and can change
> across an ICU upgrade, particularly for dates and currency. In your own
> tests, assert on shape and locale-distinctness (`de != en`, contains
> `2026`) rather than on exact bytes.

### Formatting inside a message

Two functions are callable from FTL:

```ftl
order-total = Your total is { NUMBER($amount, maximumFractionDigits: 2) }.
published = Published { DATETIME($when, dateStyle: "medium", timeStyle: "short") }
```

```rust
use suprnova::__;

let line = __!("published", when: "2026-08-01T14:30:00");
```

`NUMBER()` is Fluent's builtin, registered explicitly, and gives you
fraction-digit control inside the message. `DATETIME()` is Suprnova's:
`$value` accepts an ISO-8601 string or epoch milliseconds, and
`dateStyle` / `timeStyle` take the same names as the Rust enums, lower
case. A value it cannot parse passes through verbatim with a `warn!` -
a Fluent function cannot return an error, and a rendered page with one
odd-looking date beats a 500. Both functions format in the locale of the
catalog the message came from, so a message is never half one language:
a `Translator::translate` call that names `es` gets Spanish dates whatever
`Lang::locale()` is.

When you want ICU4X's full formatting rather than what a Fluent function
exposes, format in Rust and pass the finished string in:

```rust
use suprnova::{__, Lang};

let total = __!("order-total-text", amount: Lang::currency(19.99, "USD"));
```

## Testing your translations

Two helpers do the work: `use_lang_path` points the loader at a fixture
directory, and `scope_locale` pins the current locale for the duration
of a future.

The hermetic form - build a translator over a fixture directory and bind
it in a test-scoped container - is what the framework's own tests use,
because it touches no process-global state and survives parallel test
execution:

```rust
use std::sync::Arc;
use suprnova::testing::TestContainer;
use suprnova::{scope_locale, FluentTranslator, Lang, Locale, LocalizationConfig, Translator};

#[tokio::test]
async fn spanish_greeting_comes_from_the_catalog() {
    let _guard = TestContainer::fake();

    let config = LocalizationConfig::from_env().expect("locale config");
    let translator = FluentTranslator::from_dir("tests/fixtures/lang", &config)
        .expect("load catalogs");
    TestContainer::bind::<dyn Translator>(Arc::new(translator));

    scope_locale(Locale::parse("es").expect("locale"), async {
        assert_eq!(Lang::get("welcome"), "¡Bienvenido!");
        assert_eq!(Lang::locale().as_str(), "es");
    })
    .await;
}
```

`use_lang_path` is the right tool when the test boots the real
application and you want the *whole* app pointed at fixtures:

```rust
use suprnova::use_lang_path;

#[tokio::test]
async fn app_boots_against_fixture_catalogs() {
    use_lang_path("tests/fixtures/lang");
    // … boot the app; `lang_path("")` now resolves to the fixture dir.
}
```

It writes a process-global path override, so treat it as a per-binary
setting rather than something two parallel tests can disagree about.

Detection itself - the session/cookie/`Accept-Language` chain - is worth
testing through the real pipeline rather than by calling the middleware
directly, because the interesting cases are about header parsing and
about which source wins. Mount a route whose handler returns
`__!("welcome")`, register `LocaleMiddleware` in the
`MiddlewareRegistry`, and drive it with the loopback harness from
[HTTP Tests](http-tests.md), sending `Accept-Language: fr, es;q=0.8` and
asserting on the Spanish body. The cases worth pinning: a header
negotiates, a cookie beats a header, an unavailable locale is skipped
rather than erroring, and a malformed header still returns 200.

See [Testing](testing.md) for `TestContainer::scope` when your test runs
on a multi-threaded runtime - the thread-local `fake()` guard above does
not survive a future migrating between workers.

### Why Suprnova diverges

**FTL files, not PHP arrays.** Laravel has two formats - nested arrays
in `lang/en/messages.php`, plus flat JSON in `lang/en.json` for
string-keyed translations - and neither is loadable by a browser, nor
expresses plural selection in the file: that lives in `trans_choice`'s
pipe-and-range convention inside the string. Fluent gives us one format that the server and
the client both parse, which is what makes "the frontend shows the same
string the validator produced" a property of the design rather than a
convention you maintain. It costs you a new syntax to learn (this
chapter is most of it) and a tooling change: Poedit can't edit `.ftl`,
while Crowdin, Weblate, Lokalise, and Pontoon can. It also costs
dotted namespacing - `trans('messages.welcome')` has no equivalent,
because ids are a flat namespace per locale. Prefix instead.

**No `trans_choice`.** Laravel selects a plural form with pipe-separated
strings and explicit ranges:

```php
// Laravel
trans_choice('{1} plik|[2,4] pliki|[5,*] plików', $count);
```

Now count to 22 in Polish. CLDR puts 22 in the `few` category - `22
pliki` - but `[5,*]` swallows it and produces `22 plików`. The same
break happens at 32, 42, 102, and in Russian, Arabic, Czech, Lithuanian,
and Welsh, each in its own places. Integer ranges cannot express plural
rules, because plural rules are not about ranges; they're about the last
digit, the last two digits, and in some languages whether the value is
an integer at all. Fluent selects on the CLDR category directly, so
`$count` is an ordinary argument and the *translator* - the person who
knows the language - writes all four of Polish's categories:

```ftl
files =
    { $count ->
        [one] { $count } plik
        [few] { $count } pliki
        [many] { $count } plików
       *[other] { $count } pliku
    }
```

`one` is 1; `few` is 2-4, 22-24, 32-34, 102-104; `many` is 0, 5-21,
25-31; `other` catches the fractions (`1,5 pliku`) and carries the
default marker, per the rule above.

Laravel's rangeless form (`plik|pliki|plików`) does better - it consults
a per-language index and picks the *n*th segment - but that index is a
hand-maintained table rather than CLDR data, it offers Polish three
segments where CLDR defines four categories, the segments are positional
with no category names to review, and it can only ever select on the
count.

Which is the second benefit, falling out for free: a Fluent selector can
switch on *any* argument, not just a count. Gender, plan tier, and connection
state select the same way, and none of them needed a new facade method.

**Isolation marks are off by default.** Fluent normally wraps every
interpolation in U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP
DIRECTIONAL ISOLATE), so that a right-to-left value embedded in a
left-to-right sentence renders in the right order. Correct - and
invisible, which means every `assert_eq!("Hello Ada", …)` in an
English-only app fails with two characters nobody can see in the diff.
We default them off and make turning them on one call:

```rust
let config = LocalizationConfig::from_env()?.use_isolating(true);
```

**Turn them on when you ship an RTL locale** - Arabic, Hebrew, Persian,
Urdu - or any locale where user-supplied values mix scripts inside a
sentence. Then update your assertions to compare against strings that
carry the marks, or strip them in the assertion helper. The default
optimises for the common case; the correct case is one line away and
this paragraph is the reminder to take it.

## Next

- [Validation](validation.md) - rules, the `validate!` macro, and where
  `ValidationMessage` comes from
- [TypeScript Types](frontend-typescript-types.md) - `generate-types`,
  `inertia-props.ts`, and `lang-keys.ts`
- [Middleware](middleware.md) - ordering `LocaleMiddleware` against the
  rest of the global chain
- [Session](session.md) - the store the first detection step reads
- [Environment Variables](env-vars.md) - `APP_LOCALE`,
  `APP_FALLBACK_LOCALE`, `APP_LOCALE_PARENTS`, `APP_BASE_PATH`
- [Testing](testing.md) - `TestContainer`, `#[suprnova_test]`, and
  hermetic DI overrides


---

<!-- /docs/mail -->

# Mail

Suprnova's mail subsystem mirrors Laravel's `Mail::to(...)->send(...)` API on Tokio. One `Mail` facade, nine transports (log, in-memory, and `.eml`-file previews for dev/tests, SMTP, and five HTTP providers - Postmark, SES, SendGrid, Mailgun, Resend), Tera-rendered templates with the Mailable's serialized fields as the context, queue + delayed delivery on the durable at-least-once envelope, and a `Mail::fake()` test guard cut from the same cloth as `Bus::fake()` and `Cache::fake()`.

## Quick Start

```rust
use serde::{Deserialize, Serialize};
use suprnova::async_trait;
use suprnova::mail::{Address, Mail, Mailable};

#[derive(Serialize, Deserialize)]
struct Welcome {
    name: String,
}

#[async_trait]
impl Mailable for Welcome {
    fn mailable_name() -> &'static str { "Welcome" }
    fn subject(&self) -> String { format!("Welcome, {}", self.name) }
    fn text_template_source(&self) -> Option<String> {
        Some("Hi {{ name }}, welcome aboard.".into())
    }
    fn from(&self) -> Option<Address> {
        Some(Address::new("hello@example.com").with_name("Suprnova"))
    }
}

async fn greet(name: String) -> Result<(), suprnova::FrameworkError> {
    Mail::to("alice@example.org")
        .send(Welcome { name })
        .await
}
```

The Mailable serializes to JSON, which becomes the Tera context for the template; every `pub` field is reachable as `{{ field_name }}`.

## Configuration

`Server::run` calls `suprnova::mail::boot::bootstrap_from_env()` once at startup. It reads `MAIL_DRIVER` and binds the matching transport. Defaults to the `log` driver when unset.

| `MAIL_DRIVER` | Behavior |
|---------------|----------|
| `log`         | Emit a `tracing::info!` per send - envelope and full bodies, as Laravel does - and discard. Default outside production. |
| `memory`      | Capture every message in-process. See `suprnova::mail::boot::captured_in_memory()`. |
| `file`        | Write one RFC 5322 `.eml` per send to `MAIL_FILE_PATH` (default `storage/mail`), then discard. Open the file in a mail client to check rendering, headers, and attachments. |
| `smtp`        | Connect to an SMTP server (STARTTLS when credentials are set, plain TCP otherwise). |
| `postmark`    | POST JSON to Postmark's `/email` endpoint. |
| `ses`         | POST SigV4-signed requests to Amazon SES `SendEmail`. |
| `sendgrid`    | POST JSON to SendGrid's `/v3/mail/send`. |
| `mailgun`     | POST `application/x-www-form-urlencoded` (or `multipart/form-data` when attachments are present) to Mailgun's `/v3/{domain}/messages`. |
| `resend`      | POST JSON to Resend's `/emails`. |

### Production fails closed on a driver that discards mail

`log`, `memory`, and `file` render a message and drop it. Under `APP_ENV=production`, boot **refuses** to start on any of them - and equally on an unset `MAIL_DRIVER` or a value the build doesn't recognise, because both land on that same `log` transport:

```
refusing to boot in production: MAIL_DRIVER is unset, which defaults to the `log`
transport. Password resets and email verifications would report success while
nothing is delivered. Set MAIL_DRIVER to a delivering driver (smtp | postmark |
ses | sendgrid | mailgun | resend), or set
MAIL_ALLOW_NON_DELIVERING_IN_PRODUCTION=true to acknowledge that outgoing mail is
intentionally discarded.
```

The failure this prevents is a silent one: with the old default, a deploy that forgot `MAIL_DRIVER` - or wrote `MAIL_DRIVER=SMTP` in the wrong case - reported every password reset as sent while nothing ever left the process, and nobody found out until a user was locked out.

If a production deployment genuinely wants no outgoing mail (a read-only mirror, a dark launch), acknowledge it explicitly:

```env
MAIL_ALLOW_NON_DELIVERING_IN_PRODUCTION=true
```

Only `1`, `true`, `yes`, or `on` count as consent - `=false` or a typo leaves the guard armed. With the override set, every boot warns that outgoing mail will not be delivered.

Nothing changes outside production: `local`, `development`, `testing`, and `staging` keep the `log` default and keep the warn-and-fall-back behaviour for unknown drivers.

### Production fails closed on an unencrypted SMTP connection

The same rule, applied to how the connection is protected rather than to
whether it delivers. `MAIL_DRIVER=smtp` in production must resolve to an
encrypted transport, or boot fails.

`MAIL_SMTP_ENCRYPTION` takes `starttls`, `tls`, or `none` (`ssl` and
`null` are accepted as Laravel-compatible aliases). Left unset it derives
from the credentials:

| `MAIL_SMTP_USER` / `MAIL_SMTP_PASS` | Resolves to | Because |
|---|---|---|
| both set | `starttls` | Credentials imply a real relay on the submission port. |
| neither set | `none` | The local-catcher path. Mailpit, MailHog and maildev listen unauthenticated on 1025 without TLS. |

So a fresh scaffold keeps working with zero configuration, and a
production deploy that never wired the credentials stops instead of
quietly sending in the clear. Set `MAIL_SMTP_ENCRYPTION=tls` for a relay
that expects implicit TLS on 465 - a mode the transport has always
supported but which no combination of environment variables could reach
before.

An unrecognised value fails boot in *every* environment, not just
production. `MAIL_SMTP_ENCRYPTION=tsl` is a transposition of a mode that
encrypts, so silently treating it as "no encryption" would be the exact
failure the variable exists to prevent - better to fail on the
developer's machine than in the deploy.

The escape hatch mirrors the one above:

```env
MAIL_ALLOW_INSECURE_SMTP_IN_PRODUCTION=true
```

Only defensible when the relay is reachable solely over a private
network - a sidecar, or a Postfix inside the VPC. On anything else,
cleartext SMTP puts the credentials and every password-reset link on the
wire, and it stays there for whoever is listening on the path.

### The `log` driver logs the whole message

Same as Laravel's `log` mailer: envelope *and* rendered bodies.

```
mail (log driver): would send from=noreply@app.test to=["alice@example.org"]
  subject=Reset your password
  text=Reset your password: https://app.test/password/reset?token=9f3a…&signature=…
  html=<a href="https://app.test/password/reset?token=9f3a…&signature=…">Reset</a>
```

That link is the point. In development the console is where you read the verification or password-reset link the app just "sent", and a driver that hides it is a driver nobody can use.

It is safe here because the driver cannot reach production - boot refuses to start on `MAIL_DRIVER=log` under `APP_ENV=production` (see above). The bodies only ever exist on a developer's machine.

If you set `MAIL_ALLOW_NON_DELIVERING_IN_PRODUCTION=true` to run the `log` driver in a deployed environment, you are choosing to put single-use bearer links in your logs. Anyone who can read those files - operators, the log shipper, the retention bucket, the aggregator - can use them, and link expiry doesn't help because log shipping is faster than a person reading their inbox. Size your retention and access policy for that, or use a driver that doesn't print:

```env
# In-process capture - suprnova::mail::boot::captured_in_memory(), or Mail::fake() in tests
MAIL_DRIVER=memory

# Or write one .eml per send instead of a log line - see "Previewing mail as
# .eml files" below for the access-control trade this makes
MAIL_DRIVER=file
MAIL_FILE_PATH=storage/mail

# Or a local catcher (mailpit / maildev / mailhog), which renders the real mail in a UI
MAIL_DRIVER=smtp
MAIL_SMTP_HOST=127.0.0.1
MAIL_SMTP_PORT=1025
```

### Per-driver environment

```env
# SMTP
MAIL_DRIVER=smtp
MAIL_SMTP_HOST=smtp.mailtrap.io
MAIL_SMTP_PORT=587
MAIL_SMTP_USER=...
MAIL_SMTP_PASS=...
MAIL_SMTP_ENCRYPTION=starttls   # or `tls` for implicit TLS on 465, or `none`

# Postmark
MAIL_DRIVER=postmark
MAIL_POSTMARK_TOKEN=...

# Amazon SES
MAIL_DRIVER=ses
MAIL_SES_ACCESS_KEY=...
MAIL_SES_SECRET_KEY=...
MAIL_SES_REGION=us-east-1

# SendGrid
MAIL_DRIVER=sendgrid
MAIL_SENDGRID_API_KEY=...

# Mailgun
MAIL_DRIVER=mailgun
MAIL_MAILGUN_API_KEY=...
MAIL_MAILGUN_DOMAIN=mg.example.com

# Resend
MAIL_DRIVER=resend
MAIL_RESEND_API_KEY=...
```

Each HTTP provider also honors a corresponding `MAIL_<PROVIDER>_ENDPOINT` override that points at a regional URL or a mock server (useful for integration tests against `wiremock`).

### Auth-flow sender: `MAIL_FROM` and `MAIL_FROM_NAME`

The built-in auth-flow mailables - email verification, password reset, and the
password-changed notice - resolve their envelope `From` from the environment
rather than a hard-coded `from()`:

```env
MAIL_FROM=no-reply@example.com        # bare address (required by the auth flows; fails closed if unset)
MAIL_FROM_NAME=Acme Support           # optional display name (since 0.5.9)
```

- `MAIL_FROM` **must be a bare address.** It is lifted straight into the
  message's `From`, so a `"Name <addr>"` value would be treated as the entire
  address and rejected by the transport.
- `MAIL_FROM_NAME` (optional, added in **0.5.9**) attaches a display name, so the
  header renders as `Acme Support <no-reply@example.com>`. Unset or blank keeps
  the previous bare-address behavior. It is read at send time, so it applies to
  queued auth-flow mail too.

These two variables only affect the framework's own auth-flow mailables. Your
own `Mailable`s set their sender through `from()` (or the global `always_from`
default) - see below.

## Previewing mail as `.eml` files

`MAIL_DRIVER=log` puts the rendered bodies in your console, which works for a plain-text message and
poorly for anything else. The `file` driver writes the bytes SMTP would have put on the wire:

```
MAIL_DRIVER=file
MAIL_FILE_PATH=storage/mail
```

Each send produces one new `<millis>-<seq>.eml` in that directory. A name another writer already holds -
a second process, or a second transport on the same directory - is skipped, never overwritten. Open it with any mail client (Thunderbird,
Apple Mail, `mutt -f`) to see the message as a recipient sees it - both alternative bodies, every
attachment, and the full header set including `X-Priority`, `X-Tag`, `X-Metadata-*`, and `Return-Path`.

The directory is created on first send. When `MAIL_FILE_PATH` is unset, mail lands in
`storage_path("mail")` - the same path family every other `storage/` consumer uses, so the
directory stays inside the application base even when a service manager starts the process
from somewhere else. An absolute `MAIL_FILE_PATH` is used as given; a relative one anchors
at the application base directory (`base_path`, overridable with `APP_BASE_PATH`).

### Why Suprnova diverges

Laravel has no file mailer; its `log` mailer writes the raw MIME into the log channel, which means
grepping a log file for a MIME boundary to reconstruct an attachment. Writing a real `.eml` per message
makes the artifact openable instead of reconstructable. The trade is that mail accumulates on disk -
this driver never prunes, so treat `MAIL_FILE_PATH` as scratch space.

### Each `.eml` file is a working credential, and none of them expire on their own

Password-reset and email-verification mail carry single-use bearer links, and the `file` driver writes
them out exactly as SMTP would have sent them - readable by anyone who can open the file. Unlike the
`log` driver's stream, this is durable storage: nothing prunes `MAIL_FILE_PATH`, so a token written on
day one is still sitting there, still valid until it expires, on day one hundred. Give the directory the
same access treatment you would give a log file holding reset links - keep it out of version control,
restrict who can read the deploy filesystem, and clear it on a schedule if `file` runs anywhere near
real traffic.

## The Mailable Trait

Mailables are serializable structs that know how to render themselves. The trait defaults render with `tera::Tera::one_off` against the mailable's serialized fields:

```rust
use suprnova::async_trait;
use suprnova::mail::{Address, Attachment, Mailable};

#[async_trait]
impl Mailable for OrderShipped {
    fn mailable_name() -> &'static str { "OrderShipped" }
    fn subject(&self) -> String {
        format!("Order #{} shipped", self.order_id)
    }
    fn html_template_source(&self) -> Option<String> {
        Some("<p>Tracking: <code>{{ tracking }}</code></p>".into())
    }
    fn text_template_source(&self) -> Option<String> {
        Some("Tracking: {{ tracking }}".into())
    }
    fn from(&self) -> Option<Address> {
        Some(Address::new("orders@example.com").with_name("Acme Orders"))
    }
    fn attachments(&self) -> Vec<Attachment> {
        vec![Attachment::new("invoice.pdf", self.invoice_bytes.clone(), "application/pdf")]
    }
}
```

| Method | Required? | Purpose |
|--------|-----------|---------|
| `mailable_name()` | yes | Stable name persisted in the queue envelope - renaming breaks in-flight queued mail. |
| `subject(&self)` | yes | Computed subject. Used verbatim when `subject_template_source` returns `None`. |
| `subject_template_source(&self)` | optional | Tera template for the subject - when `Some`, takes precedence over `subject()` and renders with `self` as the context. Same semantics as the body template sources. |
| `html_template_source(&self)` | optional | HTML body Tera template. Return `None` to skip HTML. |
| `text_template_source(&self)` | optional | Plain-text body Tera template. Return `None` to skip text. |
| `from(&self)` | optional | Override the global default `noreply@localhost`. |
| `to(&self)` / `cc(&self)` / `bcc(&self)` / `reply_to(&self)` | optional | The mailable's own recipients, empty by default. See [A mailable's own recipients](#a-mailables-own-recipients). |
| `delay(&self)` | optional | How long a queued send waits before a worker may take it. Default `None`. See [Queueing](#queueing). |
| `queue(&self)` | optional | Default queue for `Mail::queue` / `Mail::later`. See [Queueing](#queueing). |
| `after_commit(&self)` | optional | `true` makes `Mail::queue` / `Mail::later` inside `DB::transaction` wait for the commit. Default `false`. See [Queueing](#queueing). |
| `attachments(&self)` | optional | Files to attach. Each is `name + bytes + mime`. |
| `render_subject(&self)` / `render_html(&self)` / `render_text(&self)` | optional | Override if you want to bypass Tera (Markdown → HTML, pre-rendered content, custom subject logic, etc.). |

At least one of `html_template_source` or `text_template_source` must return `Some` (or `render_html`/`render_text` must produce content). An empty-body mailable is refused both at dispatch (`Mail::send`) and at enqueue (`Mail::queue`).

### Tera autoescape

Autoescape is **OFF** because mail bodies are typically hand-authored HTML where Tera's `<>&` escaping would over-escape. If your literal body contains `{{` for non-template reasons (e.g., marketing copy quoting Mustache syntax), escape it: `{% raw %}{{ literal }}{% endraw %}`.

## Building Messages

The `Mail::to(...)` builder threads recipients, CC/BCC, reply-to, and a per-message sender override into the dispatch:

```rust
Mail::to("alice@example.org")
    .cc("manager@example.com")
    .bcc("audit@example.com")
    .reply_to("support@example.com")
    .from(("Operations", "ops@example.com"))   // (display name, email)
    .send(OrderShipped { order_id: 42, /* ... */ })
    .await?;
```

`Address` accepts `&str`, `String`, and `(name, email)` tuples; `Mail::to(...)` accepts anything `Into<Address>`.

### A mailable's own recipients

A mailable can carry its own recipients, as a Laravel mailable sets its own
`$to`, `$cc`, and `$bcc`. Override `to`, `cc`, `bcc`, or `reply_to`; each
returns a list of addresses and is empty by default:

```rust
#[async_trait]
impl Mailable for OrderShipped {
    fn mailable_name() -> &'static str { "OrderShipped" }
    fn subject(&self) -> String { format!("Order #{} shipped", self.order_id) }
    fn text_template_source(&self) -> Option<String> { Some("Tracking: {{ tracking }}".into()) }

    fn to(&self) -> Vec<Address> { vec![Address::new(self.customer_email.clone())] }
    // Every send of this mailable copies the audit inbox.
    fn bcc(&self) -> Vec<Address> { vec!["audit@example.com".into()] }
}

// To the mailable's own recipients.
Mail::send(order_shipped.clone()).await?;
Mail::queue(order_shipped.clone()).await?;
Mail::later(Duration::from_secs(60), order_shipped.clone()).await?;
Mail::on_queue("emails", order_shipped.clone()).await?;

// Or add to them through the builder.
Mail::to("ops@example.com").send(order_shipped).await?;
```

Sending or queueing merges the mailable's lists with the builder's: the
mailable's addresses come first, and an address whose email is already in
the list, ignoring case, is skipped. The merge runs before
[`Mail::always_to`](#global-defaults-always_from-always_reply_to-always_to-always_return_path)
applies, so the always-to address still replaces every recipient. A queued
mail carries the merged lists, and the worker adds nothing to them.

`Mail::send`, `Mail::queue`, `Mail::later`, `Mail::on_queue`, and
`Mail::queue_on` take the mailable alone, as Laravel's `Mail::onQueue` and
`queueOn` do; `queue_on` is the same as `on_queue`. Each one refuses a
mailable whose `to`, `cc`, and `bcc` are all empty with an error that names
it, before anything is sent or pushed. A reply-to address is not a
recipient, so it does not count.

#### Why Suprnova diverges

Laravel finds a mailable without recipients when the mailer hands the
message to the transport, and a queued one fails on the worker. Suprnova
refuses it when you call `Mail::send` or `Mail::queue`, so the caller gets
the error and no job is queued that can never be sent. Laravel's
`setAddress` keeps the last of two equal addresses; Suprnova keeps the
first, so the mailable's own entry wins.

Every transport writes an address the same way. The display name is quoted whenever it holds a comma, a quote, an `@`, angle brackets, `=?`, or any non-ASCII character, so a name such as `Doe, Jane`, or a name a user typed into their profile, stays one recipient on every provider. A line break in a display name becomes one space, and whitespace around an email is trimmed. The email itself must be exactly one plain address. A list (`a@example.com, b@example.com`), a `Name <email>` form, a quoted local part (`"a b"@example.com`), and a domain literal (`user@[127.0.0.1]`) are refused, and so is a display name with any other control character. See [What a message may contain](#what-a-message-may-contain).

## Attachments

```rust
use suprnova::mail::Attachment;

let attachment = Attachment::new(
    "report.csv",
    csv_bytes,
    "text/csv",
);
```

Attachments ride through the `Mailable::attachments` method, or the builder's `attach` and `attach_data`. All five HTTP providers handle them - Postmark/SendGrid/Resend over JSON (base64-encoded), SES via Raw MIME (since `Content.Simple` does not support attachments), and Mailgun via `multipart/form-data` (the form-encoded path is used when there are no attachments).

```rust
Mail::to("alice@example.org")
    .attach(Attachment::new("invoice.pdf", invoice_bytes, "application/pdf"))
    .attach_data(csv_bytes, "report.csv", "text/csv")
    .send(OrderShipped { /* ... */ })
    .await?;
```

A message carries one attachment for each distinct name and bytes, as
Laravel's `attachData` keeps one per name and data. When the mailable's
`attachments()` and the builder attach the same name and bytes, or the
builder attaches them twice, the first is kept and the later one dropped,
on the send path and on the queued path alike. Two attachments with one
name and different bytes are both sent.

`Attachment::is_equivalent(&other)` answers whether two attachments have
the same name, bytes, and content type, as Laravel's
`Attachment::isEquivalent` does, and
`Attachment::is_equivalent_with(&other, name, content_type)` compares them
with the given name and content type in place of the other's.

## Queueing

`Mail::queue(...)` builds a `SendMailJob` and pushes it onto the framework queue. The worker rebuilds the mailable from the registered factory and dispatches through the bound transport:

```rust
// One-time: register every Mailable type the worker will see.
suprnova::mail::register_mailable_factory::<Welcome>()?;

// At send time:
Mail::to("alice@example.org").queue(Welcome { name: "Alice".into() }).await?;

// Delayed:
use std::time::Duration;
Mail::to("alice@example.org")
    .later(Duration::from_secs(60), Welcome { name: "Alice".into() })
    .await?;
```

The worker already knows `SendMailJob`: the framework registers its own job, so the factory is the only registration a queued mailable needs. You never call `register_job` for it.

Route a queued dispatch to a specific queue or connection with `.on_queue(...)` / `.on_connection(...)`, or give the `Mailable` itself a default via `Mailable::queue(&self)`:

```rust
Mail::to("alice@example.org")
    .on_queue("emails")
    .queue(Welcome { name: "Alice".into() })
    .await?;
```

`.on_queue(...)` outranks both `Mailable::queue()` and any `Queue::route` registered for the mail-dispatch job - the same "per-push override wins" rule `Queue::push_with` applies everywhere. See [Queues](queues.md#queue-routing).

The same empty-body guard runs on the queue path, so a misconfigured Mailable is rejected at push-time before any envelope is created.

A mailable can declare its own delay, as Laravel's `#[Delay]` attribute
does. `Mail::queue` and `MailBuilder::queue` apply it, and an explicit
`later` delay wins over it:

```rust
impl Mailable for WeeklyDigest {
    // ...
    fn delay(&self) -> Option<Duration> { Some(Duration::from_secs(3600)) }
}

// Available to a worker an hour from now.
Mail::to("alice@example.org").queue(WeeklyDigest::new()).await?;
// Available in 10 seconds: the explicit delay wins.
Mail::to("alice@example.org").later(Duration::from_secs(10), WeeklyDigest::new()).await?;
```

### Queued mail inside a transaction

A mail queued inside a `DB::transaction` races that transaction. A worker can pop the job before the commit and render mail about a row the transaction has not committed, or about a row that a rollback then removes. Return `true` from `Mailable::after_commit` for mail about rows the transaction writes:

```rust
impl Mailable for OrderShipped {
    fn mailable_name() -> &'static str { "OrderShipped" }
    fn subject(&self) -> String { format!("Order #{} shipped", self.order_id) }
    fn after_commit(&self) -> bool { true }
    // ...
}

DB::transaction(|_tx| {
    Box::pin(async move {
        let order = Order::create(suprnova::attrs! { total: 4999i64 }).await?;
        // Nothing reaches the queue here.
        Mail::to("alice@example.org").queue(OrderShipped { order_id: order.id }).await?;
        Ok::<(), FrameworkError>(())
    })
})
.await?;
// The job is on the queue now, and only now.
```

Inside a transaction, `Mail::queue` and `Mail::later` then push at the commit, and a rollback discards the push. Outside a transaction they push at once. `after_commit` takes `&self` for the reason `queue` does: every queued mailable rides one job type, `SendMailJob`, so the job's own `Job::after_commit` cannot answer for one mailable.

A mailable that returns `false` makes no choice: the queue connection's own after-commit setting decides, then the process-wide `QUEUE_AFTER_COMMIT`. See [Which setting decides](queues.md#which-setting-decides).

## Telemetry

Every send routes through `suprnova::mail::dispatch_with_telemetry`, which opens a `mail.send` `tracing::info_span!` carrying:

- `transport` - driver name (`"postmark"`, `"smtp"`, `"in-memory"`, …)
- `to_count`, `cc_count`, `bcc_count` - recipient counts
- `has_html`, `has_text` - body shape
- `attachment_count` - number of attachments
- `tag_count`, `metadata_count` - provider-hint counts
- `priority` - `1..=5`, or `0` when unset

On completion the span emits `mail sent` (info) or `mail send failed` (warn) with `duration_ms`. The same wrapper covers `Mail::send`, the `SendMailJob` queue worker, and the notification `MailChannel`, so the span schema is identical regardless of how the message was produced.

## Testing with `Mail::fake()`

`Mail::fake()` installs an in-memory capture transport for the duration of the returned RAII guard. Mirrors `Bus::fake()` / `Queue::fake()` / `Cache::fake()`:

```rust
use suprnova::mail::Mail;

#[tokio::test]
async fn welcome_mail_is_sent_on_signup() {
    let fake = Mail::fake();

    sign_up("alice@example.org").await.unwrap();

    fake.assert_sent_count(1);
    fake.assert_sent(|m| m.to.iter().any(|a| a.email == "alice@example.org"));
    fake.assert_sent(|m| m.subject.starts_with("Welcome"));
    fake.assert_not_sent(|m| m.subject.contains("Password reset"));
}
```

When the guard drops, the previously-bound transport (if any) is restored. Tests that intermix `Mail::fake()` with explicit transport binding do not leak state.

`Mail::fake()` is `Send + Sync`; share it across awaits or threads as needed.

## Custom Transports

The `MailTransport` trait is the integration point:

```rust
use suprnova::async_trait;
use suprnova::mail::{MailTransport, OutgoingMessage};
use suprnova::FrameworkError;

pub struct StdoutTransport;

#[async_trait]
impl MailTransport for StdoutTransport {
    async fn send(&self, msg: &OutgoingMessage) -> Result<(), FrameworkError> {
        let to = suprnova::mail_wire::mailbox_list("stdout", &msg.to)?;
        println!("--- mail to {to} ---\n{}\n--- end ---", msg.subject);
        Ok(())
    }
    fn name(&self) -> &'static str { "stdout" }
}

// At boot:
use std::sync::Arc;
suprnova::mail::Mail::set_transport(Arc::new(StdoutTransport))?;
```

By the time `send` runs, the dispatch path has validated the message and put every address in its wire form. Build recipient text with `suprnova::mail_wire` - `mailbox_text`, `mailbox_list`, `email`, and `display_name` - never with `Address`'s `Display`, which does not quote the display name, so `Doe, Jane <jane@example.com>` reads as two recipients. `mail_wire::check_header` and `mail_wire::check_message` apply the rules in [What a message may contain](#what-a-message-may-contain) for a transport you also call directly.

Transports run on Tokio's runtime - async IO, connection pooling, and concurrent send are first-class. There is no per-request fork penalty.

### Why Suprnova diverges

Laravel's Mailable layer is built on Symfony Mailer, which runs synchronously inside the request lifecycle. Suprnova's `MailTransport` is `async fn send(&self, msg: &OutgoingMessage)` end-to-end: the HTTP providers use `reqwest`, the SMTP path uses an async lettre adapter, and `dispatch_with_telemetry` wraps every send in a Tokio `tracing` span. Long-haul providers don't block the handler thread, connection pools survive across requests, and concurrent sends in one handler are trivial - `tokio::try_join!(Mail::to(a).send(m), Mail::to(b).send(n))` does what you'd expect.

The other divergence is event cancellation. Laravel models a `MessageSending` listener that can return `false` and suppress the send (`events->until()`). Suprnova's dispatcher does not expose a short-circuit return channel - `MessageSending` is observation-only. To gate a send, refuse at the Mailable layer (override `render_html` / `render_text` to return an error) or wrap the `MailBuilder::send` call with your own guard. The trade is real: we lose one Laravel hook to keep the dispatcher's contract simple.

One smaller divergence is deliberate hardening. Laravel is content to leave `MAIL_MAILER=log` running in production; Suprnova refuses to boot there without an explicit acknowledgement, because a mail subsystem that reports success and delivers nothing is the kind of outage nobody notices for weeks. The `log` driver itself behaves exactly as Laravel's does - full message, bodies and links included - which is what makes it useful in development, and the production refusal is what keeps that safe (see [The `log` driver logs the whole message](#the-log-driver-logs-the-whole-message)).

## Best Practices

### Register factories at boot, not per-request

`Mail::queue` and `Mail::later` push a `SendMailJob` carrying the mailable's name and JSON payload - the worker rebuilds the concrete type via `mailable_registry`. Register every queueable `Mailable` once at `Server::run` time:

```rust
// bootstrap.rs
pub fn register() -> Result<(), suprnova::FrameworkError> {
    suprnova::mail::register_mailable_factory::<WelcomeEmail>()?;
    suprnova::mail::register_mailable_factory::<PasswordReset>()?;
    suprnova::mail::register_mailable_factory::<InvoiceShipped>()?;
    Ok(())
}
```

A `Mail::queue` for an unregistered mailable lands on the queue, runs once, hits "unknown mailable", retries per the envelope's backoff policy, and dead-letters - costing observability time you would not have spent if the factory was bound at boot.

### Queue mail for any slow or unreliable render

Sending mail in a request handler couples the user's response latency to your SMTP server (or whichever provider's HTTP API). Use `Mail::queue` for anything beyond a synchronous local-dev render, and `Mail::later` when you want the dispatch deferred - onboarding follow-ups, reminder emails, scheduled digests.

```rust
// Bad: ties response time to the mail provider
Mail::to(&user.email).send(Welcome { ... }).await?;
return json_response!({ "ok": true });

// Good: 200 OK returns immediately; the worker delivers the mail.
Mail::to(&user.email).queue(Welcome { ... }).await?;
return json_response!({ "ok": true });
```

### Always set `from` on a Mailable

The framework's default sender is `noreply@localhost` - useful for catching missing senders in development, not a sender any provider will accept in production. Override `Mailable::from(&self)` (or set `from = "..."` in the `#[mail(...)]` attribute on a `NotificationMailable`) so every dispatched message has a real sender identity:

```rust
fn from(&self) -> Option<Address> {
    Some(Address::new("orders@example.com").with_name("Acme Orders"))
}
```

The per-message override on `MailBuilder` (`.from(("Operations", "ops@example.com"))`) takes precedence over the mailable's default - useful for one-off transactional sends.

### Use the queue for at-least-once delivery, not the direct path

`MailBuilder::send` is at-most-once: if the transport fails halfway through dispatching to two providers, you cannot retry without risking a duplicate send. `MailBuilder::queue` uses durable at-least-once delivery and exposes queue and connection routing, but it does not accept an idempotency key. A redelivered mail job can send twice. If a message must be deduplicated, put an application-level idempotency guard or provider-supported idempotency mechanism in a custom queued job rather than claiming `MailBuilder` accepts a key.

## One-off Messages: `Mail::raw` and `Mail::html`

When the mail is a single transactional ping that doesn't justify a full `Mailable` struct, two shortcuts skip the boilerplate:

```rust
use suprnova::mail::Mail;

// Plain text
Mail::raw("Your code is 12345", |b| {
    b.to("alice@example.org")
        .subject("Verification code")
        .from("auth@example.com")
}).await?;

// HTML
Mail::html("<p>Hello, <b>world</b></p>", |b| {
    b.to("alice@example.org")
        .subject("Hi")
        .from("hello@example.com")
}).await?;
```

The closure receives a [`MailBuilder`] preloaded with the body and lets you layer recipients, subject, sender, tags, metadata, priority, and any other [`MailBuilder`] fluent method on top. These paths bypass the `Mailable` trait entirely - useful for one-shot test pings and short transactional notes.

## Global Defaults: `always_from`, `always_reply_to`, `always_to`, `always_return_path`

Mirroring Laravel's `Mailer::alwaysFrom` / `alwaysReplyTo` / `alwaysTo` / `alwaysReturnPath`, the Mail facade exposes four global setters:

```rust
use suprnova::mail::{Address, Mail};

// At boot:
Mail::always_from(Address::new("noreply@example.com").with_name("Acme"))?;
Mail::always_reply_to(Address::new("support@example.com"))?;
Mail::always_return_path(Address::new("bounce@example.com"))?;

// Local-dev "single inbox" - route ALL mail to one address, drop CC/BCC:
Mail::always_to(Address::new("dev-inbox@example.com"))?;

// Roll everything back (tests typically call this at teardown):
Mail::forget_always()?;
```

Precedence is conservative - defaults only apply when the dispatched message lacks an explicit value:

| Field | Default applies when |
|-------|---------------------|
| `always_from` | Message `from` is the framework default `noreply@localhost` |
| `always_reply_to` | Message has no explicit `reply_to` |
| `always_to` | Always - routes every message to this address, clears CC/BCC |
| `always_return_path` | Message has no explicit `return_path` |

The same precedence applies on the queue path: queued mailables go through `apply_always_defaults` at worker dispatch time, so direct sends and queued sends converge on identical envelope shapes.

## Tags, Metadata, Priority, Headers, Return-Path

Every dispatched message can carry Laravel-style provider hints - tags, metadata key/values, RFC-2076 priority, custom MIME headers, and a Sender / bounce-to address. They forward to the HTTP providers' native fields (Postmark `Tag` / `Metadata` / `Headers`, SES `EmailTags` plus `Content.Simple.Headers`, SendGrid `categories` / `custom_args` / `headers`, Mailgun `o:tag` / `v:` / `h:`, Resend `tags` / `headers`) and to SMTP as RFC 5322 headers. SES and Resend take a tag as a name and value pair, so each bare tag goes out as `{name: "tag_<i>", value: <tag>}`.

On SMTP, the return path also becomes the envelope sender (`MAIL FROM`), which is the address bounces are sent to. The `From` header and the recipients do not change.

### What a message may contain

Every message is checked before anything sees it. `Mail::send`, `Mail::raw`, `Mail::html`, the queue worker, and the notification mail channel validate it before `MessageSending` fires and before the transport receives it - including a transport you bound with `Mail::set_transport` and the one behind `Mail::fake()`. `Mail::queue` and `Mail::later` validate when they push, so the caller gets the error instead of a worker failing the job on every attempt. The rules:

- A header name is 1 to 76 printable ASCII characters other than `:`, with no space (the RFC 5322 field-name grammar). CR, LF, and NUL are the bytes that turn one header into two.
- `To`, `Cc`, `Bcc`, `From`, `Sender`, `Reply-To`, `Return-Path`, `Subject`, `Date`, `Message-ID`, `MIME-Version`, and every `Content-*` header are refused as custom headers. Set them with the builder methods (`to`, `cc`, `bcc`, `from`, `reply_to`, `return_path`, `subject`, `attach`).
- A header value and the subject may not contain a line break or a control character other than TAB. A templated subject (`subject_template_source`) is trimmed, so the newline at the end of a template file does no harm. lettre folds a long header value at its spaces; a single word longer than a line is written unbroken.
- A tag, a metadata value, and an attachment name may not contain a line break or any control character.
- A metadata key follows the header-name grammar and is at most 65 characters, on every transport, because SMTP, the `file` driver, and Resend write it into an `X-Metadata-<key>` header name.
- An attachment's content type must parse as a MIME type.

A message that breaks a rule fails with an internal error and is not sent. An HTTP response shows a 500 and the detail stays in the logs, as with Laravel's `RfcComplianceException`: a bad address is a fault in the application, not in the request. Three provider limits add refusals of their own: Postmark carries one tag per email, SES carries tags and metadata only when the tag, the key, and the value hold nothing but `A-Z`, `a-z`, `0-9`, `_`, and `-`, and Resend carries a tag only when it holds nothing but those characters and is at most 256 characters long.

On SES specifically, headers ride whichever content shape the message uses:
`Content.Simple.Headers` for a plain message, real MIME header lines for a
message with attachments (which SES only accepts as raw MIME). The rules above
apply the same way to both shapes. A header name repeated more than once
keeps every value on the plain-message path but only the last value on the
attachment path - the same limit SMTP has.

Two ways to attach them - at the Mailable level for per-type defaults, or per-message on the builder:

```rust
use suprnova::async_trait;
use suprnova::mail::{Mailable, PRIORITY_HIGH};
use std::collections::BTreeMap;

#[async_trait]
impl Mailable for OrderShipped {
    fn mailable_name() -> &'static str { "OrderShipped" }
    fn subject(&self) -> String { format!("Order #{} shipped", self.order_id) }
    fn text_template_source(&self) -> Option<String> { Some("...".into()) }

    fn tags(&self) -> Vec<String> { vec!["transactional".into(), "order".into()] }
    fn metadata(&self) -> BTreeMap<String, String> {
        let mut m = BTreeMap::new();
        m.insert("order_id".into(), self.order_id.to_string());
        m
    }
    fn priority(&self) -> Option<u8> { Some(PRIORITY_HIGH) }
    fn headers(&self) -> Vec<(String, String)> {
        vec![("X-Origin".into(), "warehouse".into())]
    }
}
```

```rust
// Per-message on the builder. Builder wins on metadata-key collisions; tags + headers union.
Mail::to(&user.email)
    .tag("campaign-spring")
    .metadata("ab_variant", "B")
    .priority(1)
    .header("X-Source", "promo-feed")
    .return_path("bounce@example.com")
    .send(WelcomeEmail { name: user.name.clone() })
    .await?;
```

Constants for the five priority levels live at `suprnova::mail::{PRIORITY_HIGHEST, PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_LOW, PRIORITY_LOWEST}` - same `1..=5` integer scale Laravel uses.

### SES send options

Amazon SES v2's `SendEmail` takes three options beyond the message
itself. Pin them on the transport, or override per message with a
header:

```rust
use suprnova::mail::ses::SesMailTransport;

let transport = SesMailTransport::new(key, secret, "us-east-1")
    .tenant_name("acme")                                  // TenantName
    .configuration_set_name("transactional")              // ConfigurationSetName
    .list_management("newsletter", Some("weekly"));       // ListManagementOptions
```

| Header on the message | SES field | Shape |
|---|---|---|
| `X-SES-TENANT-NAME` | `TenantName` | the tenant name |
| `X-SES-CONFIGURATION-SET` | `ConfigurationSetName` | the configuration set name |
| `X-SES-LIST-MANAGEMENT-OPTIONS` | `ListManagementOptions` | `my-list`, `contactListName=my-list`, or `my-list; topicName=weekly` |

A header always beats the transport default, so one multi-tenant
transport plus a per-message header covers the common case:

```rust
Mail::to(&user.email)
    .header("X-SES-TENANT-NAME", &tenant.slug)
    .send(WelcomeMail { name: user.name.clone() })
    .await?;
```

These headers are transport directives, not message content: they are
consumed when the request is built and never rendered into the MIME
that reaches the recipient.

### Why Suprnova diverges

Laravel reads `X-SES-TENANT-NAME` and `X-SES-LIST-MANAGEMENT-OPTIONS`
off the message, but exposes `ConfigurationSetName` only through the
transport's options array - so switching configuration sets per message
means a second transport. Suprnova gives all three the same two sources,
adding an `X-SES-CONFIGURATION-SET` header. Header-beats-transport
precedence matches Laravel's, where message-derived options are merged
over the configured ones.

## Inspecting Captured Messages

`OutgoingMessage` carries Laravel-style inspection helpers - useful for both test assertions and runtime audit logging:

```rust
fn audit_outgoing(m: &suprnova::mail::OutgoingMessage) {
    if m.has_tag("transactional") && m.has_to("alice@example.org") { /* ... */ }
    if m.has_metadata("order_id") { /* ... */ }
    if m.has_subject("Welcome") { /* ... */ }
    if m.has_attachment("invoice.pdf") { /* ... */ }
    if m.has_attached_data(b"id,total", "report.csv", "text/csv") { /* ... */ }
    if m.has_header("X-Source", "promo-feed") { /* ... */ }
}
```

Recipient checks are case-insensitive on email; metadata, tag, subject, and attachment-filename checks are exact.

`has_attachment(name)` matches the name only, so it passes for any bytes
under that name. To check the file itself, use
`has_equivalent_attachment(&attachment)`, which compares the name, bytes,
and content type, or `has_attached_data(bytes, name, content_type)`.

## Test Fake: Expanded Surface

`Mail::fake()` covers BOTH the sent and queued tracks. Sent mail (via `MailBuilder::send`) lands in the in-memory transport; queued mail (via `.queue` / `.later`) lands in the fake's queue buffer.

```rust
use suprnova::mail::Mail;

#[tokio::test]
async fn boot_dispatches_welcome() {
    let fake = Mail::fake();

    onboard_user("alice@example.org").await.unwrap();

    // Sent-side
    fake.assert_sent_count(1);
    fake.assert_sent(|m| m.has_to("alice@example.org") && m.subject.starts_with("Welcome"));
    fake.assert_sent_to("alice@example.org");
    fake.assert_not_sent(|m| m.subject.contains("Password reset"));

    // Queued-side (for delayed mails)
    fake.assert_queued("WelcomeFollowup");
    fake.assert_queued_to("alice@example.org");
    fake.assert_queued_count(1);

    // Composite
    fake.assert_outgoing_count(2);   // sent + queued
    fake.assert_not_outgoing("PasswordReset");
}
```

Additional helpers:

| Helper | Purpose |
|--------|---------|
| `fake.captured()` | All sent messages |
| `fake.count()` | Sent count |
| `fake.queued()` | All queued `QueuedSnapshot`s |
| `fake.queued_count()` | Queued count |
| `fake.outgoing_count()` | Sent + queued |
| `fake.sent(predicate)` | Filter sent by predicate |
| `fake.sent_to(email)` | Filter sent by recipient |
| `fake.queued_named(name)` | Queued mailables of a given name |
| `fake.queued_to(email)` | Queued mailables to recipient |
| `fake.assert_sent_count(n)` | Exact sent count |
| `fake.assert_queued_count(n)` | Exact queued count |
| `fake.assert_outgoing_count(n)` | Exact total |
| `fake.assert_nothing_sent()` | Empty sent buffer |
| `fake.assert_nothing_queued()` | Empty queued buffer |
| `fake.assert_nothing_outgoing()` | Both empty |
| `fake.assert_sent_to(email)` | At least one sent to recipient |
| `fake.assert_not_sent_to(email)` | None sent to recipient |
| `fake.assert_queued(name)` | At least one queued of name |
| `fake.assert_queued_with(name, fn)` | At least one queued of name matching predicate |
| `fake.assert_queued_to(email)` | At least one queued to recipient |
| `fake.assert_not_queued(name)` | None queued of name |
| `fake.has_sent(name)` | Whether a mailable of that name was sent; a queued one does not count |
| `fake.has_sent_mailable::<M>()` | `has_sent` for the mailable type `M` |
| `fake.has_queued(name)` | Whether a mailable of that name was queued |

`QueuedSnapshot::decode::<M>()` deserializes the payload back into the concrete `M`, so type-checked predicates work without bespoke decode boilerplate.

## Events: `MessageSending` and `MessageSent`

Every dispatch fires two framework events, whatever path sent it: `Mail::send`, `Mail::raw` and `Mail::html`, a queued mail when the worker sends it, and a notification sent through the mail channel. A message refused by [What a message may contain](#what-a-message-may-contain) fires neither:

- `MessageSending` - immediately BEFORE the transport call. Listeners observe the message shape (recipients, subject, tags, body-shape flags).
- `MessageSent` - immediately AFTER a successful transport call. Listeners observe the same shape; failed sends do not emit this event.

```rust
use std::sync::Arc;
use suprnova::events::EventFacade;
use suprnova::mail::MessageSent;

EventFacade::listen::<MessageSent, _>(Arc::new(MyAuditListener)).await;
```

Both events are observation-only - the dispatcher does not model a Laravel-style cancellation channel. See [Why Suprnova diverges](#why-suprnova-diverges) above for the gating workaround.

## Multi-recipient Convenience: `Mail::cc` and `Mail::bcc`

The Mail facade exposes three entry points - `to`, `cc`, `bcc` - that all return a fresh `MailBuilder`. Use whichever matches the dominant routing intent:

```rust
// Start with a cc / bcc when the message is primarily an audit copy.
Mail::cc("manager@example.com")
    .to("alice@example.org")
    .send(OrderShipped { /* ... */ })
    .await?;
```

The same fluent surface applies regardless of which entry point you start with.

### Test against `Mail::fake()`, not against the bound transport

`Mail::fake()` installs a process-local capture transport for the duration of the RAII guard and restores whatever was bound before. Tests using it do not need to clear globals on every entry/exit - drop semantics handle that. Combine `#[serial_test::serial]` with `Mail::fake()` for tests that mutate the transport global; concurrent tests would clobber each other otherwise.

## Next

- [Notifications](notifications.md) - `Notify::send` fans out across mail, database, and webpush channels; `#[derive(NotificationMailable)]` is the macro-driven shortcut over the `Mailable` trait
- [Queues](queues.md) - the durable envelope `Mail::queue` and `Mail::later` ride on
- [Events](events.md) - listening for `MessageSending` / `MessageSent` plus the wider dispatcher model
- [Testing](testing.md) - `Mail::fake()` alongside the other `*::fake()` guards
- [Configuration](configuration.md) - typed config registration for service credentials

## Reference

- Trait: `suprnova::mail::Mailable`
- Facade: `suprnova::mail::Mail` (`to`, `cc`, `bcc`, `send`, `queue`, `later`, `on_queue`, `queue_on`, `raw`, `html`, `fake`)
- Bootstrap: `suprnova::mail::boot::bootstrap_from_env()`
- Transports: `LogMailTransport`, `InMemoryMailTransport`, `FileMailTransport`, `SmtpMailTransport`, `PostmarkMailTransport`, `SesMailTransport`, `SendGridMailTransport`, `MailgunMailTransport`, `ResendMailTransport`
- Queue job: `suprnova::mail::SendMailJob`
- Test guard: `suprnova::mail::MailFake`
- Telemetry helper: `suprnova::mail::dispatch_with_telemetry`


---

<!-- /docs/notifications -->

# Notifications

A notification is a small message you want a user (or "anyone with an
email address") to receive across one or more channels - mail, in-app
inbox, browser push, real-time WebSocket - from one call site. You
write `Notify::send(&user, &OrderShipped { … })`; the dispatcher fans
that single notification out across every channel the notification
declared, addressing each one through the recipient.

Use notifications when the *what* (an order shipped, an invoice was
paid) is more interesting to your code than the *how* (which transport
ended up delivering it). For raw transport access - composing a custom
mail body, publishing to a specific broadcast channel, sending a one-off
web push - go through [mail](mail.md), [broadcasting](broadcasting.md),
or [web push](web-push.md) directly.

## Quick start

```rust
use serde::{Deserialize, Serialize};
use suprnova::FrameworkError;
use suprnova::NotificationMailable;          // derive macro
use suprnova::notifications::channels::mail::MailRendering;
use suprnova::{Notifiable, Notification, Notify};

#[derive(Serialize, Deserialize, NotificationMailable)]
#[mail(
    subject = "Order shipped - tracking {{ tracking }}",
    html    = "<p>Your order is on its way.</p><p>Tracking: <code>{{ tracking }}</code></p>",
    text    = "Tracking: {{ tracking }}",
    from    = "orders@example.com",
    from_name = "Acme Orders",
)]
pub struct OrderShipped {
    pub tracking: String,
}

impl Notification for OrderShipped {
    fn notification_name() -> &'static str { "OrderShipped" }
    fn channels(&self) -> Vec<&'static str> { vec!["mail", "database"] }
    fn data(&self) -> serde_json::Value {
        serde_json::json!({ "tracking": self.tracking })
    }
}

struct User { id: i64, email: String }
impl Notifiable for User {
    fn route_for(&self, channel: &str) -> Option<String> {
        match channel {
            "mail"     => Some(self.email.clone()),
            "database" => Some(self.id.to_string()),
            _          => None,
        }
    }
}

async fn ship(user: &User, tracking: String) -> Result<(), FrameworkError> {
    Notify::send(user, &OrderShipped { tracking }).await
}
```

`Notify::send` dispatches to both the mail channel and the database
channel in one call. The recipient declines a channel by returning
`None` from `route_for` - useful for "email-only" or "push-only" users.

## The three traits

| Trait | What it represents | Implemented by |
|---|---|---|
| `Notification` | A typed message + the channels it dispatches to | Your notification structs |
| `Notifiable` | A recipient - exposes a per-channel `route_for` | Your `User`, `Order`, anything addressable |
| `Channel` | A transport - knows how to deliver to a route | Built-in: `MailChannel`, `DatabaseChannel`, `BroadcastChannel`, `WebPushChannel` |

### `Notifiable`

```rust
pub trait Notifiable: Send + Sync {
    fn route_for(&self, channel: &str) -> Option<String>;
}
```

The recipient owns the per-channel addressing. `route_for("mail")`
returns the email address; `route_for("database")` returns the entity
id as a string; `route_for("webpush")` returns a serialized
`SubscriptionInfo` JSON; `route_for("broadcast")` returns the
broadcast channel name. Return `None` to skip a channel for this
recipient.

### `Notification`

```rust
pub trait Notification: Serialize + DeserializeOwned + Send + Sync + 'static {
    fn notification_name() -> &'static str where Self: Sized;
    fn channels(&self) -> Vec<&'static str>;
    fn data(&self) -> serde_json::Value;

    fn should_send(&self, _channel: &str) -> bool { true }
    fn after_sending(&self, _channel: &str) -> Result<(), FrameworkError> { Ok(()) }

    fn queue(&self) -> Option<&'static str> { None }
    fn timeout(&self) -> Option<std::time::Duration> { None }
    fn fail_on_timeout(&self) -> bool { false }
    fn max_tries(&self) -> u32 { 3 }
    fn backoff(&self) -> BackoffSchedule { BackoffSchedule::default() }
    fn after_commit(&self) -> bool { false }
    fn delay(&self, _channel: &str) -> Option<std::time::Duration> { None }
}
```

| Method | Purpose |
|---|---|
| `notification_name()` | Stable identifier persisted by the database channel, used as the queue envelope key, and the lookup key for the mail renderer registry. |
| `channels(&self)` | Channel names this notification dispatches to. Order is iteration order. |
| `data(&self)` | JSON-serializable payload channels deliver / persist. Typically `serde_json::to_value(self)` of the subset of fields the channels need. |
| `should_send(&self, channel)` | Per-channel veto consulted on both the synchronous and queued paths. Returning `false` skips that channel for this dispatch. Default: always send. |
| `after_sending(&self, channel)` | Post-success hook invoked once per channel that completed, on both the synchronous and queued paths. Returning `Err` propagates the same way a channel error would. Default: no-op. |
| `queue(&self)` | Queue this notification's `Notify::queue` dispatch resolves to. Default: `None` (driver default, or a `Queue::route` if one is registered). See [Queue tuning](#queue-tuning). |
| `timeout(&self)` | Per-attempt timeout for this notification's queued jobs. Default: `None` (no timeout). |
| `fail_on_timeout(&self)` | If `true`, a timeout is a permanent failure (dead-letter, no retry). Default: `false`. |
| `max_tries(&self)` | Max attempts for this notification's queued jobs. Default: `3`. |
| `backoff(&self)` | Backoff schedule for this notification's queued jobs. Default: the framework default. |
| `after_commit(&self)` | `true` makes `Notify::queue` inside `DB::transaction` wait for the commit before it pushes the jobs. Default: `false`. See [Queued notifications inside a transaction](#queued-notifications-inside-a-transaction). |
| `delay(&self, channel)` | How long `Notify::queue` holds the job for `channel` before a worker may take it. Default: `None` for every channel. See [Queue tuning](#queue-tuning). |

`should_send` and `after_sending` are honored on **both** paths. `Notify::send`
consults them in the dispatcher; `Notify::queue` checks `should_send` before
enqueuing each per-channel job, and the worker re-checks `should_send` before
delivery (state can change between enqueue and run) and runs `after_sending`
after a successful send. The three lifecycle *events*
(`NotificationSending` / `NotificationSent` / `NotificationFailed`) fire on
both paths, and both carry `data()` as their payload.

## Channels

### Mail

The mail channel delivers via the bound mail transport (see
[Mail](mail.md)). A notification opts in by implementing
`NotificationMailable`:

```rust
pub trait NotificationMailable: Notification {
    fn to_mail(&self) -> Result<MailRendering, FrameworkError>;
}
```

`MailRendering` is the rendering envelope - `subject`, `html` and/or
`text` (at least one required), optional `from`, `cc`, `bcc`,
`reply_to`, `attachments`, and `attachment_paths`. The mail channel
assembles an outgoing message from this rendering plus the recipient's
`route_for("mail")`, applies the configured sender defaults
(`Mail::always_from(...)`, `always_to(...)`, etc.), and dispatches
through the configured mail transport.

If the renderer returns a rendering with neither `html` nor `text`,
delivery fails fast - blank notification mail is never sent silently.

An empty `subject` falls back to the notification's name after its last
`::`, in title case: words split at case changes and at `_`, `-`, and
`.`, so `InvoicePaid` is sent as `Invoice Paid`, as Laravel's mail
channel falls back to the class name.

#### Attachments

`MailRendering` attaches files four ways, as Laravel's `MailMessage`
does:

```rust
use suprnova::mail::Attachment;
use suprnova::notifications::channels::mail::{AttachOptions, MailRendering};

fn to_mail(statement: &Statement) -> MailRendering {
    MailRendering {
        subject: "Your statement".into(),
        text: Some("Your statement is attached.".into()),
        ..Default::default()
    }
    // In memory.
    .attach(Attachment::new("summary.csv", statement.csv(), "text/csv"))
    .attach_data(statement.terms(), "terms.txt", "text/plain")
    // By path, read when the mail is delivered.
    .attach_path("storage/statements/42.pdf", AttachOptions {
        name: Some("statement.pdf".into()),
        ..Default::default()
    })
    .attach_many([
        ("storage/legal/privacy.pdf", AttachOptions::default()),
        ("storage/legal/fees.html", AttachOptions {
            content_type: Some("text/html".into()),
            ..Default::default()
        }),
    ])
}
```

`attach_path` and `attach_many` record the paths in `attachment_paths`,
and the channel reads each file when it delivers the mail, so a queued
notification carries paths, not file contents. A file attached by path
takes its own name unless `AttachOptions::name` gives one, and the
content type its extension names unless `AttachOptions::content_type`
gives one, `application/octet-stream` for an extension the framework
does not know. A file that cannot be read fails the delivery with an
error that names the path, and nothing is sent. Files attached by path
follow the ones in `attachments`.

#### `#[derive(NotificationMailable)]`

The derive collapses the per-Notification `to_mail` `impl` into one
`#[mail(...)]` attribute. Templates use [Tera](https://keats.github.io/tera/);
`self`'s serialized fields are the context.

```rust
#[derive(Serialize, Deserialize, NotificationMailable)]
#[mail(
    subject = "Welcome {{ name }}",
    html_template = "templates/welcome.html",
    text_template = "templates/welcome.txt",
    from = "hello@example.com",
    from_name = "Acme",
    cc = "ops@example.com, support@example.com",
)]
pub struct Welcome { pub name: String }
```

Supported keys:

| Key | Required? | Purpose |
|---|---|---|
| `subject` | yes | Tera template - rendered with `self` as context. |
| `html` | dagger | Inline HTML body Tera template. |
| `html_template` | dagger | Path to an HTML body Tera template (embedded via `include_str!`). |
| `text` | dagger | Inline plain-text body Tera template. |
| `text_template` | dagger | Path to a plain-text body Tera template (embedded via `include_str!`). |
| `from` | no | Sender email - overrides the default `noreply@localhost`. |
| `from_name` | no | Display name. Requires `from`. |
| `cc` | no | Comma-separated CC list. Whitespace and trailing commas ignored. |
| `bcc` | no | Comma-separated BCC list. |
| `reply_to` | no | Comma-separated Reply-To list. |

(dagger) At least one body variant must be present. `html` and
`html_template` are mutually exclusive; same for `text` and
`text_template`.

Every invariant is enforced at compile time - missing `subject`, empty
body, conflicting variants, `from_name` without `from`, or unknown keys
fail the build instead of failing at dispatch.

For attachments or per-instance dynamic recipients, hand-implement
`NotificationMailable` and build the `MailRendering` directly, with the
[attachment methods](#attachments) above.

### Database

The database channel persists each notification as one row in the
`notifications` table:

```rust
use std::sync::Arc;
use suprnova::{DatabaseChannel, NotificationDispatcher};

let dispatcher = NotificationDispatcher::new()
    .register_channel(Arc::new(DatabaseChannel::new(db, "users")));
```

The second argument is the recipient's polymorphic type tag (what you
store in `notifiable_type` so you can query inbox rows back later). The
recipient's `route_for("database")` becomes the `notifiable_id`.

The framework ships the table as migrations in
`suprnova::notifications::migrations`. Register them in your app's
`Migrator`, in this order:

```rust
use sea_orm_migration::{MigrationTrait, MigratorTrait};
use suprnova::notifications::migrations::{
    CreateNotificationsTable, NotificationTimestampsToDatetime, NotificationsToLaravelLayout,
};

pub struct Migrator;

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            // ... your app's migrations ...
            Box::new(CreateNotificationsTable),
            Box::new(NotificationTimestampsToDatetime),
            Box::new(NotificationsToLaravelLayout),
        ]
    }
}
```

Then run `suprnova migrate` and the table appears. Until the `Migrator`
lists the migration, the channel's first insert fails on the missing
table.

The table is Laravel's `notifications`, so a Suprnova application reads and
writes the notifications a Laravel application stored. `notifiable_id`
follows `NOTIFICATIONS_MORPH_KEY`, as Laravel's `morphs` follows its
default morph key type: `int` (the default) for a big integer, `uuid` for
the column `uuidMorphs` creates, `ulid` for the one `ulidMorphs` creates.
`CreateNotificationsTable` creates the table when it is missing and leaves
one Laravel created as it is.

The other two upgrade a table an earlier release created.
`NotificationsToLaravelLayout` moves an earlier table, whose
`notifiable_id` was a 64-character string, into Laravel's layout with every
notification. `NotificationTimestampsToDatetime` matters on MySQL and
MariaDB, where earlier versions created `read_at`, `created_at` and
`updated_at` as `TIMESTAMP`, which refuses any time after 2038-01-19
03:14:07 UTC. It converts each of those columns of an earlier table to
`DATETIME`, keeping its nullability and the stored UTC times, and changes
nothing on Postgres or SQLite or on a table Laravel created. See
[Running on a Laravel Database](laravel-database.md).

#### Reading the inbox

The read-side helpers live in `suprnova::notifications` as free
functions over `(notifiable_type, notifiable_id)`:

```rust
use suprnova::notifications::{
    all_for, unread_for, read_for,
    mark_as_read, mark_as_unread, mark_all_as_read,
    delete_for, StoredNotification,
};

let unread: Vec<StoredNotification> = unread_for(&db, "users", "42").await?;
let count = mark_all_as_read(&db, "users", "42").await?;
let removed = delete_for(&db, "users", "42").await?;
```

`StoredNotification` carries `id`, `type_name` (the
`Notification::notification_name`), `notifiable_type`, `notifiable_id`,
the decoded JSON `data`, `read_at`, `created_at`, `updated_at`.
`mark_as_read` / `mark_as_unread` are idempotent (matching Laravel's
contract).

### Web push

The web push channel encrypts the payload and POSTs it to a stored
browser push subscription endpoint via the framework's
VAPID-signing client:

```rust
use std::sync::Arc;
use suprnova::WebPushChannel;
use suprnova::web_push::{VapidKey, WebPushClient};

let client = WebPushClient::new(
    VapidKey::from_pem(b"-----BEGIN PRIVATE KEY-----\n…")?,
    "mailto:ops@example.com",
)?;
let push_channel = WebPushChannel::new(Arc::new(client), 86_400 /* TTL seconds */)?;
```

The recipient's `route_for("webpush")` returns a serialized
`SubscriptionInfo` JSON (the same shape the browser hands back from
`PushSubscription.toJSON()` - store it verbatim, return it untouched).
The TTL is forwarded to the push service.

`WebPushChannel::new` reads `WEB_PUSH_ENDPOINT_ORIGINS`. When it names the
origins of your push services, the channel refuses an endpoint at any
other origin, and an entry that is not an origin makes `new` return an
error. See [Endpoint allowlist](web-push.md#endpoint-allowlist).

When the push service tells the channel a subscription is gone (HTTP
404/410), the channel logs a structured WARN and returns success - the
notification has reached a terminal state with no recipient to retry
against. Operators see the log and remove the dead subscription;
delivery does not error.

See [Web Push](web-push.md) for the full client.

### Broadcast

The broadcast channel publishes each notification to the application's
`BroadcastHub` so WebSocket subscribers receive it in real time. The
recipient's `route_for("broadcast")` is the channel name, the
notification type is the event, and `data()` is the payload:

```rust
use std::sync::Arc;
use suprnova::BroadcastChannel;
use suprnova::broadcasting::BroadcastHub;
use suprnova::container::App;

// At boot - bind the hub before any broadcast dispatch.
App::bind::<dyn BroadcastHub>(Arc::clone(&hub));

let dispatcher = suprnova::NotificationDispatcher::new()
    .register_channel(Arc::new(BroadcastChannel::new()));
```

The channel resolves the hub from the container at delivery time. If
no `BroadcastHub` is bound when a notification declares `"broadcast"`,
the channel returns an error - a misconfigured application surfaces
the problem instead of silently dropping the message. Publishing to a
channel with zero live subscribers is not an error.

A notification that implements `NotificationBroadcast` supplies its own
`BroadcastMessage`, as Laravel's `toBroadcast` does. The message's data
replaces `data()` as the payload, and `on_queue` or `on_connection`
sends the publish through a queued `BroadcastNotificationJob` on that
queue and connection. Register the notification once at boot:

```rust
use suprnova::notifications::channels::broadcast::{
    BroadcastMessage, NotificationBroadcast, register_broadcast_renderer,
};

impl NotificationBroadcast for OrderShipped {
    fn to_broadcast(&self) -> BroadcastMessage {
        BroadcastMessage::new(serde_json::json!({ "tracking": self.tracking }))
            .on_queue("broadcasts")
    }
}

// At boot, next to the other registrations.
register_broadcast_renderer::<OrderShipped>()?;
```

A message that names neither a queue nor a connection publishes at once.
A queued message does not need a hub at delivery; the worker publishes it
to the hub bound in its own container, and the job fails, to be retried,
when none is bound. The framework registers `BroadcastNotificationJob`
with the worker, so you never call `register_job` for it.

After the publish, or the push of the job, the channel dispatches
`BroadcastNotificationCreated` with the notification's name, the route,
the data, and the message's queue and connection, so you can listen for
every broadcast notification:

```rust
use std::sync::Arc;
use suprnova::{BroadcastNotificationCreated, EventFacade};

EventFacade::listen::<BroadcastNotificationCreated, _>(Arc::new(BroadcastAudit)).await;
```

The event fires only after the broadcast went out or was queued. An error
from a listener is logged and does not fail the delivery.

To assert a queued broadcast, install `Queue::fake()` and use
`assert_pushed_on_queue::<BroadcastNotificationJob>("broadcasts", |job| ...)`.

#### Why Suprnova diverges

Laravel's `BroadcastNotificationCreated` is a `ShouldBroadcast` event, so
every broadcast notification goes through the queue. Suprnova publishes
at once unless the message names a queue or a connection, which keeps a
broadcast real-time on an application without a running worker, and
keeps failing at delivery when no hub is bound.

See [Broadcasting](broadcasting.md) for hub setup and WebSocket
plumbing.

## On-demand notifications

Sometimes you want to notify *somebody who isn't in your database* - a
one-off ops alert to an email address, a webhook receiver, a broadcast
channel that no user owns. `AnonymousNotifiable` is the "user without a
row":

```rust
use suprnova::Notify;

let recipient = Notify::route("mail", "ops@example.com")?;
Notify::send(&recipient, &IncidentNotification { id: 7 }).await?;

// Multiple channels in one builder:
let recipient = Notify::routes([
    ("mail", "ops@example.com"),
    ("broadcast", "ops-channel"),
])?;
Notify::send(&recipient, &IncidentNotification { id: 7 }).await?;
```

`Notify::route("database", …)` and `Notify::routes([..., ("database",
…)])` return `Err` - the database channel persists a
`(notifiable_type, notifiable_id)` pair that an anonymous recipient
cannot supply.

## The dispatcher

`NotificationDispatcher` holds the channel registry. Build it once at
boot and bind it globally:

```rust
use std::sync::Arc;
use suprnova::{DatabaseChannel, MailChannel, NotificationDispatcher, WebPushChannel};
use suprnova::notifications::set_dispatcher;

let dispatcher = NotificationDispatcher::new()
    .register_channel(Arc::new(MailChannel::new()))
    .register_channel(Arc::new(DatabaseChannel::new(db, "users")))
    .register_channel(Arc::new(WebPushChannel::new(push_client, 86_400)?));

set_dispatcher(Arc::new(dispatcher))?;
```

`register_channel` is last-write-wins on the channel name - registering
two channels named `"mail"` silently replaces the first. This makes
test setups ergonomic.

A notification declaring a channel the dispatcher does not register
logs a WARN (`no channel registered; skipping`) and continues to the
next channel - dispatch does not error on an unknown channel name.

`set_dispatcher` returns `Result<(), FrameworkError>` because the
dispatcher registry lives behind a `RwLock`; the error path triggers
only if the lock is poisoned (a previous writer panicked). In practice
the call site at boot uses `?`.

### Lifecycle events

Three events surround every channel delivery, synchronous or queued:

| Event | When | Listener-error behaviour |
|---|---|---|
| `NotificationSending` | Immediately before the channel runs | Listener `Err` **vetoes** the channel for this dispatch |
| `NotificationSent` | After a successful delivery | Best-effort dispatch - listener errors don't propagate |
| `NotificationFailed` | When a channel returned an error | Best-effort dispatch; the underlying channel error still propagates per the first-failure-stops contract |

All three carry `(notification, channel, route, data)`, where `data` is the
notification's `data()` - the payload the channels see. A queued
notification is rebuilt on the worker from its full serialized form, but
the events still carry `data()`, so a field you keep out of `data()` never
reaches a listener. `Failed` adds the stringified `error`. Listen with `EventFacade::listen::<E, L>` -
see [Events](events.md).

These events fire only on the synchronous `Notify::send` path. The
queued worker delivers channels directly without dispatching the
events.

### Telemetry

`NotificationDispatcher::notify` wraps the fan-out in a
`notification.dispatch` tracing span:

- `notification` - `Notification::notification_name()`
- `channel_count` - declared channel count
- `duration_ms` - fan-out latency on completion
- terminal log: `notification dispatched` (info) or
  `notification dispatch failed` (warn)

The mail channel nests its own `mail.send` span inside.

### First-failure-stops contract

`Notify::send` returns on the first channel error. Channels that
already succeeded are not rolled back; channels that haven't run yet
are not attempted. The same contract applies to the queued worker.

For at-least-once across multiple channels, dispatch each channel
through its own `Notify::queue` call - the queue envelope's
idempotency keys protect against double-sends on retry.

## Queued delivery

`Notify::send` runs in-process. `Notify::queue` pushes a
`SendNotificationJob` onto the [Queue](queues.md), pre-resolving the
per-channel routes from the recipient so the worker doesn't need a
`Notifiable` handle at execute time:

```rust
use suprnova::notifications::register_notification_factory;
use suprnova::Notify;

// At boot - once per concrete notification reachable via Notify::queue.
register_notification_factory::<OrderShipped>()?;

// Anywhere:
Notify::queue(&user, OrderShipped { tracking }).await?;
```

The worker already knows `SendNotificationJob`: the framework registers its own job, so you register factories and never call `register_job` for it.

At dispatch time the worker:

1. Looks up the notification factory by `notification_name`
2. Reconstructs the typed notification from the JSON payload
3. Iterates the channels recorded at queue time
4. For each, re-checks `should_send(channel)` (skipping vetoed channels),
   looks up the channel on the bound dispatcher, calls
   `deliver(route, &notification)`, then runs `after_sending(channel)`

Channels that were declared at queue time but aren't registered when
the worker runs log a WARN and are skipped - same contract as the
synchronous path. Channels with no pre-resolved route are skipped
silently (the recipient returned `None` at queue time).

`Notify::queue` also evaluates `should_send` at enqueue time, so a vetoed
channel is never enqueued in the first place; the worker re-check covers
state that changes between enqueue and run. The worker fires the three
lifecycle events (`NotificationSending` / `NotificationSent` /
`NotificationFailed`) around each channel exactly as `Notify::send` does,
with the same `data()` payload, and a `NotificationSending` listener error
vetoes the channel on the worker too.

### Queue tuning

Five more `Notification` methods carry per-notification queue policy onto
`Notify::queue`'s dispatch, mirroring `Job`'s own tuning methods:

| Method | Default | Mirrors |
|---|---|---|
| `queue(&self)` | `None` - driver default, or a `Queue::route` if one is registered | `Job::queue()` |
| `timeout(&self)` | `None` - no per-attempt timeout | `Job::timeout()` |
| `fail_on_timeout(&self)` | `false` - a timeout retries like any other failure | `Job::fail_on_timeout()` |
| `max_tries(&self)` | `3` | `Job::max_tries()` |
| `backoff(&self)` | exponential, 2s base, 5min cap, ±25% jitter | `Job::backoff()` |

`Notify::queue` reads these from the notification instance once and carries
them onto every per-channel `SendNotificationJob` push. A notification that
overrides none of the five gets the exact envelope a bare `Notify::queue`
call always produced.

`delay(&self, channel)` delays one channel's job, as Laravel's `withDelay`
and `#[Delay]` do. It answers per channel, because each channel is its own
job: a digest can reach the database at once and the inbox an hour later.
The default, `None`, pushes every channel at once:

```rust
impl Notification for WeeklyDigest {
    fn notification_name() -> &'static str { "WeeklyDigest" }
    fn channels(&self) -> Vec<&'static str> { vec!["mail", "database"] }
    fn data(&self) -> serde_json::Value { serde_json::Value::Null }

    fn delay(&self, channel: &str) -> Option<std::time::Duration> {
        (channel == "mail").then_some(std::time::Duration::from_secs(3600))
    }
}
```

```rust
struct WelcomeDigest;

impl Notification for WelcomeDigest {
    fn notification_name() -> &'static str { "WelcomeDigest" }
    fn channels(&self) -> Vec<&'static str> { vec!["mail"] }
    fn data(&self) -> serde_json::Value { serde_json::Value::Null }

    fn queue(&self) -> Option<&'static str> { Some("digests") }
    fn timeout(&self) -> Option<std::time::Duration> { Some(std::time::Duration::from_secs(10)) }
    fn fail_on_timeout(&self) -> bool { true }
}
```

Set `fail_on_timeout(&self)` to `true` when a timeout means the delivery is
unrecoverable rather than transient: the worker dead-letters on the first
timeout instead of retrying up to `max_tries`.

These methods, `delay` included, apply only to `Notify::queue` -
`Notify::send` runs in-process and has no queue envelope to tune.

### Queued notifications inside a transaction

A notification queued inside a `DB::transaction` races that transaction. A
worker can pop the job before the commit and notify about a row the transaction has not committed, or about a row that a rollback then removes. Return `true` from
`Notification::after_commit` for a notification about rows the transaction
writes:

```rust
impl Notification for OrderPlaced {
    fn notification_name() -> &'static str { "OrderPlaced" }
    fn channels(&self) -> Vec<&'static str> { vec!["mail", "database"] }
    fn data(&self) -> serde_json::Value { serde_json::json!({ "order_id": self.order_id }) }

    fn after_commit(&self) -> bool { true }
}

DB::transaction(|_tx| {
    Box::pin(async move {
        let order = Order::create(suprnova::attrs! { total: 4999i64 }).await?;
        // Nothing reaches the queue here.
        Notify::queue(&user, OrderPlaced { order_id: order.id }).await?;
        Ok::<(), FrameworkError>(())
    })
})
.await?;
// The jobs are on the queue now, and only now.
```

Inside a transaction, `Notify::queue` pushes the per-channel jobs at the
commit, and a rollback discards them. Outside a transaction it pushes them at
once. A notification that returns `false` makes no choice: the queue
connection's own after-commit setting decides, then the process-wide
`QUEUE_AFTER_COMMIT`. See
[Which setting decides](queues.md#which-setting-decides).

### Why Suprnova diverges

Laravel keys queued notifications off the `ShouldQueue` marker
interface - the same `Notification::send($user, $notification)` call
queues if the notification implements `ShouldQueue` and sends inline if
it doesn't. The behaviour depends on a type-level flag at the
notification site, which is invisible from the call site.

Suprnova makes that choice explicit at every call: `Notify::send` is
always synchronous; `Notify::queue` is always queued. There is no
hidden mode switch. (That's also why there's no `send_now` - `send` is
already the synchronous one.)

The recipient side diverges too. Laravel's `Notifiable` trait is a
mixin that pulls in the inbox relationship, `routeNotificationFor*`
methods, and the polymorphic primary key. Suprnova's `Notifiable` is
deliberately minimal - just `route_for(channel) -> Option<String>` -
because Rust traits don't compose by mixin. The Laravel-equivalent
read-side ships as free functions over `(notifiable_type,
notifiable_id)` (`unread_for`, `mark_as_read`, …) so plain structs
can be notifiable without inheriting an ORM relationship.

## Testing

Two fake surfaces, answering different questions.

### `Notify::fake()` - "was a notification dispatched?"

```rust
use suprnova::Notify;
use suprnova::notifications::{
    assert_count, assert_nothing_sent, assert_sent_named,
    assert_sent_times, assert_sent_to, assert_sent_to_on,
    recorded_notifications,
};

#[tokio::test]
async fn ship_dispatches_order_shipped() {
    let _fake = Notify::fake();

    Notify::send(
        &User { id: 1, email: "alice@example.org".into() },
        &OrderShipped { tracking: "1Z…".into() },
    ).await.unwrap();

    assert_sent_named("OrderShipped");
    assert_sent_to("alice@example.org", "OrderShipped");
    assert_sent_to_on("alice@example.org", "mail", "OrderShipped");
    assert_sent_times("OrderShipped", 1);
    assert_count(2); // mail + database
}
```

While the fake guard is alive, both `Notify::send` and `Notify::queue`
record the dispatch instead of running channels or enqueuing a job -
no channel runs, no queue row is written. The fake holds a
process-wide serialization mutex, so parallel tests cannot interleave
captures; let the `_fake` guard drop at end-of-test to clear the
recorder.

You use methods on the returned guard to inspect concrete notification types:

```rust,ignore
let fake = Notify::fake();
Notify::send(&user, &OrderShipped { tracking: "1Z42".into() }).await?;
let sent = fake.sent::<OrderShipped>("alice@example.org", |n| n.tracking == "1Z42")?;
fake.assert_sent_to::<OrderShipped>("alice@example.org", |n| n.tracking == "1Z42");
fake.assert_not_sent_to::<OrderShipped>("bob@example.org");
```

You pass the recipient's per-channel route string. You match the concrete Rust
type, even when two types share a notification name. Your closure reads the
full recorded notification, including fields omitted from `data()`. You get
one notification per send or queue call when several channels use the same
route. You receive a `Result<Vec<N>, FrameworkError>` from `sent`; serialization
or decoding failures propagate instead of dropping a record. Your assertions
panic when no matching notification exists or an unwanted type was sent.
You keep using the existing untyped free functions, such as
`assert_sent_to(route, "Name")`, for per-channel records.

Use `recorded_notifications()` for full custody of the captured data:

```rust
let records = recorded_notifications();
assert_eq!(records[0].notification, "OrderShipped");
assert_eq!(records[0].channel, "mail");
assert_eq!(records[0].data["tracking"], "1Z…");
```

### `Mail::fake()` + real `MailChannel` - "did the notification *render* correctly?"

`Notify::fake()` short-circuits before the channel. To assert the mail
body actually rendered the way you expect, drive the real channel
under `Mail::fake()`:

```rust
use serial_test::serial;
use std::sync::Arc;
use suprnova::mail::Mail;
use suprnova::notifications::{set_dispatcher, NotificationDispatcher};
use suprnova::{MailChannel, Notify, register_mail_renderer};

#[tokio::test]
#[serial]
async fn ordershipped_renders_tracking_in_subject() {
    let fake = Mail::fake();
    register_mail_renderer::<OrderShipped>().unwrap();
    set_dispatcher(Arc::new(
        NotificationDispatcher::new()
            .register_channel(Arc::new(MailChannel::new())),
    )).unwrap();

    Notify::send(
        &User { id: 1, email: "alice@example.org".into() },
        &OrderShipped { tracking: "1Z…".into() },
    ).await.unwrap();

    fake.assert_sent_count(1);
    fake.assert_sent(|m| m.subject.contains("1Z…"));
}
```

Tests that touch the dispatcher, renderer, or transport globals must
be `#[serial_test::serial]` - those are process-global statics.

## Best practices

### Register every factory and renderer at boot

`Notify::queue` rebuilds the notification through the factory registry
at the worker, and `MailChannel` renders through `register_mail_renderer`.
Register every queueable / mailable notification up front:

```rust
// bootstrap.rs
use suprnova::notifications::register_notification_factory;
use suprnova::register_mail_renderer;

pub fn register() -> Result<(), FrameworkError> {
    // Notification factories (one per Notification reachable via Notify::queue).
    register_notification_factory::<OrderShipped>()?;
    register_notification_factory::<InvoicePaid>()?;

    // Mail renderers (one per NotificationMailable).
    register_mail_renderer::<OrderShipped>()?;
    register_mail_renderer::<InvoicePaid>()?;
    Ok(())
}
```

An unregistered notification on the queue surfaces as `unknown
notification: {name}` at worker execute time and retries through the
dead-letter path. A `MailChannel` dispatch for an unregistered renderer
surfaces a `register via suprnova::register_mail_renderer::<N>()` error
the same way.

### Queue for multi-channel fan-outs

The synchronous dispatcher visits channels in order and returns on the
first error. A failure on channel #2 leaves channel #1 committed and
channels #3+ unattempted. For any notification that crosses more than
one channel, prefer `Notify::queue` so the worker handles retries with
backoff and the dispatch survives a process crash.

### Make channel deliveries idempotent

Worker retries mean the same `SendNotificationJob` can execute more
than once. The built-in channels are idempotent-friendly: `MailChannel`
forwards to providers that typically dedupe by message-id;
`DatabaseChannel` inserts a fresh UUID per execution (which is the
right behaviour for an audit row); `WebPushChannel` POSTs to a
provider that swallows duplicates. Custom channels should target
idempotent operations - HTTP POSTs with stable client-side dedupe
keys, upserts rather than blind inserts, no "increment a counter"
side-effects on the delivery path.

### Bind the dispatcher in one place

`register_channel` is last-write-wins, so tests can swap a real
channel for a stub in setup. Keep the production binding in
`bootstrap.rs` and let tests build their own dispatcher with whatever
stubs they need. Don't `register_channel` lazily inside request
handlers - the global lock writes plus last-write-wins semantics get
surprising under concurrent load.

## Reference

| Symbol | Path |
|---|---|
| `Notifiable`, `Notification`, `Channel`, `DynNotification` | `suprnova::` |
| `Notify` (facade), `NotifyFakeGuard` | `suprnova::` |
| `NotificationDispatcher`, `NotificationFactory` | `suprnova::` |
| `AnonymousNotifiable` | `suprnova::` |
| `MailChannel`, `MailRendering`, `NotificationMailable` | `suprnova::` |
| `AttachOptions`, `PathAttachment` | `suprnova::` |
| `register_mail_renderer::<N>()` | `suprnova::` |
| `DatabaseChannel`, `StoredNotification` | `suprnova::` |
| `WebPushChannel` | `suprnova::` |
| `BroadcastChannel`, `BroadcastMessage`, `NotificationBroadcast`, `BroadcastNotificationJob` | `suprnova::` |
| `register_broadcast_renderer::<N>()` | `suprnova::` |
| `SendNotificationJob` | `suprnova::` |
| `NotificationSending`, `NotificationSent`, `NotificationFailed`, `BroadcastNotificationCreated` | `suprnova::` |
| `set_dispatcher`, `register_notification_factory` | `suprnova::notifications::` |
| `all_for`, `unread_for`, `read_for`, `mark_as_read`, `mark_as_unread`, `mark_all_as_read`, `delete_for` | `suprnova::notifications::` |
| `CreateNotificationsTable`, `NotificationTimestampsToDatetime` | `suprnova::notifications::migrations::` |
| `assert_sent`, `assert_sent_named`, `assert_sent_times`, `assert_sent_to`, `assert_sent_to_on`, `assert_nothing_sent`, `assert_nothing_sent_to`, `assert_count`, `recorded_notifications` | `suprnova::notifications::` |
| `#[derive(NotificationMailable)]` | `suprnova::` |

## Next

- [Mail](mail.md) - the transport and `Mailable` surface the mail channel rides on
- [Broadcasting](broadcasting.md) - the `BroadcastHub` the broadcast channel publishes through
- [Web Push](web-push.md) - VAPID, encryption, subscription storage
- [Events](events.md) - listening to `NotificationSending` / `Sent` / `Failed`
- [Queues](queues.md) - the worker that drives `Notify::queue`
- [Testing](testing.md) - fake surfaces and serial-test patterns


---

<!-- /docs/processes -->

# Processes

The `Process` facade runs other programs: a build tool, `git`, an image
converter, a script. It captures what the program writes, ends it when it
runs too long, cleans up everything it started, runs several side by side,
and fakes them all in tests. It is Laravel's `Process` facade with the
command and the shell line kept apart.

```rust
use suprnova::Process;

let status = Process::command(["git", "status", "--short"])
    .path("/srv/app")
    .run()
    .await?;

if status.successful() {
    println!("{}", status.output());
}
```

## Commands and shell lines

`Process::command` takes the program and its arguments. Each argument
reaches the program as it is, through no shell, so a value from a form or
a file name with spaces is never split or run:

```rust
use suprnova::Process;

// `name` might hold "x; rm -rf ~": it is still one file name to convert.
Process::command(["convert", name.as_str(), "thumb.png"]).run().await?;
```

`Process::shell` takes a command line and runs it through the system
shell, `sh -c` (`cmd /C` on Windows), the way Laravel runs a string
command. Pipes, `&&`, redirects, `$VAR` and globs work:

```rust
use suprnova::Process;

Process::shell("npm ci && npm run build > build.log").run().await?;
```

Never build a shell line from input you do not control: the shell runs
whatever the line holds. Use `Process::command` for that.

## Results

`run` waits for the program and returns a `ProcessResult`:

| Method | Returns |
|---|---|
| `successful()` / `failed()` | whether the exit code is 0 |
| `exit_code()` | `Some(code)`, or `None` when a signal ended it |
| `output()` / `error_output()` | everything written to standard output and standard error, as text |
| `output_bytes()` / `error_output_bytes()` | the same, byte for byte, for output that is not text |
| `see_in_output(text)` / `see_in_error_output(text)` | whether the output contains `text` |
| `command()` | the command line that ran |

A nonzero exit is a result that reports failure, not an error. Call
`throw()` to turn a failed result into a `ProcessError::Failed` that
carries the exit code and both outputs, so `?` stops on it:

```rust
let built = Process::command(["cargo", "build"]).run().await?.throw()?;
```

`run` returns an error only when the program did not give a result: it
could not be started (`ProcessError::NotStarted`, which names the
program and command line), or it was killed for a timeout.

You see arguments quoted as a POSIX shell would quote them in results and
errors. `Process::command(["printf", "a b"])` reports `printf 'a b'`.
The quoting only describes the command; you still pass arguments directly.

## Options

Every option takes the builder and returns it:

| Option | Effect |
|---|---|
| `path(dir)` | the working directory |
| `env(key, value)` | adds a variable to the inherited environment; `env("HOME", None)` removes it |
| `input(bytes)` | writes to standard input, then closes it; without it, standard input is empty |
| `timeout(duration)` | the longest it may run; 60 seconds unless set, and zero means none, as in Laravel |
| `forever()` | no timeout |
| `idle_timeout(duration)` | the longest it may go without writing output |
| `quietly()` | keeps no output: it is read and thrown away, and no output callback is called |
| `tty()` | hands the program this terminal, for a program that talks to the user; nothing is captured, and an idle timeout is refused, since nothing can watch the terminal. Redirected standard input or standard output returns an error naming that stream. `Process::supports_tty()` says whether there is a terminal |

`run_with(callback)` calls the callback with each chunk of output as it
arrives, marked `OutputKind::Out` or `OutputKind::Err`:

```rust
use suprnova::{OutputKind, Process};

Process::command(["npm", "run", "build"])
    .run_with(|kind, chunk| match kind {
        OutputKind::Out => print!("{chunk}"),
        OutputKind::Err => print!("[stderr] {chunk}"),
    })
    .await?;
```

## Timeouts and cleanup

A program that runs past its timeout is killed and `run` returns
`ProcessError::TimedOut`, naming the command and the timeout. One that
writes nothing for its idle timeout is killed the same way, with
`ProcessError::IdleTimedOut`. Both errors carry the output written before
the kill.

A kill reaches everything the program started: a script that started
background jobs takes them with it. On Unix each program gets a process
group of its own, and the group is killed. A `tty()` program stays in the
terminal's group, which it must share to read the terminal, so its
descendants are found in the process table and killed one by one. On
Windows `taskkill /T` ends the tree. The same cleanup happens when the
future of `run` is dropped before it completes, as `tokio::time::timeout`
or a `select!` drops it, and when a started process is dropped. A program
that exits by itself is waited on until its output closes, and nothing it
left behind is killed.

On Linux, cleanup reads the process tree from procfs and kills descendants
that called `setsid` or otherwise left the group. It sweeps twice to find
children forked during cleanup.
You cannot rely on cleanup to find a descendant that reparented to init before
the first tree snapshot.
When you wait for a program that exits by itself, it is not collected until
its output closes, so its group id cannot pass to an unrelated process that
a later kill would hit.

A child in a group of its own does not get the `SIGINT` a terminal sends
on Ctrl-C. The server and the workers end their children when they shut
down; a console command that Ctrl-C kills outright leaves its children
running unless it handles the signal, for instance with
`tokio::signal::ctrl_c()` in a `select!` beside the run.

## Started processes

`start` returns the program running, as an `InvokedProcess`:

```rust
use std::time::Duration;
use suprnova::{Process, Signal};

let mut worker = Process::command(["./app", "queue:work"])
    .forever()
    .start()?;

println!("pid {:?}", worker.id());
while worker.running() {
    print!("{}", worker.latest_output());
    tokio::time::sleep(Duration::from_secs(1)).await;
}
let result = worker.wait().await?;
```

`output()` and `error_output()` return everything so far, and
`latest_output()` and `latest_error_output()` what came since the last
call. You use `signal(Signal::Term)` to signal the program itself.
You use `stop(grace, signal)` to signal it and everything it started,
then kill whatever remains after the grace period and return the result.
`stop(None, None)` gives it 10 seconds and sends `Signal::Term`.
`stop(Duration::from_secs(1), Signal::Interrupt)` gives it one second
after an interrupt.
`wait_until(|kind, chunk| ...)` waits until the callback returns `true` for
a chunk of output. The timeouts hold for a started process whether or not
anything waits on it: a watchdog kills it at its timeout, and `wait` then
returns the timeout error. Call `start` inside a Tokio runtime: the output
is read by tasks of its own.

## Pools

`Process::pool()` runs processes side by side. Add each under a key, or
push it to be keyed by its position:

```rust
use suprnova::Process;

let results = Process::pool()
    .add("assets", Process::command(["npm", "run", "build"]))
    .add("types", Process::command(["suprnova", "generate-types"]))
    .push(Process::command(["cargo", "check"]))
    .concurrency(2)
    .run()
    .await;

if !results.successful() {
    for key in results.failed() {
        eprintln!("{key} failed");
    }
}
```

`results.get(key)` returns that process's result, or its error when it
could not run or was killed for its timeout. A failure stops nothing else.
A pushed process is keyed by its position, or the next free number when a
key already holds it, and adding a key twice replaces the first process.
With `concurrency(n)` at most `n` run at once and the rest wait for a
slot; without it every process starts at once. `start()` returns the pool
running, as an `InvokedPool`, with `running`, `signal`, `stop` and
`wait`; each `running()` call starts waiting processes in the slots that
freed, so a pool can be polled to the end.

## Pipes

`Process::pipe()` runs processes in order, each with the previous one's
output as its input, and returns the last result:

```rust
use suprnova::Process;

let sorted = Process::pipe()
    .push(Process::command(["cat", "words.txt"]))
    .push(Process::command(["sort", "-u"]))
    .run()
    .await?;
```

The first process that fails ends the pipe and its result comes back; the
processes after it do not run. The output passes byte for byte, so a pipe
can carry an archive or an image. Each process runs to its end before the
next starts, as in Laravel. For a streaming pipe, use `Process::shell`
with `|`.

## Testing

`Process::fake()` stops every process from running while its guard lives.
A command whose command line matches a pattern gets that result; any other
gets an empty successful one:

```rust
use suprnova::Process;

let fake = Process::fake();
fake.when("git *", Process::result("main\n"));
fake.when("npm run *", Process::result("").error_output("failed").exit_code(1));

deploy().await?; // runs git and npm

fake.assert_ran("git branch --show-current");
fake.assert_ran_times("npm run build");
fake.assert_not_ran("git push --force");
```

The command line is the arguments joined by spaces, or the shell line as
given, and `*` matches any run of characters; the first matching pattern
wins. You use `assert_ran_times(command)` to assert one run and
`assert_ran_count(command, count)` to assert another count.
`fake.prevent_stray_processes()` turns an unmatched command into
`ProcessError::Stray`.

You can answer a matching command with a closure that receives the pending
process and returns a `FakeResult`:

```rust
fake.when("git *", |pending: &suprnova::PendingProcess| {
    assert_eq!(pending.arguments().map(|args| args[0].as_str()), Some("git"));
    Process::result("main\n")
});
```

You inspect `command_line()`, `arguments()`, `working_directory()`,
`environment()` and `standard_input()` in the closure. Shell commands
return `None` from `arguments()`. Environment entries hold `Some(value)`
for a set variable and `None` for a removed variable.

`Process::describe()` builds a process line by line, for a started process
that reports itself running for a number of `running()` calls:

```rust
fake.when(
    "worker *",
    Process::describe()
        .output("processing 1")
        .output("processing 2")
        .exit_code(0)
        .runs_for(2),
);
```

You receive described output and error output in the order you add their
lines, including mixed streams. Each described line ends with one newline,
including an empty line or a line you already end with a newline.

A faked started process reveals its output a line at a time, as a real one
would write it, so you can test code that polls a running process. Each call
of `output()` or `latest_output()` reveals the next standard output line:
`output()` returns every line revealed so far, and `latest_output()` returns
the line it revealed, or the empty string when no line is left. The two share
one count. `error_output()` and `latest_error_output()` do the same for the
error output:

```rust
fake.when("worker", Process::describe().output("one").output("two"));

let worker = Process::command(["worker"]).start()?;
assert_eq!(worker.latest_output(), "one\n");
assert_eq!(worker.output(), "one\ntwo\n");
assert_eq!(worker.latest_output(), "");
```

A line that `running()` showed counts as revealed, and every line is revealed
once `running()` returns `false`. The result `wait()` returns always holds the
whole output.

`.id(n)` sets the process id a described process reports, and
`.replace_output(text)` and `.replace_error_output(text)` set all of its
lines at once. A faked started process records the signals sent to it, for
`has_received_signal(Signal::Term)`.

`Process::sequence([...])` answers its results in turn, one a run, and
`.push(result)` adds one at the end. A run after the last is
`ProcessError::FakeExhausted`, unless `.dont_fail_when_empty()` makes it
an empty success or `.when_empty(result)` gives the result to answer.

The assertions are `assert_ran`, `assert_ran_with(|process| ...)`,
`assert_ran_times`, `assert_ran_count`, `assert_ran_in_order`, `assert_not_ran` (and
`assert_didnt_run`) and `assert_nothing_ran`; `recorded()` returns every
faked process with its command line, argument list, quoted command line,
working directory, environment, input and result. Runs, starts, pools and
pipes are all faked and recorded.

`assert_ran` and the patterns match the arguments joined by spaces, so
`["printf", "a b"]` and `["printf", "a", "b"]` look the same to them. When
the split matters, `assert_ran_args(&["printf", "a b"])` compares the
argument list exactly, and `assert_ran_command_line("printf 'a b'")` compares
the command line with each argument quoted for a POSIX shell, as
`InvokedProcess::command()` reports it. A shell line has no argument list, so
`assert_ran_args` never matches one; its command line is the line as given:

```rust
Process::command(["printf", "a b"]).run().await?;

fake.assert_ran("printf a b");
fake.assert_ran_args(&["printf", "a b"]);
fake.assert_ran_command_line("printf 'a b'");
```

The fake is process-global, like `Storage::fake`, and its guard
serializes the tests that take one. A test that runs real processes at
the same time as a faked test would be faked too, so keep real-process
tests out of a binary whose tests fake, or mark them `#[serial]`.

### Why Suprnova diverges

- **The command and the shell line are two methods.** Laravel's `run`
  takes either a string, run through a shell, or an array, run as it is,
  and the difference is easy to miss when a value is interpolated.
  `command` and `shell` make the choice visible.
- **A kill reaches everything the program started.** Laravel kills the
  program; a background job it started keeps running.
- **Pools take a concurrency limit.** Laravel starts every process in a
  pool at once.
- **A started process's timeout holds without a wait.** Laravel checks it
  only while something waits on the process.
- **The fake is a guard.** `Process::fake()` returns the fake, and the
  assertions are its methods, so a test cannot assert against a fake it
  did not install.
- **`assert_ran` matches the joined line.** Laravel's `assertRan` compares
  an array command as an array. Here `assert_ran` and the patterns match the
  arguments joined by spaces, which reads the way you type the command, and
  `assert_ran_args` compares the list when the split matters.

## Next

- [Queues](queues.md) - running the work in the background instead
- [Task Scheduling](scheduling.md) - running a command on a schedule
- [Testing](testing.md) - the other fakes


---

<!-- /docs/web-push -->

# Web Push

Web Push delivers a short message to a browser even when your site is
closed - the Service Worker wakes up, decrypts the payload, and shows
an OS-level notification. Suprnova ships the protocol end-to-end:
VAPID key generation, AES128GCM payload encryption, the HTTP transport,
and a `WebPushChannel` that plugs into the notifications subsystem so
the same `Notification` you send to mail or database also lands as a
push.

Reach for this when you want to alert users in real time without an
open WebSocket - order shipped, friend request, mention, balance
posted. If the user is on a desktop browser with the site closed, web
push is the only mechanism that reaches them; if they're on the site,
[Broadcasting](broadcasting.md) is usually a better fit.

The API is behind the `web-push` Cargo feature, which is enabled by default.
Applications using `default-features = false` must enable `web-push`
explicitly.

## The four pieces

Web Push has more moving parts than mail or database, because the
spec ([RFC 8030](https://datatracker.ietf.org/doc/html/rfc8030) +
[RFC 8291](https://datatracker.ietf.org/doc/html/rfc8291) +
[RFC 8292](https://datatracker.ietf.org/doc/html/rfc8292)) splits
identity, encryption, and transport across three contracts:

| Piece | What it is |
|---|---|
| `VapidKey` / `VapidSigner` | A P-256 ECDSA keypair used to sign JWTs that prove your server is who it claims to be |
| `WebPushClient` | The HTTP client that encrypts a payload, signs a VAPID JWT, and POSTs to the subscription's endpoint |
| `WebPushChannel` | The notifications-subsystem adapter that turns a `Notification` into a `WebPushClient::send` call |
| `SubscriptionInfo` | The opaque (`endpoint`, `p256dh`, `auth`) triple the browser hands you when a user subscribes - you store it; you don't generate it |

The bottom three layers - `VapidKey`, `WebPushClient`, the encrypted
POST - are re-exported from `suprnova::web_push` so applications never
need to depend on the underlying `suprnova-web-push` crate directly.

## Generate a VAPID keypair

Web Push uses VAPID (Voluntary Application Server Identification) to
let push services rate-limit and contact misbehaving senders. You need
one P-256 keypair per application; the public key goes into your
frontend so the browser can pin subscriptions to your server, and the
private key stays on the server signing JWTs.

Generate one once, persist it, and reuse it forever:

```rust
use suprnova::VapidKey;

let key = VapidKey::generate();

// Save the PEM somewhere durable - a secrets manager, a file the deploy
// pipeline mounts, an env-vars-as-files volume. You CANNOT regenerate
// this without invalidating every existing subscription.
let pem = key.to_pem()?;
std::fs::write("vapid_private.pem", &pem)?;

// The frontend needs the base64url-no-padding uncompressed public key.
// Hand this to your JS so `pushManager.subscribe()` can use it as
// `applicationServerKey`.
println!("PUBLIC_VAPID_KEY={}", key.public_key_uncompressed_b64url());
```

At boot, load the saved PEM:

```rust
use suprnova::{VapidKey, VapidSigner};

let pem = std::fs::read_to_string("vapid_private.pem")?;
let key = VapidKey::from_pem(&pem)?;
let signer = VapidSigner::new(key);
```

A `VapidSigner` produces JWTs but does not send anything - it's
purely a signing primitive. The next layer wraps it.

## Build a WebPushClient

`WebPushClient` is the HTTP-side primitive: feed it a signer and a
contact URI ("how the push service can reach you if you misbehave"),
get back an object whose `send` method encrypts a payload, signs a
JWT, and POSTs to the subscription endpoint.

```rust
use std::sync::Arc;
use suprnova::{VapidKey, VapidSigner, WebPushClient};

let signer = VapidSigner::new(VapidKey::from_pem(&pem)?);

// The subject MUST be a mailto: URI or an https: URL per RFC 8292 §2.1.
// Anything else is rejected at construction so a misconfigured deploy
// fails fast at boot - not silently after the first failed dispatch.
let client = WebPushClient::new(signer, "mailto:ops@example.org")?;

let client = Arc::new(client);
```

Why `Arc<WebPushClient>`? `WebPushClient` wraps a `VapidSigner` which
wraps a private `ES256KeyPair`. None of those are `Clone` - private
keys shouldn't be casually duplicated - and constructing a fresh
signer for every channel registration would mean N independent VAPID
identities for the same application. Wrapping in `Arc` lets a single
signed identity back every registration and every concurrent delivery.

### Endpoint policy

Subscription endpoints are user-derived data: the browser receives the
URL from a remote push service when a user subscribes, and your server
stores whatever the browser handed back. A maliciously stored
subscription can point the HTTP POST anywhere reachable, turning the
push sender into an SSRF gadget.

`WebPushClient` defaults to `EndpointPolicy::Strict`, which checks the
endpoint before anything is sent:

- The scheme must be `https`.
- The host must be a name, not an IP address.
- The name must not be `localhost`, a cloud metadata name such as
  `metadata.google.internal`, or a name under an RFC 2606 reserved
  top-level domain (`.localhost`, `.local`, `.internal`, `.test`,
  `.example`, `.invalid`).
- Every address the name resolves to must be on the public internet. The
  client looks the name up and refuses the send when any answer is a
  loopback, private, link-local, multicast, unspecified, documentation
  or reserved address, or a cloud metadata address (`169.254.169.254`,
  `fd00:ec2::254`, `100.100.100.200`). Private covers RFC 1918, the RFC
  6598 shared address space and IPv6 unique local addresses.

The last check matters because the name in a stored endpoint is not
yours: a name someone else registered can resolve to `127.0.0.1` or to
`10.0.0.5`. After the check, the client connects to one of the addresses
it checked. TLS and the `Host` header still use the name, and the name
is not looked up a second time, so a DNS answer that changes between the
check and the connection (DNS rebinding) cannot move the request.

Real push services (FCM, Mozilla Autopush, Apple's `web.push.apple.com`)
pass every check.

A refused address returns `WebPushError::RefusedDestination`. It names
the class of the address, such as `AddressClass::Private`, and never the
address itself. A lookup that fails, or a name that resolves to no
address, returns `WebPushError::Lookup`, which `is_retryable()` reports as
retryable.

The connection goes to a checked address when the client builds its own
transport, with `WebPushClient::new` or
`WebPushClient::with_client_builder`. That transport sends through no
proxy. A proxy set on the builder is dropped, and `HTTPS_PROXY` and the
other proxy variables are not read: a proxy receives the name and
resolves it again, where the check cannot follow.

A client you pass to `WebPushClient::with_client` resolves the name
itself when it connects, so the check cannot hold the connection to the
addresses it checked. Under `Strict`, a send over such a client returns
`WebPushError::UnpinnedTransport` before anything is sent, until you
call `.allow_unpinned_destinations()` on the `WebPushClient`. After that
call, the endpoint and every address the name resolves to where your
application runs are still checked, and the connection goes wherever
your client sends it. See [Custom transport](#custom-transport).

For local integration tests against a `wiremock` mock server you have
to opt out:

```rust
use suprnova::{EndpointPolicy, WebPushClient};

let client = WebPushClient::new(signer, "mailto:test@example.org")?
    .with_endpoint_policy(EndpointPolicy::AllowAny);
```

Do not use `AllowAny` in production. The strict checks exist to keep
a tampered subscriptions table from being weaponised.

If your push service runs on a private network, `Strict` refuses it,
because its name resolves to a private address. The only policy that
reaches it is `AllowAny`, which turns off every check, so use it only when
your application, not a browser, decides which endpoints are stored.

### Endpoint allowlist

`Strict` refuses private and local destinations, but any public host
passes it, so a tampered subscription can still make your server POST to a
host of the attacker's choice. A browser subscribes only through its
vendor's push service, so when your subscriptions come from browsers you
can name every host they reach. `EndpointPolicy::Allowlist` refuses every
other host:

```rust
use suprnova::{EndpointAllowlist, EndpointPolicy, WebPushClient};

let allowlist = EndpointAllowlist::new([
    "https://updates.push.services.mozilla.com",
    "https://fcm.googleapis.com",
    "https://web.push.apple.com",
    "https://*.notify.windows.com",
])?;
let client = WebPushClient::new(signer, "mailto:ops@example.org")?
    .with_endpoint_policy(EndpointPolicy::Allowlist(allowlist));
```

These are the origins of the known browser push services:

| Browser | Push service origin |
|---|---|
| Firefox | `https://updates.push.services.mozilla.com` |
| Chrome and most other Chromium browsers | `https://fcm.googleapis.com` |
| Safari | `https://web.push.apple.com` |
| Microsoft Edge | `https://*.notify.windows.com` |

The allowlist runs every check of `Strict`, with the same errors. It checks
the endpoint's origin after the checks of the URL's shape and before the
host name is looked up, so an endpoint at a host outside the list causes
no DNS query and no connection. An endpoint the list admits then goes
through the address check and connects to a checked address, as under
`Strict`.

An origin is `https://host` or `https://host:port`, with no path, no
trailing slash, no query and no user name. The host is a name, not an IP
address. An endpoint matches an origin when its scheme is `https`, its host
is the same name in any letter case, and its port is the same; an endpoint
without a port uses 443. `EndpointAllowlist::new` returns
`InvalidAllowlist`, which quotes the entry, for any other form, and for an
empty list.

Microsoft's push service spreads its subscriptions over many hosts, such
as `wns2-par02p.notify.windows.com`, so its origin needs a wildcard. A host
can start with the label `*.`, which matches exactly one label:
`https://*.notify.windows.com` admits `wns2-par02p.notify.windows.com` but
not `a.b.notify.windows.com` or `notify.windows.com`. The wildcard is the
whole first label and appears once, and the name after it has two labels
or more, so `https://*.com` is refused.

An endpoint at another origin returns `WebPushError::OriginNotAllowed`
before anything is sent. It carries the origin, such as
`https://push.example.net`, and never the path of the endpoint, which is
the token that reaches the browser. `is_retryable()` returns `false`.

To send one message under a policy other than the client's own, such as
from a client that sits behind an `Arc` shared with other senders, call
`WebPushClient::send_with_policy`.

#### Set the allowlist for the notifications channel

`WebPushChannel` reads the allowlist from `WEB_PUSH_ENDPOINT_ORIGINS`, a
comma-separated list of origins in the form above:

```env
WEB_PUSH_ENDPOINT_ORIGINS=https://updates.push.services.mozilla.com,https://fcm.googleapis.com,https://web.push.apple.com,https://*.notify.windows.com
```

When the variable names one or more origins, every send of the channel
goes under `EndpointPolicy::Allowlist` with them, whatever policy you built
the client with, `AllowAny` included. Unset, or blank, the client's own
policy applies. Spaces around an entry and empty entries are ignored.
`WebPushChannel::new` reads the variable and returns an error that names it
when an entry is not an origin, so a typo fails at boot, where you build
the channel, instead of leaving the channel open to every host.

Set the variable when your application stores subscriptions from browsers.
Leave it unset when your push service runs on a private network, because
the allowlist keeps the strict address check, which refuses it.

### Custom transport

`WebPushClient::new` applies a 30-second per-request timeout. If you
need a different transport policy, such as pinned TLS or a shorter
timeout, pass a `reqwest::ClientBuilder` to
`WebPushClient::with_client_builder`. Your builder options are honoured,
but three settings are replaced after yours, because each would let a
send reach an address the strict policy did not check:

- Redirects are disabled. A validated endpoint that answers 3xx must not
  bounce the POST to an unvalidated URL.
- The DNS resolver is replaced by the one that connects a checked name
  to its checked addresses, and looks any other name up as usual.
- No proxy is used, whether you set one on the builder or the
  environment names one.

A name you map with `ClientBuilder::resolve` or
`ClientBuilder::resolve_to_addrs` still connects where you mapped it,
not to the checked address. reqwest applies a mapping only to a host
name equal to the name you mapped, compared without case, so a stored
endpoint reaches your address only at a name you chose, and cannot add
a mapping of its own. Map only a name whose address you want every
endpoint at that name to reach. `ClientBuilder::unix_socket` and
`ClientBuilder::connector_layer` also decide where a connection goes,
and the library cannot see them, so use them only to reach an address
you chose.

```rust
use reqwest::Client;
use std::time::Duration;
use suprnova::WebPushClient;

let client = WebPushClient::with_client_builder(
    Client::builder().timeout(Duration::from_secs(10)),
    signer,
    "mailto:ops@example.org",
)?;
```

`WebPushClient::with_client` takes an already-built client whose
redirect policy and name resolution the library cannot inspect. Under
the default `Strict` policy, a send over such a client is refused before
any I/O until you accept both by name:

- `.allow_unconfined_redirects()`, when the client does not follow
  redirects. Without it, the send returns
  `WebPushError::UnconfinedRedirects`.
- `.allow_unpinned_destinations()`, when you accept that the client
  connects wherever it resolves the name. Without it, the send returns
  `WebPushError::UnpinnedTransport`.

A push service you can reach only through a proxy needs such a client:

```rust
use std::time::Duration;
use suprnova::WebPushClient;

let http = reqwest::Client::builder()
    .proxy(reqwest::Proxy::https("http://proxy.internal:3128")?)
    .redirect(reqwest::redirect::Policy::none())
    .timeout(Duration::from_secs(30))
    .build()?;
let client = WebPushClient::with_client(http, signer, "mailto:ops@example.org")?
    .allow_unconfined_redirects()
    .allow_unpinned_destinations();
```

The strict checks still run on the answers your application gets for the
name. When your application cannot resolve the name at all, every send
returns `WebPushError::Lookup`, and the only policy that sends is
`AllowAny`, which turns off every check.

## Wire WebPushChannel into notifications

The raw `WebPushClient::send` works - but the way you actually send
push notifications in Suprnova is through the
[Notifications](notifications.md) subsystem. A `Notification` declares
`vec!["webpush"]` in its `channels()`, a `Notifiable` recipient
returns a JSON-encoded `SubscriptionInfo` from `route_for("webpush")`,
and the bound `NotificationDispatcher` does the fan-out.

```rust
use std::sync::Arc;
use suprnova::{
    NotificationDispatcher, WebPushChannel, WebPushClient,
    notifications::set_dispatcher,
};

let client: Arc<WebPushClient> = Arc::new(
    WebPushClient::new(signer, "mailto:ops@example.org")?
);

// ttl_secs: how long the push service holds an undelivered message.
// 86_400 (24h) is a reasonable default for non-urgent notifications;
// drop to 60 for "act right now" alerts where a stale message is
// worse than no message.
let webpush = Arc::new(WebPushChannel::new(client, 86_400)?);

let dispatcher = NotificationDispatcher::new()
    .register_channel(webpush);

set_dispatcher(Arc::new(dispatcher))?;
```

`WebPushChannel::new` returns an error when `WEB_PUSH_ENDPOINT_ORIGINS`
holds an entry that is not an origin. See
[Set the allowlist for the notifications channel](#set-the-allowlist-for-the-notifications-channel).

`register_channel` is last-write-wins on the channel's `name()`, so
tests can swap in a stub without affecting the production binding.

## Define a notification

A push-bound notification is the same shape as any other Suprnova
notification - declare `"webpush"` in `channels()` and put whatever
JSON you want delivered into `data()`:

```rust
use serde::{Deserialize, Serialize};
use suprnova::Notification;

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct OrderShipped {
    pub order_id: i64,
    pub tracking_url: String,
}

impl Notification for OrderShipped {
    fn notification_name() -> &'static str {
        "OrderShipped"
    }

    fn channels(&self) -> Vec<&'static str> {
        vec!["webpush"]
    }

    fn data(&self) -> serde_json::Value {
        serde_json::json!({
            "title":   "Your order has shipped",
            "body":    format!("Track order #{}", self.order_id),
            "url":     self.tracking_url,
        })
    }
}
```

The `data()` JSON is what your Service Worker receives. Pick a stable
shape and document it for the frontend - Suprnova doesn't impose one,
because notification UI is a frontend concern.

## Route the recipient

A `Notifiable` returns the route for each channel it supports.
For Web Push, that route is the JSON-encoded `SubscriptionInfo` -
exactly what the browser produced via `PushSubscription.toJSON()`,
stored verbatim:

```rust
use suprnova::Notifiable;

pub struct User {
    pub id: i64,
    pub push_subscription_json: Option<String>,
}

impl Notifiable for User {
    fn route_for(&self, channel: &str) -> Option<String> {
        match channel {
            "webpush" => self.push_subscription_json.clone(),
            _ => None,
        }
    }
}
```

Returning `None` causes the dispatcher to skip the channel silently -
useful for users who haven't subscribed to push but still get email.

## Send it

Synchronous:

```rust
use suprnova::Notify;

let user = User::find(42).await?.unwrap();
Notify::send(&user, &OrderShipped {
    order_id: 1234,
    tracking_url: "https://ship.example.org/o/1234".into(),
}).await?;
```

Queued - pre-resolves the subscription route at queue time so the
worker doesn't need to re-load the user:

```rust
Notify::queue(&user, OrderShipped {
    order_id: 1234,
    tracking_url: "https://ship.example.org/o/1234".into(),
}).await?;
```

For `Notify::queue` to work, register the notification's factory at
boot so the worker can rebuild the JSON payload into the typed
notification:

```rust
suprnova::notifications::register_notification_factory::<OrderShipped>()?;
suprnova::queue::worker::register_job::<suprnova::SendNotificationJob>();
```

Behind the scenes, queued dispatch builds a `SendNotificationJob`
carrying `(notification_name, payload, per_channel_routes, channels)`.
The worker re-hydrates the notification, looks up `WebPushChannel` by
name on the bound dispatcher, and calls `deliver(route, &notification)` -
the same code path as the synchronous `Notify::send`.

## The browser side

Suprnova does not ship a JavaScript SDK - the browser side is plain
Web Push API. The flow your frontend needs to implement:

1. Register a Service Worker.
2. Ask the user for permission.
3. Subscribe via `pushManager.subscribe({ userVisibleOnly: true,
   applicationServerKey: <your VAPID public key> })`.
4. POST `subscription.toJSON()` to a Suprnova endpoint that stores
   it on the user row.

```js
// Service Worker registration (somewhere in your app entrypoint)
const registration = await navigator.serviceWorker.register('/sw.js');

if (Notification.permission === 'default') {
    await Notification.requestPermission();
}

if (Notification.permission === 'granted') {
    const subscription = await registration.pushManager.subscribe({
        userVisibleOnly: true,
        applicationServerKey: window.PUBLIC_VAPID_KEY,
    });

    await fetch('/api/push/subscribe', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(subscription.toJSON()),
    });
}
```

Your Suprnova endpoint receives the JSON, validates the shape, and
stores it on the user - the string is opaque to your server, but it
must be the exact JSON the browser produced (the
`SubscriptionInfo` type uses `Deserialize` to parse it later):

```rust
use suprnova::{Auth, Request, Response, SubscriptionInfo, attrs, json_response};

pub async fn subscribe(req: Request) -> Response {
    let user_id = Auth::id().expect("auth middleware");

    let (_parts, bytes) = match req.body_bytes().await {
        Ok(b) => b,
        Err(e) => return json_response!({ "error": e.to_string() }).map(|r| r.status(400)),
    };
    let raw = match std::str::from_utf8(&bytes) {
        Ok(s) => s.to_string(),
        Err(_) => return json_response!({ "error": "body not utf-8" }).map(|r| r.status(400)),
    };

    // Parse to validate the shape - endpoint, keys.p256dh, keys.auth.
    // If parsing fails, the browser handed us something malformed.
    let sub: SubscriptionInfo = match serde_json::from_str(&raw) {
        Ok(s) => s,
        Err(e) => return json_response!({ "error": e.to_string() }).map(|r| r.status(400)),
    };

    // Persist `raw` verbatim - that's the exact string WebPushChannel
    // will hand to serde_json::from_str on dispatch.
    User::query()
        .db_where_op("id", "=", user_id)
        .update_all(attrs! { push_subscription_json: raw })
        .await
        .unwrap();

    json_response!({ "ok": true, "endpoint": sub.endpoint })
}
```

The Service Worker decrypts the push payload and renders the
notification:

```js
// /sw.js
self.addEventListener('push', (event) => {
    const data = event.data.json();
    event.waitUntil(
        self.registration.showNotification(data.title, {
            body: data.body,
            data: { url: data.url },
        }),
    );
});

self.addEventListener('notificationclick', (event) => {
    event.notification.close();
    event.waitUntil(clients.openWindow(event.notification.data.url));
});
```

## Payload limits

The Web Push spec caps each encrypted payload at 4096 bytes total.
Suprnova rejects plaintexts larger than 3992 bytes (the cap minus the
~85-byte AES128GCM encryption overhead) at encrypt time so the
failure surfaces in your code, not in a 413 from the push service.
A `Notification` whose serialized `data()` exceeds that limit
fails in the channel's `deliver`: the client returns
`WebPushError::Encryption`, and the channel reports it as an internal
error.

For anything larger - a long message body, a thumbnail - send a short
notification carrying a URL the Service Worker fetches on click. That's
both faster (no encryption on a multi-KB payload) and more flexible
(the fetch can return whatever shape you want).

## Dead subscriptions

When the push service returns 404 or 410, the subscription is dead -
the user uninstalled the browser, revoked the permission, or cleared
storage. `WebPushChannel` treats this as a non-fatal warn:

```text
WARN webpush subscription gone (404/410); caller should remove
     channel=webpush host=fcm.googleapis.com endpoint_sha256=4e9bdab8bbe7189c
```

Dispatch returns `Ok(())` because the notification reached a terminal
state - there's no recipient to retry against. Your application is
expected to act on the warn and remove the subscription row. Suprnova
ships the warn; it does not auto-prune the subscriptions table for you.

The warning has no `endpoint` field. The path of an endpoint is the token
that reaches the browser, so the log keeps it out. `host` is the host of
the endpoint, and `endpoint_sha256` is the first 16 hexadecimal digits of
the SHA-256 of the endpoint as you stored it. To find the row, compute
the same digest of each stored endpoint and compare:

```rust
use sha2::{Digest, Sha256};

fn endpoint_digest(endpoint: &str) -> String {
    hex::encode(&Sha256::digest(endpoint.as_bytes())[..8])
}
```

### Subscriptions that cannot be used

A stored subscription can be unusable before any request leaves your
server. The client then returns `WebPushError::InvalidSubscription`, and
nothing is sent. The text of the error names the rule that refused the
subscription. Two groups of checks raise it:

- The endpoint. It is no URL, or the `Strict` endpoint policy refuses it
  because it is not `https`, has no host, names an IP address in place of a
  host, or names a host that is no push service (`localhost`, a cloud
  metadata host, or a reserved name such as `.local` or `.internal`).
  When its host name resolves to an address the policy refuses, the error
  is `WebPushError::RefusedDestination`, which carries the class of the
  address in place of a text. When the allowlist does not name its origin,
  the error is `WebPushError::OriginNotAllowed`, which carries the origin.
- The keys. `p256dh` is no base64url, does not decode to 65 bytes, is not
  in uncompressed form or is no point of the P-256 curve. `auth` is no
  base64url or does not decode to 16 bytes.

The stored data is wrong, so a retry cannot help. `is_retryable()` returns
`false`. `WebPushChannel` handles these errors as it handles a gone
subscription: it logs a warning and dispatch returns `Ok(())`, so a queue
does not send the job again. For a refused address, the reason is the
class, such as `its host name resolves to a private address`. For an origin
outside the allowlist, it is the origin, such as
`its origin https://push.example.net is not in the endpoint allowlist`.
When that origin belongs to a push service your users subscribe through,
add it to `WEB_PUSH_ENDPOINT_ORIGINS` instead of removing the
subscription.

```text
WARN webpush subscription cannot be used; caller should remove
     channel=webpush host=10.0.0.7 endpoint_sha256=533bb6dc756981d0 reason=subscription endpoint host '10.0.0.7' is an IP literal; real push services use named hosts
```

The warning carries the reason, the host and the digest of the endpoint,
as the warning for a gone subscription does, and no `endpoint` field.

A stored route that is no subscription at all gets the same warning:
text that is no JSON, or JSON without an `endpoint` or without `keys`. The
reason is the kind of the mistake and its position, such as
`the value is not JSON (line 1, column 1)`. It never quotes the route,
which holds the secret of the subscription. This warning has no host and
no digest, because the route has no endpoint to take them from.

Your application removes the subscription row, as it does for a gone
subscription. Dispatch succeeds, so no `NotificationFailed` event fires;
you learn of it from the log. When you call `WebPushClient::send`
yourself, match on `WebPushError::InvalidSubscription`:

```rust
match client.send(&sub, payload, ContentEncoding::Aes128Gcm, 60).await {
    Ok(_) => (),
    Err(
        WebPushError::SubscriptionGone
        | WebPushError::InvalidSubscription(_)
        | WebPushError::RefusedDestination(_)
        | WebPushError::OriginNotAllowed(_),
    ) => {
        // remove the subscription
    }
    Err(e) => return Err(e.into()),
}
```

## Retries and Retry-After

When the push service returns a transient 5xx, 408, or 429, the
underlying `WebPushError::PushServiceRejected` carries the parsed
`Retry-After` hint (delta-seconds form only - HTTP-date form returns
`None`):

```rust
use suprnova::WebPushError;

match client.send(&sub, payload, ContentEncoding::Aes128Gcm, 60).await {
    Ok(_) => (),
    Err(e) if e.is_retryable() => {
        let wait = e.retry_after().unwrap_or(Duration::from_secs(30));
        tokio::time::sleep(wait).await;
        // ...try again, or push back onto the queue with a delay
    }
    Err(WebPushError::SubscriptionGone) => {
        // remove the subscription
    }
    Err(e) => return Err(e.into()),
}
```

The `Retry-After` hint is capped at 24 hours so a hostile server
can't park a worker on a multi-year sleep.

`PushServiceRejected` carries the status and the hint, and no part of the
body the push service sent. The body is remote data, and an error is what
your code logs, stores and shows. The client reads the first 200 bytes of
the body and writes them to its `debug` log, with control characters
escaped, and `WebPushChannel` fails the delivery with an error that names
the status alone, such as
`WebPushChannel: push service rejected (status 500)`.

When you use `Notify::queue`, the queue retries the job for you. A
`PushServiceRejected` that carries a `Retry-After` hint leaves
`WebPushChannel::deliver` as a `FrameworkError::RateLimited` with that
hint. The worker then retries the job after the hinted time instead of the
delay from the job's backoff schedule. A job that the push service refused
with `429` goes back when the service said it would take it, not earlier and
not later. The worker caps the wait at 24 hours
(`queue::retry::RETRY_HINT_CEILING`).

The attempt still counts against `Notification::max_tries`, and the job
dead-letters when the attempts run out. Every other failure, including a
rejection that carries no `Retry-After` hint, keeps the delay from
`Notification::backoff`.

## Telemetry

The notifications dispatcher wraps the fan-out in a
`notification.dispatch` info span tagged with the notification name
and channel count. Each successful delivery emits a
`NotificationSent` event; failures emit `NotificationFailed` carrying
the channel name, route, and error string. Wire any of those into
your metrics/log pipeline the same way you wire other framework
events - see [Events](events.md).

A dead subscription emits a structured WARN with `channel="webpush"`,
the host and the digest of the endpoint, and the notification name. A
subscription that cannot be used emits a WARN with the same fields and
the reason. Neither has the endpoint. That's the signal to scrape for an
automated subscription cleanup job.

### Why Suprnova diverges

Laravel's `WebPush` driver is a community package
(`laravel-notification-channels/webpush`) - not in core, separately
versioned, opinionated about ORM. Suprnova bakes Web Push into the
framework because the protocol is well-defined and the encrypted
HTTP POST is too small a contract to wrap in a third-party
abstraction. The notifications subsystem keeps the surface uniform:
the same `Notification` you send to mail or database also lands as a
push, no driver matrix, no separate config tree.

We also surface the strict-endpoint policy by default. The Laravel
community package leaves SSRF protection to the application; we
take the position that "the endpoint came from user data" is the
shape of every Web Push subscription, and the safe default belongs
in the framework, not in your code.

The retry classification (`is_retryable`, `retry_after`) is exposed
as typed methods on `WebPushError` rather than as a magic constant
table in the queue layer. The queue still owns retry policy - the
error tells you whether a retry could succeed and how long to wait;
the queue decides whether and when to dequeue again. Separating the
two means your custom retry strategies (exponential backoff,
jittered, capped) don't have to special-case Web Push.

## Testing

Stand up a `wiremock` server, point a `WebPushClient` at it with
`EndpointPolicy::AllowAny`, and assert on the requests it receives:

```rust
use std::sync::Arc;
use suprnova::{
    EndpointPolicy, NotificationDispatcher, Notify, VapidKey, VapidSigner,
    WebPushChannel, WebPushClient,
    notifications::set_dispatcher,
};
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, ResponseTemplate};

#[tokio::test]
async fn order_shipped_pushes() {
    let server = MockServer::start().await;
    Mock::given(method("POST"))
        .and(path("/push"))
        .respond_with(ResponseTemplate::new(201))
        .mount(&server)
        .await;

    let signer = VapidSigner::new(VapidKey::generate());
    let client = Arc::new(
        WebPushClient::new(signer, "mailto:test@example.org")
            .unwrap()
            .with_endpoint_policy(EndpointPolicy::AllowAny),
    );
    let channel = Arc::new(WebPushChannel::new(client, 60).unwrap());

    let dispatcher = NotificationDispatcher::new().register_channel(channel);
    set_dispatcher(Arc::new(dispatcher)).unwrap();

    let user = test_user_with_subscription(&server.uri()).await;
    Notify::send(&user, &OrderShipped {
        order_id: 1,
        tracking_url: "https://ship.example.org/o/1".into(),
    }).await.unwrap();
    // server.received_requests() now contains the encrypted POST.
}
```

Leave `WEB_PUSH_ENDPOINT_ORIGINS` unset in a test that uses `AllowAny`.
When it names origins, the channel sends under the allowlist, which
refuses the mock server's `http` address.

For end-to-end tests that don't care about the encrypted bytes,
`Notify::fake()` (covered in [Notifications](notifications.md))
captures the dispatch without running the channel - faster, no
mock server, no encryption round-trip.

## Reference

- Primitives: `suprnova::VapidKey`, `suprnova::VapidSigner`,
  `suprnova::VapidClaims`
- Client: `suprnova::WebPushClient`, `suprnova::EndpointPolicy`,
  `suprnova::EndpointAllowlist`, `suprnova::PushResponse`,
  `suprnova::SubscriptionInfo`
- Error: `suprnova::WebPushError` - `.is_retryable()`, `.retry_after()`,
  `WebPushError::SubscriptionGone`, `WebPushError::InvalidSubscription`,
  `WebPushError::RefusedDestination`, `WebPushError::OriginNotAllowed`,
  `WebPushError::Lookup`, `WebPushError::PushServiceRejected`;
  `suprnova::InvalidAllowlist` for an origin list that does not parse
- Environment: `WEB_PUSH_ENDPOINT_ORIGINS` (see
  [Environment Variables](env-vars.md#web-push))
- Refused address classes: `suprnova::AddressClass`
- Encoding: `suprnova::ContentEncoding` (Aes128Gcm; 3992-byte plaintext cap)
- Channel: `suprnova::WebPushChannel`
- Facade: `suprnova::Notify`
- Queue job: `suprnova::SendNotificationJob`
- Factory registration:
  `suprnova::notifications::register_notification_factory`

## Next

- [Notifications](notifications.md) - the multi-channel dispatcher that
  `WebPushChannel` plugs into
- [Mail](mail.md) - the email-channel counterpart for users without push
- [Broadcasting](broadcasting.md) - real-time delivery for users who are
  on the site
- [Queues](queues.md) - how `Notify::queue` backs `SendNotificationJob`
- [Events](events.md) - listening for `NotificationSent` /
  `NotificationFailed` to watch deliveries


---

<!-- /docs/strings -->

# Strings

`Str` holds the string helpers worth carrying over from Laravel: slugs,
masks, limits, excerpts, plural and singular forms, and Markdown.
`Str::of` wraps a value in a `Stringable` that chains them. For case
conversions, use the `heck` crate; for everything else, `std::str` and
`regex`. Every count here is in characters, never bytes, so a multibyte
value is never cut inside a character.

```rust
use suprnova::Str;

let slug = Str::slug("Œuvre d'art @home", "-");          // oeuvre-dart-at-home
let card = Str::mask("4111 1111 1111 1234", '*', 0, Some(-4)); // ***************1234
let teaser = Str::limit("The quick brown fox jumps", 15, "..."); // The quick brown...
let label = Str::plural("comment", 2);                  // comments
```

## Slugs

`Str::slug(title, separator)` spells the title in ASCII, lower-cases it,
writes `@` as `at`, and joins each run of other characters between
letters and digits with the separator:

```rust
use suprnova::Str;

assert_eq!(Str::slug("Laravel 5 Framework", "-"), "laravel-5-framework");
assert_eq!(Str::slug("Ünïcödé Straße", "-"), "unicode-strasse");
assert_eq!(Str::slug("Привет мир", "-"), "privet-mir");
assert_eq!(Str::slug("foo bar", "_"), "foo_bar");
assert_eq!(Str::slug_in("Ärger", "-", "de"), "aerger");
```

The ASCII spelling is Laravel's own: the replacement map of
voku/portable-ascii, the package Laravel's `Str::ascii` uses, so a title
gets the slug it gets in Laravel. That map spells Latin, Greek, Cyrillic,
Arabic, and many other scripts, and drops what it can't spell, such as
Han characters and emoji: `Str::slug("北京 city", "-")` is `city`.
You choose the language's spelling with
`Str::slug_in(title, separator, language)`. With German, you get `ae` for
`ä`; with Esperanto, you get `cx` for `ĉ`. You pass an empty language to
keep Unicode letters instead of transliterating them.

## Masks

`Str::mask(value, character, index, length)` replaces the characters from
`index` with `character`: `length` of them, or all to the end with `None`.
A negative index counts from the end, and a negative length stops that
many short of the end:

```rust
use suprnova::Str;

assert_eq!(Str::mask("taylor@example.com", '*', 3, None), "tay***************");
assert_eq!(Str::mask("taylor@example.com", '*', -15, Some(3)), "tay***@example.com");
```

## Limits and excerpts

`Str::limit(value, limit, end)` keeps the first `limit` characters and
adds `end` when it cut. `Str::limit_words` cuts at the last space within
the limit instead, so no word is broken:

```rust
use suprnova::Str;

assert_eq!(Str::limit("The quick brown fox", 12, "..."), "The quick br...");
assert_eq!(Str::limit_words("The quick brown fox", 12, "..."), "The quick...");
```

You keep the first `words` space-separated runs with
`Str::words(value, words, end)` and add `end` when you cut. You count
markup as part of a word and keep whitespace between words. You pass a
zero word limit to leave the value as it is:

```rust
use suprnova::Str;

assert_eq!(
    Str::words("Perfectly balanced, as all things should be.", 3, " >>>"),
    "Perfectly balanced, as >>>"
);
assert_eq!(Str::words("<b>bold</b> text here", 2, "..."), "<b>bold</b> text...");
```

`Str::excerpt(text, phrase, radius, omission)` frames the first match of
a phrase, ignoring case, with up to `radius` characters on each side,
in text of any number of lines. It returns `None` when the phrase is not
there. You trim Laravel's invisible characters, including zero-width
spaces, from the ends you cut:

```rust
use suprnova::Str;

assert_eq!(
    Str::excerpt("This is my name", "my", 3, "...").as_deref(),
    Some("...is my na...")
);
```

## Plural and singular

`Str::plural(word, count)` and `Str::singular(word)` inflect by the rules
of the current locale's language, the ones Laravel's `Pluralizer` uses
from doctrine/inflector 2.1.0, the release Laravel 13 installs: English,
Esperanto, French, Italian, Norwegian Bokmål, Portuguese, Spanish, and
Turkish. Any other language uses the English rules. A count of 1 or -1
leaves the word as it is, and the result keeps the word's case:

```rust
use suprnova::Str;

assert_eq!(Str::plural("child", 2), "children");
assert_eq!(Str::plural("Person", 3), "People");
assert_eq!(Str::plural("comment", 1), "comment");
assert_eq!(Str::singular("people"), "person");
assert_eq!(Str::plural_studly("VerifiedHuman", 2), "VerifiedHumans");
assert_eq!(Str::plural_pascal("VerifiedHuman", 2), "VerifiedHumans");
assert_eq!(Str::plural_with_count("car", 3), "3 cars");
```

In a request whose locale is `fr`, `Str::plural("cheval", 2)` is
`chevaux`; in `es`, `Str::plural("ciudad", 2)` is `ciudades`. Without the
`localization` feature, the rules are English.

You inflect the last word of the value with `Str::plural_studly` or
`Str::plural_pascal`. You put the count before the inflected word with
`Str::plural_with_count(word, count)`, using the current locale's integer
format. You keep all digits even for the largest and smallest `i64`
values. Without `localization`, you get plain decimal digits.

You vary a page that [RenderCache](render-cache.md) stores by its locale
when you call these inflection helpers: add
`.vary(VarianceDimension::Locale)` to the route's policy. Without it,
RenderCache declines to store the page.

To choose the form a reader sees in a translated message, use the plural
categories of a Fluent message instead; see
[Localization](localization.md). `Str::plural` is for words in your own
code, such as a table or a label built from a model's name. The starter
kits render plain English and ship no translation catalogs; localization
is available when your application needs it.

## Markdown

`Str::markdown(value, &renderer)` renders a whole Markdown document to
HTML, and `Str::inline_markdown(value, &renderer)` renders the inline
syntax only: emphasis, code, links and line breaks, with no paragraph
around it and block markers such as `#`, `>` or `-` kept as text. You
pass the `MarkdownRenderer` (from `suprnova::content`) that decides what
raw HTML and links may do:

```rust
use suprnova::Str;
use suprnova::content::MarkdownRenderer;

let renderer = MarkdownRenderer::default();
let title = Str::inline_markdown("**Laravel** _rocks_", &renderer)?;
assert_eq!(title, "<strong>Laravel</strong> <em>rocks</em>");
assert_eq!(Str::inline_markdown("# Title", &renderer)?, "# Title");
let page = Str::markdown("# Laravel\n\nA *framework*.", &renderer)?;
assert!(page.contains("<p>A <em>framework</em>.</p>"));
# Ok::<(), suprnova::content::ContentError>(())
```

The default renderer drops raw HTML and sanitizes its output, so
`<script>` never reaches the page. You choose otherwise with the
renderer's builder calls, which hold Laravel's CommonMark options:

```rust
use suprnova::Str;
use suprnova::content::{HtmlInput, MarkdownRenderer};

let renderer = MarkdownRenderer::default()
    .html_input(HtmlInput::Strip)
    .allow_unsafe_links(false)
    .autolink(true);
let html = Str::inline_markdown("Inject: <script>alert(\"XSS\");</script>", &renderer)?;
assert_eq!(html, "Inject: alert(&quot;XSS&quot;);");
# Ok::<(), suprnova::content::ContentError>(())
```

- `html_input(HtmlInput::Sanitize)` keeps raw HTML and passes the output
  through the sanitizer, which keeps safe tags such as `<b>` and removes
  scripts, event handlers and unsafe URLs. `HtmlInput::Strip` removes raw
  HTML tags and keeps the text between them. `HtmlInput::Escape` shows raw
  HTML as text. `HtmlInput::Allow` passes it through: use it only for
  Markdown you trust.
- `allow_unsafe_links(true)` lets a Markdown link point at a
  `javascript:`, `vbscript:`, `file:` or `data:` URL. The sanitizer still
  removes such URLs, so it takes effect with `Strip`, `Escape` or `Allow`.
- `autolink(true)` turns bare URLs and email addresses into links.

A renderer that calls none of them renders as it always has: sanitized,
unless `MarkdownOptions::unsafe_html` is on.

## Fluent strings

`Str::of(value)` returns a `Stringable`, whose methods are the `Str`
helpers, so you chain them as Laravel's `Str::of($value)->...` chains:

```rust
use suprnova::Str;

let slug = Str::of("Blog Post").limit(4, "").slug("-");
assert_eq!(slug.to_string(), "blog");
let label: String = Str::of("comment").plural(3).into();
assert_eq!(label, "comments");
```

A `Stringable` converts from and into `String`, compares with `&str`, and
displays as its value. Next to the `Str` helpers it has `markdown`,
`inline_markdown`, and encryption through [`Crypt`](encryption.md):
`encrypt(purpose)`, `encrypt_for(purpose, context)`, `decrypt(purpose)`
and `decrypt_for(purpose, context)`. Every encryption names a
`CryptPurpose`, and a value sealed for one purpose does not open under
another:

```rust
use suprnova::{CryptPurpose, Str};

let sealed = Str::of("ssn-123").encrypt(CryptPurpose::Cast)?;
let opened = sealed.clone().decrypt(CryptPurpose::Cast)?;
assert_eq!(opened, "ssn-123");
assert!(sealed.decrypt(CryptPurpose::Cursor).is_err());
# Ok::<(), suprnova::FrameworkError>(())
```

`CryptPurpose::Cookie` is refused by `encrypt` and `decrypt`: a cookie
value is bound to its cookie's name, so you encrypt it with
`encrypt_for(CryptPurpose::Cookie, name)`.

### Why Suprnova diverges

- **The language follows the locale.** Laravel sets the plural language
  for the whole process with `Pluralizer::useLanguage`; here the current
  request's locale chooses it, for `Str::singular` as for `Str::plural`.
- **An excerpt can span lines.** Laravel's pattern stops at a line break,
  so `Str::excerpt` returns `null` for text with a line break inside it;
  here it finds the phrase on any line.
- **Counts are characters.** Laravel's `limit` counts display width, two
  for a wide East Asian character, and its word-preserving form also
  strips HTML tags.
- **A subset.** `Stringable` chains the helpers `Str` keeps, not every
  method of Laravel's `Stringable`; case conversions come from `heck`.
- **Markdown is sanitized by default.** Laravel's `Str::markdown` lets raw
  HTML through unless you pass `html_input`; here the default renderer
  drops it and sanitizes the output, and you opt into raw HTML with
  `HtmlInput::Allow`. The inline form keeps each line break of the text.
- **Every encryption names a purpose.** Laravel's `Stringable::encrypt`
  takes none; here `encrypt` takes a `CryptPurpose`, so a value encrypted
  for one use cannot be decrypted as another.

## Next

- [Localization](localization.md) - percentages, abbreviated numbers, and
  the rest of the locale-aware formatting
- [Dates](dates.md) - reading a date or a time from text
- [Validation](validation.md) - rules for the strings your users send


---

<!-- /docs/dates -->

# Dates

`Date` reads a date or a time from text: an exact form such as
`2026-10-09 09:30`, or a relative one such as `tomorrow`, `+2 days` or
`next monday`. It answers a `chrono::DateTime`, so you compare, format and
store the result with chrono, and the relative forms read the clock the
framework reads, so a test that freezes the clock freezes them too.

```rust
use suprnova::Date;

let due = Date::parse("tomorrow 09:30")?;       // DateTime<Utc>
let expires = Date::parse("+2 weeks")?;
let launch = Date::parse("2026-11-01T12:00:00+02:00")?;
assert!(Date::parse("soonish").is_err());
# Ok::<(), suprnova::DateParseError>(())
```

## The forms it reads

`Date::parse(text)` reads these forms, ignoring case and extra spaces,
and answers a time in UTC:

| Form | Example | Answers |
|---|---|---|
| RFC 3339 | `2026-10-09T12:00:00+02:00` | That moment |
| A date | `2026-10-09` | That day at midnight |
| A date and a time, with a space or `T` | `2026-10-09 09:30`, `2026-10-09T09:30:15.250` | That time |
| Unix seconds | `@1791547200` | That moment |
| A word | `now`, `today`, `tomorrow`, `yesterday`, `midnight`, `noon` | See below |
| A count of units from now | `+2 days`, `-30 minutes`, `5 hours`, `3 weeks ago` | See below |
| A weekday | `monday`, `next friday`, `last sunday` | That day at midnight |
| The first or last day of a month | `first day of next month`, `last day of this month` | That day, at the current time |
| A word form and a time | `tomorrow 09:30`, `next monday 08:00`, `last day of this month 23:59` | That day at that time |

The units are `second`, `minute`, `hour`, `day`, `week`, `fortnight`,
`month` and `year`, singular or plural. `N <unit> ago` counts back.

The time of day follows PHP's relative formats, which Laravel's `Date`
reads through Carbon:

- `today`, `tomorrow`, `yesterday` and `midnight` are at midnight, and
  `noon` at 12:00.
- A weekday is at midnight. A weekday alone is today when today is that
  day; `next` is strictly after today and `last` strictly before.
- `now`, a count of units and the first or last day of a month keep the
  current time of day.
- A time after a word form, `HH:MM`, sets the time.

Days, weeks, fortnights, months and years move the calendar date and keep
the wall-clock time; seconds, minutes and hours move the moment. A month
that has no such day overflows into the next month, as PHP's does: one
month after January 31 is March 3 in a common year.

Text it does not read is an error, a `DateParseError` that names the
text:

```rust
use suprnova::Date;

let error = Date::parse("in a fortnight-ish").unwrap_err();
assert_eq!(error.text(), "in a fortnight-ish");
```

`DateParseError` converts into `FrameworkError`, so a handler can use `?`.

## Time zones

`Date::parse_in(text, tz)` reads the same forms in a time zone and
answers a `DateTime<Tz>`. A date, a time without an offset and every
relative form are taken in that zone, so `tomorrow` is the next midnight
in Paris:

```rust
use suprnova::{Date, Tz};

let paris: Tz = "Europe/Paris".parse().expect("a known zone");
let tomorrow = Date::parse_in("tomorrow", paris)?;
let meeting = Date::parse_in("2026-10-09 09:30", paris)?; // 07:30 UTC
# Ok::<(), suprnova::DateParseError>(())
```

A local time that a daylight-saving change skips moves forward by the
length of the skip, as PHP's does: `2026-03-29 02:30` in Paris is 03:30.
A local time that a change repeats is the earlier of the two.

`Date::raw_parse(text)` is the same as `Date::parse`. Laravel's `rawParse`
skips the hook Carbon runs on every parse, and Suprnova has no such hook.

## Testing with a frozen clock

Every relative form reads `suprnova::clock::now()`, so freeze the clock
with `TestClock` to test code that parses relative dates:

```rust
use chrono::{DateTime, Utc};
use suprnova::Date;
use suprnova::testing::TestClock;

#[test]
fn a_reminder_is_due_tomorrow_morning() {
    let friday_noon: DateTime<Utc> = "2026-10-09T12:00:00Z".parse().unwrap();
    let _clock = TestClock::travel_to(friday_noon);

    let due = Date::parse("tomorrow 09:30").unwrap();
    assert_eq!(due.to_rfc3339(), "2026-10-10T09:30:00+00:00");
}
```

See [Testing](testing.md) for `TestClock`.

### Why Suprnova diverges

- **A named set of forms.** Carbon reads PHP's whole relative-format
  grammar, including forms such as `third friday of next month` or
  `+1 week 2 days`. `Date::parse` reads the forms listed above and refuses
  the rest, because a form read differently from PHP would be worse than
  a form refused. Combine forms with chrono's arithmetic instead.
- **Only English weekday names, spelled in full.** PHP also reads
  abbreviations such as `mon`.
- **A time follows a word form only.** PHP reads `+2 days 09:30`; here a
  count of units takes no time after it.
- **It answers chrono types.** Laravel answers a mutable Carbon instance;
  here you get a `DateTime<Utc>` or `DateTime<Tz>` value.

## Next

- [Strings](strings.md) - the other text helpers
- [Localization](localization.md) - formatting a date for a reader's
  locale
- [Testing](testing.md) - `TestClock` and the other test helpers


---

<!-- /docs/queues -->

# Queue

The `Queue` facade dispatches background work to a driver and lets a separate
worker process drain it: HTTP handlers return fast, the heavy lifting runs
behind the scenes. Reach for it whenever a request would otherwise block on
something that can be done later - sending mail, hitting a webhook, generating
a report. Pair with [`Bus`](bus.md) when you want the work to run *now* in the
current task and return a typed result; pair with [`Events`](events.md) when
you want one signal to fan out to many listeners.

## Quick start

Define a job, register it once at boot, push it:

```rust
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use suprnova::{error::FrameworkError, queue::{Job, Queue}};

#[derive(Serialize, Deserialize)]
struct SendWelcomeEmail { user_id: i64 }

#[async_trait]
impl Job for SendWelcomeEmail {
    fn job_name() -> &'static str { "SendWelcomeEmail" }

    async fn handle(self) -> Result<(), FrameworkError> {
        // … actually send the mail
        Ok(())
    }
}

// Boot once (the worker process and the dispatch process both need this).
Queue::set_driver(std::sync::Arc::new(suprnova::queue::MemoryQueueDriver::new()));
suprnova::queue::worker::register_job::<SendWelcomeEmail>();

// Push from a handler:
Queue::push(SendWelcomeEmail { user_id: 42 }).await?;
```

Register the jobs you write. The framework's own jobs - `SendMailJob` behind `Mail::queue` and `SendNotificationJob` behind `Notify::queue` - are registered before your code runs.

A worker process drains the configured driver until cancelled:

```rust
use std::sync::Arc;
use std::time::Duration;
use tokio_util::sync::CancellationToken;
use suprnova::queue::{Queue, worker::{WorkerConfig, run_worker}};

let driver = Queue::driver()?;
let cfg = WorkerConfig {
    visibility_timeout: Duration::from_secs(60),
    poll_interval: Duration::from_millis(100),
    max_jobs: None,
    queues: Vec::new(),
};
let shutdown = CancellationToken::new();
run_worker(driver, cfg, shutdown).await?;
```

`run_worker` returns a `Result`. Before its first pop, a worker whose
failed-jobs store is the database store checks `failed_jobs` and returns an
error naming the table and the column when the table is missing, lacks a
column the store writes, is in the layout an earlier release created, or on
MySQL holds `payload` or `exception` narrower than `LONGTEXT`. `queue:work`
exits non-zero with that error. A worker that started anyway would fail to
record its first failed job, and retry it without end.

In a scaffolded app, the worker is started by the binary's `queue:work`
subcommand - `cargo run -- queue:work` - which runs the same bootstrap your
HTTP server does, so observers and listeners registered in `bootstrap()`
fire identically for inserts from a queue handler. `queue:work --connection
<name>` drains a named connection instead of the default one - see
[Connections](#connections).

## Drivers

Seven drivers ship in-tree. Configure via `QUEUE_DRIVER` env or by calling
`Queue::set_driver(...)` programmatically.

| Driver | Use for | Strengths |
| --- | --- | --- |
| `MemoryQueueDriver` | tests, single-process apps | `tokio::time::DelayQueue` for `available_at`, virtual-clock compatible |
| `RedisQueueDriver` | production fan-out | consumer groups + `XAUTOCLAIM` + ZSET-backed delayed jobs |
| `DatabaseQueueDriver` | single-DB apps | `FOR UPDATE SKIP LOCKED` on Postgres/MySQL, `BEGIN`-serialised on SQLite |
| `SqsQueueDriver` | production on AWS | a managed queue outside your database and Redis; see [Amazon SQS](#amazon-sqs) |
| `MongoQueueDriver` | apps on MongoDB | one atomic `findOneAndUpdate` per reservation; brings its failed-job store and batch repository; see [MongoDB](#mongodb) |
| `SyncQueueDriver` | dev, CI | runs the handler inline on `push`, no worker |
| `NullQueueDriver` | testing wrappers | drops every push without running |

`suprnova::queue::bootstrap_from_env()` reads `QUEUE_DRIVER` and wires the matching
driver; `suprnova::queue::bootstrap_default()` always wires the memory driver. The
server boot path calls one of these for you - most apps only configure via
env.

A driver you install with `Queue::set_driver` in your `bootstrap` wins. The
server and the worker commands boot the queue after your `bootstrap`, keep
that driver, and don't read `QUEUE_DRIVER`. They still register the
connections `QUEUE_CONNECTIONS` lists beside it. A driver that an earlier
`bootstrap_from_env` call installed is replaced when you call it again, so
a process picks up a changed `QUEUE_DRIVER`. In a test that boots the queue
from the environment, call `suprnova::queue::testing::forget_driver()`
first to empty the slot a driver from an earlier test may hold.

`QUEUE_DRIVER` accepts `memory`, `sync`, `null`, `redis`, `database`, `sqs`,
`failover` and `mongodb`, and defaults to `memory`. `sync` selects `SyncQueueDriver` and
`null` selects `NullQueueDriver`. A value that names no driver is a boot
error when `APP_ENV` is `production`, because an in-memory queue chosen by
mistake loses every job at the next restart. In any other environment the
boot logs a warning that lists the accepted names and uses the memory
driver.

`FailoverQueueDriver` isn't an eighth backend. It wraps an ordered list of
the drivers above so a push one connection refuses falls through to the
next. See [Failover connections](#failover-connections).

### Environment configuration

```bash
QUEUE_DRIVER=redis
QUEUE_REDIS_URL=redis://127.0.0.1:6379
QUEUE_REDIS_STREAM=suprnova-queue
QUEUE_REDIS_GROUP=default
QUEUE_REDIS_CONSUMER=consumer-1
QUEUE_VISIBILITY_TIMEOUT_SECS=60

# Database driver - DB::init() must run first
QUEUE_DRIVER=database
QUEUE_DB_TABLE=jobs

# MongoDB driver - needs the database-mongodb feature and MONGODB_URI
QUEUE_DRIVER=mongodb
```

The database driver validates `QUEUE_DB_TABLE` as a SQL identifier at
construction, so a malformed env value fails boot rather than reaching SQL
composition. The driver and the failed-job store quote their table names
as the shipped migrations do, so a capitalized name or a reserved word
works. A schema-qualified name, such as `queues.jobs`, works on every
engine; the shipped migrations create such a table on Postgres only. Redis uses Streams consumer groups directly (`XREADGROUP`
for new work, `XAUTOCLAIM` to reclaim unacknowledged entries, Redis 6.2 or
newer). The visibility timeout is the `XAUTOCLAIM` idle threshold, set once
per connection, so the per-pop `visibility_timeout` argument is ignored on
Redis (a documented divergence from the trait contract imposed by Redis
Streams).

### Amazon SQS

`QUEUE_DRIVER=sqs` queues jobs on Amazon SQS standard queues. It reads the
variables Laravel's `sqs` connection reads:

```bash
QUEUE_DRIVER=sqs
SQS_PREFIX=https://sqs.us-east-1.amazonaws.com/123456789012
SQS_QUEUE=default          # the queue a job that names none goes to
SQS_SUFFIX=-production     # optional, appended to every queue name
AWS_DEFAULT_REGION=us-east-1
AWS_ACCESS_KEY_ID=...      # optional, see below
AWS_SECRET_ACCESS_KEY=...
```

A job goes to the queue it names, with `Job::queue` or a route, at
`SQS_PREFIX/emails-production` for `emails`, and to `SQS_QUEUE` when it
names none. A
queue name that is already a URL is used as it is, so `SQS_QUEUE` can be the
full URL of the queue and `SQS_PREFIX` left unset. `SQS_ENDPOINT` points the
driver at another endpoint: a service that is not AWS, such as LocalStack or
ElasticMQ, or a VPC endpoint. Without it the driver uses the SQS endpoint of
the region, in the China partition (`amazonaws.com.cn`) for a `cn-` region.

With `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` set (and
`AWS_SESSION_TOKEN` for temporary keys), the driver signs with them.
Without them it uses the default credential chain of AWS: the shared
profile, web identity, the ECS task role and the EC2 instance role.

The server does not boot when no region is set, when the queue is not a URL
and `SQS_PREFIX` is not set.

You can use standard and FIFO queues. For a queue ending in `.fifo`, you
set `Job::message_group()` and `Job::deduplication_id()` on each job.
Without them, you get the group `default` and a SHA-256 digest of the job
payload as its deduplication ID. FIFO sends omit `DelaySeconds`; the
worker preserves the job's scheduled time when it receives it early.

How the driver maps onto SQS:

- **A worker receives from the queues `--queue` names**, in order, and from
  `SQS_QUEUE` when it names none. SQS has no receive across queues, so a
  job sent to `emails` waits for a worker started with `--queue=emails`. A
  name there is an SQS queue name, as in Laravel: `--queue=default` receives
  from `SQS_PREFIX/default`, which holds the unrouted jobs only when
  `SQS_QUEUE` is `default`. Name `SQS_QUEUE` itself to drain them.
- **A receive waits up to `SQS_WAIT_TIME_SECONDS` for a message** (default
  1, at most 20). The wait keeps an idle worker to about one request a
  second for each queue it names, where SQS bills each request, and it makes
  SQS answer from all of its servers, so an empty answer means an empty
  queue. Setting it to `0` sends short polls, about ten a second.
- **The visibility timeout is the worker's.** A reservation that expires
  makes the job visible again, and its next delivery counts one more
  attempt.
- **A `nack` counts an attempt and a release does not**, as on the other
  drivers. A `nack` whose delay is longer than SQS can still hide the
  message, 12 hours from its receive, sends a copy that counts the attempt. The attempt count is the one in the job plus the receives SQS
  counted before this one (`ApproximateReceiveCount`), so a release sends a
  fresh copy that keeps the count and deletes the original.
- **Delays longer than 15 minutes hold.** SQS delays one message by 15
  minutes at most, so a job due later is sent on with what is left when it
  arrives early. Waiting out the delay is not an attempt.
- **`Queue::size` and its siblings** report the approximate counts SQS
  keeps for the queue you pass as `Some("reports")`, and `clear` purges
  that queue. You pass `None` to use `SQS_QUEUE`. SQS cannot list messages
  without receiving them, so `pending_jobs`, `delayed_jobs` and
  `reserved_jobs` return an error.

A release, a long `nack` and a delay sent on are each a send followed by a
delete, because SQS cannot change a message. If the delete fails after the
send, the job is on the queue twice until the original's visibility runs out:
the at-least-once delivery the queue documents. A request SQS throttles or
fails with a fault of its own is tried up to three times.

To build the driver in code, for a second connection in another region or
account, fill an `SqsConfig` and register the driver under a name:

```rust,ignore
use suprnova::{Queue, SqsConfig, SqsQueueDriver};
use std::sync::Arc;

let mut config = SqsConfig::new("eu-west-1", "reports");
config.prefix = Some("https://sqs.eu-west-1.amazonaws.com/123456789012".into());
Queue::register_connection("reports", Arc::new(SqsQueueDriver::new(config)?));
```

`SqsQueueDriver::call(action, body)` sends any other SQS action, signed as
the driver's own requests are, where Laravel hands out the AWS client with
`getSqs()`.

SQS takes at most 1 MiB in one message, and a larger job fails its push
with an error that says so. You turn on overflow to store large jobs
outside SQS. You set `SQS_OVERFLOW_STORE` to use a named cache store you
register with `Cache::register_store(name, store)`. Without a cache store,
you use the named or default disk. SQS carries a pointer to the payload:

```bash
SQS_OVERFLOW_ENABLED=true
SQS_OVERFLOW_STORE=redis                  # optional; takes precedence over the disk
SQS_OVERFLOW_DISK=s3                      # optional; the default disk otherwise
SQS_OVERFLOW_ALWAYS=false                 # true stores every job outside SQS
SQS_OVERFLOW_DELETE_AFTER_PROCESSING=true # delete the payload when the job is done
SQS_OVERFLOW_FLUSH_ON_CLEAR=false         # true deletes this queue's payloads on clear
```

You store payloads under `sqs-payloads/<queue>-<digest>/`, where the
digest is 16 hexadecimal digits of the SHA-256 of the endpoint, the region
and the full queue URL. Two queues with one name in different accounts or
regions, or one queue URL served by two endpoints (two ElasticMQ or
LocalStack instances, or LocalStack's per-region queues), never share a
directory, and `SQS_OVERFLOW_FLUSH_ON_CLEAR` deletes only the cleared
queue's payloads. You register the selected cache store or disk before boot;
a missing store stops boot. Your cache store must support tags so clearing
one queue keeps other queues and unrelated cache entries. An evicted cache
payload returns an error when you receive its pointer. A payload is deleted
only when the driver knows no message points at it any more, so a send that times out, a send that is refused after an
earlier try timed out or met a fault of the service (5xx), or a settlement
after its reservation expired, leaves the payload in its store rather than risk
a message that can no longer be read. A retry after a send that got no
answer, or met a fault of the service, carries its own copy of the payload: if
SQS took both tries, each of the two messages owns a payload, and the job's
duplicate stays readable after the first one is acknowledged.

`SqsQueueDriver` is behind the `queue-sqs` cargo feature, which is on by
default and brings `filesystem` with it.

#### Why Suprnova diverges

- **A release does not cost an attempt.** Laravel's SQS job counts every
  receive as an attempt, so releasing a job there spends one. Suprnova
  keeps the rule every other driver follows.
- **Long delays work.** Laravel passes SQS a delay over 900 seconds, which
  SQS refuses.
- **No default region or prefix.** Laravel's configuration falls back to
  `us-east-1` and a placeholder account URL; a missing setting here stops
  the boot instead.

### MongoDB

With the `database-mongodb` feature, `QUEUE_DRIVER=mongodb` keeps jobs in
the `jobs` collection on the default MongoDB connection. It also makes
`failed_jobs` the failed-job store and, unless your bootstrap installed
one, `job_batches` the batch repository. A worker reserves a job with one
atomic `findOneAndUpdate`, so two workers never run the same job. See
[MongoDB: Queue](mongodb.md#queue) for the documents and how delays round.

### Why Suprnova diverges

Laravel routes every queueable through the Bus, distinguishing
`ShouldQueue` jobs at dispatch time. Suprnova splits the two: `Bus` for
synchronous work that returns a typed result, `Queue` for asynchronous
work that survives a process crash. PHP needs the implicit routing
because its request-per-process model makes "do this later, in another
process" hard to model otherwise. Tokio doesn't - explicit `Bus::dispatch`
vs `Queue::push` is clearer, faster, and surfaces the durability choice
at the call site. See [`bus.md`](bus.md) for the side-by-side.

## Connections

A connection is a name bound to a driver. The driver you install with
`Queue::set_driver`, or that `QUEUE_DRIVER` selects, is the **default
connection**. Its name is `Queue::connection_name()`: the name you gave
`Queue::set_connection_name`, or else the driver's own name. Every other
connection you register by name:

```rust
use std::sync::Arc;
use suprnova::queue::{MemoryQueueDriver, Queue};

// bootstrap::register()
Queue::register_connection("reports", Arc::new(MemoryQueueDriver::new()));
```

A push goes to the connection it resolves to. The first of these that names
one wins:

1. `EnvelopeOverrides::connection` on `Queue::push_with` or
   `Queue::later_with`
2. a route registered with [`Queue::route`](#queue-routing)
3. the job's own `Job::connection()`
4. the default connection

`Queue::push`, `push_with`, `later`, `bulk` and `push_unique` all resolve it.
The jobs of a [batch](#queued-batches) each go to their own connection. A
failed job goes back to the connection it failed on when you retry it.

```rust
impl Job for BuildReport {
    fn job_name() -> &'static str { "BuildReport" }
    fn connection() -> Option<&'static str> { Some("reports") }
    // ...
}
```

### What a connection name means

While you register no connection, the process has one driver and every push
reaches it. A connection name is then a label on the lifecycle events and
selects nothing, so a job can name a connection before you configure it.

Once you register one connection, a name selects a driver. It is either a
registered connection or the default connection by its own name. A push to
any other name returns an error and pushes nothing. A push that waits for a
commit returns the error before the commit, while you can still abandon the
transaction.

`Queue::connection(name)` returns the driver of one connection, and
`Queue::connection_names()` lists the registered names. `Queue::size(None)` and
the other counts and listings read the default connection. Read another
connection with `Queue::connection("reports")?.size(None).await`.

### Register connections from the environment

`QUEUE_CONNECTIONS` registers one connection per entry, next to the default
one:

```bash
QUEUE_DRIVER=memory
QUEUE_CONNECTIONS=redis,database
```

Each connection is named for its driver and reads that driver's own
variables, as it would if it were `QUEUE_DRIVER`. An entry takes the same
names as `QUEUE_DRIVER`. An unknown name is a boot error in every
environment.

One queue has one connection. An entry that names the driver `QUEUE_DRIVER`
selects is a second name for the default connection, so a pause or a
`Queue::forward_on` that you set under either name reaches the whole queue.
An entry that would put a second connection over a Redis stream or a jobs
table that another connection already uses is refused at boot.

### Workers, pauses and chains

Start a worker for one connection with `--connection`, and pause a queue on
it the same way:

```bash
./app queue:work --connection=reports
./app queue:pause billing --connection=reports
./app queue:resume billing --connection=reports
```

Without `--connection` each command acts on the default connection. A
`--connection` that names no connection stops `queue:work` and
`queue:pause` before they do anything. In code, `queue::worker::run_worker_on`
does what `queue:work --connection` does:

```rust
use suprnova::queue::worker::{WorkerConfig, run_worker_on};
use tokio_util::sync::CancellationToken;

let shutdown = CancellationToken::new();
run_worker_on("reports", WorkerConfig::default(), shutdown).await?;
```

The worker carries the name of its connection on its lifecycle events and on
the failed-job records it writes. A pause and a `Queue::forward_on` gate on
that name, so the push and the worker's claim agree on it.

A chain runs on the connection of its first job, because the worker enqueues
the next link in the step that settles the one before it. Dispatching a
chain whose links resolve to different connections returns an error and
pushes nothing.

### Why Suprnova diverges

Laravel fails on a connection name that `config/queue.php` does not define.
Suprnova accepts any name while you register no connection, because
applications with one driver often name a connection on their jobs to label
their events. The first `Queue::register_connection` turns names into
selectors, and from then on an unknown name is an error rather than a push
to the default connection, where no worker of the intended connection would
run it.

## Failover connections

`FailoverQueueDriver` wraps an ordered list of connections. A push that
the first connection refuses is retried on the next, and so on down the
list, so a Redis outage doesn't turn every dispatch into a lost job.

Configure it from env:

```bash
QUEUE_DRIVER=failover
QUEUE_FAILOVER_CONNECTIONS=redis,database

# Each connection reads its own variables, exactly as it would if it
# were QUEUE_DRIVER on its own.
QUEUE_REDIS_URL=redis://127.0.0.1:6379
QUEUE_DB_TABLE=jobs
```

Or wire it yourself, when the connections need runtime configuration
that env can't express:

```rust
use std::sync::Arc;
use std::time::Duration;
use suprnova::queue::{
    DatabaseQueueDriver, FailoverQueueDriver, Queue, QueueDriver, RedisQueueDriver,
};
use suprnova::{DB, FrameworkError};

pub async fn register() -> Result<(), FrameworkError> {
    let redis = RedisQueueDriver::connect(
        "redis://127.0.0.1:6379",
        "suprnova-queue",
        "default",
        "consumer-1",
        Duration::from_secs(60),
    )
    .await?;
    let database =
        DatabaseQueueDriver::new(DB::connection()?.inner().clone(), "jobs".to_string())?;

    let failover = FailoverQueueDriver::new(vec![
        ("redis".to_string(), Arc::new(redis) as Arc<dyn QueueDriver>),
        ("database".to_string(), Arc::new(database) as Arc<dyn QueueDriver>),
    ])?;
    Queue::set_driver(Arc::new(failover));
    Ok(())
}
```

The server and `queue:work` keep the driver you install in `bootstrap`, so
both run on this failover driver whatever `QUEUE_DRIVER` says.

The `String` on each entry is the connection label reported on the
`QueueFailedOver` event. It isn't derived from the driver type, because
two connections can run the same driver.

`QUEUE_FAILOVER_CONNECTIONS` is required when `QUEUE_DRIVER=failover`,
and the list can't contain `failover` itself. An entry naming a driver
that doesn't exist is a boot error rather than the warn-and-use-memory
fallback `QUEUE_DRIVER` applies to itself: inside a failover chain, a
typo that quietly became an in-memory connection would put an ephemeral
backend in a durable list.

### A worker drains every connection

A push walks the list and stops at the first connection that accepts it. A
read covers the whole list:

- `pop` and `pop_from` begin at a different connection on each call and
  then try every connection in order, one after the other. A primary that
  is busy again after an outage cannot starve the jobs that went to a
  fallback during it.
- `ack`, `nack`, `release` and `settle` go to the connection that issued
  the reservation. A reservation token means something to the driver that
  issued it and to no other, and two backends can issue the same token.
  The failover driver gives each reservation a token of its own and keeps
  the origin until the visibility timeout ends. A token that it does not
  know, or whose timeout is over, is treated as stale and is sent to no
  connection.
- The four counters and the three inspection listings add up every
  connection, in the order of the list. `clear` clears every connection.

So one worker on the failover connection runs the jobs of the primary and
the jobs that went to a fallback:

```bash
QUEUE_DRIVER=failover QUEUE_FAILOVER_CONNECTIONS=redis,database ./app queue:work
```

A worker with `--queue` needs every connection of the list to support
queue filtering. When one connection does not, `pop_from` returns an error
that names it, and the worker claims nothing.

A [queued chain](#queued-chains) stays on the connection of the link that
ran. The worker settles a job and enqueues the next link in one call,
`settle`, and that call goes to the connection that issued the
reservation. The database driver and the Redis driver settle in one step,
so the next link is written to that connection with the acknowledgement.
When that connection is down, the settle fails and nothing falls over: the
worker leaves the reservation as it is and the visibility timeout
redelivers the job. A driver that cannot settle in one step, such as the
memory driver, answers `Settled::Unsupported`. The worker then pushes the
next link through the failover driver like any other push, so the link
goes to the first connection that accepts it.

### The `QueueFailedOver` event

Each connection that refuses a push dispatches
`queue::events::QueueFailedOver { connection, job_name, exception }`, but
only on the push that moves that connection *into* failure. A connection
already known to be failing stays quiet until a later push succeeds on
it, which re-arms it. A four-hour outage produces one event, not one per
dispatch, which is what makes it usable as an alert.

`connection` is the label of the connection that failed, not the one that
accepted the job.

When every connection refuses a push, the push returns the last
connection's error. `bulk_push` pushes each envelope separately, so each
one falls through on its own: a batch the primary half-accepted is never
re-pushed wholesale onto the fallback, and each envelope keeps the
`available_at` it was built with. A batch is not atomic. If one envelope
is refused by every connection, `bulk_push` returns that envelope's error
with the earlier envelopes already enqueued.

Falling over is not deduplication. The decorator never re-attempts an
envelope a connection accepted, but a connection that writes the envelope
and *then* reports failure produces a duplicate on the next connection,
because "wrote it and lost the acknowledgement" is indistinguishable from
"never took it". Both copies carry the same job id. That is the
framework's at-least-once delivery contract, the same one that makes
handler idempotency a requirement everywhere else - see
[Idempotency is the contract between the worker and you](#idempotency-is-the-contract-between-the-worker-and-you).

### Why Suprnova diverges

Laravel's failover connection is a `connections` array in
`config/queue.php`, resolved through the connection registry. Suprnova's
failover driver takes the drivers themselves rather than names in the
[connection registry](#connections), so the labels come from
`QUEUE_FAILOVER_CONNECTIONS` (or from the `String` you pass to
`FailoverQueueDriver::new`) and reads go to the drivers of the list rather
than to named connections. The failover driver is one driver, and it is
the default connection or a registered connection like any other.

Laravel's `FailoverQueue::bulk` loops the jobs individually so each one's
delay survives. Suprnova resolves the delay onto the envelope before any
driver sees it, so the per-envelope loop preserves it for free - but the
loop is still what keeps a half-landed batch from being double-pushed, so
it stays.

## Push variants

Every push variant takes a typed `J: Job` value and returns when the
envelope is committed to the driver - not when the handler runs.

| Method | Behavior |
| --- | --- |
| `Queue::push(job)` | enqueue immediately |
| `Queue::push_later(job, at)` | available at a specific `DateTime<Utc>` |
| `Queue::later(delay, job)` | available after `delay` from now |
| `Queue::push_with(job, overrides)` | enqueue immediately with per-push `EnvelopeOverrides` |
| `Queue::push_after_commit(job)` | enqueue when the surrounding `DB::transaction` commits |
| `Queue::later_with(delay, job, overrides)` | available after `delay` from now, with per-push `EnvelopeOverrides` |
| `Queue::push_unique(job)` | dedupe by `J::unique_id` within `J::unique_for`, returns `Ok(true)` when the envelope was pushed, `Ok(false)` when a live dedupe key suppressed it |
| `Queue::push_unique_later(job, at)` | unique + scheduled |
| `Queue::later_unique(delay, job)` | unique + delayed |
| `Queue::bulk(vec![job1, job2, ...])` | push every job (driver may use a native bulk path) |

`push_unique` requires the cache layer to be bootstrapped - the dedupe
lock lives in [`Cache`](cache.md) via
[`Idempotency::commit_on_success`](idempotency.md). A failed push releases
the dedupe key so the caller can retry; a successful push holds it for
`J::unique_for` seconds. The job must override `Job::unique_id(&self)` to
return `Some(id)` - `None` returns an internal error.

The boolean answers one question - "is this job on the queue?" - and there
is a third case behind it. If the dedupe lock's lease is lost while the push
is in flight, the push still completes (the idempotency layer never cancels a
body that may already have had an effect) and you still get `Ok(true)`, with
a `warn`-level log naming the job and its unique key. The job is queued; what
is unproven is that nobody else queued the same one concurrently. Your
handler already has to tolerate redelivery, so this needs no extra handling -
but the log is there because a burst of them means the cache backing your
dedupe lock is struggling.

A `QueuedListener` whose job declares `unique_id` pushes through
`push_unique` too, and `QueuedListener::delay` and `delay_until` delay the
listener's job ahead of its own `Job::delay`. See
[Unique queued listeners](events.md#unique-queued-listeners) and
[Delaying a queued listener](events.md#delaying-a-queued-listener).

### Unique until processing

A uniqueness lock normally lasts the whole `unique_for` window, even after the
job has run. When the lock exists to coalesce *queued* duplicates rather than
to serialize execution, opt in to releasing it the moment processing begins:

```rust
use std::time::Duration;
use suprnova::{FrameworkError, Job, async_trait};

#[derive(serde::Serialize, serde::Deserialize)]
struct RebuildSearchIndex {
    index: String,
}

#[async_trait]
impl Job for RebuildSearchIndex {
    fn job_name() -> &'static str { "rebuild-search-index" }
    fn unique_id(&self) -> Option<String> { Some(self.index.clone()) }
    fn unique_until_processing() -> bool { true }
    fn unique_for() -> Duration { Duration::from_secs(3600) }

    async fn handle(self) -> Result<(), FrameworkError> {
        // A rebuild that runs for 20 minutes no longer swallows the
        // re-dispatch that arrives at minute 2.
        Ok(())
    }
}
```

The worker releases the lock after the job's middleware pass and immediately
before the handler runs. Four consequences follow:

- A job that a middleware releases back onto the queue keeps its lock. It has
  not started processing, so nothing has changed for a duplicate.
- A job that a middleware short-circuits any other way gives up its lock,
  because it is never going to process at all. That covers deleting the job,
  dead-lettering it, and reporting it complete without ever calling the
  handler.
- A job that fails releases its lock and is still retried. The lock went the
  moment processing began, so a duplicate can enqueue while the failed attempt
  waits out its backoff, and you end up with two envelopes for the same unique
  id. That is the trade this opt-in makes. If a retry has to keep holding the
  slot, leave `unique_until_processing` off and let the `unique_for` TTL cover
  the whole attempt chain.
- The release is owner-scoped. `push_unique` records the lock's owner token on
  the envelope, and the worker releases with that token, so a redelivered
  attempt can never release a lock that a newer dispatch has since acquired.

`unique_until_processing` needs the same two things `push_unique` needs: a
`unique_id` that returns `Some(id)`, and a bootstrapped cache layer.

Under the `sync` driver the handler runs inline inside the `push_unique` call
that took the lock, so the job releases a lock its own caller is still
nominally holding. If that handler runs for longer than a third of
`unique_for`, the dedupe lease renewer notices the lock is gone and logs a
lost-lease warning, and `push_unique` logs its own "exclusivity could not be
proven" warning on top. Both are expected here rather than a fault: the job
ran, the push returns `Ok(true)`, and the lock is gone because the job itself
released it.

### Why Suprnova diverges

Laravel releases an *ordinary* unique job's lock once the handler returns.
Suprnova lets that lock expire with the `unique_for` TTL instead, which keeps
the dedupe window honest when a worker dies mid-job: the window you configured
is the window you get, whether or not the handler ever returned.
`unique_until_processing` behaves the same in both frameworks.

Suprnova also never force-releases a uniqueness lock. Laravel falls back to a
forced release for a first attempt that carries no owner token. The only
envelopes that reach a Suprnova worker without one are envelopes queued before
the token existed, and those keep TTL expiry rather than risking a release that
deletes a newer dispatch's lock.

### Debouncing - keep the last dispatch, not the first

`push_unique` suppresses a duplicate and keeps the **first** dispatch.
Debouncing is the opposite: it keeps the **last**. A burst of twenty "this
order changed" events becomes one reindex, one window after the twentieth,
carrying the newest payload.

```rust
use std::time::Duration;
use suprnova::{FrameworkError, Job, async_trait};

#[derive(serde::Serialize, serde::Deserialize)]
struct ReindexOrder {
    order_id: u32,
}

#[async_trait]
impl Job for ReindexOrder {
    fn job_name() -> &'static str { "reindex-order" }
    fn debounce_for() -> Option<Duration> { Some(Duration::from_secs(30)) }
    fn max_debounce_wait() -> Option<Duration> { Some(Duration::from_secs(300)) }
    fn debounce_id(&self) -> Option<String> { Some(self.order_id.to_string()) }

    async fn handle(self) -> Result<(), FrameworkError> {
        Ok(())
    }
}
```

- `debounce_for` is the window: each dispatch re-arms it, so the run happens
  30 seconds after the *most recent* one.
- `max_debounce_wait` stops a continuous burst from deferring the work forever.
  Once the burst has been deferring for five minutes, the next dispatch is
  queued with no delay. The window then restarts, so each burst measures its
  maximum wait from its own first dispatch.
- `debounce_id` scopes the window. Twenty updates to order 7 become one run;
  an update to order 8 is untouched by them. Omit it and every dispatch of the
  job shares one window.

Every dispatch is still enqueued. The collapse is settled at the worker: each
push overwrites a cache token, and the worker drops any envelope whose token a
newer dispatch has replaced, acknowledging it and emitting `JobDebounced`. That
is what makes the surviving run carry the newest payload rather than the oldest.
If the token has expired or been evicted, the job runs - debouncing fails open,
because a lost token is not evidence that somebody else owns the window.

A dispatch claims the window only once the driver has accepted its envelope.
A push that fails, or a dispatch cancelled before its push - an HTTP handler
whose client disconnects - leaves the window to the last dispatch that reached
the queue, so the work already queued still runs.

The [`sync` driver](#drivers) has no worker, so it runs every dispatch inline
and nothing is ever collapsed. Laravel's sync driver behaves the same way.
`Queue::bulk` arms each job's window in order and claims it once the driver
accepts the batch, so a debounced burst pushed in one call collapses onto its
last job, as separate pushes do. When the maximum wait runs out on one job of
the batch, the jobs after it for the same window are queued with no delay
too, so the job that claims the window is the run the maximum wait forced.

#### Why Suprnova diverges

Laravel's `Queue::bulk` skips debouncing, so a debounced job pushed in bulk
runs every copy. In Suprnova the window is a property of the job, declared by
`debounce_for`, so it holds however the job reaches the queue.

Set the window at the call site instead when it belongs to the caller:

```rust
use suprnova::queue::DebounceOptions;

Queue::push_debounced(
    ReindexOrder { order_id: 7 },
    DebounceOptions::new(Duration::from_secs(30))
        .max_wait(Duration::from_secs(300))
        .id("7"),
)
.await?;
```

A job cannot declare both `debounce_for` and `unique_id`: uniqueness keeps the
first dispatch of a burst and debouncing keeps the last, so the push returns an
error naming both. Chains and batches refuse a debounced job for a related
reason - a superseded link is dropped, which would strand the rest of a chain,
and a dropped batch job leaves the batch's pending count above zero so its
callbacks never fire.

### Per-push overrides with `EnvelopeOverrides`

`Queue::push_with` and `Queue::later_with` take an `EnvelopeOverrides`
alongside the job, for the one dispatch that needs different queue,
connection, timeout, or retry behavior than the job's own defaults:

```rust
use std::time::Duration;
use suprnova::queue::{EnvelopeOverrides, Queue};

let overrides = EnvelopeOverrides {
    queue: Some("priority".into()),
    timeout: Some(Duration::from_secs(10)),
    max_tries: Some(1),
    ..Default::default()
};

Queue::push_with(SendWelcomeEmail { user_id: 42 }, overrides.clone()).await?;

// The delayed counterpart, mirroring `Queue::later`'s relationship to `Queue::push`.
Queue::later_with(Duration::from_secs(60), SendWelcomeEmail { user_id: 42 }, overrides).await?;
```

Every field defaults to `None` and defers to the normal resolution
`Queue::push` already runs; a `Some` field wins over all of it for this one
push, outranking both a route registered with [`Queue::route`](#queue-routing)
and the job's own `Job::*` declaration for that field:

| Field | Outranks |
| --- | --- |
| `queue` | `Queue::route`, `Job::queue()` |
| `connection` | `Queue::route`, `Job::connection()` |
| `timeout` | `Job::timeout()` |
| `fail_on_timeout` | `Job::fail_on_timeout()` |
| `max_tries` | `Job::max_tries()` |
| `backoff` | `Job::backoff()` |
| `after_commit` | `Job::after_commit()`, `QUEUE_AFTER_COMMIT` |

A `max_tries` of `Some(0)` is unlimited, as a `Job::max_tries()` of `0` is;
see [Unlimited tries](#unlimited-tries).

`EnvelopeOverrides` is the primitive `Mail::on_queue`/`.on_connection()` and
`Notify::queue`'s per-notification queue tuning are both built on - see
[Mail](mail.md#queueing) and [Notifications](notifications.md).

### Job-declared delay

A job can carry its own default delay instead of every call site repeating
`Queue::later(Duration::from_secs(60), job)`:

```rust
impl Job for SendDigest {
    // ...
    fn delay() -> Option<Duration> { Some(Duration::from_secs(60)) }
}
```

`Queue::push(job)`, `Queue::push_with(job, overrides)`, `Queue::push_unique(job)`,
and `Queue::bulk(vec![job1, job2])` all honor it - `available_at` becomes
`now + J::delay()` instead of `now`. `Queue::bulk` resolves the delay once
per call, since every job in the vector shares the same concrete `J` and
therefore the same `Job::delay()`.

An explicit call-site delay always wins: `Queue::push_later(job, at)`,
`Queue::later(delay, job)`, `Queue::later_with(delay, job, overrides)`,
`Queue::push_unique_later(job, at)`, and `Queue::later_unique(delay, job)`
all use the timestamp or delay the caller passed, verbatim - `Job::delay()`
isn't consulted for any of them. Reach for the trait method when every
dispatch of a job type should start delayed by default; reach for one of
the `later`/`push_later` variants for a delay one specific dispatch needs
but the type doesn't otherwise declare.

A chain honors it: every link of `Queue::chain()...add(job)?` records the
job's `Job::delay()` when you add it. The head becomes available that long
after `dispatch()`, and each later link becomes available that long after
the link before it completes. See [Queued chains](#queued-chains).

A batch doesn't consult it: `Queue::batch()...add(job)` builds its envelopes
with `available_at` set to the moment you called `add`, so a job with a
declared `Job::delay()` dispatches immediately as part of a batch even though
a bare `Queue::push(job)` of the same job would wait. Give the job an
explicit delay some other way - a field on the job itself, applied in
`handle()` - if a batched step needs one.

### Why Suprnova diverges

Laravel's `$job->delay` is an instance property, set per dispatch
(`SendDigest::dispatch($user)->delay(60)`), so two dispatches of the same
class can carry different delays. `Job::delay()` here is a class-level
default instead, like `Job::queue()` or `Job::max_tries()` - a dispatch
needing a delay computed from its own data uses `Queue::later`/`push_later`,
which already outranks the declared default.

### After-commit dispatch

A job pushed inside a [`DB::transaction`](database.md#transactions) is racing
that transaction. A worker on another process can pop the envelope, look for
the row the transaction is still holding open, and fail - or worse, the
transaction rolls back and the job runs against data that no longer exists.

Opt the job into waiting for the commit:

```rust
use suprnova::{DB, FrameworkError, Job, Queue, async_trait};

#[derive(serde::Serialize, serde::Deserialize)]
struct SendReceipt {
    order_id: i64,
}

#[async_trait]
impl Job for SendReceipt {
    fn job_name() -> &'static str { "send-receipt" }
    fn after_commit() -> bool { true }

    async fn handle(self) -> Result<(), FrameworkError> {
        // The order row is guaranteed to be durable by the time this runs.
        Ok(())
    }
}

DB::transaction(|_tx| {
    Box::pin(async move {
        let order = Order::create(suprnova::attrs! { total: 4999i64 }).await?;
        // Nothing reaches the driver here.
        Queue::push(SendReceipt { order_id: order.id }).await?;
        Ok::<(), FrameworkError>(())
    })
})
.await?;
// The envelope is on the queue now, and only now.
```

Three rules cover every case:

- **Inside a transaction, the whole push waits for the commit.** Not just the
  driver write: the envelope build, the `JobQueueing` event and the
  `JobQueued` event all happen at commit time too, so a listener is never told
  about a job that a rollback then discards.
- **A rollback discards it.** The push simply never happens. If it took a
  uniqueness lock, the rollback gives that lock back.
- **Outside a transaction the push happens immediately.** That is what makes
  the opt-in safe to declare on the job type: a dispatch site does not have to
  know whether the code path it sits on is transactional.

A [savepoint](database.md#savepoints) rollback counts as a rollback for
everything registered inside it. `tx.rollback_to("name")` discards the pushes
deferred since `tx.savepoint("name")` and releases the locks they took, right
then, so a re-dispatch inside the same transaction wins the key again. Pushes
made before the savepoint are untouched, and a savepoint you never roll back
keeps everything registered inside it.

Per dispatch rather than per job type, use `EnvelopeOverrides::after_commit`.
`Some(true)` is Laravel's `afterCommit()` and has the shorthand
`Queue::push_after_commit(job)`; `Some(false)` is Laravel's `beforeCommit()`,
for the one dispatch that has to be visible to a worker before the commit
lands:

```rust
use suprnova::queue::{EnvelopeOverrides, Queue};

// Defer a job whose type does not opt in.
Queue::push_after_commit(SendWelcomeEmail { user_id: 42 }).await?;

// Push immediately even though the job type opts in.
Queue::push_with(
    SendReceipt { order_id: 7 },
    EnvelopeOverrides { after_commit: Some(false), ..Default::default() },
)
.await?;
```

A deferred `Queue::push` re-resolves [`Job::delay()`](#job-declared-delay)
against the commit, not against the push, because the delay means "wait this
long after dispatch" and for a deferred job dispatch *is* the commit. An
explicit timestamp is the caller's intent about a moment in time, so
`Queue::push_later`, `Queue::later` and `Queue::later_with` carry theirs
through the deferral unchanged.

`Queue::push_unique` defers with one deliberate asymmetry: the dedupe lock is
taken immediately, so a second `push_unique` for the same unique id inside the
same transaction is still suppressed and still reports `Ok(false)`. Only the
envelope waits. The winner reports `Ok(true)` even though its push is pending,
because the push is going to happen. A rollback releases the lock it took,
owner-scoped, so the `unique_for` window is never blocked by a dispatch that
never happened - and so does any other ending where the commit does not land,
including a refused `COMMIT`. The one bound on that guarantee is the TTL
itself: a transaction that stays open longer than `unique_for` can have its
lock expire and be re-taken by another dispatch mid-flight, so give
`unique_for` room above your longest transaction if the dedupe matters. The
`push_unique*` family takes no `EnvelopeOverrides`, so the
[order below](#which-setting-decides) starts at the job's own choice -
there is no per-push override for it.

Batches and chains do not defer: `Queue::batch()` and `Queue::chain()` build
and push their envelopes directly. Wrap the `.dispatch()` call so it runs
after the transaction returns if a batch or a chain has to wait for a
commit.

Queued [mail](mail.md#queueing) and [notifications](notifications.md) defer
when the message asks. Each rides a single shared job type (`SendMailJob` /
`SendNotificationJob`), so the job's own `Job::after_commit()` cannot answer
for one message. Instead `Mailable::after_commit(&self)` and
`Notification::after_commit(&self)` return `false` by default. When one
returns `true`, `Mail::queue`, `Mail::later` and `Notify::queue` inside
`DB::transaction` push at the commit, and a rollback discards the push.
Outside a transaction they push at once. A message that returns `false`
makes no choice, so the connection's setting and `QUEUE_AFTER_COMMIT`
below still apply to it.

#### Which setting decides

A push inside a transaction waits for the commit by the first of these
that decides, in this order:

1. The push's own `EnvelopeOverrides::after_commit`.
2. The job's `Job::after_commit_choice()`: `Some(true)`, `Some(false)`, or
   `None` for no choice. It defaults to `Some(true)` when
   `Job::after_commit()` is `true` and `None` otherwise.
3. The setting of the connection the push resolves to,
   `Queue::connection_after_commit(connection)`.
4. `QUEUE_AFTER_COMMIT`. When it is unset too, the push does not wait.

A connection takes its setting from `QUEUE_<CONNECTION>_AFTER_COMMIT`,
the connection name upper-cased with every character other than a letter
or digit written as `_`, or in code from
`Queue::set_connection_after_commit(connection, on)`, which wins over the
variable. This is the `after_commit` option of a Laravel queue
connection. `true` or `1` waits, `false` or `0` does not, and any other
value is ignored with a warning. Suprnova reads the variables at each push.

```rust
use suprnova::{FrameworkError, Job, Queue, async_trait};

// Every push to the `audit` connection inside a transaction waits for the
// commit. QUEUE_AUDIT_AFTER_COMMIT=true does the same from the environment.
Queue::set_connection_after_commit("audit", true);

// A job that must reach a worker before the commit, whatever its
// connection or QUEUE_AFTER_COMMIT say.
#[async_trait]
impl Job for ReleaseSeatHold {
    fn job_name() -> &'static str { "ReleaseSeatHold" }
    fn after_commit_choice() -> Option<bool> { Some(false) }
    async fn handle(self) -> Result<(), FrameworkError> { Ok(()) }
}
```

To defer every job push, queued mail and queued notification in the
process that nothing closer decides for, set `QUEUE_AFTER_COMMIT=true`
(`1` works too). Batches and chains still push at once. A job that says
`Some(false)` is pushed at once even then, and so is a push to a
connection whose own setting is `false`. `push_unique` and `bulk` follow
the same order, from step 2.

Under `Queue::fake()` a push is recorded immediately, deferral and all, so a
test can assert on it without committing anything. This matches Laravel's
`Bus::fake`, and it is what lets a test drive one transactional handler and
assert its dispatches in the same breath.

### Why Suprnova diverges

`Queue::bulk` is monomorphic - every element shares one concrete `J` - so its
after-commit partition is all or nothing for the call. Laravel partitions a
heterogeneous array into deferred and immediate halves; there is nothing here
to partition.

Ambient deferral follows the closure form. A push inside a manual
[`DB::begin_transaction`](database.md#manual-form) that doesn't name the
handle happens **immediately**, because manual mode installs no ambient
transaction: code that doesn't name the handle runs outside it. To wait for
that transaction, push with `Queue::push_after_commit_with_tx(&tx, job)`,
which defers to `tx.commit()` and is discarded by a rollback or by dropping
the handle uncommitted. See
[After-commit callbacks](database.md#after-commit-callbacks).

Laravel has no process-wide switch: each connection's `after_commit` is the
last step of its order. Suprnova keeps `QUEUE_AFTER_COMMIT` as a step after
the connection's own setting, for every connection that has none. A job
says "no choice" with `after_commit_choice()` returning `None` where Laravel
leaves `$afterCommit` unset, since `Job::after_commit()` returns a plain
`bool`.

### Raw pushes

`Queue::push_raw(payload, queue)` pushes a payload that is already an
envelope, in the JSON form `Envelope::to_json` writes, onto the default
connection. It is Laravel's `Queue::pushRaw`: use it for a payload you did
not build from a typed job, such as one another service produced or one
replayed from an export.

```rust
use suprnova::{FrameworkError, Queue};

async fn replay(lines: Vec<String>) -> Result<(), FrameworkError> {
    for line in lines {
        // Each line is an envelope a producer wrote with `Envelope::to_json`.
        Queue::push_raw(&line, Some("replays")).await?;
    }
    Ok(())
}
```

A worker runs a raw-pushed envelope like any other, with the handler
registered for its `job_name`, so that job type has to be registered in the
process that drains the queue. The envelope goes on the queue as it is, apart
from its queue: `Some(queue)` replaces the envelope's own queue and is
redirected by [`Queue::forward`](#forwarding-a-whole-queue) like a per-push
override, and `None` keeps the queue the envelope carries.

A raw push skips everything a typed push resolves from the job type:
`Queue::route`, `Job::after_commit`, and the `JobQueueing` / `JobQueued`
events, which Laravel's `pushRaw` does not fire either. To push to another
connection, go through its driver: `Queue::connection("reports")?.push(envelope)`
with the decoded `Envelope`. Under `Queue::fake()` the payload is recorded,
see [Testing](#raw-pushes-under-the-fake).

#### Why Suprnova diverges

Laravel stores a raw payload as whatever string it is given, and nothing
checks it until a worker tries to run it. Here the payload has to decode as an
`Envelope` this build can read, and `push_raw` returns an error when it does
not, under `Queue::fake()` too: every driver stores envelopes, so a payload
that is not one could never reach a worker. Laravel's sync driver also drops a
raw push without running it; `SyncQueueDriver` runs it, as it runs every
other envelope.

## Job configuration

Override `Job`'s associated functions to tune behavior per impl:

```rust
use std::time::Duration;
use suprnova::queue::{BackoffSchedule, JobMiddleware};

#[async_trait]
impl Job for SendWelcomeEmail {
    fn job_name() -> &'static str { "SendWelcomeEmail" }

    async fn handle(self) -> Result<(), FrameworkError> { /* … */ Ok(()) }

    fn delay() -> Option<Duration> { None }                // default: no delay
    fn max_tries() -> u32 { 5 }                            // default: 3; 0 is unlimited
    fn timeout() -> Option<Duration> { Some(Duration::from_secs(30)) }
    fn fail_on_timeout() -> bool { false }                 // default: false (timeout retries)
    fn backoff() -> BackoffSchedule {
        BackoffSchedule::Sequence { secs: vec![5, 15, 60, 300] }
    }
    fn unique_id(&self) -> Option<String> {
        Some(format!("welcome:{}", self.user_id))
    }
    fn unique_for() -> Duration { Duration::from_secs(600) }  // default: 5 minutes
    fn unique_until_processing() -> bool { true }          // default: false (TTL is the window)
    fn middleware() -> Vec<std::sync::Arc<dyn JobMiddleware>> {
        vec![/* see "Job middleware" below */]
    }
}
```

## Queue routing

By default every job goes to one queue and every worker drains all of it. Once
some jobs are slower or more important than others, you want dedicated worker
pools: a long-running export shouldn't sit behind a thousand welcome emails.

A job can state where it belongs:

```rust
#[async_trait]
impl Job for GenerateExport {
    fn job_name() -> &'static str { "GenerateExport" }
    async fn handle(self) -> Result<(), FrameworkError> { Ok(()) }

    fn queue() -> Option<&'static str> { Some("exports") }
    fn connection() -> Option<&'static str> { None }   // default connection
}
```

…and an operator can override that centrally, without touching the job:

```rust
// bootstrap::register()
use suprnova::Queue;

Queue::route::<GenerateExport>(None, Some("heavy"));
Queue::route::<SendInvoice>(Some("redis"), Some("billing"));
```

Resolution runs highest-priority first:

1. a per-push override passed to `Queue::push_with` / `Queue::later_with` (see
   [Per-push overrides with `EnvelopeOverrides`](#per-push-overrides-with-envelopeoverrides))
2. a route registered with `Queue::route`
3. the job's own `Job::queue` / `Job::connection`
4. the default: the default queue of the driver, and the default connection

Passing `None` for a field leaves that dimension alone, so routing a job's
connection does not disturb the queue it already declared.

Both dimensions are honored end to end. The **queue** is stamped on the
envelope, stored by the driver, and filtered by `--queue`. The
**connection** selects the driver a job is pushed to, as
[Connections](#connections) describes, and its name is carried on the
`JobQueueing` / `JobQueued` lifecycle events that listeners and dashboards
see.

Then dedicate a worker to the queue:

```bash
./app queue:work --queue=billing
./app queue:work --queue=exports,heavy
./app queue:work                       # drains every queue, as before
```

A job with no route belongs to `default`, so `--queue=default` drains
unrouted work rather than stranding it. The `sqs` driver is the exception:
there a name is an SQS queue, and unrouted jobs go to `SQS_QUEUE`. See
[Amazon SQS](#amazon-sqs).

### Forwarding a whole queue

`Queue::route` is keyed by job type. When you want to drain one pool through
another - retiring a queue, absorbing a backlog, moving work off a pool you are
about to take down - key the redirect by queue name instead:

```rust
// bootstrap::register()
use suprnova::Queue;

Queue::forward("default", "high");
Queue::forward_on("exports", "heavy", "redis");   // only on the `redis` connection
```

The connection in `forward_on` is a gate. It is compared against the name of
the [connection](#connections) the push goes to, which is the name the worker
on that connection was started with (`queue:work --connection`, or the default
connection's name when you pass none). Both halves of the redirect gate on that
one value, so a forward can never move the push without moving the claim. On
any other connection the forward does nothing and the queue name passes
through.

While you register no connection, every push goes to the default connection.
The gate then compares with the default's name - `Queue::set_connection_name`
if you set one, the driver's own name otherwise - whatever connection the job,
a `Queue::route` or a per-push `EnvelopeOverrides` names.

The redirect applies on both sides, which is what keeps it from stranding work:

- **On the push side**, the name is rewritten after routing and the job's own
  `Job::queue` have had their say, and after a per-push `EnvelopeOverrides`
  queue if you passed one.
- **On the pop side**, a worker started with `--queue=default` drains `high`.
  Without that half, the destination queue would collect jobs no worker claims.

A worker started with no `--queue` at all already drains everything, so a
forward changes nothing for it. Forwarding `default` catches jobs that named no
queue, because an unrouted job belongs to `default`.

A forward is a single lookup, never a chain. With `a -> b` and `b -> c`
registered, a push that resolved to `a` lands on `b`. Registering `b -> a` on
top of an existing `a -> b` is therefore a coherent pool swap, not a loop: a
push to `a` still lands on `b`, a push to `b` now lands on `a`, and a worker
started on either name claims the other - nothing chains, so nothing strands. A
longer rotation among more queue names resolves the same way, one independent
hop at a time. Laravel's `Queue::forward` has no cycle check either, for the
same reason: its resolver is this same single lookup. Forwarding a queue onto
its own name is the identity - no redirect at all - which is how you neutralize
a forward you already registered.

Only future pushes move. Envelopes already sitting on the source queue stay
there, and the worker that used to drain them is now claiming the destination,
so drain the source pool before you forward it. The same applies to
`queue:retry`: a failed job is re-enqueued onto the queue it died on.

Pausing is evaluated before the redirect, on the names the worker was started
with. `Queue::pause(&connection, "default")` still stops a worker started on
`--queue=default`, even while `default` is forwarded to `high`. The converse
also holds: pausing the forward's *destination* - `Queue::pause(&connection,
"high")` - does not stop a worker started on `--queue=default`, because that
worker is reached through its source name, not the rewritten one. The
`WorkerQueuePaused` event this transition raises carries `queue: default`,
the configured name, never `high` - Laravel orders and reports it the same way.

The inspection calls are deliberately not forwarded:
`Queue::pending_jobs(Some("default"))` lists what is literally on `default`,
not what is on `high`, which is how you see the backlog stranded on a source
queue you have just forwarded. Laravel resolves the forward there too; see
the divergence note below.

Read a registered forward back with `Queue::forward_for("default")`, which
returns the destination in `queue` and the connection gate in `connection`.

### Why Suprnova diverges

Laravel's `Queue::route(...)` takes a class string; Suprnova takes the job as a
type parameter, so a renamed or deleted job is a compile error rather than a
route that silently stops matching.

The larger divergence is what happens when a driver can't filter.
`QueueDriver::pop_from` **rejects** a queue filter it cannot honor instead of
falling back to draining everything. A worker told to drain only `billing` that
quietly drains all queues looks identical to a working deployment until the
wrong pool consumes the wrong jobs - so the misconfiguration is made loud at
the first poll. The memory and database drivers filter natively; a driver that
doesn't - the Redis driver is one, since a single stream consumer group has no
per-queue storage - will error rather than mislead.

`Queue::forward` ports the queue-to-queue half of Laravel's `Queue::forward`
in full, and only that half. Laravel's third argument can move a forwarded queue
onto a different *connection*. Suprnova selects the connection by job, route or
push, and a forward only renames the queue, so `Queue::forward_on(from, to,
connection)` treats the connection as a **gate** - it decides whether the
queue-name redirect applies - and never as a destination. To move a job to
another connection, route the job with `Queue::route`. For the same reason
`to` is required here, while Laravel's is optional: an omitted `to` in
Laravel means "move only the connection", which a forward here does not do,
so a `forward(from, None)` would be a no-op dressed as a configuration
change.

Laravel's inspection calls follow a forward, because `pendingJobs($queue)` and
its siblings run through the same driver-level `getQueue()` the push and the pop
do. Suprnova's `Queue::pending_jobs` / `delayed_jobs` / `reserved_jobs` report
the literal queue you name instead. The literal view is the only way to see the envelopes that stayed behind on a queue you have
just forwarded away - the backlog this section tells you to drain first. Ask for
the destination queue by name to see where new work is landing.

### The `jobs` table

`DatabaseQueueDriver` reads Laravel 13's `jobs` table, and the framework
ships the migration that creates it. List it in your `Migrator`:

```rust
use suprnova::queue::migrations::{CreateFailedJobsTable, CreateJobBatchesTable, CreateJobsTable};

// in Migrator::migrations(), after your own migrations:
Box::new(CreateJobsTable),
Box::new(CreateJobBatchesTable),
Box::new(CreateFailedJobsTable),
```

`jobs` holds `id`, `queue`, `payload`, `attempts`, `reserved_at`,
`available_at` and `created_at`, as Laravel's `jobs` migration creates
them. A job's `payload` is its envelope with Laravel's `displayName` and
`uuid` added. An unrouted job is stored on the queue `default`, or on
`suprnova` when the application shares its database with a Laravel
application (see [Running on a Laravel Database](laravel-database.md)).

The driver keeps each reservation's token and deadline in a table of its
own, `suprnova_jobs_reservations` (`suprnova_<table>_reservations` for
another `QUEUE_DB_TABLE`), which `CreateJobsTable` also creates. A worker
only reserves rows the framework wrote, so a Laravel job in the same table
is never run by a Suprnova worker.

`CreateJobsTable` also upgrades a `jobs` table in the layout an earlier
release documented, with its rows: a queued, delayed or reserved job stays
so, and no job runs twice.

### Backoff schedules

| Variant | Behavior |
| --- | --- |
| `Fixed { secs }` | constant per-attempt delay |
| `Exponential { base_secs, cap_secs, jitter_ratio }` | `min(base * 2^(attempts-1), cap)` × random in `[1±jitter]` |
| `Sequence { secs }` | one entry per attempt; the last entry repeats once exhausted |

The default is `Exponential { base_secs: 2, cap_secs: 300, jitter_ratio: 0.25 }` -
2 seconds to 5 minutes with ±25% jitter.

## Job middleware

Six middleware ship in-tree, all mirroring `Illuminate\Queue\Middleware\*`:

| Middleware | Behavior |
| --- | --- |
| `WithoutOverlapping` | hold a `Cache::lock` for the duration; release-with-delay on contention |
| `RateLimited` | gate on `RateLimiter` budget; release until the window resets |
| `ThrottlesExceptions` | rate-limit on consecutive *failures*, not requests |
| `Skip::when(cond)` / `Skip::unless(cond)` | drop the job when the condition is met |
| `FailOnException` | promote matching errors to permanent failures (no retry) |
| `SkipIfBatchCancelled` | drop the job if its owning batch was cancelled |

Wire them on the `Job` impl:

```rust
use std::sync::Arc;
use std::time::Duration;
use suprnova::queue::{JobMiddleware, RateLimited, WithoutOverlapping};

fn middleware() -> Vec<Arc<dyn JobMiddleware>> {
    vec![
        Arc::new(
            WithoutOverlapping::new("user-42")
                .expire_after(Duration::from_secs(120))
        ),
        Arc::new(
            RateLimited::new(10, Duration::from_secs(60))
                .by("send-mail")
        ),
    ]
}
```

`WithoutOverlapping` and `RateLimited` need the cache subsystem booted
(`Cache::init` or `App::bind::<dyn CacheStore>(...)` at startup).

### A lock that will not release does not fail the job

If `WithoutOverlapping` cannot release its lock after the handler has
run - the cache backend blipped, the connection dropped - it logs at
`warn` and returns the handler's own outcome anyway. The lock then
lapses at `expire_after`.

That is deliberate. By the time the release runs, the handler has
already committed its side effects: rows written, mail sent, charges
made. Reporting the release failure as a job failure would make the
worker retry and do all of it a second time, which is a worse outcome
than a lock key held for its TTL. A handler that genuinely failed still
reports its failure - suppressing the release error does not suppress
the handler's.

### The release-without-burning-attempt contract

Middleware returns a `JobOutcome` rather than `Result<()>`. Four variants:

- `JobOutcome::Completed` - handler ran, ack.
- `JobOutcome::Released { delay }` - re-enqueue after `delay` **without**
  incrementing `attempts`. Used by `WithoutOverlapping`, `RateLimited`. The
  worker hands the whole operation to `QueueDriver::release`, and every
  in-tree driver requeues its own stored copy in place, so the message is
  never simultaneously reserved and visible, and never neither. The
  attempt count is preserved with no arithmetic in the worker for a driver
  to disagree with - the stored copy was never bumped for this run.
- `JobOutcome::Failed { reason }` - dead-letter now, persist to the
  failed-jobs store, do not retry.
- `JobOutcome::Deleted` - drop the reservation without dead-letter. Used
  by `Skip`. If the job belonged to a batch, the batch's `pending_jobs`
  decrements anyway so callbacks can fire.

This contract is what makes "throttled because the bucket was full" feel
different from "failed because the handler errored" in retry accounting,
metrics, and lifecycle events.

### What counts as an attempt

Two ways a job leaves a worker without finishing, and both consume an
attempt:

- **The handler failed** - returned `Err`, or panicked into the
  framework's boundary. The worker nacks; the driver requeues with
  `attempts + 1`.
- **The worker died** - OOM kill, `abort()`, a segfault, `docker kill`, or
  the SIGKILL a supervisor sends when a stop times out. Nothing settles
  anything; the reservation simply lapses. Whichever worker reclaims the
  job charges the attempt at that point.

The second case used to be free, and that was a hole rather than a
kindness: a job that reliably kills its worker could never exhaust
`max_tries` and so could never be dead-lettered. It would kill each worker
that claimed it, come back byte-identical, and kill the next one, for as
long as anything kept restarting workers.

All three in-tree drivers charge it, because swapping `QUEUE_DRIVER` must
not change whether a poison job can be stopped. `database` detects a
lapsed `reserved_until`; `memory` charges it when the reaper moves the
reservation back to visible; `redis` reads the entry's delivery count from
`XPENDING`, since a Redis stream entry is immutable and its own counter is
the only record.

`JobOutcome::Released` is the deliberate exception - see the contract
above. A job throttled by `RateLimited` never ran, so it owes nothing.

**On Redis, reclaim has two clocks.** `--visibility-timeout` sets how long
an entry must sit unacked before it qualifies for reclaim; a second
interval governs how often a consumer looks. The driver ties the second to
the first, so a lost job comes back within roughly twice the configured
timeout rather than the timeout plus a fixed 30 seconds.

**The budget is checked before the handler runs, not only when settling.**
Every other dead-letter decision happens after a handler returns, which
assumes the handler returns. A job that kills its worker cannot reach
that check, so the worker also refuses to dispatch a job whose attempts
are already spent - it dead-letters it instead, before it takes another
worker down. Without this, counting the attempt would only make a number
climb while the job kept cycling.

**What this means for you.** `attempts` counts *deliveries to a worker*,
not *handler failures*. A worker lost for reasons unrelated to the job - a
host reboot, an OOM caused by a noisy neighbour - burns an attempt from
that job's budget too. Laravel behaves the same way. Size `max_tries` with
that in mind, and prefer idempotent handlers: at-least-once delivery was
always the contract, and this makes the redelivery path count honestly
rather than silently.

### Unlimited tries

A job whose `Job::max_tries()` returns `0` is retried until it succeeds, as
Laravel's `$tries = 0` is. A push with `EnvelopeOverrides { max_tries:
Some(0), .. }` does the same for that one push, and so does a notification
whose `max_tries()` returns `0`. The envelope carries `u32::MAX`, the budget
the worker's `--tries=0` gives, so the worker never dead-letters the job for
running out of attempts:

```rust
impl Job for SyncAccount {
    // ...
    fn max_tries() -> u32 { 0 } // retried until it succeeds
    fn backoff() -> BackoffSchedule {
        BackoffSchedule::Exponential { base_secs: 10, cap_secs: 3600, jitter_ratio: 0.25 }
    }
}
```

Four things still end the retries of an unlimited job and send it to the
failed-jobs store:

- An error named with `dont_retry` or `dont_retry_when`, as
  [Errors that end retries](#errors-that-end-retries) describes.
- A job middleware that fails the job, such as `FailOnException`.
- A timeout, when the job's `fail_on_timeout()` is `true`.
- A worker started with `--tries`, which replaces the job's budget with its
  own for every job that worker runs.

Give an unlimited job a backoff with a cap, as above, so a job that keeps
failing waits between tries instead of returning to a worker at once.

### Errors that end retries

Some failures repeat on every attempt: a declined card, a deleted
account, a payload the job can never parse. Name them once, in
`bootstrap.rs`, and the worker fails the job at once, whatever attempts
it has left:

```rust
use suprnova::{Exceptions, FrameworkError};

#[derive(Debug)]
pub struct CardDeclined;

impl std::fmt::Display for CardDeclined {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("the card was declined")
    }
}

impl std::error::Error for CardDeclined {}

pub fn register_retry_rules() {
    // An error that wraps a `CardDeclined`.
    Exceptions::dont_retry::<CardDeclined>();

    // Any error the predicate accepts.
    Exceptions::dont_retry_when(|error: &FrameworkError| error.status_code() == 422);
}
```

`dont_retry::<E>()` matches an error whose wrapped source is an `E`, the
error a job passed to `FrameworkError::from_external` or
`from_external_with`. `Exceptions::should_stop_retries(&error)` answers
the same question the worker asks. A job that fails this way is
dead-lettered: it reaches the failed-jobs store and raises `JobFailed`,
as a job that spent its tries does.

The list applies to every job. To end the retries of one job type only,
put `FailOnException` in that job's middleware.

Every failed attempt is also reported through `Exceptions`, retried or
not, so a callback registered with `Exceptions::reportable` sees each
one. That includes an attempt that runs past its timeout, which you
receive as a `TimeoutExceeded` error, so `dont_retry::<TimeoutExceeded>()`
ends the retries of a job that times out. See
[Error Handling](errors.md#report-errors-with-exceptions).

## Context on queued work

A job runs after the request that queued it, often in another process.
Suprnova carries the [`Context`](context.md) to it. Every push takes a
`ContextSnapshot` of the caller's visible and hidden bags and stores it in
the `context` field of the `Envelope`. The field is `None` when the caller
had nothing to carry.

```rust
use suprnova::Context;

// In a handler:
Context::add("tenant_id", "acme");
Queue::push(SendInvoice { invoice_id: 7 }).await?;

// In SendInvoice::handle, on a worker:
let tenant: Option<String> = Context::get("tenant_id");
```

The worker restores one scope from the snapshot for each attempt. The job,
its middleware and the lifecycle events around it (`JobProcessing`,
`JobProcessed`, `JobFailed` and the rest) all run in that scope, so a
listener reads what the job read and what the job added. The rules:

- The snapshot is taken when you push. A push that waits for a
  [commit](#after-commit-dispatch) carries the snapshot of the code that
  called `push`.
- Every link of a chain and every job of a batch carries the snapshot of the
  code that built it. A queued event listener carries the snapshot of the
  dispatch.
- The job works on a copy. What it adds reaches neither the request nor the
  next job, and every retry starts from the snapshot again.
- The query bag does not travel. A job that runs inline under the `sync`
  driver does not read the request's query parameters.
- A job queued while a request is served carries the request's id as
  `_request_id`.
- Hidden values travel too, because the job needs them. They reach the queue
  store and the failed-job store. They do not reach a log: the envelope a
  worker logs when no failed-job store is bound carries no hidden context.

`Context::dehydrating` and `Context::hydrated` register callbacks for the
two ends of the trip. See [Context](context.md#queued-work).

## Lifecycle events

Workers emit Laravel-shape lifecycle events through the
[`Event`](events.md) facade. Listeners get the envelope's identity (`id`,
`job_name`, `attempts`, `max_tries`, `connection`), not the typed job
instance - the worker is type-erased over JSON payloads. Errors travel
as a `String` since `FrameworkError` doesn't derive `Clone`.

| Event | Fires when |
| --- | --- |
| `JobQueueing` | before the envelope hits the driver |
| `JobQueued` | after the driver accepts |
| `UniqueJobSkipped` | `push_unique` suppressed a duplicate inside the `unique_for` window |
| `JobDebounced` | the worker dropped an envelope a newer debounced dispatch superseded |
| `JobProcessing` | first in every attempt on a worker, before the max-attempts check, the debounce check and the middleware |
| `JobProcessed` | the attempt returned without an error: the handler returned `Ok`, middleware deleted the job, released it (before `JobReleased`) or failed it without an error (after `JobFailed`), or the worker dropped it as superseded (after `JobDebounced`) |
| `JobAttempted` | last in every attempt the worker settles, whatever the outcome; not after a timeout |
| `JobExceptionOccurred` | the attempt ended in an error or a panic: before `JobReleasedAfterException` when retried, after `JobFailed` when the error failed the job (last attempt, attempts already exhausted, `FailOnException`) |
| `JobReleasedAfterException` | the job was put back after an error, before `JobAttempted` |
| `JobReleased` | middleware put the job back without spending an attempt, after `JobProcessed` |
| `JobFailed` | the job failed: an error on its last attempt, attempts already exhausted, a timeout that fails it (before `JobTimedOut`), or middleware |
| `JobTimedOut` | the attempt ran past its timeout; no `JobAttempted` follows, as Laravel's worker exits there |
| `Looping` | every loop iteration (before the pop) |
| `WorkerStarting` / `WorkerStopping` | once per worker lifetime |
| `WorkerInterrupted` | `Queue::restart()` signal observed |
| `QueuePaused` | `Queue::pause` set one queue's own switch |
| `QueueResumed` | `Queue::resume` cleared one queue's own switch |
| `QueuesPaused` | `Queue::pause_all` set the global switch |
| `QueuesResumed` | `Queue::resume_all` cleared the global switch |
| `WorkerQueuePaused` | a running worker first observed a queue as paused |
| `WorkerQueueResumed` | a running worker saw a paused queue become claimable |

Subscribe with the normal `Event::listen` API. Events are best-effort -
`Event::dispatch` with no listeners is a no-op `Ok(())`, so workers in
deployments without `Event::init()` pay nothing.

`UniqueJobSkipped` is the one event that fires on the *push* side rather
than the worker side, and the one that reports a non-failure. It carries
`job_name`, `unique_id`, and `connection` - the dedupe decision happens
before an envelope exists, so there is no envelope id to report. The
push still returns `Ok(false)`; the event is what makes an otherwise
invisible suppression observable.

`QueuePaused` / `QueueResumed` / `QueuesPaused` / `QueuesResumed` fire the
same way - from `Queue::pause` / `resume` / `pause_all` / `resume_all`
themselves, not from the worker loop. They carry no envelope identity
either; see "Pausing queues" below for the full contract.

`WorkerQueuePaused` / `WorkerQueueResumed` are the worker-side pair, and they
are the ones that tell you *why a particular worker went quiet*. They fire once
per transition from inside the worker loop, carry the connection the worker is
draining, and carry the queue name - or `None`, when an unfiltered worker is
idle on a global pause and has no queue names to report.

## Failed-jobs storage

Dead-lettered jobs land in the configured `FailedJobStore`:

```rust
use std::sync::Arc;
use suprnova::queue::{Queue, MemoryFailedJobStore};

Queue::set_failed_store(Arc::new(MemoryFailedJobStore::new()));

// In admin tooling:
let store = Queue::failed_store().unwrap();
for record in store.all().await? {
    println!("{} failed: {}", record.job_name, record.exception);
}
store.forget(some_id).await?;
store.flush(None).await?;
```

Three backends:

- `MemoryFailedJobStore` - in-process `Vec`, lost on restart.
- `DatabaseFailedJobStore` - persists to a `failed_jobs` table via SeaORM.
- `MongoFailedJobStore` - persists to a `failed_jobs` collection, with the
  `database-mongodb` feature. `QUEUE_DRIVER=mongodb` binds it.
- `NullFailedJobStore` - discards every record. Mirrors Laravel's
  `NullFailedJobProvider`.

### When the store rejects a record

If the configured store returns an error, the worker logs at `error` and
**leaves the reservation intact** rather than acking. The job returns on
visibility expiry and is retried - it is not silently dropped.

That is deliberate. The alternative, acking anyway, discards a job that
already exhausted its attempts *and* failed to be recorded anywhere, which
is unrecoverable. A job that keeps coming back is recoverable: fix the
store and the next delivery lands.

The practical case is a `DatabaseFailedJobStore` pointed at an unmigrated
`failed_jobs` table. Until you migrate, dead-lettering jobs cycle at one
redelivery per visibility timeout, each logging the store's error. If you
genuinely want failures discarded, configure `NullFailedJobStore` - that
succeeds, so the job acks and is gone.

### Retrying

```rust
use uuid::Uuid;

// Single record - false if the id wasn't in the store.
Queue::retry_failed(some_id).await?;

// Bulk - optional cutoff (only retry records older than `before`).
let count = Queue::retry_all_failed(None).await?;
```

`retry_failed` loads the envelope, resets `attempts`, `available_at`, the
`idempotency_key` and the uniqueness lock owner, pushes it to the
[connection](#connections) it failed on, then deletes the failed-job record.
Mirrors `php artisan queue:retry <id>` plus `queue:flush` semantics (each
retried envelope is pushed AND removed from the store).

`retry_all_failed` keeps a record whose connection is not registered, as it
keeps a record whose envelope does not decode, and logs a warning.
It carries on with the records after it. `retry_failed` returns the error
instead.

### Failed-job commands

The application binary has five commands over the failed-job store. Run them
as you run `queue:work`, with `./app` or `cargo run --bin app --`:

| Command | Effect |
| --- | --- |
| `queue:failed` | list every failed job: id, connection, queue, job, failure time and the first line of the error |
| `queue:retry <id>...` | push the failed jobs with these ids back onto the queue |
| `queue:retry all` | push every failed job back onto the queue |
| `queue:forget <id>` | delete one failed job |
| `queue:flush [--hours N]` | delete every failed job, or only those that failed more than `N` hours ago |
| `queue:prune-failed [--hours N]` | delete the failed jobs older than `N` hours; `N` defaults to `24` |

```bash
./app queue:failed
./app queue:retry 3f2a9c1e-5b7d-4c8e-9a10-2d6e4b8f7a11
./app queue:retry all
./app queue:flush --hours 168
```

`queue:retry` calls `Queue::retry_failed` for each id, or
`Queue::retry_all_failed` for `all`. A command exits non-zero when part of
the request fails: an id that names no failed job, or an id that is not a
UUID. The `suprnova` CLI forwards the same five commands to your
application's binary, so `suprnova queue:failed` from the project directory
does the same as `./app queue:failed`.

The commands run the application's bootstrap, as `queue:work` does, and use
the failed-job store that boot bound. `QUEUE_DRIVER=database` and
`QUEUE_DRIVER=mongodb` bind one. With any other driver, call `Queue::set_failed_store(...)` in `bootstrap::register()`.
With no store bound, a command exits non-zero and says so. A retry pushes to
the queue that boot configured, so with the `memory` driver the retried job
goes into the memory of the command's own process, not into the process that runs
your workers.

### `failed_jobs` schema

The `DatabaseFailedJobStore` reads Laravel 13's `failed_jobs` table:
`id`, a unique `uuid`, `connection`, `queue`, long-text `payload` and
`exception`, and `failed_at`. `CreateFailedJobsTable` creates it, with
`failed_at` as `DATETIME` on MySQL. Each failed job gets a fresh `uuid`, and
`queue:failed`, `queue:retry <uuid>` and `queue:forget <uuid>` use it. The
row's `payload` is the envelope with `displayName` and `uuid` added, and its
`connection` is `suprnova:` followed by the connection name, so Laravel's
own `queue:retry` refuses it. A table an earlier release created is
reshaped with its rows, and each failed job keeps its id as its `uuid`.

The `table` argument to `DatabaseFailedJobStore::new` is validated as a
SQL identifier at construction.

## Queued batches

Dispatch a group of jobs with progress tracking and completion callbacks:

```rust
use std::sync::Arc;
use suprnova::queue::{Queue, MemoryBatchRepository, batch::register_callback};

Queue::set_batch_repository(Arc::new(MemoryBatchRepository::new()));

// Register named callbacks at boot.
register_callback(Arc::new(SendSummary));
register_callback(Arc::new(PageOnFail));

let id = Queue::batch()
    .name("import-users")
    .add(ImportUser { id: 1 })
    .add(ImportUser { id: 2 })
    .add(ImportUser { id: 3 })
    .then("send-summary-email")
    .catch("page-on-fail")
    .finally("cleanup-temp-tables")
    .dispatch()
    .await?;

// Inspect progress later:
let repo = Queue::batch_repository().unwrap();
let snap = repo.find(&id).await?.unwrap();
println!("{}/{} jobs done ({}%)", snap.processed_jobs(), snap.total_jobs, snap.progress());
```

Each worker settles its job against the batch, and when `pending_jobs`
hits zero the worker fires the registered `then`/`catch`/`finally`
callbacks. By default the first failure cancels the batch;
`.allow_failures()` keeps remaining jobs going.

When a push fails part way through `dispatch()`, the jobs that never reached
the queue are recorded as failed and the batch is cancelled. If that leaves
nothing pending, because the jobs that were queued have already settled,
`dispatch()` fires the callbacks itself before it returns the push error.

The [`sync` driver](#drivers) runs each job inline inside `dispatch()` and
settles it against the batch as a worker would, so a batch on `sync` finishes
and fires its callbacks before `dispatch()` returns. A job that a middleware
releases is left pending: nothing runs it again on `sync`, as in Laravel.

### Durable batches

`MemoryBatchRepository` is lost on restart, which strands every in-flight
batch: its counters are gone, `pending_jobs` can never reach zero again,
and the callbacks never fire. Use `DatabaseBatchRepository` in production:

```rust
use std::sync::Arc;
use suprnova::queue::{Queue, DatabaseBatchRepository};

Queue::set_batch_repository(Arc::new(DatabaseBatchRepository::new(db.clone())));
```

`QUEUE_DRIVER=mongodb` installs `MongoBatchRepository` over the
`job_batches` collection when no repository is installed. Each settlement
moves the counters with one atomic update of the batch's document, so it
is durable the same way. See [MongoDB: Queue](mongodb.md#queue).

Two tables, which `CreateJobBatchesTable` creates: Laravel 13's
`job_batches`, and the framework's `job_batch_settlements`, which records
each `(batch_id, job_id)` that settled:

```sql
CREATE TABLE job_batch_settlements (
    batch_id   VARCHAR(255) NOT NULL,
    job_id     VARCHAR(255) NOT NULL,
    failed     INTEGER NOT NULL,
    settled_at BIGINT NOT NULL,
    PRIMARY KEY (batch_id, job_id)
);
```

`job_batches.options` holds the batch's options as a PHP-serialized array,
which Laravel's batch repository reads. A `job_batches` table an earlier
release created is moved into Laravel's layout, and each batch keeps its
counts.

`DatabaseBatchRepository::with_tables(db, batches, settlements)` names them
yourself; both names are validated as SQL identifiers at construction.

`pending_jobs`, `failed_jobs` and `failed_job_ids` are Laravel's columns,
and the repository writes them, but it never decrements them. Each write
derives them from the settlement rows -

```text
pending_jobs = max(0, total_jobs - COUNT(settlements))
failed_jobs  = COUNT(settlements WHERE failed)
```
 -
because queues are at-least-once, so the same job settles more than once
whenever a redelivery happens, an ack is duplicated, or a worker dies
between doing the work and recording it. A counter decremented per
settlement drifts on every one of those, and the drift is not cosmetic:
`pending_jobs` gates the callbacks, so an early zero fires `then` while
other jobs in the batch are still running. With the counts derived and the
primary key on `(batch_id, job_id)`, a repeat settlement inserts nothing and
there is no counter to get wrong - across processes, not just within one.

### When a dispatch fails halfway

If a `driver.push` fails partway through `dispatch()`, the jobs that
already reached the queue are real and already stamped with the batch id.
So the batch is settled rather than removed: every envelope that was *not*
pushed is recorded as a failed job, and the batch is cancelled.

`total_jobs` still counts what you asked for, `failed_job_ids` names
exactly the jobs that never made it, the ones already queued settle
normally, and `SkipIfBatchCancelled` drops the rest - so `pending_jobs`
still reaches zero and your `catch`/`finally` callbacks still run. If
nothing was pushed at all, `dispatch` fires them itself, because no worker
is left to. You get the original push error back either way.

### Batch options

| Option | Builder method | Effect |
| --- | --- | --- |
| Allow failures | `.allow_failures()` | continue scheduling after a job fails |
| Then callback | `.then(name)` | runs on every-job-success |
| Catch callback | `.catch(name)` | runs on first failure |
| Finally callback | `.finally(name)` | runs after batch settles either way |
| Skip cancelled | `SkipIfBatchCancelled` middleware on the job | drop remaining jobs when batch is cancelled |

### `BatchCallback` impl

```rust
use async_trait::async_trait;
use suprnova::queue::{Batch, BatchCallback};
use suprnova::error::FrameworkError;

pub struct SendSummary;

#[async_trait]
impl BatchCallback for SendSummary {
    fn name(&self) -> &'static str { "send-summary-email" }

    async fn handle(&self, batch: Batch, error: Option<String>) -> Result<(), FrameworkError> {
        let subject = match error {
            Some(_) => format!("Batch {} failed", batch.name),
            None    => format!("Batch {} done - {} jobs", batch.name, batch.total_jobs),
        };
        // … send mail
        Ok(())
    }
}
```

Register at boot with `batch::register_callback(Arc::new(SendSummary))`.
Callbacks are keyed by `name()` - the batch's options store callback
names, so a process restart picks up registered callbacks by lookup
instead of trying to deserialize a closure (Rust closures don't
serialize).

## Queued chains

Sequential workflows where each link runs only after the previous one's
handler acks:

```rust
Queue::chain()
    .add(GenerateReport { id: 99 })?
    .add(UploadToBucket { id: 99 })?
    .add(NotifyOwner { id: 99 })?
    .dispatch()
    .await?;
```

The first envelope is pushed at dispatch; the rest travel on its
`chain_remaining` payload field. On every successful settlement the
worker pops the next entry and dispatches it. A failure breaks the
chain - subsequent links are never enqueued.

The [`sync` driver](#drivers) has no worker, so it runs the whole chain
inline inside `dispatch()`, link by link. A link whose handler fails returns
its error from `dispatch()`, and the links after it do not run.

Each link applies its job's own `Job::delay()`, as a direct push does. A
delay of 30 seconds on the head makes the head available 30 seconds after
`dispatch()`. A delay on any later link makes that link available that long
after the link before it completes. A chain runs on one connection, the one
its first job resolves to - see [Workers, pauses and chains](#workers-pauses-and-chains).

### Terminal settlement

Finishing a chained job means two things: enqueue the successor, and
release the job just finished. As two separate operations there is no safe
order. Ack first, and a crash in the gap loses the rest of the chain
permanently - nothing is left in the queue to retry from. Push first, and
the same crash redelivers the finished job, so its handler runs again and
the successor is enqueued twice.

So the worker hands both to the driver at once, via
`QueueDriver::settle(token, follow_ups)`:

| Outcome | Meaning |
| --- | --- |
| `Settled::Atomically` | successor enqueued and reservation dropped in one transaction |
| `Settled::Stale` | the reservation was reclaimed by another consumer; **nothing** was enqueued or dropped |
| `Settled::Unsupported` | this driver cannot settle transactionally |

`DatabaseQueueDriver` implements it: both effects are one transaction, and
the reservation-keyed `DELETE` doubles as a fence. If your visibility
timeout expired while the handler was running and another worker picked the
job up, the delete matches nothing, the transaction rolls back, and you get
`Stale` - having enqueued nothing. Two-step settlement cannot express that
at all: your push succeeds, the new owner's push succeeds, and the chain
forks.

Redis and the in-memory driver answer `Unsupported` and keep the
push-before-ack ordering, which trades permanent loss for an at-least-once
duplicate. That is the framework's documented contract, and it is why
chained envelope ids are derived from their predecessor rather than random -
a redelivered step re-pushes the id it pushed before, so the duplicate is
recognisable as the same logical step.

If you write a driver whose follow-up write and acknowledgement share a
transaction domain, implement `settle`. Its default returns `Unsupported`,
so drivers written before this existed keep working unchanged.

## Introspection

```rust
Queue::size(None).await?;            // total
Queue::pending_size(None).await?;    // available_at <= now, not reserved
Queue::delayed_size(None).await?;    // available_at > now
Queue::reserved_size(None).await?;   // currently popped, not yet acked
Queue::clear(None).await?;           // drop every envelope, returns the count
Queue::driver_name()?;           // configured driver name for logs / admin
```

The `QueueDriver` trait declares defaults for `size` / `pending_size` /
`reserved_size` / `delayed_size` / `clear`; `MemoryQueueDriver`,
`DatabaseQueueDriver`, and `RedisQueueDriver` all implement them natively.
You pass `Some("reports")` to count or clear only that queue, including its
reserved and delayed jobs. You pass `None` to include all queues on a shared
driver, or the configured `SQS_QUEUE` on SQS. Clearing one queue preserves
other queues' jobs and live reservations. Sync and null drivers report zero.

### Inspecting queues

Counts tell you how much is queued; sometimes you need to see the actual
envelopes - an admin dashboard, a debugging session, a "what exactly is
stuck" question. `Queue::pending_jobs` / `delayed_jobs` / `reserved_jobs`
return the same information the size counters count, as a listing of
`InspectedJob` DTOs:

```rust
use suprnova::queue::{InspectedJob, Queue};

let pending: Vec<InspectedJob> = Queue::pending_jobs(None).await?;
let billing_only: Vec<InspectedJob> = Queue::pending_jobs(Some("billing")).await?;
let delayed = Queue::delayed_jobs(None).await?;
let reserved = Queue::reserved_jobs(None).await?;

for job in &pending {
    println!(
        "{} attempts={} queue={:?} payload={}",
        job.name, job.attempts, job.queue, job.payload
    );
}
```

`InspectedJob` carries `id`, `queue`, `name`, `attempts`, `payload`, and
`created_at`. `id` and `created_at` are `Option`: the database driver's
listings still report a row whose `payload` failed to decode - as
`id: None` and `payload: {"unparseable": true}` - rather than dropping it
and hiding a poison job from whoever is looking; `Queue::fake()`'s
pending and delayed projections never record a dispatch timestamp
separate from `available_at`, so `created_at` is always `None` there.

Under `Queue::fake()`, `Queue::reserved_jobs` reads no driver. It lists the
reservations workers made from the fake, each built from the envelope the
worker reserved. See [Run a worker on the fake](#run-a-worker-on-the-fake).

On the memory driver, `delayed_size()` reads the delayed store's length
directly, while `delayed_jobs()` and `pending_jobs()` first promote any
entry whose `available_at` has already passed. In the narrow window
between a job coming due and the background reaper's next 50ms tick,
`delayed_size()` can still count a job that `delayed_jobs()` has already
promoted into `pending_jobs()` - the listings are the more current view;
a mismatch there is expected, not a bug.

A reservation whose visibility timeout has lapsed keeps appearing in
`reserved_jobs()` until a `pop` or the background reaper reclaims it. Only
those two reclaim, and reclaiming is what spends an attempt, so a listing call
never changes a job's attempt count however often you call it.

#### Why Suprnova diverges

- **One method with `Option<&str>`, not a pair per listing.** Laravel ships
  `pendingJobs($queue)` alongside a separate `allPendingJobs()`; here
  `queue: None` collapses the two into one call. Same shape for
  `delayedJobs`/`allDelayedJobs` and `reservedJobs`/`allReservedJobs`.
- **The trait default is an honest `Err`, not an empty collection.**
  Laravel's Beanstalkd and SQS drivers return `[]` from these methods even
  for a queue that plainly has jobs - a lie of omission a third-party
  driver author could copy without noticing. A Suprnova driver that has
  not implemented inspection says so; `sync` and `null` override with
  `Ok(vec![])` because for them "there is never anything to list" is the
  literal truth, not an unimplemented method.
- **Redis's `reserved_jobs` is per-consumer.** The driver only knows the
  reservations it has personally handed out in-process; another
  consumer's in-flight entries are visible only through Redis's own
  `XPENDING`, not through this call.
- **Redis's `pending_jobs` means "never delivered to any consumer in this
  group."** It scans `XRANGE (<last-delivered-id> +` - everything past the
  group's delivery cursor (`XINFO GROUPS`) - rather than the whole stream,
  because `ack` only `XACK`s an entry (this driver never `XDEL`/`XTRIM`s
  the stream), so a scan that merely excluded one consumer's in-memory
  reservations would report every acked job as pending forever. A
  released or nacked job is re-published under a fresh id above the
  cursor, so it reappears once its retry is live. Same "upper bound"
  register as `pending_size`: the cursor is read once, so a concurrent
  `pop` can claim an entry between that read and the scan. In practice, a
  running consumer's background read-ahead task tends to claim a newly
  pushed entry within milliseconds of the push, well before an
  application ever calls `pop` - so `pending_jobs` mostly reflects work
  pushed while no consumer for that stream is actively polling, not "any
  envelope nobody has explicitly popped yet".

## Worker controls

You pass worker controls beside `--poll`, `--visibility-timeout`, `--max-jobs`,
`--queue` and `--connection`:

```bash
./app queue:work --sleep=3 --tries=2 --timeout=60 --memory=128
./app queue:work --once
./app queue:work --stop-when-empty --queue=emails
```

- You set `--sleep` in seconds to pause between empty polls. It overrides
  `--poll`, which remains in milliseconds. Without either, you keep the
  existing 100 millisecond poll interval.
- You set `--tries` to override the attempt budget for this worker. With
  `--tries=0`, you permit retries without an attempt cap, as a job's own
  `max_tries()` of `0` does.
- You set `--timeout` in seconds to override the attempt timeout. With
  `--timeout=0`, you remove it. Without these controls, you keep the envelope's
  attempt budget and timeout.
- You use `--once` to settle one reservation and exit. An empty first poll
  also ends the worker. You leave any second job for another worker.
- You use `--stop-when-empty` to drain available jobs and exit on the first
  empty poll. You do not wait for delayed jobs to become available.
- You set `--memory` in MiB to check resident memory from `/proc/self/status`
  after each settled job. You receive exit status 12 when it exceeds the
  limit, including when you also pass `--once` or `--max-jobs`. You use a
  supervisor to restart the worker. With `--memory=0`, you disable the limit.
  You receive an error if a configured limit cannot read resident memory.

You use `run_worker_with_controls(driver, config, controls, shutdown)` or
`run_worker_on_with_controls(connection, config, controls, shutdown)` from
Rust. You pass a `WorkerControls` and receive `Result<i32, FrameworkError>`:
0 for a normal stop, 12 for the memory limit. You keep existing worker
callers with `run_worker` and `run_worker_on`, which use default controls.

## Worker restart signal

`php artisan queue:restart` translates to:

```rust
Queue::restart().await?;
```

The signal lives in `Cache` as a millisecond timestamp. Workers poll
once per loop and exit cleanly when the timestamp is newer than their
start time. Pair with a supervisor (systemd, Kubernetes, the
`supervisor` module) so a fresh worker picks up where the previous one
stopped.

## Pausing queues

`php artisan queue:pause` / `queue:resume` translate to:

```rust
Queue::pause(&connection, "billing").await?;
Queue::resume(&connection, "billing").await?;
Queue::pause_all().await?;
Queue::resume_all().await?;
```

or from the CLI:

```bash
./app queue:pause billing
./app queue:pause --all
./app queue:resume billing
./app queue:resume --all      # alias: queue:continue
./app queue:pause billing --connection reports
```

A pause belongs to one connection. `queue:pause` and `queue:resume` take
`--connection <name>` and act on the default connection without it. See
[Connections](#connections).

A paused worker finishes whatever it already popped - pausing never
interrupts a job in flight - then stops claiming new work until resumed.
`pause_all` / `resume_all` are the global switch; pausing (or resuming) a
named queue only affects that queue. **`resume_all` does not clear a
per-queue pause** - a queue paused individually stays paused after a
global resume, matching Laravel. Clear it explicitly with
`Queue::resume(&connection, "billing")`.

A paused worker also says so. `queue:work` prints one line per transition:

```text
  2026-08-25 14:03:11 Queue billing PAUSED
  2026-08-25 14:07:44 Queue billing RESUMED
```

A worker started without `--queue` has no queue names to report, so a global
pause prints `All queues PAUSED` instead. Both lines come from the
`WorkerQueuePaused` / `WorkerQueueResumed` events, so you can listen for them
yourself and route them wherever your alerting lives.

Both signals live in `Cache`, next to the restart signal above:

| Key | Meaning |
| --- | --- |
| `suprnova:queues:paused` | global switch, set by `pause_all` |
| `suprnova:queue:paused:{connection}:{queue}` | one queue's switch, set by `pause` |

Check state with `Queue::is_paused(&connection, "billing").await?` (true if
either key is set) or `Queue::paused_queues(&connection, &queues).await?`
(which of `queues` are currently paused).

### Per-queue pausing needs a named `--queue`

A worker started with `--queue=billing,exports` only claims from those two
queues, so pausing `billing` narrows that list to `exports` for as long as
the pause holds. A worker started with no `--queue` at all drains every
queue the driver holds, and there is no way to ask "pause just `billing`"
against that - `QueueDriver::pop_from` never reports which queue names
exist, so there's nothing to check a per-queue pause key against.
`pause_all` still stops an unfiltered worker completely; a named
per-queue pause only takes effect once you also name that worker's
queues.

### Disabling pause polling

Set `QUEUE_PAUSABLE=false` and every worker in that process ignores pause
signals entirely, at no extra cache-read cost per loop. `queue:pause` (not
`queue:resume`) also refuses to run and exits non-zero, so an operator who
disabled pausing finds out immediately rather than issuing a pause that
quietly does nothing. Mirrors Laravel's `Worker::$pausable`.

### Why Suprnova diverges

An unreachable cache fails **open**: a worker that can't read the pause
keys behaves as "not paused" and keeps draining - the same fail-open
contract the worker restart signal above already uses. A transient cache
outage should degrade a worker fleet to "ignoring pause," never to "every
worker silently freezes" - the pause state is an explicit opt-in signal,
and its own unavailability should not become a hidden kill switch.

## Graceful shutdown

The worker's `CancellationToken` fires at the next pop boundary, never
mid-dispatch. A handler that's already been popped runs to completion
(bounded by its own `Job::timeout()` if set) before the worker exits.
That means in-flight side effects don't get torn mid-stride, but a
SIGTERM can take up to the per-job timeout to drain. Set
`WorkerConfig::max_jobs` for a periodic-restart strategy on long-lived
workers; the worker exits cleanly after that many settlements regardless
of outcome.

## Settlement metrics

The worker emits a `queue.settlement.failures` counter via [`Metrics`](observability.md) on every ack/nack failure. Attributes: `operation`
(`"ack"` | `"nack"`), `driver` (the configured driver's name), `job`
(the job_name), `outcome` (`"success"`, `"dead_letter"`, `"retry"`,
`"deleted"`, `"timeout_dead_letter"`, `"timeout_retry"`, `"released"`).

A non-zero rate here means at-least-once delivery may re-deliver a
successful side effect or lose attempt accounting - alert on it
explicitly.

## Typed errors

`MaxAttemptsExceeded`, `TimeoutExceeded`, and `ManuallyFailed` mirror
Laravel's `MaxAttemptsExceededException` / `TimeoutExceededException` /
`ManuallyFailedException`. The worker attaches the relevant cause to
the dead-letter `JobFailed` event so listeners can pattern-match instead
of substring-searching the error message.

## Connection naming

Workers tag every lifecycle event with a connection name. A worker on the
default connection uses that connection's name, which is by default the
driver's `name()` (e.g. `"memory"`, `"redis"`, `"database"`). Override it
with:

```rust
Queue::set_connection_name("orders-redis");
```

A worker started with `--connection reports` tags its events, and the
failed-job records it writes, with the name of that connection. See
[Connections](#connections).

## Testing

`Queue::fake()` installs the fake, and the assertions live in `queue::testing`.
`queue::testing::install_fake()` is the same call and returns the same guard:

```rust
let _guard = suprnova::Queue::fake();
my_code_that_dispatches_jobs().await;

suprnova::queue::testing::assert_pushed::<SendWelcomeEmail>(|j| j.user_id == 42);

// For delayed dispatches, pin the scheduled timestamp:
suprnova::queue::testing::assert_pushed_later::<SendWelcomeEmail>(|j, at| {
    j.user_id == 42 && at > chrono::Utc::now()
});
```

You assert absence with `assert_not_pushed::<J>(|job| job.id == 7)`.
`pushed::<J>()` and `assert_not_pushed` fail, naming the job and the decode
error, when a recorded payload of `J` doesn't decode as `J`, so neither passes
over a push it can't read. `try_pushed::<J>()` returns the error instead.
You filter a queue and its job together with
`assert_pushed_on_queue::<J>("emails", |job| job.id == 7)`. You pass
`|_| true` when you only need to check the queue. You match the per-push
queue override or the job's declared queue, including pushes without an override.

The fake guard serialises parallel tests via a process-wide mutex; it
captures `(payload, available_at, overrides)` per push and clears on
`Drop`. The `overrides` field is `EnvelopeOverrides::default()` for
every entry point except `push_with`/`later_with` - see
[Mocking](mocking.md#queue---queuefake) for
`assert_pushed_on_queue`/`assert_pushed_on_connection` and
`pushed_with_overrides`, the assertions over it. In fake mode,
`push_unique` always records the push as fresh - dedupe is irrelevant
when no driver is wired.

A debounced push behaves the same way: the fake writes nothing to the
cache, so no window is armed and the recorded `available_at` carries no
debounce delay. `assert_pushed_later` sees it as undelayed. What the
fake does still catch is a job declaring both `debounce_for` and
`unique_id` - that pair cannot hold whatever the environment is, so the
push returns an error under `Queue::fake()` exactly as it would in
production.

### Batches, chains and failed-job retries

Every path that would write to the driver records in the fake instead:
`Queue::batch()...dispatch()`, `Queue::chain()...dispatch()`,
`Queue::retry_failed` and `Queue::retry_all_failed`. None of them needs a
driver under the fake, and none writes to one that is installed, unless
[`except`](#letting-some-jobs-through) names the job.

- A batch records as a `FakedBatch` with its `id`, `name` and `jobs`. The
  repository still stores the batch, so the id you receive names a batch.
  No job runs, so the batch stays pending.
- A chain records as a `FakedChain` whose `links` run head first. A chain
  whose links resolve to different connections is refused under the fake, as
  it is in production.
- A retry records the retried envelope as a push. The failed-job record still
  leaves the store.

The jobs of a batch, the head of a chain and every retried job also record as
ordinary pushes, so `assert_pushed` sees them whichever path queued them.
Assert on the batch or the chain itself with these functions of
`queue::testing`:

```rust
use suprnova::queue::testing::{
    assert_batch_count, assert_batched, assert_chained, assert_nothing_chained,
    batched, chained,
};

let _guard = suprnova::Queue::fake();
import_users(vec![1, 2, 3]).await?;

assert_batch_count(1);
assert_batched(|batch| batch.name == "import-users" && batch.jobs.len() == 3);
assert_eq!(batched()[0].jobs_of::<ImportUser>().len(), 3);

assert_chained(&["GenerateReport", "UploadToBucket"]);
let report: Option<GenerateReport> = chained()[0].link::<GenerateReport>(0);
```

`assert_chained` takes the `Job::job_name()` of every link, head first, and
matches a chain made of exactly those jobs. `assert_nothing_batched` and
`assert_nothing_chained` assert the opposite. See
[Mocking](mocking.md#queue---queuefake) for the whole table.

You use `assert_pushed_without_chain::<J>(|job| predicate)` to assert that
a typed push of `J` matches your filter and carries no chain. A job pushed
on its own passes, and so does a batch member or a chain of one job. The head of a longer chain carries the
rest of the chain, so it does not:

```rust
use suprnova::queue::testing::assert_pushed_without_chain;

let _guard = suprnova::Queue::fake();
send_receipt(order_id).await?;

// The receipt went out on its own, not as the first step of a chain.
assert_pushed_without_chain::<SendReceipt>(|job| job.order_id == order_id);
```

### Letting some jobs through

`Queue::fake_except(&[...])` fakes every job except the ones named, which
reach the real queue as they would without the fake. Each name is a
`Job::job_name()`. `Queue::fake().except(&[...])` is the same call on the
guard, and calling `except` again adds to the names already excepted:

```rust
use std::sync::Arc;
use suprnova::Queue;
use suprnova::queue::SyncQueueDriver;
use suprnova::queue::testing::assert_pushed;

Queue::set_driver(Arc::new(SyncQueueDriver::new()));
let _guard = Queue::fake_except(&["ProvisionAccount"]);

activate_account(42).await?;

// ProvisionAccount ran on the sync driver; the welcome email was recorded.
assert_pushed::<SendWelcomeEmail>(|j| j.user_id == 42);
```

An excepted job takes the real path from end to end: it resolves its
connection, reaches the driver, emits `JobQueueing` and `JobQueued`, and fails
where a real push fails. A batch is still recorded with all of its jobs, and
only its excepted jobs reach the real queue. A chain whose first job is
excepted reaches the real queue, and the worker that runs that job dispatches
each later link through the fake, as Laravel does: a link `except` names
reaches the real queue, and any other link is recorded and does not run. A
raw push is always recorded, whatever `except` names, because a raw payload is
not a job type.

### Run a worker on the fake

`fake.driver()` returns a `QueueDriver` over the fake. A worker you run on it
reserves the recorded pushes and runs them, and the fake records each
reservation:

```rust
use suprnova::queue::testing::reserved;
use suprnova::{Queue, WorkerControls, run_worker_with_controls};
use tokio_util::sync::CancellationToken;

let fake = Queue::fake();
send_invoices().await?;

let controls = WorkerControls { stop_when_empty: true, ..Default::default() };
run_worker_with_controls(fake.driver(), Default::default(), controls, CancellationToken::new())
    .await?;

let invoices: Vec<SendInvoice> = reserved::<SendInvoice>();
let records = Queue::reserved_jobs(None).await?;
```

The driver follows these rules:

- It reserves the recorded pushes in push order, each once it is due, and
  filters by queue as the memory driver does.
- Each envelope is the one a real push builds: the job's own retry policy,
  the per-push overrides and the pusher's context, on the queue the fake
  recorded.
- A reservation lasts until the worker settles it. There is no visibility
  timeout. An `ack` takes the job off the fake's queue. A `nack` puts it back
  with one more attempt, and a `release` puts it back without one.
- A push to the driver, such as the next link of a chain, is recorded as a
  push. A raw push stays apart from the typed pushes, and the driver doesn't
  reserve it.
- The push records never change, so `pushed` still lists a job after a worker
  ran it.

`reserved::<J>()` returns every reservation of `J`, one entry per reservation,
so a job the worker retried once is listed twice. `Queue::reserved_jobs(queue)`
lists the same records as `InspectedJob`s, filtered by queue, and keeps them
after the jobs settle. `try_reserved::<J>()` returns a decode error as
`try_pushed` does. Once the guard drops, every method of the driver returns an
error.

### Raw pushes under the fake

Under the fake, [`Queue::push_raw`](#raw-pushes) records its payload and writes
no driver. Read the records back with `raw_pushes()`, every `RawPush` in push
order, or `pushed_raw(...)`, the ones a predicate accepts:

```rust
use suprnova::queue::testing::{pushed_raw, raw_pushes};

let _guard = suprnova::Queue::fake();
replay(lines).await?;

assert_eq!(raw_pushes().len(), 3);
let invoices = pushed_raw(|raw| raw.envelope().is_ok_and(|env| env.job_name == "SendInvoice"));
assert_eq!(invoices[0].queue.as_deref(), Some("replays"));
```

A `RawPush` holds the `payload` and the `queue` exactly as they were passed,
and `envelope()` decodes the payload. Raw pushes are kept apart from typed
pushes, as in Laravel: `pushed` and `assert_pushed` do not see them.

### Why Suprnova diverges

Laravel's `except` and `assertPushedWithoutChain` take class names. Rust has
no class name to pass at run time, so `except` takes `Job::job_name()`s, as
`assert_chained` and `EventFacade::fake_except` do, and
`assert_pushed_without_chain` takes the job type and a closure filter. You
assert only typed pushes with it; raw payloads remain separate. Laravel's
`QueueFake` does not record batches at all, so it has no rule for a batch
that mixes excepted and faked jobs; here the batch is recorded and each job
goes where `except` sends it.

Laravel's `QueueFake` restores a job from its serialized form only after
`serializeAndRestore()`, and its `pop` returns nothing, so a test marks a job
reserved by hand with `Queue::reserve($job)`. Suprnova records every push as
JSON and decodes it on every read, so a payload that doesn't decode always
fails the read. A real worker makes the reservations, through `fake.driver()`.

## Idempotency is the contract between the worker and you

Redis-backed queue drivers can't make `nack` atomic - `XADD` and `XACK`
are separate commands. A crash between them re-delivers the message via
`XAUTOCLAIM`. In-memory and database drivers are exactly-once-per-attempt,
but the worker loop doesn't distinguish drivers, so **every job handler
in a production deployment must be idempotent**.

For typical command-style jobs, wrap the handler body in
[`Idempotency::once`](idempotency.md) or
[`Idempotency::commit_on_success`](idempotency.md) keyed by a stable
per-operation key (entity id, caller-supplied request id, etc.). When a
retry must return the *original* outcome rather than skip re-execution,
use `Idempotency::remember`, which records the success value and
replays it on later deliveries.

## Next

- [Bus](bus.md) - synchronous dispatcher with typed results
- [Events](events.md) - pub/sub fan-out
- [Idempotency](idempotency.md) - the contract handlers honour for at-least-once delivery
- [Cache](cache.md) - backs `push_unique`, `WithoutOverlapping`, `RateLimited`
- [Mocking](mocking.md) - every fake guard, including `Queue::fake`


---

<!-- /docs/bus -->

# Bus

The Bus is Suprnova's **synchronous** command dispatcher. You define a
typed `Command` (`{ input, Output type }`), register a `Handler` for it at
boot, and then any code in the process can call `Bus::dispatch(cmd).await`
and get back a `Dispatched<T>` carrying the handler's typed result.

Bus pairs with [`Queue`](queues.md) - the asynchronous sibling. They are
two intentionally separate facades, not one routing dispatcher:

| If you want…                                          | Use            |
|-------------------------------------------------------|----------------|
| Run the work *now*, in this task, get the result back | `Bus`          |
| Push the work to a worker, retry on failure, durable  | `Queue`        |

The caller picks explicitly. Suprnova does not ship a `ShouldQueue`
marker - on Tokio both paths are non-blocking, so the explicit selection
is clearer and faster than implicit routing.

## Quick Start

Ten lines from command to dispatch:

```rust
use serde::{Deserialize, Serialize};
use suprnova::async_trait;
use suprnova::bus::command::{Command, Handler};
use suprnova::bus::Bus;
use suprnova::error::FrameworkError;

#[derive(Serialize, Deserialize)]
pub struct ChargeCustomer { pub customer_id: i64, pub cents: i64 }

#[async_trait]
impl Command for ChargeCustomer {
    type Output = String; // the charge id we got back
    fn command_name() -> &'static str { "ChargeCustomer" }
}

pub struct ChargeCustomerHandler;

#[async_trait]
impl Handler<ChargeCustomer> for ChargeCustomerHandler {
    async fn handle(&self, cmd: ChargeCustomer) -> Result<String, FrameworkError> {
        Ok(format!("charge-{}-{}", cmd.customer_id, cmd.cents))
    }
}

// At boot (once):
Bus::register::<ChargeCustomer, _>(ChargeCustomerHandler);

// In a request handler:
let charge_id = Bus::dispatch(ChargeCustomer { customer_id: 42, cents: 1999 })
    .await?
    .unwrap_executed();
```

## Defining Commands

A `Command` is any serializable struct with an associated `Output` type
and a unique `command_name()`:

```rust
#[async_trait]
pub trait Command: Serialize + DeserializeOwned + Send + Sync + 'static {
    type Output: Send + 'static;
    fn command_name() -> &'static str;
}
```

The `Output` is what the handler returns. It only has to be `Send +
'static` - the real dispatch path keeps values native via
`Box<dyn Any>`, no serde round-trip. That means non-serde outputs like
`Bytes`, opaque handles, or an `Arc<Mutex<…>>` round-trip back to the
caller as live values. The `Serialize + DeserializeOwned` bound on
`Command` itself is for the fake-capture path: `Bus::fake()` records
each dispatched command as a `serde_json::Value` so predicate-based
assertions (`assert_dispatched`, `assert_dispatched_times`) can decode
and inspect them.

`command_name()` should be a stable string unique per concrete `Command`
impl. It shows up in `assert_dispatched`/`assert_dispatched_times` failure
messages and in error returns when no handler is registered.

## Registering Handlers

A `Handler<C>` is a typed async function that takes the command and
returns `Result<C::Output, FrameworkError>`:

```rust
#[async_trait]
pub trait Handler<C: Command>: Send + Sync + 'static {
    async fn handle(&self, cmd: C) -> Result<C::Output, FrameworkError>;
}
```

Call `Bus::register::<C, H>(handler)` once per command type at boot. The
registry is global; re-registering the same `C` overwrites the previous
handler (tests rely on this to swap implementations) and emits a
`tracing::warn!` so a duplicate binding from two boot-time service
registrations is visible in the log.

```rust
Bus::register::<ChargeCustomer, _>(ChargeCustomerHandler);
Bus::register::<RefundCustomer, _>(RefundCustomerHandler);
```

## Dispatching

`Bus::dispatch::<C>(cmd)` runs the registered handler in-process and
returns a `Dispatched<C::Output>` enum:

```rust
pub enum Dispatched<T> {
    Executed(T),  // handler ran, here's the result
    Captured,    // Bus::fake() was active, handler did NOT run
}
```

`Dispatched<T>` has four helpers:

- `.unwrap_executed()` - return the value, panic on `Captured`
- `.executed() -> Option<T>` - convert to `Option`
- `.is_executed()` - bool predicate
- `.is_captured()` - bool predicate

For real-mode call sites, `.unwrap_executed()` is the idiomatic form.

### `Bus::chain` - sequential

`Bus::chain(Vec<C>)` runs commands one at a time, stopping on (and
including) the first error. All commands must be the same type. Returns
`Vec<Result<Dispatched<C::Output>, FrameworkError>>` - one entry per
command attempted.

```rust
let results = Bus::chain(vec![
    ChargeCustomer { customer_id: 1, cents: 100 },
    ChargeCustomer { customer_id: 2, cents: 200 },
    ChargeCustomer { customer_id: 3, cents: 300 },
]).await;

// Collect successful charge ids until the first failure:
let charge_ids: Vec<String> = results
    .into_iter()
    .filter_map(|r| r.ok().and_then(|d| d.executed()))
    .collect();
```

`Bus::chain` is homogeneous-only by design - the dispatcher returns
`Dispatched<C::Output>`, which is only well-typed when every input shares
one `Output`. For Laravel-style heterogeneous chains (mixed job types,
each step kicking off the next), use [`Queue::chain`](queues.md) - the
queue boxes each job into a typed envelope and so doesn't have the
same constraint.

### `Bus::batch` - concurrent

`Bus::batch(Vec<C>)` runs commands concurrently via `futures::join_all`
and collects results in input order. Same homogeneous-type constraint as
`chain`.

```rust
let results = Bus::batch(vec![
    SendWelcomeEmail { user_id: 1 },
    SendWelcomeEmail { user_id: 2 },
    SendWelcomeEmail { user_id: 3 },
]).await;
```

`Bus::batch` is homogeneous-only for the same reason as `chain`. For
heterogeneous, persisted batches with progress callbacks, lifecycle
events, and a `BatchRepository`, use [`Queue::batch`](queues.md).

## Testing

Install the fake at the top of the test with `Bus::fake()`.
`bus::testing::install_fake()` is the same call. Either one acquires a
process-wide mutex for the guard's lifetime, so two
parallel `Bus::fake()` tests can't clobber each other's captured-store -
the second blocks until the first guard drops. You still mark the
test `#[serial]` if a sibling test in the same binary calls real
`Bus::dispatch`: a real-dispatch caller doesn't acquire that mutex,
so without `#[serial]` it can race a parallel fake test and observe
`is_active() == true`. The mutex removes the fake-vs-fake hazard,
`#[serial]` removes the real-vs-fake one.

```rust
use serial_test::serial;
use suprnova::bus::Bus;
use suprnova::bus::testing::{
    assert_dispatched,
    assert_dispatched_times,
    assert_not_dispatched,
    assert_nothing_dispatched,
};

#[tokio::test]
#[serial]
async fn order_placed_dispatches_charge() {
    let _guard = Bus::fake();

    place_order(/* … */).await.unwrap();

    assert_dispatched::<ChargeCustomer>(|c| c.customer_id == 42);
    assert_dispatched_times::<ChargeCustomer>(|_| true, 1);
    assert_not_dispatched::<RefundCustomer>(|_| true);
}
```

The fake captures dispatched commands without running their handlers. A
`Bus::dispatch` call returns `Ok(Dispatched::Captured)` (no handler
output) instead of `Executed`. Real errors - encode/decode failures, a
missing registered handler before the fake was installed - still surface
as `Err(_)`.

`Bus::fake()` returns a `BusFakeGuard`. Drop it (it's RAII) and the
fake is cleared and the mutex is released. The typical
idiom is `let _guard = Bus::fake();` at the top of the test.

`Bus::fake()` covers `Bus::dispatch`. The persisted `Queue::batch` and
`Queue::chain` dispatchers go through `Queue::fake()` instead, which records
them for `assert_batched` and `assert_chained` - see
[Queues](queues.md#batches-chains-and-failed-job-retries).

### Assertion surface

| Assertion                                            | Asserts…                                                   |
|------------------------------------------------------|------------------------------------------------------------|
| `assert_dispatched::<C>(pred)`                       | at least one command of type `C` matching `pred`           |
| `assert_not_dispatched::<C>(pred)`                   | zero commands of type `C` matching `pred`                  |
| `assert_dispatched_times::<C>(pred, count)`          | exactly `count` commands of type `C` matching `pred`       |
| `assert_nothing_dispatched()`                        | zero commands of any type dispatched under the active fake |

All four panic with `Bus::fake() must be active` if no fake is installed.
The type-scoped ones panic with `expected … dispatched <command_name> …`
when the count doesn't match. `assert_nothing_dispatched` panics with
`expected no dispatched commands but found <n>`.

## When to use `Queue` instead

Reach for [`Queue`](queues.md) when you want any of:

- **Durability across restarts.** A queued job survives a process crash
  if the driver is `database` or `redis`.
- **Retries with backoff.** The queue worker applies `Job::max_tries` +
  `Job::backoff` (exponential / fixed / sequence) on each failure.
- **Per-job timeout.** `Job::timeout` + `Job::fail_on_timeout` are honored
  by the worker loop.
- **Delayed execution.** `Queue::later(duration, job)` or
  `Queue::push_later(job, at)`.
- **Dedupe / idempotency.** `Job::unique_id` + `Queue::push_unique`
  gates re-submissions for a configurable TTL.
- **Decoupling the caller from the worker.** Run jobs on a separate
  fleet of `cargo run --bin app -- queue:work` workers.

Reach for `Bus` when you want any of:

- **In-process, run-now.** No serialization across processes.
- **Typed result back to the caller.** `Dispatched<C::Output>` carries
  the handler's typed return value to the call site.
- **Synchronous composition.** A request handler that decomposes work
  into smaller `Command` calls and reads each result in sequence.

A typical app uses both: synchronous request paths dispatch
result-returning operations through `Bus`, and "fire and forget" /
durable work pushes through `Queue`.

## Next

- [Queues](queues.md) - async sibling, drivers, worker, retry policy,
  heterogeneous chains and batches
- [Events](events.md) - pub/sub dispatcher (one event → many listeners)
- [Workflows](workflows.md) - long-running stateful work that survives
  restarts, when a chain isn't enough
- [Testing](testing.md) - `#[suprnova_test]`, container fakes, and the
  process-wide serializer pattern used by `Bus::fake()`


---

<!-- /docs/rate-limiting -->

# Rate Limiting

Suprnova ships two complementary rate-limit surfaces:

| Surface | Use when... | Backend |
|---------|-------------|---------|
| `RateLimiterDriver` + `RateLimitMiddleware` | You want strict sliding-window enforcement against arbitrary storage (Redis ZSET, in-memory deque) | `dyn RateLimiterDriver` |
| `RateLimiter` + `ThrottleRequestsMiddleware` | You want Laravel-shape named limiters, `attempt()` workflow callbacks, or `X-RateLimit-*` response headers | `Cache` store (memory or Redis) |

The sliding-window driver is Suprnova's native shape - one slot per request, no separate timer key, atomic Lua eval on Redis. The Laravel facade is what migrated apps reach for and what the named-limiter / response-callback pattern requires. The two coexist by design, and a route can layer both.

## Sliding-window driver SPI

`RateLimiterDriver` is the storage SPI for the sliding-window algorithm. Each key tracks a deque of hit timestamps. On every `try_acquire`, entries older than `now - window` are evicted; if the remaining count is below `max_requests`, `now` is appended and the call accepts. Otherwise it rejects.

```rust
use std::sync::Arc;
use std::time::Duration;
use suprnova::rate_limit::memory::InMemoryRateLimiter;
use suprnova::rate_limit::{RateLimiterDriver, SlidingWindowConfig};

let limiter: Arc<dyn RateLimiterDriver> = Arc::new(InMemoryRateLimiter::new());
let cfg = SlidingWindowConfig {
    max_requests: 60,
    window: Duration::from_secs(60),
};
let ok = limiter.try_acquire("user:42", &cfg).await?;
if !ok {
    let wait = limiter.retry_after("user:42", &cfg).await?;
    // wait is the Option<Duration> until the oldest slot in the bucket
    // ages out.
}
```

### Built-in drivers

| Driver | Storage | Selected via |
|--------|---------|--------------|
| `InMemoryRateLimiter` | Per-process sharded map of buckets: a request locks only its key's shard, and the sweep of inactive buckets locks one shard at a time. It reads `tokio::time::Instant` so `start_paused` tests can drive the clock (it does not follow `TestClock`) | `RATE_LIMIT_DRIVER=memory` (default) |
| `RedisRateLimiter` | Redis ZSET + Lua atomic check-and-record; it reads `suprnova::clock::now()`, so `TestClock` moves its window ([Moving the clock](testing.md#moving-the-clock)) | `RATE_LIMIT_DRIVER=redis` + `RATE_LIMIT_REDIS_URL` |

`bootstrap_from_env()` wires the matching driver into the container. Outside production an unknown driver value falls back to memory with a `warn!` log.

### Production fails closed on the in-memory driver

In production, resolving to the in-memory limiter is a boot failure:

```
refusing to boot in production: RATE_LIMIT_DRIVER is unset, which defaults
to the in-memory limiter. Per-process buckets mean every configured quota
is multiplied by your replica count and reset by every deploy...
```

The in-memory driver keeps its buckets in one process's heap. Behind N
replicas each keeps its own count, so a "5 attempts per 15 minutes"
password-reset throttle is really 5N, and every deploy resets all of them
to zero. The limit you configured is not the limit you get - and nothing
says so, because the requests succeed, which is what a working throttle
looks like from the outside. It surfaces as a credential-stuffing or
account-enumeration incident, not as an error.

An **unrecognised** driver value fails for the same reason: it falls back
to memory. `RATE_LIMIT_DRIVER=Redis` - capitalised - would otherwise warn
once at boot and quietly leave a multi-replica deployment throttling
per-process. That is the case most likely to reach production, because it
looks configured.

Either point it at Redis:

```env
RATE_LIMIT_DRIVER=redis
RATE_LIMIT_REDIS_URL=redis://cache.internal:6379
```

or, if you genuinely run a single process, say so:

```env
RATE_LIMIT_ALLOW_MEMORY_IN_PRODUCTION=true
```

Development, testing and **staging** are untouched. Staging is
deliberately not gated, on the same reasoning as the mail guard: hard
failing it pushes teams to set the override globally, which disarms the
check exactly where it matters.

### `RateLimitMiddleware`

The HTTP wrapper around the driver. Construct with a `key_fn` closure to drive bucket selection per-request:

```rust
use std::sync::Arc;
use std::time::Duration;
use suprnova::container::App;
use suprnova::rate_limit::{
    BackendErrorPolicy, RateLimitMiddleware, RateLimiterDriver, SlidingWindowConfig,
};

let limiter: Arc<dyn RateLimiterDriver> =
    App::resolve_make::<dyn RateLimiterDriver>().unwrap();

let mw = RateLimitMiddleware::new(
    limiter,
    SlidingWindowConfig {
        max_requests: 100,
        window: Duration::from_secs(60),
    },
    |req| format!("route:{}", req.path()),
)
.on_backend_error(BackendErrorPolicy::FailClosed);
```

On rejection (over quota) it returns HTTP 429 with a `Retry-After` header.

### Per-address limit with `ip_based`

`RateLimitMiddleware::ip_based(max_requests, window)` allows each client address `max_requests` requests in `window`. It is the limit a login form or a public API needs, and it takes no key function and no driver:

```rust
use std::time::Duration;
use suprnova::rate_limit::RateLimitMiddleware;

let twenty_a_minute = RateLimitMiddleware::ip_based(20, Duration::from_secs(60));
```

The arguments are a `u32` request count and a `Duration`. Three details matter:

- **The driver is the installed one.** The middleware uses the rate limiter your application installed, which `RATE_LIMIT_DRIVER` selects. It looks the limiter up when a request arrives, so you can build the middleware where you register routes, before the drivers boot. When no limiter is installed the lookup fails as a backend error, and [the backend-error policy](#backend-error-policy) decides what the request gets.
- **The key names the address and the limit.** The address is [`Request::ip()`](requests.md#host-scheme-ip), which resolves through the trusted proxies. The key also carries the limit's numbers, so two limits with different numbers never share a bucket. Two limits with the same numbers share one, so the budget belongs to the client, whichever route spends it.
- **A request with no address gets a bucket of its own.** One shared bucket for all such requests would let one caller use it up and lock the others out. Every request the server accepts has a peer address, so only an in-process request has none.

`.on_backend_error(...)`, `.only_when(...)` and `.key_reads_body(...)` chain onto it as they do onto `RateLimitMiddleware::new`. Set up [`APP_TRUSTED_PROXIES`](#the-client-address-behind-a-proxy) before you deploy behind a proxy, or every client shares one bucket.

### Capping open connections with `connections_per_ip`

`ip_based` counts how often a client asks. It does not count what a client holds. A WebSocket is asked for once and then stays open, so a client that opens sockets and keeps them can use all the connections the server accepts. `RateLimitMiddleware::connections_per_ip(max)` gives each client address `max` open connections and refuses the next one with `429 Too Many Requests`. Put it on a WebSocket route:

```rust
use suprnova::rate_limit::RateLimitMiddleware;
use suprnova::ws;

ws!("/ws/broadcast", Broadcast).middleware(RateLimitMiddleware::connections_per_ip(100));
```

It returns a `ConnectionsPerIp`, which is a `Middleware`. What it counts and how it answers:

- **What is counted on a WebSocket route.** A socket counts from the moment the middleware lets the upgrade pass until the session of the socket ends, which is when the handler has returned and the close handshake is done. If a later middleware refuses the upgrade, the place is given back at once. A peer that vanishes without closing holds its place until the handler notices, which is when a read or a write on the socket fails.
- **What is counted on any other route.** A request, while it is handled. The place is given back when the handler drops or consumes the request, and reading the body consumes it. A connection that is kept alive and idle is not counted, and a streamed response, such as server-sent events, outlives its place. Use this cap for WebSocket routes.
- **The answer.** A request over the cap gets status `429` with the body `429 Too Many Requests`. It carries no `Retry-After` header, because nothing says when a socket will close.
- **The counts are per process.** They are kept in the memory of one process, which is the right place: the sockets an address holds in a process are what that process runs out of. Behind several replicas each replica counts for itself, so the cap for one address is `max` for each replica.
- **IPv6 addresses count by /64.** An IPv4 address counts by itself. An IPv6 address counts with its /64 network, because a subscriber line gets a /64 or more and a count for each of its addresses would be no cap. An IPv4 address written in IPv6 form, `::ffff:203.0.113.1`, counts as the IPv4 address.
- **The address is `Request::ip()`.** It reads the forwarded headers of a trusted proxy and of nobody else. A request with no address to resolve is not counted. If you run your own accept loop, pass the peer address with `suprnova::server::handle_request_with_peer`. Through `handle_request` no request has an address, and nothing is capped.

A clone of a `ConnectionsPerIp` shares its counts, so one cap can guard several routes. `open_for(address)` returns the connections an address holds through the cap right now, counted by /64 for IPv6, which is useful in a test or a diagnostic.

The middleware counts through `Request::hold_for_connection(hold)`. That method takes a guard value whose `Drop` gives the place back, and keeps it on the request. For a WebSocket upgrade the server moves the guards into the task that runs the socket and drops them when the task ends. For any other request they drop with the request. Use it in your own middleware when you take something that a connection has to give back:

```rust
use suprnova::{async_trait, Middleware, Next, Request, Response};

struct Slot(std::sync::Arc<std::sync::atomic::AtomicUsize>);

impl Drop for Slot {
    fn drop(&mut self) {
        self.0.fetch_sub(1, std::sync::atomic::Ordering::SeqCst);
    }
}

struct CountOpen(std::sync::Arc<std::sync::atomic::AtomicUsize>);

#[async_trait]
impl Middleware for CountOpen {
    async fn handle(&self, mut request: Request, next: Next) -> Response {
        self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        request.hold_for_connection(Slot(self.0.clone()));
        next(request).await
    }
}
```

`hold_for_connection` needs `&mut Request` and a value that is `Send + Sync + 'static`.

### Limiting per recipient, not just per caller

An address-keyed limit answers *is one client making too many requests*. It cannot answer *is one mailbox being flooded*. An attacker spread across a botnet, a proxy pool, or a single IPv6 `/64` stays under every per-IP budget while sending one victim thousands of password-reset emails - the inbox is the resource being exhausted, and the victim's address is the only thing those requests share. The reverse hurts too: behind carrier-grade NAT or an office gateway, per-IP limits punish a crowd for one member's behaviour.

`identity_key` keys a bucket on the account being *acted on*:

```rust
use suprnova::rate_limit::{identity_key, names_identity};

let per_recipient = RateLimitMiddleware::new(
    limiter.clone(),
    SlidingWindowConfig { max_requests: 3, window: Duration::from_secs(900) },
    |req| identity_key(req, "email", "auth-issuance"),
)
.key_reads_body(4096)
.only_when(|req| names_identity(req, "email"))
.on_backend_error(BackendErrorPolicy::FailClosed);
```

Stack it *alongside* a per-IP limiter rather than replacing one with the other. Each catches what the other cannot: per-IP stops one host enumerating many addresses; per-recipient stops many hosts targeting one address.

Four details carry the security:

- **`key_reads_body`** buffers the body (to the given cap) before the key is computed, so the field can be read out of a form-encoded POST, or a top-level string field of a JSON body, as well as a query string. It is opt-in because buffering is work an unauthenticated caller gets to make you do; the cap bounds it. A body over the cap is rejected with 413 rather than passed through unkeyed - otherwise padding the body would be a way out of the limit.
- **Both places are read, and they must agree.** A blank `?email=` does not hide the address in the body. A request whose query string and body name two different addresses is ambiguous - the handler reads one of them, and the key cannot know which - so every such request shares one bucket. It is also refused by, and counted against, the bucket of each address it names. A decoy in the place the handler ignores therefore cannot buy a fresh quota, and an address that has spent its own bucket gets no extra attempt through the shared one. No legitimate client is affected, because none sends two different addresses.
- **`only_when`** skips the limiter for requests that name nobody. Without it those fall into `identity_key`'s address fallback and are counted against *this* limiter's quota - and since a per-recipient budget is normally the tighter of the pair, it would silently become the binding limit for every route that names no one.
- **The value is normalised and hashed.** `Alice@Example.com` and `alice@example.com` reach the same mailbox and must share a bucket, or the limit is bypassed by changing capitalisation. The result is hashed because a rate-limit backend is frequently a shared Redis with weaker access control than the primary database, and a key dump should not read as a list of who is resetting their password.

### Backend-error policy

`BackendErrorPolicy` governs what happens when the limiter *backend* itself errors - e.g. Redis is unreachable - as distinct from a request legitimately exceeding its quota. The backend cannot make a decision, so the middleware must choose between availability and the limit's guarantee.

| Policy | Behaviour | When to use |
|--------|-----------|-------------|
| `FailOpen` (default) | Pass the request through; log at `warn` | Most public APIs - a limiter outage should not take down traffic |
| `FailClosed` | Reject with HTTP 503 + `Retry-After: 1`; log at `error` | Sensitive routes (login, password reset, payments) where unbounded traffic during a backend outage is worse than briefly rejecting |

Choose with `.on_backend_error(BackendErrorPolicy::FailClosed)` on the middleware. Quota-exhausted requests are always 429 regardless of the policy - the policy only affects backend-error fallthrough.

## Cache-backed Laravel-shape facade

`RateLimiter` (the struct) mirrors `Illuminate\Cache\RateLimiter`. It's a fixed-window counter built on top of the Suprnova [`Cache`](cache.md) facade. Use it for named limiters, `attempt()` workflows, or any time you want the `X-RateLimit-*` headers Laravel apps expect.

### Storage layout

For an attempt counter key `K` with decay of `D` seconds:

- `K` - i64 counter incremented by every `hit`. Initial seed is 0 (via `Cache::add`).
- `K:timer` - i64 unix-seconds-since-epoch when the window ends, set via `Cache::add` so only the first caller in a window pins the deadline.

Both keys carry the same TTL so the cache cleans them up automatically when the window ends. When the counter has reached `max_attempts` but the `:timer` is gone, `too_many_attempts` resets the counter - this is what makes the window slide forward after a quota-exhausted period.

### Counter API

```rust
use suprnova::RateLimiter;

// Burn one attempt; seeds the window if missing.
let n = RateLimiter::hit("login:1.2.3.4", 60).await?;

// Laravel's `hit($key)` defaults to a 60-second window; this is that call.
let n = RateLimiter::hit_for_minute("login:1.2.3.4").await?;

// Burn one attempt in a window that ends at a given time. A time that has
// already passed opens no window: the hit counts in a window that is
// already open, and leaves no count behind otherwise.
let window_end = suprnova::chrono::Utc::now() + suprnova::chrono::Duration::hours(2);
let n = RateLimiter::hit_until("exports:user:1", window_end).await?;

// Burn one attempt AND test the limit in a single atomic round-trip.
// Returns `true` when this hit pushed the bucket over `max` (refuse the
// request), `false` when it was admitted. Use this instead of a separate
// `too_many_attempts` + `hit` pair: checking and then hitting as two calls
// lets concurrent requests slip past the limit (a check-then-act race).
// `i64::MAX` as the max means "unlimited" - always admits, still counts.
let over_limit = RateLimiter::hit_and_check("login:1.2.3.4", 5, 60).await?;
if over_limit { /* return 429 */ }

// Increment by N; useful for "cost-weighted" limits (each request burns
// more than one attempt).
let n = RateLimiter::increment("api:user:1", 60, 5).await?;

// Read the current count (0 when never hit or expired).
let attempts = RateLimiter::attempts("login:1.2.3.4").await?;

// Number of seconds until the window reopens (0 when no window open).
let secs = RateLimiter::available_in("login:1.2.3.4").await?;

// Retries left before tripping.
let remaining = RateLimiter::remaining("login:1.2.3.4", 5).await?;
// retries_left is the Laravel-spelt alias of remaining.
let remaining = RateLimiter::retries_left("login:1.2.3.4", 5).await?;

// Is the bucket over its limit RIGHT NOW (with window still open)?
let over = RateLimiter::too_many_attempts("login:1.2.3.4", 5).await?;

// Drop only the counter (timer stays - the window is still pinned).
RateLimiter::reset_attempts("login:1.2.3.4").await?;

// Drop both counter and timer.
RateLimiter::clear("login:1.2.3.4").await?;
```

### `attempt()` workflow

Run a callback only when the bucket is under quota; the hit is only burned when the callback runs:

```rust
let result = RateLimiter::attempt(
    "login:1.2.3.4",
    5,
    || async { do_login_work().await },
    60,
).await?;
match result {
    Some(value) => { /* callback ran, attempt counted */ }
    None => { /* over limit, callback was NOT run */ }
}
```

This is the right shape for login forms - you don't burn an attempt unless the work actually reached the callback.

### Named limiters

Register at boot, resolve at request time. The Laravel-side name `for` is a Rust reserved keyword, so the primary Rust-side name is `define`; the literal Laravel alias is exposed via `r#for`.

```rust
use suprnova::{Limit, RateLimiter};

// At boot - `define` is the primary Rust-side name.
RateLimiter::define("api", |req| {
    // `req.ip()`, not the raw `X-Forwarded-For` header - see below.
    let key = req.ip().unwrap_or_else(|| "anon".into());
    Limit::per_minute(60).by(format!("ip:{key}")).into()
});

// Laravel-side alias - same thing under the keyword-escape spelling.
RateLimiter::r#for("uploads", |_req| Limit::per_hour(100).into());

// Resolve.
let cb = RateLimiter::limiter("api").unwrap();
let limit_result = cb(&request);
```

A named-limiter callback returns a [`LimitResult`], constructible from:

- A single `Limit` - apply this limit.
- A `Vec<Limit>` - apply every limit; first to trip wins.
- An `HttpResponse` - short-circuit immediately with this response (used for "admin gets unlimited access" via `Limit::none()`, or to refuse the request outright).

`RateLimiter::limiter(name)` returns a callback that wraps the one you registered, as Laravel's does. When the result holds several limits and two or more of them share a key, each of those limits gets its `fallback_key()` instead, `<key>:attempts:<max>:decay:<seconds>`. Otherwise a per-minute limit and a per-hour limit on the same key count in one bucket, and the minute's limit trips on the hour's hits:

```rust
RateLimiter::define("api", |req| {
    let ip = req.ip().unwrap_or_else(|| "anon".into());
    vec![
        Limit::per_minute(60).by(ip.clone()),
        Limit::per_day(10_000).by(ip),
    ]
    .into()
});

// For the address 203.0.113.5, the two limits count under
// `203.0.113.5:attempts:60:decay:60` and `203.0.113.5:attempts:10000:decay:86400`.
```

`ThrottleRequestsMiddleware::by_name("api")` resolves the limiter through the same method and counts each limit under `api:<key>`, so the middleware and your own code read the same buckets: `RateLimiter::attempts("api:203.0.113.5:attempts:60:decay:60")` is the count the middleware keeps.

Limits that end up with one key share one bucket, and the middleware counts a request in it once for each of those limits, as Laravel's `ThrottleRequests` hits a key once for each limit:

- Two limits with the same key, maximum and window get the same fallback key. Two `Limit::per_minute(2).by("a")` limits count a request twice under `api:a:attempts:2:decay:60`, so they admit one request a minute.
- Keys are compared as written, as Laravel compares them, so `café` and `cafe` keep their keys. They clean to one bucket (see [Sanitising keys](#sanitising-keys)), which counts a request once for each limit, and `RateLimiter::attempts("api:cafe")` reads it.

### Sanitising keys

Every counter method cleans its key with `RateLimiter::clean_rate_limiter_key(key)` before it touches the cache, as Laravel's `cleanRateLimiterKey` does. The key is first encoded as PHP's `htmlentities` encodes it under its default flags: each character with a named HTML 4.01 entity becomes that entity, `&`, `<`, `>`, and `"` included, and `'` becomes `&#039;`. Then each `&name;` marker of two or more letters is reduced to its first letter. So `café` and `cafe` count in one bucket, and a key is stored as a Laravel application sharing the cache store stores it.

```rust
use suprnova::RateLimiter;

assert_eq!(RateLimiter::clean_rate_limiter_key("café"), "cafe");
assert_eq!(RateLimiter::clean_rate_limiter_key("a&b"), "aab");
assert_eq!(RateLimiter::clean_rate_limiter_key("Ω"), "O");
// Entities named with digits, and the apostrophe, stay encoded.
assert_eq!(RateLimiter::clean_rate_limiter_key("x²"), "x&sup2;");
assert_eq!(RateLimiter::clean_rate_limiter_key("it's"), "it&#039;s");
```

Cleaning a cleaned key changes it again (`it&#039;s` cleans to `ita#039;s`), so pass the raw key to `hit`, `attempts`, and the other counter methods.

## `Limit` builder

The data type returned by named-limiter callbacks. Shorthand constructors mirror Laravel's `Limit::per*`:

```rust
use suprnova::Limit;
use std::time::Duration;

Limit::per_second(10, 1);           // 10 per 1 second (max_attempts, decay_seconds)
Limit::per_minute(60);              // 60 per minute
Limit::per_minutes(5, 100);         // 100 per 5 minutes (decay-first, Laravel signature)
Limit::per_hour(1_000);             // 1000/hr
Limit::per_hours(6, 5_000);         // 5000 per 6 hours
Limit::per_day(10_000);             // 10000/day
Limit::per_days(7, 50_000);         // 50000 per 7 days
Limit::new(123, Duration::from_secs(45));  // bare ctor

// Builder chain.
let l = Limit::per_minute(5)
    .by("user:42")
    .response(|req| {
        suprnova::HttpResponse::text("blocked").status(429)
    })
    .after(|response| response.status_code() >= 400);
```

- `.by(key)` - set the bucket key. Empty key is "global" (every caller shares one bucket).
- `.response(callback)` - generate a custom response when the limit trips; the default is plain 429 "Too Many Attempts.".
- `.after(callback)` - only burn the attempt when `callback(response)` returns true. Canonical use: only count failed logins (`after(|r| r.status_code() >= 400)`).

`Limit::none()` returns an `Unlimited` (a `GlobalLimit` with `max_attempts = i64::MAX`). Returning it from a named limiter is the Laravel pattern for bypass. `GlobalLimit` itself is a thin wrapper around `Limit` with an empty key, kept for parity with `Illuminate\Cache\RateLimiting\GlobalLimit`.

## `ThrottleRequestsMiddleware`

HTTP wrapper around the Cache-backed facade. Mirrors `Illuminate\Routing\Middleware\ThrottleRequests`. Four constructors:

```rust
use suprnova::{Limit, ThrottleRequestsMiddleware};

// The default limit - 60 requests a minute; see below.
ThrottleRequestsMiddleware::default();

// Named limiter - resolves at request time via RateLimiter::limiter(name).
ThrottleRequestsMiddleware::by_name("api");

// Inline max/decay/prefix - the literal Laravel `throttle:60,1` shape,
// counted for each signed-in user, or each address, on each path.
ThrottleRequestsMiddleware::with(60, 1, "myroute");

// Explicit list of Limits - first-to-trip wins; most Rust-idiomatic.
ThrottleRequestsMiddleware::with_limits(vec![
    Limit::per_hour(5_000).by("user:1"),
    Limit::per_minute(60).by("user:1"),
]);
```

`.prefix(...)` sets a key prefix on any of them. The limits of `with_limits` that share a key count under their fallback keys, as a named limiter's do, so the two limits above count under `user:1:attempts:5000:decay:3600` and `user:1:attempts:60:decay:60`.

### The default limit

`ThrottleRequestsMiddleware::default()` allows 60 requests a minute. The constants `DEFAULT_MAX_ATTEMPTS` (`60`) and `DEFAULT_DECAY_SECONDS` (`60`) hold the numbers. It is the shape of Laravel's default `api` limiter: `Limit::perMinute(60)->by($request->user()?->id ?: $request->ip())`.

The bucket is one for each signed-in user, and one for each client address when nobody is signed in. The two are spelled apart, as `user:<id>` and `ip:<address>`, so a user whose id reads like an address shares no bucket with it. The user's bucket follows the user across routes and across addresses, and the address's bucket is shared by every route, as in Laravel. `with(...)` differs: it counts per user or address, and per path, under `user:<id>:path:<path>` or `ip:<address>:path:<path>`. Use `.prefix(...)` to give a group of routes a budget of its own.

The user is the one the default guard signed in. Run the session middleware before this one, or a signed-in user counts as an address. The address is `Request::ip()`, so [the trusted proxies](#the-client-address-behind-a-proxy) apply.

### Named aliases

A route can name a throttle instead of building one. `ThrottleRequestsMiddleware::from_alias_args` reads the arguments of the alias the way Laravel reads `throttle:60,1`. Register it once at boot, then name it on routes with `.middleware_named(...)`:

```rust
use suprnova::middleware::register_middleware_alias_with_args;
use suprnova::{Router, ThrottleRequestsMiddleware};

register_middleware_alias_with_args("throttle", ThrottleRequestsMiddleware::from_alias_args);

let router = Router::new()
    .post("/login", login)
    .middleware_named("throttle:5,1");
```

| A route writes | It gets |
|---|---|
| `throttle` | `ThrottleRequestsMiddleware::default()` |
| `throttle:60` | 60 requests a minute, as `with(60, 1, "")` |
| `throttle:60,5` | 60 requests in 5 minutes |
| `throttle:60,5,uploads` | the same, with the key prefix `uploads` |
| `throttle:10\|60,1` | 10 requests a minute for a guest, 60 for a signed-in user |
| `throttle:api` | the limiter named `api`, as `by_name("api")` |

The numeric forms count each signed-in user in a bucket of their own on each path, whatever address they connect from, and each guest by address. A first argument of two whole numbers joined by `|` is the guest's limit and the signed-in user's, as Laravel's `resolveMaxAttempts` reads it. Any other first argument that is not a number names a limiter, and a limiter takes no further arguments. The alias refuses a number that does not parse, a limit or a window of zero (either half of `<guest>|<user>` included), and more than three arguments. The route that names it then fails to register. See [Middleware](middleware.md#named-aliases-and-groups) for how names resolve.

Wire it into a route group:

```rust
use suprnova::{Limit, RateLimiter, Router, ThrottleRequestsMiddleware};

RateLimiter::define("api", |req| {
    Limit::per_minute(60)
        .by(req.ip().unwrap_or_else(|| "anon".into()))
        .into()
});

let router = Router::new()
    .get("/api/items", list_items)
    .post("/api/items", create_item)
    .middleware(ThrottleRequestsMiddleware::by_name("api"));
```

### The client address behind a proxy

Key a limit on `req.ip()`, never on the header. `X-Forwarded-For` is caller-supplied. A limiter keyed on the raw header is defeated by sending a different value on each request - the attacker picks their own bucket, so the quota is per-request rather than per-client.

`Request::ip()` is the safe read. It returns the TCP peer address unless the peer is listed in `APP_TRUSTED_PROXIES`. When the peer is a trusted proxy, `req.ip()` reads the client address from the **right** of `X-Forwarded-For`:

1. It starts at the rightmost entry, which the peer wrote.
2. It skips each entry that is a trusted proxy.
3. It returns the first entry that is not a trusted proxy. That entry is the client. Nothing to its left was written by a proxy you trust.

Every proxy hop must be in the list. A proxy adds the address it saw to the right end of the header, and the client's own value stays at the left end. If a hop is missing from the list, `req.ip()` stops at that hop and takes it for the client, so every client behind it shares one address and one bucket. Behind a content delivery network in front of a proxy of your own, list the network's edge too.

`APP_TRUSTED_PROXIES` takes addresses and ranges in CIDR form, separated by commas:

```env
APP_TRUSTED_PROXIES=10.0.0.5,173.245.48.0/20,2400:cb00::/32
```

Four more rules apply:

- **A range must hold proxies and nothing else.** A client that connects from a listed range is believed like a proxy, and it writes the address `req.ip()` returns. The network of your cluster's pods and the range of a VPN have clients in them.
- **`/0` is refused.** A range of every address, such as `0.0.0.0/0`, makes every client a trusted proxy. Boot fails on it, as it does on an entry that is neither an address nor a range.
- **`X-Real-IP` is read only when there is no `X-Forwarded-For`.** With both headers present, `X-Real-IP` is ignored. A proxy that sets `X-Real-IP` and nothing else has to remove the client's `X-Forwarded-For` from the request.
- **The proxy has to write the header.** A proxy that adds to `X-Forwarded-For` or replaces it is a proxy to list. A proxy that passes the client's header on unchanged is not, because the client then writes all of it. The `Forwarded` header of RFC 7239 is not read.

An entry that is not an address, such as `unknown`, ends the walk, and `req.ip()` returns the proxy that wrote that entry. The clients of such a proxy share its address, and one limit.

The corollary matters as much: with `APP_TRUSTED_PROXIES` unset - the default - `req.ip()` behind a terminating proxy returns *the proxy's* address on every request, and every per-IP limit in the app collapses into a single shared bucket. `ThrottleRequestsMiddleware::with(20, 1, "login")` then means 20 attempts a minute across all users combined, which any one caller can spend to lock everybody out. Deploying behind nginx, Traefik, an ALB or Cloudflare means setting [`APP_TRUSTED_PROXIES`](env-vars.md#behind-a-reverse-proxy-set-app_trusted_proxies). See [Requests](requests.md#host-scheme-ip) for the full order in which `ip()` reads the request.

### Response headers

Every wrapped response carries one pair:

- `X-RateLimit-Limit` - the configured `max_attempts`.
- `X-RateLimit-Remaining` - retries left for this bucket.

Behind several limits, the pair is the one of the limit with the fewest retries left. When your handler sets `X-RateLimit-Remaining` itself, at or below that count, the middleware leaves your headers alone; above it, the middleware replaces them.

429 responses additionally carry:

- `Retry-After` - seconds until the window reopens.
- `X-RateLimit-Reset` - unix-seconds-since-epoch when the bucket reopens.

This matches Laravel's `ThrottleRequests::getHeaders` shape exactly.

### Refused requests

The middleware checks every limit before it counts a request, as Laravel does, and a request it refuses there leaves every bucket's count where it was. After `throttle:2,1` refuses a third request, the count is still `2`, so a client that keeps retrying a refused request doesn't keep its own window full.

The middleware then counts each bucket with one conditional increment, which counts the request only while the bucket has room and refuses it without counting when the bucket is full. The cache store compares and counts in one atomic step, so a burst of concurrent requests admits at most the limit. A request that passes the check beside concurrent requests and then finds the bucket full is refused, and that bucket's count stays where it was. The middleware never takes a count back: a decrement can't be tied to the window it would undo, and if that window ended first, the decrement would land in the next window and let it admit one request too many.

A bucket counted earlier in the same request keeps its count when a later limit refuses the request, as in Laravel, which counts every limit of a request that passes its check. That count can refuse a request early but never admits one. The middleware counts the bucket with the fewest places left first, so the bucket that runs out is usually the first one counted.

The step is `RateLimiter::increment_if_below(key, decay_seconds, amount, ceiling)`, built on [`Cache::increment_if_below`](cache.md#atomic-counters). Call it yourself to count a hit only while a bucket has room.

### Missing named limiter

When a route is wired to `by_name("X")` but no limiter under `X` has been registered, the middleware returns HTTP 503 with a body that names the missing limiter. Laravel throws `MissingRateLimiterException`; we surface it as an HTTP response so a misconfigured boot does not panic the worker thread.

### Driver-vs-facade composition

The two middlewares can coexist on a single router. Layer the sliding-window driver for low-level fairness, then the Cache-backed throttle for per-endpoint named limits:

```rust
let router = Router::new()
    .get("/api/items", list_items)
    .middleware(RateLimitMiddleware::new(limiter_driver, cfg, key_fn))
    .middleware(ThrottleRequestsMiddleware::by_name("api"));
```

## Configuration

The driver SPI is configured via environment variables; the Cache-backed facade is configured wherever your [`Cache`](cache.md) store is configured (memory or Redis).

| Variable | Used by | Default |
|----------|---------|---------|
| `RATE_LIMIT_DRIVER` | Driver SPI bootstrap | `memory` (refused in production - see above) |
| `RATE_LIMIT_ALLOW_MEMORY_IN_PRODUCTION` | Production fail-closed override | unset |
| `RATE_LIMIT_REDIS_URL` | Redis driver | `redis://127.0.0.1:6379` |
| `RATE_LIMIT_PREFIX` | Redis key prefix | `suprnova:` |
| `CACHE_DRIVER` / `REDIS_URL` / `CACHE_DEFAULT_TTL` / `REDIS_PREFIX` / `CACHE_PREFIX` | Cache-backed `RateLimiter` facade (see [`Cache`](cache.md)) | various |

## Migration from Laravel

| Laravel | Suprnova |
|---------|----------|
| `RateLimiter::for('api', fn ($req) => Limit::perMinute(60))` | `RateLimiter::define("api", \|req\| Limit::per_minute(60).into())` or `RateLimiter::r#for(...)` |
| `RateLimiter::hit($key, $decay)` | `RateLimiter::hit(key, decay).await?` |
| `RateLimiter::hit($key)` | `RateLimiter::hit_for_minute(key).await?` |
| `RateLimiter::hit($key, $date)` | `RateLimiter::hit_until(key, date).await?` |
| `RateLimiter::tooManyAttempts($key, $max)` | `RateLimiter::too_many_attempts(key, max).await?` |
| `RateLimiter::availableIn($key)` | `RateLimiter::available_in(key).await?` |
| `RateLimiter::attempt($key, $max, $cb, $decay)` | `RateLimiter::attempt(key, max, \|\| async { ... }, decay).await?` |
| `RateLimiter::retriesLeft($key, $max)` | `RateLimiter::retries_left(key, max).await?` |
| `RateLimiter::cleanRateLimiterKey($key)` | `RateLimiter::clean_rate_limiter_key(key)` |
| `Limit::perMinute(60)->by($ip)->response(fn () => abort(429))` | `Limit::per_minute(60).by(ip).response(\|_\| HttpResponse::text("...").status(429))` |
| `Limit::perMinutes(3, 100)` | `Limit::per_minutes(3, 100)` |
| `Limit::none()` | `Limit::none()` |
| `throttle:api` middleware | `.middleware_named("throttle:api")` or `ThrottleRequestsMiddleware::by_name("api")` |
| `throttle:60,1` middleware | `.middleware_named("throttle:60,1")` with `from_alias_args` registered, or `ThrottleRequestsMiddleware::with(60, 1, "")` |
| `throttle:10\|60,1` middleware | `.middleware_named("throttle:10\|60,1")` with `from_alias_args` registered |
| `throttle` middleware (the default limit) | `ThrottleRequestsMiddleware::default()` |
| `X-RateLimit-Limit/Remaining/Reset` + `Retry-After` headers | Same headers, same shape |

### Why Suprnova diverges

Laravel ships one shape: `Illuminate\Cache\RateLimiter` (Cache-backed fixed-window counter) with `Illuminate\Routing\Middleware\ThrottleRequests` as its HTTP wrapper. Suprnova ships both that shape *and* a native sliding-window driver SPI because two real questions need two real answers.

A Cache-backed counter is the right answer to "I have named limiters, response callbacks, after-callbacks for failed-login-only counting, and I want to be source-compatible with Laravel migrations." It's the wrong answer to "I need exact one-slot-per-request sliding-window enforcement against a Redis ZSET with atomic Lua eval and no separate timer key." That second question is what most Rust services hitting Tokio's concurrency limits actually have, so `RateLimiterDriver` + `RateLimitMiddleware` exist alongside, not behind a feature flag.

`ThrottleRequestsMiddleware::with`, the `throttle:60,1` shape, keeps the request path in its key, where Laravel keys the user or the address alone. Two routes behind the same inline limit therefore count apart; use a named limiter or `with_limits` for one budget across routes. Laravel checks every limit and then counts the request; Suprnova checks the same way, then counts each bucket with one conditional increment that refuses without counting when the bucket is full, so a concurrent burst can't slip past the limit between the check and the count. A request that loses that race is refused and leaves the full bucket's count where it was, where Laravel would have admitted and counted it.

The backend-error policy is also a Suprnova addition. Laravel's middleware never surfaces a "the limiter is broken" decision because PHP's per-request lifecycle hides it - the next request gets a fresh process. A long-lived Tokio worker that loses Redis for ten seconds must decide what to do with the requests arriving during that window; `BackendErrorPolicy::FailOpen` (default) vs `FailClosed` is that decision exposed explicitly.

## Next

- [Middleware](middleware.md) - how middleware composes, runs, and short-circuits in the request chain
- [Cache](cache.md) - the store the Laravel-shape `RateLimiter` facade is built on
- [Configuration](configuration.md) - typed config for the cache and Redis backends
- [Auth Flows](auth-flows.md) - `LoginThrottleMiddleware` and the brute-force lockout pattern build on this surface
- [Error Model](error-model.md) - why `Result<HttpResponse, HttpResponse>` lets the middleware short-circuit cleanly


---

<!-- /docs/redis -->

# Redis

The `Redis` facade runs Redis commands of your own: a counter, a leaderboard,
a lock that outlives a request, a message to another service. The queue and
the rate limiter already talk to Redis through their drivers, and the Redis
cache store runs on this facade's `cache` and `default` connections; the
facade is for everything else. It is Laravel's `Redis` facade over named
connections, with typed methods for the common commands and the `redis`
client underneath.

```rust
use suprnova::Redis;

let redis = Redis::connection("default")?;
redis.set("greeting", "hello").await?;
let greeting = redis.get("greeting").await?; // Some("hello")
let visits = redis.incr("visits", 1).await?;
```

## Connections

You connect through `default` using `REDIS_URL` when set. Otherwise, you
configure the server with `REDIS_HOST` (`127.0.0.1`), `REDIS_PORT` (`6379`),
`REDIS_PASSWORD` (none), and `REDIS_DB` (`0`). You select the database in
the URL's path: `redis://127.0.0.1:6379/2` selects database 2. You connect
through `cache` to the same server with the same credentials, using
`REDIS_CACHE_DB` (`1`). You replace either built-in connection with a
bootstrap definition. You name other servers or databases there too:

```rust
use suprnova::Redis;

pub async fn register() -> Result<(), suprnova::FrameworkError> {
    Redis::define("sessions", "redis://10.0.0.5:6379/0")?;
    Redis::define("local", "unix:///run/redis/redis.sock")?;
    Ok(())
}
```

`Redis::define` takes `redis://`, `rediss://`, and `unix://` URLs, with a
user and password when the server needs them. A `rediss://` URL connects
over TLS and trusts the certificate authorities of the system; so do the
cache, queue, and rate limiter URLs. `Redis::define` replaces any
connection of that name, `default` included. A name already resolved stays
resolved, on the new URL, while the handles taken before keep the server
they had. A URL that is not a Redis URL is an error that names the
connection, never the URL, since the URL may hold a password.

For what a URL cannot say, such as a private certificate authority, a
client certificate, or a server a Sentinel names, build the client with
the re-exported `redis` crate and give it to
`Redis::define_client(name, client)`:

```rust
use suprnova::Redis;
use suprnova::redis::{Client, TlsCertificates};

let client = Client::build_with_tls(
    "rediss://cache.internal:6380/0",
    TlsCertificates {
        client_tls: None,
        root_cert: Some(std::fs::read("/etc/ssl/private-ca.pem")?),
    },
)?;
Redis::define_client("cache", client);
```

TLS uses rustls. The framework installs `ring` as rustls's crypto provider
before the first Redis client opens, unless your application installed one
first.

`Redis::connection(name)` returns the connection. Resolving it sends
nothing: the connection opens on its first command, and opens again on its
own after the server drops it. Every clone of a connection shares the one
connection to the server.

`Redis::connections()` lists the names resolved so far.
`Redis::purge(name)` forgets one; it closes once nothing holds it, and the
next `Redis::connection(name)` opens a new one. A name that no `define`
gave, other than `default` and `cache`, is an error.

### The cache's connections

With `CACHE_DRIVER=redis`, the [cache](cache.md#redis-connections) runs its
commands on the `cache` connection and takes its locks on `default`, as
Laravel's cache store does. `REDIS_CACHE_CONNECTION` and
`REDIS_CACHE_LOCK_CONNECTION` name other connections, and
`Cache::set_connection(name)` moves the store's later commands to one you
defined:

```rust
use suprnova::{Cache, Redis};

pub async fn register() -> Result<(), suprnova::FrameworkError> {
    Redis::define("cache-replica", "redis://10.0.0.6:6379/1")?;
    Cache::set_connection("cache-replica")?;
    Ok(())
}
```

`Redis::define("cache", url)` in the bootstrap points the cache at another
server before the store is built.

## Key prefixes

You set `REDIS_PREFIX` to prefix every typed key, including keys in
scripts, typed pipeline methods and blocking methods. You disable the
prefix with an explicit empty value. When you leave it unset, you use the
slug of `APP_NAME` followed by `-database-`; `APP_NAME=My Shop` gives you
`my-shop-database-`. You use `Suprnova` as the default application name.
You capture the prefix when you resolve each connection. You keep values,
hash fields, list elements and Pub/Sub channels as given.

You send keys as given through `command`, `execute_raw`, the pipeline's
`command`, and `client()`. You include the prefix yourself when you access
typed keys through these methods. The cache store does this for you: its
keys are the connection's `REDIS_PREFIX`, then `CACHE_PREFIX`, then the
key you gave. You run `scan` with your matching
pattern, which receives the prefix, and get the server's full keys,
prefix included. You also get the full server key in blocking replies.
You use a raw `DEL` to remove keys returned by `scan`.

## Commands

The common commands are typed methods. Values go in and come out as text:

| Kind | Methods |
|---|---|
| Strings | `get`, `set`, `set_ex`, `mget`, `incr`, `decr` |
| Keys | `del`, `exists`, `expire`, `ttl`, `scan` |
| Hashes | `hset`, `hget`, `hgetall`, `hdel` |
| Lists | `lpush`, `rpush`, `lpop`, `rpop`, `lrange` |
| Sets | `sadd`, `srem`, `smembers` |
| Sorted sets | `zadd`, `zrange`, `zrangebyscore` |
| Other | `publish`, `eval`, `evalsha` |

```rust
use suprnova::Redis;

let redis = Redis::connection("default")?;
redis.zadd("leaderboard", "ada", 3120.0).await?;
redis.zadd("leaderboard", "grace", 2980.0).await?;
let top = redis.zrange("leaderboard", 0, 9).await?;

redis.set_ex("otp:42", "813204", 300).await?;
let keys = redis.scan("otp:*").await?;
```

`scan` walks every cursor and returns every matching key, so the server is
never blocked the way `KEYS` blocks it.

`command` runs any other command and returns the reply as a `RedisValue`:

```rust
use suprnova::{Redis, RedisValue};

let redis = Redis::connection("default")?;
redis.command("PFADD", &["visitors", "ada", "grace"]).await?;
if let RedisValue::Int(count) = redis.command("PFCOUNT", &["visitors"]).await? {
    println!("{count} distinct visitors");
}
```

You run a command line with
`execute_raw(&["LRANGE", "full-key", "0", "-1"])`, giving the command name
as its first argument. You get the same `RedisValue` as `command`, with
the same retry policy and connection guards.

You run a loaded script with `evalsha(sha, keys, args)` after you load it
through `command("SCRIPT", &["LOAD", script])`. You prefix only the keys
with `eval` and `evalsha`; you keep the script or SHA and `ARGV` as given.

`command` sends a blocking command, such as `BLMPOP` or `XREAD` with
`BLOCK`, on a connection of its own, as the typed blocking methods do.
`WAIT` and `WAITAOF` wait for the writes of the connection that sends them,
so they run on the shared connection and hold it while they wait; keep
their timeouts short.

`command` refuses the commands that would change the connection every
other command shares, and the error names what to use instead:
`subscribe` for `SUBSCRIBE` and its family, `transaction` for `MULTI` and
`EXEC`, the URL for `SELECT` and `AUTH`, and a connection of your own from
`suprnova::redis::Client` for `WATCH`, `MONITOR`, `CLIENT REPLY`, and
`CLIENT TRACKING`. A pipeline and a transaction refuse them too.

A `RedisValue` is `Nil`, `Int`, `Bytes` for a bulk string, `Status` for
a reply such as `OK`, `Array`, or, from a server speaking RESP3, `Map`,
`Double`, or `Bool`. `as_str` and `as_int` read the common cases. Binary
values go through `command`, whose arguments are bytes.

For what the facade does not cover, `client()` gives the connection the
commands use, as the `redis` crate's `ConnectionManager`. The crate is
re-exported as `suprnova::redis`, so you don't need to add it to your
dependencies:

```rust
use suprnova::Redis;

let redis = Redis::connection("default")?;
let mut client = redis.client()?;
let length: usize = suprnova::redis::cmd("XLEN")
    .arg("events")
    .query_async(&mut client)
    .await?;
```

The shared connection waits up to five seconds for a reply. A command that
blocks for longer belongs on a connection of its own; see
[Blocking commands](#blocking-commands).

### Lost connections

When the server drops the connection, a read is sent again on the new
connection: once, and once more for each retry `REDIS_COMMAND_RETRIES`
adds. The typed reads retry, and so do the reads Laravel lists as safe to
retry when they go through `command`: `GET`, `MGET`, `HGETALL`, `LRANGE`,
`SMEMBERS`, `ZRANGE`, `TTL`, `EXISTS`, and the rest. Laravel's list also
holds three writes, `MSET`, `HMSET`, and `SET` without options; Suprnova
leaves them out. A write is never sent again, since the server may have
applied it before the connection dropped, and a second one would undo a
write another client made in between. It returns the error, and the next
command reaches the new connection. A reply that takes longer than the
five-second limit counts as a lost one too.

## Pipelines and transactions

`pipeline` sends every command its closure queues before it reads a reply,
and returns the replies in order. It saves a round trip per command:

```rust
use suprnova::Redis;

let redis = Redis::connection("default")?;
let replies = redis
    .pipeline(|pipe| {
        for id in 1..=100 {
            pipe.set(&format!("user:{id}:seen"), "1");
        }
    })
    .await?;
```

A pipeline is not atomic: another client's commands can run between its
own. `transaction` sends the same commands inside `MULTI` and `EXEC`, so
they run together, and when Redis rejects one as it is queued, an unknown
command or a wrong number of arguments, none of them runs:

```rust
use suprnova::Redis;

let redis = Redis::connection("default")?;
let replies = redis
    .transaction(|pipe| {
        pipe.decr("stock:42", 1);
        pipe.rpush("orders", &["42"]);
    })
    .await?;
```

The closure queues with `command` and with these typed methods: `set`,
`set_ex`, `get`, `del`, `incr`, `decr`, `expire`, `hset`, `lpush`, `rpush`,
`sadd`, `zadd`, and `publish`. A pipeline refuses a blocking command, which
would hold up the shared connection; inside a transaction Redis runs one
without blocking. Neither is sent again after a lost connection.

## Subscriptions

`subscribe` and `psubscribe` open a connection of their own and return a
subscription. Its `next` waits for the next message:

```rust
use suprnova::Redis;

let redis = Redis::connection("default")?;
let mut orders = redis.psubscribe(&["orders.*"]).await?;

tokio::spawn(async move {
    while let Some(message) = orders.next().await {
        // message.channel is "orders.created", message.pattern is Some("orders.*")
        println!("{}: {:?}", message.channel, message.payload_str());
    }
});

redis.publish("orders.created", "42").await?;
```

The shared connection keeps running commands while a subscription is open.
Dropping the subscription closes its connection. When the server closes
it instead, on a restart, a `CLIENT KILL`, or a full output buffer, `next`
opens a new connection and subscribes again, waiting for the server as
long as it takes. Messages published in between are lost, since Pub/Sub
keeps none. `next` returns `None` only when the server refuses the new
subscription.

## Blocking commands

`blpop`, `brpop`, `blmove`, `brpoplpush`, `bzpopmin`, and `bzpopmax` each run
on a connection of their own, opened for the call. A call that waits never
holds up another command, and it waits for its whole timeout; a zero
timeout waits until something arrives:

```rust
use std::time::Duration;
use suprnova::{Redis, RedisSide};

let redis = Redis::connection("default")?;
if let Some((list, job)) = redis.blpop(&["jobs:high", "jobs:low"], Duration::from_secs(5)).await? {
    println!("{job} from {list}");
}
let moved = redis
    .blmove("jobs:low", "jobs:running", RedisSide::Left, RedisSide::Right, Duration::ZERO)
    .await?;
```

## Events

You enable command events with `Redis::enable_events()`. You register
application listeners through `EventFacade::listen` to receive
`RedisCommandExecuted`. You also receive the same event through
`Redis::listen`, with the connection's name, command, wire arguments and
duration. You receive `RedisCommandFailed`, with its error, through both
`EventFacade` and `Redis::listen_for_failures`. You see application
listener errors in the logs, while the Redis command's result stays the
same. You receive no events until you enable them, and no events for
commands inside a pipeline or a transaction:

```rust
use suprnova::Redis;

Redis::listen(|event| {
    if event.duration.as_millis() > 50 {
        tracing::warn!(command = %event.command, connection = %event.connection, "slow Redis command");
    }
});
Redis::listen_for_failures(|event| {
    tracing::error!(command = %event.command, error = %event.error, "Redis command failed");
});
Redis::enable_events();
```

`SUBSCRIBE` and `PSUBSCRIBE` are reported too. A command whose reply the
typed method cannot read, such as a `GET` of a value that is not UTF-8,
reaches the failure listeners, since the caller sees an error. A listener
runs on the task that sent the command, so keep it quick.

## Testing

The facade talks to a real server. To test code that uses it, give
`default`, or the connection the code names, a database of its own in the
test:

```rust
use suprnova::Redis;

#[tokio::test]
async fn counts_visits() -> Result<(), suprnova::FrameworkError> {
    Redis::define("default", "redis://127.0.0.1:6379/15")?;
    let redis = Redis::connection("default")?;
    redis.del(&["visits"]).await?;
    // run the code under test
    assert_eq!(redis.get("visits").await?.as_deref(), Some("1"));
    Ok(())
}
```

Connections are process-global, like the other facades. A connection opened
in one test's runtime opens again in the next test's, so every
`#[tokio::test]` can use it.

### Why Suprnova diverges

- **Connections are named in the bootstrap.** Laravel reads them from
  `config/database.php`; `Redis::define` does the same job in code, with
  the URL holding the host, port, database, user, and password.
- **Only reads retry.** With `command_retries` set, Laravel sends any
  command again after a lost connection, writes included, and its list of
  retryable commands holds three writes. Suprnova never sends a write
  twice.
- **Some commands are refused.** Every task shares one connection, so
  `SELECT`, `MULTI`, `WATCH`, `SUBSCRIBE`, `CLIENT REPLY`, and the like would
  change it for all of them. Laravel runs them on the connection of the
  process that sends them.
- **A subscription is a value.** Laravel's `subscribe` takes a callback and
  blocks the process; here it returns a subscription that a task reads.
- **Blocking commands get their own connection.** In Laravel they block
  the connection every other command uses.
- **Typed methods take and return text.** Binary values go through
  `command` and `client`.

## Next

- [Cache](cache.md) - caching through the Redis driver
- [Queues](queues.md) - the Redis queue driver
- [Rate Limiting](rate-limiting.md) - limits kept in Redis


---

<!-- /docs/scheduling -->

# Task Scheduling

Scheduled tasks are async functions the framework runs on a cron expression - every minute, hourly, daily, weekly, or any custom 5-field cron. Tasks live inside your application binary; `schedule:run` evaluates due tasks once (call it from system cron) and `schedule:work` runs the same evaluator as a long-lived daemon.

## Generating Tasks

The fastest way to create a new scheduled task is using the suprnova CLI:

```bash
suprnova make:task CleanupLogs
```

This command will:
1. Create `src/tasks/cleanup_logs_task.rs` with a working task stub
2. Create `src/tasks/mod.rs` if it doesn't exist, re-exporting the task
3. Create `src/schedule.rs` for registering tasks, if it doesn't exist
4. Declare `pub mod schedule;` and `pub mod tasks;` in `src/lib.rs`
5. Wire `.schedule(<crate>::schedule::register)` into your application
   builder in `cmd/main.rs` (or `src/main.rs` for the API starter)

Steps 2-5 are idempotent, so re-running `make:task` repairs wiring that was
removed by hand. The scheduler runs inside your application binary - there is
no separate scheduler executable to build or deploy.

```bash Examples
# Creates CleanupLogsTask in src/tasks/cleanup_logs_task.rs
suprnova make:task CleanupLogs

# Creates SendRemindersTask in src/tasks/send_reminders_task.rs
suprnova make:task SendReminders

# You can also include "Task" suffix (same result)
suprnova make:task BackupDatabaseTask
```

```rust Generated File
//! CleanupLogsTask scheduled task
//!
//! Created with `suprnova make:task cleanup_logs_task`.

use std::time::Instant;

use async_trait::async_trait;
use suprnova::{Task, TaskResult};

/// CleanupLogsTask - A scheduled task.
///
/// Register the task in `src/schedule.rs` with the fluent API; the skeleton
/// below times its own run and prints a structured log line on each
/// invocation so it works end-to-end the first time you wire it up.
pub struct CleanupLogsTask;

impl CleanupLogsTask {
    /// Create a new instance of this task.
    pub fn new() -> Self {
        Self
    }
}

impl Default for CleanupLogsTask {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl Task for CleanupLogsTask {
    async fn handle(&self) -> TaskResult {
        let started_at = Instant::now();
        println!("[CleanupLogsTask] task started");

        // Replace this with the real job. The skeleton ships as a
        // no-op success so the task can be scheduled and observed
        // before the implementation is filled in.

        println!(
            "[CleanupLogsTask] task finished in {} ms",
            started_at.elapsed().as_millis(),
        );
        Ok(())
    }
}
```

## Defining Schedules

suprnova supports three approaches for defining scheduled tasks:

### 1. Trait-Based Tasks (Recommended)

For complex tasks that need dependencies or reusable logic, implement the `Task` trait and configure the schedule during registration:

```rust
// src/tasks/cleanup_logs_task.rs
use async_trait::async_trait;
use chrono::{Duration, Utc};
use suprnova::{Task, TaskResult};
use crate::models::Log;

pub struct CleanupLogsTask;

impl CleanupLogsTask {
    pub fn new() -> Self {
        Self
    }
}

#[async_trait]
impl Task for CleanupLogsTask {
    async fn handle(&self) -> TaskResult {
        // Eloquent works exactly as it does inside a controller; tasks see
        // the same container bindings (`DB::connection()`, `App::get::<T>()`)
        // that a request handler does - see Application bootstrap below.
        let cutoff = Utc::now() - Duration::days(30);
        Log::query()
            .filter_op("created_at", "<", cutoff)
            .delete_all()
            .await?;

        println!("Old logs cleaned up successfully");
        Ok(())
    }
}
```

Then register with fluent scheduling API in `src/schedule.rs`:

```rust
// src/schedule.rs
use suprnova::Schedule;
use crate::tasks::CleanupLogsTask;

pub fn register(schedule: &mut Schedule) {
    schedule.add(
        schedule.task(CleanupLogsTask::new())
            .daily()
            .at("03:00")
            .name("cleanup:logs")
            .description("Removes logs older than 30 days")
    );
}
```

### 2. Closure-Based Tasks

For quick, inline tasks without separate files:

```rust
// src/schedule.rs
use suprnova::Schedule;

pub fn register(schedule: &mut Schedule) {
    // Simple closure task
    schedule.add(
        schedule.call(|| async {
            println!("Ping! Running every minute");
            Ok(())
        })
        .every_minute()
        .name("heartbeat")
    );

    // Configured closure task
    schedule.add(
        schedule.call(|| async {
            // Your task logic
            Ok(())
        })
        .daily()
        .at("09:00")
        .name("morning-report")
        .description("Sends daily morning report")
    );
}
```

### 3. Console Commands

To run a [console command](console.md) on a schedule, pass the command line to `Schedule::command`. Write it the way you type it after the name of the console binary:

```rust
// src/schedule.rs
use suprnova::Schedule;

pub fn register(schedule: &mut Schedule) {
    schedule.add(
        schedule.command("emails:send --force")
            .daily()
            .at("06:00"),
    );

    // A built-in command works the same way. See [Database](database.md#busy-database---dbmonitor-and-dbmonitor) for `db:monitor`.
    schedule.add(schedule.command("model:prune").daily().at("02:00"));

    // So does `db:monitor`, which dispatches `DatabaseBusy` at 80 connections.
    schedule.add(schedule.command("db:monitor --max 80").every_minute());
}
```

`command` splits the line into words the way a shell does: whitespace separates words, and single quotes, double quotes, and backslashes keep a word together. It runs no variables, globbing, or pipes, because the console runs the line and not a shell. It returns the same `TaskBuilder` as `task` and `call`, so every frequency method, `without_overlapping()`, and `on_one_server()` apply.

The command runs in the scheduler's process, not in a new one. The task is named by its command line, with one space between the words, and it is described by the command's about text. `.name(...)` and `.description(...)` override both.

The command line is checked when the schedule is built, which is at boot. `command` panics, and the boot stops, when no command has the name (the message lists the registered commands), when the arguments do not parse for the command, and when a quote is not closed. A scheduled task runs when nobody is watching, so a typing error stops the boot instead of failing at 3 a.m. A command that is not linked into the binary that runs the scheduler has no name there and stops the boot the same way.

Use `try_command` when the command line comes from configuration and you want the error:

```rust
use suprnova::{FrameworkError, Schedule};

fn add_from_config(schedule: &mut Schedule, line: &str) -> Result<(), FrameworkError> {
    // Err(FrameworkError::Internal) on a bad command line
    schedule.add(schedule.try_command(line)?.hourly());
    Ok(())
}
```

A command that returns an error is a failed task, and the scheduler reports it. The console does not print the error as well.

## Registering Tasks

Register your tasks in `src/schedule.rs`:

```rust
// src/schedule.rs
use suprnova::Schedule;
use crate::tasks;

pub fn register(schedule: &mut Schedule) {
    // Trait-based tasks with fluent schedule configuration
    schedule.add(
        schedule.task(tasks::CleanupLogsTask::new())
            .daily()
            .at("03:00")
            .name("cleanup:logs")
            .description("Removes logs older than 30 days")
    );

    schedule.add(
        schedule.task(tasks::SendRemindersTask::new())
            .daily()
            .at("09:00")
            .name("send:reminders")
            .description("Sends daily reminder emails")
    );

    schedule.add(
        schedule.task(tasks::BackupDatabaseTask::new())
            .weekly()
            .at("00:00")
            .name("backup:database")
            .description("Weekly database backup")
            .without_overlapping()
    );

    // Closure-based tasks
    schedule.add(
        schedule.call(|| async {
            println!("Quick task!");
            Ok(())
        })
        .hourly()
        .name("quick-task")
    );
}
```

## Schedule Frequency Options

suprnova provides a fluent API for defining when tasks should run:

### Common Intervals

| Method | Description |
|--------|-------------|
| `.every_minute()` | Run every minute |
| `.every_two_minutes()` | Run every 2 minutes |
| `.every_five_minutes()` | Run every 5 minutes |
| `.every_ten_minutes()` | Run every 10 minutes |
| `.every_fifteen_minutes()` | Run every 15 minutes |
| `.every_thirty_minutes()` | Run every 30 minutes |
| `.hourly()` | Run every hour at minute 0 |
| `.hourly_at(30)` | Run every hour at minute 30 |
| `.every_two_hours()` / `.every_three_hours()` / `.every_four_hours()` / `.every_six_hours()` | Run on the hour every N hours |
| `.daily()` | Run daily at midnight |
| `.daily_at("03:00")` | Run daily at 3:00 AM |
| `.twice_daily(1, 13)` | Run twice daily (e.g. 1:00 AM and 1:00 PM) |
| `.weekly()` | Run weekly on Sunday at midnight |
| `.monthly()` | Run monthly on the 1st at midnight |
| `.monthly_on(15)` | Run monthly on a specific day |
| `.quarterly()` | Run on the 1st of Jan/Apr/Jul/Oct at midnight |
| `.yearly()` | Run on January 1st at midnight |

### Day-Specific Schedules

```rust
use suprnova::DayOfWeek;

// Run on specific days
.weekly_on(DayOfWeek::Monday)
.weekly_on(DayOfWeek::Friday)

// Shorthand day methods
.sundays()
.mondays()
.tuesdays()
.wednesdays()
.thursdays()
.fridays()
.saturdays()

// Multiple days
.days(&[DayOfWeek::Monday, DayOfWeek::Wednesday, DayOfWeek::Friday])

// Weekdays/Weekends
.weekdays()  // Monday-Friday
.weekends()  // Saturday-Sunday
```

After a frequency, a time or `.cron(..)`, a day method replaces only the
day-of-week field and keeps the rest, as Laravel's `days` does:

```rust
.hourly().mondays()                         // 0 * * * 1 - every hour on Mondays
.daily().at("09:30").weekdays()             // 30 9 * * 1-5
.every_fifteen_minutes().weekends()         // */15 * * * 0,6
.days(&[DayOfWeek::Monday, DayOfWeek::Friday]).at("08:00") // 0 8 * * 1,5
```

A day method alone runs at midnight on that day: `.mondays()` is
`0 0 * * 1`. `CronExpression::with_days_of_week(days)` does the same splice
on an expression you build yourself.

### Time Modifiers

Chain `.at()` with any schedule to set a specific time:

```rust
.daily().at("14:30")           // Daily at 2:30 PM
.weekly().at("09:00")          // Weekly at 9:00 AM
.mondays().at("08:00")         // Every Monday at 8:00 AM
.monthly().at("00:00")         // First of month at midnight
.monthly_on(15).at("9")        // The 15th at 9:00 AM
.daily_at("23:59:59")          // Daily at 11:59 PM
```

A time is `H` for that hour on the hour, `HH:MM`, or `HH:MM:SS`, whose
seconds are dropped, as Laravel's `dailyAt` reads it. A non-numeric
segment is an error from `try_at`, a warning from `at` (which keeps the
expression), and `0` for `daily_at` and `try_daily_at`.

### Timezones

By default the scheduler reads every cron expression against the process's
local zone, whatever `TZ` the container was started with. Pin a task to a
named IANA zone when its schedule belongs to a place rather than to a
server:

```rust
use suprnova::chrono_tz;

schedule.add(
    schedule.task(GenerateReportTask::new())
        .daily()
        .at("02:00")
        .timezone(chrono_tz::America::New_York)
        .name("report:generate")
);
```

`timezone` takes a typed `chrono_tz::Tz`, so a misspelled zone is a compile
error rather than a task that quietly runs at the wrong hour. The zone
constants live under `suprnova::chrono_tz` (`chrono_tz::Asia::Tokyo`,
`chrono_tz::Europe::Berlin`, and so on), re-exported so you do not need
`chrono-tz` in your own `Cargo.toml`.

When the zone name only exists at runtime - a config value, a tenant
column - use the fallible sibling:

```rust
schedule.add(
    schedule.task(GenerateReportTask::new())
        .daily()
        .at("02:00")
        .try_timezone(&tenant.timezone)?   // Err(String) on an unknown zone
        .name("report:generate")
);
```

A pinned zone changes exactly one thing: which wall clock the five cron
fields are read against. The scheduler still ticks once per process minute,
and the same-minute dedup gate is unaffected.

#### A schedule-wide default

If most of your tasks belong to one business zone, set it once on the
schedule rather than repeating it on every task:

```rust
pub fn register(schedule: &mut Schedule) {
    schedule.timezone(chrono_tz::America::Chicago);

    // Read as 02:00 America/Chicago
    let nightly = schedule
        .call(|| async { Ok(()) })
        .daily()
        .at("02:00")
        .name("nightly");
    schedule.add(nightly);

    // An explicit per-task zone always wins
    let tokyo = schedule
        .call(|| async { Ok(()) })
        .daily()
        .at("09:00")
        .timezone(chrono_tz::Asia::Tokyo)
        .name("tokyo-open");
    schedule.add(tokyo);
}
```

The default is applied when a task is added, so it covers tasks registered
after the call and leaves earlier ones alone.

#### Daylight saving

Some zones observe daylight saving time. When the clocks change, a task
pinned to such a zone may run twice or not run at all:

- On a fall-back, one wall-clock hour happens twice. A task at `01:30`
  matches both passes. They are two different minutes of real time, so the
  same-minute dedup gate does not merge them and the task runs twice.
- On a spring-forward, one wall-clock hour never happens. A task at `02:30`
  is skipped entirely that day.

Avoid timezone scheduling where you can, and prefer a zone without DST
(`chrono_tz::UTC`) for anything that must run exactly once.

#### Reading the listing in another zone

`schedule:list` takes `--timezone` and shows both the cron expression and
the next run time as they read in that zone. See
[List Tasks](#list-tasks) for worked output.

### Why Suprnova diverges: timezones

Laravel's `timezone()` takes a string and its schedule-wide default comes
from an `app.schedule_timezone` config key. Suprnova takes a typed
`chrono_tz::Tz` and has no config key: `Schedule::timezone` in your
`schedule::register` function is the one place a default is set, so the
schedule reads top to bottom without a second file to consult.

Suprnova's default when nothing is pinned is the process's local zone
rather than a configured application timezone. That is the behaviour the
scheduler has always had, and it stays the default so adding this feature
changes nothing for schedules that do not use it.

### Custom Cron Expressions

For full control, use cron syntax:

```rust
// Standard cron format: minute hour day-of-month month day-of-week
.cron("0 */2 * * *")    // Every 2 hours
.cron("30 4 * * 1-5")   // 4:30 AM on weekdays
.cron("0 0 1,15 * *")   // 1st and 15th of each month
.cron("0 9 1-15/7 * *") // 9:00 AM on the 1st, 8th and 15th
```

Each field is a comma-separated list of parts. A part is `*`, a value
`N`, or a range `N-M`, and any of them can take a `/step`; `N/step` runs
from `N` to the end of the field. A step counts from the first value of
its part, and for `*` that is the field's first value: `*/2` in the
day-of-month field is the 1st, 3rd, 5th, and so on, and `*/3` in the
month field is January, April, July, and October - what cron and
Laravel mean. The expressions `schedule:list` prints for another
timezone use the same grammar, so you can schedule one as it reads.

`.cron(...)` **panics** if the expression is malformed (wrong field count,
unparseable step/range/list). Use `.try_cron(expr)` when the expression is
supplied at runtime (configuration, user input) and you'd rather propagate
the parse error:

```rust
schedule.add(
    schedule.task(MyTask::new())
        .try_cron(env_expr)?   // returns Err(String) on a bad expression
        .name("from-config")
);
```

The same `panic` / `try_*` pair exists on every numeric-range builder method:
`try_hourly_at`, `try_daily_at`, `try_twice_daily`, `try_monthly_on`. The
infallible variants panic on out-of-range numerics (e.g. `daily_at("25:00")`
or `monthly_on(40)`); the fallible siblings return `Err(String)`.

## Task Configuration

### Preventing Overlapping

Skip a tick when a previous run of the same task is still in flight:

```rust
schedule.add(
    schedule.task(LongRunningTask::new())
        .daily()
        .name("long-task")
        .without_overlapping()
);
```

**How the lock works.** When the flag is set, suprnova tries to acquire a
distributed mutex via the configured [`Cache`](cache.md) backend
(`schedule:lock:<task-name>`). A successful acquire runs the task and releases
the lock; a contended acquire is reported as a successful skip - `Ok(())`,
with the task's skip counter ticked so observability surfaces can see it
without poisoning the `schedule:run` exit code.

**Cache is required for cross-process protection.** If you run multiple
processes that schedule the same task (e.g. several boxes invoking
`suprnova schedule:run` from system cron, or `schedule:work` daemons behind a
load-balancer), the Cache backend is what coordinates them. **Without a
configured Cache, `without_overlapping()` silently degrades to a per-process
`AtomicBool`** - two separate processes will not see each other's locks. The
framework emits a one-time `WARN` (`suprnova::schedule`) the first time this
fallback fires so operators notice the weaker guarantee:

> `without_overlapping() falling back to in-process AtomicBool protection - Cache is not bootstrapped. Multi-process deployments will NOT see each other's locks. Configure Cache (CACHE_DRIVER=memory|redis) before relying on cross-process overlap protection.`

**Custom lock TTL.** The lock TTL defaults to 30 minutes - long enough for
most tasks to finish, short enough that a crashed task holding the lock
unblocks the next tick without operator intervention. Override per task with
`.without_overlapping_for(Duration)`. `Duration::ZERO` is undefined across
cache backends (Redis errors, in-memory expires instantly, Memcached treats
it as "never expire"), so the builder coerces it to the 30-minute default
with a one-time `WARN` so the operator can fix the call site.

```rust
use std::time::Duration;

schedule.add(
    schedule.task(SlowBackupTask::new())
        .daily()
        .name("backup:full")
        // This job legitimately runs longer than the 30-minute default;
        // give the lock a 2-hour TTL so a slow run doesn't get pre-empted
        // by the next tick.
        .without_overlapping_for(Duration::from_secs(2 * 3600))
);
```

### Running on One Server

Run a task exactly once per due tick, no matter how many replicas are
running the scheduler:

```rust
schedule.add(
    schedule.task(NightlyBillingTask::new())
        .daily()
        .at("02:00")
        .name("billing:nightly")
        .on_one_server()
);
```

**What goes wrong without it.** Every replica running `schedule:work`
evaluates the schedule independently, and nothing stops all of them
deciding the same tick is theirs. Three replicas were measured producing
three executions of the same task, every minute, with no variance. For a
nightly billing job that means every customer is billed three times.

**Why `without_overlapping()` does not cover this.** The two look alike
and solve different problems:

| | Lock key | Held for | Prevents |
|---|---|---|---|
| `without_overlapping()` | task | the task's duration | a slow run overlapping its own next tick |
| `on_one_server()` | task **+ the tick** | the tick window | a second replica running the same tick |

The distinction that matters is when the lock is released.
`without_overlapping()` releases as soon as the handler returns - for a
fast task, before a second replica has even looked, so all N still run.
`on_one_server()` deliberately holds its lock past the handler and lets it
expire on TTL, because a replica arriving later in the same tick has to
find it taken.

They compose. A long-running task that must also be single-server takes
both.

**Requires a shared cache.** The election is a [`Cache`](cache.md) lock, so
"one server" means "one process among those sharing a cache backend". With an
in-memory cache store the lock lives in a single process's heap, every
replica wins its own election, and the guarantee is silently absent.

With no cache store bound at all there is no lock to elect with. A schedule
with an `on_one_server()` task then refuses to start, in every environment,
with an error that names the tasks, and a tick that runs without the check
skips such a task with an error log. No path runs it on every server.

The check asks the cache store the scheduler actually locks through, not
`CACHE_DRIVER`: an in-memory store your bootstrap binds, or a typed
`CacheConfig` that selects memory, counts as per-process even when
`CACHE_DRIVER=redis`. A custom `CacheStore` whose locks are shared across
processes says so by returning `true` from `CacheStore::locks_are_shared`.

In production a per-process lock is a **boot failure**, not a warning:

> `refusing to boot in production: 1 task(s) request single-server execution (billing:nightly) but the bound cache store keeps its locks in this process (CACHE_DRIVER is memory or unset, or the application bound an in-memory store), so the election lock lives in this process's heap. Every replica would win its own election and run the task, which is what on_one_server() exists to prevent. Set CACHE_DRIVER=redis with REDIS_URL, or set SCHEDULE_ALLOW_MEMORY_LOCK_IN_PRODUCTION=true to acknowledge per-process locking - which is only accurate if you run exactly one scheduler.`

Set `SCHEDULE_ALLOW_MEMORY_LOCK_IN_PRODUCTION=true` if your deployment
really does run a single scheduler. Outside production a bound in-memory
store stays usable. The acknowledgement does not lift the refusal for a
schedule with no cache store bound: there is no lock for it to acknowledge.

**Custom lock TTL.** Defaults to 60 seconds - one minute-aligned tick.
Both edges matter: too short and a replica whose tick lands a few seconds
late finds the lock gone and runs the task again; too long and the lock
outlives its tick, so the *next* due run finds it held and is skipped
entirely. Use `.on_one_server_for(Duration)` for coarser schedules.

```rust
use std::time::Duration;

schedule.add(
    schedule.task(HourlyRollupTask::new())
        .hourly()
        .name("rollup:hourly")
        // An hourly task only needs the lock to outlast the window in
        // which replicas could still call this tick due.
        .on_one_server_for(Duration::from_secs(300))
);
```

**If the cache is unreachable**, the tick is skipped rather than run.
Losing coordination is the worst possible moment to let every replica
through: a skipped tick is recoverable next tick, duplicate side effects
generally are not.

### Why Suprnova diverges

Laravel's `onOneServer()` is the same opt-in, and Suprnova keeps that:
per-server tasks - log rotation, warming a local cache - are legitimate
and stay expressible.

Where it diverges is the failure mode. Laravel will happily run
`onOneServer()` against a cache driver that cannot coordinate. Suprnova
refuses to boot in production instead, on the same reasoning as the
in-memory rate limiter: a control that silently does much less than it
claims is worse than one that is visibly absent. With no cache store at all,
Suprnova refuses in every environment, where Laravel's mutex would fail on
the missing store.

### A single-server default

Call `schedule.always_on_one_server()` to elect one server for every task,
including tasks you already registered. You use the same shared cache and
lock TTL as `on_one_server()`. Add `.on_every_server()` to a task when you
want each server to run it. The last per-task choice wins.

### Interrupting a run

Run `./target/release/app schedule:interrupt` to write an interrupt mark in
your shared cache. You let a running task finish, then stop the run before
it starts another task. Background tasks that already started finish too.
The next run clears the mark before it starts tasks.

You can write the same mark with `Schedule::interrupt().await?` and read it
with `Schedule::has_been_interrupted_since(started_at).await?`, where
`started_at` is a `chrono::DateTime<chrono::Utc>`. You receive cache errors
as `FrameworkError`. A run stops and reports an error when its configured
cache cannot clear or read the mark.

### Environments and maintenance mode

`.environments([...])` limits a task to the named environments, read from
`Config::environment()` at each tick. A task that never calls it runs in
every environment.

```rust
use suprnova::Environment;

schedule.add(
    schedule.task(NightlyBillingTask::new())
        .daily()
        .at("02:00")
        .name("billing:nightly")
        .environments([Environment::Production]),
);
```

While the application is in maintenance mode (`./app down`, see
[Deployment](deployment.md#maintenance-mode)), `schedule:run` and
`schedule:work` skip every task that does not ask
`.even_in_maintenance_mode()`, as Laravel's `Event::isDue` does. A
maintenance state the scheduler cannot read counts as down, and the error is
logged: running every task against services an operator took down is the
worse mistake.

```rust
schedule.add(
    schedule.task(ReportQueueDepthTask::new())
        .every_minute()
        .name("queue:report-depth")
        .even_in_maintenance_mode(),
);
```

Both filters apply in `Schedule::run_due_tasks` and `run_due_tasks_into`.
`Schedule::due_tasks()` still answers by the cron expression alone, and a
`TaskEntry` reports its choices through `environments()`,
`runs_in_environment(&env)` and `runs_in_maintenance_mode()`.

### Running in Background

Detach tasks from the per-tick critical path so they don't block other due
tasks from starting:

```rust
schedule.add(
    schedule.task(BackgroundTask::new())
        .hourly()
        .name("background-task")
        .run_in_background()
);
```

**Panic isolation.** Background tasks run inside a `tokio::task::JoinSet`
with `catch_unwind`, so a panicking task surfaces as a `FrameworkError`
recorded against the task's name rather than tearing down the scheduler. The
`schedule:work` daemon drains the JoinSet on shutdown (Ctrl-C / SIGTERM) so
in-flight background tasks complete before exit, within a 30-second grace.
A stop signal that arrives while a tick's inline tasks are still running
is seen at once: the inline tasks and the background tasks share the
grace, and whatever is still running at its end is stopped.

**Combine with `without_overlapping`.** The two flags compose - a background
task with `without_overlapping()` will spawn into the JoinSet and acquire the
overlap lock from inside the spawned future, so the lock semantics described
above still apply.

### Same-Minute Dedup

Cron resolution is minute-level, and suprnova enforces that: if the same task
is asked to run twice within the same wall-clock minute inside a single
process, the second call is a no-op skip - `Ok(())`, with the task's skip
counter ticked. This closes a class of bug where a daemon loop or a tight
`schedule:run` invocation could run a `.every_minute()` task multiple times
in the same minute.

This in-process gate is **always on**, independent of `without_overlapping`.
It does NOT span processes (each process has its own per-task state). If you
need cross-process same-minute coordination, layer on `without_overlapping` + a configured Cache backend - together they cover both directions.

## Running the Scheduler

suprnova provides CLI commands for running scheduled tasks:

### Run Once

Execute all due tasks once (typically called by cron every minute):

```bash
suprnova schedule:run
```

### Daemon Mode

Run continuously, checking for due tasks every minute:

```bash
suprnova schedule:work
```

This is ideal for development or when using a process manager like systemd.

### List Tasks

Display all registered scheduled tasks:

```bash
suprnova schedule:list
```

Output:
```
Registered scheduled tasks:
  cleanup:logs [0 3 * * *] next: 2026-05-29 03:00 UTC
  send:reminders [0 9 * * *] next: 2026-05-28 09:00 UTC
  report:generate [0 6 * * *] (UTC) next: 2026-05-29 06:00 UTC
```

Each line is the task name, the cron expression, an optional zone label,
the next time the task fires, and the task's description if it has one.

`next:` is the first minute after now at which the expression matches,
computed in the zone the task is evaluated in and then shown in the
listing's zone. An expression that can never match (`0 0 30 2 *` names a
date that does not exist) prints `next: never`.

The listing's zone is UTC unless you pass `--timezone`. The `suprnova` CLI
passes the flag to your application, which exits with an error when the zone
name is unknown. `cleanup:logs` and
`send:reminders` above pinned no zone, so their expressions are printed as
written - the scheduler reads them against the process's local zone, which
has no IANA name to convert from - and they carry no zone label.
`report:generate` pinned `America/New_York` and asked for `02:00`, so its
expression is rewritten into the listing's zone and labelled with it.

```bash
suprnova schedule:list --timezone=Asia/Tokyo
```

```
Registered scheduled tasks:
  cleanup:logs [0 3 * * *] next: 2026-05-29 12:00 JST
  send:reminders [0 9 * * *] next: 2026-05-28 18:00 JST
  report:generate [0 15 * * *] (Asia/Tokyo) next: 2026-05-29 15:00 JST
```

One task can occupy several lines. An expression that straddles midnight in
the listing's zone needs one cron line per side, because no single
five-field expression describes both:

```
  monday-digest [0 23 * * 1] (Asia/Tokyo) next: 2026-06-01 23:00 JST
  monday-digest [0 5 * * 2] (Asia/Tokyo) next: 2026-06-01 23:00 JST
```

`next:` belongs to the task, not to the line, so it repeats: both lines
describe the same task and the same upcoming run.

Some conversions are refused rather than approximated, and the refused
expression is printed exactly as written, labelled with the task's own
zone. A conversion is refused when a daylight-saving transition falls
between the next two runs (no one expression is right on both sides), when
a day rollover would have to move a restricted day-of-month and a
restricted day-of-week together (cron ORs those two fields, so shifting
both would change which days match), or when a rollover would have to
decide how long February is.

## Production Setup

### Using Cron

Add a single cron entry to run the scheduler every minute:

```bash
* * * * * cd /path/to/your/project && suprnova schedule:run >> /dev/null 2>&1
```

**Cross-process coordination.** If you run `schedule:run` from system cron on
more than one host (or alongside a `schedule:work` daemon), tasks with
`.without_overlapping()` need a configured **Cache** backend
(`CACHE_DRIVER=redis` recommended for production) to coordinate across
processes. Without it, the overlap flag degrades to per-process protection
and the same task can run on multiple hosts in the same minute. See
[Preventing Overlapping](#preventing-overlapping) above for the full lock
semantics.

### Using Systemd

Create a systemd service for the scheduler daemon:

```ini
# /etc/systemd/system/myapp-scheduler.service
[Unit]
Description=MyApp Scheduler
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/your/project
ExecStart=/path/to/suprnova schedule:work
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable myapp-scheduler
sudo systemctl start myapp-scheduler
```

## Accessing App Context

Scheduled tasks have full access to the application context, just like controllers:

```rust
use async_trait::async_trait;
use suprnova::{App, Task, TaskResult};
use crate::actions::SendEmailAction;
use crate::models::User;

pub struct SendRemindersTask;

#[async_trait]
impl Task for SendRemindersTask {
    async fn handle(&self) -> TaskResult {
        // Eloquent: `.get()` returns a `Collection<User>` you can iterate.
        let users = User::query()
            .filter("reminder_enabled", true)
            .get()
            .await?;

        // Anything bound in `bootstrap.rs` is reachable here too.
        let send_email = App::get::<SendEmailAction>()
            .expect("SendEmailAction bound in bootstrap()");

        for user in users.iter() {
            send_email.execute(&user.email, "Daily Reminder").await?;
        }

        Ok(())
    }
}
```

## File Organization

The recommended file structure for scheduled tasks:

```
src/
├── tasks/
│   ├── mod.rs              # Re-exports all tasks (auto-updated by make:task)
│   ├── cleanup_logs_task.rs
│   ├── send_reminders_task.rs
│   └── backup_database_task.rs
├── schedule.rs             # Registers tasks (run by the schedule:* commands)
├── bootstrap.rs
├── routes.rs
└── lib.rs                  # Declares `pub mod schedule;` + `pub mod tasks;`
cmd/
└── main.rs                 # Calls `.schedule(<crate>::schedule::register)`
```

**src/tasks/mod.rs:**
```rust
pub mod cleanup_logs_task;
pub mod send_reminders_task;
pub mod backup_database_task;

pub use cleanup_logs_task::CleanupLogsTask;
pub use send_reminders_task::SendRemindersTask;
pub use backup_database_task::BackupDatabaseTask;
```

## Wiring the scheduler into your application

`make:task` wires `.schedule(<crate>::schedule::register)` into your
`Application` builder automatically. If you build the chain by hand, the
relevant call is on `Application`:

```rust
// cmd/main.rs (or src/main.rs for the api starter)
Application::new()
    .config(my_app::config::register)
    .bootstrap(my_app::bootstrap::bootstrap)
    .routes(my_app::routes::register)
    .schedule(my_app::schedule::register)        // <- this line
    .migrations::<my_app::migrations::Migrator>()
    .run()
    .await;
```

Without `.schedule(...)` the `schedule:*` subcommands all report that no
tasks are registered. `schedule:work` and `schedule:run` also run the same
runtime drivers and `bootstrap_fn` as the HTTP server, so observers,
listeners, and container bindings registered at boot are visible to your
task handlers exactly as they are to controllers (see
[Application Bootstrap](bootstrap.md)).

### Why Suprnova diverges

Laravel's scheduler is itself a single Artisan command (`schedule:run`) that
PHP-cron triggers every minute. The PHP runtime spins up, evaluates due
tasks, runs them in-process or shells out, then tears the runtime down. PHP
has no long-lived processes, so the daemon form (`schedule:work`) was
backported by Lumen and ships in Laravel itself as a workaround for sites
without crontab access.

In Suprnova the daemon is first-class. `schedule:work` runs inside a Tokio
runtime that's already long-lived, so:

- **Background tasks (`run_in_background`) compose with the tick loop.**
  Laravel spawns a child process per background task; we spawn into a
  `JoinSet` and surface completions on the next tick or at shutdown.
- **Graceful shutdown is a `tokio::select!` arm.** Ctrl-C / SIGTERM
  drains in-flight background tasks before exit, and in-process tasks
  get the same bounded grace to finish their current call - a task that
  hangs cannot keep the daemon from stopping.
- **Same-minute dedup is in-process state.** A `last_run_minute` atomic
  per task guarantees a single process can't double-fire a minute-aligned
  task even if the loop ticks fast. PHP can't do this - every cron tick
  is a fresh process - which is why Laravel uses filesystem locks as the
  only line of defence.

The `Cache::lock`-backed `without_overlapping` still exists for the
multi-process case (system cron on multiple hosts, multiple `schedule:work`
daemons behind a load balancer). It's the same mechanism, just at a layer
the scheduler doesn't always need.

## Summary

| Feature | Usage |
|---------|-------|
| Create task | `suprnova make:task TaskName` |
| Trait-based | Implement `Task` trait, configure schedule during registration |
| Closure-based | `schedule.call(\|\| async { ... })` |
| Console command | `schedule.command("emails:send --force")` (panics at boot on a bad line), or `schedule.try_command(line)?` |
| Register tasks | `schedule.add(schedule.task(...).daily().name("..."))` |
| Wire into app | `Application::new().schedule(schedule::register)` |
| Run once | `suprnova schedule:run` |
| Run daemon | `suprnova schedule:work` |
| List tasks | `suprnova schedule:list` |
| Prevent overlap | `.without_overlapping()` (default 30-min lock TTL via Cache backend) |
| Custom overlap TTL | `.without_overlapping_for(Duration)` |
| Background | `.run_in_background()` (panic-isolated via JoinSet) |
| Same-minute dedup | Always on per-process; skipped runs return `Ok(())` |
| Validated cron at runtime | `.try_cron(expr)` / `.try_daily_at(s)` / `.try_hourly_at(n)` |

## Next

- [Scheduling Commands](cli-scheduling.md) - `schedule:run` / `schedule:work` / `schedule:list` CLI reference
- [Queues](queues.md) - for work that should be picked up by a worker rather than tick on a clock
- [Console](console.md) - `#[command]` for one-shot operator tasks (not on a schedule)
- [Cache](cache.md) - the backend that powers cross-process `without_overlapping`
- [Application Bootstrap](bootstrap.md) - how `.schedule(...)` plugs into the builder, and what tasks can resolve from the container


---

<!-- /docs/workflows -->

# Workflows

Workflows are durable, long-running async functions whose intermediate
state survives crashes, restarts, and panics. Reach for them when a unit
of work spans multiple steps - each potentially slow, fallible, or
side-effecting - and you cannot afford to lose progress halfway through.
A workflow's body runs once; each step's output is persisted; a retry
resumes from the first step that hasn't completed yet. Pair with
[`Queue`](queues.md) when the work is a one-shot job; pair with
[`Bus`](bus.md) when the work runs synchronously in the request task.

## Quick start

A workflow is an async function returning `Result<T, FrameworkError>`;
its body invokes one or more `#[workflow_step]` functions; you enqueue
it through the `start_workflow!` macro and a worker process drains it.

```rust
use suprnova::{workflow, workflow_step, start_workflow, FrameworkError};

#[workflow_step]
async fn fetch_user(user_id: i64) -> Result<String, FrameworkError> {
    Ok(format!("user:{}", user_id))
}

#[workflow_step]
async fn send_welcome_email(user: String) -> Result<(), FrameworkError> {
    // … actually send the mail
    Ok(())
}

#[workflow]
async fn welcome_flow(user_id: i64) -> Result<(), FrameworkError> {
    let user = fetch_user(user_id).await?;
    send_welcome_email(user).await?;
    Ok(())
}

// From a handler or any async context:
let handle = start_workflow!(welcome_flow, 123).await?;
```

The macro serialises the arguments to JSON, inserts a row in the
`workflows` table, and returns a [`WorkflowHandle`](#waiting-on-results)
identifying the enqueued instance. It takes the workflow's path the way
Rust resolves it: a bare name, an imported name, a re-export, or a path
from `crate::`, `self::`, or `super::` all start the same workflow. A separate worker process picks the
row up, runs the body, and persists each step's output as it goes.

`#[workflow]` collects the function into the workflow inventory under
its fully-qualified path (`module_path::fn_name`). Two functions under
one name would leave the choice of which one runs to the order the
binary was linked in, so the framework fails loud. `WorkflowWorker::new()`
panics at boot when a name is registered twice.
`suprnova::workflow::assert_no_duplicates()` runs the same check and
returns a `Result<(), FrameworkError>` whose message lists every
duplicated name.

## Schema

Workflows persist into two tables: `workflows` (one row per instance)
and `workflow_steps` (one row per step invocation, keyed by
`(workflow_id, step_index)`). The framework owns the schema; you choose
when to apply it.

Two ways to wire the migrations.

### Generated migration files

The CLI scaffolds copies of the framework migrations into your app:

```bash
suprnova workflow:install
suprnova migrate
```

`workflow:install` writes `m_create_workflows_table.rs` and
`m_create_workflow_steps_table.rs` under `src/migrations/`, then
registers them in your `Migrator`. Use this when you want the schema
versioned alongside your other app migrations.

### Programmatic registration

Alternatively, register the framework-owned migration structs directly:

```rust
use sea_orm_migration::MigratorTrait;
use suprnova::workflow::migrations::{
    CreateWorkflowsTable, CreateWorkflowStepsTable,
};

pub struct Migrator;

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn sea_orm_migration::MigrationTrait>> {
        vec![
            Box::new(CreateWorkflowsTable),
            Box::new(CreateWorkflowStepsTable),
        ]
    }
}
```

Both routes produce identical SQL. The same convention is used by
[`features::migrations`](feature-flags.md) and
[`payments::migrations`](payments.md).

## Running the worker

In a scaffolded app, the worker is started by the binary's
`workflow:work` subcommand:

```bash
suprnova workflow:work
```

The worker runs the same bootstrap your HTTP server does, so observers,
listeners, and container bindings registered in `bootstrap()` are
visible to workflow steps. On `SIGINT` / `SIGTERM` the worker stops
pulling new claims and awaits every in-flight workflow before exiting -
no workflow is orphaned mid-step on a clean shutdown.

The claim path (`claim_next_workflow`) uses
`FOR UPDATE SKIP LOCKED` against the `workflows` table, so the worker
process **requires Postgres**. SQLite and MySQL work for tests and for
the enqueue/persistence path, but the worker returns an error at
startup, before its first claim, when the connection isn't Postgres:
`workflow:work` exits non-zero instead of running a worker that can never
claim a workflow.

## Configuration

Five environment variables tune the worker. Out-of-range values are
clamped to safe minimums with a `tracing::warn!` so a typo in `.env`
cannot brick the daemon.

| Variable | Default | Notes |
|---|---|---|
| `WORKFLOW_POLL_INTERVAL_MS` | `1000` | Sleep between empty claim rounds |
| `WORKFLOW_CONCURRENCY` | `4` | Max workflows running per worker (min 1) |
| `WORKFLOW_LOCK_TIMEOUT_SECS` | `30` | Lease duration before another worker may reclaim (min 2, max 253402300799) |
| `WORKFLOW_MAX_ATTEMPTS` | `3` | Per-workflow attempt budget (min 1) |
| `WORKFLOW_RETRY_BACKOFF_SECS` | `5` | Linear backoff: `attempts * value` (min 0; times the attempt budget, max 253402300799) |

`WorkflowWorker::new()` reads the config from the typed config registry and
panics at boot when the config is invalid or a `#[workflow]` name is
registered twice. For a config built in code, choose the constructor by
the checks you want:

| Constructor | Validates the config | Checks for duplicate names | On failure |
|---|---|---|---|
| `WorkflowWorker::new()` | yes | yes | panics |
| `WorkflowWorker::try_with_config(config)` | yes | yes | returns `Err(FrameworkError)` |
| `WorkflowWorker::with_config(config)` | no | no | never fails |

```rust
use suprnova::{FrameworkError, WorkflowConfig, WorkflowWorker};

fn build_worker() -> Result<WorkflowWorker, FrameworkError> {
    let config = WorkflowConfig {
        concurrency: 8,
        ..WorkflowConfig::default()
    };
    WorkflowWorker::try_with_config(config)
}
```

`with_config` skips both checks. If you use it, call
`WorkflowConfig::validate()` and `suprnova::workflow::assert_no_duplicates()`
where you build the worker.

## Crash recovery

Three layers of protection keep workflows from getting stuck on worker
failures.

**Panic boundary.** The workflow body runs inside
`AssertUnwindSafe(...).catch_unwind()`. A panic in any step is caught,
the payload is captured into the error column, and the row goes through
the same retry/fail accounting as a returned `Err`. Without the
boundary, a panic would skip the settlement path and leave the row at
`status='running'` forever.

**Lease heartbeat.** A long-running step that outlives
`WORKFLOW_LOCK_TIMEOUT_SECS` could otherwise have its lease expire under
its own feet. The worker spawns a heartbeat task that refreshes
`locked_until` at half the lock-timeout interval until the body
resolves. The heartbeat aborts on drop, so a returned `?` cannot leak a
renewal task and freeze the lease for a workflow nobody is running.

**Expired-lease reclaim.** When a worker dies without ever releasing
its lock (hard kill, host crash, kernel OOM), the row stays in
`status='running'` until `locked_until` passes. The claim query
explicitly picks up such rows: any `running` workflow whose lease has
expired becomes claimable by another worker on the next round, with
`attempts` incremented. Crash recovery is automatic - there's nothing
to script and no admin command to remember.

## Delivery semantics - at-least-once

Step bodies run with **at-least-once** semantics. A step may execute
more than once in two situations:

1. **Returned `Err`** - the workflow is requeued; on retry the failed
   step runs again, and any earlier steps replay from cache.
2. **Crash after the side effect, before `mark_step_succeeded` commits** -
   the lease expires, another worker reclaims, sees no cached output
   at that step index, and runs the body again.

The framework persists step **outputs** durably. [Event sourcing](event-sourcing.md)
keeps domain history for aggregate reconstruction instead. The workflow cannot observe
the side effect itself. Step bodies are your responsibility to make
idempotent. Two patterns work for almost every case.

**Conditional writes.** Use `INSERT ... ON CONFLICT DO NOTHING`,
idempotency-key columns, or `seen_event_id` markers. Derive a stable
per-step key from data already in scope: the workflow's input
arguments plus a literal step tag (`("wf-charge", customer_id)`) is
enough because the same arguments map to the same workflow row across
retries.

**External idempotency keys.** Most third-party APIs (Stripe, SES, SQS)
accept an `Idempotency-Key` header. Pass a key derived from the
workflow's input plus a step-local tag (`format!("wf-charge-{}", customer_id)`)
so retried requests deduplicate at the provider.

Do **not** assume a step that returned `Ok` cannot run a second time -
a crash can land that second run on any subsequent worker, including
after a restart on a different host. See the
[Idempotency](idempotency.md) chapter for `Idempotency::once`,
`Idempotency::commit_on_success`, and `Idempotency::remember` -
all valid wrappers around a step body.

## Determinism contract

Workflow replay reuses recorded step outputs. [Event sourcing](event-sourcing.md)
replays domain facts to rebuild aggregate state and read models.

Workflows must be deterministic across replays. Each step is keyed by
`(step_name, step_index)`, where `#[workflow_step]` names a step by its
module path and function name (`app::billing::charge`): two steps
called `charge` in two modules are two steps. A run recorded before the
module was part of the name stored the bare function name, and it
replays under that name. The framework caches each step's serialized
input alongside the output. When a step at the same index is replayed
with a different serialized input, the framework returns an error rather
than masking the corruption by returning the cached output from the
prior input.

In practice this means:

- Don't branch on `Utc::now()`, `rand::random()`, or other
  non-deterministic sources outside a `#[workflow_step]`. Step bodies
  can call them freely - their result is captured in the step output
  cache.
- Don't conditionally insert steps. If a retry hits a different number
  of steps before a given index, you get a step-name mismatch error.
  Put branching logic inside a step.
- Don't change step argument shapes between deploys without renaming
  the step. Renaming changes `step_name`, which restarts caching from
  scratch for that step. Moving a step to another module renames it
  too.

## Waiting on results

`WorkflowHandle` lets the caller poll the row, wait for it to finish,
or fetch the serialised output.

```rust
use std::time::Duration;
use suprnova::{FrameworkError, WorkflowStatus};

let handle = start_workflow!(welcome_flow, 123).await?;

match handle.wait_with_timeout(Duration::from_secs(30)).await {
    Ok(WorkflowStatus::Succeeded) => { /* done */ }
    Ok(WorkflowStatus::Failed) => { /* persisted error column */ }
    Ok(_) => unreachable!("wait_* only returns terminal status"),
    Err(FrameworkError::Timeout { .. }) => {
        // Workflow is still running; fall through to async UX.
    }
    Err(other) => return Err(other),
}
```

`wait()` polls indefinitely - use only in tests or short-lived scripts
where blocking forever is acceptable. For HTTP request paths,
`wait_with_timeout(Duration)` always wins against the inner poll loop,
even if the underlying status query stalls. When the deadline passes, the
wait returns `FrameworkError::Timeout`, which carries the deadline
(`elapsed`) and what was awaited (`message`). `err.is_timeout()` asks for it
without a `match`. That is how you tell a workflow that is still running
from a failed status query, which is a different error. A timeout error
does **not** cancel the workflow - the worker continues, and
`handle.status().await` returns the live state later. If the error reaches
a response, it renders as `504 Gateway Timeout`.

`wait_with_options(Some(poll), Some(deadline))` exposes both knobs when
the defaults don't fit.

For typed outputs, define a `T: Serialize + DeserializeOwned` return on
the workflow and call `handle.output::<T>().await?`. The raw JSON is
available via `output_raw()`.

## Step caching, in detail

Step caching is keyed by **step name + step index**. The first
invocation of a step persists its input JSON, runs the body, and on
success persists the output JSON. A replay at the same index:

- Returns the cached output if the step is `succeeded` and the
  replayed input matches the cached input.
- Returns an error if the input differs (the determinism guard).
- Reruns the body if the step is `running` or `failed` (no cached
  output to return).

Step indexes are assigned by an `AtomicI32` per workflow context, so the
order is determined by the calls your workflow body makes. Branching
that produces a different step at the same index on a retry surfaces
as a step-name mismatch error rather than silently corrupting downstream
steps.

Outputs and inputs are stored as JSON TEXT, so all step return types
and arguments must be `Serialize + DeserializeOwned`.

## Detecting workflow context from a helper

`WorkflowContext::is_active()` returns whether the current task is
running under a workflow. Use it from helpers that need to behave
differently inside vs outside the worker - for example, a logger that
attaches the workflow tag only when one exists:

```rust
use suprnova::workflow::WorkflowContext;

fn maybe_workflow_tagged(message: &str) -> String {
    if WorkflowContext::is_active() {
        format!("[workflow] {message}")
    } else {
        message.to_string()
    }
}
```

Outside a workflow (called directly from a test or handler), a
`#[workflow_step]` function still runs - `WorkflowContext::current()`
simply returns `None`, the body executes without persistence, and the
step bypasses the cache entirely. That's intentional: it makes step
functions individually testable without standing up a worker.

### Why Suprnova diverges

Laravel doesn't have a first-class workflow primitive - jobs are
the closest neighbour, but they retry by re-running the whole job
body, not by resuming from the last successful step. Suprnova ships
workflows as a separate construct because Tokio makes the "stay
checked in to a slow async function for an hour" pattern cheap, and
because step-level persistence is the right abstraction for any
multi-step external interaction (provisioning a customer, running a
saga across two payment providers, generating a report that involves
several upstream APIs).

The design is closer to [DBOS](https://www.dbos.dev/) and
Cadence/Temporal than to a queue: durable state, deterministic replay,
explicit step boundaries. The difference from Temporal is operational
weight - there's no separate workflow service to run; the worker is
just `suprnova workflow:work` against your application database.

## Notes

- Step bodies can return any `Serialize + DeserializeOwned` type. The
  `()` unit type works for steps that exist only for their side effect.
- A `#[workflow_step]` function called outside a workflow context runs
  inline - no caching, no replay. This is how tests exercise step
  bodies directly.
- Step caching is `(step_name, step_index)`-keyed; rename a step (or
  reorder calls) and the caching resets for that step on the next
  replay.
- `start_workflow!` accepts any tuple of serializable arguments. Tuples
  preserve argument order so renaming positional parameters is safe;
  changing argument types is a schema break for any in-flight workflows.
- The framework's [observability](observability.md) layer captures
  worker structured logs (`worker_id`, `workflow_id`, `attempts`,
  `max_attempts`) on every settle path so you can audit retry budgets
  in production without instrumenting your steps.

## Next

- [Queues](queues.md) - one-shot background jobs with sync/redis/database drivers
- [Idempotency](idempotency.md) - wrappers for at-least-once delivery
- [Bus](bus.md) - synchronous command dispatch with typed results
- [Supervisors](supervisors.md) - long-lived task supervision with panic-catch auto-restart
- [Error Model](error-model.md) - `FrameworkError`, the panic boundary, and why settlement runs through `?`


---

<!-- /docs/supervisors -->

# Supervisors

A supervisor is a long-lived Tokio task that the framework starts at boot and restarts automatically when it exits. Supervisors are for "always-on" work: background heartbeats, metrics collectors, connection warmers, periodic sweepers, or any async loop that should never stop running. They are distinct from [queue workers](queues.md), which consume discrete `Job` items from a queue. A supervisor has no job queue - it owns its own loop and decides when to sleep, wait, or act.

The `SupervisorRegistry` starts every registered supervisor as a detached Tokio task, watches each task's `JoinHandle`, and restarts it according to its `RestartPolicy` when it exits - whether by returning `Err`, returning `Ok`, or panicking. Restarts are separated by an exponential backoff that starts at 100ms and caps at 60 seconds, so a crashing supervisor does not spin-loop and flood logs.

## Quick Start

Define a supervisor, register it via `inventory::submit!`, and call `SupervisorRegistry::start_all()` at bootstrap.

**`src/supervisors/heartbeat.rs`:**

```rust
use async_trait::async_trait;
use std::time::Duration;
use suprnova::supervisor::{RestartPolicy, Supervisor};
use suprnova::{FrameworkError, SupervisorEntry};
use tokio_util::sync::CancellationToken;

pub struct LogHeartbeat;

#[async_trait]
impl Supervisor for LogHeartbeat {
    fn name(&self) -> &'static str { "heartbeat" }

    async fn run(&self, cancel: CancellationToken) -> Result<(), FrameworkError> {
        loop {
            tokio::select! {
                _ = cancel.cancelled() => return Ok(()),
                _ = tokio::time::sleep(Duration::from_secs(60)) => {
                    tracing::info!("supervisor heartbeat tick");
                }
            }
        }
    }

    fn restart_policy(&self) -> RestartPolicy { RestartPolicy::Always }
}

// Use the re-exported `suprnova::inventory` so a scaffolded app doesn't need
// to add `inventory` as a direct dependency.
suprnova::inventory::submit!(SupervisorEntry {
    factory: || Box::new(LogHeartbeat),
});
```

**`src/bootstrap.rs`:**

```rust
use suprnova::supervisor::SupervisorRegistry;

pub async fn register() {
    SupervisorRegistry::start_all().await;
}
```

That is the full setup. The `LogHeartbeat` supervisor starts at boot, logs every 60 seconds, and - because `RestartPolicy::Always` restarts on both `Ok` and `Err` exits - is restarted immediately if the loop ever exits for any reason.

## Restart Policies

Each supervisor declares its `RestartPolicy` via the trait method. The default is `OnError`.

| Policy | Restarts when... | Use case |
|--------|-----------------|----------|
| `RestartPolicy::OnError` | `run()` returns `Err` or panics | Tasks that should run to completion on success (e.g., a one-time init job wrapped as a supervisor). |
| `RestartPolicy::Always` | `run()` returns either `Ok` or `Err`, or panics | True daemons - loops that should never return. If the loop exits for any reason, that is a bug and a restart is warranted. |
| `RestartPolicy::Never` | (never) | One-shot tasks that should run once and not be restarted regardless of outcome. |

```rust
fn restart_policy(&self) -> RestartPolicy { RestartPolicy::OnError }   // default
fn restart_policy(&self) -> RestartPolicy { RestartPolicy::Always }    // daemon loop
fn restart_policy(&self) -> RestartPolicy { RestartPolicy::Never }     // one-shot
```

**When to pick `Always` vs `OnError`.** An infinite loop supervisor (`loop { ... }`) should use `Always` - if the loop ever returns `Ok(())`, something unexpected happened and a restart is the correct response. A supervisor that does finite work and returns `Ok` on success (e.g., refreshing a cache once) should use `OnError` so that a clean finish does not trigger a restart.

**`Never` for one-shot work.** Prefer [queue workers](queues.md) or [scheduled tasks](scheduling.md) for work that runs on a schedule. Use `RestartPolicy::Never` when the supervisor pattern is convenient for something that must run once at startup and never again.

## Panic Handling

Panics inside `run()` are caught by the registry and treated as errors - a panicking supervisor is restarted with backoff rather than crashing the process. The registry monitors each supervisor's `JoinHandle` and detects panics via the standard Tokio join mechanism.

From the restart-policy perspective, a panic is always treated as an `Err` exit regardless of the policy:

- `OnError` - restarts after a panic (panic counts as error).
- `Always` - restarts after a panic (same as any other exit).
- `Never` - does not restart after a panic (same as any other exit).

The panic is logged at `error!` level with the supervisor name before the restart backoff begins.

## Backoff

When a supervisor exits and its policy says to restart, the registry waits before spawning the replacement:

| Consecutive restart | Delay |
|---------|-------|
| 1st | 100ms |
| 2nd | 200ms |
| 3rd | 400ms |
| 4th | 800ms |
| ... | doubles each time |
| Capped | 60s |

The backoff resets after a healthy run. The delay doubles on each *consecutive* restart up to the 60 s cap, but a run that stays up at least 60 s (the cap duration) is treated as healthy: the next restart drops back to the 100 ms floor instead of inheriting backoff that climbed during an earlier burst of failures. So a daemon that ran cleanly for hours and then blips restarts promptly, not after a 60 s wait it accumulated long ago.

The reset is liveness-based, and deliberately conservative: only a run that *outlives the maximum possible backoff* counts as healthy. A run that exits before that threshold carries the current backoff forward, so a genuinely flapping supervisor - one whose runs never reach the threshold - still ramps all the way to the 60 s cap and stays there. The reset never masks a supervisor that is crash-looping.

The 60-second cap prevents a permanently-broken supervisor from sleeping indefinitely or hammering external dependencies on every retry. Combine with `error!`-level logging to alert when a supervisor enters the high-backoff band.

## Graceful Shutdown

Supervisors receive a `CancellationToken` as a parameter to `run()`. The framework cancels this token on Ctrl-C / SIGTERM as part of `Server::run`'s shutdown sequence. Supervisors that want to flush state, finish in-flight work, or otherwise exit cleanly should `tokio::select!` on `cancel.cancelled()`:

```rust
async fn run(&self, cancel: CancellationToken) -> Result<(), FrameworkError> {
    loop {
        tokio::select! {
            _ = cancel.cancelled() => return Ok(()),
            _ = tokio::time::sleep(Duration::from_secs(60)) => {
                tracing::info!("supervisor heartbeat tick");
            }
        }
    }
}
```

The framework drains the supervisor JoinSet with a 5-second grace window after cancellation. Supervisors that do not honor the token within that window get aborted via `JoinSet::abort_all`. The drain runs after the WebSocket handler drain (so WS connections clean up first) and before telemetry buffers flush.

Supervisors that ignore the token entirely will run until the 5-second window expires and then be forcibly aborted. If your supervisor holds resources that need flushing (open file handles, in-flight HTTP requests, partially-written records), always select on `cancel.cancelled()` and clean up before returning.

### Embedders and integration tests

`Server::run` calls `SupervisorRegistry::shutdown(...)` for you. So do the other subcommands of your application binary (`queue:work`, `schedule:work`, `workflow:work`, the `queue:*` commands, `down`, `up`) and your `console` binary: after the command, and on every failure exit once your bootstrap has run, they cancel and drain the supervisors your bootstrap started with the same 5-second window, then wait for queued listeners. Code that calls `SupervisorRegistry::start_all()` outside those paths (embedders driving the framework from a custom binary, or integration tests that spin up supervisors directly) must also call `SupervisorRegistry::shutdown(timeout)` at teardown, or supervisor tasks will leak past the lifetime of the test:

```rust
use std::time::Duration;
use suprnova::SupervisorRegistry;

// Test setup
SupervisorRegistry::start_all().await;

// ... exercise the supervisor ...

// Test teardown - cancels the shared token, drains the JoinSet up
// to `timeout`, then `abort_all` for stragglers.
SupervisorRegistry::shutdown(Duration::from_secs(1)).await;
```

`shutdown` is a no-op if `start_all` was never called, so it is safe to call from teardown unconditionally.

## Observability

Every error-path restart emits an `error!`-level log entry with structured fields:

- `supervisor` - from `Supervisor::name()`.
- `error` - the error message from `run()`'s `Err` return value, or `"panic: <payload>"` for a caught panic, or `"join error: <detail>"` for an unusual join failure.
- `backoff_ms` - the backoff delay in milliseconds before the next spawn.

Panics are reported through the same error log - there is no separate "panicked" message:

```
ERROR suprnova::supervisor: supervisor errored; restarting after backoff supervisor=heartbeat error=connection refused backoff_ms=400
ERROR suprnova::supervisor: supervisor errored; restarting after backoff supervisor=heartbeat error="panic: \"deliberate test panic\"" backoff_ms=800
```

`RestartPolicy::Always` returning `Ok(())` emits a `warn!` (not `error!`) with the same `supervisor` / `backoff_ms` fields and the message "supervisor returned Ok under Always policy; restarting" - useful for spotting daemon loops that exited cleanly when they shouldn't have.

Supervisors do not get an automatic tracing span around `run()` - the registry spans the lifecycle (start, restart) but not the interior of the task. Emit your own `info_span!` or `instrument` your loop body if you want span context on work done inside the supervisor:

```rust
async fn run(&self, cancel: CancellationToken) -> Result<(), FrameworkError> {
    loop {
        tokio::select! {
            _ = cancel.cancelled() => return Ok(()),
            _ = async {
                let span = tracing::info_span!("heartbeat.tick");
                let _guard = span.enter();
                do_work().await.ok();
                tokio::time::sleep(Duration::from_secs(60)).await;
            } => {}
        }
    }
}
```

### Why Suprnova diverges

Laravel has no direct equivalent. PHP's request-per-process model makes always-on in-process daemons impossible - long-lived work has to live outside the request lifecycle, typically as a `supervisord`-managed worker process consuming a queue or a cron-scheduled command. Laravel's queue worker (`php artisan queue:work`) is the closest analogue, but it is still a one-shot CLI process that an external supervisor restarts.

Suprnova runs on Tokio inside a single long-lived process. Always-on background tasks fit naturally as supervised Tokio tasks alongside the HTTP server - no extra process boundary, no external supervisor, no separate IPC channel for state. The `Supervisor` trait is the in-process equivalent of `supervisord`, scoped to the framework's own task tree, with the same restart-on-exit + backoff guarantees.

`Queue` workers (which Laravel has) still ship - see [Queues](queues.md) - for discrete-job work. Supervisors cover the "always tick" case that Laravel pushes out of the framework boundary entirely.

## Out of scope

The following are intentionally left out:

- **Supervisor trees (parent/child).** There is no hierarchy - all supervisors are peers under the single `SupervisorRegistry`. Structured supervision (where one supervisor owns and restarts child supervisors) is orchestrator territory.

- **Resource limits (cgroup, memory, CPU).** Apply resource constraints through systemd unit files (`MemoryMax=`, `CPUQuota=`) or Kubernetes resource requests/limits at the pod level. The framework does not impose process-internal resource limits on individual supervisor tasks.

- **Multi-machine supervision.** Supervisors run within a single process on a single machine. Distributing supervision decisions across machines is orchestrator territory (Kubernetes, Nomad, systemd on multiple hosts).

## Reference

The four primary types - `Supervisor`, `RestartPolicy`, `SupervisorEntry`, `SupervisorRegistry` - are re-exported at the crate root (`suprnova::Supervisor`, etc.) in addition to the longer `suprnova::supervisor::*` path. The two free accessors stay under `suprnova::supervisor::*`.

| Symbol | Purpose |
|--------|---------|
| `Supervisor` | Trait to implement on your supervisor struct. Required methods: `name() -> &'static str`, `async fn run(&self, cancel: CancellationToken) -> Result<(), FrameworkError>`. Optional: `restart_policy() -> RestartPolicy` (defaults to `OnError`). The `cancel` token is signalled on process shutdown; select on `cancel.cancelled()` to exit cleanly before the 5-second abort window expires. |
| `RestartPolicy` | Enum with variants `OnError`, `Always`, `Never`. Controls when the registry spawns a replacement task. |
| `SupervisorEntry` | Inventory item. Declare `factory: fn() -> Box<dyn Supervisor>`. Submit one entry per supervisor via `suprnova::inventory::submit!(SupervisorEntry { factory: || Box::new(MySupervisor) })`. |
| `SupervisorRegistry::start_all()` | Async fn. Iterates all submitted `SupervisorEntry` values, spawns each supervisor as a detached Tokio task into the per-process JoinSet, and begins monitoring for restarts. Idempotent - the per-process statics are `OnceLock`s. Call once from your bootstrap `register()`. |
| `SupervisorRegistry::shutdown(timeout)` | Async fn. Cancels the shared cancellation token so every supervisor watching `cancel.cancelled()` exits, drains the JoinSet up to `timeout`, then `abort_all` for stragglers. `Server::run` invokes this as part of its shutdown sequence; embedders and integration tests that call `start_all` outside `Server::run` must call this themselves to avoid leaking tasks. No-op if `start_all` was never called. |
| `suprnova::supervisor::supervisor_tasks()` / `supervisor_cancel_token()` | Accessors that return `Option<&'static …>` to the underlying JoinSet and cancellation token. Used by `Server::run`'s shutdown sequence; exposed `pub` so embedders driving the framework from a custom binary can integrate. Application code should not need these. |

## Next

- [Queues](queues.md) - supervisor-vs-queue-worker decision and the discrete-job alternative
- [Scheduling](scheduling.md) - for periodic work that doesn't need a long-lived loop
- [Workflows](workflows.md) - for stateful, long-running work that needs durable resume
- [Broadcasting](broadcasting.md) - uses the same shutdown sequence (drain ordering)
- [Request Lifecycle](lifecycle.md) - where `Server::run` and the shutdown drain fit in


---

<!-- /docs/sse -->

# Server-Sent Events

Server-Sent Events (SSE) is the minimum one-way push channel from server to
browser: the browser opens `EventSource(url)`, the server keeps a
`text/event-stream` response open, and pushes framed events as they happen.
No WebSocket handshake, no permessage-deflate, no framing libraries - just
`data:`, `event:`, `id:`, `retry:` lines terminated by a blank line, per the
[WHATWG `EventSource`](https://html.spec.whatwg.org/multipage/server-sent-events.html)
specification.

Suprnova's SSE primitive plugs into the streaming-body path: build a
`Stream<Item = SseEvent>`, hand it to `HttpResponse::sse(...)`, and the
framework owns connection management, framing, headers, and panic
isolation. The connection stays open until the producing stream ends or
the client disconnects.

## When to reach for SSE vs WebSockets

| Property | SSE | WebSockets |
|----------|-----|------------|
| Direction | Server → browser | Bidirectional |
| Transport | Plain HTTP/1.1 or HTTP/2 | Upgrade-only |
| Reconnect | Automatic, with `retry:` and `Last-Event-ID` | Manual |
| Proxies / CDNs | Works through anything that allows long HTTP responses | Often needs explicit Upgrade support |
| Browser API | `EventSource` (built in) | `WebSocket` (built in) |
| Binary frames | Text only (UTF-8) | Text or binary |
| Per-tab connection cap | 6 (HTTP/1.1) / unlimited (HTTP/2) | Unlimited |

Reach for SSE when you only need server-to-client push (activity feeds,
notifications, log tails, AI streaming). Reach for [WebSockets](websockets.md)
when you need bidirectional traffic or binary frames.

## Quickstart

```rust
use futures::StreamExt;
use suprnova::{HttpResponse, Request, Response, sse::SseEvent};
use tokio::sync::mpsc;
use tokio_stream::wrappers::ReceiverStream;

pub async fn stream_ticks(_req: Request) -> Response {
    let (tx, rx) = mpsc::channel::<SseEvent>(16);
    tokio::spawn(async move {
        for i in 0..10 {
            let evt = SseEvent::data(format!("tick {i}"))
                .with_event("tick")
                .with_id(i.to_string());
            if tx.send(evt).await.is_err() {
                break; // client disconnected
            }
            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
        }
    });
    Ok(HttpResponse::sse(ReceiverStream::new(rx)))
}
```

Wire output for one tick:

```text
event: tick
id: 0
data: tick 0

```

The browser parses this and fires a `tick` event with `evt.data === "tick 0"`
and `evt.lastEventId === "0"`.

## The `SseEvent` API

`SseEvent` is the type you push onto the stream. It has two kinds:

* **Frame** - a normal event with optional `event` / `id` / `retry` and a
  multi-line `data` payload. Built via [`SseEvent::data`](#constructors),
  `SseEvent::json`, or `SseEvent::error`.
* **Comment** - a wire-only keep-alive (`:\n\n` or `: <text>\n\n`). Built
  via `SseEvent::comment(text)` or `SseEvent::keep_alive()`. The browser
  ignores comments by spec; the bytes traversing the connection are what
  keep idle proxies and load balancers from closing it.

### Constructors

| Constructor | Produces | Use |
|-------------|----------|-----|
| `SseEvent::data(text)` | Frame with only `data:` lines | The minimal event |
| `SseEvent::json(event, &payload)` | Frame with `event:` + JSON `data:` | The 95% case - `JSON.parse(evt.data)` on the client |
| `SseEvent::error(message)` | Frame with `event: error` | Domain-level error event, distinct from the connection-level `error` the browser fires on transport failure |
| `SseEvent::comment(text)` | Comment | Keep-alive with a marker the operator can spot in logs |
| `SseEvent::keep_alive()` | Empty comment (`:\n\n`) | Canonical minimum-bytes heartbeat |

### Builders

| Builder | Effect | On `Comment` |
|---------|--------|--------------|
| `.with_event(name)` | Sets `event:` field | Silent no-op |
| `.with_id(id)` | Sets `id:` field - required for resume semantics | Silent no-op |
| `.with_retry(Duration)` | Sets `retry:` field (ms); spec says `Duration::ZERO` means "reconnect immediately" | Silent no-op |
| `.try_with_event(name)` | Fallible variant - see [Security contract](#security-contract) | `Ok(self)` unchanged |
| `.try_with_id(id)` | Fallible variant of `with_id` | `Ok(self)` unchanged |

Builders on `Comment` are no-ops on purpose - the wire format has no way
to express "comment with an event name". A misuse stays silent rather
than converting the event to a frame and surprising the producer.

### Accessors

| Method | Returns |
|--------|---------|
| `.event()` | `Option<&str>` - the event name, if set |
| `.id()` | `Option<&str>` - the last-event-id, if set |
| `.retry()` | `Option<Duration>` - the reconnect delay, if set |
| `.payload()` | `&str` - the `data:` payload (or `""` for `Comment`) |
| `.is_comment()` | `bool` |
| `.comment_text()` | `Option<&str>` - the comment text, if this is a `Comment` |

### Wire encoding

`SseEvent::to_wire()` serializes the event to `Bytes` ready for the body
stream:

**Frame:**

```text
event: <event>\n   (only if Some)
id: <id>\n         (only if Some)
retry: <ms>\n      (only if Some)
data: <line>\n     (one per line in payload, after \r/\r\n normalization)
\n                 (terminator - required by the spec)
```

**Comment:**

```text
: <line>\n         (one per line in comment text; `:\n` for empty lines)
\n                 (flush boundary)
```

## Security contract

The SSE wire format uses CR / LF / NUL as field terminators with no
escape mechanism. A producer that lets user input reach `event:` or `id:`
without sanitizing would expose a field-injection vulnerability - a
value of `"legit\ndata: injected"` would produce two `data:` fields on
the wire, and `"legit\n\nevent: spoofed"` would terminate the current
event and start a new one.

Suprnova's `to_wire()` defends in two layers:

* **`event:` and `id:` field values** - every CR / LF / NUL is stripped
  at serialize time. A structured `WARN` fires for every strip:
  `target: "suprnova::sse"`, `field = "event"|"id"`. The warn never
  logs the value - those bytes are attacker-controlled by construction.
* **`data:` and comment text** - `\r\n` and bare `\r` are normalized to
  `\n` before splitting, so a producer embedding `\r` in a payload
  cannot cause the receiver's parser to synthesize a `data:` / `event:` /
  `id:` field at parse time. NUL is stripped from comment text with a
  matching `WARN`.

If you want to **fail fast** on bad input rather than silently strip,
reach for the `try_with_*` siblings:

```rust
use suprnova::{Response, sse::SseEvent};

let evt = SseEvent::data("hello")
    .try_with_event(&user_supplied_event)?     // returns Err on CR/LF/NUL
    .try_with_id(&user_supplied_id)?;
```

The returned `FrameworkError::validation(field, ...)` names the field;
it does NOT echo the value back, so a 400 surfaced to the client is
safe to log.

## Keep-alive and proxy idle timeouts

Long-lived SSE connections are silent by default. Most production
deployments sit behind a proxy / load balancer / CDN that closes idle
connections to free resources:

* nginx default: 60 seconds
* AWS ALB default: 60 seconds
* Cloudflare default: 100 seconds

A `keep_alive()` comment every 15-30 seconds keeps the connection alive
through all of those without dispatching a `message` event to the
browser. The minimum-bytes form (`:\n\n`) is enough to flush proxy write
buffers without sending any payload.

```rust
use std::time::Duration;
use futures::StreamExt;
use suprnova::sse::SseEvent;
use tokio::sync::mpsc;
use tokio_stream::wrappers::ReceiverStream;

let (tx, rx) = mpsc::channel::<SseEvent>(16);

// Heartbeat task - independent of the event producer.
let hb_tx = tx.clone();
tokio::spawn(async move {
    let mut ticker = tokio::time::interval(Duration::from_secs(20));
    loop {
        ticker.tick().await;
        if hb_tx.send(SseEvent::keep_alive()).await.is_err() {
            break; // client gone
        }
    }
});

// Event producer ... sends frames into `tx` as they happen.
```

## Resume after drop (`Last-Event-ID`)

When the browser's `EventSource` drops the connection, it reconnects
automatically and sends the most recent `id:` it saw as the
`Last-Event-ID` header on the new request. Tag each event with
`.with_id(...)` and read the header on the resume request:

```rust
use futures::StreamExt;
use suprnova::{HttpResponse, Request, Response, sse::{self, SseEvent}};

pub async fn stream_from_resume(req: Request) -> Response {
    let resume_from: u64 = sse::last_event_id(&req)
        .and_then(|s| s.parse().ok())
        .unwrap_or(0);

    // Build the producer stream from `resume_from + 1` onward. The closure
    // owns its own running counter so the mutation stays inside the stream.
    let stream = futures::stream::iter(events_since(resume_from))
        .scan(resume_from + 1, |next_id, payload| {
            let id = *next_id;
            *next_id += 1;
            futures::future::ready(Some((id, payload)))
        })
        .map(|(id, payload)| {
            SseEvent::json("activity", &payload)
                .expect("payload is a Serialize value")
                .with_id(id.to_string())
        });

    Ok(HttpResponse::sse(stream))
}
```

`sse::last_event_id(&Request) -> Option<String>` returns any id
`.with_id(...)` accepts, Unicode included: the browser sends the id as
UTF-8, and the helper decodes it as UTF-8. It returns `None` when the
header is absent, when its bytes are not UTF-8, or when the value
contains a NUL byte (per the WHATWG spec, NUL invalidates a
last-event-id and the browser's parser would drop it). The returned
`String` is otherwise opaque user input - parse it as your own cursor /
sequence / offset before using it.

## Domain-level errors

`SseEvent::error("...")` produces the conventional `event: error\ndata: <msg>\n\n`
shape. Subscribers can listen for it separately from the connection-level
`error` the browser fires on transport failure:

```js
const es = new EventSource("/stream");

// Connection / transport errors (no `data`).
es.onerror = (evt) => console.warn("transport error", evt);

// Domain-level errors emitted by SseEvent::error(...).
es.addEventListener("error", (evt) => console.error("server-side:", evt.data));
```

When mapping a `Stream<Item = Result<T, E>>` to `Stream<Item = SseEvent>`,
the idiomatic pattern is `map(|r| match r { Ok(x) => SseEvent::json(...), Err(e) => SseEvent::error(...) })` -
the consumer-side error mapping stays in the producer's hands and the
framework never has to invent a default shape.

## Broadcasting one stream to many subscribers

Fan-out to many SSE subscribers is already covered by the
[broadcasting subsystem](broadcasting.md): subscribe to a
`BroadcastHub` channel and adapt the `broadcast::Receiver` into the
`SseEvent` stream with `tokio_stream::wrappers::BroadcastStream` +
`.map(...)`. Each connection gets its own receiver; the hub handles
slow-consumer policy (`Lagged(n)` errors when a subscriber falls behind)
and you decide how to surface that to the client.

The working dogfood example at `app/src/controllers/sse_example.rs`
implements this in ~25 lines:

```rust
use futures::StreamExt;
use std::sync::Arc;
use suprnova::broadcasting::BroadcastHub;
use suprnova::container::App;
use suprnova::{HttpResponse, Request, Response, sse::SseEvent};
use tokio_stream::wrappers::BroadcastStream;

pub async fn stream(_req: Request) -> Response {
    let hub: Arc<dyn BroadcastHub> = App::make::<dyn BroadcastHub>()
        .expect("BroadcastHub not bootstrapped");
    let rx = hub.subscribe("user_registered");

    let stream = BroadcastStream::new(rx).map(|result| match result {
        Ok(envelope) => SseEvent::json("user.registered", &envelope.data)
            .unwrap_or_else(|_| {
                SseEvent::data(envelope.data.to_string())
                    .with_event("user.registered")
            }),
        Err(tokio_stream::wrappers::errors::BroadcastStreamRecvError::Lagged(n)) => {
            SseEvent::data(n.to_string()).with_event("lagged")
        }
    });

    Ok(HttpResponse::sse(stream))
}
```

The `lagged` event lets the client trigger a full refetch and resume -
the connection stays open through the lag.

## `event_stream` and `stream_json`

`HttpResponse::sse` takes full control of framing - you build every
`SseEvent` yourself. Two higher-level siblings cover the common shapes:

```rust
use suprnova::sse::{EndSignal, StreamedEvent};
use suprnova::{HttpResponse, Request, Response};
use tokio::sync::mpsc;

pub async fn progress(_req: Request) -> Response {
    let (tx, rx) = mpsc::channel::<StreamedEvent>(16);
    tokio::spawn(async move {
        for pct in [25, 50, 75, 100] {
            let evt = StreamedEvent::message(pct).unwrap();
            if tx.send(evt).await.is_err() {
                break; // client disconnected
            }
        }
    });
    let stream = tokio_stream::wrappers::ReceiverStream::new(rx);
    Ok(HttpResponse::event_stream(stream, EndSignal::default()))
}
```

`StreamedEvent::message(data)` defaults `event` to `"update"` - what
`useEventStream` listens for out of the box; `StreamedEvent::named(event,
data)` overrides it for a producer fanning out more than one logical
channel over the same connection. `data` reaches the wire unquoted for a
bare string, JSON-encoded otherwise. `event_stream`'s `end: EndSignal`
argument controls the terminal frame sent after the stream ends:
`EndSignal::default()` sends `event: update\ndata: </stream>\n\n`
(Laravel's own default, and what `useEventStream`'s `endSignal` option
checks for); `EndSignal::None` omits it; `EndSignal::text(...)` /
`EndSignal::Event(...)` customize it. This is Suprnova's
`ResponseFactory::eventStream($callback, $headers, $endStreamWith)`.

`HttpResponse::stream_json(stream)` - Laravel's
`ResponseFactory::streamJson` / `StreamedJsonResponse` - takes any
`Stream<Item = impl Serialize>` and flushes it as one incrementally-built
JSON array (`Content-Type: application/json`) instead of buffering the
whole collection first. The bytes on the wire are exactly
`[item,item,...]`; concatenate the whole response and it deserializes
with any JSON parser.

## Consuming from React / Vue / Svelte

Every Inertia kit ships Suprnova's stream client in `frontend/src/lib/stream/`:
`core.ts`, the engine all three kits share, and `index.ts`, the kit's hooks
over it. The hooks keep the names, options and results of Laravel's
`@laravel/stream-react`, `@laravel/stream-vue` and `@laravel/stream-svelte`, so
Laravel's stream examples work with the import changed to `lib/stream`.

| Hook | Request | Suprnova builder |
|---|---|---|
| `useStream(url, options)` | `fetch` POST, the response read as text as it arrives | `HttpResponse::stream_bytes` |
| `useJsonStream(url, options)` | The same, the whole response parsed as JSON when it ends | `HttpResponse::stream_json` |
| `useEventStream(url, options)` | `EventSource` GET, which the browser reconnects | `HttpResponse::event_stream` |
| `useJsonEventStream(url, options)` | `fetch` POST, each event's data parsed as JSON | `HttpResponse::event_stream` |

A React page that streams a chat reply and a deployment's progress:

```tsx
import { useJsonEventStream, useStream } from '../lib/stream'

type Step = { step: string; percent: number }

export default function Deploy() {
  const reply = useStream<{ message: string }>('/chat')
  const deploy = useJsonEventStream<Step, { environment: string }>('/deploy')

  return (
    <div>
      <button onClick={() => reply.send({ message: 'Hello' })}>Ask</button>
      {reply.isFetching ? <p>Connecting...</p> : <p>{reply.data}</p>}

      <button onClick={() => deploy.send({ environment: 'production' })}>Deploy</button>
      {deploy.events.map((event) => (
        <p key={event.step}>{event.step}: {event.percent}%</p>
      ))}
    </div>
  )
}
```

The `/deploy` handler reads the body and answers with an event stream:

```rust
use serde::Deserialize;
use suprnova::sse::{EndSignal, StreamedEvent};
use suprnova::{FrameworkError, HttpResponse, Request, Response};

#[derive(Deserialize)]
struct Deploy {
    environment: String,
}

pub async fn deploy(req: Request) -> Response {
    let input: Deploy = req.json().await?;
    let events = ["build", "migrate", "release"]
        .iter()
        .enumerate()
        .map(|(i, step)| {
            StreamedEvent::message(serde_json::json!({
                "step": format!("{step} {}", input.environment),
                "percent": (i + 1) * 100 / 3,
            }))
        })
        .collect::<Result<Vec<_>, _>>()
        .map_err(|e| FrameworkError::internal(e.to_string()))?;
    Ok(HttpResponse::event_stream(
        futures::stream::iter(events),
        EndSignal::default(),
    ))
}
```

In Vue each result is a ref, read as `reply.data.value` in a script and as
`reply.data` in a template. In Svelte each hook returns a store, read as
`$reply.data`; call it while the component initializes. The event stream hooks
connect when their component mounts; the fetch hooks send on mount only when
`initialInput` is given and otherwise wait for `send`. Every hook cancels its
request when the component unmounts, so the server render opens no connection.

The `fetch` hooks send a JSON body with the CSRF token: from the `csrfToken`
option, else the `<meta name="csrf-token">` tag the root template writes, else
the `XSRF-TOKEN` cookie [CSRF protection](csrf.md) sets, sent back as
`X-XSRF-TOKEN`. They read it when a request starts, so a token rotated by a
sign-in is the one sent. `useStream` also sends `X-STREAM-ID`, a random id
that correlates requests and authenticates nothing; components that pass the
same `id` option share one stream, its text and its callbacks. `useEventStream`
sends neither: `EventSource` cannot set request headers, and a GET is not
CSRF-checked.

A request the server refuses reaches `onError` as a `StreamResponseError`
with the response's `status` and `body`: 419 for a missing CSRF token, 422
with the validation errors as JSON. `streamJsonEvents(request)` is the engine
under `useJsonEventStream` for state you keep yourself, and it takes any
method; a `GET` sends no body.

An application scaffolded before 4.2.1 can take the two files from a new
scaffold of the same kit (`suprnova new scratch --frontend react`). They import
nothing but the kit's UI framework.

Two details differ from Laravel's packages. One decoder reads a whole text
response, so a character whose bytes arrive in two reads comes out whole. A
response's error status reaches `onError` as a `StreamResponseError`, not a
plain `Error` holding the body.

## Production setup

### Response headers

`HttpResponse::sse(...)` sets the required headers for you:

| Header | Value | Why |
|--------|-------|-----|
| `Content-Type` | `text/event-stream` | Spec-defined; the browser's `EventSource` requires it |
| `Cache-Control` | `no-cache` | Stops intermediaries from caching the stream |
| `Connection` | `keep-alive` | HTTP/1.1 long-lived response |
| `X-Accel-Buffering` | `no` | Disables nginx proxy buffering - events flush immediately. No-op on non-nginx |

### Tuning reconnect

The default browser reconnect delay is 3 seconds. Send a `retry:` field
once at the start of the stream to override it:

```rust
let preamble = SseEvent::data("ready").with_retry(Duration::from_secs(5));
```

`Duration::ZERO` is valid per the spec ("reconnect immediately") and is
emitted verbatim - no coercion. For production streams a 5-15 second
retry strikes a balance between fast recovery and not hammering the
server during a regional outage.

### Why Suprnova diverges

Laravel ships SSE as a one-off helper on `Response`: `Response::eventStream(fn () => ...)`
takes a generator-yielding closure and frames each yielded value as a
`data:` line. It does not model `event:` / `id:` / `retry:` as first-class
fields, has no built-in keep-alive primitive, and does not sanitize values
that would inject extra fields on the wire.

Suprnova treats SSE as a real subsystem rather than a one-off helper:

- `SseEvent` is a typed value with fallible (`try_with_*`) and infallible
  (`with_*`) builders, distinct `Frame` and `Comment` kinds, and a
  documented sanitization contract on every single-line field.
- `HttpResponse::sse(stream)` plugs into the same `stream_bytes` body
  pipeline used by any other long-lived response, so SSE shares one
  cancellation, headers, and panic-isolation path with the rest of the
  framework.
- Producers compose any `Stream<Item = SseEvent>` - `tokio::sync::mpsc`,
  `tokio::sync::broadcast`, `futures::stream::iter`, or the
  [BroadcastHub](broadcasting.md) fan-out adapter. None of these require
  a framework escape hatch.
- A `Last-Event-ID` reader (`sse::last_event_id`) and the WHATWG NUL-drop
  rule are in the box, so resume-after-drop is one parse call away rather
  than a custom header utility per app.

## Reference

| Symbol | Purpose |
|--------|---------|
| `suprnova::sse::SseEvent` | One emittable piece of an SSE stream. Two kinds - `Frame` (event with optional `event` / `id` / `retry` + `data`) and `Comment` (keep-alive). |
| `SseEvent::data(text)` | Build a frame with only `data:` lines. |
| `SseEvent::json(event, &payload)` | Build a frame whose payload is `serde_json`-serialized `payload`; sets `event:` to `event`. Returns `Result<Self, serde_json::Error>`. |
| `SseEvent::error(message)` | Build a frame with `event: error` and the supplied message as `data`. |
| `SseEvent::comment(text)` | Build a comment-only event (`: <text>\n\n`). Browser-invisible; keeps proxies awake. |
| `SseEvent::keep_alive()` | Shorthand for the empty comment `:\n\n`. Minimum-bytes heartbeat. |
| `.with_event(name)` / `.with_id(id)` / `.with_retry(Duration)` | Infallible builders on a `Frame`; silent no-op on a `Comment`. Strip CR / LF / NUL at `to_wire()` time with a structured WARN. |
| `.try_with_event(name)` / `.try_with_id(id)` | Fallible siblings - return `Err(FrameworkError::validation(...))` on CR / LF / NUL. Use when the value flows from user input and you want a 4xx instead of a silent strip. |
| `.event()` / `.id()` / `.retry()` / `.payload()` / `.is_comment()` / `.comment_text()` | Accessors. `payload()` is named to avoid colliding with the `data` constructor. |
| `SseEvent::to_wire()` | Serialize to `Bytes` in the SSE wire format. Public so tests and adapters can encode without crossing the response builder. |
| `suprnova::sse::last_event_id(&Request) -> Option<String>` | Read the `Last-Event-ID` header, decoded as UTF-8. Returns `None` when absent, when the bytes are not UTF-8, or when the value contains a NUL byte (WHATWG drops invalid ids). |
| `suprnova::sse::last_event_id_from_value(Option<&str>)` | Pure helper exposing the same validation contract - unit-testable without building a `Request`. |
| `HttpResponse::sse(stream)` | Build a streaming response from any `Stream<Item = SseEvent> + Send + Sync + 'static`. Sets `Content-Type`, `Cache-Control`, `Connection`, `X-Accel-Buffering`. |
| `suprnova::sse::StreamedEvent` | One item pushed onto an `event_stream` - `{ event: String, data: serde_json::Value }`. |
| `StreamedEvent::message(data)` / `StreamedEvent::named(event, data)` | Build under the default `"update"` name, or an explicit one. Both return `Result<Self, serde_json::Error>`. |
| `suprnova::sse::EndSignal` | The terminal frame `event_stream` sends after the producer ends - `None` / `Message(String)` / `Event(StreamedEvent)`. `Default` is `text("</stream>")`. |
| `HttpResponse::event_stream(stream, end)` | Build an `event_stream` response from any `Stream<Item = StreamedEvent> + Send + Sync + 'static`. Built on `sse`. |
| `HttpResponse::stream_json(stream)` | Build a `stream_json` response from any `Stream<Item = impl Serialize> + Send + Sync + 'static`. Built on `stream_bytes`. |

## Next

- [WebSockets](websockets.md) - the other long-lived connection, when you need bidirectional or binary frames.
- [Broadcasting](broadcasting.md) - `BroadcastHub` fan-out shared with WebSocket subscribers.
- [Notifications](notifications.md) - channel drivers for non-streaming push delivery (mail, database, broadcast).
- [Web Push](web-push.md) - server-pushed notifications that reach the client when no `EventSource` is open.
- [Responses](responses.md) - the rest of the `HttpResponse` builder surface.


---

<!-- /docs/websockets -->

# WebSockets

Suprnova WebSocket routes sit alongside HTTP routes in the same router. You register a path and a handler; the framework detects the `Upgrade: websocket` request at that path, runs the same middleware chain an HTTP GET to that path would run, completes the RFC 6455 handshake, and calls your handler with a typed `WsSocket` plus the original `Request`. There is no separate WebSocket server - connections are upgraded from the same hyper listener that serves your HTTP traffic. The framework also tracks every spawned handler in a per-server `JoinSet`, so a graceful shutdown drains in-flight connections before the listener exits.

## Quick start

Add an `EchoHandler` and register it in `routes!`.

`src/ws/echo.rs`:

```rust
use async_trait::async_trait;
use suprnova::{FrameworkError, http::Request, ws::{WebSocketHandler, WsSocket}};

pub struct EchoHandler;

#[async_trait]
impl WebSocketHandler for EchoHandler {
    async fn handle(&self, mut socket: WsSocket, _req: Request) -> Result<(), FrameworkError> {
        while let Some(text) = socket.recv_text().await? {
            socket.send_text(format!("echo: {text}")).await?;
        }
        Ok(())
    }
}
```

`src/routes.rs` (inside `routes! { ... }`):

```rust
ws!("/ws/echo", app_ws::echo::EchoHandler),
```

Start the app and connect with `wscat`:

```bash
cargo run --bin app
```

```text
$ wscat -c ws://localhost:3000/ws/echo
Connected (press CTRL+C to quit)
> hello
< echo: hello
> suprnova
< echo: suprnova
```

When `recv_text()` returns `Ok(None)` the peer closed the connection; the loop exits, the handler returns `Ok(())`, and the framework sends a clean Close(1000) frame.

## Lifecycle of an upgrade

A WebSocket handshake is an HTTP GET with `Upgrade: websocket`. The framework runs the full request pipeline against it before any frames flow:

1. **Route match.** The router looks up the path in the WS route table; on miss the request falls through to the HTTP fallback.
2. **Origin policy.** The configured [`OriginPolicy`](#origin-policy) is enforced. A violation returns HTTP 403 with no upgrade.
3. **Subprotocol negotiation.** If the route has `accepted_protocols`, the first client-offered token that overlaps is echoed on the 101 response, in the client's own spelling.
4. **Middleware chain.** `RequestIdMiddleware` runs outermost, followed by every globally-registered middleware, followed by the route's per-route middleware. A non-2xx response from any middleware short-circuits the upgrade - the peer receives the HTTP error, and the WebSocket future drops cleanly. When the chain lets the upgrade through, the headers middleware added to its response, such as a session middleware's `Set-Cookie`, are sent on the 101. The handshake fields (`Connection`, `Upgrade`, `Sec-WebSocket-*`) and the body framing fields (`Content-Length`, `Content-Type`, `Content-Encoding`, `Transfer-Encoding`) stay the upgrade's own.
5. **Handshake.** `hyper_tungstenite::upgrade` produces the future that resolves into a `WebSocketStream`. Registered [terminable middleware](middleware.md#terminable-middleware---post-response-hooks) runs for the upgrade response like for any other response: with status 101, or with the status that refused the upgrade.
6. **Handler dispatch.** The (possibly middleware-rewritten) `Request` and a freshly-built `WsSocket` are handed to `WebSocketHandler::handle`.
7. **Heartbeat + handler.** The framework spawns a per-connection heartbeat task and awaits the handler future under a `ws.connection` tracing span carrying the request id.
8. **Close handshake.** On `Ok(())` the framework sends Close(1000); on `Err(_)` it sends Close(1011 "internal error"). The forwarder is awaited so the close frame is flushed to the wire before the connection's tracked task is reported done.

Return value semantics are inverted from HTTP: there is no body. `Ok(())` means clean disconnect; `Err(_)` is logged and the peer sees Close(1011). Either way the connection tears down.

## The `WsSocket` API

`WsSocket` is the bidirectional handle the framework passes to your handler. Internally the underlying tungstenite stream is split into Sink + Stream halves: a forwarder task owns the sink and drains an mpsc; the handler-facing send methods enqueue onto the mpsc. The handler reads directly from the stream half. This split means the framework can also push frames (heartbeat pings, broadcaster fanout) without contending with the handler's send path.

### `send_text`

```rust
socket.send_text("hello").await?;
socket.send_text(format!("user {id} joined")).await?;
```

Enqueues a UTF-8 text frame. Returns `Err` only when the connection is already closed.

### `send_binary`

```rust
socket.send_binary(bytes).await?;
```

Enqueues a binary frame. Accepts anything `Into<Vec<u8>>`. Same error semantics as `send_text`.

### `recv_text`

```rust
while let Some(text) = socket.recv_text().await? {
    // text: String
}
// Ok(None) means the peer closed.
```

Returns the next text message, silently discarding frame kinds a text-only handler isn't expected to care about:

- `Message::Binary` - peer binary payload
- `Message::Ping` - peer-initiated ping (tungstenite handles the pong automatically)
- `Message::Pong` - peer pong reply to a framework heartbeat (the missed-ping counter is reset to zero as a side effect)
- `Message::Frame` - raw frame variants from server-side contexts; never expected at this layer

A swallowed frame is gone; there is no retroactive way to see it. If the handler needs to observe binary frames or close codes, use [`recv`](#recv) from the very first read.

### `recv`

```rust
use tokio_tungstenite::tungstenite::Message;

while let Some(msg) = socket.recv().await? {
    match msg {
        Message::Text(t)   => { /* ... */ }
        Message::Binary(b) => { /* ... */ }
        Message::Close(_)  => break,
        _                  => {}
    }
}
```

Returns the next message of any kind, including Binary, Ping, Pong, and Close. `Pong` still resets the missed-ping counter as a side effect before it's returned. `Ok(None)` means the underlying stream ended.

### `close`

```rust
socket.close(1008, "policy violation").await?;
return Ok(());
```

Enqueues a close frame and returns. The forwarder writes the frame to the sink, calls `close()` on the sink, and terminates. Subsequent sends on the same socket return `Err` because the forwarder is gone. Always return `Ok(())` immediately after calling `close`.

`close` validates its arguments up front against RFC 6455 §7.4 + §5.5.1:

- `code` must satisfy `CloseCode::is_allowed()`. Reserved or invalid codes (1004, 1005, 1006, 1015, anything below 1000, anything above 4999) are rejected with `Err` and **no frame is sent** - the connection stays open and the caller can retry with a valid code. Use 1000 for normal closure, 1001-1013 for the defined reasons, 3000-3999 for IANA-registered codes, or 4000-4999 for application-private codes.
- `reason` is capped at 123 bytes (the 125-byte control-frame limit minus the two-byte code). Longer reasons are rejected without enqueuing anything.

### `sender`

Every method above takes `&mut self`. While the handler waits in `recv`, nothing else can send on the same `WsSocket`. `socket.sender()` takes `&self` and returns a `WsSender`, a handle on the same connection that you can move to another task:

```rust
use suprnova::{FrameworkError, ws::WsSocket};

async fn handle(mut socket: WsSocket) -> Result<(), FrameworkError> {
    let sender = socket.sender();
    let ticker = tokio::spawn(async move {
        let mut interval = tokio::time::interval(std::time::Duration::from_secs(1));
        loop {
            interval.tick().await;
            if sender.send_text("tick").await.is_err() {
                // The connection has ended.
                return;
            }
        }
    });

    while let Some(text) = socket.recv_text().await? {
        socket.send_text(format!("echo: {text}")).await?;
    }
    ticker.abort();
    Ok(())
}
```

A `WsSender` is cheap to clone, and every clone sends on the same connection, in the order the queue accepted the frames. The queue is bounded, so a send waits while the queue is full. A peer that reads slowly slows its senders down, and memory does not grow.

### `split`

`socket.split()` consumes the socket and returns `(WsSender, WsReceiver)`. Move each half into the task that owns that direction:

```rust
use suprnova::{FrameworkError, ws::WsSocket};

async fn handle(socket: WsSocket) -> Result<(), FrameworkError> {
    let (sender, mut receiver) = socket.split();

    let announcer = sender.clone();
    tokio::spawn(async move {
        let _ = announcer.send_text("welcome").await;
    });

    while let Some(text) = receiver.recv_text().await? {
        sender.send_text(format!("echo: {text}")).await?;
    }
    Ok(())
}
```

The `WsSender` clones. The `WsReceiver` has one owner.

### `WsSender`

| Method | Behaviour |
|---|---|
| `send_text(text)` | Enqueue a text frame. Takes `&self`. Returns `Err` when the connection has ended. |
| `send_binary(bytes)` | Enqueue a binary frame. Takes `&self`. Same error rule. |
| `close(code, reason)` | Send a close frame and end the connection for every sender. Takes the same `code` and `reason` rules as `WsSocket::close`. A frame that another sender queued behind the close frame is not sent. |
| `is_closed()` | `true` once the connection has ended: a close frame went out, a write to the peer failed, or the handler returned. |
| `closed()` | An async fn that completes when the connection has ended. |

The connection does not wait for its senders. When the handler returns, the framework sends the close frame and stops the forwarder, however many `WsSender` values are still alive. From then on every send returns `Err`, `is_closed()` returns `true` and `closed()` completes. A `WsSender` that outlives the handler does not hold the connection open. A task that keeps a sender treats any of the three as its signal to stop. A task that sends only rarely has no failed send to tell it the peer is gone, so it waits on `closed()` beside its own work:

```rust
use suprnova::ws::WsSender;

async fn pump(sender: WsSender, mut events: tokio::sync::mpsc::Receiver<String>) {
    loop {
        tokio::select! {
            _ = sender.closed() => break,
            event = events.recv() => match event {
                Some(text) => {
                    if sender.send_text(text).await.is_err() {
                        break;
                    }
                }
                None => break,
            },
        }
    }
}
```

### `WsReceiver`

`WsReceiver` has the read methods of `WsSocket`, with the same behaviour:

| Method | Behaviour |
|---|---|
| `recv_text()` | The next text message. Drops frames of every other kind. `Ok(None)` when the connection ends. |
| `recv()` | The next message of any kind. `Ok(None)` when the connection ends. |

It is also a `Stream` with `Item = Result<Message, FrameworkError>`, for code that combines it with other streams. The stream gives every message, as `recv` does, and ends when the connection ends.

**Read the receiving half.** The peer's answer to the framework's ping arrives on the receiving half, and the count of unanswered pings returns to zero only when that half reads the answer. If you drop the `WsReceiver`, or never read it, the connection closes with code 1011 after `max_missed_pings` pings. A handler that only sends must still read, and stop when the read returns `None`. See [Heartbeat and close-on-no-pong](#heartbeat-and-close-on-no-pong).

### Why Suprnova diverges

PHP frameworks bolt WebSocket support on as a separate process (ratchet, soketi, pusher). Suprnova's WebSocket route lives in the same `routes! { ... }` as your HTTP routes, served by the same hyper listener, drained by the same graceful-shutdown path. There is one binary, one config, one deploy. Long-lived connections are first-class because Tokio makes them cheap; the framework doesn't have to apologize for them.

## Path parameters

WebSocket routes support the same `{param}` capture syntax as HTTP routes. Captured values are available on the `Request` passed to the handler, percent-decoded the same way as HTTP route parameters: `/ws/rooms/a%20b` gives `"a b"`.

```rust
// In routes!:
ws!("/ws/rooms/{id}", RoomHandler),
```

```rust
use async_trait::async_trait;
use suprnova::{FrameworkError, http::Request, ws::{WebSocketHandler, WsSocket}};

pub struct RoomHandler;

#[async_trait]
impl WebSocketHandler for RoomHandler {
    async fn handle(&self, mut socket: WsSocket, req: Request) -> Result<(), FrameworkError> {
        let room_id = req.param("id")?;
        socket.send_text(format!("joined room {room_id}")).await?;
        while let Some(text) = socket.recv_text().await? {
            socket.send_text(format!("[{room_id}] {text}")).await?;
        }
        Ok(())
    }
}
```

`req.param("id")` returns `Result<&str, ParamError>`; the `?` propagates a `FrameworkError::ParamError` if the segment is missing, which causes the handler to return `Err` and the framework to send Close(1011). In practice the capture is always present when the route matched - the error path is a safety net against param-name typos.

Express-style `:id` segments are also accepted (`ws!("/ws/rooms/:id", h)`) and convert to matchit-form internally.

For the full `Request` API - headers, cookies, query string, peer address - see [the request docs](requests.md).

## Per-route middleware

Chain `.middleware(M)` on the `ws!` entry. Multiple middleware compose left to right and run in the same fixed order an HTTP request to the same path would run: `RequestIdMiddleware` outermost, then every globally registered middleware, then the per-route chain, then the handler.

```rust
ws!("/ws/private", PrivateHandler)
    .middleware(AuthMiddleware::new())
    .middleware(RateLimitMiddleware::connections_per_ip(100)),
```

`RateLimitMiddleware::connections_per_ip(100)` allows each client address 100 open sockets on the route and refuses the next upgrade with `429 Too Many Requests`. A socket counts until its session ends, which is when the handler has returned and the close handshake is done. An upgrade that a later middleware refuses gives its place back at once. The counts are kept in one process, and an IPv6 address counts with its /64 network. The address is `Request::ip()`, so set `APP_TRUSTED_PROXIES` behind a proxy. See [Rate Limiting](rate-limiting.md#capping-open-connections-with-connections_per_ip) for the full rules.

`connections_per_ip` counts through `Request::hold_for_connection(guard)`. A middleware calls it with a value whose `Drop` gives back what the middleware took. The server moves those values into the task that runs the socket and drops them when the task ends, so they outlive the middleware chain, which has returned by then.

A non-2xx response from any middleware short-circuits the upgrade. The peer receives the rejection (e.g. 401, 403) with `X-Request-Id` set, the unwoken WebSocket future drops cleanly, and the handler is never called. This is the right layer for transport-level checks: who may open the connection at all, where the connection is coming from, how many concurrent connections per identity.

Middleware can substitute a modified `Request` by calling `next(modified_req)`. The terminator captures whatever the chain ultimately passes through, and that is what the handler sees as its `Request` argument. Middleware that resolves identity (a session lookup, a token check) can attach the result via `Request` extensions; the handler reads it back the same way HTTP controllers do.

Direct-on-`Router` variants (`Router::ws`, `Router::ws_with_middleware`, `Router::ws_with_config`, `Router::ws_with_middleware_and_config`) cover the same surface for code that builds a `Router` outside the macro. Each has a fallible `try_*` sibling that returns `Err(FrameworkError)` on duplicate or malformed patterns instead of panicking.

### Why Suprnova diverges

Most ecosystems either skip middleware on WebSocket upgrades (the Node convention) or force a separate registration ceremony for "WebSocket middleware" (the .NET / Spring convention). Suprnova treats the upgrade as the HTTP GET it actually is: the same chain runs, in the same order, with the same short-circuit semantics. There is no second concept to learn - `AuthMiddleware`, `RateLimitMiddleware`, `RequestIdMiddleware`, `CorsMiddleware` work on WS routes because they work on any route. Origin enforcement is the only extra wrinkle, and it's a property of `WsConfig`, not a separate middleware.

## Auth at connect

The handler receives the middleware-rewritten `Request`. Three patterns work well, in increasing order of integration with the rest of the framework:

**Pattern 1 - inline bearer token in the handler.** Simplest. Works without any auth middleware. `wscat`, browser clients, and load balancers all pass headers cleanly.

```rust
use async_trait::async_trait;
use suprnova::{FrameworkError, http::Request, ws::{WebSocketHandler, WsSocket}};

pub struct PrivateChatHandler;

#[async_trait]
impl WebSocketHandler for PrivateChatHandler {
    async fn handle(&self, mut socket: WsSocket, req: Request) -> Result<(), FrameworkError> {
        let Some(token) = req.header("authorization")
            .and_then(|v| v.strip_prefix("Bearer "))
        else {
            socket.close(1008, "missing bearer token").await?;
            return Ok(());
        };
        let Some(user_id) = verify_token(token).await else {
            socket.close(1008, "invalid bearer token").await?;
            return Ok(());
        };
        while let Some(text) = socket.recv_text().await? {
            socket.send_text(format!("[user {user_id}] {text}")).await?;
        }
        Ok(())
    }
}

async fn verify_token(_token: &str) -> Option<i64> { Some(42) }
```

**Pattern 2 - gate the upgrade with a route middleware.** Reject unauthorized opens before any frames flow. Cleaner separation of concerns; the handler only sees authenticated connections.

```rust
ws!("/ws/private", PrivateChatHandler)
    .middleware(AuthMiddleware::new()),
```

`AuthMiddleware` returns 401 on unauthenticated requests; the upgrade is aborted with the rejection response and the handler is never called.

**Pattern 3 - middleware gate plus handler re-read.** Middleware short-circuits unauthorized opens; the handler then re-reads the same credential (token, cookie, etc.) it knows is now present to identify which user just connected:

```rust
async fn handle(&self, mut socket: WsSocket, req: Request) -> Result<(), FrameworkError> {
    // Middleware already vetted the bearer; we only get here if it was valid.
    let token = req.bearer_token().expect("auth middleware vetted bearer presence");
    let user_id = lookup_user_by_token(&token).await?;
    // ...
}
```

**Pattern 4 - let the middleware authenticate and read the result.** Preferred when an auth middleware already runs on the upgrade. The identity it resolved is carried on the request itself:

```rust
async fn handle(&self, mut socket: WsSocket, req: Request) -> Result<(), FrameworkError> {
    let Some(user_id) = req.auth_user_id() else {
        socket.close(1008, "unauthenticated").await?;
        return Ok(());
    };
    // `user_id` came from the session/token middleware, not from anything
    // the client sent in a frame.
    socket.send_text(format!("welcome, {user_id}")).await?;
    Ok(())
}
```

This is what makes a private broadcast channel's `authorize` hook meaningful: it receives the same `Request`, so it can gate on server-derived identity instead of a value the client chose. Before `auth_user_id` existed, a channel had nothing trustworthy to consult, and the obvious placeholder - "accept any subscriber whose subscribe frame carries a token that looks right" - is not a gate at all.

The thread-local accessors that work in HTTP controllers - `session()`, `Auth::user()`, the per-request `Context` bag - are still **not** populated inside a WebSocket handler. The middleware chain's task-local scopes unwind when the chain returns; the handler runs in a freshly spawned task that only inherits the request id and the resolved auth id. Read everything else the handler needs directly off the `Request` (headers, cookies via `req.cookie("...")`, captured params, the bearer token via `req.bearer_token()`) - those survive into the handler task.

### Why Suprnova diverges

Laravel authorizes broadcast channels over a separate HTTP endpoint (`/broadcasting/auth`), so the channel callback runs in an ordinary request with the full session available. Suprnova authorizes in-process during the upgrade instead - one connection, no second round trip - which means the identity has to be carried explicitly across the spawn boundary rather than looked up again.

## `WsConfig`

`WsConfig` controls per-connection behavior. Defaults aim at public, browser-facing endpoints - each active connection reserves a tungstenite buffer sized to `max_message_size`, so the framework defaults small and lets routes that need more raise the limits explicitly.

| Field                 | Default        | Type            | Effect |
|-----------------------|----------------|-----------------|--------|
| `ping_interval`       | 30s            | `Duration`      | How often the framework sends a Ping frame to keep the connection alive. |
| `max_message_size`    | 1 MiB          | `usize`         | Maximum reassembled message size in bytes. Larger messages are rejected by tungstenite. |
| `max_frame_size`      | 64 KiB         | `usize`         | Maximum single WebSocket frame size in bytes. |
| `max_missed_pings`    | 2              | `usize`         | Consecutive missed Pongs before the heartbeat closes the connection with code 1011. `usize::MAX` disables enforcement. |
| `origin_policy`       | `SameOrigin`   | `OriginPolicy`  | Origin-header check enforced at upgrade time. See [Origin policy](#origin-policy). |
| `accepted_protocols`  | `vec![]`       | `Vec<String>`   | Server's accepted `Sec-WebSocket-Protocol` tokens. Empty means no negotiation. See [Subprotocols](#subprotocols). |

Recommended overrides by use case:

- **Chat / notifications / cursor positions** - defaults are fine. Drop `ping_interval` to 5-10s if your LB has an aggressive idle timeout.
- **Trusted internal feeds** (server-to-server fan-out, bulk export, large binary transfers) - start from `WsConfig::generous()`, which raises `max_message_size` to 64 MiB and `max_frame_size` to 16 MiB while keeping other defaults.
- **Specific oversize payload** (one route that uploads 256 MiB audio files) - set the fields directly; don't apply the larger limit to routes that don't need it.

The config struct is `Default`-constructible and every field is public:

```rust
use std::time::Duration;
use suprnova::ws::WsConfig;

let chat = WsConfig {
    ping_interval: Duration::from_secs(5),
    max_missed_pings: 1,
    ..Default::default()
};

let trusted = WsConfig::generous();
assert_eq!(trusted.max_message_size, 64 * 1024 * 1024);
assert_eq!(trusted.max_frame_size, 16 * 1024 * 1024);
```

Apply the override per route either on the `ws!` entry or on `Router::ws_with_config`:

```rust
ws!("/ws/chat", ChatHandler).config(chat),
```

`WsConfig` is validated at route registration. A zero `ping_interval` would panic the heartbeat task, and a `max_missed_pings` below 2 would close every connection on its first ping; both are rejected at boot rather than failing at the first connection.

### Heartbeat and close-on-no-pong

For each upgraded connection the framework spawns a heartbeat task that sends `Ping(b"")` every `ping_interval`. On each tick the missed-ping counter increments; on each peer Pong it resets to zero. The peer's Pong is read by the code that reads the socket (`recv`, `recv_text`, or the `WsReceiver` after `split`), so a connection nobody reads is closed. If the counter reaches `max_missed_pings`, the heartbeat sends Close(1011 "no pong response") and the connection tears down. Set `max_missed_pings` to `usize::MAX` to disable enforcement (pings still flow, but the connection is never closed for missing pongs).

The first tick is consumed at task start so the peer gets at least one full interval of grace before the first ping.

## Origin policy

Browsers always send an `Origin` header on WebSocket handshakes. Unlike `fetch()` / `XMLHttpRequest`, WebSocket upgrades aren't protected by CSRF token middleware (the handshake carries no token), so a same-origin `Origin` check is the only thing standing between a malicious page and a privileged WS endpoint on a logged-in user's session. The framework enforces the configured policy before it answers the 101 and before the middleware chain runs; a violation returns HTTP 403 with no upgrade.

```rust
use suprnova::ws::{OriginPolicy, WsConfig};

let cfg = WsConfig {
    origin_policy: OriginPolicy::AllowList(vec![
        "https://app.example.com".into(),
        "https://admin.example.com".into(),
    ]),
    ..Default::default()
};
```

| Variant      | Behavior |
|--------------|----------|
| `SameOrigin` (default) | Allow only when `Origin` is the request's own origin: the same scheme, host, and port. A missing `Origin` is rejected, and so is a request whose public scheme the framework cannot determine. See [Same-origin behind a proxy](#same-origin-behind-a-proxy). |
| `AllowAny`   | Skip the check. Use only for non-browser endpoints (server-to-server, native apps, test mocks). |
| `AllowList(Vec<String>)` | Allow only when `Origin` exactly matches (case-insensitive) one of the supplied origins. Each entry is the full `scheme://host[:port]` form a browser would send. |

Non-browser clients (CLI tools, servers, native apps) typically don't send an `Origin` header. Routes that serve such clients exclusively should use `AllowAny`; routes serving both should use `AllowList` enumerating every production frontend origin.

### Same-origin behind a proxy

`SameOrigin` compares the whole origin. A page at `http://app.example.com` is a different origin from the application at `https://app.example.com`, so it can't open the application's socket.

The framework builds the request's own origin from three parts:

- **Scheme.** `Request::scheme()`, which reads `X-Forwarded-Proto` and `X-Forwarded-Ssl` only from a trusted proxy.
- **Host.** `Request::host()`: `X-Forwarded-Host` from a trusted proxy, otherwise the `Host` header.
- **Port.** `Request::port()`, or 443 for `https` and 80 for `http` when the request names no port. An `Origin` without a port takes the same defaults, so `https://app.example.com` and `app.example.com:443` match.

The framework itself serves plain HTTP. When it can't tell which scheme the browser used, it refuses the upgrade. That happens in three cases:

- The peer is a trusted proxy and sends neither `X-Forwarded-Proto` nor `X-Forwarded-Ssl`.
- The peer is a trusted proxy and `X-Forwarded-Proto` names a scheme other than `http` or `https`.
- The peer isn't a trusted proxy, but the request carries `X-Forwarded-Proto` or `X-Forwarded-Ssl`. The request came through a proxy that the application doesn't trust.

Behind a TLS-terminating proxy, do both of these:

1. List the proxy in `APP_TRUSTED_PROXIES`, for example `APP_TRUSTED_PROXIES=127.0.0.1`.
2. Have the proxy send `X-Forwarded-Proto`. The nginx example in [Production deployment](#production-deployment) sets it.

If the proxy can't be trusted, use `AllowList` with the exact public origins instead.

## Subprotocols

A WebSocket subprotocol is an application-level token (e.g. `graphql-transport-ws`, `jsonrpc-2.0`) the client and server agree on during the handshake. Populate `accepted_protocols` to participate:

```rust
use suprnova::ws::WsConfig;

let cfg = WsConfig {
    accepted_protocols: vec![
        "graphql-transport-ws".into(),
        "graphql-ws".into(),
    ],
    ..Default::default()
};
```

When the client offers `Sec-WebSocket-Protocol`, the framework picks the first client-offered token (in client preference order per RFC 6455 §4.2.2) that overlaps with `accepted_protocols`, matched case-insensitively, and echoes it on the 101 response exactly as the client spelled it. A client offering `CHAT` to a route that accepts `chat` gets `CHAT` back: RFC 6455 makes the client fail a handshake that names a protocol it did not offer, and browsers compare the strings exactly. If the client offered protocols but none matched, the upgrade still succeeds with no `Sec-WebSocket-Protocol` header - RFC 6455 then requires the browser to fail the connection client-side, which is the right behavior (a server that proceeded would silently be speaking the wrong protocol).

When `accepted_protocols` is empty, negotiation is skipped entirely - the upgrade response omits `Sec-WebSocket-Protocol` and the client falls back to default protocol handling.

## Production deployment

The framework handles the handshake and frame I/O. On the framework side, production needs one setting: list your proxy in `APP_TRUSTED_PROXIES`, so the [same-origin check](#same-origin-behind-a-proxy) can believe the scheme the proxy reports.

**TLS termination happens upstream.** Clients connect to `wss://` on nginx, Caddy, or the cloud load balancer; the proxy strips TLS and forwards plain `ws://` to the framework, with `X-Forwarded-Proto` naming the scheme the client used. The framework does not need a `rustls` feature or a TLS certificate.

### nginx

```nginx
location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}
```

`proxy_read_timeout` and `proxy_send_timeout` must be long enough to cover idle gaps between heartbeats. With the default 30s `ping_interval`, 3600s is a comfortable ceiling.

### Caddy

```caddy
reverse_proxy /ws/* localhost:3000 {
    header_up Upgrade {http.request.header.Upgrade}
    header_up Connection "Upgrade"
}
```

Caddy handles `Upgrade` / `Connection` automatically when proxying; the explicit `header_up` directives above are for clarity. Caddy sends `X-Forwarded-Proto` by default.

### Cloud load balancers (AWS ALB, GCP GLB)

Enable WebSocket support on the listener rule (AWS ALB does this automatically when the target group's protocol is HTTP/1.1 with sticky sessions off). Ensure the load balancer's idle timeout is at least as long as `ping_interval`; the framework's heartbeat keeps the wire active, but the LB drops connections that look idle from its perspective.

## Graceful shutdown

Every spawned WebSocket handler is tracked by the server. On `Ctrl-C` or an external shutdown signal, the listener stops accepting new connections and `Server::run` drains the set before the process exits. The handler future doesn't resolve until the close handshake has been flushed: after the user's `handle` returns, the framework awaits the forwarder so the final Close(1000) or Close(1011) frame is written to the wire before the connection's task is reported done. In a clean shutdown peers see a normal close, not a TCP reset.

Completed handles are reaped opportunistically during the lifetime of the server, so the `JoinSet` doesn't grow unbounded under long-running operation.

## Reference

| Symbol | Purpose |
|---|---|
| `suprnova::ws::WebSocketHandler` | Trait: `async fn handle(&self, socket: WsSocket, request: Request) -> Result<(), FrameworkError>`. `Send + Sync + 'static`. |
| `suprnova::ws::WsSocket` | Bidirectional handle. Methods: `send_text`, `send_binary`, `recv_text`, `recv`, `close`, `sender`, `split`. `close` validates code + reason length up front. |
| `suprnova::ws::WsSender` | Sending half. Clones, and every method takes `&self`: `send_text`, `send_binary`, `close`, `is_closed`, `closed`. From `WsSocket::sender` or `WsSocket::split`. |
| `suprnova::ws::WsReceiver` | Receiving half, one owner. `recv`, `recv_text`, and a `Stream` of `Result<Message, FrameworkError>`. Has to be read for the heartbeat to work. From `WsSocket::split`. |
| `suprnova::ws::WsConfig` | Per-connection config. Fields: `ping_interval`, `max_message_size`, `max_frame_size`, `max_missed_pings`, `origin_policy`, `accepted_protocols`. `Default` + `generous()` constructors. Validated at registration. |
| `suprnova::ws::OriginPolicy` | `SameOrigin` (default), `AllowAny`, `AllowList(Vec<String>)`. Enforced at upgrade time. |
| `ws!(path, Handler)` | Macro form for `routes! { ... }`. Returns a `WsRouteDef` supporting `.config(WsConfig)` and `.middleware(M)` in either order. |
| `Router::ws(path, handler)` | Direct registration. Returns `Router`. |
| `Router::ws_with_config(path, handler, cfg)` | Per-route `WsConfig` override. |
| `Router::ws_with_middleware(path, handler, mws)` | Per-route middleware list. |
| `Router::ws_with_middleware_and_config(...)` | Both. |
| `Router::try_ws*` family | Fallible siblings - return `Err(FrameworkError)` on duplicate or malformed patterns instead of panicking. |

## Next

- [Broadcasting](broadcasting.md) - channels, presence, the wire protocol on top of `ws!`
- [Server-Sent Events](sse.md) - one-way push for browsers behind strict proxies
- [Routing](routing.md) - what `routes!` and `ws!` actually expand into
- [Middleware](middleware.md) - writing middleware that gates HTTP and WS uniformly
- [Requests](requests.md) - headers, cookies, query, extensions on the `Request` your handler receives


---

<!-- /docs/live -->

# Live

Suprnova Live is the framework's server-driven interaction engine. A Live
component is a Rust struct whose state lives on the server, whose view is an
Askama template, and whose actions run over a signed protocol from a small
browser runtime that morphs the re-rendered HTML in place. There is no
client-side state model to keep in sync, no build tool to install to use the
shipped runtime, and no inline JavaScript in your documents.

This chapter covers the application-facing surface: authoring a component,
registering it, serving documents and islands, the security boundaries every
Live request crosses, uploads, asynchronous updates, assets, testing,
diagnostics, and recovery. Everything here uses only `suprnova::live` and
`suprnova::view`.

## Quick start

A project created by `suprnova new` is Live-ready: it ships `src/live/mod.rs`
with an empty component registry and a `routes()` function, its bootstrap
binds the registry, and `cmd/main.rs` installs the routes. Scaffold a
component, then check it:

```bash
suprnova live:make Counter
suprnova live:check
```

`live:make` writes `src/live/counter.rs` and `templates/live/counter.html`,
registers the component in `src/live/mod.rs`, and prints the next steps.
`live:check` builds your application and proves every registered view against
the integrated checker.

## Authoring a component

```rust
use suprnova::live::{LiveComponent, live};

/// A counter rendered by `live/counter.html`.
#[derive(LiveComponent)]
#[live(name = "app.counter", view = "live/counter.html")]
pub struct Counter {
    /// Current count, exposed to the view.
    #[public]
    count: u64,
}

#[live]
impl Counter {
    /// Increments the counter in response to `live:click="increment"`.
    #[action]
    pub fn increment(&mut self) {
        self.count += 1;
    }
}
```

- `name` is the registered component name. Use a dotted, kebab-case name
  such as `app.counter`; the CLI derives `<package>.<kebab>`.
- `view` is the template identity, relative to the template root.
- `#[public]` fields are rendered and carried in the signed snapshot. `#[model]`
  fields additionally accept browser proposals through `live:model`.
  A model field declares its timing on the attribute, such as
  `#[model(debounce = 250)]`; a debounce is 100, 250, or 500 milliseconds,
  the durations `live:model.debounce.<n>ms` accepts, and any other fails to
  compile.
  A form submitted with `live:submit` proposes every model control inside
  it in one request, which carries up to 127 fields beside the action;
  `live:check` refuses a larger form.
  A proposal the field cannot decode, such as an empty number for a `u64`
  field, is a validation error on that field: the action does not run, the
  field keeps its value, and `live:error` shows the error.
  A `live:error` output under a field shows the message the server resolved
  for it: the rule's own `message = "..."`, else the validation catalog's
  text in the request's locale. An error with no words of its own, such as
  the undecodable proposal, shows the generic validation announcement.
- `#[action]` methods are the only entry points the browser can invoke. They
  receive validated arguments and may return typed outcomes such as a
  redirect or a flash.
- `#[session]` fields live in the visitor's session, not in the snapshot.
  Each request that runs the component for one visitor reads them from the
  session, and a request whose outcome is accepted writes them back; a
  failed action leaves the session as it was. A public seed, which every
  visitor shares, renders them with their defaults. They need
  `SessionMiddleware` on the page and on the Live routes.

Every field type must implement `Default`; a fresh island starts from those
defaults unless a mount hook says otherwise.

## Views

Views are Askama templates. The template root is `templates/` unless an
`askama.toml` names other directories, so `live/counter.html` lives at
`templates/live/counter.html`:

```html
<div>
<p>Count: {{ count }}</p>
<button type="button" live:click="increment">Increment</button>
</div>
```

The view sees every field that is not secret by its name, such as
`{{ count }}`, and the component itself as `component`, so
`{{ component.total() }}` calls a method. A field may be named `component`
too: the view then reads the field as `component` and the component as
`component_`, or as the first of `component__`, `component___`, and so on
that no field takes.

Directives use the closed `live:` grammar: `live:click`, `live:submit`,
`live:model`, `live:upload`, `live:key`, `live:loading`, and the rest of the
documented set. The checker proves every directive against the component:
an unknown action, an unknown model field, a raw `safe` filter, or an
accessibility violation fails `live:check` with the file, line, and column.
`live:key` names an element's stable identity across morphs, and it is the
one key attribute a template writes: the runtime reads it for morph
identity, for morph controls such as `live:preserve.self`, and for the
scopes that keep browser state; `data-suprnova-live-key` is the engine's
own spelling on the roots it renders. `live:key` values and element ids
inside an island use one alphabet, the one the runtime checks at every morph:
an ASCII letter or digit first, then letters, digits, `_`, `-`, `.`, and `:`,
at most 128 bytes, each unique in the island. `live:check` refuses a literal
key or id outside it, and a literal id inside a loop, which every item after
the first would repeat.

### Action arguments

An action directive can pass literal arguments to an action with
parameters. Write them after the action name, in the order the action
declares its parameters:

```rust
use suprnova::live::{LiveComponent, live};

/// A task list rendered by `live/tasks.html`.
#[derive(LiveComponent)]
#[live(name = "app.tasks", view = "live/tasks.html")]
pub struct Tasks {
    /// Titles of the tasks still open.
    #[public]
    open: Vec<String>,
    /// Whether finished tasks stay visible.
    #[public]
    show_done: bool,
}

#[live]
impl Tasks {
    /// Removes the task at `index`, from `live:click="remove(0)"`.
    #[action]
    pub fn remove(&mut self, index: u64) {
        if let Ok(index) = usize::try_from(index)
            && index < self.open.len()
        {
            self.open.remove(index);
        }
    }

    /// Adds a task, from `live:click="add('Write the report', true)"`.
    #[action]
    pub fn add(&mut self, title: String, show_done: bool) {
        self.open.push(title);
        self.show_done = show_done;
    }
}
```

```html
<div>
<button type="button" live:click="remove(0)">Remove the first task</button>
<button type="button" live:click="add('Write the report', true)">Add a task</button>
</div>
```

The arguments are literals, never expressions: JSON numbers, strings in
single or double quotes with JSON escapes, `true`, `false`, and `null`, up
to 128 of them. Each literal binds the parameter at its position, and you
can leave out a trailing parameter whose type is an `Option`. The same
syntax works on every directive that invokes an action: `live:click`,
`live:submit`, `live:change`, `live:input`, `live:keydown`, and `live:init`.

`live:check` checks each call against the action's signature. A call with
too many arguments, without a required one, or with a literal of the wrong
type, such as `remove('first')` above, fails with the file, line, and
column of the directive. At runtime, the island root lists each action's
parameter names in its `data-suprnova-live-actions` attribute, and the
runtime sends `remove(0)` as the arguments `{ "index": 0 }`.

An argument written with `{{ }}`, such as `remove({{ loop.index0 }})`, is
dynamic: the checker can't prove it, so `live:check` reports it as
unproved. The runtime parses the rendered text with the same grammar, so a
quote inside an interpolated string changes the arguments. Interpolate
only values that render as a literal, such as numbers.

Documents that place islands are ordinary views declared with
`#[suprnova::view]`; the only unescaped value they accept is `TrustedHtml`
through the `trusted_html` filter.

## Registration and bootstrap

`src/live/mod.rs` owns the registry and the routes:

```rust
use suprnova::live::{LiveRegistry, RegistryError};

pub mod counter;

/// Builds the registry of every Live component in this application.
pub fn registry() -> Result<LiveRegistry, RegistryError> {
    let registry = LiveRegistry::builder()
        .register::<counter::Counter>()?
        .build();
    Ok(registry)
}
```

Bind it during bootstrap so the server, the workers, and the `suprnova
live:*` commands see the same components:

```rust
suprnova::App::singleton(crate::live::registry().expect("Live component registry"));
```

The registry is immutable once the runtime assembles. A duplicate component
name or view, or a component whose actions need validation without a
validation port, fails registration with a typed `RegistryError`.

## Routes

`Router::try_live()` installs the reserved namespace exactly once:
`/__live/action`, `/__live/upload`, the `/__live/async/*` control
routes and WebSocket handshake, and the immutable `/__live/assets/*`
routes. Startup fails if an application route can claim `/__live`.
Behind a reverse proxy that serves the application under a path prefix,
the routes still match `/__live/...` as the application receives it, and
the page names them under the public root: the configuration element's
endpoint is `/billing/__live/action`, and the browser runtime reaches the
upload and asynchronous routes beside it
([Serving under a path prefix](deployment.md#serving-under-a-path-prefix)).

The reserved request routes carry a strict policy: every request needs
session, origin, CSRF, principal, tenant, and rate-limit facts. The framework
records the session and the CSRF proof; your application attaches the rest
with the route guard:

```rust
use std::sync::Arc;
use std::time::Duration;

use suprnova::live::{LiveTenantMiddleware, LiveTenantResolver};
use suprnova::rate_limit::memory::InMemoryRateLimiter;
use suprnova::{AuthMiddleware, FrameworkError, RateLimitMiddleware, Request, Router, SlidingWindowConfig, async_trait};

pub fn routes(router: Router) -> Result<Router, FrameworkError> {
    let limiter = Arc::new(InMemoryRateLimiter::new());
    router.try_live_with(|guard| {
        guard
            .middleware(AuthMiddleware::optional())
            .middleware(LiveTenantMiddleware::new(Arc::new(SingleTenant)))
            .middleware(RateLimitMiddleware::new(
                limiter,
                SlidingWindowConfig { max_requests: 600, window: Duration::from_secs(60) },
                |request: &Request| format!("live:{}", request.ip().unwrap_or_else(|| "anon".into())),
            ))
    })
}

struct SingleTenant;

#[async_trait]
impl LiveTenantResolver for SingleTenant {
    async fn resolve(&self, _request: &Request) -> Result<Option<String>, FrameworkError> {
        Ok(None)
    }
}
```

Install the routes from the entry point so the runtime and the mount catalog
are ready before the first request:

```rust
Application::new()
    .bootstrap(bootstrap::register)
    .try_routes(|| live::routes(routes::register()))
    .run()
    .await;
```

## Documents and islands

A document route declares its islands once, renders them through
`LiveDocument`, and emits the bootstrap tags:

```rust
use std::collections::BTreeMap;

use suprnova::live::{CanonicalValue, LiveBootstrapOptions, LiveDocument, LiveMount, MountFlags};
use suprnova::view::{AssetSet, DocumentResponseIntent, TrustedHtml, ViewName};
use suprnova::{FrameworkError, HttpResponse, Request, Response, Router, StatusCode};

mod filters {
    pub use suprnova::view::filters::trusted_html;
}

#[suprnova::view(path = "live/page.html")]
struct Page<'a> {
    bootstrap: &'a TrustedHtml,
    counter: &'a TrustedHtml,
}

pub fn install(router: Router) -> Result<Router, FrameworkError> {
    let mount = LiveMount::<Counter>::identity_bound("/dashboard", "counter", "dashboard-counter")?;
    let handler_mount = mount.clone();
    let router: Router = router
        .get("/dashboard", move |request: Request| {
            let mount = handler_mount.clone();
            async move { render(request, &mount).await }
        })
        .middleware(AuthMiddleware::redirect_to("/login"))
        .into();
    router.try_live_mount(&mount)
}

async fn render(request: Request, mount: &LiveMount<Counter>) -> Response {
    let result: Result<HttpResponse, FrameworkError> = async {
        let mut document = LiveDocument::from_request(&request)?;
        let counter = document
            .mount(mount, CanonicalValue::Object(BTreeMap::new()), MountFlags::empty())
            .await?;
        let bootstrap = document.bootstrap(LiveBootstrapOptions::esm())?;
        document
            .render(
                ViewName::parse("live/page.html").map_err(|_| FrameworkError::internal("view"))?,
                &Page { bootstrap: bootstrap.html(), counter: counter.html() },
                DocumentResponseIntent::html(StatusCode::OK).map_err(|_| FrameworkError::internal("intent"))?,
                AssetSet::empty(),
            )
            .map_err(FrameworkError::from)
    }
    .await;
    result.map_err(|_| HttpResponse::text("Live document failed").status(500))
}
```

- `LiveMount::public_seed` declares an island any visitor may render; its
  state is a reusable seed promoted to an instance on its first request, an
  action or a model update.
- `LiveMount::identity_bound` declares an island that belongs to the current
  session and principal; the document route must authenticate.
- Mount every island before `bootstrap`, and call `bootstrap` once. The
  bootstrap emits the inert configuration element and the script tags for
  the ESM or classic strategy, adding the upload and asynchronous roles when
  a mounted component needs them and the Stimulus bridge on request.
- The document template places `{{ bootstrap|trusted_html }}` in `<head>` and
  each island where it belongs.

### Shared view data

A layout often needs a value every page has, such as the application's
name or the signed-in user, without every view struct carrying a field for
it. `View::share` makes a value available to every document and island the
application renders afterwards, as Laravel's `View::share` does.
`View::share_for_request` does the same for the current request alone, and
its values win over the application's. A template reads a shared value
with Askama's `value` filter, naming the type you shared:

```rust
use suprnova::{FrameworkError, Middleware, Next, Request, Response, View, async_trait};

pub fn boot() {
    View::share("app_name", "Acme".to_string());
}

pub struct ShareViewer;

#[async_trait]
impl Middleware for ShareViewer {
    async fn handle(&self, request: Request, next: Next) -> Response {
        if let Some(name) = request.header("X-Viewer") {
            View::share_for_request("viewer", name.to_string())?;
        }
        next(request).await
    }
}
```

```html
<title>{% if let Ok(name) = "app_name"|value::<String> %}{{ name }}{% endif %}</title>
<p>{% if let Ok(viewer) = "viewer"|value::<String> %}Hello, {{ viewer }}{% else %}Hello{% endif %}</p>
```

A value nobody shared fails the render, so test for it with `if let Ok(..)`
where it can be missing. `View::shared::<T>(key)` answers the value a render
would read: the request's value, else the application's, `None` when
neither is a `T`. A view keeps reading its own fields by name; shared
values arrive only through the `value` filter.

The application's values belong to the application container, so a test
under `TestContainer::fake()` sees only what it shared. A request's values
live in the request's container scope; `View::share_for_request` returns an
error outside one. A page whose render read a value shared for the request
is never stored in the [render cache](render-cache.md), so it is never
served to another request. `App::inertia_share` keeps reaching Inertia props
only.

#### Why Suprnova diverges

Laravel's `View::share` is process-wide, which is safe because PHP serves
one request per process. One Rust process serves many requests at once, so
the request's own values need `View::share_for_request`, and a shared value
reaches the template through Askama's runtime values rather than as a
variable, because a checked template knows its variables at compile time.
A Live component template reads the application's values on every render,
a public seed's and an action's included, but never a value shared for the
request: a component's view is rendered again on its action requests, and a
public seed is shared between visitors. A component template that requires
a request's value fails its render.

## Security boundaries

Live never bypasses the framework's middleware. What each request needs:

| Fact | Recorded by |
|---|---|
| Session | `SessionMiddleware` |
| Origin and CSRF | `CsrfMiddleware` with origin verification enabled |
| Principal | `AuthMiddleware` on its authenticated branch |
| Tenant | `LiveTenantMiddleware` with your resolver |
| Rate limit | `RateLimitMiddleware` on its allowed branch |

The shipped runtime sends the Live media type and the browser's own
`Sec-Fetch-Site` header; it carries no session token. The CSRF middleware
verifies that proof for every Live request on its own, whatever origin policy
you configure, so a same-origin Live request passes with the stateless CSRF
disposition while a cross-site or header-less request falls back to token
validation and is refused. Ordinary routes keep token validation under the
default policy; using Live relaxes nothing else:

```rust
global_middleware!(CsrfMiddleware::new());
```

Anonymous visitors render public seeds, and they can act on them when the
guard uses `AuthMiddleware::optional()`: a signed-in principal is recorded, an
anonymous visitor continues, and the mount kind decides. A public seed then
promotes for the visitor's own session on its first request, while an
identity-bound island still refuses a request without principal evidence.
With `AuthMiddleware::new()` the guard answers `401` for every anonymous
request before any engine work. Identity-bound islands require a session and
a principal; the tenant is bound into the island's scope whenever your
resolver names one, and a resolver that cannot determine the tenant must
return an error rather than `None`. Every rejection is closed:
a `409` for a stale or tampered snapshot carries no body, and production
messages never include snapshots, tokens, cookies, or rendered HTML.

Gated actions, uploads, subscriptions and the principal of an asynchronous
membership read the route's user: the user of the guard the last
`AuthMiddleware` on the Live routes checked. The principal string your Live
gates receive is the bare id for the default guard, as `Auth::id()` reports
it, so a default-guard application sees the value it always saw. The one
exception is an id that holds a `:`: it gets a leading `:`, so web user
`admin:9` reaches your gates as `:admin:9` and never as admin `9`. Behind
`AuthMiddleware::for_guard(..)` naming any other guard - a second session
guard, a token guard, or a guard of your application (see
[Authentication](authentication.md)) - it is `<guard>:<id>`, such as
`admin:9`. A user of another guard in the same session never stands in for
the route's user, and a route whose guard has no user is refused.

A `:principal` topic parameter takes the same value. A `<guard>:<id>`
principal is not a topic segment, so behind a guard other than the default a
stream with a `:principal` topic does not resolve, and its subscription is
refused rather than bound to another guard's user. Give such a stream topics
that name their audience another way. Logging the guard out, or its
Magnetar session failing validation, ends that guard's memberships on this
node, as a default-guard logout does.

## Uploads

Declare an upload policy on a model field:

```rust
use suprnova::live::{LiveComponent, UploadPolicy, UploadReplacement, UploadScan, UploadType, live};

fn avatar_policy() -> UploadPolicy {
    UploadPolicy::builder()
        .maximum_files(1)
        .maximum_file_bytes(512 * 1024)
        .replacement(UploadReplacement::RetirePrevious)
        .accept(UploadType::Png)
        .scan(UploadScan::Disabled)
        .finalize_action("save_avatar")
        .build()
}

#[derive(LiveComponent)]
#[live(name = "app.avatar-uploader", view = "live/avatar-uploader.html")]
pub struct AvatarUploader {
    #[model]
    #[upload(policy = avatar_policy)]
    avatar: String,
}

#[live]
impl AvatarUploader {
    #[action]
    pub fn save_avatar(&mut self) {}
}
```

The view binds the field with `<input type="file" live:upload="avatar">`. The
runtime creates, transfers, and completes the upload through
`/__live/upload`; the file waits in quarantine until the declared finalize
action runs, when the framework hands it to your `UploadFinalizer`. Bind the
finalizer, and any scanner or validator, before the runtime assembles:

```rust
App::singleton(LiveUploadHost::new().with_finalizer(Arc::new(AppUploadFinalizer::default())));
```

Uploads are authorized per field and control through the gate. Define the
abilities `live:<component>.upload.<field>.<Control>` for `Create`,
`Reacquire`, `Status`, `Queue`, `BeginTransfer`, `PutChunk`, `Complete`,
`Accept`, `BeginFinalize`, `CommitFinalize`, `Cancel`, `Reject`, `Expire`,
and `Fail`.

### Checking a policy

The engine registers a component only when every upload policy in it is
valid. `UploadPolicy::validate()` returns `Ok(())` for a valid policy. For
an invalid one it returns the first rule that the policy breaks, as a
`suprnova::live::UploadPolicyError`. Use it in a test of the policy:

```rust
use suprnova::live::{UploadPolicy, UploadPolicyError};

#[test]
fn the_avatar_policy_is_valid() {
    assert_eq!(avatar_policy().validate(), Ok(()));

    let no_limit = UploadPolicy::builder().maximum_files(1).build();
    assert_eq!(no_limit.validate(), Err(UploadPolicyError::MaximumFileBytes));
}
```

| Variant | The policy breaks this rule |
|---|---|
| `MaximumFiles` | `maximum_files` is not set, or is `0` |
| `MaximumFileBytes` | `maximum_file_bytes` is not set, or is `0` |
| `AcceptedType { media_type }` | An `accept_application` media type or one of its extensions is not in canonical form. A media type is `type/subtype` in lower case letters, digits and `+ . -`, at most 127 bytes. It has 1 to 16 extensions of lower case letters and digits, each at most 32 bytes |
| `AcceptedTypes` | More than 16 accepted types, or one media type declared twice |
| `Dimensions` | A limit of `dimensions` is `0` |
| `MissingFinalizeAction` | `finalize_action` is not set |
| `FinalizeAction { name }` | The `finalize_action` name is not a valid action name |

The enum is `#[non_exhaustive]`, so a `match` on it needs a wildcard arm.
`validate()` does not check that the `finalize_action` names an action of
your component, because a policy does not know its component. The
registration checks that.

When you register a component, a refused policy fails the registration and
logs an error with the field and the rule (`the upload policy of a Live
field was refused`, with the `field` and `reason` fields). The error that
the registration returns is the same closed `invalid_component_upload_metadata`
error for every rule, so no detail of the component reaches a browser.

A browser that lost its transfer grant reacquires it through a route your
application owns outside the reserved namespace:

```rust
let router: Router = router
    .try_live_upload_reacquisition("/account/uploads/{handle}/reacquire")?
    .middleware(AuthMiddleware::new())
    .into();
```

The route requires the same facts as an action, answers only the session and
principal that created the upload, and returns a fresh grant with the current
transfer state.

## Asynchronous updates

A component declares the streams it listens to; the browser runtime
subscribes over SSE or WebSocket and falls back to polling:

```rust
use suprnova::live::{EventPayloadMetadata, LiveComponent, live};

pub struct ActivityPosted;

impl EventPayloadMetadata for ActivityPosted {
    const NAME: &'static str = "activity.posted";
    const VERSION: u16 = 1;
}

#[derive(LiveComponent)]
#[live(
    name = "app.activity-feed",
    view = "live/activity-feed.html",
    minimum_protocol_version = 2,
    streams(stream(name = "activity", topics("activity"), events(ActivityPosted)))
)]
pub struct ActivityFeed {
    #[public]
    headline: String,
}
```

Define the ability `live:<component>.stream.<name>` for subscribers, then
publish from anywhere in the application:

```rust
let streams = LiveStreams::resolve()?;
streams.event::<ActivityPosted>("activity", LiveEventTarget::Island, payload).await?;
streams.refresh("activity").await?;
```

A refresh tells subscribed islands to fresh-render; an event is delivered to
the island's registered handlers. Polling is the ordinary fresh render: the
island's state catches up whenever a transport is unavailable, but event
payloads published in between are not replayed to their handlers, which the
runtime reports as a degraded stream rather than a current one. A component
that declares exactly one stream gets its island root subscribed for it; a
component with several streams subscribes each through the runtime's
registered calls.

A stream ends with the session that opened it. When a session is destroyed on
the node holding the stream, through a plain logout, invalidation, id
regeneration, or a "log out everywhere", every membership it opened there is
retired at once and no later event reaches it. A session destroyed on another
node is caught by delivery itself: each membership's session is re-checked
against the session store at most once per ten seconds, so events stop within
that interval. The stream's gate is asked again before every delivery
regardless, so a policy change ends delivery immediately on every node.

## Topic signals

A topic signal says that named data changed. It carries the topic, its state
generation, a cursor within that generation, and the prop names that should be refreshed. It never carries a model
or its values. Live components can subscribe to the same topic, and an Inertia
page can turn the signal into a partial reload as described in [Live topic
bindings](frontend-pages.md#live-topic-bindings).

Declare application topics beside components in the immutable registry. A
private topic requires a signed-in principal and an ability named
`live:topic.<topic>`. A public topic explicitly permits anonymous subscribers:

```rust
use suprnova::live::LiveRegistry;
use suprnova::{FrameworkError, Gate};

pub fn registry() -> Result<LiveRegistry, FrameworkError> {
    Gate::define::<String, String>("live:topic.posts", |principal, _topic| {
        !principal.is_empty()
    });

    Ok(LiveRegistry::builder()
        .topic("posts")?
        .public_topic("announcements")?
        .build())
}
```

The second `String` passed to the gate is the registered topic name. Make the
ability express the audience for that topic; the signal contains no record
with which to make a row-level decision.

Resolve the publisher after binding the registry and its gates. Resolution
assembles and binds the Live runtime when needed. Then report changes from
handlers, services, or jobs:

Private data uses an owner-scoped family instead of one global topic. The
family authorizer receives the full instance name as its resource:

```rust
use suprnova::{Gate, live::{LiveRegistry, LiveTopics}};

Gate::define::<String, String>("live:topic.notes", |principal, instance| {
    instance == &format!("notes.{principal}")
});
let registry = LiveRegistry::builder().topic_family("notes")?.build();
suprnova::App::singleton(registry);
LiveTopics::resolve()?.on_model_scoped::<Note>(
    "notes", |note| note.user_id.to_string(), &["stats"],
)?;
```

The instances `notes.42` and `notes.73` have separate memberships, cursors,
rate windows, and fanout. `public_topic_family("announcements")?` explicitly
permits anonymous instances. A Live island can subscribe to an instance name such as `notes.42`, using
the same family ability check. A page supplies the key with the
[Live response loader](frontend-pages.md#live-topic-bindings).
`changed("notes.42", &["stats"]).await?` and
`changed_with_tx(&tx, "notes.42", &["stats"]).await?` publish to the same instance.
Family names cannot overlap another family or one of its static instances.

```rust
use suprnova::live::LiveTopics;

let topics = LiveTopics::resolve()?;
topics.changed("posts", &["posts", "post_count"]).await?;
let cursor = topics.cursor("posts").await?;
```

`changed` automatically registers its publish with `DB::after_commit`. Inside
an ambient database transaction it sends only after the outer commit, and a
rollback sends nothing. A committed change flushes when its request or job
ends. Outside both scopes it publishes immediately. Every queue job attempt
has a fresh coalescing scope. Repeated changes to one topic become one signal
whose prop list is the union. Use `batch` for another explicit unit of work:

```rust
let topics = LiveTopics::resolve()?;
topics
    .batch(async {
        import_posts().await?;
        topics.changed("posts", &["posts"]).await?;
        rebuild_post_count().await?;
        topics.changed("posts", &["post_count"]).await
    })
    .await??;
```

A manual transaction handle is not ambient state. Name it when the change
belongs to its commit. Rollback and savepoint rollback discard this callback:

```rust
let topics = LiveTopics::resolve()?;
let tx = suprnova::DB::begin_transaction().await?;
topics.changed_with_tx(&tx, "posts", &["posts"]).await?;
tx.commit().await?;
```

An empty prop list means reload every prop bound to the topic. It dominates
named props when changes merge. A union beyond 256 names also requests all
bound props, so the bounded transport never discards that invalidation.
`suppress` is for a replay or bulk operation
whose intermediate states must stay quiet. Changes inside its closure are
merged, then one final signal per touched topic is released:

```rust
let topics = LiveTopics::resolve()?;
topics
    .suppress(|| async {
        restore_posts_from_snapshot().await?;
        topics.changed("posts", &[]).await
    })
    .await??;
```

If a manual transaction commits after the closure returns, its callbacks keep
the replay group open. The group releases after those transactions commit or
roll back. Committed changes still join the enclosing request or job group;
rolled-back prop names never enter its union.

An explicit `batch` inside a request, job or another batch reuses that outer
group. It does not publish before the enclosing unit finishes.

`LiveStreams::refresh` uses this same deferred signal path for
registered application topics and component-stream aliases. It invalidates all
props bound to the topic and advances the same hub cursor. Its publications
share the configured rate bound:

```rust
let streams = suprnova::live::LiveStreams::resolve()?;
streams.refresh("posts").await?;
```

For a manual transaction, use
`LiveTopics::changed_with_tx(&tx, "posts", &[]).await?` to name the commit.

A component-stream page binding receives changes for its bound stream alias.
It does not inherit the island's other named topics or typed browser events.
Both page and island delivery of the alias re-check the stream's own ability.
The `topic` slot and `topic` document-key pair identify the framework's
subscription-only mount. Use another identity pair for a rendered island.

For model-wide invalidation, register the model once during bootstrap after
binding the registry. Generated model hooks call it after every successful
save and delete; the ordinary after-commit rule still applies:

```rust
let topics = LiveTopics::resolve()?;
topics.on_model::<Post>("posts", &["posts", "post_count"])?;
```

The generation and cursor belong to the topic, not to a subscriber. A
binding records both before its page loader runs, so reconnect can distinguish a current
subscription from one that needs a reload. With a cross-process hub, every
replica observes the same cursor. Without a configured hub, Live binds its
in-memory fallback and signals reach only this process. See [Inertia Live topic
signals](broadcasting.md#inertia-live-topic-signals) for multi-replica fanout.
In-process counters and memberships end with the process. A recovery reload
takes the new rendered baseline from the page object; the polling fallback
keeps the page current while push reconnects. Redis-backed cursor state lives
in the configured hub instead of an individual process.

Family listeners exist only while this runtime has issued memberships for the
instance. Publishing or reading a cursor does not create a listener. When the
last membership expires and is pruned, its listener and receiver are released.

Idle instances expire after `LIVE_TOPIC_INSTANCE_RETENTION_SECS=86400` seconds.
Zero is rejected. A publication, baseline read or membership renews activity.
In-memory pruning retains active memberships and pending rate-limited signals;
Redis renews the idle cursor/rate hash TTL on publication, baseline reads and
membership heartbeats. Pending work has no TTL and pins that hash until a
successful flush. The flush restores its idle TTL. Its prop set and schedule
survive a worker outage. A missing pending hash produces a full invalidation. Static
topics never expire. All callers share one sweep per second. The ordered idle
index excludes active memberships, pending work and static topics, so a sweep
visits only instances whose idle deadline has passed. Configure the same retention window on every replica:

```rust
let config = suprnova::live::LiveConfig::builder()
    .topic_instance_retention_secs(86400)
    .build()?;
suprnova::App::singleton(config);
```

Every topic instance has a generation that identifies one lifetime of its
authority state. Generations are unique and increasing within an authority
and unique across in-process restarts; across process restarts they differ
except with negligible probability. Memory draws one random 22-bit nonce per
process and uses `(now_seconds << 22) | nonce` as the clock input. Each new
lifetime receives the greater of that input and the process-wide high-water
mark plus one. An atomic compare-and-swap advances the mark, so restarting an
authority or moving its clock backward cannot reuse an allocation. A new
process has a different nonce with probability `1 - 2^-22`. Redis uses
`max(now_ms, last_allocated + 1)` with one persistent counter per hub stream,
allocated in the same Lua script that creates the instance hash. That counter
does not expire when an instance retires. Allocations fail if they exceed the
browser-safe integer limit. Static topics use the same allocator and never
retire. Clients compare generations for inequality only.
Retirement creates a new generation at cursor 0; its next publication advances
to 1. A signal
from a different generation makes an open page reload all bound props even
when its old cursor is higher. The response adopts the new generation and
cursor. Island recovery also seeds a generation at cursor 0. Signals in the
same generation at or below the rendered cursor are discarded. Polling remains
the fallback while push delivery is unavailable.

A binding may also name an existing component stream as
`component::stream`. Such a binding uses the component ability
`live:<component>.stream.<stream>`. A subscription by application topic name
uses `live:topic.<topic>`, for a page or an island.

### Why Suprnova diverges

Laravel has no built-in Inertia topic binding. The `inertia-live` package
adds that behavior separately. Suprnova uses Live's existing memberships and
authorization so islands and Inertia pages share one delivery contract.

## Assets and no-build use

The framework serves the exact reviewed runtime artifacts at
`/__live/assets/<identity>/<file>` with immutable caching, strong
validators, and integrity attributes in the bootstrap tags. A strict
`script-src 'self'` policy holds because documents contain no inline script.
To publish the same bytes to a CDN or a static directory:

```bash
suprnova live:assets --out public/__live
```

The publication is atomic and refuses to replace a directory whose bytes
differ unless you pass `--replace`.

## Limits

Live's runtime limits are settings with defaults sized for large pages: a
data table of tens of thousands of rows renders, travels and morphs without
touching one. The server's configuration is the only source. The bootstrap
writes every value into the page's configuration element, and the browser
runtime applies what it reads there, so it never refuses what the server
allows.

Component metadata has fixed limits of 512 fields, 256 actions, and 64
browser tool actions. Metadata exceeding these bounds is rejected before
islands are served. Headless-only tools do not count toward the browser tool
limit.

Set a limit in the application's `.env` file:

```bash
LIVE_MAX_HTML_BYTES=67108864
LIVE_MAX_RESPONSE_BYTES=67108864
LIVE_MAX_REQUEST_BYTES=67108864
LIVE_MORPH_MAX_NODES=5000000
```

Or build the configuration in code and bind it before the runtime assembles.
The builder starts from the defaults, and `LiveConfigBuilder::from_env()`
starts from the `.env` values instead:

```rust
use suprnova::App;
use suprnova::live::LiveConfig;

let config = LiveConfig::builder()
    .topic_signal_interval_ms(100)
    .max_html_bytes(64 * 1024 * 1024)
    .max_response_bytes(64 * 1024 * 1024)
    .max_request_bytes(64 * 1024 * 1024)
    .morph_max_nodes(5_000_000)
    .build()
    .expect("the Live limits nest");
App::singleton(config);
```

| Key | Default | Bounds |
|---|---|---|
| `LIVE_TOPIC_SIGNAL_INTERVAL_MS` | 100 ms | Hub-global minimum spacing between signals for one topic, at most 10 per second by default |
| `LIVE_MAX_REQUEST_BYTES` | 16 MiB | One request body, the snapshot included |
| `LIVE_MAX_RESPONSE_BYTES` | 16 MiB | One response body |
| `LIVE_MAX_HTML_BYTES` | 16 MiB | One island render's HTML |
| `LIVE_MAX_JSON_DEPTH` | 32 | JSON nesting |
| `LIVE_MAX_JSON_ENTRIES` | 1,000,000 | Entries in one request |
| `LIVE_MAX_REQUEST_ITEMS` | 65,536 | Proposals, operations or arguments in one request |
| `LIVE_MAX_RESPONSE_ITEMS` | 65,536 | Validation entries, events, effects, or children of one render |
| `LIVE_MAX_CONTEXT_LIFETIME_MS` | 30,000 | The trusted request context's validity |
| `LIVE_REQUEST_TIMEOUT_MS` | 60,000 | The browser's wait for one response |
| `LIVE_MAX_QUEUED_PER_ISLAND` | 8 | Requests one island queues |
| `LIVE_MAX_PARALLEL_PER_ISLAND` | 1 | Requests one island runs at once |
| `LIVE_MORPH_MAX_NODES` | 1,000,000 | Nodes in one morphed island |
| `LIVE_MORPH_MAX_DEPTH` | 512 | Element nesting in one morphed island |
| `LIVE_MORPH_MAX_KEYS` | 1,000,000 | Keyed elements in one morphed island |
| `LIVE_MORPH_MAX_ATTRIBUTES` | 10,000,000 | Attributes in one morphed island |
| `LIVE_MORPH_MAX_ATTRIBUTES_PER_ELEMENT` | 4,096 | Attributes on one element |
| `LIVE_MORPH_DEADLINE_MS` | 0, no deadline | How long one morph may run |
| `LIVE_ASYNC_MAX_PAYLOAD_BYTES` | 1 MiB | One asynchronous event payload |
| `LIVE_ASYNC_MAX_BUFFER_BYTES` | 16 MiB | One open document's delivery queue |
| `LIVE_ASYNC_MAX_QUEUED_EVENTS` | 4,096 | Events one open document holds before its islands apply them |
| `LIVE_ASYNC_MAX_REPLAY_EVENTS` | 4,096 | Events in one reconnect replay |
| `LIVE_ASYNC_MAX_REPLAY_BYTES` | 4 MiB | One subscription's replay log |
| `LIVE_ASYNC_REPLAY_BUDGET_BYTES` | 256 MiB | Every replay log in the process together |
| `LIVE_ASYNC_MAX_TRANSPORTS_PER_SESSION` | 64 | Open tabs one session streams to |
| `LIVE_ASYNC_MAX_TRANSPORTS` | 16,384 | Streaming connections in the process |
| `LIVE_MAX_REDIRECT_BYTES` | 64 KiB | One redirect or reflected URL |
| `LIVE_UPLOAD_CHUNK_BYTES` | 8 MiB | One upload chunk request |
| `LIVE_UPLOAD_MAX_ACTIVE` | 8 | Upload transfers running at once |
| `LIVE_UPLOAD_MAX_FILE_BYTES` | 1 GiB | One uploaded file |
| `LIVE_UPLOAD_MAX_PENDING_FILES` | 1,024 | Files selected and not yet finished |
| `LIVE_UPLOAD_MAX_PENDING_BYTES` | 4 GiB | Bytes across the files selected and not yet finished |
| `LIVE_UPLOAD_MAX_STORAGE_BYTES` | 16 GiB | The temporary upload store, across every visitor |
| `LIVE_LEDGER_MAX_INSTANCES` | 100,000 | Mounted component instances |
| `LIVE_LEDGER_INSTANCE_LIFETIME_MS` | 7 days | How long one instance lives |
| `LIVE_LEDGER_CLAIM_LEASE_MS` | 30,000 | How long one action holds its instance |
| `LIVE_LEDGER_MAX_ACCEPTED_OUTCOMES` | 64 | Outcomes kept per instance for retries |

The byte limits nest: the island HTML travels inside the response, and the
response's snapshot comes back in the next request, so `LIVE_MAX_HTML_BYTES`
must be at most `LIVE_MAX_RESPONSE_BYTES`, which must be at most
`LIVE_MAX_REQUEST_BYTES`. A setting you leave unset follows the one it must fit
inside, so lowering only `LIVE_MAX_REQUEST_BYTES` lowers all three. The upload
limits nest the other way: a chunk is part of one file, one file is part of the
pending bytes, and the pending bytes are part of the store, so an unset pending
or store limit grows to hold a larger file. Every key's
type and range is in [Environment Variables](env-vars.md#live).

When a limit trips, the message names the limit, both values and the key to
change. The browser prints it to the console unless the runtime boots with
`diagnostics: "off"`, and the server writes it to the log:

```text
Suprnova Live island HTML size limit exceeded: measured 20971520 bytes,
configured 16777216 bytes. Raise LIVE_MAX_HTML_BYTES in the application's .env
file to allow it.
```

A request the browser would have to send over `LIVE_MAX_REQUEST_BYTES` fails in
the browser before it is sent. A render over `LIVE_MAX_HTML_BYTES` fails on the
server, which logs the `limit` field beside the failed operation's cause. A
published payload over `LIVE_ASYNC_MAX_PAYLOAD_BYTES` fails with a
`LiveStreamError` whose `limit()` names the setting. A file over
`LIVE_UPLOAD_MAX_FILE_BYTES`, or a selection past the pending limits, is
refused in the browser before any transfer starts; the server refuses the same
file with a 413 and logs the key. `suprnova live:inspect` prints every limit the
application runs under, by its key.

Nothing retires an instance when the visitor closes the page, so the ledger
fills at `LIVE_LEDGER_MAX_INSTANCES` page views per
`LIVE_LEDGER_INSTANCE_LIFETIME_MS`, about 14,000 private-island page views a
day at the defaults. A full ledger still mounts every new page: it evicts the
instance that expires soonest to make room, which is usually a page the
visitor closed long ago. If that page is still open, its next action is told
to refresh, and the browser reloads the page with current state. A site whose
open pages get evicted raises the instance limit.

### Sizing a small host

The defaults admit large pages, and every byte of a request is held while it
is read. Live reads a whole request before it checks the request's context,
because the context depends on the island the request names. At the defaults
(`LIVE_MAX_REQUEST_BYTES` 16 MiB, `LIVE_MAX_JSON_ENTRIES` 1,000,000), one
request costs its 16 MiB body plus what parsing it builds: about 60 MiB for an
array of a million short strings and about 165 MiB for an object of a million
members, measured on an optimized build. Concurrent requests add up. On a host
with little memory, lower both limits to what the pages need:

```bash
LIVE_MAX_REQUEST_BYTES=2097152
LIVE_MAX_JSON_ENTRIES=100000
```

At 2 MiB and 100,000 entries, the same measurements give about 6 MiB and 16
MiB, so the worst request costs about 18 MiB with its body. The
response and island HTML limits follow the request limit down unless set.

## Component library

You can install `search-box` with `suprnova live:add search-box`. It combines
the `search-input` control with scoped model results, checked highlights,
facets, keyboard selection, and rejection of stale results. Mount the registered
`suprnova::live::components::SearchBox` with an index and page size; selection
emits `suprnova:search.selected` with the index and key. See
[Search](search.md) for parameters, analytics, and the selection contract.

Suprnova ships the foundations of a component library for Live: a token
stylesheet with a base layer, and a form family of presentational components
built on native controls and the `live:model`, `live:error`, and
`live:loading` vocabulary. The base is a runtime artifact. Opt a document in
and it arrives as one stylesheet link under the same identity, integrity, and
cache contract as the runtime scripts:

```rust
let bootstrap = document.bootstrap(LiveBootstrapOptions::esm().with_suprnova_ui())?;
```

Every rule in it sits inside the `suprnova-ui` cascade layer, so your own
unlayered styles win without a specificity fight. Every visual value is a
`--sn-` custom property for color, font, space, radius, shadow, motion,
density, and state, with light and dark values: override a token on `:root` to
retheme, or drop the layer and keep every behavior, name, and state attribute,
because a component styles its states from the attributes the checker proves
(`aria-invalid`, `aria-busy`, `aria-expanded`, `aria-pressed`, `aria-current`,
`aria-selected`, `:disabled`), never from a class. A Tailwind CSS 4 `@theme`
preset maps the tokens onto Tailwind's namespaces; Tailwind is never required.
Components install with `live:add`, one directory each under the reserved
`templates/suprnova-ui/` root: the Askama macro view, the stylesheet, the
JavaScript when the component has one, and the manifest that names them:

```bash
suprnova live:add field
suprnova live:add password-input
```

`live:add` records the digest of every file it writes, so a later run
replaces a file you never edited when the library changes it, keeps a file
you edited, and says so; `--force` replaces an edited file too. It records
each install in `suprnova.toml` at the project root. A third-party component
installs from its library's signed tree by address, such as
`suprnova live:add acme/acme-ui/counter`, from an `https://` URL, or from a
`./path` on disk, under its library's own root; `--manifest <path>` names a
component on disk too. It can carry Rust, which `live:add` writes under
`src/live/` and registers. [Installing Live Components](live-add.md) covers
the plan, capabilities, key pins and the record, and [Live Component
Libraries](live-libraries.md) covers writing a library. Call the macros from
your views, serve the vendored stylesheet and script with
`try_live_ui_assets()`, and link them from the document with
`url::root()` in front, so the links still work when a reverse proxy serves
the application under a path prefix:

```html
<link rel="stylesheet" href="{{ suprnova::url::root() }}/suprnova-ui/field/field.css">
<link rel="stylesheet" href="{{ suprnova::url::root() }}/suprnova-ui/input/input.css">
```

```html
{% import "suprnova-ui/field/field.html" as field %}
{% import "suprnova-ui/input/input.html" as input %}
{% call field::field("email", "Email", required=true) %}
{% call input::input("email", kind="email", required=true) %}{% endcall %}
{% endcall %}
```

`try_live_ui_assets()` reads the files from `templates/suprnova-ui/` under the
application base path on each request, so ship that directory with the
binary and start the application from the directory that holds it, or set
`APP_BASE_PATH` to that directory. When the directory cannot be read, the
application refuses to start and names it.

A third-party library installs its components under its own root,
`templates/<namespace>-ui/`, and each library takes one call of its own:
`try_live_ui_assets_for("acme")` serves `templates/acme-ui/` at
`/acme-ui/{component}/{file}` under the same rules, and `live:add` names
the call when it installs the library's first component. Only stylesheets
and scripts of at most 1 MiB are served, never a view, a Rust file, a
manifest or the install record, and never a file reached through a symbolic
link below the root. The server opens the component directory and the file
through the root it holds open, so a link swapped in while a request is in
flight is refused too, and it checks the 1 MiB bound on the file it then
reads.
The namespace call refuses `suprnova`, whose call is `try_live_ui_assets()`,
and the reserved `sn` and `live`; `try_live_ui_assets_for_from(namespace,
directory)` serves the same route from an explicit directory.

```rust
let router = router.try_live_ui_assets()?.try_live_ui_assets_for("acme")?;
```

The checker expands the macros, so `live:check` proves a library view like any
other. The form family: field, label, input, textarea, number input,
slider, search input, password input with reveal, checkbox and checkbox group,
radio group, switch, select, button and link button, button group, fieldset,
form actions, validation summary, and file input. Library components are named
`suprnova.*` and the registry refuses that prefix from any other crate; custom
elements are light DOM and carry the `sn-` prefix.

Each value control takes the island's current value, so the page shows it and
a submit that changed nothing sends it back unchanged: `value=` for an input,
textarea, number input, slider, search input, and date picker, `checked=` for
a checkbox and a switch, and `selected=` for a select, a radio group, and a
checkbox group, which takes the list of checked values. A password and a
one-time code never render their value. Radio and checkbox group inputs are
keyed by value, so a choice the user has not sent survives a re-render. A
checkbox group is proposed as the list of checked values whatever its number
of options, as is any field that more than one checkbox binds; a single
checkbox is proposed as a boolean. A render that must replace
what the user has typed, such as the one answering a reset, passes a sequence
number as `authority=`, and the next render passes none:

```html
{% call input::input("email", kind="email", value=email, authority=authority) %}{% endcall %}
{% call checkbox::checkbox_group("topics", "Topics", topic_options, topics) %}{% endcall %}
```

An input also takes `maxlength=`, the most characters the browser lets the
user type, such as `maxlength="254"` on an email address. It is a hint for
the browser: the action's own rule still checks the length.

The overlay family ships on the same foundations: tooltip, collapsible and
accordion, popover, a single-level dropdown menu, dialog, sheet, and drawer.
Each one owns its open state through the browser's own primitive before any
script runs: `details` for disclosures, the `popover` attribute for popovers
and menus, and `dialog` for the three modals, which the vendored `sn-dialog`,
`sn-sheet`, and `sn-drawer` elements open with `showModal()` and close with
focus returned to the trigger. Opening and closing never makes a Live request;
only an action you place inside an overlay does. Every overlay root carries a
stable key and `live:preserve.self`, so an open overlay survives a morph that
did not replace its region:

```html
{% import "suprnova-ui/dialog/dialog.html" as dialog %}
{% call dialog::dialog_trigger("confirm", "Delete everything", variant="danger") %}{% endcall %}
{% call dialog::dialog("confirm", "confirm", "Delete everything?") %}
<p>This removes every note.</p>
{% call button::button("Delete", action="confirm_delete", variant="danger") %}{% endcall %}
{% call dialog::dialog_close("confirm", "Cancel") %}{% endcall %}
{% endcall %}
```

The `popover` attribute sets the supported baseline at Chrome and Edge 114,
Firefox 128, and Safari 17. Where CSS anchor positioning exists the popover and
menu sit under their trigger; elsewhere the browser centres them. The
accordion's single-open mode rests on `details name`, which older supported
releases treat as independent disclosures. The tooltip stays open while the
pointer moves from its trigger onto the bubble, so its text can be read or
selected, and Escape dismisses it where it is shown, without moving the
pointer or focus; the next hover or focus of that trigger shows it again.
The dismissal is the vendored `sn-tooltip` element, and the bubble still
shows on hover and on focus in a page that never loads it.

The feedback family and the navigation family follow. Feedback: alert,
skeleton, spinner, progress, empty state, and a toast region with a flash
region beside it. Each one presents a state the server or the runtime already
holds. An alert chooses its role from its variant and marks every variant with
a glyph and a hidden label, never color alone. A spinner or skeleton is bound
with `live:loading.show` to a registered action and authored hidden, so the
runtime reveals it after its own delay and keeps it past its minimum, and a
fast action never flashes it. Progress is the native `progress` element with a
label and a text readout, and carries a value only for determinate work. The
empty state takes its reason (empty, no results, no permission, disconnected)
from server-rendered state and offers a next action only where the caller
renders one. A toast announces once from a polite status region and never
takes focus; the vendored `sn-toast-region` element times toasts out, pauses
while the pointer is over any part of a toast or focus is inside it, bounds how many show at once, and answers the
dismiss button, with each toast keyed and preserved so a dismissed toast stays
dismissed across a morph. A critical error belongs in an alert as well; a
toast is never its only surface. Toasts render inside a loop, so their keys
pass through the `live_key` filter, and the island that mounts them exposes
it with `pub mod filters { pub use suprnova::view::filters::live_key; }`.
`live_key` fails the island's render for a value outside the key alphabet,
such as an email address; key such data with `live_key_digest`, which turns
any value into a stable key in the alphabet and is exported the same way from
`suprnova::view::filters`.
The flash region renders what the previous request left in the session, once:

```html
{% import "suprnova-ui/alert/alert.html" as alert %}
{% import "suprnova-ui/spinner/spinner.html" as spinner %}
{% call alert::alert("saved", variant="success") %}<p>Your changes are saved.</p>{% endcall %}
{% call button::button("Save", action="save") %}{% endcall %}
{% call spinner::spinner(action="save", label="Saving") %}{% endcall %}
```

Navigation: header bar, footer, sidebar with collapsible groups, breadcrumbs,
tabs, pagination, and load more. Every destination is an anchor with a real
route URL and every action is a button; the current item carries
`aria-current` from the value you bind, never from the browser's location.
The sidebar's groups are native `details`, keyed and preserved. Tabs require a
mode: `local` panels with tablist semantics, arrow keys from the vendored
`sn-tabs` element, and no request on a change, or `route` tabs as anchors.
Tabs nest: an inner tabs instance selects only its own tabs and panels.
Pagination requires a mode too: route pages are canonical links, and Live
pages are buttons on your actions whose result reflects the new query into the
current history entry through `url_intent`, with no history entry per page.
Load more is a button on a registered action that appends to a keyed list, so
the morph keeps every row already there, and the control leaves the view when
you render it exhausted. A URL reflection is a protocol 2 result, so an island
that paginates through `url_intent` declares `minimum_protocol_version = 2`;
its keyed rows pass through `live_key` like a toast does:

```html
{% import "suprnova-ui/tabs/tabs.html" as tabs %}
{% call tabs::tabs("details", mode="local", label="Details") %}
{% call tabs::tab_list("Details") %}
{% call tabs::tab("tab-summary", "panel-summary", "Summary", selected=true) %}{% endcall %}
{% call tabs::tab("tab-history", "panel-history", "History") %}{% endcall %}
{% endcall %}
{% call tabs::tab_panel("panel-summary", "tab-summary", selected=true) %}<p>Summary</p>{% endcall %}
{% call tabs::tab_panel("panel-history", "tab-history") %}<p>History</p>{% endcall %}
{% endcall %}
```

The data display family closes the built-in set. Presentational: separator,
scroll area, aspect image, card, badge, avatar and avatar group, list group,
description list and stat card. Each keeps document order and native
semantics: the separator is an `hr` or a labeled separator role, the scroll
area is a focusable labeled region that scrolls natively, the aspect image is
the `img` itself with a named ratio, the card is an article or section
labeled by its own heading with actions in a labeled group, and the
description list is a `dl`. A badge always carries its text, an avatar names
its person in `alt` or in the label of its initials, and a stat's trend says
"Up", "Down" or "Flat" in text before the delta, so no status rests on color
alone. The list group keys every item through `live_key`, so a reorder keeps
each node. The chart is server-rendered: the island calls `render_chart`
from `suprnova::live::charts`, which draws bar or line marks through
`charts-rs` from bounded typed series and returns trusted markup, and the
macro renders the SVG beside a text summary and a data table in a disclosure,
so the canonical document reads without the picture and no charting script
ever reaches the browser:

```rust
use suprnova::live::charts::{ChartKind, ChartSeries, render_chart};

pub fn chart_svg(&self) -> TrustedHtml {
    render_chart(
        ChartKind::Bar,
        &["Apr", "May", "Jun"],
        &[ChartSeries::new("Revenue", vec![42.0, 47.0, 51.0])],
    )
    .expect("a bounded fixed series renders")
}
```

`render_chart` returns an error rather than drawing a value whose magnitude
exceeds 1e9, beyond the range the renderer's axis arithmetic holds.

The datatable is the last component, and one island per table. It is a
native `table` with a caption naming the result count, column headers with
`scope`, and `aria-sort` on the sorted column. Sort and filter are Live
submits on the island's model fields, page changes are Live buttons, and the
island declares the applied sort, direction, filter and page as `#[url]`
fields and reflects them through `url_intent` after every action, so the
address bar always holds a shareable URL and the document mounts the same
view from it:

```rust
#[live(name = "app.invoices", view = "live/invoices.html", minimum_protocol_version = 2)]
pub struct Invoices {
    #[model]
    pub sort: String,
    #[url(key = "sort")]
    pub sorted_by: String,
    #[url(key = "dir")]
    pub direction: String,
    #[model]
    #[url(key = "filter")]
    pub filter: String,
    #[url(key = "page")]
    pub page: u64,
    pub rows: Vec<Invoice>,
}
```

The live-native family is the last one, the components that only make sense
on the running runtime. The upload widget renders the shipped upload
protocol: its file input carries `live:upload` for the island's upload
field, its `progress` element is the runtime's progress root, and cancel,
retry and remove act on the temporary reference through `live:upload.cancel`
and its siblings. Every state the domain knows is rendered as text and shown
from the progress root's `data-live-upload-state`, and "ready" reads as
verified but not saved, because nothing is durable until the finalizing
action runs:

```html
{% call upload::upload("attachment", "Attachment", accept="image/png") %}{% endcall %}
<button type="submit" live:loading.disabled="save_attachment">Save attachment</button>
```

The live feed and the notification bell sit on a stream-backed island. The
runtime writes `data-live-stream-state` on the island root and announces
every change into the `[data-live-stream-status]` element the macros render
(Updates disconnected, Connecting to updates, Updates current, Updates
degraded, Reconnecting to updates, Updates closed), so a degraded,
reconnecting or closed stream says so and only the current state reads
current. Feed items pass through `live_key`. The account menu is a `details`
disclosure of anchors and a sign-out form that posts with the session's
CSRF token; it is a stitch slot under RenderCache, so an application mounts
it as its own identity-bound island and the shared shell never holds the
principal's name.

The custom-element tier enhances native controls it never replaces. Each
element is a light-DOM `HTMLElement` subclass defined only by its own
vendored file, carries the `sn-` prefix, and holds no form value, because
the native input inside it is the control: block the script and the form
still submits the same value. The input OTP is one native input
(`inputmode="numeric"`, `autocomplete="one-time-code"`, a length pattern) on
a transient model, and `sn-input-otp` mirrors the typed characters into
`aria-hidden` cells. The date picker is a `type="date"` input, and its year,
month and day strips are fieldsets of native radios inside CSS scroll-snap
containers, so tap, click and arrow keys select with no script;
`sn-date-picker` composes a complete selection into the input. The combobox
is the accessible combobox pattern (`role="combobox"`, `aria-expanded`,
`aria-activedescendant`, a `role="listbox"` of options) over a native input
with a `datalist` for the script-free case, and `sn-combobox` moves the
active option and selects. Each option is a `(value, label)` pair, and the
combobox binds two fields: `name` holds the chosen option's value, through a
hidden input that a selection fills and an edit of the text clears, and
`<name>_query` holds the typed text. Pass the island's current value as
`value` and its text as `query`, so both render back (the option holding
the value renders selected). By default the options are your server's
answer to the query: render them for the query field on every render, and
the element shows all of them while the query they answer is the input's
text, whatever your search matched, and keeps an answer to older text
hidden, so a stale result never replaces results for a newer query. Pass
`remote=false` for a fixed list, which the element filters by the typed
text:

```html
{% call otp::input_otp("code", "One-time code") %}{% for index in cells %}{% call otp::otp_cell(index) %}{% endcall %}{% endfor %}{% endcall %}
{% call date::date_picker("when", "Renewal date", years, months, days, min="2026-01-01", max="2028-12-31") %}{% endcall %}
{% call combo::combobox("country", "Country", countries, query=country_query, placeholder="Type a country", value=country) %}{% endcall %}
```

### Why Suprnova diverges

Laravel ships Blade components and a starter kit's markup; Suprnova ships the
library through the framework itself, on Live's own vocabulary, with no client
application owning the page. The skin is on by default and removable with
nothing breaking, which is what headless means here.

## Testing

`suprnova::live::testing` prepares a router's runtime and mount catalog for
in-process tests. The application tests in `app/tests/live_*.rs` show the
complete pattern: an in-memory database, a seeded session cookie, the real
global middleware stack, and requests through `handle_request`:

```rust
let router = app::live::routes(app::routes::register())?;
let runtime = prepare_live_router_for_test(&router)?;
App::singleton(runtime.clone());
```

Decode an island's snapshot from its `data-suprnova-live-snapshot` attribute,
post an action with the session cookie and `Sec-Fetch-Site: same-origin`, and
assert on the accepted render. A stale snapshot answers `409` with an empty
body; a missing principal answers `401`.

## Diagnostics and operations

- `suprnova live:check` proves every registered view; `--allow-unproved`
  accepts dynamic structures the checker deliberately makes no claim about.
- `suprnova live:inspect` reports the bound registry, configuration limits,
  installed upload capabilities, assembled runtime services, and the asset
  identity without exposing state or secrets.
- `LiveConfig` holds every limit Live applies; set them with the `LIVE_*`
  keys in `.env` or bind a custom one before the runtime assembles. See
  [Limits](#limits).
- Errors carry closed kinds such as `live_document_context_rejected` and
  `invalid_live_bootstrap`; telemetry labels are closed enumerations.

### Why an operation failed

When a trusted part of the engine fails an operation, the browser gets one
closed reason and nothing more: the island is told to refresh. The framework
records why in the log, so you do not have to reproduce the request. It writes
one `WARN` event for each failed action, and one for each rejected mount.

A failed action writes this event:

| Field | Holds |
|---|---|
| message | `Live operation failed and the browser must refresh the island` |
| `component` | The registered name of the component, such as `app.counter` |
| `reason` | The coarse reason the browser gets, such as `ExecutionFailed` or `LedgerUnavailable` |
| `cause` | The closed cause, written in the `Debug` form, such as `Ledger(ProviderUnavailable)` |

A rejected mount writes one of two events. The message is
`Live public mount was rejected` for a mount that a document asks for, and
`Live private mount was rejected` for a mount that carries a request of its
own. Each has these fields:

| Field | Holds |
|---|---|
| `kind` | The coarse kind of the mount error, such as `LedgerRejected` |
| `cause` | The closed cause, or `None` when the kind says everything |

A refresh that is no failure has no cause and writes no warning. A stale
revision is the usual case: the island refreshes and the log stays quiet. A
mount refusal with no subsystem error behind it, such as an identity
collision, has `cause=None`.

The cause names the part that failed and the kind of its error. An action
cause is one of these groups:

| Group | Look at |
|---|---|
| `Action` | The registered action: its lookup, arguments, authorization, dispatch or outcome |
| `Lifecycle` | The component: a recovery render, a model sync, a parameter change, a lazy completion or a promotion mount. `Panicked` means the component panicked |
| `Ledger`, `LedgerSuccessorMismatch` | The instance ledger: `ProviderUnavailable` points at the store, `CapacityExceeded` at a stored record over its 32 KiB bound |
| `Clock` | The host clock: no time, or a deadline that overflowed |
| `ContextExpired` | The request context ran out before the new snapshot was signed |
| `Snapshot`, `Identity` | The signed state: the kind says which check refused it, such as `SignatureInvalid` or `Expired` |
| `View` | The rendered view: for example `TemplateRenderFailed` or `MissingIslandRoot` |
| `OutcomeShape` | An outcome that is incomplete |
| `CompositionOwnerMissing`, `CompositionChildUntracked`, `CompositionChildUnknown`, `CompositionLineage`, `ChildParameters` | The parent and child components of a page: their lineage or their sealed parameters |
| `Host` | A port of the application: `Begin`, `Commit`, `Rollback`, `Reporting` or `ResponseIntent` names which one |
| `ResponseIntents`, `ResponseSealing` | The preparation or the sealing of the response |

A mount cause is one of `Clock`, `Registry`, `Snapshot`, `Canonical`,
`Composition`, `Random`, `Lifecycle`, `View` or `Ledger`. Each names the
subsystem that refused the mount and carries the kind of its error.

The values are closed. They never hold the text of an error, the identifier of
an instance or anything of a request. You can copy a log line into a report
without removing a secret from it.

## Recovery

- A `409` tells the runtime to fresh-render the island; the operation is not
  replayed.
- A refresh that follows a failed operation tells the browser only to
  refresh. The cause is in the log only; see [Why an operation failed](#why-an-operation-failed).
- A closed asynchronous transport is retired and the runtime reconnects with
  a new transport generation; a stale generation is refused.
- A session that expires or rotates invalidates identity-bound work; the
  application exposes its sign-in path and the visitor continues from a fresh
  document.

Live runs complete without RenderCache. Caching Live documents is
RenderCache's job; see [RenderCache](render-cache.md).

## CLI reference

| Command | Purpose |
|---|---|
| `suprnova live:make <name>` | Scaffold a component and its view and register it |
| `suprnova live:add <component>` | Install a component from the shipped library or a third-party library; see [Installing Live Components](live-add.md) |
| `suprnova live:registry new\|check\|sign\|rotate-key` | Scaffold, check, sign and re-key a component library; see [Live Component Libraries](live-libraries.md) |
| `suprnova live:check` | Verify every recorded third-party component offline, then prove every registered view with the integrated checker |
| `suprnova live:inspect` | Report safe runtime, registry, provider, and artifact state |
| `suprnova live:assets --out <dir>` | Publish the reviewed runtime artifacts atomically |

## Next

Bind page props to the same topics with [Live topic bindings](frontend-pages.md#live-topic-bindings).
Configure cross-process delivery with [Broadcasting](broadcasting.md#inertia-live-topic-signals).


---

<!-- /docs/live-add -->

# Installing Live Components

`suprnova live:add` installs a Live component into your application from the
shipped library or from a third-party library. A third-party component can
carry Rust as well as a view, a stylesheet and a script, so installing one
adds its author's code to your application. `live:add` treats it that way:
it verifies the component's signature, scans every file without running any
of it, shows you everything it will write and every capability the component
uses, and writes nothing until you approve. Then the copy is yours, and
`suprnova.toml` records where it came from.

This chapter follows one install from the command to a rendered component.
To publish a library of your own, see [Live Component
Libraries](live-libraries.md).

## Quick start

```bash
suprnova live:add acme/acme-ui/counter
```

`live:add` fetches the component from the newest release of the library at
`github.com/acme/acme-ui`, verifies it, scans it, and prints its plan. On a
terminal it asks you to approve each capability the component uses, to pin
the library's key, and to confirm the plan. Then it writes the files,
declares the component's Rust module, registers its Live component, and
records the install. A shipped component installs the same way, by its
name, with no questions:

```bash
suprnova live:add field
```

## Sources

`live:add` takes one of four sources:

| Source | Example | Installs from |
|---|---|---|
| A name | `field` | The shipped library, embedded in the CLI. `suprnova.field` is the same. |
| A repository address | `acme/acme-ui/counter`, `gitlab.com/acme/acme-ui/counter@1.2.0` | The library at the root of that repository, at a release tag. The host is `github.com` when you omit it, or `gitlab.com` or `codeberg.org`. |
| An `https://` URL | `https://ui.acme.test/acme-ui/components/counter` | The library two levels above the component directory. |
| A path | `../acme/components/counter` | A library tree on disk. The path starts with `./`, `../` or `/`, and names a component directory or its `manifest.json`. `--manifest <file>` is the same source. |

A repository address is `[<host>/]<owner>/<library>/<component>[@<version>]`.
With no version, `live:add` takes the highest `v<semver>` tag the forge
lists, pre-releases excluded, and refuses a repository with no release tag.
`@1.2.0` takes the tag `v1.2.0`.

Every source resolves to one library address and one component address
before anything is fetched. A repository's library address is
`<host>/<owner>/<library>`, lowercase, so `Acme/Acme-UI/counter` and
`acme/acme-ui/counter` are one component. A URL's is its lowercase scheme
and host, a port that is not the default, and the path two segments above
the component, with no trailing slash. A path's is the absolute library root
with symbolic links resolved. A library fetched by repository address or URL
must name that address as the `source` in its `library.json`, so a fork that
copies another library's files and signatures is refused. A path source is
an author's tree on disk, whose `source` names where it will be published.

Fetching follows fixed rules. Every request is HTTPS, except to a loopback
host, and carries no credentials. A response over 2 MiB, one that takes over
30 seconds, a redirect to another origin, and a JSON document that is not one
object or holds a duplicate key are refused, and so is a plan that fetches
more than 64 MiB in all. Repository files are read raw
at the commit the tag names, never as release assets, and a redirect to
another repository path, as a renamed repository answers, is refused with
the new address named. Only public repositories are supported.

## The plan

Before it writes anything, `live:add` fetches, verifies and scans the whole
plan, dependencies included, and prints it. This is the plan for a first
install of the example component of a library that
`live:registry new acme --source github.com/acme/acme-ui` scaffolded and that
was published at that address:

```text
framework: suprnova 3.3.0
github.com/acme/acme-ui/counter 0.1.0
  commit      5b0f3c9e2a7d41e8c6b1f0a9d3e5c7b2a4f6e8d0
  hash        sha256:58982952bdf9cfc32fe817ffc459ab3a9302e68581b1eaef1a77b59d2049653e
  templates/acme-ui/counter/manifest.json  new
  templates/acme-ui/counter/counter.html  new
  templates/acme-ui/counter/counter.css  new
  templates/acme-ui/counter/counter.js  new
  src/live/acme/counter.rs  new
  module      src/live/mod.rs: pub mod acme;
  module      src/live/acme/mod.rs: pub mod counter;
  register    crate::live::acme::counter::Counter
github.com/acme/acme-ui/counter: capabilities: none
key: pin sha256:0d7344c941b351c781be6ee0ce4c3146a85a2df7d526d1f2c45f2160a21d27c7 for github.com/acme/acme-ui (no key is pinned for it yet)
serve its assets: call `router.try_live_ui_assets_for("acme")` when you build the router
```

| Line | Means |
|---|---|
| `framework:` | The `suprnova` version your application depends on, which each library's `framework` requirement was checked against. It comes from `Cargo.lock`, or, with no lock, from the `v<version>` tag of the `suprnova` git dependency in `Cargo.toml`. With neither, `live:add` refuses and asks you to run `cargo generate-lockfile`. |
| `<address> <version>` | One component and the library version it comes from. Dependencies come first. |
| `commit` | The commit the release tag resolved to. Every file of the library comes from it. |
| `hash` | The component's verification hash. The signature was verified over it. |
| `<path>  <outcome>` | Each file, where it lands, and what happens to it: `new`, `unchanged`, `replaced`, `kept, edited locally`, `kept, changed since the record`, or `removed: the library dropped it`. See [Updates, edits and --force](#updates-edits-and---force). |
| `forced` | A refusal `--force` let through: a downgrade, a released version whose content changed, or a dependency an installed component recorded at another version. |
| `module` | A module declaration and the file it goes in. `already declared` marks one the file already holds, which `live:add` leaves as it is. |
| `register`, `unregister` | A Live component it registers in your registry builder, or removes because the new version no longer defines it. `already registered` marks one the builder already holds. |
| `depends on` | A dependency and the version it resolved to. |
| `capabilities:` | Each capability the scan found the component uses, or `none`. |
| `approval` | Each capability's approval: given at an earlier install, given by `--allow`, or needed from you. |
| `key:` | A key `live:add` would pin, or re-pin after a key change, by fingerprint. |
| `serve its assets:` | The router call that serves the library's stylesheets and scripts, shown at the library's first install. |

A library's files land under `templates/<namespace>-ui/<component>/` (views,
stylesheets, scripts, the manifest and the install record) and
`src/live/<namespace_module>/` (Rust), where `<namespace_module>` is the
namespace with each hyphen written as an underscore.

## Capabilities

A component reaches a database, the network, files, mail, a queue, a cache,
the session, the environment or a process only through Suprnova's API, and
every part of that API carries a capability. The scan reports each
capability a component uses, and you approve each one by name before it
installs:

| Capability | Allows the component to |
|---|---|
| `database` | Read or write a database. |
| `network` | Open a connection to another host. |
| `files` | Read or write files, a storage disk included. |
| `mail` | Send mail. |
| `queue` | Push to or work a queue. |
| `cache` | Read or write a cache. |
| `session` | Read or write the session. |
| `environment` | Read the environment or the configuration. |
| `process` | Start a process. |

On a terminal, `live:add` asks about each capability in turn. Without a
terminal, approve them with `--allow`, once per capability:

```bash
suprnova live:add acme/acme-ui/invoice-table --yes --allow database --allow cache
```

Denying a capability, or leaving one unapproved without a terminal, refuses
the install with nothing written. `suprnova.toml` records each approval, so
an update that uses the same capabilities installs without asking again, and
an update that uses a new one asks for that one. A component that uses no
capability needs no approval.

## Confirm the plan

`live:add` asks you to confirm a plan that holds any component from a
library but the shipped one. A terminal here means standard input and
standard error are both a terminal, and no is the default answer. Without a
terminal, `live:add` refuses unless you pass `--yes`.

`--yes` confirms the plan and does nothing else. It never approves a
capability, which takes `--allow`, and never pins or re-pins a key, which
takes a terminal or a pin you write yourself. It does not skip a key's
question either: on a terminal, `live:add` asks before it pins or re-pins a
key, with `--yes` or without it.

## Trust on first use

The first install from a library pins the key its `library.json` names, in
`suprnova.toml`, once you confirm on a terminal. Every later install from
that library must be signed by the pinned key. A library whose key differs
from its pin is refused, with both fingerprints named, unless the pinned key
handed the library to the new key: then the plan shows both fingerprints, and
`live:add` asks on a terminal whether to re-pin. Yes re-pins the key; no
refuses the install and writes nothing. Without a terminal the change is
refused, even with `--yes`. A re-pin keeps the former key in the library's
pin table, under `previous_keys`, so the components you installed under the
former key still verify.

To install without a terminal, pin the key yourself first. Add the library's
table to `suprnova.toml`, with the key from its `library.json`:

```toml
[live.libraries."github.com/acme/acme-ui"]
key = "ed25519:6HedMVA4Z2cro3wHx0Fh7Vqb3WLDpUtZCsqhG7DpkJA="
```

A pinned key proves continuity, not identity: every version you install
later comes from whoever held the key when you first installed, or from
whoever that holder handed it to. It does not prove who that is. Decide
whether to trust a library before its first install, from its address and
its author.

A namespace stays with the library you first installed it from. A second
library that claims the same namespace is refused, with both addresses named.

## The provenance record

`suprnova.toml`, at your project root, is your application's record of
every component it installed. `live:add` creates it when it is missing and
edits it in place: every comment, key and table it does not own stays as it
was. This is the record the plan above wrote:

```toml
[live.components."github.com/acme/acme-ui/counter"]
source = "github.com/acme/acme-ui"
version = "0.1.0"
commit = "5b0f3c9e2a7d41e8c6b1f0a9d3e5c7b2a4f6e8d0"
library_json = "sha256:867b1291d119d68bee3e3a46ce007a7ca8ab60bbae23a04892ad7a6eb9e9ec81"
manifest = "sha256:7ff819c5e8fb1d4439ca865cbddd2a690f4d3b31433c56ebed0850e8c3cb99e8"
hash = "sha256:58982952bdf9cfc32fe817ffc459ab3a9302e68581b1eaef1a77b59d2049653e"
signature = "FeJtqDThMDVmGseOl4KmygWPQghVwD0dUyDWzQw9/+xBzWmLWfvlopI4n2O9LKVuNYhshCLDgqeKSdVoR1SuAA=="
files."counter.css" = "sha256:c44ae7cd896d867174fb62154a80e113c4a67b5bb56bf3d578ca4c3650a7bca2"
files."counter.html" = "sha256:174ccd0130ffc0e366ddc8a25888113e392e185f203d6d15d68d6120bd615f42"
files."counter.js" = "sha256:49a53e15ede8c5a59bf1bd577ad333211aac956aee507f7ad412b17a7ce19acd"
files."counter.rs" = "sha256:048febcec71d261406a1931ba59b42f9a2df630d0df8a093be448928cbd85c73"
registered = ["crate::live::acme::counter::Counter"]

[live.libraries."github.com/acme/acme-ui"]
namespace = "acme"
key = "ed25519:6HedMVA4Z2cro3wHx0Fh7Vqb3WLDpUtZCsqhG7DpkJA="
```

Each `[live.components."<address>"]` table holds exactly what arrived:

| Key | Holds |
|---|---|
| `source`, `version` | The library's `source` and the version installed. |
| `commit` | The commit the release tag resolved to. A URL or path source has none. |
| `library_json`, `manifest` | The digests of `library.json` and `manifest.json` as they arrived. |
| `hash`, `signature` | The verification hash and the signature over it. |
| `files` | The digest of each file the manifest names, as it arrived. |
| `dependencies` | Each dependency's address and the version it resolved to. |
| `registered` | The full path of each Live component it registered, as the registration line names it. |
| `capabilities` | Each capability the scan found, with how you approved it: `terminal` or `flag`. |
| `kept` | Each file the install kept because you had edited it. |

In `suprnova.toml`, a component's `capabilities`, `kept` and `commit` are
your own record of decisions made at install time, not part of the signed
statement, so `live:check` does not verify them and editing them by hand
changes no provenance.

Each `[live.libraries."<address>"]` table holds the namespace the library
owns in your application, the `key` pinned for it, and, after a key change,
`previous_keys`: the keys the pin replaced. A shipped component's
table holds only the CLI's version and digests, since the shipped library is
neither signed nor hashed:

```toml
[live.components."suprnova/field"]
source = "suprnova"
version = "3.3.0"
manifest = "sha256:9540febdf7b22bd79c2fdcede86e14b6e9693201de58620e564ced94f7e85620"
files."field.css" = "sha256:3b552944e95a30c31439afd0248491e77b301e9d26be9bf73beb78991a97b7c5"
files."field.html" = "sha256:f576888a8dbad260b3e42cf6be7981fc7d69a9c40cbadedddb95800be4d26d4b"
```

The record holds what arrived, never what is on disk now: editing a vendored
file changes no provenance. Each component directory's
`.suprnova-installed.json` holds the digest of the bytes `live:add` last
wrote at each path, which is how it tells your edits from its own files.

## Render the component

An installed component is registered, but nothing renders it until a page
mounts it. Serve the library's stylesheets and scripts with the call the
plan named, and render the component as its own island. This page module,
`src/counter_page.rs`, does both:

```rust
//! The installed counter, rendered by its own island.

use std::collections::BTreeMap;

use suprnova::live::{CanonicalValue, LiveBootstrapOptions, LiveDocument, LiveMount, MountFlags};
use suprnova::view::{AssetSet, DocumentResponseIntent, TrustedHtml, ViewName};
use suprnova::{FrameworkError, HttpResponse, Request, Response, Router, StatusCode};

use crate::live::acme::counter::Counter;

mod filters {
    pub use suprnova::view::filters::trusted_html;
}

#[suprnova::view(path = "counter_page.html")]
struct Page<'a> {
    bootstrap: &'a TrustedHtml,
    counter: &'a TrustedHtml,
}

/// Serves the acme library's stylesheets and scripts and the counter page.
pub fn routes(router: Router) -> Result<Router, FrameworkError> {
    let router = router.try_live_ui_assets_for("acme")?;
    let mount = LiveMount::<Counter>::public_seed("/counter", "counter", "acme-counter")?;
    let handler = mount.clone();
    let router: Router = router
        .get("/counter", move |request: Request| {
            let mount = handler.clone();
            async move { render(request, &mount).await }
        })
        .into();
    router.try_live_mount(&mount)
}

async fn render(request: Request, mount: &LiveMount<Counter>) -> Response {
    let result: Result<HttpResponse, FrameworkError> = async {
        let mut document = LiveDocument::from_request(&request)?;
        let counter = document
            .mount(mount, CanonicalValue::Object(BTreeMap::new()), MountFlags::empty())
            .await?;
        let bootstrap = document.bootstrap(LiveBootstrapOptions::esm())?;
        document
            .render(
                ViewName::parse("counter_page.html")
                    .map_err(|_| FrameworkError::internal("view name"))?,
                &Page {
                    bootstrap: bootstrap.html(),
                    counter: counter.html(),
                },
                DocumentResponseIntent::html(StatusCode::OK)
                    .map_err(|_| FrameworkError::internal("response intent"))?,
                AssetSet::empty(),
            )
            .map_err(FrameworkError::from)
    }
    .await;
    result.map_err(|error| HttpResponse::text(format!("counter page: {error}")).status(500))
}
```

Its view, `templates/counter_page.html`, links the component's stylesheet
and script from the namespace's route, with `url::root()` in front so the
links work under a path prefix too
([Serving under a path prefix](deployment.md#serving-under-a-path-prefix)):

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Counter</title>
<link rel="stylesheet" href="{{ suprnova::url::root() }}/acme-ui/counter/counter.css">
<script type="module" src="{{ suprnova::url::root() }}/acme-ui/counter/counter.js"></script>
{{ bootstrap|trusted_html }}
</head>
<body>
<main>
{{ counter|trusted_html }}
</main>
</body>
</html>
```

Declare the module in `src/lib.rs` with `pub mod counter_page;`, and install
its routes in `src/live/mod.rs`, inside the RenderCache install:

```rust
pub async fn routes_with_render_cache(router: Router) -> Result<Router, FrameworkError> {
    RenderCache::install(
        crate::counter_page::routes(routes(router)?)?,
        RenderCacheConfig::from_env()?,
    )
    .await
}
```

Build and start the application, and `/counter` renders the count and its
button through the component's own island, with its stylesheet served from
`/acme-ui/counter/counter.css`. The reserved Live routes of an application
`suprnova new` generated take `AuthMiddleware::new()`, so the button's action
runs for a signed-in visitor; [Routes](live.md#routes) shows the guard with
`AuthMiddleware::optional()` for anonymous actions.

`try_live_ui_assets_for("acme")` serves `templates/acme-ui/` at
`/acme-ui/{component}/{file}`: stylesheets and scripts only, never a view,
a Rust file, a manifest or the install record. Each library's namespace takes
one call; the shipped library's is `try_live_ui_assets()`. See [Component
library](live.md#component-library) for the shared rules.

## Updates, edits and --force

Run `live:add` again to update a component. Each file is judged against the
install record: a file you never edited is replaced when the library changes
it, a file you edited is kept, and the plan says which. A Rust file is judged
the same way. When a kept Rust file belongs to a component whose new version
registers different types, `live:add` refuses and names the file to
reconcile. A file the new version no longer names is removed when you never
edited it, and kept when you did. `--force` replaces or removes every edited
file.

`suprnova.toml` pins the version you installed, and `live:add` guards it:

- A version lower than the recorded one is refused unless you pass `--force`.
- The recorded version with a different hash is refused, reporting that the
  library changed a released version, unless you pass `--force`.
- An install that would move a dependency to another version than an
  installed component recorded names that component and is refused unless
  you pass `--force`.

The plan shows each refusal `--force` let through as a `forced` line, and
marks what the application already holds. An application that installed
0.2.0 of the counter and goes back to 0.1.0 sees this plan:

```bash
suprnova live:add acme/acme-ui/counter@0.1.0 --force
```

```text
framework: suprnova 3.3.0
github.com/acme/acme-ui/counter 0.1.0
  commit      5b0f3c9e2a7d41e8c6b1f0a9d3e5c7b2a4f6e8d0
  hash        sha256:1f75c3d54657a2e51a102fb49b4f5e012e7124dc2aae68601012487109eee208
  templates/acme-ui/counter/manifest.json  unchanged
  templates/acme-ui/counter/counter.html  unchanged
  templates/acme-ui/counter/counter.css  replaced
  templates/acme-ui/counter/counter.js  unchanged
  src/live/acme/counter.rs  unchanged
  forced      downgrade from 0.2.0 to 0.1.0, let through by --force
  module      src/live/mod.rs: pub mod acme; already declared
  module      src/live/acme/mod.rs: pub mod counter; already declared
  register    crate::live::acme::counter::Counter already registered
github.com/acme/acme-ui/counter: capabilities: none
```

## Dependencies

A component's `dependencies` install first, each at most once, a cycle
included. A bare dependency is a shipped component, and `./<component>` is a
component of the same library at the same version. Any other dependency is a
repository address, which resolves as an address you type does, or the
`https://` URL of a component on a public host: a manifest you fetched from
someone else cannot point `live:add` at a path on your disk, a loopback
address or a private network. A plan that needs one component at two
versions is refused before anything is written, naming the components that
require each, and a plan of more than 64 components is refused.

## Dry run

```bash
suprnova live:add acme/acme-ui/counter --dry-run
```

`--dry-run` fetches, resolves, verifies, scans and reports the whole plan,
dependencies included, and makes the same framework check an install makes.
It writes nothing: not `suprnova.toml`, not the lock, not the journal.

## The lock and the journal

An install holds an exclusive lock on the project, the file
`.suprnova-live.lock` at its root, from before it reads your records until it
finishes. A second `live:add` refuses to start while one runs.

Before its first write, an install writes `.suprnova-live-journal.json`,
naming every path it will change or create and the prior bytes of each it
will change. When any step after that fails, it puts every changed file back,
`suprnova.toml` included, removes every file it created, and deletes the
journal. When an install is killed partway, the next `live:add` or `suprnova
serve` finds the journal with no lock held, restores from it before anything
else, and says so.

`suprnova serve` builds through `suprnova live:wait`. It starts no build
while an install holds the lock, and it holds a shared lock on the project
until the build finishes, so the dev server never builds a half-written
install and `live:add` refuses to start while a build is reading the
project. Both files are this machine's state: a scaffold's `.gitignore` names
them.

## Verify installed components

```bash
suprnova live:check
```

Before it checks your views, `live:check` verifies every third-party
component `suprnova.toml` records, with no network: it recomputes each hash
from the recorded fields and verifies the recorded signature against the
key pinned for its library. A record altered by hand, a bad signature or a
missing pin fails the check. A vendored file whose bytes differ from what
arrived is reported as changed since install and does not fail it, since the
copy is yours to edit.

## The project file

The CLI reads one project file, `suprnova.toml`, all lowercase, at the
project root. `suprnova serve` reads its [extra dev
processes](cli-serve.md#extra-dev-processes) from it, and `live:add` writes
its records there.

An earlier CLI read `Suprnova.toml`; rename that file to `suprnova.toml`.
Until you do, `serve` and `live:add` refuse to run and name the rename. On a
file system that ignores case, rename it in two steps:

```bash
git mv Suprnova.toml suprnova.toml.tmp  # rename, step one
git mv suprnova.toml.tmp suprnova.toml
```

## What live:add never does

- Run anything a component carries: no build script, procedural macro,
  script or view runs while it fetches, verifies, scans or installs.
- Start a process.
- Change `Cargo.toml` or `Cargo.lock`, or add a crate to your build.
- Write anything before the whole plan is fetched, verified, scanned and
  approved.

A component that passes the scan can still fail to compile, for example
against another framework version than its author built it for. That failure
runs none of its code; fix or remove the component as you would your own.

### Why Suprnova diverges

shadcn's CLI copies a component's source from a registry into your project
with no signature and no scan. Laravel installs packages through Composer,
whose plugins run during the install, and a package's service provider runs
on every boot. `live:add` copies like shadcn, so the component is yours, but
trusts nothing it has not checked: the signature against a pinned key, every
file scanned as data, every capability approved by name, and a record in
`suprnova.toml` that `live:check` verifies again offline.

## Next

- [Live Component Libraries](live-libraries.md) - write, sign and publish a
  library of your own
- [Live](live.md) - components, documents, islands and the shipped
  component library
- [CLI Overview](cli.md) - every `live:*` command
- [suprnova serve](cli-serve.md) - the dev runner and `suprnova.toml`


---

<!-- /docs/live-libraries -->

# Live Component Libraries

A Live component library is a git repository of Live components that any
Suprnova application can install with `suprnova live:add`. A component can
carry a view, a stylesheet, a script, and the Rust of a Live component: its
state, actions and view binding. The application that installs it owns the
copy, as it owns the components of the shipped library.

Every library has the same tree, the shipped one included, and every
component in it is signed with the library's key. `live:add` verifies the
signature and scans every file as data before it writes anything, so nothing
a component carries runs during an install. This chapter takes you from an
empty directory to a signed, tagged release. [Installing Live
Components](live-add.md) is the other side: what an application sees when it
installs from your library.

## Quick start

`live:registry new` scaffolds a library with one example component, a
preview application, and a signing key:

```bash
suprnova live:registry new acme --source github.com/acme/acme-ui
cd acme
suprnova live:registry check
```

`--source` is required: the address the library will be published at,
which `library.json` records as its `source` and every signature covers;
see [library.json](#libraryjson). If you later empty or remove `source` by
hand, `check`, `sign` and `rotate-key` refuse until you set it again.

The argument is the library's namespace. It prefixes everything the library
installs: views and assets under `templates/acme-ui/`, Rust under
`src/live/acme/`, Live component names (`acme.counter`), and custom element
tags (`acme-counter`). A namespace is 1 to 32 bytes of lowercase letters,
digits and hyphens, starts with a letter, and its module form (each hyphen
written as an underscore) is not a Rust keyword. The namespaces `suprnova`,
`sn` and `live` belong to the shipped library.

`new` prints where it wrote your private signing key. Back that file up
now; [The private key](#the-private-key) says why.

## The library tree

`live:registry new acme --source github.com/acme/acme-ui` writes this tree
into `./acme`:

```text
acme/
  library.json
  components/
    counter/
      manifest.json
      manifest.sig
      counter.html
      counter.css
      counter.js
      counter.rs
  preview/
```

`library.json` describes the library, `components/` holds one directory per
component, and `preview/` is an application that renders each component from
where it sits. The library sits at the repository's root: `live:add` reads
`library.json` there and each component under `components/`.

### library.json

`library.json` is one JSON object. This is the one `new` wrote above:

```json
{
  "namespace": "acme",
  "source": "github.com/acme/acme-ui",
  "version": "0.1.0",
  "framework": "^3.3.0",
  "publicKey": "ed25519:6HedMVA4Z2cro3wHx0Fh7Vqb3WLDpUtZCsqhG7DpkJA=",
  "title": "acme",
  "description": "Suprnova Live components."
}
```

It holds the keys in this table and no others:

| Key | Holds |
|---|---|
| `namespace` | The namespace every component installs under. |
| `source` | The library's address where you publish it: `github.com/<owner>/<repository>`, `gitlab.com/<owner>/<repository>` or `codeberg.org/<owner>/<repository>`, all lowercase, or the `https://` URL of the tree. `new --source` writes it; without `--source` it is empty, and `check`, `sign` and `rotate-key` refuse until you set it. `live:add` refuses a library whose `source` is not the address it fetched it from, so a fork that copies your files and signatures cannot install as yours. |
| `version` | The release, a semver version. It must equal the release tag: version `0.1.0` is the tag `v0.1.0`. |
| `framework` | A semver requirement on the `suprnova` version of the application. `live:add` refuses an application its requirement does not admit. `new` writes `^` and the version of the CLI that scaffolded the library. |
| `publicKey` | The library's signing key, `ed25519:` and the base64 of its 32 bytes. |
| `previousKeys` | Optional. A statement from each former key that hands the library to `publicKey`; see [Change the signing key](#change-the-signing-key). |
| `title`, `description` | Optional text for people. |

### manifest.json

Each component's `manifest.json` is one JSON object of at most 1 MiB. It
names the component's files and nothing more: a component has no version of
its own, since the library's version is the release, and it declares no
crates.

```json
{
  "name": "acme.counter",
  "root": "acme-ui/counter",
  "title": "Counter",
  "description": "A count kept on the server, raised by a button or the plus key.",
  "files": [
    "counter.html",
    "counter.css",
    "counter.js",
    "counter.rs"
  ],
  "elements": [
    "acme-counter"
  ],
  "register": [
    "counter::Counter"
  ]
}
```

| Key | Holds |
|---|---|
| `name` | `<namespace>.<directory>`. |
| `files` | Each file the component carries, by name, each once. At least one is an `.html` view. |
| `root` | Optional. `<namespace>-ui/<directory>`, which is also the default. |
| `title`, `description` | Optional text for people. |
| `elements` | Optional. Each custom element tag the component's script defines, each starting with `<namespace>-`. |
| `register` | Optional. Each Live component the component's Rust defines, as `<module>::<Type>`, where `<module>` is the stem of one of its `.rs` files. |
| `dependencies` | Optional. Components to install first: a shipped component by its name (`field`), a component of the same library and version (`./date-grid`), a repository address that may carry a version (`acme/acme-base/icon@1.2.0`), or the `https://` URL of a component on a public host. A path on disk is never a dependency. |

A file's extension decides where `live:add` writes it:

| Extension | Lands at | Name |
|---|---|---|
| `.html` | `templates/<namespace>-ui/<directory>/` | Lowercase letters, digits, hyphens and dots, at most 128 bytes |
| `.css`, `.js` | `templates/<namespace>-ui/<directory>/`, served at `/<namespace>-ui/<directory>/<file>` | A stem of 1 to 64 lowercase letters, digits and hyphens, neither starting nor ending with a hyphen |
| `.rs` | `src/live/<namespace_module>/` | A lowercase Rust identifier that is not a keyword, `mod` or `lib` |

`<namespace_module>` is the namespace with each hyphen written as an
underscore. A component directory's name follows the same rule as a
stylesheet stem, because it is the asset route's component segment. Two
components of one library cannot install the same Rust file.

### The example component

The example's Rust is an ordinary Live component, named for the namespace:

```rust
use suprnova::live::{LiveComponent, live};

/// A counter rendered by `acme-ui/counter/counter.html`.
#[derive(LiveComponent)]
#[live(name = "acme.counter", view = "acme-ui/counter/counter.html")]
pub struct Counter {
    /// The current count, rendered by the view.
    #[public]
    count: u64,
}

#[live]
impl Counter {
    /// Adds one in answer to `live:click="increment"`, stopping at the
    /// largest count rather than wrapping to zero.
    #[action]
    pub fn increment(&mut self) {
        self.count = self.count.saturating_add(1);
    }
}
```

Its view names the view path it installs at, `acme-ui/counter/counter.html`.
Every Live component name a library's Rust defines starts with
`<namespace>.`, and each `#[live]` type is exactly one entry of `register`.
When an application installs the component, `live:add` writes
`src/live/acme/counter.rs`, declares `pub mod acme;` and `pub mod counter;`,
and adds this line to the application's registry builder:

```rust
.register::<crate::live::acme::counter::Counter>()?
```

The script defines a light DOM custom element, `acme-counter`, when no
other script has defined that name. The view works without it.

## Preview your components

`preview/` is an application `suprnova new` generated, with the library's
components wired in where they sit. Nothing is copied into it:

- `askama.toml` makes `../components/` a second template root, and each
  view under `templates/acme-ui/` is a one-line stub that includes the
  library's view.
- `src/live/acme/mod.rs` compiles each component's Rust file from
  `../components/` with `#[path]`.
- `src/preview.rs` serves the stylesheets and scripts straight from
  `../components/` at `/acme-ui/<component>/<file>`, the same URL an
  application serves them at after it installs the component, and renders
  one page per component.

Run it from the preview's directory:

```bash
cd preview
suprnova serve --backend-only
```

Then open `http://localhost:8765/preview/counter`. The preview's own test
starts its server and reads the same page:

```bash
cargo test
```

`serve` rebuilds and restarts the preview when a file under its own `src/`
or `templates/` changes. The library's files under `../components/` sit
outside the preview, so `serve` does not watch them. A stylesheet or script
edit shows on the next reload, because the asset route reads the file on
each request. A view or Rust edit shows after the next rebuild: restart
`serve`, or save a file under `preview/src/`.

To preview a new component, give it a page in `src/preview.rs`: add its view
stub under `templates/acme-ui/<component>/`, a `#[path]` line in
`src/live/acme/mod.rs`, its registration in `src/live/mod.rs`, and its mount
and route, as the counter's are. `live:registry check` reads the preview's
registry, so a `register` entry the preview does not register fails the
check.

## Check the library

```bash
suprnova live:registry check
```

`check` runs, from the library's root, every check `live:add` makes for a
reason the library alone decides:

- The tree: `library.json`, the component directories, and their names.
- Each manifest and each file it names: every named file must be a regular
  file inside its component's directory, never a symbolic link.
- Each signature, over the component's verification hash.
- The scan of every view, stylesheet, script and Rust file; see [What the
  scan admits](#what-the-scan-admits).
- The names: Live component names, element tags and `register` entries.
- The dependencies, resolved as `live:add` resolves them: a `./` dependency
  must be in your tree, a bare one in the shipped library, and a full
  address must fetch and verify.

It lists each component's capabilities as `live:add` shows them to the
developer who installs it:

```text
counter: capabilities: none
```

A capability is an effect a component reaches through Suprnova's API, such
as `database` or `network`. [Installing Live
Components](live-add.md#capabilities) lists all nine.

## Sign the library

```bash
suprnova live:registry sign
```

`sign` runs every check `check` runs except the signatures it is about to
replace. Then it signs every component, verifies every new signature, and
only then writes every component's `manifest.sig`. When any component
fails a check, it writes no signature at all. Signing is deterministic:
the same tree and key always sign to the same bytes, so signing an
unchanged tree changes nothing.

Sign again after any change to a component or to `library.json`. Each
component's signature covers the digest of `library.json`, so a new
version, `source` or key leaves every signature stale until you sign
again, and `check` reports each one.

### The private key

`live:registry new` creates the key pair. It writes the public key into
`library.json` and the private key outside the library, into your
configuration directory:

| System | Key file |
|---|---|
| Linux and other Unix | `$XDG_CONFIG_HOME/suprnova/library-keys/<fingerprint>.key`, or `~/.config/...` when `XDG_CONFIG_HOME` is not set |
| macOS | `~/Library/Application Support/suprnova/library-keys/<fingerprint>.key` |
| Windows | `%APPDATA%\suprnova\library-keys\<fingerprint>.key` |

`<fingerprint>` is the hex digest of the public key, so each library has
its own file and `sign` finds it from `library.json` alone. On Unix the file
is readable only by you, and `new` never replaces a file that exists.

To sign on another machine, such as a release job, put the key file there
and name it with `SUPRNOVA_LIBRARY_KEY`:

```bash
SUPRNOVA_LIBRARY_KEY=/run/secrets/acme.key suprnova live:registry sign
```

`sign` refuses a key file inside the library, so a key never ships with a
release. Never commit it.

**Losing the private key strands every pin.** An application that installed
your library pinned its key, and from then on it installs only versions that
key signed, or that a key it handed the library to signed. Without the
private key you can sign no new version and hand the library to no new key,
so every application that pinned it stays on the version it has. Keep a
backup of the key file somewhere safe.

### What a signature covers

A component's signature covers its verification hash: the sha256 digest of
its *statement*, one JSON object with no whitespace and these keys in this
order:

| Key | Value |
|---|---|
| `format` | `suprnova-component/1` |
| `library` | The library's `source` |
| `version` | The library's `version` |
| `component` | The component's directory name |
| `libraryJson` | The digest of `library.json` |
| `manifest` | The digest of `manifest.json` |
| `files` | An object of each named file's digest by file name, names in byte order |

Every digest is `sha256:` and the lowercase hex digest of the file's bytes.
The hash is `sha256:` and the lowercase hex digest of the statement's UTF-8
bytes. `manifest.sig` holds the Ed25519 signature, by the key `library.json`
names, over the ASCII bytes of the hash, as the standard padded base64 of
its 64 bytes and nothing else, not even a final newline. A key's
fingerprint is `sha256:` and the lowercase hex digest of the key's 32 bytes.

The statement names the directory and the library's `source`, so a
component signed under one name or address does not verify under another,
and one changed byte in any file, the manifest or `library.json` changes
the hash.

### Test vector

This vector is the `widget` component of the fixture library the CLI's own
tests install, signed with a test key. A tool that builds the statement and
checks the signature the same way must reproduce the hash and accept the
signature. Never trust this key for anything else.

```text
statement {"format":"suprnova-component/1","library":"github.com/acme/acme-ui","version":"1.0.0","component":"widget","libraryJson":"sha256:94f8914ee1f7889c447b8e0b52251e4e9faeb4badf5c530b3023671972e96b02","manifest":"sha256:3a266a23a32091ed78d8ad3894166799be2bb2a2c8c7f728e5b54734d79699bf","files":{"widget.css":"sha256:5c2f8bed08981ed1f07fbdc1e9ad4d6d0536ec3f1548679b0bf6c36dfed9d81f","widget.html":"sha256:4dff021923cf2408f82e6733a90c590d004f5598d6751dffcd164261c5270471"}}
hash sha256:25a0757c3fed1fcc9ec54986400f546bc1c51f3ba49c5404900e5450dda37a8e
publicKey ed25519:5z4SbonRkzk8kbuQFeoIuaaV0iVATslPzuqhE7XuKwg=
signature OiIoP3FOXZcbC8AqnvgENWiqPucexXxto2Y+b8scJDMVTtw0bvlshIfAL3TKDtIn9dvvi8bTPNUiTVj8ueaLCA==
```

## Publish a release

A release is a `v<version>` tag in a public repository on GitHub, GitLab
or Codeberg. `live:add` reads the tag's files raw, at the commit the tag
names, and never reads release assets.

`live:registry new` creates no git repository. Run `git init` in the
library's root, and add the forge's repository as the `origin` remote. The
repository holds the whole tree, `preview/` included; the preview's own
`.gitignore` keeps its build output and `.env` out. Then, for each release:

1. Make sure `source` in `library.json` is the repository's address, such
   as `github.com/acme/acme-ui`.
2. Set `version` to the release, such as `0.1.0`.
3. Check and sign the library:

   ```bash
   suprnova live:registry check
   suprnova live:registry sign
   ```

4. Commit the signed tree, tag the commit with the version, and push both:

   ```bash
   git add .
   git commit -m "Release 0.1.0"
   git tag v0.1.0
   git push origin main v0.1.0
   ```

An application then installs a component by its address:

```bash
suprnova live:add acme/acme-ui/counter
```

With no version, `live:add` takes the highest `v<semver>` tag, pre-releases
excluded; `acme/acme-ui/counter@0.1.0` names one. A GitLab or Codeberg
library is addressed with its host first: `gitlab.com/acme/acme-ui/counter`.

For each later release, raise `version`, sign, commit, and tag again. Never
move a tag you published. An application records the hash of what it
installed, and `live:add` refuses the same version with different content,
reporting that the library changed a released version.

Keep a published repository's name. Every application that installed from
your library recorded its address and bound your namespace to it.
`live:add` refuses to follow a forge's redirect to a renamed repository, and
refuses a second address that claims a namespace an application already
gave to the first.

To publish without a forge, serve the same tree from any HTTPS host and set
`source` to its URL, such as `https://ui.acme.test/acme-ui`. An application
installs a component by its directory's URL,
`https://ui.acme.test/acme-ui/components/counter`, at the one version
`library.json` names.

## Change the signing key

To move the library to a new key, run `rotate-key` from the library's root:

```bash
suprnova live:registry rotate-key
```

It reads the current private key as `sign` does, from `SUPRNOVA_LIBRARY_KEY`
or your configuration directory, and makes a new key pair. It writes the new
private key into your configuration directory, named by its fingerprint, as
`new` does. It updates `library.json`: `publicKey` becomes the new key, and
`previousKeys` is rewritten as one statement per former key, each handing
the library to the new key. The former keys are the key you are leaving and
every key the library used before it, and each one signs its own statement:
`rotate-key` reads each earlier key from its file in your configuration
directory. It also raises the patch part of `version`, from `1.0.0` to
`1.0.1`: a rotation changes the signed content of every component, and
`live:add` refuses content that changed at a version an application
recorded. Then it signs every component again with the new key, all or
nothing, as `sign` does. It prints both fingerprints and the path of the new
key file. Back up the new key file, then commit the result and tag the new
version as for any release.

**Keep every former key file.** An application installs a release under a
new key only when the key it pinned vouches for that key. A library on its
third key needs a statement from each of its two former keys, so an
application pinned to either one can follow. When a former key's file is
missing, `rotate-key` refuses and names the key. To go ahead without it,
pass `--drop-key` with that key's fingerprint:

```bash
suprnova live:registry rotate-key --drop-key sha256:<fingerprint>
```

`--drop-key` leaves that key's statement out of `previousKeys`. An
application still pinned to the dropped key then refuses every later
release, because its pin vouches for no change, and its developer must pin
the new key by hand. Tell your users the new key's fingerprint through a
channel they already trust before you publish a release without a
statement they need.

After a change, `library.json` looks like this:

```json
{
  "namespace": "acme",
  "source": "github.com/acme/acme-ui",
  "version": "1.0.1",
  "framework": "^3.3.0",
  "publicKey": "ed25519:<the new key>",
  "previousKeys": [
    {
      "publicKey": "ed25519:<a former key>",
      "next": "sha256:<the new key's fingerprint>",
      "signature": "<that former key's signature>"
    }
  ]
}
```

`previousKeys` holds one such entry for each former key. Each former key
signs the UTF-8 bytes of one JSON object with no whitespace,
`{"format":"suprnova-key-handover/1","library":"<source>","next":"<fingerprint>"}`,
where `library` is the `source` in this `library.json` and `next` is the new
key's fingerprint. The statement names the library, so a former key that
signs for several libraries hands over only this one. `signature` holds the
signature in standard padded base64. The format is open, so other tooling
can produce a statement too.

An application that pinned a former key installs the new release only if
the statement from its pinned key verifies, and it re-pins only when its
developer confirms the change on a terminal. The application keeps the
former key in its pin table, so the components it installed under that key
still verify.

A developer whose pinned key you dropped pins the new key by hand: in the
library's table of `suprnova.toml`, set `key` to the new key and move the
dropped key into `previous_keys`, so the components installed under it still
verify:

```toml
[live.libraries."github.com/acme/acme-ui"]
namespace = "acme"
key = "ed25519:<the new key>"
previous_keys = ["ed25519:<the dropped key>"]
```

## What a pinned key proves

The first time an application installs from your library, its developer
pins the key `library.json` names. A pinned key proves continuity: every
later version that application installs comes from whoever held the key at
that first install, or from whoever that holder handed it to through
`previousKeys`. It does not prove who that is. An application trusts your
library because its developer chose to install from your address, and the
pin keeps that choice from silently changing hands.

## What the scan admits

`live:add` scans every component from any library but the shipped one, and
`live:registry check` runs the same scan. The scan reads each file's syntax
tree, compiles and runs none of it, and admits only what it can classify.
A construct it cannot classify, or a name it cannot resolve, is refused,
and no finding can be overridden. A refusal names the check, the file and
the line. Acceptance proves what a component can reach, not that it
compiles.

In Rust, a component may name its own items, the modules of the components
it depends on, Suprnova's documented public API, including the crates
Suprnova re-exports through the `suprnova::` path, and the part of `std`
that has no effects. The scan refuses:

- Any other path, under any alias, a `#[doc(hidden)]` re-export included.
- `unsafe`, `extern` blocks and functions, and `macro_rules!`.
- Every macro, attribute and derive not on its allowlist.
- `#[path]`, a `mod` declaration without a body, `env!`, `option_env!`,
  `include!`, `include_str!`, `include_bytes!` and `cfg_attr`.
- `TrustedHtml`'s constructors, so a view writes unescaped only markup the
  framework built from typed data.
- A method call whose receiver type it cannot name, and a service resolved
  from the container whose type it cannot name.
- A test fake, an app-wide hook or an install, whatever capability the
  facade's chapter grants: `Http::fake` and its siblings, `Queue::fake`,
  `Mail::fake`, `Storage::fake`, `Process::fake`, `Http::global_options`
  and the global request and response middleware, `Queue::set_driver`,
  `Cache::set_connection`, the `install` of a service, the test container
  and the test clock. Each changes what every other caller in the process
  sees, which is the application's to decide, not a component's.
- The application's error handling: `Exceptions::reportable`,
  `dont_report`, `dont_report_when`, `dont_report_duplicates`, `dont_retry`
  and `dont_retry_when`. A component that could change them could hide its
  own failures from the error tracker. A component still reports an error
  with `Exceptions::report` or `try_report`.
- The request's CSP nonce (`Request::csp_nonce`). Whoever holds it can write
  a script the page's policy runs, and a component's view holds no script.
- The engine surfaces the framework holds for the host: the host ports a
  bootstrap installs (`HostCapabilities` and the action, subscription and
  upload authorization, continuity, credential and registry ports), the
  trusted contexts and fingerprints the engine mints, the snapshot key
  material, the wire protocol and proposal application, and the component
  hooks the macros implement. Beyond those, an item of the Live engine or of
  Magnetar, and any item under `suprnova::live`, `suprnova::render_cache`
  or `suprnova::view`, reaches a component only when the generator's admit
  table names it, so neither a re-export made for applications nor a new
  Live item of the framework widens the allowlist by default. Magnetar's
  types are refused, the OAuth provider types at the crate root included:
  authentication is the application's, through the auth flows, never a
  component's.

Each capability the admitted paths carry goes into the plan. Resolving a
trait your own library defines carries none, because the application binds
it to its own implementation.

In a view, parsed with Askama's parser:

- An expression reads the component's state and calls only admitted paths
  that carry no capability, the framework's view helpers, and the
  component's own functions and methods that reach no capability, directly
  or through another of its own items. A view never calls into a
  dependency's Rust, because the scan of this component does not read it.
- No Rust macro, no filter that is neither Askama's nor the framework's, and
  no unescaped output but `trusted_html`: no `safe`, and no `escape` or `e`
  with an escaper other than `html`.
- An `include`, `import` or `extends` names only a view of the component,
  of a component it depends on, or of the shipped library.
- No `script`, `iframe`, `object`, `embed`, `base`, `link` or `meta` element,
  no event handler attribute, no `javascript:` or `data:` URL, and no SVG
  `animate`, `set` or `foreignObject`.
- A URL attribute (`href`, `src`, `srcset`, `action`, `formaction`,
  `poster`, `data`, `xlink:href`, `ping`) holds a constant on the
  application's origin, or a value the application passes in.
- CSS, in a stylesheet or a `style` element or attribute, has no `@import`,
  and every resource it names stays on the application's origin.

In a script, parsed as a JavaScript module:

- Every call resolves to a function the script defines or a standard browser
  API, including calls made through `Reflect`, `call`, `apply`, `bind`,
  getters, setters, `Proxy` traps and tagged templates.
- No `eval` or `Function` under any spelling, no timer given anything but a
  function, no dynamic `import`, no `Worker`, and no `document.write` or
  `document.open`.
- A static `import` is a relative path (`./` or `../`) to one of the
  component's own scripts or to a script a dependency's manifest names, so
  it still resolves when the application serves under a path prefix
  ([Serving under a path prefix](deployment.md#serving-under-a-path-prefix)).
  An absolute path such as `/acme-ui/x/x.js` and a URL are refused, even
  when they name the component's own script, and so is a relative path with
  one `../` more than the component is deep: it leaves the components' root,
  so under a prefix it would resolve outside the prefix. A shipped
  component's script counts only when the component depends on that shipped
  component.
- No `script`, `iframe`, `object` or `embed` element created, and no element
  created by a name the scan cannot trace to a constant.
- No HTML parsed into the document (`innerHTML`, `outerHTML`,
  `insertAdjacentHTML`, `setHTMLUnsafe`, `createContextualFragment`,
  `DOMParser`), no `attachShadow`, and no change to a built-in or to a
  built-in prototype.
- A prototype may be read but not held. `Array.prototype.slice.call(list)`
  and `Object.prototype.toString.call(value)` read a member of a prototype
  and are admitted. A prototype kept in a name, passed as an argument,
  returned, or put in an array or an object is refused, however the script
  reaches it: `Array.prototype`, `Array["prototype"]` or
  `Object.getPrototypeOf(list)`. The scan cannot follow a value to where
  it is used, so it stops the prototype before it leaves the expression
  that reads it. Every write to a member of a prototype is refused, in any
  form (`=`, `+=`, `??=`, `++`, a destructuring or `for` loop target), and
  so is `delete` of one. So is a write to a member of a value read from a
  prototype, wherever the script keeps it: in a name, or in a parameter a
  call hands it to, as `f(Array.prototype.slice)` hands `slice` to `p` in
  `function f(p) { p.call = g }`. A method called on the prototype itself,
  such as `Array.prototype.push(1)`, is refused too: it runs with the
  prototype as `this` and changes it. So is destructuring `prototype` out
  of an object (`const { prototype } = Array`), which puts the prototype in
  a name.
- A built-in may be called, read and kept in a name, but not changed. A
  write to a member of a built-in object or function is refused in every
  form a prototype's is: `Object.keys = f`, `JSON.parse = f`,
  `Math.random = f`, the same through the global object
  (`globalThis.Object.keys = f`, `window.JSON.parse = f`), and
  `Object.keys.call = f`. The scan follows a built-in through the names a
  script keeps it in, so `const k = Object; k.keys = f` is refused, and so
  is a write to a member of a parameter given a built-in by its default or
  by a call of its function by name (`function f(p) { p.call = g }` with
  `f(Object.keys)`).
- A member read under a built-in method's name (`slice`,
  `addEventListener`, `toString`) from a value the script did not make is
  taken to be the method that value inherits, so `[].slice.call = g` and
  `element.addEventListener.call = g` are refused. A member the script's
  own object or class defines under such a name is not, but a field that
  shares one is: `form.search.value = ""` is refused, and
  `form.querySelector("[name=search]").value = ""` is admitted. Reading
  such a member stays admitted.
- A member read off a literal is the built-in method the literal inherits,
  whatever its name: `(0).toPrecision`, `"".anchor`, `[].copyWithin` and
  `/x/.compile`, and the same read off an operator's result such as `-1`
  or `"a" + b`, or off a constant that holds a literal
  (`const n = 0; n.toPrecision`). Writing a member of one is refused, and
  so is passing one on. A string's or an array's `length` and indices, and
  a regular expression's `lastIndex`, `source` and flags, are the literal's
  own and stay admitted. A class that extends a built-in inherits its
  statics, so `class A extends Promise {}` hands over
  `Promise.withResolvers` as `A.withResolvers`, unless the class declares
  a static of that name. A parameter or a variable that may hold a literal
  is not treated as one, because the scan reads no `typeof` test.
- `call`, `apply` and `bind` are how every script borrows a built-in
  method, and any value may hold one under any name: the number
  `Math.random()` returns holds `toPrecision`, an input's `value` holds
  `anchor`, an element holds `requestFullscreen`. So a member of one of
  these three names may be written only on a value the script made: an
  object, array, function or class literal, a function or class it
  declares, a new instance of a standard constructor such as `new Map()`,
  or a name that holds only those. `const o = {}; o.call = 1` and
  `this.call = c` in a class stay admitted; `api.call = f` on a parameter
  the scan cannot trace is refused, and so is `this.state.call = c`, whose
  `state` the scan does not follow.
- Where the scan stops following a built-in, it is refused: passed to
  anything but a function the script calls by name or a browser API that
  only calls it back (`list.map(Number)` is admitted), put in an array or
  an object, written to a member, destructured (`const { keys } = Object`),
  returned, thrown or exported. That covers
  `Object.defineProperty(Object, "keys", ...)`,
  `Reflect.set(Math, "random", f)` and
  `Promise.resolve(Math).then((m) => { m.random = f; })`. A constant such
  as `Number.MAX_SAFE_INTEGER` is a number, not a built-in, and may go
  anywhere. A write to a member of the script's own object or function
  stays admitted (`const o = {}; o.keys = f`,
  `function cache() {} cache.size = 0`), and so does a call
  (`Object.keys(o)`).
- `document`, `location` and `history` hold the page, which a component
  may change: `document.title`, `location.hash` and a value read from
  them, such as `document.body`, stay under the other rules. Their methods
  are built-in functions every script on the page calls, so assigning one
  (`document.createElement = f`, `location.assign = f`) is refused, however
  the script reaches the object: `this.ownerDocument`, what `getRootNode()`
  returns, which is the document for any node in it
  (`document.getRootNode().open = f`), and `Object(document)` included.
  The page also reaches a script through paths the scan does not follow:
  an element's `parentNode`, an event's `currentTarget`, and an array, a
  promise or a function that hands `document` back. So a method of the page
  whose name is never ordinary data (`createElement`, `querySelector`,
  `getElementById`, `addEventListener`, `pushState` and the rest of the
  page's own) may be assigned only on a value the script made, as above.
  An instance of the script's own class does not count, because its
  constructor may return `document`.
- The window `window.open` returns is a global object like `window`, so a
  built-in read from it, or a method of its `document`, is refused written
  or passed on as this window's is: `window.open("/x").JSON.parse = f`, and
  `popup.Object.keys = f` after `const popup = window.open("/x")`. Using
  the window, as `popup.focus()` and `popup.location.href = "/y"` do,
  stays admitted.
- A write to a member of the global object is refused, whatever the name
  and in every form: `window.AcmeState = {}`,
  `globalThis["Acme" + "State"] = 1`, `window.acmeState++` and
  `delete window.fetch` are all refused, and so is a write to a member of
  the window `window.open` returns (`popup.name = "x"`). Every script on
  the page shares the global object, so such a write could replace a
  browser API or a name the application or the Live runtime keeps there.
  Keep a component's state in its module scope instead: a `let` or `const`
  at the top of the script, or a field of its element class. A write never
  unlocks a read: after `try { window.localStorage = 1 } catch {}`,
  reading `window.localStorage` is still refused, as is any read of a
  global the scan does not admit.
- An attribute name given to `setAttribute` traces to constants and is not an
  event handler, `srcdoc` or `style`.
- A URL given to `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`,
  `sendBeacon`, `location`, `window.open`, or a URL property or attribute is
  a constant on the application's origin.
- `customElements.define` takes a constant name the manifest's `elements`
  declares.

A component reaches the database, the network, files, mail, a queue, a cache,
the session, the environment or a process only through Suprnova's API, and
each of those carries a capability the installing developer approves.
`live:add` never adds a crate to the application, so nothing enters its
build that the scan did not read.

### Why Suprnova diverges

Laravel packages arrive through Composer and run as soon as the application
boots: a package's service provider is code the application runs, chosen by
the package. shadcn copies a component's source into a project from a
registry, with no signature and no scan. A Suprnova library sits between the two. Like
shadcn, `live:add` copies the component into the application, which owns it
from then on. Unlike either, every component is signed by its library's key,
pinned on first use, and scanned as data before anything is written, and the
developer approves each capability by name. The library declares no
dependencies of its own, so the scan reads everything the component adds to
the build.

## Next

- [Installing Live Components](live-add.md) - the plan, capabilities, pins,
  and the provenance record an install writes
- [Live](live.md) - components, views, documents and islands
- [CLI Overview](cli.md) - every `live:*` command
- [suprnova serve](cli-serve.md) - the dev runner the preview uses


---

<!-- /docs/static-publication -->

# Static Publication

Static publication serves explicitly public Inertia pages from a named storage
disk. Each page has separate HTML and JSON objects. The origin keeps the route
available when storage or a CDN is unavailable.

## Declare a public page

Use the same checked props contract as [RenderCache](render-cache.md). Every
field must be public. Register shared props by name and list every shared key
as public. Authentication, errors, flash and credential props cannot be public.
An opaque shared provider cannot prove its fields and refuses publication.

```rust
use suprnova::{InertiaProps, InertiaResponse, Request, Response, Router};

#[derive(InertiaProps)]
#[inertia(cacheable)]
struct AboutProps {
    #[inertia(public)]
    title: String,
}

async fn about(request: Request) -> Response {
    InertiaResponse::new("About")
        .cacheable(AboutProps { title: "About us".into() })?
        .resolve(&request).await.map_err(Into::into)
}

fn routes() -> Result<Router, suprnova::FrameworkError> {
    let router: Router = Router::new().get("/about", about).into();
    router.public_page::<AboutProps>("/about", "About")
}
```

A group can opt in through `router.public_page_group("/articles")`. Each
handler still needs an `Inertia::public_page::<Props>(pattern, component)`
declaration. An unmarked route never enters the publication inventory.

```rust
suprnova::Inertia::share("site", "Example")?;
suprnova::Inertia::public_shared(&["site"])?;
```

Public rendering uses no visitor session. It skips session and CSRF middleware,
excludes session props and uses the dependency collector to refuse a handler
that reads session, identity or secret context. A refusal names the route and
cause. It fails the whole publication and keeps the previous inventory live. The failure
and route appear in status. It does not stop the server listener.

## Configure a disk and boot publication

The disk can be local, S3, GCS, Azure or any registered OpenDAL operator. Give
publication its own disk root. Pruning owns that root and can remove objects
that no retained publication references.

```rust
use suprnova::{FrameworkError, Router, Storage};
use suprnova::static_publish::{PublishConfig, Publisher, StaticPublication};

fn publish(router: &Router) -> Result<(), FrameworkError> {
    Storage::register_memory("pages");
    let publisher = Publisher::new("pages", "build-20261022", PublishConfig::default())?;
    let publication = StaticPublication::install(router, publisher)?;
    publication.assets(Storage::disk("public-assets")?)?;
    publication.add_path("/articles/welcome")?;
    Ok(())
}
```

Register the source disk `public-assets` against the application's public
directory before this function. It supplies built assets and source images.
Use the same Inertia asset version for the page config and the publisher.
Asset versions reserve `lease`, `manifest.json`, `lease.json`, every name that
begins with `_` and every name that contains `/`. Both publisher constructors
refuse these names because they overlap the publication control namespace.
Concrete parameterized paths can be listed with `add_path`. A missing public
path is also rendered and published when its first origin request arrives.

`Server::run` starts publication after `TcpListener::bind`. Health checks can
run while assets upload. Shutdown cancels rendering and staging. Once delivery
starts, it runs as owned work; graceful shutdown waits for the switch and
manifest commit or rollback. The configured timeout bounds this work, including
cleanup. A quarter of the timeout, up to ten seconds, is reserved for recovery.
Uploads have a configured concurrency limit. An upload failure leaves the live
manifest in place and logs an error.

```bash
cargo run --bin console -- static:publish
cargo run --bin console -- static:status
```

The publish command runs the same pipeline as boot. Status reports the live
revision, last outcome and pending work. No page body or credential appears in
the status output.

## Objects, versions and switching

Pages use `_pub/<asset-version>/<revision>/<path>.html` and
`_pub/<asset-version>/<revision>/<path>.json`. The root page uses `index`.
The extra revision keeps regeneration from overwriting the currently live
page. Fingerprinted assets retain their names and receive
`public, max-age=31536000, immutable`. Other assets, such as an SVG favicon,
receive bounded cache directives. Pages reference their versioned keys, so every referenced object exists before delivery begins.

Page objects never receive `immutable`. Their `Cache-Control` contains
`s-maxage`, `stale-while-revalidate` and `stale-if-error`. Browser `max-age`
is clamped to `revalidate`. Object entries retain content type and hash CSP.
Cookies are excluded. `Vary` may name only `X-Inertia` and `X-Inertia-Version`;
other fields and `*` refuse publication. Request cache directives compare
case-insensitively before storage lookup.

```rust
use std::time::Duration;
use suprnova::static_publish::PublishConfig;

let policy = PublishConfig {
    revalidate: Duration::from_secs(60),
    browser_max_age: Duration::from_secs(10),
    s_maxage: Duration::from_secs(60),
    stale_while_revalidate: Duration::from_secs(30),
    stale_if_error: Duration::from_secs(300),
    concurrency: 4,
    ..PublishConfig::default()
};
```

`_pub/manifest.json` records `live` and a `versions` map. Each version records
its asset version, publication time, retirement time and objects. Each object
records its storage path, public URL, SHA-256 digest, asset version, dependency
tags and response headers. Previous versions remain until their grace expires.

All versioned uploads finish before the manifest PUT. Unchanged digests skip
uploads. A CDN driver selects `_pub/<asset-version>/<revision>/` as the page
origin path. Without a driver, stable `<path>/index.html` and
`<path>/index.json` aliases are written one at a time after the manifest commit.
The manifest is the origin switch; stable bucket aliases are a post-commit mirror that converges.

## Publishers in separate processes

Publication and pruning acquire an epoch record under `_pub/lease/` before
reading the manifest or planning work. Keys use a zero-padded 20-digit unsigned
integer, such as `_pub/lease/00000000000000000001.json`. A record contains
`owner`, `epoch` and `expires_at_ms`. The highest epoch is the current lease;
foreign keys are ignored and no lease key is served by the origin.

Installing static publication reserves the `/_pub/lease/` URL prefix for
GET and HEAD requests. Such a request below it receives 404 before application
routing, so a GET or HEAD application route declared there is never reached.
Other methods are not intercepted.

If no record exists, acquisition atomically creates epoch 1. An unexpired
highest record refuses another publisher. An expired record permits atomic
creation of the next epoch. A competing creation of that same key refuses as
held. Acquisition never deletes or replaces a record. Takeover needs only
`write_with_if_not_exists` or `write_with_if_none_match` and works the same on
every disk. Every publisher sharing the disk must use this epoch protocol.
Fs lease creation uses the registered-disk confined exclusive-create primitive
at the operator's root, including for application operators with `atomic_write_dir`.
Application operator layers still handle publication data, lease reads and release;
lease creation uses the confined operator directly. A root that cannot support
this primitive refuses setup and names `Storage::register_fs` in the diagnostic.

Verification lists the chain and checks the highest epoch, owner and acquired
expiry. Release overwrites only the holder's own record with expiry zero, so
the next acquisition advances the epoch instead of reusing its key. Bounded
Drop cleanup does the same; failed release leaves expiry as the fallback.
Prune verifies ownership before deleting records below the highest, which it
always retains. All other keys in the lease namespace stay outside orphan
cleanup.

The manifest retains its separate conditional write: `write_with_if_match`
uses the observed manifest ETag when available; otherwise a byte comparison
detects a changed manifest. Atomic epoch creation does not require conditional
replacement. A process that ignores the lease must not write the publication
disk.

Hosts must use NTP and keep their clock difference below
`STATIC_PUBLISH_CLOCK_SKEW` seconds, which defaults to 10; non-integer settings refuse publication setup. A holder stops using
its lease at `expires_at - skew`; a taker waits until `expires_at + skew`.
Rollback verifies ownership first. If ownership changes or the holder's usable
window expires, it leaves the CDN to the new owner and records the failure.

```bash
STATIC_PUBLISH_CLOCK_SKEW=10 cargo run --bin console -- static:publish
```

Mirror writes, prune deletions and prune manifest commits verify ownership
before each operation; a lost lease stops maintenance and reports the current
owner.

Run the same commands with the application's `console` binary, from the server deployment or a console process:

```bash
cargo run --bin console -- static:publish
cargo run --bin console -- static:status
```

The publisher releases its lease before bounded status persistence, so a slow
status write cannot consume the lease release budget.

A refused lease appears in status. Boot continues serving. An interrupted
manifest PUT is reconciled by reading the durable manifest: the attempted live
version means success; the predecessor means failure and a fenced rollback.
A failed read or a third version records `outcome: "unknown"`, `previous_version`
and `attempted_version` in status and leaves the CDN unchanged. The next
publication reads the manifest fresh and checks `CdnDriver::selected_version`
before rendering. A different or unknown selection calls `switch_version` for
the manifest's live version, independently of cached status. CloudFront reads
its configured origin path; custom drivers may return unknown. The first
publication has no live version to restore.

Mutable assets and the fingerprinted dependencies in their relative asset graph
form one set at `_pub/<asset-version>/_assets/<set-digest>/<public path>`.
The set digest is SHA-256 over the JSON array of sorted public path and content
digest pairs. HTML and JSON reference set members at these paths, so relative
CSS URLs and module imports resolve inside the set. Page-only changes reuse the
set without uploading or copying assets. A changed set writes every member once,
using server-side copy for unchanged members when the disk supports it, or upload
otherwise. Fingerprinted assets also retain their canonical names.

Each manifest version records `asset_set_digest` and a `page_asset_sets` map of
page URLs to set roots. Omitted pages keep their set references in a partial
publication. Prune removes a set directory only when no retained version
references it; the live version and retired versions inside grace retain theirs.

## CDN drivers

`CdnDriver` is the single publish-side interface. It switches a version,
advertises purge capabilities and purges tags, URLs or a prefix. The in-memory
driver records operations for tests. Cloudflare and CloudFront drivers ship with
the framework. An application can add another provider by implementing this trait.

```rust
use std::sync::Arc;
use suprnova::static_publish::{Publisher, PublishConfig};
use suprnova::static_publish::cdn::MemoryCdnDriver;

let driver = Arc::new(MemoryCdnDriver::default());
let publisher = Publisher::new("pages", "build-42", PublishConfig::default())?
    .with_cdn(driver);
```

### Enable a CDN driver

Both drivers are on by default: `cdn-cloudflare`, which adds no dependency,
and `cdn-cloudfront`, which shares the AWS signing stack with the S3 disk and
adds `quick-xml`. Cloudflare with R2 is the recommended setup; R2 charges no
egress. An application built with `default-features = false` lists the
feature for the driver it constructs, or
`suprnova::static_publish::cdn::CloudflareDriver` or `CloudFrontDriver` does
not exist and the build names the missing item.

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", default-features = false, features = ["filesystem", "cdn-cloudflare"] }
```

### Cloudflare and R2

An R2 bucket with a custom domain is the whole setup: the bucket is the
publication disk, the custom domain serves it, Cloudflare's cache sits in
front, and the driver owns a few rules on the zone and the purges. Nothing
runs at the edge. R2 charges no egress.

Register the bucket through `S3Config`: the account's R2 endpoint, the `auto`
region, and static keys from an R2 API token with read and write access to the
bucket. In the Cloudflare dashboard, connect a custom domain to the bucket
(R2 Object Storage, the bucket, Settings, Custom Domains); that is the `host`
the driver takes. Create a zone API token with Cache Purge, Transform Rules
edit and Cache Rules edit. Read the keys and the token from the application's
configuration and pass them in; the driver reads no environment variable.

```rust
use std::{sync::Arc, time::Duration};
use suprnova::{FrameworkError, S3Config, Storage};
use suprnova::static_publish::{PublishConfig, Publisher};
use suprnova::static_publish::cdn::CloudflareDriver;

fn cloudflare(
    account_id: &str,
    access_key: &str,
    secret_key: &str,
    zone_id: &str,
    zone_token: &str,
) -> Result<Publisher, FrameworkError> {
    let s3 = S3Config {
        bucket: "public-pages".into(),
        endpoint: Some(format!("https://{account_id}.r2.cloudflarestorage.com")),
        region: Some("auto".into()),
        access_key_id: Some(access_key.into()),
        secret_access_key: Some(secret_key.into()),
        root: None,
    };
    Storage::register_s3("pages", s3.clone())?;
    let driver = CloudflareDriver::new(zone_id, "docs.example.com", zone_token, &s3)?;
    let policy = PublishConfig {
        // Every changed page is purged after its publication, so a long shared
        // lifetime is safe; the default of a minute would refetch each page from
        // the bucket every minute per data center.
        s_maxage: Duration::from_secs(86_400),
        ..PublishConfig::default()
    };
    Ok(Publisher::new("pages", "build-42", policy)?.with_cdn(Arc::new(driver)))
}
```

The custom domain serves the bucket's keys as paths, and after every manifest
commit the publisher mirrors the live version to stable keys, `about/index.html`
and `about/index.json`, so the mirror is the switch and the driver has no origin
path to move; `selected_version` reports unknown and the publisher realigns with
its manifest. The driver creates its rules on the first switch and corrects them
on every later one, each on `http.host eq "<host>"` and identified by a `ref`
that starts with `suprnova-static-publication-`, so rules the application wrote
on the same zone are never touched:

- Two URL rewrites in the `http_request_transform` phase: a path that ends in
  `/` gets `index.html` appended, and a path without an extension and not under
  `/_pub/` gets `/index.html` appended, so `/about` and `/about/` both serve
  `about/index.html` while `/about/index.json` and fingerprinted assets pass
  through. With a disk root, every path is prefixed with it, through one more
  rewrite for the paths that already name an object.
- One response header rule in `http_response_headers_transform` that sets the
  headers the publisher validated, such as `Content-Security-Policy`; R2 serves
  `Content-Type`, `Cache-Control` and the other object headers itself, so the
  rule does not repeat them.
- One cache rule in `http_request_cache_settings` that makes a response on
  the host eligible for the cache only when its own `Cache-Control` allows a
  shared cache, as every published object's does (Cloudflare caches no HTML
  or JSON by default), and for the time it names. A dynamic page on the same
  host that sends no such header is never cached, so one visitor's page never
  reaches another. The edge keeps each page for its `s-maxage`, so set
  `PublishConfig::s_maxage` to hours or a day: changed pages are purged after
  every publication.

A rollback of the first publication deletes those rules; a later rollback has
nothing to move. The constructor refuses the same ambiguous root segments as
CloudFront. The public dashboard setting named Local Uploads speeds uploads
into the bucket and plays no part in serving.

For a hostname that also serves dynamic pages, keep its DNS at the application
behind Cloudflare's proxy and use `CloudflareDriver::for_origin(zone_id, host,
zone_token)`: the application serves the published objects and their headers
itself, as it does for every published path, the driver writes only the cache
rule and purges, and unpublished paths reach the application as usual. A cache miss is
then a request to the application, so the `s_maxage` advice above matters most
there.

The driver advertises URL and prefix purges, so the publisher purges each
republished page by URL: full HTTPS URLs in batches of 100, the per-request
limit on Free, Pro and Business (Enterprise allows 500). Single-file rate
limits are 800 URLs per second on Free, 1500 on Pro and Business, and 3000 on
Enterprise. Cloudflare also purges by tag on every plan, but a tag purge clears
only responses that carried a `Cache-Tag` header, which the publication does
not set; an application that sets the header through its own rule can call
`purge(Purge::Tags(...))` itself. Prefix and tag purge requests are limited to
5 per minute on Free, 5 per second on Pro, 10 per second on Business and 50
per second on Enterprise, with at most 100 operations per request; tags are
batched to that. Prefix values contain a host and path without a scheme, query
or fragment. Provider refusals include the HTTP status and first error code and
message, with the token redacted. See the
[purge API](https://developers.cloudflare.com/api/resources/cache/methods/purge/),
the [single-file guide](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-single-file/),
the [plan limits](https://developers.cloudflare.com/cache/how-to/purge-cache/#availability-and-limits)
and the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/rulesets-api/).

### CloudFront

CloudFront uses AWS signed requests with the same credential provider chain
as the S3 disk. It reads the complete distribution configuration and its ETag,
changes the selected origin's path, sends `If-Match`, waits for deployment and
creates invalidations. Static keys can be passed from `S3Config`; otherwise
the AWS profile or instance role supplies credentials.

The default `cdn-cloudfront` feature supplies the driver independently of SQS.
Register the publication disk and construct the driver from its configuration:

```rust
use std::{sync::Arc, time::Duration};
use suprnova::{FrameworkError, S3Config, Storage};
use suprnova::static_publish::{PublishConfig, Publisher};
use suprnova::static_publish::cdn::CloudFrontDriver;

fn cloudfront(s3: S3Config) -> Result<Publisher, FrameworkError> {
    Storage::register_s3("pages", s3.clone())?;
    let driver = CloudFrontDriver::new("E123EXAMPLE", "public-pages", &s3)?
        .with_response_headers_function(
            "arn:aws:cloudfront::123456789012:function/suprnova-public-headers",
        )?;
    let policy = PublishConfig {
        timeout: Duration::from_secs(900),
        ..PublishConfig::default()
    };
    Ok(Publisher::new("pages", "build-42", policy)?.with_cdn(Arc::new(driver)))
}
```

`public-pages` is the distribution's origin ID. An S3 root of `pages` selects
`/pages/_pub/<version>`; the constructor refuses ambiguous root segments. The driver preserves other
origins and configuration fields. A failed switch or manifest write restores
the previous origin version, including the original distribution configuration
when the first publication fails. Rollback failures appear in the publication
error. A custom driver implements `rollback_version` to restore its initial
configuration as well.

Configure the distribution to map `/about` to `/about.html` and
`/about/index.json` to `/about.json`. Send fingerprinted asset paths and `/_pub/*` asset paths to the
asset origin without the page version prefix, retaining the S3 root prefix. An origin-path switch changes
the prefix; it does not create these viewer-request rewrite rules.

S3 returns custom headers as `x-amz-meta-*`. Those names do not enforce CSP.
Publish the supplied viewer-response function once. Write its source with:

```rust
use suprnova::static_publish::cdn::RESPONSE_HEADERS_FUNCTION;

fn main() -> std::io::Result<()> {
    std::fs::write("public-headers.js", RESPONSE_HEADERS_FUNCTION)
}
```

Create and publish the function with the AWS CLI:

```sh
aws cloudfront create-function --name suprnova-public-headers \
  --function-config 'Comment=PublicHeaders,Runtime=cloudfront-js-2.0' \
  --function-code fileb://public-headers.js
aws cloudfront publish-function --name suprnova-public-headers \
  --if-match ETAG_FROM_CREATE
```

Associate its ARN with the `viewer-response` event on each cache behavior
that uses the public page origin. Pass that ARN to
`with_response_headers_function`. The driver refuses a switch if any matching
behavior lacks the function. The function replays every validated recorded header, including Content-Disposition,
Reporting-Endpoints and HSTS, then removes the metadata headers. Headers the
viewer-response function cannot carry refuse publication before switching.
The origin applies HSTS only for trusted HTTPS delivery. It blocks scripts in an HTML object
that has lost its CSP metadata. This follows the
[CloudFront response event format](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-event-structure.html).

Storage writes delivery policy headers as metadata: Cache-Control, CSP, Vary,
HSTS, reporting, content type protection, referrer and permissions policies,
cross-origin policies and validated application headers. Content-Type is native
storage metadata. Content-Length, ETag and Content-Encoding belong to the served
representation; the CloudFront function preserves them after compression.

A local static server or another CDN must likewise serve the manifest's
`headers` as HTTP headers. A plain S3 website exposes custom headers only as
metadata; place a header bridge in front of it before serving public documents.
The Suprnova origin fallback already serves the headers directly. Header restrictions
follow the [AWS edge function contract](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-function-restrictions-all.html).

Fingerprint classification uses the same default file-stem pattern as StaticFiles:
a hyphen followed by eight base64url characters with a digit, uppercase letter,
underscore or hyphen. Names such as `brand-background.svg` remain mutable.
Select another build convention explicitly:

```rust
use suprnova::static_publish::{Publisher, PublishConfig};
let publisher = Publisher::new("pages", "build-42", PublishConfig::default())?
    .fingerprint(r"\.release$")?;
```

## CSP and private requests

Nonce documents cannot be published. Select the public hash mode described in
[Security Headers](security-headers.md). It hashes the trusted document's
executable inline scripts. Public pages contain no nonce attributes. Private
pages retain their fresh per-request nonce. A later injected script does not
gain a hash source.

```rust
let headers = suprnova::SecurityHeaders::balanced().hash_public_pages();
suprnova::middleware::register_global_middleware(headers);
```

All three [starter kits](starter-kits.md) install the same static HTTP client.
The document lists public page JSON URLs. Public navigation fetches these
objects while preserving the canonical page URL. Partial reloads, polling,
deferred and once props, and mutations use the live URL with
`__suprnova_origin=1` and `Cache-Control: no-store`. A version mismatch reloads
the document. Flash and validation errors arrive through this private path.

The client reads `XSRF-TOKEN`. If the cookie is absent before a mutation, it
makes a same-origin private GET first. The existing CSRF middleware issues the
cookie and accepts its `X-XSRF-TOKEN` header. Public objects contain no CSRF
token. See [Inertia Responses](frontend-inertia-responses.md).

## Regenerate after writes and by time

Generation writes keep RenderCache's transactional advancement. A successful
framework commit queues affected dependency tags. Rollback discards the work.
The worker coalesces queued tags and renders dependent HTML and JSON through
the original publication pipeline. It purges through the installed driver
after the switch. Without a purge driver, the edge lifetimes bound staleness.
The configured revalidation interval also refreshes pages by time.

`Publisher::publish` and `publish_with` replace the complete inventory, so
removed routes and assets can retire. `publish_partial` and
`publish_partial_with` retain omitted pages and assets during a targeted
regeneration. Boot, the console command and timed revalidation publish the full
inventory; dependency regeneration and first-visit fallback publish a subset.

```rust
use std::sync::Arc;
use suprnova::{FrameworkError, Schedule, static_publish::StaticPublication};

fn scheduled(publication: &Arc<StaticPublication>, schedule: &mut Schedule) -> Result<(), FrameworkError> {
    publication.schedule(schedule)
}
```

Bind the application's `Arc<dyn BroadcastHub>` before installing publication to
carry committed dependency tags from standalone workers to serving nodes. The
publication subscriber uses the same configured hub transport as other framework
broadcasting and queues each received tag for the serving worker. For example:

```rust
use std::sync::Arc;
use suprnova::{App, BroadcastHub, InMemoryBroadcastHub};
let hub: Arc<dyn BroadcastHub> = Arc::new(InMemoryBroadcastHub::new());
App::bind::<dyn BroadcastHub>(hub);
```

Use a cross-process hub driver in a worker deployment. Without a configured hub,
notifications remain process-local and the revalidate interval bounds freshness.
A disconnected or lagging hub also falls back to timed revalidation and logs the
failure. Only dependency digests travel through the hub, never rendered props.

## Prepare images

Publication resolves local image URLs against the document path. Posters, image
preloads and other collected raster references use the same preparation path.
Without the media feature, raster references refuse publication with a route
diagnostic. It emits
fingerprinted WebP objects at quality 85 and keeps a metadata-stripped original
fallback. Picture sources preserve responsive descriptors, media and sizes.
Quality must stay between 85 and 100. AVIF requires explicit enablement and
the ImageMagick driver with an AVIF codec.

```rust
use suprnova::static_publish::images::ImageOptions;

let mut images = ImageOptions::default();
images.keep_png.insert("icons/app.png".into());
publication.images(images)?;
```

`data-static-keep-png`, configured `keep_png` paths, linked PNG icons and web
manifest PNG icons use oxipng Maximum with Zopfli. Metadata is stripped from
every prepared raster. Absolute URLs on the application's public origin use the local source disk.
Raster data URLs are decoded and published as metadata-stripped objects, with
modern variants and a rewritten fallback just like local images. An invalid
raster data URL refuses publication with the route and cause; the origin keeps
serving the page. Third-party images are neither transcoded nor published.
Linked stylesheets are build outputs published byte for byte; their images belong
to the build, including small images Vite inlines below `assetsInlineLimit`.
Raster data URLs and same-origin raster `url(...)` references in document style
attributes or `<style>` elements refuse publication with the route and element;
move the image into an `<img>`, a `<picture>` or a stylesheet file.
Non-raster data URLs stay unchanged. SVG and ICO files
keep their existing representation. See [Images](images.md).

The collector reads the complete Vite inventory before image preparation.
A raster referenced only by a Vite entry or CSS keeps its key and its original
format. The media pipeline strips its metadata and recompresses retained PNGs
with the Maximum preset. Without the media feature, these dependencies refuse
publication with the route and the reason.

## Prune retired objects

Every successful attempt prunes, including an unchanged inventory. The same pass is available on
demand. Reports list removed and kept keys. Live objects, stable aliases and
versions inside the grace period stay protected. Grace starts when a version
stops being live. Prune commits removal of expired version records before any
object deletion. A failed deletion leaves orphans rather than dangling manifest
references. Set reuse consults only versions still in the manifest. The next
prune sweeps unreferenced asset-set directories, including failed staging sets,
within the publication deadline. Other objects with no reliable age stay
protected. A prune failure does not remove the live version or undo its switch.

```bash
cargo run --bin console -- static:prune
cargo run --bin console -- static:status
```

### Why Suprnova diverges

Laravel does not publish Inertia routes to object storage itself. Packages
provide that behavior. Suprnova uses its typed props declarations, transactional
dependency collector and named disk drivers. Separate HTML and JSON keys avoid
depending on an object store varying responses on `X-Inertia`.

The origin trusts a forwarded HTTPS scheme only from the proxies named in
`APP_TRUSTED_PROXIES`; `APP_TRUSTED_PROXIES` is empty by default, so a deployment
behind a TLS-terminating proxy must list it or HSTS is never sent.

## Next

- [RenderCache](render-cache.md)
- [Security Headers](security-headers.md)
- [Starter Kits](starter-kits.md)


---

<!-- /docs/render-cache -->

# RenderCache

RenderCache stores a proven-safe copy of a GET or HEAD route's response and
serves the next matching request from it without running your handler at
all. You opt routes and groups in explicitly; everything else keeps working
exactly as it does today. A route you never opt in is untouched. A route you
do opt in still renders and serves correctly even when nothing about that
particular request turns out to be safe to cache - it just never gets
stored, and you can find out why.

This chapter covers enabling the cache, opting routes and groups in,
declaring variance, reading the response headers it adds, the reasons a
render is declined, operational control, and how it differs from
`suprnova::Cache`.

## The chapters

This is the first of five. Read them in order the first time; after that,
each answers one question on its own.

| Chapter | Answers |
|---|---|
| RenderCache (this one) | How do I turn it on and opt a route in? |
| [Representations](render-cache-representations.md) | What is actually stored, and under what key? |
| [Generations](render-cache-generations.md) | When does a stored copy stop being current? |
| [Deployment](render-cache-deployment.md) | How do several nodes share one cache? |
| [Operations](render-cache-operations.md) | How do I inspect it, test it, measure it, and switch it off? |

## Enabling the cache

Two environment variables matter to start:

- `RENDER_CACHE_ENABLED` - `true` unless set to `false` or `0`. With it
  disabled, every request bypasses RenderCache entirely; nothing is looked
  up and nothing is stored.
- `RENDER_CACHE_L1_DIR` - unset by default, which means no on-disk tier. Set
  it to a directory the process can create and write to, and stored
  representations survive a process restart in a file-backed second tier.

A handful of other variables tune the defaults: `RENDER_CACHE_L0_ENTRIES`
(4,096) and `RENDER_CACHE_L0_BYTES` (128 MiB) bound the in-process tier;
`RENDER_CACHE_L1_BYTES` (1 GiB) bounds the file tier; `RENDER_CACHE_FAILURE`
(`open` by default, or `closed`) decides whether a store or database problem
serves the route uncached or refuses the request; `APP_BUILD_ID` namespaces
every cached entry to the build that produced it. Set it explicitly to
something that changes every deploy: its default is a compiled-in crate
version, which does not. See
[RenderCache Deployment](render-cache-deployment.md).

`RENDER_CACHE_PROFILE` (`embedded` by default, or `database` or `redis`)
chooses whether the second tier and the rebuild coordinator are in this
process or shared with every other node. A shared profile also needs a
migration your application lists. Both are the
[Deployment](render-cache-deployment.md) chapter's subject, together with
the full variable table.

## Opting a route or a group in

Nothing is cached until you say so. `Router::try_render_cache` opts one
already-registered route pattern in; `Router::try_render_cache_group` opts
every route under a path prefix in. Both take a policy built with
`RenderCachePolicy::builder`:

```rust
use suprnova::{FrameworkError, Router};
use suprnova::render_cache::{
    FreshnessPolicy, RenderCachePolicy, RepresentationClass, SharedCachePolicy,
};

fn add_render_cache(router: Router) -> Result<Router, FrameworkError> {
    router.try_render_cache_group(
        "/blog",
        RenderCachePolicy::builder(RepresentationClass::PublicShared)
            .freshness(FreshnessPolicy::new(300_000, 60_000, 300_000)?)
            .shared(SharedCachePolicy::SMaxAge { seconds: 300 })
            .build()?,
    )
}
```

`FreshnessPolicy::new(fresh_ms, stale_servable_ms, stale_on_error_ms)` sets
how long a representation is fresh, and then two windows measured from that
fresh edge: how far past it the stored copy may still be served while a
background rebuild runs, and how far past it the stored copy may be served
if a foreground rebuild fails outright. The two windows are not stacked; see
[RenderCache Representations](render-cache-representations.md).

`RepresentationClass` runs from widest to narrowest sharing: `PublicShared`
(one representation for everyone who matches the declared variance),
`PublicShellStitched` (a Live document or typed Inertia page whose public shell
is stored once and whose request slots resolve after the route guards; see
[Representations](render-cache-representations.md)),
`PrivateCached` (one representation per signed-in visitor or tenant), and
`Uncacheable`.

A route pattern must already be registered before you opt it in, and you
must finish opting routes and groups in **before** calling
`RenderCache::install` (below) - the install step reads whatever has been
registered by that point.

A route-level policy can also be a narrowing patch of its enclosing group,
using `PolicyPatch` instead of a full `RenderCachePolicy`: it inherits
everything the group declared and may only make it narrower (a shorter
freshness window, a stricter class), never wider. Pulling one route out of a
cached group entirely is a `PolicyPatch` that sets the class to
`Uncacheable`.

Finish wiring RenderCache in with one line, after every middleware
registration that establishes request-scoped locale, session, or identity
(RenderCache reads them to build its lookup key, so it needs to run after
whatever sets them up):

```rust
use suprnova::RenderCache;
use suprnova::render_cache::RenderCacheConfig;

Application::new()
    // ...
    .try_routes_async(|| async {
        let router = add_render_cache(routes::register())?;
        RenderCache::install(router, RenderCacheConfig::from_env()).await
    });
```

## Declaring variance

By default a cached representation varies only by route pattern, path
parameters, and the application build. Anything else your handler's output
actually depends on needs to be declared, with two mechanisms:

- **Query parameters.** `.query(QueryPolicy::declared(["page", "sort"]))`
  names the query parameters that distinguish representations; any other
  query parameter present on a request bypasses the cache for that request
  rather than being silently ignored.
- **Variance dimensions**, added one at a time with `.vary(dimension)`:
  - `VarianceDimension::Locale` partitions by the negotiated locale.
  - `VarianceDimension::Host` partitions by the request's host, where your
    deployment makes more than one host meaningful.
  - `VarianceDimension::Tenant` partitions by the current tenant as opaque
    key material; a route whose handler ever reads the tenant must declare
    it.
  - `VarianceDimension::Principal` partitions by the signed-in visitor as
    opaque key material, bound to a permission version (see "Epoch,
    permissions, and inspection" below); a `PrivateCached` route must
    declare `Principal` or `Tenant` (or both) or it fails to build at all.
- **`Media` and `Encoding`**, declared together with their own closed set:
  `.vary_media(NegotiatedPolicy::declared(["text/html", "application/json"],
  "text/html")?)` and `.vary_encoding(NegotiatedPolicy::declared(["identity",
  "gzip"], "identity")?)`. The bare `.vary(VarianceDimension::Media)` (or
  `::Encoding`) is rejected at `build`/`apply`: unlike every other
  dimension, these two negotiate against a set only the route can name, so
  there is nothing to key by without it.

  Negotiation reads the request's `Accept` (for `Media`) or
  `Accept-Encoding` (for `Encoding`) header, matches it against the
  declared set, and adds the matching request header to `Vary`. It is
  `q`-weighted: the declared member with the highest quality wins, and
  equal quality keeps the header's own left-to-right order, so the
  candidate listed first wins a tie. A wildcard (`*/*`, `type/*`, a bare
  `*`) is compared as a literal token, not expanded against the set, so it
  practically never matches a real declared value. An absent header, a
  value naming nothing in the declared set, or a header this cannot make
  sense of - a `q=0`, an out-of-range or unparsable quality, garbage syntax -
  resolves to the declared default rather than creating a variant or
  failing the request. Two different negotiated values are two different
  keys; the same negotiated value, however it was spelled or weighted on
  the wire, is always the one stored representation for it.

`VarianceDimension::FeatureVersion`, `VarianceDimension::ConfigVersion`, and
a custom `VarianceDimension::Application(name)` exist on the type, but
nothing gives them a value, so no key can be built for a policy that
declares one. The framework refuses such a policy when you register it.
`try_render_cache` and `try_render_cache_group` return an error, so your
application stops at boot. The refusal applies to a full policy and to a
patch that brings one of the three in. The other six dimensions register
without error.

The error is a `FrameworkError`. Its message names the route pattern (or the
group prefix) and the dimension, and tells you to remove the dimension from
the policy:

```text
RenderCache policy for `/blog` varies on FeatureVersion, and nothing gives that
dimension a value, so no response for `/blog` could be cached. Remove the
dimension from the policy.
```

A group whose policy declares one of the three is refused even when every
route under it has a patch that replaces the dimensions. Take the dimension
out of the group's policy.

## Publish public Inertia pages

[Static Publication](static-publication.md) uses the same checked
`#[inertia(cacheable)]` props contract and dependency collector. A route must
also opt in with `public_page`. All fields and registered shared props must
be public. Public rendering reads no session. Per-request fields and nonce
CSP documents refuse publication. The origin still answers these routes.

Published page objects carry bounded browser lifetimes and the configured
`s-maxage`, `stale-while-revalidate` and `stale-if-error` directives. They
never receive `immutable`. Fingerprinted assets receive the immutable
one-year lifetime. Separate HTML and JSON objects preserve Inertia's
representation boundary on storage disks that cannot vary on `X-Inertia`.

```rust
let router = router.public_page::<AboutProps>("/about", "About")?;
```

## Reading the response headers

A served hit carries `ETag` (a strong validator your client can send back as
`If-None-Match` for a `304`), `Cache-Control`, `Vary`, and `Age` (whole
seconds since the representation was published, and the quickest local sign
that a response came out of the store rather than out of your handler). A
response served past its fresh interval additionally carries
`Warning: 110 - "Response is Stale"`. Each of the five is defined, with the
values the dogfood routes are asserted to send, in
[RenderCache Representations](render-cache-representations.md).

## Why a render is never stored

Being opted in is not a guarantee. Two independent checks run after every
render, and either can decline storage without failing the request - the
response you get back is identical either way, it just never becomes a
cache entry:

**Eligibility** declines outright for a response that is not a plain `200`
to a `GET` or `HEAD`, that streams its body, that sets a cookie, or that
carries a hop-by-hop or tracing header. These are almost always accidental
(a redirect, an error page, a response that happens to touch
`Set-Cookie`) rather than something you need to design around.

**Classification** declines based on what your handler actually did while
it ran, in terms you will recognize:

- **You read a session value.** Any read of the current session (through
  `session()`, `session_mut`, or a session cookie) forces the render to
  `Uncacheable`, permanently, no matter what variance the route declares.
  The one thing this does *not* cover is the signed-in visitor's own
  identity. `Auth::id()` reads it out of the session when nothing earlier in
  the request resolved it, and that read is classified as an identity read,
  not a session read - so an ordinary cookie-backed login is exactly what a
  `PrivateCached` route declaring `Principal` variance is for, and reaching
  for the visitor's id does not quietly make the page uncacheable. Every
  other value in the session still does. Two consequences worth knowing: an
  anonymous request to such a route caches under the `Anonymous` key,
  because the render resolved no identity, observed no principal material,
  and the key says so - a signed-in visitor derives a `Private` key that
  never reaches that entry; and a named guard's own identifier is principal
  material too, recorded as `<guard>:<id>`. The key's `Principal` dimension
  is the default guard's identity, so a page built from another guard's
  user never matches it and is never stored, even when both guards name
  the same id. A default-guard id that holds a `:` is keyed as `:<id>`, so
  web user `admin:9` never matches admin `9` either. A hit skips the route's own `AuthMiddleware`, so such a page
  would otherwise reach a visitor who holds only the default guard's
  sign-in.
- **You read an identity, on a route that does not declare `Principal`.**
  Reading the signed-in user narrows the class to `PrivateCached`; if the
  route's declared variance does not include `Principal`, there is no way
  to key the entry per visitor, so it is declined rather than shared.
- **You translated (or your view engine did) without declaring `Locale`.**
  Any read of the negotiated locale needs a declared `Locale` dimension, or
  the render is declined. Every Inertia page's document shell reads the
  locale to set `<html lang>`, whether or not the page's own data has
  anything to do with language - so an Inertia route needs `Locale`
  declared to ever cache at all, even one with no translated content of its
  own.
- **You checked authorization.** A decision is judged by what its own
  evaluation read. A gate whose body reads only the tenant - through
  `suprnova::live::current_tenant()`, say - classifies under `Tenant` alone
  and caches on a route keyed by `Tenant`. A gate that reads a per-user
  fact, or that reads nothing RenderCache can see, still needs `Principal`
  declared: a body that decided from its `user` argument through no
  instrumented accessor is indistinguishable from one that decided from a
  constant, and the safe reading of that is the conservative one.
- **A model behind the page carries a global scope that reads per-request
  state.** Declare what the scope depends on. A `GlobalScope` returning
  `ScopeDependency::Constant` records nothing and costs no cache hits. The
  default, `ScopeDependency::PerRequest`, requires the scope's `apply` to
  read that state through an instrumented accessor -
  `suprnova::live::current_tenant()`, `Auth::id()`, `Lang::locale()`. A
  per-request scope whose evaluation reads none of them narrows the render
  to `Uncacheable` and names itself in the decline, so an invisible tenant
  filter costs you the cache rather than costing your visitors each other's
  rows.
- **You read a secret configuration value, or an undeclared request
  context.** Both force `Uncacheable`. A response's dependence on an
  ordinary request header, or on `Config::get`, is invisible to RenderCache
  entirely - it cannot decline what it cannot see, so declaring the
  matching variance is on you.
- **You ran raw SQL through `DB::select`, `DB::select_one`, `DB::scalar`, or
  `DB::select_on`, or a query that carries a raw fragment.** The framework
  cannot name the tables a raw statement or fragment read, so the render is
  never stored; it is still served. A raw fragment is a `select_raw`, an
  `order_by_raw`, or a raw `WHERE` clause (`where_raw`, `or_where_raw`,
  `filter_raw`, `or_filter_raw`) on `DB::table(..)` or a model query,
  subqueries included; a `select_raw`
  that is a bare number, such as `select_raw("1")`, reads nothing and
  doesn't count. Other reads through `DB::table(..)` know their tables and
  are cached normally, and so is `Auth::user()`, which resolves through
  that path.
  The framework's own RBAC role and permission checks name the five tables
  they read - `roles`, `permissions`, `role_has_permissions`, `model_has_roles`,
  and `model_has_permissions` - so a cached route that evaluates one is observed
  precisely and cached normally.
- **The write was made by a queue worker, a scheduled task, or a console
  command.** Nothing special is needed any more. Every process whose
  configuration enables RenderCache and whose database holds the RenderCache
  migration advances generations, so such a write invalidates exactly what
  the same write invalidates in the server, and
  `RenderCache::bump_permission_version()` works from any of them. A process
  with `RENDER_CACHE_ENABLED=false`, or one whose database does not hold the
  migration, advances nothing and issues no RenderCache SQL at all.

On PostgreSQL the render runs in a `REPEATABLE READ` transaction so that what
it read and the generations it recorded agree; a cached route's handler that
updates a row another transaction changed after the render began sees a
serialization failure. Design cached routes as read paths. A handler that
does write inside the render transaction still advances generations, but it
competes with concurrent writers for the same rows and can see the
serialization failure above.

A write made outside any transaction (`model.save()` on its own) commits
first and advances its generations in an immediately following transaction,
so the moment between the two is "new data, old generation": one extra
rebuild, never stale content.

None of this needs special tooling to see happen in practice: the hidden
`render-cache:inspect` command (below) shows whether a route's entry
exists at all, or you can just try two requests in a row and check whether
the second one carries an `Age` header.

## A route that caches

A public listing page with no per-visitor content:

```rust
use suprnova::{handler, HttpResponse, Response};

#[handler]
pub async fn index() -> Response {
    let posts = Post::query().order_by_desc("published_at").get().await?;
    Ok(HttpResponse::html(render_post_list(&posts)))
}
```

registered and opted in:

```rust
use suprnova::{get, routes};
use suprnova::render_cache::{FreshnessPolicy, RenderCachePolicy, RepresentationClass, SharedCachePolicy};

routes! {
    get!("/blog", controllers::blog::index),
}

router.try_render_cache(
    "/blog",
    RenderCachePolicy::builder(RepresentationClass::PublicShared)
        .freshness(FreshnessPolicy::new(300_000, 60_000, 300_000)?)
        .shared(SharedCachePolicy::SMaxAge { seconds: 300 })
        .build()?,
)?;
```

`index` never touches the session, the signed-in visitor, or the locale, so
the first request renders and publishes; every request for the next five
minutes is served from that stored copy with an `Age` header, a `304` for a
client that already has it, and `Cache-Control: public, max-age=300,
s-maxage=300` for any CDN in front of it.

## A route that is declined

The same shape of page, but the handler reads the session to show a flash
message:

```rust
use suprnova::session::session;
use suprnova::{handler, HttpResponse, Response};

#[handler]
pub async fn index() -> Response {
    let posts = Post::query().order_by_desc("published_at").get().await?;
    let flash = session().and_then(|s| s.get::<String>("status"));
    Ok(HttpResponse::html(render_post_list_with_flash(&posts, flash.as_deref())))
}
```

opted in exactly the same way as above. Every request still renders and
serves the correct page - flash message included - but nothing is ever
stored: the session read narrows the class to `Uncacheable` before
RenderCache even reaches the eligibility check, so a second request for the
same URL renders again from scratch rather than coming back with an `Age`
header. The fix, if this page is meant to cache, is to stop reading the
session in the cached path (render the flash from a query parameter or a
separate small response instead) - there is no variance declaration that
makes a session read cacheable, because a session read means the response
depends on something no key could safely partition by.

## Epoch, permissions, and inspection

- **`RenderCache::bump_permission_version().await?`** - call this whenever
  an application action changes what a signed-in user is allowed to do (a
  role change, a permission grant or revocation). It advances a persisted
  generation that every principal-keyed render observes. The generation
  survives a restart, and the bump joins the transaction the role change
  runs in when there is one. Without the bump, a user whose permissions just
  changed keeps matching whatever was cached under their prior permission
  set.
- **`RenderCache::advance_epoch()`**, or the hidden
  `render-cache:epoch-advance` command - an emergency invalidation. The
  epoch is baked into the lookup key itself, so advancing it puts stored
  entries out of reach with nothing to enumerate and nothing to delete. On
  the process that runs it the effect is immediate: it drops that process's
  epoch lease and clears its in-process tier the same instant. Another node
  catches up at its next authority read, and its file-backed tier keeps its
  old files until a sweep reclaims them - the automatic one every 256th
  publication, or an explicit `RenderCache::sweep()` - which is disk hygiene
  rather than a correctness concern. Reach for this when something
  is wrong with cached content and you cannot wait for individual entries to
  expire; on more than one node, see
  [RenderCache Operations](render-cache-operations.md).
- **The hidden `render-cache:inspect <key>` command** reports one stored
  entry's metadata (never its body) by the key text your application logs
  or telemetry can surface, alongside the current epoch, so you can tell
  whether what you are looking at is still live authority or has already
  aged out from underneath. It looks the key up in the running process's
  in-process tier only, never in the shared one, so on a `database` or
  `redis` profile it reports no entry for a key this node has not served
  itself.

## RenderCache versus `suprnova::Cache`

`suprnova::Cache` is a key-value store you call explicitly: you choose the
key, you choose what to store, you choose when to invalidate it
(`Cache::put`, `Cache::get`, `Cache::remember`, `Cache::forget`). It works
for any data your code decides is worth caching, on any backend you
configure (memory or Redis).

RenderCache is not a general-purpose store, and you never call it from your
handler. It caches whole HTTP responses, the key is derived automatically
from the route and its declared variance, and invalidation is
generation-based: an ordinary database write through the ORM or query
builder advances the generations the render depended on, and the entry is
recomputed the next time it is asked for rather than deleted by hand; a
render that read raw SQL is never stored in the first place, so there is
nothing to recompute. Reach
for `suprnova::Cache` when you have a specific value you want to compute
once and reuse; reach for RenderCache when you have a whole route whose
response is expensive to render and safe to share.

### Inertia representations

Install Inertia before serving cached pages. RenderCache declares `X-Inertia`,
the partial component, sorted `only` and `except` sets, and the current and
requested asset versions in every Inertia key. List entries retain whitespace,
as the Inertia protocol requires. Reset, once exclusions, error bags, and scroll
intent also partition entries. A stale GET version returns 409 before lookup.
An Inertia response keeps `Vary: X-Inertia` and JSON hits keep `X-Inertia: true`.
Cacheable pages use `#[inertia(cacheable)]` and classify every field as
`#[inertia(public)]` or `#[inertia(per_request)]`. Register their shared prop
lists with `Inertia::cache_page` before installing a `PublicShellStitched`
policy. Boot refuses an unlisted shared prop with the route and prop name.
The assembled response stays `private, no-store`. See the complete runnable
[cacheable page example](frontend-inertia-responses.md#cacheable-pages).

The usual eligibility and privacy rules still apply. Session reads decline a
Complete page. Declare `Locale` for document shells.

```rust,no_run
use suprnova::render_cache::{FreshnessPolicy, RenderCachePolicy, RepresentationClass, VarianceDimension};

fn page_policy() -> Result<RenderCachePolicy, suprnova::FrameworkError> {
    let freshness = FreshnessPolicy::new(60_000, 0, 0)
        .map_err(|e| suprnova::FrameworkError::internal(e.to_string()))?;
    RenderCachePolicy::builder(RepresentationClass::PublicShared)
        .freshness(freshness).vary(VarianceDimension::Locale).build()
        .map_err(|e| suprnova::FrameworkError::internal(e.to_string()))
}
```

See [Inertia responses](frontend-inertia-responses.md) and [Representations](render-cache-representations.md).

### Why Suprnova diverges

Laravel has no equivalent in the framework itself. Response caching is a
package you add, it wraps the route in middleware that stores the rendered
response under a key you compose, and everything after that is yours: which
routes are safe to cache, what makes two visitors different, and when a
stored page stops being true. The framework does not know a page was cached,
so it cannot tell you when caching one was a mistake.

RenderCache is part of the framework for exactly that reason. It sees the
render happen, so it can record what the handler read, compare that against
what the route declared, and refuse to store a response whose safety it
cannot account for - silently, without changing what the visitor is served.
Opting a route in is a declaration the framework then holds you to, rather
than a promise you make to yourself. The cost is that some routes you would
like to cache are declined and you have to find out why; the benefit is that
the ones that are stored were proven safe to store, once, by the process
that rendered them.

## Next

- [RenderCache Representations](render-cache-representations.md) - what is
  actually stored, under what key, and in which layers
- [RenderCache Generations](render-cache-generations.md) - how a stored copy
  stops being current
- [Cache](cache.md) - the explicit key-value store this chapter contrasts
  with
- [Live](live.md) - the documents a stitched representation is cut from


---

<!-- /docs/render-cache-representations -->

# RenderCache Representations

A cached route does not store "a page". It stores a **representation**: one
concrete response, under one lookup key, in one or more storage layers, with
enough metadata beside it to answer a conditional request and to prove later
that it is still current. Two visitors get the same stored bytes only when
the key they derive is the same key, and the key is derived from what the
route declared - never from what the handler happened to do.

This chapter is about that stored thing. What forms a representation can
take (`Complete` and `Composite`), what goes into its key, which layers it
is written to, the `ETag`, `Cache-Control`, `Vary`, `Age`, and `Warning` a
served hit carries, the four freshness states it can be in, how it answers
`If-None-Match` and `HEAD`, and what `PrivateCached` and
`PublicShellStitched` actually store. *Why* a representation leaves the
fresh band - a write, an epoch advance - is the next chapter's subject; here
it is enough that the bands exist and that one representation sits in one of
them. Every example below is a route in this repository's dogfood application
(`app/src/live/mod.rs`) and is proved by a named test in
`app/tests/live_render_cache.rs`.

## Two entry forms

A stored entry is one of two kinds.

- **`Complete`** is a finished answer: a status, a set of replayable
  headers, and one body buffer. Serving it copies nothing and runs nothing.
  Every `PublicShared` and `PrivateCached` route stores this form.
- **`Composite`** is a shared **shell** with typed holes cut in it, plus a
  segment graph saying what goes back into each hole. Only
  `RepresentationClass::PublicShellStitched` stores this form, and only a
  Live document or a registered cacheable Inertia page produces one.

The class you declare in the policy decides which form is even reachable.
`/live/public` and `/live/todos` both declare `PublicShared`;
`the_database_profile_serves_a_hit_through_the_sql_stores` reads
`/live/todos`'s published entry back out of the store and asserts it is an
`EntryKind::Complete` one, and
`the_public_document_is_a_hit_whose_seed_still_promotes` reads
`/live/public`'s back out of L0 and asserts the class it was stored under;
`RenderCacheProbe::route("/live/public").l0()` reads the same entry in your
own test. That matters, because "it was stored"
and "it was silently declined" produce the same response: the claim has to
be made against the entry, not against what the visitor sees.

## The lookup key

The key a request derives is built from the route pattern, its path
parameters, the query parameters the policy declared, each declared variance
dimension's resolved value, the application build id (`APP_BUILD_ID`), and
the current authority epoch. Nothing else. A query parameter that arrives on
the request but is not named by `QueryPolicy::declared` bypasses the cache
for that request rather than being quietly dropped from the key, because
dropping it would serve the wrong page to whoever sent it.

The key is text an operator can hold:
`the_operator_commands_inspect_without_a_body_and_advance_the_epoch` asserts
that the key of `/live/todos` starts with `rk1.`, and `render-cache:inspect`
takes exactly that text. `RenderCacheProbe::key` derives it in your own test.

Because the epoch is part of the key, an epoch advance does not have to find
and delete anything. Every previously stored entry simply stops being
reachable by ordinary lookup at the next request. That is the mechanism the
[Operations](render-cache-operations.md) chapter's emergency invalidation
relies on.

## Which layers a policy writes to

There are two storage layers. **L0** is in-process memory, bounded by
`RENDER_CACHE_L0_ENTRIES` and `RENDER_CACHE_L0_BYTES`. **L1** is whatever
the deployment profile configures - a directory of files, a database table,
or Redis - and is shared by every process that points at it.

The policy builder stores in **L0 only** unless you say otherwise:
`StorageLayers::l0_only()` is the default. A route that is worth putting in
the shared tier declares it:

```rust
use suprnova::render_cache::{
    FreshnessPolicy, RenderCachePolicy, RepresentationClass, StorageLayers,
};

let router = router.try_render_cache(
    "/live/todos",
    RenderCachePolicy::builder(RepresentationClass::PublicShared)
        .freshness(FreshnessPolicy::new(300_000, 60_000, 300_000)?)
        .layers(StorageLayers::l0_and_l1())
        .build()?,
)?;
```

That is `/live/todos`'s declaration from `app/src/live/mod.rs`. It is the
one document in that application whose bytes every node can share, so it is
the one that declares `l0_and_l1()`. Under the embedded profile, where L1 is
disabled unless `RENDER_CACHE_L1_DIR` names a directory, declaring the layer
changes nothing; under the Database profile the entry lands in
`suprnova_render_entries` and a second process finds it there.

`the_database_profile_serves_a_hit_through_the_sql_stores` is the proof.
It boots the application on the Database profile's providers, reads the
published entry directly out of L1 under the very key the middleware
derived, then empties L0 and asks again - and the second request is still
answered without the handler running. An in-memory hit would look identical
from the client's side, which is why the test reaches for the store.

Pick the layers per route rather than globally. L1 costs a round trip on a
miss that L0 alone does not, and an entry that only one node will ever ask
for is not worth putting where every node can see it.

## The metadata a served hit carries

Five response fields describe a served representation, and this is where
they are defined; the other chapters use them without restating them.

| Field | What it says |
|---|---|
| `ETag` | A strong validator over exactly the bytes sent. A client may send it back as `If-None-Match`. |
| `Cache-Control` | `private, no-cache` for every class by default: the browser may keep the bytes but asks the server before every reuse, so a write that invalidates the stored entry reaches the next view instead of waiting out a `max-age` in the browser. The question is cheap, because an unchanged entry answers the browser's `If-None-Match` with a `304`. For a `PrivateCached` response it is also what keeps accounts apart: the browser's own cache keys a response by URL alone and would otherwise show one account's page to the next account signed in on the same browser. A `PublicShared` route that sets `SharedCachePolicy::SMaxAge` gets `public`, `max-age` and `s-maxage` instead, which is the only way a shared proxy is ever invited to keep the bytes. A `Composite` document with at least one island is `private, no-store`, whether it was assembled on a hit or rendered by the leader that published the shell. |
| `Vary` | Derived from the declared variance dimensions that imply a request header: `Locale` implies `Accept-Language`, `Media` implies `Accept`, `Encoding` implies `Accept-Encoding`. A dimension that implies none adds nothing. The names are emitted sorted by header name, not in the order you declared the dimensions. |
| `Age` | Whole seconds since the representation was published. Its presence is the simplest local proof that a response came out of the store. |
| `Warning` | `110 - "Response is Stale"`, and only on a response served past its fresh interval. |

The dimension-to-header mapping is `VarianceDimension::vary_header` in
`crates/suprnova-live/src/render_cache/variance.rs`. Two engine tests prove
the `Locale` and `Encoding` halves of it and the joined header value:
`a_descriptor_orders_dimensions_and_bounds_values`
(`crates/suprnova-live/tests/render_cache_variance.rs`) asserts a descriptor
carrying both reports `["Accept-Encoding", "Accept-Language"]`, and
`cache_control_and_vary_agree_with_class_variance_and_seed_deadline`
(`crates/suprnova-live/tests/render_cache_coherence.rs`) asserts the same
pair emits `Accept-Encoding, Accept-Language` and that a descriptor with no
header-implying dimension emits no `Vary` at all. `Media` implying `Accept`
is documented from the code; no test here pairs it.

Three of the response values are asserted against the running application:
`the_public_document_is_a_hit_whose_seed_still_promotes` reads
`private, no-cache` off `/live/public` and requires an `Age` header on
the second request;
`the_private_document_is_cached_per_principal_and_never_crosses` reads
`private, no-cache` off `/live/me`;
`the_dashboard_is_stitched_per_principal_from_one_shared_shell` reads
`private, no-store` off the dashboard on the render that publishes its shell
as well as on the assembled hit after it, because that value follows what the
bytes hold and not which path produced them.

## The four freshness states

Every hit resolves to exactly one of four states before anything is served.
`FreshnessPolicy::new(fresh_ms, stale_servable_ms, stale_on_error_ms)` sets
them. **The two stale windows are both measured from the end of the fresh
interval, not stacked one after the other** - this is the detail that trips
people up:

| State | Age since publication | What the visitor gets |
|---|---|---|
| Fresh | below `fresh_ms` | the stored bytes, no `Warning` |
| Stale-servable | past `fresh_ms` by less than `stale_servable_ms` | the stored bytes immediately, under `Warning`, with a bounded rebuild spawned behind the request |
| Stale-on-error | past `fresh_ms` by at least `stale_servable_ms`, and by less than `stale_on_error_ms` | a foreground rebuild; the stored bytes under `Warning` only if that rebuild itself fails |
| Dead | past `fresh_ms` by the larger of the two windows or more | nothing; the request renders |

`/live/todos` declares `FreshnessPolicy::new(300_000, 60_000, 300_000)`, so
it is fresh for five minutes, stale-servable for the sixth, stale-on-error
until ten minutes, and dead after that.

Two rules override the bands. A `PrivateCached` representation is **never**
served stale: past its fresh interval it is Dead, which is why `/live/me`
declares `FreshnessPolicy::new(60_000, 0, 0)` - a stale band there would
read as a promise the cache does not keep. And a stored public-seed
document whose promotion deadline has passed is Dead whatever its intervals
say, because a seed past its deadline can never be promoted again.

`stale_service_is_marked_and_rebuilt_in_the_background` drives `/live/todos`
across the first boundary on a controlled clock and asserts the served body,
`Warning: 110 - "Response is Stale"`, and `Age: 300`. What *causes* a
representation to leave the fresh band early - a write, an epoch advance -
is [RenderCache Generations](render-cache-generations.md)'s subject.

## Conditional requests and HEAD

A client that sends a served `ETag` back as `If-None-Match` gets a `304`
with no body, and a `HEAD` gets the headers with no body. Neither reaches
your handler:

```
GET  /live/todos                          -> 200, ETag: "..."
GET  /live/todos  If-None-Match: "..."    -> 304, empty body
HEAD /live/todos                          -> 200, same ETag, empty body
```

`conditional_and_head_requests_are_answered_from_the_stored_entry` asserts
all three against the running application, including that the render count
does not move across the last two.

One exception, and it is deliberate: a `Composite` response never answers
`304`. Every assembly is a distinct representation - fresh island identities,
a fresh bootstrap nonce where the document has one - so a `304` would tell
the client to pair the body it already holds with headers minted for this
request. The `ETag` on an assembled response is still strong over exactly
the bytes that were sent; it simply never matches a later request. Step 7
of `the_dashboard_is_stitched_per_principal_from_one_shared_shell` sends a
served validator straight back and asserts a `200` with a different `ETag`.

## A representation that belongs to one person

`RepresentationClass::PrivateCached` stores one representation per
signed-in visitor. It is refused at build time unless the policy also
declares `Principal` or `Tenant` variance, so the pairing cannot drift apart
by accident:

```rust
use suprnova::render_cache::{
    FreshnessPolicy, RenderCachePolicy, RepresentationClass, VarianceDimension,
};

let router = router.try_render_cache(
    "/live/me",
    RenderCachePolicy::builder(RepresentationClass::PrivateCached)
        .freshness(FreshnessPolicy::new(60_000, 0, 0)?)
        .vary(VarianceDimension::Principal)
        .build()?,
)?;
```

The handler behind it is an ordinary one. It resolves the signed-in visitor
and renders their name:

```rust
pub async fn me(_request: Request) -> Response {
    let result: Result<HttpResponse, FrameworkError> = async {
        let user = Auth::user_as::<User>()
            .await?
            .ok_or_else(|| FrameworkError::internal("Live account document without a principal"))?;
        html(&MeView { name: user.name })
    }
    .await;
    result.map_err(failed)
}
```

Nothing extra is wired up to make that cache. The route carries the same
`AuthMiddleware::redirect_to("/login")` the dashboard does, so an anonymous
visitor is redirected before the handler runs, and the principal itself is
resolved inside the render. Reading the signed-in visitor's identity out of
the session is classified as an **identity read**, not a session read, so
the render narrows to `PrivateCached`, the key carries opaque per-principal
material, and the two agree.

`the_private_document_is_cached_per_principal_and_never_crosses` signs in
two visitors, hits twice each with no render, and asserts that each body
names its own person and not the other's; a third visitor renders, because
they share nothing with either. The served `Cache-Control` is
`private, no-cache`, so no shared proxy is ever offered the bytes, and the
browser revalidates before every reuse: a visitor who signs out and the next
one who signs in on the same browser never get each other's page out of the
browser's own cache. The revalidation is cheap, because the same visitor's
`If-None-Match` is answered `304` from the stored entry. The
same test shows the other half of the bargain: the render resolves its
principal through the provider that reads the `users` table, so seeding a
third visitor invalidates every stored `/live/me` entry, and the next
request for each rebuilds. That is table-granular invalidation doing exactly
what [Generations](render-cache-generations.md) describes.

Two consequences of that classification are worth knowing before you
declare the class:

- An **anonymous** request to a `PrivateCached` route with `Principal`
  variance caches under the `Anonymous` key. The render resolved no
  identity, so no principal material was observed, the key says `Anonymous`,
  and the two agree. A signed-in visitor derives a `Private` key that can
  never reach that entry. This applies when such a request actually renders
  a `200`, which `/live/me` never does - its login redirect answers a `302`,
  and a `302` is refused by eligibility before any of this is consulted. The
  framework test that does reach it is
  `an_anonymous_render_resolving_identity_through_the_session_caches_anonymously`
  in `framework/tests/render_cache/middleware.rs`.
- A **named guard's** identifier is principal material in exactly the same
  way as the default guard's. Reading it records a principal read and, when
  there is an id, the value.

And one rule that has not moved: a route that reads the principal *without*
declaring `Principal` variance is declined from storage. There is no way to
key such an entry per visitor, so it is never stored rather than shared.
Every other session value still forces `Uncacheable`; see the
classification list in [RenderCache](render-cache.md).

## A shell with holes in it

`RepresentationClass::PublicShellStitched` supports Live documents and typed
Inertia pages. The public frame is shared and request slots are not. The stored entry
holds the shell alone. No identity-bound island's markup and no signed
snapshot is ever inside the stored bytes; every hit re-mounts every island
for whoever is asking, under authority derived for that request.

This repository's dashboard is that route:

```rust
router.try_render_cache(
    "/live",
    RenderCachePolicy::builder(RepresentationClass::PublicShellStitched)
        .freshness(FreshnessPolicy::new(300_000, 60_000, 300_000)?)
        .build()?,
)
```

`the_dashboard_is_stitched_per_principal_from_one_shared_shell` asserts what
that buys and what it costs. The stored entry is an `EntryKind::Composite`
with three slots, one per identity-bound island. A second principal is
answered from that shell, and the two documents differ **only** in their
island tags - the test strips the three island tags from each and compares
what is left, byte for byte. The route's own login redirect still runs on
every hit: a stitched hit is forwarded through the route's whole middleware
chain before anything is served, so an anonymous visitor gets the redirect,
never an assembled document.

A stitched document with at least one slot is sent
`Cache-Control: private, no-store`, on the render that publishes the shell as
much as on every assembly after it. It holds one principal's islands under
authority re-derived for one request, and a `max-age` would let a shared
browser profile replay them to whoever sits down next; which path produced the
bytes does not change what is in them. A zero-slot `Composite`
carries no per-principal bytes at all, only a per-request nonce, so it is
sent `private, no-cache` like any other private representation;
`a_zero_slot_composite_is_assembled_with_a_fresh_nonce_on_every_hit` in
`framework/tests/render_cache/stitch.rs` asserts that. Either way the class
refuses `SharedCachePolicy::SMaxAge` at policy build time, so no shared
proxy is ever offered the bytes.

Live routes complete assembly in the Live completion middleware. Registered
cacheable Inertia routes complete at the handler boundary, after the route's
guards. Inertia stores public page JSON with one structured request slot;
the composite engine checks its identity, surrounding bytes, and body bound.
It then writes page JSON or renders the root document. SSR runs against the
assembled props on every HTML visit when enabled. Inertia assemblies stay
`private, no-store`, including the response that first publishes the shell.
If current request props exceed the assembly bound, the response uses those
current values without repeating the handler or its resolvers. Invalid slot
identities still fail closed. A nonce CSP declines Inertia shell publication.
A stitched entry is never
served by the stale-on-error fallback and never triggers a background rebuild. The
[Generations](render-cache-generations.md) chapter says what that second one
means in practice.

A typed declaration makes the same boundary explicit for Inertia:

```rust,no_run
use suprnova::{Inertia, InertiaProps, Prop, FrameworkError};

#[derive(InertiaProps)]
#[inertia(cacheable)]
struct PageProps {
    #[inertia(public)]
    title: String,
    #[inertia(per_request)]
    viewer: Prop,
}

fn register_page() -> Result<(), FrameworkError> {
    Inertia::cache_page::<PageProps>("/page", "Page", &[], &["errors", "flash"])
}
```

Register named shared props first, then attach a `PublicShellStitched`
policy and install RenderCache. The handler uses
`InertiaResponse::new("Page").cacheable(PageProps { ... })?`.
The [Inertia response chapter](frontend-inertia-responses.md#cacheable-pages)
contains the complete handler and boot example.

### Why Suprnova diverges

Laravel has no server-side representation model at all. Its response-caching
packages store the rendered output of a route under a key you compose
yourself - typically the URL, sometimes the URL plus a hand-written suffix
for the logged-in user - and hand it back on the next request. There is one
form of stored thing, it is always a finished body, and whether two visitors
share it is a property of the string you built.

Suprnova makes the key a declaration and the form a consequence. You name
the class and the variance dimensions; the framework derives the key,
refuses `PrivateCached` without a partitioning dimension, compares what the
render actually observed against what the key actually said, and declines to
store the render when the two disagree. And because `PublicShellStitched`
exists, a page that is 95 percent shared and 5 percent private does not have
to choose between caching nothing and caching something it should not: the
shared part is stored once and the private part is re-rendered per request,
with the private bytes never entering the store.

## Next

- [RenderCache Generations](render-cache-generations.md) - how a stored
  representation stops being current, and what happens next
- [RenderCache](render-cache.md) - declaring policies, variance, and the
  reasons a render is never stored
- [Live](live.md) - the islands a stitched shell has holes for


---

<!-- /docs/render-cache-generations -->

# RenderCache Generations

Most caches expire. RenderCache expires too, but expiry is the backstop
rather than the mechanism. The mechanism is a **generation**: every piece of
data a render read has a counter in the database, the render stores the
counters it saw, and a write advances the counter for whatever it changed.
A stored representation is current when the counters it saw still match the
counters the database holds now. You write no invalidation rule for your own
data, because an ordinary `model.save()` already is one.

This chapter is about that machinery from the outside: what a render is
recorded as depending on, how coarse those dependencies really are, what the
framework cannot see and therefore cannot invalidate, how the coherence
check is paid for on a hit, which request rebuilds when several want the
same entry at once, and what a visitor is served in the window between "no
longer current" and "rebuilt". Every claim below is held down by a named
test or a checked-in measurement; the dogfood examples are routes in
`app/src/live/mod.rs` proved by `app/tests/live_render_cache.rs`.

## What a render is recorded as depending on

While a render runs, a request-scoped collector records each dependency it
can name: a table read, a record read by primary key, a query class, a
relation, a configuration identity, a feature, a locale, a route, and one
always-present `Broad` identity that every representation observes. Reads
through the ORM and the query builder record themselves; you write nothing.
A search records each index it read, and a write to that index makes the
page stale; see [Search pages in RenderCache](search.md#search-pages-in-rendercache).

`/live/todos` is the whole pattern in one handler:

```rust
pub async fn todos(_request: Request) -> Response {
    let result: Result<HttpResponse, FrameworkError> = async {
        let titles: Vec<String> = Todo::all()
            .await?
            .into_vec()
            .into_iter()
            .map(|todo| todo.title)
            .collect();
        html(&TodosView { count: titles.len(), titles })
    }
    .await;
    result.map_err(failed)
}
```

`Todo::all()` records the `todos` table. Nothing else in the handler or the
template reads the session, the signed-in visitor, or a translation, which
is what lets the route stay a shared representation at all.

## An ordinary write is the invalidation

`an_orm_write_invalidates_the_todos_document_through_generations` walks the
whole cycle through the running application:

1. The first `GET /live/todos` renders and publishes.
2. The second is a hit: it never reaches the handler, carries no `Warning`,
   and schedules nothing.
3. A `POST /todos/random` writes a row - through the application's own
   route, with the session and CSRF token a browser would send.
4. The next `GET` is served with `Warning: 110 - "Response is Stale"` and
   schedules exactly one background rebuild. Its five fresh minutes have
   barely started, so the advanced generation of the `todos` table is the
   only thing that can explain either.
5. That rebuild really runs: the test waits on the render counter - a state
   barrier, not a timed wait - until a render the test itself did not
   dispatch has happened.
6. The written row really is in the listing. This is a **separate** step and
   deliberately not an assertion about the background rebuild's own output:
   the test drops L0 first and renders again, because the rebuild's
   publication lands at a moment nothing reachable from the application
   makes observable, so asserting on whichever request happened to catch it
   would be a race.
7. And the route settles back to a plain hit against the republished entry.

No cache key was named anywhere in that sequence. An ORM write inside a
`DB::transaction` advances its generations inside that same transaction, so
a rolled-back write advances nothing at all.

## How narrow invalidation is

This is the single most important thing to know before you size a cached
route.

A primary-key point read that returns a row records that **row's** identity
and the table's **unkeyed-write** identity, not the table itself.
`Model::find`, `Model::find_or_fail`, and `Model::find_many` each observe
one record identity per row they hydrated and one unkeyed-write identity
beside them, so a row-level write elsewhere in the table leaves the entry
current, while a bulk `update_all` or `delete_all`, a `DB::table(..)` write,
or a raw statement on the table still reaches it. A point read that returns
no row observes the table instead, because inserting the missing row is what
would change the answer.

Every other read is table-granular: `Model::all`, every `Builder` terminal,
and every relation load record the whole table, so any write to that table
invalidates every cached entry that read from it. That is safe - it can only
invalidate too much, never too little - and it is measured rather than
assumed. The invalidation-storm workload in
`framework/benches/render_cache_workloads.rs` publishes 64 keys over 12
record identities, drives 1,000 writes, and records the fan-out it observed
in `crates/suprnova-live/benchmarks/render-cache-workloads-v1.json`
(abridged; the recorded object also carries the burst, sweep, hit, rebuild,
statement, and latency fields):

```json
"invalidation_storm": {
  "keys": 64,
  "identities": 12,
  "writes": 1000,
  "every_write_invalidates_every_key": false,
  "point_read_invalidation_ratio": 0.09375,
  "rebuilds_per_write": 1.28,
  "final_bodies_coherent": true
}
```

`every_write_invalidates_every_key` is `false` because a point read no longer
depends on its whole table; `point_read_invalidation_ratio` is what replaced
it as the number worth watching.

Design around it. A cached route backed by a table your application writes
to constantly will rebuild constantly, whatever its freshness window says. A
cached route backed by a table that changes when an editor publishes
something will sit still for hours. If you need finer granularity than the
table, the honest answer is that you do not have it.

## What the framework cannot see

A dependency that cannot be named cannot be invalidated, and the framework
is deliberate about which of those it declines to store and which it lets
through.

**Declined outright.** Raw SQL through `DB::select`, `DB::select_one`,
`DB::scalar`, or `DB::select_on` cannot name the tables its statement read,
so the render is marked unobservable and never stored. The response is still
served, correctly, every time.
The framework's own RBAC role and permission checks name the five tables
they read - `roles`, `permissions`, `role_has_permissions`, `model_has_roles`,
and `model_has_permissions` - so a cached route that evaluates one is observed
precisely and cached normally.
Reads through `DB::table(..)` know their table and cache normally.

**Invisible, and your responsibility.** A request header read through
`Request::header` and a `Config::get` call both change what a render
produces without the collector seeing anything. Declare the matching
variance dimension on such a route; nothing here can catch the omission for
you.

**Global scopes.** An Eloquent global scope declares what its filter
depends on. A `GlobalScope` returning `ScopeDependency::Constant` records
nothing and costs no cache hits. The default, `ScopeDependency::PerRequest`,
requires the scope's `apply` to read that state through an instrumented
accessor - `suprnova::live::current_tenant()`, `Auth::id()`,
`Lang::locale()`. A per-request scope whose evaluation reads none of them
narrows the render to `Uncacheable` and names itself in the decline, so an
invisible tenant filter costs you the cache rather than costing your
visitors each other's rows.

**Feature flags.** Every read of a flag through the framework's evaluators
observes that flag's own generation, whether the `features` table holds a
rule for it at any scope key or not. A flag the table does not hold yet
renders the default compiled into `is_enabled!`, and the first rule stored
for it changes that answer, so the read depends on it all the same.
`DatabaseEvaluator::set_flag` and `DatabaseEvaluator::reload()` make the new
value visible to readers, tell the cached evaluator which flags changed, and
only then advance each changed flag's generation, so a render that read the
old answer during the write is invalidated once the write completes.

**Translation catalogs.** A render that calls `Lang::locale()` - every
translation does - observes the catalog's generation. `Lang::reload()`, and
the per-request hot reload in `local` and `development`, advance it when a
catalog's text changed, so the pages rendered from the old text miss.
`Translator::reload` on its own advances nothing.

**The write side.** Every process whose configuration enables RenderCache and
whose database holds the RenderCache migration advances generations, so a
write made by a queue worker, a scheduled task, or a console command
invalidates exactly what the same write invalidates in the server, and
`RenderCache::bump_permission_version()` works from any of them. A process
with `RENDER_CACHE_ENABLED=false`, or one whose database does not hold the
migration, advances nothing and issues no RenderCache SQL at all. See
[RenderCache Operations](render-cache-operations.md).

## What a hit costs

The coherence check is what turns "we have bytes" into "these bytes are
current", and it is the only work a hit does.

A hit runs **no handler, no ORM query, no template, and no serializer**, and
copies no body bytes: the bytes the server writes to the socket are the
bytes the store holds, proved by address rather than by value in
`framework/tests/render_cache/bypass.rs`. What is left is the database read
that proves currency, and how often you pay for it is the policy's
`CoherenceMode`:

| Mode | SQL statements per hot hit | What it trusts |
|---|---|---|
| `Authority` (default) | exactly 1 | the ledger, reread every hit |
| `Lease { max_age_ms }` | 0 | a locally granted validation lease, until it expires |

`an_authority_mode_hit_issues_exactly_one_statement` holds authority mode to
one round trip: the observed generations and the authority epoch are read
together in a single `UNION ALL`, not as two reads.
`a_lease_mode_hit_runs_nothing_and_issues_no_statement` holds lease mode to
zero, because the epoch the key was derived under is leased alongside the
generations rather than read per request.

The epoch itself is read once per process, not once per request.
`the_epoch_is_read_once_at_first_use` measures the first miss of a fresh
runtime against an otherwise identical second one and finds the first pays
exactly one statement more - the single authority read that fills the epoch
lease. Every request after that pays nothing for it.

## When the epoch moves

`render-cache:epoch-advance` is the emergency invalidation, and the epoch is
baked into every lookup key, so what happens next depends on where you are
standing:

- **On the node that ran the command**, the very next request sees the new
  epoch. L0 is cleared outright at the same instant, and the cache is
  invalidated immediately.
- **On another node**, an `Authority`-mode route learns at its very next
  hit. A `Lease`-mode route learns at its next authority reread, which is at
  most `max_age_ms` later.

A route with a stale-servable window serves the moved entry once under
`Warning` while the rebuild runs behind the request; a route without one
rebuilds in the foreground and the requester waits for it. That difference
is the whole reason to declare a stale-servable window, and it applies to
any move, not only an epoch advance.

Three tests in `framework/tests/render_cache/middleware.rs` hold those
paths down by name:
`an_epoch_advanced_by_another_node_reaches_an_authority_mode_route_on_its_next_hit`,
`an_epoch_advanced_by_another_node_reaches_a_lease_mode_route_when_its_lease_expires`,
and
`an_epoch_advanced_by_another_node_serves_a_stale_servable_entry_once_then_rebuilds`.

## One rebuild per key: singleflight and waiters

When an entry is missing or no longer current, the requests that arrive for
it do not all render. They are admitted through a **rebuild coordinator**,
which picks exactly one of them:

- The **leader** is the one request that renders and may publish. It holds a
  lease on that key for the length of its render.
- **Waiters** are the requests that arrive for the same key while the leader
  holds it. They wait in process, and when the leader releases they
  re-evaluate what is now stored and serve that. A waiter never trusts the
  wait: if the leader's cycle failed to publish, or published something the
  waiter's own freshness check finds dead, the waiter renders too, rather
  than serving what it found.
  `a_singleflight_waiter_never_serves_a_superseded_entry_as_fresh` in
  `framework/tests/render_cache/middleware.rs` is that rule.
- A request that arrives once `RENDER_CACHE_MAX_WAITERS` (default 128) are
  already waiting **bypasses**: it renders and publishes nothing, rather
  than growing an unbounded queue.

`concurrent_misses_render_once_and_waiters_reuse_the_publication` proves the
ordinary case end to end - two concurrent misses, one render, identical
bodies - and `one_leader_per_key_and_fence_with_bounded_waiters` in
`crates/suprnova-live/tests/render_cache_singleflight.rs` proves the cap
directly against the coordinator: past its waiter limit, admission answers
`Bypass`.

Two publications for one key can never both be accepted, whatever the
coordinator decided. A leader mints a publication token under its lease, and
the store compares that fence before it writes: an older epoch, or an equal
epoch with a lower token, loses. That is what makes duplicate *rendering*
safe to accept while duplicate *publishing* is not, and it is why there is
no cross-node waiting at all - a key another node is rebuilding is a bypass
here. See [RenderCache Deployment](render-cache-deployment.md).

## Serving something while it is rebuilt

The four freshness states, the bands `FreshnessPolicy` sets, and the
`Warning` and `Age` a stale response carries are defined in
[RenderCache Representations](render-cache-representations.md). What matters
here is that a generation move puts an entry into those bands early: a
moved entry is evaluated at an effective age of **at least** its fresh
interval, whatever its real age. Its real age still decides which band that
lands it in:

- Real age below `fresh_ms + stale_servable_ms`, on a route that declares a
  stale-servable window: stale-servable. The stored copy is served once
  under `Warning` and the rebuild runs behind the request. That is step 4 of
  the write test above, on an entry whose five fresh minutes had barely
  started.
- Real age past that, but not yet at the dead edge: stale-on-error. The
  request waits for a foreground rebuild and sees the stored copy only if
  that rebuild fails.
- On a route with no stale-servable window at all, and on every
  `PrivateCached` route (whose dead edge *is* its fresh edge), a move is
  Dead: the request rebuilds in the foreground and waits.

`stale_service_is_marked_and_rebuilt_in_the_background` shows the same
handoff driven by the clock rather than by a write: past `/live/todos`'s
300,000 fresh milliseconds and inside its 60,000 stale-servable ones, the
visitor is handed the copy on hand under `Warning: 110 - "Response is
Stale"` and `Age: 300`, exactly one rebuild is scheduled, and that rebuild
really runs.

A node bounds the rebuilds it runs behind requests. A key whose rebuild is
already running starts no second one, and the node runs at most
`RENDER_CACHE_MAX_BACKGROUND_REFRESHES` of them at once across all keys. The
default is 32 for every CPU the process can use. Past that limit a
stale-servable hit still gets the stored copy at once and starts nothing. A
later hit starts the rebuild once a running one finishes, and an entry that
goes Dead first is rebuilt in the foreground. Zero turns these background
rebuilds off. In `framework/tests/render_cache/middleware.rs`,
`stale_hits_during_a_running_background_refresh_start_no_more_refreshes`
proves the first rule, and
`stale_hits_past_the_background_refresh_limit_serve_stale_and_start_nothing`
proves the second.

The stale-on-error fallback covers the request that leads a rebuild **and** a
waiter behind a leader whose rebuild failed. Both are answered the same way:
the stale bytes under `Warning`, rather than the failure.
`framework/tests/render_cache/races.rs` proves each arm separately -
`a_waiter_behind_a_failed_leader_is_served_the_stale_entry_it_was_waiting_on`
and `a_waiter_that_re_evaluates_onto_a_stale_on_error_entry_falls_back_to_it` -
and the second one by revert: dropping the fallback from the waiting arm
turns its final assertions from `200` into `500`.

Stitched routes are the exception, and it is a deliberate one. A `Composite`
entry is never served by the stale-on-error fallback and never triggers a
background rebuild: serving a stored shell after a failed rebuild would
answer a request the route's own authorization chain never got to gate, and
a background rebuild carries none of the request's authorization state, so
its shell would be whatever the page renders for nobody. On a stitched
route, a failed rebuild's own outcome is what the client sees.

## Cached routes are read paths

The leader's render runs inside a database transaction, opened at
`REPEATABLE READ` on PostgreSQL and MySQL, so the generations it records and
the data it read share one snapshot. Two consequences follow.

A cached route's handler that **writes** competes with concurrent writers
for the same rows, and on PostgreSQL a handler that updates a row another
transaction changed after the render began sees a serialization failure.
Design cached routes as read paths.

A write made outside any transaction - `model.save()` on its own - commits
its row first and advances its generations in an immediately following
transaction. The moment between the two is "new data, old generation": it
costs one extra rebuild and never serves stale content.

Finally, after the render finishes, the observed dependencies and the epoch
are read again, outside the render's own transactional view. Anything that
moved during the render discards the candidate rather than publishing it.
That is why a write landing mid-render costs a rebuild instead of a wrong
page.

### Why Suprnova diverges

Laravel's cache is a key-value store and its response-caching packages are
built on top of it, so invalidation is something you write. You call
`Cache::forget`, or you tag entries and flush a tag, or you register a model
observer that clears the keys you believe that model feeds. Every one of
those is a mapping you maintain by hand, and the failure mode is silent: the
page that nobody remembered to forget keeps serving until its TTL runs out.

Suprnova inverts the direction. The render records what it read, the write
advances what it changed, and the two meet in a database ledger rather than
in your head. There is no `forget` call to forget. The price is that the
recorded dependency is a table rather than a row, so a busy table rebuilds
its dependents often, and that reads through raw SQL are declined from
storage rather than cached with a dependency nobody can name. Both of those
are visible and measured - the fan-out in the checked-in storm workload, the
decline in your own missing `Age` header - rather than a stale page you find
out about from a customer.

## Next

- [RenderCache Deployment](render-cache-deployment.md) - profiles,
  providers, and the migration that makes generation truth durable
- [RenderCache Representations](render-cache-representations.md) - what is
  actually stored, and under what key
- [Database](database.md) - transactions and isolation, which cached renders
  run inside


---

<!-- /docs/render-cache-deployment -->

# RenderCache Deployment

One process caching for itself needs nothing but memory. Several processes
behind a load balancer need to agree on what is stored, on who is allowed to
rebuild an entry, and on when something stopped being true - and they need
to agree without any of them being able to convince the others that stale
content is current. RenderCache answers that with **profiles**: a profile
names which providers a process builds, and nothing else changes. Route
declarations, policies, keys, the collector, the middleware flow, and
stitching are identical at every profile, and no application-facing type
differs between them.

This chapter is how you choose and wire one. The three profiles and what
each provides, the environment variables the framework config actually
reads, the migration your application has to list before a shared profile
will boot, where the install goes in your bootstrap, and what the tiers do
and do not promise. The dogfood application in this repository runs the
embedded profile by default and is booted on the Database profile by
`the_database_profile_serves_a_hit_through_the_sql_stores` in
`app/tests/live_render_cache.rs`.

## Three profiles

| Profile | L1 entries | Rebuild leadership | Live instance records |
|---|---|---|---|
| `embedded` (default) | one file per key, or none | in process | in process |
| `database` | `suprnova_render_entries` | `suprnova_render_leases` | `suprnova_live_instances`, `suprnova_live_promotions` |
| `redis` | one Redis hash per key | one Redis hash per key, plus a token counter | one Redis hash per record |

The thing that does **not** move between them is generation truth. The
database-backed generation ledger is the authority at every profile:
whichever tier handed over the bytes, currency is proved against the
database - by rereading it on the hit under `CoherenceMode::Authority`, or
by a validation lease granted from an earlier read of it under
`CoherenceMode::Lease`. That is what keeps an accelerator an accelerator:
Redis can lose everything it holds without anything stale being proven
current, because nothing Redis holds proves currency in the first place.

Choose by what you actually need to share:

- **`embedded`** for a single process, and for several processes that are
  happy to each keep their own copy. Set `RENDER_CACHE_L1_DIR` and each
  process gains a file tier that survives its own restart.
- **`database`** when several nodes should share stored entries and elect
  one rebuild leader per key, and you would rather not add another moving
  part to the deployment.
- **`redis`** when the shared tier's latency matters more than its
  durability, with the database still holding generation truth underneath.

## The environment variables

`RenderCacheConfig::from_env` reads these, in
`framework/src/render_cache/config.rs`:

| Variable | Default | Meaning |
|---|---|---|
| `RENDER_CACHE_ENABLED` | `true` | anything but `false` or `0`; `false` makes `RenderCache::install` a no-op |
| `RENDER_CACHE_PROFILE` | `embedded` | `embedded`, `database`, or `redis`; sets the two rows below |
| `RENDER_CACHE_L1` | the profile's | `disabled`, `file`, `database`, or `redis` |
| `RENDER_CACHE_COORDINATOR` | the profile's | `local`, `database`, or `redis` |
| `RENDER_CACHE_L0_ENTRIES` | 4,096 | in-process entry ceiling |
| `RENDER_CACHE_L0_BYTES` | 128 MiB | in-process byte ceiling |
| `RENDER_CACHE_L1_DIR` | unset | the file tier's directory; under `embedded`, setting it is what turns L1 on |
| `RENDER_CACHE_L1_BYTES` | 1 GiB | the whole directory for the file tier, one entry for the database and Redis tiers |
| `RENDER_CACHE_REDIS_URL` | `REDIS_URL`, then `redis://127.0.0.1:6379` | where both Redis cache tiers connect |
| `RENDER_CACHE_REDIS_PREFIX` | `suprnova_render:` | the key namespace both Redis cache tiers write under |
| `RENDER_CACHE_LEASE_MS` | 30,000 | rebuild lease lifetime |
| `RENDER_CACHE_MAX_WAITERS` | 128 | in-process waiter ceiling |
| `RENDER_CACHE_MAX_BACKGROUND_REFRESHES` | 32 per CPU | most keys one node refreshes behind requests at once; `0` turns background refresh off |
| `RENDER_CACHE_HINTS` | the profile's | `disabled` or `redis`; credible generation hints on `<prefix>hints`, over the endpoint above |
| `RENDER_CACHE_FAILURE` | `open` | `open` serves the route uncached on a provider failure, `closed` answers `503` |
| `APP_BUILD_ID` | the application's package version (see below) | namespaces every entry to the build that produced it |

`RENDER_CACHE_HINTS` is the one knob here that changes no answer. It defaults
to `redis` under the `redis` profile and to `disabled` under the other two,
and it has no endpoint of its own - it rides the `RENDER_CACHE_REDIS_URL` and
`RENDER_CACHE_REDIS_PREFIX` above. A hint can only shorten a validation lease
a node already holds, so a deployment with it off, one whose channel is dead,
and one built without the feature all serve the same entries and admit the
same rebuilds; only the moment of revalidation differs. That is also why an
unreachable hint endpoint does not stop the boot the way an unreachable cache
tier does.

The profile is a shorthand, not a lock. `RENDER_CACHE_L1` and
`RENDER_CACHE_COORDINATOR` each override their own half, so a deployment
that wants its entries in the database but its rebuild leases in process
says exactly that rather than picking the nearest whole profile.

A variable with a closed set of accepted values that is set to something
outside it fails the boot with a message naming the variable. The rejected
value is never repeated in that message, because an environment value can
carry a secret.

**Set `APP_BUILD_ID` explicitly, once per deploy.** It is mixed into every
lookup key, so changing it is what stops a new build from serving entries
the previous one published. Absent the variable, `RenderCacheConfig::from_env`
takes your application's own package version: `#[suprnova::main]` records
`CARGO_PKG_VERSION` from the application crate's own compilation the moment
it loads the environment, and that recorded value is what the default falls
back to here. Only a binary that never expands `#[suprnova::main]` falls
back further, to this **framework** crate's own version - named as such
because it is otherwise easy to mistake for the application's. Either way
the value moves only when someone bumps a version number, and a package
version rarely changes per deploy: a deploy that changes a template, a
translation, or a handler without a version bump keeps the same build id and
can serve entries the previous build published. Set it to something that
changes every time you ship - a commit id or a release identifier:

```bash
APP_BUILD_ID=$(git rev-parse --short HEAD)
```

An install that never reads the environment sets the same value in code
with `RenderCacheConfig::with_build_id`, which overrides whatever
`from_env` chose - explicit `APP_BUILD_ID` included - for an application
that derives its own per-deploy identifier programmatically.

Whichever value you set, the production binary that reads it is expected
to be built in Suprnova's [production build shape](deployment.md#production-build-shape) -
default features off, `testing` reserved for `cargo test` alone.

Live's own instance ledger is configured separately, because it is Live's
authority rather than the cache's storage: `LIVE_LEDGER_DRIVER` (`memory`,
`database`, or `redis`), `LIVE_REDIS_URL`, and `LIVE_REDIS_PREFIX`. A
deployment may run the cache on one tier and the ledger on another.

## The migration your application must list

RenderCache's schema is framework-owned and application-applied. Your
`Migrator` lists it, so `suprnova migrate` provisions the tables alongside
your own:

```rust
Box::new(suprnova::render_cache::migration::Migration),
Box::new(suprnova::render_cache::migration::TierMigration),
```

That is `app/src/migrations/mod.rs` verbatim, and the two are not
interchangeable:

- **`Migration`** creates the three `suprnova_render_*` tables that hold
  durable generation truth: current generations, an append-only change log,
  and the authority epoch. Every profile needs it, including `embedded`,
  because generation truth never moves into a cache tier.
- **`TierMigration`** creates the four tables the database L1 store and the
  database rebuild coordinator read. Only a profile that reaches them needs
  it - but `RenderCache::install` refuses to boot the Database profile
  without them, so listing it is what makes `RENDER_CACHE_PROFILE=database`
  a configuration choice your application can actually make.

An application that sets `RENDER_CACHE_ENABLED=false` need not carry either:
the install returns the router untouched, probes nothing, assembles no
runtime, registers no middleware, and leaves the write side uninstrumented,
so nothing pays for a cache that is off.

## Installing it

`RenderCache::install` is asynchronous, because it probes for the tables and
pings every distinct Redis endpoint the configuration would use before it
assembles anything. `Application::try_routes_async` is the hook that hosts
it. This is `app/src/live/mod.rs`, and the split into two functions is worth
copying:

```rust
/// [`routes`] followed by the RenderCache middleware. This is the entry
/// point every server in this application uses.
pub async fn routes_with_render_cache(router: Router) -> Result<Router, FrameworkError> {
    routes_with_render_cache_with_config(router, RenderCacheConfig::from_env()?).await
}

#[doc(hidden)]
pub async fn routes_with_render_cache_with_config(
    router: Router,
    config: RenderCacheConfig,
) -> Result<Router, FrameworkError> {
    RenderCache::install(routes(router)?, config).await
}
```

`routes` is the synchronous inner half: it registers the reserved Live
routes, the document routes, and every cache policy, and installs no
middleware. `cmd/main.rs` reaches `routes_with_render_cache` through
`Application::try_routes_async`, and the browser scenario's server in
`app/examples/live_dogfood_host.rs` awaits it directly.

The configuration seam underneath it is not decoration. A test that needs a
different profile or a clock it can move has no other way in, and it matters
that it installs *the same* routes, policies, and middleware ordering the
server does, differing only in the configuration it passed. Both dogfood
boots go through it: `the_database_profile_serves_a_hit_through_the_sql_stores`
passes a Database-profile configuration, and
`stale_service_is_marked_and_rebuilt_in_the_background` passes one carrying
an adjustable clock. See "Testing a cached route" in
[RenderCache Operations](render-cache-operations.md).

Two ordering rules, both the caller's responsibility:

1. Every route and group must be opted in **before** `install`, which reads
   whatever has been registered by that point.
2. `install` appends to the global middleware chain, so it must run **after**
   the session, locale, and identity middleware whose request-scoped state
   the cache middleware reads while deriving a lookup key.

The install fails closed, through two probes. It checks that the tables the
configuration would reach exist, and it pings every distinct Redis endpoint
the configuration would use, once per endpoint. Either failing stops the
boot with one actionable sentence naming the migration or the variable to
fix, so nothing is ever served against a missing table or an endpoint
nothing answers. (Live's own instance ledger is probed separately, by
`Server::run`, before any request is served.)

## Choosing where a route's entries live

The profile decides what L1 *is*; the policy decides which routes use it.
The builder stores in L0 only unless a route declares otherwise, so a shared
tier is populated on purpose:

```rust
RenderCachePolicy::builder(RepresentationClass::PublicShared)
    .freshness(FreshnessPolicy::new(300_000, 60_000, 300_000)?)
    .layers(StorageLayers::l0_and_l1())
    .build()?
```

`the_database_profile_serves_a_hit_through_the_sql_stores` proves the round
trip end to end on the Database profile: the published entry is read back
out of the SQL store under the key the middleware derived, then L0 is
emptied and the next request is still answered without a render. See
[RenderCache Representations](render-cache-representations.md) for how to
decide per route.

## One conformance suite, every provider

Every store answers the same suite.
`framework/tests/render_cache/store_conformance.rs` runs the engine's
provider scenarios - written against the `RenderStore`
trait alone - over the file-backed L1, the SQL L1 on SQLite, PostgreSQL, and
MySQL, and the Redis L1, and the in-process store answers the same suite in
the engine crate. PostgreSQL, MySQL, and Redis run through ignored tests
that `scripts/check-postgres.sh`, `scripts/check-mysql.sh`, and
`scripts/check-redis.sh` select by name against real servers. A provider is
not "supported" here because it exists; it is supported because it passes
the same words as every other one.

## What the tiers promise, and what they do not

- **No cross-node waiting.** A key another node is already rebuilding is a
  bypass: this node renders and publishes nothing. Bounded duplicate
  computation across nodes is accepted; two accepted publications are not,
  and the store's own publication fence is what forbids the second.
- **A lost backend is a miss, never a wrong answer.** Eviction, expiry, or a
  Redis restart makes entries miss and instances missing. The coherence
  check against the database generation ledger runs on every hit whatever
  served the bytes.
- **Tampered bytes are a miss.** Entry bytes in a row or a hash are a signed
  codec frame, so a torn, truncated, or altered value fails its integrity
  check and is treated as a miss rather than served.
- **The database and Redis tiers do not evict to make room.**
  `RENDER_CACHE_L1_BYTES` bounds one entry there, not the table or the
  keyspace; growth is bounded by retention instead. Only the file tier
  bounds a whole directory, because it owns that directory alone.
- **The Redis adapters target a single Redis 7 or newer instance.** Redis
  Cluster is refused: the scripts touch keys they do not declare, and they
  read the store clock with `TIME` inside a script.
- **MySQL needs 8.0.19 or newer** for precise duplicate-key classification.
  Older MySQL and MariaDB report a collision this build will not attribute
  to a table, so it degrades to a provider-unavailable error - the safe
  direction, and nothing is granted twice either way.
- **Every cross-node expiry decision is made on the backend's clock**, read
  inside the operation that acts on it. A node whose clock runs fast can
  neither extend a lease, nor hide a live entry from its peers, nor declare
  a peer's record elapsed.

### Why Suprnova diverges

Laravel's response-caching packages inherit the cache store you already
configured, so "deploying the cache across several nodes" means pointing
`CACHE_STORE` at Redis and trusting that whatever is in there is right.
There is no separate notion of who may rebuild an entry, no fence that stops
two workers publishing conflicting bytes for the same key, and - most
consequentially - no authority underneath the store. If Redis holds a page,
the page is served; if Redis is flushed, everything is recomputed. The store
*is* the truth.

Suprnova splits the two apart deliberately. The shared tier holds bytes and
nothing else; the database holds generation truth at every profile, and it
is what a hit is checked against. That is why losing Redis here costs
latency rather than correctness, why a rebuild is leased and a publication
is fenced rather than raced, and why the same route declarations run
unchanged from `cargo run` on a laptop to a database-coordinated fleet. The
cost is a migration your application has to list and a database read on the
hit path that a plain key-value cache does not pay - one statement, or zero
under a validation lease. See
[RenderCache Generations](render-cache-generations.md) for what that read
buys.

## Next

- [RenderCache Operations](render-cache-operations.md) - the console
  commands, telemetry, disk hygiene, and what to do when something is wrong
- [Deployment](deployment.md) - the surrounding production checklist
- [Migrations](migrations.md) - how the `Migrator` list above is applied


---

<!-- /docs/render-cache-operations -->

# RenderCache Operations

A cache you cannot see is a cache you cannot trust. RenderCache answers two
operator questions directly and without ever printing a stored page: **what
is this node holding under this key, and is it still current?** and **how do
I make everything stop?** It answers a third - "is this route being served
from a stored copy at all?" - through telemetry and through the `Age` header
rather than through a command, because that question is about traffic rather
than about one entry. There are two console commands, nine telemetry
counters, one bounded disk sweep, and one emergency lever.

This chapter is the operating surface: the commands, exactly what they print
and what they can see; the counters and their closed outcome sets; how the
file tier reclaims disk; how to test a cached route so the test proves
caching rather than merely responding; what to do when something is wrong,
including the multi-node procedure a database restore needs; and how the
cache's own performance is measured and what those numbers are honestly
worth. The command examples are the ones
`the_operator_commands_inspect_without_a_body_and_advance_the_epoch` drives
through this repository's own console entry point in
`app/tests/live_render_cache.rs`.

## The two console commands

Both are hidden commands, registered by the framework and reachable through
your project's `console` binary like any other. Neither ever prints a stored
body or a raw dependency identity.

```bash
cargo run --bin console -- render-cache:inspect rk1.<43 base64url characters>
cargo run --bin console -- render-cache:epoch-advance
```

**`render-cache:inspect <key>`** reports one stored entry's shape: its
representation class, its `body_bytes`, its other metadata, and the current
authority epoch beside it, so you can tell whether the entry you are looking
at is still live authority or has already aged out from underneath. It
prints `no entry (current epoch: {epoch})` when the key names nothing it can
see, and it fails - it does not report success - on an unparseable key or
with no runtime installed.

**It reads this process's in-process L0 and nothing else.**
`RenderCache::inspect` looks the key up in L0 alone; it never consults the
L1 tier. On the Database
or Redis profile that matters: an entry that is live in
`suprnova_render_entries` or in Redis, published by another node or by this
one before a restart, prints `no entry` here unless this process has served
it since it started. Read the report as "what this node has in memory",
never as "what the deployment has stored". The same is true of
`RenderCache::store_inspection`, which reports L0 occupancy and the current
epoch.

The key is the text the lookup itself uses: `rk1.` plus 43 base64url
characters, which is what your application's logging and telemetry can
surface. It is not a second hash of anything, so a key an operator holds
names exactly one entry.

That body-free claim is checked, not merely stated. The test takes the
document that was actually served, splits it into lines, and requires that
**every** non-trivial line of it is absent from what the inspect report
printed.

**`render-cache:epoch-advance`** is the emergency invalidation. It advances
the authority epoch and prints `epoch advanced to {epoch}`. Because the
epoch is baked into every lookup key, this puts stored entries out of reach
with nothing to enumerate and nothing to delete. The test asserts the
printed line and then the consequence that matters: after the command, the
route renders again.

**On the node that runs it**, the effect is immediate: the command drops
that process's epoch lease and clears its in-process tier, so its very next
request derives keys under the new epoch and finds nothing. (That last
clause holds while the epoch only moves forward, which is the ordinary case;
after a database restore the advanced value may be one the deployment has
used before, so see "Restoring the database" below.) **On any other
node**, the ledger has moved but that process still holds its old leased
epoch and its own L0, and it catches up at its next authority read -
immediately under `CoherenceMode::Authority`, and up to `max_age_ms` later
under `CoherenceMode::Lease`. Run the command on each node, or restart the
others. "Restoring the database" below has the full procedure and the tests
behind it.

Reach for it when something is wrong with cached content and you cannot wait
for individual entries to expire, and after a job that changed what cached
pages show (see "known gaps" in
[RenderCache Generations](render-cache-generations.md)).

## Permission changes

`RenderCache::bump_permission_version().await?` is the one invalidation call
an application makes by hand, and it is not really an operations command -
it belongs in the code path that changes what a signed-in user is allowed to
do. It advances a persisted generation that every principal-keyed render
observes, it survives a restart, and it joins the transaction the role
change runs in when there is one. Without it, a user whose permissions just
changed keeps matching whatever was cached under their prior permission set.

## Telemetry

Nine closed counter names, and nothing in any of them names a tier, a
provider, or a backend:

| Counter | Attribute |
|---|---|
| `suprnova.render_cache.lookups` | `outcome`, and `reason` when `outcome="declined"` |
| `suprnova.render_cache.hits` | `outcome` |
| `suprnova.render_cache.publications` | none |
| `suprnova.render_cache.rebuilds` | none |
| `suprnova.render_cache.stitch.assemblies` | `outcome` |
| `suprnova.render_cache.stitch.slots` | `outcome` |
| `suprnova.render_cache.stitch.nested` | `outcome`, `cause` |
| `suprnova.render_cache.hints` | `outcome` |
| `suprnova.render_cache.epoch_rewinds` | none |

`lookups` and `hits` carry the same closed set of eight outcomes:

- `l0`, `l1` - a fresh entry served from the in-process or the shared tier.
- `conditional` - a fresh hit whose `If-None-Match` matched, answered `304`.
- `stale` - a stale-servable entry served immediately, or the stale-on-error
  fallback after a foreground rebuild failed.
- `miss` - nothing found, a stale-on-error rebuild in progress, or a dead
  entry.
- `bypass` - an undeclared query parameter, an unresolvable declared
  variance dimension, or an exhausted waiter list.
- `moved` - the reread after rendering found a dependency or the epoch had
  changed; the candidate was discarded, never published.
- `declined` - the render was not storable, for one of the forty-seven
  reasons below, carried in the `reason` attribute beside `outcome`.
  `reason` is emitted only alongside `outcome="declined"`; every other
  outcome carries none. The reason is computed from a typed value at the
  exact branch that declined, never reconstructed from the response
  afterwards, so it names the contract that actually refused the render:

  - Eligibility (`policy.eligibility`, mirroring the engine's own
    `DeclineReason`): `policy_uncacheable`, `method`, `status`,
    `streaming`, `sets_cookie`, `unsafe_header_name`, `no_store_directive`.
  - Observation (the collector's report and the in-transaction ledger
    read): `observation_overflowed`, `ledger_read_failed`,
    `handler_not_begun`, `foreign_connection_read`, `snapshot_unavailable`.
  - Classification narrowed to `Uncacheable`: `session_value_read`,
    `secret_context_read`, `undeclared_context`.
  - Search (see [Search pages in RenderCache](search.md#search-pages-in-rendercache)):
    `viewer_scoped_search`, `analytics_search`, `search_opt_out`.
  - Cacheable Inertia facts outside their registered stitched route:
    `inertia_without_registered_stitching`.
  - Live document facts: `identity_bound_without_stitching`,
    `invalid_stitch_capture`, `no_store_intent`,
    `unresolvable_seed_deadline`.
  - Invariants over the key (whether the render's own observations agree
    with the values the lookup key was already built from):
    `unreasoned_private_class`, `principal_undeclared`,
    `principal_divergent`, `tenant_undeclared`, `tenant_divergent`,
    `locale_undeclared`, `locale_divergent`.
  - Publication: `seed_deadline_elapsed`, `unsafe_header_value`,
    `nonce_source_policy`, `vary_undeclared`, `head_render`,
    `composite_capture_invalid`,
    `composite_slot_count_mismatch`,
    `composite_too_many_slots`, `composite_digest_mismatch`,
    `composite_empty_slot`, `composite_slot_not_found`,
    `composite_slot_ambiguous`, `composite_nested_unauthorizable`,
    `composite_nested_wider_class`, `composite_nested_longer_freshness`,
    `composite_nested_depth_exceeded`, `composite_nested_cycle`,
    `composite_nested_unresolvable`.

`hits` increments only for `l0`, `l1`, `conditional`, and `stale`.
`publications` counts only a store answering "published", never a fenced or
rejected attempt. `rebuilds` counts one per spawned background rebuild.
A node runs at most one background rebuild per key at a time: a stale hit on
a key whose rebuild is still running serves the stale copy and spawns
nothing. A background rebuild renders only when the coordinator makes it the
key's leader, so a rebuild another node is already running costs this node
no handler run.

The two island-stitch counters carry their own sets: `assembled` and
`fail_document` for assemblies; `rendered`, `omitted`, `fallback`, and
`failed` for slots.

`suprnova.render_cache.stitch.nested` distinguishes a named inner cached
segment's own outcome from an island slot's, one increment per
`Segment::Nested` resolution attempt. Its `outcome` attribute takes exactly
one of `resolved`, `omitted`, `fallback`, and `failed`; its `cause`
attribute takes exactly one of `none` (used only when `outcome="resolved"`),
`fetch_failed`, `version_mismatch`, `length_mismatch`, `depth_exceeded`,
`cycle`, and `unauthorized`. Neither attribute ever carries a key, a route
name, or an identity digest. A failed or degraded segment always resolves
through the policy the including graph declared for it
(`FailDocument`/`Omit`/`Fallback`), exactly as an island slot's own failure
does; `outcome="failed"` (from a `FailDocument` policy) abandons assembly
for the whole document and falls through to the route's own uncached
handler.

`epoch_rewinds` counts detections, not entries: one increment each time a
node meets an entry or a leased epoch stamped above the authority's own,
lifts the ledger's epoch past that stamp, and clears its own L0. A non-zero
value after a database restore is the signal that the restore was noticed. A
non-zero value at any other time means an authority moved backwards for a
reason nobody intended.

`hints` counts credible generation hints this node handled on the Tier 2
pub/sub channel: one increment per message received, one per subscription
ending, and one per announcement a full publish queue kept this node from
sending. It is the one counter here a deployment can leave permanently at
zero by choice: hints are off unless the Redis profile, or
`RENDER_CACHE_HINTS=redis`, turns them on, and a node with them off serves
exactly what a node with them on serves. Its `outcome` attribute takes
exactly one of `applied` (the message named a digest a validation lease on
this node observes, and every such lease was shortened),
`ignored_unknown_key` (it named nothing this node holds a lease against,
which includes a message this node cannot read at all), `dropped_over_bound`
(it carried more than 64 digests, or more bytes than 64 digests take, and
was dropped whole rather than truncated, because a truncated hint is a
silently wrong hint; an oversized payload is dropped before it is copied or
queued),
`subscriber_dropped` (this node's subscription ended, because it fell behind
or the connection failed, and is being re-established), and
`dropped_publish_queue_full` (this node had an advance to announce and its
own publish queue was full, so the message was dropped rather than made to
wait on the write that produced it, one count for every message that went
unannounced). No attribute ever carries a route, a key, or a dependency
identity.

A hint can only shorten a validation lease this node already holds. It can
never extend one, create one, or stand in for the generation ledger, and
every hit still reads that ledger. So a rising `subscriber_dropped` means
this node is revalidating later than it could - at worst as late as the
lease's own `max_age_ms`, which is the staleness bound the route already
declared - and never that anything is being served that the coherence check
would have refused.

**A high `declined` rate is the signal worth alerting on.** It means routes
you opted in are rendering and serving correctly while never being stored,
and the response looks identical either way. The fastest local check is two
requests in a row: if the second carries no `Age` header, nothing was
stored.

## Disk hygiene

Only the file tier needs sweeping, and it mostly sweeps itself.

`FileRenderStore` stores one file per key, flat under `RENDER_CACHE_L1_DIR`.
An entry is dead when its age since publication reaches the retention it was
published with, or when its fence epoch is older than the current epoch.
Retention comes from the same class-aware dead edge the live freshness check
uses, so a private entry's file is retired earlier than a public one's and a
sweep can never disagree with a freshness check about whether an entry is
truly dead.

`sweep` removes at most 64 entries per call, and returns whether more
remain. It takes entries whose retention has run out, in the order it ran
out, then entries from an older epoch, and it finds them through indexes
kept in that order, so the work of one call does not grow with the number
of live entries in the directory. It runs automatically on every 256th
publication, so a healthy directory needs no attention. `RenderCache::sweep()`
drives it explicitly when you want to, and a backlog larger than one call's
limit drains across later triggers rather than blocking on one long scan.

Two things the sweep is not:

- **An epoch advance does not touch L1.** It clears L0 outright, because
  that is in-process memory with nothing to reconcile against, and leaves
  every pre-epoch file on disk until a sweep reclaims it. That is disk
  hygiene, not a correctness concern - the files are already unreachable by
  lookup.
- **The database tier has no automatic sweep**, and is reclaimed only
  through `RenderCache::sweep()`. The Redis tier needs none: every entry it
  stores carries an expiry and Redis reclaims the bytes itself.

Publication is crash-safe. It writes a temporary file, fsyncs it, renames it
over the target, and fsyncs the parent directory, so a reader only ever sees
the previous complete file or the new complete file. On open, the store
removes any leftover temporary file and any file that fails its frame check,
treating a torn write as self-healing rather than a permanently poisoned
entry.

## Testing a cached route

A test that asserts a cached route responds correctly passes whether the
response came out of the store or out of a fresh render. Every claim has to
be made against something only a stored entry actually being served can
produce. Four patterns do that, and this repository's own dogfood tests make
all four claims: `app/tests/live_render_cache.rs` with the harness in
`app/tests/live_support/mod.rs`.

**1. Count renders on the handler side of the cache.** Register a counting
middleware *after* `RenderCache::install`. Registration appends, so it lands
closer to the handler than `RenderCacheMiddleware`, and a request the cache
answers returns before calling it:

```rust
let router = app::live::routes_with_render_cache_with_config(routes::register(), config)
    .await
    .expect("install the routes and the RenderCache middleware");
// After the install, so it only sees requests the cache forwarded.
render_counter::register();
```

The difference between two readings of `render_counter::renders()` is then
the number of renders the cache did not avoid, and nothing else - unlike
identical bodies or an `Age` header, both of which have honest non-cache
explanations. Every hit assertion in
`an_orm_write_invalidates_the_todos_document_through_generations` rests on
it. Wait for a render you did not dispatch (a background rebuild) with the
counter's own barrier, `wait_until_renders_at_least`, never with a sleep.

**The exception is a `PublicShellStitched` route, and it is not a small
one.** A stitched hit is deliberately forwarded through the route's whole
chain - its authorization guard has to run again, and only the Live
completion middleware at the end of that chain serves the hit. A counting
middleware registered globally after the install sits outside the route's
own chain, so it is reached on a stitched hit exactly as on a miss. On such
a route the counter cannot carry the "no handler ran" claim at all.

Assert instead on what the store holds, what the served document is made of,
and how old it is - which is what
`the_dashboard_is_stitched_per_principal_from_one_shared_shell` does: the
stored entry is `EntryKind::Composite` with the expected slot count
(read with the probe's `l0()`), two principals' documents differ in their island
tags and nowhere else, and the second principal's response reports an `Age`
of the whole seconds that have passed since the shell was published.

That last one is the proof the test turns on, and it is the local proof of
store service in its exact form. The `Age` header on its own is the weak
signal this chapter warned about above, because a render sets one too - at
zero. The number is not weak: a render publishes its response and its entry
at the same instant, so a rendered response reports zero however far the
clock has moved, while an assembly reports the age of the shell it was
assembled from. The test drives an adjustable clock, well inside the route's
fresh window, so what it reads is exact rather than incidental.

The response also carries `Cache-Control: private, no-store`, but read that
for what it is: the directive a slotted route in this class carries, pinned
on the render that publishes the shell as much as on every assembly after
it, because it follows what the bytes hold and not which path produced them.
Slotted is the operative word: a zero-slot `Composite` is sent
`private, no-cache` instead, so the directive says something about a route
with islands in it and nothing about one without. That test asserts
`renders() == before + 1` on a hit, and says in its own note why that is the
honest reading rather than a failure.

**2. Read the entry back.** Two facade calls are ordinary public API:
`RenderCache::store_inspection()` reports L0 occupancy, bytes, and the
current epoch, and `RenderCache::inspect(key_text)` reports one entry's
body-free metadata. To find the entry of one route, use
`suprnova::render_cache::testing::RenderCacheProbe`:

| Call | What it gives a test |
|---|---|
| `RenderCacheProbe::route(pattern)` | a probe for the route registered under `pattern`, written as the router holds it (`/posts/{id}`, not `/posts/1`) |
| `.params(&[("id", "1")])` | the route parameters of the request, as name and value pairs |
| `.at_epoch(epoch)` | the epoch to derive the key under; without it the probe uses epoch 1, the value the migration seeds |
| `.key()` | the key text the middleware derives, the text `RenderCache::inspect` and `render-cache:inspect` take |
| `.l0().await` | the entry L0 holds under that key: class, kind, status, `body_bytes`, slots |
| `.l1().await` | the same, out of the configured L1 tier |
| `RenderCacheProbe::clear_l0()` | empties L0 and leaves L1, the epoch, and the coordinator alone |

`key()` returns `Result<String, FrameworkError>`, `l0()` and `l1()` return
`Result<Option<EntryInspection>, FrameworkError>`, and `clear_l0()` returns
`Result<(), FrameworkError>`. None of them panics. Each error names the route
pattern and what went wrong: no runtime installed, no policy covering the
route, a key that cannot be derived, no L1 tier configured, a failed L1 read,
an entry that does not decode. An error never carries a login, a parameter
value, or a key.

```rust
use suprnova::render_cache::testing::RenderCacheProbe;

// After the request to /posts/1 has been served:
let probe = RenderCacheProbe::route("/posts/{id}").params(&[("id", "1")]);
assert!(probe.l0().await?.is_some(), "the request published the page");

// Prove that the next request comes out of L1 and not out of memory.
RenderCacheProbe::clear_l0()?;
assert!(probe.l0().await?.is_none());
assert!(probe.l1().await?.is_some());
```

The probe builds the key with the function the middleware builds its own
with, so an entry it finds is the entry the request is served from. That has
one consequence you must act on: **tell the probe each dimension the route's
policy varies on.** A key derived without them is a key nothing was stored
under, so the probe reads `None` whether or not the page was cached. A test
that proves nothing looks the same as a test that proves a miss.

| The policy varies on | Tell the probe | Left out |
|---|---|---|
| `Principal` | `.login(id)`, the identifier `get_auth_identifier` returns for the user | the key of an anonymous request |
| `Tenant` | `.tenant(id)`, the identifier the tenant middleware set | the key of a request with no tenant |
| `Locale` | `.locale(tag)`, written as `Lang::locale().as_str()` writes it (`fr`, `pt-BR`) | the current locale of the process |
| `Host` | `.host(host)`, written as `Request::http_host` reports it (`shop.example.test`, `shop.example.test:8080`) | an error that names the dimension, because a request always names a host |
| `Media`, `Encoding` | nothing | the policy's declared default, as a request that negotiates nothing gets |

A dimension the policy does not declare has no effect on the key, whatever the
probe is told. The probe takes the request to carry no query string.

The epoch is part of the key too. A test that has advanced the epoch, on this
node or through the ledger on another, names the new one with `.at_epoch(..)`
or it looks up a key nothing was published under.

Two reads differ in what they do to the eviction order. `l0()` does not count
as a use of the entry, so a test of eviction can probe between two requests
without changing which entry the next publication evicts. `RenderCache::inspect`
does count as a use: it moves the key to the most recently used end of L0, as a
request that hits it would.

`the_probe_derives_the_key_a_request_is_stored_under` and
`clear_l0_empties_memory_and_leaves_the_entry_in_l1` in
`framework/tests/render_cache/operations.rs` show both uses: the first finds an
entry under the key the probe derives for a login and finds none under the
anonymous key, and the second empties L0 and shows the next request came out of
L1, which is the only way to prove that it did not come out of memory.

**3. Move the clock instead of waiting.** The clock the runtime reads is
settable on a `RenderCacheConfig` and never by `from_env`, so a test that
needs a freshness band installs its own with `with_clock`:

```rust
let clock = Arc::new(AdjustableTestClock::new(unix_now_ms()));
// Bound to its own name first: passing `Arc::clone(&clock)` inline leaves
// the compiler inferring the trait object as the clone's return type.
let for_runtime = Arc::clone(&clock);
let config = RenderCacheConfig::from_env()?.with_clock(for_runtime);
// ... install through the application's own configuration seam, then:
clock.advance_ms(300_001);
```

`AdjustableTestClock` comes from `suprnova::live::testing`, and `unix_now_ms`
is the harness's own wall-clock reading, so an adjustable clock starts where
the system one is rather than at a time origin the rest of the process would
disagree with. (That is a clock zero, not the authority epoch this chapter
otherwise means by the word.) The harness wraps the pair as
`setup_app_with_clock` and `advance_clock_ms`, the second of which panics
rather than silently doing nothing when the boot took the system clock.
`stale_service_is_marked_and_rebuilt_in_the_background` is the test. To pass
a clock of your own, implement `suprnova::live::Clock`: its `now` returns a
`suprnova::live::UnixMillis`, or a `suprnova::live::ClockError` when it
cannot read the time.

**4. Count SQL statements.** A cache that skipped the handler but still
consulted the database on every hit satisfies every handler-side counter and
still costs a round trip. `suprnova::database::testing::StatementCounter`
counts the prepared statements run through a connection: the queries and
executes SeaORM builds from a statement. It sees statements on the pool and on
every transaction started from it. Unprepared SQL and transaction control are
not counted, so a `BEGIN` or a savepoint does not move the count.

```rust
use suprnova::database::testing::StatementCounter;

// Immediately after connecting, before the connection is cloned or bound
// into the container: installing needs sole ownership of the pool.
let mut conn = DbConnection::connect(&config).await?;
let statements = StatementCounter::install(&mut conn)?;

// ... bind `conn`, boot the app, dispatch the request under test ...
statements.reset();
let hit = dispatch_get("/posts/1").await;
assert_eq!(statements.count(), 0, "the cache answered without the database");
```

`install` returns an error, and installs nothing, when the connection is
already shared, because a counter that read zero would be a false proof.
`count()` returns a `u64` and `reset()` sets it back to zero. A clone of the
counter reads the same count. The counter is told nothing about a statement:
no SQL text, no bound value, because a count is the whole point.

Read a count only after a request you know the cache stored. The render that
publishes an entry runs statements, and under `CoherenceMode::Lease` the first
hit grants the lease, so measure the second hit.
`a_lease_mode_hit_runs_no_statement_and_its_render_does` in
`framework/tests/render_cache/operations.rs` shows the sequence: the render
costs more than zero statements, and the hit that follows costs none.
`an_authority_mode_hit_issues_exactly_one_statement` in
`framework/tests/render_cache/bypass.rs` holds an authority-mode hit to one,
and `the_epoch_is_read_once_at_first_use` measures two misses against each
other to show the epoch costs one read per runtime.

**Every item in this section needs the `testing` feature.**
`RenderCacheProbe`, `RenderCacheConfig::with_clock` and `StatementCounter`
do not exist in a build without it. A scaffolded application and the
dogfood `app` turn it on for tests only, through a dev-dependency on the
framework:

```toml
[dev-dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "<version>", features = ["testing"] }
```

The application's own `[dependencies]` entry leaves the feature off, so the
binaries carry none of it. See "Production build shape" in
[Deployment](deployment.md).

Two habits worth keeping. Boot the harness through your own application's
configuration seam rather than through a hand-built router, so the test
installs the same routes, policies, and middleware ordering the server does.
And never add a timing wait: every barrier above is a state barrier on a
counter, which is what makes these tests reproducible rather than flaky.

## When something is wrong

- **A page is showing content you know is old.** Check whether the route is
  storing at all (two requests, look for `Age`). Every process whose
  configuration enables RenderCache and whose database holds the
  RenderCache migration advances generations for its own writes, so a
  queue worker, a scheduled task, or a console command invalidates the
  same generations the serving process would; confirm the writing process
  actually has RenderCache enabled and migrated, since one that does not
  writes nothing. Under `CoherenceMode::Lease`, a stale-but-stored entry
  still catches up within `max_age_ms` rather than immediately. For
  everything else, run `render-cache:epoch-advance` (per node - see the
  last bullet).
- **A page you expected to cache never carries an `Age` header.** It is
  being declined, not failing. Read the `reason` label on the `declined`
  lookup first - it names the exact contract that refused the render, from
  the closed set in "Telemetry" above - then, for one of the
  classification-narrowed reasons, work through the classification list in
  [RenderCache](render-cache.md): a session read, an identity read on a
  route with no `Principal` variance, a locale read with no `Locale`
  variance, an authorization check, or a raw SQL read.
- **A backend is unreachable.** `RENDER_CACHE_FAILURE` decides: `open` (the
  default) serves the route uncached, `closed` answers a bare `503`. A
  backend missing at boot stops the boot instead, with a sentence naming the
  migration or the variable to fix.
- **Redis was flushed or restarted.** Entries miss and are re-rendered.
  Nothing stale can be proven current: currency is proved against the
  database generation ledger, never against the tier that held the bytes.
- **A rebuild leader died mid-rebuild.** Its lease is taken over once store
  time passes the expiry, and the former leader's own publication is fenced
  out rather than racing the new one. It publishes nothing; its request's
  response is still served.
- **An L1 file was torn by a crash or a full disk.** Nothing serves it. Each
  file carries a digest over its own frame, so a truncated or altered file
  fails that check and is a miss; the store removes it, and any leftover
  temporary file, the next time it opens. A torn write is self-healing here
  rather than a permanently poisoned entry.
- **The database was restored from a backup.** This one has a procedure
  rather than a sentence; see "Restoring the database" below.
- **You need everything gone, now.** `render-cache:epoch-advance`. On more
  than one node, run it on each, or restart the ones you did not run it on:
  the advance moves the ledger's epoch for the whole deployment, but it
  clears L0 and drops the leased epoch only in the process that ran it. The
  restore procedure below spells out why.

## Restoring the database

The generation ledger is the authority every hit is proved against, so
restoring the database changes what "current" means for every entry already
stored. Two things decide what a stored entry does next, and neither of them
is "it is quietly dropped".

**It is handled for you.** The first authority read after the restore that
meets an epoch or an entry stamped above the restored value refuses that
entry outright - not served once under `Warning`, not at any age, whatever
the route's freshness policy says - rebuilds it, lifts the ledger's epoch to
one past the highest stamp it saw, replaces that node's epoch lease with the
lifted value, and clears that node's L0. Every other node sees the lifted
epoch at its own next authority read: immediately under
`CoherenceMode::Authority`, and within `max_age_ms` under
`CoherenceMode::Lease`. `suprnova.render_cache.epoch_rewinds` counts each
detection.

That is the whole of it, and it is the same convergence an operator's
`render-cache:epoch-advance` produces, reached without the operator. The
three `an_epoch_advanced_by_another_node_*` tests in
`framework/tests/render_cache/middleware.rs` measure the propagation bound,
and `a_rewound_epoch_refuses_the_entry_rebuilds_and_lifts` measures the
refusal.

**One optional step remains.** Empty the shared L1 tier if a route with a
stale-servable window must not serve a pre-restore representation once
before its rebuild. The lift is what makes that reachable: an L1 entry
stamped *below* the lifted epoch is an ordinary moved entry again, and a
moved entry on such a route is served once under `Warning` while the rebuild
runs behind the request. Delete the file tier's directory contents,
`DELETE FROM suprnova_render_entries`, or delete the Redis keys matching
`<prefix>entry:*` - whichever tier the profile configures. Skip it and the
worst case is one `Warning`-marked pre-restore body per such key.

## Measuring it

RenderCache ships two benchmarks, and they are **on-demand tools, never gate
steps**:

```bash
crates/suprnova-live/scripts/run-render-cache-budget.sh
```

That runs the engine bench (`render_cache_budget`, the hot-hit and composite
assembly measurements with a counting allocator), then the framework
workload bench (`render_cache_workloads`, the same route through the whole
middleware), then the contract test over the checked-in results. Both are
pinned to `SUPRNOVA_LIVE_S1_CPUSET`.

A full run needs a disposable PostgreSQL (`PG_TEST_URL`) and a disposable
Redis (`REDIS_TEST_URL`), because the checked-result contract requires all
three recorded profiles. **A partial run must redirect both result files**
with `SUPRNOVA_LIVE_BENCH_RESULT` and `SUPRNOVA_LIVE_WORKLOADS_RESULT` under
`benchmarks/local/`; without that it overwrites the checked-in results with
a shorter file and then fails its own contract.

The checked-in numbers, from
`crates/suprnova-live/benchmarks/render-cache-budget-v1.json` and
`render-cache-workloads-v1.json`:

| Measurement | Value |
|---|---|
| Engine work for a fresh `Complete` L0 hit, p95 | 0.76 microseconds |
| Heap allocations, fresh hit | 3 |
| Heap allocations, conditional `304` hit | 3 |
| Heap allocations, hit bounded by a seed deadline | 4 |
| Body copies on any of them | none; the buffer is shared |
| The same route through the middleware, server side, p95 | 14.4 microseconds |
| The same request over a loopback HTTP round trip, p95 | 109 microseconds |
| SQL statements per hot hit (lease mode) | 0 |

The middleware figures are for a 65,536-byte body whose render read 12 rows,
recorded as 14 observed dependency identities.

**Read those as exploratory, not as qualified evidence.** Every checked-in
result carries `"classification": "local_exploratory"` and
`"s1_requirements_met": false`: they were produced on a developer
workstation with a shared CPU, a `powersave` governor, and loopback
providers. They are useful for catching a regression of a whole order of
magnitude and for nothing finer. A number is qualified evidence only when it
was produced on the dedicated runner with its attestation set, and these
were not.

### Why Suprnova diverges

Laravel's response-caching packages leave operations to the cache store
underneath. Inspecting an entry means finding its key by hand and reading
the value - which is the rendered page, so looking at it means printing
somebody's HTML to a terminal - and invalidating everything means flushing a
store that also holds your sessions, your rate limits, and your queue.
Observability is whatever the store driver happens to emit.

Suprnova gives the cache its own operating surface, deliberately narrow.
Inspection is body-free by construction, so an operator can confirm an entry
exists, what class it is stored under, and how large it is, without ever
being shown its contents. Invalidation is an epoch bump that costs nothing
to apply and touches only this cache - your sessions and your queue are not
in the blast radius. Telemetry is a closed set of nine counters with closed
attribute sets, which is what makes a dashboard over them stable across
releases rather than a set of strings that drift. The trade is that there is
no "delete this one key" command: the levers are per entry read-only, or
epoch-wide.

## Next

- [RenderCache](render-cache.md) - the declarations these commands operate on
- [Observability](observability.md) - where the counters above are exported
- [Testing](testing.md) - the surrounding test conventions the patterns above
  sit inside
- [Deployment](deployment.md) - the production checklist around them


---

<!-- /docs/idempotency -->

# Idempotency

When a client retries a POST, you want the second call to be safe. The
network is unreliable and clients retry - but `POST /charges` should never
charge the card twice, and `POST /orders` should never produce two orders
for one click. Idempotency keys are the contract that says "if you see this
same key again, give me the original answer; don't redo the work."

Suprnova's `Idempotency` is a thin facade over `Cache::lock` that gives you
three escalating guarantees: dedupe-only, dedupe with retry-on-failure, and
Stripe-style result replay. All three keep the lock's lease alive for as
long as the body runs, so a slow body can never let the lock expire and a
duplicate slip past.

```rust
use std::time::Duration;
use suprnova::{Idempotency, Idempotent};

let outcome: Idempotent<OrderId> = Idempotency::once(
    "create-order:user-42:client-key-abc",
    Duration::from_secs(86_400),
    || async {
        // Runs exactly once per key within the 24-hour window.
        place_order(&user, &cart).await
    },
)
.await?;

match outcome {
    Idempotent::Fresh(id) => /* first call - id is the new order */ {},
    Idempotent::FreshUnfenced(id) => {
        // The order was placed, but the lock's lease was lost partway
        // through, so another caller may have placed one too. Reconcile
        // or alert - see "When exclusivity is lost" below.
    },
    Idempotent::Duplicate => /* same key already used */ {},
}
```

## The three primitives

| Method | Body runs | Duplicate sees | Failure releases lock? | Use when |
|---|---|---|---|---|
| `Idempotency::once` | exactly once per window | `Duplicate` marker | no | side effects must NEVER repeat (mail sent, charge attempted) |
| `Idempotency::commit_on_success` | once per success per window | `Duplicate` marker | yes | transient failures should be retryable, but a success holds |
| `Idempotency::remember` | once per success per window | the original return value | yes | duplicates must receive the original payload, not a marker |

All three live under `suprnova::idempotency` and are re-exported from the
crate root as `Idempotency`, `Idempotent`, and `Replay`. They share the
same key-hashing, lease-renewal, and lock semantics - only the
success/failure policy differs.

### `Idempotency::once` - at-most-once

The strictest contract. The first caller in the TTL window runs the body
and gets `Fresh(value)`. Every subsequent caller within the window gets
`Duplicate` and the body does NOT run again - even if the first caller's
body returned `Err`. The TTL IS the dedupe window.

```rust
use std::time::Duration;
use suprnova::{Idempotency, Idempotent};

// Send a welcome email exactly once per signup, regardless of how many
// times the signup callback retries.
let result = Idempotency::once(
    &format!("welcome-mail:{}", user.id),
    Duration::from_secs(7 * 24 * 3600),
    || async {
        Mail::to(&user.email).send(WelcomeMail { user: user.clone() }).await
    },
)
.await?;
```

Reach for `once` when the side effect is the kind where "I tried; even
if I errored after the side effect, don't try again" - sending an email,
posting to an external API that doesn't honour idempotency keys of its
own, writing an audit log entry whose double-write would corrupt
downstream analytics.

### `Idempotency::commit_on_success` - at-least-once on success, retry on failure

Like `once`, but if the body returns `Err`, the dedupe lock is released so
the next caller within the TTL window can retry. A successful body keeps
the lock for the rest of the window.

```rust
use std::time::Duration;
use suprnova::{Idempotency, Idempotent};

let outcome = Idempotency::commit_on_success(
    &format!("publish-post:{}", post.id),
    Duration::from_secs(300),
    || async {
        // Posts a message to an upstream service. Network errors are
        // transient - the next retry should re-enter, not be told
        // "already done" when nothing actually happened.
        social_media_client.post(&post).await
    },
)
.await?;
```

Use `commit_on_success` when the body has retryable failure modes
(transient network errors, upstream rate limits, expired credentials
that a refresh would fix) and you want at-least-once on success but
the lock to surrender on a failure so a retry can re-enter.

### `Idempotency::remember` - Stripe-style result replay

The contract the HTTP `Idempotency-Key` header was invented for. The first
caller runs the body, stores the success value, and gets `Replay::Fresh`.
A later caller within the window gets `Replay::Replayed(<original value>)` -
the recorded return value, not a marker. A concurrent caller that
arrives *while* the first is still running gets `Replay::InProgress`.

```rust
use std::time::Duration;
use suprnova::{
    handler, AppError, Auth, FrameworkError, HttpResponse, Idempotency, Replay, Request, Response,
};

#[handler]
pub async fn create_charge(req: Request) -> Response {
    // Extract the header to an owned String before consuming `req` for the body.
    let key = req
        .header("Idempotency-Key")
        .ok_or_else(|| FrameworkError::bad_request("Idempotency-Key header required"))?
        .to_string();

    let user = Auth::user_as::<User>()
        .await?
        .ok_or_else(|| AppError::unauthorized("login required"))?;

    let form: ChargeForm = req.json().await?;

    let outcome = Idempotency::remember(
        &format!("charge:{}:{}", user.id, key),
        Duration::from_secs(24 * 3600),
        || async {
            let charge = StripeClient::charge(&form).await?;
            Ok(ChargeResponse {
                id: charge.id,
                amount: charge.amount,
                status: charge.status,
            })
        },
    )
    .await?;

    match outcome {
        Replay::Fresh(body) | Replay::Replayed(body) => {
            let json = serde_json::to_value(&body)
                .map_err(|e| FrameworkError::internal(format!("serialize: {e}")))?;
            Ok(HttpResponse::json(json))
        }
        Replay::FreshUnfenced(body) => {
            // Same response to the client, but worth a metric: exclusivity
            // was not held for the whole body.
            tracing::warn!("idempotent body completed unfenced");
            let json = serde_json::to_value(&body)
                .map_err(|e| FrameworkError::internal(format!("serialize: {e}")))?;
            Ok(HttpResponse::json(json))
        }
        Replay::InProgress => Ok(HttpResponse::text("retry")
            .status(409)
            .header("Retry-After", "1")),
    }
}
```

Notice that `Fresh` and `Replayed` are handled identically by the
client-facing response - the whole point of `remember` is that the second
caller can't tell whether they were the one who ran the body or whether
they got the recorded result.

`InProgress` is the case worth thinking about: a duplicate arrived while
the first caller's body was still executing, so there's no recorded result
to hand back yet. `409 Conflict` with a `Retry-After: 1` header is the
canonical answer - the client backs off briefly, then retries, and the
second attempt either races the original to the `Cache::get` short-circuit
or hits `Replayed`.

## Key material

All three methods accept an arbitrary `&str` for the key. Before it
touches the cache backend, the key is SHA-256 hashed into a 64-character
hex digest. This buys you three things:

1. **Bounded backend key length.** A client that POSTs a 10 KB
   `Idempotency-Key` header still produces a 64-byte cache key.
2. **Raw identifiers don't leak into cache tooling.** If the key contains
   an email address, a session id, or an internal user id, those don't
   show up in `redis-cli KEYS idem:*`.
3. **No character-class collisions.** Whatever the cache backend
   interprets specially (colons, glob characters, control bytes) is
   already gone - the hash is hex-only.

The hash is over the user-provided key, not the cache key prefix -
`Idempotency::once("k", …)` and `Idempotency::once("k", …)` from two
different call sites in the same process collide on purpose. Namespace
your keys yourself if you don't want that:

```rust
Idempotency::once(
    &format!("billing:charge:{}:{}", tenant_id, client_key),
    Duration::from_secs(86_400),
    || async { /* … */ },
)
.await?;
```

## Lease renewal - the slow-body problem

A naive lock + TTL combination has a window bug: if the body runs longer
than the TTL, the lock expires while the body is still running, and a
second caller can acquire a fresh lock and run the body again
concurrently. The dedupe contract breaks for exactly the operations
slow enough to need it.

Suprnova solves this by spawning a background task that refreshes the
lock at one-third of the TTL (floored at 50 ms) for the entire duration
of the body. A `tokio::select!` with `biased` ordering guarantees the
body branch is the only one that ever resolves the future.

A refresh *error* is not treated as a lost lease. It means the backend
could not be asked, not that somebody else took the lock, so renewal
retries at the next interval and only gives up after several consecutive
failures. Abandoning on the first blip guaranteed the lease would lapse
even when the backend recovered milliseconds later.

### When exclusivity is lost

Renewal can still genuinely fail: the token stops matching, because the
lock expired and somebody else claimed it. At that moment two callers can
be running the same body.

The body is **not** cancelled. By the time a lease is lost it may already
have charged a card or sent a message, and cancelling would strand that
half-done with nothing recording it. The body runs to completion and the
loss is reported:

| Outcome | Means |
|---|---|
| `Fresh(v)` / `Replay::Fresh(v)` | body ran, exclusivity held throughout |
| `FreshUnfenced(v)` | body ran and produced `v`, but another caller may have run concurrently |

`FreshUnfenced` is a separate variant rather than a flag on `Fresh`
specifically so an exhaustive `match` cannot ignore it by accident. What
to do with it is yours to decide - reconcile, alert, compensate - but
treating it as `Fresh` throws away the only signal you get that the
guarantee did not hold.

Losing a lease requires the backend to be unreachable for several refresh
intervals, or a stop-the-world pause longer than the TTL. It is rare. It
is not impossible, and it used to be invisible.

The practical upshot: pick a TTL based on your dedupe window
(`how long should a duplicate request be deduped?`), not your
worst-case body duration. A 30-minute body with a 1-minute TTL is fine -
the lock will be refreshed about ninety times during the body's run.

A test that exercises this: a 200 ms TTL with a body that blocks for
500 ms, and a second caller arriving at 400 ms. Without renewal, the
second caller would re-execute the body. With renewal, it sees
`Duplicate`. The lock holds.

## Shared backend

Cross-process dedupe requires a cross-process cache. The in-memory backend
holds locks in a per-process `HashMap`, so two `cargo run` instances on
the same machine won't see each other's idempotency keys. Production
deployments where any of these matter - multiple app processes,
horizontal scaling, blue/green deploys with overlapping traffic windows -
must set `CACHE_DRIVER=redis` and provide a reachable `REDIS_URL`.

The bootstrap is fail-closed: if `CACHE_DRIVER=redis` and Redis is
unreachable, the app refuses to start rather than silently downgrading
to per-process memory. See [cache.md](cache.md) for the full cache
backend contract.

## Error handling

The body's `FrameworkError` propagates up through `Idempotency`
unchanged. A lock-acquisition failure (Redis is down mid-request, the
backend returns an error) propagates as a `FrameworkError` from the
cache layer - there is no silent fallback. The error type is the
framework's standard `FrameworkError`, so handlers can `?` it through
to their controller's error converter:

```rust
use std::time::Duration;
use suprnova::{handler, FrameworkError, HttpResponse, Idempotency, Replay, Response};

#[handler]
pub async fn handler(order_id: i64) -> Response {
    let outcome: Replay<MyDto> = Idempotency::remember(
        &format!("order:{order_id}"),
        Duration::from_secs(60),
        || async move {
            let row = MyRow::find(order_id)
                .await?
                .ok_or_else(|| FrameworkError::not_found("missing"))?;
            Ok(MyDto::from(row))
        },
    )
    .await?;

    match outcome {
        Replay::Fresh(dto) | Replay::Replayed(dto) | Replay::FreshUnfenced(dto) => {
            let json = serde_json::to_value(&dto)
                .map_err(|e| FrameworkError::internal(format!("serialize: {e}")))?;
            Ok(HttpResponse::json(json))
        }
        Replay::InProgress => Ok(HttpResponse::text("retry")
            .status(409)
            .header("Retry-After", "1")),
    }
}
```

A release failure on the `Err` path of `commit_on_success` or `remember`
is **logged, never returned** - the body's error is the only error the
caller sees on that path. A failed release means the lock will hold
until the TTL lapses; a retry within the window will see `Duplicate`
or `InProgress` until then. Logs include the hashed key (never the raw
key material) so operators can correlate without leaking PII.

## Cancellation

If the caller drops the `Idempotency::remember` future before the body
completes, the body is cancelled like any other `tokio::select!` branch -
the lock is **not** released, and a duplicate arriving before the TTL
lapses sees `InProgress` (then, after the TTL, `Fresh` again). This is
the safe default: a half-finished body whose effects you don't know
about should not be presumed safe to retry. Wrap bodies that hold
unmanaged side effects in `tokio::spawn` and join the handle if you
need to make the body uncancellable.

## Queue integration

The queue layer uses `Idempotency::commit_on_success` internally to
implement `Queue::push_unique`. If you want a job to be enqueued at most
once per `Job::unique_for()` window per `Job::unique_id(&self)`, you
don't need to call `Idempotency::*` yourself:

```rust
use suprnova::{Job, Queue};

let was_pushed = Queue::push_unique(SendReceipt { order_id: 42 }).await?;
if was_pushed {
    // We won the race; the job is on the queue.
} else {
    // Another caller already enqueued this; treat as success.
}
```

See [queues.md](queues.md) for the full job-uniqueness contract.

## Payment webhook ingress

The payments webhook handler does NOT use `Idempotency::*`. Webhook
ingress has a stricter requirement - every event must be auditable, even
on first delivery, so the audit row is the source of truth and the
de-dupe key is the database `UNIQUE(provider, provider_event_id)`
constraint. `Idempotency::remember` would store the response payload in
the cache; the webhook handler stores the *full event envelope plus
processing outcome* in `payments_webhook_events`, which means an
operator can replay or re-process events offline by reading the table.

The two patterns are complementary. Use `Idempotency::*` for client-driven
keys with TTL-scoped dedupe; use a `UNIQUE`-indexed audit table for
provider-driven webhook ingress that needs auditability past the cache
TTL. See [payments.md](payments.md) for the webhook contract.

### Why Suprnova diverges

Laravel's `Cache::lock` is a primitive; the Stripe-style idempotency
contract (record the result, replay it, distinguish in-progress from
duplicate) is left as a userland recipe. Every Laravel project that
needs it ends up writing the same lock-and-cache dance, usually with
one of these three bugs:

1. **No lease renewal.** A body that outlives the TTL re-executes
   concurrently in a duplicate caller. The lock was there; it just
   expired at the wrong moment.
2. **Release on the success path.** Releasing the lock when the body
   succeeds opens a window between `body() -> Ok` and the next caller
   acquiring a fresh lock - the very window the dedupe was supposed to
   close.
3. **Raw keys in the cache backend.** Client-supplied `Idempotency-Key`
   headers go straight into Redis keys, leaking PII into operator
   tooling and producing unbounded key sizes.

Suprnova ships the recipe as a first-class primitive so every caller
gets the same lease renewal, the same fail-closed release semantics,
the same hashed-key safety. The three methods (`once`,
`commit_on_success`, `remember`) name the three policies you actually
have to choose between - pick the one that matches your body's failure
model and move on.

## Testing

`Idempotency` resolves its `CacheStore` through the container, so tests
that bind an `InMemoryCache` get a fresh, isolated cache per test:

```rust
use std::sync::Arc;
use std::time::Duration;
use suprnova::cache::InMemoryCache;
use suprnova::cache::store::CacheStore;
use suprnova::container::testing::TestContainer;
use suprnova::idempotency::{Idempotency, Replay};

#[tokio::test]
async fn duplicate_remember_replays_the_first_result() {
    let _guard = TestContainer::fake();
    let store: Arc<dyn CacheStore> = Arc::new(InMemoryCache::with_prefix("idem:"));
    TestContainer::bind::<dyn CacheStore>(store);

    let r1: Replay<i32> = Idempotency::remember(
        "k",
        Duration::from_secs(60),
        || async { Ok(7) },
    )
    .await
    .unwrap();
    assert_eq!(r1, Replay::Fresh(7));

    let r2: Replay<i32> = Idempotency::remember(
        "k",
        Duration::from_secs(60),
        || async { Ok(999) },
    )
    .await
    .unwrap();
    assert_eq!(r2, Replay::Replayed(7));
}
```

The framework's own `framework/tests/idempotency/idempotency.rs` covers the
contract surface: duplicate suppression, TTL expiry, error-vs-success
release policy, lease renewal across body durations that outlive the
TTL, the `InProgress` race, and the case where the cache's
`release_lock` itself errors. Read those tests if you want to see the
exact behaviour you can rely on.

## Gotchas

- **`Idempotency::once` consumes the window on error.** A failing first
  caller still holds the lock until the TTL lapses. Use
  `commit_on_success` if you want retries within the window.
- **`Idempotency::remember` stores `T` in the cache backend.** The key
  is hashed, but the *payload* is serialized with serde and written to
  the backend. Don't put secrets in a replayed value that must not
  appear in your cache store.
- **Two processes need a shared cache.** In-memory dedupe is
  per-process. Cross-process correctness requires `CACHE_DRIVER=redis`
  (or another cross-process store).
- **TTLs under 150 ms are not lease-tested.** The renewal floor is
  50 ms, so a 100 ms TTL refreshes about every 50 ms - fine for the
  contract, but the framework's lease tests run at `ttl >= 1s`. Use
  realistic dedupe windows; an idempotency window measured in
  milliseconds usually means the contract isn't quite the right tool.
- **The body's cancellation does not release the lock.** A cancelled
  body leaves the lock holding until the TTL lapses. This is the
  fail-closed choice; arrange your timeouts so the cancellation
  matches what a duplicate caller should see.

## Next

- [cache.md](cache.md) - the underlying lock primitive and the
  `CACHE_DRIVER` selection.
- [queues.md](queues.md) - how `Queue::push_unique` builds on
  `Idempotency::commit_on_success` for job-level dedupe.
- [payments.md](payments.md) - webhook ingress that uses
  database-row idempotency instead of cache-keyed dedupe, and when to
  reach for which.
- [rate-limiting.md](rate-limiting.md) - adjacent middleware that uses
  the same `Cache` backend for sliding-window enforcement.
- [middleware.md](middleware.md) - how to factor idempotency-key
  extraction into a reusable middleware over your POST/PUT routes.


---

<!-- /docs/timeout -->

# Request Timeouts

`TimeoutMiddleware` puts a hard deadline on every HTTP request. A slow
handler - a hung database query, an unresponsive upstream API, an
accidental infinite loop in some hot path - would otherwise hold a hyper
connection open until the client gave up or the OS killed the process.
The timeout middleware caps that wait, drops the in-flight handler, and
returns `503 Service Unavailable` so the operator sees the failure
instead of the application silently leaking connections.

Reach for it when you're building anything that talks to the public
internet, anything that fans out to third-party APIs, or anything where
"the database might be slow today" is a realistic Tuesday.

```rust
use suprnova::{global_middleware, TimeoutMiddleware};

pub async fn register() {
    // Every HTTP route gets a 30-second ceiling.
    global_middleware!(TimeoutMiddleware::default());
}
```

That single line gives the whole application the same default ceiling
Suprnova uses for its database connect timeout - pick once, apply
everywhere. Per-route overrides are one line each. The rest of this
chapter explains exactly what the deadline bounds, what it intentionally
doesn't, and how it interacts with the panic boundary, streaming
responses, and WebSockets.

## The middleware

`TimeoutMiddleware` lives at `suprnova::TimeoutMiddleware`. It exposes
three constructors and one accessor:

```rust
use std::time::Duration;
use suprnova::TimeoutMiddleware;

let default_30s = TimeoutMiddleware::default();
let custom      = TimeoutMiddleware::new(Duration::from_millis(2_500));
let whole_secs  = TimeoutMiddleware::seconds(5);

assert_eq!(default_30s.duration(), Duration::from_secs(30));
assert_eq!(custom.duration(),      Duration::from_millis(2_500));
assert_eq!(whole_secs.duration(),  Duration::from_secs(5));
```

`TimeoutMiddleware::default()` uses a 30-second deadline. That number is
not arbitrary - it matches `DB_CONNECT_TIMEOUT` (also 30s) so a request
blocked waiting for a brand-new database connection and a request blocked
inside the handler share one ceiling. If you raise one, raise the other.

`TimeoutMiddleware::seconds(n)` is shorthand for the common whole-seconds
case. `TimeoutMiddleware::new(Duration::…)` is the escape hatch when you
need millisecond precision (an internal health check that should never
take more than 200ms; a synthetic probe with a 50ms budget).

## Installing globally

A global timeout is the right starting point: it gives every route a
ceiling without anyone having to remember to add it. Install it in
`bootstrap.rs` alongside your other global middleware:

```rust
// src/bootstrap.rs
use suprnova::{
    global_middleware, CorsConfig, CorsMiddleware, DB, RequestIdMiddleware, TimeoutMiddleware,
};
use crate::middleware::LoggingMiddleware;

pub async fn register() {
    DB::init().await.expect("database connect");

    // Run-order matters: request-id first (so timeout logs carry it),
    // then logging (so slow requests are still observed), then the
    // timeout itself.
    global_middleware!(RequestIdMiddleware);
    global_middleware!(LoggingMiddleware);
    global_middleware!(TimeoutMiddleware::default());

    global_middleware!(CorsMiddleware::new(
        CorsConfig::allow_origins(["https://app.example"]),
    ));
}
```

The order matters because global middleware wraps the rest of the chain
in registration order: `RequestIdMiddleware` runs first on the way in
and last on the way out, so the request id is in scope while the timeout
fires its `503`. Putting the timeout before logging would hide slow
requests that did eventually complete from the access log.

A project that `suprnova new` creates installs the default timeout for
you. The Inertia and Live kits install it after the session middleware and
the error page, so its `503` renders as the error page in the visitor's
session and locale, and before CSRF, so it bounds the CSRF check. The API
kit installs it first.

## Tightening per route

A 30-second global ceiling is generous on purpose - it's there to catch
runaway handlers, not to enforce SLAs. When a specific endpoint should
fail faster, attach a per-route timeout:

```rust
use suprnova::{Router, TimeoutMiddleware};

Router::new()
    // Public report endpoint: must respond in 5s or we'd rather 503
    // and let the client retry than block.
    .get("/report", controllers::report::show)
    .middleware(TimeoutMiddleware::seconds(5));
```

You can attach a tighter timeout to a route group too. This is the
typical shape for a public API where each request should be quick, while
the rest of the app keeps the 30-second default:

```rust
use suprnova::Router;
use suprnova::TimeoutMiddleware;

Router::new()
    .group("/api", |r| {
        r.get("/users",       controllers::api::users::index)
         .post("/users",      controllers::api::users::create)
         .get("/users/{id}",  controllers::api::users::show)
    })
    .middleware(TimeoutMiddleware::seconds(3));
```

### Global is a ceiling; per-route can only tighten

Global middleware runs **outside** route middleware. The chain wraps
inside-out:

```
Global timeout (30s) → Route timeout (3s) → handler
```

Both `tokio::time::timeout` futures are armed; the inner one fires
first because it has the shorter deadline. So a per-route timeout can
only make a route *stricter* than the global, never looser.

If a single endpoint legitimately needs to run *longer* than the global
default - a slow report, a large upload, a long-poll fallback - you
have two options:

1. Raise the global value. Simplest, but it relaxes the ceiling for
   every other route too.
2. Scope the global middleware to a route group that *excludes* the
   long endpoint, and attach a separate timeout (or none) to the slow
   route. This keeps the strict default everywhere else.

The second option is the right shape for one outlier; the first is
right when the whole class of work needs more room.

## What the deadline actually bounds

The deadline races the future returned by `next(request)`. That future
resolves the moment your handler returns its `HttpResponse` - not when
the body finishes streaming. That distinction is load-bearing:

- **Normal handlers** build their full body before returning, so the
  deadline effectively bounds total handler time. A handler that
  serialises a JSON list, renders an Inertia page, or assembles an HTML
  response holds the future until the work is done.
- **Streaming responses** (`HttpResponse::sse(...)`,
  `HttpResponse::stream_bytes(...)`) return *immediately* with a lazy
  body. The middleware chain has already completed by the time hyper
  starts pulling bytes off the stream, so the deadline never observes
  the body's lifetime. An SSE event stream can stay open for hours
  under a 30-second timeout, by design - see
  [Server-Sent Events](sse.md) for the streaming model.
- **WebSocket upgrades** are skipped explicitly. See the next section.
- **Request bodies** that a handler, or a middleware inside the timeout,
  reads are part of the work the deadline bounds. A slow upload can reach
  the timeout's `503` before the server's own body deadlines answer `408`;
  see [Body read deadlines](requests.md#body-read-deadlines). For a route
  that takes long uploads, raise both.

This is the behaviour you almost certainly want. If you wrapped a
long-lived SSE stream in a 30-second timeout, the framework would tear
the connection down mid-stream every 30 seconds and the feature would
be unusable.

## WebSocket carve-out

The middleware inspects the request before arming the deadline:

```rust
if is_websocket_upgrade(request.headers()) {
    return next(request).await;
}
```

Any request carrying `Upgrade: websocket` skips the timeout entirely.
The check is case-insensitive on the token value (`WebSocket`,
`websocket`, `WEBSOCKET` all match), and a bare `Connection: upgrade`
without `Upgrade: websocket` is *not* treated as a WS upgrade - that
flows through the timeout normally.

WebSocket upgrades take a separate server path that doesn't run
global middleware at all, so this guard is defence in depth - it
keeps the timeout from ever bounding a long-lived bidirectional channel
if that path changes. See [WebSockets](websockets.md) for how upgrades
are dispatched and the lifetime of a connected socket.

## What happens at the deadline

When `tokio::time::timeout` elapses before the handler completes, the
middleware does three things, in order:

1. **Drops the in-flight handler future.** The future was being polled
   inside the `timeout` combinator; the combinator returns `Err(Elapsed)`
   and the future is dropped where it was last suspended.
2. **Logs a warning** with the route path and the timeout duration in
   milliseconds:

   ```
   WARN suprnova::timeout request exceeded its timeout; returning 503 Service Unavailable
       route=/report timeout_ms=5000
   ```

   The log is at `WARN` so it surfaces in operator dashboards by
   default, separate from `INFO` access logs of normal requests.
3. **Returns `503 Service Unavailable`** with a plain-text body:

   ```
   HTTP/1.1 503 Service Unavailable
   Content-Type: text/plain
   Content-Length: 42

   Service Unavailable: request timed out
   ```

The 503 is wrapped in `Err(HttpResponse::…)` so it short-circuits the
rest of the chain just like any other middleware-rejected request.
Outer middleware (logging, request-id, CORS) still runs its post-handler
side, so the response goes out with the correct headers.

### Why 503 and not 504

`504 Gateway Timeout` is the right code when *you* are the gateway and
an *upstream* timed out. `503 Service Unavailable` is the right code
when *this* service couldn't produce the response in time. The timeout
middleware is bounding *our own* handler, so it returns 503. If you
want a different shape - a JSON body, a different status, a
machine-readable code - wrap your own outer middleware around the
timeout and translate its 503 response.

## Cancel safety

When the deadline elapses, the handler future is **dropped** at its
current `.await` point. This is normal Tokio cancellation; the same
thing happens when a client closes the connection mid-request. Anything
held across the await boundary is released by its `Drop` impl:

- **Database transactions** roll back. A SeaORM `DatabaseTransaction`
  has a `Drop` impl that issues `ROLLBACK` on the underlying connection.
- **Mutex and RwLock guards** release. A standard library or
  `parking_lot` guard releases on drop; another waiter can take it
  immediately.
- **File handles** close. The OS-level descriptor is released when the
  `tokio::fs::File` is dropped.
- **Network connections** check back into the pool or close, depending
  on the pool's drop behaviour.

The result is that a timed-out handler leaves nothing dangling - the
operator sees the 503, the database sees the rollback, the next request
sees a clean pool.

### What is *not* cancelled

Anything you moved off the request with `tokio::spawn` is **detached**.
Spawned tasks live on the runtime, not the request future, so dropping
the request does not stop them. This matters when you wrote something
like this:

```rust
pub async fn webhook(req: Request) -> Response {
    let payload: WebhookPayload = req.json().await?;

    // Fire-and-forget background work. Survives the request timing out.
    tokio::spawn(async move {
        if let Err(e) = process_webhook(payload).await {
            tracing::error!("webhook processing failed: {e}");
        }
    });

    Ok(HttpResponse::new().status(204))
}
```

If the request times out *before* the `spawn` line runs, the spawn
never happens. If the request times out *after* the spawn, the
background task keeps running - it is not cancelled with the request.
That's almost always what you want for webhook-style work, but it does
mean cleanup after a long `.await` inside the handler is **not**
guaranteed to run:

```rust
pub async fn upload(req: Request) -> Response {
    let temp_path = save_to_temp(&req).await?;

    // If this is what times out, the cleanup below DOES NOT RUN.
    let processed = long_running_processing(&temp_path).await?;

    // Not guaranteed under a timeout.
    tokio::fs::remove_file(&temp_path).await?;

    Ok(HttpResponse::json(serde_json::to_value(&processed)?))
}
```

The fix is to use RAII. Wrap the temporary file in a struct whose
`Drop` impl removes it; then the cleanup runs whether the handler
returns, returns an error, or is dropped mid-`.await` by the timeout.
This is the same discipline you'd apply for any cancellation source -
client disconnect, runtime shutdown, panic recovery.

## Interaction with the panic boundary

The Suprnova server wraps the entire middleware chain in
[`execute_chain_safely`](lifecycle.md), which uses
`AssertUnwindSafe(...).catch_unwind()` to translate panics into a sanitised
`500 Internal Server Error`. A timed-out request is **not** a panic -
the future is dropped cleanly - so the timeout's `503` goes out
without involving the panic boundary at all.

The two boundaries handle different failure modes:

| Failure | Boundary | Status | Body |
|---|---|---|---|
| Handler `.await` exceeds deadline | `TimeoutMiddleware` | `503` | `Service Unavailable: request timed out` |
| Handler panics (`.unwrap()` on `None`, etc.) | `execute_chain_safely` | `500` | `{"message": "Internal Server Error"}` |
| Handler returns `Err(HttpResponse)` | normal `Response` flow | whatever the handler set | whatever the handler set |

You don't have to pick - both boundaries are always installed. A handler
that panics *after* exceeding its timeout still produces a 503 (the
future was dropped before the panic could happen). A handler that
panics *before* exceeding its timeout produces a 500.

## Operational tuning

Three considerations when picking timeout values:

1. **Match your database connect timeout.** If `DB_CONNECT_TIMEOUT=30`
   (the default), a request timeout shorter than 30s will fire before
   a slow connect ever completes - the user sees `503` instead of the
   chance to recover. Either raise the connect timeout or accept that
   "30s" is the floor.
2. **Account for the slowest legitimate handler.** Look at a histogram
   of your `INFO`-level request durations. The p99 of the slow tail
   should sit comfortably below the timeout, with headroom for clock
   skew and event-loop jitter. A timeout that fires routinely on
   healthy traffic is a misconfiguration, not a feature.
3. **Per-route timeouts are observability.** Tightening
   `TimeoutMiddleware::seconds(3)` on `/api/*` turns a degraded API
   into a visible alert (logs full of WARN, 503s in the load balancer)
   instead of a creeping latency problem. Use them where you have an
   SLA and want a hard failure when you miss it.

The framework's own integration tests use durations in the millisecond
range (`TimeoutMiddleware::new(Duration::from_millis(50))`) to exercise
the deadline deterministically. Production deadlines are almost always
in whole seconds.

### Why Suprnova diverges

In a Laravel + PHP-FPM deployment, request timeouts live outside the
application: nginx's `proxy_read_timeout`, PHP-FPM's
`request_terminate_timeout`, the load balancer's idle timeout. The
PHP process is killed when the budget is exhausted, and any open
state - database connections, file handles - leaks until the next
request reuses the worker.

Suprnova bounds the request inside the application because it can. The
handler is a Tokio future, not a PHP process, so dropping it runs `Drop`
impls cleanly: transactions roll back, locks release, descriptors close,
the connection pool stays healthy. The 503 also goes out *as a real HTTP
response* - clients see a proper status code instead of an upstream
reset.

This is also why the middleware doesn't try to be a Tower
`Timeout` layer. Tower's layer is generic over any Tokio service and
returns `tower::timeout::error::Elapsed`, which callers then have to map
to an HTTP status. The Suprnova middleware knows it's wrapping an HTTP
request pipeline; it returns `503` directly, logs the offending route,
and respects the framework's WebSocket and streaming carve-outs without
the caller having to reason about them. The Tower layer is the right
primitive for a generic Tokio service; for an HTTP request, this is the
right shape.

## Next

- [Middleware](middleware.md) - the trait, the chain, global vs per-route registration, terminable hooks
- [Request Lifecycle](lifecycle.md) - where the timeout sits in the chain, and how `execute_chain_safely` handles panics
- [Server-Sent Events](sse.md) - the streaming response model the timeout intentionally doesn't bound
- [WebSockets](websockets.md) - the upgrade path that bypasses the timeout entirely
- [Errors](errors.md) - how 5xx responses are dispatched as `ErrorOccurred` events for observability


---

<!-- /docs/feature-flags -->

# Feature Flags

Suprnova's feature-flag system combines compile-time `Feature` declarations with runtime overrides persisted to a `features` table. A flag's value at evaluation time is determined by, in order:

1. A scoped row in the `features` table - `user:42` or `team:staff`.
2. The global row in the `features` table (scope `""`).
3. The compile-time `default` baked into the `Feature` declaration.

Toggles via the admin CRUD propagate to live evaluators before the mutation call returns. Kill-switch flags actually disable in real time, not "within the next TTL window."

## Quick start

```rust
// app/src/features.rs - every flag your app references lives here.
use suprnova::features::Feature;

pub const NEW_CHECKOUT_FLOW: Feature<'static> = Feature::new("new-checkout-flow", false);
```

```rust
// app/src/bootstrap.rs - wire the chain once during boot.
use std::time::Duration;
use suprnova::features::{bootstrap_database_cached, FeatureMiddleware};

pub async fn register() {
    // ... DB::init, session, etc.

    bootstrap_database_cached(Duration::from_secs(60))
        .await
        .expect("feature flags wired");

    global_middleware!(FeatureMiddleware::new());
}
```

```rust
// any handler - Feature::is_enabled() resolves against the per-request context.
use crate::features::NEW_CHECKOUT_FLOW;

pub async fn index(req: Request) -> Response {
    let banner = if NEW_CHECKOUT_FLOW.is_enabled() {
        Some("Try the new checkout - faster, fewer steps.")
    } else {
        None
    };
    // ...
}
```

```rust
// flip the flag from an admin route or CLI:
use suprnova::features::admin;

let actor_id = Auth::id();  // Option<String> - None for system-initiated changes
admin::upsert("new-checkout-flow", "", true, None, actor_id).await?;
//                                  ^   ^                  ^
//                                  |   |                  └ audit: who toggled it
//                                  |   └ enabled
//                                  └ scope_key: "" = global, "user:42" = scoped override
```

The next `NEW_CHECKOUT_FLOW.is_enabled()` call observes `true` - including any cached evaluator entry, which was invalidated synchronously inside `admin::upsert`.

## The pieces

### `Feature<'a>`

The compile-time declaration. Carries the flag name and a default-when-absent value.

```rust
pub const KILL_SWITCH_PAYMENTS: Feature<'static> =
    Feature::new("kill-switch.payments", true);
//                                      ^ default: true (payments enabled until disabled)
```

Centralising every declaration in `app/src/features.rs` gives you:

- a single place to grep when an operator asks "what flags exist?"
- compile-time uniqueness for the flag name - a typo at the call site doesn't compile
- the obvious place to put a doc comment explaining what the flag controls

Call `flag.is_enabled()` to read against the ambient context (set up by [`FeatureMiddleware`](#featuremiddleware)) or `flag.is_enabled_in(Some(&ctx))` to pass a specific [`Context`](https://docs.rs/featureflag/latest/featureflag/context/struct.Context.html).

The `feature!` and `is_enabled!` macros are also re-exported from `suprnova::*` for call sites that don't want to import the constant:

```rust
use suprnova::is_enabled;

if is_enabled!("new-checkout-flow", false) {
    // ...
}
```

### `DatabaseEvaluator`

Reads the `features` table into an in-memory snapshot at boot and on every [`reload()`](#flow-control-flag-propagation). The hot path (`is_enabled`) is fully synchronous - no DB query per request, no `block_on` inside the evaluator.

Resolution order on lookup, most specific first:

1. `user:{id}` - when the request context carries a `UserIdField`.
2. `team:{name}` - when the context carries a `TeamField`.
3. `""` - the global flag.
4. `None` - the row doesn't exist, the compile-time default takes over.

### `CachedEvaluator`

Memoizes `(feature, user, team)` lookups behind a `DashMap` with a TTL you pick. The hot path stays sync; entries are dropped synchronously when [`admin::upsert`](#admin-crud) writes a flag.

A TTL of zero degenerates to "no cache" - every call falls through to the inner evaluator. Useful for low-flag-count apps that want the propagation plumbing without the cache.

### `FeatureMiddleware`

Opens a per-request featureflag context populated by user-defined extractors. Defaults:

- `user_id` - from `Auth::id()`.
- `team` - none.

Override either via the builder:

```rust
let middleware = FeatureMiddleware::new()
    .with_user_id_extractor(|req| {
        // Custom: pull from a header instead of the session.
        req.header("X-User-Id").map(String::from)
    })
    .with_team_from_header("X-Team");
// or: .with_team_extractor(|req| your_custom_team_resolver(req))

global_middleware!(middleware);
```

### Admin CRUD

`suprnova::features::admin` is the persistence layer for the `features` table. Use it from admin handlers, CLI tools, deployment scripts - anywhere a flag needs to flip:

```rust
use suprnova::features::admin;

// Create or update a global flag.
admin::upsert("kill-switch.payments", "", false, Some("ops-2026-05-19".into()), actor_id).await?;
// args: name, scope_key, enabled, description, actor_id

// User-scoped override (beats the global).
admin::upsert("new-checkout-flow", "user:42", true, None, actor_id).await?;

// Remove a row entirely - flag falls back to compile-time default.
admin::delete("kill-switch.payments", "", actor_id).await?;

// Read for an admin UI table.
let all_flags = admin::list().await?;
let one_row = admin::get("kill-switch.payments", "").await?;
```

Every mutation fires the corresponding [event](#events) and calls [`features::sync::notify`](#flow-control-flag-propagation) so any live evaluator bound into the App container refreshes before the call returns.

`actor_id: Option<String>` is the audit pointer. Pass the operator's user id (the same one your auth layer issues); leave `None` for system-initiated changes (CLI, deploy migration, etc.).

## Flow control: flag propagation

The trait that makes "admin toggle visible immediately" work:

```rust
#[async_trait]
pub trait FeatureSync: Send + Sync + 'static {
    async fn on_flag_changed(&self, feature: &str, scope_key: &str);
}
```

Implementors react to mutations:

- `DatabaseEvaluator::on_flag_changed` calls `self.reload()` - pulls the full snapshot.
- `CachedEvaluator::on_flag_changed` calls `self.invalidate(feature)` - drops every cached entry for that name.

The canonical chain is a `CompositeFeatureSync`, which **orders data sources before caches** - caches must invalidate *after* the data source refreshes, or a concurrent reader can hit the empty cache, fall through to the stale data source, and repopulate the cache with the old value.

```rust
let composite = CompositeFeatureSync::new(
    vec![database.clone() as Arc<dyn FeatureSync>], // data sources first
    vec![cached.clone() as Arc<dyn FeatureSync>],   // caches second
);
App::bind::<dyn FeatureSync>(composite);
```

`features::sync::notify(feature, scope_key)` resolves `Arc<dyn FeatureSync>` from the container and awaits `on_flag_changed`. No-op when no sync is bound - the right behaviour for out-of-process admin tools that only write the DB and have no live evaluator to refresh.

## Bootstrap helper

`bootstrap_database_cached(ttl)` wires everything in one call:

```rust
let features = bootstrap_database_cached(Duration::from_secs(60))
    .await
    .expect("feature flags wired");

// Optional: hold onto features.database to schedule periodic reloads or
// expose admin diff views. Most apps drop the handle and let
// notify-driven refresh do the work.
```

What it does:

1. Constructs `DatabaseEvaluator` against the primary DB connection.
2. Wraps it in `CachedEvaluator` with the requested TTL.
3. Calls `install_evaluator(cached)` - sets the global featureflag default *and* flips a framework-owned "installed" tracker so the middleware doesn't log the "no evaluator" warning.
4. Builds a `CompositeFeatureSync` with the right slot order and binds it into the App container.

Returns `BootstrappedFeatures { database, cached }` for callers that want direct handles to either layer.

If your topology isn't `Cached(Database)` - a Redis-backed cache, a remote sync source, a multi-tier chain - wire the chain manually using the same primitives. `bootstrap_database_cached` is convenience, not a contract.

## Migrations

The framework owns the `features` table schema:

```rust
// app/src/migrations/mod.rs
vec![
    // ... your app's migrations ...
    Box::new(suprnova::features::migrations::CreateFeaturesTable),
    Box::new(suprnova::features::migrations::FeatureTimestampsToDatetime),
    Box::new(suprnova::features::migrations::FeaturesToPennantLayout),
]
```

The table is laravel/pennant's `features`, so the framework reads and writes
the flags a Laravel application stored with Pennant:

```sql
features (
    id          BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
    name        VARCHAR(255) NOT NULL,
    scope       VARCHAR(255) NOT NULL,
    value       TEXT        NOT NULL,
    created_at  DATETIME    NULL,
    updated_at  DATETIME    NULL,
    UNIQUE INDEX (name, scope)
)
```

That is the MySQL shape of the table `CreateFeaturesTable` creates; Pennant's
own migration says `TIMESTAMP`, and a table Pennant created is left exactly
as it is. A flag's framework scope key maps to Pennant's `scope`:

| Scope key | Stored `scope` |
|---|---|
| `""` (global) | `__laravel_null` |
| `user:42` | `App\Models\User\|42`, or `{FEATURES_USER_SCOPE}\|42` |
| anything else, such as `team:staff` | the key as it is |

`value` holds JSON. The framework stores `true` or `false`, as Pennant does
for an activated or deactivated flag, and reads any stored value other than
`false` as enabled, as Pennant's `active()` does, so a rich value such as
`"blue"` is enabled. Each flag's description and the actor who last changed
it live in the framework's `suprnova_feature_details` table, because
Pennant's has no column for them.

`FeaturesToPennantLayout` moves a `features` table an earlier release
created (`scope_key`, `enabled`, `description`, `updated_by`) into
Pennant's layout with its rows, so no flag changes its answer.
`FeatureTimestampsToDatetime` converts the `TIMESTAMP` columns of such an
earlier table to `DATETIME` on MySQL and MariaDB, keeping the stored UTC
times. See [Running on a Laravel Database](laravel-database.md).

## User and team ids

`UserIdField` and `TeamField` are typed extensions stored in
`featureflag::Context::extensions`. Both are string-typed so opaque framework or
Magnetar user IDs and numeric `app_users.id` values share one evaluation shape.

Building a context manually (outside the middleware):

```rust
use featureflag::context;
use std::sync::Arc;

let ctx = featureflag::evaluator::with_default(cached.clone(), || {
    // string user ids - UUIDs, ULIDs, anything opaque.
    context! { user_id = "01HZK6V3J7Q5G4P8X9N2D1B0M3".to_string(), team = "staff".to_string() }
});

// numeric ids still work - the framework coerces i64 → String at on_new_context time.
let ctx_numeric = featureflag::evaluator::with_default(cached.clone(), || {
    context! { user_id = 42_i64 }
});
```

## Events

Two events fire from the admin CRUD path:

```rust
pub struct FeatureUpdated {
    pub name: String,
    pub scope_key: String,
    pub enabled: bool,
    pub actor_id: Option<String>,
}

pub struct FeatureDeleted {
    pub name: String,
    pub scope_key: String,
    pub actor_id: Option<String>,
}
```

Listen for them via the framework's event dispatcher to feed an audit log, Slack alert, or whatever downstream pipeline you need:

```rust
EventFacade::listen::<FeatureUpdated, _>(Arc::new(FlagChangeAuditor)).await;
```

**`is_enabled` does not fire a read-path event.** Every request that checks a flag would multiply the event volume by the number of flags checked - fine for an audit-of-mutations story, prohibitive for read-path tracing. If your deployment needs sampled read-path audit, layer a custom evaluator that records into a bounded log channel (a Redis stream or a fanout queue, depending on scale).

## Missing-evaluator detection

If `FeatureMiddleware` is installed but no evaluator was registered via `install_evaluator` / `bootstrap_database_cached`, every flag silently returns its compile-time default - a hard misconfiguration to catch in QA. The middleware emits exactly one `tracing::warn!` per process on the first request that observes this state:

```
WARN suprnova::features: FeatureMiddleware is in the stack but no feature-flag evaluator is installed.
     is_enabled!() calls will return compile-time defaults until features::bootstrap_database_cached(...)
     or features::install_evaluator(...) is called during app boot.
```

The flip uses an `AtomicBool::swap` so a concurrent request storm at boot serializes to a single warning emission, not one per worker.

## Testing

Two patterns, depending on what you're verifying.

### Unit-test a Feature in isolation

Use `featureflag::evaluator::with_default` to scope a stand-in evaluator inside a sync closure:

```rust
#[test]
fn flag_enabled_returns_new_path() {
    use featureflag::evaluator::with_default;
    use suprnova::features::DatabaseEvaluator;

    let flagger = Arc::new(tokio_test::block_on(async {
        let e = DatabaseEvaluator::new_in_memory().await.unwrap();
        e.set_flag("new-checkout-flow", "", true).await.unwrap();
        e
    }));

    with_default(flagger, || {
        assert!(crate::features::NEW_CHECKOUT_FLOW.is_enabled());
    });
}
```

`DatabaseEvaluator::new_in_memory()` is a test-only helper that boots its own SQLite + runs `CreateFeaturesTable` so the test stays hermetic. Don't use it in production paths.

### Integration-test propagation end-to-end

Use `TestDatabase::fresh::<TestMigrator>()` for the DB and `TestContainer::bind` (NOT `App::bind`) for the FeatureSync - parallel tests on the same process would otherwise overwrite each other's binding via the global container:

```rust
#[tokio::test]
async fn admin_upsert_propagates_to_cached_chain() {
    use std::sync::Arc;
    use std::time::Duration;
    use suprnova::features::sync::FeatureSync;
    use suprnova::features::{admin, CachedEvaluator, CompositeFeatureSync, DatabaseEvaluator};
    use suprnova::features::migrations::CreateFeaturesTable;
    use suprnova::testing::{TestContainer, TestDatabase};

    struct TestMigrator;
    impl sea_orm_migration::MigratorTrait for TestMigrator {
        fn migrations() -> Vec<Box<dyn sea_orm_migration::MigrationTrait>> {
            vec![Box::new(CreateFeaturesTable)]
        }
    }

    let _db = TestDatabase::fresh::<TestMigrator>().await.unwrap();

    let database = Arc::new(DatabaseEvaluator::new().await.unwrap());
    let cached = Arc::new(CachedEvaluator::new(
        database.clone() as Arc<dyn featureflag::evaluator::Evaluator + Send + Sync>,
        Duration::from_secs(60),
    ));
    let composite = Arc::new(CompositeFeatureSync::new(
        vec![database.clone() as Arc<dyn FeatureSync>],
        vec![cached.clone() as Arc<dyn FeatureSync>],
    ));
    TestContainer::bind::<dyn FeatureSync>(composite);

    let ctx = featureflag::evaluator::with_default(cached.clone(), || {
        featureflag::context! { user_id = "user-42".to_string() }
    });

    assert_eq!(cached.is_enabled("new-feature", &ctx), None);
    admin::upsert("new-feature", "", true, None, None).await.unwrap();
    assert_eq!(cached.is_enabled("new-feature", &ctx), Some(true)); // propagates instantly
}
```

See `framework/tests/features/features.rs` for the full set of composition tests.

### Why Suprnova diverges

Laravel Pennant resolves every flag against the database on demand (with optional driver-level memoization per request). The PHP request-per-process model makes a per-request DB hit cheap because the connection is dedicated and dies with the request.

Suprnova's process model is the opposite - one long-running binary serving thousands of concurrent requests. A per-request DB hit on every flag check would multiply the connection pool's load by the flag-check count. The two-layer chain (`DatabaseEvaluator` snapshot + `CachedEvaluator` TTL) is the Rust-native answer: the hot path is fully synchronous against in-memory data, and the `FeatureSync` trait gives operator-initiated changes sub-second propagation without a polling reload. The shape is the same as Pennant - define a flag, check it in a handler, override it from an admin route. The plumbing is different because the runtime is different.

## Design notes

- **Why a sync evaluator over async?** featureflag's `is_enabled` is the hot path. An async evaluator would force a `block_on` (deadlock-prone) or push every handler to `.await` on flag reads (ergonomic disaster). The framework bridges sync ↔ async via an in-memory snapshot refreshed asynchronously by `FeatureSync`.

- **Why a separate `FeatureSync` trait instead of extending `Evaluator`?** featureflag's `Evaluator` is owned by an upstream crate; we can't add methods to it. `FeatureSync` is a sibling trait apps implement on the same concrete types. The trait object is bound separately in the App container so a process can layer multiple evaluators while still routing notifications correctly.

- **Why is `set_flag` `pub` on `DatabaseEvaluator`?** Test convenience. The production write path is `admin::upsert`; `set_flag` exists so tests can seed flags without setting up an `EventFacade` listener. Both paths call `features::sync::notify` so the propagation contract holds either way.

- **Why no `FeatureRetrieved` event?** Volume. A handler checking ten flags per request fires ten events per request - for a 1k req/s service that's 36M events/hour, far above any audit pipeline's signal-to-noise ratio. Mutation-path audit (`FeatureUpdated` / `FeatureDeleted`) is what ships; read-path sampling, if needed, layers on top via a custom evaluator wrapper.

## Next

- [Middleware](middleware.md) - `FeatureMiddleware` belongs after `SessionMiddleware`; this chapter covers ordering and the global stack
- [Events](events.md) - listen to `FeatureUpdated` / `FeatureDeleted` to drive audit logs, Slack alerts, or downstream pipelines
- [Service Container](container.md) - how the `dyn FeatureSync` binding is resolved, and why `TestContainer::bind` exists for parallel tests
- [Testing](testing.md) - `TestDatabase::fresh::<M>()` and `TestContainer::fake` patterns this chapter relies on
- [Authentication](authentication.md) - `Auth::id()` is the default user-id extractor and feeds `actor_id` for admin mutations

External: the [featureflag crate docs](https://docs.rs/featureflag) cover the upstream `Evaluator`, `Context`, and `Feature` primitives. `suprnova::features::admin` is the full CRUD facade - `cargo doc --open -p suprnova` to browse.


---

<!-- /docs/observability -->

# Observability

Three layers of operator-visible signal ship in the framework: structured
logs (always on), per-request id correlation (always on, propagates into
spawned tasks), and an opt-in OpenTelemetry bridge that turns every
`tracing` span into an exported OTel span. The same `#[tracing::instrument]`
you'd write for local logs becomes a distributed-trace span when the OTel
feature is on - no second instrumentation API.

```rust
use suprnova::telemetry::{init_telemetry, OtelConfig};
use suprnova::logging::LogConfig;

#[suprnova::main]
async fn main() {
    let guard = init_telemetry(LogConfig::from_env(), OtelConfig::from_env());

    // ... run the app ...

    // Flush buffered telemetry before exit. The OTel batch processors hold
    // spans/metrics/logs in memory; dropping the guard without `shutdown`
    // loses whatever hasn't been exported yet.
    guard.shutdown().await;
}
```

A scaffolded app's `Server` already calls `init_telemetry` for you and
flushes the guard on the shutdown signal - you only wire it by hand when
embedding Suprnova in your own runtime.

## The three layers

| Layer | Always on | What it gives you |
|---|---|---|
| Structured logging (`tracing`) | Yes | Stdout logs in `pretty` (dev) or `json` (production) format, environment-aware |
| Request-id correlation | Yes | Per-request id scoped through a `tokio::task_local!`, echoed on `X-Request-Id`, propagates into `spawn_with_request_id` tasks |
| OpenTelemetry export | `otel` feature + collector endpoint | OTLP HTTP/proto export of traces, metrics, and logs; W3C `traceparent` propagation both ways |

The OTel layer is **opt-in at compile time** so default builds carry no
OpenTelemetry dependencies and the [`Metrics`](#metrics) facade compiles to
inert no-ops. With the feature off, "trace" and "metric export" silently
become no-ops - your logs still work.

### Why Suprnova diverges

Laravel's observability story splits between in-framework events
(`QueryExecuted`, `MessageSent`, `JobProcessed`) and runtime concerns
delegated to PHP extensions (OpenTelemetry, Sentry, New Relic) plugged in
at the FPM layer. The event surface is rich; the runtime surface is
"install the extension your APM vendor needs."

Suprnova is a single async process, so it owns both halves. The event
surface is parity (same `QueryExecuted`/`NotificationSent`/`ErrorOccurred`
shape), and the runtime surface is a `tracing` → OpenTelemetry bridge
inside the framework. You don't install an extension; you flip a feature
flag and the same spans you already emit become OTel-exported.

## Structured logging

`LogConfig::from_env()` reads two env vars:

| Var | Default | Notes |
|---|---|---|
| `LOG_LEVEL` | `"info"` | `tracing-subscriber` env-filter syntax (e.g. `"debug,sqlx=warn,hyper=warn"`) |
| `LOG_FORMAT` | environment-aware | `"json"` in production, `"pretty"` everywhere else; explicit value always wins |

The format default is detected from `APP_ENV` via `Environment::detect()`:
a production deploy gets one-JSON-object-per-line output for log
aggregators by default, local/dev runs get human-readable multi-line
output. An explicit `LOG_FORMAT=pretty` will override the production
default if you want raw stdout in production.

```bash
# Local dev - explicit overrides win
LOG_LEVEL=debug,sqlx=warn,hyper=warn LOG_FORMAT=pretty cargo run

# Production - APP_ENV=production flips the format default to json
APP_ENV=production LOG_LEVEL=info cargo run --release
```

A malformed `LOG_LEVEL` directive does not crash boot - it falls back to
`"info"` and prints a one-line warning on stderr so the misconfiguration
is operator-visible.

### Span context in every line

Every routed HTTP request runs inside a `request` span created by the
framework's outermost middleware. The span carries three fields -
`request_id`, `method`, `path` - and the JSON formatter nests them under
`span` on every event emitted inside the request. Your application code
doesn't need to read or record the id on every line; the span carries it
implicitly:

```rust
use tracing::info;

pub async fn show(req: suprnova::Request) -> suprnova::Response {
    info!(user_id = 42, "loaded dashboard");
    // JSON line carries span.request_id / span.method / span.path
    // without the call site having to thread anything in.
    Ok(suprnova::json_response!({ "ok": true }))
}
```

## Request-id correlation

Every request gets a 36-character lowercase UUID v4 id, scoped through a
`tokio::task_local!`. The middleware reuses an inbound `X-Request-Id`
when the header value passes a strict safety check (ASCII alphanumeric
plus `-_.:`, max 128 bytes); anything outside that charset is rejected
and replaced with a fresh UUID so an attacker cannot inject control
characters into log output or balloon downstream pipelines.

The same id is echoed on **every** response - success, error, and panic
recovery - as the `X-Request-Id` header, so a frontend or upstream
service can include it in bug reports and operators can grep for it in
the structured log.

### Reading the id

```rust
use suprnova::{current_request_id, spawn_with_request_id, HttpResponse};

pub async fn checkout(req: suprnova::Request) -> suprnova::Response {
    // Inside a request, the id is always present.
    let id = current_request_id().expect("inside a request");
    tracing::info!(request_id = %id, "checkout starting");

    // Background work spawned from a handler. `tokio::spawn` starts a
    // task with empty task-locals - the spawned future would lose the
    // request id without help. `spawn_with_request_id` captures the
    // caller's id and re-scopes it for the spawned future, and attaches
    // the current `tracing` span so the task's events inherit
    // `request_id` the same way in-request events do.
    spawn_with_request_id(async move {
        // This log line carries the originating request's id.
        tracing::info!("post-checkout fanout running");
    });

    Ok(HttpResponse::ok())
}
```

`current_request_id()` returns `None` outside a request - background
jobs, scheduled tasks, and tests without the middleware see no id, and
the helper does not invent one. `spawn_with_request_id` outside a
request scope is exactly `tokio::spawn`; nothing magical happens.

### Where the id is also available

| Surface | How |
|---|---|
| `tracing` events | `span.request_id` on every line inside the request |
| Response header | `X-Request-Id` on success, error, and panic-recovered responses |
| `Context` bag | `Context::get("_request_id")` - readable from observers, listeners, jobs that consult `Context` |
| Spawned tasks | `current_request_id()` after `spawn_with_request_id` |

## Built-in events for observability

The framework dispatches typed events at the points an operator usually
wants to instrument. Each is a `suprnova::Event` you can `listen` for via
`EventFacade::listen::<E, _>(...)` and ship to Sentry, Datadog, Slack, or
your metrics pipeline. All of them run through `dispatch_best_effort`, so
a failing listener does not break the request that triggered it.

| Event | When it fires | Carries |
|---|---|---|
| `ErrorOccurred` | Any `FrameworkError` → 5xx conversion (including panic recovery) | error context + request id |
| `QueryExecuted` | Every query routed through the instrumented executor helpers | sql, bindings, duration, connection, read/write classification, result |
| `ConnectionEstablished` | `DbConnection::connect` succeeded | connection name |
| `TransactionBeginning` / `TransactionCommitted` / `TransactionRolledBack` | Closure-form `DB::transaction` + manual handles | connection name |
| `NotificationSending` / `NotificationSent` / `NotificationFailed` | Per-channel before/after/error of `Notification::send` | notification + channel + recipient |

`ErrorOccurred` is the hook for shipping 5xx exceptions; `QueryExecuted`
is the hook for slow-query alerts; the notification trio is the hook for
delivery dashboards. See [Events](events.md) for the listener API and
[Lifecycle](lifecycle.md) for where in the request path each event fires.

### Direct DB query observation

`DB::listen` is a second, synchronous hook tailored specifically for
`QueryExecuted`. It fires inline inside the executor, so a slow listener
slows the query - keep it light. The dispatcher path
(`EventFacade::listen::<QueryExecuted, _>`) is run-them-all
best-effort and tolerates errors; prefer it for anything that can fail.

```rust
use suprnova::DB;

// In bootstrap.rs:
DB::listen(|q| {
    if q.time > std::time::Duration::from_millis(100) {
        tracing::warn!(
            sql = %q.sql,
            ms = q.time.as_millis(),
            "slow query"
        );
    }
})?;
```

A listener that itself issues a database query will **not** re-fire
`QueryExecuted` for the nested call - a task-local re-entrancy guard
prevents the "log-to-DB listener → emits event → log-to-DB → ..." loop.

### Capturing a query log for tests / debug

For test assertions or one-off "what ran during this block?" debugging:

```rust
use suprnova::DB;

DB::enable_query_log()?;
// ... run the code you want to inspect ...
let queries = DB::get_query_log()?;
for q in &queries {
    println!("{:>4}ms  {}", q.time.as_millis(), q.to_raw_sql());
}
DB::disable_query_log()?;
DB::flush_query_log()?;
```

The buffer is **unbounded** - every captured query grows it. Use it for
tests and one-shot investigation, flush periodically if you leave it on
in production.

In a test, the log and any `DB::listen` callback belong to the test
container that `TestDatabase` or `TestContainer::fake` starts, so they
hold only the queries of that test. For more information, see
[Listeners and the query log in tests](database.md#listeners-and-the-query-log-in-tests).

## Distributed tracing (OTel)

Add the `otel` feature to opt in:

```toml
[dependencies]
suprnova = { git = "...", features = ["otel"] }
```

Configure via the standard OTel environment variables:

```bash
# Minimum: where the collector lives.
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=my-app          # defaults to "suprnova"
OTEL_SERVICE_VERSION=1.4.2        # defaults to your crate version
```

Telemetry is **enabled** only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set
**and** the kill switch `OTEL_SDK_DISABLED` is not on. With no endpoint
the logging layer runs alone, and the returned guard holds no providers,
so dropping it without `shutdown()` is silent (no spurious "buffered
telemetry may be lost" warning on every test process).

### Trace context joins automatically

**Inbound.** When a request arrives carrying a W3C
[`traceparent`](https://www.w3.org/TR/trace-context/) header - i.e. it
was made by another traced service - the middleware extracts that
context and reparents the request span onto the caller's span. Your
server span shows up as a child in the *same* distributed trace, not a
fresh root. A request without `traceparent` (a direct browser hit) stays
a clean root span.

**Outbound.** The framework HTTP client ([`Http`](http-client.md))
injects the active trace context as `traceparent` on every outbound
call, so the downstream service continues the same trace.

Together: `upstream service → your handler → downstream service` is one
connected trace, with no manual span plumbing in your handlers.

**Error status.** When a handler returns a 5xx, the request span is
marked errored so the OTel backend shows `Status::Error`. (A handler
*panic* is caught and turned into a 500 with an error-level log and an
`ErrorOccurred` event, but the OTel span status is not set on that path -
the panic unwinds the span's future before the marker runs.)

### Adding your own spans

Because the bridge turns every `tracing` span into an OTel span, you
instrument with plain `tracing` - no OTel-specific API in your code:

```rust
use suprnova::DatabaseConnection;

#[tracing::instrument(skip(db))]
async fn load_dashboard(db: &DatabaseConnection, user_id: i64) -> anyhow::Result<()> {
    // This span nests under the request span automatically, and exports
    // to your collector when the `otel` feature is on.
    Ok(())
}
```

### Environment variables Suprnova reads

| Var | Effect |
|---|---|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Collector base URL. Unset or blank → telemetry disabled. Each signal is posted to its own path under it. |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Full URL for traces, used as written. Takes precedence over the base URL for traces. |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Full URL for metrics, used as written. Takes precedence over the base URL for metrics. |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Full URL for logs, used as written. Takes precedence over the base URL for logs. |
| `OTEL_SERVICE_NAME` | `service.name` resource attribute (default `"suprnova"`). |
| `OTEL_SERVICE_VERSION` | `service.version` resource attribute (default: crate version). |
| `OTEL_SDK_DISABLED` | Kill switch. Case-insensitive `true` or `1` disables export even with an endpoint set. |

The rest of the standard OTLP knobs are read by the SDK itself, so
configure them the normal way:

| Var | Read by |
|---|---|
| `OTEL_EXPORTER_OTLP_HEADERS` | exporter (collector auth, e.g. `Authorization=Bearer ...`) |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | exporter (`http/protobuf`, the protocol the build compiles in) |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | exporter |
| `OTEL_EXPORTER_OTLP_COMPRESSION` | exporter (`gzip` is supported; `zstd` is not) |

#### Where each signal is sent

`OTEL_EXPORTER_OTLP_ENDPOINT` is a base URL. Suprnova posts each signal to
its own path under it:

| Signal | URL posted to |
|---|---|
| Traces | `<base>/v1/traces` |
| Metrics | `<base>/v1/metrics` |
| Logs | `<base>/v1/logs` |

A trailing slash on the base is ignored. With
`OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`, traces go to
`http://localhost:4318/v1/traces`.

The three per-signal variables hold a full URL. Suprnova uses it as
written and adds no path, so include the path your collector expects. A
per-signal URL takes precedence over the base URL for its signal, so traces,
metrics and logs can go to different collectors:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4318/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://mimir:9009/otlp/v1/metrics
# Logs have no variable of their own: http://localhost:4318/v1/logs
```

The base endpoint is what turns telemetry on. If it is not set, a per-signal
variable has no effect.

An endpoint must be an `http` or `https` URL with a host. A signal whose
endpoint is not one is left out, the reason is written to the log, and the
other signals are still exported. The reason never repeats the URL, because
a URL can carry a password or a token.

`OTEL_EXPORTER_OTLP_COMPRESSION=gzip` works. `zstd` is not compiled in: if you
ask for it, the signals are left out and the reason is written to the log.

## Metrics

`Metrics` is the facade for counters, histograms, and gauges. Handles
are cheap to clone and resolve the global meter on each construction:

```rust
use suprnova::telemetry::Metrics;

// Counter - monotonic.
let signups = Metrics::counter("user.signups");
signups.inc();                                  // +1
signups.inc_by(3);                              // +3
signups.inc_with(&[("plan", "pro")]);           // +1 with a label

// Histogram - distributions (latency, sizes).
let latency = Metrics::histogram("request.latency_ms");
latency.record(42.0);
latency.record_with(42.0, &[("route", "/checkout")]);

// Gauge - point-in-time value.
let queue_depth = Metrics::gauge("jobs.pending");
queue_depth.set(17.0);
queue_depth.set_with(17.0, &[("queue", "emails")]);
```

Without the `otel` feature every call above is a no-op with zero
allocation - leave instrumentation in hot paths and pay nothing in
default builds.

Metric handles bind to whichever meter provider is active when the
underlying instrument is first resolved. Create handles **after**
`init_telemetry` has run (or lazily at first use) - a handle constructed
before initialization resolves against the no-op provider and stays
inert. The idiomatic pattern is a `once_cell` / `LazyLock` handle
resolved on first emit, well after boot.

### Attribute values are typed

`inc_with`, `record_with` and `set_with` take a slice of
`(&'static str, V)` pairs, where `V` converts into `AttrValue`. A backend
treats an attribute by its type, so a status `404` sent as text matches no
filter on a number. `AttrValue` has four variants, and each arrives at the
backend as its own OpenTelemetry type:

| Variant | OpenTelemetry type | Made from |
|---|---|---|
| `AttrValue::Text(&str)` | string | `&str`, `&String`, `&&str`, `&Box<str>`, `&Arc<str>`, `&Rc<str>`, `&Cow<str>` |
| `AttrValue::Int(i64)` | int | `i64`, `i32`, `i16`, `i8`, `u32`, `u16`, `u8`, `u64`, `usize`, `isize` |
| `AttrValue::Float(f64)` | double | `f64`, `f32` |
| `AttrValue::Bool(bool)` | boolean | `bool` |

A `u64`, `usize` or `isize` value that does not fit an `i64` is sent as the
nearest `i64` limit. The measurement is not lost.

When every value in the slice has one type, write the values as they are.
When the types differ, make each value an `AttrValue` with `AttrValue::from`,
so the slice has one element type:

```rust
use suprnova::{AttrValue, Metrics};

let requests = Metrics::counter("http.requests.total");

// One type for every value.
requests.inc_with(&[("route", "/posts"), ("method", "GET")]);
requests.inc_with(&[("http.response.status_code", 404)]);

// Several types: each value is an `AttrValue`.
requests.inc_with(&[
    ("route", AttrValue::from("/posts")),
    ("http.response.status_code", AttrValue::from(404)),
    ("error", AttrValue::from(true)),
]);
```

For a call with no attributes, use `inc()`, `record(value)` or `set(value)`.
An empty slice, `inc_with(&[])`, does not compile, because an empty list has
no type for its values.

`AttrValue` is `#[non_exhaustive]`, so a `match` on it needs a wildcard arm.

Naming: stable, ASCII, dot-delimited (e.g. `"http.requests.total"`,
`"http.request.duration"`). The standard OTel semantic conventions live
in `opentelemetry-semantic-conventions::metric::*`.

## The shutdown contract

`init_telemetry` returns a `TelemetryGuard` that owns the SDK provider
handles. The OTel batch processors buffer spans / metrics / logs in
memory and flush asynchronously, so you must `guard.shutdown().await`
before the process exits or you lose whatever is still buffered.

- Calling `shutdown()` flushes and is safe to call once (it takes
  `self`).
- Dropping the guard **without** `shutdown()` logs a warning - but only
  when the guard actually holds providers. A telemetry-disabled run (no
  endpoint, or `OTEL_SDK_DISABLED`, or a non-`otel` build) hands back a
  provider-less guard whose drop is silent, so collector-less dev and
  test runs don't get spammed.
- A second `init_telemetry` call while a guard still holds providers
  changes nothing: it builds and installs no providers, and returns a
  provider-less guard. The first guard stays in charge of the global
  tracer and meter providers, so shutting the second one down can't stop
  the `Metrics` facade. Once the first guard is dropped, with
  `shutdown()` or without it, the next call installs providers again.

## Summary

| Task | API |
|---|---|
| Enable OTel | `features = ["otel"]` + `OTEL_EXPORTER_OTLP_ENDPOINT` |
| Initialize | `init_telemetry(LogConfig::from_env(), OtelConfig::from_env())` |
| Flush on exit | `guard.shutdown().await` |
| Disable at runtime | `OTEL_SDK_DISABLED=true` |
| Custom span | `#[tracing::instrument]` (auto-bridged to OTel) |
| Counter / histogram / gauge | `Metrics::counter/histogram/gauge(name)` |
| Distributed trace join | Automatic - inbound `traceparent` extracted, outbound injected |
| Read current request id | `current_request_id()` |
| Propagate id into spawn | `spawn_with_request_id(future)` |
| Synchronous query observer | `DB::listen(|q| { ... })` |
| Best-effort query observer | `EventFacade::listen::<QueryExecuted, _>(...)` |
| Capture queries for tests | `DB::enable_query_log()` → `DB::get_query_log()` |

## Next

- [Events](events.md) - listener API, dispatch modes, `EventFacade::fake()` for tests
- [Lifecycle](lifecycle.md) - where in the request path each event fires and where the request span is constructed
- [Error Handling](errors.md) - `ErrorOccurred`, `HttpError`, sanitised 5xx bodies
- [Database](database.md) - `QueryExecuted`, `DB::transaction`, the executor helpers that fire the events
- [HTTP Client](http-client.md) - outbound `traceparent` injection that closes the distributed-trace loop


---

<!-- /docs/vector -->

# Vector

Suprnova ships a Laravel-shape `Vector` facade backed by one of five
drivers - in-process Memory, Qdrant, Pinecone, MariaDB native
`VECTOR(N)`, or Postgres with pgvector - picked explicitly at boot via `Vector::register`. The
facade is a thin layer over a `VectorDriver` trait, so custom backends
plug in the same way the built-ins do.

## Quickstart

```rust
use std::sync::Arc;
use suprnova::{MemoryVectorDriver, Vector, VectorItem};

// Bootstrap (typically once at app start)
Vector::register("documents", Arc::new(MemoryVectorDriver::new()));

// Use it
let store = Vector::store("documents")?;
store
    .upsert(vec![
        VectorItem::new("doc-1", embedding_for("Hello"), serde_json::json!({ "title": "Hello" })),
        VectorItem::new("doc-2", embedding_for("World"), serde_json::json!({ "title": "World" })),
    ])
    .await?;

let hits = store.similar(query_embedding, 10).await?;
for hit in hits {
    println!("{}: {} (score {:.3})", hit.id, hit.metadata["title"], hit.score);
}
```

## The contract

```rust
#[async_trait]
pub trait VectorDriver: Send + Sync + 'static {
    async fn upsert(&self, store: &str, items: Vec<VectorItem>) -> Result<(), FrameworkError>;
    async fn similar(&self, store: &str, query: Vec<f32>, k: usize) -> Result<Vec<VectorMatch>, FrameworkError>;
    async fn delete(&self, store: &str, ids: Vec<String>) -> Result<(), FrameworkError>;
    async fn count(&self, store: &str) -> Result<usize, FrameworkError>;
}
```

`VectorItem` carries an arbitrary `String` id, an `embedding: Vec<f32>`, and freeform `metadata: serde_json::Value` (must be a JSON object or `null`). `VectorMatch` returns the original id, the backend's similarity score, and the same metadata shape.

The trait is intentionally small. When you need filter expressions on search, sparse vectors, scroll/list, snapshots, or quantization knobs, drop down to the driver's underlying SDK via its public `client()` trapdoor.

### Why Suprnova diverges

Laravel ships vectors only through Postgres `pgvector`. That's the
PHP-shape answer: pick one storage backend, hide it behind a single
driver, and call it done. Suprnova treats the choice as a configuration
concern. The same trait covers an in-process `HashMap` for tests,
a dedicated vector DB (Qdrant, Pinecone) when the embedding count
justifies the operational cost, and a relational backend (MariaDB
11.7+, or Postgres with pgvector) when you'd rather keep vectors next to
the rows that produced them. Weaviate, Milvus, LanceDB, and LibSQL queue up
behind real consumer demand - none are blocked by the trait shape.

When the rest of your app fits on one engine, MariaDB 11.7+ keeps
vectors alongside relational tables, JSON documents, and
system-versioned temporal data - fewer moving parts than running
Postgres + Redis + Qdrant separately. See [Deployment](deployment.md)
for the recommendation in context.

## Drivers

### Memory - `MemoryVectorDriver`

In-process driver backed by `HashMap`. Cosine similarity, dimension-mismatch points are silently skipped on query (so mixed-dim test data doesn't blow up), zero-vector queries error clearly.

```rust
Vector::register("docs", Arc::new(MemoryVectorDriver::new()));
```

Use in tests and dev. Each `MemoryVectorDriver::new()` instance is hermetic - no shared state between two `new()`s.

### Qdrant - `QdrantVectorDriver`

Talks to Qdrant over gRPC (default port 6334) via the official `qdrant-client` SDK.

```rust
use suprnova::{QdrantDistance, QdrantVectorDriver};

let driver = QdrantVectorDriver::from_url("http://localhost:6334")?
    .with_distance(QdrantDistance::Cosine)  // default
    .with_auto_create(true);                // default

Vector::register("docs", Arc::new(driver));
```

For Qdrant Cloud:

```rust
let driver = QdrantVectorDriver::from_url_with_api_key(
    "https://xxxxxxxx.eu-central.aws.cloud.qdrant.io:6334",
    std::env::var("QDRANT_API_KEY")?,
)?;
```

To choose the store by environment, call `from_env`:

```rust
let driver = QdrantVectorDriver::from_env()?;
```

| Variable | Required | Meaning |
|---|---|---|
| `QDRANT_URL` | Yes | The gRPC URL, by default port 6334 |
| `QDRANT_API_KEY` | No | The key of Qdrant Cloud, or of a self-hosted instance that asks for one |

A missing or blank `QDRANT_URL` is an error at boot. The error names the
variable and never repeats its value. `from_env` builds the client without
the Qdrant client's version check, which connects to the server and blocks
the thread while the application boots. The first request connects.

**ID mapping.** Qdrant requires point IDs to be either `u64` or a valid UUID. The framework bridges arbitrary strings with three rules:

1. If the string is the canonical decimal spelling of a `u64` (no sign, no leading zero), use the `Num(u64)` variant.
2. If the string is a UUID in its canonical spelling (lowercase, hyphenated) and not of version 5, use the `Uuid(String)` variant verbatim.
3. Otherwise, derive a deterministic v5 UUID from a stable namespace.

The id is a merge key, so `"1"`, `"01"`, and `"+1"` are three items, as they are in every other driver. Only the canonical spellings map to native ids, because Qdrant would read `"01"` as point `1`, and every spelling of one UUID as one point. A version 5 UUID is derived like any other string, because rule 3 produces version 5 UUIDs: taken verbatim, a caller could name the point of another id. Items written before these rules with a non-canonical numeric or UUID id, or with a version 5 UUID, now resolve to a derived id; rewrite them (upsert, then delete the old point through `driver.client()`) to keep one point per item.

The caller's original string is stashed in the point's payload under the reserved key `__suprnova_id` (exported as `SUPRNOVA_ID_PAYLOAD_KEY`) and stripped from `VectorMatch.metadata` on retrieval. Power users who query Qdrant directly via `driver.client()` can filter on `__suprnova_id` to bridge framework writes with direct calls.

**Auto-create.** On first `upsert` for an unseen collection, the driver creates it with the dimension inferred from the first item and the configured distance metric (Cosine by default). Race-safe - concurrent upserters on the same fresh collection won't fail; whichever creates first wins, the other proceeds. Disable via `.with_auto_create(false)` to require explicit creation.

**Cache invalidation.** If a collection is dropped externally (or Qdrant restarts before persistence flushed), the driver detects the "not found" error on upsert, drops the cache entry, re-runs `ensure_collection`, and retries once.

**Trapdoor.** `driver.client()` returns the underlying `qdrant_client::Qdrant` - use it for filter expressions on search, scroll, snapshots, or other APIs not surfaced via the trait. `QdrantVectorDriver::resolve_point_id`, `build_point`, and `decode_match` let you mix direct and trait-routed calls without losing id translation.

**Local setup.** Run Qdrant via Docker:

```bash
docker run -p 6334:6334 -p 6333:6333 qdrant/qdrant
```

Integration tests run via:

```bash
QDRANT_URL=http://localhost:6334 cargo test -p suprnova --test vector -- --ignored qdrant::
```

### Pinecone - `PineconeVectorDriver`

> **Feature-gated - off by default.** Enable with `cargo build --features vector-pinecone` (or add `features = ["vector-pinecone"]` under the `suprnova` dep in your `Cargo.toml`). The feature costs no extra dependencies - it gates compilation of the driver, nothing more - so it is off simply because most apps don't use Pinecone and shouldn't pay to compile it.

Talks to Pinecone over its REST API, using the HTTP client the framework already carries.

> **Why not the official SDK?** The driver used to wrap `pinecone-sdk`, which uses gRPC. That crate's newest release (0.1.2, published 2024-09-06) pins `tonic 0.11 → rustls 0.22 → rustls-webpki 0.102`, and `rustls-webpki 0.102` carries four RustSec advisories that are all fixed upstream in `>= 0.103.13`. One abandoned crate held the whole tree back, with no version of "wait for upstream" that was going to end. Pinecone exposes every operation this driver needs over HTTPS, so the REST route removed four advisories and two dependencies at once.

```rust
use suprnova::PineconeVectorDriver;

// API key directly
let driver = PineconeVectorDriver::from_api_key(std::env::var("PINECONE_API_KEY")?)?;

// Or via env: PINECONE_API_KEY, plus optional PINECONE_CONTROLLER_HOST
// and PINECONE_API_VERSION
let driver = PineconeVectorDriver::from_env()?;

// Bind to a non-default namespace
let driver = driver.with_namespace("public");

Vector::register("docs", Arc::new(driver));
```

The store name passed via `Vector::store(name)` maps to a Pinecone index name. The driver resolves that index's host lazily on first use via the control plane's `GET /indexes/{name}`, then caches it. Skip the round trip by pinning the host you already know:

```rust
let driver = PineconeVectorDriver::from_env()?
    .with_index_host("docs", "docs-abc123.svc.aped-1234.pinecone.io");
```

A host learned from the control plane is always contacted over `https`, whatever the response says. A host pinned through `with_index_host` keeps the scheme you gave it, so a local emulator on `http://` works.

**API version.** Pinecone versions its REST API by date and wants that version pinned in a header. The driver pins `2025-04` - the version its request and response shapes were written and tested against - and exposes `with_api_version` (or `PINECONE_API_VERSION`) for moving deliberately. It does not float: the namespace-key convention in `describe_index_stats` is one of the things that has changed between versions, and `count()` reads that map.

**No auto-create.** Pinecone index creation requires picking cloud (AWS/GCP/Azure), region, vector dimension, distance metric, and deletion-protection - too many trade-offs to default well. Create indexes via the Pinecone console, the Pinecone CLI, or a `control_plane_post` call before registering, then point the framework at the existing name.

This is the principal asymmetry with the Qdrant driver, which auto-creates collections on first upsert.

**IDs and metadata.** Pinecone accepts arbitrary `String` ids natively, so `VectorItem::id` passes straight through. Metadata is carried as JSON end to end - `PineconeVectorDriver::metadata_from_json` / `metadata_to_json` only enforce the framework's own rule that metadata is an object or null. Pinecone itself restricts metadata *values* to strings, numbers, booleans and lists of strings, and rejects nested objects server-side; the driver doesn't re-implement that check, because Pinecone's rules are versioned and a local copy would drift.

**Batch limits.** Pinecone documents a maximum of 1000 vectors per upsert and 1000 ids per delete. The driver sends what you give it in one request rather than chunking silently - a partial-success write is harder to reason about than a rejected one. Batch on your side if you exceed those limits.

**Namespaces.** One driver instance binds to one namespace. To use multiple namespaces of the same index, register one driver per namespace under different store names:

```rust
Vector::register("docs-public", Arc::new(
    PineconeVectorDriver::from_env()?.with_namespace("public")
));
Vector::register("docs-private", Arc::new(
    PineconeVectorDriver::from_env()?.with_namespace("private")
));
```

**Throughput.** Nothing serializes. The driver caches a host string per index, not a connection handle, and requests share `reqwest`'s connection pool - so concurrent calls to the same index proceed concurrently. (The gRPC driver this replaces held one `Index` per name behind a `tokio::Mutex`, because `pinecone-sdk` exposed `Index` only behind `&mut self`.)

**Trapdoor.** `control_plane_get`, `control_plane_post` and `data_plane_post` reach any endpoint Pinecone ships, with your own request and response types, over the driver's authenticated and host-resolved transport - filter expressions, sparse vectors, fetch-by-id, `/vectors/list`, index management:

```rust
#[derive(serde::Deserialize)]
struct FetchResponse { vectors: Vec<suprnova::vector::PineconeVector> }

let hits: FetchResponse = driver.data_plane_post(
    "docs",
    "/vectors/fetch_by_metadata",
    &serde_json::json!({ "filter": { "genre": { "$eq": "comedy" } }, "limit": 2 }),
).await?;
```

**Tests.** Wire-contract tests run by default under the feature: they drive the driver against a local fake and assert the exact method, path, headers and JSON body it puts on the wire. Those pin the driver to Pinecone's *documented* contract. Confirming the documentation matches the live service needs the `#[ignore]`d integration tests, which require both env vars:

```bash
PINECONE_API_KEY=... PINECONE_TEST_INDEX=my-test-index \
    cargo test -p suprnova --features vector-pinecone \
    --test vector -- --ignored pinecone::
```

### MariaDB - `MariaDbVectorDriver`

Talks to MariaDB 11.7+ via direct `sqlx::MySqlPool`, using MariaDB's native `VECTOR(N)` column type and HNSW indexing. The first time you call a driver method, it runs `SELECT VERSION()` and rejects anything below 11.7 - older servers don't have the vector functions.

```rust
use std::sync::Arc;
use suprnova::{MariaDbDistance, MariaDbVectorDriver, Vector};

let driver = MariaDbVectorDriver::from_url(
    "mysql://user:pass@localhost:3306/myapp",
)?
.with_distance(MariaDbDistance::Cosine);  // default

Vector::register("documents", Arc::new(driver));
```

`from_url` takes a `mysql://` or a `mariadb://` URL. It is lazy - it validates the URL syntax but does NOT open a connection until first use, so calling it at app bootstrap is safe even before the database is reachable. Wrap an existing pool with `MariaDbVectorDriver::from_pool(pool)` when you need custom pool options.

To choose the store by environment, call `from_env`. It reads `MARIADB_URL`. When `MARIADB_URL` is not set, it reads `DATABASE_URL` and takes it if the URL names a MariaDB or a MySQL database. That fallback suits an application with one database, a MariaDB, that holds both its rows and its vectors. A `DATABASE_URL` of another engine is not taken.

```rust
let driver = MariaDbVectorDriver::from_env()?;
```

A `mysql://` URL is taken because a MariaDB server is written that way too. If it is the URL of a MySQL server, the driver fails on its first query, because MySQL has no vector functions. When no variable gives a usable URL, `from_env` returns an error that names the variables and never the URL, which carries the password.

**Schema is yours.** The driver does not auto-create tables - schema is a migration concern. The recommended path is `driver.ensure_table_sql_for(name, dim)`, which inherits the driver's configured distance so the migration's `DISTANCE=` clause and the query function `similar` uses are guaranteed to match:

```rust
let driver = MariaDbVectorDriver::from_url(url)?
    .with_distance(MariaDbDistance::Cosine);

let sql = driver.ensure_table_sql_for("documents", 1536)?;
// Result:
// CREATE TABLE IF NOT EXISTS `documents` (
//   id VARBINARY(254) NOT NULL PRIMARY KEY,
//   embedding VECTOR(1536) NOT NULL,
//   metadata JSON NULL,
//   VECTOR INDEX (embedding) DISTANCE=cosine
// ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
```

For migration generators that don't have a driver in scope (CLI tools, build scripts), use the static `MariaDbVectorDriver::ensure_table_sql(name, dim, distance)` and pass the same `MariaDbDistance` you'll later configure on the driver.

**Distance must match on both ends.** MariaDB silently falls back to a full table scan when the function used at query time doesn't match the index's `DISTANCE=` clause. The driver guards against this in two layers:

1. **`ensure_table_sql_for(name, dim)`** reads `self.distance` for both the emitted migration SQL and the runtime function in `similar` - they cannot drift apart by construction.
2. **A runtime check on first `similar` call** runs one `SHOW CREATE TABLE` per store, reads the distance of the vector index from the live schema, and errors clearly if it disagrees with `with_distance(...)`. The server prints the index as `` VECTOR KEY `embedding` (`embedding`) `DISTANCE`=cosine ``, not as the DDL you wrote, and the check reads that form. Result is cached, so subsequent calls are zero-cost. This catches hand-written migrations or `from_pool` setups that bypass `ensure_table_sql_for`.

**Store-name safety.** Store names interpolate into emitted SQL (MySQL doesn't parameterize identifiers). Names are validated as `[A-Za-z_][A-Za-z0-9_]*` of length ≤ 64; the validated name is then backtick-quoted in every statement. Invalid names error with `FrameworkError::param` at the `register`/`upsert`/`similar`/`delete`/`count` boundary.

**IDs and metadata.** The id column takes any `String` id up to 254 bytes of UTF-8 - no UUID derivation, no reserved payload keys. It is `VARBINARY(254)` for two reasons: MariaDB refuses a vector index on a table whose primary key is longer than 256 bytes, which a `utf8mb4` `VARCHAR(255)` key is, and a binary column compares ids byte for byte, so `Doc` and `doc` are two rows, as they are in every other driver. Metadata round-trips through MariaDB's `JSON` column type; `null` metadata stores as SQL `NULL`. Non-object metadata (arrays, primitives) is rejected with `FrameworkError::param` for parity with Qdrant and Pinecone.

**Score normalization.** MariaDB returns raw *distance* (lower = closer). The trait contract is *score* (higher = more similar) - the driver converts per metric:

| Metric    | MariaDB returns       | Exposed `score`              |
| --------- | --------------------- | ---------------------------- |
| Cosine    | `[0, 2]` (`1 - cos`)  | `1.0 - d / 2.0` → `[0, 1]`   |
| Euclidean | `[0, ∞)` L2 norm      | `1.0 / (1.0 + d)` → `(0, 1]` |

In both cases, ranking is preserved (best result first), but the absolute score values are NOT comparable across drivers - only the ordering is. Each backend lands on a `higher = better` convention, but the ranges differ: Memory's cosine returns `[-1, 1]`, MariaDB's normalized cosine returns `[0, 1]`, Qdrant emits its native cosine similarity in `[-1, 1]`, and Pinecone returns the raw similarity for whichever metric the index was created with. Use `score` to sort within a single driver's result set; don't compare numeric scores across drivers without re-normalizing yourself.

**Trapdoor.** `driver.pool()` returns the underlying `sqlx::MySqlPool` for raw queries the trait doesn't cover. `MariaDbVectorDriver::embedding_to_vec_text`, `score_from_distance`, and `ensure_table_sql` are pure functions you can call independently when mixing direct SQL with trait-routed calls.

**Bulk upsert behavior.** `upsert` emits one multi-row `INSERT ... VALUES (...), (...), ...` statement per 500-row chunk, all wrapped in a single transaction. Network round-trips drop ~500x vs per-row inserts when loading a fresh corpus; the call stays atomic across the whole batch. The batch size is internal - call `upsert` once with all your items and the driver handles chunking.

**HNSW indexes rebuild at commit time.** MariaDB updates the HNSW graph as rows go in, but the index work concentrates at commit. A 1M-row `upsert` will hold the transaction open for the full duration of the index build, which can be minutes. For very large initial loads, break the corpus into 10k-100k-row batches and call `upsert` repeatedly so each batch commits and frees the lock between rounds. (Smaller `upsert` calls are not slower per row - they just spread the index work into more commit points.)

**Dimension is pinned at table creation.** `VECTOR(N)` fixes the dimension; switching embedding models from a 768-dim model to a 1536-dim model means a full table migration (new table, re-embed, swap). Plan model upgrades the same way you'd plan a schema migration - there is no "ALTER COLUMN VECTOR(768) → VECTOR(1536)" path.

**Pool sizing.** `from_url` uses sqlx's default `MySqlPoolOptions` - `max_connections = 10` in sqlx 0.9, the version the framework pins. For high-QPS workloads (hundreds of `similar` calls per second), build the pool yourself with `MySqlPoolOptions::new().max_connections(N).connect_lazy(url)` and pass to `from_pool`. The driver doesn't impose its own connection cap.

**Local setup.** Run MariaDB 11.7+ via Docker:

```bash
docker run -p 3306:3306 \
    -e MARIADB_ROOT_PASSWORD=secret \
    -e MARIADB_DATABASE=vectors \
    mariadb:11.7
```

Integration tests run via:

```bash
MARIADB_URL='mysql://root:secret@localhost:3306/vectors' \
    cargo test -p suprnova --test vector -- --ignored mariadb::
```

### pgvector - `PgVectorDriver`

Talks to Postgres through its own `sqlx::PgPool`. The server needs the pgvector package installed and the `vector` extension enabled in the application's database. On first use, the driver checks `pg_extension`; a missing extension produces an error naming the pgvector package and `CREATE EXTENSION vector`. A successful check is cached per driver. Connection and query failures can be retried on the next call.

**Feature.** `vector-pgvector` is on by default beside `vector-mariadb`. It enables `sqlx/postgres` and `database-postgres`. Minimal builds can omit the driver by disabling default features.

`from_url` accepts `postgres://` or `postgresql://` and connects lazily, so registration does not require a reachable server. `from_pool(pool)` accepts a pool with your own connection limits and timeouts. `from_env()` reads `PGVECTOR_URL` first; when it is unset or blank, it takes `DATABASE_URL` only if its scheme is `postgres` or `postgresql`. Errors name the variables without showing the URL, which carries the password.

**Schema is yours.** The driver never creates tables or extensions. Run this SQL in your application migration before using a 1536-dimensional cosine store:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS "documents" (
  id VARCHAR(254) PRIMARY KEY,
  embedding vector(1536) NOT NULL,
  metadata JSONB NULL
);
CREATE INDEX ON "documents" USING hnsw (embedding vector_cosine_ops);
```

Generate migration text with `driver.ensure_table_sql_for("documents", 1536)?` to use the driver's configured distance. The static `PgVectorDriver::ensure_table_sql("documents", 1536, PgVectorDistance::Cosine)?` is available to migration generators without a driver. Both return the extension, table, and index statements above. The index statement creates a new index each time: run the migration once. Use the opclass for the same distance you configure on the driver.

**Distances and scores.** Results are best first, with higher scores meaning more similar. pgvector returns the negative inner product from `<#>` so Postgres can scan the index in ascending order. The driver reverses that sign for the exposed score.

| Distance | Operator | HNSW opclass | Exposed `score` |
| --- | --- | --- | --- |
| Cosine (default) | `<=>` | `vector_cosine_ops` | `1 - distance`, usually `[-1, 1]` |
| Euclidean | `<->` | `vector_l2_ops` | `1 / (1 + distance)`, `(0, 1]` |
| Inner product | `<#>` | `vector_ip_ops` | `-distance`, unbounded |

The cosine score keeps negative similarity; it does not use MariaDB's `[0, 1]` normalization. A zero query under cosine is an error because its direction is undefined. Euclidean and inner product accept zero queries. An empty query or `k == 0` returns an empty list. These formulas follow [pgvector's distance operators](https://github.com/pgvector/pgvector#distances).

**Store-name safety.** Names use `[A-Za-z_][A-Za-z0-9_]*`, at most 63 bytes, so Postgres cannot silently truncate them. Every SQL identifier is validated and double-quoted; every runtime value is bound. IDs round-trip unchanged through `VARCHAR(254)`. Metadata must be a JSON object or null; null is stored as SQL `NULL` in the `JSONB` column.

**Writes.** Upserts use batches of 500 rows with `ON CONFLICT (id) DO UPDATE`; deletes use batches of 1000 IDs. Each call uses one transaction across all batches, so an error rolls the whole call back. Embeddings are bound as text such as `[0.1,0.2,0.3]` and cast to `vector`. Postgres enforces the table's dimension; its error text is preserved in `FrameworkError` with the store name. Changing embedding models to a new dimension requires a migration and re-embedding.

**Example.** After migrating a three-dimensional `documents` table, set `PGVECTOR_URL` or a Postgres `DATABASE_URL` and run:

```rust
use std::sync::Arc;
use suprnova::{FrameworkError, PgVectorDistance, PgVectorDriver, Vector, VectorItem};

#[tokio::main]
async fn main() -> Result<(), FrameworkError> {
    let driver = PgVectorDriver::from_env()?
        .with_distance(PgVectorDistance::Cosine);
    Vector::register("documents", Arc::new(driver));

    let store = Vector::store("documents")?;
    store.upsert(vec![VectorItem::new(
        "doc-1", vec![1.0, 0.0, 0.0], serde_json::json!({"title": "Hello"}),
    )]).await?;
    for hit in store.similar(vec![1.0, 0.0, 0.0], 10).await? {
        println!("{}: {} (score {})", hit.id, hit.metadata["title"], hit.score);
    }
    Ok(())
}
```

**Trapdoor.** `driver.pool()` exposes the `sqlx::PgPool` for joins or queries beyond the trait. `embedding_to_vec_text`, `score_from_distance`, and `ensure_table_sql` keep direct SQL consistent with the driver.

**Tests.** Database-free tests run by default. Integration tests create the extension and a unique table per test, then drop the table. They require a disposable database because the missing-extension test attempts `DROP EXTENSION vector` without `CASCADE`, restores it afterward, and prints a skip reason if the role cannot drop it or other tables depend on it. All Postgres tests share an advisory lock to prevent that test racing the others.

```bash
PG_TEST_URL='postgres://user:pass@localhost:5432/vectors' \
    cargo nextest run -p suprnova --test vector --run-ignored only -E 'test(pgvector::postgres_)'
```

## Driver comparison

| Aspect | Memory | Qdrant | Pinecone | MariaDB | pgvector |
| --- | --- | --- | --- | --- | --- |
| Backing store | `HashMap` | Qdrant gRPC | Pinecone REST | MariaDB SQL | Postgres SQL |
| Persistence | None | Yes | Yes | Yes | Yes |
| Auto-create | n/a | Yes (configurable) | No (user creates index) | No (migration is yours) | No (migration is yours) |
| String IDs | Native | Hashed to UUID-5 | Native | Native | Native |
| Metadata key reserved | None | `__suprnova_id` | None | None | None |
| Throughput | Per-process | Concurrent | Concurrent (pool-bounded) | Concurrent (pool-bounded) | Concurrent (pool-bounded) |
| Distance metric | Cosine | Configurable | Set at index creation | Cosine / Euclidean | Cosine / Euclidean / Inner product |
| Version requirement | - | Any | Any | **11.7+** | Postgres with pgvector and HNSW support |

## Operational notes

**Store name conventions.** The store name passed to `Vector::register` and `Vector::store` is a label - it can be any string. For Qdrant the framework uses it as the collection name; for Pinecone as the index name. Match the label to the backend's existing naming scheme.

**Re-registering** a name with a new driver instance is a last-write-wins operation by design - useful for swapping drivers in test harnesses without restarting the process.

**Test isolation.** Both Memory and registry-backed driver tests use timestamp-tagged unique store names to avoid collisions under parallel test runs.

**Error semantics.** `Vector::store(name)` returns `FrameworkError::not_found` for unregistered names. Driver-level failures (network, auth, dimension mismatch) come back as `FrameworkError::internal` or `FrameworkError::param` with the cause string in the display message.

## Extending

To add a sixth backend (Weaviate, Milvus, LanceDB, LibSQL, ...):

1. Add a new `framework/src/vector/<backend>.rs` implementing `VectorDriver`.
2. Re-export the driver type from `framework/src/vector/mod.rs` and the crate root.
3. Mirror the Pinecone test split: pure-function tests and wire-contract tests (against a local `wiremock` fake) always run; integration tests are `#[ignore]`-gated behind env vars for credentials. The middle layer is the one that earns its keep - a backend nobody can reach from CI still has a wire format that a typo can break.

The trait is intentionally small so the bar to ship a new driver stays low. If a backend needs surface that doesn't fit (filter expressions, sparse vectors, hybrid search), expose it through a trapdoor on the driver - don't bloat the trait.

## Next

- [Search](search.md) - searchable models, native lexical ranking, and hybrid retrieval
- [Deployment](deployment.md) - the MariaDB-as-default-production
  recommendation in context
- [Database](database.md) - multi-driver SeaORM setup, including
  MariaDB as a relational backend alongside vectors
- [Environment Variables](env-vars.md) - `QDRANT_URL`,
  `PINECONE_API_KEY`, `MARIADB_URL`, `PGVECTOR_URL` and other driver env contracts
- [Cache](cache.md) - sibling facade with the same driver-trait shape
- [Laravel Parity Map](parity.md) - where vector search sits relative
  to Scout


---

<!-- /docs/search -->

# Search

You search Eloquent models through one typed API. The engine ranks documents
with its own relevance score. Suprnova expands your query, applies your viewer's
scope, fuses lexical and semantic results, hydrates models, and formats matches.
You choose `database`, `qdrant`, `collection`, or `null` without changing the
model's search calls.

The default is lexical search on your application's database. You need no
embedding model or external search service. For vector storage without model
search, see [Vector](vector.md).

## Declare a searchable model

Place `#[derive(Searchable)]` below `#[suprnova::model]` so the derive sees the
model's generated metadata. In a generated application, this declaration works
with the default features and the application's Serde and SeaORM dependencies:

```rust
use suprnova::{AttributeValue, Filter, FrameworkError, IndexSettings, Searchable, Viewer};

#[suprnova::model(table = "articles", timestamps = false)]
#[derive(Searchable)]
#[searchable(
    index = "articles",
    should_index = "is_published",
    with = "prepare_search",
    scope = "article_scope",
    scope_fields("owner_id"),
    settings = "article_settings",
    geo(name = "location", lat = "lat", lng = "lng")
)]
pub struct Article {
    pub id: i64,
    #[searchable(text(weight = 2.0), embed, title)]
    pub title: String,
    #[searchable(text, embed)]
    pub body: String,
    #[searchable(facet, sortable)]
    pub category: Option<String>,
    #[searchable(facet, sortable)]
    pub price: f64,
    #[searchable(filterable)]
    pub published: bool,
    #[searchable(filterable)]
    pub owner_id: String,
    pub lat: f64,
    pub lng: f64,
}

impl Article {
    fn is_published(&self) -> Result<bool, FrameworkError> {
        Ok(self.published)
    }

    async fn prepare_search(models: Vec<Self>) -> Result<Vec<Self>, FrameworkError> {
        Ok(models)
    }
}

fn article_scope(viewer: &Viewer) -> Filter {
    Filter::Eq(
        "owner_id".into(),
        AttributeValue::Text(viewer.id().unwrap_or("__guest__").into()),
    )
}

fn article_settings() -> IndexSettings {
    IndexSettings::default()
}
```

Create the matching application table through your [migrator](migrations.md).
Use an owner value that your application never assigns for the guest branch.
After adding `suprnova::search::migrations()` to the migrator, provision the
initial persistent index before model writes:

```bash
cargo run -- migrate
cargo run --bin console -- search:index articles
cargo run --bin console -- search:import articles
```

The index name defaults to the model's table name. Field declaration order is
the searchable attribute order. You can combine these field attributes:

| Attribute | Meaning |
|---|---|
| `text` | Include the field in lexical ranking. Its default weight is 1. |
| `text(weight = 2.0)` | Apply a positive finite native column weight. `text, weight = 2.0` is equivalent. |
| `filterable` | Allow bound comparisons in filters and scopes. |
| `sortable` | Allow attribute ordering. |
| `facet` | Count values and allow filtering; this implies `filterable`. |
| `embed` | Join the field into the embedding source in declaration order. |
| `title` | Supply the embedding template's title. |

Supported field types are `String`, integer types through `i64` and `u64`,
`f32`, `f64`, `bool`, `chrono::NaiveDateTime`, `chrono::DateTime<chrono::Utc>`,
`DateTimeUtc`, and `Vec<String>`, including their `Option` forms. Search stores
integers as `i64` and rejects unsigned overflow. Text roles accept strings and
text lists. Optional values remain null; non-finite floats are errors.

The struct options are `index`, `soft_delete`, `should_index`, `with`, `scope`,
`scope_fields("field", ...)`, `settings`, `touches("relation", ...)`, and
`geo(name = "location", lat = "lat", lng = "lng")`. `should_index` names a model method returning
`Result<bool, FrameworkError>`; false removes an existing document. `with` names
an async model method taking and returning `Vec<Self>` through `Result`, so you
can load relations once per chunk before `make_searchable_using` projects rows.
`scope` names `fn(&Viewer) -> Filter`, and `scope_fields` names every
filterable field it reads; the two come together. `settings` names
`fn() -> IndexSettings`.

The geo option synthesizes a filterable, sortable geo attribute from numeric
latitude and longitude fields. Coordinates use degrees, latitude -90 to 90 and
longitude -180 to 180. Distances use meters. The coordinate source fields do not
become public search attributes unless you declare them separately.

`to_search_document()` returns a `Result<SearchDocument, FrameworkError>` with
the textual model key, index, declared typed attributes, embed text, and title.
Timestamped projections use `updated_at` in UTC microseconds. A model without
`updated_at` gets a version the framework keeps per row in the
`search_source_versions` table: every save raises it inside the save's own
transaction, so a rolled-back save leaves it unchanged, and reading a row never
raises it. `to_search_document()` is synchronous and cannot query, so Eloquent
loads each kept version together with its row, and each
model carries the version of the revision it holds: the one its load found or
its save raised. A model keeps that version for as long as you hold it; a row
another process saved since then reads the newer version on its next load.
An ordinary SELECT's correlated version lookup shares the content's snapshot on
Postgres, MySQL/InnoDB and SQLite. A commit after that SELECT cannot attach
a newer version to older content, including a row with no kept version yet.
For a locking model query on Postgres or MySQL, Eloquent holds the row locks
while reading versions with the same lock on the same transaction. This reads
current metadata on MySQL even when the transaction has an older snapshot;
Postgres reads metadata after any row-lock wait. A pool query owns a short
transaction for those reads. SQLite's lock hints are no-ops and use the ordinary
single SELECT. Derived union and window queries also keep the single SELECT.
Undeclared model fields stay outside the document.

## Index settings

Return settings from your code-owned function and run
`search:sync-index-settings [index]`. The command prints changed fields by
class and reports whether it builds a generation. You can read stored settings
with `SearchRegistry::engine_for(index)?.read_settings(descriptor, &generation)`.

| Query-time setting | Default | Effect on the next query after sync |
|---|---|---|
| `typo_tolerance` | Enabled, one edit from 5 scalars, two from 9 | Correction thresholds and excluded words or attributes. |
| `synonyms` | Empty | Two-way groups or one-way source/replacement groups. |
| `stop_words` | Empty | Remove words from the query before retrieval. |
| `distinct_attribute` | None | Keep the first ranked hit for each value. |
| `hits_cap` | 1000 | Bound accessible ranked hits. |
| `fusion_depth` | 200 | Bound candidates from each hybrid leg. |
| `hybrid_ratio` | 0 | Choose lexical versus semantic weight when the builder gives none. |
| `highlight_pre_tag`, `highlight_post_tag` | `<em>`, `</em>` | Wrap escaped matches with validated markup. |
| `crop_marker` | `...` | Mark omitted text. |
| `facet_value_cap`, `facet_order` | 100, `FacetOrder::Count` | Select frequent values, then order by count or alphabetically. |

`SEARCH_HITS_CAP` and `SEARCH_FUSION_DEPTH` supply deployment defaults when
the code keeps those settings at their defaults.

Every change to `IndexTimeSettings` requires a new generation: `language`,
`searchable_attributes` with weights, `embed_source`, `embed_template`,
`filterable_attributes`, `sortable_attributes`, `facet_attributes`, `embedder`,
`model`, `sparse_model`, and `dimensions`. The derive supplies attribute sets and
embed sources from the declaration. An empty `embed_template` uses the model
profile's template. Facets must also be filterable with the same type.

Use `LanguageConfig::Postgres { configuration: "english".into() }` for a
Postgres text configuration; `LanguageConfig::Sqlite { tokenizer:
"porter unicode61".into() }` for SQLite stemming; or
`LanguageConfig::Qdrant { tokenizer: "word".into(), stemmer: None,
stop_words: vec![], folding: true }` for Qdrant's text index.
`LanguageConfig::Server`, the default, uses each engine's defaults. MySQL and
MariaDB accept only server language settings. A language setting for another
engine is rejected.

## Query models

Import `suprnova::Searchable` to call `Article::search`. Fluent methods defer
validation; terminal methods return `Result`. Using the model above, you can
run this in an authenticated handler after importing the listed types:

```rust
use suprnova::{FrameworkError, Searchable};

async fn article_titles() -> Result<Vec<String>, FrameworkError> {
    let result = Article::search("gardem")
        .highlight(["title", "body"])
        .limit(10)
        .get()
        .await?;
    Ok(result.hits.into_iter().map(|hit| hit.model.title).collect())
}
```

These examples each start a new query over that model:

| Method | Example | Result or behavior |
|---|---|---|
| `filter` | `Article::search("garden").filter("price >= 10")` | Add typed AST or grammar predicates; repeated calls combine with AND. |
| `facets` | `Article::search("garden").facets(["category"])` | Request value counts. |
| `facet_stats` | `Article::search("garden").facet_stats(["price"])` | Request typed min/max. |
| `sort_by` | `Article::search("garden").sort_by("price", SortDirection::Asc)` | Order by a declared sortable attribute. |
| `sort_by_distance` | `Article::search("garden").sort_by_distance("location", GeoPoint { lat: 40.0, lng: -73.0 }, SortDirection::Asc)` | Order by meters from a point. |
| `group_by` | `Article::search("garden").group_by("category", 3)` | Keep a representative and up to two additional group members. |
| `highlight` | `Article::search("garden").highlight(["title"])` | Return formatted fields. |
| `crop` | `Article::search("garden").crop("body", 120)` | Format a bounded fragment around the first match. |
| `hybrid` | `Article::search("garden").hybrid(0.5)` | Fuse lexical and semantic candidates. |
| `rerank` | `Article::search("garden").rerank("BAAI/bge-reranker-base", 20)` | Rerank a bounded leading slice. |
| `limit` | `Article::search("garden").limit(10)` | Bound the returned page. |
| `offset` | `Article::search("garden").offset(10)` | Skip ranked hits. |
| `hits_cap` | `Article::search("garden").hits_cap(100)` | Reduce, never increase, the index's accessible cap. |
| `for_viewer` | `Article::search("garden").for_viewer(Viewer::Guest)` | Apply an explicit viewer's scope. |
| `with_trashed` | `Article::search("garden").with_trashed()` | Include soft-deleted rows only if the index also opts in. |
| `query` | `Article::search("garden").query(|query| query.filter("published", true))` | Adjust the Eloquent hydration query once. |
| `get` | `Article::search("garden").get().await?` | Return `SearchResults<Article>`. |
| `paginate` | `Article::search("garden").paginate(10, 2).await?` | Page 2, with 10 hits per page. |
| `simple_paginate` | `Article::search("garden").simple_paginate(10, 2).await?` | The same result envelope, including `pagination.has_more`. |
| `keys` | `Article::search("garden").keys().await?` | Return scoped, live-checked `Vec<String>`. |
| `raw` | `Article::search("garden").raw().await?` | Return `Vec<RawHit>` containing declared attributes. |
| `facet_search` | `Article::search("garden").facet_search("category", "out").await?` | Return matching facet values and counts. |
| `search_query` | `Article::search("garden").search_query().limit` | Inspect the typed plan without executing it. |

Import `SortDirection`, `GeoPoint`, and `Viewer` from `suprnova` for the table's
examples. `SearchBuilder::new` is the constructor behind `Model::search`.
Pagination uses `(per_page, page)`, with positive one-based pages. Keys break
score ties, so pages slice one ranked list on an unchanged index. The default
page limit is 20. The hit cap limits navigation, not exact lexical totals or
facets.

Each hit contains `model`, `key`, `engine_score`, `normalized_score` in [0, 1]
within the returned result, `engine`, `formatted`, optional `geo_distance`, and
`group_members`. The response adds `Total::Exact` or `Total::Estimated`,
`facets`, `facet_stats`, `processing_time_ms`, engine name, query, pagination,
and an optional analytics impression. Semantic top-k makes totals estimated.
Scores from different engines have different scales.

Hydration loads models through Eloquent. Missing rows are dropped and their
index removals are queued; stale rows outside scope are dropped too. The
`query` callback controls hydration, not engine candidates, totals, or facets.
Use search filters and the declared scope for access restrictions.

For several registered indexes, use federation:

```rust
use suprnova::{Search, Viewer};

let results = Search::federated(["articles", "notes"])
    .search("garden")
    .for_viewer(Viewer::Guest)
    .highlight(["title"])
    .paginate(10, 1)
    .await?;
```

Both indexes must declare the requested attributes. `FederatedBuilder` supports
`search`, `filter`, `for_viewer`, `facets`, `facet_stats`, `highlight`, `crop`,
`hybrid`, `limit`, `offset`, `get`, `keys`, and `paginate`. It merges per-index
ranks by reciprocal rank fusion with k = 60, using your index order for ties.
Keys remain `(index, key)` pairs; facets and stats remain grouped by index.
`Search::for_index("articles")?.search("garden")` provides runtime index
selection with filters, facets, highlights, attribute sorting, limits, offsets,
viewer selection, and a `get` returning declared projections after hydration.

## Filters

Filters name declared filterable attributes and bind values separately from
engine syntax. You can pass a `Filter` tree or a string to `.filter(...)`:

```rust
use suprnova::{AttributeValue, Filter, Searchable};

let results = Article::search("garden")
    .filter(Filter::Gte("price".into(), AttributeValue::Float(10.0)))
    .filter("category IN ['outdoors', 'books'] AND NOT published = false")
    .get()
    .await?;
```

The grammar includes every operator below:

| Grammar | Typed form | Meaning |
|---|---|---|
| `category = 'books'`, `category == 'books'` | `Filter::Eq` | Equality; list attributes match an element. |
| `category != 'books'` | `Filter::Ne` | Negated equality, including missing values unless you compare null. |
| `category IN ['books', 'outdoors']` | `Filter::In` | Any listed value. |
| `category NOT IN ['hidden']` | `Filter::NotIn` | Exclude any listed value. |
| `price > 10`, `price >= 10` | `Filter::Gt`, `Filter::Gte` | Exclusive/inclusive lower bound. |
| `price < 20`, `price <= 20` | `Filter::Lt`, `Filter::Lte` | Exclusive/inclusive upper bound. |
| `price 10 TO 20` | `Filter::Between` | Inclusive range. |
| `category IS NULL`, `category IS NOT NULL` | `Filter::IsNull`, `Filter::IsNotNull` | Missing/null or present. |
| `(published = true AND price < 20) OR category = 'books'` | `Filter::And`, `Filter::Or` | Boolean composition. |
| `NOT (category = 'hidden')` | `Filter::Not` | Negation. |
| `_geoRadius(40, -73, 1000)` | `Filter::GeoRadius` | Within 1000 meters; grammar requires exactly one filterable geo attribute. |

Keywords are case-insensitive. Precedence is NOT, AND, OR; parentheses override
it. Quote strings with single or double quotes and escape the next character
with a backslash. Numbers, booleans, and null are typed; datetime literals are
UTC-compatible timestamps such as `2026-01-01T00:00:00Z`. Ordered comparisons
exclude missing values. Use the AST to name a geo attribute when the index has
more than one. Invalid names, types, reversed ranges, negative radii, or
non-finite coordinates fail before engine access. Grammar input is bounded to
64 KiB and 4096 tokens; filter trees are bounded to 64 levels.

## Facets and stats

`.facets(["category"])` counts the full filtered lexical candidate set before
distinct, grouping, the hit cap, pagination, or semantic top-k. Counts remain
exact, including on Qdrant. The most frequent values survive `facet_value_cap`;
`FacetOrder::Alphabetical` changes their presentation after selection.

`.facet_stats(["price"])` returns typed `min` and `max` over the same set for
numeric or datetime facets. A facet without non-null values has no extrema.
`.facet_search("category", "out")` provides type-ahead values with counts
under the same query, filters, soft-delete policy, and scope. A value's count
equals the exact lexical total when you filter the query to that value.

## Sorting and geo distance

Attribute and distance sorts precede relevance in lexical and hybrid modes.
Missing values sort last in both directions; relevance and then the key break
ties. Repeated `sort_by` calls add ordered clauses. Geo sorts populate each
hit's `geo_distance` in meters. Radius filters and distance sorts use the same
Haversine model. `group_by("category", 3)` keeps the first ranked representative
and at most three total members, including it. The representative's
`group_members` holds the additional members. Distinct is a query setting,
`distinct_attribute`, that keeps the first hit for each value.

## Highlights and crops

Request `.highlight(["title", "body"])` or `.crop("body", 120)` to populate
`hit.formatted`. Corrected words, synonyms, original-word prefixes, and phrases
are marked in the original text. Crops count visible Unicode characters
around the first match and never cut a tag. Postgres uses native headline
matches; SQLite uses native FTS5 matches and snippets. MySQL, MariaDB, Qdrant,
and collection use the framework formatter.

Document text is HTML-escaped before tags are added. Settings accept matching
`mark`, `em`, `strong`, `b`, or `span` tags with at most one `class` attribute.
Event handlers, other attributes, and mismatched tags fail validation. Tags
come from code, never request parameters; the crop marker is escaped text.

In Live, use the `trusted_html` filter only on the checked `TrustedHtml` value
that the component supplies. For a `SearchBoxHit` named `hit`, the shipped
template uses:

```html
{% let markup = hit.highlight("title")? %}
{{ markup|trusted_html }}
```

Keep ordinary document text escaped. The kits render only core-produced
formatted fields as HTML.

## Typo tolerance, synonyms, and stop words

Typos expand query words against the generation's vocabulary. The budgets are
zero edits below 5 Unicode scalars, one from 5 through 8, and two from 9.
Damerau-Levenshtein distance counts a transposition as one edit. Numbers,
including numeric forms that overflow, are never corrected. Named words and
attributes in `disable_on_words` and `disable_on_attributes` stay exact for
typos; synonyms still apply. Quoted phrases and negative words do not receive
ordinary word correction. Tokens longer than 64 scalars skip correction.
Only the first 32 query tokens receive correction. Queries are bounded to
64 KiB and 1024 source tokens.

Set `query.typo_tolerance.enabled = false` to disable correction. Alternatives
include the original and are capped by `SEARCH_EXPANSION_TERMS` (64 per word),
with higher document frequency first and stable ties. Only the original last
word gets prefix matching, not its typo corrections. SQLite vocabulary comes
from `fts5vocab`; Postgres uses `ts_stat`, refreshed after builds and every
`SEARCH_VOCABULARY_REFRESH` writes (1000 by default). MySQL, MariaDB, and Qdrant
maintain document frequencies and remove zero-frequency words.

For example, add this in your settings function:

```rust
let mut settings = suprnova::IndexSettings::default();
settings.query.synonyms.push(suprnova::Synonym {
    terms: vec!["bike".into(), "bicycle".into()],
    one_way: false,
});
settings.query.synonyms.push(suprnova::Synonym {
    terms: vec!["nyc".into(), "new york".into()],
    one_way: true,
});
settings.query.stop_words.insert("the".into());
```

Two-way groups expand any member; one-way groups expand the first term to the
others. Multi-word source and replacement synonyms match as phrases. Query
stop words are independent of the engine's index-time stop words. Expansion
does not override an engine's minimum token length, stemming, or stop list.

## Hybrid search and embedders

`SEARCH_EMBEDDER=none` is lexical. A positive `.hybrid(ratio)` without an
embedder fails with an error naming `SEARCH_EMBEDDER`. With an embedder, zero
keeps lexical order, one keeps cosine order, and intermediate ratios use
weighted reciprocal rank fusion: lexical weight `1 - ratio`, semantic weight
`ratio`. Each leg takes `fusion_depth` candidates under the same filter and
scope. Qdrant performs native fusion; other engines use the framework's RRF
with k = 60. Ratios must be finite and between 0 and 1 inclusive. Sorts still
take precedence.

The `Embedder` trait exposes `profile`, `embed_documents`, `embed_query`, and
optional sparse operations. You choose `fastembed` or `http`, or register your
own provider with `SearchRegistry::register_embedder`. An index's
`index_time.embedder` overrides the deployment provider. Model profiles own
the model id and revision, dimensions, token context, query prefix, document
template, pooling, normalization, Matryoshka dimensions, precision, output key,
input kinds, and artifact files. The local media profile accepts image, audio
and video parts. The HTTP provider and default local profile accept text only.
Unsupported parts fail.

Application boot constructs the environment-selected provider before the bootstrap
hook, so the hook can provision a first generation. Register provider configuration
in the application's `config` callback or environment. The bootstrap hook can still
register a custom provider that replaces the constructed one.

### Local inference

Enable the `search-fastembed` Cargo feature and select
`SEARCH_EMBEDDER=fastembed`. Enabling `search-fastembed` makes the `ort` crate's
build script download the ONNX Runtime library at compile time. Your build
machine needs network access for that feature. The default build downloads
nothing.

Register a `LazyEmbedder` with a shipped profile and a loader to start services
and run tests without downloading weights. Registration and `profile()` use the
shipped metadata. The first embedding call or `resolve_profile()` loads the model
once; a failed load can be retried. Before creating a generation, the coordinator
resolves the profile and records the loaded model's `id@revision` and dimensions.
The loaded id and dimensions must match the shipped profile.

This example runs without a model download; replace the fake loader with your
local inference loader in application bootstrap:

```rust
use std::sync::Arc;
use suprnova::{Embedder, FakeEmbedder, FrameworkError, LazyEmbedder, SearchRegistry};

fn register_local_model() -> Result<(), FrameworkError> {
    let shipped = FakeEmbedder::new(16)?.profile().clone();
    let lazy = LazyEmbedder::new(shipped, || async {
        Ok(Arc::new(FakeEmbedder::new(16)?) as Arc<dyn Embedder>)
    })?;
    SearchRegistry::register_embedder("local", Arc::new(lazy))
}
```

The default local model is `hf:onnx-community/embeddinggemma-2-ONNX`,
EmbeddingGemma 2 text, fp32, 768 dimensions, mean pooling, L2 normalization,
and an 8192-token context. Its model artifacts total about 1.04 GiB
(1,116,768,801 bytes). Model download happens on first load into
`SEARCH_MODEL_CACHE`, which defaults to `storage/search/models`.

You pass unprefixed text. The framework applies `task: search result | query: `
to queries and `title: {title} | text: {text}` to documents; an absent title
becomes `none`. Local inference truncates with the model tokenizer after
preparation, including prefixes and special tokens, and runs on blocking
threads. Vectors must have the profile's dimensions and finite values. A
supported Matryoshka reduction re-normalizes the truncated vector.

The shipped profiles are listed below. All normalize their output. Names also
resolve through their repository ids. BGE's instruction means
`Represent this sentence for searching relevant passages: `.

| Profile | Dimensions | Context tokens | Pooling | Query prefix / document template | Reduced dimensions |
|---|---:|---:|---|---|---|
| `embeddinggemma-2` | 768 | 8192 | Mean | `task: search result \| query: ` / `title: {title} \| text: {text}` | 512, 256, 128 |
| `embeddinggemma-2-media` | 768 | 8192 | Mean | Same as EmbeddingGemma 2, with ordered media parts | 512, 256, 128 |
| `embeddinggemma-300m` | 768 | 2048 | Mean | Same as EmbeddingGemma 2 | 512, 256, 128 |
| `bge-small-en-v1.5` | 384 | 512 | CLS | BGE instruction / `{text}` | None |
| `bge-base-en-v1.5` | 768 | 512 | CLS | BGE instruction / `{text}` | None |
| `bge-large-en-v1.5` | 1024 | 512 | CLS | BGE instruction / `{text}` | None |
| `bge-m3` | 1024 | 8192 | CLS | Empty / `{text}` | None |
| `multilingual-e5-small` | 384 | 512 | Mean | `query: ` / `passage: {text}` | None |
| `multilingual-e5-base` | 768 | 512 | Mean | `query: ` / `passage: {text}` | None |
| `multilingual-e5-large` | 1024 | 512 | Mean | `query: ` / `passage: {text}` | None |
| `nomic-embed-text-v1.5` | 768 | 8192 | Mean | `search_query: ` / `search_document: {text}` | 512, 256, 128, 64 |
| `gte-base-en-v1.5` | 768 | 8192 | CLS | Empty / `{text}` | None |
| `gte-large-en-v1.5` | 1024 | 8192 | CLS | Empty / `{text}` | None |
| `mxbai-embed-large-v1` | 1024 | 512 | CLS | Empty / `{text}` | 512 |
| `snowflake-arctic-embed-xs` | 384 | 512 | CLS | Empty / `{text}` | None |
| `snowflake-arctic-embed-s` | 384 | 512 | CLS | Empty / `{text}` | None |
| `snowflake-arctic-embed-m` | 768 | 512 | CLS | Empty / `{text}` | None |
| `snowflake-arctic-embed-l` | 1024 | 512 | CLS | Empty / `{text}` | None |
| `all-MiniLM-L6-v2` | 384 | 256 | Mean | Empty / `{text}` | None |
| `all-MiniLM-L12-v2` | 384 | 128 | Mean | Empty / `{text}` | None |

Nomic's 8192-token context requires an export with the model's RoPE scaling.
The shipped Arctic and mxbai profiles use no retrieval prefix; declare a
custom profile if you need another preparation convention.

`SEARCH_EMBED_MODEL` accepts a fastembed named model, `hf:owner/repository`,
`hf:owner/repository@revision`, or `path:/absolute/model-directory`. For an
unrecognized export, provide `FastembedConfig.profile: Some(ModelProfile)` in
registered configuration. Declare the graph, optional external tensor file,
`tokenizer.json`, `config.json`, `tokenizer_config.json`,
`special_tokens_map.json`, pooling, precision, and optional output key.

`SEARCH_EMBED_PRECISION` accepts `fp32`, `int8`, or `q4`; fp16 is refused.
The default graph names are `onnx/model.onnx` with `onnx/model.onnx_data`,
`onnx/model_quantized.onnx`, and `onnx/model_q4.onnx`, respectively. Dynamic
quantization uses singleton inference so document batches and queries agree.
BGE-M3 sparse inference uses its joint int8 export and external tensors.
`SEARCH_EMBED_BATCH` otherwise bounds inference batches, default 64. A local
model counts it in texts of 512 tokens: attention memory grows with the square
of a batch's longest text, so a longer text takes the room of several by that
square, and one longer than that runs alone. Texts of similar length share a
batch, measured with the model's own tokenizer.
`SEARCH_EMBED_DIMENSIONS` selects a supported reduced dimension.

Each cache directory has `manifest.json` with repository, resolved revision,
recording time, and a SHA256 and size for every file. Local directories receive
an artifact-derived revision. Generated special-token maps and the text graph
that binds unused media inputs to empty tensors are recorded as derived files
with their own hashes and derivation descriptions. Every cached file is
verified before loading; a changed byte is refused. A verified cache works
offline. Keep the manifest with its artifacts. Generation settings pin the
resolved model revision and dimensions; `ModelProfile::provenance()` exposes
the manifest digest and file hashes, and baseline records include them.
Indexing and semantic queries refuse a provider whose model id or revision differs
from the generation's pin, even when its dimensions match. After changing models,
rebuild the index with `search:reindex <Model|index>`.

### Media embeddings

Enable `search-fastembed`. Set `SEARCH_EMBEDDER=fastembed` and
`SEARCH_EMBED_PROFILE=embeddinggemma-2-media`.
The default model stays `hf:onnx-community/embeddinggemma-2-ONNX`.
The media profile verifies the text, vision and audio graphs, their external
weights and processor configuration in one cache manifest. It returns 768
normalized values. The fp32 graphs, weights and tokenizer need about
2.8 GiB in the model cache. Text-only documents keep the text batch planner.

Declare storage path fields in the order the model should receive their parts:

```rust
#[searchable(embed)]
pub caption: String,
#[searchable(media(kind = "image", disk = "private"))]
pub poster: Option<String>,
#[searchable(media(kind = "audio", disk = "private"))]
pub soundtrack: String,
#[searchable(media(kind = "video", disk = "private"))]
pub clip: Option<String>,
```

These attributes belong on fields of a `Searchable` model. A null optional
path contributes no part. A model with only media paths embeds empty text
with its declared parts. The worker reads each path asynchronously through
`Storage`. `SEARCH_MEDIA_MAX_BYTES` limits each part to 33554432 bytes by
default. Set a smaller positive limit to reduce worker memory. Larger limits
are refused. A size check and a bounded range read apply to every part.
Each part's bytes join the document's content hash, so a file replaced at the
same path is embedded again. Replacing a file does not reindex anything by
itself, and a save that changes no column returns before search
synchronization runs. After you replace a file, call
`suprnova::search::searchable::<M>(&keys)` for the row, or save it with a
changed column. Every save that reaches search synchronization reads all of the
document's media parts, even unchanged ones, to compare them.

Images accept PNG, JPEG and WebP. Audio accepts PCM WAV, mixes channels to
mono and resamples to 16 kHz with a Hann-windowed sinc filter. It computes
the model's log-mel features and mask.
Audio is limited to 30 seconds. Image decoding has dimension and memory caps.
The default `search-media` feature exposes the Rust processors without ONNX.

Video requires a host `ffmpeg` binary. `SEARCH_FFMPEG_BINARY` selects its path
and defaults to `ffmpeg`. A missing binary fails with that variable's name.
The worker samples frames at 1 fps, keeps at most 32 frames and applies the
video processor's 140-token image budget. Long clips use uniform samples
across their duration. Video duration must be at most 24 hours. Each decode
has a 30-second timeout.
Temporary input and frame files are removed when decoding ends.

Boot and `search:sync-index-settings` reject a declared kind that the model
profile cannot accept. The error names the index and model. The default
EmbeddingGemma 2 profile and the `http` provider remain text only. The HTTP
provider refuses media even if a caller supplies a custom profile.

### OpenAI-compatible HTTP inference

Select `SEARCH_EMBEDDER=http`, set `SEARCH_EMBED_BASE_URL` to the deployment's
base URL, and set `SEARCH_EMBED_MODEL`. The provider sends
`POST {base}/embeddings` with the OpenAI-compatible shape:

```json
{"model":"your-model","input":["prepared text"],"dimensions":768,"encoding_format":"float"}
```

`dimensions` is omitted when you do not request it. The response is
`{"data":[{"index":0,"embedding":[0.1,0.2]}]}`, with actual vectors matching
the configured dimensions. Response indexes must cover each batch exactly
once; the provider restores input order. Unknown models use configured
dimensions or one boot-time probe, an empty query prefix, and `{text}` as the
document template. `SEARCH_EMBED_QUERY_PREFIX` and
`SEARCH_EMBED_DOCUMENT_TEMPLATE` override preparation for unknown models.
Known models use their shipped profile. You can supply an explicit profile
through `HttpEmbedder::with_profile`.

Call `embed_documents_metered` or `embed_query_metered` to receive the vectors
in `.value` and the provider's optional `prompt_tokens` and `total_tokens` in
`.usage`. Missing or malformed usage is `None`. Document calls sum the usage
reported across their batches, keeping fields the provider sends on only some
batches. No reported usage means `None`, never an estimate.

```rust
use suprnova::{Embedder, FrameworkError, HttpEmbedder};

#[tokio::main]
async fn main() -> Result<(), FrameworkError> {
    let embedder = HttpEmbedder::from_env().await?;
    let result = embedder.embed_query_metered("rust search").await?;
    println!("Provider usage: {:?}", result.usage);
    Ok(())
}
```

`EmbeddingUsageReported` carries the model, operation, input count and usage
for each embedding request that reports it. Vector-only calls emit it too,
so a listener can bill the framework's own indexing and search calls. Register
your ledger function during bootstrap; listener failures log a warning and
leave the embedding successful.

```rust
use std::sync::Arc;
use suprnova::{EmbeddingUsageReported, EventFacade, FrameworkError, Listener};

struct BillEmbeddings {
    settle: fn(&EmbeddingUsageReported, u64) -> Result<(), FrameworkError>,
}

#[suprnova::async_trait]
impl Listener<EmbeddingUsageReported> for BillEmbeddings {
    async fn handle(&self, event: &EmbeddingUsageReported) -> Result<(), FrameworkError> {
        if let Some(tokens) = event.usage.total_tokens {
            (self.settle)(event, tokens)?;
        }
        Ok(())
    }
}

async fn register_embedding_billing(
    settle: fn(&EmbeddingUsageReported, u64) -> Result<(), FrameworkError>,
) {
    EventFacade::listen::<EmbeddingUsageReported, _>(Arc::new(BillEmbeddings { settle })).await;
}
```

Use `HttpEmbedder::with_transport(config, profile, transport)` when the
application owns HTTP admission, credentials, deadlines or kill switches.
The transport is an `Arc<dyn EmbeddingTransport>`. Its `send` method receives
a `TransportRequest` with the method, pinned URL, headers, optional JSON body,
timeout and `max_response_bytes`, and returns a `TransportResponse` with the
status, headers and body bytes. Configured bearer headers are marked sensitive;
with no `SEARCH_EMBED_API_KEY`, the transport can resolve its own credentials.
Endpoint validation still applies. For example, pass your transport at boot:

```rust
use std::sync::Arc;
use suprnova::{EmbeddingTransport, FrameworkError, HttpEmbedder, HttpEmbedderConfig};

async fn application_embedder(
    config: HttpEmbedderConfig,
    transport: Arc<dyn EmbeddingTransport>,
) -> Result<HttpEmbedder, FrameworkError> {
    HttpEmbedder::with_transport(config, None, transport).await
}
```

Preparation, retries, `Retry-After`, status checks, JSON parsing, index validation
and dimension probing stay in the framework. The transport must enforce the
deadline and cap the body while streaming. The embedder checks the returned
body size again before parsing, even when an application transport ignores the
cap. The existing constructors use the default reqwest transport.

The destination comes from deployment configuration, never a request or
tenant. HTTPS is required except for `localhost`, `127.0.0.1`, and `::1`.
URLs with credentials, query strings, or fragments are rejected. The default
transport follows no redirects. `SEARCH_EMBED_API_KEY` is a bearer key sent only
to the pinned destination. Defaults are 64 inputs per batch, a 30-second timeout including
the response body, 16 MiB per response, and three additional attempts for 429
or 5xx only. Retries are capped at 16; `Retry-After` is bounded. HTTP uses no
provider-specific fields. Hosted models with published limits are built in:
OpenAI's `text-embedding-3-small`, `text-embedding-3-large` and
`text-embedding-ada-002` (8192 tokens), and Google's `gemini-embedding-001`
(2048 tokens) and `gemini-embedding-2` (8192 tokens), with or without an
`owner/` prefix such as OpenRouter's `openai/text-embedding-3-small`. Any
other model outside the shipped profiles takes its context from the
service's model list: OpenRouter's `embeddings/models` (`context_length`),
or `models` with vLLM's `max_model_len`, LM Studio's or Mistral's
`max_context_length`. The list is read on the first embedding, not at boot,
so the application starts while the service is down. When the list names no
context for the model, the provider uses 8192 tokens, the limit OpenAI,
Mistral and Google's newer models publish; when the list cannot be read, it
uses 8192 for that embedding, logs a warning, and reads the list again next
time. `SEARCH_EMBED_MAX_TOKENS` wins over the profile, the list and the
default, for a model with a smaller context or a server that caps input
below it.
Every prepared input is cut to the model's context before it is sent. Set `SEARCH_EMBED_TOKENIZER` to the model's own
`tokenizer.json`, published beside the weights in its Hugging Face repository,
and the cut falls after the last token that fits. Without it the protocol
gives no way to count tokens, so the cut is in UTF-8 bytes, four short of the
context: it never exceeds the context, and it keeps about a quarter of what
the model can read in English text. Suprnova never downloads the file.

## Reranking

`.rerank("BAAI/bge-reranker-base", 20)` runs a named fastembed cross-encoder on
the leading 20 representatives after retrieval, distinct, and grouping, before
pagination. It replaces their order and leaves the remaining tail in order.
You need `search-fastembed` for shipped local rerankers. Their runtimes load
lazily when first used; boot registers supported repository ids, short names,
and enum spellings without downloading every model. You can register a custom
`Reranker` with `SearchRegistry::register_reranker`; its positional scores must
be finite. A missing reranker or invalid depth fails at the terminal method.

## Engines

Set `SEARCH_DRIVER` globally or call
`SearchRegistry::set_index_driver("articles", "qdrant")?` at bootstrap. Register
custom engines with `SearchRegistry::register_engine`; a custom engine that
serves the graph recommender also implements `stored_keys`, which reports the
documents a generation holds. To move an index, select
its destination driver, configure that service, then run `search:reindex`
against it. Query call sites stay the same. Keep the old service available
until its queued work drains, and remove its storage separately when retired.

### Database

The database engine uses your application's connection, including a model's
named connection, and a side table per index generation. It stores typed
attributes, versions, hashes, and generation metadata beside native indexes.

| Dialect | Native index and rank | Tokenization, stemming, stop words, minimum length | Prefixes, phrases, highlights |
|---|---|---|---|
| SQLite | FTS5 external-content table, triggers, weighted `bm25()` | `unicode61` by default, case/diacritic folding, no stop list or server minimum; optional `porter unicode61` stems English | Last-word `*`, adjacent quoted phrases; native `highlight()` and `snippet()` matches |
| Postgres | Stored weighted `tsvector`, GIN, `ts_rank` normalized by document length | The server's `default_text_search_config` by default, copied when a generation is created so a later server change cannot split its vectors from its queries; a named configuration overrides it (`english` stems and drops stop words, `simple` keeps every word); no InnoDB minimum | `:*`, `<->` phrase adjacency; native `ts_headline` matches |
| MySQL | Per-column FULLTEXT plus combined FULLTEXT, weighted sum of `MATCH ... AGAINST (... IN BOOLEAN MODE)` | Server parser and collation; no framework stemming; InnoDB minimum commonly 3 and server stop words apply | Native `*` and quoted phrases, subject to indexed tokens; framework formatting |
| MariaDB | Same FULLTEXT and weighted boolean relevance path | Server parser and collation; no framework stemming; server token minimum and stop words apply | Native `*` and quoted phrases, subject to indexed tokens; framework formatting |

Postgres maps descending distinct attribute weights to its four A/B/C/D
classes; weights beyond four classes share D. A generation built with the
server's language owns a text search configuration named after its table with
a `_ts` suffix; the engine drops it with the generation. Ranking uses `ts_rank`
rather than `ts_rank_cd`: cover density rewards query words that sit close
together, which suits all-word queries, while a search matches any query
word. MySQL/MariaDB text matching
follows the index collation, while filters and facets preserve exact values.
`search:status` reports `innodb_ft_min_token_size`, `innodb_ft_enable_stopword`,
and the server/user stop-word table settings. Configure these on the server and
rebuild affected indexes. Suprnova does not disguise document tokens to bypass
native limits, so short words or stop words can match differently by dialect.

For a database index's semantic leg, register a [Vector driver](vector.md)
under the index name, or set `SEARCH_VECTOR_STORE` to a registered store name.
You can use any Vector driver. Points carry generation and content identities;
durable pending delivery repairs interrupted writes. Retrieval asks the store
for four times the fusion depth, applies the SQL filter and scope to those
keys, and doubles the request until the filtered depth is complete or the
store is exhausted. A Vector driver cannot filter, so a narrow filter, such as
one user's private documents among many users' documents, can read most of
the store on every semantic query. Qdrant applies the filter inside its own
index, so prefer it for large, narrowly scoped data. Keep the store persistent
when your search index must survive process exits.

### Qdrant

Set `QDRANT_URL` to the gRPC URL, normally port 6334, and optionally
`QDRANT_API_KEY`. `SEARCH_QDRANT_TIMEOUT_SECS` bounds calls, default 10 seconds.
Install the SQL search migrations too: generations, pending work, tombstones,
and vocabulary use your application's database.

Qdrant 1.19 or later is required. Each `search_<index>_<generation>` collection
has a named cosine `dense` vector, a language-configured text payload index,
typed payload indexes, keys, and source versions. A lexical index needs no dense
model; its unused dense schema has size 1.

Default lexical ranking uses Qdrant's own `qdrant/bm25` model. Qdrant encodes
each weighted searchable attribute's text on the server into a named
`bm25_<attribute>` sparse vector with the IDF modifier. A Qdrant formula sums
the attribute scores multiplied by their declared weights. This works on
self-hosted Qdrant without `search-fastembed` or a model download. Setting
`index_time.sparse_model = Some("bm25".into())` selects the same default path.
Reindex existing default Qdrant generations to adopt this vector layout.

Document and query inference use identical options from the index's language
settings: tokenizer, stemmer, stop words, and ASCII folding. The default uses
`word`, ASCII folding, no stemmer, and an empty stopword set. Disabling stemming
and stopword removal uses Qdrant's language-neutral options, which need Qdrant
1.19 or later. `LanguageConfig::Server` uses these defaults too.
`SEARCH_BM25_AVERAGE_LENGTH` supplies `avg_len`, default 256. Qdrant's defaults
for `k` (1.2) and `b` (0.75) stay in effect. Reindex after changing the average
length. Text payload indexes enforce words, phrases, and exclusions separately
from ranking. Normalized keyword words support prefix filters and the typo
vocabulary; they never score a hit.

Native queries keep the source spelling for ranking, phrases, and exclusions.
Qdrant tokenizes that text itself; normalized typo and synonym alternatives
are added separately. Keyword words and typo expansion split `word` and `prefix`
text on non-alphanumeric characters and `whitespace` text on whitespace, then
lowercase and fold accents as configured. For `multilingual`, keyword words and
expansion use whitespace as an approximation because Qdrant segments text with
language dictionaries. Ranking and text predicates still use Qdrant's own
multilingual segmentation. Reindex existing generations to update keyword words.

For a learned sparse model, configure `SEARCH_EMBED_SPARSE_MODEL` on the local
provider and set the generation's `sparse_model` to that registered provider's
name, such as `fastembed`. Providers must use one vector space for documents
and expanded queries, returning finite weights with sorted unique token ids.
Learned sparse document fields combine their declared attribute weights.
These providers use one named `sparse` vector with the IDF modifier.
Qdrant performs native weighted RRF for hybrid queries.

Qdrant's default text tokenizer is `word`; supported alternatives are
`whitespace`, `prefix`, and `multilingual`. Code settings can change its
tokenizer, stemmer, stop words, and ASCII folding, requiring a generation.
The text index lowercases tokens, enables phrase matching, and indexes tokens
from one character. The default has ASCII folding and no stemmer or stop list.
Text predicates support any-word matching, prefixes, required per-field
phrases, and exclusions; payload filters and exact facets still apply.
The default BM25 leg uses the same language options as the text predicates.

### Collection and null

Collection stores documents and generations in memory and uses deterministic
BM25, the framework's case/diacritic-folding tokenizer, no native stemming or
stop list, no minimum token length, original-last-word prefixes, and
field-local phrase matching. Use it for tests with fresh engine instances.
It does not persist between processes. Null acknowledges writes, retains
generation settings, and returns empty results; it reports no semantic or
lexical retrieval capabilities.

## Indexing

Model create, update, restore, delete, and force-delete hooks synchronize search.
Ambient transactions, explicit handles, and nested savepoints defer work until
the outer commit; rollback discards it. With `SEARCH_QUEUE=true`, the default,
the configured connection and queue receive registered framework jobs. Run a
worker for `SEARCH_QUEUE_CONNECTION` and `SEARCH_QUEUE_NAME`, for example:

```bash
cargo run -- queue:work --connection search --queue search
```

Set those names only after configuring the corresponding queue connection.
With `SEARCH_QUEUE=false`, deferred inline work runs after commit. Scoped model
mutations synchronize inline after commit even when queuing is enabled, before
the request returns, so changed access does not wait for a worker.

`SearchIndexJob` carries index, key, source version, operation, and optional
generation. It reloads authoritative rows on execution and removes missing or
ineligible rows. Chunk jobs load and prepare a whole chunk before projecting
it. Older versions cannot replace newer ones. Equal content hashes with the
same generation settings skip embedding and engine writes while preserving
the version watermark.

Removal tombstones prevent delayed retries from resurrecting documents for
`SEARCH_TOMBSTONE_HOURS`, default 24 hours. Schedule `search:status --prune`
to expire tombstones and clean eligible retired generations:

```rust
schedule.add(schedule.try_command("search:status --prune")?.daily());
```

Soft-deleted models normally leave the index. Add `#[searchable(soft_delete)]`
to retain a filterable `__soft_deleted` flag, and call `.with_trashed()` to read
them. Both declaration and query must opt in.

Bulk APIs are `Article::make_all_searchable().await?`,
`Article::remove_all_from_search().await?`, and the free functions
`suprnova::search::searchable::<Article>(&keys).await?` and
`unsearchable::<Article>(&keys).await?`, where keys are `String`s. They chunk
work by `SEARCH_CHUNK`, default 500. Mass `update_all`, `delete_all`, and
`force_delete_all` do not emit model events. Import after mass updates; flush
then import after hard mass deletes so orphaned documents leave the index.

To suppress automatic synchronization within one awaited operation, use
`Article::without_syncing_to_search(|| async { /* model writes */ Ok(()) })`.
It is task-local; other tasks continue syncing. Reimport the affected rows
afterward. Declare `#[searchable(touches("comments"))]` on a parent whose
document depends on that relation. `search_touches` captures dependent parent
keys when related models change, then reloads parents and their chunk hook.

### Generations and switching

`search:reindex` and index-time settings changes build a hidden generation.
Live writes target both current and building generations. A durable pending-job
ledger, separate from queue storage, records deliveries and transaction-local
intents. After bulk import, the coordinator drains work through a watermark,
checks under the publication fence, and atomically switches readers. The old
generation remains until no pending job references it.

Drain waits have a 30-second deadline. A stalled worker or continuous writes
can time out a build while the current generation remains readable; rerun to
resume. Status recovers interrupted dispatches. SQL and external Qdrant/vector
services do not share an atomic transaction; retained job identities and
authoritative reloads support retries after interrupted acknowledgements.

An application with a single migrator can recover an interrupted generation
while holding its own exclusive migration lock. Call
`suprnova::search::generations::reclaim_generation(index, &generation).await?`,
or run `search:reclaim <index> <generation>` under that same ownership.
The caller vouches that the previous creator has stopped. The framework cannot
see or acquire the application's lock.

`Reclaimed::LeaseReleased` clears a creating generation's lease immediately;
call the existing create path with the same generation and settings to resume.
`Reclaimed::Published` publishes a building generation through the normal fence,
which still refuses pending jobs. `Reclaimed::AlreadyCurrent` means readers
already use the generation. Unknown generations and other states fail by name.

With exclusive migration ownership held, recover a known generation through
your application's console binary:

```sh
cargo run --bin console -- search:reclaim products catalog_v2
```

## Scopes and the viewer

An index scope returns a `Filter` over the filterable fields its
`scope_fields` name; a scope that reads any other field fails the read with an
error naming the field. A recommendation event records the target's values
for exactly those fields as its access boundary, so name only what the scope
reads, for every viewer, signed in or not. Every read
path applies it inside engine candidates: hits, keys, raw projections, facets,
stats, totals, groups, federation, the JSON endpoint, and recommendation reads.
The request supplies `Viewer::current()` through Auth. Background code can use
`.for_viewer(viewer)`; without a request identity it receives `Viewer::Guest`.

Hydration rechecks the live row against the scope. Writes to scoped models
refresh access after commit before returning. Keep ownership and visibility
in the declared filterable document and scope, not just in a hydration callback
or a presentation filter. The model example above limits reads to its owner.

## Analytics and suggestions

Set `SEARCH_ANALYTICS=true` to retain searches. It is off by default. The
`search_queries` table records index, original and folded query, filters, hit
count, and processing time. `SEARCH_ANALYTICS_VIEWER=true` additionally stores
authenticated viewer ids; guest identities are never stored in query rows.
`search_impressions` holds a session hash and the exact shown keys with
zero-based positions. `search_clicks` records accepted clicks.

`Search::click(&impression, &key, position).await?` accepts only an unexpired
impression from the current server session containing that key at that
position. Analytics-disabled, missing, expired, other-session, and forged
position reports fail. With [recommendations](recommendations.md) enabled,
shown impressions and validated clicks also become recommendation events.

`Search::suggest("articles", "gar", 10).await?` returns Unicode-case-folded
retained queries for that index by frequency with stable ties. The limit is
at most 1000; disabled analytics returns none. `search:analytics` reports top
queries, zero-result queries, and click positions. Retention defaults to 90
days through `SEARCH_ANALYTICS_RETENTION_DAYS`. Schedule pruning explicitly:

```rust
schedule.add(schedule.try_command("search:analytics-prune")?.daily());
```

Pruning deletes linked clicks, impressions, and queries and also expires search
tombstones. Recommendation event retention remains an independent application
decision.

## Search pages in RenderCache

A search that runs on a route opted into [RenderCache](render-cache.md) is
stored like any other render. The stored page depends on each index the
search read. Any change to one of those indexes makes the page stale, so the
next request renders it again:

- Indexing or removing documents, one at a time or in bulk, including
  imports and queued `SearchIndexJob` work.
- Flushes, generation creation, reindexing, generation switches, and index
  deletion.
- Settings sync.
- Tombstone pruning and pending vector writes.

A write to another index leaves the page alone. Each logical index is one
dependency, so a switch to a new generation invalidates the page the same way
a document write does.

Declare every query parameter the search reads. A request that carries an
undeclared query parameter bypasses the cache, and each declared value gets
its own entry, so page 2 is stored apart from page 1:

```rust
use suprnova::{FrameworkError, Router};
use suprnova::render_cache::{
    FreshnessPolicy, QueryPolicy, RenderCachePolicy, RepresentationClass,
};

fn cache_docs_search(router: Router) -> Result<Router, FrameworkError> {
    router.try_render_cache(
        "/docs/search",
        RenderCachePolicy::builder(RepresentationClass::PublicShared)
            .freshness(FreshnessPolicy::new(300_000, 60_000, 300_000)?)
            .query(QueryPolicy::declared(["q", "page"]))
            .build()?,
    )
}
```

Some searches must run on every request. RenderCache serves the page they
render but never stores it, and records a `declined` outcome with one of these
reasons (see [RenderCache Operations](render-cache-operations.md)):

| Search | Reason |
|---|---|
| The index declares a [scope](#scopes-and-the-viewer), or the search calls `.for_viewer(...)`. | `viewer_scoped_search` |
| `SEARCH_ANALYTICS=true` is set, so each request records an impression. | `analytics_search` |
| The search calls `.without_render_cache()`. | `search_opt_out` |

When you turn analytics on, RenderCache also stops serving search pages that
it stored while analytics was off.

`.without_render_cache()` keeps one search out of the cache. It is available
on `Model::search`, `Search::for_index`, and `Search::federated`:

```rust
use suprnova::{FrameworkError, Search};

async fn live_stock_count(query: &str) -> Result<usize, FrameworkError> {
    let results = Search::for_index("inventory")?
        .search(query)
        .without_render_cache()
        .get()
        .await?;
    Ok(results.hits.len())
}
```

Inside a cached render, an unscoped search with analytics off runs as
`Viewer::Guest` and does not read the session. Without a scope the viewer
changes no result, and a session read would make the page uncacheable.

A custom engine needs no extra code. The registry guards each of its writes
and advances the index after the write finishes.

## JSON endpoint

Register an explicit allowlist with `Search::routes(&["articles"])?`, which
returns a `Router`, or `router.try_search_endpoint(&["articles"])?` on your
existing router. Unknown or duplicate registration names fail. Attach session
and your authentication middleware, and apply your rate-limiting policy.
Analytics-enabled endpoint requests require a nonempty server session.

`GET /search` accepts:

| Parameter | Default | Meaning |
|---|---|---|
| `index` | None | An allowlisted index name. |
| `q` | Empty | Query words, phrases, and exclusions. |
| `filter` | None | The typed filter grammar above. |
| `facets` | None | Comma-separated declared facet attributes. |
| `sort` | None | Comma-separated `attribute:asc` or `attribute:desc`; omitted direction is ascending. |
| `page` | 1 | Positive one-based page. |
| `per_page` | 20, bounded by the index cap | Positive page size, at most the effective hit cap. |

For example, `GET /search?index=articles&q=gardem&page=1&per_page=10` returns:

```json
{
  "hits": [{
    "attributes": {"title": {"type": "text", "value": "Garden planning"}},
    "key": "1",
    "score": 2.5,
    "normalized_score": 1.0,
    "formatted": {"title": "<em>Garden</em> planning"}
  }],
  "facets": {},
  "total": 1,
  "total_estimated": false,
  "page": 1,
  "per_page": 10,
  "processing_time_ms": 2,
  "impression": "550e8400-e29b-41d4-a716-446655440000"
}
```

The example abbreviates the document attributes. The actual response contains
only declared attributes, using `AttributeValue`'s `type`/`value` encoding,
and no additional hydrated model fields. `impression` is present only when
recorded. An unlisted or missing index returns a non-disclosing 404. Invalid
filters, facets, sorting, page sizes, or page numbers, and a `q` over 65536
bytes or 1024 words, return 422 errors naming the failing parameter;
undeclared attributes are refused.

`POST /search/click` accepts JSON
`{"impression":"...","key":"1","position":0}` and returns
`{"recorded":true}` after validation. It requires the same session and a
valid CSRF token under the [CSRF middleware](csrf.md).

## Live search-box

Install the shipped component with `suprnova live:add search-box`. It installs
the `search-input` dependency, Askama macro and island templates, stylesheet,
and JavaScript, and registers `suprnova::live::components::SearchBox`.
Mount it with server-owned parameters `{"index":"articles","per_page":10}`;
`per_page` must be 1-100. The index cannot change through a model proposal.

The presentational macro's arguments are:

```text
search_box(name, label, query, hits, facets, filters, impression,
           sequence=0, control_id="query")
```

The island binds query text with a 250 ms debounce and renders highlighted
results and optional facet checkboxes. Arrow keys, Home, End, Enter, and Escape
control the combobox/listbox. A query sequence rejects stale results, including
repeated text from an older request. Each mount owns its control ids. Clear
filters remains available when selected facets produce no results.

Selection validates the key against the signed shown list, records its click
when analytics supplies an impression, and emits `search.selected` version 1.
The browser event is `suprnova:search.selected` with `{index, key}`. Use it to
navigate or update the hosting page. See [Live](live.md) for mounting and
event handling. The Live kit's notes list uses the same scoped model search
and checked highlights within its own note-list component.

## Starter kits

The Svelte, React, Vue, and Live kits search notes through `Note::search` with
title/body highlights and an owner scope. Inertia search cursors bind the query
and offset; the Live list loads ranked pages and records only displayed
impressions. Empty search keeps the notes listing behavior.

Register an account first, then run:

```bash
cargo run --bin console -- db:seed
```

`NotesSeeder` attaches three example notes to the first registered account:
Garden planning, Ocean journal, and Library reading. It creates no account of
its own and fails with registration instructions when none exists. Repeated
seeding does not duplicate those titles for that owner. Sign in as that account
and search `oceam` to find Ocean journal through a one-letter typo. For rows
that predate search, run `cargo run --bin console -- search:import notes`.

The kit migrator lists both `search::migrations()` and
`recommendations::migrations()`. Bootstrap provisions the initial notes index,
registers `NotesSeeder`, and schedules search maintenance. The default search
driver uses the kit's database.

## Relevance and latency baseline

`search:baseline` measures the complete committed SciFact BEIR test split:
5183 documents, 300 queries, and 339 judgments. Claims and judgments are
CC BY 4.0; abstracts are ODC-By 1.0. Attribution, licenses, corpus, queries,
and judgments live in `framework/tests/search/fixtures/`.

Calibration indexes the same corpus into Meilisearch and Typesense, waits for
imports, and measures each rival over a small grid of its own search settings:
Meilisearch's `matchingStrategy` (`last`, `frequency` and `all`), and
Typesense's `drop_tokens_threshold` (1 and 10) with `text_match_type`
(`max_score` and `sum_score`). Every grid entry warms every query, then records
nDCG@10 and p50/p95/p99 latency. The entry with the highest nDCG@10 becomes the
rival's score; a tie goes to the lower p95. `baseline.json` keeps the chosen
settings and the whole grid. The committed calibration is:

| Rival | Version | Chosen settings | Lexical nDCG@10 | p95 |
|---|---|---|---:|---:|
| Meilisearch | 1.55.0 | `matchingStrategy` `frequency` | 0.4665 | 2.232596 ms |
| Typesense | 30.2 | `drop_tokens_threshold` 10, `text_match_type` `max_score` | 0.4274 | 52.005666 ms |

Lexical mode must reach the stronger rival minus the committed absolute
tolerance, 0.05: the floor is about 0.416543. Hybrid mode at the benchmark's
ratio 0.5 must exceed 0.466543. Every engine's committed p95 budget is
104.011332 ms, about 104.0 ms. It is two times the slower rival's p95, with its
chosen settings, from the same calibration run. If a rival refuses a request,
calibration stops with the error and leaves `baseline.json` as it was.
`search:baseline calibrate` writes the budget and
the loader re-derives it; a hand-edited budget that disagrees is refused.

Supply `SEARCH_BASELINE_MEILISEARCH_URL`, `SEARCH_BASELINE_MEILISEARCH_KEY`,
`SEARCH_BASELINE_TYPESENSE_URL`, and `SEARCH_BASELINE_TYPESENSE_KEY` through
your deployment's environment, then run from this repository:

```bash
cargo run --release -p app --bin console -- search:baseline calibrate
cargo run --release -p app --bin console -- search:baseline run --engine sqlite
```

Review and commit the replacement `baseline.json` after calibration.
`SEARCH_BASELINE_TOLERANCE` defaults to 0.05. An uncalibrated fixture is refused
unless you explicitly set `SEARCH_BASELINE_ALLOW_UNCALIBRATED=1`; that override
does not turn provisional numbers into rival measurements.

Framework measurements warm an isolated generation with a fixed vocabulary.
Each sample asks for the first page of 10 hits at the depth the builder
requests for that page. The engine sample includes parsing, expansion,
retrieval, and fusion. Query
inference has separate percentiles. Corpus embedding, indexing, vocabulary
preparation, and hydration are outside that sample; vocabulary preparation is
reported separately. Records under `target/search-baseline/<engine>.json`
include engine, model profile and provenance, fixture digest, rival versions,
measurement time, and tree hash.

`BudgetCheck::for_build()` enforces p95 only in an optimized build and reports
it in a debug build. Relevance floors apply in both. The rivals run as release
binaries, so the release gate measures with
`cargo nextest run --cargo-profile release`. For example:

```bash
cargo nextest run --cargo-profile release -p suprnova --test search \
    -E 'test(/^baseline::baseline_(collection|sqlite)$/)'
```

Live engine measurement tests have a fifteen-minute nextest limit. When
`SEARCH_EMBEDDER` is set to a model provider, the corpus is embedded first;
run `cargo nextest run --profile search-model` for its six-hour limit. Add
`--features search-fastembed` for local inference, and `--run-ignored only`
when selecting ignored service or real-model tests. Postgres and MySQL baseline
runs read `PG_TEST_URL` and `MYSQL_TEST_URL`; Qdrant service tests use
`QDRANT_TEST_URL`, while the console uses `QDRANT_URL`. Use disposable test
databases. These test variables are listed in [Environment Variables](env-vars.md).

## Matching rule

A document needs any ordinary query word. The engine's own relevance ranks
documents holding more of those words higher. Quoted phrases are required,
and minus-prefixed words are excluded. The last ordinary word also matches
prefixes. Engines can order the same matches differently.

For `apple pie "fresh baked" -green`, with no additional typo or synonym
alternatives, the renderings are:

| Engine | Rendered predicate |
|---|---|
| Collection | `(apple OR pie*) AND phrase("fresh baked") AND NOT green` |
| SQLite | `(("apple") OR ("pie"*)) AND "fresh baked"`, with `rowid NOT IN (... MATCH '"green"')` |
| Postgres | `((('apple')) \| (('pie':*))) & ('fresh' <-> 'baked') & !('green')` |
| MySQL | `(pie*) ("apple") +"fresh baked" -"green"`, plus a MATCH guard requiring an ordinary positive word |
| MariaDB | `(pie*) ("apple") +"fresh baked" -"green"`, with the same guard |
| Qdrant | `must=[should(text_any(apple), text_any(pie) OR prefix(pie)), per-field phrase("fresh baked")]; must_not=[text(green)]` |
| Null | No hits. |

MySQL and MariaDB put the prefix group first because their boolean parser can
ignore a prefix after a quoted term. Runtime values remain bound even when
the engine query syntax contains these rendered clauses.

## Commands

Run commands through your application's console binary, such as
`cargo run --bin console -- search:status`. Unknown options fail.

| Command | Arguments and flags | Purpose |
|---|---|---|
| `search:index` | `<index>` | Create an initial generation. |
| `search:import` | `<Model\|index>` | Import eligible rows in chunks. |
| `search:flush` | `<Model\|index>` | Remove indexed documents with versioned removal fences. |
| `search:delete-index` | `<index>` | Drain pending references and remove index storage. |
| `search:sync-index-settings` | `[index]` | Sync one or all declared indexes; report classes and build as needed. |
| `search:reindex` | `<Model\|index>` | Build or resume a generation and publish it after draining. |
| `search:reclaim` | `<index> <generation>` | Release an abandoned creation lease or publish a built generation under the caller's migration lock. |
| `search:status` | `[index] [--prune]` | Report generations and server token limits; optionally prune. |
| `search:analytics` | `[--index name] [--days N]` | Report retained demand, misses, and click positions; default 30 days, bounded by retention. |
| `search:analytics-prune` | None | Delete expired analytics and prune tombstones. |
| `search:baseline` | `calibrate` or `run [--engine collection\|sqlite\|postgres\|mysql\|qdrant]` | Replace calibration or measure engines; run defaults to collection and SQLite. |

Model names can be unambiguous short names or fully qualified names.
`search:index`, `search:delete-index`, `search:reclaim`, settings sync, and status take index names.
The full [environment reference](env-vars.md#search) covers queue, embedding,
Qdrant, analytics, and calibration controls.

## Testing search

Use a fresh collection engine and isolated registry for deterministic tests.
This runnable async test requires no database or download:

```rust
#[tokio::test]
async fn collection_search_conforms() -> Result<(), suprnova::FrameworkError> {
    use std::sync::Arc;
    use suprnova::search::{CollectionEngine, testing::conformance};

    conformance::run(Arc::new(CollectionEngine::new()), conformance::Options::default()).await
}
```

The `testing` feature exposes conformance. Its isolated generations exercise
filters, facets, stats, ranking, scope predicates, phrases, exclusions, sorts,
geo, versioned writes, and generation switching. Semantic checks use
three-dimensional vectors; configure a persistent vector store accordingly.
It restores an existing current generation on success; a new index retains an
empty active generation. `Options` lets you choose an isolated `index_name`
and optional `test_semantic`/`test_geo` checks.

For model tests, `SearchRegistry::isolated(async { ... }).await` separates
services. `SearchConfig::scope(config, future).await?` scopes configuration;
`FakeEmbedder::new(16)?` gives deterministic normalized vectors without network
or inference. Register it under a provider name and select that name in the
index's settings. Keep real-provider tests separate from engine conformance.

### Why Suprnova diverges

Laravel Scout supplies drivers for hosted search products and a model-oriented
builder. Suprnova keeps native ranking in your database or Qdrant, then adds
query expansion, formatting, and fusion around it. There are no Algolia,
Meilisearch, or Typesense search drivers; the baseline measures against
Meilisearch and Typesense on the same judged corpus.

Generations separate complete rebuilds from live reads. Viewer scopes run
inside every candidate read and are checked again on live rows. Typed filter
grammar validates attributes and binds values before a driver sees them.
These guarantees also cover facets, federation, and recommendation reads.

## Next

- [Recommendations](recommendations.md) - record interactions and read scoped suggestions.
- [Vector](vector.md) - configure semantic storage for database search.
- [Queues](queues.md) - run indexing workers on your configured connection.
- [Live](live.md) - mount search-box and handle its selection event.
- [Environment Variables](env-vars.md) - all search configuration defaults.


---

<!-- /docs/recommendations -->

# Recommendations

You record interactions with searchable documents and read recommendations
through `Recommend`. The starter engine uses SQL events, search facets,
timestamps, scopes, and optional search vectors. You need no embedding model
to generate collaborative, attribute-affinity, popularity, and recent results.
The `Recommender` trait lets you replace the engine without changing callers.

The purpose of the starter engine is to build the data the graph recommender
needs: immutable events, materialized recommendations, explanations, and run
records under a versioned storage contract. Two engines ship: `starter`, the
default, and `graph`, which you select with `RECOMMEND_ENGINE=graph` once your
events carry enough shared engagement (see
[Rank with the graph engine](#rank-with-the-graph-engine)).

## Record events

Install the migrations and provision the target's [search index](search.md)
first. In an authenticated request, this function records a view of an existing
searchable note and returns its provenance:

```rust
use suprnova::{
    EventProvenance, EventType, FrameworkError, Recommend,
    RecommendationEvent, RecommendationTarget,
};

async fn record_note_view(key: &str, dedupe: &str) -> Result<EventProvenance, FrameworkError> {
    let target = RecommendationTarget { index: "notes".into(), key: key.into() };
    let event = RecommendationEvent::new(EventType::View, target, None, "notes", dedupe).await?;
    Recommend::record(event).await
}
```

`RecommendationEvent::new(event_type, target, actor, surface, dedupe_key)` loads
the registered target's document. It captures its source version, the index's
guest access filter as canonical JSON, and the current UTC time. A missing or
ineligible target is an error. The access-scope snapshot describes the fact's
record-time policy; it does not replace the current viewer's scope on reads.
Recording requires a target, a non-null scope equal to the descriptor's guest
filter, and a source version. The event also stores its type, weight, actor,
surface, dedupe key, and scoring snapshot.

With `actor=None`, Auth supplies the authenticated user. For guests, resolve
`Actor::current(Some(server_session_id)).await?` or
`Actor::guest(server_session_id)?` and pass that actor to the constructor.
Guest actors store a lowercase SHA256 session digest, never the raw session.
Trusted background code can use `Actor::User(user_id)`. Never take an actor
from a request body: `Actor` and `RecommendationEvent` have no `Deserialize`
implementation. Resolve identities on the server.

A dedupe key is unique per actor. Repeating an actor/key pair returns the
original event id and digest and leaves that first event unchanged, even if
the retry changes its type or weight. Separate actors can use the same key.
Use a stable interaction identity for retries. Surface and dedupe key allow
1-128 bytes without control characters; target index allows 128 bytes and
target key 255.

`Recommend::record` validates the actor and dedupe key before resolving a retry.
An existing fact returns its original provenance even after its target is deleted
or its access scope changes. A first write still requires a live target and a
matching access-scope snapshot.

### Event types and scoring

Every event's score is its base plus signed integer `weight / 20`. Weight is
in basis points from -10000 to 10000, defaults to zero, and division truncates
toward zero. Class determines how the event affects recommendations; changing
weight does not turn an impression into positive affinity.

| Event type | Rust variant | Class | Base score |
|---|---|---|---:|
| `view` | `EventType::View` | Positive | 1000 |
| `consume` | `EventType::Consume` | Positive | 1000 |
| `complete` | `EventType::Complete` | Positive | 1200 |
| `skip` | `EventType::Skip` | Negative | -1000 |
| `hide` | `EventType::Hide` | Negative | -1000 |
| `report` | `EventType::Report` | Negative | -1000 |
| `like` | `EventType::Like` | Positive | 1400 |
| `favorite` | `EventType::Favorite` | Positive | 1600 |
| `share` | `EventType::Share` | Positive | 1500 |
| `comment` | `EventType::Comment` | Positive | 1200 |
| `follow` | `EventType::Follow` | Positive | 800 |
| `impression` | `EventType::Impression` | Seen | 0 |
| `click` | `EventType::Click` | Positive | 300 |
| `purchase` | `EventType::Purchase` | Positive | 2000 |
| Application name | `EventType::Custom(String)` | Positive | 500 |

`EventType::from_name` recognizes the shipped names even when supplied through
`Custom`. Declare application classes and base scores through
`RecommendConfig.event_types` or `RECOMMEND_EVENT_TYPES`:

```json
{"playlist_add":{"class":"positive","score":1600},"dismiss":{"class":"negative","score":-1200}}
```

Classes are `positive`, `negative`, and `seen`. Override scores must be between
-1000000 and 1000000. Overrides also accept shipped event names. Existing
events keep their stored class and score when configuration changes.

## Generate with the starter engine

The batch reads at most `RECOMMEND_HISTORY` newest positive and negative
events per actor combined, ordered by time and id; the default is 500. Seen
impressions are aggregated separately in SQL and do not consume those slots.
Shared positive targets identify peers, sampled to `RECOMMEND_PEERS` (200)
by their most recent shared activity. Candidate scores sum sampled peers'
positive scores. A collaborative candidate needs at least `RECOMMEND_MIN_PEERS`
(3) distinct peers: with fewer, it can still arrive through a later tier, which
names no peers. Otherwise a suggestion whose peer count is 1 would point at that
one person, and the suggestion would be one of their own views or purchases.
`Recommend::similar_to` counts co-occurrence under the same rule. Negative and
previously seen/interacted targets are excluded.
Materialized reads also enforce the current peer minimum, so older rows cannot
reveal a lone peer while waiting for the next generation. That generation
refreshes all actors when ranking settings change, replacing stale scores and
explanations even when no history changed.
Scores sort descending with `(index, key)` as a deterministic tie-break.

When the higher tier is short, results fill in this order:

1. Collaborative candidates from shared positive targets, with search semantic
   neighbours folded in when vectors exist.
2. Attribute affinity over declared facet values of authorized positive seeds.
3. Popularity from positive activity in `RECOMMEND_POPULARITY_WINDOW`, default
   30 UTC days.
4. Recent eligible documents, using `published_at`, `created_at`, or
   `updated_at` when declared, otherwise the search source version.

Declare facet and timestamp attributes on your searchable models to supply
those signals. Semantic retrieval reuses the target index's provider, document
profile, generation, and vector store. It creates no second vector store.
Every target passes the viewer's search scope inside candidate retrieval and
again against its live document before display. Removed or inaccessible
documents cannot supply displayed evidence.

Run `cargo run --bin console -- recommendations:generate` on demand. Add this task to your
application's schedule:

```rust
schedule.add(
    schedule.command("recommendations:generate").hourly().without_overlapping()
);
```

`schedule.command("recommendations:generate").hourly().without_overlapping()`
uses the same generation path as an on-demand command. The starter also holds
a renewable cache lock named `recommendations:generate`, with
`RECOMMEND_LOCK_TTL_SECS` defaulting to 3600 seconds. Configure a shared lock
backend when several processes generate recommendations. Contention returns
`GenerationOutcome::Locked` immediately; a lost lease aborts the run.

### Runs and explanations

Runs have `running`, `complete`, or `failed` states. A run stages rows under
its own id and publishes by marking itself complete in one statement. Reads
select only the latest completed run and retrieve ranked rows and evidence together
in bounded pages pinned to that run. Previous rows are removed only after publication. A failed
run removes its staged rows and explanations, keeps an error record, and leaves
the previous completed run current.

Generation tracks a completed high-water mark, new events, capped history
snapshots, a search catalog digest, and a ranking settings digest covering the
history cap, peer cap, peer minimum, and popularity window. It regenerates affected
actor/surface pairs and copies unaffected rows into the next snapshot. History and
catalog checks catch late commits and changed content. A filtered `--user` or
`--surface` run preserves other rows and does not consume their pending global
delta or a pending ranking settings refresh.

`recommendation_runs` records start time, duration in milliseconds, events
read, new events, users covered, items scored, coverage, fallback share,
high-water mark, catalog digest, ranking digest, history snapshots, state, and error.
`recommendations:status` prints the ten latest attempts. The committed
million-event fixture has a 300-second generation budget; run its ignored
budget test separately from ordinary application tests.

Every materialized row carries its run id and explanation id. The public
explanation contains peer and shared-target counts, authorized affinity
attribute values, a tier (`collaborative`, `semantic`, `affinity`, `popularity`,
or `recent`), and shared-target titles only where the viewer can see them.
It exposes no peer identity, peer interaction, or private evidence id. Stored
evidence retains event provenance for derivation without exposing it in the
display projection.

New starter explanations retain every contributing positive event, including both
actors' events on each shared target and repeated events whose scores were summed.
Verify each stored id/digest pair with `Recommend::verify_provenance`; a deleted
contributor returns `Removed`. Regenerate older recommendations to refresh their
stored evidence.

## Read recommendations

Select the subject and surface, and let the request resolve the viewer:

```rust
use suprnova::{FrameworkError, Recommend, Recommendation, Viewer};

async fn home_recommendations(user_id: &str) -> Result<Vec<Recommendation>, FrameworkError> {
    let viewer = Viewer::current().await?;
    Recommend::for_user(user_id)
        .surface("home")
        .limit(10)
        .for_viewer(viewer)
        .get()
        .await
}
```

`for_user` takes a string-like user id, not an authorization decision. Your
application authorizes which subject a caller may request. The viewer comes
from Auth when `get()` executes or from explicit `for_viewer`. Without an
identity, the guest scope applies. `Recommend::for_actor(actor)` supports a
trusted guest actor too. The default surface is `home`, the limit is 10,
zero returns no rows, and limits above 10000 fail. Before a completed run
exists, materialized reads return no recommendations.

Materialized reads hydrate only a page's candidate targets and shared evidence
targets. They refill after authorization filtering until the requested limit is
met or the ranked rows run out. On-demand similarity loads bounded histories only
for the selected peers and the viewer, preserving peer selection and score order.
Custom search engines support `SearchEngine::stored_keys` for keyed starter reads,
as they do for graph reads, so removed search documents stay excluded.

`Recommend::similar_to(RecommendationTarget { index: "notes".into(),
key: "1".into() }).for_viewer(viewer).limit(10).get().await?` computes
co-occurrence with optional semantic neighbours on demand. It refuses a
missing or inaccessible seed before scoring. The viewer's negatives and seen
targets are excluded. Its results have `run_id=None`; materialized results
name the completed run. Both return a target, declared `SearchDocument`,
score, one-based returned rank, and projected explanation.

## Rank with the graph engine

The graph engine keeps a knowledge graph of your search documents and ranks
from it live, at read time. Every node and edge it holds names its source, and
every hop it takes stays inside the viewer's scope. When the graph supports a
list too thinly, it answers with the starter engine's rows for the same viewer
and says so, so turning it on early costs nothing.

### Turn it on

Set `RECOMMEND_ENGINE=graph`. `Recommend::generate` then publishes the starter
run as before, because those rows are the fallback, and pushes a
`GraphDeriveJob` onto your queue, so the graph engine needs a configured queue.
The job rebuilds the graph into a new generation and switches readers to it
only when the rebuild completes; a failed rebuild leaves readers on the
previous one. Run `recommendations:graph-rebuild` or
`Recommend::rebuild_graph()` to rebuild at once.

### What the graph holds

A rebuild reads the event stream, within each actor's `RECOMMEND_HISTORY`
bound, and the relations you declare, over the documents still in their
search index:

- **Shared engagement.** Two documents get a `co_engaged` edge when at least
  `RECOMMEND_MIN_PEERS` actors hold both among their most recent
  `RECOMMEND_GRAPH_FANOUT` positives. Positive events count, and only the
  aggregate is stored, so no edge describes one person.
- **Public engagement.** For the event types `RECOMMEND_PUBLIC_EVENT_TYPES`
  lists, each signed-in actor gets an `engaged` edge to the documents they
  engaged with. No type is public unless you list it; a type that is not
  public never becomes a per-actor fact.
- **Declared relations.** A relation reads related documents from a
  document's search projection, so the graph follows it without loading
  models. Its edges run both ways, as `relation:<name>` and
  `relation:<name>:inverse`.

```rust
use suprnova::{AttributeValue, FrameworkError, GraphRelation, Recommend, RecommendationTarget};

// Each track points at its artist, at 80 percent confidence.
pub fn declare_relations() -> Result<(), FrameworkError> {
    Recommend::graph_relation(GraphRelation::new("artist", "tracks", 8_000, |document| {
        Ok(match document.attributes.get("artist_id") {
            Some(AttributeValue::Integer(id)) => vec![RecommendationTarget {
                index: "artists".into(),
                key: id.to_string(),
            }],
            _ => Vec::new(),
        })
    })?)
}
```

Every fact carries the scope of the document it describes, that document's
source version, and its provenance: an event's id and content digest, or the
relation and the document revision it was read from. A rebuild is
deterministic, so rebuilding from the same stream and documents reproduces the
same facts. Between rebuilds the graph follows its sources: a search write
queues a `GraphDocumentJob` that removes what a deleted document held and
replaces what a newer revision changed, and `Recommend::prune` removes the
facts resting on the events it deletes. It deletes the oldest events first,
in pages, and revokes each page's facts before the page goes, so a failed
revocation leaves the events for a retry to find. A shared-engagement edge
names its oldest event as provenance, so it goes as soon as one actor's
event behind it does. A removed fact is never read, traversed or cited again.

A document revision replaces its node in place before removing stale declared
relations, so its event-backed engagement edges keep counting. If the job fails
after saving the node, retrying the same revision finishes the relation writes.
Custom graph stores handle `Revocation::DocumentRelationsBefore` by removing
older relation-derived edges and auxiliary nodes while preserving the document
node itself. `DocumentBefore` retains its existing broader removal behavior.

### Where the graph lives

The graph lives behind the `GraphStore` trait, which `RECOMMEND_GRAPH_STORE`
selects:

- `database`, the default, keeps the graph in your application's database
  (SQLite, Postgres, MySQL or MariaDB), in the tables the recommendation
  migrations create, so the graph engine needs no other service.
- `memgraph` keeps it in a Memgraph server over the Bolt protocol. Enable the
  `graph-memgraph` feature and set `RECOMMEND_GRAPH_URL` to a `bolt://` or
  `bolt+s://` address without credentials; `RECOMMEND_GRAPH_USERNAME` and
  `RECOMMEND_GRAPH_PASSWORD` are read only when the store connects. Memgraph
  holds the graph in memory, so after its data is lost, run
  `recommendations:graph-rebuild` to restore it from the stream.

A store only persists facts and answers bounded hops; the framework applies
the viewer's scope at every hop and computes every score, so both stores rank
the same graph the same way. Bind your own `GraphStore` in the container to
replace both.

### How the graph ranks

A read authorizes before it scores. Seeds, negatives, every traversed edge
and every candidate must pass the viewer's scope. The read also checks every
fact it walks, scores or cites against its live source:

- a document node counts only while its document is still in its index, which
  `unsearchable` ends, and the viewer may see the live document;
- a fact resting on an event counts only while the event is still in the
  stream;
- a relation fact read from an older revision of its source counts only while
  the relation still finds it in the live revision.

So a fact whose `GraphDocumentJob` is still queued, or one a rebuild read
before its source changed, never counts, while a document saved again keeps
counting. The blended score then weighs:

- graph affinity, the strongest path of at most `RECOMMEND_GRAPH_DEPTH` hops
  from one of the viewer's positives, weighted by that positive;
- semantic similarity in the search collection's own vectors (see below);
- social proximity (see below);
- freshness, from `published_at`, `created_at` or `updated_at`;
- the viewer's negatives near the candidate, subtracted;
- trust risk, the target's hide and report events weighed against its
  positive events, subtracted.

`RECOMMEND_GRAPH_SURFACES` sets per-surface weights, a confidence threshold
and diversity caps in basis points and counts; a surface it does not name uses
the defaults:

```bash
RECOMMEND_GRAPH_SURFACES='{"home":{"affinity":5000,"threshold":6000,"per_value":2}}'
```

The caps keep one list from collapsing: at most `per_value` results share one
facet value, at most `per_node` are reached through one intermediate node, and
at most `per_band` come from the most popular tenth of the catalog. The
confidence is the share of the list that graph paths or social proximity
support. Below the surface's `threshold` the engine returns the starter's rows,
with `explanation.engine` set to `starter` and `explanation.fallback_reason`
saying why.

A graph row's explanation has `engine` set to `graph` and `evidence` listing
the stored facts it rests on: the viewer's own events, as id and digest, the
edges of the path, and the seed documents, every one of which the viewer may
see. It never names a peer or a followed actor. Serialized explanations omit
`engaged` and `co_engaged` edge references because their keys can be recomputed
from known actors or documents. The server-side explanation retains those
references for verification against the graph store; public counts remain
available. Keep the server-side explanation when verifying engagement evidence:
serializing and loading it again does not restore those private references.

### Social proximity

Social proximity counts followed actors who publicly engaged with a target.
Set `RECOMMEND_ACTOR_INDEX` to the search index whose documents are your
users, keyed by user id; a viewer's `follow` events on that index's documents
name the actors they follow. Only `engaged` edges, which exist only for
public event types, count, and a target gains social proximity only when at
least `RECOMMEND_SOCIAL_MIN_ACTORS` followed actors agree on it, so a viewer's
list never reveals what one followed account did. The explanation's
`peer_count` reports how many agreed.

### Similar items, vectors and discover

The graph engine reads the vectors your search collection already stores; it
keeps no copy. Where the index's search engine is Qdrant, it uses Qdrant's own
recommend and discover operations by point id, under the viewer's scope
filter. On the database and collection engines, it folds the stored vectors
into one query, the positives' mean pushed away from the negatives', and ranks
the result. The positive and negative points are always the viewer's own
events on documents the viewer may see. A graph read never steers by another
person's events: `Recommend::for_user(id)` read by a viewer other than that
user answers with the starter's rows for the user, with `fallback_reason`
saying why, and so does `Recommend::for_actor(actor)` with a guest actor read
by a signed-in viewer.

`Recommend::similar_to(target)` seeds the graph and the vectors with one
document; the viewer's negatives push the vectors away and, like the targets
the viewer has already seen, are left out of the list.
`Recommend::discover(target)` searches near a document and ranks the
neighbourhood by context pairs built from the viewer's own positive and
negative events. Every negative joins a pair, repeating positives when there
are fewer of them, or pairing with the seed when the viewer has none. It needs
the graph engine and refuses a seed the viewer cannot see.

## Bridge search events

Set both `SEARCH_ANALYTICS=true` and `RECOMMEND_ENABLED=true` to forward shown
search impressions and validated clicks into the event stream. The bridge
uses the authenticated actor or a server-session hash, surface `search`, and
dedupe keys derived from impression id, event type, and shown position.
Impressions count as seen; clicks contribute the click score.

Search verifies the impression's session, expiration, key, and zero-based
position before forwarding a click. A forged key or position supplies no
recommendation event. The `POST /search/click` endpoint also requires CSRF.
See [Search](search.md) for analytics middleware and endpoint registration.

`RECOMMEND_ENABLED` controls automatic search forwarding. It does not disable
explicit `Recommend::record` or generation. Turning search analytics off
stops its event production; it does not erase recommendation history.

## Verify provenance and control retention

`Recommend::record` returns `EventProvenance { id, digest }`. The digest is
SHA256 over canonical event content, including its stored class and score.
Keep the pair together when you derive evidence. Verification re-reads content
and recomputes the digest:

```rust
use suprnova::{EventProvenance, FrameworkError, ProvenanceState, Recommend};

async fn evidence_is_intact(reference: &EventProvenance) -> Result<bool, FrameworkError> {
    Ok(Recommend::verify_provenance(reference).await? == ProvenanceState::Intact)
}
```

`Intact` means content matches, `Altered` means the id exists with changed or
invalid content, and `Removed` means retention removed the event. A
configuration change does not rewrite an earlier scoring snapshot.

Engines never prune or rewrite the append-only event stream. Your application
owns retention. Run `recommendations:prune --older-than 90` only when that is
your retention policy; the argument is a positive number of days. There is
no automatic event-expiration default. Pruning search analytics is separate.

## Commands

Run these through your application's binary:

| Command | Arguments and flags | Purpose |
|---|---|---|
| `recommendations:generate` | `[--surface name] [--user id]` | Publish a complete snapshot or report lock contention. |
| `recommendations:status` | None | Print the ten latest runs, including failures. |
| `recommendations:prune` | `--older-than days` | Apply your event retention policy. |
| `recommendations:graph-rebuild` | None | Rebuild the graph engine's facts into a new generation. |

Value flags accept `--name value` or `--name=value`. Unknown, repeated, empty,
and missing values fail. You can also call `Recommend::generate(GenerateRun)`,
`Recommend::status(limit)`, and `Recommend::prune(days)`; status limits are at
most 1000. `GenerateRun` has optional `user` and `surface` strings.

## Migrations and the data contract

Extend your application's migration list with
`suprnova::recommendations::migrations()`. The kits already include this and
`suprnova::search::migrations()`. The recommendation migrations create:

| Table | Stored contract |
|---|---|
| `recommendation_events` | Immutable id, actor kind/id, target index/key, type, weight, surface, UTC microsecond time, access scope (the index scope's guest filter and the target's values for the index's `scope_fields` when the event was recorded), source version, dedupe key, class, and score. |
| `recommendation_explanations` | Run id, event-id/digest provenance pairs, attribute values, peer count, shared-target count and references, and fallback tier. |
| `starter_recommendations` | Run id, actor, surface, target index/key, score, rank, and explanation id. |
| `recommendation_runs` | Publication state and batch statistics, watermarks, catalog digest, ranking digest, history snapshots, and error. |
| `recommendation_schema` | `recommendation_schema_version`, 2 once the graph migration runs. |
| `recommendation_graph_generations` | Graph generations and which one readers use. |
| `recommendation_graph_nodes` | Nodes per generation: key, type, target, scope, source version, and provenance. |
| `recommendation_graph_edges` | Edges per generation: key, endpoints, type, confidence, scope, source version, provenance, and times. |

The data this engine builds is the graph engine's input under that versioned
contract. Event identity plus content digest distinguishes intact evidence
from facts removed by retention. These tables preserve the handoff without
requiring a graph to serve starter recommendations; the graph engine reads
them when you select it.

## Variables

| Variable | Default | Purpose |
|---|---|---|
| `RECOMMEND_ENABLED` | `false` | Forward validated search events automatically. |
| `RECOMMEND_HISTORY` | `500` | Newest positive and negative events per actor combined. |
| `RECOMMEND_PEERS` | `200` | Most recent shared peers to sample. |
| `RECOMMEND_MIN_PEERS` | `3` | Distinct peers a collaborative candidate needs. |
| `RECOMMEND_POPULARITY_WINDOW` | `30` | UTC days of positive activity for popularity. |
| `RECOMMEND_LOCK_TTL_SECS` | `3600` | Renewable generation lock lifetime. |
| `RECOMMEND_EVENT_TYPES` | `{}` | JSON class and base-score overrides. |
| `RECOMMEND_ENGINE` | `starter` | `starter` or `graph`. |
| `RECOMMEND_GRAPH_STORE` | `database` | `database` or `memgraph`. |
| `RECOMMEND_GRAPH_URL` | unset | The Memgraph Bolt address, without credentials. |
| `RECOMMEND_GRAPH_USERNAME` | unset | The Memgraph user, read when the store connects. |
| `RECOMMEND_GRAPH_PASSWORD` | unset | The Memgraph password, read when the store connects. |
| `RECOMMEND_GRAPH_DEPTH` | `2` | Most hops in a graph path, 1 to 4. |
| `RECOMMEND_GRAPH_FANOUT` | `50` | Most edges followed out of one node per hop. |
| `RECOMMEND_GRAPH_MAX_NODES` | `2000` | Most nodes one walk reaches. |
| `RECOMMEND_PUBLIC_EVENT_TYPES` | unset | Comma-separated event types other viewers may see. |
| `RECOMMEND_SOCIAL_MIN_ACTORS` | `3` | Followed actors who must agree for social proximity. |
| `RECOMMEND_ACTOR_INDEX` | unset | The search index whose documents are users. |
| `RECOMMEND_GRAPH_SURFACES` | `{}` | JSON per-surface weights, threshold, and caps. |

`RecommendConfig::current()` uses registered configuration, environment
configuration, or a task-local override from `RecommendConfig::scope`.
Malformed values and zero numeric bounds fail with the variable name.
See [Environment Variables](env-vars.md#recommendations) for types and limits.

## Testing

Use a migrated test database, a scoped searchable test model, a fresh
`CollectionEngine`, and `SearchRegistry::isolated` to exercise the real event
and read paths without external services. Set `SearchConfig.queue=false`
within `SearchConfig::scope` when your test needs inline indexing. Add a
`FakeEmbedder` only when testing semantic neighbours, and keep provider
qualification separate from ranking tests.

Record shared positives for the subject and three peers, an unseen candidate
the peers share, and negative and seen facts for the subject. Generate a run and check the candidate,
fallback order, authorized explanations, immutable dedupe result, and
provenance after retention. Also check that a failed run leaves the previous
completed run readable and that another viewer cannot read an inaccessible
seed or target.

The repository's suite includes these behaviors and an ignored million-event
budget fixture:

```bash
cargo nextest run -p suprnova --test recommendations
cargo nextest run -p suprnova --test recommendations --run-ignored only \
    -E 'test(million_events_complete_within_the_committed_budget)'
```

### Why Suprnova diverges

Laravel has no first-party recommender. Suprnova supplies an immutable event
stream, an explainable SQL starter, and a knowledge-graph engine behind a
replaceable trait. You reuse search documents, scopes, and vectors, keep the
graph in your own database or in Memgraph, and retain provenance from every
recommendation back to its events instead of tying interaction history to a
hosted recommendation service.

## Next

- [Search](search.md) - declare targets, scopes, facets, and semantic providers.
- [Task Scheduling](scheduling.md) - register generation and retention tasks.
- [Cache](cache.md) - configure the generation lock backend.
- [Migrations](migrations.md) - register the versioned data contract.
- [Environment Variables](env-vars.md) - configure bounds and event scores.


---

<!-- /docs/agents -->

# Agents

Suprnova lets AI agents use your application through tools. A tool is an
ordinary routed handler marked `#[tool]`. Agents reach it two ways:

- **Over MCP.** An MCP client, such as Claude Code or an agent that runs on a
  server, calls the application's MCP endpoint at `/mcp`.
- **In the browser.** An agent in the user's browser calls the tools a page
  offers through WebMCP (`document.modelContext`), with the user's session.

Either way, a tool call is a request to the handler's route. It runs the
route's middleware, bindings, form request validation, `#[authorize]`
policies and rate limits, so a tool can do nothing its route would refuse.
Nothing is a tool unless you mark it.

Every tool says which callers it accepts. A `public` tool needs no sign-in. A
`user` tool acts for a signed-in user, by browser session or by a token the
user approved for an MCP client. An `agent` tool accepts an agent account
that registered under [auth.md](https://github.com/workos/auth.md). This
chapter covers all three.

## The pieces

| Type | Role |
|---|---|
| `#[tool]` / `#[tool_input]` | Mark a handler as a tool and derive its input schema |
| `tool_scopes!` | Declare the scopes a token caller can be granted |
| `ToolCaller` | The caller a tool handler and its policies read |
| `AgentsConfig` / `Router::agents` | Serve the MCP endpoint and its discovery documents |
| `OAuthServer` / `ConnectedAgents` | Let users approve MCP clients, and list and revoke what they approved |
| `OutsideIssuer` | Accept user tokens from an identity provider you already run |
| `AgentAuth` / `AgentClaimed` | Agent accounts under auth.md, and the event a claim dispatches |
| `AgentApprovals` / `AgentClaims` / `ConsentPageHeaders` | Build your own approval and claim pages |
| `Router::share_tools` / `with_tools` / `PageTools` | Choose the server tools each page offers in the browser |
| `WebMcpConfig` | The WebMCP Origin Trial token |
| `suprnova-webmcp` | Page tools for Rust front ends compiled to WebAssembly |
| `TestClient::tool` / `McpTestClient` / `Agents::fake` | Call tools in tests as any caller |

The `agents` feature turns all of this on. It is a default feature of the
framework. A project that lists its features, as a scaffolded one does, needs
`"agents"` in that list.

## Quick start

Declare a scope, mark a handler, route it, and serve agents:

```rust
use suprnova::agents::AgentsConfig;
use suprnova::{Response, Router, ToolCaller, handler, json_response, post, routes, tool, tool_input};

suprnova::tool_scopes! {
    /// The scopes a client can be granted.
    pub mod scope {
        POSTS_WRITE = "posts:write" => "Create and edit your posts";
    }
}

/// A draft post to create.
#[tool_input]
pub struct CreatePost {
    /// The post's title.
    #[validate(length(min = 1, max = 200))]
    pub title: String,
}

#[tool(
    name = "create_post",
    description = "Create a draft post for the signed-in user.",
    callers = [user, agent],
    scopes = [scope::POSTS_WRITE],
    input = CreatePost,
)]
#[handler]
pub async fn store(caller: ToolCaller, form: CreatePost) -> Response {
    json_response!({ "title": form.title, "user": caller.user_id() })
}

mod web {
    use super::*;

    routes! {
        post!("/posts", store).name("posts.store"),
    }
}

/// `Application::routes(routes::register)` calls this once at boot.
pub fn register() -> Router {
    web::register().agents(AgentsConfig::new())
}
```

The router now serves `POST /mcp`. Point an MCP client at it, for example
Claude Code:

```bash
claude mcp add my-app --transport http https://app.example.com/mcp --scope user
```

Give the client the host `APP_URL` spells, `app.example.com` here. The
protected resource metadata names the endpoint under `APP_URL`, and a client
checks that against the URL it was given; `localhost` and `127.0.0.1` are
different hosts to it, so a mismatch stops sign-in before it starts.

`create_post` accepts users and agents, so calling it needs a token. The
client sees it in `tools/list` without one, and its first call answers 401,
which sends the client to sign in. Turn on the
[OAuth server](#users-who-approve-a-client) or
[agent accounts](#agent-accounts) to issue tokens. A `public` tool works with
no token at all.

A project made with `suprnova new` serves all of this from the first run. Its
`search_notes` and `create_note` tools, under the `notes:read` and
`notes:write` scopes, are a worked example of the sections below: see
[Agents in the Inertia kits](starter-kits.md#agents-in-the-inertia-kits) and
[Agents in the Live kit](starter-kits.md#agents-in-the-live-kit).

## Tools

### Mark a handler

`#[tool]` sits above or below `#[handler]` on a non-generic `async fn` that a
route serves. It takes these keys:

| Key | Required | Meaning |
|---|---|---|
| `name` | yes | What agents call the tool: 1 to 64 ASCII letters, digits and `_`, unique in the application |
| `description` | yes | A non-empty string literal. An agent reads it to decide when to call the tool |
| `callers` | yes | The callers it accepts: one or more of `public`, `user` and `agent` |
| `scopes` | no | The scopes a token caller needs, as constants `tool_scopes!` declared |
| `input` | no | The argument type, usually a `#[tool_input]` struct. Without it, the tool takes no input |
| `output` | no | A `#[tool_output]` struct, whose JSON Schema is the tool's output schema |
| `annotations(...)` | no | Hints for clients, described below |
| `title` | no | A display name |
| `route` | no | The route name, when the handler serves more than one route |
| `guard` | no | The auth guard a user caller is signed in to for the call. It must use the default guard's provider; another provider is refused as a configuration error because an id in one provider does not name the same person in another. |
| `budget` | no | `budget = ignore` silences this tool's compile warning; boot still logs its budget warnings |

Use short action names such as `create_post` or `search_notes`. The build
warns when a name exceeds 30 characters or a description exceeds 500
characters. Boot logs the same budgets and warns about each input field
without a description. Boot warnings never refuse a tool. Give every input
field a doc comment; `#[tool_input]` carries it into the JSON Schema.

The compile warning is a Rust `deprecated` lint. A build with
`RUSTFLAGS="-D warnings"` fails on it. Keep the tool within the budget. If a
tool keeps its long name on purpose, set `budget = ignore` to silence that
tool's compile warning. Boot still logs its budget warnings. This key works
on handlers and Live methods and leaves other deprecation warnings in their
code visible:

```rust
#[tool(
    name = "search_archived_project_records",
    description = "Search archived project records.",
    callers = [user],
    budget = ignore,
)]
#[handler]
async fn search_records() -> Response {
    json_response!([])
}
```

Names, descriptions and schemas are fixed when the application is built. An
agent reads them as instructions, so nothing at run time can change them. The
build fails on an invalid name, a missing or empty description, a missing
`callers`, a `public` tool with scopes, an `input` type none of the handler's
arguments has, or two tools with one name in a crate. When tools in two crates
share a name, the build fails at link time with a duplicate-symbol error that
names the tool. The boot check still refuses duplicate names. Boot also fails
when a tool names a scope no `tool_scopes!` declares,
when a path parameter of the tool's route is not a field of its input, or when
a tool's handler serves several routes and `route` names none of them. A
marked handler that no route serves is left out, with a warning at boot.

### Input and output schemas

`#[tool_input]` makes a struct a form request and derives its JSON Schema
(draft 2020-12) from the struct, its `serde` attributes and its `validator`
attributes. Integer fields are published as `type: integer` with their bounds
and no `format`, because clients do not know Rust's integer formats. The schema
an agent reads names the same fields, required flags and bounds the server
enforces:

```rust
use suprnova::tool_input;

/// A product review.
#[tool_input]
pub struct CreateReview {
    /// The review's text.
    #[validate(length(min = 1, max = 10000))]
    #[serde(rename = "content")]
    pub body: String,
    /// How many stars, 1 to 5.
    #[validate(range(min = 1, max = 5))]
    pub stars: u8,
    /// Whether to publish it now.
    #[serde(default)]
    pub publish: Option<bool>,
}
```

The handler takes the struct as an argument, as it takes any form request,
and the framework validates it before the handler runs. Over MCP, invalid
input comes back as a tool result with `isError: true` that names each field,
not as a protocol error, so the agent can correct the call. In the browser the
route answers its usual validation error.

A doc comment on a field becomes its description in the schema. A call fills
the route's path parameters from the input's fields of the same names.

#### Nested types

A field's type needs a JSON Schema too. A nested struct can be a
`#[tool_input]` of its own. An enum, or a struct that should not be a form
request, takes `#[tool_schema]`, which derives the schema through the
framework and leaves the type's serde derives to you:

```rust
use serde::Deserialize;
use suprnova::{tool_input, tool_schema};

/// How to order the reviews.
#[tool_schema]
#[derive(Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReviewOrder {
    /// Newest first.
    Newest,
    /// Highest rated first.
    TopRated,
}

/// The input of `list_reviews`.
#[tool_input]
pub struct ListReviews {
    /// The order to list the reviews in.
    pub order: ReviewOrder,
}
```

The enum's schema becomes part of the tool's input schema, so an agent sees the
values it may send, and a value outside them is refused as invalid input.

`output = T` publishes `T`'s schema as the tool's output schema. Mark `T`
with `#[tool_output]`, the output counterpart of `#[tool_input]`. It derives
`Serialize` and `JsonSchema` through the framework, so the application needs
no `schemars` dependency of its own. A type nested in the output takes
`#[tool_output]` or `#[tool_schema]`:

```rust
use suprnova::tool_output;

/// What `create_review` answers.
#[tool_output]
pub struct ReviewView {
    /// The review.
    pub id: u64,
    /// Its stars, 1 to 5.
    pub stars: u8,
}
```

`T` is any struct or enum, and a doc comment on a field becomes its
description. A JSON object answer reaches every client as structured data. A
list, a scalar or another non-object answer, and a non-object output schema,
are structured data for clients on revision 2026-07-28, which takes any JSON
value. Clients on 2025-06-18 and 2025-11-25 get such an answer as text, and
see the tool without its output schema, because those revisions take an
object only. Wrap a list in a struct field, such as `{ "items": [...] }`, when
those clients should get it as structured data too.

### Declare scopes

A scope is what a token lets its client do. `tool_scopes!` declares the
application's scopes, each with a description the approval page shows:

```rust
suprnova::tool_scopes! {
    /// The scopes a client can be granted.
    pub mod scope {
        POSTS_READ = "posts:read" => "Read your posts";
        POSTS_WRITE = "posts:write" => "Create and edit your posts";
        POSTS_DELETE = "posts:delete" => "Delete your posts";
    }
}
```

Each line makes a constant of type `suprnova::agents::Scope`. A tool names its
scopes with these constants, so a scope nobody declared does not compile. A
scope name is visible ASCII without spaces, quotes or backslashes, and its
description is not blank. `declared_scopes()` lists every scope the
application declared.

A token caller needs every scope the tool lists. A browser session holds
every scope, because the user is present and acting for themselves.

### Callers

`callers = [...]` lists who may call the tool:

- **`public`** accepts anyone, with no credential. A `public` tool accepts
  every other caller too, and it cannot declare scopes, since a guest would
  call it without a token.
- **`user`** accepts a signed-in user: by browser session, or by a token the
  user approved for an MCP client. A `user` tool never accepts an agent
  account, even one bound to a user.
- **`agent`** accepts an agent account that registered under auth.md.

An action for both people and agents lists `callers = [user, agent]`.

A handler reads the caller by taking a `ToolCaller` argument:

```rust
use suprnova::{Response, ToolCaller, handler, json_response, tool};

#[tool(
    name = "read_user_profile",
    description = "Read the signed-in user's profile.",
    callers = [user, agent],
)]
#[handler]
pub async fn profile(caller: ToolCaller) -> Response {
    json_response!({
        "kind": caller.kind().as_str(),
        "user": caller.user_id(),
        "browser": caller.via_browser(),
        "client": caller.client_id(),
    })
}
```

`ToolCaller` answers what the handler needs to know:

| Method | Answers |
|---|---|
| `kind()` | `CallerKind::Public`, `User` or `Agent` |
| `is_guest()` / `is_user()` / `is_agent()` | The same, one kind at a time |
| `channel()` | `CallerChannel::Browser` (the page, with the session), `Client` (the MCP endpoint) or `Direct` (the route, with a bearer, basic or custom guard) |
| `via_browser()` | Whether the call came from a page with the user's session |
| `acting_user()` / `user_id()` | The user the call acts for: the signed-in user, or the user an agent is bound to |
| `registration()` | The agent registration, for an agent caller |
| `client_id()` | The client or provider the call came through |
| `can(scope)` | Whether the caller holds a scope; a browser session holds every scope |
| `granted_scopes()` | The token's scopes, or `None` for a browser session |
| `address()` | The client address |

Outside a tool call, a `ToolCaller` argument answers 500. A handler that
serves both people and tools reads `ToolCaller::current()`, which is `None`
outside a tool call.

Policies read the caller the same way. This one lets users delete posts and
forbids agents to:

```rust
use suprnova::{Gate, ToolCaller};

Gate::define::<User, Post>("delete_post", |_user, _post| {
    !ToolCaller::current().is_some_and(|caller| caller.is_agent())
});
```

### Annotations

Annotations tell a client what a tool does, so it can ask the user before a
risky call. A bare key means `true`:

```rust
#[tool(
    name = "delete_post",
    description = "Delete one post.",
    callers = [user, agent],
    scopes = [scope::POSTS_DELETE],
    input = PostRef,
    annotations(destructive),
)]
```

| Key | MCP | WebMCP |
|---|---|---|
| `read_only` | `readOnlyHint` | `readOnlyHint` |
| `destructive` | `destructiveHint` | `consequentialHint` |
| `idempotent` | `idempotentHint` | not sent |
| `open_world` | `openWorldHint` | not sent |
| `untrusted_content` | not sent | `untrustedContentHint` |
| `debugging` | not sent | `debugging` |

`debugging` marks a tool meant for debugging and developer tooling rather than
for end users, such as one that dumps the page's state, so an agent acting for
a user can leave it aside. MCP's annotations have no such hint.

Over MCP only the hints you set are sent. A page sends WebMCP's four hints
always, `false` where you set nothing. After a tool that is not marked
`read_only`, the page refreshes its data, so mark tools that only read.
Annotations are hints. They never replace the route's policies.

### Budgets

Every tool call counts against a budget, in the cache store the rate limiter
uses. `AgentsConfig` sets three:

| Builder | Default | Counts |
|---|---|---|
| `caller_limit(CallLimit)` | 120 a minute | Calls by one user or one agent, through the browser and the MCP endpoint together |
| `address_limit(CallLimit)` | 60 a minute | `public` calls from one client address |
| `request_limit(CallLimit)` | 600 a minute | Every request to the MCP endpoint from one client address, including `tools/list` and refused tokens |

```rust
use std::time::Duration;
use suprnova::agents::{AgentsConfig, CallLimit};

let config = AgentsConfig::new()
    .caller_limit(CallLimit::per_minute(60))
    .address_limit(CallLimit::new(20, Duration::from_secs(60)));
```

A call over budget answers 429 with `Retry-After`. If the limiter's store
fails, the call answers 503 rather than run without a limit. An IPv6 client
is counted by its `/64`. The route's own throttle middleware applies as well.
A browser request counts against the budget only when it carries the
`Suprnova-Tool-Call` header, which a page's tool call sends and an ordinary
click does not.

### Tools on GET routes

A GET tool takes its input as any tool does, with a `#[tool_input]` struct. A
form request on GET or HEAD reads its query, as in Laravel, so the same
handler serves a browser link, a page's tool call and an MCP call:

```rust
/// What to look for.
#[tool_input]
pub struct NoteQuery {
    /// The text to find.
    pub q: String,
}

#[tool(
    name = "lookup_note",
    description = "Look a note up by its text.",
    callers = [public],
    input = NoteQuery,
    annotations(read_only),
)]
#[handler]
pub async fn lookup(form: NoteQuery) -> Response {
    json_response!({ "q": form.q })
}
```

A page's call of a GET tool sends every argument in the query, path arguments
included. An MCP call sends a JSON body, which the form request reads instead
of the query. Because a browser can send only strings, numbers and booleans in
a query, boot refuses a GET tool offered on a page whose input has an object
or a list field. Serve a tool with structured input on POST.

## The MCP endpoint

`Router::agents` serves the endpoint and the documents a client discovers it
by. Every setting has a default, so `AgentsConfig::new()` is a working
endpoint at `/mcp` that serves `public` tools:

```rust
use std::time::Duration;
use suprnova::agents::AgentsConfig;

let config = AgentsConfig::new()
    .allow_origin("https://admin.example.com")
    .call_timeout(Duration::from_secs(10))
    .instructions("Posts stay drafts until a person publishes them.");
```

| Builder | Default | What it sets |
|---|---|---|
| `path` | `/mcp` | The endpoint's path |
| `allow_origin` | none | Another origin a browser may call the endpoint from, besides the application's own (`APP_URL`) |
| `max_body_bytes` | 1 MiB | The largest request body; a larger one answers 413 before it is read |
| `max_result_bytes` | 8 MiB | The largest answer a tool's route may give; a larger one becomes a tool error |
| `call_timeout` | 30 seconds | How long one call may run; a longer one is stopped and answered with a tool error |
| `caller_limit`, `address_limit`, `request_limit` | see [Budgets](#budgets) | Call budgets |
| `resolver` | none | A token resolver, asked in the order added |
| `resolver_timeout` | 5 seconds | How long a resolver may take; a slower one answers 503 |
| `server_info` | `APP_NAME` and the framework's version | The name and version the endpoint reports |
| `instructions` | none | Guidance for agents, sent on discovery and `initialize` |
| `resource_name` | `APP_NAME` | The name in the protected resource metadata |
| `oauth_server` | off | The [OAuth server](#users-who-approve-a-client) |
| `agent_auth` | off | [Agent accounts](#agent-accounts) |
| `authorization_server` | none | Metadata of an authorization server you run elsewhere |

`Router::agents` registers these routes, each under the application's public
root, so an application served under a path prefix is discoverable without
owning the host root:

| Route | Serves |
|---|---|
| `POST /mcp` | The endpoint. `GET` and `DELETE` answer 405 |
| `GET /.well-known/oauth-protected-resource` and `GET /.well-known/oauth-protected-resource/mcp` | Protected resource metadata (RFC 9728) |
| `GET /.well-known/oauth-authorization-server` and `GET /.well-known/openid-configuration` | Authorization server metadata (RFC 8414), or 404 when no authorization server is configured |

It panics when one of these routes is already registered or when it is called
twice. `Router::try_agents` returns the error instead.

### Transport and protocol revisions

The endpoint uses MCP's Streamable HTTP transport, revision 2026-07-28: one
`POST` per JSON-RPC request, with `server/discover`, `tools/list`,
`tools/call` and `ping`. Clients of revisions 2025-06-18 and 2025-11-25, which
open with `initialize`, work on the same endpoint. The endpoint keeps no
session and never mints `Mcp-Session-Id`.

- An answer is JSON, or a stream of server-sent events when the client's
  `Accept` header prefers one. Closing the response cancels the call.
- The `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name` headers must agree
  with the body, or the request answers 400 with error `-32020`.
- An unsupported protocol version answers error `-32022`, listing the
  supported ones.
- A request whose `Origin` header names an origin the application does not
  allow answers 403. This stops a web page from reaching the endpoint through
  the user's browser. Clients outside a browser send no `Origin`, and those
  requests are accepted.
- `tools/list` with a token returns exactly the tools that token may call.
  Without a token it returns every tool, including the ones that need a
  token, so a client sees what signing in would let it call. Both lists keep
  a fixed order.

### Tokens and discovery

A tool that does not accept `public` callers needs a bearer token. A call
without one answers 401 with `WWW-Authenticate: Bearer resource_metadata="..."`
and the tool's scopes, so a client finds the protected resource metadata and,
through it, the authorization server. Claude Code, for example, then reports
that the server needs you to sign in, and `/mcp` signs you in. Every other
request works without a token, `public` tools included. A token that lacks a
scope answers 403 with `error="insufficient_scope"` and every scope the call
needs.

The endpoint verifies no token itself. It asks each resolver on
`AgentsConfig` in order: the OAuth server's and agent auth's when they are
on, then yours. A token no resolver accepts is refused, and the endpoint never
forwards a token to the tool's route. The route sees the caller, not the
token.

A resolver of your own implements `CallerResolver`:

```rust
use async_trait::async_trait;
use suprnova::ToolCaller;
use suprnova::agents::{CallerResolver, ResolveContext, ResolveError};

struct ServiceTokens;

#[async_trait]
impl CallerResolver for ServiceTokens {
    async fn resolve(
        &self,
        token: &str,
        ctx: &ResolveContext<'_>,
    ) -> Result<ToolCaller, ResolveError> {
        // `lookup` is the application's own token store.
        let Some(grant) = lookup(token).await else {
            return Err(ResolveError::NotMine);
        };
        if grant.resource != ctx.resource {
            return Err(ResolveError::Invalid("the token was issued for another resource"));
        }
        Ok(ToolCaller::user(grant.user).scopes(grant.scopes).client(grant.client_id))
    }
}
```

`NotMine` passes the token to the next resolver. `Invalid` answers 401
`invalid_token` and asks no other resolver. `Unavailable` answers 503: a
caller is never served as a guest because a store was down. Register it with
`AgentsConfig::new().resolver(Arc::new(ServiceTokens))`.

## Callers

A tool accepts the callers its `callers` list names. This section covers how
each kind reaches it, and how a token becomes a caller.

### Public callers

A `public` tool needs no credential. Every caller can call it, and the
endpoint lists it for a client with no token. Its budget is per client
address. Use it for what any visitor of the site may already do, such as a
search.

### Users who approve a client

The OAuth server lets a user approve an MCP client to act as them. It is a
Magnetar plugin, an OAuth 2.1 authorization server built for MCP clients.
Turn it on with `oauth_server`:

```rust
use suprnova::agents::{AgentsConfig, OAuthServer};

pub fn register() -> Router {
    web::register().agents(AgentsConfig::new().oauth_server(OAuthServer::new()))
}
```

The client follows the MCP authorization flow:

1. The client reads the protected resource metadata, then the authorization
   server metadata.
2. It identifies itself with a client ID metadata document, an HTTPS URL that
   describes it, or registers dynamically (RFC 7591).
3. It sends the user to `/oauth/authorize`. A guest signs in first, at
   `/login?return_to=...`.
4. The approval page names the client, its host and every scope it asked
   for. The user approves or denies.
5. The client exchanges the code at `/oauth/token`, with PKCE.

What the server enforces:

- The authorization code grant with PKCE `S256`, and no other code challenge
  method.
- Redirect URIs compared exactly. On a plain HTTP loopback redirect,
  `127.0.0.1`, `[::1]` or `localhost`, any port is allowed, as native
  clients need: Claude Code registers `http://localhost/callback` and signs
  in on whatever port the system gives it.
- The `iss` parameter on every authorization response (RFC 9207).
- Access tokens bound to the MCP endpoint (RFC 8707) and to the approved
  scopes. The endpoint refuses a token issued for another resource.
- Refresh tokens rotated on every use. A refresh token presented a second
  time, at once or later, revokes every token of that grant.
- Revocation at `/oauth/revoke` (RFC 7009).
- Tokens and codes stored only as SHA-256 digests.
- A password change, or signing out other devices, ends the user's client
  grants as it ends their sessions.
- A client metadata document fetched over HTTPS only, never from a private
  or loopback address, with no redirects and a bounded size and time.

The server's issuer is the application's public URL, `APP_URL`, with its path
prefix. Outside the `local` and `testing` environments, the router refuses to
build when `APP_URL` is unset. A client checks the issuer of every response,
so it must be the URL clients reach the application at. An issuer that is not
`https` is refused unless its host is a loopback address.

| Builder | Default |
|---|---|
| `route_prefix` | `/oauth` |
| `sign_in(path, parameter)` | `/login` and `return_to` |
| `approval_page(path)` | The framework's approval page at `/oauth/approve` |
| `custom_approval_page(path)` | Your own approval page; the framework mounts none |
| `connected_agents_page(path)` | The framework's connected-agents page at `/oauth/connected` |
| `custom_connected_agents_page()` | No connected-agents page; you build one with `ConnectedAgents` |
| `access_token_lifetime` | One hour |
| `refresh_token_lifetime` | 30 days |
| `registration_limit` | 20 dynamic registrations an hour per client address |
| `client_metadata_fetcher` | Magnetar's fenced HTTPS fetch |
| `connection` | The application's database connection |

The scopes are the ones `tool_scopes!` declared. The server keeps its grants
in four tables. `OAuthServer::migrate(&db)` creates them and is safe to run on
every boot; the Magnetar default engine's migrations create them too.

Every node prunes those tables every five minutes while it serves. It deletes
pending authorizations and codes that lapsed, tokens that expired, and grants
that ended more than 30 days ago: revoked grants, and grants with no token
left and no use since. A live grant or token is never pruned. A spent refresh
token stays until it expires, so a second use of it is still caught.
`agents:prune` runs the same pass once, with or without agent auth.

The token, revocation and registration endpoints are called by clients, with
no cookie, so they get no session and need no CSRF token. The approval page
needs the signed-in user, takes its answer by a CSRF-protected form and
refuses to be framed.

#### Replace the pages

The default pages are plain server-rendered HTML with no script. To render
the approval page in your own front end, name it with
`custom_approval_page(path)` and build it on `AgentApprovals`, as [Consent
pages of your own](#consent-pages-of-your-own) shows.

#### Connected agents

`ConnectedAgents` lists and revokes what the signed-in user approved. Each
method takes the request it serves and acts only on that user's grants:

```rust
use suprnova::{ConnectedAgents, HttpResponse, Request, Response, handler};

#[handler]
pub async fn index(request: Request) -> Response {
    let grants = ConnectedAgents::client_grants(&request).await?;
    let agents = ConnectedAgents::agent_accounts(&request).await?;
    Ok(HttpResponse::json(serde_json::json!({ "grants": grants, "agents": agents })))
}
```

| Method | Does |
|---|---|
| `client_grants(&request)` | The user's live client grants, newest first, as `ClientGrant`: client name and host, scopes, when it was approved and last used |
| `revoke_client_grant(&request, grant_id)` | Revokes one grant and its tokens; `false` when the user has no such grant |
| `agent_accounts(&request)` | The agent registrations bound to the user, as `AgentAccount` |
| `revoke_agent_account(&request, registration_id)` | Revokes one registration and its tokens; `false` when the user has none by that id |

A guest gets 401. A router with no OAuth server answers 500, naming
`AgentsConfig::oauth_server`.

### Users from an outside issuer

An application that already runs an identity provider can accept that
provider's user tokens instead of running the OAuth server. `OutsideIssuer`
verifies them against the provider's published keys, for issuer, audience,
expiry and scope, and finds the user with the default guard's provider. It
serves the `user` caller kind only: an outside token is never an agent
account.

The tool's guard must use the default guard's provider; a guard on another
provider is refused as a configuration error because an id in one provider
does not name the same person in another.

```rust
use std::sync::Arc;
use suprnova::agents::{AgentsConfig, OutsideIssuer};

let issuer = OutsideIssuer::new(
    "https://login.example.com",
    "https://login.example.com/.well-known/jwks.json",
)?
.user_claim("email")
.match_user_on("email");
let config = AgentsConfig::new().resolver(Arc::new(issuer));
```

The token names its user in one claim. Choose the claim with care, because it
decides who the token signs in:

- **`sub`, the default.** The issuer assigns it, so no verified flag is read.
  It links one user across clients only where the issuer gives a user the same
  `sub` for every client application. Many issuers do not: each MCP client is
  its own client application, and a pairwise `sub` differs for each.
- **An issuer-assigned id, with `id_claim`.** A claim the issuer assigns and
  the user can neither choose nor change. `id_claim` refuses a claim a user
  can set, such as `email`, `preferred_username` or `upn`.
- **Any other claim, with `user_claim`.** The token must also carry the
  issuer's verified flag set to `true`: `<claim>_verified`, such as
  `email_verified`, or the flag `verified_by(..)` names. A missing, `false` or
  non-boolean flag refuses the token. There is no way to turn this check off:
  without it, an issuer that lets users set their own address would let anyone
  sign in here as `victim@example.com`.

Microsoft Entra ID gives each client application a different `sub` for the
same user. Match on `oid`, the user's object id, and name the tenant's own
issuer, which pins tokens to that tenant:

```rust
let issuer = OutsideIssuer::new(
    "https://login.microsoftonline.com/<tenant id>/v2.0",
    "https://login.microsoftonline.com/<tenant id>/discovery/v2.0/keys",
)?
.id_claim("oid")?
.match_user_on("entra_oid");
```

Without `match_user_on`, the claim's value is the user's id. With it, the
provider looks the user up by that field through `retrieve_by_credentials`.
`EloquentUserProvider` matches only the columns its `credential_columns`
lists, `email` by default, so list the field there, such as
`.credential_columns(["email", "entra_oid"])`.

| Builder | Default |
|---|---|
| `audience` | The MCP endpoint's URL |
| `user_claim`, `id_claim`, `match_user_on`, `verified_by` | `sub`, matched as the user's id |
| `leeway` | 60 seconds for `exp`, `nbf` and `iat` |
| `key_cache(max_age, refetch_after)` | Keys kept 10 minutes; an unknown key id refetches at most every 30 seconds |
| `key_fetch` | The fenced HTTPS fetch, which refuses private addresses |

The token's `scope` (space-separated) or `scp` (a list) gives the caller's
scopes, and its `client_id` or `azp` the client. Only asymmetric signing
algorithms are accepted.

### Agent accounts

An agent account is an agent that registered with the application itself,
under [auth.md v0.6.0](https://github.com/workos/auth.md), rather than one a
user signed in. Agent auth is a second Magnetar plugin. It issues its tokens
on the OAuth server's token endpoint, so it needs the OAuth server too:

```rust
use suprnova::agents::{AgentAuth, AgentsConfig, IdentityType, OAuthServer, TrustedIssuer};

pub fn register() -> Router {
    web::register().agents(
        AgentsConfig::new()
            .oauth_server(OAuthServer::new())
            .agent_auth(
                AgentAuth::new()
                    .enable(IdentityType::IdentityAssertion)
                    .trust(TrustedIssuer::new(
                        "https://agents.acme.example",
                        "https://agents.acme.example/.well-known/jwks.json",
                        "Acme",
                    ))
                    .pre_claim_scopes([scope::POSTS_READ])
                    .post_claim_scopes([scope::POSTS_READ, scope::POSTS_WRITE]),
            ),
    )
}
```

Without `oauth_server`, the router refuses to build.

#### How an agent registers

An agent reads `/auth.md`, which the framework writes from your
configuration: the endpoints, the registration types that are on, the scopes
and the trust list. It then registers at `POST /agent/identity` in one of
three ways:

- **`anonymous`.** No identity. The agent gets an identity assertion at once
  and holds the pre-claim scopes until a user claims it. On by default.
- **`service_auth`.** The agent names a user by email and waits for that user
  to claim it. It holds nothing until then. On by default.
- **`identity_assertion` (ID-JAG).** The agent presents an identity assertion
  from a provider on your trust list, such as an AI platform the user signed
  in to. Off until you call `.enable(IdentityType::IdentityAssertion)` and
  `.trust(...)`.

The agent exchanges its identity assertion for an access token at the OAuth
server's token endpoint. Agent tokens carry no refresh token. Each type can
be turned off, and the endpoint then answers with auth.md's
`*_not_enabled` code. To refuse anonymous registration:

```rust
let agent_auth = AgentAuth::new().disable(IdentityType::Anonymous);
```

An ID-JAG is accepted only from an issuer on the trust list. Its signature is
checked against the issuer's keys, its audience, expiry and issue time within
two minutes of the server's clock, its verified email or phone, and its
`auth_time` within `max_auth_age` (one hour by default). A reused `jti` is
refused on every node. A user is matched first by an earlier delegation from
that issuer; a match only by verified email or phone asks the user to confirm
through the claim ceremony. With no match, `provision_users` decides; without
it the ID-JAG is refused. The display name the confirmation shows comes from
your trust list, never from the provider.

#### The claim

A user claims an agent to make it theirs:

1. The agent asks to be claimed at `POST /agent/identity/claim` and hands the
   user a link to the claim page, `/agent/claim`, and a six-digit code.
2. The user signs in. The page accepts only the user with the email the claim
   names, and only once that email is verified. An application verifies an
   address with `EmailVerification`, or with `Auth::email_verification()`
   when its users live in Magnetar's tables; see
   [Email Verification](auth-flows.md#email-verification).
3. The page shows the agent and every scope it will hold. The user enters the
   code, which a CSRF-protected form posts.
4. The agent's next poll gets a token bound to the user.

A code lasts ten minutes and allows five wrong entries. An unclaimed
registration expires after 24 hours. Claiming an anonymous registration
revokes its pre-claim tokens. Claim tokens, attempt tokens and codes are
stored only as SHA-256 digests.

To render the claim page in your own front end, name it with
`.custom_claim_page(path)` and build it on `AgentClaims`, as [Consent pages of
your own](#consent-pages-of-your-own) shows.

#### What an agent can call

A tool accepts agents only when its `callers` list `agent`. Within those:

- **Before a claim**, an anonymous registration holds no scope, unless
  `pre_claim_scopes` names some.
- **After a claim**, a registration holds every scope the application
  declared, unless `post_claim_scopes` names fewer.

So an agent tool that declares no scope is open to every agent, claimed or
not. To require a claim, give the tool a scope only claimed agents hold, one
`post_claim_scopes` includes and `pre_claim_scopes` leaves out. Or check in
the handler: `registration()` returns the agent's registration, and
`is_claimed()` is `true` once it is bound to a user.

```rust
#[tool(
    name = "publish_post",
    description = "Publish a draft post.",
    callers = [user, agent],
    scopes = [scope::POSTS_WRITE],
    input = PostRef,
)]
#[handler]
pub async fn publish(caller: ToolCaller, form: PostRef) -> Response {
    let unclaimed = caller
        .registration()
        .is_some_and(|registration| !registration.is_claimed());
    if unclaimed {
        return Err(HttpResponse::json(serde_json::json!({
            "message": "Ask a person to claim this agent first."
        }))
        .status(403));
    }
    json_response!({ "published": form.post })
}
```

A narrowed `post_claim_scopes` applies at once, to registrations claimed
before the change as to new ones. A registration keeps the post-claim scopes
of the day it registered, so a scope you add later reaches only
registrations made after the change.

#### The claim event

A claim dispatches `AgentClaimed`, so the application can move what the agent
created to the user who claimed it:

```rust
use async_trait::async_trait;
use suprnova::{AgentClaimed, FrameworkError, Listener, attrs};

use crate::models::Post;

pub struct AdoptAgentPosts;

#[async_trait]
impl Listener<AgentClaimed> for AdoptAgentPosts {
    async fn handle(&self, event: &AgentClaimed) -> Result<(), FrameworkError> {
        let user_id: i64 = event
            .user_id
            .parse()
            .map_err(|_| FrameworkError::internal("a user id is a number"))?;
        // Running this again for the same claim changes nothing.
        Post::query()
            .filter("agent_registration_id", event.registration_id.as_str())
            .update_all(attrs! { user_id: user_id })
            .await?;
        Ok(())
    }
}
```

Register it in `bootstrap.rs` as any listener, with
`EventFacade::listen::<AgentClaimed, _>(Arc::new(AdoptAgentPosts)).await`. See
[Events](events.md).

The event is delivered at least once. The claim's transaction writes it to
an outbox, so a committed claim always has its event, and it is dispatched
right after the commit with a stable `event_id`:

- Make every listener idempotent, keyed on `event_id`: do the work once per
  id, or make doing it again change nothing.
- Tag every row an agent creates with its registration id, which a tool
  reads from `caller.registration()`, so the move is one query.
- A listener's error never undoes the claim. The maintenance pass retries
  the event. After 12 failed attempts the event is marked failed, logged once
  at error level and kept. Fix the listener, then run
  `agents:prune --retry-failed` to put it back.
- Every node runs the maintenance pass in `serve`, every five minutes.
  `event_delivery_timeout` bounds one delivery (60 seconds by default).

`AgentClaimed` carries `event_id`, `registration_id`, `registration_type`,
`user_id`, `provider` (the trust list's display name, for an ID-JAG) and
`client_address`.

#### Revocation

Revocation works at both layers auth.md names:

- **Tokens**, at the OAuth server's `/oauth/revoke` (RFC 7009). An unknown
  token answers 200.
- **Registrations**, by a Security Event Token (RFC 8417) a trusted provider
  pushes to `POST /agent/event/notify` (RFC 8935). It is verified against the
  provider's keys, audience and `jti`, revokes the registration and every
  token derived from it, and answers 202. The route exists only while ID-JAGs
  are on.

A user revokes their own registrations on the connected-agents page or
through `ConnectedAgents::revoke_agent_account`. A password change or signing
out other devices ends the user's bound agents too.

#### Keys and operations

Agent auth signs identity assertions with a P-256 key you configure, with
`.signing_key(kid, pem)` or the `AGENT_AUTH_KEY_ID` and
`AGENT_AUTH_PRIVATE_KEY` variables. A missing or unreadable key fails the
router build in every environment, because a key made up at boot would make
nodes and restarts disagree. A deploy with no `.env` file must set both
variables in the process environment. The `agents:key` command prints a new
pair, ready for `.env`, and writes nothing:

```bash
cargo run -- agents:key
```

- **Rotate** by moving the old key to `AGENT_AUTH_PREVIOUS_KEY_ID` and
  `AGENT_AUTH_PREVIOUS_PRIVATE_KEY`, with `AGENT_AUTH_PREVIOUS_ROTATED_AT` set
  to when it stopped signing (RFC 3339), and the new key in the main pair. The
  previous key keeps verifying what it signed until those assertions expire.
  `.previous_signing_key(kid, pem, rotated_out_at)` does the same in code.
- **After a leaked key**, configure a new key first and leave the leaked one
  out of the previous key. Then run `agents:revoke-all --force`. The command
  builds the router, which needs a key, and revokes every registration and
  every token the leaked key could have reached. In production it also asks
  you to type the environment's name at a terminal. Running it again finishes
  a run that failed partway.
- **`agents:prune`** runs the maintenance pass once. It prunes the OAuth
  server's rows that can no longer be used. With agent auth on, it also
  delivers waiting claim events, expires unclaimed registrations, prunes
  spent replay records and deletes claim events delivered more than seven
  days ago, and reports how many events failed. `--retry-failed` puts failed
  events back first, and needs agent auth.
- **Keep the nodes' clocks in sync.** Expiry, the two-minute skew on issue
  times and the delivery leases compare each node's clock.
- **The audit log holds email addresses.** Agent auth writes one structured
  record per auth.md audit event: registration created, assertion issued,
  token issued, token revoked, claim requested, user code minted, claim
  confirmed, registration expired and registration revoked. The claim request
  names the user's email. Send `audit_log_channel(name)` to a channel where
  personal data may be kept. The same events reach listeners as
  `MagnetarLifecycleEvent`, with their details in `attributes`.
- **Keep CORS closed.** The claim routes answer with the signed-in user's
  email. Do not open them, or any `/agent` route, to cross-origin requests
  with credentials in your CORS policy.
- **Store emails in lowercase.** Agent auth matches a user's email without
  case. `EloquentUserProvider` compares `LOWER(email)`, so on a large user
  table add an index on `LOWER(email)`, and store new addresses in lowercase.
  A provider of your own implements `retrieve_all_by_email_ignoring_case`,
  whose default matches exactly.

Registration is rate-limited per client address and per application:
5 and 100 an hour for `anonymous` and `service_auth`, 60 and 1000 for ID-JAGs.
`registration_limit(type, per_address, per_application)` changes them. Every
route agent auth adds bounds its body to 16 KiB. Its four tables come from
`AgentAuth::migrate(&db)`, or from the Magnetar default engine's migrations.

| Builder | Default |
|---|---|
| `enable` / `disable` | `anonymous` and `service_auth` on, `identity_assertion` off |
| `trust` | No trusted provider |
| `pre_claim_scopes` | None |
| `post_claim_scopes` | Every declared scope |
| `max_auth_age` | One hour |
| `registration_window` | 24 hours |
| `user_code_lifetime` | Ten minutes |
| `max_user_code_failures` | 5 |
| `assertion_lifetime` | 30 days |
| `provision_users` | None: an unmatched ID-JAG is refused |
| `user_directory` | The default guard's provider |
| `route_prefix` / `document_path` | `/agent` and `/auth.md` |
| `claim_page` / `custom_claim_page` | The framework's page at `/agent/claim` |
| `service_name` | `APP_NAME` |
| `audit_log_channel` | The default log channel |
| `key_set_cache(floor, ceiling)` | 10 minutes and 24 hours |
| `event_delivery_timeout` | 60 seconds |

### Consent pages of your own

The OAuth server and agent auth ship plain default pages. To render the
approval page and the claim page in your own front end, turn the defaults off
and build the handlers on the consent facade: `AgentApprovals` for the
approval page and `AgentClaims` for the claim page. The framework's default
pages use the same two types, and the starter kits' pages are built on them:
see [Agents in the Inertia kits](starter-kits.md#agents-in-the-inertia-kits)
and [Agents in the Live kit](starter-kits.md#agents-in-the-live-kit). The API
kit serves the framework's default pages behind a sign-in for consent only;
see [Agents in the API kit](starter-kits.md#agents-in-the-api-kit).

```rust
use suprnova::agents::{AgentAuth, AgentsConfig, OAuthServer};

let config = AgentsConfig::new()
    .oauth_server(OAuthServer::new().custom_approval_page("/oauth/approve"))
    .agent_auth(AgentAuth::new().custom_claim_page("/agent/claim"));
```

Both types act only for the user the default guard signed in. Another user's
authorization reads as ended, and another user's claim as someone else's.
`AgentApprovals::of(&request)` and `AgentClaims::of(&request)` refuse a tool
call with 403, whether the MCP endpoint dispatched it or a page sent it with
the `Suprnova-Tool-Call` header: consent comes from the person, never from an
agent acting as them. Take the handle with `of` before you read the request's
body.

#### The approval page

The authorization endpoint sends the user to your page with the pending
authorization's id in the `authorization` query parameter. `pending` reads
it, and `decide` records the user's answer:

```rust
use serde::Deserialize;
use suprnova::agents::{AgentApprovals, ApprovalDecision, ApprovalLookup};
use suprnova::{FrameworkError, Inertia, InertiaResponse, Redirect, Request, Response};

pub async fn show_approval(request: Request) -> Response {
    let approvals = AgentApprovals::of(&request)?;
    let id = request.query_param("authorization").unwrap_or_default();
    match approvals.pending(&id).await? {
        ApprovalLookup::Pending(approval) => Ok(InertiaResponse::new("Agents/Approve")
            .with("approval", approval)
            .resolve(&request)
            .await?),
        ApprovalLookup::Ended => Err(ended().into()),
        ApprovalLookup::SignIn => Redirect::guest(&request, "/login").into(),
    }
}

#[derive(Deserialize)]
pub struct DecisionForm {
    authorization: String,
    decision: String,
}

pub async fn decide(request: Request) -> Response {
    let approvals = AgentApprovals::of(&request)?;
    let form: DecisionForm = request.form().await?;
    match approvals.decide(&form.authorization, form.decision == "approve").await? {
        ApprovalDecision::Redirect(url) => Ok(Inertia::location(url)),
        ApprovalDecision::Ended => Err(ended().into()),
        ApprovalDecision::SignIn => Redirect::to("/login").into(),
    }
}

fn ended() -> FrameworkError {
    FrameworkError::domain("This request has ended. Start again from the app.", 404)
}
```

- `PendingApproval` holds the `id` to post the decision with, the
  `client_name`, the `client_host`, the `redirect_uri` the user returns to,
  every scope with its `name` and `description`, and `expires_at`. Show the
  client's name beside its host and every scope. The client chose its name and
  redirect URI, so isolate their direction (`<bdi>`). The type carries no
  logo or home page on purpose: loading the logo would tell the client who
  looked, and a link the client chose is a phishing aid on a consent screen.
- `decide(id, approve)` spends the authorization either way, so deciding
  again is `ApprovalDecision::Ended`. `Ended` also covers a request that
  lapsed or belongs to another user.
- `ApprovalDecision::Redirect` sends the browser to the client's redirect
  URI, usually on another origin. The security headers' `form-action 'self'`
  blocks a redirect there after a native form post. On an Inertia page,
  answer with `Inertia::location(url)`: the visit is a script request, so
  the browser leaves by `window.location`, which `form-action` does not
  govern. A page that posts a native form gets a plain redirect from
  `Inertia::location` too, which the browser blocks, so answer it with a
  short page of your own that navigates there: a link to the address and
  `<meta http-equiv="refresh" content="0; url=...">`, with the address
  escaped for an attribute.
- `SignIn` means no user is signed in, or the session predates the user's
  last password change or "sign out everywhere".

#### The claim page

The verification URI an agent hands the user opens your page with the
attempt in the `claim_attempt_token` query parameter. `pending` reads the
claim, and `confirm` takes the code the user types:

```rust
use serde::Deserialize;
use suprnova::agents::{AgentClaims, ClaimConfirmation, ClaimLookup, ClaimRefusal};
use suprnova::{FrameworkError, InertiaResponse, Redirect, Request, Response};

pub async fn show_claim(request: Request) -> Response {
    let claims = AgentClaims::of(&request)?;
    let token = request.query_param("claim_attempt_token").unwrap_or_default();
    match claims.pending(&token).await? {
        ClaimLookup::Pending(claim) => Ok(InertiaResponse::new("Agents/Claim")
            .with("claim", claim)
            .with("token", token)
            .resolve(&request)
            .await?),
        ClaimLookup::Refused(ClaimRefusal::SignIn) => Redirect::guest(&request, "/login").into(),
        ClaimLookup::Refused(refusal) => Err(refused(refusal).into()),
    }
}

#[derive(Deserialize)]
pub struct CodeForm {
    claim_attempt_token: String,
    user_code: String,
}

pub async fn confirm(request: Request) -> Response {
    let claims = AgentClaims::of(&request)?;
    let form: CodeForm = request.form().await?;
    match claims.confirm(&form.claim_attempt_token, &form.user_code).await? {
        ClaimConfirmation::Claimed { .. } => Redirect::to("/dashboard").into(),
        ClaimConfirmation::WrongCode { attempts_remaining } => Err(FrameworkError::validation(
            "user_code",
            format!("That code is wrong. You can try {attempts_remaining} more times."),
        )
        .into()),
        ClaimConfirmation::Refused(ClaimRefusal::SignIn) => Redirect::to("/login").into(),
        ClaimConfirmation::Refused(refusal) => Err(refused(refusal).into()),
    }
}

fn refused(refusal: ClaimRefusal) -> FrameworkError {
    match refusal {
        ClaimRefusal::OtherAccount => FrameworkError::domain(
            "Sign in with the email address the agent named to claim it.",
            403,
        ),
        ClaimRefusal::NotFound | ClaimRefusal::Ended => {
            FrameworkError::domain("This claim has ended. Ask the agent to start again.", 404)
        }
        ClaimRefusal::SignIn | ClaimRefusal::Invalid => {
            FrameworkError::domain("This claim cannot be read.", 400)
        }
    }
}
```

- `PendingClaim` holds the `registration_type`, the `provider` (the trust
  list's display name, never one the provider sent), the `signed_in_as`
  address, the `email` the agent named, every scope the agent will hold,
  `expires_in_seconds`, `attempts_remaining`, and two warnings:
  `first_time_account` when no agent has acted for this account before, and
  `first_time_provider` when none from this provider has. Show both
  warnings, and isolate every text but the scopes' words, since the user, the
  agent or the provider chose it.
- `confirm` counts a wrong code against the attempt and answers
  `ClaimConfirmation::WrongCode { attempts_remaining }`. When none remain, the
  attempt ends and the agent starts a new one.
- `ClaimConfirmation::Claimed { registration_id }` means the registration is
  the user's. The agent's next poll gets its tokens, and `AgentClaimed` is
  dispatched.
- `ClaimRefusal::OtherAccount` means the claim names another address, or the
  signed-in user's address before it was verified. Tell the user to sign in
  with the address the agent named, and show nothing of the claim.
  `NotFound` means no such attempt or one already confirmed, `Ended` an
  expired code or too many wrong ones, and `Invalid` a request the engine
  cannot read.

#### Route the pages

Run every consent route behind `ConsentPageHeaders`, and the routes that
record a decision behind the CSRF middleware, which the global CSRF
middleware already provides:

```rust
use suprnova::agents::ConsentPageHeaders;
use suprnova::{get, group, post, routes};

use crate::controllers::consent;

routes! {
    group!("/", {
        get!("/oauth/approve", consent::show_approval),
        post!("/oauth/approve", consent::decide),
        get!("/agent/claim", consent::show_claim),
        post!("/agent/claim", consent::confirm),
    }).middleware(ConsentPageHeaders),
}
```

`ConsentPageHeaders` holds for every answer of those routes, errors
included: a CSRF refusal, an error page rendered after the middleware chain
and a panic's answer.

- **No framing.** The policy's `frame-ancestors` becomes `'none'` and
  `X-Frame-Options` becomes `DENY`, so no page can frame "Allow" under a
  click. The rest of the policy, nonce sources included, stays as
  `SecurityHeaders` and your overrides made it, so the page's scripts run.
  Under report-only, relaxed or off, an enforced `frame-ancestors 'none'` is
  sent all the same.
- **No caching, no referrer.** `Cache-Control: no-store` and
  `Referrer-Policy: no-referrer` keep the authorization id and the attempt
  token in the page's address out of caches and other sites' logs.

It runs inside `SecurityHeaders` and route overrides, before every other
middleware. A header your handler sets gives way to these. Without
`SecurityHeaders` installed, it sets all four headers on the answers that
pass through it, but an answer the server makes after the chain, such as a
panic's, carries only what the server set.

#### Pages that fetch JSON

A front end that fetches its data can use the plugins' JSON routes instead of
handlers of its own. They act for the signed-in user only, and the routes
that record a decision need the CSRF token.

- **Approval.** Read the pending authorization from
  `GET /oauth/authorizations/{id}`, and post the decision to
  `POST /oauth/authorizations/{id}` as the form field `decision` (`approve` or
  `deny`).
- **Claim.** Read the pending claim from
  `GET /agent/identity/claim/attempt?claim_attempt_token=...`, and post
  `claim_attempt_token` and `user_code` to
  `POST /agent/identity/claim/complete`.

The page that hosts them still runs `ConsentPageHeaders`, sends a guest to
sign in and back to itself, and shows the client, its host and every scope,
or the provider and every scope.

## Tools in the browser

WebMCP lets an agent in the browser call tools a page registers with
`document.modelContext`. The call runs in the user's tab, with the user's
session, and the page shows what the agent did. Suprnova registers three
kinds of browser tool:

- **Server tools**: `#[tool]` handlers the server lists for a page. A call
  is a same-origin request to the tool's route with the session cookie, the
  CSRF token and the `Suprnova-Tool-Call` header.
- **Live tools**: actions of a mounted Live component.
- **Front-end tools**: tools a React, Vue, Svelte or WebAssembly component
  defines and registers while it is mounted.

A browser registers a tool only on a page that is allowed to use WebMCP. See
[Security Headers](security-headers.md#webmcp-and-permissions-policy) for the
`tools` permission and the Origin Trial.

### Page tools

The server decides which server tools each page offers. Name them on the
router, a route, a group or a response:

```rust
use suprnova::{InertiaResponse, PageTools, Request, Response, Router};

/// `Application::routes(routes::register)` calls this once at boot.
pub fn register() -> Router {
    web::register()
        // Every page offers the search tool.
        .share_tools(["search_posts"])
}

// In the route list, a route adds its own:
// get!("/posts", posts::index).with_tools(["create_post"]).name("posts.index"),

pub async fn show(request: Request) -> Response {
    // A handler adds tools for this request only.
    PageTools::add(["update_post"]).await?;
    Ok(InertiaResponse::new("Posts/Show")
        .with_tools(["delete_post"])
        .resolve(&request)
        .await?)
}
```

| Where | How |
|---|---|
| Every page | `Router::share_tools([...])` |
| A route, a `get!` or `post!` route, or a `group!` | `.with_tools([...])` |
| An Inertia response | `InertiaResponse::with_tools([...])` |
| A Live document | `document.with_tools([...]).await`, before `bootstrap` |
| The current request, from any handler | `PageTools::add([...]).await` |

Each name must be a routed `#[tool]` that accepts `public` or `user` callers.
A name the router, a route or a group offers that is not one stops the server
at boot; one a handler or a response adds fails that page's render. Either
way the error names the tool. An agent-only tool is never offered in the
browser, because a browser viewer is never an agent account, and a Live tool
is offered by its own island. A page offers at most 64 tools.

Each page lists only the tools its viewer may call: a guest sees `public`
tools, and a user signed in by session sees `user` and `public` tools. An
Inertia page carries the list in its page object's `agentTools` field, on
every visit and partial reload. A Live page carries it in a
`<script type="application/json" id="suprnova-agent-tools">` element its
document's bootstrap writes. A plain view puts `PageTools::element(&request)`
in its `<head>`.

The server tools on a page leave when the user navigates away. After a call
of a tool that is not marked `read_only`, the page refreshes its data so the
screen matches what the agent did: an Inertia page reloads its props, and a
Live page renders every island again.

A request that carries the `Suprnova-Tool-Call` header names a tool. On a
route that serves no tool, or a different one, it answers 400. Only a request
with the header counts against the tool budget; the caller checks apply to
every request to a tool's route.

#### Page tools and RenderCache

A page whose tools all accept `public` callers is the same for every viewer.
The server reads no viewer to build its list, so a cached copy stays shared.
A page with a `user` tool reads who the viewer is. On a route whose cache
policy varies by principal, RenderCache stores that page once per signed-in
user, and guests share one copy. On a route with no principal variance it
declines to store the page. So keep busy public pages to public-only tools.
See [RenderCache](render-cache.md).

### Live actions as tools

Mark a Live action `#[tool]` to offer it to agents. The action's arguments
give the input schema, and fields marked `#[agent_visible]` are what the
agent reads back:

```rust
use suprnova::live::{LiveComponent, live};

#[derive(LiveComponent)]
#[live(name = "app.counter", view = "live/counter.html")]
pub struct Counter {
    #[agent_visible]
    count: u64,
    #[agent_visible]
    label: String,
}

#[live]
impl Counter {
    #[mount]
    pub fn mount(start: u64, label: String) -> Self {
        Self { count: start, label }
    }

    #[tool(
        name = "add_to_counter",
        description = "Add to the counter.",
        callers = [user, agent],
    )]
    #[action]
    pub fn add(&mut self, amount: u64) {
        self.count += amount;
    }

    #[tool(
        name = "peek_counter",
        description = "Read the counter.",
        callers = [public],
        annotations(read_only),
    )]
    #[action]
    pub fn peek(&mut self) {}
}
```

A Live tool takes `name`, `description`, `title`, `callers`, `scopes`,
`annotations`, `guard`, `arguments(...)` and `headless`. Its arguments come from the action's
parameters, so it takes no `input`. Each argument must have a JSON Schema an
agent can read: `String`, `bool`, `i64`, `u64`, `f64`, `Date`,
`OffsetDateTime` or `Uuid`, or an `Option`, `Vec` or `BTreeMap` of them.

Describe action parameters with `arguments(...)` on the tool marking:

```rust,ignore
#[tool(
    name = "add_to_tally",
    description = "Add to the current tally.",
    callers = [user],
    arguments(amount = "How much to add to the tally."),
    headless,
)]
#[action]
pub fn add(&mut self, amount: u64) {
    self.count += amount;
}
```

An argument without a description raises a compiler warning and a boot
warning. A description of an argument the action does not take is a build
error. For an agent-supplied mount property, put its description on the
parameter as `#[doc = "The initial count."]`, for example
`fn mount(#[doc = "The initial count."] start: u64) -> Self`.

In the browser, the Live runtime registers a mounted component's tool actions
with `document.modelContext` and removes them when the component leaves the
page or the user navigates away. A call runs the ordinary action path: the
signed snapshot, the CSRF check, the action's authorization and its
transaction. An action marked `#[action(authorize = "current")]` asks the
Gate for `live:{component}.{action}`, as a click does. The result carries the
agent-visible fields and no other state.

One component may declare at most 64 browser tools. Metadata validation
rejects more before the page is served. Headless-only tools do not count
toward this limit; the component's overall limit remains 256 actions.

The browser names a Live tool after its island: `peek_counter-main` for the
island `live:key="main"`. The key must be one literal of 1 to 63 ASCII
letters, digits, `_` and `-`, outside any loop, so data never reaches a name
an agent reads as an instruction. `suprnova live:check` refuses any other key
on a component with browser tools, and a key used twice on one page. A Live
tool name, the `-` separator and the key must fit in 64 characters in all.
The checker names the island, tool and combined length when they do not.
Tool names contain no hyphens, so the first hyphen separates the name from
its key, including a key such as `left-pane`.

Marking an action `#[tool]` narrows who can click it to the callers you list.
The caller check runs on every request to the action, with or without the
tool-call header, so `callers = [user, agent]` refuses a guest's click with
401. An action for both people and agents lists `callers = [user, agent]`,
and adds `public` for guests. An action no person should click lists only
`agent` and is never registered in the browser.

### The Inertia kits

The React, Vue and Svelte kits type-check their WebMCP registration through
`webmcp-types` 0.1.10. The package defines the model context, tool definition,
execution options and annotations. It leaves the result payload open, so
Suprnova keeps its `ToolResult` type for structured content and errors.

The React, Vue and Svelte kits ship helpers in `src/lib/agents`, and their
notes page uses them; see
[Agents in the Inertia kits](starter-kits.md#agents-in-the-inertia-kits).
Each kit's entry calls `installPageTools(router)` before `createInertiaApp`. It
registers the server tools in the page object's `agentTools`, swaps them on
every visit, and reloads the page's props after a write tool.

A component registers a tool for as long as it is mounted with
`usePageTool`:

```tsx
import { usePageTool } from '../lib/agents'

export default function Cart({ items }: { items: string[] }) {
  usePageTool({
    name: 'list_cart_items',
    description: 'List the items in the visible cart.',
    inputSchema: { type: 'object', properties: {} },
    readOnly: true,
    execute: () => ({ items }),
  })
  return <ul>{items.map((item) => <li key={item}>{item}</li>)}</ul>
}
```

`readOnly`, `untrustedContent`, `consequential` and `debugging` set the
tool's four WebMCP hints, as the `#[tool]` annotations above do. `useFormTool`
takes `destructive` and `debugging`.

`useFormTool` makes a kit form a tool. The input schema comes from the
form's server request type: `suprnova generate-types` writes every form
request's schema to `frontend/src/types/tool-schemas.ts`, keyed by the
struct's name, and `suprnova serve` keeps it current. A call fills the form,
which the user sees, and submits it through Inertia. Validation errors come
back as a tool result with `isError: true` that names each field:

```tsx
import { useForm } from '@inertiajs/react'
import { useFormTool } from '../lib/agents'
import { toolSchemas } from '../types/tool-schemas'

export default function NewNote() {
  const note = useForm({ title: '', body: '' })
  useFormTool(note, {
    name: 'create_note',
    description: 'Write a note.',
    schema: toolSchemas.StoreNoteRequest,
    action: { method: 'post', url: '/notes' },
  })
  // ...the form itself
}
```

A form for a destructive action, marked `destructive: true` or sent with
`DELETE`, is filled and left for the user to submit. A form tool sends no
tool-call header: it drives the page's own form, so the route's throttle and
checks apply rather than the tool budget. Its submission carries
`Suprnova-Form-Tool: 1` instead (`suprnova::agents::FORM_TOOL_HEADER`), and
the consent facade refuses a request that carries it, so a form tool on an
approval or claim page can never approve or claim for the user. Vue and
Svelte take the same options; their `useFormTool` takes the `useForm` object.

`generate-types` refuses, by name, a request type it cannot describe exactly
as the server does, rather than write an approximate schema.

### WebAssembly front ends

The `suprnova-webmcp` crate brings the same tools to a Rust front end
compiled to WebAssembly. `PageTool` registers a typed tool whose input
schema is derived as the server derives a `#[tool]`'s, and `ServerTools`
registers and calls the server tools the page lists:

```rust
use suprnova_webmcp::{PageTool, ServerTools, ToolHandle, ToolResult, WebMcpError, tool_input};

/// An item to add to the visible todo list.
#[tool_input]
struct AddTodo {
    /// What to do.
    #[validate(length(min = 1, max = 200))]
    title: String,
}

/// Register the page's tools. They stay registered while the caller keeps
/// the handles this returns.
fn boot() -> Result<(ToolHandle, Vec<ToolHandle>), WebMcpError> {
    let add = PageTool::<AddTodo>::new("add_todo", "Add an item to the visible todo list.")
        .title("Add todo")
        .register(|input: AddTodo| async move { Ok(ToolResult::json(&input.title)?) })?;
    let server = ServerTools::from_document()?;
    let tools = server.register_all(|| async { /* refetch the app's data */ })?;
    Ok((add, tools))
}
```

A registration lasts as long as its `ToolHandle`; dropping the handle removes
the tool. `ServerTools::from_document` reads the
`suprnova-agent-tools` element, so the page that boots the front end puts
`PageTools::element(&request)` in its `<head>`. A server tool call carries
the session, the CSRF token and the tool-call header, and its validation
errors name each field as the server's do. The crate's `#[tool_input]`
brings its own copies of `serde`, `schemars` and `validator`, so the front
end needs none of them. An enum or another type nested in the input takes
`#[suprnova_webmcp::tool_schema]`, as on the server. `PageTool` sets the
WebMCP hints with `read_only`, `untrusted_content`, `consequential` and
`debugging`.

Every function compiles on every target, so a crate shared with the server
builds natively too. Outside the browser, registering or calling a tool
returns `Unsupported::Target`. In a browser without WebMCP, registering
returns `Unsupported::NoModelContext`, while reading and calling server tools
still work.

## Headless Live tools

A Live tool action marked `headless` can also be called over the MCP
endpoint, with no browser. An action without the marking is never offered
there.

```rust
// src/live/tally.rs
use suprnova::live::{LiveComponent, live};
use suprnova::{FrameworkError, ToolCaller};

#[derive(LiveComponent)]
#[live(name = "app.tally", view = "live/tally.html")]
pub struct Tally {
    #[agent_visible]
    count: u64,
    #[locked]
    owner: String,
}

#[live]
impl Tally {
    #[mount]
    pub fn mount(start: u64, #[resolve(crate::live::tally::owner_of)] owner: String) -> Self {
        Self { count: start, owner }
    }

    #[tool(
        name = "add_to_tally",
        description = "Add to the tally.",
        callers = [user, agent],
        headless,
    )]
    #[action]
    pub fn add(&mut self, amount: u64) {
        self.count += amount;
    }
}

/// The owner is the caller, never a value the agent sends.
pub async fn owner_of(caller: &ToolCaller) -> Result<String, FrameworkError> {
    caller
        .user_id()
        .ok_or_else(|| FrameworkError::internal("a headless tally needs a user"))
}
```

The tool's input has three parts:

- **`mount`**: the component's mount properties, to start a new component.
  Each is declared by its `#[mount]` parameter, appears in the schema and is
  validated like an action argument. An `Option` parameter may be left out.
- **`handle`**: the handle an earlier call returned, to act on the same
  component. Send `mount` or `handle`, never both.
- **`arguments`**: the action's arguments.

Mount properties an agent sends are untrusted input. Before anything loads,
the framework asks the Gate ability `live:{component}.mount` with the caller
and the values, and refuses the mount when no policy defines it:

```rust
use suprnova::{Gate, LiveMountRequest, ToolCaller};

Gate::define::<ToolCaller, LiveMountRequest>("live:app.tally.mount", |caller, mount| {
    caller.is_user()
        && mount
            .property("start")
            .and_then(|value| value.as_u64())
            .is_some_and(|start| start < 100)
});
```

Each property reaches the policy in its codec's one JSON form, whatever form
the agent wrote. Write the policy so a property it cannot read refuses the
mount. A property filled by `#[resolve(...)]` is left out of the schema: the
agent cannot set it, and the resolver fills it from the caller after the
policy allows the mount.

The action then runs through the same authorization and transaction as in
the browser. The call returns the outcome, the agent-visible fields, a new
`handle` and its `expiresAt`. The handle is Live's signed snapshot, sealed so
the agent sees none of the state it carries, and bound to the caller: a
handle issued to one caller is refused for any other. It expires as a
browser snapshot does, after `LIVE_LEDGER_INSTANCE_LIFETIME_MS`. A stale
handle answers 409, and the agent calls again with the latest one or without
one.

Headless outcomes are `accepted`, `no_render`, `redirect`, and `invalid`.
If the sealed successor would make even the smallest follow-up request exceed
the endpoint's `max_body_bytes`, the outcome is `too_large` with `isError: true`.
The result keeps the agent-visible `fields` and any `validation` issues, but
returns no `handle`. Its message explains that the component's state no longer
fits one request and the mount must be started again.

A headless tool's component cannot have `#[session]` fields, and an action
that finalizes an upload cannot be headless.

## Testing

`TestClient` calls tools through both surfaces, as any caller, without
running the OAuth or auth.md ceremonies. The test path runs every check the
real path does: middleware, validation, policies, scopes, budgets and the
`Origin` check.

`TestClient::tool` calls a tool from the browser, as a page does: the session,
the CSRF token and the tool-call header. Sign a user in with `acting_as`:

```rust
use std::sync::Arc;
use serde_json::json;
use suprnova::cache::{CacheStore, InMemoryCache};
use suprnova::container::testing::TestContainer;
use suprnova::testing::TestClient;
use suprnova::MiddlewareRegistry;

#[tokio::test]
async fn a_signed_in_user_creates_a_post_from_the_page() {
    // Tool budgets count in the cache store.
    let _container = TestContainer::fake();
    TestContainer::bind::<dyn CacheStore>(Arc::new(InMemoryCache::new()));
    let client = TestClient::new(routes::register(), MiddlewareRegistry::new());
    // `user` is a user the test created.
    let call = client
        .acting_as(&user)
        .tool("create_post", json!({ "title": "From a page" }))
        .send()
        .await;
    call.assert_ok();
}
```

`TestClient::mcp` calls the MCP endpoint. `as_caller` chooses who calls, with
the scopes the token would carry:

```rust
use suprnova::ToolCaller;

#[tokio::test]
async fn an_agent_needs_the_write_scope() {
    let _container = TestContainer::fake();
    TestContainer::bind::<dyn CacheStore>(Arc::new(InMemoryCache::new()));
    let client = TestClient::new(routes::register(), MiddlewareRegistry::new());

    let refused = client
        .mcp()
        .as_caller(ToolCaller::agent("reg-1").claimed(true))
        .call("create_post", json!({ "title": "No scope" }))
        .await;
    assert_eq!(refused.status(), 403);

    let created = client
        .mcp()
        .as_caller(ToolCaller::agent("reg-1").claimed(true).scopes([scope::POSTS_WRITE]))
        .call("create_post", json!({ "title": "Scoped" }))
        .await;
    assert!(!created.is_error());
}
```

| Helper | Does |
|---|---|
| `client.tool(name, arguments)` | A browser tool call, as a guest or the `acting_as` user |
| `client.live_tool(name, page, arguments)` | A Live tool call on the island that offers it in `page`, the HTML of a page the client rendered |
| `client.mcp()` | An MCP client, a guest speaking revision 2026-07-28 |
| `.as_caller(ToolCaller)` | Call as a user or an agent, with chosen scopes, claimed or not |
| `.protocol_version(...)`, `.header(...)`, `.with_token(...)` | Speak an older revision, send a header, or present a real token |
| `.discover()`, `.initialize()`, `.list()`, `.call(name, arguments)` | The MCP methods, answered as `McpResponse` and `McpToolResult` |
| `response.page_tools()`, `page_tool(name)` | The tools a rendered page offers |
| `Agents::fake().token_for(caller)` | A token that stands for a caller, for a raw request |

`ToolCaller::user(user)`, `ToolCaller::agent(id)` and `ToolCaller::guest()`
build callers; `.scopes([...])`, `.claimed(bool)`, `.client(id)` and
`.bound_to(user)` shape them. Over MCP, only the token's verification is
faked. [Mocking](mocking.md) covers `TestContainer`.

### Try it in a browser

For local work, open `chrome://flags/#enable-webmcp-testing` in Chrome,
set it to **Enabled**, and relaunch. See [Chrome's WebMCP guide](https://developer.chrome.com/docs/ai/webmcp#local-webmcp).
WebMCP needs a [secure context](https://webmachinelearning.github.io/webmcp/#idl-index):
use HTTPS or [localhost](https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy).

In DevTools, open **Application > WebMCP**. The
[WebMCP pane](https://developer.chrome.com/docs/devtools/application/webmcp)
lists available tools and their calls, including inputs, outputs and errors.
Select a tool, enter its arguments and click **Run tool** to test it directly.

The [example agentic extension](https://github.com/GoogleChromeLabs/webmcp-extension)
needs Chrome 155 or later; its manifest sets the minimum to 155.0.8052.0.
It always asks before calling a tool marked `consequentialHint: true`.
By default, it also asks before tools without `readOnlyHint: true`. Users can
turn those alerts off or allow a site's actions for the chat. Those choices
never bypass a consequential tool's prompt.
The extension cuts results at 8,000 characters and appends a warning. Keep
answers small enough for the client that reads them. Suprnova's browser tools
carry JSON in `structuredContent` only, without repeating it as text.

The [Model Context Tool Inspector](https://github.com/beaufortfrancois/model-context-tool-inspector),
listed in [webmcp-tools](https://github.com/GoogleChromeLabs/webmcp-tools),
inspects exposed tools and their input schemas and helps debug connections.

For an agent using [chrome-devtools-mcp](https://developer.chrome.com/docs/devtools/application/webmcp#command-line-flags),
add `--categoryExperimentalWebmcp` to its server arguments. This enables
`list_webmcp_tools` and `execute_webmcp_tool`, which are off by default.

### Why Suprnova diverges

Laravel serves MCP through the `laravel/mcp` package: a tool is a class
registered on a server class, with its own schema, validation and
authorization, and Passport or Sanctum authenticates clients. Suprnova marks
the routed handler itself, so a tool call runs the route's middleware,
validation and policies, and a tool cannot drift from the page it backs. The
schema is derived from the input type at build time, never written beside it.
Suprnova offers tools only, not MCP prompts or resources.

Laravel has no first-party WebMCP or auth.md support. Suprnova's browser
tools let an agent work in the user's own tab, and its agent accounts let an
agent register before any person signs it in. The OAuth server is built for
MCP clients only: the authorization code grant with PKCE and client metadata
documents, without Passport's password, client credentials and implicit
grants or its personal access tokens.

## Next

- [Authorization](authorization.md) - policies a tool's route already runs
- [Validation](validation.md) - the rules `#[tool_input]` publishes
- [Live](live.md) - components, actions and snapshots
- [Starter Kits](starter-kits.md#agents-in-the-inertia-kits) - what each kit
  wires for agents, its consent pages and its notes tools
- [Security Headers](security-headers.md) - the `tools` permission and the Origin Trial
- [Environment Variables](env-vars.md#agents) - the signing key and trial token


# Security

---

<!-- /docs/authentication -->

# Authentication

Suprnova ships a Laravel-shaped authentication system: a static `Auth`
facade, named guards resolved through an `AuthManager`, pluggable user
providers, an `Authenticatable` trait on your User model, and middleware
to gate routes. A scaffolded project boots with a session guard (`web`)
and a token guard (`api`) already wired against your typed `User`, so
login, registration, and protected routes work the day you run
`suprnova new`.

## The pieces

| Type | Role |
|---|---|
| `Auth` | Framework facade for guards plus Magnetar-backed password, magic-link, passkey, and OAuth operations |
| `MagnetarConfig` / `init_magnetar` | Compose and atomically install the default password, session, lockout, passkey, and factor engines |
| `Authenticatable` | Trait your application model implements; surfaces `get_auth_identifier() -> String` and the password hash |
| `UserProvider` | Trait that fetches application users; `EloquentUserProvider<M>` and `DatabaseUserProvider` ship built in |
| `AuthManager` | Holds the `AuthConfig` and registered providers; resolves named guards on demand |
| `SessionGuard` / `TokenGuard` | Framework stateful and stateless guard contracts |
| `BearerTokenMiddleware` | Resolves Magnetar bearer sessions into framework request authentication state |
| `AuthMiddleware` / `GuestMiddleware` / `BasicAuthMiddleware` | Route guards |
| `Credentials` | JSON-shaped credential map, typically `{ "email", "password" }` |

Framework guard/provider code lives in `framework/src/auth/`. The Magnetar host
adapters and facades live in `framework/src/magnetar_integration/`; the engine
crate lives in `crates/suprnova-magnetar/`. An application never depends on
that crate: every Magnetar type a public signature of the framework names is
re-exported under `suprnova::magnetar_integration`. Higher-level email
verification, password reset, lockout, and TOTP flows live in
`framework/src/auth_flows/` and are covered by [Auth flows](auth-flows.md).
OAuth, Apple, and magic-link login are covered by
[OAuth and passwordless login](oauth.md).

## Identifier model

The authenticated user's id flows through Suprnova as a `String`
end-to-end - session storage, [`UserProvider::retrieve_by_id`], the
remember-me table, every auth event. The canonical surface is
`Authenticatable::get_auth_identifier() -> String` (Laravel's
`getAuthIdentifier`). Numeric primary keys stringify trivially; UUIDs,
ULIDs, and opaque OAuth provider ids flow through unchanged.

```rust
use std::any::Any;
use suprnova::Authenticatable;

impl Authenticatable for User {
    fn get_auth_identifier(&self) -> String {
        self.id.to_string()
    }

    fn get_auth_password(&self) -> Option<&str> {
        Some(&self.password)
    }

    fn as_any(&self) -> &dyn Any {
        self
    }
}
```

`get_auth_password` is what the built-in providers verify a plaintext
password against via `hashing::verify_async`. Return `None` for users
that authenticate by other means (OAuth, passkey, magic link). The
`auth_identifier_name() -> &'static str` method (default `"id"`) names
the column the id lives in. The convenience `auth_identifier() -> i64`
default-parses the string id and falls back to `0` for non-numeric ids -
Suprnova itself never calls it; override only for integer-keyed models
that want to skip the parse.

### Why Suprnova diverges

Laravel's `getAuthIdentifier()` returns `mixed`. PHP doesn't care
whether the id is an int, a UUID string, or a stringly-typed primary
key from a legacy table. Rust needs a single concrete type the session,
the provider, and the events all agree on. `String` is the only choice
that accommodates every id shape without forcing the framework to know
which one your app uses. The `auth_identifier()` integer convenience
exists for the common case where your column is a `BIGINT`, but the
framework never depends on it - switch your `User` to a ULID tomorrow
and nothing in the auth stack notices.

## Wiring auth at boot

The Rust analogue of `config/auth.php` is an `AuthConfig` registered as
an `AuthManager` singleton on the container, plus a `UserProvider`
registered under a name. `bootstrap.rs` typically does both in two
lines:

```rust
use std::sync::Arc;
use suprnova::{App, Auth, AuthConfig, AuthManager, EloquentUserProvider};

use crate::models::user::User;

pub async fn bootstrap() -> Result<(), suprnova::FrameworkError> {
    // ... DB::init, SessionMiddleware install, etc.

    App::singleton(AuthManager::new(AuthConfig::from_env()));
    Auth::register_provider("users", Arc::new(EloquentUserProvider::<User>::new()))
        .expect("register users provider");

    Ok(())
}
```

`AuthConfig::from_env()` reads the default guard from `AUTH_GUARD`
(default `"web"`) and ships with two named guards out of the box: a
`web` session guard and an `api` token guard, both backed by the
`"users"` provider. Apps that need more guards (separate `admins`
provider, distinct stateful and stateless guards) build the config
explicitly:

```rust
use suprnova::{AuthConfig, GuardConfig};

let config = AuthConfig::new("web")
    .guard("web", GuardConfig::session("users"))
    .guard("admin", GuardConfig::session("admins"))
    .guard("api", GuardConfig::token("users"));
```

## Initialize the Magnetar engine

The API starter initializes Magnetar after the database and `APP_KEY` are
ready:

```rust
use suprnova::{DB, MagnetarConfig, PasskeyConfig, init_magnetar};

pub async fn register_auth() -> Result<(), suprnova::FrameworkError> {
    let database = DB::connection()?;
    let magnetar = MagnetarConfig::from_sea_orm(database.inner().clone())
        .passkey_config(PasskeyConfig {
            rp_id: "app.example.com".to_string(),
            rp_origin: "https://app.example.com".to_string(),
        });

    init_magnetar(magnetar).await
}
```

The default engine shares the application SeaORM connection and creates its
schema unless `.apply_migrations(false)` is selected. It installs the
password/session and passkey adapters atomically. Reinitialization returns an
error rather than replacing one adapter while another request still uses the
old store.

`MagnetarConfig` also accepts session, lockout, and two-factor policy values:

```rust,ignore
let magnetar = MagnetarConfig::from_sea_orm(database)
    .session_config(session_policy)
    .lockout_config(lockout_policy)
    .two_factor_config(factor_policy)
    .passkey_config(passkey_policy);
```

The default host binding uses the canonical `app_users` table with `i64`
application IDs. Magnetar's public `UserId` remains opaque at the facade
boundary; the default binding parses the stored identifier only where it
crosses into the application table.

### Magnetar-backed facade methods

The installed engine powers these framework-owned methods:

- `Auth::password().register(...)`.
- `Auth::password().authenticate(...)`.
- `Auth::magic_link().send(...)` and `.consume(...)`.
- `Auth::passkey().begin_registration(...)` and `.finish_registration(...)`.
- `Auth::passkey().begin_authentication(...)` and
  `.finish_authentication(...)`.
- `Auth::oauth(provider)` when an OAuth delegate is installed.
- Remember-me issuance, rotation, and revocation.
- Bearer-session lookup through `BearerTokenMiddleware`.
- `list_sessions`, `revoke_session`, and `revoke_all_sessions` in
  `suprnova::magnetar_integration`.

Successful sign-in rotates the framework session ID and CSRF token, stores the
application user ID, and records an opaque Magnetar web binding. The framework
continues to own HTTP middleware, cookies, mail, events, and its guard/provider
contracts.

#### Framework logins under the engine

The framework's own login paths check credentials outside Magnetar:
`Auth::login_id`, `Auth::attempt`, `Auth::login`, `Auth::login_using_id`, and
`TwoFactor::complete_challenge`. With the engine installed, every web login
needs a Magnetar session, so revocation and auth epochs reach it. For these
paths, `SessionMiddleware` issues the user's Magnetar session at the end of the
request and records its binding before it stores the session. This issuance is
host-trusted, like Laravel's `Auth::loginUsingId`: the engine takes the
framework's word for who signed in, and no Magnetar plugin can reach it.

- **Same user ids.** The default guard's `UserProvider` must resolve
  Magnetar's user ids, for example a provider over Magnetar's `app_users`
  table. The framework cannot check this at boot, because a provider is opaque
  until it resolves a user. A login whose id Magnetar does not know fails with
  a `500` that names the cause.
- **Second factors.** An account with a confirmed Magnetar second factor is
  refused with `409`, because the framework login did not prove it. The
  session guards, including the once-only paths (`Auth::once`,
  `Auth::once_using_id` and `BasicAuthMiddleware::once()`),
  `Auth::login_remember` and `TwoFactor` ask before they log in or read a
  code, so a refusal fires no `Login` event, consumes no code,
  and issues no remember-me credential. `Auth::login_id` cannot await the engine, so its refusal arrives
  at the end of the request, which then stores nothing and retires a
  remember-me credential issued during it.
- **Framework TOTP.** The reverse holds too. Magnetar's own sign-ins -
  `Auth::password()`, `Auth::magic_link()`, `Auth::passkey()` and
  `Auth::oauth()` - never read the framework's `TwoFactor` table, so each of
  them refuses an account with confirmed framework TOTP with `409` before a
  session or challenge exists. That account signs in through the
  application's login and `TwoFactor::complete_challenge`. A remembered
  sign-in still passes, because a remember-me credential is issued only
  after a full sign-in. Enrolling either factor returns `409` while the
  account has the other, confirmed or pending, so an account holds one. An
  account that has both anyway, from before that check or from an import, is
  refused by every path until an administrator disables one of them; see
  [One second factor per account](auth-flows.md#one-second-factor-per-account).
- **Auth epochs.** Every framework sign-in carries the user's auth epoch, as
  [Auth epochs](#auth-epochs) describes. Under the engine, the default guard's
  epoch is Magnetar's own, and the session middleware checks it on every
  request by validating the Magnetar session, so the framework compares no
  second value for that guard. `Auth::attempt` issues the session at the auth
  epoch read with the password, and carries that epoch into
  `TwoFactor::start_challenge` rather than reading it again. A password reset or "sign out everywhere"
  that commits after the password was read therefore cancels the sign-in
  with `401`, and one between `start_challenge` and `complete_challenge`
  cancels the challenge with `401` before its code is read. The epoch comes
  from the same row read as the password hash when the user model returns it
  from `Authenticatable::auth_epoch`; otherwise the session guard reads it
  right after looking the user up and before checking the password.
  They never see a password elsewhere: `Auth::login_id` reads the epoch when
  the request commits, and a `start_challenge` after the application's own
  password check reads it when it runs.
- **Remember-me.** The factor check covers remember-me credentials issued
  during these logins. A credential issued later with
  `Auth::issue_remember_cookie` is not checked: Magnetar treats a remembered
  sign-in as having proved every factor, so issue one only for a user who
  did.
- **Replaced logins.** When a login replaces a bound identity, or a logout
  ends one, the old Magnetar session is revoked.
- **Custom engines.** A custom engine signs these logins in only if it
  implements `admit_host_sign_in` and `issue_host_session`. Their default
  bodies refuse, so under an engine without them every framework login fails
  closed with `503` instead of storing an identity the next request would
  drop.

When the engine refuses or fails, the request answers with that error and
stores nothing. The browser is never told it signed in when the next request
would sign it out.

### Password authentication

Use the Magnetar password facade when the application wants the integrated
credential, lockout, factor-gate, and session path:

```rust,ignore
use suprnova::{Auth, HttpResponse, Registration};

// Both outcomes get the same answer, so the endpoint does not reveal which
// addresses already have an account.
let _registration: Registration = Auth::password()
    .register("alice@example.com", password)
    .await?;
let response = HttpResponse::json(serde_json::json!({
    "message": "Registration received. Sign in with your email and password."
}))
.status(202);

// Later, on the sign-in endpoint:
let (user, session) = Auth::password()
    .authenticate(
        "alice@example.com",
        password,
        request.header("User-Agent").map(str::to_string),
        request.peer_ip().map(str::to_string),
    )
    .await?;
```

`register` returns a `Registration`. `Registration::Created(user)` carries the
new account. An address that already has an account returns
`Registration::Accepted`, which carries nothing: that account is neither
changed nor returned, so registration can never sign the requester in as its
owner. Signing a `Created` account in at once is safe, because its password is
the one just submitted, but that answer differs from the one `Accepted` can
give, so it shows that the address was free. Answer both variants the same way
when registration must not reveal which addresses have accounts.

The two outcomes cost nearly, not exactly, the same. Both hash the submitted
password, the expensive step, before the address is looked up, and both read
an account back. Only a new address writes a row, so over many requests the
response time can still tell a free address from a taken one where a write is
slow. Registration goes through the auth abuse limiter, which keeps that kind
of probing slow; don't rely on the timing alone to hide an address.

### Why Suprnova diverges

Laravel's starter kits validate registration with a `unique:users` rule, which
answers "The email has already been taken" and so tells any visitor which
addresses have accounts. `register` instead reports an existing address as
`Registration::Accepted` and returns nothing about its account, so the
application can give one answer to every registration.

`authenticate` returns HTTP 401 errors for invalid credentials, lockout, or a
required second factor. Storage and engine failures remain server errors. The
method never returns password material.

### Passkeys

Passkey begin and finish calls require `SessionMiddleware` because the
single-use ceremony selector is stored in the framework session:

```rust,ignore
let challenge = Auth::passkey()
    .begin_authentication("alice@example.com")
    .await?;

let (user, session) = Auth::passkey()
    .finish_authentication("alice@example.com", browser_credential)
    .await?;
```

Registration follows the corresponding `begin_registration` and
`finish_registration` pair. Existing-account enrollment requires a verified
request actor and recent reauthentication through the plugin path; a bare user
ID in a legacy session is not promoted into a credential actor.

### First email proof and auth epochs

Magnetar treats the first successful mailbox proof on an unverified account as
an atomic credential boundary. Password reset, magic-link consumption, and
OAuth verified-email completion can win this boundary.

The transaction advances the account's authentication epoch, revokes old
sessions and remember credentials, and removes provisional credentials that a
squatter could have registered before the mailbox owner arrived. Password,
passkey, linked-account, and two-factor writes carry an actor snapshot and fail
if the account epoch changed while the operation was in flight.

For an already verified account, password reset preserves legitimate passkeys,
linked accounts, and two-factor enrollment while still rotating the password
and invalidating sessions. OAuth never auto-links an unverified existing
account by email alone; it requires verified-email completion or explicit
linking according to host policy.

### Direct Magnetar crate surface

Most applications stay on the framework facades. Applications building a
custom identity host can depend directly on `suprnova-magnetar` for:

- Framework-neutral plugin routes and effect handlers.
- Password and password-management plugins.
- Passkey and two-factor engines.
- OAuth authorization, grants, provider plugins, device authorization, and
  token-broker services.
- Opaque, JWT, remember, and grant session engines.
- Custom storage bindings and the default SeaORM schema.
- Shape-aware auth-data migration.

Direct use does not transfer HTTP or application-user ownership to Magnetar.
The host still maps wire requests, mail effects, application IDs, rate-limit
drivers, and session bindings into its own framework.

## The `Auth` facade

The static `Auth` facade is the Laravel-shaped surface you call from
controllers and middleware. The credential- and user-based methods
delegate to the **default guard** (whatever `AuthConfig::default_guard`
points at, default `"web"`); the synchronous `check`/`guest`/`id` reads
are the session-backed fast path and need no manager.

```rust
use suprnova::{Auth, Credentials};

// Validate credentials and log the user in. Fires Attempting → (Login +
// Authenticated), honours remember-me. Returns the resolved user, or
// None on bad credentials.
if let Some(user) = Auth::attempt(&Credentials::password(&email, &password), remember).await? {
    println!("Welcome, user {}", user.get_auth_identifier());
}

// Log a known user in directly.
Auth::login(user, remember).await?;

// Log in by id without re-checking credentials (e.g. just-finished registration).
Auth::login_using_id(&id, remember).await?;

// Validate credentials without persisting a session (password-confirmation dialogs).
let ok: bool = Auth::validate(&Credentials::password(&email, &password)).await?;

// Authenticate for this request only - no session write. Laravel's `once`.
let ok: bool = Auth::once(&Credentials::password(&email, &password)).await?;
Auth::once_using_id(&id).await?;

// Session-backed fast path (no AuthManager required).
if Auth::check()    { /* authenticated */ }
if Auth::guest()    { /* not authenticated */ }
if let Some(id) = Auth::id() { /* string id */ }

// Whether the current user was authenticated by remember-me cookie this
// request. Laravel's `viaRemember()`.
if Auth::via_remember() { /* … */ }

// Resolve the current user (via the registered provider).
if let Some(user) = Auth::user().await? {
    println!("user id: {}", user.get_auth_identifier());
}
if let Some(user) = Auth::user_as::<User>().await? {
    println!("Welcome, {}!", user.name);
}

// Tear down auth + revoke remember-me + rotate CSRF + fire Logout.
Auth::logout().await?;

// Full session destruction (regenerate id + flush + revoke remember-me + fire Logout).
Auth::logout_and_invalidate().await?;
```

`Auth::attempt` returns the resolved user on success rather than a bare
`bool` - richer than Laravel's API, and saves the follow-up `Auth::user()`
call. `Ok(None)` means the credentials did not resolve a user; `Err`
means a database / hashing / configuration failure that needs to bubble.

If you have already verified a user's identity yourself and only want
to establish the session - say after an OAuth callback completes -
reach for the synchronous primitive:

```rust
// Sync, no provider, no AuthManager, no events. Returns Err when called
// outside a request scope (no SessionMiddleware installed) so a
// silently-dropped login can never look like success.
Auth::login_id(user.id.to_string())?;
```

`login_id` regenerates the session id (preventing session fixation) and
rotates the CSRF token, then writes the id into the session. It's
deliberately failure-loud: previous versions silently no-op'd outside a
session scope, and the audit fixed that - a "successful login" that
never landed is the kind of bug nothing else catches.

You call `Auth::logout_other_devices(password).await?` from a session-backed
request to sign out your other devices. You verify the password against the
current user through the default guard's provider. With the correct password,
you revoke the user's other sessions and remember credentials while keeping
the current session ID, CSRF token, session data, and remember selector. With
an incorrect password, you receive `FrameworkError::Validation` on `password`
and keep every credential unchanged.

When the provider rewrites the password hash after the password check, as
`EloquentUserProvider` and `DatabaseUserProvider` do for a database shared
with Laravel, the hash is a new [auth epoch](#auth-epochs). The current
session is bound to the new epoch, and without Magnetar the current
remember-me cookie is replaced with one bound to it, so this browser stays
signed in.

With Magnetar installed, you also revoke its other sessions and remember
credentials while keeping the current web binding. You keep the current
browser signed in without advancing the user's auth epoch. You propagate
storage errors. With a custom session store, you implement
`SessionStore::destroy_other_guard_sessions`; with a custom Magnetar remember
store or engine, you implement `revoke_other_remember` to preserve the given
selector.

## `Auth::user()` and `user_as<T>`

`Auth::user()` returns the user behind the trait:

```rust
if let Some(user) = Auth::user().await? {
    println!("user id: {}", user.get_auth_identifier());
}
```

That trait object covers anyone who implements `Authenticatable`. To get
your concrete `User` back, downcast through `user_as::<T>()`:

```rust
use suprnova::Auth;
use crate::models::user::User;

if let Some(user) = Auth::user_as::<User>().await? {
    // Field access on the model directly.
    println!("Welcome, {}!", user.name);
}
```

`user_as` returns `Ok(None)` both when no user is authenticated *and*
when the resolved user isn't a `T` (e.g. an `Auth::set_user(...)` of
a different type elsewhere in the stack). Inside a request the user is
cached per-request, so calling `Auth::user()` repeatedly only hits the
provider once.

## Named guards

The bare `Auth::*` methods talk to the default guard. To act against a
specific guard, resolve it by name:

```rust
use suprnova::Auth;

// Read-only operations work on every driver.
if Auth::guard("api")?.check().await? { /* … */ }

// Login/logout/attempt need a stateful guard. Token guards fail loud here.
let user = Auth::stateful_guard("web")?
    .attempt(&credentials, false)
    .await?;
```

`Auth::guard("name")` returns `Arc<dyn Guard>` (the read contract) and
`Auth::stateful_guard("name")` returns `Arc<dyn StatefulGuard>` (adds
`attempt`/`login`/`logout`). Asking for the stateful contract on a token
guard returns an error with a remediation message rather than silently
limiting the API.

## Guards of your application

The framework ships two guard drivers, `session` and `token`. For a
guard it does not ship (an API key, a client certificate, a single
sign-on cookie), you register a driver of your own and declare a guard
that uses it. `GuardDriver` has three variants: `Session`, `Token`, and
`Custom(String)`. It is not `Copy`, so borrow a driver or call
`.clone()` where you copied it, and give a `match` that names every
variant a `GuardDriver::Custom(_)` arm.

The name of a guard of your application cannot be empty or contain `:`,
and neither can the name of any other guard except the default session or
token guard. The manager returns an error when you resolve such a guard,
and `via_request` refuses to register a resolver for it, before either
changes anything. The rule keeps two guards from attesting the same principal (see
[Guards and Live](#guards-and-live)).

### `Auth::extend`

`Auth::extend(driver, factory)` registers the factory of a driver.
`GuardConfig::custom(driver, provider)` declares a guard of that driver:

```rust
use std::sync::Arc;
use suprnova::{Auth, AuthConfig, Guard, GuardConfig, TokenGuard};

let config = AuthConfig::from_env()
    .guard("partner", GuardConfig::custom("api_key", "partners"));

// The factory gets the name of the guard and its provider. It returns
// any `Guard`; `TokenGuard` stands in for your own type here.
Auth::extend("api_key", |_name, provider| {
    Ok(Arc::new(TokenGuard::new(provider)) as Arc<dyn Guard>)
})?;
```

The factory has the type
`Fn(&str, Arc<dyn UserProvider>) -> Result<Arc<dyn Guard>, FrameworkError>`.
Inside a request the manager builds one instance per guard name and keeps
it for that request, so the factory runs once per request and a guard may
keep its user on the instance; outside a request each `Auth::guard("partner")`
builds a fresh one. State that must outlive the request still belongs in
the session or your own store, not in the guard value.

If you resolve a guard whose driver has no factory, you get an error
that names the guard and the driver and tells you to call
`Auth::extend`. It never falls back to a built-in driver. Registering a
driver twice keeps the last factory, and `Auth::extend` never replaces
`session` or `token`. It refuses a driver name that starts with
`via_request:`, because that prefix belongs to `Auth::via_request`.

### `Auth::via_request`

Most custom guards read one thing from the request and look up a user.
`Auth::via_request(name, resolver)` is the short form for that. The
resolver gets the `&Request` and answers with the user (`Ok(Some(user))`),
with no user (`Ok(None)`), or with an error. You declare the guard with
the driver that `AuthManager::via_request_driver(name)` derives from its
name.

This example authenticates a partner from the `X-Api-Key` header, from
the config to the route:

```rust
use std::sync::Arc;
use suprnova::http::text;
use suprnova::{
    handler, App, Auth, AuthConfig, AuthManager, AuthMiddleware, GuardConfig,
    Request, Response, Router, UserProvider,
};

pub async fn bootstrap() -> Result<(), suprnova::FrameworkError> {
    // `PartnerProvider` is your `UserProvider`. Its
    // `retrieve_by_credentials` looks the partner up by a hash of the
    // key, so the code never compares a secret with `==`.
    let partners: Arc<dyn UserProvider> = Arc::new(PartnerProvider);

    // Declare the guard under the driver that `via_request` derives.
    let driver = AuthManager::via_request_driver("partner");
    let entry = GuardConfig::custom(driver, "partners");
    let config = AuthConfig::from_env().guard("partner", entry);
    App::singleton(AuthManager::new(config));
    Auth::register_provider("partners", partners.clone())?;

    // Read what the future needs from the request first, so the future
    // owns its data.
    Auth::via_request("partner", move |request| {
        let key = request.header("x-api-key").map(str::to_owned);
        let partners = partners.clone();
        Box::pin(async move {
            let Some(key) = key else { return Ok(None) };
            let credentials = serde_json::json!({ "api_key": key });
            partners.retrieve_by_credentials(&credentials).await
        })
    })?;
    Ok(())
}

#[handler]
pub async fn me(_req: Request) -> Response {
    match Auth::guard("partner")?.user().await? {
        Some(user) => text(format!("partner {}", user.get_auth_identifier())),
        None => text("no partner"),
    }
}

pub fn routes() -> Router {
    Router::new()
        .get("/partner/me", me)
        .middleware(AuthMiddleware::new().for_guard("partner"))
}
```

`GuestMiddleware::for_guard("partner")` runs the resolver the same way.

These rules hold for a guard of `Auth::via_request`:

- The resolver runs once for a request, inside the middleware for that
  guard. `AuthMiddleware::for_guard` and `GuestMiddleware::for_guard`
  run it, and the guard reads the answer.
- Outside that middleware, `Auth::guard("partner")` reports no user,
  as the token guard does without `BearerTokenMiddleware`. A handler
  that no such middleware protects sees a guest.
- An error of a factory or of a resolver fails the request with `500`.
  It is never a guest, and `AuthMiddleware::optional()` does not change
  that.
- The guard is read-only through the manager. `Auth::stateful_guard`
  returns an error for it, and so does `BasicAuthMiddleware::for_guard`.
- Each guard sees its own user. A guard of your application never reads
  the user of the default guard or of another guard, and
  `AuthMiddleware::for_guard` takes the principal of the request from
  the user of that guard.

`AuthManager::via_request(name, resolver)` is the method of the manager
behind `Auth::via_request`. It returns a `Result`, so end the call with
`?`.

The same rules hold for a guard that `Auth::extend` registers, except
that no resolver runs. A middleware earlier in the chain validates the
credential and records what it proved in request-scoped state, and your
guard reads that state, as the token guard reads the bearer id.

### `Auth::via_request_with_provider`

A resolver that looks the user up through the guard's own provider takes
that provider as a second argument. `Auth::via_request_with_provider(name,
resolver)` hands it the `Arc<dyn UserProvider>` that the guard's
configuration names, as Laravel's `viaRequest` callback receives `$request`
and `$provider`:

```rust
use suprnova::Auth;

// `partner` is declared with `GuardConfig::custom(driver, "partners")`,
// so `provider` is the provider registered under `partners`.
Auth::via_request_with_provider("partner", |request, provider| {
    let key = request.header("x-api-key").map(str::to_owned);
    Box::pin(async move {
        let Some(key) = key else { return Ok(None) };
        let credentials = serde_json::json!({ "api_key": key });
        provider.retrieve_by_credentials(&credentials).await
    })
})?;
```

The resolver doesn't capture a provider of its own, so a callback you port
from Laravel keeps its shape. The manager looks the provider up each time
the resolver runs. A provider you register after the resolver, or register
again under the same name, is the one the resolver receives, and the same
one the guard's `validate` uses. If no provider is registered under the
name the configuration gives, the request fails with `500` before the
resolver runs.

`Auth::via_request` is built on this function: its resolver takes the
request alone, and the rules above hold for both. Registering a guard name
twice keeps the last resolver, whichever function registered it.
`AuthManager::via_request_with_provider` is the method of the manager
behind it.

### A guard of your application as the default guard

A guard of your application is read-only through the manager. When you
declare one as the default guard, the functions of `Auth` that take no
guard name act as follows:

- `Auth::user` and the other functions that load the user ask that guard.
- `Auth::logout`, `Auth::login_id` and `Auth::login_remember` return an
  error and change nothing. So do the stateful functions that go through
  `Auth::stateful_guard`, such as `Auth::login` and `Auth::attempt`.
- `Auth::set_user` behaves as it does with the token guard: `Auth::id` and
  `Auth::check` see the user, and `Auth::user` still answers from the guard
  itself.
- `AuthMiddleware::new()`, with no `for_guard`, asks that guard, runs its
  resolver, and attests the user it returns.

A logout forgets the users that the guards of your application resolved in
the request, so the request does not sign itself back in through a later
middleware.

### Guards and Live

The principal that `AuthMiddleware` attests for a Live component is the
user of the guard it checked. For the default session or token guard, it is
the bare id, such as `7`. For any other guard - a second session guard such
as `admin`, a second token guard, or a guard of your application - it is
`<guard>:<id>`.
The same id under two guards is two principals: web user `7` differs from
admin `7` and from partner `7`, even when both guards read one table. A user
of another guard in the same session never stands in for the guard's own
user.

A default-guard id that holds a `:` gets a leading `:`. Web user `admin:9`
attests `:admin:9`, so it never reads as admin `9`, whose principal is
`admin:9`. No guard can attest a principal that starts with `:`, because a
guard name cannot be empty. An id without a `:` is its own principal, so an
application whose ids are numbers, UUIDs or ULIDs sees the value it always
saw.

The render cache keys a page by the default guard's principal. An identity
read through any other guard is recorded as `<guard>:<id>`, so a page built
from it is never stored under the default guard's key and never served to a
visitor who lacks that guard's sign-in. See [Render
cache](render-cache.md).

Live's gated actions, uploads, subscriptions and memberships, and the
Pusher endpoints, use the same principal: the route's user, the bare id for
the default guard (with the leading `:` above) and `<guard>:<id>` for any
other. See [Live](live.md#security-boundaries) and
[Broadcasting](broadcasting.md).

### Why Suprnova diverges

In Laravel, the closure of `Auth::viaRequest` runs when the guard
resolves its user, and it gets the current request. A Rust guard cannot
reach the request from `user()`. So the middleware for the guard runs
the resolver with the request, and the guard reads the answer. That is
why the guard reports no user outside that middleware.

Laravel's request guard also answers `validate` through its closure, which
checks no password. A Suprnova request guard validates credentials through
its provider, as the token guard does.

## User providers

A `UserProvider` tells the auth stack how to fetch and validate users.
Two providers ship built in, so the common case needs no custom
implementation:

- **`EloquentUserProvider<M>`** - resolves through a typed
  `#[suprnova::model]` `User` that is also `Authenticatable`. Looks up
  by primary key for ids, by `email` (default) for credentials.
- **`DatabaseUserProvider`** - resolves a raw table by name into a
  `GenericUser` (id + attribute map). Use it when you don't have or
  want a typed model.

Both filter credential lookups against an allowlist (default
`["email"]`) - a hostile credential map cannot inject extra `WHERE`
predicates. Customise the allowlist with `.credential_columns([...])`,
the lookup column with `.identifier_column("uuid")`, or the id-binding
strategy with `.with_id_parser(...)`.

By default a numeric id binds as an integer and any other id as text. An
id above `i64::MAX` binds as a `u64`, so a user whose key is Laravel's
`BIGINT UNSIGNED` `users.id` signs in at any value on MySQL. Postgres and
SQLite hold no integer key that large, so there such an id finds no user.
A text identifier column that holds the id's digits finds the user on
every database: `DatabaseUserProvider` reads the column's type for such
an id and compares the digits as text. The type comes from the table the
lookup reads: on Postgres the first schema of the search path that holds
it, or the schema the table name names, so a table of the same name in
another schema never decides the bind.

To plug in a custom source (LDAP, an external API), implement
`UserProvider` directly. `retrieve_by_id` takes the identifier as
a `&str`:

```rust
use async_trait::async_trait;
use std::sync::Arc;
use suprnova::{Authenticatable, FrameworkError, UserProvider};

struct LdapProvider;

#[async_trait]
impl UserProvider for LdapProvider {
    async fn retrieve_by_id(
        &self,
        id: &str,
    ) -> Result<Option<Arc<dyn Authenticatable>>, FrameworkError> {
        // … fetch from LDAP, return as Arc<dyn Authenticatable>
        Ok(None)
    }

    // retrieve_by_credentials + validate_credentials have trait defaults
    // that return None / false. Override them to support `Auth::attempt`
    // and `Auth::validate` against your source.
}
```

Register it on the manager:

```rust
Auth::register_provider("ldap", Arc::new(LdapProvider))?;
```

## Protecting routes

### `AuthMiddleware`

Gate authenticated-only routes. Unauthenticated requests are redirected
to a login page or receive `401`:

```rust
use suprnova::{AuthMiddleware, Router};

pub fn routes() -> Router {
    Router::new()
        .get("/dashboard", controllers::dashboard::index)
        .post("/logout", controllers::auth::logout)
        .middleware(AuthMiddleware::redirect_to("/login"))
}
```

`AuthMiddleware::new()` returns `401 Unauthorized` instead - best for
JSON APIs. `AuthMiddleware::redirect_to("/login")` issues a `302` for
regular requests and a `409 X-Inertia-Location` for Inertia requests
(which the Inertia client turns into a full-page visit). To gate on a
specific guard, chain `for_guard`:

```rust
// 401 unless the api guard is authenticated.
.middleware(AuthMiddleware::new().for_guard("api"))
```

A token guard (`for_guard("api")`) relies on whatever bearer-token
middleware runs earlier in the chain to populate the request's auth id;
without it the guard always reports unauthenticated.

A guard of your application (see [Guards of your
application](#guards-of-your-application)) decides alone. The user it
resolves is the principal of the request, and the middleware attests it as
`<guard>:<id>`. With no `for_guard`, `AuthMiddleware::new()` does the same
when the default guard is a guard of your application.

### `GuestMiddleware`

The inverse - for login and registration pages that authenticated users
shouldn't see:

```rust
use suprnova::{GuestMiddleware, Router};

pub fn routes() -> Router {
    Router::new()
        .get("/login", controllers::auth::show_login)
        .post("/login", controllers::auth::login)
        .get("/register", controllers::auth::show_register)
        .post("/register", controllers::auth::register)
        .middleware(GuestMiddleware::redirect_to("/dashboard"))
}
```

`GuestMiddleware::for_guard("name")` works the same way as
`AuthMiddleware::for_guard`.

### `BasicAuthMiddleware`

HTTP Basic auth from the `Authorization: Basic` header against a
guard's provider:

```rust
use suprnova::BasicAuthMiddleware;

// Stateful - logs the user into the session on success (Laravel's `basic`).
.middleware(BasicAuthMiddleware::new())

// Stateless - authenticates for this request only (Laravel's `onceBasic`).
.middleware(BasicAuthMiddleware::once())
```

The decoded username is matched against the `field` credential (default
`"email"`); a missing, malformed, or invalid header returns `401` with
a `WWW-Authenticate: Basic realm="..."` challenge. Configure with
`.field(...)`, `.realm(...)`, and `.for_guard(...)`.

With `BasicAuthMiddleware::new()`, a request whose session is already signed
in to the guard passes without a header. The guard first resolves that user
and compares its [auth epoch](#auth-epochs), as `AuthMiddleware` does, so a
session signed in before a password change is signed out and must present
valid credentials.

## Lifecycle events

The guards dispatch five lifecycle events. Listen for them via the
[`EventFacade`](events.md):

| Event | When |
|---|---|
| `Attempting` | a credential attempt begins (`attempt`/`once`) |
| `Authenticated` | a user is actively authenticated this request (`login`/`once`/`once_using_id`) |
| `Login` | a user is persisted to the session (`login`/successful `attempt`) |
| `Logout` | a user is logged out |
| `Failed` | a credential attempt fails (bad password or unknown id) |

Every event carries the guard name and a string user id - never the
plaintext password and never the raw credential map. `Authenticated`
fires only when a user is actively established, not on a passive
`Auth::user()` resolution off an existing session, so listeners don't
get a stream of duplicates on every authenticated request.

## The scaffolded login flow

`suprnova new` generates an authentication controller that uses
`Auth::attempt` against the registered provider. `FormRequest` and `Validate`
produce the `{ message, errors }` validation envelope. For an Inertia request,
the installed validation-redirect middleware turns that failure into an HTTP
`303 See Other` redirect back and flashes the errors for the originating page.
A non-Inertia client receives the HTTP `422 Unprocessable Entity` JSON
envelope:

```rust
use serde::Deserialize;
use suprnova::{
    handler, inertia_response, redirect, Auth, Credentials, FormRequest,
    InertiaProps, Request, Response, Validate, ValidationErrors,
};

// No `errors` prop: the framework seeds `errors` on every Inertia page
// from the session-flashed validation bag, and an explicit prop of the
// same name would replace it.
#[derive(InertiaProps)]
pub struct LoginProps {}

#[handler]
pub async fn show_login(req: Request) -> Response {
    inertia_response!(&req, "auth/Login", LoginProps {})
}

#[derive(Deserialize, Validate)]
pub struct LoginRequest {
    #[validate(email(message = "Please enter a valid email address"))]
    pub email: String,
    #[validate(length(min = 1, message = "Password is required"))]
    pub password: String,
    #[serde(default)]
    pub remember: bool,
}

impl FormRequest for LoginRequest {}

fn invalid_credentials() -> suprnova::FrameworkError {
    let mut errs = ValidationErrors::new();
    errs.add("email", "These credentials do not match our records.");
    suprnova::FrameworkError::Validation(errs)
}

#[handler]
pub async fn login(form: LoginRequest) -> Response {
    match Auth::attempt(
        &Credentials::password(&form.email, &form.password),
        form.remember,
    )
    .await?
    {
        Some(_user) => redirect!("/dashboard").into(),
        None => Err(invalid_credentials().into()),
    }
}

#[handler]
pub async fn logout(_req: Request) -> Response {
    Auth::logout().await?;
    redirect!("/").into()
}
```

Registration follows the same shape: validate the form, create the
user, mail a verification link with `EmailVerification::send_link`, then
`Auth::login(Arc::new(user), false).await?` logs the freshly created user
into the session, fires the `Login` event, and continues to
`/verify-email`. The generated `email_verification` and `password_reset`
controllers complete the account flows; see [Auth flows](auth-flows.md).

## The scaffolded `User` model

The generated `User` is a `#[suprnova::model]` that implements
`Authenticatable`. It also contains
`email_verified_at: Option<DateTime<Utc>>` and implements `MustVerifyEmail` and
`CanResetPassword`. Those bridges let `EloquentUserProvider<User>` mark email
verification and supply password-reset identity data. The excerpt below shows
only the guard-login fields and helpers; use the generated model template for
the complete auth-flow implementation. Its password helpers use the
[`hashing`](hashing.md) module:

```rust
use chrono::{DateTime, Utc};
use suprnova::{attrs, hashing, model, Authenticatable, FrameworkError};

#[model(
    table = "users",
    fillable = ["name", "email", "password"],
    hidden = ["password", "remember_token"],
    timestamps,
    casts = {
        email_verified_at = suprnova::AsOptionalNaiveDateTime,
        created_at = suprnova::AsNaiveDateTime,
        updated_at = suprnova::AsNaiveDateTime,
    },
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub password: String,
    pub remember_token: Option<String>,
    pub email_verified_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

impl User {
    pub async fn find_by_email(email: &str) -> Result<Option<Self>, FrameworkError> {
        <Self as suprnova::eloquent::Model>::query()
            .filter("email", email)
            .first()
            .await
    }

    pub fn verify_password(&self, password: &str) -> Result<bool, FrameworkError> {
        hashing::verify(password, &self.password)
    }

    pub async fn create(
        name: impl Into<String>,
        email: impl Into<String>,
        password: &str,
    ) -> Result<Self, FrameworkError> {
        let hashed = hashing::hash(password)?;
        <Self as suprnova::eloquent::Model>::create(attrs! {
            name: name.into(),
            email: email.into(),
            password: hashed,
        })
        .await
    }
}
```

The `hidden = ["password", "remember_token"]` attribute makes the model
skip those columns when serialising to JSON for the wire - they exist
on the struct but never leak through an Inertia response.

The generated users migration creates `email_verified_at`, `created_at` and
`updated_at` with `.date_time()`: `DATETIME` on MySQL, `timestamp` on
Postgres. The casts name the native casts for those columns; the default
`AsDateTime` stores text, which those columns refuse (see
[native date-time casts](eloquent-mutators.md#native-date-time-casts)).
An application generated before this change has `.timestamp()` columns
instead, `TIMESTAMP` on MySQL and MariaDB and `timestamp` on Postgres, and a
`User` without casts, which fails to register or sign in a user on those
engines. Give its three fields the casts for its columns:
`AsNativeDateTime` and `AsOptionalNativeDateTime` on MySQL and MariaDB,
`AsNaiveDateTime` and `AsOptionalNaiveDateTime` on Postgres. On SQLite
either pair reads the rows the text cast wrote.

## Remember-me

When a Magnetar engine is installed, `Auth::attempt(credentials, true)` and
`Auth::issue_remember_cookie` issue purpose-bound Magnetar remember
credentials. The browser still receives the framework's encrypted
`remember_me` cookie, while Magnetar owns verifier storage, auth-epoch checks,
single-use rotation, anomaly handling, and revocation.

On a request without an active framework login, `SessionMiddleware` consumes
the cookie through the installed engine, rotates the remember credential,
issues a fresh Magnetar session, and binds both session layers. A stale auth
epoch, revoked account session, malformed credential, or replay does not
authenticate the request.

`Auth::revoke_remember_tokens()` invalidates every remember credential for the
current user. The clear cookie is queued before backend revocation, so the
browser drops its credential even when the storage operation fails.

When no Magnetar engine is installed, the framework retains the legacy
`remember_tokens` fallback for compatibility. New applications should
initialize Magnetar rather than relying on that fallback. Each row of the
fallback is bound to the user's [auth epoch](#auth-epochs) at issue: its
hash covers the verifier and the epoch together, so a cookie issued before
a password change fails verification after it, its row is deleted, and its
cookie is cleared.

## Auth epochs

Every sign-in that the framework issues through a user provider records the
user's *auth epoch*, and every request that resolves the user compares it
with the user's current one. A password change therefore ends every older
sign-in on its next request, even when the password reset's revocation of
the user's other sessions failed.

The epoch of a user is the value `Authenticatable::auth_epoch` returns. When
the model returns `None`, the epoch is a digest of the password hash that
`Authenticatable::get_auth_password` returns. Every password write stores a
new hash, with a new salt even for the same password, so the digest changes
with every reset, change, and rehash, and no table needs a new column.

The framework records and compares the epoch in these places:

- **Session sign-ins.** `Auth::attempt`, `Auth::login`,
  `Auth::login_using_id`, `Auth::login_remember`, and the same methods of a
  named session guard read the epoch through the guard's provider and record
  it beside the guard's identity in the session. `Auth::login_id`,
  `session::set_auth_user`, and `TwoFactor::complete_challenge` don't read
  it themselves. The request that signs in reads it through the default
  guard's provider before `SessionMiddleware` stores the session. If the
  provider fails that read, the sign-in isn't stored, and the framework
  logs a warning with the guard and the user id.
- **Remember-me credentials.** Without the Magnetar engine, each
  `remember_tokens` row is bound to the epoch that the guard's provider read
  for the sign-in. The cookie verifies only against the user's current
  epoch, read through the provider of the guard that the cookie names. A
  `SessionGuard` that you build yourself under a name the `AuthManager`
  doesn't know can't issue one: its login completes without a remembered
  session and logs a warning that names the guard. To use remember-me with
  such a guard, register the guard with the `AuthManager`.
- **Requests.** `Auth::user`, a guard's `user` method, `AuthMiddleware`, and
  `BasicAuthMiddleware::new()` resolve the user and compare.
  `BasicAuthMiddleware::new()` lets a session that is already signed in
  pass without an `Authorization` header only after this comparison.
  `Auth::id` and `Auth::check` read the session without resolving the
  user, so they don't compare.

When the epochs differ, the framework ends that sign-in before the request
reaches your handler. The guard's identity leaves the session, the
remember-me credential this session holds for the guard is deleted and its
cookie cleared, and the request continues as a guest's: `AuthMiddleware`
answers `401` or redirects to your login page, and `BasicAuthMiddleware::new()`
answers its `401` challenge unless the request carries valid credentials,
which sign the user in again. The framework logs the user id at `info`
level. It dispatches no `Logout` event, because the user didn't sign out,
and it leaves the other guards of the session signed in.

The session that changes its own user's password keeps its sign-in. When a
request that resolved the signed-in user writes that user through the model
(`save`, `update`, and their transactional forms) and the write sets the
password column (`Authenticatable::auth_password_name`, `password` unless
you override it), the sign-in records the epoch of the values the write
sent to storage, after the casts, so the password form's own session
continues while every other session and remember-me cookie of the user
ends. Inside a transaction the sign-in follows the commit: a write that
rolls back leaves it as it was. A write that leaves the password column
alone, a request that writes the user without resolving the signed-in user,
or a write that bypasses the model (a query-builder `update` or raw SQL)
never moves a sign-in, so a password change another session commits
meanwhile still ends this one on its next request. `EloquentUserProvider`
recognizes the written model as its user; a provider of your own implements
`UserProvider::written_user` the same way, with a downcast to its model
type.

A user whose model returns `None` from both `auth_epoch` and
`get_auth_password`, such as an OAuth-only account, records no epoch and
isn't checked. A session signed in before 4.0.0 carries no epoch either; it
is checked from the user's next sign-in.

If your table keeps a counter that also advances without a password change,
for example on a "sign out everywhere" action, return it from `auth_epoch`:

```rust
use std::any::Any;
use std::sync::Arc;
use suprnova::Authenticatable;

struct User {
    id: i64,
    password: String,
    session_version: u64,
}

impl Authenticatable for User {
    fn get_auth_identifier(&self) -> String {
        self.id.to_string()
    }

    fn get_auth_password(&self) -> Option<&str> {
        Some(&self.password)
    }

    // Takes the place of the password digest: bump it to end every session.
    fn auth_epoch(&self) -> Option<u64> {
        Some(self.session_version)
    }

    fn as_any(&self) -> &dyn Any {
        self
    }

    fn into_arc_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync> {
        self
    }
}
```

The first time a model returns a counter, the sessions it recorded under the
digest end once.

With the Magnetar engine installed, the default guard's sign-ins carry
Magnetar's own epoch instead; see
[Framework logins under the engine](#framework-logins-under-the-engine).

### Why Suprnova diverges

Laravel compares a session with the user's password hash only on routes
that run the `AuthenticateSession` middleware, and flushes the whole session
on a mismatch. Suprnova compares on every request that resolves a user, for
every session guard and for remember-me cookies, so a stolen credential
stops working after a password change whatever middleware the route runs. A
mismatch ends only that guard's sign-in, so another guard signed in on the
same session keeps its sign-in. Laravel keeps the session that changed the
password by storing its user object's hash again after the handler ran;
Suprnova rebinds that session at the model write, from the values the
write sent to storage, once it commits.

## Security guarantees

A short list of invariants the auth stack establishes:

- **`Auth::login_id` fails loud outside a request scope.** Previous
  versions silently dropped the session write; a "successful login"
  that never landed is the kind of bug nothing else catches.
- **Session id and CSRF token regenerate on every login.** Both
  `login_id` and the guard-backed `login`/`attempt` rotate them to
  prevent session fixation.
- **Logout clears auth state before revoking remember-me.** If the DB
  revoke fails, the session is already in a logged-out state, so a
  stale auth slot cannot survive a partial logout. The remember-me
  clear cookie is queued *before* the DB delete, so the browser drops
  the cookie even when the row delete fails (the prune sweep cleans up
  later).
- **A password change ends older sign-ins.** Every session sign-in and
  remember-me credential records the user's [auth epoch](#auth-epochs), and
  a request that resolves the user refuses one recorded under an earlier
  password, so a session that a failed revocation left behind stops working
  on its next request.
- **Credential allowlists block injection.** Both built-in providers
  filter `retrieve_by_credentials` against `credential_columns`, so
  extra keys in an attacker-influenced credential map cannot become
  extra `WHERE` predicates.
- **Credential writes are actor-fenced.** Password, passkey, linked-account,
  two-factor, session, and remember mutations carry the user ID and auth epoch
  established by verified authentication. Revocation or a first-proof epoch
  change makes an in-flight stale write fail.
- **The first mailbox proof is atomic.** On an unverified account, password
  reset, magic-link consumption, or OAuth verified-email completion advances
  the auth epoch and removes provisional credentials in the same transaction.
  A concurrent squatter write cannot restore access after commit.
- **Email verification is actor-bound.** The framework verification facade
  requires an authenticated user whose ID matches the token owner. A token for
  another account is rejected without being consumed.
- **OAuth email is not account ownership.** An unverified existing account is
  never auto-linked from a provider email alone. Verified accounts require
  explicit linking; unverified accounts require the first-email-proof
  completion path.
- **Auth events never carry plaintext.** Guard name + string user id,
  nothing else. Failed-attempt tracking (email-keyed lockouts) belongs
  to `BruteForce` in [Auth Flows](auth-flows.md), not the lifecycle
  events.

The [Session](session.md) chapter covers the cookie configuration
(`SESSION_LIFETIME`, `SESSION_COOKIE`, `SESSION_SECURE`,
`SESSION_SAME_SITE`, and `SESSION_COOKIE_PREFIX`) that session-backed guards
inherit.

## Next

- [Auth flows](auth-flows.md) - email verification, password reset,
  Magnetar-backed account lockout, framework TOTP 2FA, and auth-flow events
- [OAuth and passwordless login](oauth.md) - Magnetar OAuth, Apple, magic
  links, provider policy, and auth-data migration
- [Authorization](authorization.md) - `Gate`, policies, and `Authorizable`
- [Session](session.md) - the browser session and cookie layer
- [CSRF protection](csrf.md) - state-changing request protection
- [Hashing](hashing.md) - bcrypt and Argon2 helpers


---

<!-- /docs/auth-flows -->

# Auth Flows

`suprnova::auth_flows` is the lifecycle layer on top of
[authentication](authentication.md). Where `auth::*` answers "who is this
request", `auth_flows::*` covers mailbox proof, password recovery, account
lockout, and framework TOTP challenges.

Five surfaces ship under the namespace:

- `EmailVerification` mints and consumes framework `auth_flow_tokens`, sends
  the link through the user's `send_email_verification_notification`, a
  [notification](notifications.md) by default, and marks the authenticated
  token owner verified through the configured `UserProvider`.
- `PasswordReset` uses the installed Magnetar engine when available. Without
  Magnetar, verified accounts can reset through the configured `UserProvider`
  and framework `auth_flow_tokens`; unverified accounts fail closed because a
  generic provider cannot perform Magnetar's atomic first-email-proof policy.
- `BruteForce` and `LoginThrottleMiddleware` delegate account lockout state to
  the installed Magnetar engine.
- `TwoFactor` is the framework-owned TOTP facade over
  `two_factor_credentials`. It provides enrollment, confirmation, verification,
  recovery codes, secret rotation, challenge promotion, timestep replay
  protection, and a second-factor brute-force counter of its own in
  `two_factor_attempts`.
- `remember_me` re-exports the legacy framework remember module for namespace
  compatibility. When Magnetar is installed, normal `Auth` and
  `SessionMiddleware` remember flows use Magnetar credentials instead.

Two route-gate middleware ship in the same namespace:

- `EnsureEmailVerifiedMiddleware` composes after `AuthMiddleware` and gates
  routes on `email_verified_at`.
- `TwoFactorChallengeMiddleware` composes before `AuthMiddleware` and redirects
  a session with a pending framework TOTP challenge to the challenge form.

Transactional messages always go out through the framework [`Mail`](mail.md)
transport, the verification link as a mail notification. Magnetar supplies
security engines and storage contracts; it does not install a second
application mail transport.

### Where state lives

Email-verification tokens live in the framework's `auth_flow_tokens` table and
the verified timestamp is written through the configured `UserProvider`.
Verification is actor-bound: the current authenticated user must own the token.

Password-reset tokens, password credentials, lockout rows, opaque sessions,
remember credentials, passkey ceremonies, OAuth ceremonies, and auth epochs
belong to the installed Magnetar host engine. Password reset, magic link, and
OAuth verified-email completion share Magnetar's atomic first-email-proof
boundary for reclaiming unverified accounts.

The public `TwoFactor` facade in this chapter retains its framework-owned
`two_factor_credentials` schema. Magnetar also has a factor engine used by the
integrated password, magic-link, passkey, OAuth, and session flows. Do not
assume the two stores are interchangeable: use one enrollment surface
consistently for a given application.

Suprnova continues to own HTTP middleware, cookies, outbound mail, events, and
the `UserProvider` bridge. Application code uses framework facades rather than
calling storage engines directly.

## Failure semantics across flows

Every facade follows one ordering rule: the durable state change
commits first, then notification side effects fire. A listener panic, a
transient mail-transport failure, or a dispatcher error after the
mutation cannot roll the mutation back.

- `EmailVerification::verify` requires the authenticated token owner, consumes
  the token, and marks the user verified before firing `EmailVerified`. An
  account that is already verified has the token consumed and keeps its
  verification time, and no event fires.
- `PasswordReset::complete` commits through the installed Magnetar engine when
  available, including first-proof policy, auth-epoch advancement, and atomic
  revocation. The provider fallback is verified-account-only: it consumes the
  framework token, rotates the provider password, then reports framework
  session and remember revocation outcomes. When a revocation fails, it
  queues a retry before it returns, and returns an error when the retry
  cannot be queued. Mail and events run afterward.
- `BruteForce::unlock_account` commits the unlock before firing
  `AccountUnlocked`.
- `TwoFactor::confirm` stamps `confirmed_at` before firing
  `TwoFactorEnrolled`; `TwoFactor::disable` deletes the row before
  firing `TwoFactorDisabled`; `TwoFactor::complete_challenge`
  promotes pending → authed before dispatching the standard
  `auth::Login` + `auth::Authenticated` pair followed by
  `TwoFactorChallenged`.

A listener that needs durability should buffer its work (queue a
job from the listener body); the facades never retry a listener. The one
retry the framework queues itself is the retry of a password reset's
failed revocation, described in
[When a revocation fails](#when-a-revocation-fails).

## Bootstrapping

Initialize Magnetar after `DB::init` and after `APP_KEY` has initialized
`Crypt`:

```rust
use suprnova::{DB, MagnetarConfig, PasskeyConfig, init_magnetar};

pub async fn register() -> Result<(), suprnova::FrameworkError> {
    let database = DB::connection()?;
    let config = MagnetarConfig::from_sea_orm(database.inner().clone())
        .passkey_config(PasskeyConfig {
            rp_id: "app.example.com".to_string(),
            rp_origin: "https://app.example.com".to_string(),
        });

    init_magnetar(config).await
}
```

`init_magnetar` creates the default auth schema unless migrations are disabled,
then installs password/session and passkey adapters atomically. Calling it a
second time returns an error. Tests that need process-global installation
should use a dedicated integration-test binary because an installed engine is
not replaceable.

### Email verification

Email verification needs:

1. A registered `UserProvider` that can retrieve users by email and mark the
   verification timestamp.
2. `MustVerifyEmail` on the application user type.
3. A nullable `email_verified_at` column.
4. The framework `auth_flow_tokens` table.

```rust
use chrono::{DateTime, Utc};
use suprnova::MustVerifyEmail;

impl MustVerifyEmail for User {
    fn email(&self) -> &str {
        &self.email
    }

    fn email_verified_at(&self) -> Option<DateTime<Utc>> {
        self.email_verified_at
    }

    fn set_email_verified_at(&mut self, value: Option<DateTime<Utc>>) {
        self.email_verified_at = value;
    }
}
```

The verification handler must run inside authenticated session scope. A valid
token for another user is refused with `403` and is not consumed.

### Password reset and lockout

`BruteForce` requires the installed Magnetar password engine. Password reset
prefers that engine, but a provider-backed application can reset already
verified users without installing Magnetar when its `UserProvider` explicitly
supports password reset. `EloquentUserProvider<M>` opts in automatically when
`M` implements `MustVerifyEmail + CanResetPassword`. Unverified users receive
no reset link on the provider path; install Magnetar to use password reset as
an atomic first mailbox proof.

`MagnetarConfig::lockout_config` accepts
`magnetar::password::lockout::LockoutConfig`. The default policy enables
lockout after five failed attempts for 15 minutes, retains audit rows for seven
days, and fails closed when the lockout backend is unavailable.

The same policy counts the failed codes of Magnetar's own second-factor
challenge (`Auth::factor()`), but in a table of their own,
`auth_second_factor_lockouts`, which `default_schema::migrate` creates beside
`auth_lockouts`. Password sign-in counts against any string it's given as an
address, and anyone can register any string as one, so a shared table would
let an address reach a user's second-factor counter. A correct password
therefore doesn't clear second-factor failures, a failed sign-in can't lock a
second factor, and wrong codes don't lock password sign-in. The second factor's
keys aren't addresses, so its locks and unlocks never touch an `app_users` row:
an account registered under an address equal to a key is never locked or
unlocked by it. A password reset proves the mailbox, not the second factor, so it
leaves a second-factor lock in place until the window passes. Confirming an
enrollment, rotating the secret, and regenerating recovery codes count their
wrong codes in the same table. Each of these paths reserves its attempt before
it reads the code, so parallel guesses never get past the limit, and a failure
the lockout store can't record is returned as an error instead of a wrong code.
A confirmation confirms only the secret its code was checked against, once, and
uses the code up: if another request replaces the enrollment in between,
nothing is confirmed and the caller gets a conflict. A rotation waits beside
the confirmed secret in `auth_two_factor`'s pending columns, which
`default_schema::migrate` adds to an existing table. The confirmed secret and
its recovery codes keep gating sign-in until a code from the new secret
confirms the rotation, a plain enrollment can't replace a waiting rotation,
and disabling the factor discards it.

Password reset normalizes an unknown or provider-backed unverified address to
`Ok(())` only after the abuse-limiter, mail configuration, provider/engine, and
storage checks succeed. Configuration and storage failures still surface.
Magnetar completion uses the atomic first-email-proof store. Provider fallback
completion returns a `PasswordResetOutcome` with explicit framework session and
remember-revocation results, and queues a retry of a revocation that failed.

### Registering the 2FA migrations

The framework ships the schema; your app opts in by loading the two-factor
list, `auth_flows::two_factor::migrations()`, next to its own migrator:

```rust
use suprnova::Application;

#[suprnova::main]
async fn main() {
    Application::new()
        .bootstrap(my_app::bootstrap::bootstrap)
        .routes(my_app::routes::register)
        .migrations::<my_app::migrations::Migrator>()
        .load_migrations_from(suprnova::auth_flows::two_factor::migrations)
        .run()
        .await
}
```

The list holds every two-factor migration in order: `migration` creates
`two_factor_credentials`, `migration_replay` adds `last_used_timestep` for
TOTP replay protection, `migration_attempts` creates `two_factor_attempts`,
the second-factor brute-force counter, and `migration_rotation` creates
`two_factor_rotations`, where a rotation waits for its new secret to be
confirmed. A release that adds a two-factor migration adds it to the list,
so your application runs it without an edit. Every migrate command runs the
list; see [Migrations](migrations.md#migrations-from-the-framework-and-from-crates).

An application that lists the four migrations in its own migrator by hand
keeps working: a migration whose name the migrator already lists runs once.

The migrations are idempotent against an already-applied database (the
v1, the attempt table and the rotation table use `CREATE TABLE IF NOT
EXISTS`; the v2 is a column add). Re-running `suprnova migrate` against a production database
that already has the schema is a no-op.

An application that upgrades from a release without the attempt counter
runs `migrate` once; an application that lists the migrations by hand must
add the third one. Until it runs, every `TwoFactor` proof path answers
`503`: the attempt cannot be counted, so no code is evaluated.

### Environment

The transactional mailables read two environment variables at send
time:

| Var | Default | Used for |
|---|---|---|
| `APP_NAME` | `"Suprnova"` | Subject branding and the `otpauth://` issuer label that authenticator apps display. |
| `MAIL_FROM` | none - **errors when unset** | Envelope `From` on every outgoing message. Set to a verified sender domain. |
| `PASSWORD_RESET_TIMEBOX_MS` | `200` | How long `PasswordReset::send_link` holds every answer, in milliseconds. `0` turns the hold off. A value that is not a whole number makes `send_link` return an error before it looks anything up. |

`MAIL_FROM` deliberately has no default. Defaulting to a placeholder
like `noreply@example.com` would silently break DMARC / SPF in
production and ship from a domain the operator doesn't control, so the
facade fails closed instead. `EmailVerification::send_link` and
`PasswordReset::send_link` surface the error as `Err`;
`PasswordReset::complete` logs via `tracing::warn!` and continues
(the password change has already committed, so the notification path
cannot roll it back).

Apps additionally set `APP_URL` so controllers can derive the base URL
used in `send_link` calls; the framework facade itself takes the base
URL as a parameter.

The mail driver is configured separately via `MAIL_DRIVER` - see the
[Mail](mail.md) docs.

## Email Verification

`EmailVerification` mints, checks, and consumes verification tokens
against the `auth_flow_tokens` table and marks the user verified through
the configured provider. Four operations cover the lifecycle:

| Method | Signature | Notes |
|---|---|---|
| `send_link` | `send_link<U: MustVerifyEmail>(user: &U, base_url: &str) -> Result<()>` | Mint the token and send the link through the user's `send_email_verification_notification`, given a user already in hand. |
| `resend` | `resend(email: &str, base_url: &str) -> Result<()>` | Sends through the provider's `send_email_verification_notification`. Normalizes an unknown provider result to `Ok(())`; token storage and mail failures still return `Err`, and execution time is not equalized. |
| `check` | `check(token: &str) -> Result<bool>` | Non-consuming - safe to call on a landing page. |
| `verify` | `verify(token: &str) -> Result<String>` | Actor-bound and single-use: the authenticated user must own the token; success consumes it, marks the user verified, and returns that user ID. Another account's token gets `403`; an unknown, expired or used token gets `400`. |

```rust
use suprnova::auth_flows::EmailVerification;

// After a fresh signup, with the freshly-created user in hand:
EmailVerification::send_link(&user, "https://app.example.com/verify-email").await?;

// Optional landing-page check - non-consuming, so a page refresh
// does not burn the token.
let valid: bool = EmailVerification::check(&token_str).await?;

// The click-through handler runs behind authentication. `verify`
// consumes the token only when `Auth::id()` matches its owner.
let user_id: String = EmailVerification::verify(&token_str).await?;
```

`verify` fires `EmailVerified` on success - listeners are the right
place to unlock additional functionality (welcome email, default
follows, "complete your profile" CTA) without coupling them to the
verification handler. The event carries the provider's user id. When the
provider's `is_email_verified` already reports the account verified, `verify`
consumes the token and returns the user ID without a new stamp and without the
event, so a second link never moves the first verification time.

### Sending your own verification message

`send_link` mints the token, builds the link, and passes it to the user's
`MustVerifyEmail::send_email_verification_notification`. The default sends the
framework's `VerifyEmailNotification` to `email()` as an on-demand mail
notification through `Notify`. It goes through the mail channel of the
dispatcher you bound with `notifications::set_dispatcher`, or through the
framework's mail channel when you bound none, so verification mail needs no
notification setup.

Override the method to send your own message. The framework then sends
nothing itself, and the link you receive carries the same single-use token, so
`verify` accepts it:

```rust
use chrono::{DateTime, Utc};
use suprnova::{FrameworkError, Mail, MustVerifyEmail};

impl MustVerifyEmail for User {
    fn email(&self) -> &str {
        &self.email
    }

    fn email_verified_at(&self) -> Option<DateTime<Utc>> {
        self.email_verified_at
    }

    fn set_email_verified_at(&mut self, value: Option<DateTime<Utc>>) {
        self.email_verified_at = value;
    }

    async fn send_email_verification_notification(
        &self,
        verification_link: &str,
    ) -> Result<(), FrameworkError> {
        Mail::raw(format!("Confirm your address: {verification_link}"), |mail| {
            mail.to(self.email.as_str()).subject("Confirm your address")
        })
        .await
    }
}
```

`resend` holds only the ID the provider returned, so it sends through
`UserProvider::send_email_verification_notification(id, verification_link)`.
`EloquentUserProvider` loads the model and calls the model's method, so your
override runs on both paths. The provider default sends the framework's
notification to `verification_email(id)`, greeting the name of
`flow_user_by_id(id)`, and returns an error when the provider reports no
verification address.

`resend` binds the link to the provider's `verification_email(id)`, not to the
address it looked the account up by. For `EloquentUserProvider` that is your
model's `email()`, the address `send_link` binds and `verify` checks. A model
whose `email()` reads a column other than the `email` column `resend` looks up
by therefore gets a link that `verify` accepts. A provider that reports no
verification address keeps the lookup address, and its
`send_email_verification_notification` decides the outcome.

### The resend endpoint (anti-enumeration)

`resend` takes only the email and looks up the user through the active
provider. An unknown provider result is normalized to `Ok(())`. For a known
account, the facade mints a token and sends the mail.
`EmailVerification::resend` likewise normalizes an unknown provider result to
`Ok(())`; it does not guarantee identical timing or identical behavior when
token storage or mail delivery fails. A handler can still return a neutral
message after either successful result:

```rust
use std::collections::HashMap;
use suprnova::auth_flows::EmailVerification;
use suprnova::{FrameworkError, HttpResponse, Request, Response};

pub async fn resend(req: Request) -> Response {
    resend_inner(req).await.map_err(HttpResponse::from)
}

async fn resend_inner(req: Request) -> Result<HttpResponse, FrameworkError> {
    let raw = req.query().unwrap_or("");
    let params: HashMap<String, String> =
        url::form_urlencoded::parse(raw.as_bytes()).into_owned().collect();
    let email = params
        .get("email")
        .ok_or_else(|| FrameworkError::bad_request("missing email"))?;

    let base = format!(
        "{}/auth/verify",
        std::env::var("APP_URL").unwrap_or_else(|_| "http://localhost:8765".into()),
    );
    // `resend` performs the lookup and normalizes an unknown address to `Ok(())`.
    EmailVerification::resend(email, &base).await?;

    Ok(HttpResponse::text(
        "If this email is on file, a verification link has been sent.",
    ))
}
```

`send_link` and `resend` both build the URL as
`{base_url}?token={plaintext_token}`. A trailing slash on `base_url` is
trimmed before the query string is appended, so
`https://app.example.com/verify/` and `https://app.example.com/verify`
both produce a clean URL.

The click-through handler must run behind `AuthMiddleware`. It pulls the token
from the query string and calls `verify`:

```rust
async fn verify_inner(req: Request) -> Result<HttpResponse, FrameworkError> {
    let raw = req.query().unwrap_or("");
    let params: HashMap<String, String> =
        url::form_urlencoded::parse(raw.as_bytes()).into_owned().collect();
    let token = params
        .get("token")
        .ok_or_else(|| FrameworkError::bad_request("missing token"))?;

    let _user_id = EmailVerification::verify(token).await?;
    Ok(HttpResponse::new().status(302).header("Location", "/"))
}
```

`verify` checks the route's user against the token owner before consumption.
The route's user is the user of the guard the last `AuthMiddleware` checked,
or of the default guard, and `verify` reads and stamps it through that guard's
provider; behind `AuthMiddleware::for_guard("admin")` it is the admin user,
never the default guard's user in the same session. A live token belonging to
another account returns `403` with the message `This action is unauthorized.`
and remains unused. An unknown, expired or used token returns `400` with the
message `invalid or expired verification token`. On success, the provider
marks the authenticated owner verified and the facade fires `EmailVerified`.

A link proves the mailbox it was sent to, and no other. The token carries a
digest of that address, and `verify` compares it with the account's current
verification address, which the provider's `verification_email` reports.
When the account changed its address after the link was sent, `verify`
returns `403` `This action is unauthorized.`, leaves the token unused, and
marks nothing verified. The provider stamps the verification through
`mark_email_verified_for`, which writes only while the address is still the
one the link was sent to, so a change that lands while `verify` runs is
refused too; the token is spent by then, and the user asks for a new link. A
link sent before an upgrade to this behavior carries no address and is
refused the same way, so the user asks for a new one.

`EloquentUserProvider` reports the `MustVerifyEmail` address, and rereads it
under a row lock in the same transaction as the stamp. A custom provider
reports the email of `flow_user_by_id` unless it implements
`verification_email`.

A custom provider that does not implement `mark_email_verified_for` leaves a
window. The default reads the address with `verification_email`, compares it,
and then calls `mark_email_verified`: two separate storage operations. An
address change that commits between them is marked verified without proof of
the new mailbox. To close the window, implement `mark_email_verified_for`
itself, not `mark_email_verified`, so that the check and the write are one
storage operation: a conditional write such as
`UPDATE users SET email_verified_at = ? WHERE id = ? AND email = ?` that
reports whether it matched a row, or a reread under a row lock
(`SELECT ... FOR UPDATE`) in the same transaction as the write. It returns
`Ok(false)`, and writes nothing, when the address is no longer the one it was
given.

### Verified-only routes: `EnsureEmailVerifiedMiddleware`

`EnsureEmailVerifiedMiddleware` gates routes on the authenticated
user's `email_verified_at`. Compose it after `AuthMiddleware` and the
chain blocks any request whose user has not yet completed the verify
step.

The user it checks is the user of the route's guard: the guard the last
`AuthMiddleware` to pass the request on checked, or the default guard when
none names one. It asks that guard's provider. Behind
`AuthMiddleware::new().for_guard("admin")`, the gate checks the admin user
through the `admin` guard's provider, and a verified default-guard user
signed in on the same session does not pass it.

The middleware decides each answer from the request:

- A request that expects JSON (`Request::expects_json`) gets `403` with
  `{"message": "Your email address is not verified."}`, even when the
  middleware names a redirect.
- Any other request gets the redirect the middleware names: `302`, or `409`
  with `X-Inertia-Location` for an Inertia visit. The redirect goes through
  `Redirect::guest`, so the intended URL is stored by its rule: a `GET` stores
  its own path and query, any other request stores the page the user was on.
  After verification, `Redirect::intended` sends the user back.
- With no redirect named, as with `new()`, every caller gets the `403`.

Name the redirect by path with `redirect_to(path)` or by route with
`redirect_to_route(name)`. The route name is resolved on each request through
`routing::try_route`, so the redirect follows the route's path and public
root. A name no route carries fails the request with a `500` whose error names
the route, and so does a route whose path needs parameters.

```rust
use suprnova::{AuthMiddleware, EnsureEmailVerifiedMiddleware, group, get};

// API surface - 403 with a JSON body.
group!("/api")
    .middleware(AuthMiddleware::new())
    .middleware(EnsureEmailVerifiedMiddleware::new())
    .routes([
        get!("/me", profile::show),
    ]);

// Web surface - 302 to the route's path (or 409 + X-Inertia-Location for
// Inertia visits), 403 JSON for a request that expects JSON.
group!("/dashboard")
    .middleware(AuthMiddleware::redirect_to("/login"))
    .middleware(EnsureEmailVerifiedMiddleware::redirect_to_route("verification.notice"))
    .routes([
        get!("/", dashboard::index),
    ]);
```

If no user is authenticated, the middleware falls into the same response
branch as "authed but not verified" - matching Laravel's
`! $request->user() || ! hasVerifiedEmail()` shape. Compose
`AuthMiddleware` first when you want a separate `401` for unauthed
requests.

For in-handler branching (e.g. conditionally rendering a "please
verify" CTA without redirecting), load the typed user through the
session guard and read the trait method:

```rust
use suprnova::{Auth, MustVerifyEmail};
use crate::models::users::User;

if let Some(user) = Auth::user_as::<User>().await? {
    let verified: bool = user.is_email_verified();
    // branch on it
}
```

### Email verification through Magnetar

`EmailVerification` keeps its tokens in `auth_flow_tokens` and finds the user
through the configured provider. An application whose users live in
Magnetar's tables, as the API kit's do, verifies through the installed
Magnetar engine instead, with `Auth::email_verification()`:

```rust
use suprnova::{Auth, EmailVerificationIssue, EmailVerificationOutcome};

// On the signed-in user's request for a link:
if let EmailVerificationIssue::Issued(link) = Auth::email_verification().issue().await? {
    // Mail a link that carries link.token to link.email.
}

// On the page the link opens, for the user signed in there:
match Auth::email_verification().verify(&token).await? {
    EmailVerificationOutcome::Verified | EmailVerificationOutcome::AlreadyVerified => {
        // The address is verified.
    }
    EmailVerificationOutcome::SignIn => {
        // Send the guest to sign in and back to this page.
    }
    _ => {
        // Another account's link, a changed address, an expired or unknown
        // link: ask for a new one.
    }
}
```

| Method | Does |
|---|---|
| `issue()` | Mints a single-use token for the signed-in user, by bearer token or session, and answers `Issued(link)` with the `email` to mail and the `token` the link carries. It answers `AlreadyVerified` when there is nothing to verify, and `SignIn` for a guest. |
| `issue_for(&user)` | The same for an account the request just registered, which nobody has signed in to yet. |
| `verify(token)` | Verifies the signed-in user's address when the token is theirs, unused, unexpired and mailed to the address the account holds now. |

`verify` needs the account's own user signed in, because anyone can register
another person's address with a password of their own. A link that verified
whoever opened it would let that person's click verify the account the
registrant holds, and a verified address is what agent auth binds an agent's
claim to. So `verify` answers:

- `Verified`, or `AlreadyVerified` when the address was verified before; the
  token is spent either way.
- `SignIn` for a guest, and the token stays unused, so the page can send the
  guest to sign in and back.
- `OtherAccount` for another account's token, which stays unused for its
  owner.
- `AddressChanged` when the link was mailed to an address the account no
  longer holds. Nothing is stamped; the user asks for a new link.
- `Expired` or `Unknown` for a token past its 24 hours, already used, or
  never issued.

A link works once, and verifying with one spends the account's other links.
Verifying changes no credential and starts no session. `issue` and
`issue_for` count against the address's email verification budget, three
links an hour, and answer `429` past it. The token keeps the SHA-256 of the
address in `auth_tokens.address_digest`, never the address. A custom Magnetar
engine or store implements `email_verification_issue`,
`email_verification_verify`, `TokenStore::issue_bound`, `TokenStore::inspect`
and `UserStore::mark_email_verified_for`, or both calls fail closed.

### Why Suprnova diverges

Laravel's `EnsureEmailIsVerified` redirects to the `verification.notice` route
when no route is named. `EnsureEmailVerifiedMiddleware::new()` names no
redirect and answers `403` to every caller: the framework registers no
verification page, and a route name nobody registered would fail every
request. An application made with `suprnova new` names its page
`verification.notice`, so `redirect_to_route("verification.notice")` gives
Laravel's behavior there.

Laravel's verification link is a signed URL that carries the user's ID and a
hash of the address. Suprnova's link carries a single-use token stored in
`auth_flow_tokens` and bound to the address. A used link cannot be replayed,
which a signed URL allows until it expires. `verify` answers the checks a
signed URL makes in Laravel's `EmailVerificationRequest`, another account's
link and a changed address, with the same `403`.

## Password Reset

`PasswordReset` has four operations:

| Method | Signature | Notes |
|---|---|---|
| `send_link` | `send_link(email: &str, base_url: &str) -> Result<()>` | Uses Magnetar when installed; otherwise issues a framework token only for a verified user from an explicitly reset-capable provider and sends the link through the provider's `send_password_reset_notification`. Unknown and unverified addresses return `Ok(())`. Every answer is held for `PASSWORD_RESET_TIMEBOX_MS`. |
| `check` | `check(token: &str) -> Result<bool>` | Non-consuming validation through Magnetar or the framework token store used by the provider fallback. |
| `complete` | `complete(token: &str, new_password: &str) -> Result<String>` | Runs Magnetar's atomic first-proof transaction when installed; otherwise rotates a verified provider user, revokes framework session/remember state, and queues a retry of a revocation that failed. |
| `complete_with_outcome` | `complete_with_outcome(token, new_password) -> Result<PasswordResetOutcome>` | Returns committed Magnetar counts or the provider fallback's explicit framework revocation outcomes, and says whether a retry was queued. |

```rust
use suprnova::auth_flows::PasswordReset;

// From the "forgot password" form. An unknown address returns `Ok(())`
// after prerequisite checks succeed; configuration and backend errors still surface.
PasswordReset::send_link(&email, "https://app.example.com/reset").await?;

// Optional landing-page check before rendering the new-password form.
let valid: bool = PasswordReset::check(&token).await?;

// The click-through handler, after the user submits a new password:
// consume the token, rotate the password, and revoke the user's other
// sessions and remember-me tokens. Report success only when both
// revocations succeeded: a stolen session still works until they do.
let outcome = PasswordReset::complete_with_outcome(&token, &new_password).await?;
outcome.sessions_revoked?;
outcome.remember_tokens_revoked?;
let user_id: String = outcome.user_id;
```

`complete` returns the user id alone and discards the two revocation
outcomes, so a handler that calls it reports success while a stolen session
may still work; prefer `complete_with_outcome`. Both queue the retry of a
failed revocation, as [When a revocation fails](#when-a-revocation-fails)
describes. Both pass the plaintext
password through `SecretString`; Magnetar hashes it inside the credential
engine. Do not pre-hash it. An empty or whitespace-only
password returns HTTP 400 before the engine is called.

### Sending your own reset message

On the provider path, `send_link` mints the token, builds the link, and passes
it to `UserProvider::send_password_reset_notification(id, reset_link)`.
`EloquentUserProvider` loads the model and calls its
`CanResetPassword::send_password_reset_notification`. The default sends the
framework's `PasswordResetMail` to `email_for_reset()`, which stays the address
your model chooses for reset mail. The default mail greets the reader without a
name, because `CanResetPassword` has none to read.

Override the method to send your own message; the framework then sends nothing
itself, and `complete` accepts the link you receive:

```rust
use suprnova::{CanResetPassword, FrameworkError, Mail};

impl CanResetPassword for User {
    fn email_for_reset(&self) -> &str {
        &self.email
    }

    fn set_password_hash(&mut self, hash: &str) {
        self.password = hash.to_string();
    }

    async fn send_password_reset_notification(
        &self,
        reset_link: &str,
    ) -> Result<(), FrameworkError> {
        Mail::raw(format!("Choose a new password: {reset_link}"), |mail| {
            mail.to(self.email.as_str()).subject("Your password reset link")
        })
        .await
    }
}
```

A custom reset-capable provider keeps the provider default, which sends the
framework's mail to the address `flow_user_by_id(id)` returns and greets its
name, or overrides `send_password_reset_notification`. The default returns an
error when `flow_user_by_id` finds no user. The Magnetar path holds an address,
not a model. It always sends the framework's mail, greeting the name Magnetar
holds for the account, and never calls `send_password_reset_notification`.

### Bounded anti-enumeration behavior

`PasswordReset::send_link` returns `Ok(())` for an unknown address only after
the abuse-limiter, mail configuration, engine, and storage checks succeed.
Configuration, limiter, storage, and mail failures still return `Err`. The
dogfood controller gives successful known- and unknown-account requests the
same HTTP status and body.

`send_link` also holds every answer until `PASSWORD_RESET_TIMEBOX_MS`
milliseconds have passed since the call began, `200` by default as Laravel's
`auth.timebox_duration` is: a known address and an unknown one, the abuse
refusal and every error. An unknown address therefore answers no sooner than
a known one, unless the work for the known one takes longer than the timebox.
Raise the value if your mail transport is slower than that:

```bash
PASSWORD_RESET_TIMEBOX_MS=500
```

### Why Suprnova diverges

Laravel's broker answers an unknown address with the `INVALID_USER` status.
`send_link` answers `Ok(())` for it, as for a sent link, so a handler cannot
show a different message by mistake. `email_for_reset` has no default, unlike
Laravel's `getEmailForPasswordReset`, because the trait has no address field
to fall back to.

### `complete` side effects

Magnetar commits password reset in one transaction:

1. Consume the single-use reset token.
2. Apply first-email-proof policy when the account is still unverified.
3. Hash and replace the password.
4. Advance the authentication epoch.
5. Revoke old opaque sessions and remember credentials.
6. Remove provisional credentials when this reset is the account's first
   mailbox proof.

After commit, the framework sends `PasswordChangedMail` and dispatches
`PasswordResetCompleted`. Mail or listener failure cannot roll back the reset.

On an already verified account, reset preserves legitimate passkeys, linked
accounts, and confirmed two-factor enrollment. On an unverified squatted
account, first proof removes provisional credentials so the prior registrant
cannot retain access.

### When a revocation fails

On the provider path, the reset writes the password before it revokes the
user's other sessions and remember-me tokens, and the reset token is spent by
then. A revocation that fails can't undo either step, so the reset reports the
failure and makes the revocation durable instead:

- `complete_with_outcome` returns the store's error in `sessions_revoked` or
  `remember_tokens_revoked`. Your handler answers an error, never the success
  page. The controller that `suprnova new` writes returns that error. The
  dogfood application answers `500` and logs the failure at error level with
  the user's id.
- Before it returns, the reset pushes a `RevokeUserCredentials` job for the
  user with `Queue::push`. `complete` pushes it too. The outcome's
  `revocation_retry` field is then `RevocationRetry::Queued`.
  `RevocationRetry::NotNeeded` means both revocations succeeded.
- When the push fails too, nothing would retry the revocations, so
  `complete_with_outcome` and `complete` return an error instead of the
  outcome. The error says that the user's password changed, names each
  revocation that failed with the store's error, gives the push's error, and
  asks for `RevokeUserCredentials::new("<id>")` to be queued once the queue
  works. The framework logs it at error level with the user's id, and sends
  no `PasswordChangedMail` and no `PasswordResetCompleted` for that reset.
  Your handler's `?` answers it as a `500`.
- A worker running `queue:work` runs the job. Each run revokes both the
  sessions and the remember-me tokens, fails while either store refuses, and
  succeeds once both confirm. A run after the credentials are gone revokes
  nothing and succeeds, so running the job again is always safe. It revokes
  every session and remember-me token of the user, those opened after the
  reset too, so a retry that succeeds later signs the user out once more;
  the error answer already told them to sign in again on every device.
- Until the job succeeds, the stale credentials still don't work. Each sign-in
  records the user's authentication epoch, which a password change moves. On
  every request, the framework compares the recorded epoch with the current
  one, so a session or remember-me cookie from before the reset is signed out
  and answered as a guest. A user whose provider exposes neither an epoch nor
  a password hash records no epoch, so for that user the job is the only
  remedy.

With Magnetar installed, the revocations commit in the reset's own
transaction, so there is nothing to retry and `revocation_retry` is
`RevocationRetry::NotNeeded`.

The job retries until both stores confirm, with no bound on the number of
tries: it declares zero tries, which the queue reads as unlimited. The first
retry waits about 10 seconds and each later one twice as long, up to one hour
between tries, for as long as a store refuses. Each try has a 60-second
timeout, and a try that times out is retried too. The job reaches
`failed_jobs` only when the worker's `--tries` bounds it, or when a try
returns an error that ends retries, as
[Errors that end retries](queues.md#errors-that-end-retries) describes.
`queue:retry` then runs it again. The framework registers the job with the
worker, so it needs no `register_job` call.

The retry is only as durable as the queue that holds it:

- The `database` and `redis` drivers keep the job until a worker runs it.
- The `memory` driver keeps it in the web process, so a restart loses it.
- The `null` driver discards it, so nothing retries.
- The `sync` driver runs the job inside the push. When both stores confirm
  on that run, the revocations are done. When a store still refuses, the
  push fails and the reset returns the error described above.

A handler that reads the outcome logs the queued retry with the user's id. A
failed push never reaches it as an outcome; `?` returns that error:

```rust
use suprnova::FrameworkError;
use suprnova::auth_flows::PasswordReset;

// A retry that could not be queued is an `Err` here.
let outcome = PasswordReset::complete_with_outcome(&token, &new_password).await?;
if outcome.sessions_revoked.is_err() || outcome.remember_tokens_revoked.is_err() {
    // `outcome.revocation_retry` is `RevocationRetry::Queued`.
    tracing::warn!(user_id = %outcome.user_id, "queued a retry of the revocations");
    return Err(FrameworkError::internal(
        "Your password was changed, but signing you out of your other devices failed.",
    ));
}
```

After a failed push, queue the job yourself once the queue works again, for
example from an operator command, with the id the error names:

```rust
use suprnova::Queue;
use suprnova::auth_flows::RevokeUserCredentials;

Queue::push(RevokeUserCredentials::new(user_id)).await?;
```

Queue the same job after any other credential change whose revocation failed.

## Brute-Force Protection

The brute-force layer has two parts: the `BruteForce` facade that
records and queries lockout state, and the `LoginThrottleMiddleware`
that short-circuits at the HTTP layer before the handler is invoked.

### The `BruteForce` facade

Call `record_failed_attempt` from the failed-auth branch of your login
handler, and `reset_attempts` from the success branch:

```rust
use suprnova::auth_flows::BruteForce;

// In the failed-auth path:
let status = BruteForce::record_failed_attempt(&email, Some(&peer_ip)).await?;
if status.is_locked {
    // Optionally surface a custom response. The middleware will do
    // this for you on the *next* request - see below.
}

// In the success path:
BruteForce::reset_attempts(&email).await?;
```

`record_failed_attempt` returns the updated `LockoutStatus`
(`is_locked`, `failed_attempts`, and `locked_until` when locked). Pass
the optional `ip` for audit logs; pass `None` if your transport doesn't
surface a client IP cleanly.

Two additional operations:

```rust
// Read-only - safe on emails with no history.
let status = BruteForce::get_lockout_status(&email).await?;
let locked: bool = BruteForce::is_locked(&email).await?;

// Admin / forced unlock. Fires `AccountUnlocked` only on a real state
// transition (no-op unlock on an already-unlocked account does not fire).
let was_locked: bool = BruteForce::unlock_account(&email).await?;
```

`unlock_account` returns `true` when the account had been locked at the
time of the call, `false` otherwise. The `AccountUnlocked` event fires
only on `true` - a `false` return is the no-op it is, not an audit
event.

### `LoginThrottleMiddleware`

The middleware reads the lockout state for whichever email a request is
targeting and short-circuits with `429 Too Many Requests` when the
account is locked. The login handler is never invoked, so a locked
account does not even get to attempt a credentials check:

```rust
use suprnova::auth_flows::LoginThrottleMiddleware;
use suprnova::Router;

// The email extractor is a sync closure over `&Request`. Reading
// JSON/form body is async and consumes `Request`, so the closure
// cannot read the body - pull from a header, query string, or
// route param instead.
let throttle = LoginThrottleMiddleware::new(|req| {
    req.header("X-Login-Email").map(str::to_string)
});

let router = Router::new()
    .post("/login", login_handler)
    .middleware(throttle);
```

Practical extraction surfaces:

- A header (`X-Login-Email`), set by a preceding pre-processor - the
  pattern used in the dogfood app.
- A query string parameter (`?email=…`).
- A route parameter (`/login/{email}`).

Returning `None` from the extractor is the explicit "I have nothing to
check" signal - the middleware passes the request through unchanged.
This makes the middleware safe to install on routes that occasionally
see anonymous traffic (e.g. the same `POST /login` endpoint that also
handles a no-email "request password reset" sub-action).

On lock the middleware returns:

- Status `429 Too Many Requests`.
- `Retry-After` header - seconds, computed from the lockout's
  `locked_until` via `LockoutStatus::retry_after_seconds`. Falls back
  to `900` (15 minutes, Magnetar's default lockout period) if the
  timestamp is somehow absent.
- Body: `"Account locked due to too many failed login attempts. Try
  again later."`

### Backend errors (fail closed by default)

If `get_lockout_status` returns an error, `LoginThrottleMiddleware` logs the
failure and, by default, returns HTTP `503 Service Unavailable` with
`Retry-After: 1` without invoking the login handler. To keep login available
during a lockout-backend outage, opt in explicitly with
`.on_backend_error(BackendErrorPolicy::FailOpen)`; only that policy passes the
request to the handler.

### Layering with `RateLimitMiddleware`

`LoginThrottleMiddleware` is per-account - it gates a single email
when the threshold is crossed. For per-IP quotas, layer it with
[`RateLimitMiddleware::ip_based`](rate-limiting.md#per-address-limit-with-ip_based).
It counts requests for each client address, using the rate limiter your
application installed. The two compose naturally:

```rust
use std::time::Duration;
use suprnova::auth_flows::LoginThrottleMiddleware;
use suprnova::rate_limit::RateLimitMiddleware;
use suprnova::Router;

let router = Router::new()
    .post("/login", login_handler)
    .middleware(LoginThrottleMiddleware::new(|req| { /* ... */ }))
    .middleware(RateLimitMiddleware::ip_based(20, Duration::from_secs(60)));
```

Together they cover the realistic shapes of credential stuffing:
distributed (one email × many IPs) is the rate limit's job; focused
(many attempts × one email) is the throttle middleware's job.

### Configuration

`MagnetarConfig` accepts a `LockoutConfig`. The default is five failed attempts,
a 15-minute counting and lockout period, seven-day attempt retention, and
`BackendErrorPolicy::FailClosed`:

```rust,ignore
let config = MagnetarConfig::from_sea_orm(database)
    .lockout_config(lockout_policy);
```

Use `LockoutConfig::disabled()` only when another fail-closed identity control
replaces account lockout.

## Two-Factor (TOTP)

`TwoFactor` covers TOTP-based 2FA - the kind that pairs with any
standards-compliant authenticator app (Google Authenticator, 1Password,
Bitwarden, Authy). The flow is enrollment → confirmation → ongoing
verification, plus single-use recovery codes for when the user loses
their device, plus the challenge flow that stitches everything into the
login lifecycle.

### The `TwoFactorUser` trait

The framework cannot reach into your application's user storage, so
callers implement a small trait to bridge from their user model to the
2FA facade:

```rust
use suprnova::auth_flows::TwoFactorUser;

pub trait TwoFactorUser: Send + Sync {
    fn user_id(&self) -> &str;
    fn email(&self) -> &str;
}
```

`user_id` is an opaque storage key. It can be a numeric application ID rendered
as text, a UUID, or a Magnetar `UserId`. The framework TOTP table has no foreign
key to the application user table.

`email` is folded into the `otpauth://` URL's `account_name` segment so the
authenticator app displays a recognizable account label.

```rust
use suprnova::auth_flows::TwoFactorUser;

struct AppUser2fa<'a> {
    user: &'a User,
}

impl TwoFactorUser for AppUser2fa<'_> {
    fn user_id(&self) -> &str {
        &self.user.auth_id
    }

    fn email(&self) -> &str {
        &self.user.email
    }
}
```

### Storage

2FA state lives in the framework-owned `two_factor_credentials` table.
Secrets and recovery codes are encrypted at rest with
`crate::crypto::Crypt::encrypt_string`, which requires a process-global
`EncryptionKey`. Apps opt into the schema by listing the four migrations
in their `Migrator::migrations()` - see [Bootstrapping](#bootstrapping).
The table is keyed by `user_id`, a `TEXT` column on PostgreSQL and SQLite.
MySQL and MariaDB can't index a `TEXT` key, so there the column is
`VARCHAR(255)`. The attempt and rotation tables key the user id in 255
characters on every engine, so `enroll` refuses a longer id with `422` on
every engine.

### Enroll, confirm, verify

```rust
use suprnova::auth_flows::{TwoFactor, EnrollmentResponse};

// 1. Enrollment: generate a fresh secret + 10 recovery codes, persist
//    them encrypted, return everything needed to render the QR code.
let response: EnrollmentResponse = TwoFactor::enroll(&user_2fa).await?;
// response.otpauth_url - `otpauth://totp/...` deep link
// response.qr_code_svg - <svg> wrapping a base64 PNG, embed inline
// response.recovery_codes - Vec<String>, 10 plaintext codes - show ONCE

// 2. Confirm: the user opens the authenticator app and types in the
//    6-digit code. `confirm` validates it and stamps `confirmed_at`.
TwoFactor::confirm(&user_2fa, &user_typed_code).await?;
// fires `TwoFactorEnrolled`

// 3. On subsequent logins, gate the session on `verify`:
let ok: bool = TwoFactor::verify(&user_2fa, &code_from_login_form).await?;
if !ok {
    return Err(suprnova::FrameworkError::domain("invalid 2FA code", 401));
}
```

Every method that checks a code or a recovery code - `verify`,
`consume_recovery_code`, `confirm`, `re_enroll`,
`regenerate_recovery_codes` and `complete_challenge` - reserves one
attempt in the second-factor counter before it reads the code. A wrong
code turns the reservation into a failure. Five failures inside fifteen
minutes (both configurable, see below) lock the second factor: every one
of those methods then returns
`429 Too Many Requests` without evaluating the code, so the right code
cannot open a locked account either. A correct code clears the failures,
and parallel guesses cannot all pass one status read. When the counter
cannot record an attempt, the methods answer `503` rather than evaluate
the code unthrottled.

The counter is the framework's `two_factor_attempts` table, keyed by the
user id. It is separate from the per-email password lockout that
`BruteForce` and `LoginThrottleMiddleware` use: a successful password
check does not clear second-factor failures, and the lock works with no
Magnetar engine installed. `complete_challenge` is the exception that needs
the engine: it resolves the pending user, and returns it, through Magnetar. A wrong code fires `AccountLocked` once, on
the failure that sets the lock. `TwoFactor::unlock(&user)` clears the
counter early and fires `AccountUnlocked` when a lock was in effect.

Two settings shape the lock:

| Var | Default | Meaning |
|---|---|---|
| `TWO_FACTOR_MAX_ATTEMPTS` | `5` | Failures inside the window that lock the second factor. |
| `TWO_FACTOR_LOCKOUT_MINUTES` | `15` | How long each attempt counts. The window slides: a failure stops counting this long after it happened, so a lock lifts once the oldest failure still counted is this old. |

Both must be whole numbers of at least 1, and the window at most 43200
minutes (thirty days): a longer window reaches back past the timestamp
range MySQL and MariaDB store. `Config::init` checks them at boot, so a
zero, malformed or too-long value stops the app with the variable named.
To set them in code instead, bind a `TwoFactorLockout`, which wins over the
environment:

```rust
use suprnova::App;
use suprnova::auth_flows::TwoFactorLockout;

App::singleton(TwoFactorLockout::new(3, 30)?);
```

`enroll` returns plaintext recovery codes **exactly once**. There is
no API to retrieve them later - the encrypted column is one-way from
this point on. Show them on the enrollment success page, encourage the
user to save them, and don't store the plaintext anywhere else.

`enroll` refuses to overwrite a **confirmed** enrollment - it returns a
`409` to push the caller toward `re_enroll`, which requires proof of
possession. Re-enrolling on an unconfirmed (pending) row is allowed:
the prior enrollment never became authoritative.

Both writes are conditional on what was read, so concurrent requests on
one account cannot cross. `confirm` stamps only the enrollment whose
secret the code was checked against: if a second `enroll` replaced the
secret in between, `confirm` returns `409` and the new secret stays
unconfirmed. A confirmation stamps an enrollment once: a second
confirmation racing it gets `409` and fires no second `TwoFactorEnrolled`.
It also uses its code up the way a successful `verify` does, so the code
that confirmed the enrollment is refused at the next sign-in; the user
signs in with a later code.
`enroll` checks that the row is still unconfirmed in the statement that
writes it, so a confirmation that lands while it runs also gets the `409`.

### One second factor per account

With Magnetar installed, an account holds the framework's TOTP or a Magnetar
second factor, never both. Each refuses the sign-ins that don't verify it: the
framework's logins refuse an account with a Magnetar factor, and Magnetar's own
sign-ins refuse an account with the framework's TOTP. An account with both
could sign in by no path, so neither system lets the second one in.

- `TwoFactor::enroll` and `TwoFactor::confirm` return `409` while the account
  has a Magnetar factor, confirmed or waiting for its confirmation. `confirm`
  checks before it reads the code, so of two enrollments racing each other the
  second to confirm loses.
- Magnetar's `TwoFactorService` returns a conflict on
  `magnetar::two_factor::OTHER_SECOND_FACTOR` from `enroll` and `confirm` while
  the account has the framework's TOTP, confirmed or pending. `init_magnetar`
  gives its service that check; a host that builds its own service passes
  `suprnova::magnetar_integration::engine::FrameworkTotpEnrollment` to
  `TwoFactorService::with_other_second_factor`.
- Two enrollments can race, one in each system, each checking before the
  other writes. So each `enroll` asks again once its own enrollment is
  stored, and withdraws it with the same `409` or conflict when the other
  factor is there. Of two enrollments that both stored one, at least one
  sees the other and withdraws, so the account keeps one, and at worst both
  answer `409` and the user enrolls again. A Magnetar `TwoFactorStore`
  withdraws through `withdraw_enrollment`; the default implementation
  removes nothing, so a host's own store implements it to take part.

An account can still hold both if it enrolled before these checks, or if a
migration imported a Magnetar factor for an account that has the framework's
TOTP. Every sign-in path refuses it with `409` until one factor is disabled,
and disabling either one is the recovery. The user can't sign in to do it, so
it's an administrator's action:

```rust
// Disable the framework TOTP. Auth::password() and Magnetar's other
// sign-ins then ask for the Magnetar factor.
TwoFactor::disable(&user_2fa).await?;
```

A host that holds its `TwoFactorService` can disable the Magnetar factor
instead. The account then signs in through the application's login and
`TwoFactor::complete_challenge`.

### Replay protection

`verify` writes the current TOTP timestep to `last_used_timestep` on
success. Subsequent verifies where `current_timestep <=
last_used_timestep` are rejected even when the code itself is
structurally valid, defeating a stolen-code replay inside the 30-second
window.

The timestep claim is atomic. The stamp lands via a conditional
`UPDATE … WHERE last_used_timestep IS NULL OR last_used_timestep <
:current`, and the verify only succeeds when the statement affects
exactly one row. Two concurrent verifies cannot both win, even when
they straddle a 30-second boundary: the first flips the column, the
second's predicate no longer matches, and the second is treated as a
replay. A plain
read-modify-write would be a TOCTOU race - both verifies read the
pre-stamp row, both validate the same code, both stamp, both succeed.
Concurrent racers are also counted as failed attempts so the
second-factor counter records them.

### Recovery codes

```rust
let consumed: bool = TwoFactor::consume_recovery_code(&user_2fa, &code).await?;
```

Single-use: a matching code is removed from the row before the call
returns, so a second attempt against the same code returns `false`.
Codes are 12 decimal digits in `NNNNNN-NNNNNN` shape (~40 bits of
entropy each, matching Laravel Fortify's format).

`consume_recovery_code` only accepts codes when 2FA is fully confirmed -
it short-circuits to `Ok(false)` while `confirmed_at` is NULL.
Without this gate, an attacker who triggered enrollment on a victim
account (or any flow that creates the row without confirming) could
authenticate using only a fresh recovery code, bypassing TOTP entirely.
The contract is symmetric with `verify`'s "confirmed enrollment only"
guard.

### Rotating recovery codes and secrets

When a user exhausts their recovery codes, or wants to rotate them
after a suspected compromise:

```rust
let fresh: Vec<String> = TwoFactor::regenerate_recovery_codes(&user_2fa, &proof).await?;
```

`proof` must validate as either a current TOTP code or an unused
recovery code. Without the proof check, a session-hijacked attacker
could silently blow away the legitimate user's recovery codes
(denial-of-service against account recovery). The fresh codes replace
the persisted set; the existing secret and `confirmed_at` are
preserved, so the user's authenticator app keeps working without
re-pairing. Errors:

- `400` - no confirmed enrollment exists; call `enroll`/`confirm` first.
- `401` - `proof` validates as neither a TOTP code nor an unused
  recovery code.
- `429` - wrong codes have locked the second factor.

To rotate the **secret** (re-pair to a new device) without disabling
2FA first:

```rust
let response = TwoFactor::re_enroll(&user_2fa, &proof).await?;
```

Same proof model as `regenerate_recovery_codes`. A fresh secret + 10
fresh recovery codes wait as a pending rotation in `two_factor_rotations`
until the user calls `confirm` with a code from the new authenticator.
Until then the confirmed secret and its recovery codes keep gating
sign-in, so a rotation nobody finishes never turns 2FA off, and `enroll`,
which takes no proof, can't replace the pending secret. Confirming the
rotation swaps in the new secret and recovery codes in one transaction.

### Disable

```rust
TwoFactor::disable(&user_2fa).await?;
// fires `TwoFactorDisabled` only if a row was removed
```

Idempotent: a disable on a user who never enrolled is not an error.
The `TwoFactorDisabled` event fires only on a real state transition,
so audit listeners see one entry per actual disable rather than one
per click on a no-op button.

### Challenge flow (gating login on the second factor)

The enroll / confirm / verify primitives are the building blocks; the
**challenge flow** stitches them into the login lifecycle so a user
with 2FA enabled cannot reach protected pages on password alone.

The flow:

1. Password login resolves a user.
2. If `TwoFactor::is_enabled_by_id(&user_id)` returns `true`, the login
   handler calls `TwoFactor::start_challenge(user_id, remember)` -
   that stashes the user-id as **pending** in the session, clears the
   fully-authenticated slot, revokes any remember-me cookie issued by
   `Auth::attempt`, and remembers whether the user opted into
   remember-me so the cookie can be re-issued after the challenge
   completes. `Auth::id()` returns `None` from this point until the
   challenge completes.
3. The handler redirects to a `/two-factor-challenge` route that shows
   the code form.
4. The challenge POST handler calls
   `TwoFactor::complete_challenge(code)` - verifies the code (TOTP
   **or** an unused recovery code, matching Fortify's challenge
   controller), promotes pending → authed, rotates the session id
   (defeating session fixation) and the CSRF token, re-issues the
   remember-me cookie when the user opted in, and dispatches the
   standard `auth::Login` + `auth::Authenticated` lifecycle events
   plus the 2FA-specific `TwoFactorChallenged`.

```rust
use suprnova::auth_flows::TwoFactor;
use suprnova::{Auth, Authenticatable, Credentials, redirect};

pub async fn login(form: LoginRequest) -> Response {
    match Auth::attempt(&Credentials::password(&form.email, &form.password), form.remember).await? {
        Some(user) => {
            let user_id = user.get_auth_identifier();
            if TwoFactor::is_enabled_by_id(&user_id).await? {
                // Demote to "pending": auth slot cleared, pending set,
                // remember-me cookie revoked. Pass through the form's
                // remember flag so `complete_challenge` can re-issue
                // the cookie on success.
                TwoFactor::start_challenge(user_id, form.remember).await?;
                redirect!("/two-factor-challenge").into()
            } else {
                redirect!("/dashboard").into()
            }
        }
        None => Err(invalid_credentials().into()),
    }
}

pub async fn complete(form: TwoFactorChallengeRequest) -> Response {
    let _user = TwoFactor::complete_challenge(&form.code).await?;
    // Session id + CSRF have rotated; remember-me has been re-issued
    // if the original login form set it. Listeners that hook
    // `auth::Login` / `auth::Authenticated` saw a normal login.
    redirect!("/dashboard").into()
}
```

`complete_challenge` rotates the session id and CSRF token as part of
the promotion to authed. That closes the classic session-fixation
attack where an attacker plants a known session id on a victim before
they log in - after the rotation, the planted id is dead and only the
freshly-generated id carries the authenticated state. The contract
matches `Auth::login_id` / `Auth::login_using_id`, so 2FA logins are
indistinguishable from no-2FA logins in terms of session state and
listener observability. With the Magnetar engine installed, the promoted
login is backed by a Magnetar session like every other web login - see
[Framework logins under the engine](authentication.md#framework-logins-under-the-engine).

Gate every protected route group with `TwoFactorChallengeMiddleware`
**before** `AuthMiddleware` so a pending session is bounced to the
challenge page rather than the login page:

```rust
use suprnova::{AuthMiddleware, TwoFactorChallengeMiddleware, group, get};

group!("/dashboard")
    .middleware(TwoFactorChallengeMiddleware::redirect_to("/two-factor-challenge"))
    .middleware(AuthMiddleware::redirect_to("/login"))
    .routes([
        get!("/", dashboard::index),
    ]);
```

The challenge page itself (the GET that renders the form, the POST
that calls `complete_challenge`) must NOT install
`TwoFactorChallengeMiddleware` - it is the destination. The POST
handler typically also checks `TwoFactor::pending_user_id().is_some()`
up front so a stale link does not reach the verify logic with an
empty session.

`TwoFactor::cancel_challenge()` clears both pending slots without
authenticating anyone - wire it to a "back to login" link on the
challenge page.

**Recovery code fallback.** `complete_challenge(code)` tries the TOTP
path first and falls back to consuming a recovery code, so a user who
lost their authenticator can still get in. Each recovery code is
single-use.

**Brute-force linkage.** Failed challenge codes feed the second-factor
counter, the same one bare `TwoFactor::verify` uses. An attacker
grinding the challenge form trips `AccountLocked` after the configured
number of failures (`TWO_FACTOR_MAX_ATTEMPTS`, default 5).
A single bad submission counts as **one** failed attempt even though
`complete_challenge` tries both the TOTP and recovery-code forms. Signing
in with the password again does not clear the count.

**Lockout gate.** `complete_challenge` reserves its attempt up front
and returns `429 Too Many Requests` if the account is already locked -
even when the submitted code is correct. Without this in-method gate an
attacker who tripped the lockout could still get in by submitting the
right code on the next request. Every other code-checking method applies
the same gate. `LoginThrottleMiddleware` guards the password path with
the separate password lockout; composing it in front of the challenge
POST route is fine.

**Failure event.** `complete_challenge` dispatches
`TwoFactorChallengeFailed { user_id }` on a bad code (or a locked
account), distinct from the password path's `auth::Failed`. Listeners
watching for "user tried 2FA and failed" subscribe to the new event;
listeners watching for "password didn't authenticate" stay on
`auth::Failed`. The two surfaces are kept separate so a 2FA mistype
does not look like a password failure to audit pipelines.

### Why Suprnova diverges

The framework TOTP `user_id` is a `String`. A fixed `i64`, UUID, or Magnetar
identifier type would tie the reusable facade to one application schema. The
string boundary lets an app choose any stable identifier at the cost of one
conversion at the call site.

Magnetar's integrated factor gate is separate from this retained facade. The
separation preserves compatibility for applications using
`two_factor_credentials`, but applications should not enroll the same account
through both stores.

## Password rehash on sign-in

A provider's `validate_credentials` answers whether the password matches and
writes nothing, as Laravel's `validateCredentials` does. `Auth::validate` and a
guard's `validate` therefore leave the stored hash as it is.

The rewrite of a stored hash runs in the sign-in instead, through
`UserProvider::rehash_password_if_required(user, credentials)`: after the
password validates and before the user is signed in, in the session guard's
`attempt` and `once`, and in `Auth::logout_other_devices` after its password
check. The default does nothing. `EloquentUserProvider` and
`DatabaseUserProvider` rewrite a `$2b$` or Argon2id hash as the `$2y$` hash
Laravel accepts while the shared-database setting is on (see
[Running on a Laravel Database](laravel-database.md)). A rewrite that cannot
be minted or stored fails the sign-in with that error and leaves the stored
hash as it was; the next sign-in tries again.

The session guard's `attempt` binds the sign-in to the password it verified:
it reads the user's credential epoch from the snapshot whose hash it checked,
and it refuses the sign-in when the stored epoch moved before the session was
issued, so a password reset that commits during a sign-in cancels that
sign-in. A rehash changes a hash-derived epoch, so `attempt` rehashes through
`UserProvider::rehash_password_for_sign_in(user, credentials, recorded_epoch)`
instead of the method above. An implementation checks that the stored epoch
and the old hash are still the ones it verified, writes the new hash in that
same atomic step, and returns the snapshot it wrote (never a fresh read, which
could carry a concurrent reset); it returns an error when the epoch moved,
which fails the sign-in. The default calls `rehash_password_if_required` only
for a user without a credential epoch and otherwise does nothing, because an
unconditional rewrite could undo a reset. A user with a password hash has an
epoch, so a custom provider that upgrades hashes on sign-in implements
`rehash_password_for_sign_in` for `attempt`; `once` and
`Auth::logout_other_devices` still call `rehash_password_if_required`.

A custom provider upgrades hashes on sign-in by implementing both methods. The
conditional store returns the record it wrote:

```rust
use std::sync::Arc;
use suprnova::serde_json::Value;
use suprnova::{Authenticatable, FrameworkError, UserProvider, async_trait, hashing};

pub struct LegacyUsers;

#[async_trait]
impl UserProvider for LegacyUsers {
    async fn retrieve_by_id(
        &self,
        id: &str,
    ) -> Result<Option<Arc<dyn Authenticatable>>, FrameworkError> {
        legacy::find(id).await
    }

    async fn rehash_password_if_required(
        &self,
        user: &dyn Authenticatable,
        credentials: &Value,
    ) -> Result<(), FrameworkError> {
        let password = credentials.get("password").and_then(|v| v.as_str());
        if let (Some(plaintext), Some(stored)) = (password, user.get_auth_password())
            && hashing::needs_rehash(stored)
        {
            let fresh = hashing::hash_async(plaintext).await?;
            legacy::store_hash(&user.get_auth_identifier(), &fresh).await?;
        }
        Ok(())
    }

    async fn rehash_password_for_sign_in(
        &self,
        user: &dyn Authenticatable,
        credentials: &Value,
        recorded_epoch: Option<u64>,
    ) -> Result<Option<Arc<dyn Authenticatable>>, FrameworkError> {
        let password = credentials.get("password").and_then(|v| v.as_str());
        let (Some(plaintext), Some(stored)) = (password, user.get_auth_password()) else {
            return Ok(None);
        };
        if !hashing::needs_rehash(stored) {
            return Ok(None);
        }
        let fresh = hashing::hash_async(plaintext).await?;
        // One statement replaces the hash only while the row still holds the
        // verified hash at the verified epoch, and returns the row it wrote.
        let written = legacy::replace_hash_if_unchanged(
            &user.get_auth_identifier(),
            stored,
            recorded_epoch,
            &fresh,
        )
        .await?
        .ok_or(FrameworkError::Unauthorized)?;
        Ok(Some(Arc::new(written)))
    }
}
```

### Why Suprnova diverges

Laravel rehashes on sign-in whenever its hasher reports that a hash needs it,
unless `hashing.rehash_on_login` is off. The built-in Suprnova providers
rewrite only while the shared-database setting is on, because their rewrite
exists to keep a hash a Laravel application on the same database can verify.
Outside that setting they leave the hash as it is; implement
`rehash_password_for_sign_in` (for `attempt`) and `rehash_password_if_required`
(for `once` and `logout_other_devices`) on your provider to upgrade hashes on
sign-in.

## Remember-me

`suprnova::auth_flows::remember_me` re-exports the legacy
`suprnova::auth::remember` module for compatibility.

When Magnetar is installed, ordinary `Auth::attempt(..., true)`,
`Auth::issue_remember_cookie`, and `SessionMiddleware` hydration use Magnetar's
purpose-bound remember credentials. Magnetar stores verifier digests, checks the
auth epoch, rotates credentials on successful use, revokes them with the user
session, and reports replay or malformed-credential anomalies without exposing
the secret.

The browser-facing cookie remains owned by the framework. It is encrypted with
the logical `remember_me` name, follows `SESSION_COOKIE_PREFIX`, and is cleared
before backend revocation so a storage failure cannot leave the browser sending
the old credential.

The legacy database-row implementation remains available when no Magnetar
engine is installed. New applications should initialize Magnetar and treat the
legacy re-export as a transition surface.

## Events

Nine events fire across the flows, one per security-state transition:

| Event | Fired by | Carries |
|---|---|---|
| `EmailVerified` | `EmailVerification::verify` on success, for an account that was not verified yet | `user_id: String` |
| `PasswordResetLinkSent` | `PasswordReset::send_link` on success - anti-enumeration silent for absent emails | `user_id: String`, `email: String` |
| `PasswordResetCompleted` | `PasswordReset::complete` on success | `user_id: String` |
| `AccountLocked` | `BruteForce::record_failed_attempt` on the unlocked → locked transition | `email: String`, `failed_attempts: u32` |
| `AccountUnlocked` | `BruteForce::unlock_account` when an actual unlock occurred | `email: String` |
| `TwoFactorEnrolled` | `TwoFactor::confirm` on success | `user_id: String` |
| `TwoFactorChallenged` | `TwoFactor::complete_challenge` promoted pending → authed | `user_id: String` |
| `TwoFactorChallengeFailed` | `TwoFactor::complete_challenge` rejected a bad code or refused a locked account | `user_id: String` |
| `TwoFactorDisabled` | `TwoFactor::disable` when a row was actually removed | `user_id: String` |

Every event is `Debug + Clone + 'static`, carries no sensitive data
(no plaintext tokens, no IPs), and uses stringy identifiers so
listeners can serialize them across task boundaries without leaking
type information from the user-storage backend.

### Listening

Subscribe via the standard event API - same surface as every other
in-process event:

```rust
use std::sync::Arc;
use suprnova::async_trait;
use suprnova::auth_flows::events::AccountLocked;
use suprnova::{EventFacade, FrameworkError, Listener};

pub struct PageOpsOnLockout;

#[async_trait]
impl Listener<AccountLocked> for PageOpsOnLockout {
    async fn handle(&self, event: &AccountLocked) -> Result<(), FrameworkError> {
        tracing::warn!(
            email = %event.email,
            failed_attempts = event.failed_attempts,
            "account locked - paging ops",
        );
        // ... Slack notification, audit table append, etc.
        Ok(())
    }
}

// In bootstrap.rs:
EventFacade::listen::<AccountLocked, _>(Arc::new(PageOpsOnLockout)).await;
```

Listeners run on Tokio's runtime and are dispatched in registration
order. See the [Events](events.md) chapter for the full surface.

## Testing

Three fakes cover the auth-flows surface, and they compose.

### `Mail::fake()`

Installs a process-local capture transport. Every send during the
guard's lifetime lands in an in-memory buffer instead of going out:

```rust
use suprnova::mail::Mail;

#[tokio::test]
async fn send_link_dispatches_email() {
    let fake = Mail::fake();
    // ... drive the flow ...
    EmailVerification::send_link(&user, "https://app.example.com/verify")
        .await
        .unwrap();
    fake.assert_sent(|m| {
        m.to.iter().any(|a| a.email == "alice@example.com")
            && m.subject.contains("Verify")
    });
    fake.assert_sent_count(1);
}
```

`MailFake` exposes `assert_sent`, `assert_not_sent`,
`assert_sent_count`, plus the raw `captured()` and `count()`
accessors. When the guard drops, the previously-bound transport is
restored - tests that interleave fakes with explicit transport
binding do not leak state.

### `Notify::fake()`

The verification link goes out as a `VerifyEmailNotification`. Under
`Notify::fake()` it is recorded instead of sent, and the typed record gives
you the link:

```rust
use suprnova::auth_flows::{EmailVerification, VerifyEmailNotification};
use suprnova::notifications::Notify;

#[tokio::test]
async fn send_link_notifies_the_users_address() {
    let notify = Notify::fake();
    // ... drive the flow ...
    EmailVerification::send_link(&user, "https://app.example.com/verify")
        .await
        .unwrap();
    let sent = notify
        .sent::<VerifyEmailNotification>("alice@example.com", |_| true)
        .unwrap();
    let link = &sent[0].mail.verification_link;
    assert!(link.starts_with("https://app.example.com/verify?token="));
}
```

The notification's public payload, which the untyped records and the
`NotificationSending` listeners see, leaves the link out: the link carries a
single-use token.

### `EventFacade::fake()`

The same shape, but for events:

```rust
use suprnova::auth_flows::events::EmailVerified;
use suprnova::events::testing::assert_dispatched;
use suprnova::EventFacade;

#[tokio::test]
async fn verify_fires_email_verified_event() {
    let _guard = EventFacade::fake();
    // ... drive the flow ...
    EmailVerification::verify(&token).await.unwrap();
    assert_dispatched::<EmailVerified>(|e| !e.user_id.is_empty());
}
```

The fake records dispatched events without invoking listeners, so a
listener that talks to an external service will not fire during the
test. The companion `assert_not_dispatched::<E>(pred)` asserts the
negative; `dispatched_count::<E>(pred)` returns the raw count for
finer-grained assertions.

### Integration tests for email verification and password reset

Email-verification tests create `auth_flow_tokens`, register a `UserProvider`,
establish the authenticated token owner, set `MAIL_FROM`, and drive the facade
under `Mail::fake()`.

Password-reset tests install a `MagnetarPasswordAuthEngine` test adapter and
assert issue, non-consuming check, atomic completion, session revocation, and
single-use behavior.

Canonical source examples are:

- `framework/tests/auth_flows/email_verify.rs` for actor-bound verification and
  single-use tokens.
- `framework/tests/auth_flows/password_reset.rs` for Magnetar delegation and completion
  outcomes.
- `framework/tests/auth_flows/laravel_auth_gaps.rs` for the verification and reset
  hooks, the reset timebox, the verified gate's per-request answer, and the
  rehash on sign-in.
- `framework/tests/magnetar_integration/default_engine.rs` for real default-engine setup.
- `framework/tests/auth_flows/brute_force.rs` for lockout lifecycle.
- `framework/tests/auth_flows/two_factor_challenge_flow.rs` for the retained framework
  TOTP challenge flow.
- `framework/tests/magnetar_integration/remember_middleware.rs` for remember rotation and
  dual-session binding.

Process-global Magnetar installation is intentionally one-shot. Put tests that
need different engines in separate integration-test binaries, or install one
test adapter once for the whole binary.


## Reference

| Symbol | Purpose |
|---|---|
| `suprnova::auth_flows::EmailVerification` | `send_link`, `resend`, `check`, and actor-bound `verify`; `verify` returns the user ID. |
| `suprnova::auth_flows::EnsureEmailVerifiedMiddleware` | `new()` for 403 JSON to every caller; `redirect_to(path)` and `redirect_to_route(name)` for browser or Inertia redirects, with 403 JSON for a request that expects JSON. |
| `suprnova::auth_flows::VerifyEmailNotification` | The framework's verification notification, rendered from `EmailVerificationMail`. |
| `suprnova::auth_flows::PasswordReset` | Magnetar-first reset with a verified-account `UserProvider` fallback over framework `auth_flow_tokens`. |
| `suprnova::auth_flows::RevokeUserCredentials` | Queued job that revokes a user's sessions and remember-me tokens, retried until both stores confirm; a reset queues it when a revocation fails. |
| `suprnova::auth_flows::RevocationRetry` | Whether a reset queued that job: `NotNeeded` or `Queued`. A reset whose push failed returns an error instead. |
| `suprnova::MustVerifyEmail` | Application-user contract for the framework verification facade; `send_email_verification_notification` sends the link. |
| `suprnova::CanResetPassword` | Application-user contract for the provider reset path; `send_password_reset_notification` sends the link. |
| `suprnova::auth_flows::token_store::create_auth_flow_tokens_table` | SeaORM table definition for framework verification tokens. |
| `suprnova::auth_flows::BruteForce` | Magnetar-backed account lockout facade. |
| `suprnova::auth_flows::LoginThrottleMiddleware` | HTTP middleware that returns 429 before the login handler when the account is locked. |
| `suprnova::auth_flows::TwoFactor` | Retained framework TOTP enrollment, verification, recovery, and challenge facade. |
| `suprnova::auth_flows::TwoFactorUser` | Application-user bridge for the framework TOTP facade. |
| `suprnova::auth_flows::TwoFactorChallengeMiddleware` | Gate for sessions waiting on the framework TOTP challenge. |
| `suprnova::auth_flows::remember_me` | Compatibility re-export of the legacy framework remember module. |
| `suprnova::MagnetarConfig` / `suprnova::init_magnetar` | Default Magnetar engine configuration and one-shot installation. |
| `suprnova::auth_flows::events::*` | Authentication lifecycle events. |

## Next

- [Authentication](authentication.md) - guards, providers, the
  `Auth` facade, `AuthMiddleware`.
- [Mail](mail.md) - the transport layer the `send_link` calls
  dispatch through.
- [Notifications](notifications.md) - the channel the verification
  notification goes through.
- [Events](events.md) - registering listeners for the nine
  auth-flow events.
- [Rate Limiting](rate-limiting.md) - pair
  `RateLimitMiddleware::ip_based` with `LoginThrottleMiddleware` for
  layered defence.
- [Session](session.md) - what `start_challenge` /
  `complete_challenge` touch when they rotate the session id.


---

<!-- /docs/oauth -->

# OAuth, Apple, and magic-link login

Suprnova exposes OAuth, Sign in with Apple, and passwordless magic links through
the framework-owned `Auth` facade. Magnetar supplies the credential, ceremony,
identity, factor-gate, and session engines behind that facade.

The public entry points are:

- `Auth::oauth(provider)` for OAuth and Apple.
- `Auth::magic_link()` for passwordless email login.

Suprnova does not install routes for these flows. Applications provide small
start and callback handlers and decide how to deliver magic-link email.

## Initialize Magnetar with OAuth

Configure OAuth on the same `MagnetarConfig` that initializes password,
passkey, session, lockout, and two-factor services. The provider registry is
published atomically with those services: if any service cannot be built, none
of them becomes visible.

```rust,no_run
use std::sync::Arc;

use suprnova::{
    AbuseLimiter, App, AutoLinkPolicy, DB, DatabaseConnection, EndpointOverrides,
    FrameworkAbuseLimiter, GoogleOAuthProvider, GoogleProviderConfig, MagnetarConfig,
    MagnetarOAuthHostConfig, MagnetarOAuthProviderConfig, OAuthAuthorizationConfig,
    OAuthHttpTransport, PasskeyConfig, RateLimiterDriver, ReqwestOAuthTransport,
    RevocationTransport, SecretString, init_magnetar,
};

fn auth_config(
    database: DatabaseConnection,
    transport: Arc<dyn OAuthHttpTransport>,
    revocation: Arc<dyn RevocationTransport>,
    limiter: Arc<dyn AbuseLimiter>,
) -> MagnetarConfig {
    let provider = Arc::new(GoogleOAuthProvider::new(
        GoogleProviderConfig {
            client_id: "google-client".to_owned(),
            client_secret: SecretString::from("google-secret".to_owned()),
            redirect_uri: Some("https://app.example.com/auth/google/callback".to_owned()),
            scopes: vec!["openid".to_owned(), "email".to_owned()],
            endpoints: EndpointOverrides::default(),
        },
        revocation,
    ));
    let oauth = MagnetarOAuthHostConfig::new(
        vec![MagnetarOAuthProviderConfig {
            provider,
            redirect_uri: "https://app.example.com/auth/google/callback".to_owned(),
            scopes: vec!["openid".to_owned(), "email".to_owned()],
        }],
        transport,
        limiter,
        OAuthAuthorizationConfig::default(),
        AutoLinkPolicy::default(),
    )
    .expect("valid OAuth host configuration");

    MagnetarConfig::from_sea_orm(database)
        .passkey_config(PasskeyConfig {
            rp_id: "app.example.com".to_owned(),
            rp_origin: "https://app.example.com".to_owned(),
        })
        .oauth(oauth)
}

pub async fn register_auth() -> Result<(), suprnova::FrameworkError> {
    let database = DB::connection()?;
    let transport = Arc::new(ReqwestOAuthTransport::try_default()?);
    let limiter = Arc::new(FrameworkAbuseLimiter::new(
        App::resolve_make::<dyn RateLimiterDriver>()?,
    ));
    init_magnetar(auth_config(
        database.inner().clone(),
        transport.clone(),
        transport,
        limiter,
    ))
    .await
}
```
The framework re-exports the `OAuthProvider` contract, the five first-party
providers and configuration types, and every type needed to implement a custom
provider. `ReqwestOAuthTransport` supplies production token, userinfo, and
revocation I/O. `FrameworkAbuseLimiter` uses the application's configured
`RateLimiterDriver`. Applications need neither a direct `suprnova-magnetar`
dependency nor hand-written transport and limiter adapters.

`MagnetarConfig` creates its schema when `apply_migrations` is enabled, which is
the default. Use `.apply_migrations(false)` only when deployment prepares the
same schema separately. A second initialization returns an error instead of
replacing any installed engine.

### Keep an existing user and session stack

An application can use Magnetar for OAuth ceremonies and provider proof without
making Magnetar authoritative for password, passkey, framework-session, or
remember-me state. Build the same `MagnetarOAuthHostConfig`, then install it
through the OAuth-only initializer:

```rust,no_run
use suprnova::{
    MagnetarOAuthOnlyConfig, init_magnetar_oauth_only,
};

let database = DB::connection()?;
init_magnetar_oauth_only(
    MagnetarOAuthOnlyConfig::from_sea_orm(
        database.inner().clone(),
        oauth,
    ),
)
.await?;
```

Start the ceremony normally with `Auth::oauth(provider).begin()`. In the
callback, call `verify_oauth_identity(code, state)`, map the verified provider
subject into the application's own user table, and establish the existing
framework session with `Auth::login`. Do not call `complete` in this mode:
`complete` applies Magnetar's default account and session mapping, while the
purpose of OAuth-only initialization is to leave those decisions with the
application.

OAuth-only and full default initialization are alternatives. A second
initializer fails instead of mixing session authorities.

### GitHub provider requirements

GitHub's REST user endpoint requires a `User-Agent`; a community provider adds
it, and any media-type `Accept` value it needs, through
`OAuthProvider::userinfo_headers`. Suprnova adds the bearer `Authorization`
header separately and rejects provider attempts to override it.

GitHub's `/user` response includes an email only when the user made it public.
The verified primary address requires a second `/user/emails` request, while
`resolve_identity` deliberately performs no I/O and receives one userinfo
response. A GitHub provider can return `email: None` and use Suprnova's email
completion ceremony, or point `userinfo_endpoint` at a host adapter that
combines `/user` with the verified primary email. Do not treat an unverified or
merely public address as account ownership.

### Report the account picture

Each first-party provider reads the account picture from the profile response
it already parses:

- Google reads the userinfo `picture` claim.
- TikTok reads `avatar_url`.
- Facebook reads `picture.data.url`. Its profile request names
  `fields=id,name,email,picture`, because the Graph API returns only `id` and
  `name` for a request that names no fields.
- X reads `profile_image_url`, which its profile request names in
  `user.fields`.
- Apple reports no picture.

A custom provider reports a picture by adding `OAuthProvider::avatar_url`. The
method receives the same `ProviderResponse` that `resolve_identity` parses, and
it performs no I/O. Its default returns `None`, so a provider written without
it compiles unchanged and reports no picture.

```rust,ignore
use suprnova::{OAuthProvider, ProviderResponse};

#[derive(serde::Deserialize)]
struct AcmeProfile {
    avatar_url: Option<String>,
}

#[suprnova::async_trait]
impl OAuthProvider for AcmeProvider {
    // name, resolve_identity, and the other required methods as before.

    fn avatar_url(&self, response: &ProviderResponse) -> Option<String> {
        let ProviderResponse::UserInfo { body } = response else {
            return None;
        };
        let profile: AcmeProfile = serde_json::from_str(body).ok()?;
        profile.avatar_url.filter(|url| !url.is_empty())
    }
}
```

Return `None` for a missing or empty picture rather than an error: a profile
without a picture still signs in. Keep the picture out of the struct
`resolve_identity` deserializes, as the example does: there, a picture of a
shape you didn't expect fails the whole profile, and the sign-in with it. If
the provider's API omits fields that the request doesn't name, add the
picture field to `userinfo_endpoint`.


## Session binding

OAuth begin requires `SessionMiddleware`. Magnetar binds the ceremony to a
digest of the initiating framework session, so the callback cannot be moved to
another browser session.

Successful password, magic-link, passkey, and OAuth sign-in rotates the
framework session ID and CSRF token, records the application user ID, and stores
an opaque Magnetar web binding. Remember-me hydration rotates both the Magnetar
credential and the framework session binding.

## Start an OAuth flow

Use `begin` in the provider's start handler:

```rust,ignore
use suprnova::Auth;

let kickoff = Auth::oauth("google").begin().await?;
// Return an HTTP redirect to kickoff.authorization_url.
```

The returned `OAuthKickoff` contains:

- `authorization_url`, the URL to send to the browser.
- `state`, the single-use selector bound to the initiating session.

`begin` marks that session for storage, so the start response always sets
the session cookie. The start can be the browser's first request to your
application, and it can be a JSON or `POST` request; the callback still
arrives under the session the ceremony is bound to.

Magnetar owns state generation, PKCE policy, ceremony persistence, provider
exchange, identity verification, and abuse limiting. The host controller owns
the HTTP redirect and callback route.

## Verify or complete the callback

The callback has two entry points:

| Method | Result | Side effects |
|---|---|---|
| `verify_oauth_identity(code, state)` | `OAuthIdentity` | Verifies the provider proof and returns the provider, subject, verified email, display name, and picture URL without creating an application session. |
| `complete(code, state)` | `(User, Session)` | Resolves the identity through the installed host engine, applies account-link policy and the factor gate, rotates the framework session, and returns the framework-owned user and Magnetar session values. |

```rust,ignore
let identity = Auth::oauth("google")
    .verify_oauth_identity(&code, &state)
    .await?;

let (user, session) = Auth::oauth("google")
    .complete(&code, &state)
    .await?;
```

`OAuthIdentity.email` is present only when the provider supplied a verified
email. Persist the provider and subject as the stable external identity. Email
is not a stable provider identifier.

`OAuthIdentity.avatar_url` holds the account picture URL when the provider
reports one. It's `None` when the profile has no picture, an empty one, or one
that isn't the string the provider documents, and the picture never fails the
callback. The owner of the provider account
controls this value, so treat it as untrusted profile data. Before you render,
fetch, or store it, check its scheme and length:

```rust,ignore
let avatar_url = identity
    .avatar_url
    .filter(|url| url.starts_with("https://") && url.len() <= 2048);
```

## Account-link policy

OAuth completion does not treat possession of an unverified email string as
proof that the caller owns an existing application account.

The completion result can require more work instead of issuing a session:

- **Email completion required** returns HTTP 409 when the provider identity
  needs a separate verified-email ceremony.
- **Explicit link required** returns HTTP 409 when an existing verified account
  must authorize the link.
- **Factor required** returns HTTP 401 when account policy requires a second
  factor before session issuance.

A verified-email completion that wins the first-email-proof boundary reclaims
an unverified squatted account atomically. The transaction advances the auth
epoch, removes provisional credentials, revokes old sessions and remember
credentials, and attaches the verified provider account. A verified account is
never auto-linked by email alone.

## Sign in with Apple

Apple uses the same `Auth::oauth("apple")` facade, but its callback commonly
uses `response_mode=form_post`. Register the callback as a `POST` route and
pass the optional Apple `user` form field through the Apple-specific methods:

```rust,ignore
let identity = Auth::oauth("apple")
    .verify_apple_identity(&code, &state, form_post_user.clone())
    .await?;

let (user, session) = Auth::oauth("apple")
    .complete_with_apple_form_post(&code, &state, form_post_user)
    .await?;
```

`AppleIdentity` includes the stable subject, optional verified email,
`email_verified`, and `is_private_email`. Persist the subject as the stable key.
Apple can supply the display name only during the first authorization, so the
provider adapter must preserve that first `form_post` value.

Apple token and identity verification belongs to the installed provider
implementation. Current Magnetar providers require signature, issuer,
audience, expiry, and nonce checks rather than trusting an ID token's decoded
JSON.

## Magic-link login

Magic-link login uses the installed Magnetar password/session engine. The
framework returns the plaintext single-use token, while the application owns
mail composition and URL shape:

```rust,ignore
use suprnova::{Auth, Mail};

let token = Auth::magic_link()
    .send("alice@example.com", "https://app.example.com/auth/magic")
    .await?;

let url = format!("https://app.example.com/auth/magic?token={token}");
Mail::to("alice@example.com")
    .send(MagicLinkMail { url })
    .await?;

let (user, session) = Auth::magic_link().consume(&token).await?;
```

`send` applies the authentication abuse budget before token issuance. `consume`
is single-use, applies the factor gate, binds the resulting session into the
framework request session, and returns the user and Magnetar session.

For an unverified pre-existing account, successful magic-link consumption is a
first email proof. The transaction reclaims the account and removes provisional
password, passkey, linked-account, two-factor, session, and remember state so a
prior squatter cannot retain access.

## Routes to add

A typical application adds these routes:

```rust,ignore
get!("/auth/oauth/{provider}/start", controllers::oauth::start),
get!("/auth/oauth/{provider}/callback", controllers::oauth::callback),
post!("/auth/apple/callback", controllers::oauth::apple_callback),
post!("/auth/magic", controllers::magic_link::send),
get!("/auth/magic/callback", controllers::magic_link::consume),
```

Apply `SessionMiddleware` to every OAuth and passkey start/callback route. The
session carries the ceremony selector and binds the round trip to the browser
that started it.

## Authentication migration

The `suprnova-magnetar` crate includes a shape-aware migration engine for
Torii, Suprnova web, Suprnova API, and existing Magnetar schemas. It is a
library surface and example, not a `suprnova` CLI subcommand.

Enable the `migration` feature plus the source database driver and run a dry
plan before applying. For PostgreSQL:

```text
cargo run -p suprnova-magnetar \
  --features migration,seaorm-postgres \
  --example migrate -- \
  --source-shape torii \
  --database-url "$SOURCE_DATABASE_URL" \
  --app-database-url "$DATABASE_URL"
```

Use `seaorm-mysql` or `seaorm-sqlite` instead when that is the source and
application database driver.

Add `--apply` to apply the reviewed plan. The runner rechecks source and schema
fingerprints before import, records retry state, refuses identity collisions,
and uses transactional imports. MySQL same-database migrations use a
write-barrier-protected shadow swap with resumable restore and abort paths.

Keep the generated plan and report in deployment records. Do not apply a plan
whose source fingerprint changed after review.

## Reference

- Default boot: `MagnetarConfig`, `PasskeyConfig`, and `init_magnetar`.
- Facades: `Auth::oauth(provider)` and `Auth::magic_link()`.
- OAuth installation: `MagnetarConfig::oauth`, `ReqwestOAuthTransport`, and
  `FrameworkAbuseLimiter`.
- Migration library: `magnetar::migration` from the `suprnova-magnetar` crate.
- Bearer authentication: `BearerTokenMiddleware`.

## Next

- [Authentication](authentication.md) covers password, passkey, guards,
  framework sessions, and engine initialization.
- [Auth flows](auth-flows.md) covers email verification, password reset,
  lockout, and two-factor authentication.
- [Mail](mail.md) covers application-owned magic-link delivery.
- [Session](session.md) covers the browser session that binds OAuth and passkey
  ceremonies.


---

<!-- /docs/authorization -->

# Authorization

Authentication answers _"who are you?"_; authorization answers _"are you
allowed to do this?"_ Suprnova ships a Laravel-shaped `Gate` facade plus the
`#[policy]` macro for resource-oriented wiring, with sync and async variants
of every check so the same surface works whether your policy body needs a DB
hit or just a struct-field comparison.

## Quick start

```rust
use suprnova::{Authorizable, Gate};

#[derive(Debug)]
struct User { id: i64, is_admin: bool }
#[derive(Debug)]
struct Post { id: i64, author_id: i64, is_public: bool }

// Lets users opt into the `user.can(action, &resource)` ergonomics.
impl Authorizable for User {}

// Wire one ability:
Gate::define::<User, Post>("update", |user, post| {
    user.is_admin || post.author_id == user.id
});

let alice = User { id: 1, is_admin: false };
let own_post = Post { id: 10, author_id: 1, is_public: false };
let foreign_post = Post { id: 11, author_id: 99, is_public: false };

assert!(alice.can("update", &own_post));
assert!(alice.cannot("update", &foreign_post));

// Return 403 directly from a handler:
alice.authorize("update", &foreign_post)?;
```

## The `Gate` surface

### Defining abilities

```rust
// Sync closure - invoked directly, no boxed future.
Gate::define::<User, Post>("view", |user, post| post.is_public || user.id == post.author_id);

// Async closure - the future must be owned (no borrows past closure return).
Gate::define_async::<User, Post, _, _>("publish", |user, post| {
    let user_is_admin = user.is_admin;
    let post_id = post.id;
    async move {
        // ...DB lookup, RPC call, etc.
        user_is_admin || check_publish_permission(post_id).await
    }
});
```

Type-erased internally; the registry keys on `(action, TypeId<U>, TypeId<R>)`.
A `User` action gate and a `Comment` action gate of the same name live
independently - `Gate::has::<User, Post>("publish")` and
`Gate::has::<User, Comment>("publish")` answer separately.

### Checking abilities

| Method | Returns | Use |
|---|---|---|
| `Gate::allows(action, &user, &resource)` | `bool` | Quick branch |
| `Gate::denies(action, &user, &resource)` | `bool` | Inverse |
| `Gate::authorize(action, &user, &resource)` | `Result<(), FrameworkError>` | 403 on a bare deny; a rich denial carries its own status/message (see [Rich decisions](#rich-decisions-response-inspect-raw)) - short-circuits a handler with `?` |
| `Gate::inspect(action, &user, &resource)` | `Response` | Full decision: `allowed` + `message` + `code` + HTTP `status` |
| `Gate::raw(action, &user, &resource)` | `Option<Response>` | Like `inspect`, but `None` = no rule defined (vs an explicit deny) |
| `Gate::any(&[...], &user, &resource)` | `bool` | True if any allow |
| `Gate::none(&[...], &user, &resource)` | `bool` | True if none allow |
| `Gate::check(&[...], &user, &resource)` | `bool` | True if all allow |
| `Gate::inspect_current(action, &resource).await` | `Result<Response, FrameworkError>` | `inspect_async` for the user of the route's guard (see [Check the route's user](#check-the-routes-user)) |
| `Gate::none_current(&[...], &resource).await` | `Result<bool, FrameworkError>` | `none_async` for the user of the route's guard |

Every method in the first eight rows has an `_async` sibling that works for
both sync- and async-registered gates, so handlers don't need to know which
kind of closure backs the action. The last two are async only.

### Check the route's user

`Gate::inspect_current` and `Gate::none_current` find the user themselves,
as Laravel's `Gate::inspect` and `Gate::none` do. They ask the route's
guard, the guard `#[authorize]` asks (see [Authorize a
handler](#authorize-a-handler)), so you don't pass a user:

```rust
use suprnova::http::text;
use suprnova::{Gate, Request, Response};

async fn edit_form(req: Request) -> Response {
    let post = load_post(&req).await?;
    let decision = Gate::inspect_current("update", &post).await?;
    if decision.denied() {
        return text(decision.message().unwrap_or("You cannot edit this post."));
    }
    // ... render the form
    text("edit form")
}

async fn read_only_banner(req: Request) -> Response {
    let post = load_post(&req).await?;
    let read_only = Gate::none_current(&["update", "delete"], &post).await?;
    text(if read_only { "read only" } else { "editable" })
}
```

The checks follow these rules:

- The user is checked as its concrete type. The gates, policies, and hooks
  you registered for that type answer, async ones included, and
  `inspect_current` answers what `Gate::inspect_async` answers for the same
  user.
- With no user signed in, a gate defined with `Gate::define_optional` or
  `Gate::define_optional_with`, or a policy method that takes
  `Option<&User>`, receives `None`. Every other ability answers the
  default denial (see [Default denial response](#default-denial-response)).
  A guest is not an error: you get a denied `Response`, never the `401`
  that `#[authorize]` answers.
- `none_current` stops at the first action that allows. An empty list
  answers `true`.
- Both return the error the route's guard returns when it cannot resolve
  the user, such as a user provider that cannot reach its database. They
  don't guess an answer for a user they could not resolve.

### Introspection

```rust
// Is an ability defined?
Gate::has::<User, Post>("publish");  // bool

// What abilities exist? (sorted + deduped by action name)
let all: Vec<String> = Gate::abilities();
```

`abilities()` dedupes across resource types: registering `"view"` for
both `User`-on-`Post` and `User`-on-`Comment` yields a single `"view"`
entry. Useful for admin pickers and Inertia shared-data.

### Missing-gate semantics

Calling `allows` / `denies` / `authorize` on an action that was never
registered **defaults to deny**. Same for calling the sync API on an
async-registered gate (the sync path can't await - defaulting deny
surfaces the bug in logs via `tracing::warn!` rather than silently
passing). Async-registered gates respond correctly from the
`_async` paths.

## Policies with `#[policy]`

When a resource type has several abilities, group them into a policy struct
and let `#[policy]` register every method as a gate:

```rust
use suprnova::policy;
use suprnova::authorization::Response;

struct User { id: i64, is_admin: bool }
struct Post { id: i64, author_id: i64, is_public: bool }
struct PostPolicy;

#[policy(User, Post)]
impl PostPolicy {
    // A `-> bool` method is a plain allow/deny gate.
    fn view_any(_user: &User, _post: &Post) -> bool {
        true // anyone can list posts
    }
    fn view(user: &User, post: &Post) -> bool {
        post.is_public || post.author_id == user.id || user.is_admin
    }

    // A `-> Response` method can carry a message + HTTP status on denial.
    fn update(user: &User, post: &Post) -> Response {
        if post.author_id == user.id || user.is_admin {
            Response::allow()
        } else {
            Response::deny_with("You may only edit your own posts.")
        }
    }
    fn delete(user: &User, post: &Post) -> Response {
        if user.is_admin {
            Response::allow()
        } else {
            Response::deny_as_not_found() // hide the post from non-admins
        }
    }
}
```

Each method becomes one `inventory::submit!`. `Server::run` drains the
inventory via `init_policies()` at boot, so by the time the first request
arrives every action is registered (see [Bootstrap](bootstrap.md) for where
this slots into the boot sequence). `init_policies()` lives at
`suprnova::authorization::init_policies` and is idempotent - call it manually
in tests that exercise policy registration without standing up a server.

Policy methods are stateless associated functions taking `(user, resource)` -
the same shape as Laravel's `update(User $user, Post $post)`, where `$this` is
the stateless policy object. Every method takes both arguments for a uniform
gate signature; `view_any` / `create` simply ignore the resource (`_post`).
Methods you don't write aren't registered, and an unregistered action
default-denies.

You accept a guest by declaring the user as `Option<&User>` in a policy
method. The method receives `None` for a guest and `Some(user)` for an
authenticated request. You return `true` to allow the guest or `false` to
answer `403`. A rich denial keeps its status, including `404`.
You can register the same shape directly with `Gate::define_optional` or
`Gate::define_optional_with`. Authenticated checks keep the hook pipeline.
If several nullable policies name the same ability and resource for
different user types, your guest check denies because it cannot select a
user type.

### Method-name → action mapping

Method name is used directly as the action's verb segment, with the
resource kebab-cased and suffixed:

| Method | Action |
|---|---|
| `view` on `Post` | `"view-post"` |
| `view_any` on `Post` | `"view_any-post"` |
| `force_delete` on `UserProfile` | `"force_delete-user-profile"` |

This diverges from Laravel's camelCase action names (`viewAny`,
`forceDelete`) to keep the Rust surface idiomatic - every action
string mirrors the method identifier you'd autocomplete in your
editor.

### Return type: `bool` or `Response`

A policy method's return type selects how it registers - and what a denial
can carry:

| Return type | Registers via | Denial surfaces as |
|---|---|---|
| `bool` | `Gate::define` | bare `403` (`This action is unauthorized.`) |
| `Response` | `Gate::define_with` | the message, code, and HTTP status the `Response` carries |

Return `bool` for a simple yes/no. Return a `Response` (imported from
`suprnova::authorization::Response`) when a denial should carry a reason or a
non-403 status - `Response::deny_with("…")` for a message, or
`Response::deny_as_not_found()` to answer `404` and hide the resource's
existence. Both compile to the same type-erased gate (a `bool` is wrapped into
a bare allow/deny). Any other return type - or a missing one - is a compile
error.

## The `Authorizable` trait

Drop-in user-side sugar for the `Gate` calls:

```rust
use suprnova::Authorizable;

impl Authorizable for User {}

// Sync sugar
if alice.can("update", &post)    { /* ... */ }
if alice.cannot("delete", &post) { /* ... */ }
alice.authorize("update", &post)?;  // 403 on deny

// Async sugar
if alice.can_async("publish", &post).await    { /* ... */ }
alice.authorize_async("publish", &post).await?;
```

Every method has a default body that delegates to the matching `Gate`
method, so `impl Authorizable for User {}` (no body) is enough.
Opt-in rather than blanket-impl: not every type that can be passed to
`Gate::allows` is meant to be the subject of `.can` - most often
it's your application's `User`.

## Composition patterns

### Gating route groups

```rust
use suprnova::{group, get, Auth, AuthMiddleware, FrameworkError, Request, Response};

// Middleware checks the auth user; the handler authorizes the action.
group!("/posts")
    .middleware(AuthMiddleware::new())
    .routes([
        get!("/{id}/edit", edit_form),
    ]);

async fn edit_form(req: Request) -> Response {
    let user: User = Auth::user_as::<User>()
        .await?
        .ok_or(FrameworkError::Unauthorized)?;
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| FrameworkError::param_parse("id", "i64"))?;
    let post = Post::find(id).await?
        .ok_or_else(|| FrameworkError::not_found("Post"))?;
    user.authorize("update", &post)?;
    // ... render edit form
}
```

### Many-action checks

A "list all the things this user can do on this resource" page:

```rust
let actions = ["view", "update", "delete", "restore", "force_delete"];
let mut allowed = Vec::new();
for action in &actions {
    if user.can(action, &post) {
        allowed.push(*action);
    }
}
// Or short-circuit:
let can_do_anything = Gate::any(&actions, &user, &post);
let is_locked_out   = Gate::none(&actions, &user, &post);
```

### Multi-gate authorization

```rust
// Only allow if the user can do ALL of these actions on the resource.
Gate::authorize_async("publish", &user, &post).await?;
if Gate::check_async(&["update", "view"], &user, &post).await {
    // Combine checks.
}
```

### Gating resource routes

When a `Router::resource` surface exists, `authorize_resource::<U, R>()`
wires the conventional ability check onto all seven routes at once, so you
do not depend on every controller method remembering to authorize:

```rust
Gate::define::<User, Post>("view",   |u, _p| u.is_member);
Gate::define::<User, Post>("create", |u, _p| u.is_author);
Gate::define::<User, Post>("update", |u, _p| u.is_author);
Gate::define::<User, Post>("delete", |u, _p| u.is_admin);

let router: Router = Router::new()
    .resource("posts", PostsCtl)
    .authorize_resource::<User, Post>()   // index/show→view, store→create, …
    .into();
```

A denied ability returns `403` before the handler runs; an unauthenticated
request fails closed. The check runs against the user of the route's guard,
the same user `#[authorize]` checks (see [Authorize a
handler](#authorize-a-handler)). The full action → ability table lives in
the [routing chapter](routing.md).

## Authorize a handler

A gate check inside the handler body works only if nobody forgets it.
`#[authorize]` on a `#[handler]` declares the check instead, the way
Laravel's `#[Authorize]` controller attribute does:

```rust
use suprnova::http::text;
use suprnova::{Response, authorize, handler};
use crate::models::Post;
use crate::requests::StorePost;

// Route: post!("/posts", controllers::post::store)
#[handler]
#[authorize("create-post", Post)]
pub async fn store(form: StorePost) -> Response {
    text(format!("stored {}", form.title))
}

// Route: put!("/posts/{post}", controllers::post::update)
#[handler]
#[authorize("update-post", post)]
pub async fn update(post: Post) -> Response {
    text(format!("updated {}", post.id))
}
```

The second argument is either a parameter or a type:

- A single name that starts with a lowercase letter, such as `post`, is a
  parameter of the handler. The check runs against the value the route
  binds to it, or the path value it reads (`id: i64`). For a
  `RouteParam<Post>` parameter, that is the `Post` inside. The name can
  also be the binding of a pattern, as in
  `RouteParam(post): RouteParam<Post>`. A name the handler does not take
  is a compile error.
- Anything else, such as `Post` or `post::Model`, is a type. The gate is
  keyed by type, so the check runs against `Post::default()`, the same
  stand-in [`authorize_resource`](#gating-resource-routes) uses. Every
  `#[suprnova::model]` struct implements `Default`.

The ability goes to the gate as written. A `#[policy(User, Post)]` method
`update` registers the ability `update-post`, so a handler that relies on
that policy names `"update-post"`. An ability registered with
`Gate::define` or `Gate::define_async` is named the way it was registered.

You can also write `#[authorize(Ability::Update, post)]`. Your enum
implements `Into<String>` and returns the ability name, such as
`"update-post"`. The converted name reaches the same async gate as a string.

The check runs at a fixed point in the request:

1. The route parameters are bound and the path values read. A model that
   does not exist answers `404 Not Found`, whatever the gate would decide.
2. Each `#[authorize]` runs, in the order written. The first one that
   fails ends the request.
3. The request body is read and validated, so a denied user never sees a
   validation error.
4. The handler body runs.

The check asks the async gate about the user of the route's guard.
Policies, async gates, async `before` hooks, and the
[permission bridge](#answering-the-gate-with-permissions) all answer it.

The route's guard is the guard that the last `AuthMiddleware` to pass the
request on checked. For `AuthMiddleware::new().for_guard("api")`, that is
the `api` guard, so the check runs against the user the `api` guard
authenticated. With no `for_guard`, or with no `AuthMiddleware` at all,
it is the default guard, and the user is the one `Auth::user()` resolves:

```rust
use suprnova::{AuthMiddleware, Router};

// `update` carries `#[authorize("update-post", post)]`. The check asks the
// `api` guard for the user, not the default guard.
pub fn routes() -> Router {
    Router::new()
        .put("/api/posts/{post}", controllers::post::update)
        .middleware(AuthMiddleware::new().for_guard("api"))
        .into()
}
```

When the route's guard has no user, your nullable policy receives `None`.
A policy that requires `&User` answers `401`, even if another guard has one. A user of the default guard never stands in for the
user of the route's guard. This also holds under
`AuthMiddleware::optional().for_guard("api")`, which lets a guest through.

When the check fails, it answers the request with one of these statuses:

| Situation | Status |
|---|---|
| No user on the route's guard and the policy requires a user | `401 Unauthorized`, `{"message": "Unauthenticated."}` |
| The gate denies | `403 Forbidden` |
| A rich denial with a status, such as `Response::deny_as_not_found()` | That status, `404 Not Found` here |

`#[authorize]` may sit above or below `#[handler]`, and a handler may carry
several. Without `#[handler]` it is a compile error. The handler must be an
`async fn`, and the parameter it names must come from the route: its type
must implement `RouteBinding`, as every `#[suprnova::model]` does, or be a
primitive path value read through `FromParam`, such as `id: i64`. A form
request or a `Request` reads the body, and the check runs before the body
is read, so naming one is a compile error too.

### Why Suprnova diverges

You receive `401 Unauthorized` when the policy requires a user. Laravel
answers `403` in this case. Your nullable policies run for guests in both
frameworks.

In Laravel, `auth:api` makes `api` the default guard for the rest of the
request, so `Auth::user()` and the `can` middleware both read the `api`
user. In Suprnova, `AuthMiddleware::for_guard("api")` doesn't change the
default guard: `Auth::user()` still reads the default guard. The route
checks follow the route's guard: `#[authorize]`,
`EnsureEmailVerifiedMiddleware`, `RoleMiddleware` and
`PermissionMiddleware`. To read the same user in the handler body, call
`Auth::guard("api")?.user()`.

Laravel tells a model class from a route parameter by the backslash in
`Post::class`. Rust has no class strings, so Suprnova uses Rust's naming
conventions instead: a single lowercase name is a parameter, and anything
else is a type. For the type form, Laravel calls a policy method that takes
no model. Suprnova's gate always passes a resource, so the type form passes
a default value of the type.

## Async semantics

`Gate::define_async`'s closure must return an **owned** future - the
type-erased registry cannot let `&user` or `&resource` references
outlive the closure return. Copy or clone any fields you need inside
the `async move {}` block before returning it:

```rust
Gate::define_async::<User, Post, _, _>("publish", |user, post| {
    let user_id = user.id;        // copy primitive
    let post_id = post.id;
    let admin   = user.is_admin;
    async move {
        // No `user` / `post` references here - only the captured copies.
        admin || check_can_publish(user_id, post_id).await
    }
});
```

Sync gates work transparently from the async path (`Gate::allows_async`
dispatches them without an `.await`), so a codebase can register
sync gates today and migrate individual abilities to async later
without changing call sites.

## Lock-poison posture

The `Gate` registry uses an `RwLock` internally. If the lock is ever
poisoned (a thread panicked while holding the write guard), the
registry **safe-denies** - every subsequent `authorize` call returns
`Unauthorized` rather than panicking. Registration calls log to
`tracing::error!` and continue. This matches the broader framework
policy: a poisoned lock never aborts the process.

## Rich decisions: `Response`, `inspect`, `raw`

A bare `bool` gate answers only allow/deny. For a denial that carries a
*message*, a machine *code*, or a non-403 HTTP *status*, register the gate
with `define_with` (or `define_async_with`) and return a `Response`:

```rust
use suprnova::authorization::Response;  // re-exported at the crate root as `GateResponse`

Gate::define_with::<User, Post>("update", |user, post| {
    if post.author_id == user.id {
        Response::allow()
    } else {
        Response::deny_with("You do not own this post.")
    }
});

// Hide a resource's existence rather than admit it exists:
Gate::define_with::<User, Secret>("view", |user, secret| {
    if user.can_see(secret) {
        Response::allow()
    } else {
        Response::deny_as_not_found()  // a 404, not a 403
    }
});
```

Inspect the full decision with `Gate::inspect` (sync) / `Gate::inspect_async`:

```rust
let decision = Gate::inspect("update", &user, &post);
decision.allowed();   // bool
decision.message();   // Option<&str> - Some("You do not own this post.")
decision.status();    // Option<u16> - None here; Some(404) after deny_as_not_found
```

`Response` constructors mirror Laravel: `allow()`, `deny()`,
`deny_with(msg)`, `deny_with_status(status, msg)`, `deny_as_not_found()`,
plus `with_message` / `with_code` / `with_status` / `as_not_found` builders.

### How a denial becomes an error

`Gate::authorize` collapses the decision through `Response::authorize()`:

| Decision | `authorize` result |
|---|---|
| allowed | `Ok(())` |
| bare `deny()` (no message/code/status) - what an unconfigured default denial response falls back to | `FrameworkError::Unauthorized` (403, `"This action is unauthorized."`) |
| denial with a code (`with_code`) | `FrameworkError::Denial { message, status_code, code }` |
| any other rich denial (message and/or status set) - including a configured default denial response that carries one | `FrameworkError::Domain { message, status_code }` |

So `deny_as_not_found()` surfaces as a 404, `deny_with_status(422, "…")` as a
422, and `deny_with("…")` as a 403 carrying your message. A denial's code
travels through `authorize`, as Laravel's `AuthorizationException` keeps
it. Read it with `FrameworkError::code()` after `?`:

```rust
use suprnova::{FrameworkError, Gate};

async fn publish(user: &User, post: &Post) -> Result<(), FrameworkError> {
    match Gate::authorize_async("publish", user, post).await {
        Err(error) if error.code() == Some("over-limit") => {
            // Offer an upgrade instead of a bare refusal.
            Err(error)
        }
        other => other,
    }
}
```

The denial's status and message reach the client as they do for any other
denial. The code stays on the server: the response body carries the
message only, as Laravel renders a denial.

Whichever status a denial lands on, it reaches the client as the
framework's JSON error body. An Inertia app should also name an
[error page](frontend-inertia-responses.md#error-pages) - without one,
the Inertia client treats that body as a non-Inertia response and shows
its full-screen error modal instead of rendering anything, so a user
with the wrong role sees a crash rather than "you cannot do that".

### `raw`: "denied" vs "undefined"

`Gate::raw` (and `raw_async`) returns `Option<Response>`: `None` means *no
rule applied* - no `before` hook fired, no gate is registered, no `after`
hook filled in - as distinct from an explicit `Some(deny)`. `inspect`
normalizes that `None` to the configured default denial response (a bare
deny unless `Gate::default_denial_response` has set something else); `raw`
preserves the `None` for diagnostics ("is this action governed at all?").

### Default denial response

Laravel's `Gate::defaultDenialResponse($response)` reshapes what an
*undecided* denial looks like - not every denial, only the ones that would
otherwise fall back to the bare `Response::deny()`. Set it once, typically
in `bootstrap::register()`:

```rust
use suprnova::authorization::Response;
use suprnova::Gate;

Gate::default_denial_response(Response::deny_as_not_found());
```

After that call, two kinds of outcome pick up the new shape: a bare
`false` - from a bool gate (`define`/`define_async`, including a `#[policy]`
method returning `bool`), or from a `before`/`after` hook that decided
`false` -
and an evaluation nothing else decided at all: an undefined ability with no
hook opinion either. All of those used to surface as a bare
`Response::deny()` (a 403); now they surface as whatever
`default_denial_response` was given - a 404 in the example above. That is
the standard "hide the resource's existence from a user who may not view
it" move (see the `Secret` example earlier in this chapter), applied once
for the whole application instead of gate by gate.

The default applies to **bare `false` only**. A gate registered with
`define_with` (or `define_async_with`) already returned the `Response` it
wanted - `Response::deny_with("…")`, `Response::deny_as_not_found()`, even
an explicit bare `Response::deny()` - and every one of those passes through
`inspect` untouched. This mirrors Laravel's own rule: `Gate::inspect` only
substitutes the default for a truly falsy callback result, never for a
`Response` object the callback built itself.

## `before` / `after` hooks

`Gate::before` registers a check that runs *before* any gate; the first hook
to return `Some(decision)` short-circuits everything. The canonical use is a
global override:

```rust
// Administrators may do anything.
Gate::before::<User>(|user, _action| user.is_admin.then_some(true));
```

`Gate::after` runs *after* the gate. Following Laravel's `??=` semantic, an
after hook can only **fill in** an undecided result (no gate matched and no
before hook fired) - it can never override an allow/deny already produced.
Every after hook still runs, so it doubles as the audit-logging seam:

```rust
Gate::after::<User>(|user, action, decided| {
    audit_log(user.id, action, decided);   // observe every evaluation
    None                                    // record-only; don't change the result
});
```

Hooks are keyed by the **user type** `U`, not by resource - a hook fires for
every `(action, U, R)`. Put resource-specific logic in the gate. A `before`
hook is a synchronous predicate and applies to the async evaluation path too;
for async authorization logic in a gate, use `define_async` /
`define_async_with`.

An after hook that needs the resource, as Laravel's after callbacks receive
`$arguments`, is registered with `Gate::after_with_arguments::<U, R>`. It
receives the resource as a fourth argument and runs only for checks whose
resource is an `R`. Otherwise it follows the rules of `Gate::after`: it runs
on every such check and can only fill in an undecided result. It answers
`Option<bool>`, never a `Response`:

```rust
// When no gate decides, an author may act on their own post.
Gate::after_with_arguments::<User, Post>(|user, _action, decided, post| {
    decided.is_none().then(|| post.author_id == user.id)
});
```

### Async `before` hooks

A hook that has to wait on I/O, such as a database read, cannot be a
synchronous closure. Register it with `Gate::before_async`. The closure must
return an owned future, as `define_async` requires:

```rust
// Staff, as the directory service lists them, may do anything.
Gate::before_async::<User, _, _>(|user, _action| {
    let id = user.id;
    async move { is_staff(id).await.then_some(true) }
});
```

Sync and async `before` hooks share one list per user type. Evaluation walks
the list in the order you registered the hooks, and the first `Some(decision)`
wins. Only the async forms of the gate (`allows_async`, `denies_async`,
`authorize_async`, `inspect_async`, `raw_async` and the async multi-action
methods) wait on an async hook. Never block a thread on I/O inside a
synchronous hook to get around this: it stalls a runtime worker on every check.

#### A denial here is not enforced everywhere

A hook that answers `Some(false)` denies only on the async forms. The forms
that cannot wait skip the hook and go on as if it had answered nothing, so a
gate that allows still allows there. These forms are `Gate::allows`,
`denies`, `authorize`, `inspect`, `raw`, `any`, `none` and `check`, and `can`,
`cannot` and `authorize` on [`Authorizable`](#the-authorizable-trait). A hook
that must deny belongs in `Gate::before`. Otherwise every check your
application makes has to use an async form.

## The `GateEvaluated` event

Every check dispatches one `GateEvaluated` event for each action it
evaluates, after the `before` hooks, the gate, and the `after` hooks run, as
Laravel's `Gate::raw` does. That covers `inspect`, `raw`, their async
siblings, and every check built on them: `allows`, `denies`, `authorize`,
`any`, `none`, `check`, the `Authorizable` methods, `#[authorize]`,
`inspect_current`, and `none_current`. The event carries these fields:

| Field | Value |
|---|---|
| `user_type` | `std::any::type_name` of the user, `None` for a guest |
| `user_id` | The user's identifier when the check found the user itself (`inspect_current`, `none_current`, `#[authorize]`), else `None` |
| `action` | The action |
| `resource_type` | `std::any::type_name` of the resource |
| `decision` | `Some(true)`, `Some(false)`, or `None` when nothing decided |

Listen for it to keep an audit trail of every decision:

```rust
use std::sync::Arc;
use suprnova::{EventFacade, FrameworkError, GateEvaluated, Listener};

struct AuditGate;

#[suprnova::async_trait]
impl Listener<GateEvaluated> for AuditGate {
    async fn handle(&self, event: &GateEvaluated) -> Result<(), FrameworkError> {
        audit_log(&event.action, event.user_id.as_deref(), event.decision);
        Ok(())
    }
}

EventFacade::listen::<GateEvaluated, _>(Arc::new(AuditGate)).await;
```

An async check waits for the listeners. A sync check inside a Tokio
runtime must not block the runtime's thread, so it runs the dispatch once in
place. A listener that finishes without waiting on anything has run when the
check returns, and the rest continues on a task spawned on that runtime.
Outside a Tokio runtime, a sync check runs the dispatch to completion on a
single-threaded runtime built for it, so every listener has run when the
check returns. A listener's error is logged and never changes the decision.
When nothing listens and no fake is installed, the check builds no event at
all.

A check that finds the user itself names the user's type through
`Authenticatable::auth_type_name`, which every implementation inherits, so
the event names a signed-in user's own type even when that type registered
no gate, policy, or hook.

In a test, assert on the events through the events fake:

```rust
use suprnova::events::testing::dispatched;
use suprnova::{EventFacade, Gate, GateEvaluated};

let _events = EventFacade::fake();
assert!(Gate::allows("update", &author, &post));
let events = dispatched::<GateEvaluated>(|event| event.action == "update");
assert_eq!(events.len(), 1);
assert_eq!(events[0].decision, Some(true));
```

### Why Suprnova diverges

Laravel's `Gate::forUser($user)->allows(...)` rebinds the gate's *implicit*
current-user resolver so the next check evaluates as that user. Suprnova's
gate takes the user **explicitly** on every call, so "check as a different
user" is just `Gate::allows(action, &other_user, &resource)`. Only
`inspect_current` and `none_current` find the user themselves, from the
route's guard, so there is no resolver to rebind and `forUser` has nothing
to do.

`inspect_current` and `none_current` return a `Result`. Laravel's
`Gate::inspect` throws when its user resolver throws; Suprnova returns that
error instead of an answer.

Laravel's `GateEvaluated` holds the user object and the check's arguments.
A Suprnova gate is generic over the user and the resource, so the event
names their types and carries the user's identifier only when the check
found the user itself. One listener then serves every gate, and no user or
resource is cloned into the event. For the same reason,
`after_with_arguments` takes the resource's type and runs only for checks
about that type.

The same reasoning applies to Laravel's policy auto-discovery by class name.
Suprnova ties policy methods to the type-erased `(action, U, R)` key at
registration time, so a `Post` policy and a `Comment` policy with the same
method name register two distinct gates without a naming convention or a
discovery scan.

`Gate::default_denial_response` also diverges from Laravel in one respect:
passing it an allow-shaped `Response::allow()` is logged and ignored rather
than accepted. Laravel's `defaultDenialResponse` has no such guard, but this
is a *denial* default - accepting an allow-shaped one would silently invert
every bare `false` gate result to allowed, the one fail-open direction on
this surface.

## Roles and permissions

Suprnova ships a small role and permission system in `suprnova::rbac`. It is
optional. You add the tables, implement one trait on your user model, and
assign roles and permissions to users.

- A **permission** is a name, such as `"posts.publish"`.
- A **role** is a named set of permissions, such as `"editor"`.
- A user holds a permission **directly**, or **through a role** that carries it.

Add `suprnova::rbac::migrations::CreateRbacTables` and `RbacToSpatieLayout`
to your migrator. The tables take spatie/laravel-permission's layout:
`roles`, `permissions`, `model_has_roles`, `model_has_permissions` and
`role_has_permissions`. On a database where spatie's migration created them,
the RBAC reads the roles, permissions and assignments spatie recorded, and
the migrations leave those tables as they are. `model_id` follows
`RBAC_MODEL_KEY`: `int` (the default), `uuid` or `ulid`. `RbacToSpatieLayout`
moves the tables an earlier release created (`role_permissions`,
`model_roles`, `model_permissions`, and a `display_name` on roles and
permissions) into spatie's layout with every row; the display names move to
`suprnova_role_details` and `suprnova_permission_details`. Every role and
permission has a guard name. The helpers that take no guard use `"web"`,
and so does every check on this page.

An assignment is stored with the user model's `morph_type` as its
`model_type`, as spatie stores the model's morph class. Declare
`#[model(morph_type = "App\\Models\\User")]` on your user model to share
assignments with a Laravel application; without a `morph_type`, the
`model_type` is the model's Rust type path. The `HasRoles` methods also
read and remove assignments stored under the model's `morph_aliases` and
under its Rust type path, the default before it followed `morph_type`, so
the roles an earlier release assigned still apply; `rbac_model_types()`
lists them all. See
[Running on a Laravel Database](laravel-database.md).

Implement `HasRoles` on the user model. It has no required methods:

```rust
use suprnova::HasRoles;
use suprnova::rbac::{create_role, give_permission_to_role};

impl HasRoles for User {}

// Setup, for example in a seeder:
create_role("editor").await?;
give_permission_to_role("editor", "posts.publish").await?;

user.assign_role("editor").await?;
user.give_permission_to("posts.delete").await?;

user.has_role("editor").await?;                  // true
user.has_permission_to("posts.publish").await?;  // true, through the role
user.has_permission_to("posts.delete").await?;   // true, held directly
```

The helpers that create and grant are idempotent. A second call leaves the
one row the first call wrote, and so do two requests that make the same
grant at once: both succeed, on SQLite, Postgres and MySQL alike.

For a route, `RoleMiddleware::<User>::new("editor")` and
`PermissionMiddleware::<User>::new("posts.publish")` require the role or the
permission. Put them after `AuthMiddleware`. A user who lacks it gets a `403`,
or a redirect if you build the middleware with `redirect_to`. A failed
database read also refuses the request.

Both check the user of the route's guard, the guard the last
`AuthMiddleware` to pass the request on checked, as `#[authorize]` does.
Behind the default guard, they read the grants the `HasRoles` methods write.
Behind another guard, they read that guard's grants, the ones the
`*_on_guard` helpers write:

```rust
use suprnova::rbac::assign_role_to_model_on_guard;
use suprnova::{AuthMiddleware, FrameworkError, HasRoles, RoleMiddleware, Router};

// Grant `editor` on the `admin` guard, for example in a seeder.
async fn grant_editor(admin: &User) -> Result<(), FrameworkError> {
    let model_type = admin.rbac_model_type();
    assign_role_to_model_on_guard(&model_type, &admin.rbac_model_id(), "editor", "admin").await
}

pub fn routes() -> Router {
    Router::new()
        .get("/admin/posts", controllers::admin::posts)
        .middleware(AuthMiddleware::new().for_guard("admin"))
        .middleware(RoleMiddleware::<User>::new("editor"))
        .into()
}
```

A default-guard user signed in on the same session never passes for the
admin route's user, whatever roles that user holds.

### Answering the gate with permissions

Without more setup, the gate does not know about permissions:
`Gate::allows_async("posts.publish", &user, &post)` asks only the gate
definitions and the policies. Call `register_gate_bridge` once, in
`bootstrap::register()`, to connect the two:

```rust
suprnova::rbac::register_gate_bridge::<User>();

// Allowed when the user holds "posts.publish", directly or through a role.
if Gate::allows_async("posts.publish", &user, &post).await {
    // ...
}
```

The bridge is a `before` hook of the gate, built on `Gate::before_async`. It
follows these rules:

- **It allows and never denies.** If the ability is a permission the user
  holds, the gate allows. For any other ability the bridge has no opinion, and
  the gate goes on to its definitions and policies. A user who does not hold
  the permission can still be allowed by a gate or a policy.
- **A `before` hook answers first.** A held permission allows the ability of
  the same name even where a gate definition or a policy would deny it. This
  is why the bridge is opt-in: keep permission names and policy ability names
  apart unless you want them to overlap.
- **Only the async forms see permissions.** The bridge reads the database,
  so `allows_async`, `authorize_async`, `inspect_async` and the other async
  forms use it. `allows`, `authorize` and `inspect` skip it, and a permission
  never answers them.
- **One read per request.** The bridge reads all the permissions of a user
  with one query the first time a check in a request needs them, and answers
  the rest of the request from that set. It keeps nothing after the request.
  A grant or a revocation made before the first check of a user in a request
  is seen by that check. After that check, it is seen from the next request.
- **A check in a transaction reads for itself.** Inside `DB::transaction` a
  check neither uses the set nor adds to it. It reads on the transaction, so it
  sees what the transaction changed, and it keeps nothing.
- **A unit of work with its own scope reads for itself.** A job that the sync
  queue driver runs inline, or a future you run with `App::run_scoped`, opens
  its own container scope inside the request. Its checks read the database
  again and leave nothing for the request.
- **Outside a request, every check reads the database.** A queued job, a
  console command or a task you spawn from a handler is not inside the request.
- **A failed read allows nothing.** The bridge logs the error, without the id
  of the user, and answers nothing. The gate then denies unless a definition
  or a policy allows.
- **The guard is `"web"`.** Permissions on another guard do not answer the
  gate.

`register_gate_bridge` also adds `GateBridgeMiddleware` to the front of the
global middleware, which holds the per-request set. Calling it twice for the
same user type changes nothing. If you never call it, nothing changes: the gate
answers as before.

### Why Suprnova diverges

The gate takes the user explicitly and has a sync surface and an async
surface. A permission is a database read, so it can answer only the async
surface. Use `allows_async` and `authorize_async` wherever a permission
decides.

## Next

- [Authentication](authentication.md) - the user-side half: guards,
  `Auth::user()`, `Auth::user_as::<T>()`
- [Bootstrap](bootstrap.md) - where `init_policies()` runs in the boot
  sequence, plus how to register before/after hooks
- [Middleware](middleware.md) - pairing `AuthMiddleware` with route-level
  authorization
- [Error Model](error-model.md) - how a gate denial collapses into a 403, a
  404, or a custom-status `FrameworkError::Domain`
- [Events](events.md) - listening for `GateEvaluated` to audit every
  decision, and the events fake that asserts on it


---

<!-- /docs/encryption -->

# Encryption

Suprnova ships application-level encryption as a process-wide facade
named `Crypt`. It encrypts strings or any `Serialize` value under
AES-256-GCM, keyed by your `APP_KEY`. Reach for it whenever you need
to put something sensitive into storage you don't fully trust - a
column, a cookie, a pagination cursor - and need to read it back
intact later.

```rust
use suprnova::{Crypt, CryptPurpose};

let wire = Crypt::encrypt_string(CryptPurpose::Cast, "ssn-123-45-6789")?;
let plain = Crypt::decrypt_string(CryptPurpose::Cast, &wire)?;
assert_eq!(plain, "ssn-123-45-6789");
```

The framework itself uses `Crypt` for encrypted cookies, encrypted
pagination cursors, 2FA secrets, recovery codes, and the
`AsEncrypted*` Eloquent casts. The same facade is available to your
code with no extra wiring once `APP_KEY` is configured (see
[configuration.md](configuration.md#the-env-file)).

When a value belongs under a key other than `APP_KEY`, build an
`Encrypter` with that key (see
[An encrypter with its own key](#an-encrypter-with-its-own-key)).

## The wire format

`encrypt_string` and `encrypt` both return URL-safe base64 (no
padding) over `nonce || ciphertext_with_tag`:

```
base64url( [12-byte random nonce] || [ciphertext] || [16-byte GCM tag] )
```

Each call samples a fresh 12-byte nonce from the OS RNG, so two
encryptions of the same plaintext under the same key produce distinct
ciphertexts. There is no padding oracle to leak length information
beyond the plaintext itself.

The output is safe to put in URL query strings, JSON bodies, headers,
and cookies without further encoding. A minimum valid wire is 28 bytes
(12 nonce + 16 tag) - anything shorter is rejected up front.

## `APP_KEY` - the one secret that matters

Suprnova reads a single 32-byte symmetric key from the `APP_KEY`
environment variable. The expected format is URL-safe base64, no
padding, decoding to exactly 32 bytes (43 base64 characters):

```env
APP_KEY=hQ7rW0X9_NkSi8Cw5fF8j6V_K6JzgB3y2Hq9LpL9-Wo
```

Generate one with the CLI:

```bash
suprnova key:generate
# Generated a new APP_KEY (AES-256, base64 URL-safe, no padding):
#
#     hQ7rW0X9_NkSi8Cw5fF8j6V_K6JzgB3y2Hq9LpL9-Wo
#
# Add it to your .env (or your secrets manager):
#
#     APP_KEY=hQ7rW0X9_NkSi8Cw5fF8j6V_K6JzgB3y2Hq9LpL9-Wo
```

Or pipe straight into the environment:

```bash
echo "APP_KEY=$(suprnova key:generate --show)" >> .env
```

### Generating a key in code

`EncryptionKey::try_generate` draws 32 bytes from the operating system
random source. It returns `Err` when the source refuses, for example in a
sandbox that blocks the call, so a request handler or a job keeps running.
`Crypt::try_generate_key` does the same under the name of Laravel's
`Crypt::generateKey`:

```rust
use suprnova::{Crypt, EncryptionKey};

let key = EncryptionKey::try_generate()?;
println!("APP_KEY={}", key.to_base64());

let tenant_key = Crypt::try_generate_key()?;
```

Neither function changes the key `Crypt` holds. That key is the one
`APP_KEY` named at boot. `EncryptionKey::generate` panics when the source
refuses; use it only in tests and one-off commands.

### Boot-time validation - fail closed

`Server::from_config` validates `APP_KEY` **on every boot**, not just
the first one. The rules:

| Environment | `APP_KEY` unset | `APP_KEY` malformed |
|---|---|---|
| `local`, `development`, `testing` | Generated transient key, warn in logs | Hard error - fails boot |
| `staging`, `production`, anything else | Hard error - fails boot | Hard error - fails boot |

A malformed key is **always** a hard error, even in `local` - better to
fail boot than mask a typo. A `Custom` environment value the framework
doesn't recognise (e.g. `APP_ENV=k8s`) is treated as production-like:
no `APP_KEY`, no boot.

The diagnostic points at the fix:

```
APP_KEY is required when APP_ENV=production. Generate one with
`suprnova key:generate` and set it in your environment (e.g. .env
or your secrets manager). Suprnova refuses to boot without an
encryption key outside of local/development/testing because session
cookies and pagination cursors would otherwise be unsigned and
forgeable.
```

## `CryptPurpose` - domain separation through AAD

Every `Crypt::*` call takes a `CryptPurpose`. The variant maps to a
stable byte label that is bound into the AES-GCM authentication tag
as Associated Data (AAD):

```rust
pub enum CryptPurpose {
    Cookie,            // bound to the cookie name, see below
    Cursor,            // suprnova:cursor:v1
    TwoFactorSecret,   // suprnova:2fa:secret:v1
    TwoFactorRecovery, // suprnova:2fa:recovery:v1
    Cast,              // suprnova:cast:v1
}
```

The label is **not** stored in the wire. GCM mixes the AAD into the
authentication tag without including it in the ciphertext, so:

- The on-wire format is unchanged - still
  `base64(nonce || ciphertext || tag)`.
- A wire produced under one purpose is **rejected** by
  any decrypt call that supplies a different purpose. The GCM tag
  check fails before any post-decrypt parsing runs.
- Adding a new surface (a future queue payload encryption, an
  encrypted file header) means adding a new variant - not changing
  the wire format.

```rust
use suprnova::{Crypt, CryptPurpose};

let wire = Crypt::encrypt_string(CryptPurpose::Cast, "ssn-123-45-6789")?;

// Same key, same wire, different purpose - fails.
let result = Crypt::decrypt_string(CryptPurpose::Cursor, &wire);
assert!(result.is_err());

// Same purpose - succeeds.
let plain = Crypt::decrypt_string(CryptPurpose::Cast, &wire)?;
```

`CryptPurpose::Cookie` is the one purpose that has no context-free form. A
cookie value is always bound to the name of its cookie (see
[Cookie-name-bound AAD](#cookie-name-bound-aad)). `Crypt::encrypt_string` and
`Crypt::encrypt` with `CryptPurpose::Cookie` return an error, and so do
`Crypt::decrypt_string`, `Crypt::decrypt_string_with_origin`, `Crypt::decrypt`
and `Crypt::decrypt_with_origin`. For a cookie, use `Cookie::encrypted` and
`Cookie::read_encrypted_for`, or the `_for` functions with the cookie name.

### Why Suprnova diverges

Laravel's `Crypt::encryptString` does not take a purpose. The single
`APP_KEY` is reused across cookies, signed URLs, signed expiry
tokens, and any user calls to `Crypt::encrypt`, with no domain
separation at the crypto layer. If two surfaces happen to accept
ciphertext of the same plaintext shape, a value minted for one
surface can be replayed into the other.

Suprnova reuses the same `APP_KEY` for the same reason - operators
manage one secret - but binds each surface to its own AAD label.
Cross-surface ciphertext replay is rejected at the GCM tag check,
before any parsing runs. The cost to the caller is one extra enum
parameter; the gain is a property the wire format alone cannot break.

The version suffix on each label gives every surface its own label. A change
of the label of one surface invalidates the old ciphertext of that surface
**only** and leaves cursors, 2FA secrets, and cast columns alone.

## Cookie-name-bound AAD

An encrypted cookie is bound to its logical name.
`Cookie::encrypted("suprnova_session", value)` binds
`suprnova:cookie:v2:suprnova_session` into the GCM tag, and
`Cookie::read_encrypted_for("suprnova_session", wire)` supplies the same
context on the way back:

```rust
use suprnova::Cookie;

let cookie = Cookie::encrypted("suprnova_session", "session-id")?;
let wire = cookie.value().to_string();
assert_eq!(
    Cookie::read_encrypted_for("suprnova_session", &wire)?,
    "session-id"
);
assert!(Cookie::read_encrypted_for("other_cookie", &wire).is_err());
```

The bound name is logical, not rendered. A later `__Host-` or `__Secure-`
wire-name prefix therefore does not change the AAD and does not log users out.
The prefix is a browser and header concern; the cookie name is the
cryptographic domain.

### A cookie opens under its own name and in no other way

The wire format has no version byte and no name. The reader supplies the name,
and the GCM tag check fails when it is not the name the writer used. A value
from one cookie therefore does not open in another cookie, and a value that was
written without a cookie name does not open in any cookie. Both fail with the
same error as a tampered value, and the error quotes neither the plaintext nor
the ciphertext.

Key rotation works for cookies as it does for every other purpose.
`Cookie::read_encrypted_for` tries the name-bound context across the whole key
ring, current key first. A cookie that a previous key wrote opens and reports
`KeyOrigin::Previous`.

The functions that take no name refuse `CryptPurpose::Cookie` before they touch
a key:

```rust,no_run
use suprnova::{Crypt, CryptPurpose};

assert!(Crypt::encrypt_string(CryptPurpose::Cookie, "session-id").is_err());
assert!(Crypt::decrypt_string(CryptPurpose::Cookie, "any-wire").is_err());

// With the name, a cookie value round-trips.
let wire = Crypt::encrypt_string_for(CryptPurpose::Cookie, "suprnova_session", "session-id")?;
let plain = Crypt::decrypt_string_for(CryptPurpose::Cookie, "suprnova_session", &wire)?;
assert_eq!(plain, "session-id");
```

The error names the function to use instead.

A cookie that does not open is a request without that cookie. It is never an
error response:

- The session middleware starts a new session. The user signs in again.
- The remember-me hydration does not sign the user in and clears the cookie.
- The maintenance mode treats the request as one without the bypass cookie, so
  it gets the maintenance response. The operator visits the secret URL again.

A cookie value that was written without a cookie name does not open, so the
users who hold one sign in again.

### Reading `DecryptOrigin`

Three functions return the value and a `DecryptOrigin`. Use them when your
code has to act on where a value came from. They serve the purposes other than
`CryptPurpose::Cookie`, and the two that take no context return an error for a
cookie:

| Function | Reads like |
|---|---|
| `Crypt::decrypt_string_with_origin(purpose, wire)` | `decrypt_string` |
| `Crypt::decrypt_string_for_with_origin(purpose, context, wire)` | `decrypt_string_for` |
| `Crypt::decrypt_with_origin::<T>(purpose, wire)` | `decrypt` |

Each returns `Result<(value, DecryptOrigin), FrameworkError>` and has the
errors of the function it reads like. None of them logs a rotation warning,
because you have the origin.

`DecryptOrigin` has two independent axes. `DecryptOrigin`, `KeyOrigin` and
`AadVersion` are exported from the crate root.

- `origin.key = KeyOrigin::Previous(index)` means the value still depends on
  `APP_KEY_PREVIOUS[index]`. Re-encrypt the value under the current key and
  remove that previous key only after the rotation tail is gone.
- `origin.aad = AadVersion::Legacy` means a `_for` read opened a value that was
  written without a context. That read falls back to the additional data
  without a name for the purposes that store values which do not expire as a
  cookie does, such as a cast or a cursor. Read the value with
  `decrypt_string_for_with_origin` and write it again with
  `encrypt_string_for`. A cookie never reports `Legacy`: it opens under its
  name or not at all.

Both axes can be stale together. `origin.needs_reencryption()` returns `true`
when either axis is stale, so you do not have to check both.

### Re-encrypting a value after a rotation

The job that ends a rotation reads every stored value, writes again the ones
that need it, and removes the previous key when none is left:

```rust,no_run
use suprnova::{Crypt, CryptPurpose, FrameworkError};

fn refresh(stored: &str) -> Result<Option<String>, FrameworkError> {
    let (plain, origin) = Crypt::decrypt_string_with_origin(CryptPurpose::Cast, stored)?;
    if origin.needs_reencryption() {
        return Ok(Some(Crypt::encrypt_string(CryptPurpose::Cast, &plain)?));
    }
    Ok(None)
}
```

Write the value again with the function that pairs with the one you read
it with:

- A value read with `decrypt_string_for_with_origin` is written by
  `Crypt::encrypt_string_for` with the same context. That gives it the
  current key and the current label.
- `Crypt::encrypt_string` writes the label without a context. Read that value
  with a context again and it matches the legacy label, so
  `needs_reencryption()` stays `true` and a job that runs until it is
  `false` never ends.

The plain `decrypt_string` logs a warning for each stale axis and returns the
value alone. The warning is for a person who reads the log. A program cannot
act on it.

## The two encrypt / decrypt pairs

There are two shapes for two use cases.

### Strings - `encrypt_string` / `decrypt_string`

For UTF-8 strings:

```rust
use suprnova::{Crypt, CryptPurpose};

let wire: String =
    Crypt::encrypt_string(CryptPurpose::Cast, "alice@example.com")?;

let plain: String =
    Crypt::decrypt_string(CryptPurpose::Cast, &wire)?;
```

The decrypt path returns a `String` - non-UTF-8 bytes (which a normal
encrypt run can't produce, but which a corrupt or attacker-supplied
wire might) surface as a clear `FrameworkError::Internal`.

### Anything `Serialize` - `encrypt` / `decrypt`

For structured values, JSON-encode-then-encrypt in one call:

```rust
use serde::{Serialize, Deserialize};
use suprnova::{Crypt, CryptPurpose};

#[derive(Serialize, Deserialize)]
struct Secret {
    api_key: String,
    last_rotated_at: chrono::DateTime<chrono::Utc>,
}

let value = Secret {
    api_key: "sk_live_…".into(),
    last_rotated_at: chrono::Utc::now(),
};

let wire = Crypt::encrypt(CryptPurpose::Cast, &value)?;
let round_trip: Secret = Crypt::decrypt(CryptPurpose::Cast, &wire)?;
```

The wire format is the same - base64 over `nonce || ciphertext ||
tag` - the only difference is that the plaintext is `serde_json` bytes
of `value` instead of UTF-8 of a string. Use this for any record
shape: a config blob, a session payload, a queue argument tuple.

### `appears_encrypted` - shape check, not tamper check

For middleware that needs to skip already-encrypted values on the
egress pass (matching Laravel's `EncryptCookies` behaviour),
`Crypt::appears_encrypted` does a cheap heuristic check:

```rust
if Crypt::appears_encrypted(cookie_value) {
    // pass through - already wrapped
} else {
    // encrypt before sending
}
```

It returns `true` when the input decodes as URL-safe base64 and the
decoded length is at least 28 bytes (nonce + tag). It never calls
into AES-GCM, so it **cannot** distinguish a valid ciphertext from
random bytes of the right shape. Callers that need authentication
must call `decrypt_string` / `decrypt` and handle the error.

## An encrypter with its own key

`Crypt` holds one key ring for the whole process, sealed at boot from
`APP_KEY`. Some values belong under another key: a tenant's own key, a key
you share with one other service, or a key you read from a secrets manager
after boot. For these, build an `Encrypter`:

```rust
use suprnova::{CryptPurpose, EncryptionKey, Encrypter};

// A key you keep per tenant, for example in a secrets manager.
let key = EncryptionKey::from_base64(&tenant_key_base64)?;
let encrypter = Encrypter::new(key);

let wire = encrypter.encrypt_string_for(CryptPurpose::Cast, "tenants.api_token", "tok_123")?;
let plain = encrypter.decrypt_string_for(CryptPurpose::Cast, "tenants.api_token", &wire)?;
assert_eq!(plain, "tok_123");
```

`Encrypter::new` takes the key and nothing else. It installs nothing and
reads no environment, so it works before boot, in a test, and next to a
`Crypt` that holds another key. Building one never changes what `Crypt`
encrypts or decrypts.

The four methods take the arguments of their `Crypt` counterparts and
write the same payload:

| `Encrypter` method | Reads like |
|---|---|
| `encrypt_string_for(purpose, context, plaintext)` | `Crypt::encrypt_string_for` |
| `decrypt_string_for(purpose, context, wire)` | `Crypt::decrypt_string_for` |
| `encrypt(purpose, &value)` | `Crypt::encrypt` |
| `decrypt::<T>(purpose, wire)` | `Crypt::decrypt` |

Because the payload is the same, a value `Crypt` wrote under a key opens
with `Encrypter::new` of that key, and a value an encrypter of the current
`APP_KEY` wrote opens with `Crypt`. A value opens only under the key, the
purpose and the context it was written with.

The rules of `Crypt` hold here too:

- `decrypt_string_for` makes the two tries `Crypt` makes. For every purpose
  but `CryptPurpose::Cookie` it opens a value written without a context.
  It logs no warning for that value; write it again with
  `encrypt_string_for`.
- `encrypt` and `decrypt` refuse `CryptPurpose::Cookie`. Use the `_for`
  pair with the cookie name.
- An encrypter has one key and no previous keys. Key rotation stays with
  `Crypt` and `APP_KEY_PREVIOUS`.
- The errors are the ones in [Failure modes](#failure-modes---what-errors-look-like),
  with `Encrypter` in place of `Crypt`. There is no "not initialized"
  error.
- `format!("{encrypter:?}")` prints the key as `[REDACTED]`.

The key is always 32 bytes. `EncryptionKey::from_base64` refuses a value
that decodes to any other length, a 16-byte key included, so no weaker key
reaches the cipher.

### Why Suprnova diverges

Laravel's `new Encrypter($key, $cipher)` takes a cipher name and accepts
AES-128 and AES-256, in CBC and GCM modes. Suprnova's `Encrypter` has one
cipher, AES-256-GCM, and no cipher argument, so no configuration can move a
value to a weaker cipher or a shorter key.

Each call takes a `CryptPurpose`, and the string pair takes a context,
because the encrypter writes the purpose-bound payload of `Crypt`. That is
what lets the two read each other's values. The payload is not Laravel's
JSON payload of `iv`, `value`, `mac` and `tag`, so an `Encrypter` does not
read a value that Laravel's encrypter wrote.

Laravel's `Encrypter::generateKey` throws when `random_bytes` fails.
`EncryptionKey::try_generate` and `Crypt::try_generate_key` return the
failure as an error.

## Key rotation - the keyring

Suprnova supports zero-downtime rotation through a key *ring*: one
current key (used for every new encryption) plus an ordered list of
previous keys (tried as fallbacks on decrypt). You roll `APP_KEY`
without re-encrypting every column in lock-step.

Set `APP_KEY_PREVIOUS` to a comma-separated list of base64 keys,
oldest to newest:

```env
APP_KEY=<new key>
APP_KEY_PREVIOUS=<old key>
# Or for multi-step rotation (older → newer):
APP_KEY_PREVIOUS=<oldest>,<middle>,<previous>
```

`APP_KEY_PREVIOUS` is Suprnova's canonical name.
`APP_PREVIOUS_KEYS` is accepted as a Laravel-compatible alias. If both
variables are set, `APP_KEY_PREVIOUS` wins. When their trimmed values
differ, boot logs a warning and ignores `APP_PREVIOUS_KEYS`.

Encryption **always** uses the current key. Decryption tries the
current key first; if that fails, each previous key is tried in
order. On a previous-key hit, `Crypt` emits a `tracing::warn!`:

```
WARN previous_index=0 Crypt decrypted a value with APP_KEY_PREVIOUS[0];
re-encrypt (load + save) this row under the current APP_KEY and remove
the corresponding APP_KEY_PREVIOUS entry once the rotation completes.
```

The log line deliberately excludes both the plaintext and the
ciphertext - only the fact-of-rotation plus an actionable hint
travels. Operators running a log search for `APP_KEY_PREVIOUS` land
on every column still depending on an old key.

### The cap - `MAX_PREVIOUS_KEYS = 8`

`APP_KEY_PREVIOUS` is capped at 8 entries. A realistic rotation chain
is 1-3 entries (one in-flight roll, maybe one stalled prior roll the
operator hasn't cleaned up); 8 leaves generous headroom. Past the
cap, boot **fails loudly** with a diagnostic that names both the
count and the cap:

```
APP_KEY_PREVIOUS holds 12 keys; the maximum is 8. A realistic
rotation chain is 1-3 entries - a longer list is almost always a
config-templating accident. Trim the list to the keys still needed
for in-flight rotation; once a re-encrypt job has migrated every
row off an old key, drop that entry.
```

Silent truncation would drop a key the operator may still depend on,
leaving columns undecryptable with no diagnostic. The hard cap is
intentional.

Empty entries are tolerated:
`APP_KEY_PREVIOUS=,,,old1,,,old2,,,` parses to two real keys. A
malformed entry (typo, wrong length, bad base64) is a hard error -
half-rotated secrets fail boot, not silently drop a fallback.

### Rotation procedure

```bash
# 1. Mint a new key.
NEW=$(suprnova key:generate --show)

# 2. Move the current key to APP_KEY_PREVIOUS, install the new one.
#    Edit your .env or secrets manager:
#
#      APP_KEY_PREVIOUS=<old_value_of_APP_KEY>
#      APP_KEY=<NEW>

# 3. Deploy. New writes use the new key; existing rows continue
#    to decrypt via the previous-key fallback. Logs identify
#    columns still on the old key.

# 4. Run a re-encrypt pass. For each model with encrypted casts:
#
#      User::query().chunk(500, |batch| async {
#          for mut row in batch { row.save().await?; }
#          Ok(())
#      }).await?;
#
#    `Cast::to_storage` always uses the current key, so a no-op
#    load-then-save migrates the row.

# 5. Once warnings stop appearing in logs, drop APP_KEY_PREVIOUS
#    and deploy again.
```

The whole procedure is online - at no point is there a window where
new requests fail.

### Observing the ring

For operator dashboards or health checks:

```rust
use suprnova::Crypt;

if Crypt::has_previous_keys() {
    let n = Crypt::previous_key_count();
    tracing::info!(previous_keys = n, "APP_KEY rotation in progress");
}
```

The key bytes themselves are never accessible from public API.
`EncryptionKey`'s `Debug` impl prints `"[REDACTED]"`, and there is no
accessor that surfaces a raw key outside of the crate.

## Eloquent integration - the `AsEncrypted*` casts

Application-level encryption is most useful at the column boundary.
The `AsEncrypted*` family of casts wraps `Crypt::encrypt_string` so
your model fields stay typed plaintext at runtime and ciphertext at
rest:

```rust
use suprnova::{model, Model};
use suprnova::eloquent::casts::{
    AsEncrypted, AsEncryptedArray, AsEncryptedObject, AsEncryptedCollection,
};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Clone)]
pub struct ApiKey {
    pub provider: String,
    pub secret: String,
}

#[model(table = "users", casts = {
    api_token     = AsEncrypted,
    api_keys      = AsEncryptedArray<ApiKey>,
    billing       = AsEncryptedObject<BillingDetails>,
    ssh_keys      = AsEncryptedCollection<String>,
})]
pub struct User {
    pub id: i64,
    pub api_token: String,
    pub api_keys: Vec<ApiKey>,
    pub billing: BillingDetails,
    pub ssh_keys: suprnova::eloquent::Collection<String>,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

| Cast | Runtime type | Storage shape |
|---|---|---|
| `AsEncrypted` | `String` | encrypted string |
| `AsEncryptedArray<T>` | `Vec<T>` | JSON → encrypted string |
| `AsEncryptedObject<T>` | `T` | JSON → encrypted string |
| `AsEncryptedCollection<T>` | `Collection<T>` | JSON → encrypted string |

All four route through `CryptPurpose::Cast`. A wire minted by an
encrypted cast is rejected by any code that tries to decrypt it as a
cookie or cursor - even though `APP_KEY` is the same, the AAD label
differs.

For the full cast surface, table of failure modes, and re-encryption
recipes see [eloquent.md](eloquent.md). The encryption mechanics are
the same as the facade above - the cast is sugar that runs
`Crypt::encrypt_string(CryptPurpose::Cast, …)` on the storage
boundary.

### Encryption vs hashing - pick the right tool

`AsEncrypted` is **reversible**. The plaintext can be recovered with
`APP_KEY`. Use it for data your application needs to read back: API
tokens you display in a settings page, third-party secrets you
forward to upstream services, addresses you ship orders to.

For data your application only ever needs to *verify* - passwords,
API key prefixes you compare against incoming tokens - use a hash
instead. Hashes are one-way: there is no plaintext to leak even if
`APP_KEY` is compromised. See [hashing.md](hashing.md) for the
Bcrypt / Argon2id facade and the `AsHashed` cast.

## Where else `Crypt` is used inside the framework

You don't have to do anything to opt into these - they are wired
automatically once `APP_KEY` is configured.

- **Encrypted cookies** - `Cookie::encrypted(...)` /
  `Cookie::read_encrypted_for(...)` use `CryptPurpose::Cookie`. The
  session cookie, the remember-me cookie, and the maintenance-mode
  bypass cookie all ride this. See [responses.md](responses.md) and
  [session.md](session.md).
- **Cursor pagination** - `CursorPaginator` encodes the cursor under
  `CryptPurpose::Cursor` so the on-wire `?cursor=…` value cannot be
  forged or replayed across surfaces. See
  [eloquent.md](eloquent.md#cursor-paginate-keyset).
- **2FA secrets** - the encrypted base32 TOTP secret on
  `two_factor_authentications.secret` uses
  `CryptPurpose::TwoFactorSecret`; recovery codes use
  `CryptPurpose::TwoFactorRecovery`. Distinct purposes prevent
  within-row cross-column ciphertext replay. See
  [auth-flows.md](auth-flows.md).
- **HMAC-derived signing** - signed URLs and password-reset tokens
  derive an HMAC key from `APP_KEY` rather than encrypting under it.
  The raw key bytes are not exported; the derivation lives inside
  the framework. See [routing.md](routing.md#signed-urls).

## Testing with `Crypt`

The `Crypt` facade is `OnceLock`-backed, so the first installer in a
test binary wins. The testing helpers handle the boilerplate:

```rust
use suprnova::testing::install_test_encryption_key;

#[tokio::test]
async fn encrypts_and_round_trips() {
    install_test_encryption_key(); // idempotent - safe to call from every test

    let wire = suprnova::Crypt::encrypt_string(
        suprnova::CryptPurpose::Cast,
        "hello",
    ).unwrap();

    let plain = suprnova::Crypt::decrypt_string(
        suprnova::CryptPurpose::Cast,
        &wire,
    ).unwrap();

    assert_eq!(plain, "hello");
}
```

The test key is deterministic, so tests can decrypt stable fixtures and
exercise rotation against a known key. Ciphertext strings must not be
compared for equality across calls or runs: every encryption still uses a
fresh random nonce.

For rotation tests, install a keyring directly and mint historical
ciphertext with `suprnova::crypto::testing::encrypt_string_under`. The
function is compiled with the `testing` feature:

```rust
use suprnova::testing::install_test_encryption_keyring;
use suprnova::EncryptionKey;

let current = EncryptionKey::generate();
let old = EncryptionKey::generate();

install_test_encryption_keyring(current, vec![old.clone()]);

// Simulate a value written when `old` was current.
let legacy_wire = suprnova::crypto::testing::encrypt_string_under(
    &old,
    suprnova::CryptPurpose::Cast,
    "legacy",
).unwrap();

// The current ring decrypts it via the previous-key fallback and
// reports the origin.
let (plain, origin) = suprnova::Crypt::decrypt_string_with_origin(
    suprnova::CryptPurpose::Cast,
    &legacy_wire,
).unwrap();

assert_eq!(plain, "legacy");
assert!(origin.needs_reencryption());
```

`encrypt_string_for_under(key, purpose, context, plaintext)` is the same for a
value that `encrypt_string_for` writes. Both helpers are compiled out of
production binaries when the `testing` feature is disabled
(`default-features = false`).

## Failure modes - what errors look like

Every fallible `Crypt::*` call returns `Result<_, FrameworkError>`.
The six errors you can see:

| Cause | Where | Surface |
|---|---|---|
| `Crypt` not initialised | Any call before boot | `FrameworkError::Internal("Crypt is not initialized - set APP_KEY before serving")` |
| Wire is not valid base64 | `decrypt_string`, `decrypt` | `FrameworkError::Internal("Crypt base64 decode failed: …")` |
| Wire too short (< 28 bytes) | `decrypt_string`, `decrypt` | `FrameworkError::Internal("AEAD wire too short …")` |
| Tag check fails - wrong key, wrong AAD, tampered bytes | `decrypt_string`, `decrypt` | `FrameworkError::Internal("AEAD decrypt failed: …")` |
| JSON encode / decode fails | `encrypt`, `decrypt` | `FrameworkError::Internal("Crypt JSON {encode,decode} failed: …")` |
| The operating system random source refuses | `EncryptionKey::try_generate`, `Crypt::try_generate_key` | `FrameworkError::Internal("the operating system random source refused to supply the 32 bytes of an encryption key: …")` |

There is no silent fallback to garbage. A wrong key against an
existing ciphertext is always a hard error, both at the facade
level and at the cast level. This matches Laravel's `Encrypter`
behaviour and is the property that lets rotation be safe: a missed
column would surface immediately, not return plausible-but-wrong
plaintext.

A decode error names the kind of mistake and its position, for example
`Crypt JSON decode failed: the value is not JSON (line 1, column 3)`. It
never quotes the decrypted value, because an error is logged and can reach a
client.

When a previous key successfully decrypts a wire, the call still
returns `Ok(...)` - but the `tracing::warn!` line fires alongside,
so log-driven alerting catches the rotation tail before
`APP_KEY_PREVIOUS` is removed. To act on it in code, read the origin with
[`decrypt_string_with_origin`](#reading-decryptorigin).

## Next

- [configuration.md](configuration.md) - `APP_KEY`, `APP_ENV`, and
  the rest of the boot environment.
- [eloquent.md](eloquent.md) - the `AsEncrypted*` casts, the full
  cast table, and rotation procedure for model columns.
- [hashing.md](hashing.md) - one-way alternative when you need to
  *verify* not *recover*; bcrypt and Argon2id facades plus
  `AsHashed`.
- [auth-flows.md](auth-flows.md) - 2FA secret and recovery code
  storage, which ride `Crypt` under their own purposes.
- [session.md](session.md) - the session cookie, encrypted and
  signed by `Crypt` via `CryptPurpose::Cookie`.


---

<!-- /docs/hashing -->

# Hashing

The `suprnova::hashing` module is the framework's password hashing surface, with three first-class drivers - **bcrypt** (default, matches Laravel), **Argon2i** (memory-hard, side-channel-resistant), and **Argon2id** (OWASP 2024 recommendation). Use it when storing user passwords, hashing remember-me verifier tokens, or anywhere a one-way function is the right primitive. Driver selection is env-driven, and the facade is algorithm-aware end-to-end (`info`, `is_hashed`, `needs_rehash`, `verify`) so a stored bcrypt hash still verifies after you flip `HASH_DRIVER=argon2id`.

## Overview

```rust
use suprnova::hashing;

// Async (preferred inside Tokio request handlers - runs the CPU-bound
// hash on spawn_blocking so the worker thread stays free):
let hashed = hashing::hash_async("my_password").await?;
let valid = hashing::verify_async("my_password", &hashed).await?;

// Sync (tests, CLI tools, non-async contexts):
let hashed = hashing::hash("my_password")?;
let valid = hashing::verify("my_password", &hashed)?;
```

The async functions run on the blocking pool under one process-wide limit, `HASH_MAX_CONCURRENCY`, which Magnetar's sign-in hashing shares. One Argon2id hash under the defaults holds 64 MiB, so without a limit a burst of sign-ins could hold up to the pool's 512 threads and 32 GiB at once. With it, the burst holds at most the limit times one hash's memory, and the rest waits as tasks that hold no thread. A hash keeps its place under the limit until it returns, even when its caller stops waiting.

The free-function facade reads the active driver from `HASH_DRIVER` (or falls back to bcrypt). For explicit-driver calls, construct the driver type directly and pass it to `hash_with` / `verify_with` / `needs_rehash_with`.

## Configuration

| Variable | Description | Default | Range |
|----------|-------------|---------|-------|
| `HASH_DRIVER` | Active algorithm | `bcrypt` | `bcrypt` \| `argon` \| `argon2i` \| `argon2id` \| a name registered with `hashing::extend` |
| `HASH_ROUNDS` | Bcrypt cost factor | `12` | `4..=31` (bcrypt only) |
| `HASH_MEMORY` | Argon memory cost in KiB | `65536` (64 MiB) | `>= 8` (argon only) |
| `HASH_TIME` | Argon time iterations | `4` | `>= 1` (argon only) |
| `ARGON_TIME` | Laravel's name for the Argon time, read when `HASH_TIME` is unset | unset | `>= 1` (argon only) |
| `HASH_THREADS` | Argon parallelism / lanes | `1` | `>= 1` (argon only) |
| `HASH_VERIFY` | When true, `verify()` rejects cross-algorithm hashes | `false` | `true` / `false` |
| `HASH_MAX_CONCURRENCY` | Most password hashes running at once in the process, the async functions and Magnetar together | the host's available parallelism | whole number `>= 1`; blank is unset |

Misconfiguration (bad value, out-of-range parameter, a `HASH_DRIVER` that names neither an algorithm nor a registered driver) surfaces as a `FrameworkError::param` at the first call to `hash` / `verify` / `needs_rehash` - not as a silent default.

A Laravel `.env` that sets `ARGON_TIME` keeps working: Suprnova reads it as the Argon time when `HASH_TIME` is unset, under the same minimum of `1`. When both are set, `HASH_TIME` wins.

### Example `.env` for argon2id

```env
HASH_DRIVER=argon2id
HASH_MEMORY=65536
HASH_TIME=4
HASH_THREADS=1
```

### Why Suprnova's Argon2 defaults are stronger than Laravel's

| Param | Laravel default | Suprnova default | Source |
|-------|-----------------|------------------|--------|
| Memory | 1 024 KiB (1 MiB) | 65 536 KiB (64 MiB) | OWASP 2024 |
| Time | 2 iterations | 4 iterations | OWASP 2024 |
| Threads | 2 | 1 | OWASP 2024 / libsodium-aligned |

Laravel's defaults assume PHP's request-per-process model - a worker can only spend so much on each password hash before the box is full. Tokio's `spawn_blocking` lets Suprnova hand the hash off to a blocking thread pool without freezing the request loop, so the OWASP 2024 numbers are realistic on real production hardware.

## Drivers

### Bcrypt (default)

```rust
use suprnova::hashing::{BcryptHasher, BcryptOptions, hash_with, verify_with};

let driver = BcryptHasher::new(BcryptOptions { rounds: 14 });
let hashed = hash_with(&driver, "my_password")?;
assert!(verify_with(&driver, "my_password", &hashed)?);
```

Bcrypt has a **72-byte block-size cap** on the password input - the underlying primitive silently truncates longer inputs, which means two distinct passphrases sharing their first 72 bytes hash to the same value. Suprnova rejects an oversized password up-front when it hashes one: the framework's bcrypt path errors on `hash()`. `verify()` accepts a password of any length and judges it on its first 72 bytes, as PHP's `password_verify` does, so a user whose long password a Laravel application hashed still signs in. Argon2 has no such ceiling.

An application that shares its database with a Laravel application turns on `LARAVEL_SHARED_DATABASE`. Then `hash()` writes `$2y$` bcrypt hashes, which Laravel's hasher accepts with `HASH_VERIFY=true`, and a valid sign-in rewrites a `$2b$` or Argon2id hash as `$2y$`. See [Running on a Laravel Database](laravel-database.md).

The bcrypt cap is exposed as `suprnova::hashing::MAX_BCRYPT_PASSWORD_BYTES` (71 - the usable limit after the bcrypt null terminator).

### Argon2id (OWASP 2024 recommendation)

```rust
use suprnova::hashing::{Argon2idHasher, Argon2Options, hash_with, verify_with};

let driver = Argon2idHasher::new(Argon2Options {
    memory: 65_536,  // 64 MiB
    time: 4,
    threads: 1,
})?;

let hashed = hash_with(&driver, "my_password")?;
assert!(verify_with(&driver, "my_password", &hashed)?);

// Argon2 accepts arbitrary-length passphrases - the bcrypt 72-byte cap
// doesn't apply.
let long = "x".repeat(500);
let h = hash_with(&driver, &long)?;
assert!(verify_with(&driver, &long, &h)?);
```

### Argon2i

Same shape as Argon2id; `Argon2iHasher::new(opts)`. Use Argon2id for new projects - Argon2i is supported for parity but Argon2id is the modern recommendation.

### Argon options for one call

Laravel passes options to one hash, as in `Hash::make($password, ['time' => 3])`. In Suprnova, build an `Argon2idHasher` from `Argon2Options` and hash with `hash_with`, as the Argon2id example above does. The options apply to that call only, under the minimums `HASH_TIME`, `HASH_MEMORY`, and `HASH_THREADS` have, and the configured driver stays as it is.

## Registering a driver (`extend`)

`hashing::extend(name, factory)` registers a driver of your own under a name, and `HASH_DRIVER=<name>` selects it, as Laravel's `Hash::extend` does. The factory is a closure that returns a `Box<dyn Hasher>`. Use it for a peppered hasher, a hasher that wraps a key service, or an algorithm the framework doesn't ship.

```rust
use suprnova::hashing::{self, BcryptHasher, BcryptOptions, Hasher};

// At boot, before the first hash. With `HASH_DRIVER=strong-bcrypt`, the
// facade hashes with this driver.
hashing::extend("strong-bcrypt", || {
    Ok(Box::new(BcryptHasher::new(BcryptOptions { rounds: 14 })) as Box<dyn Hasher>)
})?;

let hashed = hashing::hash_async("my_password").await?;
```

The factory runs once, when the facade first resolves its driver, and only when `HASH_DRIVER` names it. It takes no arguments, so the algorithm settings in the environment don't reach it; read what your driver needs inside the closure. The cross-algorithm gate follows the driver's own `verify_algorithm()`, not `HASH_VERIFY`, and compares a stored hash's algorithm with the driver's `algorithm()`. `verify` still dispatches on the stored hash's algorithm, and hands a hash in no recognised algorithm to your driver.

`extend` returns an error and registers nothing when:

- The name is a built-in algorithm's (`bcrypt`, `argon`, `argon2i`, `argon2id`, in any case), or blank, or has surrounding whitespace.
- A driver is already registered under the name.
- The facade has already resolved its driver, through a hash, a verify, a rehash check, or `set_default_driver`. A registration could no longer take effect.

`HASH_DRIVER` matches a registered name exactly, case included. A `HASH_DRIVER` that names neither a built-in algorithm nor a registered driver fails with `FrameworkError::param`; the facade never falls back to bcrypt. With `HASH_DRIVER` unset, the default driver stays bcrypt, whatever you register.

### Why Suprnova diverges

Laravel's `extend` replaces a driver registered under the same name, and accepts a registration at any time. Suprnova refuses both. The facade builds its driver once per process, so a late registration would do nothing, and an error at boot says so. Two packages that register the same name would otherwise swap each other's hasher in silence, which changes how every password is stored.

## Bcrypt with an explicit cost (`hash_with_cost`)

`hash_with_cost(password, cost)` and `hash_with_cost_async(password, cost)` mint a bcrypt hash at a caller-supplied cost factor regardless of `HASH_DRIVER`. Use these when policy or per-tenant config flows a cost into the call site rather than into the process env - for example, a high-security account class that uses cost 14 while the rest of the app runs at the default 12.

```rust
use suprnova::hashing::{hash_with_cost, hash_with_cost_async};

// Sync - tests, CLI tools.
let h = hash_with_cost("my_password", 14)?;

// Async - inside Tokio request handlers.
let h = hash_with_cost_async("my_password", 14).await?;
```

Both entry points reject `cost` outside `MIN_BCRYPT_COST..=MAX_BCRYPT_COST` (`4..=31`) with `FrameworkError::param`, mirroring the env-side `HASH_ROUNDS` validation:

```rust
use suprnova::hashing::{hash_with_cost, MIN_BCRYPT_COST, MAX_BCRYPT_COST};

assert!(hash_with_cost("pw", MIN_BCRYPT_COST - 1).is_err()); // < 4
assert!(hash_with_cost("pw", MAX_BCRYPT_COST + 1).is_err()); // > 31
```

The bounds check matters because each cost increment doubles CPU time. At cost 31 a single bcrypt hash takes hours on commodity hardware - bounds-checking inside the framework keeps a policy/config typo from accidentally pinning a worker thread for the rest of the day. The async variant goes through `spawn_blocking` so even a legitimately high cost doesn't freeze the request loop.

## Algorithm-aware needs_rehash

`needs_rehash` returns `true` when the stored hash should be re-hashed under the active driver. It covers three cases:

1. **Algorithm mismatch** - bcrypt hash stored while `HASH_DRIVER=argon2id` (or vice versa). Triggers a rotation on next successful verify.
2. **Parameter weakness** - bcrypt cost below `HASH_ROUNDS`, or argon `m`/`t`/`p` below `HASH_MEMORY`/`HASH_TIME`/`HASH_THREADS`.
3. **Bcrypt legacy variants** - `$2a$`, `$2x$`, `$2y$` rotate to canonical `$2b$` even at the configured cost.

```rust
if hashing::needs_rehash(&stored_hash) {
    let fresh = hashing::hash_async("plaintext_at_login").await?;
    // Persist `fresh`. Standard Laravel "rehash on successful login"
    // pattern; works across algorithms.
}
```

Malformed input returns `true` - the caller naturally rotates anything it can't parse.

## Hash inspection (`info` + `is_hashed`)

```rust
use suprnova::hashing::{info, is_hashed};

let h = hashing::hash_async("my_password").await?;
let i = info(&h);
println!("algo: {}", i.algo.as_str());
println!("bcrypt cost: {:?}", i.rounds);
println!("argon memory KiB: {:?}", i.memory);

// True for any recognised algorithm hash; false for plaintext / garbage.
assert!(is_hashed(&h));
assert!(!is_hashed("plaintext"));
```

`info().algo` is one of: `Bcrypt`, `Argon2i`, `Argon2id`, `Argon2d` (recognised but never minted), `Unknown`.

`is_hashed` is what the `AsHashed` eloquent cast uses to skip re-hashing an already-hashed column - works across all three drivers, so flipping `HASH_DRIVER` mid-project doesn't cause a hash-of-hash loop on the next save.

## Cross-algorithm verification gate (`HASH_VERIFY`)

By default, `verify()` checks the password against the hash regardless of which algorithm produced the hash - this is what lets legacy bcrypt hashes still verify after you flip `HASH_DRIVER=argon2id` (so you can rotate them on login). Set `HASH_VERIFY=true` once every user is rotated to enforce the active algorithm strictly:

```env
HASH_VERIFY=true
```

With the gate on, `verify()` returns `Ok(false)` for any hash whose algorithm differs from the active driver - same shape as Laravel's `RuntimeException`, but Suprnova returns false rather than throwing because the auth-flow caller expects a `Result<bool>` either way.

While `LARAVEL_SHARED_DATABASE` is on, the gate accepts bcrypt hashes as well as the active driver's: the application then writes bcrypt, and a user whose hash the active driver wrote still signs in, which rewrites the hash as `$2y$`.

## Async vs sync

Both bcrypt at cost 12 (~250 ms) and Argon2id at memory=64 MiB (~80 ms) are intentionally CPU-bound - that's the entire point of slow hashing. Calling the sync `hash` / `verify` directly from a Tokio request handler blocks the worker thread for the whole hash duration, starving other requests on the same worker.

Use the `*_async` siblings inside `async fn` handlers. They wrap the CPU-bound call in `tokio::task::spawn_blocking` so the worker stays free for other requests:

```rust
// GOOD - inside an async handler
let hashed = hashing::hash_async(&form.password).await?;

// BAD - blocks the worker for ~250 ms
let hashed = hashing::hash(&form.password)?;
```

The sync variants are for tests, CLI tools, and other non-async contexts where blocking is fine.

## Eloquent integration: `AsHashed` cast

The `AsHashed` eloquent cast hashes a plaintext field on write using the active driver, and is **idempotent across all drivers** - saving a model whose `password` column already contains a recognised hash (bcrypt or argon) passes the value through unchanged. Without this guard, `User::find(id).await?.save().await?` would hash the existing hash on every save, breaking authentication.

```rust
use suprnova::eloquent::casts::AsHashed;

#[suprnova::model(casts = { password = AsHashed })]
struct User {
    pub password: String,
    // ...
}
```

The idempotence check uses `hashing::is_hashed`, so flipping `HASH_DRIVER` mid-project is safe - both the legacy bcrypt hashes and the fresh argon2id hashes are recognised and skipped on re-save.

## Use with `Auth::attempt`

`Auth::attempt(&credentials)` calls `UserProvider::validate_credentials`, which in turn calls `hashing::verify_async` against the user's stored hash. Verify dispatches on the *stored* hash's algorithm, not the configured driver - so after you flip `HASH_DRIVER=argon2id`, every existing bcrypt hash still verifies, and `needs_rehash` returns `true` so the standard rotate-on-login pattern carries the user base across to the new algorithm one login at a time.

## Overriding the driver in tests

`set_default_driver(Box<dyn Hasher>)` installs a driver programmatically for tests and embedded CLI tools that build the driver without going through `HASH_DRIVER`. It is one-shot - the first call wins, and a second call returns `FrameworkError::internal` rather than swapping the driver mid-process. Use it at suite startup, before any code path resolves the default.

## Next

- [Authentication](authentication.md) - `Auth::attempt`, the user-provider trait, and how hashing integrates with login
- [Auth flows](auth-flows.md) - `PasswordReset::complete` rotates the stored password hash through the active driver; remember-me tokens are hashed before storage via `hash_async`
- [Eloquent](eloquent.md) - `casts = { password = AsHashed }` reference and the broader cast surface
- [Encryption](encryption.md) - two-way authenticated encryption for at-rest data; the complement to one-way hashing
- [Error Model](error-model.md) - what `FrameworkError::param` looks like when a hashing config value is rejected


# Database

---

<!-- /docs/database -->

# Database

Suprnova's database layer wraps SeaORM with a Laravel-shaped `DB` facade:
raw query escapes, a model-less query builder, transactions with
savepoints and retry-on-deadlock, connection registry for read replicas
and shards, and a full observability surface that mirrors Laravel 13's
`DB::listen` / `QueryExecuted` / query log API.

The Eloquent ORM (`use suprnova::eloquent::*`) builds on top of this
layer and lives in [eloquent.md](eloquent.md). When you want a typed
model, go there; when you want a raw query against an unmodeled table
or want to observe every query the framework runs, this is the page.

## Configuration

```rust
use suprnova::{Config, DB, DatabaseConfig};

// In bootstrap.rs
Config::register(DatabaseConfig::from_env());
DB::init().await.expect("DB::init failed");
```

`DatabaseConfig::from_env` reads `DATABASE_URL` and (optionally) the
pool tunables `DB_MAX_CONNECTIONS`, `DB_MIN_CONNECTIONS`,
`DB_CONNECT_TIMEOUT`, `DB_LOGGING`. When `DATABASE_URL` is unset the
config falls back to `sqlite://./database.db` - convenient for
zero-setup development; production boots refuse the fallback via
`validate_for_environment` so you can't accidentally ship a SQLite
file in `APP_ENV=production`.

URL → driver detection:

```text
postgres://user:pass@host/db       → DatabaseType::Postgres
postgresql://user:pass@host/db     → DatabaseType::Postgres
mysql://user:pass@host/db          → DatabaseType::Mysql
mariadb://user:pass@host/db        → DatabaseType::Mysql
sqlite://./file.db                 → DatabaseType::Sqlite
sqlite::memory:                    → DatabaseType::Sqlite
```

A `mariadb://` URL selects the MySQL driver, because MariaDB uses the
MySQL protocol. Wherever a URL reaches the driver, the framework hands it
over with the `mariadb` scheme written as `mysql`: the primary connection,
each named connection and read replica, the migrator, and
`MariaDbVectorDriver::from_url`. Only the scheme changes. `DB::driver_title()`
answers `MariaDB` for a `mariadb://` URL and `MySQL` for a `mysql://` one,
so a MariaDB server reached through `mysql://` reports as MySQL.

### Character set and collation

On a `mysql://` or `mariadb://` URL, `DatabaseConfig` carries a character
set and a collation, as Laravel's `mysql` connection does: `DB_CHARSET`,
`utf8mb4` by default, and `DB_COLLATION`, `utf8mb4_unicode_ci` by default.
A `charset` or `collation` parameter in the URL wins over the variables,
and the builder's `charset` and `collation` win over both. On a Postgres or
SQLite URL both are `None`.

Every connection the pool opens, the default one and each named one, sends
`SET NAMES <charset> COLLATE <collation>`, and every table
`Schema::create` makes takes them as its defaults unless its blueprint
names its own:

```rust
use suprnova::schema::Schema;

Schema::create(manager, "api_tokens", |t| {
    t.id();
    t.string("token").unique();
    // Compare tokens byte by byte.
    t.collation("utf8mb4_bin");
})
.await?;
```

```bash
DATABASE_URL=mysql://app:secret@db.internal/shop?collation=utf8mb4_general_ci
```

A table Suprnova creates then compares and sorts text the way a table
Laravel creates beside it does. Only letters, digits and underscores make
a name; anything else fails the connection or the migration, since the
names reach SQL unquoted.

**Tables created before you upgraded keep the server's default
collation**, `utf8mb4_0900_ai_ci` on MySQL 8, and MySQL refuses to compare
string columns of two collations ("Illegal mix of collations"). If your
tables use the server's default, keep it by setting `DB_COLLATION` to that
collation:

```bash
DB_COLLATION=utf8mb4_0900_ai_ci
```

`SHOW TABLE STATUS` lists each table's collation.

### MySQL semantics on MariaDB

MariaDB 11.8 and later turn `innodb_snapshot_isolation` on by default.
Under it, an `UPDATE`, a `DELETE` or a locking read inside a `REPEATABLE
READ` transaction fails with error 1020, "Record has changed since last
read", when another transaction committed a change to the row after this
transaction's first read. MySQL 8.4 instead waits for the row and works on
its latest committed version. The framework's own concurrency is written
for MySQL's behavior. For example, spending a single-use token, such as an
email verification or password reset link, and advancing the RenderCache
ledger, which every model write does, each read a row and then update it
in one transaction. On MariaDB with the setting on, two of them at once
failed one request with a database error.

So every connection the framework opens to a MySQL or MariaDB server runs
this once, when the pool opens it:

```sql
SET SESSION innodb_snapshot_isolation = OFF
```

That covers the primary connection, each named connection and read
replica, `TestDatabase`, and `MariaDbVectorDriver::from_url`. MySQL, older
MariaDB releases and other MySQL-compatible servers have no such variable
and refuse the statement with error 1193, which the framework takes to mean
there is nothing to turn off: the connection opens as usual and nothing is
logged.

The statement never fails a connection. A MySQL-compatible proxy or
service, such as Vitess, ProxySQL or TiDB, may refuse it with another
error. The connection then opens anyway, keeping the server's own setting,
and the pool logs one warning at `warn` that names
`innodb_snapshot_isolation`. On MariaDB 11.8 and later that means
concurrent transactions behave as the server does on its own, and two at
once can fail one with error 1020. The warning carries the server's error,
never the URL or a credential.

There is no setting to turn this off. The server's global value stays as it
is for every other client, and a pool your application builds and hands to
the framework, through `DbConnection::from_raw` or
`MariaDbVectorDriver::from_pool`, keeps whatever its builder set.

### Pool liveness

A NAT gateway, a load balancer, or a firewall will silently drop a TCP
connection that has been idle too long. The pool does not find out. The
next query on that connection fails, and it fails on a request that had
nothing to do with the outage.

Laravel answers this with libpq's `keepalives`, `keepalives_idle`,
`keepalives_interval` and `keepalives_count` DSN options, which keep the
socket warm. **Those are not reachable from Suprnova.** sqlx 0.9 parses
only `sslmode`, `application_name`, `options` and the statement-cache
size out of a Postgres URL, and carries no TCP keepalive setter at any
layer, so there is nowhere to forward them to.

What Suprnova gives you instead is the pool-side answer: stop trusting
old connections.

```bash
# Close a connection that has been idle for two minutes.
DB_IDLE_TIMEOUT=120
# Recycle every connection after fifteen minutes regardless.
DB_MAX_LIFETIME=900
# Ping a connection before handing it out, but only once it has been
# idle for thirty seconds. Hot connections skip the round trip.
DB_PING_AFTER_IDLE=30
```

Or programmatically:

```rust
Config::register(
    DatabaseConfig::builder()
        .url(std::env::var("DATABASE_URL")?)
        .idle_timeout(120)
        .max_lifetime(900)
        .ping_after_idle(30)
        .build(),
);
```

Every knob is unset by default, which means the pool keeps sqlx's own
defaults: connections close after 600 idle seconds, recycle after 1800
seconds, and are pinged before every checkout. Set
`DB_IDLE_TIMEOUT=0` or `DB_MAX_LIFETIME=0` to turn off that form of
reaping entirely.

`DB_PING_AFTER_IDLE` and `DB_TEST_BEFORE_ACQUIRE` are alternatives, not
a pair: setting a threshold turns the per-checkout ping off, because
running both would ping on every acquire and make the threshold
meaningless.

### Why Suprnova diverges

Keepalives and pool recycling solve the same failure from opposite
ends. Keepalives keep a middlebox from expiring the connection;
recycling accepts that it will and makes sure the pool never hands out
a connection old enough to have been expired. The second is what the
driver stack exposes, and it also covers failures keepalives do not -
a failed-over replica, a rotated credential, a server-side idle
disconnect. If you need the libpq options specifically, that is a
change to sqlx, not to Suprnova.

## Raw queries

The `DB` facade ships the full Laravel 13 raw escape surface. Every
helper goes through the same instrumented executor - every call fires
`QueryExecuted` (see [Observability](#observability)).

Bindings are `sea_orm::Value` - one of the few sea_orm types the
framework intentionally does NOT re-mask, because every value that hits
the wire goes through it. `Value::from(...)` works for every primitive
the database understands.

```rust
use suprnova::DB;
use sea_orm::Value;

// SELECT - all rows as DynamicRow.
let users = DB::select(
    "SELECT * FROM users WHERE active = ?",
    vec![Value::from(true)],
).await?;

// SELECT - first row only.
let alice = DB::select_one(
    "SELECT * FROM users WHERE name = ?",
    vec![Value::from("alice")],
).await?;

// SELECT - first column of first row as a typed value.
let count: i64 = DB::scalar(
    "SELECT COUNT(*) FROM users",
    vec![],
).await?;

// INSERT - returns bool (true when at least one row was affected).
DB::insert(
    "INSERT INTO users (name, active) VALUES (?, ?)",
    vec![Value::from("bob"), Value::from(true)],
).await?;

// UPDATE / DELETE - return the rows-affected count.
let updated = DB::update(
    "UPDATE users SET active = ? WHERE id = ?",
    vec![Value::from(false), Value::from(1)],
).await?;
let deleted = DB::delete(
    "DELETE FROM users WHERE active = ?",
    vec![Value::from(false)],
).await?;

// Any prepared statement with bindings.
DB::statement(
    "UPDATE users SET votes = votes + ? WHERE id = ?",
    vec![Value::from(1), Value::from(42)],
).await?;

// DDL with no bindings - `unprepared` mirrors Laravel's
// `DB::unprepared` for statements (CREATE INDEX, ALTER TABLE, VACUUM)
// that reject placeholder binding.
DB::unprepared("CREATE INDEX idx_users_name ON users(name)").await?;

// affecting_statement is the explicit form used by update/delete
// internally - drop to it directly for ops that don't fit either name
// (e.g. INSERT...ON CONFLICT DO UPDATE).
let affected = DB::affecting_statement(
    "INSERT INTO users (id, name) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET name = excluded.name",
    vec![Value::from(1), Value::from("alice")],
).await?;
```

### Placeholder syntax

`?` for SQLite + MySQL. `$1`, `$2`, ... for Postgres. The active
backend is auto-detected from `DatabaseConfig::url`.

### DynamicRow

Untyped rows materialise as `DynamicRow` - a `serde_json::Map` newtype
with typed accessors:

```rust
for row in users {
    let id: i64 = row.get_int("id")?;
    let name: String = row.get_string("name")?;
    let nickname: Option<String> = row.get_optional_string("nickname")?;
    let score: Option<i64> = row.get_optional_int("score")?;
    // Deserialise an arbitrary T (chrono::DateTime, your own struct, etc.):
    let prefs: UserPrefs = row.get_as("prefs")?;
}
```

`get_*` errors when the column is absent OR null. `get_optional_*`
errors only when absent and returns `Ok(None)` for SQL NULL. The full
accessor list is `get_int` / `get_string` / `get_bool` / `get_float` /
`get_value` / `get_as<T>` plus `get_optional_string` /
`get_optional_int`; for nullable types without a dedicated
`get_optional_*` reach for `get_value` + a `serde_json::Value` match,
or `get_as::<Option<T>>`.

## Model-less query builder - `DB::table`

For ad-hoc queries against tables you haven't bothered to model with
`#[suprnova::model]`, `DB::table(...)` returns a chainable builder
shaped like the Eloquent `Builder<M>` but materialising rows as
`DynamicRow`:

```rust
use suprnova::{DB, attrs};

let rows = DB::table("audit_log")
    .select(["id", "event", "actor_id"])
    .filter("actor_id", 42i64)
    .filter_op("created_at", ">=", "2025-01-01")
    .order_by_desc("id")
    .limit(50)
    .get()
    .await?;

let first = DB::table("audit_log")
    .filter("event", "user.deleted")
    .first()
    .await?;

let count = DB::table("audit_log")
    .filter("actor_id", 42i64)
    .count()
    .await?;

let id = DB::table("audit_log")
    .insert(attrs! { event: "user.created", actor_id: 42 })
    .await?;

let updated = DB::table("audit_log")
    .filter("id", id)
    .update(attrs! { event: "user.created.v2" })
    .await?;

let deleted = DB::table("audit_log")
    .filter("actor_id", 42i64)
    .delete()
    .await?;
```

### Trust boundary on identifiers

Table names, column names, ORDER BY directions, and SQL operators are
interpolated INTO the SQL string verbatim - they are NOT bound as
parameters (SQL doesn't allow placeholder-bound identifiers). Treat
every `impl Into<String>` argument as a TRUSTED literal:

```rust
// Safe - the column name is a constant.
DB::table("users").filter("email", request.email()).get().await?;

// UNSAFE - never splice user input into a column name.
DB::table("users").filter(&request.column_name(), value).get().await?;
```

Values (the right-hand side of `filter` / `filter_op`) ARE bound as
parameters and safe for user input.

The framework enforces a strict allowlist on identifiers
(`[A-Za-z_][A-Za-z0-9_]*` with one optional `schema.` prefix) and
operators (`=`, `<>`, `<`, `<=`, `>`, `>=`, `LIKE`, `NOT LIKE`,
`ILIKE`, `NOT ILIKE`, `IS`, `IS NOT`). Violations error at the I/O
boundary before the SQL string is rendered.

## Full-text search

`where_full_text(columns, text)` searches one or more text columns for
words, on `DB::table` and on the Eloquent builder. `or_where_full_text`
adds the search with `OR`. The text is a bound parameter, so it can come
from the request:

```rust
use suprnova::DB;

let rows = DB::table("articles")
    .where_full_text(["title", "body"], "query builder")
    .get()
    .await?;

let search = request.query_param("q").unwrap_or_default();
let posts = Post::query()
    .filter("status", "draft")
    .or_where_full_text(["title", "body"], search)
    .get()
    .await?;
```

The Eloquent builder also takes the Rust names `filter_full_text` and
`or_filter_full_text`.

Each engine writes its own search:

| Engine | SQL |
| --- | --- |
| MySQL and MariaDB | `MATCH (title, body) AGAINST (? IN NATURAL LANGUAGE MODE)` |
| Postgres | `(to_tsvector('english', title) \|\| to_tsvector('english', body)) @@ plainto_tsquery('english', ?)` |
| SQLite | an error that names SQLite and the call, before any I/O |

MySQL and MariaDB need a `FULLTEXT` index over exactly the columns you
search, or the query fails. Postgres runs the search without an index, and
answers it from a `GIN` index over the same `to_tsvector` expression when
one exists. `Blueprint::full_text` creates the right index on each engine;
see [Full-text indexes](migrations.md#full-text-indexes).

### Search options

The `_with` methods take a `FullTextOptions`: the mode, the Postgres
language, and MySQL's query expansion. They are the options array of
Laravel's `whereFullText`:

```rust
use suprnova::{DB, FullTextMode, FullTextOptions};

let rows = DB::table("articles")
    .where_full_text_with(
        ["title", "body"],
        "\"query builder\" -php",
        FullTextOptions::new()
            .mode(FullTextMode::Websearch)
            .language("english"),
    )
    .get()
    .await?;
```

Each mode renders on the engine that has it. On the other engine the text
is read as natural language, as Laravel does:

| Mode | MySQL and MariaDB | Postgres |
| --- | --- | --- |
| `FullTextMode::NaturalLanguage` (the default) | `IN NATURAL LANGUAGE MODE` | `plainto_tsquery` |
| `FullTextMode::Boolean` | `IN BOOLEAN MODE` | `plainto_tsquery` |
| `FullTextMode::Websearch` | `IN NATURAL LANGUAGE MODE` | `websearch_to_tsquery` |

- `.language(name)` names the Postgres text search configuration, such as
  `simple` or `french`. The default is `english`. Use the language the
  `GIN` index was built with, or Postgres can't use the index. MySQL and
  MariaDB ignore it.
- `.expanded()` adds `WITH QUERY EXPANSION` in natural-language mode on
  MySQL and MariaDB. Boolean mode and Postgres ignore it.

### Why Suprnova diverges

- Laravel replaces a language it doesn't know with `english`. Suprnova
  takes any plain name (letters, digits, and `_`, with an optional
  `schema.` prefix), so a text search configuration you created works.
  Anything else is an error before the query runs, because the name is
  written into the SQL.
- An empty column list is an error. Laravel writes `MATCH ()`, which the
  database refuses.
- Rust has no optional arguments, so the options go to the `_with` forms
  instead of a third argument.

## Transactions

Three entry points, each with the `QueryExecuted` /
`TransactionBeginning` / `TransactionCommitted` /
`TransactionRolledBack` observation hooks wired in.

### Closure form

```rust
use suprnova::DB;

DB::transaction(|_tx| {
    Box::pin(async move {
        let mut alice = User::query().filter("name", "alice").first_or_fail().await?;
        alice.balance -= 30;
        alice.save().await?;

        let mut bob = User::query().filter("name", "bob").first_or_fail().await?;
        bob.balance += 30;
        bob.save().await?;
        Ok::<(), suprnova::FrameworkError>(())
    })
}).await?;
```

Commit on `Ok(_)`. Rollback + propagate the error on `Err(_)`.

An `Err` is not always a rollback. If an
[after-commit](queues.md#after-commit-dispatch) callback fails, the commit has
already landed and is durable; `DB::transaction` still returns `Err`, and the
message reads `after-commit callback failed (the transaction itself
committed): <the callback's error>`. The closure's return value is lost, its
writes are not, and only a deferred dispatch failed. Every registered callback
still runs and the first error is the one you get.
`DB::transaction_with_attempts` never retries that error, however
deadlock-shaped it reads: re-running a closure whose writes are already durable
would apply them twice.

Operations inside the closure automatically pick up the active
transaction via a `tokio::task_local` - you do NOT have to thread a
`&tx` handle through every model call. You can nest `DB::transaction`:
your inner call opens a SeaORM savepoint on the same connection. An
inner error rolls back that savepoint alone, so you can handle the error
and continue your outer transaction. A successful inner call releases
its savepoint; an outer rollback still undoes its rows.

You read your ambient depth with `DB::transaction_level()`: 0 outside
a closure transaction, 1 in its outer closure and 2 in a nested closure.
Manual handles do not install an ambient transaction, so they do not
change this depth.

The closure form is also the only form that can defer work to the commit. A
job whose type declares `Job::after_commit()` (or a dispatch made with
`Queue::push_after_commit`) waits inside this closure and only reaches the
queue driver once the commit succeeds; a rollback discards it. See
[After-commit dispatch](queues.md#after-commit-dispatch).

For typed aggregate or custom SQL that must execute on the same pinned
connection, use the transaction handle directly:

```rust
use sea_orm::{DbBackend, Statement};

DB::transaction(|tx| {
    Box::pin(async move {
        let backend = tx.backend();
        let rows = tx.query_all(Statement::from_string(
            backend,
            "SELECT CAST(COUNT(*) AS BIGINT) AS total FROM orders".to_owned(),
        )).await?;
        let total = rows[0].try_get::<i64>("", "total")?;
        Ok::<_, suprnova::FrameworkError>(total)
    })
}).await?;
```

`query_all` emits normal `QueryExecuted` observations and returns typed
SeaORM `QueryResult` rows. Use bound `Statement::from_sql_and_values` for
dynamic values; do not interpolate untrusted input.

### Retry on deadlock

```rust
DB::transaction_with_attempts(5, |_tx| {
    Box::pin(async move {
        // Same closure body as above. Re-runs from scratch when the
        // database refused the attempt with a deadlock, a lock wait
        // timeout or a serialization failure.
        Ok::<(), suprnova::FrameworkError>(())
    })
}).await?;
```

The database's error code decides whether an attempt runs again: MySQL's
and MariaDB's error numbers 1213 (deadlock), 1205 (lock wait timeout) and
1020 (a row changed after the transaction's first read), and Postgres's
SQLSTATEs 40001 (serialization failure) and 40P01 (deadlock). An error
with any other code is returned at once, even when its message mentions a
deadlock. The code is read from the database error a `FrameworkError`
keeps as its source, as `FrameworkError::from_external(db_err)` does, or,
for a MySQL or MariaDB error that `?` turned into text, from the error
number the driver writes at its front. An error that carries no code, such
as one the closure builds itself, is retried when its message contains
"deadlock" or one of the two SQLSTATEs. A Postgres error turned into text
by `?` carries no code, so only its message decides: a deadlock is retried
and a serialization failure is not; wrap the `DbErr` with
`FrameworkError::from_external` to retry both.

### Manual form

```rust
use suprnova::{DB, attrs};

let tx = DB::begin_transaction().await?;

// Per-model: the `*_with_tx` shims pin one CRUD op to the manual tx.
User::create_with_tx(&tx, attrs! { name: "alice" }).await?;
Order::create_with_tx(&tx, attrs! { user_id: 1, total: 30 }).await?;

// Per-query: `Builder::with_tx(&tx)` pins a builder chain.
let stale = Order::query()
    .filter("status", "pending")
    .with_tx(&tx)
    .get()
    .await?;

if some_condition() {
    tx.rollback().await?;
} else {
    tx.commit().await?;
}
```

Manual mode does NOT install the task-local - every operation that
should run inside the transaction has to opt in, either via
`Builder::with_tx(&tx)` on a chained query or one of the
`Model::*_with_tx` shims (`create_with_tx`, `save_with_tx`,
`delete_with_tx`, etc.). Operations that forget to opt in run against
the global pool and are NOT part of the transaction.

Holding a `Transaction` handle pins one pool connection for its
lifetime; pre-load any rows you need to read BEFORE the
`begin_transaction()` call, especially on SQLite (single shared
connection).

The same holds for after-commit work. Code that doesn't name the handle runs
outside the manual transaction, so `DB::after_commit` and an
[after-commit](queues.md#after-commit-dispatch) job pushed that way run at
once. Register on the handle instead, as described in
[After-commit callbacks](#after-commit-callbacks).

### Savepoints

```rust
DB::transaction(|tx| {
    Box::pin(async move {
        Order::create(/* ... */).await?;

        tx.savepoint("after_order").await?;
        if let Err(e) = Payment::charge().await {
            // Drop the payment attempt but keep the order.
            tx.rollback_to("after_order").await?;
        }
        Ok::<(), suprnova::FrameworkError>(())
    })
}).await?;
```

All three first-class backends support `SAVEPOINT` / `ROLLBACK TO
SAVEPOINT` - SQLite included.

A savepoint rollback also unwinds the
[after-commit registry](queues.md#after-commit-dispatch). A queue push deferred
to the commit inside the savepoint is discarded along with the rows it
described, and the compensation registered with it runs immediately, so a
deferred `push_unique`'s dedupe lock goes back and a re-dispatch inside the same
transaction can win it. Anything registered before the savepoint is untouched,
and a savepoint you release or simply never roll back keeps everything
registered inside it.

Repeating a savepoint name is allowed, and the registry follows the database:
`ROLLBACK TO SAVEPOINT x` unwinds to the most recent `x` and destroys the
savepoints established after it. A manual transaction's savepoints unwind
the handle's own registry, the one `tx.after_commit` fills, the same way.

Only `Transaction::savepoint` marks the registry. A savepoint you create with
raw SQL is invisible to it, so `rollback_to` rolls those rows back, logs a
warning, and leaves every deferred dispatch registered inside it in place -
discarding one on a guess would be the worse failure. Use
`Transaction::savepoint` when the deferred dispatches are meant to unwind with
the rows.

### After-commit callbacks

`DB::after_commit` runs a callback once the transaction around it commits,
like Laravel's `DB::afterCommit`. Use it for work that must wait until the
rows it describes are durable, such as a webhook or a message to another
service:

```rust
use suprnova::{DB, FrameworkError, attrs};

DB::transaction(|_tx| {
    Box::pin(async move {
        let order = Order::create(attrs! { total: 30 }).await?;
        let id = order.id;
        DB::after_commit(move || async move { notify_warehouse(id).await }).await?;
        Ok::<(), FrameworkError>(())
    })
}).await?;
```

The callback is an async closure that returns `Result<(), FrameworkError>`,
the shape the after-commit queue already runs, so it can await database,
cache, or HTTP work. It runs as follows:

- Inside `DB::transaction`, it runs after the commit, outside the
  transaction, in the order the callbacks were registered. It never runs if
  the transaction rolls back.
- With no transaction open, it runs at once, and `DB::after_commit` returns
  its result.
- `tx.rollback_to(name)` drops the callbacks registered since that
  savepoint, the same unwinding [Savepoints](#savepoints) describes for a
  deferred queue push. Callbacks registered before the savepoint, after the
  rollback, or inside a savepoint you keep still run at the commit.
- If it fails after the commit, `DB::transaction` returns the
  `after-commit callback failed (the transaction itself committed)` error
  that [Closure form](#closure-form) describes. The other callbacks still
  run, and the commit stands.

You keep a successful inner transaction's after-commit callbacks until
the outermost commit. An inner rollback discards only its callbacks.

Inside a transaction you started with `DB::begin_transaction`, register on
the handle. That transaction is not ambient: code that doesn't name the
handle runs outside it, and its writes don't join it either. So
`DB::after_commit` beside it runs at once, while `tx.after_commit` and
`Queue::push_after_commit_with_tx` wait for `tx.commit()`:

```rust
use suprnova::{DB, Queue, attrs};

let tx = DB::begin_transaction().await?;
let order = Order::create_with_tx(&tx, attrs! { total: 30 }).await?;
let id = order.id;
tx.after_commit(move || async move { notify_warehouse(id).await });
Queue::push_after_commit_with_tx(&tx, OrderPlaced { id }).await?;
tx.commit().await?;
```

A callback or push on the handle follows the rules above against that
handle. It runs after `tx.commit()` and is discarded by `tx.rollback()`, by
dropping the handle without committing it, and by `tx.rollback_to(name)` to
a savepoint taken before it. If one fails after the commit, `tx.commit()`
returns the same `after-commit callback failed (the transaction itself
committed)` error.

#### Why Suprnova diverges

In Laravel, `DB::afterCommit` inside `DB::beginTransaction()` waits for
`DB::commit()`, because the connection itself is in the transaction. A
Suprnova manual transaction is a handle that only the calls naming it use,
so the after-commit work that waits for it names it too:
`tx.after_commit(callback)` rather than `DB::after_commit(callback)`. When
you port `DB::beginTransaction()` code, change each `DB::afterCommit` in it
to `tx.after_commit`: a `DB::after_commit` there runs at once, before the
commit, even when the transaction then rolls back.

### Rollback callbacks

You register compensation with `DB::after_rollback(callback).await?`.
You use the same async closure returning `Result<(), FrameworkError>`
as `after_commit`. Your callback runs when its enclosing transaction
rolls back and never when it commits. An inner rollback runs only that
scope's callbacks; after a successful inner scope, your callback also
runs if the outer transaction later rolls back. With no ambient
transaction, you discard the callback because no rollback occurs.

You can query the still open outer transaction from an inner rollback
callback. For an outer rollback, you run outside the rolled back
transaction. Callback failures are logged and do not replace the
original transaction error.

### Before starting a transaction

You register a synchronous guard before opening transactions:

```rust
DB::before_starting_transaction(|| {
    check_database_write_policy()?;
    Ok::<(), suprnova::FrameworkError>(())
});
```

You run each listener in registration order before `BEGIN`, including
`begin_transaction`, and before each nested savepoint. Returning an
error prevents that transaction from starting and gives the caller the
same error. Your listeners belong to the active test container in tests,
and otherwise to the application.

## Observability

Laravel 13's `DB::listen` / `QueryExecuted` / query log surface, ported
to Rust through Suprnova's event dispatcher.

### `DB::listen` - direct callback

```rust
use suprnova::{DB, QueryExecuted};

// In bootstrap.rs (or a service provider).
DB::listen(|event: &QueryExecuted| {
    tracing::debug!(
        sql = %event.sql,
        bindings = ?event.bindings,
        time_ms = event.time.as_millis(),
        connection = %event.connection_name,
        "query executed",
    );
})?;
```

Listeners run **synchronously inside the executor helper**. A slow
listener slows the query - keep direct callbacks light. For anything
that can fail, prefer the `EventFacade` path below; it runs through
`dispatch_best_effort` and tolerates errors.

### `EventFacade` dispatch path

`QueryExecuted` is a real `suprnova::Event` - listen through the
dispatcher to get queued, fakeable, fail-tolerant delivery:

```rust
use suprnova::{EventFacade, Listener, QueryExecuted, FrameworkError};
use std::sync::Arc;

struct LogToDatabase;

#[suprnova::async_trait]
impl Listener<QueryExecuted> for LogToDatabase {
    async fn handle(&self, event: &QueryExecuted) -> Result<(), FrameworkError> {
        // Even if THIS listener queries the database, the re-entrancy
        // guard prevents infinite recursion.
        DB::statement(
            "INSERT INTO query_log (sql, time_ms) VALUES (?, ?)",
            vec![event.sql.clone().into(), (event.time.as_millis() as i64).into()],
        ).await?;
        Ok(())
    }
}

// In bootstrap.rs.
EventFacade::listen::<QueryExecuted, _>(Arc::new(LogToDatabase)).await;
```

Listeners on this path:

- Run through `dispatch_best_effort` - a failing listener does NOT
  fail the query.
- Are short-circuited when they themselves issue a query (re-entrancy
  guard).
- Can use `Event::fake()` in tests to assert dispatch without
  actually running listeners.

### In-memory query log

```rust
DB::enable_query_log()?;

User::query().filter("active", true).get().await?;
Order::query().count().await?;

let log = DB::get_query_log()?;
for query in &log {
    println!("{} ({}ms)", query.sql, query.time.as_millis());
}

DB::flush_query_log()?;     // drop entries, keep enabled
DB::disable_query_log()?;   // stop capturing
let still_capturing = DB::logging();
```

The log is **unbounded** - every captured query grows it until the
process exits, `flush_query_log()` runs, or `disable_query_log()` is
called. Use it for development, not as a long-running production
profiler.

### Listeners and the query log in tests

Inside a test container, `DB::listen` callbacks and the query log
belong to that container. `TestDatabase::fresh`,
`TestDatabase::sqlite_memory`, and `TestContainer::fake` each start
one, so a test that counts queries counts only the queries it runs,
even when `cargo test` runs other tests in the same process. The
callbacks and the log end with the container.

```rust
use suprnova::testing::TestDatabase;
use suprnova::DB;

#[tokio::test]
async fn listing_posts_runs_one_query() {
    let _db = TestDatabase::fresh::<Migrator>().await.unwrap();
    DB::enable_query_log().unwrap();

    Post::query().get().await.unwrap();

    assert_eq!(DB::get_query_log().unwrap().len(), 1);
}
```

A callback that you register outside any test container, as
`bootstrap.rs` does, receives every query of the process, including
the queries that tests run inside their containers.

### Transaction lifecycle events

`TransactionBeginning`, `TransactionCommitted`, and
`TransactionRolledBack` are real `suprnova::Event` types - listen for
them through `EventFacade::listen` to drive auditing, distributed
locks, or compensation logic.

```rust
EventFacade::listen::<TransactionCommitted, _>(Arc::new(AuditCommit)).await;
EventFacade::listen::<TransactionRolledBack, _>(Arc::new(MetricRollback)).await;
```

All three transaction entry points
(`DB::transaction` / `DB::transaction_with_attempts` /
`DB::begin_transaction` + `Transaction::commit`/`rollback`) fire the
events. A leaked manual `Transaction` handle that gets dropped without
explicit commit/rollback emits no event - SeaORM's `Drop` impl is
synchronous and can't reach the async dispatcher.

### Busy database - `DB::monitor` and `db:monitor`

`DatabaseBusy` is a real `suprnova::Event`. It reports that the database
server has as many connections as you allow, or more. Its fields are
`connection_name` and `connections`. Nothing dispatches it by itself.
Two calls dispatch it:

- `DB::monitor(max)` asks the server of every connection the application
  has, the default one and each named one. It dispatches `DatabaseBusy`
  for each server with `max` connections or more, and returns the events
  it dispatched. `max` must be at least 1.
- The `db:monitor --max <n>` console command does the same and prints the
  count for each connection. Without `--max` it prints the counts and
  dispatches nothing.

The server does the counting, from every client of it, so the answer is
the same from every process. That lets you run the check from the
scheduler, which is a process of its own:

```rust
use suprnova::Schedule;

pub fn register(schedule: &mut Schedule) {
    schedule.add(schedule.command("db:monitor --max 80").every_minute());
}
```

A listener decides what a busy database means: a page, a metric, a log
line.

```rust
use std::sync::Arc;
use suprnova::{DatabaseBusy, EventFacade, FrameworkError, Listener};

struct PageOnCall;

#[suprnova::async_trait]
impl Listener<DatabaseBusy> for PageOnCall {
    async fn handle(&self, event: &DatabaseBusy) -> Result<(), FrameworkError> {
        tracing::error!(
            connection = %event.connection_name,
            connections = event.connections,
            "the database is busy"
        );
        Ok(())
    }
}

// In bootstrap.rs.
EventFacade::listen::<DatabaseBusy, _>(Arc::new(PageOnCall)).await;
```

A listener that fails does not stop the check. The count comes from the
server:

| Engine | Count |
|---|---|
| PostgreSQL | The rows of `pg_stat_activity`, which include the server's own workers |
| MySQL and MariaDB | `threads_connected` |
| SQLite | None. SQLite has no server, so it is never busy. |

`DB::connection_counts()` returns the counts as a `Vec<ConnectionCount>`,
each with a `connection_name` and `connections: Option<u32>`, and
`DbConnection::server_connections()` returns the count of one connection.
`DbConnection::connections_in_use()` is a different number: the
connections of this process's own pool that are out of the pool now. It
says nothing about another process.

### `QueryExecuted` payload

```rust
pub struct QueryExecuted {
    pub sql: String,
    pub bindings: Vec<String>,         // debug-rendered (`{:?}`)
    pub time: std::time::Duration,
    pub connection_name: String,
    pub read_write_type: Option<ReadWriteType>,
    pub result: Result<(), String>,    // Err on driver error
}
```

`to_raw_sql()` substitutes the captured bindings into the SQL for
display:

```rust
let query = /* captured from a listener */;
println!("{}", query.to_raw_sql());
// SELECT * FROM users WHERE id = 42 AND active = true
```

The substitution is **debug-format** (not SQL-safe escaping) and is
intended for log output only. Never feed the result back into a query.
When the bindings do not match the placeholders - one is missing, or
one is left over - `to_raw_sql()` returns the SQL unchanged rather than
a half-substituted statement.

### Coverage scope

`QueryExecuted` fires for every query:

- Every raw helper on `DB` (`select` / `select_one` / `scalar` /
  `insert` / `update` / `delete` / `statement` / `affecting_statement` /
  `unprepared`).
- Every terminal method on `DbTableBuilder` (the model-less builder).
- `DB::transaction` / `DB::begin_transaction` BEGIN / COMMIT / ROLLBACK
  fire transaction events.
- `DbConnection::connect` fires `ConnectionEstablished`.
- Every Eloquent read and write: `Builder<M>::get` / `first` /
  `count` / pagination / chunking, `Model::find` / `all`, and model
  CRUD, including the `IN (...)` queries behind eager loading.

## Connection metadata

```rust
let name = DB::database_name()?;        // "myapp" for postgres://.../myapp
let driver = DB::driver_name()?;        // "postgres" | "mysql" | "sqlite"
let title = DB::driver_title()?;        // "Postgres" | "MySQL" | "MariaDB" | "SQLite"
let version = DB::server_version().await?;  // "15.5" | "8.0.36" | "3.42.0"
```

`server_version` issues a backend-specific introspection query
(`SELECT VERSION()` for Postgres + MySQL, `SELECT sqlite_version()`
for SQLite). Cache the result if you call it often - every call is a
round trip.

## Named connections

For read replicas, sharded shards, or per-model warehouse pools:

```rust
// In bootstrap.rs
DB::register_named("__read_replica__", read_config).await?;
DB::register_named("warehouse", warehouse_config).await?;

// Per-query routing:
let rows = User::query().on("__read_replica__").get().await?;
let warehouse_rows = DB::table("audit_log").on("warehouse").get().await?;
let raw = DB::select_on("warehouse", "SELECT ...", vec![]).await?;
```

The `__read_replica__` name is well-known: when registered, every
read-shape terminal method auto-routes through it. Writes ignore the
replica and target the primary. Use `Builder::on_write_connection`
(per query) or `#[model(connection = "...")]` (per model default) to
opt back to the primary for specific operations.

Reserved names:

- `__primary__` - the default pool. Cannot be registered (it's the
  return value of `DB::connection()`).
- `__read_replica__` - well-known read replica. ANY connection
  registered under this name takes over read routing.

See [eloquent.md → Multi-connection routing](eloquent.md#multi-connection-routing) for the
full precedence chain (builder tx override → ambient tx → builder
`on(name)` → model default → `__read_replica__` → primary).

## Testing

`TestDatabase` builds an in-memory SQLite database, registers it in
the test container so `DB::connection()` resolves to it, and runs your
migrations:

```rust
use suprnova::testing::TestDatabase;
use crate::migrations::Migrator;

#[tokio::test]
async fn test_user_creation() {
    let db = TestDatabase::fresh::<Migrator>().await.unwrap();
    // Any code calling DB::connection() now gets this in-memory DB.
    let _ = CreateUser::run("alice@example.com").await.unwrap();
}

// `test_database!()` is the macro shortcut.
let db = test_database!();
```

For tests that build their own ad-hoc schema:

```rust
let db = TestDatabase::sqlite_memory().await.unwrap();
db.execute_unprepared("CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)").await.unwrap();
```

When a `TestDatabase` is dropped, the test container is cleared and
the connection registry is wiped - no cross-test leakage. Tests that
mutate process-wide state, such as the connection registry, should be
annotated `#[serial_test::serial]` so they don't collide. `DB::listen`
callbacks and the query log aren't process-wide inside a test: see
[Listeners and the query log in tests](#listeners-and-the-query-log-in-tests).

## Next

- [Eloquent](eloquent.md) - the typed `#[suprnova::model]` ORM that
  sits on top of this layer
- [Migrations](migrations.md) - `Migrator`, `make:migration`, and the
  `db:sync` workflow
- [Database Testing](database-testing.md) - `TestDatabase`, fixture
  loading, and serial-test annotations
- [Events](events.md) - the dispatcher behind `QueryExecuted` /
  `TransactionCommitted` listeners
- [Configuration](configuration.md) - registering `DatabaseConfig`
  alongside the rest of your typed config

## Surface index

| Surface | Laravel analogue |
| --- | --- |
| `DB::init` / `DB::init_with` / `DB::connection` / `DB::is_connected` / `DB::get` | `DB::connection()` |
| `DB::table(name)` → `DbTableBuilder` | `DB::table($name)` |
| `where_full_text` / `or_where_full_text` / `where_full_text_with` / `or_where_full_text_with` / `FullTextOptions` / `FullTextMode` | `whereFullText` / `orWhereFullText` |
| `DB::select` / `select_one` / `scalar` / `insert` / `update` / `delete` / `statement` / `affecting_statement` / `unprepared` | `DB::select` / `selectOne` / `scalar` / `insert` / `update` / `delete` / `statement` / `affectingStatement` / `unprepared` |
| `DB::transaction` / `transaction_with_attempts` / `begin_transaction` | `DB::transaction($cb, $attempts)` / `DB::beginTransaction` |
| `DB::transaction_level()` / `DB::before_starting_transaction(listener)` | `transactionLevel` / `beforeStartingTransaction` |
| `DB::after_rollback(callback)` | `afterRollBack` |
| `DB::after_commit(callback)` / `Transaction::after_commit(callback)` | `DB::afterCommit` |
| `Transaction::commit` / `rollback` / `savepoint` / `rollback_to` | `DB::commit` / `rollBack` / savepoint helpers |
| `DB::listen(callback)` | `DB::listen` |
| `DB::monitor` / `connection_counts` / `DbConnection::server_connections` / `connections_in_use` | `db:monitor` |
| `DB::enable_query_log` / `disable_query_log` / `get_query_log` / `flush_query_log` / `logging` | `DB::enableQueryLog` / `disableQueryLog` / `getQueryLog` / `flushQueryLog` / `logging` |
| `DB::database_name` / `driver_name` / `driver_title` / `server_version` | `getDatabaseName` / `getDriverName` / `getDriverTitle` / `getServerVersion` |
| `DB::register_named` / `named` / `select_on` / `table_on` / `statement_on` / `affecting_statement_on` | multi-connection `DB::connection($name)` |
| `QueryExecuted` / `TransactionBeginning` / `TransactionCommitted` / `TransactionRolledBack` / `ConnectionEstablished` / `DatabaseBusy` | `Illuminate\Database\Events\*` |
| `DatabaseConfig::builder()` / `from_env` / `validate_for_environment` / `idle_timeout` / `max_lifetime` / `acquire_timeout` / `test_before_acquire` / `ping_after_idle` / `charset` / `collation` | `config/database.php` |
| `TestDatabase::fresh::<M>` / `sqlite_memory` / `execute_unprepared` / `fetch_one` / `fetch_all` | `RefreshDatabase` testing trait |


---

<!-- /docs/queries -->

# Query Builder

When you want to query a table without modelling it as a typed
`#[suprnova::model]` struct, reach for `DB::table(name)`. It returns a
chainable builder shaped like the typed Eloquent `Builder<M>`, but
materialises rows as `DynamicRow` - a `serde_json::Map` newtype with
typed accessors. This is the chapter for audit logs, ad-hoc reports,
dashboard aggregates, and any table you haven't bothered to model. For
the typed equivalent, see [Eloquent](eloquent.md). For raw `DB::select`
inside transactions or with `DB::listen` observation, see
[Database](database.md).

```rust
use suprnova::DB;

let rows = DB::table("audit_log")
    .select(["id", "event", "actor_id"])
    .filter("actor_id", 42i64)
    .filter_op("created_at", ">=", "2026-01-01")
    .order_by_desc("id")
    .limit(50)
    .get()
    .await?;

for row in rows.iter() {
    let id: i64 = row.get_int("id")?;
    let event: String = row.get_string("event")?;
    println!("{id}: {event}");
}
```

## When to use which surface

Three query surfaces overlap; pick the right one for the table.

| Table is… | Use | Returns |
|---|---|---|
| Modeled with `#[suprnova::model]` | `Model::query()` → `Builder<M>` | typed `M` values |
| Unmodeled but you want a chainable WHERE/ORDER/LIMIT shape | `DB::table(name)` → `DbTableBuilder` | `DynamicRow` |
| Anything the builders can't express - CTEs, window functions, backend DDL | `DB::select` / `DB::statement` / `DB::affecting_statement` | `DynamicRow` / `bool` / `u64` |

`DbTableBuilder` exists for the middle case. You get the WHERE / ORDER /
LIMIT chain without committing to a `#[suprnova::model]` struct and
without dropping all the way to raw SQL strings.

## The chainable surface

`DB::table(name)` returns a `DbTableBuilder`. Build it up, then call a
terminal method to execute.

### Filtering

```rust
// Equality.
DB::table("users").db_where("email", "alice@example.com").get().await?;

// Arbitrary operator. Allowlist: =, <>, <, <=, >, >=, LIKE, NOT LIKE,
// ILIKE, NOT ILIKE, IS, IS NOT.
DB::table("orders").filter_op("total", ">=", 100i64).get().await?;
DB::table("posts").filter_op("title", "LIKE", "%rust%").get().await?;

// Multiple filters AND together.
DB::table("audit_log")
    .filter("actor_id", 42i64)
    .filter_op("event", "<>", "noop")
    .get()
    .await?;
```

`filter` and `filter_op` both accept any `Into<SeaValue>` for the
right-hand side, which covers `i64`, `String`, `&str`, `bool`, `f64`,
`Option<T>`, `chrono::*`, `uuid::Uuid`, and `serde_json::Value` - every
column type the backend understands.

`db_where(column, value)` and `filter(column, value)` use `=`.
`r#where(column, value)` is the same comparison under Laravel's name: `where`
is a Rust keyword, so you write it as the raw identifier `r#where`. You pass
an operator with `filter_op`; `or_where` and `or_where_op` add their
comparisons with `OR`. A null value in an equality comparison becomes
`IS NULL`, with no null binding.

A `u64` above `i64::MAX` compares as the number it is, whatever the
column's type, in a filter and in a raw fragment's bindings alike, so the
count is the database's own count for the stored rows. Postgres has no unsigned integers, so it receives the value as a
`numeric`: a `bigint` column matches no row, and a `numeric` or `double
precision` column compares exactly. SQLite receives its digits and applies
the column's affinity, as it does to a literal. MySQL receives an
unsigned integer. Compare a text column with the digits as a string:
Postgres refuses to compare text with a number.

The rest of the `WHERE` vocabulary uses the Laravel names:

```rust
// Lists, and NULL checks.
DB::table("users").where_in("role", ["admin", "editor"]).get().await?;
DB::table("users").where_not_in("id", [1i64, 2]).get().await?;
DB::table("users").where_null("deleted_at").get().await?;
DB::table("users").where_not_null("verified_at").get().await?;

// Two columns compared, with no value.
DB::table("orders").where_column("shipped_at", "paid_at").get().await?;
DB::table("orders").where_column_op("shipped_at", ">", "paid_at").get().await?;

// A raw fragment. Write each value as `?` and pass it in the bindings;
// Postgres gets `$N` markers numbered for their place in the statement.
DB::table("orders")
    .where_raw("total * ? > budget", vec![1.2.into()])
    .get()
    .await?;
```

An empty `where_in` list matches no row, and an empty `where_not_in`
list excludes none.

You pass inclusive bounds with `where_between(column, low..=high)` or
`where_not_between(column, low..=high)`. The `or_where_between` and
`or_where_not_between` forms keep the same flat OR precedence. You can
use a plain column, `DB::raw("score + 1")`, or a scalar `DB::table`
subquery as the column. Plain names still pass identifier validation;
your subquery's values stay bound.

#### OR conditions

Each `or_*` method adds a flat `OR` condition. You get SQL precedence:
`where(a).or_where(b).where(c)` means `a OR b AND c`, and `AND` binds
before `OR`. You use a grouped helper when comparisons must stay together:

```rust
// WHERE active = ? AND role IN (?, ?) OR invited_by IS NOT NULL
DB::table("users")
    .filter("active", true)
    .where_in("role", ["admin", "editor"])
    .or_where_not_null("invited_by")
    .get()
    .await?;
```

The `or_` family is `or_where`, `or_where_op`, `or_where_in`, `or_where_not_in`, `or_where_null`,
`or_where_not_null`, `or_where_raw`, `or_where_between`,
`or_where_not_between`, and the three grouped helpers below.

#### One comparison across several columns

`where_any` compares several columns with one operator and value, and
matches when any of them does. `where_all` matches when every column
does, and `where_none` when none does:

```rust
// WHERE (code LIKE ? OR description LIKE ?)
let found = DB::table("products")
    .where_any(["code", "description"], "like", format!("%{search}%"))
    .get()
    .await?;

// WHERE is_admin = ? AND NOT (banned = ? OR suspended = ?)
let staff = DB::table("users")
    .filter("is_admin", true)
    .where_none(["banned", "suspended"], "=", true)
    .get()
    .await?;
```

The comparisons sit in parentheses, so an `OR` inside never reaches the
conditions around it: `filter("a", 1).where_any(["b", "c"], "=", 2)`
returns only rows whose `a` is 1. `or_where_any`, `or_where_all`, and
`or_where_none` add the parenthesized group with a flat `OR`. An empty
column list adds no condition.

#### Subqueries

`where_in`, `where_not_in`, and their `or_` forms also take another
`DB::table` builder, which runs as a subquery. `where_exists` and
`where_not_exists` take one too, and the subquery can refer to the outer
table through `where_column`:

```rust
// Rooms with a slot on Monday.
let booked = DB::table("rooms")
    .where_in("id", DB::table("slots").select(["room_id"]).filter("day", "mon"))
    .get()
    .await?;

// Users who have written a post.
let authors = DB::table("users")
    .where_exists(
        DB::table("posts")
            .select_raw("1")
            .where_column("posts.author_id", "users.id"),
    )
    .get()
    .await?;
```

A subquery's values stay bound parameters, in the position they take in
the statement. On Postgres the `$N` numbers continue through the
subquery.

#### Byte-exact comparison

`where_binary` compares the raw bytes of a column instead of matching
under its collation, so `"Alice"` does not match `"alice"` or `"ALICE"`:

```rust
DB::table("users").where_binary("email", submitted).get().await?;
DB::table("users").where_not_binary("email", submitted).get().await?;
```

This is a MySQL and MariaDB feature - it emits their `binary` operator
modifier, `email = binary ?`. Postgres and SQLite have no equivalent, so
on those backends every terminal returns an error when the statement
renders, before any query runs. Suprnova refuses rather than falling back
to a plain `=`, because a fallback would compare under the column's
collation and return rows you asked to exclude.

If you need case-sensitive matching on Postgres or SQLite, set a
case-sensitive collation on the column, or use `DB::select` with a
backend-specific expression.

### Selecting columns

```rust
// Default is SELECT *.
DB::table("users").get().await?;

// Restrict columns when you only need some.
DB::table("users").select(["id", "email"]).get().await?;

// An alias renames a column in the result; `table.*` selects one
// table's columns, which matters once a query joins another table.
DB::table("users").select(["users.*", "email as login"]).get().await?;

// Add an expression with select_raw, and group the rows.
DB::table("orders")
    .select(["status_id"])
    .select_raw("COUNT(*) AS total")
    .group_by("status_id")
    .get()
    .await?;
```

`select` replaces the list each time you call it. `select_raw` adds an
expression to the end of the list, so it combines with `select`. The
expression is written into the query as given, so never build it from
request data.

You use `DB::raw(expression)` when SQL must evaluate an expression in
`group_by`, `having` or `having_op`. You write trusted SQL there; the
expression is never a bound value:

```rust
let rows = DB::table("orders")
    .select_raw("status_id, SUM(total) AS total")
    .group_by(DB::raw("status_id + 0"))
    .having_op(DB::raw("SUM(total)"), ">", 100i64)
    .get().await?;
```

You keep application values in bindings with
`select_raw_with_bindings(sql, Vec<sea_orm::Value>)`,
`where_raw(sql, bindings)` and `order_by_raw(sql, bindings)`. You write
portable `?` markers; Postgres receives correctly numbered `$N` markers.
On a model query, you use `order_by_raw_with_bindings` for a bound
ordering and keep `order_by_raw(sql)` for SQL without bindings.

### Joins

`join`, `left_join`, and `right_join` take the table and one `ON`
condition between two columns. To join a table under an alias, write
`"table as alias"`. `cross_join` takes the table; `cross_join_with` also
takes a closure whose conditions become its `ON` clause. This query lists
every post with its category and author:

```rust
let rows = DB::table("posts")
    .left_join("categories", "categories.id", "=", "posts.category_id")
    .left_join("users as authors", "authors.id", "=", "posts.author_id")
    .select([
        "posts.title",
        "categories.name as category_name",
        "authors.name as author_name",
    ])
    .order_by_asc("posts.title")
    .get()
    .await?;

for row in rows.iter() {
    let author: Option<String> = row.get_optional_string("author_name")?;
}
```

The rows come back as `DynamicRow`. Columns that the joined tables share,
such as `id` or `name`, overwrite one another in the row, so alias them
in `select`.

For more than one condition, `join_with`, `left_join_with`, and
`right_join_with`, and `cross_join_with` pass a `JoinClause` to a closure. `on` and `or_on`
compare two columns. `db_where`, `db_where_op`, `or_where`, and
`or_where_op` compare a column with a value, as Laravel's `where` and
`orWhere` do in a join closure. `filter`, `filter_op`, `or_filter`, and
`or_filter_op` do the same:

```rust
// INNER JOIN users ON users.id = posts.author_id
//   AND posts.views > ? OR users.role = ?
let rows = DB::table("posts")
    .join_with("users", |join| {
        join.on("users.id", "=", "posts.author_id")
            .db_where_op("posts.views", ">", 100)
            .or_where("users.role", "editor")
    })
    .get()
    .await?;
```

A join condition's value is a bound parameter, like every other value.
You get the same flat `AND` and `OR` precedence in an `ON` clause as
in a `WHERE` clause. A join other than `cross_join` needs at least one
condition: the query fails with an error before it runs otherwise.

To join a subquery, pass another `DB::table` builder and an alias to
`join_sub` or `left_join_sub`. `join_sub_with` and `left_join_sub_with`
take a closure instead of one condition. This query counts each status's
orders, with zero for a status that has none:

```rust
let totals = DB::table("orders")
    .select(["status_id"])
    .select_raw("COUNT(*) AS total")
    .group_by("status_id");

let rows = DB::table("statuses")
    .left_join_sub(totals, "order_totals", "order_totals.status_id", "=", "statuses.id")
    .select(["statuses.name"])
    .select_raw("COALESCE(order_totals.total, 0) AS total")
    .get()
    .await?;
```

The subquery's values bind ahead of the values of the conditions and
`WHERE` clauses after it, so the order you call the methods in doesn't
matter.

`get` and `count` record a read of every table the query names,
including joined tables and the tables a subquery names, so a cached
page that ran the query is invalidated when any of them changes. A
`select_raw`, `where_raw`, or `or_where_raw` fragment can read a table
the builder doesn't name, so a query that carries one anywhere, subqueries
included, keeps the page out of the cache: the response is still served,
but it is never stored. A `select_raw` that is a bare number, such as the
`select_raw("1")` in an `EXISTS` subquery, reads nothing and doesn't
count. See [Render cache](render-cache.md).

### Ordering and windowing

```rust
DB::table("posts")
    .order_by_desc("created_at")
    .order_by_asc("title")
    .limit(20)
    .offset(40)
    .get()
    .await?;
```

`order_by_desc` and `order_by_asc` chain in insertion order; the
generated SQL preserves it.

`reorder()` drops every ordering set so far, and `reorder_by(col,
Direction::Asc)` drops them and orders by `col` instead. Use it on a base
query before you reuse it as a subquery:

```rust
use suprnova::Direction;

let recent = DB::table("slots").select(["room_id"]).order_by_desc("starts_at");
let rooms = DB::table("rooms")
    .where_in("id", recent.reorder())
    .reorder_by("name", Direction::Asc)
    .get()
    .await?;
```

You call `oldest()` to order a table by `created_at` ascending, or
`oldest_by(column)` to choose another column, expression or scalar
subquery. On a model query, `oldest()` and `latest()` use your model's
declared creation timestamp, including a renamed `created_at` option.
You override it with `oldest_by(column)` or `latest_by(column)`.

You call `in_random_order()` on either builder to order rows randomly.
MySQL orders by `RAND()`, and Postgres and SQLite order by `RANDOM()`.

When you need the same order again, for example to page through one
shuffled list, you call `in_random_order_seeded(seed)` instead. On
MySQL, you get `RAND(seed)`. On Postgres, you set the connection seed in
the same statement before ordering by `random()`. Repeating the seed on
the same rows and connection repeats the order on those engines. On
SQLite, `RANDOM()` cannot be seeded. Both builders order by an expression
derived from the seed and each row's `rowid`, then by the `rowid` itself,
so the same seed repeats the order on the same rows, whatever type your
primary key has. A model query carries the rowid through a union: each
query of the union adds it to its selected columns, so the union and its
pages repeat the order too, and `UNION` removes only copies of the same
row. Every table a migration creates has a rowid. A view or a
`WITHOUT ROWID` table has none, and a seeded order on it returns the
engine's error. You still receive each matching row once.

```rust
let sample = DB::table("posts").in_random_order().limit(5).get().await?;
let shuffled = DB::table("posts")
    .in_random_order_seeded(42)
    .limit(20)
    .get()
    .await?;
```

### Terminals

```rust
// All matching rows.
let rows: Collection<DynamicRow> = DB::table("audit_log")
    .filter("actor_id", 42i64)
    .get()
    .await?;

// First row or None.
let first: Option<DynamicRow> = DB::table("audit_log")
    .filter("event", "user.deleted")
    .first()
    .await?;

// Just the count (drops any select list and ordering).
let n: u64 = DB::table("audit_log")
    .filter("actor_id", 42i64)
    .count()
    .await?;
```

You call `first_or_fail()` when a missing row must produce a 404. The
default message names the table or model. You supply your own message
with `first_or_fail_with(message)` on either builder; database failures
still return their original error.

You read the largest value with `max::<i64>(column).await?`, choosing
the Rust type your column uses. You receive `None` for an empty set or
SQL NULL, and an error if the value cannot decode into your chosen type.
You can pass a plain column, `DB::raw(expression)` or a scalar subquery.

You inspect a table query's SQL with `to_sql_for(backend)`. You receive
`Result<(String, Vec<sea_orm::Value>), FrameworkError>` and no query runs.

On a query with `group_by`, `count()` returns the number of groups.

A limit or an offset stays on the count, as in Laravel, where it bounds
the one row the count returns rather than the rows it counts.
`limit(10).count()` counts every match, and `offset(1).count()` returns
0, because the offset skips the count's only row.

`get()` returns `Collection<DynamicRow>` - the same collection wrapper
typed models use, with the same `.iter()`, `.len()`, `.into_vec()`
surface. See [Eloquent Collections](eloquent-collections.md).

### Inserts, updates, deletes

```rust
use suprnova::attrs;

// INSERT, returns the new row's auto-increment id.
let id: i64 = DB::table("audit_log")
    .insert(attrs! { event: "user.created", actor_id: 42 })
    .await?;

// UPDATE, returns rows affected.
let updated: u64 = DB::table("audit_log")
    .filter("id", id)
    .update(attrs! { event: "user.created.v2" })
    .await?;

// DELETE, returns rows affected.
let deleted: u64 = DB::table("audit_log")
    .filter("actor_id", 42i64)
    .delete()
    .await?;
```

The `attrs!` macro builds the column-to-value map at the call site.
Keys are SQL identifiers (validated) and values are bound as
parameters. An explicit null is emitted as SQL `NULL` because the JSON
attribute map no longer carries its original Rust type; all non-null values
remain parameter-bound. The same rule applies to typed Eloquent mass writes
and many-to-many pivot extras.

You mix raw assignments and bound values with `UpdateAttrs` on either
builder. You keep `attrs!` for updates containing only data:

```rust
use suprnova::{DB, UpdateAttrs};

let mut changes = UpdateAttrs::new();
changes.insert("views", DB::raw("views + 1"));
changes.insert("status", "published");
DB::table("posts").filter("id", 42i64).update(changes).await?;
```

You can also pass an array for one kind of assignment:
`update([("views", DB::raw("views + 1"))])`. You validate assignment
column names as usual. Raw expressions contain trusted SQL and reach the
database unbound; you never build them from request data.

A `u64` above `i64::MAX` is written as the number it is, and no column
stores a rounded value of it. A `numeric` or text column stores it exactly
on every database, and a floating-point column stores the nearest float,
as it does for any number. An integer column refuses it: MySQL's
unsigned columns store it, but a signed integer column refuses it on every
database. SQLite would store it in an INTEGER or NUMERIC column as a
rounded REAL, so there `insert` and `update` read the column's affinity
first and refuse the write before it is sent. Every refusal is a database
error: a client gets the generic 500 response and the log gets the detail.

#### `update_all` and `delete_all` aliases

`update` and `delete` are the Laravel-faithful names. The
`Builder<M>`-style aliases - `update_all` and `delete_all` - call the
same implementation. Prefer the `_all` form when the table-wide intent
is the point of the call site; it makes a missing `filter` visible to
reviewers:

```rust
// Same behaviour as DB::table("rate_limits").delete().await? but the
// _all suffix tells reviewers "yes, I meant to truncate the table".
DB::table("rate_limits").delete_all().await?;

// Mass update with a WHERE - the _all suffix here matches the typed
// Builder<M> convention for the same operation.
DB::table("sessions")
    .filter_op("expires_at", "<", chrono::Utc::now())
    .update_all(attrs! { status: "expired" })
    .await?;
```

#### Empty WHERE on update or delete operates on every row

`DB::table("x").delete().await?` removes every row in the table. That
is supported by design - sometimes you really do want to truncate -
but it's rarely correct. Always look at a `delete()` / `delete_all()`
call and check whether there's a `filter` in front of it. The same is
true of `update` / `update_all`.

`update` and `delete` keep every join and predicate when selecting rows
to change. You write columns on the builder's base table; joined tables
only constrain the match. Both methods return the affected base-row count.

#### Insert backend split

`RETURNING id` is used on Postgres and SQLite. MySQL doesn't support
`RETURNING`, so the builder runs the INSERT and reads the driver's
per-connection `last_insert_id()` from the result. The model-less
builder assumes a standard `id` auto-increment primary key. UUID,
composite, renamed, or non-integer primary keys aren't supported on
this surface - use the typed [Eloquent](eloquent.md) `Model` interface
instead, which consults the model definition for primary-key shape.

## `DynamicRow` - typed accessors over a JSON map

Every row returned by `DB::table` or `DB::select` materialises as
`DynamicRow`, a `serde_json::Map<String, Value>` newtype with typed
accessors. Each getter returns `Result<T, FrameworkError>` with a
clear error message on missing key or type mismatch.

```rust
for row in rows.iter() {
    let id: i64                 = row.get_int("id")?;
    let event: String           = row.get_string("event")?;
    let active: bool            = row.get_bool("active")?;
    let weight: f64             = row.get_float("weight")?;
    let payload: serde_json::Value = row.get_value("payload")?;
}
```

For nullable columns, use `get_optional_*`. These distinguish "column
missing" (error - schema mismatch) from "column present, value SQL
NULL" (`Ok(None)`):

```rust
let title: Option<String> = row.get_optional_string("title")?;
let score: Option<i64>    = row.get_optional_int("score")?;
```

The optional family covers `String` and `i64`. For other
nullable types, use `get_value` and match on `serde_json::Value::Null`
yourself, or read the column through `get_as::<Option<T>>` (any
`T: DeserializeOwned`).

To deserialise a column into any struct or container type, use
`get_as`. The full `serde_json` deserialisation surface is available:

```rust
#[derive(serde::Deserialize)]
struct UserPrefs {
    theme: String,
    notifications: bool,
}

let prefs: UserPrefs    = row.get_as("prefs")?;
let tags: Vec<String>   = row.get_as("tags")?;
let when: chrono::DateTime<chrono::Utc> = row.get_as("created_at")?;
```

`DynamicRow` derefs to `Map<String, Value>`, so iteration and
key-existence checks work directly:

```rust
for (key, value) in row.iter() {
    println!("{key} = {value}");
}

if row.contains_key("deleted_at") { /* … */ }
```

## Identifier trust boundary

Table names, column names, aliases, ORDER BY directions, and SQL
operators are written into the SQL string - they are NOT bound as
parameters (SQL doesn't allow placeholder-bound identifiers). Treat
every `impl Into<String>` argument as a trusted, compile-time literal.

```rust
// Safe - the column name is a constant; the value is bound.
DB::table("users").filter("email", request.email()).get().await?;

// UNSAFE - never splice user input into a column name.
DB::table("users")
    .filter(request.user_supplied_column(), value)
    .get()
    .await?;
```

The framework enforces a strict allowlist at the I/O boundary -
identifiers must match `[A-Za-z_][A-Za-z0-9_]*` with one optional
`schema.` prefix, and operators must come from a fixed list. Violations
fail closed with a `FrameworkError::Database` before any SQL is
rendered. The builder then quotes every identifier for the backend:
backticks on MySQL and MariaDB, double quotes on Postgres and SQLite.
That's a safety net, not a license: keep identifiers literal in your
code. `select_raw` and `where_raw` fragments are written as given and
never checked.

Values on the right-hand side of `filter` / `filter_op`, in `where_in`
lists, in join conditions, and in raw-fragment bindings are always bound
as parameters and safe to splice through from request data.

## Raw queries

When the builder can't express what you need - recursive CTEs, window
functions, backend-specific DDL, `INSERT … ON CONFLICT DO UPDATE` -
drop to a raw string. Placeholders match the active backend (`$1, $2,
…` for Postgres, `?` for MySQL and SQLite); the framework auto-detects
from `DatabaseConfig::url`.

```rust
use suprnova::DB;
use sea_orm::Value;

// SELECT - every row as DynamicRow.
let rows = DB::select(
    "SELECT u.name, COUNT(p.id) AS post_count
     FROM users u LEFT JOIN posts p ON p.user_id = u.id
     GROUP BY u.id
     HAVING COUNT(p.id) > ?",
    vec![Value::from(5i64)],
).await?;

// SELECT - first row only, mirrors Laravel's DB::selectOne.
let alice = DB::select_one(
    "SELECT * FROM users WHERE email = ?",
    vec![Value::from("alice@example.com")],
).await?;

// SELECT - first column of first row as a typed scalar.
let total: i64 = DB::scalar(
    "SELECT COUNT(*) FROM users WHERE active = ?",
    vec![Value::from(true)],
).await?;

// INSERT - true when at least one row was affected.
DB::insert(
    "INSERT INTO users (name, active) VALUES (?, ?)",
    vec![Value::from("bob"), Value::from(true)],
).await?;

// UPDATE / DELETE - return the rows-affected count.
let updated: u64 = DB::update(
    "UPDATE users SET active = ? WHERE id = ?",
    vec![Value::from(false), Value::from(1i64)],
).await?;

let deleted: u64 = DB::delete(
    "DELETE FROM users WHERE active = ?",
    vec![Value::from(false)],
).await?;

// Any prepared statement with bindings.
DB::statement(
    "UPDATE users SET votes = votes + ? WHERE id = ?",
    vec![Value::from(1i64), Value::from(42i64)],
).await?;

// DDL or other no-binding statements that reject placeholder binding.
DB::unprepared("CREATE INDEX idx_users_name ON users(name)").await?;

// Generic "rows affected" path - for upserts and operations that
// don't fit the named helpers.
let n: u64 = DB::affecting_statement(
    "INSERT INTO counters (k, n) VALUES ($1, 1)
     ON CONFLICT (k) DO UPDATE SET n = counters.n + 1",
    vec![Value::from("page_views")],
).await?;
```

### Computed columns on SQLite

SQLite declares no type for a computed column: `COUNT(*) AS n`,
`COALESCE(t.total, 0) AS total`, or any other `select_raw` expression.
Rows from `DB::table` and `DB::select` still carry the column. Suprnova
reads each such value by its runtime type, so an integer comes back as a
JSON integer, a real as a JSON number, text as a string, and `NULL` as
`null`:

```rust
let rows = DB::select(
    "SELECT actor_id, COUNT(*) AS n FROM audit_log GROUP BY actor_id",
    vec![],
).await?;
let n: i64 = rows[0].get_int("n")?;
```

## Bridge to typed Eloquent

When the table is worth a `#[suprnova::model]` struct, the chainable
shape carries over. `Model::query()` returns `Builder<M>`, which
ships the same `filter` / `filter_op` / `order_by_*` / `limit` /
`offset` / `get` / `first` / `count` surface - plus a much wider WHERE
vocabulary (`filter_in`, `filter_between`, `filter_null`, `filter_has`,
`filter_raw`, …) and Laravel-shape aliases (`db_where`, `where_in`,
`where_between`, `where_null`, `where_has`, `where_raw`, …).

```rust
use suprnova::Model;

let admins = User::query()
    .filter("role", "admin")
    .filter_op("created_at", ">=", since)
    .order_by_desc("created_at")
    .limit(20)
    .get()
    .await?;     // Collection<User> - typed, not DynamicRow

let alice = User::query().filter("email", &email).first().await?;
let total = User::query().filter("active", true).count().await?;
// Note: Builder<M>::count returns i64 (matches Laravel's Eloquent),
// whereas DbTableBuilder::count returns u64. Both surfaces give you a
// non-negative SQL COUNT - they only differ in their wire type.
```

The full `Builder<M>` surface - every WHERE shape, aggregates,
relations, eager loading, scopes, paginators, chunk iteration - is in
[Eloquent](eloquent.md). The chainable shape you learned above is the
same shape; the differences are typing and reach. The joins, the
grouped `where_any` family, the `or_` helpers, subqueries, and `reorder`
work the same way on both builders, and a model query takes a
`DB::table` builder as its subquery.

## Routing to a named connection

`DB::table` and the raw helpers default to the primary connection. To
target a read replica, shard, or warehouse pool, pin the call:

```rust
// Builder pinned to a named connection.
let rows = DB::table("audit_log").on("warehouse").get().await?;

// Equivalent shorthand.
let rows = DB::table_on("warehouse", "audit_log").get().await?;

// Raw escapes have _on variants too.
let rows = DB::select_on("warehouse", "SELECT …", vec![]).await?;
let n    = DB::affecting_statement_on(
    "warehouse",
    "UPDATE …",
    vec![],
).await?;
```

When `__read_replica__` is registered, every read-shape terminal
auto-routes through it; writes (`insert` / `update` / `delete` /
`update_all` / `delete_all`) always target the primary. Inside a
`DB::transaction` closure the active transaction's connection wins
absolutely - `on(name)` is silently ignored to preserve atomicity. See
[Database - Named connections](database.md) for the full precedence
chain.

### A default for one task

Use `DB::with_default_connection(name, future)` when several queries need
one named pool without repeating `.on(name)`:

```rust
let rows = DB::with_default_connection("reporting", async {
    assert_eq!(DB::default_connection(), "reporting");
    DB::table("audit_log").get().await
}).await?;
```

You route default `DB` calls, direct `DB::connection()` access, and model
queries to that pool. Explicit query or model connections keep their
precedence. You start new transactions on that pool; an already active
transaction stays on its original pool. Your scoped default takes
precedence over an automatic read replica.

You keep each concurrent task's default isolated. Nested scopes restore
your outer default on return, error, panic or cancellation. A task you
spawn starts with its own default. Outside a scope,
`DB::default_connection()` returns `PRIMARY_CONNECTION_NAME` (`"__primary__"`).
An unknown connection fails before your future runs.

### Stored keys for chunk cursors

When you call a model query's `chunk_by_id(size, closure)`, you advance
from the key as the database stores it. A model cast can change the key's
value in the model you receive, but it does not change the next chunk's
cursor. You see every matching stored row once, in stored-key order.
You receive an error for a zero chunk size or a failing closure.

### Why Suprnova diverges

Laravel's `DB::table(...)` is its model-less query builder; under the
hood it returns a `stdClass` per row (a PHP object whose properties
are the columns). Suprnova returns `DynamicRow` instead - a
`serde_json::Map` newtype with typed accessors. The accessor shape
catches missing-column and wrong-type errors at the boundary instead
of panicking deep in user code with a property-access exception.

The dual `update`/`update_all` and `delete`/`delete_all` names exist
because the typed Eloquent `Builder<M>` surface uses the `_all` suffix
to make table-wide intent explicit at the call site. Rather than pick
a side, the model-less builder ships both - `update` and `delete`
match Laravel's `DB::table($t)->update(...)` and `->delete()` letter
for letter; `update_all` and `delete_all` match the convention `M`
users will already have in their muscle memory.

`where_binary` returns an error on Postgres and SQLite where Laravel
throws a `RuntimeException` from the base grammar. The reason is the
same and only the mechanism differs: public-surface code in Suprnova
returns `Result` rather than panicking, so the refusal arrives as an
`Err` from the terminal instead of an exception from the grammar.

Laravel's `join` and `whereExists` also take a closure that builds the
subquery, an Eloquent builder, or a raw expression. Here a subquery is
always a `DB::table` builder, and a join's closure only adds conditions.
The column-list helpers take the operator every time -
`where_any(cols, "=", value)` - because Rust has no optional arguments.
You use `where_column_op(a, op, b)` for a column comparison with an
operator, because Rust cannot overload `where_column(a, b)` by arity.

## Next

- [Database](database.md) - `DB` facade, transactions with savepoints,
  `DB::listen` observability, named connections
- [Eloquent](eloquent.md) - typed `#[suprnova::model]` structs and the
  full `Builder<M>` surface
- [Pagination](pagination.md) - `paginate` / `simple_paginate` /
  `cursor_paginate` on typed builders
- [Eloquent Collections](eloquent-collections.md) - the `Collection<T>`
  returned by `get()` on both surfaces
- [Migrations](migrations.md) - defining the schema the builders query


---

<!-- /docs/pagination -->

# Pagination

Suprnova ships three paginators that match Laravel's surface line-for-line:
length-aware (knows the total), simple (one query per page), and cursor
(opaque keyset). All three serialize into the Laravel-shaped
JSON Inertia and JSON:API consumers already understand - you fetch a
page and return it; nothing else is required.

```rust
use crate::models::User;

let page = User::query()
    .filter("active", true)
    .order_by_desc("created_at")
    .paginate(20)
    .await?;
```

That one call runs the `COUNT(*)` and the `LIMIT/OFFSET` page fetch,
parses `?page=N` from the active request, and returns a
`LengthAwarePaginator<User>` ready to ship. The two siblings -
`simple_paginate(20)` and `cursor_paginate(20)` - return the same shape
of value with different trade-offs. The rest of this chapter is which
one to reach for, what each one costs, and how the JSON arrives.

## Picking a paginator

The fastest way to choose is the trade-off table:

| Method | Type | Queries / page | Knows total? | Use when |
|---|---|---|---|---|
| `paginate(n)` | `LengthAwarePaginator<M>` | 2 (`COUNT(*)` + page) | yes | UI shows numeric pages or "page 3 of 17" |
| `simple_paginate(n)` | `Paginator<M>` | 1 (`LIMIT n+1`) | no | Large tables; a "Next" button is enough |
| `cursor_paginate(n)` | `CursorPaginator<M>` | 1 (`LIMIT n+1`) | no | Infinite scroll; deep pages on hot tables |

The cost difference matters once your table is large. `COUNT(*)` over
a hundred million rows is the most expensive query in your request
budget. `simple_paginate` saves the count. `cursor_paginate` saves the
count *and* avoids the `OFFSET N` linear scan that bites every
deep-page request on a big table - a cursor seek is `O(1)`-ish with the
right index, regardless of where in the result set the user is.

### Why Suprnova diverges

The JSON of the three paginators has the fields of Laravel's
`toArray()`, so a front end that was written for Laravel's paginator
reads it. That includes the pagination components of the Inertia starter
kits, which draw the `links` array as it comes. Three differences matter
to a reader who knows Laravel:

- A paginator does not know the base URL of the request. You give it
  one with `with_path(...)`. With no `path`, the page URLs are relative
  (`?page=2`) and `path` is left out of the JSON, where Laravel writes
  `/`. A `path` that starts with `/` gets the public root in front of it
  in every page URL, so behind a proxy that serves the application under
  `/billing` the next page of `/users` is `/billing/users?page=2`.
- Give a `path` and a query string, never a URL with a host. The `path`
  is written into every URL as you give it, and the host of a request is
  whatever its `Host` header says, which the client chooses.
- `simple_paginate` keeps `has_more` beside Laravel's fields.

[`Inertia::paginate`](frontend-inertia-responses.md) attaches Inertia
scroll metadata (page identifiers, not absolute URLs), and
[`Resource::paginated`](eloquent-resources.md) attaches JSON:API
`links.{self,first,last,prev,next}` per the JSON:API recommendation. The
page URLs and helpers of the bare paginator are covered in the
[URL generation](#url-generation-and-paths) section.

## `paginate` - length-aware

```rust
use suprnova::LengthAwarePaginator;
use crate::models::User;

pub async fn index(_req: suprnova::Request) -> suprnova::Response {
    let page: LengthAwarePaginator<User> = User::query()
        .filter("active", true)
        .order_by_desc("created_at")
        .paginate(20)
        .await?;

    Ok(suprnova::json_response!(page))
}
```

The struct's public fields:

```rust
pub struct LengthAwarePaginator<T> {
    pub data: Vec<T>,           // rows on this page
    pub current_page: u64,       // 1-based
    pub last_page: u64,          // 1-based; 1 when total == 0
    pub per_page: u64,
    pub total: u64,              // every row across all pages
    pub from: Option<u64>,       // 1-based first row index on this page
    pub to: Option<u64>,         // 1-based last row index on this page
    pub path: Option<String>,    // base URL for url_for_page (optional)
    pub page_name: Option<String>, // query key of the page; "page" when None
}
```

The JSON of a paginator with `with_path("/api/users")`, on page 2 of 3:

```json
{
  "current_page": 2,
  "data": [...],
  "first_page_url": "/api/users?page=1",
  "from": 11,
  "last_page": 3,
  "last_page_url": "/api/users?page=3",
  "links": [
    {"url": "/api/users?page=1", "label": "&laquo; Previous", "page": 1, "active": false},
    {"url": "/api/users?page=1", "label": "1", "page": 1, "active": false},
    {"url": "/api/users?page=2", "label": "2", "page": 2, "active": true},
    {"url": "/api/users?page=3", "label": "3", "page": 3, "active": false},
    {"url": "/api/users?page=3", "label": "Next &raquo;", "page": 3, "active": false}
  ],
  "next_page_url": "/api/users?page=3",
  "path": "/api/users",
  "per_page": 10,
  "prev_page_url": "/api/users?page=1",
  "to": 20,
  "total": 25
}
```

`path` is omitted from the JSON when unset. `from` and `to` are `null`
when the page is empty (no rows on this page, or the requested page is
past the last page). `next_page_url` is `null` on the last page, and
`prev_page_url` is `null` on the first page.

### The `links` array

`links` is the row of links that a pagination component draws. Each entry
has `url`, `label`, `page`, and `active`:

- The first entry is the link to the previous page. Its label is
  `&laquo; Previous`, with the entity written out, because a front end
  puts the label into the page as markup. Its `url` and `page` are `null`
  on the first page.
- One entry follows for each page in the window, labelled with the page
  number. `active` is `true` for the current page only.
- Where pages are left out, an entry with the label `...` stands in. It
  has a `null` `url`, and it has no `page` key.
- The last entry is the link to the next page. Its label is
  `Next &raquo;`. Its `url` and `page` are `null` on the last page.

The window is Laravel's. Up to 13 pages, every page is listed. With more
pages, the row lists the first two pages, the last two pages, and seven
pages around the current one, with `...` between the groups. Near either
end, the pages of that end are listed in one run of ten instead. For 50
pages with page 25 current, the labels are `1 2 ... 22 23 24 25 26 27 28
... 49 50`.

When you have no matches, you get `last_page` 1 and page URLs pointing to
page 1 (`?page=1` with no path). Your `links` array includes page 1 between
the disabled previous and next links.

In Rust, `links()` returns the same entries as `Vec<PageLink>`. A
`PageLink` has the public fields `url: Option<String>`, `label: String`,
`page: Option<u64>`, and `active: bool`.

### Reading `?page=N` automatically

Use `paginate(n)` to read `?page=N` from your active request through
`Context::query_param`. You get page 1 for missing, empty, non-numeric,
or below-one values, including `?page=0`, `?page=-1`, and `?page=abc`.

### Multiple paginators on one page

When a page renders more than one paginated list, give each its own
query-string key with `paginate_using`:

```rust
let posts = Post::query()
    .order_by_desc("created_at")
    .paginate_using("posts_page", 10)
    .await?;

let comments = Comment::query()
    .order_by_desc("created_at")
    .paginate_using("comments_page", 25)
    .await?;
```

`paginate_using` also sets `page_name` on the returned paginator so
`url_for_page` builds URLs with the same key:

```rust
posts.url_for_page(2);     // "/posts?posts_page=2"  (when path is set)
comments.url_for_page(3);  // "/posts?comments_page=3"
```

### Page-position predicates

The full Laravel `AbstractPaginator` predicate set is implemented:

```rust
page.has_more_pages();   // current_page < last_page
page.on_first_page();    // current_page <= 1
page.on_last_page();     // !has_more_pages()
page.has_pages();        // we're not on page 1 OR more pages exist
page.is_empty();         // data.is_empty()
page.is_not_empty();     // !is_empty()
page.count();            // data.len() - page slice, not total
```

`count()` is the slice size, not the total - Laravel's `Countable`
shape; for the total use the `total` field directly.

## `simple_paginate` - one query, no count

```rust
use suprnova::Paginator;
use crate::models::User;

let page: Paginator<User> = User::query()
    .order_by_desc("id")
    .simple_paginate(20)
    .await?;
```

```rust
pub struct Paginator<T> {
    pub data: Vec<T>,
    pub current_page: u64,
    pub per_page: u64,
    pub has_more: bool,          // was there an extra row past per_page?
    pub path: Option<String>,
    pub page_name: Option<String>, // query key of the page; "page" when None
}
```

JSON, with `with_path("/api/users")`, on page 2:

```json
{
  "current_page": 2,
  "current_page_url": "/api/users?page=2",
  "data": [...],
  "first_page_url": "/api/users?page=1",
  "from": 11,
  "has_more": true,
  "next_page_url": "/api/users?page=3",
  "path": "/api/users",
  "per_page": 10,
  "prev_page_url": "/api/users?page=1",
  "to": 20
}
```

`next_page_url` is `null` when `has_more` is `false`, and `prev_page_url`
is `null` on the first page. `from` and `to` are `null` for a page with no
rows. `path` is omitted when unset.

`simple_paginate(n)` reads the page from `?page=N`. To give a listing its
own key, as `paginate_using` does for the length-aware paginator, call
`simple_paginate_using`:

```rust
let comments: Paginator<Comment> = Comment::query()
    .order_by_desc("id")
    .simple_paginate_using("comments_page", 25)
    .await?;

comments.url_for_page(2);  // "?comments_page=2"
```

It reads the page from `?comments_page=N` and sets `page_name`, so the
page URLs and the Inertia scroll metadata's `pageName` use the same key.

The trick is in the SQL. `simple_paginate(20)` issues `LIMIT 21`, looks
at whether the 21st row came back, sets `has_more` from that, and
truncates `data` back to 20. One query per page; no `COUNT(*)`.

You give up `total`, `last_page`, `last_page_url`, and `links`. In exchange you can
paginate tables where `COUNT(*)` is too expensive to run on every page
load. The UI surface is "Next" / "Previous" buttons, not "page 7 of
142".

The same predicate set as the length-aware paginator is implemented:
`has_more_pages()`, `on_first_page()`, `on_last_page()`, `has_pages()`,
`is_empty()`, `is_not_empty()`, `count()`.

## `cursor_paginate` - opaque keyset

```rust
use suprnova::CursorPaginator;
use crate::models::User;

let page: CursorPaginator<User> = User::query()
    .cursor_paginate(20)
    .await?;
```

```rust
pub struct CursorPaginator<T> {
    pub data: Vec<T>,
    pub per_page: u64,
    pub next_cursor: Option<String>,    // None on the last page
    pub prev_cursor: Option<String>,    // None on the first page
    pub path: Option<String>,
    pub cursor_name: Option<String>,    // query key of the cursor; "cursor" when None
    pub current_cursor: Option<String>, // the cursor this page was fetched with
}
```

JSON, with `with_path("/api/users")`:

```json
{
  "data": [...],
  "path": "/api/users",
  "per_page": 10,
  "next_cursor": "...",
  "next_page_url": "/api/users?cursor=...",
  "prev_cursor": null,
  "prev_page_url": null
}
```

`next_cursor`, `next_page_url`, `prev_cursor`, and `prev_page_url` are
always present as JSON keys (`null` when absent) so client schemas can
rely on field presence. A URL is the `path` with the cursor in the
`cursor` key, and it is `null` when its cursor is. `path` is omitted when
unset.

### How cursors work on the wire

The client passes the previous page's cursor through `?cursor=<opaque>`:

```
GET /api/users?cursor=eyJ0IjoiQmlnSW50IiwidiI6MTAwLCJkIjoibmV4dCJ9...
```

`cursor_paginate` decodes the cursor, walks the keyset filter past the
boundary in your query's order (for `prev`, in the reversed order, and
then reverses the page back), fetches `LIMIT n+1` rows, and re-emits
`next_cursor` / `prev_cursor` as the page's neighbours exist. It's
bidirectional - the client can walk forward and back without losing
its position. With no `order_by`, the filter is `pk > boundary ASC` for
`next` and `pk < boundary DESC` for `prev`. The page keeps the cursor it
was fetched with in `current_cursor`, and `None` on the first page.

`cursor_paginate` keeps your query's order, as Laravel's
`cursorPaginate` does. A descending order walks downward, so a list that
starts with the newest row stays newest first on every page:

```rust
let page = User::query()
    .latest() // ORDER BY created_at DESC
    .cursor_paginate(20)
    .await?;
```

Order by several columns to keep ties in your chosen order:

```rust
let page = User::query()
    .order_by_desc("created_at")
    .order_by_asc("id")
    .cursor_paginate(20)
    .await?;

let cursor = suprnova::Cursor::decode(page.next_cursor.as_deref().ok_or_else(||
    suprnova::FrameworkError::bad_request("No next page"))?)?;
let created_at = cursor.parameter("created_at");
let id = cursor.parameter("id");
```

You carry every ordered column in a named map, with each value's SQL type.
`Cursor::parameter(name)` returns `None` for a missing name. The boundary
compares the first column, then the next column when the earlier values
tie. You preserve mixed ascending and descending orders while moving in
either direction. The builder adds the primary key, ascending, when
your ordered columns do not include it, so ties have a stable final
order: `latest()` walks `created_at DESC, id ASC`. Select every ordered
column and use non-null values. A missing cursor parameter, a null
boundary, or an order the cursor cannot carry (`order_by_raw`,
`in_random_order`) returns a 400 error rather than a page in another
order. An order on a joined table's column, such as `teams.name`, also
returns a 400 error, because the cursor reads each boundary from the model
row, which holds none of the joined table's values. Order by the model's
own columns instead, bare or qualified with the model's table
(`users.created_at`); in a joined query, the builder qualifies the primary
key it adds the same way and quotes each ordered column, so a table name
with capitals also works on Postgres.
An `OFFSET` on the builder positions the first page only, the page
requested without a cursor. Every later page starts at its cursor, so
an offset never skips rows between two pages.

On a union, the cursor bounds the rows of the whole union, written as a
derived table, so every arm is paged together. The first query keeps an
ordering and a limit it had before `union`.

### Cursors are encrypted and authenticated

Suprnova cursors are **not** Laravel's base64-JSON plaintext. The wire
cursor contains the named boundaries (typed `sea_orm::Value` values -
`Int`, `BigInt`, `Uuid`, datetimes, decimals, strings, bytes) plus a direction
tag, JSON-encoded and then sealed with AES-256-GCM via the framework
`Crypt` keyring (bound to `CryptPurpose::Cursor`, so a cursor
ciphertext can never be replayed into any other surface - cookie, 2FA
secret, cast).

This means three things in practice:

1. **No tampering.** A client that flips bits in `?cursor=` gets a 400
   `Invalid pagination cursor`, not a different page of data.
2. **No information leak.** The boundary value (often a primary key,
   sometimes a timestamp) is sealed inside the cursor - clients can't
   enumerate ranges by editing it.
3. **Typed boundaries round-trip losslessly.** The wire envelope tags
   the SeaORM variant (`"BigInt"`, `"Uuid"`, etc.), so on decode the
   value re-binds with the same SQL type the original column emitted.
   No string-coercion bugs across Postgres / MySQL / SQLite.

There is no plaintext fallback. If `Crypt` is not initialised - which
should be impossible after `Server::from_config` - encoding errors
rather than emitting a forgeable cursor.

### Why Suprnova diverges

Laravel's cursor paginator is forward-only by default and the wire
cursor is a base64-encoded JSON blob - readable, editable, replayable.
Suprnova's cursor is bidirectional (matching the `cursorPaginate()`
surface Laravel added later) and is authenticated end-to-end so the
client can't construct or alter one. The Rust ecosystem already has
AES-GCM as a primitive; using it costs the framework one extra trait
impl and gives every cursor a security property a plaintext base64
payload can't offer.

## The facade - `Pagination::length_aware` / `Pagination::cursor`

Most chapters of this manual show pagination through the Eloquent
builder, because that's the common path. If you're building a SeaORM
`Select<E>` directly - say, joining onto a non-model query for a
report - the `Pagination` facade is the equivalent surface:

```rust
use suprnova::{Pagination, LengthAwarePaginator};
use sea_orm::EntityTrait;

let select = User::find()  // or any SeaORM Select<E>
    .filter(user::Column::Active.eq(true));

let page: LengthAwarePaginator<user::Model> =
    Pagination::length_aware(select, 20, 1).await?;
```

The facade also offers `length_aware_on(conn, ...)` and
`cursor_on(conn, ...)` for routing to a specific named connection, and
a typed `cursor(query, cursor, per_page, order_col)` form that takes
the keyset column explicitly - used when the cursor sorts on something
other than the primary key.

When your `Select` orders by several entity columns, `Pagination::cursor`
keeps each column and direction. Include a unique column to break ties.
With zero or one explicit order, you order by the supplied `order_col`
alone, ascending. You apply an `OFFSET` to the first page only.

`Pagination::length_aware` treats the `Select` the way `paginate` does,
as in Laravel: it drops a `LIMIT` and an `OFFSET` the `Select` already
has, so the total counts every matching row and the page takes its own
limit and offset.

Routing rules match the Eloquent builder. An ambient
`DB::transaction` is honoured (both the COUNT and the page query run on
the transaction's connection), and a registered `__read_replica__`
connection is used automatically for reads. The `__primary__` sentinel
selects the default pool when you want to bypass the replica.

## Validation - `per_page == 0`

All three methods reject `per_page == 0`:

```rust
let result = User::query().paginate(0).await;
assert!(matches!(
    result,
    Err(FrameworkError::ParamError { ref param_name }) if param_name == "per_page",
));
```

The error renders as HTTP 400 with the standard error body. There is no
silent "empty page" - a zero page size is always wrong and is rejected
at the call site, matching the Eloquent builder and the `Pagination`
facade. The same validation lives on `cursor_paginate`, `simple_paginate`,
`Pagination::length_aware`, `Pagination::length_aware_on`,
`Pagination::cursor`, and `Pagination::cursor_on` - one rule, six
entry points.

The `current_page` value is **clamped**, not validated: `0` becomes `1`,
negative numbers from a defensive frontend cannot happen (the parser is
`u64`), and any `?page=N` greater than `last_page` returns a paginator
with empty `data` plus `from`/`to` of `None`. Walking past the end is
the client's mistake, not an error.

## Error shape

| Condition | Variant | HTTP |
|---|---|---|
| `per_page == 0` | `FrameworkError::ParamError { param_name: "per_page" }` | 400 |
| Tampered / invalid cursor | `FrameworkError::Domain` (`"Invalid pagination cursor"`) | 400 |
| `Crypt` not initialised at cursor decode | `FrameworkError::Internal` | 500 |
| Cursor variant mismatch on `decode_cursor` | `FrameworkError::Internal` | 500 |
| Underlying DB failure | `FrameworkError::Database` | 500 |

The tampered-cursor case is the one to remember. Cursors are read
directly off the wire - the `?cursor=…` query string is attacker input
by definition, and bit-flipped base64 and replayed ciphertext are
expected failure modes, not server bugs. The decryption step downgrades
to a 400 `Invalid pagination cursor` so client-triggerable failures
don't pollute the 500 telemetry channel. The static message gives the
client nothing to probe with.

Post-decrypt failures (JSON parse, variant-tag dispatch, direction
parse) stay 500 - any byte sequence that survived AEAD authentication
was produced by *us*, so a malformed payload past that point is a
framework bug worth flagging.

## URL generation and paths

The paginator carries an optional `path` field. When set,
`url_for_page(n)` and the cursor link emission use it to build query
strings:

```rust
let page = User::query()
    .paginate(20)
    .await?
    .with_path("/api/users");

page.url_for_page(1);    // "/api/users?page=1"
page.url_for_page(2);    // "/api/users?page=2"
```

When the base path already carries a query string, the separator
switches to `&` so the URL stays well-formed:

```rust
let page = User::query()
    .paginate(20)
    .await?
    .with_path("/users?sort=name");

page.url_for_page(2);    // "/users?sort=name&page=2"
```

If `path` is unset, `url_for_page` falls back to a bare relative
query: `?page=2`. The page-parameter name comes from
`with_page_name(...)` (defaulting to `"page"`); `paginate_using(name, n)`
sets it automatically so the generated URLs use the same key the
paginator was driven from. The parameter name is form-urlencoded, so
even a name with reserved characters can't corrupt the URL.

A page parameter that the `path` already has is replaced, so you can give
the path and query string of the current request as the `path`. A
fragment of the `path` stays at the end of the URL:

```rust
let page = User::query()
    .paginate(20)
    .await?
    .with_path("/users?role=admin&page=2#list");

page.url_for_page(3);    // "/users?role=admin&page=3#list"
```

The JSON uses these URLs for `first_page_url`, `last_page_url`,
`next_page_url`, `prev_page_url`, and each `url` in `links`.

In Rust, each paginator returns the same values as methods:

| Paginator | Methods |
|---|---|
| `LengthAwarePaginator` | `url_for_page(n)`, `next_page_url()`, `previous_page_url()`, `links()` |
| `Paginator` | `url_for_page(n)`, `next_page_url()`, `previous_page_url()`, `first_item()`, `last_item()` |
| `CursorPaginator` | `next_page_url()`, `previous_page_url()` |

`next_page_url()` and `previous_page_url()` return `None` where the JSON
has `null`.

Cursor paginators have the same shape: `with_path(...)` sets the base,
`with_cursor_name(...)` overrides the query key (defaults to `"cursor"`),
and the JSON:API link builder picks them up automatically.

Most apps hand the paginator straight to a response. The JSON already
carries the URLs, and the two integration surfaces below build the URLs
the right way for their protocol.

## Inertia integration - infinite scroll props

For Inertia front-ends, the `Inertia::paginate(component, key, paginator)`
helper attaches the paginator as a scroll prop:

```rust
use suprnova::Inertia;

pub async fn index(_req: suprnova::Request) -> suprnova::Response {
    let users = User::query()
        .order_by_desc("created_at")
        .cursor_paginate(20)
        .await?;

    Ok(Inertia::paginate("Users/Index", "users", users).into())
}
```

All three paginators work here - `LengthAwarePaginator`, `Paginator`, and
`CursorPaginator`. The metadata page-name comes from the paginator
itself, and it is the query parameter the paginator reads: the name a
`LengthAwarePaginator` got from `paginate_using` or `with_page_name`
(`"page"` by default), the name a `Paginator` got from
`simple_paginate_using` or `with_page_name` (`"page"` by default), and the name a `CursorPaginator` got from
`with_cursor_name` (`"cursor"` by default). The client receives the rows
under the chosen prop key plus a `ScrollMetadata` descriptor with
`current_page`, `next_page` and `previous_page`: page numbers for the
offset paginators, and for a cursor paginator `1` on its first page,
else the cursor the page was fetched with (`cursor_paginate` and
`Pagination::cursor` record it; `with_current_cursor` sets it by hand),
else the request's cursor parameter. The `useInfiniteScroll` and `WhenVisible` Inertia helpers
consume it for infinite scroll.

Each paginator builds that descriptor through `ProvidesScrollMetadata` -
the same interface Laravel's paginator adapter satisfies
(`ProvidesScrollMetadata::getPageName` / `getPreviousPage` / `getNextPage`
/ `getCurrentPage`). A paginator this crate doesn't know about - a
third-party crate's cursor type, a hand-rolled repository result - can
implement the four methods and hand the framework a `ScrollMetadata` the
same way: see [Inertia
Responses](frontend-inertia-responses.md#merge-strategies-and-infinite-scroll).

`simple_paginate` is worth calling out, because a listing over a table
big enough to make `COUNT(*)` the dominant cost of the request is exactly
where an Inertia collection page hurts:

```rust
let users = User::query()
    .order_by_asc("id")
    .simple_paginate(20)     // no COUNT, one query
    .await?;

Ok(Inertia::paginate("Users/Index", "users", users).into())
```

Its `next_page` comes from the `LIMIT n+1` overflow probe rather than
from a computed last page, since there is no total to compute one from.
The client gets "there is another page" instead of "there are 4,812
pages" - which is all an infinite-scroll UI ever reads.

### Projecting rows before they go out

Use `through(transform)` to change the item type on a length-aware,
simple, or cursor page. You preserve every count, URL setting, and cursor:

```rust
let page = User::query().cursor_paginate(20).await?;
let page = page.through(PublicUser::from);
```

Your closure runs once per item in order. It does not run for an empty
page. You keep pagination metadata unchanged, so a resource projection
still describes the query that produced the page.
The same helper exists as a chainable method on
`InertiaResponse::paginate(key, paginator)` if you want to mix a
paginator with other props:

```rust
inertia_response!("Dashboard")
    .with("stats", &stats)
    .paginate("recent_users", users)
    .into()
```

See [Inertia Responses](frontend-inertia-responses.md) for the broader
prop model.

## JSON:API integration - `Resource::paginated`

For JSON:API consumers, `Resource::paginated(paginator)` builds the
full envelope:

```rust
use suprnova::Resource;

pub async fn index(_req: suprnova::Request) -> suprnova::Response {
    let users = User::query()
        .paginate(20)
        .await?
        .with_path("/api/users");

    Ok(Resource::paginated(users).into())
}
```

The response carries:

- `data` - every row rendered through the model's `IntoJsonResource`.
- `meta.pagination` - `{ total, per_page, current_page, last_page }`
  for length-aware; `{ next_cursor, prev_cursor }` for cursor.
- `links.{self,first,last,prev,next}` - absolute hrefs for the
  length-aware paginator (built from `path`); `links.{prev,next}` for
  the cursor paginator.

Both paginator types implement the `Paginated<T>` trait that
`Resource::paginated` consumes - there is no separate code path for
length-aware vs cursor. If you build a custom paginator-like type that
implements `Paginated<T>`, it composes the same way.

See [JSON:API resources](eloquent-resources.md) for the resource
model.

## Custom JSON envelopes

If neither Inertia nor JSON:API matches your client, ship the
paginator directly through `json_response!`:

```rust
let page = User::query().paginate(20).await?;
Ok(suprnova::json_response!({
    "users": page.data,
    "pagination": {
        "current_page": page.current_page,
        "last_page": page.last_page,
        "per_page": page.per_page,
        "total": page.total,
    }
}))
```

Or just hand the whole paginator across - its `Serialize` impl
emits the shape documented above:

```rust
Ok(suprnova::json_response!(User::query().paginate(20).await?))
```

The fields are public; reshape as your contract requires.

## Routing across connections

Pagination respects the same multi-connection routing the Eloquent
builder uses. Inside a `DB::transaction(...)` the COUNT and the page
query both run on the transaction's connection - they never split
across connections, so the count never disagrees with the page it
described. A registered `__read_replica__` is used automatically for
reads outside a transaction. To pin a paginator to a specific named
connection use the `_on(connection, ...)` variants on the `Pagination`
facade, or `Builder::on("replica_b").paginate(20)` from the Eloquent
side.

See [Eloquent - multi-connection routing](eloquent.md) for the routing
contract.

## When to reach for which

A rough decision tree:

- **Numeric page UI is part of the design** → `paginate`. You need
  `last_page` to render "Page 3 of 17", and the COUNT cost is OK on
  your table size.
- **"Next" / "Previous" buttons only, large table** → `simple_paginate`.
  One query per page; you give up `total` and `last_page` but the page
  load halves.
- **Infinite scroll** → `cursor_paginate`. Bidirectional cursors mean
  the client can keep scrolling past page 1000 without the OFFSET
  scanning thousands of rows first.
- **Tail of a hot append-only feed** → `cursor_paginate`. Keyset
  ordering by primary key is concurrent-safe: new rows land beyond the
  cursor, never inside it. OFFSET-based pagination skips rows under
  inserts.
- **Building a `Select<E>` outside an Eloquent model** →
  `Pagination::length_aware` / `Pagination::cursor`. Same trade-offs;
  the facade is the model-less equivalent.

When in doubt, start with `paginate`. Move to `simple_paginate` when
the `COUNT(*)` shows up in your slow query log. Move to
`cursor_paginate` when deep pages start dominating request time, or
when the UI is infinite scroll.

## Where each piece lives

| Piece | File |
|---|---|
| `Pagination` facade, `Paginated<T>` trait | `framework/src/pagination/mod.rs` |
| `LengthAwarePaginator<T>` | `framework/src/pagination/length_aware.rs` |
| `Paginator<T>` (simple) | `framework/src/pagination/simple.rs` |
| `CursorPaginator<T>`, `Cursor`, `CursorDirection`, `encode_value`, `decode_value` | `framework/src/pagination/cursor.rs` |
| `IntoInertiaScroll` bridge | `framework/src/pagination/inertia.rs` |
| `Builder::paginate` / `simple_paginate` / `simple_paginate_using` / `cursor_paginate` | `framework/src/eloquent/builder.rs` |
| `Inertia::paginate`, `InertiaResponse::paginate` | `framework/src/inertia/facade.rs`, `framework/src/inertia/response.rs` |
| `Resource::paginated`, `JsonApi::paginated` | `framework/src/resources/response.rs` |

## Next

- [Eloquent API](eloquent.md) - the model layer that drives every
  paginator returned from `Builder::paginate*`
- [Query Builder](queries.md) - the model-less queries that compose
  with `Pagination::length_aware` and `Pagination::cursor`
- [Inertia Responses](frontend-inertia-responses.md) - how scroll
  props attach paginators to Inertia pages
- [JSON:API resources](eloquent-resources.md) - `Resource::paginated`,
  links, meta, and the `Paginated<T>` trait
- [Error Model](error-model.md) - the `FrameworkError::param`
  validation rule and the cursor-tampering downgrade


---

<!-- /docs/migrations -->

# Migrations

Migrations describe how your schema evolves - each file is a small Rust struct with `up()` and `down()` methods that the framework runs in timestamp order. Use them whenever you change tables, columns, indexes, or foreign keys; that change moves from your laptop to staging to production by running the same migrate command in each place.

Suprnova's migrations are SeaORM migrations underneath. The CLI generates them, the `Migrator` aggregates them, and `Application::migrations::<Migrator>()` plugs them into your app's boot. For the full per-command reference (flags, output samples, exit codes) see [CLI Migrations Reference](cli-migrations.md); this chapter covers what to put *inside* the files.

## Creating migrations

Generate a new migration file:

```bash
suprnova make:migration create_users_table
```

The generator writes a timestamped file under `src/migrations/` (creating the
directory the first time) and registers it in the `Migrator`:

```
src/migrations/
├── mod.rs                              ← the Migrator (CLI-managed)
└── m20240115_120000_create_users_table.rs
```

The filename is `m{YYYYMMDD}_{HHMMSS}_<name>.rs`; ordering is by filename, so
the timestamp prefix is what enforces a deterministic apply order.

### What the generator emits

`make:migration create_users_table` produces this skeleton:

```rust
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .create_table(
                Table::create()
                    .table(Users::Table)
                    .if_not_exists()
                    .col(
                        ColumnDef::new(Users::Id)
                            .integer()
                            .not_null()
                            .auto_increment()
                            .primary_key(),
                    )
                    .col(
                        ColumnDef::new(Users::CreatedAt)
                            .timestamp()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .col(
                        ColumnDef::new(Users::UpdatedAt)
                            .timestamp()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .to_owned(),
            )
            .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .drop_table(Table::drop().table(Users::Table).to_owned())
            .await
    }
}

#[derive(DeriveIden)]
enum Users {
    Table,
    Id,
    CreatedAt,
    UpdatedAt,
}
```

The generator infers the table name from the migration name
(`create_X_table` → `X`, `add_Y_to_X` → `X`, `drop_X_table` → `X`). Anything
else becomes the literal name.

### The Migrator

`src/migrations/mod.rs` collects every migration into a single `Migrator`
that `MigratorTrait` walks. The CLI maintains this file when you
`make:migration`, so you rarely touch it by hand:

```rust
pub use sea_orm_migration::prelude::*;

mod m20240115_120000_create_users_table;
mod m20240115_130000_create_posts_table;

pub struct Migrator;

#[async_trait::async_trait]
impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            Box::new(m20240115_120000_create_users_table::Migration),
            Box::new(m20240115_130000_create_posts_table::Migration),
        ]
    }
}
```

Wire the migrator into your app's `main.rs` so `serve`, `migrate`,
`migrate:status`, `migrate:rollback`, and `migrate:fresh` all see the same
list:

```rust
use suprnova::Application;

#[suprnova::main]
async fn main() {
    Application::new()
        .config(my_app::config::register)
        .bootstrap(my_app::bootstrap::bootstrap)
        .routes(my_app::routes::register)
        .migrations::<my_app::migrations::Migrator>()
        .run()
        .await
}
```

The scaffolder writes this for you on `suprnova new`.

### Migrations from the framework and from crates

Some migrations live outside `src/migrations`: the framework's two-factor
tables, a payments adapter's schema, or an internal crate your applications
share. Load such a list with `Application::load_migrations_from`, and every
migrate command runs it after your migrator's own list: `migrate`,
`migrate:status`, `migrate:rollback`, `migrate:fresh`, `schema:dump` and the
migration `serve` runs on boot. Laravel's service providers do the same with
`loadMigrationsFrom`.

```rust
use suprnova::Application;

#[suprnova::main]
async fn main() {
    Application::new()
        .config(my_app::config::register)
        .bootstrap(my_app::bootstrap::bootstrap)
        .routes(my_app::routes::register)
        .migrations::<my_app::migrations::Migrator>()
        .load_migrations_from(suprnova::auth_flows::two_factor::migrations)
        .load_migrations_from(suprnova::payments::migrations::migrations)
        .run()
        .await
}
```

A list is a function that returns the migrations in order,
`fn() -> Vec<Box<dyn MigrationTrait>>`. A crate registers its own list for
every application that links it with `register_migrations!`, in its
`lib.rs`:

```rust
pub fn migrations() -> Vec<Box<dyn sea_orm_migration::MigrationTrait>> {
    vec![Box::new(m_2026_10_01_create_invoices::Migration)]
}

suprnova::register_migrations!("acme-billing", migrations);
```

The order is your migrator's list, then each loaded list in the order you
loaded it, then the registered lists by owner name. A migration whose name
an earlier list already holds runs once, so a list that repeats a migration
your migrator lists is harmless. The framework registers none of its own
migrations: an application that never loads the two-factor list gets none
of its tables.

`migrate:status` prints every migration of the combined list with
`Applied` or `Pending`, one line each. `TestDatabase::fresh::<Migrator>()`
runs the migrator you name and nothing else; list what a test needs in that
migrator.

### Why Suprnova diverges

Most of the framework deliberately hides SeaORM - you write `#[suprnova::model]`
and `User::query().db_where(...)`, not `Entity::find().filter(...)`. Migrations
are the one place where SeaORM stays visible. Two reasons.

First, the schema builder compiles to SeaORM's own statements
(`Table::create()`, `Table::alter()`, `Index`, `ForeignKey`) and runs them on
the migration's `SchemaManager`. It adds no migration engine, so SeaORM is one
step away for everything the builder does not cover: a column type change, a
check constraint, a raw statement. You write that step with
`sea_orm_migration::prelude::*` in the same `up()`. Second, migration files are
pure Rust - your CI compiler verifies them.

If you need a SeaORM type the framework has not re-exported, the escape hatch
is `use suprnova::sea_orm;`.

The builder differs from Laravel's `Blueprint` in four ways:

- `timestamps()` and `soft_deletes()` create string columns, not native
  date-time columns. A model stores a `DateTime<Utc>` field as RFC 3339 text
  by default, and the string column is the one type that round-trips on all
  three backends. Laravel's native forms are `timestamps_tz()`,
  `datetimes()`, `soft_deletes_tz()` and `soft_deletes_datetime()`, paired
  with a native cast on the model.
- There is no table rebuild on SQLite. An operation SQLite cannot run in place
  returns an error that names the operation.
- There is no column type change. `Schema::table` adds, renames and drops
  columns, but it does not alter the type of an existing column.
- `suprnova make:migration` generates the SeaORM form. The schema builder is
  the alternative you write by hand.

See [The schema builder](#the-schema-builder).

## Migration structure

Every migration has two methods:

```rust
#[async_trait::async_trait]
impl MigrationTrait for Migration {
    // Apply the change
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> { /* ... */ }

    // Reverse the change
    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> { /* ... */ }
}
```

Both arms return `Result<(), DbErr>` - bubble errors with `?` and the framework
turns a failed migration into a non-zero exit so deploy pipelines abort.

## The schema builder

`suprnova::schema::Schema` is a shorter way to write the common migration. A
closure records columns, indexes and foreign keys on a `Blueprint`, and the
builder turns the description into SQL. This is the posts migration as a
complete file:

```rust
use sea_orm_migration::prelude::*;
use suprnova::schema::Schema;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        Schema::create(manager, "posts", |t| {
            t.id();
            t.string("title");
            t.text("body").nullable();
            t.string("slug").length(120).unique();
            t.boolean("published").default(false);
            t.foreign_id("author_id")
                .constrained("users")
                .on_delete(ForeignKeyAction::Cascade);
            t.index(&["published", "created_at"]);
            t.timestamps();
            t.soft_deletes();
        })
        .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        Schema::drop_if_exists(manager, "posts").await
    }
}
```

Every `Schema` function is `async`, takes the migration's `manager`, and
returns `Result<_, DbErr>`. The builder opens no connection of its own, so each
statement runs on the migration's connection and inside its transaction.

The layer lives at `suprnova::schema::Schema`. Import it by that path.
`suprnova::Schema` at the crate root is SeaORM's `Schema`, a different type.

### Entry points

| Function | Effect |
|----------|--------|
| `Schema::create(manager, table, closure)` | Creates the table, then its indexes. Foreign keys are part of `CREATE TABLE`. |
| `Schema::table(manager, table, closure)` | Alters an existing table. |
| `Schema::drop(manager, table)` | Drops the table. It is an error if the table does not exist. |
| `Schema::drop_if_exists(manager, table)` | Drops the table if it exists. |
| `Schema::rename(manager, from, to)` | Renames a table. |
| `Schema::has_table(manager, table)` | Returns `Result<bool, DbErr>`: whether the table exists. |
| `Schema::has_column(manager, table, column)` | Returns `Result<bool, DbErr>`: whether the column exists. |

### Column methods

A column is `NOT NULL` unless you call `.nullable()` or use `timestamps()`. The table lists the column
each method creates. The SQLite column is the type name SQLite stores, and its
affinity is what the database reports.

| Method | SQLite | Postgres | MySQL |
|--------|--------|----------|-------|
| `id()` | `integer`, auto-increment, primary key | `bigserial`, primary key | `bigint unsigned`, auto-increment, primary key |
| `unsigned_id()` | as `id()` | as `id()` | `bigint unsigned`, auto-increment, primary key |
| `foreign_id(name)` | `integer` | `bigint` | `bigint unsigned` |
| `unsigned_foreign_id(name)` | `integer` | `bigint` | `bigint unsigned` |
| `big_integer(name)` | `integer` | `bigint` | `bigint` |
| `integer(name)` | `integer` | `integer` | `int` |
| `small_integer(name)` | `integer` | `smallint` | `smallint` |
| `tiny_integer(name)` | `integer` | `smallint` | `tinyint` |
| `unsigned_big_integer(name)`, `unsigned_integer(name)`, `unsigned_small_integer(name)`, `unsigned_tiny_integer(name)` | the signed type | the signed type | the type, `unsigned` |
| `boolean(name)` | `tinyint(1)` | `boolean` | `tinyint(1)` |
| `string(name)` | `varchar(255)` | `varchar(255)` | `varchar(255)` |
| `char(name, length)` | `char(length)` | `char(length)` | `char(length)` |
| `text(name)` | `text` | `text` | `text` (64 KB) |
| `medium_text(name)` | `text` | `text` | `mediumtext` (16 MB) |
| `long_text(name)` | `text` | `text` | `longtext` (4 GB) |
| `enumeration(name, &[values])` | `varchar` with `CHECK (name IN (..))` | `varchar(255)` with `CHECK (name IN (..))` | `enum(..)` |
| `float(name)` | `float` | `double precision` | `float(53)` |
| `double(name)` | `double` | `double precision` | `double` |
| `decimal(name, precision, scale)` | `decimal(precision, scale)` | `numeric(precision, scale)` | `decimal(precision, scale)` |
| `date(name)` | `date_text` | `date` | `date` |
| `time(name)` | `time_text` | `time` | `time` |
| `date_time(name)` | `datetime_text` | `timestamp` | `datetime` |
| `timestamp_tz(name)` | `datetime` | `timestamp(0) with time zone` | `timestamp(0)` |
| `json(name)` | `json_text` | `jsonb` | `json` |
| `uuid(name)` | `char(36)` | `uuid` | `char(36)` |
| `ulid(name)` | `char(26)` | `char(26)` | `char(26)` |
| `ulid_with_length(name, n)` | `char(n)` | `char(n)` | `char(n)` |
| `binary(name)` | `blob` | `bytea` | `blob` |
| `remember_token()` | nullable `varchar(100)` named `remember_token` | the same | the same |

`id()` is a `BIGINT` on Postgres and MySQL, and `foreign_id` has the same type.
The types match because MySQL refuses a foreign key between columns of
different types. A table has one `id()`.

Where the databases differ, the builder does what Laravel does rather than
refusing: `unsigned` applies on MySQL only, because Postgres and SQLite have no
unsigned integers; `tiny_integer`, `medium_text` and `long_text` take the
nearest type; and `enumeration` becomes a string with a `CHECK` off MySQL. An
`enumeration` value may contain a quote; the builder escapes it. The migration
fails on a value listed twice, which MySQL refuses, and on a value with a
backslash, which MySQL and Postgres read differently depending on server
settings.

A model field has to match the column's width on Postgres, whose driver reads
each integer type into one Rust type only: `i16` for `tiny_integer` and
`small_integer`, `i32` for `integer`, `i64` for `big_integer`, `id()` and
`foreign_id`. MySQL and SQLite read any signed integer column into `i64`.

You get Laravel's default float precision, 53 binary digits. Postgres uses
`double precision`; MySQL's `float(53)` selects double storage. You request
single precision with `t.float("ratio").precision(24)`. SQLite uses its native
floating point storage and ignores this setting.

You get whole-second zoned timestamps on Postgres unless you call
`.precision(n)`. SQLite declares `datetime` and keeps your supplied text,
including fractional seconds. You use a positive length with
`ulid_with_length("code", 20)` or `ulid("code").length(20)`.

You preview the validated CREATE SQL without connecting to the target engine:

```rust
let sql = suprnova::Blueprint::create_sql(
    "events", suprnova::sea_orm::DbBackend::Postgres, |t| {
        t.boolean("flag");
        t.float("ratio");
        t.timestamp_tz("at");
    },
)?;
```

You receive one string per statement, using the same plan as `Schema::create`.
Invalid precision or length returns a migration error before you execute SQL.

#### Laravel tables on MySQL

Laravel's `id()` and `foreignId()` are `BIGINT UNSIGNED` on MySQL, and MySQL
refuses a foreign key whose type differs from the referenced column's, sign
included. Use the default `id()` and `foreign_id()` for your new tables:

```rust
Schema::create(manager, "orders", |t| {
    t.id();
    t.foreign_id("user_id").constrained("users").cascade_on_delete();
    t.enumeration("status", &["draft", "paid"]).default("draft");
    t.timestamps_tz();
})
.await?;
```

A model reads an unsigned column into an unsigned field: the MySQL driver
refuses to read an unsigned column into a signed type, `BIGINT UNSIGNED` into
an `i64` included. Declare the key `u64`, and the foreign key fields `u64` to
match. The model takes its key type from the key field, so it needs no
`key_type`:

```rust
#[model(table = "orders")]
pub struct Order {
    pub id: u64,
    pub user_id: u64,
    pub status: String,
}
```

The same model runs on Postgres and SQLite, which have no unsigned integers.
There, `unsigned_id()` creates a signed `BIGINT`, and a `u64` field holds `0`
to `i64::MAX` (9223372036854775807). Writing a larger value fails with an
error that names the column, before anything reaches the database. It is a
database error, so a client gets the generic 500 response and the log gets
the detail. Reading by a larger value finds nothing, because no row holds
one: `find` returns `None`, and a route that binds such a key answers 404. A
negative value in the column fails the read, naming the column. The tests of
a Laravel port can therefore run on the SQLite `TestDatabase`.

You get unsigned IDs on MySQL by default, as Laravel creates them. Set
`unsigned_ids = false` in the package that builds your binary when your
schema needs signed IDs:

```toml
[package.metadata.suprnova.schema]
unsigned_ids = false
```

`#[suprnova::main]` installs the setting before your entry point runs.
Every migration uses it, including migrations from libraries. Your Postgres
and SQLite columns stay signed. An unknown key or value fails the build
with an error naming it. Your scaffold carries the opt-out commented out.

If you run migrations without `#[suprnova::main]`, install the signed
opt-out before your first migration:

```rust
suprnova::schema::Schema::set_unsigned_ids(false);
```

Use `Schema::set_unsigned_ids(true)` or `Schema::use_unsigned_ids()` to
restore the default before migrations.

### Modifiers

Each column method returns a builder. Chain the modifiers on it.

| Modifier | Effect |
|----------|--------|
| `.nullable()` | Allows `NULL`. |
| `.default(value)` | Sets the value the database stores when an insert leaves the column out. It takes a plain Rust value (`7`, `"draft"`, `false`) or a SeaQuery `Expr` such as `Expr::current_timestamp()`. |
| `.unique()` | Adds a unique index over this column alone, named `{table}_{column}_unique`. |
| `.length(n)` | Sets the length of a `string` or `ulid` column. On any other column type the migration fails with an error that names the column. Use `char(name, length)` for a fixed length. |
| `.index()` | Adds an index over this column alone, named `{table}_{column}_index`. |
| `.primary()` | Makes this column the primary key. For a key over several columns, `t.primary(&[..])`. |
| `.unsigned()` | `UNSIGNED` on MySQL, for an integer column. Ignored on Postgres and SQLite. On any other column type the migration fails. |
| `.precision(n)` | Sets 1 to 53 binary digits for `float`, or 0 to 6 fractional-second digits for `date_time`, `timestamp_tz` or `time`. You get 53 digits for `float` and whole seconds for `timestamp_tz` by default. SQLite ignores precision. |
| `.use_current()` | Defaults a `date_time` or `timestamp_tz` column to the current time, `CURRENT_TIMESTAMP`. Combined with `.default(..)` the migration fails. |
| `.after(column)` | Places a column that `Schema::table` adds after `column`, on MySQL. Ignored on Postgres and SQLite; `Schema::create` refuses it, because MySQL does. |

A native date-time column on MySQL keeps whole seconds unless you set a
precision, and drops the fraction a model writes: MySQL rounds it, MariaDB
truncates it. Declare
`t.timestamp_tz("paid_at").precision(6)` to keep microseconds. MySQL's
`TIMESTAMP` also ends in 2038; `date_time` does not.

### Timestamps and soft deletes

You use `t.timestamps()` to add nullable `created_at` and `updated_at`, as
Laravel does.
`t.soft_deletes()` adds a nullable `deleted_at`. These are `VARCHAR(255)`
columns on every backend, not native date-time columns.

The reason is the model. A `#[suprnova::model]` field of type `DateTime<Utc>`
with no declared cast uses `AsDateTime`, which stores RFC 3339 text
(see [Eloquent Mutators](eloquent-mutators.md)). Postgres refuses a text
parameter for a `timestamp` column. A string column round-trips on all three
backends.

For native date-time columns, use Laravel's helpers and give the model's
fields the matching cast (see
[Native date-time casts](eloquent-mutators.md#native-date-time-casts)):

| Helper | Columns | Cast |
|---|---|---|
| `t.timestamps_tz()` | nullable `created_at`, `updated_at` with a time zone | `AsNativeDateTime` |
| `t.soft_deletes_tz()` | nullable `deleted_at` with a time zone | `AsOptionalNativeDateTime` |
| `t.datetimes()` | nullable `created_at`, `updated_at` without a time zone | `AsNaiveDateTime` |
| `t.soft_deletes_datetime()` | nullable `deleted_at` without a time zone | `AsOptionalNaiveDateTime` |

```rust
Schema::create(manager, "orders", |t| {
    t.id();
    t.string("reference");
    t.timestamps_tz();
    t.soft_deletes_tz();
})
.await?;
```

```rust
use suprnova::{AsNativeDateTime, AsOptionalNativeDateTime, model};

#[model(
    table = "orders",
    soft_deletes,
    casts = {
        created_at = AsNativeDateTime,
        updated_at = AsNativeDateTime,
        deleted_at = AsOptionalNativeDateTime,
    },
)]
pub struct Order {
    pub id: i64,
    pub reference: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
    pub deleted_at: Option<chrono::DateTime<chrono::Utc>>,
}
```

Declare a single native column with `t.timestamp_tz("published_at")` or
`t.date_time("published_at")` and the same casts.

To give every model in a package one of these casts without naming it on each
field, set `datetime_cast` in the package's `Cargo.toml`. For more
information, see
[Native date-time casts](eloquent-mutators.md#native-date-time-casts).

### Indexes and foreign keys

```rust
Schema::create(manager, "comments", |t| {
    t.id();
    t.foreign_id("post_id")
        .constrained("posts")
        .on_delete(ForeignKeyAction::Cascade)
        .on_update(ForeignKeyAction::Cascade);
    t.string("author");
    t.index(&["post_id", "author"]);
    t.unique(&["post_id", "author"]);
})
.await
```

- `t.index(&["a", "b"])` creates an index named `{table}_{columns}_index`.
- `t.unique(&["a", "b"])` creates a unique index named `{table}_{columns}_unique`.
- The columns are joined with `_` in the name.
- Indexes are separate `CREATE INDEX` statements that run after the table.
- On Postgres, `Schema::create`, `Schema::table`, `Schema::drop`,
  `Schema::drop_if_exists` and `Schema::rename` read a table named
  `schema.table` as that table in that schema, as Laravel does, and the
  `.` becomes `_` in the index and foreign key names. On MySQL and SQLite
  the builder refuses a schema-qualified name.
- `foreign_id(name).constrained(table)` creates a foreign key to the `id`
  column of `table`, named `{table}_{column}_foreign`.
- `.references(table, column)` points the key at another column. On MySQL that
  column must be a `BIGINT`.
- `.on_delete(action)` and `.on_update(action)` take a `ForeignKeyAction`. The
  database default (`NO ACTION`) applies when you do not call them.
- A `foreign_id` with no `constrained` or `references` call is a plain `BIGINT`
  column.
- `.cascade_on_delete()`, `.restrict_on_delete()`, `.null_on_delete()` and
  `.no_action_on_delete()` are short for `.on_delete(..)` with that action, and
  the `_on_update` forms for `.on_update(..)`.
- `.name("orders_state_fk")` names the constraint instead of
  `{table}_{column}_foreign`. A name used twice in one closure, by two keys or
  by a key and an index, fails the migration.
- `.null_on_delete()` and `.null_on_update()` need a nullable column. On a
  column the closure declares `NOT NULL` the migration fails before its first
  statement, because MySQL would refuse the key only after adding the column.
- `t.foreign("state_id")` creates a foreign key on a column declared on its own,
  or one the table already has in `Schema::table`. It takes the same
  `.references(table, column)`, `.constrained(table)`, `.name(..)` and actions,
  and without a referenced table the migration fails.
- `t.primary(&["post_id", "tag_id"])` makes a composite primary key, as a pivot
  table needs. A table has one primary key: `id()` and `primary` together fail,
  and so does a nullable column in the key.

```rust
Schema::create(manager, "post_tag", |t| {
    t.foreign_id("post_id").constrained("posts").cascade_on_delete();
    t.foreign_id("tag_id").constrained("tags").cascade_on_delete();
    t.primary(&["post_id", "tag_id"]);
})
.await
```

The builder refuses a name longer than 63 bytes for an index or a foreign key,
on every backend. It is the limit Postgres keeps, so a migration that runs on
one backend runs on all three.

### Full-text indexes

`t.full_text(&["title", "body"])` creates the index that
[`where_full_text`](database.md#full-text-search) searches, named
`{table}_{columns}_fulltext`:

```rust
Schema::create(manager, "articles", |t| {
    t.id();
    t.string("title");
    t.text("body");
    t.full_text(&["title", "body"]);
})
.await
```

Each engine gets its own index:

| Engine | Statement |
| --- | --- |
| MySQL and MariaDB | ``CREATE FULLTEXT INDEX `articles_title_body_fulltext` ON `articles` (`title`, `body`)`` |
| Postgres | `CREATE INDEX "articles_title_body_fulltext" ON "articles" USING gin ((to_tsvector('english', "title") \|\| to_tsvector('english', "body")))` |
| SQLite | an error that names SQLite and `full_text`, before any statement runs |

The Postgres index stores the same `to_tsvector` expression the search
reads, so Postgres answers the search from the index. Laravel writes the
same statements, so an index a Laravel migration created serves a Suprnova
query too.

- `.language("french")` builds the Postgres index with another text search
  configuration. The default is `english`. A search uses the index only when
  it names the same language with `FullTextOptions::language`. MySQL and
  MariaDB ignore the language.
- The language is written into the SQL, so a name with anything but letters,
  digits, and `_` (and an optional `schema.` prefix) fails the migration on
  every backend.
- `t.drop_full_text(&["title", "body"])` drops the index over those columns
  in `Schema::table`. To drop a full-text index with another name, use
  `drop_index(name)`.

```rust
Schema::table(manager, "articles", |t| {
    t.drop_full_text(&["title", "body"]);
})
.await
```

### Altering a table

`Schema::table` accepts:

- new columns of any type, with the same modifiers
- `rename_column(from, to)` and `drop_column(name)`
- `index`, `unique` and `drop_index(name)`
- `full_text(&[..])` and `drop_full_text(&[..])`, on Postgres and MySQL
- `foreign_id(..).constrained(..)`, `foreign(column)` and `drop_foreign(name)`
- `drop_constrained_foreign_id(column)`, which drops the key
  `{table}_{column}_foreign` and then the column. A key `.name(..)` named has
  another name: drop it with `drop_foreign(name)` and the column with
  `drop_column`.
- `primary(&[..])`, on Postgres and MySQL

```rust
Schema::table(manager, "posts", |t| {
    t.string("subtitle").nullable();
    t.rename_column("body", "content");
    t.index(&["subtitle"]);
})
.await
```

It runs the operations in the order you write them, each as its own statement.
Changing the type of an existing column is not supported. `rename_column`,
`drop_column`, `drop_index`, `drop_full_text` and `drop_foreign` belong to
`Schema::table`: `Schema::create` returns an error if its closure records one.

The builder checks the description for the mistakes it can see before it runs
the first statement: a duplicate column, an index over a column the table does
not declare, an empty table name. A statement the database refuses stops the
call. On MySQL and SQLite the migrator runs a migration without a transaction,
so the statements before the refused one stay applied. On Postgres the
migration's transaction rolls them back.

Every refusal the builder makes is a `DbErr::Migration` whose text starts with
`schema:` and names the table, the column and the operation.

### SQLite limits

SQLite cannot run some alterations in place, and the builder does not rebuild
the table. `Schema::table` on SQLite returns an error, before it runs any
statement of the call, for:

- Adding or dropping a foreign key, `drop_constrained_foreign_id` included.
- Adding a primary key column, or a primary key.
- Adding a `NOT NULL` column with no default.
- Adding a column with `.use_current()`.
- Creating or dropping a full-text index. `Schema::create` refuses
  `full_text` on SQLite too. SQLite has no `FULLTEXT` or `GIN` index.

The errors read:

```text
schema: cannot add the foreign key `{name}` on the existing table `{table}`: SQLite cannot add or drop a foreign key on an existing table; create the key with the table in Schema::create, or write this step with SeaORM's SchemaManager
schema: cannot add the primary key column `{column}` to the existing table `{table}`: SQLite cannot add a PRIMARY KEY column; create the table with id() instead
schema: cannot add the NOT NULL column `{column}` to the existing table `{table}` without a default: SQLite refuses it; call .nullable() or .default(value)
```

Dropping a foreign key reads `cannot drop the foreign key` in the first text.

SQLite also refuses `CURRENT_TIMESTAMP` as the default of a column added to an
existing table, so use a constant default there; the builder refuses
`.use_current()` up front, and cannot see a `CURRENT_TIMESTAMP` passed through
`.default(..)`. It refuses to drop a column
that an index, a unique constraint or a foreign key covers: record the
`drop_index` earlier in the same closure.

### Why Suprnova diverges

- Laravel's `enum` is `enumeration`: `enum` is a Rust keyword.
- `references(table, column)` takes both names in one call, where Laravel
  chains `->references($column)->on($table)`.
- `.unsigned()` applies to integers only. Laravel also lets it mark a decimal
  or floating point column; MySQL deprecated that in 8.0.17.
- You use `ulid_with_length(name, length)` or `ulid(name).length(length)`
  for Laravel's `ulid(name, length)`. Rust has no optional arguments.
- `use_current()` together with `.default(..)` fails the migration. Laravel
  lets `useCurrent` win silently.
- `drop_full_text` takes the index's columns. Laravel's `dropFullText` takes
  the columns or the index name; for a name, use `drop_index(name)`.
- A full-text language that is not a plain name fails the migration. Laravel
  writes it into the statement as given.

### Both styles in one Migrator

A `Schema` migration and a SeaORM migration implement the same
`MigrationTrait`, so both sit in one `Migrator`. One `up()` can mix them:
call `Schema::create` for the table, then a `manager` call of your own for
the step the builder does not cover.

## Schema operations

These are the SeaORM forms of the same operations. The [schema builder](#the-schema-builder) is the shorter alternative for the common cases.

### Creating tables

```rust
use sea_orm_migration::prelude::*;

async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .create_table(
            Table::create()
                .table(Users::Table)
                .if_not_exists()
                .col(
                    ColumnDef::new(Users::Id)
                        .integer()
                        .not_null()
                        .auto_increment()
                        .primary_key(),
                )
                .col(ColumnDef::new(Users::Email).string().not_null().unique_key())
                .col(ColumnDef::new(Users::Name).string().not_null())
                .col(ColumnDef::new(Users::PasswordHash).string().not_null())
                .col(ColumnDef::new(Users::CreatedAt).timestamp().not_null())
                .col(ColumnDef::new(Users::UpdatedAt).timestamp().not_null())
                .to_owned(),
        )
        .await
}

// Define the table and column identifiers
#[derive(DeriveIden)]
enum Users {
    Table,
    Id,
    Email,
    Name,
    PasswordHash,
    CreatedAt,
    UpdatedAt,
}
```

### Dropping tables

```rust
async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .drop_table(Table::drop().table(Users::Table).to_owned())
        .await
}
```

### Column types

| Method | Database Type | Notes |
|--------|---------------|-------|
| `integer()` | INTEGER | 32-bit integer |
| `big_integer()` | BIGINT | 64-bit integer |
| `small_integer()` | SMALLINT | 16-bit integer |
| `float()` | FLOAT | Floating point |
| `double()` | DOUBLE | Double precision |
| `decimal()` | DECIMAL | Fixed-point |
| `string()` | VARCHAR(255) | Variable length string |
| `string_len(n)` | VARCHAR(n) | Custom length string |
| `text()` | TEXT | Long text |
| `boolean()` | BOOLEAN | True/false |
| `timestamp()` | TIMESTAMP | Date and time |
| `date()` | DATE | Date only |
| `time()` | TIME | Time only |
| `blob()` | BLOB | Binary data |
| `json()` | JSON | JSON data |
| `uuid()` | UUID | UUID type |

### Column modifiers

```rust
ColumnDef::new(Column::Name)
    .string()
    .not_null()                                // NOT NULL constraint
    .null()                                    // Allows NULL (default)
    .default("value")                          // Default value
    .default(Expr::current_timestamp())        // Function default (e.g. NOW())
    .unique_key()                              // UNIQUE constraint
    .primary_key()                             // PRIMARY KEY
    .auto_increment()                          // AUTO_INCREMENT
```

For surrogate primary keys, prefer `big_integer().auto_increment().primary_key()`
on real tables - `INTEGER` (32-bit) is fine for tiny lookup tables but the
scaffolded `users` table uses `BIGINT` because a 4-byte counter is the kind of
constraint you regret three years in.

## Adding columns

```rust
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .alter_table(
            Table::alter()
                .table(Users::Table)
                .add_column(
                    ColumnDef::new(Users::PhoneNumber)
                        .string()
                        .null()
                )
                .to_owned(),
        )
        .await
}

async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .alter_table(
            Table::alter()
                .table(Users::Table)
                .drop_column(Users::PhoneNumber)
                .to_owned(),
        )
        .await
}
```

## Modifying columns

```rust
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .alter_table(
            Table::alter()
                .table(Users::Table)
                .modify_column(
                    ColumnDef::new(Users::Name)
                        .string_len(500)  // Change VARCHAR(255) to VARCHAR(500)
                        .not_null()
                )
                .to_owned(),
        )
        .await
}
```

## Renaming columns

```rust
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .alter_table(
            Table::alter()
                .table(Users::Table)
                .rename_column(Users::Name, Users::FullName)
                .to_owned(),
        )
        .await
}
```

## Indexes

### Creating indexes

```rust
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .create_index(
            Index::create()
                .name("idx_users_email")
                .table(Users::Table)
                .col(Users::Email)
                .unique()  // Optional: make it unique
                .to_owned(),
        )
        .await
}
```

### Composite indexes

```rust
manager
    .create_index(
        Index::create()
            .name("idx_posts_user_created")
            .table(Posts::Table)
            .col(Posts::UserId)
            .col(Posts::CreatedAt)
            .to_owned(),
    )
    .await
```

### Dropping indexes

```rust
async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .drop_index(Index::drop().name("idx_users_email").to_owned())
        .await
}
```

## Foreign keys

### Adding foreign keys

```rust
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager
        .create_table(
            Table::create()
                .table(Posts::Table)
                .if_not_exists()
                .col(
                    ColumnDef::new(Posts::Id)
                        .integer()
                        .not_null()
                        .auto_increment()
                        .primary_key(),
                )
                .col(ColumnDef::new(Posts::UserId).integer().not_null())
                .col(ColumnDef::new(Posts::Title).string().not_null())
                .col(ColumnDef::new(Posts::Content).text().not_null())
                .foreign_key(
                    ForeignKey::create()
                        .name("fk_posts_user")
                        .from(Posts::Table, Posts::UserId)
                        .to(Users::Table, Users::Id)
                        .on_delete(ForeignKeyAction::Cascade)
                        .on_update(ForeignKeyAction::Cascade),
                )
                .to_owned(),
        )
        .await
}
```

### Foreign key actions

| Action | Description |
|--------|-------------|
| `Cascade` | Delete/update child rows automatically |
| `SetNull` | Set foreign key to NULL |
| `SetDefault` | Set foreign key to default value |
| `Restrict` | Prevent delete/update if referenced |
| `NoAction` | Similar to Restrict |

## Migration workflow

A typical change goes through four steps:

```bash
# 1. Generate the file (creates src/migrations/m{ts}_create_posts_table.rs
#    and updates src/migrations/mod.rs).
suprnova make:migration create_posts_table

# 2. Edit src/migrations/m{ts}_create_posts_table.rs to define your schema.

# 3. Apply the migration.
suprnova migrate

# 4. Regenerate SeaORM entity files from the live schema so the models
#    compile against the new shape. `db:sync` also runs any pending
#    migrations first (use --skip-migrations to skip that step).
suprnova db:sync
```

`db:sync` writes auto-generated entity glue to `src/models/entities/<table>.rs`
and a user-editable stub to `src/models/<table>.rs`. Re-running it updates the
entity files; your user stubs are left alone unless you pass
`--regenerate-models` (which overwrites them - keep custom methods elsewhere
or version-control before you run it).

### Auto-migrate on serve

Your application's `serve` and `web:run` subcommands apply any pending
migrations before opening the HTTP socket. The default policy is **fail-closed**: if `up()`
errors, the process aborts non-zero before bind, so a broken migration can
never reach traffic.

Two escape hatches:

| Flag / env | Effect |
|---|---|
| `--no-migrate` (on `serve` / `web:run`) | Skip the auto-migrate step entirely. Useful when migrations run from a separate deploy step. |
| `SUPRNOVA_AUTO_MIGRATE_BEST_EFFORT=true` | Opt back into the legacy log-and-continue behaviour. The process keeps booting on a migration error. Not recommended in production. |

`suprnova serve`, the development command, runs the pending migrations once
when it starts, then starts the watched backend as `serve --no-migrate`, so a
save of a source file does not run them again. Pass `--migrate always` to
`suprnova serve` to migrate on every restart of the backend. See
[suprnova serve](cli-serve.md#migrations).

Background workers (`queue:work`, `workflow:work`, `schedule:run`) do *not*
auto-migrate - they assume schema is already in place when they boot, since
running migrations from N workers concurrently would race.

### Running migrations in tests

`TestDatabase::fresh::<Migrator>()` spins up an isolated in-memory SQLite
database, runs every migration, and binds the connection into the test
container so `DB::connection()` and `#[inject]` resolve to it:

```rust
use suprnova::testing::TestDatabase;
use crate::migrations::Migrator;

#[tokio::test]
async fn users_table_is_created() {
    let db = TestDatabase::fresh::<Migrator>().await.unwrap();
    // `db` is dropped at the end of the test, clearing the container.
}
```

See [Database Tests](database-testing.md) for the full pattern (factories,
parallel safety, picking a real driver instead of in-memory SQLite).

## Best practices

### Always write down migrations

Always implement `down()` to allow rollbacks:

```rust
// Good: Reversible migration
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager.create_table(/* ... */).await
}

async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
    manager.drop_table(/* ... */).await
}
```

### Use descriptive names

```bash
# Good: Describes the change
suprnova make:migration add_email_verified_to_users
suprnova make:migration create_order_items_table
suprnova make:migration add_index_to_posts_slug

# Bad: Vague names
suprnova make:migration update_users
suprnova make:migration change_table
```

### One change per migration

Keep migrations focused on a single change:

```bash
# Good: Separate migrations
suprnova make:migration create_categories_table
suprnova make:migration add_category_id_to_posts

# Avoid: Multiple unrelated changes in one migration
```

### Test migrations both ways

Before committing, verify both directions work:

```bash
suprnova migrate           # Apply
suprnova migrate:rollback  # Rollback
suprnova migrate           # Apply again
```

## Squashing migrations

A project with years of migrations can replace them with one snapshot.
Use `--without-migration-data` to omit ledger rows from your dump. Use
`--database reporting` to select `DATABASE_REPORTING_URL`; an unknown name
fails with an error naming it. Otherwise you dump `DATABASE_URL`.

`suprnova schema:dump` writes the database's schema and its migration
ledger to `database/schema/<engine>-schema.sql`, where the engine is
`sqlite`, `postgres`, `mysql`, or `mariadb`:

```bash
suprnova schema:dump            # writes database/schema/postgres-schema.sql
suprnova schema:dump --prune    # and prunes the applied migrations
suprnova schema:dump --without-migration-data
suprnova schema:dump --database reporting
```

Commit the dump. When `migrate`, `migrate:fresh`, or `serve` meets a
database that has run no migration, it loads the dump first and then runs
only the migrations newer than it. A database that has run a migration is
never loaded. Neither is a database that already holds tables while its
migration ledger is missing or empty, such as one ported from Laravel:
that is an error, and its tables stay as they were. To load another file,
pass `--schema-path <file>` to `migrate` or `migrate:fresh`; a path that
names no file is an error. `migrate:fresh` drops the views, routines,
sequences, and types of the current schema as well as its tables before
it loads a dump; objects in other Postgres schemas are yours to drop.

`TestDatabase::fresh` loads `database/schema/sqlite-schema.sql` the same
way when every migration the dump records is in the test's `Migrator`, so
tests on SQLite need a SQLite dump. A test with a `Migrator` of its own
runs that `Migrator` from scratch.

Postgres is dumped with `pg_dump` and loaded with `psql`, MySQL with
`mysqldump` and `mysql`, and MariaDB with `mariadb-dump` and `mariadb`.
SQLite needs no tool. These client tools must be on `PATH` wherever a
dump is written or loaded, and `pg_dump` must be at least the server's
major version. They reach the database the way your app does: the URL's
TLS settings (`sslmode`, `sslrootcert`, `sslcert`, and `sslkey` for
Postgres; `ssl-mode`, `ssl-ca`, `ssl-cert`, and `ssl-key` for MySQL and
MariaDB) and its socket go with them, in every spelling the app's
connection accepts (`ssl-mode` and `ssl-root-cert` for Postgres,
`sslmode` and `sslca` for MySQL, and so on). When a parameter appears in
two spellings, the later one wins, as it does for the connection. A
Postgres `password` parameter wins over the password in the URL's user
part, as it does for the connection. The password reaches them through
`PGPASSWORD` or a private option file, never through their arguments,
and a password in `~/.my.cnf` does not replace it. A dump that fails
leaves the earlier file as it was, and a load that fails runs no
migration, even with `SUPRNOVA_AUTO_MIGRATE_BEST_EFFORT` set.

The image `suprnova docker:init` writes carries `database/schema` and
the Postgres client, so a new environment can start from the dump. For
MySQL or MariaDB, build it with `--build-arg DB_CLIENT=mariadb-client`;
for SQLite, with `--build-arg DB_CLIENT=`.

### Pruning

`--prune` deletes each migration the dump's ledger records and keeps its
name in your `Migrator`'s list:

```rust
vec![
    Box::new(suprnova::PrunedMigration::new("m20250101_000001_create_users")),
    Box::new(m20260301_120000_create_invoices::Migration),
]
```

The name stays because a database that ran the migration records it, and
SeaORM refuses a recorded migration it can't find. A database that would
need the pruned migration's schema, such as an empty one with no dump to
load, fails with an error that names the migration instead of skipping
it. A migration the dump does not record stays as it is. A migration
whose `name()` differs from its file name can't be matched to its file,
so `--prune` stops and changes nothing; rename the file or prune it by
hand. Rebuild the app after pruning.

### Why Suprnova diverges

- **Pruning keeps what the dump does not cover.** Laravel's `--prune`
  deletes every migration file, including any the dumped database never
  ran. Here only the migrations the dump records go, and each keeps its
  name.
- **A dump never loads over tables.** Laravel loads a dump into any
  database whose migrations table is empty, and a MySQL dump drops each
  table it creates. Here the dump has no `DROP TABLE`, and a database that
  already holds tables is an error.
- **No schema events.** Laravel fires `SchemaDumped`, `SchemaLoaded`, and
  `MigrationsPruned`. Suprnova's migration commands run before the
  bootstrap registers listeners, so no listener would hear them.
- **The file is named after the engine.** Laravel names it after the
  connection; Suprnova migrates one connection, `DATABASE_URL`.

## CLI commands at a glance

| Command | Description |
|---------|-------------|
| `suprnova make:migration <name>` | Create a new migration |
| `suprnova migrate` | Run all pending migrations |
| `suprnova migrate:status` | Show migration status |
| `suprnova migrate:rollback` | Rollback the last migration |
| `suprnova migrate:rollback --step 3` | Rollback the last 3 migrations |
| `suprnova migrate:fresh` | Drop all tables and re-run every migration |
| `suprnova schema:dump` | Write the schema and migration ledger to `database/schema/` |
| `suprnova schema:dump --prune` | Also replace the dumped migrations with their names |
| `suprnova db:sync` | Run migrations and regenerate entity files |
| `suprnova db:sync --skip-migrations` | Regenerate entity files without applying migrations |
| `suprnova db:sync --regenerate-models` | Also overwrite user-editable model stubs |

See [CLI Migrations Reference](cli-migrations.md) for the full per-command
reference (flags, output samples, exit codes).

## Next

- [CLI Migrations Reference](cli-migrations.md) - flag-by-flag reference for `migrate*` and `db:sync`
- [Database](database.md) - connection configuration, transactions, read/write split
- [Eloquent](eloquent.md) - the model layer your migrations feed
- [Seeding](seeding.md) - populating tables once their schema exists
- [Database Tests](database-testing.md) - `TestDatabase::fresh::<Migrator>()` and parallel-safe patterns


---

<!-- /docs/seeding -->

# Seeding

Seeders populate the database with fixture data - the rows your app needs before
a real user has done anything. Think a default admin account, the canonical list
of countries, the demo posts on the staging environment, the 50 users + 200
posts your local dev iteration loop depends on. They are the runtime sibling of
[migrations](migrations.md): migrations build the empty schema, seeders fill it.

A seeder is a zero-sized type that implements the `Seeder` trait. The framework
keeps an ordered process-global registry; the per-project `console db:seed`
command runs the root you register, or one specific seeder via `--class=<Name>`.
You retain registration order when you register no root. You usually write a
few lines that call a [model factory](eloquent.md) to generate the rows.

```rust
use suprnova::{async_trait, Factory, FrameworkError, Seeder};
use crate::factories::UserFactory;

pub struct UsersSeeder;

#[async_trait]
impl Seeder for UsersSeeder {
    fn name() -> &'static str { "UsersSeeder" }

    async fn run() -> Result<(), FrameworkError> {
        UserFactory::new().count(50).create_many().await?;
        Ok(())
    }
}
```

Register it once at boot:

```rust
// src/bootstrap.rs
suprnova::seed::register::<crate::seeders::UsersSeeder>();
```

Then:

```bash
cargo run --bin console -- db:seed
# (50 rows inserted)
```

That's the whole loop. The rest of this chapter covers the layout conventions,
the bigger registry composition patterns, the `--class` targeting flag, the
factory integration, the `without_events` escape hatch, and the
when-to-seed-vs-migrate-vs-factory call.

## Writing a seeder

A seeder is a unit type plus a `Seeder` impl. `name()` is the registry key
(also what `db:seed --class=<Name>` matches against), and `run()` is the
async fn that performs the inserts.

```rust
// src/seeders/users_seeder.rs
use suprnova::{async_trait, Factory, FrameworkError, Seeder};

use crate::factories::UserFactory;

pub struct UsersSeeder;

#[async_trait]
impl Seeder for UsersSeeder {
    fn name() -> &'static str { "UsersSeeder" }

    async fn run() -> Result<(), FrameworkError> {
        UserFactory::new().count(50).create_many().await?;
        Ok(())
    }
}
```

`Seeder` is re-exported at the crate root, so `use suprnova::Seeder` is
enough - you do not need to reach into `suprnova::seed::Seeder`. `async_trait`
is also re-exported (`use suprnova::async_trait`) because `Seeder` is an
`#[async_trait]` trait: the seeder registry stores each run as a boxed `Send`
future, which `#[async_trait]` produces.

The `FrameworkError` return type is the same error envelope every other async
surface in the framework uses; bubbling the `?` out of a factory call or a
`Model::create` is the expected shape. See [Error Model](error-model.md) for
the full taxonomy.

### Layout convention

Mirror Laravel's `database/seeders/` directory, but at the source root:

```
src/
├── bootstrap.rs
├── factories/
│   ├── mod.rs
│   ├── user_factory.rs
│   └── post_factory.rs
├── seeders/
│   ├── mod.rs              // pub mod base_seeder; pub use base_seeder::BaseSeeder;
│   └── base_seeder.rs      // Seeder impl, registered in bootstrap.rs
└── …
```

`suprnova make:seeder Users` writes `src/seeders/users_seeder.rs` and declares
it in `src/seeders/mod.rs`, and `suprnova make:factory User` does the same for
the factory the seeder calls. See [Code Generators](cli-generators.md).

### A seeder that runs other seeders

The Laravel idiom of a single top-level `DatabaseSeeder::run` that orchestrates
the per-model seeds works here too. Instead of registering five small seeders
in bootstrap and trusting their registration order, register one composite
seeder and call the rest of them yourself:

```rust
use suprnova::{async_trait, Factory, FrameworkError, Seeder};

use crate::factories::{PostFactory, UserFactory};

pub struct BaseSeeder;

#[async_trait]
impl Seeder for BaseSeeder {
    fn name() -> &'static str { "BaseSeeder" }

    async fn run() -> Result<(), FrameworkError> {
        // 50 users first - the post factory generates author_id in
        // 1..=50, so the references resolve.
        UserFactory::new().count(50).create_many().await?;

        // 200 posts referencing the user ids above.
        PostFactory::new().count(200).create_many().await?;

        Ok(())
    }
}
```

This is the recommended default. It keeps the dependency order
(`users` before `posts`) inside the seeder rather than scattered across the
bootstrap file, and `db:seed --class=BaseSeeder` is a single-target invocation
that runs the whole bundle.

If you want to chain seeders by name rather than by direct factory call, use
`seed::call` from inside your root seeder:

```rust
async fn run() -> Result<(), FrameworkError> {
    suprnova::seed::call(["UsersSeeder", "PostsSeeder", "CommentsSeeder"]).await?;
    Ok(())
}
```

You register each child with `seed::register` in `bootstrap.rs`. You select
the composite with `seed::register_root::<BaseSeeder>()?`. A bare `db:seed`
runs only that root, which chooses its children and order.

`call` runs names in the order you give and writes `RUNNING <name>` followed
by `DONE <name> (<ms> ms)` to the command's console output. You capture these
lines with `console::test(["db:seed"]).run().await`. A failed child stops the
list, returns its error, and has no DONE line. Earlier inserts remain.

You use `call_silent(names)` to suppress progress. You use `call_once(names)`
to skip each seeder that already completed in this invocation, including one
run through `call` or `call_silent`. You can retry a failed seeder. The next
`db:seed` invocation starts with an empty set. A recursive call to a running
seeder returns an error.

You pass named inputs with `call_with(name, params)`:

```rust
seed::call_with("UsersSeeder", suprnova::attrs! { count: 50 }).await?;
```

You read those inputs by overriding the default parameter path:

```rust
#[async_trait]
impl Seeder for UsersSeeder {
    fn name() -> &'static str { "UsersSeeder" }
    async fn run() -> Result<(), FrameworkError> {
        Self::run_with(suprnova::SeederParams::new()).await
    }
    async fn run_with(params: suprnova::SeederParams) -> Result<(), FrameworkError> {
        let count = match params.get("count") {
            None => 10,
            Some(value) => value.as_u64()
                .ok_or_else(|| FrameworkError::bad_request("count must be an integer"))?,
        };
        let count = usize::try_from(count)
            .map_err(|_| FrameworkError::bad_request("count is too large"))?;
        UserFactory::times(count).create().await?;
        Ok(())
    }
}
```

`SeederParams` is an `Attrs` map. Existing seeders keep their `run()` signature:
the default `run_with(params)` calls it. You resolve services with
`App::make::<Service>()` inside either method, as you do elsewhere in your app.

## The seeder registry

You register peers in a process-global ordered map. Each stored function takes
`SeederParams` and returns a boxed future. You register a root separately to
choose which seeder a bare `db:seed` runs.

### `register::<S>()`

Add a seeder to the registry under its `Seeder::name()`:

```rust
suprnova::seed::register::<crate::seeders::UsersSeeder>();
```

You select a root with `seed::register_root::<BaseSeeder>()?`. This registers
the root and replaces the previous root selection, if any.

Two things to know about the registry:

- **Order matters.** `run_all` visits seeders in the order they were
  registered. If `B` needs rows from `A`, register `A` first.
- **Re-registering a name replaces in place.** The slot keeps its original
  position, the function pointer changes. This is intentional - it lets a
  test bind a stub seeder over the real one without shifting the order. In
  production code, register each seeder exactly once at boot.

### `run_all()`

You run every registered seeder in registration order explicitly. A bare
`console db:seed` calls the registered root; without a root it calls `run_all`.

```rust
suprnova::seed::run_all().await?;
```

Stops on the first error. Seeders that already ran are not rolled back -
`run_all` does not wrap a transaction around the batch because most seeders
span multiple statements and many backends do not nest transactions cleanly.
If you need rollback semantics, open the transaction inside the seeder and
keep all its work inside that scope.

### `run_one(name)`

Run one named seeder without running the others. This is the engine for
`db:seed --class=<Name>` and is also useful from one-off scripts:

```rust
suprnova::seed::run_one("AdminAccountSeeder").await?;
```

Misses return ``FrameworkError::not_found("no seeder registered for `X`")``.
The console command propagates that to a non-zero exit and a stderr line -
no silent no-op.

### `count()` and `is_registered(name)`

Two read helpers, both useful in tests that assert "bootstrap wired up the
expected seeders":

```rust
assert_eq!(suprnova::seed::count(), 3);
assert!(suprnova::seed::is_registered("BaseSeeder"));
```

Both return zero / false on a poisoned registry lock (after logging an error),
which keeps tests deterministic in the face of an upstream panic.

## The `db:seed` command

`db:seed` is a framework-provided console command - it ships with the
framework and lands in your project's `console` binary automatically through
the same `inventory` registry that picks up your own `#[command]`s. See
[Console](console.md) for the binary's mechanics; this section covers the
seeder-specific surface.

### Run the root

```bash
cargo run --bin console -- db:seed
```

The `suprnova` CLI runs the same command through your project's console
binary. `suprnova db:seed` runs your root, `suprnova db:seed UsersSeeder`
and `suprnova db:seed --class=UsersSeeder` run one. The CLI checks no name;
the console binary does.

You run the root registered with `seed::register_root`. Without one you run
every registered peer in order. On an empty registry you receive a
warning to stderr (`db:seed: no seeders registered - nothing to run`) and
exits zero - that's correct behavior for "someone ran the command before
registering anything" and keeps test suites that haven't seeded anything
specific from failing.

### Run one seeder

Three accepted forms, in increasing order of how Laravel-shaped they feel:

```bash
cargo run --bin console -- db:seed --class=UsersSeeder
cargo run --bin console -- db:seed --class UsersSeeder
cargo run --bin console -- db:seed UsersSeeder
```

All three look the seeder up in the registry by exact name and run it.
A name the registry doesn't hold fails with
``no seeder registered for `<Name>` `` and a non-zero exit, including on
an empty registry.

A targeted run reports its progress:

```text
  UsersSeeder .......................................................... RUNNING
  UsersSeeder ...................................................... 812 ms DONE

```

You receive these outer progress lines on stdout for a named run. A bare
`db:seed` leaves outer progress to your root's `call` methods. You keep the
`tracing` record per seeder for machine logs.

An unknown name fails fast:

```bash
cargo run --bin console -- db:seed --class=NotARealSeeder
# Error: no seeder registered for `NotARealSeeder`
# (exit 1)
```

A malformed flag (`--class` with no following value, `--class=` with empty
value, `--class --force`) fails fast too, with a diagnostic that names the
expected shape.

### Production and connection selection

You pass `--force` in production. Without it the command returns an error
before any seeder runs. You select another registered connection with
`--database reporting` or `--database=reporting`:

```bash
./console db:seed --force
./console db:seed --database reporting --class=UsersSeeder
```

You use the selected connection for the invocation's default queries and
factories. Explicit model and query connections keep their precedence.
The enclosing default returns after success or failure. An unknown connection
fails before your seeder runs. `Config::is_production()` uses your loaded app
configuration, or detects `APP_ENV=production` when none is loaded.

### From a built binary

In a containerized or systemd-managed deployment, the console binary lives at
`target/release/console` (or wherever your release artifact lands). Same
syntax, no `cargo` in front:

```bash
./console db:seed
./console db:seed --class=BaseSeeder
```

The console binary calls `suprnova::console::dispatch_argv(std::env::args())`,
which routes through the same registry as `cargo run --bin console --`. There
is no separate dispatch path for built artifacts.

## Composing with factories

Seeders almost always end up calling [factories](eloquent.md). The factory
trait knows how to build a randomized instance of one model; the seeder
sequences the factory calls and any non-randomizable wiring (deterministic
admin credentials, joined-table rows, file uploads).

The minimal factory + seeder pair:

```rust
// src/factories/user_factory.rs
use suprnova::Factory;
use crate::models::users::User;

pub struct UserFactory;

impl Factory for UserFactory {
    type Model = User;

    fn definition() -> User {
        User {
            id: 0,                              // persist_via_seaorm flips PK to NotSet
            name: "Factory User".into(),
            email: "factory@example.suprnova.app".into(),
            password: "factory-placeholder".into(),
            created_at: chrono::Utc::now(),
            updated_at: chrono::Utc::now(),
            ..Default::default()
        }
    }
}
```

```rust
// src/seeders/users_seeder.rs
use suprnova::{async_trait, Factory, FrameworkError, Seeder};
use crate::factories::UserFactory;

pub struct UsersSeeder;

#[async_trait]
impl Seeder for UsersSeeder {
    fn name() -> &'static str { "UsersSeeder" }

    async fn run() -> Result<(), FrameworkError> {
        UserFactory::new().count(50).create_many().await?;
        Ok(())
    }
}
```

The fluent builder lives on `FactoryBuilder<M>`; what you can chain before
`create_many` matches Laravel:

```rust
// Build one persisted row with overrides:
let admin = UserFactory::new()
    .with(|u| u.email = "admin@example.com".into())
    .with(|u| u.role = "admin".into())
    .create()
    .await?;

// Build N persisted rows, all admins:
UserFactory::times(5)
    .with(|u| u.role = "admin".into())
    .create_many()
    .await?;

// Conditional state - applies the closure only when the flag is set:
UserFactory::times(10)
    .when(seed_admins, |b| b.with(|u| u.role = "admin".into()))
    .create_many()
    .await?;
```

`make` / `make_one` / `make_many` are the in-memory siblings (no insert) for
unit tests that don't want a database round-trip. See the
[Eloquent](eloquent.md) chapter for the full factory surface (including
`prepend`, `Sequence`, and the `#[derive(Factory)]` macro, with `#[factory(name = "…")]` to rename
the generated factory).

### Idempotency is the seeder's responsibility

`run_all` does not snapshot or wrap a transaction; if a seeder inserts
unconditionally, re-running it produces duplicates. The two standard ways to
make a seeder safe to re-run:

- **Reset first.** Local dev's "wipe and reseed" loop usually does
  `suprnova migrate:fresh && cargo run --bin console -- db:seed` -
  `migrate:fresh` drops and rebuilds every table, so the seeder always
  starts from empty. This is the shape most projects use day to day.
- **Upsert / check-first.** For a seeder that must coexist with existing
  data (a default admin account in production, the canonical list of
  countries), guard the insert with a lookup or use an upsert query.

```rust
async fn run() -> Result<(), FrameworkError> {
    let exists = User::query()
        .db_where("email", "admin@example.com")
        .exists()
        .await?;

    if !exists {
        let password_hash = suprnova::hashing::hash("change-me-on-first-login")?;
        User::create(attrs!{
            email: "admin@example.com",
            name: "Admin",
            password: password_hash,
        }).await?;
    }
    Ok(())
}
```

## Muting model events with `without_events`

A seeder that calls `Model::create` in a loop fires every lifecycle event -
`Creating`, `Saving`, `Created`, `Saved` - on every row. That wakes any
registered `Observer<M>`, runs any queued broadcast listeners, and can
incidentally enqueue a hundred background jobs you don't actually want.
`seed::without_events` is the Laravel-`WithoutModelEvents` analogue:

```rust
use suprnova::{async_trait, FrameworkError, Seeder, seed};
use crate::models::users::User;

pub struct UsersSeeder;

#[async_trait]
impl Seeder for UsersSeeder {
    fn name() -> &'static str { "UsersSeeder" }

    async fn run() -> Result<(), FrameworkError> {
        seed::without_events(async {
            for i in 0..50 {
                User::create(attrs!{
                    name: format!("user{i}"),
                    email: format!("user{i}@example.com"),
                }).await?;
            }
            Ok(())
        }).await
    }
}
```

While the inner future is awaiting, both the cancellable veto path
(`dispatch_cancellable`) and the after-event fanout (`dispatch_after`)
short-circuit to `Ok(())`. Observers are silent, the broadcaster doesn't
wake, downstream jobs don't enqueue.

The effect is task-scoped - only work performed inside `fut` is muted.
Concurrent work on other tasks (HTTP request handlers, queue workers running
in the background, other seeders) continues to fire events normally. Nested
calls compose: an inner `without_events` block inherits the outer flag.

### Factories fire model events

A factory insert of a `#[suprnova::model]` struct takes the same insert
as `Model::create`. It dispatches `Creating`, `Saving`, `Created`, and
`Saved`, so an observer sees a factory's rows as it sees the
application's. `seed::without_events` mutes a factory path too. For a
single factory call, `create_quietly()` and `create_many_quietly()` insert
with the events muted.

In practice: if a seeder should not wake observers, wrap its inserts in
`without_events`, whether they are factory calls or a hand-rolled loop of
`User::create(attrs)`.

## Using seeders in tests

The same registry the console binary drives is callable from a
`#[tokio::test]` - handy when you want a known fixture set in front of an
integration test:

```rust
use serial_test::serial;
use suprnova::container::testing::TestContainer;
use suprnova::{DbConnection, seed};

use app::seeders::BaseSeeder;

#[tokio::test]
#[serial]
async fn dashboard_renders_seeded_posts() {
    // Reset the registry so a prior test's registrations don't leak.
    seed::clear();

    let _guard = TestContainer::fake();
    let conn = sea_orm::Database::connect("sqlite::memory:").await.unwrap();
    app::migrations::Migrator::up(&conn, None).await.unwrap();
    TestContainer::singleton(DbConnection::from_raw(conn.clone()));

    // Register the seeder you want, run it, and assert against the
    // fresh database.
    seed::register::<BaseSeeder>();
    seed::run_all().await.unwrap();

    // …controller test against the seeded data…

    seed::clear();
}
```

Two notes on the test shape:

- `#[serial]` is required when the test mutates the process-global registry -
  parallel tests sharing the same registry will race. Add `serial_test`
  as a dev-dependency in your project's `Cargo.toml` to get the attribute.
- `seed::clear()` forgets every registered seeder. It is compiled with the
  `testing` feature, which is a default feature, and it is meant for tests:
  the registry is built once at boot and needs no reset in production. The
  guard of `TestContainer` does not reset the registry, so a test that
  registers a seeder calls `clear()` first and again when it finishes.

See [Testing](testing.md) for the broader test-harness conventions
(`#[suprnova_test]`, `TestContainer`, `TestDatabase::fresh::<Migrator>()`,
the fakes for every external surface).

## When to seed, migrate, or factory

These three patterns all put rows into tables. The decision is usually
straightforward, but it's worth naming the dividing lines explicitly because
PHP teams often blur them.

| You want… | Use |
|---|---|
| A column to exist | [Migration](migrations.md) |
| A row that must exist for the app to boot (the default admin, the singleton site-config row, the canonical list of currencies) | **Seeder** - idempotent, runs in every environment, including production |
| A randomized set of rows for local dev or staging (50 users, 200 posts, 1000 events) | Seeder that calls a factory |
| A row a unit test needs | [Factory](eloquent.md) called directly inside the test |
| The shape of a row | [Factory](eloquent.md) |

The mistakes to avoid:

- **Don't insert data from a migration.** Migrations describe schema, not
  state. A migration that inserts a default row will run once on the
  production database and then never again - the moment a column changes, you
  have a forked source of truth between migration history and the seeder.
  Put the insert in a seeder; if production needs the row, run
  `console db:seed --force --class=DefaultsSeeder` as part of deploy.
- **Don't write fixture data into your test by hand.** Reach for a factory.
  Five `User::create(attrs!{ … })` blocks in a test are five rewrites the
  moment you add a NOT NULL column. One `UserFactory::new().create()` survives.
- **Don't put production data in a seeder.** A seeder is for the rows the
  application requires to function, not for "here are the 8,000 historical
  records we're importing." Imports are one-off scripts (write a `#[command]`
  for them; see [Console](console.md)).

### Why Suprnova diverges

You explicitly register your root with `seed::register_root::<S>()?`, because
Rust has no class autoloader to discover `DatabaseSeeder`. You keep a flat
registry of named peers and compose them with `call`, `call_silent`,
`call_once` and `call_with`. A project that registers no root retains the
previous registration-order default.

You receive plain progress lines from nested calls. A named command keeps
its outer dot leader at 80 columns. Laravel sizes that leader to the terminal
and colors the status word. You receive whole milliseconds without a
thousands separator, so you can capture progress without terminal escape codes.

## Bootstrap registration

Every seeder needs a `seed::register` call in `bootstrap.rs`, alongside the
other process-global wiring (config, observers, supervisors, queue jobs).
The pattern is the same shape used elsewhere in the bootstrap file:

```rust
// src/bootstrap.rs
pub async fn register() -> Result<(), FrameworkError> {
    // …config + container bindings + auth wiring…

    // Seeders. Order matters - run_all visits in registration order.
    suprnova::seed::register_root::<crate::seeders::BaseSeeder>()?;
    suprnova::seed::register::<crate::seeders::DemoContentSeeder>();

    // …observers, supervisors, queue jobs…
    Ok(())
}
```

If you forget to register a seeder, `console db:seed --class=X` fails with
"no seeder registered for `X`" - a clear signal rather than a silent skip.
The `seed::count()` and `seed::is_registered("…")` helpers exist precisely
so a test can assert the bootstrap registered every seeder you expected.

See [Bootstrap](bootstrap.md) for the full file's structure and the order
the framework expects each subsystem to be wired in.

## Next

- [Migrations](migrations.md) - the schema half of the seed/migrate pair
- [Eloquent](eloquent.md) - models, factories, and the `Persistable` machinery
  every seeder calls into
- [Console](console.md) - the per-project `console` binary that hosts
  `db:seed` alongside your own `#[command]`s
- [Testing](testing.md) - `TestContainer`, `TestDatabase::fresh`, and the
  `#[serial]` pattern for tests that touch the seeder registry
- [Error Model](error-model.md) - what `FrameworkError` is and how
  `run`'s `Result<(), _>` shape composes with the rest of the framework


---

<!-- /docs/laravel-database -->

# Running on a Laravel Database

A Suprnova application can run on a database a Laravel 13 application
created, and it can run next to that Laravel application on the same
database. This chapter lists the tables Suprnova shares with Laravel and the
layout each one takes, explains how an existing Suprnova application
upgrades its own tables to those layouts, and describes the one setting an
application turns on when a Laravel application uses the database at the
same time.

## The tables Suprnova shares with Laravel

Every table the framework or a new scaffold creates under a name that
Laravel, a first-party Laravel package or spatie/laravel-permission also
uses takes that table's layout: the same columns, types, nullability, keys
and indexes that Laravel's or the package's migration creates. There is one
difference. On MySQL, a table Suprnova creates holds its time columns as
`DATETIME` where Laravel's migration says `TIMESTAMP`, because `TIMESTAMP`
refuses any time after 2038-01-19.

| Table | Layout | Created by |
|---|---|---|
| `jobs` | Laravel's `jobs` | `queue::migrations::CreateJobsTable` |
| `job_batches` | Laravel's `job_batches` | `queue::migrations::CreateJobBatchesTable` |
| `failed_jobs` | Laravel's `failed_jobs` | `queue::migrations::CreateFailedJobsTable` |
| `sessions` | the Laravel 13 skeleton's `sessions` | `session::migrations::CreateSessionsTable` |
| `notifications` | Laravel's `notifications` | `notifications::migrations::CreateNotificationsTable` |
| `users` | the Laravel 13 skeleton's `users` | the scaffold's `create_users_table` |
| `features` | laravel/pennant's `features` | `features::migrations::CreateFeaturesTable` |
| `roles`, `permissions` | spatie/laravel-permission's | `rbac::migrations::CreateRbacTables` |
| `model_has_roles`, `model_has_permissions`, `role_has_permissions` | spatie/laravel-permission's | `rbac::migrations::CreateRbacTables` |

Each migration creates its table when it is missing, and leaves a table
Laravel or a package already created exactly as it is. It never alters or
indexes Laravel's table.

Some columns follow the key type of your models, as Laravel's do:

- `notifications.notifiable_id` follows `NOTIFICATIONS_MORPH_KEY`: `int`
  (the default) for Laravel's `morphs`, `uuid` for `uuidMorphs`, or `ulid`
  for `ulidMorphs`.
- `sessions.user_id` follows the key of the default guard's user model.
  Pass `SessionUserKey::Integer` (Laravel's `foreignId`), `SessionUserKey::Uuid`
  (`foreignUuid`) or `SessionUserKey::Ulid` (`foreignUlid`) to
  `CreateSessionsTable::new`.
- `model_has_roles.model_id` and `model_has_permissions.model_id` follow
  `RBAC_MODEL_KEY`: `int`, `uuid` or `ulid`.

Data the framework keeps that Laravel's layout has no column for lives in
tables of its own, under names Laravel does not use:

| Framework table | Holds |
|---|---|
| `suprnova_jobs_reservations` | the token and deadline of each job a worker reserved |
| `job_batch_settlements` | which jobs of a batch settled, so a redelivered job is not counted twice |
| `suprnova_feature_details` | a flag's description and the actor who last changed it |
| `suprnova_role_details`, `suprnova_permission_details` | the display names an earlier release kept |

`cache`, `cache_locks`, `password_reset_tokens` and the tables of the other
first-party packages share no name with a framework table, and Suprnova
leaves them alone.

### What each table holds

- `jobs`: a Suprnova job's `payload` is its envelope with Laravel's
  `displayName` and `uuid` added. Suprnova's workers only reserve rows
  Suprnova wrote, so a Suprnova worker never runs a Laravel job.
- `failed_jobs`: each failed job gets a fresh `uuid`. Its `connection` is
  `suprnova:` followed by the Suprnova connection name, a form no
  connection in Laravel's default `config/queue.php` takes.
- `job_batches`: the counters are kept in Laravel's columns, and `options`
  holds a PHP-serialized array that Laravel's batch repository reads.
- `sessions`: the `payload` is base64-encoded JSON, as the Laravel 13
  skeleton serializes it. Session garbage collection only deletes rows
  Suprnova wrote.
- `features`: a flag is stored as Pennant stores it. The global scope is
  `__laravel_null`, and a user's scope is `App\Models\User|<id>`.
  `FEATURES_USER_SCOPE` names another class or morph alias. A stored value
  other than `false` reads as enabled, as Pennant's `active()` decides.
- `users`: Suprnova never writes `remember_token`, so Laravel's own
  remember-me keeps working. A password reset may clear it, as Laravel's
  documented reset does.

## Registering the migrations

List the framework's migrations in your `Migrator`, after your own:

```rust,no_run
use sea_orm_migration::{MigrationTrait, MigratorTrait};
use suprnova::features::migrations::{
    CreateFeaturesTable, FeatureTimestampsToDatetime, FeaturesToPennantLayout,
};
use suprnova::notifications::migrations::{
    CreateNotificationsTable, NotificationTimestampsToDatetime, NotificationsToLaravelLayout,
};
use suprnova::queue::migrations::{CreateFailedJobsTable, CreateJobBatchesTable, CreateJobsTable};
use suprnova::rbac::migrations::{CreateRbacTables, RbacToSpatieLayout};
use suprnova::session::migrations::{CreateSessionsTable, SessionUserKey};

pub struct Migrator;

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            // ... your own migrations, the users table first ...
            Box::new(CreateSessionsTable::new(SessionUserKey::Integer)),
            Box::new(CreateJobsTable),
            Box::new(CreateJobBatchesTable),
            Box::new(CreateFailedJobsTable),
            Box::new(CreateNotificationsTable),
            Box::new(NotificationTimestampsToDatetime),
            Box::new(NotificationsToLaravelLayout),
            Box::new(CreateFeaturesTable),
            Box::new(FeatureTimestampsToDatetime),
            Box::new(FeaturesToPennantLayout),
            Box::new(CreateRbacTables),
            Box::new(RbacToSpatieLayout),
        ]
    }
}
```

Then run `suprnova migrate`. On a database Laravel created, the migrations
add only the framework's own tables listed above.

## Upgrading an existing Suprnova application

An application an earlier release created has its own layouts under these
names. The same migrations upgrade it in place when `suprnova migrate`
runs:

- `failed_jobs` is reshaped into Laravel's layout. Each failed job keeps its
  id as its `uuid`, so `queue:failed`, `queue:retry <id>` and
  `queue:forget <id>` still find it.
- `jobs` is moved into Laravel's layout. A queued job stays queued, a
  delayed job stays delayed, and a reserved job stays reserved by the same
  token until the same deadline, so the worker that holds it settles it and
  no job runs twice.
- `job_batches` is moved into Laravel's layout, and each batch keeps its
  total, pending and failed counts.
- `sessions` is moved into the skeleton's layout. Every session keeps its
  id, its user, its data and its CSRF token, so nobody is signed out.
- `notifications`, `features`, `roles` and `permissions` are reshaped into
  the layouts above, with every notification, flag, role, permission and
  assignment. The earlier `model_roles`, `model_permissions` and
  `role_permissions` are moved into spatie's tables and dropped.

Each table is copied aside as `suprnova_earlier_<table>` before it is
reshaped, and its rows move in chunks. A `migrate` that stops part way
starts again where it stopped on the next run, and moves no row twice.
Every other table an earlier release created keeps working unchanged.

The framework never reshapes `users`: it is your application's own
migration. This migration moves an earlier scaffold's `users` into the
Laravel 13 skeleton's layout, keeping every row and id. If your `users` has
columns of your own, add them to `Schema::create` and to both column lists.

```rust,no_run
use sea_orm_migration::prelude::*;
use sea_orm_migration::sea_orm::DbBackend;
use suprnova::schema::Schema;

/// Moves the `users` table an earlier scaffold created into the Laravel 13
/// skeleton's layout. Every row keeps its id. A run that stops part way
/// starts again from `users_earlier` on the next `migrate`.
#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        let db = manager.get_connection();
        if !manager.has_table("users_earlier").await? {
            db.execute_unprepared("CREATE TABLE users_earlier AS SELECT * FROM users")
                .await?;
        }
        Schema::drop_if_exists(manager, "users").await?;
        Schema::create(manager, "users", |t| {
            t.unsigned_id();
            t.string("name");
            t.string("email").unique();
            t.date_time("email_verified_at").precision(0).nullable();
            t.string("password");
            t.remember_token();
            t.date_time("created_at").precision(0).nullable();
            t.date_time("updated_at").precision(0).nullable();
        })
        .await?;
        db.execute_unprepared(
            "INSERT INTO users (id, name, email, email_verified_at, password, \
             remember_token, created_at, updated_at) \
             SELECT id, name, email, email_verified_at, password, remember_token, \
             created_at, updated_at FROM users_earlier",
        )
        .await?;
        Schema::drop_if_exists(manager, "users_earlier").await?;
        if manager.get_database_backend() == DbBackend::Postgres {
            // The rows kept their ids; the next one follows the largest.
            db.execute_unprepared(
                "SELECT setval(pg_get_serial_sequence('users', 'id'), \
                 COALESCE((SELECT MAX(id) FROM users), 0) + 1, false)",
            )
            .await?;
        }
        Ok(())
    }

    /// Leaves the skeleton's layout, which holds every earlier row.
    async fn down(&self, _manager: &SchemaManager) -> Result<(), DbErr> {
        Ok(())
    }
}
```

After it runs, the scaffold's `User` model reads `id` into a `u64`, and its
timestamps into `Option<DateTime<Utc>>`.

## Sharing the database with a running Laravel application

When a Laravel application uses the database at the same time, turn on one
setting:

```bash
LARAVEL_SHARED_DATABASE=true
```

or call `LaravelDatabase::share(true)` in your bootstrap. With the setting
on:

- Every password hash the framework and Magnetar write is a `$2y$` bcrypt
  hash, which Laravel's hasher accepts with `HASH_VERIFY=true`. A valid
  sign-in rewrites a `$2b$` or Argon2id hash as `$2y$`, at the configured
  bcrypt cost or at the stored hash's cost when that is higher, and
  Magnetar no longer upgrades bcrypt hashes to Argon2id. So Laravel signs
  in every user Suprnova signed in, registered or reset. If Suprnova can't
  write the `$2y$` hash, the sign-in fails with that error, because Laravel
  couldn't sign that user in. The stored hash stays as it was, and the next
  sign-in tries the rewrite again.
- A job queued with default settings is stored on the queue `suprnova`
  instead of `default`. Laravel's `database` connection reads `default`, so
  Laravel's worker never reserves a Suprnova job. Inside Suprnova the
  queue keeps its name: a job routed to `default` and a worker started with
  `--queue=default` both use the stored `suprnova`.

The setting gives up two things the framework does by default:

- Argon2id. Without the setting, Magnetar upgrades a bcrypt hash to
  Argon2id on a valid sign-in. With it, every hash stays bcrypt, which
  judges a password by its first 72 bytes.
- The stored queue name `default`. A tool that reads the `jobs` table
  directly, Laravel's `queue:monitor` included, sees `suprnova` for
  Suprnova's unrouted jobs.

Without the setting, `$2y$` hashes Laravel wrote still verify through
`Auth::attempt` and Magnetar, passwords of 72 bytes and longer included.

### Laravel's `queue:retry` and Suprnova's failed jobs

Laravel's `queue:retry` cannot retry a failed job Suprnova wrote, because
Laravel has no queue connection named `suprnova:<connection>`. So
`queue:retry all` stops at the first failed job Suprnova wrote. Run
`queue:retry --queue=<queue>` with a queue only Laravel uses, and Laravel
retries its own failed jobs. Retry Suprnova's failed jobs with Suprnova's
`queue:retry`.

## Polymorphic types and morph aliases

Laravel stores a PHP class name, such as `App\Models\Post`, in a
polymorphic `*_type` column. Declare it as the model's `morph_type`. A
Laravel application that adopted `Relation::morphMap` late holds both the
class name and the alias, such as `post`, for one model. Register the
alias with `morph_aliases`:

```rust,no_run
use suprnova::model;

#[model(
    table = "posts",
    morph_type = "App\\Models\\Post",
    morph_aliases = ["post"],
    relations = {
        comments: MorphMany<Comment> { name = "commentable" },
    },
)]
pub struct Post {
    pub id: u64,
    pub title: String,
}

#[model(table = "comments", relations = {
    commentable: MorphTo { name = "commentable", targets = [Post] },
})]
pub struct Comment {
    pub id: u64,
    pub commentable_type: String,
    pub commentable_id: u64,
    pub body: String,
}
```

Reads accept every name: a `MorphTo` loads the post a row names by either
form, and a `MorphOne` or `MorphMany`, direct or eager, matches rows that
hold either. Writes store the `morph_type`. The RBAC stores a model's
`morph_type` as spatie's `model_type`, so declare `morph_type =
"App\\Models\\User"` on your user model when spatie's tables hold Laravel's
assignments.

## Unsigned keys on MySQL

Your new tables use unsigned IDs on MySQL by default. You use `id()` and
`foreign_id()` to match Laravel's keys, and `timestamps()` to create
nullable timestamps. A new scaffold's `users.id` is already unsigned.
Declare unsigned keys as `u64` in your models.

If your existing tables use signed IDs, keep that shape in new migrations
with the opt-out:

```toml
[package.metadata.suprnova.schema]
unsigned_ids = false
```

`#[suprnova::main]` installs it before migrations. Without that entry point,
you call `suprnova::schema::Schema::set_unsigned_ids(false)` before your first
migration. You keep signed columns on Postgres and SQLite with either
setting. See [Migrations](migrations.md).

## What Suprnova does not support

- Sanctum tokens Laravel issued. Suprnova does not read
  `personal_access_tokens`.
- Columns Laravel's encrypter wrote, such as Fortify's two-factor secrets
  and recovery codes, and any column with an `encrypted` cast. Suprnova
  cannot decrypt them.
- Remember-me cookies Laravel issued. A user signed in to Laravel signs in
  to Suprnova separately.
- A Laravel application or a database server whose time zone is not UTC.
  Suprnova reads every stored time as UTC.

### Why Suprnova diverges

Laravel owns each of these tables in its own application, and a second
application writing to them is not a case Laravel plans for. Suprnova takes
Laravel's layouts so both applications read the same rows, and it keeps
what Laravel's layouts cannot hold in tables of its own instead of adding
columns to Laravel's tables. A failed job's connection names a connection
Laravel does not have, so Laravel's `queue:retry` refuses it instead of
running a job Laravel cannot decode. The setting is off by default because
`$2b$`, Argon2id and the queue name `default` are the better choices for an
application that does not share its database.

## Next

- [Database](database.md) - connections, transactions and the query builder
- [Migrations](migrations.md) - the schema builder and `unsigned_ids`
- [Queues](queues.md) - workers, failed jobs and batches
- [From Laravel](from-laravel.md) - how Laravel habits map to Suprnova


---

<!-- /docs/mongodb -->

# MongoDB

MongoDB stores documents instead of rows: each record is a BSON document
with nested values, arrays, and embedded documents. Suprnova talks to it
through the official `mongodb` driver, behind the `database-mongodb`
feature. The `Mongo` facade answers the connection, its database, and typed
collections, the way Laravel's `mongodb` connection does with the
`laravel-mongodb` package.

```rust
use suprnova::Mongo;
use suprnova::bson::{Document, doc};

Mongo::ping().await?;
let users = Mongo::collection::<Document>("users")?;
let ada = users.find_one(doc! { "name": "Ada" }).await?;
```

## Installation

The MongoDB backend is off by default, because the driver is a large
dependency tree that an SQL-only application never needs. To turn it on,
add the `database-mongodb` feature to the `suprnova` dependency:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", features = ["database-mongodb"] }
```

The feature brings the `mongodb` driver and the `bson` crate. You don't add
either to your own `Cargo.toml`: Suprnova re-exports BSON as
`suprnova::bson` and the driver's types under `suprnova::mongodb`, at the
versions it links. Without the feature, neither crate is in your build.

You need a MongoDB server. For local work, the MongoDB Community Server
runs on Linux, macOS, and Windows, or in Docker:

```bash
docker run -d --name mongodb -p 27017:27017 mongo:8
```

## Configuration

Two variables configure the connection, the same ones Laravel's MongoDB
page uses:

```ini
MONGODB_URI="mongodb://127.0.0.1:27017"
MONGODB_DATABASE="shop"
```

`MONGODB_URI` is the connection string. It starts with `mongodb://`, or with
`mongodb+srv://` for a MongoDB Atlas cluster:

```ini
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority"
MONGODB_DATABASE="shop"
```

`MONGODB_DATABASE` names the database your application uses. When it's
unset, Suprnova takes the database from the URI's path, so
`mongodb://127.0.0.1:27017/shop` alone also selects `shop`.
`MONGODB_DATABASE` wins when both name one.

Pool and timeout options go in the URI's query string, as the driver reads
them: `maxPoolSize`, `minPoolSize`, `maxIdleTimeMS`, `maxConnecting`,
`connectTimeoutMS`, and `serverSelectionTimeoutMS`, among others. For
example, `mongodb://127.0.0.1:27017/?maxPoolSize=20` caps each server's pool
at 20 connections.

Suprnova checks the configuration before it uses it, without contacting
the server:

- An unset or blank `MONGODB_URI` is an error that names `MONGODB_URI`.
- A value that isn't a MongoDB connection string is an error that names
  `MONGODB_URI` and gives the driver's reason.
- A missing database, or a name MongoDB refuses (empty, longer than 63
  bytes, or holding `/`, `\`, `.`, a space, `"`, or `$`), is an error that
  names `MONGODB_DATABASE`.

None of these is a panic, and no error or `Debug` output shows the URI's
password or query string.

### Configure the connection in code

To configure the connection in code, build a `MongoConfig` and register it
in your configuration. The builder takes the URI, the database, and the pool
options, and it falls back to `MONGODB_URI` and `MONGODB_DATABASE` for what
you don't set:

```rust
use std::time::Duration;
use suprnova::{Config, MongoConfig};

pub fn register() -> Result<(), suprnova::FrameworkError> {
    Config::register(
        MongoConfig::builder()
            .uri("mongodb://127.0.0.1:27017")
            .database("shop")
            .max_pool_size(50)
            .min_pool_size(5)
            .max_idle_time(Duration::from_secs(300))
            .max_connecting(4)
            .connect_timeout(Duration::from_secs(5))
            .server_selection_timeout(Duration::from_secs(5))
            .build()?,
    );
    Ok(())
}
```

A pool option you set in the builder wins over the same option in the URI.
`build` refuses a `max_pool_size` or `max_connecting` of 0 and a
`min_pool_size` above `max_pool_size`, naming the option.

`MongoConfig::from_env()` is the builder with nothing set: the two variables
and nothing else.

### Named connections

The connection that `MONGODB_URI` configures is named `mongodb`, as in
Laravel's `config/database.php`; `DEFAULT_MONGO_CONNECTION` holds the name.
To reach a second server or database, add a named connection to the
builder:

```rust
use suprnova::{Config, MongoConfig, MongoConnectionConfig};

let analytics = MongoConnectionConfig {
    max_pool_size: Some(5),
    ..MongoConnectionConfig::new("mongodb://analytics.internal:27017", "events")
};

Config::register(
    MongoConfig::builder()
        .connection("analytics", analytics)
        .build()?,
);
```

A connection can't be named `mongodb` or have an empty name, and an error
about a named connection names it.

## Connect at boot

The server registers the connections in the container when it boots, if
`MONGODB_URI` is set or a `MongoConfig` is registered. The queue, schedule,
and workflow workers and the console register them the same way. It happens
before the cache and the queue boot, so the drivers that run on MongoDB find
the connection. With neither set, nothing is registered and the boot goes
on.

The driver connects lazily. Registering a connection opens no socket, so a
MongoDB server that is down doesn't stop your application from booting.
Instead, the first call that needs the server fails: `Mongo::ping()`
returns a `FrameworkError`, and so does a driver operation such as
`find_one` once `?` converts its error. The one exception is a
`mongodb+srv://` URI: the driver looks up its DNS records when the
connection is registered, because it needs them to know the hosts.

A `MONGODB_URI` that is set but invalid stops the boot of the server and
the workers with the error that names it. The console reports it and goes
on, so a command that doesn't use MongoDB still runs.

Your application's `bootstrap` hook runs before the boot registers the
connections. To use MongoDB there, for example to create indexes, register
the connections yourself first:

```rust
use suprnova::Mongo;

pub async fn register() -> Result<(), suprnova::FrameworkError> {
    // Reads the registered `MongoConfig`, or `MONGODB_URI` and
    // `MONGODB_DATABASE` when none is registered.
    Mongo::init().await?;
    Ok(())
}
```

`Mongo::init_with(config)` registers the connections of a `MongoConfig` you
pass. Both replace connections registered before. The boot keeps
connections that your application registered first.

The driver runs its pool and server monitors as Tokio tasks, so a connection
is opened from inside your application's runtime. Opening one anywhere else
is an error, not a panic.

## The Mongo facade

The facade answers the connections the boot registered:

| Call | Returns |
|---|---|
| `Mongo::connection()` | The `mongodb` connection, a `MongoConnection`. |
| `Mongo::connection_named(name)` | The connection `name`. `"mongodb"` is the default one. |
| `Mongo::database()` | The default connection's database, a `suprnova::mongodb::Database`. |
| `Mongo::collection::<T>(name)` | A typed `suprnova::mongodb::Collection<T>` in that database. |
| `Mongo::ping()` | `Ok(())` when the server answers `ping`. |

Every call returns a `Result`. With no connection registered, the error says
why: `MONGODB_URI` is unset or invalid, the database name from
`MONGODB_DATABASE` or the URI is missing or invalid, or `MONGODB_URI` is set
or a `MongoConfig` is registered while the boot hasn't run yet in this
process. An unknown name in `connection_named` is an error that names it.

A `MongoConnection` has the same methods for one connection, plus `name()`
and `client()`, the driver's client for other databases, sessions, and
transactions:

```rust
use suprnova::Mongo;
use suprnova::bson::Document;

let analytics = Mongo::connection_named("analytics")?;
analytics.ping().await?;
let events = analytics.collection::<Document>("page_views");
let other = analytics.client().database("archive");
```

### Typed collections

A collection reads and writes your own types through serde. Nothing is sent
to the server until an operation runs:

```rust
use serde::{Deserialize, Serialize};
use suprnova::Mongo;
use suprnova::bson::doc;

#[derive(Debug, Serialize, Deserialize)]
struct Note {
    title: String,
    pages: i32,
}

let notes = Mongo::collection::<Note>("notes")?;
notes.insert_one(Note { title: "Draft".into(), pages: 3 }).await?;
let draft = notes.find_one(doc! { "title": "Draft" }).await?;
```

The collection is the driver's own type, so every driver operation works on
it: `find`, `aggregate`, `update_many`, `create_index`, and the rest. For the
driver's options, cursors, and other types, use `suprnova::mongodb::driver`,
which is the whole `mongodb` crate.

A driver operation returns the driver's error. In code that returns
`Result<_, FrameworkError>`, `?` converts it, and the driver's error stays
the source:

```rust
use suprnova::bson::{Document, doc};
use suprnova::{FrameworkError, Mongo};

async fn count_users() -> Result<u64, FrameworkError> {
    let users = Mongo::collection::<Document>("users")?;
    Ok(users.count_documents(doc! {}).await?)
}
```

### Health checks

`Mongo::ping()` sends `ping` to the server. A server that can't be reached
fails after the server selection timeout, 30 seconds unless the URI or the
builder sets another. The error names the connection and keeps the driver's
error as its source, which `FrameworkError::external_source` returns.

## Models

A document model is a struct that `#[suprnova::document]` stores in a
collection. It has the Eloquent calls of an SQL model: `create`, `find`,
`find_or_fail`, `all`, `query`, `save`, `update`, `delete`, `fresh`, and
`refresh`. The calls come from the `DocumentModel` trait, so import it where
you call them:

```rust
use suprnova::bson::doc;
use suprnova::{DocumentModel, FrameworkError};

#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct Address {
    pub street: String,
    pub city: String,
}

#[suprnova::document(
    collection = "users",
    fillable = ["name", "email", "password", "tags", "addresses"],
    hidden = ["password"],
    soft_deletes
)]
pub struct User {
    pub name: String,
    pub email: String,
    pub password: Option<String>,
    pub tags: Vec<String>,
    #[embeds_many]
    pub addresses: Vec<Address>,
    pub created_at: Option<suprnova::bson::DateTime>,
    pub updated_at: Option<suprnova::bson::DateTime>,
    pub deleted_at: Option<suprnova::bson::DateTime>,
}

async fn example() -> Result<(), FrameworkError> {
    let user = User::create(doc! {
        "name": "Ada",
        "email": "ada@example.com",
        "tags": ["math"],
    })
    .await?;

    let found = User::find(user.id).await?;
    let user = user.update(doc! { "name": "Ada Lovelace" }).await?;
    user.delete().await?;
    Ok(())
}
```

The macro derives `Clone` and `Debug`, and it implements serde's `Serialize`
for the struct, so don't derive those three yourself. The model's events
need the first two, and the third honours `hidden` and `visible`.

### Collection and connection

`collection = "..."` names the collection. Without it, the collection is the
plural snake-case name of the struct, so `BlogPost` is stored in
`blog_posts`. `connection = "..."` stores the model on a named connection
instead of the default `mongodb` one.

### Keys

Every document has a key, which MongoDB stores as `_id`. Without a
`primary_key`, the key is the field `id`. A struct without an `id` field
gets one: `pub id: ObjectId`, which the model generates when you make or
create it. You read it as `user.id`, and `User::find` takes it.

To use another field as the key, name it with `primary_key`. That field is
stored as `_id`, and you give its value when you create a document:

```rust
#[suprnova::document(collection = "products", primary_key = "sku", fillable = ["sku", "title"])]
pub struct Product {
    pub sku: String,
    pub title: String,
}

let anvil = Product::create(doc! { "sku": "A-1", "title": "Anvil" }).await?;
let same = Product::find("A-1").await?;
```

A key of type `ObjectId`, `String`, `i64`, or `i32` works out of the box. For
another type, implement `DocumentKey`: it says how a route parameter names a
key and whether the model can generate one.

In queries, the key's field name means `_id`, so
`User::query().where_("id", "=", id)` matches the stored `_id`.

### Mass assignment

`fillable` and `guarded` take the same lists as on an SQL model, and the
same rules apply: `create`, `update`, `make`, and `fill` drop a field the
guard refuses, or return an error when you turned on
`prevent_silently_discarding_attributes(true)`. Without either list, the
guard refuses the key. `suprnova::eloquent::unguarded` turns the guard off
for one task, as it does for SQL models.

A field that the struct doesn't declare is an error that names it, since the
model has nowhere to keep its value. A value of the wrong type, such as a
string for an `i64` field, is an error that names the field, and nothing is
written.

`make(attrs)` builds a model without storing it, and `fill(attrs)` sets
fields on one. Call `save` to store either.

### Field types and casts

Each field is stored through serde, so strings, numbers, booleans, `Vec`s,
nested structs, and `bson::Document` values keep their BSON types. A unit
enum is stored as its serde name, which is a string. Three field types get
the BSON type made for them:

| Field type | Stored as | Cast |
|---|---|---|
| `bson::DateTime` | BSON datetime | none needed |
| `chrono::DateTime<Utc>` | BSON datetime | `AsBsonDateTime` |
| `rust_decimal::Decimal` | `Decimal128` | `AsDecimal128` |

The macro selects the cast for a `chrono::DateTime<Utc>` or a `Decimal`
field, and for an `Option` of one. A BSON datetime holds milliseconds, so a
`chrono` time with finer precision reads back truncated to the millisecond.
Both casts also read a string, which is how a date or a decimal arrives in
attributes you build with `doc!`.

To store a field another way, write a type that implements
`DocumentCast<FieldType>` and name it in `casts`, as on an SQL model:

```rust
#[suprnova::document(casts = { colour = AsHexColour })]
pub struct Theme {
    pub colour: Colour,
}
```

When a stored document lacks a field, an `Option` field reads as `None` and a
`Vec` field reads as empty. Any other missing field is an error that names
it.

### Timestamps

When the struct has both `created_at` and `updated_at`, the model manages
them as BSON datetimes. `create` sets both, and so does a `save` that inserts
the document. Every write through the model sets `updated_at`: `save`,
`update`, `restore`, a soft `delete`, `increment`, `decrement`, `push`,
`push_unique`, and `pull`, and the embedded relations' `save`, `save_many`,
`destroy`, `clear`, and `delete`. Each call sets it in the same write as its
change.

A struct with only one of the two fields fails to compile.
`timestamps = true` on a struct without the fields also fails to compile. To
turn the timestamps off, set `timestamps = false`. To rename the fields, set
`created_at = "..."` and `updated_at = "..."`.

### Soft deletes

With `soft_deletes`, `delete` sets the `deleted_at` field instead of removing
the document, and queries leave such trashed documents out. The field must
be an optional date-time. To use another field, set
`soft_deletes_column = "..."`.

```rust
user.delete().await?;                           // sets deleted_at
let trashed = User::only_trashed().get().await?;
let everyone = User::with_trashed().get().await?;

let user = trashed.into_vec().remove(0).restore().await?;
user.force_delete().await?;                     // removes the document
```

`restore` on a model without soft deletes is an error that names `restore`.

### Embedded documents

Mark a `Vec<T>` field `#[embeds_many]`, or an `Option<T>` field
`#[embeds_one]`, to store `T` values inside the document. `T` is a plain
struct that implements serde's `Serialize` and `Deserialize`. The model reads
and writes the field like any other, and it gains a method with the field's
name that answers the relation:

```rust
let mut user = User::find_or_fail(id).await?;
user.addresses()
    .save(&Address { street: "2 Engine Row".into(), city: "Leeds".into() })
    .await?;
user.addresses().destroy(&old_address).await?;
```

An `embeds_many` relation has `save`, `save_many`, `destroy`, and `clear`.
An `embeds_one` relation has `save` and `delete`. Each call writes to the
server and reloads the model from the result.

### Array and counter operators

These calls change one field on the server and reload the model. On a model
with timestamps, every call also sets `updated_at` in the same write:

| Call | Operator |
|---|---|
| `push(field, value)` | `$push`: append `value`, and set `updated_at` |
| `push_unique(field, value)` | `$addToSet`: append unless present, and set `updated_at` |
| `pull(field, value)` | `$pull`: remove every equal element, and set `updated_at` |
| `increment(field, by)` | `$inc`, and set `updated_at` |
| `decrement(field, by)` | `$inc` with `-by`, and set `updated_at` |

```rust
user.push("tags", "rust").await?;
user.pull("tags", "math").await?;
user.increment("logins", 1).await?;
```

`field` can be a dotted path into an embedded document. A field the model
doesn't declare, or the key, is an error that names it, and so is an
`increment` amount that isn't an integer or a float.

### Events and observers

Document models fire the lifecycle events of SQL models, in Laravel's order:
`Saving`, then `Creating` or `Updating`, the write, `Created` or `Updated`,
and `Saved`. SQL models in Suprnova fire `Creating` before `Saving`; document
models keep Laravel's order. `delete` fires `Deleting`, `Trashed` when the model soft
deletes, and `Deleted`. `restore` fires `Restoring`, the update's events,
and `Restored`. Queries fire `Retrieving` and `Retrieved`. Each event is a
generic type in `suprnova::mongodb::events`, such as `Created<User>`.

A listener on `Saving`, `Creating`, `Updating`, `Deleting`, or `Restoring` can
cancel the write: the call returns a `400 Bad Request` error with the
listener's reason, and nothing is written. The first three carry the
attributes about to be written as a `bson::Document`, which the listener can
change.

To collect the callbacks in one place, implement `DocumentObserver` and
register it with `#[suprnova::observer]`, as for an SQL model:

```rust
use suprnova::bson::Document;
use suprnova::{DocumentObserver, EventResult};

pub struct UserObserver;

#[suprnova::observer(User)]
#[suprnova::async_trait]
impl DocumentObserver<User> for UserObserver {
    async fn creating(&self, attrs: &mut Document) -> EventResult {
        attrs.insert("tags", vec!["new"]);
        EventResult::ok()
    }
}
```

`User::observe(UserObserver).await` registers an observer by hand instead.

### Serialization

The model serializes as its fields: the key under its field name, an
`ObjectId` as its hex string, a datetime as RFC 3339 text, and a
`Decimal128` as its decimal text. `hidden = [...]` leaves fields out, and
`visible = [...]` writes only the fields it lists. So a handler can answer a
model as JSON:

```rust
let json = serde_json::to_value(&user)?;
// {"id":"6523...","name":"Ada","email":"ada@example.com","tags":["math"],...}
```

For the stored form, call `to_document()`, which writes the key as `_id`.

### Route binding

A document model binds from a route parameter by its key, like an SQL
model. A parameter that isn't a valid key, such as text that isn't an
`ObjectId`, binds nothing, so the route answers `404 Not Found` without a
query. A route with `with_trashed()` also binds trashed documents. A
parameter with a binding field, such as `{user:email}`, matches that field
as text.

### Why Suprnova diverges

- **Calls through a trait.** Laravel models extend
  `MongoDB\Laravel\Eloquent\Model`. A Suprnova document model implements the
  `DocumentModel` trait, so you import the trait to call `create` or `find`.
- **Declared fields.** A Laravel MongoDB model stores any attribute you set.
  A Suprnova model stores the fields its struct declares, so an attribute
  that names no field is an error instead of an extra stored field.
- **Embedded relations by field.** Laravel declares `embedsMany` in a
  relation method. Suprnova marks the field, so the embedded documents are
  part of the struct and read with it.

## Queries

A model's `query()` returns a `DocumentQuery`, the builder for its
collection. Chain conditions and finish with a call that runs the query:

```rust
use suprnova::{Direction, DocumentModel};

let adults = User::query()
    .where_("age", ">=", 18)
    .where_in("role", ["admin", "editor"])
    .order_by("name", Direction::Asc)
    .skip(10)
    .take(5)
    .get()
    .await?;
```

The method is `where_` because `where` is a Rust keyword.

### Conditions

| Call | Matches |
|---|---|
| `where_(field, op, value)` | `field` compared with `value` |
| `or_where(field, op, value)` | the same, joined with OR |
| `where_in(field, values)` | `field` equal to one of `values` (`$in`) |
| `where_not_in(field, values)` | `field` equal to none of `values` (`$nin`) |
| `where_null(field)` | `field` null or missing |
| `where_not_null(field)` | `field` present and not null |
| `where_between(field, low..=high)` | `field` from `low` to `high`, both included |
| `where_date(field, date)` | a datetime `field` on the UTC day `date` |
| `where_exists(field)` | `field` present, null or not |
| `where_raw(filter)` | a filter in MongoDB's query language |

`op` is one of `=`, `!=` (or `<>`), `<`, `<=`, `>`, `>=`, `like`, and
`not like`. `like` takes an SQL pattern, where `%` matches any run of
characters and `_` matches one character. It matches the whole value and
ignores case, so `where_("name", "like", "jo%")` matches `Joan` and `john`.

Conditions join with AND. `or_where` starts a new group, and the conditions
after it join that group. AND binds tighter than OR, as in SQL, so this
query matches people over 60, and admins in the core team:

```rust
let people = User::query()
    .where_("age", ">", 60)
    .or_where("role", "=", "admin")
    .where_("team", "=", "core")
    .get()
    .await?;
```

A field can be a dotted path into an embedded document, such as
`addresses.city`. `where_raw` takes its filter as written, so in it the key
is `_id`. `=` compares the whole value, so a document such as
`{"$ne": null}` or a regular expression you pass to `where_` matches only a
field that holds that value; send query operators through `where_raw`. An
unknown operator, or `like` with a value that isn't a string, makes the
query an error that names `where_`.

### Order, offset, limit, and projection

`order_by(field, direction)` sorts, and later calls sort the ties of earlier
ones. `skip(n)` and `take(n)` set the offset and the limit. `project(fields)`
reads only those fields of each document. A projected query hydrates a model
only when its other fields are `Option` or `Vec` fields, so read projected
documents with `get_documents()`, which answers them as `bson::Document`
values.

### Reading

| Call | Returns |
|---|---|
| `get()` | the matching models, as a `Collection` |
| `get_documents()` | the matching documents, unread |
| `first()` | the first match, or `None` |
| `count()` | the number of matches |
| `exists()` | whether anything matches |
| `pluck(field)` | the value of `field` in each match |
| `distinct(field)` | the distinct values of `field` |
| `sum(field)`, `avg(field)`, `min(field)`, `max(field)` | one value, or `None` when nothing matches |
| `paginate(per_page, page)` | a `LengthAwarePaginator` with the total |
| `simple_paginate(per_page, page)` | a `Paginator` without a total |

The page is 1-based, and your handler passes it. For example, read it from
the query string:

```rust
use suprnova::Context;

let page = Context::query_param("page")
    .and_then(|page| page.parse().ok())
    .unwrap_or(1);
let users = User::query()
    .order_by("name", Direction::Asc)
    .paginate(15, page)
    .await?;
```

### Grouping and aggregates

`group_by(fields)` groups the matches. Add aggregates to it, then call
`get()`, which answers one `bson::Document` per group: the group fields and
the aggregates. `count()` adds `count`. `sum(field)`, `avg(field)`,
`min(field)`, and `max(field)` add `sum_<field>`, `avg_<field>`,
`min_<field>`, and `max_<field>`:

```rust
let per_role = User::query()
    .where_("active", "=", true)
    .group_by(["role"])
    .count()
    .avg("age")
    .order_by("count", Direction::Desc)
    .get()
    .await?;
// [{ "role": "user", "count": 12, "avg_age": 31.5 }, ...]
```

The order, skip, and take apply to the groups. `group_by` with no fields puts
every match in one group.

### Writing

These calls write to every matching document and return how many changed:

| Call | Writes |
|---|---|
| `update(doc)` | the fields of `doc` with `$set`, or `doc` as update operators |
| `increment(field, by)`, `decrement(field, by)` | `$inc` |
| `push(field, value)`, `pull(field, value)` | `$push`, `$pull` |
| `unset(fields)` | `$unset` |
| `delete()` | removes the matches, or trashes them when the model soft deletes |
| `force_delete()` | removes the matches, trashed or not |

`update` with plain fields leaves the other fields as they are. With update
operators, such as `doc! { "$inc": { "views": 1 } }`, it sends them as they
are. `update`, `increment`, and `decrement` also set `updated_at` when the
model manages timestamps. These calls don't fire model events, as Laravel's
query updates don't.

`upsert(values, unique_by)` inserts each value, or updates the document
whose `unique_by` fields equal the value's:

```rust
User::query()
    .upsert(
        vec![doc! { "email": "ada@example.com", "name": "Ada" }],
        &["email"],
    )
    .await?;
```

### Rendering without a server

`to_filter()` answers the parts of the find command the builder sends: the
filter, the sort, the skip, the limit, and the projection. `to_pipeline()`
answers the same query as aggregation stages. A group's `to_pipeline()`
answers its `$group` stage and the rest. Use them to check a query in a test:

```rust
let rendered = User::query()
    .where_("age", ">=", 18)
    .where_in("role", ["a", "b"])
    .to_filter()?;
assert_eq!(rendered.filter, doc! { "age": { "$gte": 18 }, "role": { "$in": ["a", "b"] } });
```

On a soft-deleting model, the filter includes the condition that leaves
trashed documents out.

### Chains that can't run

A chain that MongoDB can't run as written is an error that names the call,
not a query that matches more or less than you asked for. The builder checks
before it contacts the server:

- A write after `skip` or `take`: MongoDB writes every matching document.
- `upsert` after a condition, an order, `skip`, or `take`: it matches each
  value by its `unique_by` fields.
- `upsert` of a value without its `unique_by` fields, or without a key the
  model can't generate.
- `distinct(field)` ordered by another field, which the distinct values don't
  carry.
- `update` that mixes operators and fields, or that writes the key.
- A one-value aggregate such as `sum` with a projection.

### Why Suprnova diverges

- **Explicit page.** Laravel's `paginate` reads the page from the request.
  `paginate(per_page, page)` takes the page as an argument, so you can call
  it outside a request.
- **Writes take no limit.** Laravel MongoDB accepts a limit on some writes,
  such as `take(1)` before a delete. Suprnova refuses `skip` and `take` on
  every write, so a write never matches more or less than its conditions
  say. To write some of the matches, select their keys with `pluck` and
  write by them.
- **Aggregates by name.** Laravel's grouped aggregates come back as
  `aggregate`. Suprnova names each one after its function and field, so one
  group can carry several.

## Relations

Document models relate to each other the way SQL models do, and to SQL
models across the two stores. Declare relations in `relations = { ... }` on
`#[suprnova::document]`, with the grammar of `#[suprnova::model]`:

```rust
use suprnova::bson::oid::ObjectId;

#[suprnova::document(
    collection = "users",
    fillable = ["name"],
    relations = {
        posts: HasMany<Post>,
        profile: HasOne<Profile>,
        roles: BelongsToMany<Role>,
    }
)]
pub struct User {
    pub name: String,
    pub role_ids: Vec<ObjectId>,
}

#[suprnova::document(
    collection = "posts",
    fillable = ["user_id", "title"],
    relations = { user: BelongsTo<User> }
)]
pub struct Post {
    pub user_id: ObjectId,
    pub title: String,
}
```

A document relates with these kinds:

| Kind | Relates to | Method answers |
|---|---|---|
| `HasOne<D>` | one document of `D` whose foreign key holds this key | `HasOneDocument<D>` |
| `HasMany<D>` | the documents of `D` whose foreign key holds this key | `HasManyDocuments<D>` |
| `BelongsTo<D>` | the document of `D` this foreign key names | `BelongsToDocument<D>` |
| `BelongsToMany<D>` | documents of `D`, each side keeping the other's keys in an array | `BelongsToManyDocuments<Self, D>` |
| `BelongsToModel<M>` | the SQL model `M` this foreign key names | `BelongsToModel<M>` |

Each relation's keys default to Laravel's names. Name others with options:

| Kind | Default | Options |
|---|---|---|
| `HasOne`, `HasMany` | `<parent>_id` on the related document, holding this key | `fk` names the related field; `lk` names this document's field instead of the key |
| `BelongsTo`, `BelongsToModel` | `<related>_id` on this document, holding the related key | `fk` names this document's field; `lk` names the related field or column instead of the key |
| `BelongsToMany` | `<related>_ids` on this document and `<this>_ids` on the related one | `pivot_related_key` names this document's array; `pivot_foreign_key` names the related array |

A document with relations gets an `__eager` field beside its own fields. It
holds what `with` loaded, and the collection never stores it.

### Read a relation

Each relation adds a method of its name. The method sends no query. Its
`get` reads the related documents, and its `query` answers the
`DocumentQuery`, so you can add conditions first:

```rust
let posts = user.posts().get().await?;
let drafts = user.posts().query().where_("published", "=", false).get().await?;
let count = user.posts().count().await?;
let author = post.user().get().await?;
```

`HasMany` and `BelongsToMany` have `get`, `first`, `count`, and `exists`.
`HasOne` and `BelongsTo` have `get`, which answers an `Option`. A
`BelongsTo` whose foreign key is null answers `None` without a query.

`create` on a `HasMany` or a `HasOne` creates a related document with the
foreign key set to the parent's key. The model's guard applies to the
attributes you pass, and the relation's key always wins:

```rust
let post = user.posts().create(doc! { "title": "Hello" }).await?;
assert_eq!(post.user_id, user.id);
```

### Eager loading

`with` loads relations for every document a query reads, with one query per
relation however many documents there are. Read a loaded relation with
`<name>_loaded()`, which answers `None` when no query loaded it:

```rust
let users = User::query().with(["posts", "profile"]).get().await?;
for user in users.iter() {
    let posts = user.posts_loaded().unwrap_or_default();
    let profile = user.profile_loaded();
}
```

A dotted path loads a relation of the related documents, with one more
query per step: `with(["posts.user"])` loads each post's user. `get`,
`first`, `paginate`, and `simple_paginate` load the relations.
`relation_loaded("posts")` answers whether a query loaded one. A name the
model doesn't declare is an error that names it, before any query runs.

### Many-to-many

A `BelongsToMany` keeps no pivot collection. Each side keeps the keys of the
other in an array, as Laravel MongoDB stores it: a user's `role_ids` holds
its roles, and each role's `user_ids` holds its users. The relation reads
the related side's array, so declare it on both models to read it from
both:

```rust
#[suprnova::document(
    collection = "roles",
    fillable = ["name"],
    relations = { users: BelongsToMany<User> }
)]
pub struct Role {
    pub name: String,
    pub user_ids: Vec<ObjectId>,
}
```

`attach`, `detach`, `detach_all`, and `sync` write both arrays and answer
the parent as the server holds it after. Assign the answer to keep the
parent's own array current:

```rust
let user = user.roles().attach([editor.id, admin.id]).await?;
let users = editor.users().get().await?;
let user = user.roles().detach([admin.id]).await?;
let user = user.roles().sync([editor.id]).await?;
```

The parent is written first, so a parent that no longer exists fails the
call before any related document changes. Without a transaction, the two
writes are separate. Each one is idempotent, so calling `attach` again
completes one that failed between them.

### Relations across stores

An SQL model relates to documents with `HasManyDocuments<D>` and
`HasOneDocument<D>`, and a document relates to an SQL model with
`BelongsToModel<M>`. Each relation reads through its own store: the
documents from their collection, the SQL model through its connection.

```rust
#[suprnova::model(table = "accounts", relations = {
    notes: HasManyDocuments<Note>,
    setting: HasOneDocument<Setting>,
})]
pub struct Account {
    pub id: i64,
    pub name: String,
}

#[suprnova::document(
    collection = "notes",
    fillable = ["account_id", "body"],
    relations = { account: BelongsToModel<Account> }
)]
pub struct Note {
    pub account_id: i64,
    pub body: String,
}

let notes = account.notes().get().await?;
let owner = note.account().get().await?;
let accounts = Account::query().with(["notes"]).with_count(["notes"]).get().await?;
let notes = Note::query().with(["account"]).get().await?;
```

On the SQL side, `with` and `with_count` read the documents with one query,
and `<name>_loaded()` and `<name>_count()` answer `None` until a query loads
them. A dotted path crosses the stores both ways, such as
`with(["notes.account"])`. A document's `BelongsToModel` query is the SQL
model's `Builder`, so its global scopes and soft deletes apply. An SQL
model's relations to documents honour lazy-loading prevention, as its SQL
relations do.

These calls don't reach across the stores, and each one is an error that
says so:

- `with_where` on a relation to documents. Add the conditions to the
  relation's `query()` instead.
- `with_sum`, `with_avg`, `with_min`, and `with_max` over documents.
  Aggregate the relation's `query()` instead.

### Key types

The key a relation compares and the field that holds it must have types that
can match: the same type, the field holding it in an `Option`, or a `Vec` of
keys for a many-to-many array. Each relation checks this when it compiles. A
pair that can't match fails the build with an error that names both models:

```text
error[E0277]: `Account` and `Note` cannot relate: the key `i64` cannot match `ObjectId`
```

The key and foreign key fields must be visible where the relation is
declared.

### Why Suprnova diverges

- **Key types checked at build time.** Laravel compares keys when the query
  runs, so a foreign key of the wrong type answers no related documents.
  Suprnova refuses the relation when it compiles.
- **Writes answer the parent.** Laravel's `attach` changes the parent model
  in place. Suprnova's `attach`, `detach`, and `sync` answer the parent as
  stored after the write, so assign it.
- **`BelongsTo` keys follow the model.** Laravel names a `belongsTo` foreign
  key after the relation method. Suprnova names it after the related model,
  `user_id` for `BelongsTo<User>`, as its SQL `BelongsTo` does. Name another
  with `fk`.
- **No existence queries across stores.** `has` and `where_has` render SQL,
  which doesn't reach a collection. Read the keys you need with `pluck` and
  filter with `where_in`.
- **Loaded relations belong to the instance.** A call that reloads a document
  from the server, such as `update` or `refresh`, answers it without the
  relations `with` loaded.

## Queue

Set `QUEUE_DRIVER=mongodb` to keep queued jobs in MongoDB. The boot builds
three stores on the default connection:

- `MongoQueueDriver` over the `jobs` collection.
- `MongoFailedJobStore` over `failed_jobs`, which becomes the failed-job
  store, as `QUEUE_DRIVER=database` makes its table the store.
- `MongoBatchRepository` over `job_batches`, which becomes the batch
  repository unless your bootstrap installed one.

```ini
QUEUE_DRIVER=mongodb
MONGODB_URI="mongodb://127.0.0.1:27017"
MONGODB_DATABASE="shop"
```

Run workers with `queue:work` as for any other driver. The collections need
no migration: each store creates its indexes on its first operation.

A job is one document with Laravel's fields: `queue`, `payload`,
`attempts`, `reserved_at`, `available_at`, and `created_at`, the last three
as epoch seconds. Two fields of Suprnova's own hold the reservation:
`token`, which the worker settles the job with, and `reserved_until`, when
the reservation lapses.

A worker reserves a job with one `findOneAndUpdate`. It picks the earliest
available job on the worker's queues that no live reservation holds, sets
the reservation, and adds 1 to `attempts`. The server applies the update to
one document atomically, so two workers never reserve the same job. A job
whose worker died is reserved again once `reserved_until` passes, and that
delivery counts as an attempt.

`available_at` holds whole seconds. A job due when you push it is
available at once. A delayed job rounds its time up, so a worker never
reserves it early; it can start up to a second late.

`QUEUE_DRIVER=mongodb` uses the default connection and Laravel's
collection names. Each store also takes a connection and a collection of
your choice, for code that drives a store itself, such as a test or a
worker you start with `run_worker`:

```rust
use std::sync::Arc;
use suprnova::{Mongo, MongoBatchRepository, MongoFailedJobStore, MongoQueueDriver};

let reporting = Mongo::connection_named("reporting")?;
let jobs = Arc::new(MongoQueueDriver::with_collection(&reporting, "report_jobs")?);
let failed = MongoFailedJobStore::with_collection(&reporting, "report_failed_jobs")?;
let batches = MongoBatchRepository::new(&reporting);
```

A batch is one document. Each job that settles updates it once, moving
`pending_jobs` and `failed_jobs` with `$inc` and adding the job to
`settled_job_ids`, so jobs that finish at the same moment never lose a
count and a job delivered twice counts once. The `then`, `catch`, and
`finally` callbacks run once: the first worker to set `finished_at` runs
them.

## Cache

Set `CACHE_DRIVER=mongodb` to keep the cache in MongoDB. The boot builds
`MongoCache` on the default connection, over the `cache` collection for
entries and `cache_locks` for locks, with the `CACHE_PREFIX` and
`CACHE_DEFAULT_TTL` of the other drivers.

```ini
CACHE_DRIVER=mongodb
CACHE_PREFIX=shop-cache-
```

The `Cache` facade works as with any driver:

```rust
use std::time::Duration;
use suprnova::Cache;

Cache::put("report:today", &42, Some(Duration::from_secs(60))).await?;
Cache::increment("visits", 1).await?;
let added = Cache::add("slot:9", &"taken", Some(Duration::from_secs(30))).await?;
```

An entry is one document: `_id` (the prefix and the key), `value`,
`expires_at`, and `tags`. A value that is a whole number is stored as a
BSON integer, so `increment` adds to it on the server with `$inc` in one
`findOneAndUpdate`, and two increments at once never lose a step. Any other
value is stored as its JSON text.

Both collections have a TTL index on `expires_at`, which the store creates
on its first operation, so the server removes expired entries and locks.
The server's sweep runs once a minute, so every read also compares
`expires_at` with the time now and never returns an expired entry.

`Cache::add` is one upsert that matches only an expired entry: it inserts
a missing key, replaces an expired one, and fails on a live one, so two
callers never both add. Tags are an array on the entry, and
`Cache::flush_tags` deletes every entry under the store's prefix whose tags
hold one of the tags. A lock is one document whose `_id` is the key: acquiring it is an upsert that
fails while another owner's lock is live, and releasing or refreshing it
checks the owner's token.

To use other collections or another connection, build the store and bind
it in your bootstrap:

```rust
use std::sync::Arc;
use suprnova::{App, CacheConfig, CacheStore, Mongo, MongoCache};

pub async fn register() -> Result<(), suprnova::FrameworkError> {
    Mongo::init().await?;
    let store = MongoCache::with_collections(
        &Mongo::connection()?,
        &CacheConfig::from_env()?,
        "app_cache",
        "app_cache_locks",
    )?;
    App::bind::<dyn CacheStore>(Arc::new(store));
    Ok(())
}
```

## Session

Set `SESSION_DRIVER=mongodb` to keep sessions in MongoDB. The session
middleware then stores them with `MongoSessionDriver`, in the collection
`SESSION_TABLE` names (`sessions` by default), on the MongoDB connection
`SESSION_CONNECTION` names or the default one.

```ini
SESSION_DRIVER=mongodb
SESSION_LIFETIME=120
```

Your bootstrap builds the middleware as it does for the database driver:

```rust
use suprnova::{SessionConfig, SessionMiddleware, global_middleware};

pub async fn register() {
    global_middleware!(SessionMiddleware::install(SessionConfig::from_env()).await);
}
```

The middleware is built before the boot registers the MongoDB connections,
so the driver looks the connection up on each call.

A session is one document: `session_id`, `user_id` (the default guard's
user), `guards` (each other guard signed in, with its user), `payload` (the
session data and the CSRF token), and `last_activity`. The store creates a
unique index on `session_id` on its first operation.

`destroy_for_user` and the other revocations find sessions by `user_id`
and `guards`, and delete them one at a time until none is left, so a
session signed in during the revocation goes too. A session a request
loaded and a revocation then deleted isn't written back. `gc` deletes the
sessions whose last activity is older than the lifetime, and the session
middleware's collector calls it every `SESSION_GC_INTERVAL` seconds.

The two-factor promotion renames the pending session to its new id with
one update of one document, so the old id stops working and the new one
holds the session in the same step.

### Why Suprnova diverges

- **No default URI.** Laravel's configuration falls back to
  `mongodb://localhost:27017` and the `laravel_app` database. Suprnova has
  no fallback: an unset `MONGODB_URI` is an error that names it, so an
  application never writes to a server it wasn't pointed at.
- **A facade of its own.** Laravel reaches MongoDB through
  `DB::connection('mongodb')`. Suprnova's `DB` facade is SQL only, so
  MongoDB has the `Mongo` facade, and its default connection keeps
  Laravel's name, `mongodb`.
- **Configuration in code.** Laravel lists connections and driver options
  in `config/database.php`. Suprnova reads the default connection from the
  environment and takes named connections and pool options from
  `MongoConfig::builder()`.
- **Only the worker that holds a job settles it.** Laravel's database
  queue deletes a finished job by its id, so a worker whose reservation
  lapsed can delete a job another worker now runs. Suprnova's driver keeps
  a `token` and a `reserved_until` beside Laravel's fields, and settles a
  job by its token.
- **A release doesn't spend an attempt.** Laravel counts each reservation
  as an attempt and keeps the count when a job is released. Suprnova gives
  the delivery back, as its other drivers do.
- **Batch settlements count once.** Laravel's batch repository moves the
  counters on every settlement, so a job delivered twice counts twice.
  Suprnova records the settled jobs on the batch and moves the counters in
  the same update, so a redelivery changes nothing. MongoDB's 16 MiB
  document limit bounds a batch at about 300,000 jobs.
- **A chained job's successor is pushed before the acknowledgement.**
  Without a transaction, which a standalone server lacks, the driver can't
  enqueue the successor and drop the finished job in one step. The worker
  pushes first, as it does on Redis, so a crash between the two runs the
  finished job again rather than losing the rest of the chain.
- **Sessions are keyed by a `session_id` field, not `_id`.** A document's
  `_id` can't change, and the two-factor promotion has to give a session a
  new id atomically, so the id is a field with a unique index.

## Next

- [Database: Getting Started](database.md) - the SQL connections beside
  MongoDB
- [Eloquent](eloquent.md) - SQL models
- [Queues](queues.md) - queue drivers
- [Cache](cache.md) - cache stores
- [Session](session.md) - session drivers


# Eloquent ORM

---

<!-- /docs/eloquent -->

# Eloquent API

Suprnova's Eloquent layer gives Laravel developers the API they know,
implemented as a thin shim over SeaORM. Copy code from the Laravel
docs, swap PHP syntax for Rust, add `.await?`, and it runs.

The whole layer is a struct attribute (`#[suprnova::model]`), a trait
(`Model`), and a chainable query builder (`Builder<M>`) - that's it.
Behind the scenes the macro generates a SeaORM `Entity`, `Model`,
`ActiveModel`, and `Column` enum, plus every Eloquent trait impl. The
SeaORM types stay reachable for the rare case the Eloquent surface
doesn't cover (see the [SeaORM escape hatches](#dropping-to-seaorm)).

## Table of contents

- [Quick start](#quick-start)
- [The `#[suprnova::model]` attribute](#the-suprnovamodel-attribute)
- [Model module layout](#model-module-layout)
- [Finding rows](#finding-rows)
- [Creating and updating](#creating-and-updating)
- [Deleting and soft deletes](#deleting-and-soft-deletes)
- [Query builder - dual API](#query-builder---dual-api)
- [Row locking](#row-locking)
- [Transactions](#transactions)
- [Scopes](#scopes)
- [Relationships](#relationships)
- [Eager loading](#eager-loading)
- [Preventing lazy loading](#preventing-lazy-loading)
- [Pagination](#pagination)
- [Chunking and lazy iteration](#chunking-and-lazy-iteration)
- [Collections](#collections)
- [Mass assignment](#mass-assignment)
- [Casts](#casts)
- [Accessors and mutators](#accessors-and-mutators)
- [Timestamps](#timestamps)
- [Observers and lifecycle events](#observers-and-lifecycle-events)
- [Prunable](#prunable)
- [Multi-connection routing](#multi-connection-routing)
- [Replication](#replication)
- [Debugging - dump and dd](#debugging---dump-and-dd)
- [Testing models](#testing-models)
- [Dropping to SeaORM](#dropping-to-seaorm)
- [Migrating from `database::Model`](#migrating-from-databasemodel)
- [DB facade - model-less queries](#db-facade---model-less-queries)
- [Laravel-13 parity - relation-existence + cheap shortcuts](#relation-existence--cheap-shortcuts)

## Quick start

One attribute on a struct turns it into a fully-featured Eloquent
model:

```rust
use chrono::{DateTime, Utc};
use suprnova::{model, Model};

#[model(table = "users")]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
```

Once declared, you can write:

- `User::query()` - start a fluent query builder.
- `User::find(id).await?` - fetch by primary key.
- `User::find_or_fail(id).await?` - same, but errors with `ModelNotFound` on miss.
- `User::all().await?` - every row.
- `User::create(attrs!{ name: "Alice", email: "alice@example.com" }).await?` -
  insert with mass-assignment filtering.
- `User::filter("email", "alice@example.com").first().await?` -
  one row that matches.
- `user.update(attrs!{ name: "Alice B" }).await?` - partial update.
- `user.save().await?` - persist in-memory changes.
- `user.delete().await?` - remove the row.
- `user.refresh().await?` / `user.fresh().await?` / `user.replicate().await?` -
  the rest of the Laravel lifecycle.

The user-facing struct (here `User`) IS the type your handlers and
controllers carry. The macro emits a per-model inner module (`user::`)
with the SeaORM `Entity`, `Column`, `ActiveModel`, and `Model` types
for the cases where you want to drop down to SeaORM directly. The
struct is also registered in an inventory-backed `ModelEntry` so
admin and tooling code can enumerate every model at boot.

## The `#[suprnova::model]` attribute

The single entry point for declaring a model. Every attribute is
optional; the defaults are tuned so a struct with `id` +
`created_at` + `updated_at` works as a Suprnova model with zero
configuration.

### Macro attribute reference

| Attribute | Type | Default | Notes |
|-----------|------|---------|-------|
| `table` | string | snake_case-plural of struct name | Override the table name |
| `primary_key` | string | `"id"` | Override the PK column name |
| `key_type` | type | the primary-key field's type | Optional. The key type comes from the field `primary_key` names; a `key_type` that names another type fails the build |
| `auto_increment` | bool | `true` | Disable for UUID PKs |
| `connection` | string | `"default"` | Multi-connection apps name a non-default connection |
| `fillable` | list of strings | (default = `guarded = ["id"]`) | Mass-assignment allowlist |
| `guarded` | list of strings | `["id"]` when neither set | Mass-assignment denylist (mutually exclusive with `fillable`) |
| `defaults(field = value, ...)` | field expressions | none | Set the values you read on a new instance and save when a create omits them |
| `casts` | map of `field = CastType` | `{}` | Per-column casts |
| `hidden` | list of strings | `[]` | Excluded from `to_json` / `to_array` |
| `visible` | list of strings | (all) | Inclusive variant of `hidden` (mutually exclusive) |
| `appends` | list of strings | `[]` | Accessors to include in serialization |
| `soft_deletes` | flag | `false` | Enable `deleted_at` column + tombstone semantics |
| `soft_deletes_column` | string | `"deleted_at"` | Override the soft-delete column name |
| `timestamps` | flag / bool | `true` when both `created_at` and `updated_at` exist | Disable auto-managed timestamps |
| `created_at` | string | `"created_at"` | Override the column name |
| `updated_at` | string | `"updated_at"` | Override the column name |
| `touches` | list of relation names | `[]` | `BelongsTo` or `MorphTo` relations whose owner row gets its `updated_at` bumped after this model is created, saved, updated, or deleted |
| `mutators` | list of strings | `[]` | Field names whose JSON-fill path routes through a `set_<field>(value)` mutator method |
| `route_key` | string | the primary key | The column a route parameter without a binding field matches (Laravel's `getRouteKeyName()`). A name that is no column of the model fails the build. See [Route model binding](routing.md#route-model-binding) |
| `custom_route_binding` | flag | off | The model implements `RouteBinding` itself; the macro emits none. `suprnova::database::resolve_model_route_binding` stays callable from your impl |

### Full example

```rust
use chrono::{DateTime, Utc};
use serde_json::Value as Json;
use suprnova::{model, AsBool, AsEncrypted, AsJson};

#[model(
    table = "users",
    fillable = ["name", "email", "preferences"],
    casts = {
        active = AsBool,
        preferences = AsJson<Json>,
        api_token = AsEncrypted,
    },
    hidden = ["password", "remember_token", "api_token"],
    appends = ["full_name"],
    soft_deletes,
    timestamps,
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub password: String,
    pub remember_token: Option<String>,
    pub api_token: Option<String>,
    pub active: bool,
    pub preferences: Json,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub deleted_at: Option<DateTime<Utc>>,
}
```

### Function-level macros

Function-level macros work alongside the struct attribute:

- `#[accessor]` on a `fn name(&self) -> T` makes it an Eloquent
  accessor. The model's `to_array()` calls it when `name` is listed
  in `appends = [...]` (and `to_json()` picks it up via the
  `to_array` → string delegation).
- `#[mutator]` on a `fn set_name(&mut self, value: serde_json::Value)`
  makes it an Eloquent mutator. The model's JSON-fill path routes
  through it when `name` is listed in `mutators = [...]`.
- `#[suprnova::scopes(Model)]` on an `impl Model { ... }` block:
  every method whose signature is
  `fn name(query: Builder<Self>[, args…]) -> Builder<Self>` becomes
  both a chainable `.scope_name(args)` on `Builder<Self>` and a
  `Model::scope_name(args)` shortcut. There is no function-level
  `#[scope]` form - scopes are declared per impl-block.
- Global scopes are a runtime registration via the `GlobalScope`
  trait, registered with `ScopeRegistry::register::<M, _>(scope)`. There is no
  function-level `#[global_scope]` macro - see
  [Macros](macros.md#suprnovascopesmodel) for the full pattern.
- `#[prunable]` on `impl Prunable for T { ... }` registers the
  pruner via inventory so `model:prune` finds it.

## Model module layout

`#[suprnova::model]` keeps your user-facing struct (e.g. `Post`) at
parent scope and emits a sibling `pub mod` named after the struct in
snake_case (`post`). That inner module is where the SeaORM types live.

For a model declared at `app/src/models/posts.rs`:

```rust
use chrono::{DateTime, Utc};
use suprnova::model;

#[model(table = "posts", fillable = ["title", "body"], timestamps)]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub body: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

// Convention: re-export the SeaORM types the macro emits inside the
// inner module so call sites can use the unprefixed names. Suprnova's
// own dogfood models all carry this line (see `app/src/models/users.rs`,
// `app/src/models/posts.rs`, etc.).
pub use post::{ActiveModel, Column, Entity};
```

You now have these items reachable from `crate::models::posts`:

| Path | What it is |
|------|-----------|
| `crate::models::posts::Post` | Your user-facing struct - the Eloquent model |
| `crate::models::posts::post::Entity` | SeaORM `EntityTrait` impl for the `posts` table |
| `crate::models::posts::post::Column` | SeaORM `Column` enum (one variant per column) |
| `crate::models::posts::post::ActiveModel` | SeaORM `ActiveModel` for insert/update |
| `crate::models::posts::post::Model` | SeaORM-shape row (storage-typed columns) |
| `crate::models::posts::{Entity, Column, ActiveModel}` | The `pub use` convention above; not auto-emitted |

Two things to know about the inner module's `Model`:

1. It is the **SeaORM-shape** row, not your `Post` struct. Cast columns
   carry their `Storage` type here (e.g. `bool` becomes the underlying
   integer), and the `__eager` / `__pivot` runtime slots from your
   struct are absent.
2. `From<post::Model> for Post` and `From<Post> for post::Model` bridge
   the two shapes. See [Dropping to SeaORM](#dropping-to-seaorm) for the
   round-trip pattern.

`Model` is intentionally **not** part of the conventional parent
re-export - the user-facing `Post` already occupies the `Post` name at
parent scope, and `post::Model` is a separate type that callers reach
through `post::Model` (or `From` conversion) when they need the inner
shape.

### When to reach into the inner module

The Eloquent surface (`Model` trait + `Builder<M>`) covers the vast
majority of queries. Reach into `post::*` when you need SeaORM-only
features:

- **Raw query construction** with SeaORM's `EntityTrait::find()` chain
  when Eloquent doesn't expose the helper you want.
- **Custom join logic** - building `JoinType::*` joins explicitly via
  `QuerySelect::join()` for a relation Eloquent's `with(...)` doesn't
  model.
- **SeaORM-native subqueries** through `Entity::find().select_only()`.
- **Plain `ActiveModel` mutation** for the rare case you want to bypass
  the Eloquent lifecycle (no observers, no auto-timestamps).

```rust
// Common case - Column re-exported at parent module level via the
// `pub use post::{...}` convention above.
use crate::models::posts::Column;

let drafts = Post::query()
    .db_where(Column::Status, "draft")
    .get()
    .await?;

// Power-user case - reach into the inner module for the SeaORM Entity
// directly. This is what the parent `pub use` does not surface.
use crate::models::posts::post;
use suprnova::sea_orm::{ColumnTrait, EntityTrait, QueryFilter};

let db = suprnova::DB::connection()?;
let rows: Vec<post::Model> = post::Entity::find()
    .filter(post::Column::Status.eq("published"))
    .all(db.inner())
    .await?;

// Bridge back to the Eloquent shape when the caller wants it.
let posts: Vec<Post> = rows.into_iter().map(Post::from).collect();
```

If you find yourself reaching into the inner module routinely for the
same operation, that's a signal Eloquent is missing a helper - open an
issue, or add the helper to the `Model` / `Builder` surface.

## Finding rows

```php
// Laravel
$user = User::find(1);
$user = User::findOrFail(1);          // throws on missing
$users = User::findMany([1, 2, 3]);
```

```rust
// Suprnova
let user: Option<User> = User::find(1).await?;
let user: User = User::find_or_fail(1).await?;
let users: Vec<User> = User::find_many([1, 2, 3]).await?;
```

`find_or_fail` returns `FrameworkError::ModelNotFound` (HTTP 404 when
bubbled to a controller).

### `first_or_create` / `update_or_create` / `first_or_new` / `first_or`

```php
// Laravel
$user = User::firstOrCreate(
    ['email' => 'alice@example.com'],
    ['name' => 'Alice'],
);
$user = User::updateOrCreate(
    ['email' => 'alice@example.com'],
    ['name' => 'Alice Updated'],
);
$user = User::firstOrNew(['email' => 'alice@example.com']);  // unsaved
```

```rust
// Suprnova
let user = User::first_or_create(
    attrs! { email: "alice@example.com" },          // lookup keys
    attrs! { name: "Alice" },                       // extras on create
).await?;

let user = User::update_or_create(
    attrs! { email: "alice@example.com" },
    attrs! { name: "Alice Updated" },
).await?;

let user = User::first_or_new(
    attrs! { email: "alice@example.com" },
).await?;   // returns an unsaved User; caller inserts it explicitly
let user = user.persist().await?;   // `use suprnova::Persistable;`
```

Lookup keys go in the first map; extra fields applied on the
create-path go in the second map. Returning an unsaved model via
`first_or_new` lets the caller mutate it further before inserting it
with `persist().await?`, which fires `creating` and `created` and
returns the saved model with the key the database assigned. When
`first_or_new` finds a row, the model it returns is loaded, and `save`
updates it.

### Why Suprnova diverges

Laravel's `save` inserts a model that does not exist yet and writes the
new key into it. Suprnova's `save` borrows the model, so it cannot hand
the new key back. A model built in the process whose key still holds its
reset value - a new model from `first_or_new` or `find_or_new`, or a
replica - has no row to update, so `save` refuses it with an error that
names `persist`. `persist` consumes the model and returns the inserted
one, key included.

## Creating and updating

### Create

```php
// Laravel
$user = User::create([
    'name' => 'Alice',
    'email' => 'alice@example.com',
]);
```

```rust
// Suprnova
let user = User::create(attrs! {
    name: "Alice",
    email: "alice@example.com",
}).await?;
```

`attrs!` is a macro that produces an `Attrs` value (a typed JSON
map). Pure JSON also works -
`User::create(serde_json::json!({"name": "Alice", "email": "..."}))`.
The `Fillable` filter runs inside `create`; non-fillable fields are
silently dropped, matching Laravel's behaviour.

### Declared defaults

Declare `defaults(field = value, ...)` to give new instances initial values:

```rust
use suprnova::{Model, attrs, model};

#[model(
    table = "posts",
    fillable = ["title", "status", "votes"],
    defaults(status = "draft", votes = 0),
)]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub status: String,
    pub votes: i64,
}

let draft = Post::new();
assert_eq!(draft.status, "draft");
let draft = Post::create(attrs! { title: "First" }).await?;
let live = Post::create(attrs! { title: "Second", status: "live" }).await?;
```

You read declared defaults before saving a new instance. A partial `create`
uses every declared default that your filtered attributes omit, before
creation events and the insert. Your supplied attributes win. The same
rules apply to `create_with_tx` and unsaved instances from `first_or_new`.

You supply values convertible into the declared field types, so `"draft"`
works for a `String`. You name each column at most once. An unknown column
or a value of the wrong type fails the build. Your defaults are trusted
model values; your caller's attributes still pass through the fillable
filter. A model without the declaration keeps its existing construction
and insert behavior.

### Save / update

```php
// Laravel
$user->name = 'Alice B';
$user->save();

$user->update(['name' => 'Alice B']);
```

```rust
// Suprnova
user.name = "Alice B".into();
user.save().await?;

user.update(attrs! { name: "Alice B" }).await?;
```

You call `save()` after changing a loaded model. It compares your values
with the original values kept in memory, without re-reading the row. A
clean save issues no `UPDATE` and fires neither `Updating` nor `Updated`;
`Saving` and `Saved` still fire. A `Saving` listener can make the model
dirty by changing its attributes. A dirty save writes changed columns and
updates its timestamp.

You use `update(attrs)` to apply a partial attribute map, with the
Fillable filter and declared mutators, before writing.

### Changes after a save

After a save, a model reports which attributes that save changed. While
the save's `updated` and `saved` observers run, the original values are
still the ones loaded before the save; once the save returns, they are the
saved ones:

```php
// Laravel
$user->is_admin = true;
$user->save();

$user->wasChanged('is_admin');        // true
$user->wasChanged(['name', 'email']); // false
$user->getChanges();                  // ['is_admin' => 1]
$user->getOriginal('is_admin');       // true
```

```rust
// Suprnova
use suprnova::Model;

user.is_admin = true;
user.save().await?;

user.was_changed("is_admin");             // true
user.was_changed_any(&["name", "email"]); // false
user.was_changed_any(&[]);                // true: the save changed something
user.get_changes();                       // Attrs { "is_admin": 1 }
user.get_original("is_admin")?;           // Some(true): the saved value
user.get_raw_original("is_admin");        // Some(1), as stored
user.get_previous("is_admin");            // Some(0): before the change
```

An observer reads the value from before the save, which is how an audit
trail records both sides of a change:

```rust
use async_trait::async_trait;
use suprnova::eloquent::observers::Observer;
use suprnova::{FrameworkError, Model};

pub struct AdminAudit;

#[suprnova::observer(User)]
#[async_trait]
impl Observer<User> for AdminAudit {
    async fn updated(&self, _previous: &User, user: &User) -> Result<(), FrameworkError> {
        if user.was_changed("is_admin") {
            let before = user.get_raw_original("is_admin"); // Some(0)
            tracing::info!(user_id = user.id, ?before, after = user.is_admin, "admin flag changed");
        }
        Ok(())
    }
}
```

The rules follow Laravel's `save`:

- A column counts as changed when the value the database stores after the
  save differs from the value the model held before it. Writing the same
  value back is not a change. A column that a `Saving` listener or the
  timestamps rewrote is one, so a model with timestamps also reports
  `updated_at`. An encrypted column stores a new ciphertext on every save,
  so it is compared by its decrypted value instead: it counts as changed
  only when that value changed.
- `get_previous(attribute)` returns the stored value before the last
  change for that attribute. You get `None` for an unchanged or unknown
  attribute. A clean or failed save keeps this record.
- `get_changes` and `get_raw_original` return stored values, before casts,
  as Laravel does. `get_original` reads the value through the model's casts
  and returns an error only when the stored value no longer decodes.
- The record describes the last save that changed something. A later save
  that changes something replaces it. A save that changes nothing, or a
  save that fails, leaves it in place.
- `save`, `update`, `save_with_tx`, and `update_with_tx` record a save. A
  model you `create` reports no changes, and a model you load reports none
  until you save it. The original is the row as the model last read or
  saved it, whatever you change in memory. To answer this, every model a
  query loads keeps a copy of its stored row beside its fields, so a large
  result takes more memory than the fields alone. A clone keeps the record;
  `replicate` builds a new model without one.
- A model you build in memory and save without reading it first has no
  loaded values to compare with: every column counts as changed, and
  `get_original` returns `None` until that save returns. Such a model
  needs a key a row already holds: while its key holds the reset value,
  as a replica's and a new `first_or_new` model's do, `save` refuses it
  and `persist` inserts it.

### Why Suprnova diverges

A save that changes nothing runs no `UPDATE` and fires neither `updating`
nor `updated`, as in Laravel, while `saving` and `saved` still fire; the
previous save's change record stays in place. `refresh` replaces the model
with a fresh read, so it also clears the record, where Laravel's `refresh`
keeps `getChanges`.

### Increment / decrement

```php
// Laravel
$user->increment('login_count');
$user->increment('login_count', 5);
$user->decrement('credits', 10);
User::where('plan', 'free')->increment('quota_reset_count');
```

```rust
// Suprnova
user.increment("login_count", 1).await?;
user.increment("login_count", 5).await?;
user.decrement("credits", 10).await?;
User::filter("plan", "free").increment("quota_reset_count", 1).await?;
```

`increment` / `decrement` emit `UPDATE table SET col = col + N WHERE
...` SQL - atomic against concurrent updates, no read-modify-write
race. Available both on a fetched model instance (uses the row's PK
in the WHERE clause) and as a Builder terminal (uses the chain's
WHERE clauses).

### Fresh / refresh / replicate

```php
// Laravel
$user->refresh();                          // reload from DB
$user->refreshForUpdate();                 // reload under a row lock
$copy = $user->fresh();                    // fetch + return copy
$replica = $user->replicate();             // unsaved clone with fresh PK
$replica = $user->replicate(['email']);    // skip a field
```

```rust
// Suprnova
user.refresh().await?;
user.refresh_for_update().await?;
let copy: User = user.fresh().await?;
let replica: User = user.replicate().await?;
let replica: User = user.replicate_except(["email"]).await?;
```

`refresh` mutates in place; `fresh` returns a separately-fetched
copy. `refresh_for_update` is `refresh` under a `SELECT ... FOR UPDATE`
row lock - use it inside a transaction when you need the row's current
values and the exclusive lock in one statement. Unlike `refresh`,
`refresh_for_update` bypasses every registered global scope AND the
`#[model(soft_deletes)]` filter: it reloads a trashed row too, with
`deleted_at` coming back set. The reload is a lookup by primary key
under a lock - scoping it the way an ordinary read is scoped would
hand admin tooling and cross-tenant callers a false not-found for a
row they already hold a reference to. `replicate` builds an
in-memory clone with the PK and the timestamps reset
(`Default::default()` for each type). Insert it with
`replica.persist().await?` (the `Persistable` trait), which stamps
`created_at` and `updated_at` the way `create` does. `replica.save()`
refuses it: the replica has no row yet, and its reset key would name
another row.

`refresh` and `refresh_for_update` both return an error when the row no
longer exists, rather than leaving the model holding stale values.
SQLite has no row-level locking, so `refresh_for_update` reloads without
a lock there - see [Row locking](#row-locking).

### Replicating event

`replicate` and `replicate_except` fire the per-model
`Replicating { source, replica }` event after constructing the
in-memory clone and BEFORE returning it. The `replica` field is an
`Arc<tokio::sync::Mutex<Self>>` so listeners can mutate the replica
before the caller sees it - useful for prefixing titles with
`(copy)`, clearing flags, resetting derived columns, etc.

```rust
use suprnova::events::{EventFacade, Listener};
use async_trait::async_trait;

pub struct PrefixTitle;

#[async_trait]
impl Listener<post::events::Replicating> for PrefixTitle {
    async fn handle(&self, e: &post::events::Replicating)
        -> Result<(), FrameworkError>
    {
        let mut replica = e.replica.lock().await;
        replica.title = format!("(copy) {}", replica.title);
        Ok(())
    }
}

// Wire it up once at boot:
EventFacade::listen::<post::events::Replicating, _>(
    std::sync::Arc::new(PrefixTitle)
).await;
```

### Cross-type replication

```rust
let replica: UserDraft = user.replicate_into().await?;  // cross-type clone
```

A Suprnova divergence - Laravel can't do this because PHP doesn't
have types. Useful when promoting a draft model into a final one
or vice-versa.

`replicate_into<T>` does NOT fire `Replicating` (the event carries
`Arc<Mutex<Self>>`, so a listener on the source type couldn't mutate
the cross-type replica anyway). Callers wanting per-T setup should
run it on the returned `T` before calling `persist` - the normal
`Creating` / `Saving` / `Created` / `Saved` chain still fires inside
`persist`.

## Deleting and soft deletes

### Soft deletes flag

Add `soft_deletes` to the macro attribute and a
`deleted_at: Option<DateTime<Utc>>` column to the struct:

```rust
#[model(table = "users", soft_deletes, timestamps)]
pub struct User {
    pub id: i64,
    pub email: String,
    pub deleted_at: Option<DateTime<Utc>>,
    // ...
}
```

### Lifecycle

```rust
user.delete().await?;             // UPDATE: sets deleted_at (and updated_at) = NOW()
user.trashed();                   // -> true
let trashed = User::with_trashed().find(user.id).await?.unwrap();
trashed.restore().await?;         // UPDATE: sets deleted_at = NULL

let only_dead = User::only_trashed().get().await?;
let all_including_dead = User::with_trashed().get().await?;

user.force_delete().await?;       // actual DELETE
```

`delete()` sets `updated_at` along with `deleted_at` when the model manages
timestamps, as Laravel's soft delete does. The mass form follows the row
form. `delete_all()` on a builder soft-deletes every row the query matches
with one `UPDATE`, and it sets `updated_at` too. `force_delete_all()` removes the rows for good.
Neither fires per-row events. See
[Mass mutation](#mass-mutation---update_all--delete_all--upsert--_each).

```rust
User::query().filter("active", false).delete_all().await?;        // soft delete
User::only_trashed().force_delete_all().await?;                   // actual DELETE
```

### Default scope

When `soft_deletes` is set, the macro overrides `Model::query()` so
default reads filter out trashed rows automatically. `with_trashed()`
and `only_trashed()` opt back in. Concretely: `User::find(id)`
skips trashed rows; `User::with_trashed().find(id)` finds them.

## Query builder - dual API

`Builder<M>` is the chainable query type returned by `User::query()`,
`User::filter(...)`, `User::db_where(...)`, and every other static
method that doesn't terminate the chain.

### Naming note: dual API

`where` is a Rust keyword, so the bare-equality where method can't
share Laravel's name. Rather than pick a winner, every where-shape
method ships under **both** a Rust-idiomatic name (`filter`,
`filter_in`, `filter_null`, …) and a Laravel-shape name (`db_where`,
`where_in`, `where_null`, …). They're aliases over one canonical
implementation - pick whichever your muscle memory matches.

```rust
// Rust dev:
User::query().filter("active", true).filter_in("role", ["admin"]).get().await?;

// Laravel dev:
User::db_where("active", true).where_in("role", ["admin"]).get().await?;

// Same query. Same result. Different muscle memory.
```

### Where shortcuts

```php
// Laravel
$users = User::where('email', $email)->get();
$users = User::where('age', '>=', 18)->get();
$users = User::where('email', 'like', '%@example.com')->get();
```

```rust
// Suprnova - pick either family; both compile, both documented.

// Rust-shape (filter family):
let users = User::query().filter("email", &email).get().await?;
let users = User::query().filter_op("age", ">=", 18).get().await?;
let users = User::query().filter_like("email", "%@example.com").get().await?;

// Laravel-shape (db_where / where_* family):
let users = User::db_where("email", &email).get().await?;
let users = User::query().db_where_op("age", ">=", 18).get().await?;
let users = User::query().where_like("email", "%@example.com").get().await?;
```

### Where variants

Every row has two equivalent Suprnova forms - Rust-shape (`filter*`)
and Laravel-shape (`db_where` / `where_*`). Both call the same
canonical implementation; both are tagged with `#[doc(alias = "...")]`
so rustdoc search finds either.

| Laravel | Suprnova (Rust-shape) | Suprnova (Laravel-shape) | Notes |
|---------|----------------------|--------------------------|-------|
| `->where(col, val)` | `.filter(col, val)` | `.db_where(col, val)` | Equality |
| `->where(col, op, val)` | `.filter_op(col, op, val)` | `.db_where_op(col, op, val)` | Arbitrary operator |
| `->orWhere(...)` | `.or_filter(...)` | `.or_where(...)` | |
| `->orWhereKey(id)` | `.or_filter_key(id)` | `.or_where_key(id)` | PK filter as a disjunct |
| `->orWhereKeyNot(id)` | `.or_filter_key_not(id)` | `.or_where_key_not(id)` | Negated PK filter as a disjunct |
| `->whereNot(col, val)` | `.filter_not(col, val)` | `.where_not(col, val)` | |
| `->whereIn(col, vals)` | `.filter_in(col, vals)` | `.where_in(col, vals)` | A list or a `DB::table` subquery |
| `->whereNotIn(col, vals)` | `.filter_not_in(col, vals)` | `.where_not_in(col, vals)` | A list or a subquery |
| `->orWhereIn(col, vals)` | `.or_filter_in(col, vals)` | `.or_where_in(col, vals)` | A list or a subquery |
| `->orWhereNotIn(col, vals)` | `.or_filter_not_in(col, vals)` | `.or_where_not_in(col, vals)` | A list or a subquery |
| `->whereAny(cols, op, v)` | `.filter_any(cols, op, v)` | `.where_any(cols, op, v)` | `(c1 op v OR c2 op v ...)` |
| `->orWhereAny(cols, op, v)` | `.or_filter_any(cols, op, v)` | `.or_where_any(cols, op, v)` | |
| `->whereAll(cols, op, v)` | `.filter_all(cols, op, v)` | `.where_all(cols, op, v)` | `(c1 op v AND c2 op v ...)` |
| `->orWhereAll(cols, op, v)` | `.or_filter_all(cols, op, v)` | `.or_where_all(cols, op, v)` | |
| `->whereNone(cols, op, v)` | `.filter_none(cols, op, v)` | `.where_none(cols, op, v)` | `NOT (c1 op v OR c2 op v ...)` |
| `->orWhereNone(cols, op, v)` | `.or_filter_none(cols, op, v)` | `.or_where_none(cols, op, v)` | |
| `->whereBetween(col, [a, b])` | `.filter_between(col, a..=b)` | `.where_between(col, a..=b)` | Rust range |
| `->whereNotBetween(col, [a, b])` | `.filter_not_between(col, a..=b)` | `.where_not_between(col, a..=b)` | |
| `->whereNull(col)` | `.filter_null(col)` | `.where_null(col)` | |
| `->whereNotNull(col)` | `.filter_not_null(col)` | `.where_not_null(col)` | |
| `->orWhereNull(col)` | `.or_filter_null(col)` | `.or_where_null(col)` | |
| `->orWhereNotNull(col)` | `.or_filter_not_null(col)` | `.or_where_not_null(col)` | |
| `->whereDate(col, '2026-05-19')` | `.filter_date(col, NaiveDate)` | `.where_date(col, NaiveDate)` | |
| `->whereMonth(col, 5)` | `.filter_month(col, 5)` | `.where_month(col, 5)` | |
| `->whereDay(col, 19)` | `.filter_day(col, 19)` | `.where_day(col, 19)` | |
| `->whereYear(col, 2026)` | `.filter_year(col, 2026)` | `.where_year(col, 2026)` | |
| `->whereTime(col, '12:30')` | `.filter_time(col, NaiveTime)` | `.where_time(col, NaiveTime)` | |
| `->whereLike(col, pattern)` | `.filter_like(col, pattern)` | `.where_like(col, pattern)` | |
| `->whereNotLike(col, pattern)` | `.filter_not_like(col, pattern)` | `.where_not_like(col, pattern)` | |
| `->whereBinary(col, val)` | `.filter_binary(col, val)` | `.where_binary(col, val)` | Byte-exact; MySQL and MariaDB only |
| `->orWhereBinary(col, val)` | `.or_filter_binary(col, val)` | `.or_where_binary(col, val)` | |
| `->whereNotBinary(col, val)` | `.filter_not_binary(col, val)` | `.where_not_binary(col, val)` | |
| `->orWhereNotBinary(col, val)` | `.or_filter_not_binary(col, val)` | `.or_where_not_binary(col, val)` | |
| `->whereJsonContains(col, v)` | `.filter_json_contains(col, v)` | `.where_json_contains(col, v)` | Backend-dispatched |
| `->whereJsonLength(col, op, n)` | `.filter_json_length(col, op, n)` | `.where_json_length(col, op, n)` | |
| `->whereColumn(a, b)` | `.filter_column(a, b)` | `.where_column(a, b)` | Column-to-column compare |
| `->whereExists(query)` | `.filter_exists(query)` | `.where_exists(query)` | A `DB::table` subquery |
| `->whereNotExists(query)` | `.filter_not_exists(query)` | `.where_not_exists(query)` | |
| `->whereHas(rel, closure)` | `.filter_has(rel, fn)` | `.where_has(rel, fn)` | Relation predicate (10B) |
| `->whereDoesntHave(rel)` | `.filter_doesnt_have(rel)` | `.where_doesnt_have(rel)` | (10B) |
| `->whereRelation(rel, col, op, v)` | `.filter_relation(...)` | `.where_relation(...)` | (10B) |
| `->whereRaw(sql, bindings)` | `.filter_raw(sql, bindings)` | `.where_raw(sql, bindings)` | |
| `->orWhereRaw(sql, bindings)` | `.or_filter_raw(sql, bindings)` | `.or_where_raw(sql, bindings)` | |

Every `or_*` method adds a flat `OR` condition, so
`r#where(a).or_where(b).r#where(c)` means `a OR b AND c`. You use
`r#where(column, value)` or `db_where(column, value)` for equality, and
`filter_op` or `or_where_op` for an explicit operator. A null equality
value compiles to `IS NULL`. Global scopes keep your complete condition
list in a group when it contains an `OR`.

The grouped helpers keep their comparisons in parentheses: this query never
returns a user whose `active` is false, and the model's soft-delete
filter still applies:

```rust
// WHERE deleted_at IS NULL AND active = ? AND (is_admin = ? OR is_staff = ?)
let staff = User::query()
    .filter("active", true)
    .where_any(["is_admin", "is_staff"], "=", true)
    .get()
    .await?;
```

An empty column list adds no condition. `where_in` and its siblings
take another `DB::table` builder as a subquery, and so do
`where_exists` and `where_not_exists`, whose subquery can refer to the
model's table through `where_column`:

```rust
use suprnova::DB;

let booked = Room::query()
    .where_in("id", DB::table("slots").select(["room_id"]).filter("day", "mon"))
    .get()
    .await?;

let authors = User::query()
    .where_exists(
        DB::table("posts")
            .select_raw("1")
            .where_column("posts.author_id", "users.id"),
    )
    .get()
    .await?;
```

A subquery's values are bound parameters in their place in the
statement. For a declared relation, `has` and `where_has` build the
`EXISTS` subquery for you. The full subquery and `OR` rules are in
[Query Builder](queries.md#subqueries).

The `binary` family compares raw bytes instead of matching under the
column's collation. MySQL and MariaDB emit `col = binary ?`; Postgres
and SQLite have no equivalent operator, so a terminal on those backends
returns an error when the statement renders rather than falling back to
a collation-dependent `=`. See [Byte-exact comparison](queries.md#byte-exact-comparison).

Bound raw predicates use portable `?` markers on SQLite, MySQL, and PostgreSQL:

```rust
let rows = User::query()
    .filter("active", true)
    .filter_raw(
        "score >= ? AND role = ?",
        vec![serde_json::json!(80), serde_json::json!("admin")],
    )
    .get()
    .await?;
```

On PostgreSQL, Suprnova rebases those markers after earlier query bindings, so
the example renders `$1` for `active` and `$2`/`$3` for the raw predicate. Use
`??` for a literal question-mark operator in a bound raw fragment, such as
`"payload ?? 'enabled' AND status = ?"`. Existing `$N` fragments remain
accepted, but portable markers avoid coupling call sites to query position.
Mixed marker styles and marker/binding count mismatches are rejected before
database I/O. As with every raw expression, the SQL text must be trusted;
untrusted values belong only in the bindings vector.

### Ordering

```php
$users = User::orderBy('name', 'asc')->get();
$users = User::orderByDesc('created_at')->get();
$users = User::latest()->get();        // shortcut: orderBy(created_at, desc)
$users = User::oldest()->get();        // shortcut: orderBy(created_at, asc)
$users = User::inRandomOrder()->get();
```

```rust
let users = User::query().order_by("name", Direction::Asc).get().await?;
let users = User::query().order_by_desc("created_at").get().await?;
let users = User::latest().get().await?;
let users = User::oldest().get().await?;
let users = User::query().in_random_order().get().await?;
```

`Direction::Asc` / `Direction::Desc` is the Suprnova enum
re-exported from SeaORM.

`reorder()` drops every ordering set so far, and `reorder_by(col, dir)`
drops them and orders by `col` instead. Orderings a global scope adds
when the query runs stay, as in Laravel:

```php
$users = User::latest()->reorder('name')->get();
```

```rust
let users = User::latest().reorder_by("name", Direction::Asc).get().await?;
```

#### Ordering by an explicit sequence

`in_order_of` sorts rows into the order you list. Anything whose value
is not in the list sorts after everything that is.

```php
$users = User::inOrderOf('role', ['admin', 'member', 'guest'])->get();
```

```rust
let users = User::query()
    .in_order_of("role", ["admin", "member", "guest"])
    .get()
    .await?;
```

Suprnova renders this as a bound `CASE` expression, so the values are
parameters and are safe to take from request data:

```sql
ORDER BY CASE WHEN role = ? THEN 0 WHEN role = ? THEN 1 WHEN role = ? THEN 2 ELSE 3 END
```

The column name is an SQL identifier, not a parameter. Hardcode it or
pick it from an allowlist, the same as every other column argument. An
empty value list adds no ordering at all, so you can build the sequence
conditionally without special-casing the empty case.

For a column that uses the `AsEnum<E>` cast, pass each variant through
`as_ref()`. That is the exact string the cast stores:

```rust
let users = User::query()
    .in_order_of("role", [Role::Admin.as_ref(), Role::Member.as_ref()])
    .get()
    .await?;
```

`in_order_of` ships on the typed `Builder<M>` surface. The model-less
`DB::table(...)` builder orders by column and direction only.

### Grouping + having

```php
$rows = User::groupBy('role')->having('count(*)', '>', 5)->get();
```

```rust
let rows = User::query()
    .group_by("role")
    .having_op("count(*)", ">", 5)
    .get()
    .await?;
```

### Limit / offset

```php
$users = User::limit(10)->offset(20)->get();
$users = User::take(10)->skip(20)->get();   // aliases
```

```rust
let users = User::query().limit(10).offset(20).get().await?;
let users = User::query().take(10).skip(20).get().await?;
```

### Select / add_select / select_raw

```rust
let users = User::query().select(["id", "name", "email"]).get().await?;
let users = User::query().select("name").add_select("email").get().await?;
let rows  = User::query().select_raw("count(*) as total, role")
    .group_by("role")
    .get_raw()
    .await?;
```

`get_raw()` returns the raw column-shape result for `select_raw`
cases where the columns don't match the model schema; `get()`
returns `Vec<User>` and requires the selected columns to fill the
model struct.

### Distinct

```rust
let emails: Vec<String> = User::query().distinct().pluck("email").await?;
```

### Aggregates

```rust
let count   = User::count().await?;
let count   = User::filter("active", true).count().await?;
let sum     = User::sum::<f64>("balance").await?;
let visits  = Page::sum::<u64>("views").await?;
let avg     = Order::avg::<f64>("total").await?;
let exact   = Order::avg::<Decimal>("total").await?;
let min     = Order::min::<DateTime<Utc>>("created_at").await?;
let max     = Order::max::<DateTime<Utc>>("created_at").await?;
let exists  = User::filter("email", &email).exists().await?;
let missing = User::filter("email", &email).doesnt_exist().await?;
```

`count` returns an `i64`. `sum`, `avg`, `min` and `max` take the type to
read as a type parameter; for `avg` it is `f64` or `rust_decimal::Decimal`
(the `AvgValue` trait). Suprnova aliases generated
aggregate expressions internally so the same typed result is decoded on
PostgreSQL, MySQL, and SQLite. `sum` and `avg` return zero for an empty
match set, while `min` and `max` return `None`. The same holds when no row
comes back at all - an offset skips the aggregate's one row, as
`skip(10).count()` does, or a grouped query has no group: `count`, `sum`
and `avg` return zero and `min` and `max` return `None`, as Laravel's
`count`, `sum`, `min` and `max` do. An incompatible requested
Rust type or missing result column is a database error; it is never
converted into a plausible zero or `None`.

The database chooses the type of a sum or an average: PostgreSQL answers
`numeric` for the sum of a `bigint` column and for any average of
integers, MySQL answers `DECIMAL`, and SQLite answers an integer or a
real. `sum` and `avg` read whichever arrives. An integer type such as
`i64` or `u64` takes a sum exactly, and a sum with a fraction, or outside
the type's range, is an error rather than a truncated value. `Decimal`
takes a sum or an average exactly, so the average of a `DECIMAL` money
column keeps every digit, and a value it can't hold is an error. `f64`
takes the nearest value. SQLite has no exact decimal type: it stores a
`DECIMAL` column as a real, and `Decimal` reads that real.

### Terminals

```rust
let users:  Vec<User>          = User::all().await?;
let first:  Option<User>       = User::first().await?;
let user:   User               = User::first_or_fail().await?;
let value:  Option<String>     = User::filter("...").value("email").await?;
let emails: Vec<String>        = User::pluck::<String>("email").await?;
let keyed:  HashMap<i64, String> = User::pluck_keyed::<i64, String>("id", "name").await?;
let ids:    Vec<i64>           = User::query().model_keys().await?;
let sql:    String             = User::filter("...").to_sql();
```

`value`, `pluck` and `pluck_keyed` skip a NULL: `value` returns `None`
and `pluck` leaves the row out. A value that doesn't read as the type you
name is an error that names the column, rather than a missing row. These
terminals, the aggregates and `DB::scalar` read `u64` and `Option<u64>` on
every database, as a model's `u64` field does: on Postgres and SQLite a
negative value fails the read. A read by a `u64` above `i64::MAX` answers
what the database holds. On Postgres a signed integer column holds only
integers, so no row matches and the query gets its answer without
sending the value: `find` returns `None`, `find_many` skips it, and in a
filter `=`, `>`, `>=` and `IN` match no row, while `!=`, `<`, `<=` and
`NOT IN` match every row whose column is not NULL. SQLite compares the
value's digits, as it does a literal, because an INTEGER column there can
hold a REAL above `i64::MAX` that raw SQL or an older write left. MySQL
compares the unsigned number.

The same holds for a column of a narrower integer field such as `i64` or
`i32`, which can't hold such a value on any database, and a mass update
that writes one to it is refused on Postgres and SQLite before anything is
sent. A column the model doesn't know, such as a joined table's column,
compares as the number on every database, as with `DB::table`. A mass
write (`update_all`, `upsert`) to a field that is neither an integer nor
text, such as a decimal, also takes the value as `DB::table` does: a
numeric column on Postgres or MySQL stores it exactly, and SQLite refuses
it for a column of INTEGER or NUMERIC affinity, which would store a
rounded REAL.

`to_sql` returns the parameterised SQL the next terminal would emit -
useful for debugging or building views. The bindings are
accessible via `.to_sql_with_bindings() -> (String, Vec<Value>)`.

`model_keys` is the key-only terminal: it projects the **qualified**
primary key (`users.id`) and never hydrates a model, so a "which rows
matched?" question costs one column instead of a full row per match.
The qualification is what lets it survive a query that joins another
table carrying its own `id`. Any `select(...)` already on the builder is
discarded - the caller asked for keys.

### Joins

`join`, `left_join`, `right_join`, and `cross_join` work as they do on
the `DB::table` builder, along with the closure forms (`join_with`,
`left_join_with`, `right_join_with`, `cross_join_with`) and the subquery joins (`join_sub`,
`left_join_sub`, `join_sub_with`, `left_join_sub_with`). See
[Query Builder - Joins](queries.md#joins) for the conditions a join
takes.

```php
$posts = Post::join('users', 'users.id', '=', 'posts.author_id')
    ->where('users.active', true)
    ->get();
```

```rust
let posts = Post::query()
    .join("users", "users.id", "=", "posts.author_id")
    .filter("users.active", true)
    .get()
    .await?;
```

Without a `select`, a model query with a join selects only the model's
own columns (`"posts".*`), so the joined table's `id`, `name`, or
`created_at` never lands in the model. Call `select` to choose the
columns yourself; `select(["posts.*"])` is the default spelled out.
Qualify a column that both tables carry, such as `users.active` above.
On a model that soft-deletes, the soft-delete filter names the model's
table once the query joins another, so a joined table with its own
`deleted_at` doesn't make the column ambiguous. The joined table's own
soft-delete filter isn't applied, as in Laravel.

`count` and `paginate` count the joined rows. You use `update` or
`update_all` to update matching base rows, and `delete` or `delete_all`
to delete them. On a soft-delete model, deletion writes its tombstone;
`force_delete_all` removes the rows. Every join and predicate still
constrains these writes. `increment_each` still refuses joins.

You compare two columns with `where_column(a, b)` for equality or
`where_column_op(a, op, b)` for another allowed operator.

### Unions

```rust
let first  = User::filter("active", true);
let second = User::filter("role", "admin");
let users  = first.union(second).get().await?;
let users  = first.union_all(second).get().await?;
```

As in Laravel, an ordering, a limit, or an offset belongs to the whole
union when you add it after `union`, and to the first query alone when
you add it before. `paginate`, `simple_paginate`, `cursor_paginate`,
`first`, and `count` all come after `union`, so they page, take, and
count the rows of the union; a cursor bounds the rows of every arm:

```rust
let page = User::filter("active", true)
    .union(User::filter("role", "admin"))
    .order_by_desc("id")      // orders the union
    .paginate(20)             // pages the union; `total` counts its rows
    .await?;

let latest_active = User::filter("active", true)
    .order_by_desc("created_at")
    .limit(10)                // the ten newest active users only
    .union(User::filter("role", "admin"));
```

The union is wrapped as a subquery for these clauses, so order it by the
bare names of its columns (`id`, not `users.id`). A `UNION` keeps one
copy of a row both queries return, and `total` counts it once;
`union_all` keeps both.

## Row locking

Two builder methods request a per-row database lock at SELECT time:

```rust
// Exclusive write lock - blocks other transactions trying to lock
// or write the same rows until this transaction commits.
let order = Order::query()
    .filter("id", 42)
    .lock_for_update()
    .first_or_fail()
    .await?;

// Shared read lock - allows other shared readers, blocks writers.
let inventory = Inventory::query()
    .filter("sku", sku)
    .shared_lock()
    .first_or_fail()
    .await?;
```

Per-backend SQL emitted:

| Backend  | `lock_for_update()` | `shared_lock()`        |
|----------|---------------------|------------------------|
| Postgres | `FOR UPDATE`        | `FOR SHARE`            |
| MySQL    | `FOR UPDATE`        | `LOCK IN SHARE MODE`   |
| SQLite   | (no SQL, see below) | (no SQL, see below)    |

The lock clause is appended at the very end of the compound
statement - after every `UNION` arm, every `ORDER BY`, every
`LIMIT` / `OFFSET`. A `union(...)` of two builders followed by
`.lock_for_update()` emits exactly **one** `FOR UPDATE` at the
outer scope, not one per arm.

To reload a model you already hold and take the lock in the same
statement, use `refresh_for_update`:

```rust
DB::transaction(|tx| async move {
    let mut order = Order::find_or_fail(42).await?;
    order.refresh_for_update().await?;   // SELECT ... WHERE id = ? FOR UPDATE
    order.status = "processed".into();
    order.save_with_tx(&tx).await?;
    Ok(())
}).await?;
```

### Use inside a transaction

The lock only does useful work **inside a transaction** - without
one, the SQL still emits but the lock releases at statement end.
Pair with `DB::transaction(...)`:

```rust
DB::transaction(|tx| async move {
    let order = Order::query()
        .filter("id", 42)
        .lock_for_update()
        .first_or_fail()
        .with_tx(&tx)
        .await?;
    // Other transactions trying to lock id=42 block here until commit.
    order.status = "processed".into();
    order.save_with_tx(&tx).await?;
    Ok(())
}).await?;
```

### `lock_for_update` vs `shared_lock`

Most "read then write" flows want `lock_for_update`. A shared
lock still lets another `shared_lock` reader race you to a
following `UPDATE` - only `FOR UPDATE` is mutually exclusive.

`shared_lock` is right for consistent snapshot reads where you
read a row, derive a decision from it, and don't write back -
e.g. an inventory check that doesn't itself decrement stock.

### SQLite

SQLite has no row-level locking. It uses file-level transaction
locking only (`BEGIN IMMEDIATE` / `BEGIN EXCLUSIVE`). The lock
methods are **kept** in the SQLite path so cross-backend code
compiles, but they emit no SQL.

The first time per process that `lock_for_update` / `shared_lock`
runs against a SQLite backend, the framework logs a single
`warn!` on the `suprnova::eloquent::lock` tracing target. This
surfaces the no-op without spamming high-volume code paths.

If you need cross-row contention guarantees on SQLite, wrap the
critical section in an explicit `BEGIN IMMEDIATE` transaction - at
the file level that blocks every other writer.

### Not provided

- **`NOWAIT` / `SKIP LOCKED`** - useful for job-queue claim
  workflows but they add API surface, so they are added only when a
  real consumer needs them.

## Transactions

Suprnova ships three entry points for database transactions plus
nested-rollback via savepoints. Two of them - the closure form and
the retry-on-deadlock helper - install an ambient context so model
operations inside the closure auto-route through the transaction
without callers threading a handle through every call site.

### Closure form - `DB::transaction`

The closure form is the common case. The closure receives a
`&Transaction` it can use to checkpoint with `savepoint(name)`;
every `Model::*` / `Builder::*` operation inside the closure
auto-routes through the transaction: the closure's task carries it as
the ambient transaction.

```rust
use suprnova::{DB, FrameworkError, Model};

DB::transaction(|_tx| {
    Box::pin(async move {
        let mut alice = User::query().filter("name", "alice").first_or_fail().await?;
        alice.balance -= 30;
        alice.save().await?;

        let mut bob = User::query().filter("name", "bob").first_or_fail().await?;
        bob.balance += 30;
        bob.save().await?;
        Ok::<(), FrameworkError>(())
    })
}).await?;
```

- Closure returns `Ok` → **commit**.
- Closure returns `Err` → **rollback** (original error propagates).
- Closure panics → rollback (the in-flight transaction is dropped
  on unwind; SeaORM's `DatabaseTransaction::drop` rolls back).

Reads inside the closure see writes from the same transaction
(every leaf SQL call looks up the ambient transaction). The first
`DB::transaction` call after process start picks the database
backend off `DB::connection()`; subsequent calls reuse the same
connection registry.

The signature uses a higher-ranked trait bound + `Pin<Box<dyn
Future>>` so closures can borrow `tx` across `.await` points:

```rust
DB::transaction(|tx| {
    Box::pin(async move {
        // ... pre-savepoint work ...
        tx.savepoint("inner").await?;
        // ... inner work ...
        if some_condition {
            tx.rollback_to("inner").await?;
        }
        Ok::<(), FrameworkError>(())
    })
}).await?;
```

The `Box::pin(async move { ... })` shape is the cost of letting
the future use `&tx` after an `.await` - without it, the lifetime
of the borrow can't escape the closure body. Mirrors SeaORM's
`TransactionTrait::transaction` signature.

### Savepoints - `tx.savepoint(name)` / `tx.rollback_to(name)`

Savepoints checkpoint the transaction so you can drop a block of
inner work without aborting the outer commit. Works on all three
backends - SQLite's `SAVEPOINT` is fully functional even though
SQLite has no row-level locking.

```rust
DB::transaction(|tx| {
    Box::pin(async move {
        let mut account = Account::query().filter("id", id).first_or_fail().await?;
        account.balance = 200;
        account.save().await?;     // committed when the outer tx commits

        tx.savepoint("audit_trail").await?;

        let entry = AuditEntry::create(attrs! { actor_id: actor, ... }).await?;
        if audit_validation_failed(&entry) {
            tx.rollback_to("audit_trail").await?;
            // audit_trail row gone; account update still pending commit
        }

        Ok::<(), FrameworkError>(())
    })
}).await?;
```

The savepoint name is interpolated verbatim into the SQL - use a
static identifier, do **not** splice user input.

### Nested `DB::transaction` is rejected at runtime

```rust
DB::transaction(|_outer| Box::pin(async move {
    let inner = DB::transaction(|_inner| Box::pin(async move {
        Ok::<(), FrameworkError>(())
    })).await;
    // inner is Err(FrameworkError::Database(
    //     "nested DB::transaction is not supported; use tx.savepoint(name) for nested rollback"
    // ))
    Ok::<(), FrameworkError>(())
})).await?;
```

SeaORM's `DatabaseConnection::begin()` doesn't compose - calling
it on a connection that's already holding a transaction starts a
brand-new physical transaction that commits / rolls back
independently of the outer scope. That's a silent data-integrity
footgun, so `DB::transaction` checks for an ambient transaction up front and
returns a database error instead of producing the wrong
semantics. Use `tx.savepoint(name)` for nested behaviour.

### Retry-on-deadlock - `DB::transaction_with_attempts`

Postgres `SERIALIZABLE` reads and MySQL row-level locks can raise
serialization-failure / deadlock errors that resolve by retrying
the transaction. `transaction_with_attempts` runs the closure
from scratch each time, up to `attempts`:

```rust
DB::transaction_with_attempts(3, |_tx| {
    Box::pin(async move {
        // SERIALIZABLE-isolated logic that may race a concurrent
        // tx and surface SQLSTATE 40001 / 40P01 on commit.
        let inventory = Inventory::query()
            .filter("sku", sku)
            .lock_for_update()
            .first_or_fail()
            .await?;
        if inventory.units < requested {
            return Err(FrameworkError::bad_request("out of stock"));
        }
        Inventory::query()
            .filter("sku", sku)
            .update(attrs! { units: inventory.units - requested })
            .await?;
        Ok::<(), FrameworkError>(())
    })
}).await?;
```

Detection is by Display-string substring against the inner error:

- Postgres SQLSTATE `40001` (serialization_failure)
- Postgres SQLSTATE `40P01` (deadlock_detected)
- Case-insensitive `"deadlock"` substring (covers MySQL
  `Deadlock found when trying to get lock` and any user-surfaced
  deadlock string)

On the final attempt the error propagates unchanged. The closure
runs from scratch on every attempt - capture owned state or
`Arc`s rather than `&mut` references so the retry path is
well-defined.

> **Caveat:** because detection includes a case-insensitive
> `"deadlock"` substring (needed for MySQL whose driver doesn't
> surface a SQLSTATE), any inner error whose `Display` contains
> the word will trigger a retry. When raising your own errors
> from inside a `transaction_with_attempts` closure, avoid
> "deadlock" in the message - otherwise an unrelated validation
> error retries up to `attempts` times before propagating. The
> Postgres SQLSTATE matches (`40001` / `40P01`) are the reliable
> signal; the heuristic is for MySQL only.

### Manual form - `DB::begin_transaction` + `*_with_tx` shims

When the transaction lifetime doesn't fit a closure (e.g. spans
multiple control-flow branches), open a manual `Transaction` and
opt each operation into it explicitly:

```rust
let tx = DB::begin_transaction().await?;

let mut user = User::query()
    .filter("name", "alice")
    .with_tx(&tx)
    .first_or_fail()
    .await?;
user.balance = 500;
user.save_with_tx(&tx).await?;

if some_condition {
    let mut other = User::query()
        .filter("name", "bob")
        .with_tx(&tx)
        .first_or_fail()
        .await?;
    other.update_with_tx(&tx, attrs! { balance: 200i64 }).await?;
}

tx.commit().await?;  // or tx.rollback().await?;
```

Manual mode does **not** install an ambient transaction. Scope individual
operations through the transaction with `Builder::with_tx(&tx)`
or the `Model::*_with_tx(&tx, ...)` shims:

| Trait method        | Manual variant                            |
|---------------------|-------------------------------------------|
| `Model::create`     | `Model::create_with_tx(&tx, attrs)`       |
| `Model::save`       | `Model::save_with_tx(&tx)`                |
| `Model::update`     | `Model::update_with_tx(&tx, attrs)`       |
| `Model::delete`     | `Model::delete_with_tx(&tx)`              |
| `Model::force_delete` | `Model::force_delete_with_tx(&tx)`      |
| `Builder::*`        | `Builder::with_tx(&tx).*`                 |

Holding a `Transaction` pins one pool connection for the entire
lifetime of the handle. On SQLite the pool has a single connection,
so any parallel non-transactional read against the same database
blocks until the transaction completes - **load any pre-flight
rows BEFORE `DB::begin_transaction()`** and route every dependent
write through the returned `tx`.

`Transaction::commit` / `Transaction::rollback` consume the
handle and require `Arc::try_unwrap` of the inner SeaORM
transaction; if any `TxHandle` clones (from `tx.handle()` /
`Builder::with_tx(&tx)`) are still alive at commit / rollback
time, both fail with a "TxHandle clones still alive" error. The
correct fix is to drop your `Builder<M>` / outstanding handles
before calling `commit` - the framework refuses to race a
half-uncommitted write against a parallel writer holding the same
tx.

### Precedence

Three-way precedence for routing an operation through a connection:

1. **Builder-level override** - `Builder::with_tx(&tx)` or any
   `Model::*_with_tx(&tx, ...)` shim. Explicit beats ambient. The
   eager loads of such a query read through the same transaction, and
   those of an `on(name)` query read from that connection, unless the
   related model declares a connection of its own.
2. **The ambient transaction** - installed by `DB::transaction` /
   `DB::transaction_with_attempts` for the closure's task scope.
   A read that names another connection, through `on(name)` or a
   model's declared connection, still runs on that connection: the
   transaction is pinned to one database, so a read cannot join it
   there, and rerouting it would change which database the code reads
   from (audit finding ASTRA-06, 2026-09-13). Writes stay on the
   transaction, since atomicity must not split across connections.
3. **Pool fallback** - `DB::connection()` returns the global
   `DbConnection` singleton.

Inside `DB::transaction(|tx| ...)`, calling
`Builder::with_tx(&other_tx)` explicitly routes that one query
through `other_tx` - bypassing the ambient transaction. That's
almost certainly a bug; the override path exists for the manual
form, not for overriding the closure's own tx.

### `with_tx` and global scopes

A builder carrying a `tx_override` still respects global scopes,
named scopes, and the eager-load plan - the override only changes
the connection routing, not the SQL.

### Relations and DDL inside a transaction

- **Relation eager loads** - `Builder::with(["posts"])` and
  `Collection::load(["posts"])` run their `IN (...)` sub-queries
  through the active transaction, so pending writes inside a
  `DB::transaction` closure are visible to relations loaded there.
- **DDL** - `DB::statement(...)` inside a transaction runs the DDL
  against the transaction's connection, which Postgres allows;
  MySQL and MariaDB commit implicitly on DDL, so DDL is unsupported
  inside a Suprnova transaction on those engines (the same caveat as
  Laravel's `DB::transaction`).

## Scopes

Suprnova ships two flavours of scope, mirroring Laravel:

- **Local scopes** - extension methods on the builder, declared per
  model with `#[suprnova::scopes(Model)]`. Each free function in the
  annotated `impl` block becomes both `Model::name()` (a static
  starter) and `Builder::name()` (a chainable method).
- **Global scopes** - implementations of `GlobalScope<M>` registered
  at boot via `ScopeRegistry::register::<M, _>(scope)`. Every
  `Model::query()` call layers them on automatically.

### Local scopes

Declare local scopes by giving them the shape
`fn(query: Builder<Self>, args...) -> Builder<Self>`:

```rust
#[suprnova::scopes(User)]
impl User {
    pub fn active(query: Builder<Self>) -> Builder<Self> {
        query.filter("active", true)
    }

    pub fn popular(query: Builder<Self>, threshold: i64) -> Builder<Self> {
        query.filter_op("followers_count", ">", threshold)
    }
}

// Use as either a starter or a chainable method:
let active_users  = User::active().get().await?;
let popular_users = User::query().active().popular(500).get().await?;
```

A method that does not handle a `Builder` passes through unchanged, so
scopes and ordinary methods can share one `impl` block.

A method that takes or returns a `Builder` in any other form is a scope
written wrong, and the macro refuses it with a compile error that names
the accepted shape. This covers a first parameter of `&mut Builder<User>`
or `&Builder<Self>`, a model name in place of `Self` (`Builder<User>`),
and a missing `Builder<Self>` return type. Left alone, such a method would
be an ordinary method and no `.name()` would reach the builder. Put
`#[not_scope]` on a helper that handles a builder and is not a scope:

```rust
#[suprnova::scopes(User)]
impl User {
    #[not_scope]
    fn describe(query: &Builder<User>) -> String {
        query.to_sql()
    }
}
```

### Global scopes

Global scopes apply on every `Model::query()` call. The classic use
case is multi-tenancy - every read is scoped to the current tenant
without each caller threading the filter through.

```rust
use suprnova::eloquent::scopes::{GlobalScope, ScopeRegistry};

pub struct TenantScope;

impl GlobalScope<Article> for TenantScope {
    fn apply(&self, query: Builder<Article>) -> Builder<Article> {
        // Reads the current tenant from a task-local /
        // AtomicI64 / wherever per-request state lives.
        query.filter("tenant_id", current_tenant_id())
    }
}

// At boot - typically inside your provider/bootstrap module:
ScopeRegistry::register::<Article, _>(TenantScope);

// Every read is auto-scoped to the active tenant:
let scoped = Article::query().get().await?;
```

Multiple scopes per model compose in registration order - first
registered runs first, so its filter clauses appear first in the
WHERE chain. AND-combined filters don't care about order, but
left-to-right matters for any clause whose side-effect order is
visible (e.g. ordering, having, raw fragments).

You call `apply_scopes()` to keep a builder with its registered scopes and
soft-delete filter already applied. You inspect the resulting SQL or run
the same builder. Repeated calls keep each scope's clauses once. You set
`without_global_scopes()` or `with_trashed()` before applying scopes when
you need those opt-outs.

```rust
let query = Article::query().apply_scopes();
let sql = query.to_sql();
let rows = query.get().await?;
```

### Opting out of a global scope

Each model the `#[suprnova::model]` macro touches gets two static
helpers emitted on it:

```rust
// Bypass exactly one registered scope by type. Other scopes still apply.
let all_tenants = Article::without_global_scope::<TenantScope>().get().await?;

// Bypass every registered scope. Admin tooling pattern.
let everything = Article::without_global_scopes().get().await?;
```

The opt-outs also chain on a `Builder`:
`Model::query().without_global_scope::<S>()` and
`Model::query().without_global_scopes()` return the same rows as the
static helpers, wherever you write them in the chain.

The builder applies global scopes when the query runs, not when
`Model::query()` builds it. The statement reads `<scopes> AND <your
terms>`. Your own terms stay together after the scopes: an `or_where`
never widens past a scope. `update_all`, `delete_all`, and
`increment_each` resolve scopes the same way, so a mass write reaches
only the rows a read returns. A scope that reads per-request state reads
it when the query runs.

### Where global scopes apply

| Path | Global scopes apply? |
|------|----------------------|
| `Model::query()` | Yes - the canonical scoped entry point |
| `Model::without_global_scope::<S>()` | Yes, minus `S` |
| `Model::without_global_scopes()` | No |
| `Model::query().without_global_scope::<S>()` | Yes, minus `S`, wherever it is chained |
| `Model::with_trashed()` / `Model::only_trashed()` | Yes - only the soft-delete filter is lifted |
| Route binding (`post: Post`, `RouteParam<Post>`) | Yes - the bound row is read through `Model::query()` |
| `Model::find(id)` | No - PK lookup goes through SeaORM directly |
| `Model::find_many([...])` | No - same reason |
| `Model::all()` | No - same reason |

This mirrors Laravel: `Eloquent\Model::find` doesn't trigger
`addGlobalScopes`. Callers that want scoped PK lookups use
`Self::query().filter("id", pk).first().await?`.

### Soft deletes and global scopes coexist

`#[suprnova::model(soft_deletes)]` installs the
`deleted_at IS NULL` filter via a separate string-tag mechanism, not
through the typed scope registry. Both layers compose:

- `Model::query()` filters out trashed rows AND runs every registered
  scope.
- `Model::without_global_scopes()` drops registered scopes but
  preserves the soft-delete filter - admin tooling that wants to read
  every column-set still excludes trashed rows by default.
- `Model::with_trashed()` and `Model::only_trashed()` lift only the
  soft-delete filter. Every registered scope still runs, so a tenant
  scope keeps trashed reads inside the tenant, as Laravel's
  `withTrashed()` does.

## Relationships

Suprnova ships every Eloquent relation flavour. They're declared in
the `relations = { ... }` block on `#[suprnova::model]`, and the
macro emits - per declared relation - a method on the struct, a
loaded-accessor (`<name>_loaded()`), a count-accessor
(`<name>_count()`), and the dispatcher arm the eager loader calls
into. This section covers the per-kind shape and option table; the
deep dive on join-key resolution, the morph registry, pivot rows,
and the polymorphic enum lowering lives in
[Eloquent Relationships](eloquent-relationships.md). The relation
kinds:

| Kind                | One/many | Across families | Backed by |
|---------------------|----------|-----------------|-----------|
| `HasOne<R>`         | one      | no              | `IN` query on `<parent>_id` |
| `BelongsTo<R>`      | one      | no              | `IN` query on FK on this row |
| `HasMany<R>`        | many     | no              | same as `HasOne`, returns `Vec<R>` |
| `BelongsToMany<R, P>` | many   | no              | pivot table `P`, INNER JOIN + `pivot::<P>()` |
| `HasOneThrough<B, R>`  | one   | no              | two-query JOIN `parent → B → R` |
| `HasManyThrough<B, R>` | many  | no              | same as above, returns `Vec<R>` |
| `MorphOne<R>`       | one      | yes             | `IN` + `<name>_type = "<self>"` filter |
| `MorphMany<R>`      | many     | yes             | same as `MorphOne`, returns `Vec<R>` |
| `MorphTo`           | one      | yes (children → many families) | per-family enum emitted at the declaration site |
| `MorphToMany<R, P>` | many     | yes             | polymorphic m2m pivot `P` |
| `MorphedByMany<R, P>` | many   | yes (inverse)   | same pivot, scanned the other way |

### `relations = { ... }` syntax

Every relation declaration carries the same outer shape: the relation
name, the kind, the related type (and pivot/intermediate types where
applicable), and a `{ ... }` block of options.

```rust
use suprnova::model;

#[model(
    table = "users",
    relations = {
        // HasMany<R>
        posts: HasMany<crate::models::Post> {
            fk = "author_id",         // override default `user_id`
        },
        // BelongsToMany<R, Pivot>
        roles: BelongsToMany<crate::models::Role, crate::models::RoleUser> {
            with_pivot = ["assigned_at"],
            with_timestamps,
        },
    },
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

Common options:

| Option                     | Relation kinds                | Purpose |
|----------------------------|-------------------------------|---------|
| `fk = "..."`               | every kind with a child FK    | Column on the CHILD pointing at the parent. Default = `<snake(parent_struct)>_id`. |
| `lk = "..."`               | one/many kinds                | Column on the PARENT used as the join key. Default = the parent model's primary key. |
| `related_key = "..."`      | `BelongsToMany`, `MorphToMany` | The related-side COLUMN the pivot's related key holds. Default = the related model's primary key. |
| `with_pivot = ["...", ...]` | `BelongsToMany`, `MorphToMany` | Extra columns on the pivot to surface in the join. |
| `with_timestamps`          | `BelongsToMany`, `MorphToMany` | Stamp `created_at` / `updated_at` on attach/sync. |
| `with_default = \|\| { ... }` | `BelongsTo`                 | Closure producing a default when the FK is null OR the parent is missing. |
| `first_key`, `second_key`, `second_local_key` | `HasOneThrough`, `HasManyThrough` | JOIN key overrides - see the Through section below. |
| `name = "..."`             | every morph kind              | Morph family name (e.g. `"commentable"`, `"taggable"`). Drives the `<name>_id` / `<name>_type` columns on the child/pivot. |
| `targets = [T1, T2, ...]`  | `MorphTo`                     | The list of concrete morph targets. The macro emits a `<Name>Morph` enum at the declaration site with one variant per target plus `Unknown(String, serde_json::Value)`. |
| `target_morph_type = "..."` | `MorphedByMany`              | The morph-type string identifying the target family on the pivot. |
| `pivot_table`, `pivot_foreign_key`, `pivot_related_key` | `BelongsToMany`, `MorphToMany` | Pivot-side column / table overrides when the defaults don't fit. |

### Why Suprnova diverges: default foreign key names

A default foreign key column always ends in `_id`. Laravel ends it in
the parent model's primary key name instead (`getForeignKey()` is the
snake-cased class name, `_`, and `getKeyName()`), so the two agree for
the usual `id` key and differ for any other. `BelongsTo` differs in the
name as well: Laravel takes it from the relation, Suprnova from the
target model.

| Relation | Suprnova default | Laravel default |
|----------|------------------|-----------------|
| `HasOne`, `HasMany` on a parent keyed by `uuid` | `user_id` | `user_uuid` |
| `BelongsTo` declared as `author: BelongsTo<User>` | `user_id` (the target model) | `author_id` (the relation name) |
| `BelongsToMany` pivot keys | `<snake(model)>_id` | `<snake(model)>_<primary key>` |
| Through `first_key` / `second_key` | `<snake(model)>_id` | `<snake(model)>_<primary key>` |

Most schemas name the column `<model>_id` whatever the parent's key is
called, as Laravel's own `$table->foreignUuid('user_id')` does, so the
default matches the column you would write. The join column on
the other side already follows the model: `lk`, `related_key` and the
owner key default to the model's primary key. When you mirror a
Laravel schema whose columns follow Laravel's rule, name them with
`fk = "..."`, `pivot_foreign_key`, `pivot_related_key`, `first_key` or
`second_key`.

### `HasOne<R>` and `BelongsTo<R>`

One-to-one in both directions. `HasOne` lives on the parent side and
calls `R::query().filter(<fk>, <self.id>).first()`. `BelongsTo` lives
on the child side and reads the FK off `self`, then calls
`R::query().filter(<owner_key>, <fk_value>).first()`.

```rust
#[model(table = "users", relations = {
    profile: HasOne<crate::models::Profile>,
})]
pub struct User { /* ... */ }

#[model(table = "profiles", relations = {
    user: BelongsTo<crate::models::User>,
})]
pub struct Profile {
    pub id: i64,
    pub user_id: i64,
    pub bio: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

let user = User::find(1).await?.unwrap();
let profile: Option<Profile> = user.profile().first().await?;

let profile = Profile::find(42).await?.unwrap();
let owner: Option<User> = profile.user().first().await?;
```

`BelongsTo` supports `with_default = || R { ... }`, which fires
either when the FK is null OR when the parent row is missing. The
default closure runs per call (and per eager-loaded row) - perfect
for an empty stand-in when a deleted user still has comments:

```rust
#[model(table = "comments", relations = {
    author: BelongsTo<crate::models::User> {
        with_default = || User {
            name: "[deleted]".into(),
            ..Default::default()
        },
    },
})]
pub struct Comment { /* ... */ }

let c = Comment::find(99).await?.unwrap();
// Always Some - the default fires when the user row is missing.
let author = c.author().first().await?.unwrap();
```

### `HasMany<R>`

One-to-many on the parent side. Returns a fluent builder; chain
filter / order / latest / take / get / count and terminate.

```rust
#[model(table = "users", relations = {
    posts: HasMany<crate::models::Post> {
        fk = "author_id",
    },
})]
pub struct User { /* ... */ }

let u = User::find(1).await?.unwrap();

// Every post by this user, default ordering:
let posts: Vec<Post> = u.posts().get().await?;

// Filtered + ordered + paged:
let recent = u.posts()
    .filter("published", true)
    .latest()                          // ORDER BY created_at DESC
    .take(10)
    .get()
    .await?;

// COUNT alone - no row fetching:
let total: i64 = u.posts().count().await?;
```

Available terminal methods: `.first()`, `.get()`, `.count()`. Available
chainable filters: `.filter` / `.db_where`, `.filter_in` / `.where_in`,
`.order_by`, `.latest`, `.oldest`, `.limit`, `.take`.

### `BelongsToMany<R, P>` - first-class Pivot

Many-to-many through a `#[suprnova::model]`-declared pivot. The pivot
is a first-class model with its own row identity - not a tuple, not a
hidden hash map. Two key benefits over Laravel's anonymous-pivot
shape:

1. The pivot row is type-safe. Read `with_pivot` columns via
   `r.pivot::<P>().<column>`, never via `r.pivot.get("...")`.
2. The pivot model is reachable from the rest of the framework
   (factories, scopes, casts, hooks) the same way every model is.

```rust
#[model(table = "role_user", fillable = ["user_id", "role_id", "assigned_at"])]
pub struct RoleUser {
    pub id: i64,
    pub user_id: i64,
    pub role_id: i64,
    pub assigned_at: Option<chrono::DateTime<chrono::Utc>>,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

#[model(table = "users", relations = {
    roles: BelongsToMany<crate::models::Role, RoleUser> {
        with_pivot = ["assigned_at"],
        with_timestamps,
    },
})]
pub struct User { /* ... */ }

let u = User::find(1).await?.unwrap();
let admin = Role::create(attrs! { name: "admin" }).await?;

// Attach + sync mutators
u.roles().attach(admin.id).await?;
u.roles().attach_with(admin.id, attrs! { assigned_at: chrono::Utc::now() }).await?;
u.roles().sync([role_a.id, role_b.id, role_c.id]).await?;
u.roles().sync_without_detaching([role_d.id]).await?;
u.roles().detach(admin.id).await?;

// Read pivot data through the per-row downcast accessor:
let roles = u.roles().get().await?;
for r in &roles {
    let p: &RoleUser = r.pivot::<RoleUser>();
    println!("user {} got role {} at {:?}", p.user_id, p.role_id, p.assigned_at);
}
```

- `.attach(id)` - INSERT a single pivot row. Errors on duplicate
  unless your pivot allows it (the framework doesn't dedupe at the
  Rust layer; use `.sync` for idempotency).
- `.attach_with(id, attrs! { ... })` - INSERT with extra pivot
  columns. Stamps timestamps when `with_timestamps` is on.
- `.detach(id)` - DELETE the pivot row(s) linking parent → id.
- `.sync([ids...])` - diff-and-apply: attach what's new, detach what's
  missing, update supplied pivot columns on existing rows. You receive
  `SyncChanges` with `attached`, `detached` and `updated` id lists.
- `.sync_without_detaching([ids...])` - attach what's new and keep every
  existing row. You can supply `(id, attrs! { ... })` records to update
  existing pivot columns. Unchanged rows keep their timestamps, and the
  returned `SyncChanges.detached` is empty.

You pass ids alone or `(id, Attrs)` records to either sync method.
Only rows whose supplied columns change appear under `updated`. Pivot
filters constrain the current set, updates and detachments; rows outside
that set remain unchanged. All changes run in one transaction. You call
`.touch_parent()` to update the parent's timestamp when sync changes the
relation; the touch commits or rolls back with the pivot writes.

Each id and extra column binds by the type its column has: the pivot
model's field, or else the key the column holds. On Postgres and SQLite,
a `u64` above `i64::MAX` written to the pivot fails with an error that
names the column, and nothing is sent. `detach` of such an id deletes
nothing on Postgres, and on SQLite it compares the id's digits, as it does
a literal. On MySQL an unsigned pivot column holds the whole `u64` range,
and `sync` and `.get()` read its ids back.

`.get()` returns `Vec<R>` with the pivot stamped on each row's
internal `__pivot` field. The `.pivot::<P>()` accessor downcasts the
`Arc<dyn Any>` to the pivot type you declared. Calling it with the
wrong type panics - match the type to the declared pivot.

### `HasOneThrough<B, R>` and `HasManyThrough<B, R>`

Reach a final target `R` through an intermediate `B`. Useful when the
relation traverses two tables but you don't need to expose the
intermediate (`A → B → R`).

```rust
#[model(table = "countries", relations = {
    posts: HasManyThrough<crate::models::User, crate::models::Post>,
})]
pub struct Country {
    pub id: i64,
    pub name: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

let c = Country::find(1).await?.unwrap();
let posts: Vec<Post> = c.posts().get().await?;
```

The dispatcher infers JOIN keys from struct names. Overrides:

| Option              | Default                          | Description |
|---------------------|----------------------------------|-------------|
| `first_key`         | `<snake(parent_struct)>_id`      | Column on intermediate `B` pointing at parent `A`. |
| `second_key`        | `<snake(intermediate_struct)>_id` | Column on final `R` pointing at intermediate `B`. |
| `second_local_key`  | `"id"`                           | Column on intermediate `B` matched by `second_key`. Required when `B` uses a non-`id` PK. |

The parent's primary-key column is read from the model's `primary_key`
declaration (defaulting to `"id"`) - there is no `local_key` override
on `HasManyThrough` / `HasOneThrough`; change the parent's PK via the
`#[suprnova::model]` attribute if you need a non-`id` parent key.

```rust
#[model(table = "countries", relations = {
    posts: HasManyThrough<crate::models::User, crate::models::Post> {
        first_key = "country_id",
        second_key = "author_id",
    },
})]
pub struct Country { /* ... */ }
```

### `MorphTo` with `targets = [...]` and per-family enum

Polymorphic relations point a child row at one of several parent
families. The child carries a `(<name>_id, <name>_type)` pair; the
`*_type` column holds the morph-type string each parent declares.

`MorphTo` lives on the child. Its declaration lists every parent
family it can point at via `targets = [...]`. The macro emits a
per-family enum named `<RelationName>Morph` (matching the relation
name's PascalCase form, suffixed with `Morph`) with one variant per
target type plus `Unknown(String, serde_json::Value)` for legacy rows whose
`<name>_type` value doesn't match any registered target. The second field
is the value of `<name>_id` as JSON: a number for an integer key, a string
for a `String`, UUID or ULID key, `null` for a null column.

```rust
#[model(table = "posts", morph_type = "post")]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video")]
pub struct Video { /* ... */ }

#[model(table = "comments", relations = {
    commentable: MorphTo {
        name = "commentable",
        targets = [
            crate::models::Post,
            crate::models::Video,
        ],
    },
})]
pub struct Comment {
    pub id: i64,
    pub commentable_id: i64,
    pub commentable_type: String,
    pub body: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

let c = Comment::find(1).await?.unwrap();
match c.commentable().get().await? {
    CommentableMorph::Post(post)   => println!("comment on post {}", post.title),
    CommentableMorph::Video(video) => println!("comment on video {}", video.url),
    // Legacy / dangling rows - `<name>_type` doesn't match any target,
    // OR the morph_type matched but the row at `<name>_id` is gone.
    CommentableMorph::Unknown(ty, id) => {
        eprintln!("comment {} points at unknown {ty}#{id}", c.id);
    }
}
```

The `morph_type = "..."` attribute on each target struct is what the
loader writes into the child's `<name>_type` column on insert and
filters by on read. Without `morph_type`, the framework derives the
type-string from `to_snake(struct_name)`.

`MorphTo` dispatch - how the per-family enum picks the right variant -
consults the runtime morph registry (the inventory populated by
every `#[suprnova::model(morph_type = "...")]` declaration). For each
declared target, the fetch helper looks up the target's `TypeId`,
reads the registered `morph_type` string, and compares it against the
stored `<name>_type` value on the child row. First match wins, in
declaration order. Targets without an explicit `morph_type` attribute
fall back to `to_snake(target_type_name)` - the same default the
parent-side `MorphMany` / `MorphOne` uses to stamp the type-string at
write time, so the two sides stay aligned. This means custom
`morph_type` values (e.g. `morph_type = "blog_post"` on a struct
named `Post`, or any non-conventional string) dispatch correctly
without changes to the declaration site.

### `MorphOne<R>` and `MorphMany<R>` - parent side

The inverse direction of `MorphTo`: a parent type declares the
polymorphic one-or-many it owns. `MorphOne` returns `Option<R>` from
`.first()`; `MorphMany` returns `Vec<R>` from `.get()`. Both filter
the child's `(<name>_id, <name>_type)` pair by `self.id` and the
parent's `morph_type`.

```rust
#[model(table = "posts", morph_type = "post", relations = {
    comments: MorphMany<crate::models::Comment> {
        name = "commentable",
    },
    cover: MorphOne<crate::models::Image> {
        name = "imageable",
    },
})]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video", relations = {
    comments: MorphMany<crate::models::Comment> {
        name = "commentable",
    },
})]
pub struct Video { /* ... */ }

let post = Post::find(1).await?.unwrap();
let post_comments: Vec<Comment> = post.comments().get().await?;
let post_cover:    Option<Image> = post.cover().first().await?;

let video = Video::find(1).await?.unwrap();
let video_comments: Vec<Comment> = video.comments().get().await?;
// post.comments() returns only `commentable_type = "post"` rows;
// video.comments() returns only `commentable_type = "video"`.
```

The same chainable surface as `HasMany` / `HasOne`: `.filter` /
`.db_where`, `.order_by` / `.latest` / `.oldest`, `.limit` / `.take`,
`.first` / `.get` / `.count`.

### `MorphToMany<R, P>` and `MorphedByMany<R, P>`

Polymorphic many-to-many. The shared pivot `P` carries the FK pair
PLUS a `<name>_type` discriminator column. One end declares
`MorphToMany` (e.g. `Post.tags()`, `Video.tags()`), the other end
declares one `MorphedByMany` per target family (e.g. `Tag.posts()`,
`Tag.videos()`).

```rust
#[model(table = "taggables", fillable = ["tag_id", "taggable_id", "taggable_type"])]
pub struct Taggable {
    pub id: i64,
    pub tag_id: i64,
    pub taggable_id: i64,
    pub taggable_type: String,
}

#[model(table = "posts", morph_type = "post", relations = {
    tags: MorphToMany<crate::models::Tag, Taggable> {
        name = "taggable",
    },
})]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video", relations = {
    tags: MorphToMany<crate::models::Tag, Taggable> {
        name = "taggable",
    },
})]
pub struct Video { /* ... */ }

// Inverse: Tag declares one MorphedByMany per target family.
#[model(table = "tags", relations = {
    posts: MorphedByMany<crate::models::Post, Taggable> {
        name = "taggable",
        target_morph_type = "post",
    },
    videos: MorphedByMany<crate::models::Video, Taggable> {
        name = "taggable",
        target_morph_type = "video",
    },
})]
pub struct Tag { /* ... */ }

let post  = Post::find(1).await?.unwrap();
let video = Video::find(1).await?.unwrap();
let tag   = Tag::create(attrs! { name: "rust" }).await?;

// `attach` / `attach_with` / `detach` / `sync` / `sync_without_detaching`
// work the same way as BelongsToMany. The `<name>_type` column lands automatically from
// the calling parent's `morph_type`.
post.tags().attach(tag.id).await?;
video.tags().attach(tag.id).await?;          // independent attachment
post.tags().sync([tag_a.id, tag_b.id]).await?;

// Inverse direction - Tag splits by family:
let posts_with_tag:  Vec<Post>  = tag.posts().get().await?;   // typed "post"
let videos_with_tag: Vec<Video> = tag.videos().get().await?;  // typed "video"
```

`MorphedByMany`'s `target_morph_type` is required because the macro
at `Tag`'s declaration site can't introspect the target's
`morph_type = "..."` attribute (it lives in a separate
`#[suprnova::model]` invocation). Setting it explicitly keeps each
`MorphedByMany` arm honest about which family it scans.

### Escape hatch: hand-written relation methods

The relations declared in `relations = { ... }` are the only ones the
eager-load dispatcher (and `with`, `with_count`, etc.) knows about.
If a relation is too unusual for the macro shape - for example a
query that aggregates across two pivots, or a typed view of a
denormalised cache table - you can omit it from `relations = { ... }`
and write a plain inherent impl:

```rust
impl User {
    /// Posts this user authored OR is tagged in. Crosses two relations
    /// and is therefore not expressible as a single `relations = { ... }`
    /// declaration - written by hand.
    pub async fn posts_touched(&self) -> Result<Vec<Post>, FrameworkError> {
        let authored: Vec<Post> = self.posts().get().await?;
        let tagged:   Vec<Post> = /* ...custom query... */;
        // ...merge + dedupe...
        Ok(/* ... */)
    }
}
```

Such methods lose eager-load support - `User::with(["posts_touched"])`
will error because the dispatcher has no arm for `posts_touched`. The
in-macro declarations remain the path the framework knows how to
eager-load, count, aggregate, and predicate-filter.

### Polymorphic keys and nested loads

- **Morph IDs follow the target's primary key.** A `MorphTo` target
  can declare an `i64`, `String`, UUID or ULID primary key, and the
  child table's `<name>_id` column takes the same type. All targets of
  one `MorphTo` relation share one key type. A relation that mixes key
  types, or a child whose `<name>_id` field has another type than the
  key, is a compile error.
- **The parent side is not checked.** `MorphMany` and `MorphOne` are
  not compared with the child's `<name>_id` field. Keep that field at
  the key type of every parent that owns it.
- **`MorphTo::morph_id` is a `serde_json::Value`.** So is the id in the
  `Unknown` variant. Call `as_i64()` or `as_str()` to read it as a
  number or a string.
- **Lazy and eager reads treat global scopes differently.** The lazy
  `comment.commentable().get()` finds the target by its key and applies
  no global scope of the target. The eager `with(["commentable"])` runs
  the query of the target and applies its global scopes, so a target
  that a scope hides comes back as `Unknown`.
- **Nested eager loading through `MorphTo`.** A dotted path like
  `with(["commentable.user"])` loads `user` on every morph target,
  one query per target type. The loader groups the targets by type and
  loads the rest of the path once for each type that is present.

```rust
// Comments on posts and on videos; both models declare `user`.
// 1 query for comments + 1 for posts + 1 for videos
// + 2 for the users (one per target type) = 5 queries,
// however many comments there are.
let comments = Comment::query()
    .with(["commentable.user"])
    .get()
    .await?;
```

Every target of the relation must declare the next relation of the
path. A target that does not is an error that names the type and the
relation. The check covers all targets, so it fails also when no row of
that type is loaded, and when no row is loaded at all.

## Eager loading

Eager loading avoids N+1 queries. Instead of `posts.len()` queries to
fetch every user's posts, Suprnova issues ONE query per top-level
relation regardless of how many parent rows are loaded.

To find the reads that should be eager loads, see
[Preventing lazy loading](#preventing-lazy-loading).

The full surface - flat list, nested paths, count, aggregates, and
predicate-filtered eager loads - is reached through the
`#[suprnova::model]`-emitted helpers on each model:

```rust
// Single relation:
let users = User::with(["posts"]).get().await?;
for u in &users {
    for p in u.posts_loaded() { /* ... */ }
}

// Multiple relations:
let users = User::with(["posts", "profile"]).get().await?;

// Nested paths - three queries (users + posts + comments), no N+1:
let users = User::with(["posts.comments"]).get().await?;
let p1 = users[0].posts_loaded()[0];
let comments = p1.comments_loaded();

// Deeper nesting works as expected:
let users = User::with(["posts.comments.author"]).get().await?;

// Count alongside the parent rows:
let users = User::with_count(["posts"]).get().await?;
for u in &users {
    println!("{} has {} posts", u.name, u.posts_count());
}

// Aggregates - Sum / Avg / Min / Max over a relation column. The
// ergonomic read is the macro-emitted `<rel>_sum_of(col)` accessor.
let users = User::with_sum(("posts", "views")).get().await?;
let sum: f64 = users[0]
    .posts_sum_of("views")
    .expect("with_sum populated the cache");

// Multiple aggregates on the same relation compose - the cache key
// is the wide `<rel>_<kind>_<col>` form, so distinct kinds and
// distinct columns don't collide:
let users = User::with_sum(("posts", "views"))
    .with_avg(("posts", "views"))
    .with_min(("posts", "id"))
    .get()
    .await?;
let u = &users[0];
let sum = u.posts_sum_of("views").unwrap();   // Some(_) - sum of views
let avg = u.posts_avg_of("views").unwrap();   // Some(_) - avg of views
let min = u.posts_min_of("id").unwrap();      // Some(Some(_)) - non-empty group
let max = u.posts_max_of("id");               // None - with_max was not called

// Filter the eager-loaded children. The macro emits a typed
// `with_where_<rel>(closure)` static helper per relation so the closure
// parameter type is inferred - no need to spell out `Builder<Post>`:
let users = User::with_where_posts(|q| q.filter("published", true))
    .get()
    .await?;
// The returned `Builder<User>` chains with any other base-query
// builder method:
let users = User::with_where_posts(|q| q.filter("published", true))
    .filter("active", true)
    .get()
    .await?;
// The generic form is still available - useful when the relation name
// is computed at runtime - but you'll need to name the target type on
// the closure:
let users = User::query()
    .with_where(("posts", |q: Builder<Post>| q.filter("published", true)))
    .get()
    .await?;
// Each u.posts_loaded() contains only published posts.
```

### Cache layout

The per-row `__eager` cache cells are keyed by:

- `<rel>` (relation NAME alone) for `with` and `with_count`. The rows
  and the count are kept in separate cells, so `with(["posts"])` and
  `with_count(["posts"])` on one query keep both, and a count alone
  does not count as loaded rows for `load_missing`.
- `<rel>_<kind>_<col>` (e.g. `posts_sum_views`) for the four
  aggregate kinds - `with_sum` / `with_avg` / `with_min` / `with_max`.
  This wide key lets multiple aggregates on the same relation coexist
  on the same row without overwriting each other.

| Method                              | Cache key            | Cache cell type   | Empty-group value |
|-------------------------------------|----------------------|-------------------|-------------------|
| `with(["posts"])`                   | `posts`              | `Vec<Post>`       | `Vec::new()`      |
| `with(["profile"])`                 | `profile`            | `Option<Profile>` | `None`            |
| `with_count(["posts"])`             | `posts`              | `u64`             | `0`               |
| `with_sum(("posts","views"))`       | `posts_sum_views`    | `f64`             | `0.0`             |
| `with_avg(("posts","views"))`       | `posts_avg_views`    | `f64`             | `0.0`             |
| `with_min(("posts","id"))`          | `posts_min_id`       | `Option<f64>`     | `None`            |
| `with_max(("posts","id"))`          | `posts_max_id`       | `Option<f64>`     | `None`            |

The macro emits matching accessors on each model:

- `<rel>_loaded()` - for collection relations: `&[Post]` (panics if
  the relation wasn't eager-loaded). For single-value relations:
  `Option<&Profile>`.
- `<rel>_count()` - `u64`. Panics if `with_count(["..."])` wasn't
  called.
- `<rel>_sum_of(col)` / `<rel>_avg_of(col)` - return `Option<f64>`
  (`None` if the matching `with_sum` / `with_avg` was not called).
- `<rel>_min_of(col)` / `<rel>_max_of(col)` - return
  `Option<Option<f64>>`: outer `Option` is "was `with_min` /
  `with_max` called?", inner `Option` is "is there a numeric
  minimum?". It is `None` when the group was empty or the minimum is
  not a number, such as a date.
- `<rel>_min_as::<T>(col)` / `<rel>_max_as::<T>(col)` - return
  `Option<T>`: the minimum or maximum read as `T`, whatever the column's
  type, as Laravel's `withMax('posts', 'created_at')` attribute holds
  it. A date or a time reads from its ISO 8601 text, so `T` can be the
  chrono type of the column. A `numeric` / `DECIMAL` minimum on Postgres
  or MySQL reads exactly as `rust_decimal::Decimal`, as the nearest value
  as `f64`, and as its decimal text as `String`. `None` when the call was
  not made, the group was empty, or the value doesn't read as `T`.

The accessors are the ergonomic surface - read through them rather
than reaching into `__eager.get_aggregate::<T>(...)` directly. They
build the same cache key under the hood via
`eloquent::relations::aggregate_cache_key`.

### Composing aggregates on the same relation

The wide cache key means you can stack as many `with_*` calls on the
same relation in one query as you want - no collisions:

```rust
let users = User::with_sum(("posts", "views"))
    .with_avg(("posts", "views"))
    .with_min(("posts", "id"))
    .with_max(("posts", "id"))
    .get()
    .await?;

let u = &users[0];
let total_views: f64 = u.posts_sum_of("views").unwrap();
let avg_views:   f64 = u.posts_avg_of("views").unwrap();

// Min/Max are double-Option because SQL min/max NULLs on empty:
match u.posts_min_of("id") {
    None              => panic!("with_min not called"),
    Some(None)        => println!("no posts yet"),
    Some(Some(min))   => println!("smallest post id: {min}"),
}

// Accessor returns `None` when the matching `with_*` was skipped:
assert!(u.posts_avg_of("score").is_none()); // never called with col="score"

// The latest post's date, as Laravel's withMax('posts', 'created_at'):
let users = User::with_max(("posts", "created_at")).get().await?;
let latest: Option<DateTime<Utc>> = users[0].posts_max_as("created_at");
```

### Aggregates and INTEGER columns

SUM over an INTEGER column lands in the cache as `f64`. The database
chooses the type of an aggregate: an integer of the column's width, a
real, or `numeric` / `DECIMAL` (Postgres and MySQL sum and average
integers that way). The dispatcher reads whichever arrives, and a value
that is not a number, such as the maximum of a date column, is kept for
`<rel>_max_as` rather than failing the query. Read via the
macro-emitted accessors regardless of the source column type.

### `with_where` predicate routing

`User::with_where_posts(|q| q.filter("published", true))` applies a
closure to the inner `Builder<Post>` BEFORE the
`filter_in(<fk>, parent_ids)` IN-query is issued, so only matching
child rows reach the cache. The macro emits one typed
`with_where_<rel>` static helper per declared relation, so the closure's
parameter type is inferred from the method signature.

The generic
`with_where(("posts", |q: Builder<Post>| q.filter("published", true)))`
is still available - useful when the relation name is computed at
runtime, or when you already hold a `Builder<User>` and want to attach
a predicate. It requires naming the target type on the closure because
the predicate goes through a `Box<dyn Any>` and Rust can't infer the
type from the relation name alone. (Rust's orphan rules forbid the
macro from adding a typed method directly on `Builder<User>`, so the
typed shorthand is offered only on the model - `User::with_where_<rel>` -
not as a builder-chain method.)

For the polymorphic kinds, the predicate runs against the related-table
query - not the pivot scan.

`with_where` is supported on every relation kind EXCEPT `MorphTo`.
MorphTo's per-family enum erases the child type, so no single
`Builder<R>` covers all variants. Nested eager loading through
MorphTo does work: `with(["commentable.user"])` groups the loaded
targets by type and loads `user` once per type.

### `Collection::load` / `load_missing`

When you've already fetched rows and want to eager-load relations
after the fact:

```rust
use suprnova::Collection;

let mut users: Collection<User> = User::all().await?.into();
users.load(["posts.comments"]).await?;
```

`load_missing` is per-row: each row in the collection is partitioned
independently. Rows that already have the named relation cached stay
untouched; rows that don't get the relation loaded. Mirrors Laravel's
`$collection->loadMissing(...)` semantics.

For nested paths the partition repeats at every level. Given
`load_missing(["posts.comments"])`:

- Rows without `posts` cached get the FULL path loaded - `posts` plus
  their `comments`.
- Rows WITH `posts` already cached recurse into the cached posts and
  load `comments` only on the posts that don't already have comments
  cached.

The same per-row partition repeats at every further segment of a
longer dotted path (`"posts.comments.author"` etc.) - at each step
only the rows missing that segment get the bulk-load.

#### `load` / `load_missing` on one model

When you hold one model, call the same methods on it. They are methods of
the `Model` trait, so they work on any model and through an `M: Model`
bound:

```rust
use suprnova::Model;

let mut post = Post::find_or_fail(id).await?;
post.load(["comments"]).await?;
post.load_missing(["comments.user", "tags"]).await?;
```

The relations land in the model's own relation cache. Read them with the
`<relation>_loaded()` accessors, which do not query again.

Both methods take the same relation names as the collection methods,
including dotted names, and run the same loader, so each relation costs
one query. Inside a `DB::transaction` closure the reads go through the
transaction.

`load` loads a relation again when the model already has it.
`load_missing` runs no query for a relation the model has. It checks a
dotted name at every level: with `comments` loaded,
`load_missing(["comments.user"])` loads only the users that the cached
comments lack.

## Preventing lazy loading

A relation read on one model runs one query. A template that reads
`post.author()` for each of 50 posts runs 51 queries. Eager loading
(`with`, `load`, `load_missing`) reads the relation for every row with
one query. `prevent_lazy_loading(true)` makes the 51-query loop fail
where it is written, instead of under load in production.

Turn it on in the bootstrap of the application, outside production.
`Config::is_production()` reads `APP_ENV` (see
[Configuration](configuration.md)):

```rust
use suprnova::{Config, prevent_lazy_loading};

prevent_lazy_loading(!Config::is_production());
```

The switch is process-wide and off by default. With it off, every read
behaves as if this section did not exist.

### What is refused

With the switch on, a relation read is refused when both hold:

- The model came out of a query that returned more than one row: a
  `get`, `all` or `find_many`, a page of a paginator, a batch of
  `chunk`, `lazy` or `cursor`, a row of `each` over a query that matches
  more than one row, the rows of a `HasManyThrough` relation, or the
  related rows of an eager load that fetched more than one.
- The relation is not in the model's cache, because it was not loaded
  with `with`, `load` or `load_missing`.

The reads are `get()` and `first()` of every relation kind. A refused
read runs no query and returns an error that names the model and the
relation and says to use `with` or `load`. The error holds no key and no
value of the row.

These reads are not refused:

- A model from `find`, `first`, a `get` that returned one row, or
  `create`. Its relations load lazily, as in Laravel.
- A model you build in the process, and a replica from `replicate`.
- A relation that is loaded.
- `count()` of a relation. It loads no model. Its eager form is
  `with_count`.
- `attach`, `detach` and `sync`, which write.

The last batch of a `chunk` walk that holds one row is not marked, in the
same way that a `get` of one row is not.

```rust
prevent_lazy_loading(true);

let posts = Post::query().get().await?;   // several rows
for post in &posts {
    // Err: lazy loading of the relation `author` of `Post` is prevented
    let author = post.author().first().await?;
}

let posts = Post::with(["author"]).get().await?;
for post in &posts {
    let author = post.author_loaded();    // no query
}
```

### Logging instead of failing

`handle_lazy_loading_violation` registers one handler for the process.
With a handler, a violation calls it and the read goes on and runs its
query. A staging system can log the reads and keep serving:

```rust
use suprnova::{LazyLoadingViolation, handle_lazy_loading_violation, prevent_lazy_loading};

prevent_lazy_loading(true);
handle_lazy_loading_violation(|violation: &LazyLoadingViolation| {
    tracing::warn!(
        model = violation.model,
        relation = violation.relation,
        "lazy loading of a relation",
    );
})?;
```

`LazyLoadingViolation` has two fields: `model`, the struct name of the
model (such as `"Post"`), and `relation`, the relation name as
`relations = { ... }` declares it (such as `"author"`). Both are
`&'static str`. The handler runs with no framework lock held, so a
handler that panics does not break the next read.

`clear_lazy_loading_violation_handler()` removes the handler, so a
violation is an error again. `preventing_lazy_loading()` returns whether
the switch is on.

### Why Suprnova diverges

The rule is Laravel's `preventLazyLoading`. Two behaviours differ:

- `refresh()` replaces the row with a fresh `find`, so the row loses its
  mark. Laravel keeps it.
- `cursor()` and `lazy()` hydrate in batches, so their rows are marked.
  Laravel's `cursor()` hydrates one row at a time and marks nothing.

## Pagination

Three paginator types compose on top of `Builder<M>`:

| Method | Returns | Queries per page | Use when |
|--------|---------|------------------|----------|
| `paginate(per_page)` | `LengthAwarePaginator<M>` | 2 (COUNT + LIMIT) | UI needs total page count |
| `simple_paginate(per_page)` | `Paginator<M>` | 1 (LIMIT + 1) | Large tables; "Next" button only |
| `cursor_paginate(per_page)` | `CursorPaginator<M>` | 1 (LIMIT + 1) | Infinite scroll; deep pagination |

All three implement `Serialize` with the Laravel-standard JSON shape,
so they ship directly to Inertia / JSON consumers without reshaping.

### Length-aware

```rust
use suprnova::LengthAwarePaginator;

let page: LengthAwarePaginator<User> = User::query()
    .filter("active", true)
    .order_by_desc("created_at")
    .paginate(20)
    .await?;

// page.data: Vec<User>
// page.total: u64 - total row count across all pages
// page.last_page: u64 - 1-based last page index
// page.current_page: u64
// page.per_page: u64
// page.from / page.to: Option<u64> - 1-based window bounds
// page.path: Option<String> - optional base URL for link generation
```

Page-param parsing reads `?page=N` from the active request via
`Context::query_param`. To paginate multiple lists on the same page
with their own query keys, use `paginate_using`:

```rust
let posts = Post::query().paginate_using("posts_page", 10).await?;
let comments = Comment::query().paginate_using("comments_page", 25).await?;
```

**JSON shape** (with `with_path("/api/users")`, page 1 of 3):

```json
{
  "current_page": 1,
  "data": [...],
  "first_page_url": "/api/users?page=1",
  "from": 1,
  "last_page": 3,
  "last_page_url": "/api/users?page=3",
  "links": [...],
  "next_page_url": "/api/users?page=2",
  "path": "/api/users",
  "per_page": 10,
  "prev_page_url": null,
  "to": 10,
  "total": 25
}
```

`path` is omitted from JSON when unset. The fields are Laravel's, and
`links` is the row of page links. See [Pagination](pagination.md) for the
`links` entries and the page URLs.

### Simple paginate (no count)

`paginate` always runs two queries - a `COUNT(*)` plus the page
fetch. On large tables the count alone can dominate request time.
`simple_paginate` skips the count entirely; instead it fetches
`per_page + 1` rows and reports whether a next page exists via the
`has_more` flag:

```rust
use suprnova::Paginator;

let page: Paginator<User> = User::query()
    .order_by_desc("id")
    .simple_paginate(20)
    .await?;

// page.has_more: bool - was there an extra row past per_page?
// page.current_page, page.per_page, page.data, page.path: as above.
```

**JSON shape** (with `with_path("/api/users")`, page 1):

```json
{
  "current_page": 1,
  "current_page_url": "/api/users?page=1",
  "data": [...],
  "first_page_url": "/api/users?page=1",
  "from": 1,
  "has_more": true,
  "next_page_url": "/api/users?page=2",
  "path": "/api/users",
  "per_page": 10,
  "prev_page_url": null,
  "to": 10
}
```

### Cursor paginate (keyset)

Cursor paginate is the choice for infinite scroll, deep pagination,
or anywhere a stable row order with cheap O(1)-per-page seeking is
worth more than a numeric page UI. Bidirectional - it reads the
`?cursor=<opaque>` query parameter, walks forward or backward by the
cursor's direction, and emits both `next_cursor` and `prev_cursor` as
the page's neighbours exist (matching Laravel's `cursorPaginate()`).

```rust
use suprnova::CursorPaginator;

let page: CursorPaginator<User> = User::query()
    .cursor_paginate(20)
    .await?;

// page.data: Vec<User>
// page.per_page: u64
// page.next_cursor: Option<String> - opaque cursor for the next page (None on the last)
// page.prev_cursor: Option<String> - opaque cursor for the previous page (None on the first)
// page.path: Option<String>
```

Cursors are **encrypted and authenticated** via `CursorPaginator::encode_value` -
they encode the keyset boundary (each ordered column's value, the
model's primary key among them) plus a direction tag, AES-256-GCM-sealed
with the framework's `APP_KEY`.
Tampering produces a 400 ParamParse error; the cursor is opaque to
the client and unforgeable without the key.

The next request passes the cursor through `?cursor=<opaque>`:

```
GET /api/users?cursor=eyJ0IjoiQmlnSW50IiwidiI6MTAwLCJkIjoibmV4dCJ9...
```

Cursor pagination keeps the builder's `ORDER BY`, as Laravel's
`cursorPaginate` does: `latest()` pages newest first, and a descending
order walks downward. The primary key, ascending, breaks ties when no
order names it, and a builder with no order walks the primary key
ascending. An order the cursor cannot carry (`order_by_raw`,
`in_random_order`) returns a 400 error. See
[Pagination](pagination.md#how-cursors-work-on-the-wire).

**JSON shape:**

```json
{
  "data": [...],
  "path": "/api/users",
  "per_page": 10,
  "next_cursor": "...",
  "next_page_url": "/api/users?cursor=...",
  "prev_cursor": null,
  "prev_page_url": null
}
```

`next_cursor`, `next_page_url`, `prev_cursor`, and `prev_page_url` are
always present as JSON keys (emitted as `null` when absent) so client
schemas can rely on the field's presence; `path` is omitted when unset.
A page URL is the `path` with the cursor in the `cursor` key.

### Errors

| Condition | Variant | HTTP |
|-----------|---------|------|
| `per_page == 0` | `FrameworkError::ParamError { param_name: "per_page" }` | 400 |
| Invalid cursor (bad base64, JSON, or HMAC fails) | `FrameworkError::Internal` from `Crypt::decrypt_string` | 500 |
| Underlying DB failure | `FrameworkError::Database` | 500 |

Cursor authentication failure surfaces as `Internal` (not
`ParamParse`) so a tampered cursor doesn't leak protocol-level
information to the client; the response body still carries a
human-readable reason.

### Reading query params outside a real request

Tests, console commands, and background workers don't run inside a
hyper request - so `Context::query_param("page")` returns `None` and
`paginate` falls back to page 1. Tests that need to exercise a
specific page can install a per-thread override:

```rust
use suprnova::context::Context;

#[tokio::test]
async fn paginate_page_2() {
    Context::test_clear_query();
    Context::test_set_query("page", "2");

    let page = User::query().paginate(10).await.unwrap();
    assert_eq!(page.current_page, 2);

    Context::test_clear_query();
}
```

`test_set_query` / `test_clear_query` are gated behind the
`testing` feature (default-enabled in `framework/Cargo.toml`) so
release builds never see this surface.

## Chunking and lazy iteration

Seven streaming entry points on `Builder<M>` let you process large
result sets in bounded memory. Pick by trade-off:

| Method | Pagination | Concurrent-safe? | Returns |
|--------|-----------|------------------|---------|
| `chunk(n, async \|batch\| { ... })` | OFFSET | No | `Result<(), _>` |
| `chunk_by_id(n, async \|batch\| { ... })` | PK cursor | **Yes** | `Result<(), _>` |
| `chunk_map(n, async \|batch\| { ... })` | OFFSET | No | `Collection<U>` |
| `each(async \|row\| { ... })` | OFFSET, size 1 | No | `Result<(), _>` |
| `lazy()` | PK cursor, batch 1000 | **Yes** | `LazyCollection<M>` |
| `lazy_by_id(batch_size)` | PK cursor, custom batch | **Yes** | `LazyCollection<M>` |
| `cursor()` | Alias for `lazy()` | **Yes** | `LazyCollection<M>` |

### chunk - OFFSET-paginated batches

```rust
use suprnova::{Collection, Model};

User::query().chunk(100, |batch: Collection<User>| async move {
    for user in &batch {
        send_welcome_email(user).await?;
    }
    Ok(())
}).await?;
```

The closure receives a `Collection<M>` per batch - slice-shape access
(`.iter()`, indexing) works directly via `Deref`.

`chunk`, `chunk_map`, and `each` keep the query's own `OFFSET` and
`LIMIT`, as Laravel's `chunk` does: the offset skips rows once, at the
start of the walk, and the limit caps the rows the whole walk visits.

`chunk` is OFFSET-paginated and **not safe under concurrent inserts**:
rows inserted before the next batch's offset get skipped; rows deleted
before the offset get processed twice (whatever shifted into their
slot). Use `chunk_by_id` for production-grade bulk processing against
tables under write load.

### chunk_by_id - PK-cursor batches, concurrent-safe

```rust
User::query().chunk_by_id(500, |batch| async move {
    for user in &batch {
        reindex_user(user).await?;
    }
    Ok(())
}).await?;
```

Each batch filters on `WHERE id > last_id ORDER BY id ASC LIMIT n`,
so rows inserted mid-iteration with PKs above the cursor land in a
later batch (or are picked up by a subsequent run) - they never cause
an original row to skip or duplicate.

The walk sets its own order. An `ORDER BY` already on the query is
dropped, because any other order would make the cursor skip some rows
and repeat others. An `OFFSET` on the query skips that many rows once,
before the first batch; every later batch starts at the cursor. A
`LIMIT` on the query caps the rows the whole walk visits, as in
Laravel's `chunkById`: `.limit(10).chunk_by_id(3, ..)` hands over 3, 3,
3 and 1 rows.

The cursor is the value of the primary key, in the order of the key.
These keys work:

- An integer key (`i64`, `i32`, and the other integer types).
- A text key: `String`, and the keys of `unique_id = "uuid"`,
  `"uuid_v4"` and `"ulid"`, which the model stores as text.

For a key that grows with the creation time of its row (auto-increment,
UUID v7, ULID), a row inserted mid-run lands after the cursor, and a
later batch finds it. A random key (UUID v4) has no such order: a row
inserted mid-run with a key below the cursor is not seen by that walk,
and the next run picks it up. Every row that existed when the walk
started is seen once.

`chunk_by_id` refuses a key that cannot carry the cursor with
`FrameworkError::internal`. The error names the model and the column and
never the value of the key. Two cases are refused before the first
query:

- A composite key.
- A key column that is neither an integer nor text, such as a native
  `uuid::Uuid` column, a timestamp or a decimal.

A third case is found while the walk runs. A row whose key is null, or is
not of the kind of its column, ends the walk with the same error. The
check runs on each batch before the closure sees it, so the closure never
processes a batch that holds such a row.

A `u64` key walks its whole range. On MySQL, whose unsigned keys reach
`u64::MAX`, that includes keys above `i64::MAX`; on Postgres and SQLite no
key passes `i64::MAX`.

For a key that `chunk_by_id` refuses, use `chunk()`. It paginates by
OFFSET, so it needs no cursor, and it has the concurrency limits above.

### chunk_map - chunk + per-chunk map

```rust
let totals: Collection<i64> = Order::query()
    .chunk_map(1000, |batch| async move {
        let sum: i64 = batch.iter().map(|o| o.amount).sum();
        Ok(Collection::from_vec(vec![sum]))
    })
    .await?;
```

Maps each batch through `f`, concatenates the mapped output, and
returns a single `Collection<U>`. Memory-bounded only when `U` is
strictly smaller than `M` - pick this when you're producing summaries
(per-batch totals, ids, aggregates) rather than transformed rows.

### each - one row at a time, OFFSET

```rust
User::query().each(|user| async move {
    send_welcome_email(&user).await?;
    Ok(())
}).await?;
```

Sugar for `chunk(1, ...)` - one query per row. For large datasets,
switch to `lazy()` which batches internally (default 1000 rows per
fetch) while still surfacing one row at a time to the consumer.

### lazy / lazy_by_id / cursor - streams

```rust
let mut stream = User::query().lazy();
while let Some(row) = stream.next().await {
    let user = row?;
    println!("{}", user.email);
}
```

`lazy()` returns a `LazyCollection<M>` - a `Send` stream wrapper
that yields `Result<M, FrameworkError>` per row. Backpressure works
naturally: a slow consumer parks at the `await` point and the next
batch only fetches when the in-memory buffer drains.

`lazy()` batches via PK cursor with a default size of 1000 rows.
Override the batch size with `lazy_by_id(500)`. `cursor()` is the
Laravel name and is a zero-cost alias for `lazy()`.

`lazy()`, `lazy_by_id()` and `cursor()` use the same keyset cursor as
`chunk_by_id`, so the same keys work, the same keys are refused, and an
`ORDER BY` or `OFFSET` on the query is treated the same way. The
error is the first item of the stream. Refusal by column type happens
before the first query. A row with a null or mismatched key is refused
when its batch arrives, before the stream yields any row of that batch.

### Eager loads inside chunks

All seven entry points **reject `.with(...)` up front** with a loud
`FrameworkError::internal`. The Builder's cross-batch clone drops
the type-erased eager-load plan (its boxed-`dyn Any` predicate isn't
clonable without tightening the public API), so honouring the plan
would be silently inconsistent across batches. Re-apply `.with(...)`
inside the per-chunk closure when needed - each batch's
`Collection<M>` composes with `load(...)` / `load_missing(...)`:

```rust
User::query().chunk(100, |batch| async move {
    let mut batch = batch;
    batch.load("posts").await?;
    for u in &batch {
        let posts = u.posts_loaded();
        // ...
    }
    Ok(())
}).await?;
```

## Collections

`Collection<T>` is Suprnova's Laravel-shape collection - the return
type of `Builder::get` (where `T` is the model), of `Model::all`, of
`pluck` / `chunk_map`, and of every other terminal that yields more
than one row. It dereferences to `&[T]` so existing Vec call sites
keep working without changes; the Laravel surface is composed on top.
This section is the everyday surface; the full method index, the
generic-vs-model split, the `LazyCollection<M>` streaming wrapper,
and the borrow-vs-consume rules are in
[Eloquent Collections](eloquent-collections.md).

### Generic surface

Available on every `Collection<T>` regardless of `T`:

```rust
use suprnova::Collection;

let nums: Collection<i32> = Collection::from_vec(vec![3, 1, 4, 1, 5, 9]);

nums.first();              // Some(&3)
nums.last();               // Some(&9)
nums.len();                // 6
nums.is_empty();           // false
nums.contains(&4);         // true
// Predicate closures receive `&&T` - note the double-deref `**n`:
nums.first_where(|n| **n > 3);    // Some(&4)
nums.contains_where(|n| **n > 8); // true
// For a count, run the predicate inline: `nums.iter().filter(|n| **n > 2).count()` - 4
```

Transformations consume `self` and return a new `Collection`:

```rust
let doubled: Collection<i32> = nums.clone().map(|n| n * 2);
let evens:   Collection<i32> = nums.clone().filter(|n| n % 2 == 0);
let chunks:  Vec<Collection<i32>> = nums.clone().chunk(2); // [[3,1],[4,1],[5,9]]
let unique:  Collection<i32> = nums.clone().unique();
let sorted:  Collection<i32> = nums.clone().sort();
```

### Model-aware methods on `Collection<M>`

When `T` is a model, additional string-keyed methods route through
the macro-emitted `field_value(name)` accessor:

```rust
let users: Collection<User> = User::query().get().await?;

let emails: Collection<String> = users.pluck::<String>("email");
let by_role: HashMap<String, Vec<User>> =
    users.clone().group_by::<String>("role");
let active: Collection<User> = users.clone().where_eq("active", true);

let total: f64 = users.clone().sum::<f64>("balance");
let avg:   f64 = users.clone().avg::<f64>("balance");
let max:   Option<i64> = users.clone().max::<i64>("login_count");
```

The closure-based `pluck_by` is the typed alternative - useful when
the field name would otherwise require a string lookup the type
system can't check:

```rust
let names: Collection<String> = users.pluck_by(|u| u.name.clone());
```

Per-row `field_value(name)` returns `Option<serde_json::Value>` -
`None` when the column name doesn't match any declared field. Custom
casts that fail to serialise also surface as `None`. The string-keyed
methods silently skip those rows; the closure form short-circuits in
the closure body so the caller can decide.

### Streaming via `LazyCollection`

For datasets too large to materialise, `Builder::lazy()` /
`lazy_by_id(n)` / `cursor()` return a `LazyCollection<M>` - a
`Stream` wrapper that fetches rows in PK-cursor batches. See
[Chunking and lazy iteration](#chunking-and-lazy-iteration).

### Eager loading on a collection

`Collection::load(["posts"])` / `load_missing(["posts"])` execute
the same eager-load dispatch a `Builder::with(...)` chain emits,
but against an existing collection. `load_missing` is per-row: each
row in the collection is partitioned into "needs load" / "already
loaded" buckets and only the missing ones get the bulk-load. See
[Eager loading](#eager-loading).

## Mass assignment

### Fillable allowlist

```rust
#[model(
    table = "users",
    fillable = ["name", "email"],
)]
pub struct User { /* ... */ }

User::create(attrs! {
    name: "Alice",
    email: "alice@example.com",
    admin: true,    // silently dropped at runtime - not in fillable
}).await?;
```

### Guarded denylist

`guarded` is the inverse - every field is fillable EXCEPT the
guarded ones. Mutually exclusive with `fillable`; using both at
once is a compile-time error from the macro.

```rust
#[model(
    table = "posts",
    guarded = ["id", "user_id"],   // everything else is fillable
)]
pub struct Post { /* ... */ }
```

### Default policy

When neither `fillable` nor `guarded` is set, the default policy is
`guarded = ["id"]` (or whatever `primary_key = "..."` resolves to) -
every field is fillable except the primary key. This matches
Laravel's "all fields fillable except the PK" default.

### `unguarded(closure)` escape hatch

`unguarded(closure)` turns off the filter for a block:

```rust
use suprnova::eloquent::unguarded;

// Bypass the filter for a one-shot data-migration script:
unguarded(|| async {
    User::create(attrs! {
        name: "Bootstrap",
        email: "boot@example.com",
        admin: true,    // assignable inside the closure
    }).await
}).await?;
```

Implementation: a `tokio::task_local!` boolean the `Fillable::apply`
filter checks before running. Task-local means concurrent requests
aren't affected by another task's `unguarded` scope.

## Casts

Casts run at the boundary between storage (column value) and runtime
(model field). Each cast type implements the `Cast` trait. Built-in
casts cover Laravel's full set; users register custom casts via the
trait. This section is the quick-reference index; the full per-cast
contract - primitive, temporal, structured, enum, encrypted, hashed,
plus the `casts!` runtime override macro - lives in
[Eloquent Casts, Accessors & Mutators](eloquent-mutators.md).

### Explicit, with two defaults

Casts are declared in `#[model(casts = { ... })]`. A `prefs: Json` field
doesn't implicitly become `AsJson`; you write `casts = { prefs = AsJson }`.
Rationale: you should be able to read the model and know exactly what runs
at storage boundaries.

Two field types get a cast without one, because they don't work without it.
A field's own cast wins over both:

- A `DateTime<Utc>` or `Option<DateTime<Utc>>` field gets `AsDateTime` or
  `AsOptionalDateTime`, which store text. `datetime_cast` in the package's
  `Cargo.toml` swaps them for the native casts; see
  [Native date-time casts](eloquent-mutators.md#native-date-time-casts).
- A `u64` or `Option<u64>` field, the key included, gets `AsU64` or
  `AsOptionalU64`. SeaORM reads a `u64` on MySQL only; the cast reads it on
  Postgres and SQLite too, where it holds `0` to `i64::MAX`. For more
  information, see
  [Laravel tables on MySQL](migrations.md#laravel-tables-on-mysql).

### Example

```rust
use suprnova::{model, AsArray, AsBool, AsCollection, AsDate, AsDateTime,
    AsEncrypted, AsEnum, AsObject, AsTimestamp};

#[model(
    table = "users",
    casts = {
        active        = AsBool,
        preferences   = AsArray<String>,
        options       = AsObject<UserOptions>,
        profile       = AsCollection<ProfileField>,
        birthday      = AsDate,
        last_seen_at  = AsDateTime,
        role          = AsEnum<UserRole>,
        api_token     = AsEncrypted,
    },
)]
pub struct User { /* ... */ }
```

### Full Laravel cast list and Suprnova mapping

| Laravel cast | Suprnova cast | Runtime type |
|--------------|---------------|--------------|
| `bool`, `boolean` | `AsBool` | `bool` |
| `int`, `integer` | `AsInt<I>` | `I: PrimInt` |
| `float`, `double`, `real` | `AsFloat` | `f64` |
| `decimal:N` | `AsDecimal<N>` | `rust_decimal::Decimal` |
| `string` | `AsString` | `String` |
| `array` | `AsArray<T>` | `Vec<T>` (JSON-encoded) |
| `array` (nullable column) | `AsOptionalArray<T>` | `Option<Vec<T>>` (`None` is SQL `NULL`) |
| `object` | `AsObject<T>` | `T: Serialize + DeserializeOwned` |
| `object` (nullable column) | `AsOptionalObject<T>` | `Option<T>` |
| `collection` | `AsCollection<T>` | `Collection<T>` |
| `collection` (nullable column) | `AsOptionalCollection<T>` | `Option<Collection<T>>` |
| `json` | `AsJson<T>` | `T` (raw JSON column) |
| `json` (nullable column) | `AsOptionalJson<T>` | `Option<T>` |
| `date`, `date:format` | `AsDate` | `chrono::NaiveDate` |
| `datetime`, `datetime:format` | `AsDateTime` | `chrono::DateTime<Utc>` |
| `datetime` (nullable column) | `AsOptionalDateTime` | `Option<chrono::DateTime<Utc>>` |
| `datetime` (native column with a zone) | `AsNativeDateTime` | `chrono::DateTime<Utc>` |
| `datetime` (nullable native column with a zone) | `AsOptionalNativeDateTime` | `Option<chrono::DateTime<Utc>>` |
| `datetime` (native column without a zone) | `AsNaiveDateTime` | `chrono::DateTime<Utc>` (stored as the UTC wall clock) |
| `datetime` (nullable native column without a zone) | `AsOptionalNaiveDateTime` | `Option<chrono::DateTime<Utc>>` |
| `immutable_date` | `AsImmutableDate` | `chrono::NaiveDate` |
| `immutable_datetime` | `AsImmutableDateTime` | `chrono::DateTime<Utc>` |
| `timestamp` | `AsTimestamp` | `i64` (unix epoch) |
| `encrypted` | `AsEncrypted` | `String` (encrypted via `Crypt`) |
| `encrypted:array` | `AsEncryptedArray<T>` | `Vec<T>` (JSON + encrypted) |
| `encrypted:object` | `AsEncryptedObject<T>` | `T` (JSON + encrypted) |
| `encrypted:collection` | `AsEncryptedCollection<T>` | `Collection<T>` |
| `EnumClass::class` | `AsEnum<E>` | `E: EnumString + AsRefStr` |
| `AsArrayObject::class` | `AsArrayObject<T>` | `IndexMap<String, T>` |
| `AsArrayObject::class` (nullable column) | `AsOptionalArrayObject<T>` | `Option<IndexMap<String, T>>` |
| `hashed` | `AsHashed` | `String` (`Hash::make` on write; never decrypts) |

31 casts total. Most map one-to-one with Laravel. A Laravel cast passes
`null` through on any column; in Rust the field type says whether a
value can be missing, so the five JSON casts and three of the
date-time casts have `AsOptional*` forms for nullable columns. The
`AsOptionalDateTime` (used by `soft_deletes`) is auto-injected by
the macro when the soft-delete column is `Option<DateTime<Utc>>`.

### Encrypted cast failure modes

The four `AsEncrypted*` casts route every encrypt/decrypt through the
`Crypt` facade (keyed by `APP_KEY`). When decryption fails - wrong
key, truncated ciphertext, tampered bytes, AEAD tag mismatch - the
cast surfaces a clear `FrameworkError::Internal` from
`Cast::from_storage`. There is no silent fallback to garbage:

- Loading a row through `Model::find` / `Model::query()` propagates
  the decrypt error and (per the macro-generated `From<inner::Model>`)
  panics with `cast from_storage failed - corrupt data in database
  column`. Operators see the failure in logs immediately; the model
  never carries plausible-but-wrong plaintext.
- The `AsHashed` cast is one-way; it never decrypts so this failure
  mode does not apply.

This matches Laravel's `encrypted` cast: a wrong `APP_KEY` against an
existing encrypted column is a hard error, never a quiet
`null`/empty string.

### Rotating `APP_KEY`

Suprnova supports zero-downtime key rotation via a key *ring*: the
current `APP_KEY` encrypts; an optional `APP_KEY_PREVIOUS` env var
(comma-separated, oldest-to-newest) supplies decrypt fallbacks for
data written under older keys. Encryption *always* uses the current
key - previous keys participate only on decrypt.

Each decrypt that falls through to a previous key emits a
`tracing::warn!` line containing the previous-key index. The log
payload deliberately excludes plaintext and ciphertext; just the
fact-of-rotation plus an actionable re-encrypt hint.

**Rotation procedure** (zero-downtime, safe for production):

1. Mint a new key: `suprnova key:generate` (writes to stdout).
2. Move the old key to `APP_KEY_PREVIOUS` and set `APP_KEY` to the
   new value:
   ```
   APP_KEY_PREVIOUS=<old_key>
   APP_KEY=<new_key>
   ```
3. Deploy. New writes use the new key; existing rows continue to
   decrypt via the previous-key fallback. Warnings in logs identify
   columns that still depend on `APP_KEY_PREVIOUS`.
4. Run a re-encrypt pass. You explicitly update each encrypted attribute:
   ```rust
   User::query().chunk(500, |batch| async move {
       for user in batch {
           let token = user.api_token.clone();
           user.update(attrs! { api_token: token }).await?;
       }
       Ok::<(), suprnova::FrameworkError>(())
   }).await?;
   ```
   You use an explicit update because a clean save writes no columns.
   The cast encrypts the supplied attribute under the current key.
5. Once logs show no more `APP_KEY_PREVIOUS` warnings (give the
   batch + any soft-deleted / archived data a generous window),
   remove `APP_KEY_PREVIOUS` from the environment and redeploy.

**Multi-step rotation.** If you rotate again before completing the
previous pass, append: `APP_KEY_PREVIOUS=<oldest>,<previous>`. The
ring tries every previous key in order. The list is capped at
8 entries - a realistic chain is 1-3 (one in-flight rotation, maybe
one stalled prior roll) and a longer list is almost always a config-
templating accident; exceeding the cap fails boot with an actionable
diagnostic rather than silently dropping a key the operator may still
depend on.

**Constraints.**

- A malformed entry in `APP_KEY_PREVIOUS` fails boot loudly (same as
  a malformed `APP_KEY`) - a half-rotated secret should never
  silently degrade.
- More than 8 entries in `APP_KEY_PREVIOUS` fails boot loudly -
  see [`suprnova::crypto::MAX_PREVIOUS_KEYS`].
- Empty entries in the list (e.g. trailing commas from templated
  config) are tolerated as "no key in this slot" - not an error.
- The wire format is unchanged from the pre-rotation single-key
  layout: no key identifier is embedded in the ciphertext. The ring
  trial-decrypts each key in order until one succeeds.

### Runtime cast override - `with_casts`

```rust
let users = User::query()
    .with_casts(suprnova::casts! { birthdate = AsDateTime })
    .get()
    .await?;
```

`with_casts` overrides the model's declared casts for the duration
of a single query - useful when a raw column comes back from a
join / view / `select_raw` and needs a different type coercion
than the model's default.

### Custom casts

Custom casts implement `Cast`:

```rust
use suprnova::eloquent::casts::Cast;
use suprnova::FrameworkError;

pub struct AsAesGcmJson<T>(std::marker::PhantomData<T>);

impl<T: serde::Serialize + serde::de::DeserializeOwned + Send + Sync> Cast
    for AsAesGcmJson<T>
{
    type Runtime = T;
    type Storage = String;
    fn to_storage(value: &T) -> Result<String, FrameworkError> { /* ... */ }
    fn from_storage(stored: &String) -> Result<T, FrameworkError> { /* ... */ }
}

#[model(casts = { secret = AsAesGcmJson<SecretBundle> })]
pub struct Vault { /* ... */ }
```

The `Cast` trait is shipped alongside the primitive casts. Custom
casts can use either `String` storage (when JSON-encoding) or any
of the SeaORM-supported scalar types (`i64`, `f64`, `bool`,
`Vec<u8>`).

## Accessors and mutators

### Accessors

```rust
#[model(
    table = "users",
    appends = ["full_name"],
)]
pub struct User {
    pub id: i64,
    pub first_name: String,
    pub last_name: String,
    // ...
}

impl User {
    #[accessor]
    pub fn full_name(&self) -> String {
        format!("{} {}", self.first_name, self.last_name)
    }
}
```

When `user.to_array()` runs (or `user.to_json()`, which delegates
to it), the `full_name` accessor is called and its return value
is inserted into the JSON output. Calling `user.full_name()` from
Rust is just a regular method call.

### Mutators

Mutators run before storage:

```rust
#[model(
    table = "users",
    fillable = ["first_name", "last_name", "password"],
    mutators = ["password"],
)]
pub struct User { /* ... */ }

impl User {
    #[mutator]
    pub fn set_password(
        &mut self,
        value: serde_json::Value,
    ) -> Result<(), suprnova::FrameworkError> {
        let raw: String = serde_json::from_value(value).map_err(|e| {
            suprnova::FrameworkError::validation("password", format!("{e}"))
        })?;
        self.password = hash::make(&raw);
        Ok(())
    }
}
```

Calling `user.password = "secret".into()` directly assigns the raw
value without running the mutator. To run the mutator path, call
`user.set_password(json!("secret"))` or use the JSON path
(`user.fill(attrs!{password: "secret"})`), which routes through
the mutator automatically because `"password"` is listed in
`mutators = [...]`.

### How routing works

- **Serialization (`to_array` → `Value`, `to_json` → `String`)**
  runs accessors. Every field name listed in `appends = [...]`
  becomes a call to `self.<name>()`; the return value is inserted
  into the JSON output. `to_json()` is a thin wrapper:
  `serde_json::to_string(&self.to_array())`.
- **Fill-style writes (`fill`, `create`, `update`)** route through
  mutators. Every field name listed in `mutators = [...]` becomes a
  call to `self.set_<field>(value)` instead of direct assignment.

The function-level `#[accessor]` and `#[mutator]` macros emit
registry entries the macro's serialization / fill paths walk.

### Malformed values are errors, not defaults

A value that cannot decode into its field's type fails the write and
names the field:

```rust
let err = user.fill(attrs! { age: "not a number" }).unwrap_err();
// ValidationError { field: "age", message: "could not decode the
// supplied value: invalid type: string \"not a number\", expected i32" }
```

The model is left untouched - a rejected `fill` applies nothing.

Two nearby cases behave differently, on purpose:

- An **unknown column** is still skipped silently, matching Laravel's
  `$model->fill()`. Not knowing about a column is not the same as
  being handed a broken value for one you do know.
- A column excluded by `fillable` / `guarded` is dropped by the
  mass-assignment filter *before* decoding, so a malformed value for a
  field the caller may not set is also silent. Erroring there would
  tell an unauthorised caller which columns exist.

Numeric widening is not a type error: a JSON integer decodes into an
`f64` field normally.

> Before v0.8.0 a malformed value was silently replaced by the field's
> `Default` and the call returned `Ok` - `fill(attrs!{ age: "abc" })`
> set `age = 0` and reported success. If you were relying on that
> coercion, validate or convert before calling `fill`.

### Hidden / visible

```rust
#[model(
    table = "users",
    hidden = ["password", "remember_token"],
)]
pub struct User { /* ... */ }
```

`hidden = [...]` is a denylist - every column except the listed
ones serialises. `visible = [...]` is the inclusive form - only the
listed ones serialise. Mutually exclusive at compile time.

## Timestamps

When both `created_at` and `updated_at` columns exist, the macro
auto-detects them and enables timestamp tracking:

- `created_at` is set to `Utc::now()` on `save()` for new rows.
- `updated_at` is set to `Utc::now()` when a dirty `save()` writes. A clean
  save leaves the timestamp unchanged.

The auto-detect is conservative: if the struct has only one of the
two columns, the macro errors out so a typo
(`craeted_at`) doesn't silently disable timestamps. Set
`timestamps = false` to opt out entirely.

A struct with neither column gets no timestamps by default. If you ask
for them with `timestamps = true` (or the bare `timestamps` flag), the
build fails and the error names both columns, as
`#[suprnova::document]` does, so a model never silently writes none.

### Disabling auto-timestamps

```rust
#[model(table = "audit_logs", timestamps = false)]
pub struct AuditLog {
    pub id: i64,
    pub event: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    // No updated_at field - but timestamps = false silences the
    // macro's `only one column found` error too.
}
```

### `touch()` - bump updated_at without other changes

```rust
user.touch().await?;
```

`touch()` issues `UPDATE table SET updated_at = ? WHERE pk = ?` -
atomic, no read-modify-write. The macro emits a `Touchable` impl on
every timestamped model.

### Parent touching

```rust
#[model(
    table = "comments",
    touches = ["post"],
    relations = {
        post: BelongsTo<Post> { fk = "post_id" },
    },
)]
pub struct Comment {
    pub id: i64,
    pub post_id: i64,
    // ...
}
```

After a comment is created, saved, updated, or deleted, its post's
`updated_at` is bumped - one
`UPDATE posts SET updated_at = ? WHERE id = ?`, no SELECT. That is what
a cache key hanging off `post.updated_at` needs to stay honest when
only a child changed.

Every name in `touches` must be a `BelongsTo` or a `MorphTo` relation
declared in the same `relations = { ... }` block. A name that doesn't
resolve, or one that resolves to a different relation kind, is a compile
error rather than a surprise on the first save.

A `MorphTo` name touches the owner that the row's `<name>_type` and
`<name>_id` columns point at:

```rust
#[model(
    table = "comments",
    touches = ["commentable"],
    relations = {
        commentable: MorphTo { targets = [Post, Video] },
    },
)]
pub struct Comment {
    pub id: i64,
    pub commentable_id: i64,
    pub commentable_type: String,
    // ...
}
```

The write finds the owner after the pre-write listeners (`Creating`,
`Saving`, `Updating`, `Deleting`) have run and before the statement, from
the values the statement writes. A listener that rewrites `<name>_type`
or `<name>_id` therefore decides which owner is touched. A
`<name>_type` that names none of the targets makes the write fail: the
write returns `Err`, no row is written, no post-write event is
dispatched and no owner is touched.

An owner whose model has `timestamps = false` is **skipped**: no error,
no write, and the child's save still returns `Ok`. Same for an owner
reached through a `NULL` foreign key or a `NULL` `<name>_id`, and for a
soft-deleted owner.

The touch runs on the same executor as the write that triggered it, so
inside a `DB::transaction` closure it joins that transaction and a
rollback reverts it.

### Why Suprnova diverges

Laravel's `touchOwners` loads each parent model and recurses, so a
comment save also bumps the post's own owners and fires each parent's
`saved` event. Suprnova resolves the parent through the relation
registry and writes the column directly - one statement per touched
relation, no hydration. The cascade is therefore one level deep and
fires no parent events. That is the trade for a save that doesn't issue
a SELECT per touched relation. Reach for an observer when you need the
grandparent bump or the event.

`restore()` on a soft-deleted child does not touch its owners.
Laravel's `restore` goes through `save`; Suprnova's is a direct
`UPDATE deleted_at = NULL`.

### Format

Always ISO 8601 with UTC. No `Model::$timestampsFormat` override
(per the divergence-from-Eloquent table - frontend interop comes
first; locale formatting belongs in the i18n layer).

## Observers and lifecycle events

Every model goes through a fixed 16-event lifecycle as it moves
through `create` / `save` / `update` / `delete` / `restore` /
`replicate` / Builder query paths. Listeners can hook each event
to log, audit, side-effect, validate, or cancel the in-flight
operation.

### The 16 lifecycle events

Events split into two groups by cancellability:

**Cancellable (5)** - fire BEFORE the database write. A listener
returning `EventResult::cancel("reason")` aborts the operation with
`FrameworkError::bad_request(reason)`.

| Event       | When                                      | Payload                                                 |
|-------------|-------------------------------------------|---------------------------------------------------------|
| `Saving`    | Before both `create` and `save`           | `Arc<Mutex<Attrs>>` + `is_creating: bool`               |
| `Creating`  | Before `create`                           | `Arc<Mutex<Attrs>>`                                     |
| `Updating`  | Before `save` / `update` on existing row  | Pre-update model snapshot + `Arc<Mutex<Attrs>>`         |
| `Deleting`  | Before `delete` (soft or hard)            | Model + `is_force: bool` (force-delete on soft-delete)  |
| `Restoring` | Before `restore` on soft-delete model     | Model                                                   |

**Non-cancellable (11)** - fire AFTER the operation. Listener errors
propagate but cannot stop a write that already landed.

| Event           | When                                              | Payload                          |
|-----------------|---------------------------------------------------|----------------------------------|
| `Retrieving`    | Once per Builder query, before the DB call        | None                             |
| `Retrieved`     | Once per row returned by a Builder query          | Model                            |
| `Created`       | After successful `create`                         | Model                            |
| `Updated`       | After successful `save` / `update`                | Previous + current snapshots     |
| `Saved`         | After both `create` and `save`                    | Model                            |
| `Deleted`       | After successful `delete`                         | Model + `is_force: bool`         |
| `Trashed`       | After soft-delete (NOT force-delete)              | Model                            |
| `Restored`      | After successful `restore`                        | Model                            |
| `Replicating`   | During `replicate` / `replicate_except`, before return (NOT `replicate_into` - per-source-type) | Source + `Arc<Mutex<replica>>` (mutable) |
| `ForceDeleting` | Before `force_delete` on soft-delete model        | Model                            |
| `ForceDeleted`  | After successful `force_delete`                   | Model                            |

The cancellable / non-cancellable split mirrors Laravel's `creating`
vs `created` hook pair. `Saving` fires for both insert and update -
override that one when the behaviour is identical across both paths
and discriminate via `is_creating`.

`Replicating` is the one non-cancellable hook that hands a mutable
reference (the replica is `Arc<Mutex<M>>`). Use it to clear
timestamps, regenerate UUIDs, reset auto-increments, etc. before the
clone is returned to the caller.

### Observers vs raw listeners

Two ways to hook lifecycle events:

1. **Raw listeners** - call `EventFacade::listen::<Created, _>(Arc::new(MyListener))`
   for each event you want, one impl per event. This is the
   underlying mechanism; observers ride on top of it.

2. **Observers** - bundle all 16 hooks under one trait. The macro
   sees which methods the user overrode and registers exactly those.
   This is the recommended path for any non-trivial set of hooks.

```rust
use async_trait::async_trait;
use suprnova::eloquent::attrs::Attrs;
use suprnova::eloquent::events::EventResult;
use suprnova::eloquent::observers::Observer;
use suprnova::FrameworkError;

pub struct AuditObserver;

#[suprnova::observer(User)]   // <- MUST precede #[async_trait]
#[async_trait]
impl Observer<User> for AuditObserver {
    async fn creating(&self, attrs: &mut Attrs) -> EventResult {
        if attrs.get("email").is_none() {
            return EventResult::cancel("email is required");
        }
        EventResult::ok()
    }

    async fn created(&self, user: &User) -> Result<(), FrameworkError> {
        tracing::info!(user.id = user.id, "user created");
        Ok(())
    }
}
```

Every trait method has a default no-op, so the impl block contains
only the events you care about. The macro identifies overrides by
name match against the closed 16-method set; methods you don't
override register no listeners.

### Required attribute ordering

`#[suprnova::observer(M)]` MUST appear ABOVE `#[async_trait]`:

```rust
#[suprnova::observer(User)]   // outer - runs first, sees raw async fns
#[async_trait]                // inner - rewrites async fn signatures
impl Observer<User> for AuditObserver { /* ... */ }
```

Attribute macros expand outside-in. `async_trait` rewrites every
`async fn` into a desugared `Pin<Box<dyn Future>>` poll-fn shape;
if `#[async_trait]` ran first, the observer macro's name-match
against the 16 trait method names would find nothing and silently
emit zero listeners.

### Four registration paths

| Path                                         | When to use                                         |
|----------------------------------------------|-----------------------------------------------------|
| `#[suprnova::observer(M)]` (inventory)       | Static observer known at compile time. Auto-installs on boot. |
| `#[model(observers = [Foo, Bar])]`           | Documentation + compile-time validation that the listed types resolve. Does NOT itself register. |
| `Model::observe(MyObs).await`                | Runtime registration. Hand-driven; useful when registration depends on config. |
| `EventFacade::listen::<events::Created, _>(...)` | Lowest level - one event at a time. Use when an observer feels heavy. |

The `observers = [...]` attribute on `#[model]` is a documentation
marker. It compiles to a `const _: fn() = || { let _ =
::std::any::type_name::<T>; ... };` block that proves each listed
type resolves to a real Rust item; typos surface at the model
declaration site. Actual install is via the inventory pathway -
the `#[observer(M)]` attribute on `Foo` is what enrolls `Foo` for
auto-install.

### Bootstrap

Call `bootstrap_observers()` once at startup to drain the inventory
and install every `#[observer(M)]`-registered observer:

```rust
suprnova::eloquent::observers::bootstrap_observers().await?;
```

The drain is idempotent for the inventory pathway - each observer's
install closure is gated by a per-type `AtomicBool` (T2b's macro
emission), so calling `bootstrap_observers()` twice does not
double-register.

The runtime `Model::observe(MyObs)` shim is NOT gated. Calling it
twice registers two listener sets, matching Laravel's manual
`Model::observe(MyObs::class)` semantics. If a hand-driven observer
also has `#[observer]`, the inventory adapter fires in addition to
the manually-installed ones.

### Cancelling from an observer

The five cancellable hooks return `EventResult`. To abort the
operation, return `EventResult::cancel("reason")`:

```rust
#[suprnova::observer(Subscription)]
#[async_trait]
impl Observer<Subscription> for PolicyObserver {
    async fn creating(&self, attrs: &mut Attrs) -> EventResult {
        if let Some(plan) = attrs.get("plan") {
            if plan == "blocked" {
                return EventResult::cancel("plan is blocked");
            }
        }
        EventResult::ok()
    }
}
```

The cancel reason surfaces as `FrameworkError::bad_request(reason)`
from `Subscription::create`. The row never lands in the database -
cancel is a true abort, not a "delete after the fact".

Multiple observers may register cancellable hooks on the same model;
any one of them returning `Cancel` stops the operation. Order is the
inventory enrolment order (link order in practice).

### Multiple observers on one model

Multiple `Observer<M>` impls all fire for the same event -
EventFacade dispatch fans out to every registered listener rather
than picking one:

```rust
#[suprnova::observer(Comment)]
#[async_trait]
impl Observer<Comment> for AuditObserver { /* ... */ }

#[suprnova::observer(Comment)]
#[async_trait]
impl Observer<Comment> for NotifyObserver { /* ... */ }

// Comment::create(...) fires AuditObserver::created AND NotifyObserver::created.
```

This matches Laravel's fan-out semantics and is the load-bearing
property behind the "decompose hooks by concern" pattern: an
`AuditObserver` only knows about audit, a `NotifyObserver` only
knows about notifications, and the model declaration doesn't care
how many observers attach.

### Manual `Model::observe()`

Every `#[suprnova::model]` struct gets a per-model `observe<O>()`
shim. Call it at boot for dynamic registration:

```rust
#[derive(Clone)]
struct MyObs;

#[async_trait]
impl Observer<User> for MyObs { /* ... */ }

// At runtime:
User::observe(MyObs).await;
```

The shim's `O: Clone + 'static` bound is what lets the framework
hand a fresh observer clone to each of the 16 internal adapter
listeners. All 16 listener adapters install on every call - the
trait defaults make non-overridden methods cheap no-ops.

### Constraints

- **The macro version requires the impl block use plain method
  names matching the trait's 16 hooks.** Renamed methods,
  `#[allow]`-suppressed defaults, and `#[cfg]`-gated bodies fall
  outside the name-match and don't register listeners.

- **Observer structs the macro inspects must be zero-sized** (no
  fields). The macro constructs the observer via `let obs =
  MyObserver;` inside each adapter. Stateful observers (carrying
  `Arc<Inner>`) need the runtime `Model::observe()` path, which
  takes the observer by value and clones it into each adapter.

- **Test isolation: use unique model types per scenario.** The
  process-global EventDispatcher means listeners installed for
  `User` are visible to every test in the same binary. Per-test
  unique model types (`T2Comment`, `T2Subscription`, …) keep
  cross-test bleed out of the counter assertions. The
  `eloquent_observers.rs` integration tests exercise this pattern.

## Prunable

Laravel ships a `Prunable` trait that lets a model declare a scope
of rows to delete on a schedule. Suprnova mirrors that with two
traits and a console command.

### Declaring a pruner

```rust
use async_trait::async_trait;
use chrono::{Duration, Utc};
use suprnova::eloquent::Prunable;

#[suprnova::prunable]
#[async_trait]
impl Prunable for ExpiredSession {
    fn prunable() -> suprnova::Builder<Self> {
        Self::query().filter_op(
            "expires_at",
            "<",
            (Utc::now() - Duration::days(30)).to_rfc3339(),
        )
    }
}
```

### `MassPrunable` - bulk-delete variant

For high-volume tables (audit logs, request logs, expired cache
entries) `MassPrunable` skips per-row events and runs a single
`DELETE WHERE …` statement. It runs where the `prunable()` query routes,
the same place the `--pretend` count reads: the model's declared
connection, or the query's own `on(name)` or `with_tx`:

```rust
use suprnova::eloquent::MassPrunable;

#[suprnova::prunable]
#[async_trait]
impl MassPrunable for AuditLog {
    fn prunable() -> suprnova::Builder<Self> {
        Self::query().filter_op(
            "created_at",
            "<",
            (Utc::now() - Duration::days(365)).to_rfc3339(),
        )
    }
}
```

### Triggering pruning

Run it with the `suprnova` CLI. The CLI runs your project's console
binary, which owns the command:

```bash
suprnova model:prune                          # prune every registered type
suprnova model:prune --model=ExpiredSession   # filter to one model
suprnova model:prune --pretend                # dry run; deletes nothing
```

`cargo run --bin console -- model:prune` runs the same command without the
CLI.

`--model` matches the last segment of the type name. When no registered
pruner has that name, the command prints
``model:prune: no pruner registered for `<name>` `` on the error stream,
deletes nothing and exits with code 0.

Programmatically the runners are at
`suprnova::eloquent::{prune_all, prune_all_dry, prune_one}`.

### Pruning hook

`Prunable::pruning(&self)` fires before each row delete so the user
can run side-effects (cleaning up associated files, fanning out
events, etc.). The default impl is empty. `MassPrunable` skips this
hook by definition - bulk deletes don't enumerate rows.

### Cascade behavior

**Pruning does NOT auto-cascade to related rows.** A `Prunable` or
`MassPrunable` impl on `User` deletes user rows; their `posts`,
`role_user` pivot entries, polymorphic `comments`, etc. are LEFT
ORPHANED with FK columns pointing at the now-deleted user.

This matches Laravel's contract: relation cleanup is the user's job.
Two clean ways to handle it:

1. **Database-level FK cascade** - declare `ON DELETE CASCADE` (or
   `ON DELETE SET NULL`) in the foreign-key constraint when you write
   the migration. The DB engine handles cascade for free, with no
   per-row Rust code.

2. **Per-row hook** - implement `Prunable::pruning(&self)` to delete
   children before the parent row is dropped. The hook fires inside
   the same logical operation as the parent delete, so consistent
   ordering is guaranteed:

   ```rust
   #[async_trait]
   impl Prunable for User {
       fn prunable() -> Builder<Self> {
           Self::query().filter_op("deleted_at", "<", thirty_days_ago())
       }

       async fn pruning(&self) -> Result<(), FrameworkError> {
           // Delete posts.
           Post::query().filter("user_id", self.id).get().await?
               .into_iter()
               .map(|p| p.delete());
           // Detach role pivots.
           self.roles().sync(Vec::<i64>::new()).await?;
           Ok(())
       }
   }
   ```

`MassPrunable` is set-based - `pruning()` does not fire. Use plain
`Prunable` whenever you need cascade. The framework will not silently
issue a per-row DELETE when you opt into `MassPrunable`; the trade-off
is documented loudly.

### Registry mechanism

Pruner registration uses the same inventory pattern as observers,
commands, and supervisors. The `#[suprnova::prunable]` attribute on
the `impl Prunable for T { ... }` block auto-registers via
`inventory::submit!` at compile time. No central config file; adding
a new prunable type is one attribute.

## Multi-connection routing

Production apps regularly need more than one database connection -
the canonical case is a read replica for analytics + the primary
for writes, but the surface generalises to any named connection
(reporting DB, archive DB, per-tenant shard).

### Registering a connection

Call `DB::register_named(name, config)` at boot for every
non-default connection your app talks to:

```rust
DB::register_named(
    "reporting",
    DatabaseConfig {
        url: env::var("REPORTING_DATABASE_URL")?,
        max_connections: Some(20),
        ..Default::default()
    },
).await?;
```

Two names are reserved: `__primary__` short-circuits the registry
to `DB::connection()`, and `__read_replica__` opts the connection
into automatic read-write split routing - see below.

### Per-query opt-in: `Model::on(name)`

`Model::on("reporting")` returns a `Builder<M>` pre-set to route
through the named connection:

```rust
let totals = Order::on("reporting")
    .order_by_desc("total")
    .limit(100)
    .get()
    .await?;
```

`on(...)` is request-scoped - it only affects the chained builder.
The next plain `Order::query()` call resolves through the default.

### Per-model default: `#[model(connection = "...")]`

When a model always lives on one connection, declare the default
on the attribute:

```rust
#[model(table = "events", connection = "events_db")]
pub struct Event { /* ... */ }
```

Every `Event::query()` / `Event::create()` / `Event::find()` call
routes through `events_db` without needing the per-query `.on(...)`
override. An explicit `.on(...)` on a builder still wins.

### Read-write split

Registering a connection under the reserved name
`__read_replica__` opts every model into automatic routing: read
methods (`first` / `get` / `find` / `count` / `paginate` / `chunk` /
the closure-driven walkers) flow through the replica; writes
(`save` / `create` / `update` / `delete` / `force_delete` /
`replicate` / `attach` / `detach` / `sync` / `increment` /
`decrement`) flow through the primary.

`Model::on_write_connection()` opts a single builder OUT of the
replica - useful when read-your-writes consistency matters
(e.g. immediately after a `save`, before replication catches up).

### Routing precedence

Every read and every write resolves its connection in this order:

1. **Active transaction wins absolutely.** Inside `DB::transaction`
   every read AND every write uses the tx connection. `on(name)` is
   IGNORED inside a transaction - the tx is bound to a specific
   physical connection. SeaORM can't begin a transaction on one
   connection and run statements against another.
2. **Per-builder `on(name)`.** Set via `Model::on(name)` /
   `Builder::on(name)`. Wins over the model default and the
   read/write split.
3. **`Model::on_write_connection()`.** Forces the primary even
   when the operation would otherwise route to the replica.
4. **Per-model `#[model(connection = "...")]` default.** Wins
   over the read/write split for the model's own queries.
5. **Read/write split.** When `__read_replica__` is registered,
   read methods route there; writes route to the primary.
6. **Default.** `DB::connection()` - the primary, the one
   `DB::init()` set up.

### Caveats

- Active transactions IGNORE `on(name)` (see §1 above). If you
  need a write on a different connection mid-tx, you can't - the
  tx is bound to one connection.
- The reserved names `__primary__` and `__read_replica__` cannot
  be used as user connection names. `DB::register_named` returns
  an error on collision.
- Replica lag is YOUR problem. Suprnova does not retry-on-read or
  fall back to primary when the replica is stale; if you need
  read-your-writes after a save, use
  `Model::on_write_connection()` explicitly.

## Replication

`Model::replicate()` returns an unsaved copy of the model with the
primary key reset to its default. Useful for "duplicate this
record" UX where the user wants to start from an existing row.

```rust
let template: User = User::find_or_fail(42).await?;
let mut copy = template.replicate().await?;  // id reset to default
copy.email = "fresh@example.com".into();
copy.save().await?;  // INSERT, not UPDATE
```

`replicate` is **async** in Suprnova (diverges from Laravel) because
it fires the `Replicating` event - `Saving` / `Created` / etc.
listeners can mutate the replica before it's returned. See
[Replicating event](#replicating-event) for the listener mutation
contract.

### `replicate_except`

Drop named fields from the replica:

```rust
let copy = order.replicate_except(["payment_token", "stripe_id"]).await?;
```

Listed fields fall back to the model's `Default` impl - `String`s
become `""`, `Option`s become `None`, etc. Use this for sensitive
columns the replicated row shouldn't carry forward.

### Cross-type `replicate_into::<T>`

The Suprnova divergence - Laravel can't because PHP has no types.
`replicate_into::<T>()` bridges to a sibling type via
`serde_json`:

```rust
let order: Order = Order::find_or_fail(42).await?;
let invoice: Invoice = order.replicate_into::<Invoice>().await?;
invoice.save().await?;
```

Fields with matching names + serde-compatible types carry over;
fields that don't match on either side silently drop. `T` must
implement `Default` so unfilled fields have a value. Cross-type
replication does NOT fire `Replicating` (the event carries a
`&mut Self` - there's no way to address `T` through it). If you
need event-driven mutation, replicate same-type first and then
materialise `T` from the result.

## Debugging - dump and dd

Two interactive debugging aids on every `Builder<M>`:

```rust
// Logs SQL + bindings via tracing::info!, returns self.
let users = User::query()
    .filter("active", true)
    .dump()                       // → log line, builder continues
    .order_by_desc("created_at")
    .get()
    .await?;

// Logs at tracing::error!, then panics with the SQL in the message.
User::query().filter("id", 1).dd();  // - !
```

`dump` is chainable; `dd` returns `!` (never returns - the panic is
the contract). Both mirror Laravel's `Builder::dump()` /
`Builder::dd()` exactly.

Both helpers fall back to the SQLite dialect when no live DB
connection is bound (matches the `to_sql_with_bindings` fallback) so
they stay useful at REPL or in a test without `TestDatabase`.

The panic message uses the literal prefix `eloquent dd:` so tests
can assert against it:

```rust
#[test]
#[should_panic(expected = "eloquent dd")]
fn dd_panics_with_sql_in_message() {
    User::query().filter("id", 1).dd();
}
```

**Never commit `dd()` to a production code path.** It's an
interactive debugging aid; the panic on the way out is the entire
point. `dump()` is safer (just logs) but spamming it in hot paths
will fill your logs - strip it before pushing.

If you want the SQL without the side effects, reach for the
non-logging helpers:

- `Builder::to_sql()` - returns the rendered SQL as a `String`.
- `Builder::to_sql_with_bindings()` - returns `(String, Vec<SeaValue>)`.
- `Builder::to_sql_for(backend)` - render for an explicit dialect
  (cross-backend debugging).

## Testing models

Tests instantiate a real database via `TestDatabase`, which
registers the connection in the per-test container so anything
calling `DB::connection()` inside the SUT resolves to the test DB.

### Two entry points

- **`TestDatabase::fresh::<MyMigrator>().await`** - runs every
  migration the production migrator runs. Use this for app-level
  dogfood tests where you want the test schema to exactly match
  what `suprnova migrate` produces.
- **`TestDatabase::sqlite_memory().await`** - opens an in-memory
  SQLite database WITHOUT applying any migrations. Use this for
  framework-level unit tests where you want precise column-shape
  control via per-test `db.execute_unprepared("CREATE TABLE …")`.

### App-level dogfood pattern

```rust
use app::migrations::Migrator;
use app::models::users::User;
use suprnova::testing::TestDatabase;
use suprnova::{attrs, Model};

#[tokio::test]
async fn user_lifecycle() {
    let _db = TestDatabase::fresh::<Migrator>().await.unwrap();

    let alice = User::create(attrs! {
        name: "Alice",
        email: "alice@example.com",
        password: "hashed",
    }).await.unwrap();

    assert!(alice.id > 0);

    alice.delete().await.unwrap();
    assert!(User::find(alice.id).await.unwrap().is_none(),
        "default scope hides soft-deleted rows");
}
```

The `_db` binding holds the `TestDatabase` for the whole test -
dropping it tears the container down and releases the in-memory
SQLite connection. Don't shadow it to `_` or the connection
disappears before the SUT runs.

### Framework-level shape pattern

```rust
use suprnova::testing::TestDatabase;
use suprnova::{attrs, model, Model};

#[model(table = "t_users", timestamps = false)]
pub struct TUser { pub id: i64, pub name: String }

#[tokio::test]
async fn shape_test() {
    let db = TestDatabase::sqlite_memory().await.unwrap();
    db.execute_unprepared(
        "CREATE TABLE t_users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)"
    ).await.unwrap();

    let u = TUser::create(attrs! { name: "Alice" }).await.unwrap();
    assert_eq!(u.name, "Alice");
}
```

### Key patterns

- `TestDatabase::fresh::<MyMigrator>()` for app-level tests with the
  production schema. `TestDatabase::sqlite_memory()` for unit-level
  shape tests.
- Use `TestContainer::bind` (NOT `App::bind`) for any singletons
  the test mutates - global registry overrides race in parallel
  runs. The `TestDatabase` constructor handles the DB binding for
  you.
- Keep model declarations at module scope, not inside test fns.
  The macro emits an inner `mod` whose `use super::*;` only sees
  the file's top-level imports - declaring a model inside a test
  function breaks SeaORM type resolution.

## Dropping to SeaORM

Three escape hatches keep SeaORM reachable from inside the Eloquent
layer:

1. **The inner module** - `user::Entity`, `user::Column`,
   `user::ActiveModel`, `user::Model`. The macro emits these for every
   model; they're SeaORM types you can use directly. See
   [Model module layout](#model-module-layout) for the full layout and
   when to reach in.
2. **`From` conversions** - `From<user::Model> for User` and
   `From<User> for user::Model` bridge between SeaORM-shape rows
   (storage-typed columns) and Eloquent-shape rows (runtime-typed
   columns). Useful when you want to issue a SeaORM query and
   convert the result to the Eloquent shape, or vice-versa.
3. **The Suprnova-aliased SeaORM types** - every SeaORM type a
   consumer would touch is re-exported under `suprnova::*`. You
   shouldn't need `use sea_orm::*` in app code.

```rust
use suprnova::sea_orm::{ColumnTrait, EntityTrait};

// Drop to SeaORM mid-query - Eloquent doesn't have a method for
// this, but SeaORM does:
let db = suprnova::DB::connection()?;
let users = user::Entity::find()
    .filter(user::Column::Email.like("%@example.com"))
    .all(db.inner())
    .await?;

// Convert to Eloquent shape:
let eloquent: Vec<User> = users.into_iter().map(User::from).collect();
```

Three escape hatches and the From bridge means the Eloquent layer
never blocks you from reaching the underlying ORM.

## Migrating from `database::Model`

Older code may carry `impl suprnova::database::Model for Entity {}`
on a hand-rolled SeaORM entity. The trait was renamed to `EntityExt`
to make room for the new `Model` trait - which sits on the
user-facing struct, not on the SeaORM entity.

The recommended migration path is to switch the type to
`#[suprnova::model]`, which gives you the full Eloquent surface
plus the renamed `EntityExt` traits as a bonus. For the rare case
where you want to keep the old SeaORM-Entity-extension shape, the
`EntityExt` / `EntityExtMut` trait names are still available under
`suprnova::database::*`. They behave exactly like the old
`database::Model` did.

## DB facade - model-less queries

Some tables don't belong on a `#[suprnova::model]` struct: short-lived
audit logs, ad-hoc reporting joins, dashboard aggregates. For those,
reach for the `DB` facade. Two surfaces sit under it:

### `DB::table(name)` - chainable query builder

`DbTableBuilder` mirrors the where / order / limit shape of
`Builder<M>` but returns rows as `DynamicRow` (a typed-accessor
newtype over `serde_json::Map<String, Value>`):

```rust
use suprnova::DB;

let rows = DB::table("audit_log")
    .filter("actor_id", 42)
    .filter_op("created_at", ">=", "2026-01-01")
    .order_by_desc("id")
    .limit(50)
    .get()
    .await?;

for row in rows.iter() {
    let event: String = row.get_string("event")?;
    let actor_id: i64 = row.get_int("actor_id")?;
    println!("{actor_id}: {event}");
}
```

The full surface:

| Method | Returns | Purpose |
|--------|---------|---------|
| `.select(["id", "event"])` | `DbTableBuilder` | Restrict columns (default `*`) |
| `.filter(col, val)` | `DbTableBuilder` | `WHERE col = ?` |
| `.filter_op(col, op, val)` | `DbTableBuilder` | `WHERE col <op> ?` |
| `.order_by_asc(col) / _desc(col)` | `DbTableBuilder` | Ordering |
| `.limit(n) / .offset(n)` | `DbTableBuilder` | Window |
| `.get()` | `Collection<DynamicRow>` | All matching rows |
| `.first()` | `Option<DynamicRow>` | First row or `None` |
| `.count()` | `u64` | `SELECT COUNT(*) ...` |
| `.insert(attrs)` | `i64` | New row's `id` |
| `.update(attrs)` | `u64` | Rows affected |
| `.delete()` | `u64` | Rows affected |

**Identifier trust boundary.** Table names, column names, SQL
operators, and ORDER BY directions are interpolated into the SQL
string verbatim - they are NOT bound as parameters. Pass only
trusted, compile-time literals to these arguments. Values (the
right-hand side of `filter` / `filter_op`) ARE bound and safe to pass
through from request data.

**Empty WHERE on `update` / `delete` operates on every row.**
`DB::table("audit_log").delete().await?` truncates the table by
design - add a `filter` if you don't mean that.

**Insert backend split.** `RETURNING id` is used on Postgres and
SQLite; MySQL runs the INSERT then issues
`SELECT LAST_INSERT_ID() as id` to recover the auto-increment.

### `DynamicRow` - typed accessors over JSON map

`DynamicRow` wraps a `serde_json::Map<String, Value>` and exposes
typed getters. Each returns `Result<T, FrameworkError>` with a clear
error message on missing key or type mismatch:

```rust
let event: String     = row.get_string("event")?;
let actor_id: i64     = row.get_int("actor_id")?;
let active: bool      = row.get_bool("active")?;
let prefs: Prefs      = row.get_as("prefs")?;  // any DeserializeOwned
let raw: serde_json::Value = row.get_value("meta")?;
```

Nullable columns: use `get_optional_*`. These distinguish "column
missing" (error - schema mismatch) from "column present, value null"
(`Ok(None)`):

```rust
let score: Option<i64>      = row.get_optional_int("score")?;
let title: Option<String>   = row.get_optional_string("title")?;
```

`DynamicRow` derefs to `Map<String, Value>`, so iteration and
key-existence checks work naturally:

```rust
for (key, value) in row.iter() {
    println!("{key} = {value}");
}
```

### Raw-SQL escapes

When the builder isn't enough - window functions, recursive CTEs,
backend-specific DDL - drop to a raw string. Placeholders match the
active backend (`$1, $2, ...` for Postgres, `?` for MySQL + SQLite):

```rust
// Raw SELECT, materialised as DynamicRow.
let rows = DB::select(
    "SELECT u.name, COUNT(p.id) as post_count
     FROM users u LEFT JOIN posts p ON p.user_id = u.id
     GROUP BY u.id
     HAVING post_count > ?",
    vec![5i64.into()],
).await?;

// Raw UPDATE / DELETE - return rows-affected.
let updated = DB::update(
    "UPDATE users SET verified_at = NOW() WHERE id = ANY($1)",
    vec![ids.into()],
).await?;

let deleted = DB::delete(
    "DELETE FROM stale_sessions WHERE expires_at < ?",
    vec![now.into()],
).await?;

// Raw DDL or no-binding statements.
DB::statement("CREATE INDEX CONCURRENTLY idx_users_email ON users(email)")
    .await?;

// Generic affecting statement - for INSERT ... ON CONFLICT etc.
let rows = DB::affecting_statement(
    "INSERT INTO counters (k, n) VALUES ($1, 1) ON CONFLICT (k) DO UPDATE SET n = counters.n + 1",
    vec!["page_views".into()],
).await?;
```

Use these escape hatches sparingly - the typed builder catches more
errors at compile time and reads cleaner in business logic. But when
you need them, they're here.

A computed column such as `SELECT COUNT(*) AS n FROM t` comes back in
raw `DB::select` rows on every backend. SQLite declares no type for it,
so Suprnova reads the value by its runtime type; see
[Computed columns on SQLite](queries.md#computed-columns-on-sqlite).

## Relation-existence + cheap shortcuts

Suprnova mirrors Laravel's relation-existence query family. Every
method here pairs the Laravel-shape name with an idiomatic Rust alias
(Suprnova's standing dual-API convention).

### Relation-existence filters (`has` / `where_has` / `where_belongs_to`)

The correlated `EXISTS (...)` family constrains the parent query by
the existence (or absence, or count) of related rows, without joining
the relation into the outer SELECT.

```rust
use suprnova::Model;

// Users who have at least one post.
let users = User::query().has("posts").get().await?;

// Users who have NO posts.
let empty = User::query().doesnt_have("posts").get().await?;

// Users with >= 3 posts (Laravel `has("posts", ">=", 3)`).
let prolific = User::query().has_count("posts", ">=", 3).get().await?;

// Inner constraint via closure - restrict the EXISTS subquery body.
let recent = User::query()
    .where_has::<Post, _>("posts", |q| q.filter_op("created_at", ">=", "2026-01-01"))
    .get()
    .await?;

// One-column shortcut - equivalent to `where_has` with a tiny closure.
let with_pub = User::query()
    .where_relation("posts", "published", true)
    .get()
    .await?;

// Belongs-to direct join (no EXISTS - FK lives on this table).
let posts = Post::query().where_belongs_to("author", author.id).get().await?;
```

All variants compose with `or_*` and `*_doesnt_have` companions:

- `has` / `or_has` / `has_count` / `doesnt_have` / `or_doesnt_have`
- `where_has` / `or_where_has` / `where_doesnt_have` / `or_where_doesnt_have`
- `where_relation` / `where_relation_op` / `or_where_relation`
- `where_belongs_to`

The engine reads relation metadata from the macro-generated
`RelationEntry` inventory: join columns, pivot tables, morph
discriminators all flow through automatically. Three subquery shapes
are rendered:

- **Has** - `EXISTS (SELECT 1 FROM child WHERE child.fk = parent.pk)`
- **Pivot** - `EXISTS (SELECT 1 FROM pivot INNER JOIN target ON ... WHERE pivot.parent_fk = parent.pk)`
- **Morph** - has/pivot shape plus `AND target.<morph>_type = '<value>'`

Unknown relation names render the safe-fail form (`EXISTS (SELECT 1
WHERE 1 = 0)`), which evaluates to `FALSE` and returns zero rows. A
typo never leaks a full-table scan.

### `MorphTo` existence

You use `has_morph` or `doesnt_have_morph` with your `MorphTo` relation's
name and registered morph names. You also use a model's registered alias
or Rust type name. You pass `"*"` to query every owner type the relation
declares in its `targets` list, an owner without a `morph_type` included.
The wildcard absence form includes rows whose type column is null.
Explicit type lists match only those types, including their aliases.

```rust
let comments = Comment::query()
    .where_has_morph("commentable", ["post"], |q: Builder<()>, kind| {
        q.filter("published", kind == "post")
    })
    .get()
    .await?;
let missing = Comment::query()
    .doesnt_have_morph("commentable", "*")
    .get()
    .await?;
```

You use `where_has_morph` or `where_doesnt_have_morph` to constrain each
type's existence query. Your closure receives a builder and the canonical
morph name once per selected type. The target's global scopes and soft-delete
filter apply. An unknown morph type or a relation that is not `MorphTo`
returns an error when you compile or execute the query. An empty type list
matches no rows for existence, and every row for absence.

### Cheap builder shortcuts

```rust
// PK filters.
User::query().where_key(7).first().await?;        // sugar for filter("id", 7)
User::query().where_key_not(7).get().await?;      // sugar for filter_op("id", "!=", 7)
User::query().filter("name", n).or_where_key(7).get().await?;      // ... OR id = 7
User::query().filter("name", n).or_where_key_not(7).get().await?;  // ... OR id != 7
// Rust-idiomatic aliases: filter_key / filter_key_not /
// or_filter_key / or_filter_key_not.

// Order by created_at.
Post::query().latest().get().await?;              // ORDER BY created_at DESC
Post::query().oldest().get().await?;              // ORDER BY created_at ASC
Post::query().latest_by("published_at").get().await?;  // named column

// Exact-one matching.
let one = User::query().filter("email", e).sole().await?;          // errors on 0 or >1
let val: i64 = User::query().filter("id", 1).sole_value("views").await?;
let v: i64 = User::query().filter("name", "x").value_or_fail("views").await?;

// Eager-load opt-outs.
User::query().with(["posts","tags"]).without(["tags"]).get().await?;
User::query().with_only(["posts"]).get().await?;   // wipes the plan first

// Fully-qualified columns (for joins).
Builder::<User>::qualify_column("name");           // -> "users.name"
Builder::<User>::qualify_columns(["name", "id"]);  // -> ["users.name", "users.id"]
```

### Mass mutation - `update_all` / `delete_all` / `upsert` / `*_each`

These hit the database directly with a single statement and do NOT
fire per-row model events. Use them when scope-narrowing is sufficient
and you don't need lifecycle hooks; for per-row hooks iterate with
`.get()` and call `.update()` / `.delete()` per row.
`delete_all` always targets the model's static `M::TABLE`; runtime table
names are not accepted as executable SQL. On a `soft_deletes` model it
soft-deletes: one `UPDATE` sets the deleted-at column across the scope,
as Laravel's builder `delete()` does. `force_delete_all` removes the rows
for good.
Explicit null attributes are emitted as SQL `NULL`, so nullable bigint,
integer, boolean, timestamp, and other non-text columns retain their database
type on PostgreSQL. Every non-null attribute remains parameter-bound. Upsert
rows must have the same column set; a missing or extra key is rejected rather
than being interpreted as null.

```rust
// Mass UPDATE.
let n = User::query()
    .filter("active", false)
    .update_all(attrs! { archived_at: Utc::now() })
    .await?;

// Mass DELETE.
let n = Session::query()
    .filter_op("expires_at", "<", cutoff)
    .delete_all()
    .await?;

// INSERT ... ON CONFLICT (Postgres / SQLite) / ON DUPLICATE KEY UPDATE (MySQL).
let n = Counter::query()
    .upsert(
        vec![attrs! { key: "page_views", n: 1 }, attrs! { key: "signups", n: 1 }],
        vec!["key"],                  // conflict target
        Some(vec!["n"]),              // update columns; None = every non-unique column
    )
    .await?;

// Atomic increment/decrement against a scope.
User::query()
    .filter("id", 7)
    .increment_each(vec![("views", 1), ("likes", 1)])
    .await?;

User::query()
    .filter("id", 7)
    .decrement_each(vec![("balance", 100)])
    .await?;
```

### Static `Model` helpers

```rust
// Mass-destroy by PK set. Per-row events fire (each row goes through
// .delete() so soft-delete tombstone semantics + Deleting/Deleted
// dispatch are honoured).
let removed: u64 = User::destroy(vec![1i64, 2, 3]).await?;
let removed: u64 = User::force_destroy(vec![1i64, 2, 3]).await?;

// Identity comparison by PK.
assert!(alice.is(&also_alice));
assert!(alice.is_not(&bob));
```

You use `force_destroy(keys)` to remove matching rows physically, including
rows you already soft-deleted. You receive the number removed. Duplicate
or missing keys add nothing to the count, and an empty list returns zero.
Each removed row fires its force-delete lifecycle events.

### `*Quietly` variants - suppress lifecycle events

Sugar over `seed::without_events`. The five static lifecycle events
(`Saving`/`Creating`/`Updating`/`Deleting`/`Restoring`) and the
non-cancellable after-events both short-circuit inside the scope.

```rust
user.save_quietly().await?;            // no Saving / Updated / Saved
user.update_quietly(attrs).await?;
user.delete_quietly().await?;
user.force_delete_quietly().await?;
```

### `*_or_fail` variants

Explicit error on the not-found case. Useful in invariant-checking
code paths where a missing row is a bug.

```rust
let user = user.update_or_fail(attrs).await?;   // not_found if row deleted mid-flight
user.delete_or_fail().await?;
```

On a model declared with `soft_deletes`, `delete_or_fail`, `delete_quietly`,
`destroy`, and a `delete` called through the `Model` trait all tombstone
the row, as `delete()` does. `delete_or_fail` answers not-found for a row
that is already trashed.

### Filtered serialisation - `to_array_except` / `to_array_only`

Suprnova's Rust-native replacement for Laravel's per-instance
`makeHidden` / `makeVisible`. The Eloquent struct doesn't carry a
runtime attribute bag, so the column list is supplied at the call
site:

```rust
return Json::ok(user.to_array_except(&["password_hash", "remember_token"]));
return Json::ok(user.to_array_only(&["id", "name", "email"]));
```

**Divergence note.** Laravel's per-instance `makeHidden` mutates state
that propagates when the model is nested inside a parent's `toArray()`
call. Suprnova's filter is terminal - it produces a `serde_json::Value`
and doesn't affect future serialisations of `self`. For
declarative-and-permanent visibility control, use the `#[model(hidden
= [...])]` / `#[model(visible = [...])]` attributes.

### UUID / ULID primary keys - `#[model(unique_id = "...")]`

Suprnova's analogue of Laravel's `HasUuids` / `HasUlids` /
`HasVersion4Uuids` trait family. Set the attribute, type the PK as
`String`, and the macro auto-populates the ID before INSERT. The key type
comes from the `String` field.

```rust
#[model(
    table = "users",
    primary_key = "id",
    auto_increment = false,
    unique_id = "uuid",      // or "uuid_v4", "ulid"
)]
pub struct User {
    pub id: String,
    pub email: String,
}

// Auto-populated:
let u = User::create(attrs! { email: "a@b.com" }).await?;
// u.id is a fresh UUID v7.

// Caller-supplied IDs still win (matches Laravel's HasUuids behaviour).
let u = User::create(attrs! { id: "...", email: "..." }).await?;
```

Supported strategies:

- `"uuid"` / `"uuid_v7"` - UUID v7 (timestamp-ordered, recommended;
  matches Laravel 11+'s default `Str::uuid7()`)
- `"uuid_v4"` - random UUID (matches `HasVersion4Uuids`)
- `"ulid"` - lowercase 26-char Crockford-base32 ULID

The macro emits an `impl HasUniqueId for YourStruct` block exposing
`UNIQUE_ID_KIND` and a `new_unique_id()` hook you can override on the
type for a custom generator (e.g. prefixed IDs like `usr_<uuid>`).

### `find_or` / `find_or_new` / `create_or_first`

Round out the `FirstOrCreate` trait surface.

```rust
// Look up by PK; run fallback if not found.
let user = User::find_or(id, || async {
    User::create(attrs! { id, name: "guest" }).await
}).await?;

// Look up by PK; build an unsaved instance from defaults if not found.
let user = User::find_or_new(id, attrs! { name: "draft" }).await?;
// user.id == 0 here - the instance is in-memory only; insert it with
// `user.persist().await?`.

// Race-safe insert: try create, fall back to fetch on conflict.
let user = User::create_or_first(
    attrs! { email: "race@x.com" },
    attrs! { name: "race winner" },
).await?;
```

### `without_touching` scope

The Suprnova analogue of Laravel's `Model::withoutTouching`. Inside
the scope, every `model.touch().await` call short-circuits - useful
when running data migrations or batch jobs that mutate timestamps
through other paths.

```rust
use suprnova::eloquent::without_touching;

without_touching(async {
    // .touch() calls here are no-ops.
    for post in posts {
        post.touch().await?;
    }
}).await;
```

The scope is `tokio::task_local`-backed, so concurrent requests on
other tasks continue to honour their own scope (or its absence).
`without_touching` also suppresses the [parent-touch
cascade](#parent-touching) - a child saved inside the scope leaves
every owner named in its `touches` list alone.

`without_touching_on::<Post, _, _>(fut)` is the per-type form -
Laravel's `Model::withoutTouchingOn([Post::class], $cb)`. Inside it,
`post.touch()` and any cascade that would bump a `Post` go quiet, while
owners of every other type keep bumping:

```rust
use suprnova::eloquent::without_touching_on;

without_touching_on::<Post, _, _>(async {
    // Comment saves in here leave their Post owners alone; a Video
    // owner on the same comment still bumps.
    comment.save().await
}).await?;
```

The per-type form also holds for a `MorphTo` owner: when the owner the
row points at is a `Post`, the touch is skipped.

Scopes nest, and both are `tokio::task_local`-backed.

## Next

- [Eloquent Relationships](eloquent-relationships.md) - deep dive on
  every relation kind, the morph registry, and the polymorphic enum
  lowering
- [Eloquent Collections](eloquent-collections.md) - full
  `Collection<T>` surface, the generic-vs-model split, and
  `LazyCollection<M>` streaming
- [Eloquent Casts, Accessors & Mutators](eloquent-mutators.md) - the
  31 built-in casts plus the `casts!` runtime override
- [Eloquent Serialization](eloquent-serialization.md) - `to_array`,
  `to_json`, hidden / visible / appends, filtered terminals
- [Eloquent Factories](eloquent-factories.md) - randomized model
  instances for tests and seeders


---

<!-- /docs/eloquent-relationships -->

# Eloquent Relationships

[Eloquent](eloquent.md) covers the day-to-day relationship surface -
declaration syntax, the option table, basic per-kind chaining. This
chapter is the relationship-specific deep dive: how a `user.posts()`
call actually resolves to SQL, how the eager loader avoids N+1, how
the existence engine (`has` / `where_has` / `where_belongs_to`) renders
correlated `EXISTS` subqueries, how polymorphism survives Rust's lack
of late static binding, and what falls out of the type system when
all eleven relation kinds have to coexist on one trait.

If you're new to Eloquent on Suprnova, read
[Eloquent](eloquent.md#relationships) first - that page teaches the
declaration syntax. This page assumes you have a model with a
`relations = { ... }` block already and want to understand what's
underneath.

## The eleven relation kinds

Every relation kind in [`RelationKind`][relations] is one of:

| Kind                  | Side       | Cardinality | Across families | Pivot |
|-----------------------|------------|-------------|-----------------|-------|
| `HasOne<R>`           | parent     | one         | no              | - |
| `HasMany<R>`          | parent     | many        | no              | - |
| `BelongsTo<R>`        | child      | one         | no              | - |
| `BelongsToMany<R, P>` | either     | many        | no              | yes   |
| `HasOneThrough<B, R>` | parent     | one         | no              | - |
| `HasManyThrough<B, R>`| parent     | many        | no              | - |
| `MorphOne<R>`         | parent     | one         | yes             | - |
| `MorphMany<R>`        | parent     | many        | yes             | - |
| `MorphTo`             | child      | one         | yes (n targets) | - |
| `MorphToMany<R, P>`   | parent     | many        | yes             | yes   |
| `MorphedByMany<R, P>` | m2m partner| many        | yes (inverse)   | yes   |

"Across families" means the related row's *type* varies - a `Comment`
might belong to a `Post` or a `Video`, not just one fixed parent table.
That's polymorphism, and Suprnova handles it via the [morph
registry](#the-morph-registry) plus a per-family enum.

[relations]: https://docs.rs/suprnova

### What the macro emits

When you write:

```rust
use suprnova::model;

#[model(table = "users", relations = {
    posts: HasMany<Post>,
})]
pub struct User {
    pub id: i64,
    pub name: String,
}
```

`#[suprnova::model]` expands into five things for `posts`:

1. **Relation method** - `fn posts(&self) -> HasMany<Self, Post>`. Returns
   a lazy wrapper carrying `self.id` plus FK metadata; no SQL runs yet.
2. **Loaded-accessor** - `fn posts_loaded(&self) -> &[Post]`. Reads from
   the eager cache after `User::with(["posts"])`. Empty slice when no
   eager load ran.
3. **Count-accessor** - `fn posts_count(&self) -> u64`. Reads from the
   same cache after `User::with_count(["posts"])`.
4. **Dispatcher arm** - match arm in the model's `__eager_load`
   inherent method. The eager loader looks up `"posts"` and runs the
   `IN`-query.
5. **Inventory entry** - one `inventory::submit!(RelationEntry { ... })`
   so the relation is enumerable at runtime (admin tooling, the
   existence engine, the morph dispatcher all walk this).

You never see (4) or (5). They power the rest of this chapter.

## Lazy resolution: how `user.posts()` becomes SQL

`user.posts()` returns a `HasMany<User, Post>` wrapper, not a query
result. The wrapper holds the parent's PK value plus the FK column
name, and a pre-filtered `Builder<Post>` with
`WHERE posts.user_id = ?` already applied. Nothing has touched the
database yet.

```rust
use suprnova::Direction;

// No SQL.
let posts_q = user.posts();

// SQL: SELECT * FROM posts WHERE user_id = ? ORDER BY id DESC LIMIT 5
let recent = user.posts()
    .order_by("id", Direction::Desc)
    .limit(5)
    .get()
    .await?;

// SQL: SELECT COUNT(*) FROM posts WHERE user_id = ?
let n = user.posts().count().await?;
```

The dual-API surface ([Eloquent → Naming note](eloquent.md#naming-note-dual-api))
is honoured on the wrapper: both `.filter("col", v)` and
`.db_where("col", v)` work, identically. The chainable surface on
`HasOne` / `HasMany` / `MorphOne` / `MorphMany` covers `filter` /
`db_where` / `order_by` / `latest` / `oldest` / `limit` / `take`.
Through and morph m2m relations expose only their terminal methods -
they go through hand-written SQL stitches, not a `Builder<R>`, so
they can't compose with the standard chain. See [Through
relations](#hasonethrough-and-hasmanythrough) and [Polymorphic
m2m](#morphtomany-and-morphedbymany) below.

### Soft deletes follow through

When the related type implements [`SoftDeletes`](eloquent.md#soft-deletes-flag),
the relation wrapper inherits its global scope. `user.posts().get()`
hides trashed posts the same way `Post::query().get()` does. Three
forwarders punch through:

```rust
let alive = user.posts().get().await?;                 // default: alive only
let all = user.posts().with_trashed().get().await?;    // alive + trashed
let dead = user.posts().only_trashed().get().await?;   // trashed only
```

`with_trashed` / `only_trashed` exist on `HasOne`, `HasMany`,
`MorphOne`, `MorphMany`, `BelongsToMany`, `MorphToMany`,
`MorphedByMany`, and `BelongsTo`. `HasOneThrough` and `HasManyThrough`
do not have them: they always leave trashed rows out, as
[Through soft-deletes](#through-soft-deletes) below describes.

## One-to-one: `HasOne` and `BelongsTo`

`HasOne` is the parent saying "this child has a column pointing at me".
`BelongsTo` is the child saying "I have a column pointing at the
parent". Both run a single `WHERE fk = ? LIMIT 1` and return
`Option<R>`.

```rust
// HasOne - parent → child
let profile: Option<Profile> = user.profile().first().await?;

// BelongsTo - child → parent
let owner: Option<User> = profile.user().first().await?;
```

`BelongsTo` adds one Laravel-shaped affordance the others don't need:
`with_default`. When the child's FK is null OR the parent row was
deleted, `first()` returns the closure's stand-in rather than `None`:

```rust
#[model(table = "comments", relations = {
    author: BelongsTo<User> {
        with_default = || User { id: 0, name: "Guest".into(), .. },
    },
})]
pub struct Comment { /* ... */ }

// Always returns Some(User) - either the real author or the Guest stub.
let display: Option<User> = comment.author().first().await?;
```

The eager-load dispatcher honours the same fallback - lazy and eager
paths share the default behaviour, so template code that prints
`comment.author_loaded()[0].name` doesn't have to branch.

## One-to-many: `HasMany`

`HasMany` is the parent-side many-cardinality relation. The terminal
`.get()` returns a [`Collection<R>`](eloquent.md#collections) - the
Laravel-shaped wrapper around `Vec<R>` - so the model-aware surface
composes:

```rust
let titles = user.posts()
    .order_by("created_at", Direction::Desc)
    .limit(10)
    .get()
    .await?
    .pluck::<String>("title");
```

`latest()` and `oldest()` are sugar for
`order_by("created_at", Direction::Desc)` and `Asc` respectively -
they only resolve against models that declare a `created_at` column,
which the `#[suprnova::model]` macro auto-adds whenever timestamps are
on (the default).

### Finding or creating a related record

You call `first_or_create(attributes, extra)` on `HasOne`, `HasMany` or
`BelongsToMany` to return a matching record or create it. You supply lookup
columns in `attributes` and creation values in `extra`. You keep an
existing record's values. Your relation sets its foreign key after applying
the related model's mass-assignment guard, including a custom local key.
You also attach a pivot row through a many-to-many relation. You attach
an existing record when it matches outside the relation.

```rust
let post = user.posts()
    .first_or_create(attrs! { title: "Draft" }, attrs! { views: 0 })
    .await?;
let role = user.roles()
    .first_or_create(attrs! { name: "editor" }, attrs! {})
    .await?;
```

You call `increment_or_create(attributes, column, default, step, extra)`
on the same relation kinds to create a counter or increment it. You use
`default` for a new record. You add `step` to an existing record, including
a zero or negative step. You supply integer amounts. You apply `extra`
to an existing record in the same database update as the increment. You
receive the record with its stored counter value.

```rust
let post = user.posts()
    .increment_or_create(attrs! { title: "Draft" }, "views", 1, 3, attrs! {})
    .await?;
```

## Many-to-many: `BelongsToMany<R, P>` and the first-class pivot

`BelongsToMany` is many-to-many through a join table. Suprnova's pivot
is itself a `#[suprnova::model]` struct with its own migrations, its
own accessors, its own events. That's the divergence - see [below](#why-suprnova-diverges-pivot-is-a-real-model).

```rust
#[model(table = "users", relations = {
    roles: BelongsToMany<Role, RoleUser> {
        with_pivot = ["assigned_at"],
        with_timestamps,
    },
})]
pub struct User { /* ... */ }

#[model(table = "role_user", primary_key = "id")]
pub struct RoleUser {
    pub id: i64,
    pub user_id: i64,
    pub role_id: i64,
    pub assigned_at: Option<chrono::DateTime<chrono::Utc>>,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

Mutators run against the pivot row:

```rust
use suprnova::attrs;

user.roles().attach(role.id).await?;
user.roles().attach_with(role.id, attrs! { assigned_at: now }).await?;
user.roles().detach(role.id).await?;
user.roles().sync([role_a.id, role_b.id, role_c.id]).await?;
```

Extra pivot columns go through the pivot model's casts and mutators, as
`Model::create` does: a column the pivot declares `AsEncrypted` is
stored encrypted, and reads back through `r.pivot::<RoleUser>()` as the
plain value. A key the pivot model does not declare is written as it
is.

`sync` reads the current pivot set, computes
`attach_set = ids - current` and `detach_set = current - ids`, and
runs the deltas inside a transaction. Duplicates in the input set
collapse by their JSON-string form so `sync([1, 1, 2])` does what you
mean.

`sync_without_detaching` is the attach half of `sync`, Laravel's
`syncWithoutDetaching`. It attaches each id the relation doesn't hold yet
and leaves every other pivot row as it is, which suits an "add to
favorites" action that must not drop the rows already there:

```rust
// The user holds roles 1 and 2.
user.roles().sync_without_detaching([2, 3]).await?;
// Now it holds 1, 2, and 3. The rows for 1 and 2 are unchanged.
```

An id the relation already holds is skipped, not rewritten, so its row
keeps its extra pivot columns and its `created_at` and `updated_at`. The
new rows get timestamps when the relation has `with_timestamps`. The
inserts run in one transaction, so one that fails rolls back the others.
You receive `SyncChanges` from both methods: `attached`, `detached` and
`updated` hold JSON ids. `sync_without_detaching` always reports an empty
`detached` list. You supply per-id columns with `(id, Attrs)` records:

```rust
let changes = user.roles()
    .sync_without_detaching([(2, attrs! { assigned_at: now })])
    .await?;
assert_eq!(changes.updated, vec![serde_json::json!(2)]);
```

An existing row updates only when a supplied column changes. You keep
unsupplied columns, and an unchanged row keeps its timestamps. A changed
row receives `updated_at` when you enable `with_timestamps`. Both methods
reconcile and write inside one transaction. You add `.touch_parent()`
when the parent timestamp must advance after a relation change. An
inverse relation named in the related model's `touches` also enables that
parent touch; `without_touching` suppresses it.

Reading goes through the two-query strategy:

```rust
// Query 1: SELECT roles.*, role_user.* via INNER JOIN, scoped by user_id.
// Query 2: SELECT role_user.* for the same join, to stamp __pivot per row.
let roles = user.roles().get().await?;

// Each role carries the pivot context the macro made accessible:
for r in &roles {
    let pivot = r.pivot::<RoleUser>();
    println!("{} assigned at {:?}", r.name, pivot.assigned_at);
}
```

You delete a loaded pivot without a surrogate `id` through its original
foreign-key pair. You declare one key as the pivot model's `primary_key`
and keep both keys as fields. You obtain the pivot from a lazy or eager
relation read, then clone it because `delete()` consumes the model:

```rust
role.pivot::<RoleUser>().clone().delete().await?;
```

Your other attachments remain in place. A loaded morph pivot also uses its
original type column, so another morph family with the same keys remains.
A pivot with a surrogate `id` uses its ordinary model deletion path.

### Mapping related records in chunks

You call `chunk_map(size, closure)` on `BelongsToMany`, `HasOneThrough` or
`HasManyThrough` to map each related record while reading bounded batches.
You receive a `Collection` of mapped values in primary-key order. Your
closure receives one record and returns an asynchronous `Result`. A
many-to-many record gives you its pivot context. You retain target scopes,
soft-delete filters and pivot filters. You receive an error for a zero size.
You stop at the first database or closure error and receive that error.

```rust
let names = user.roles()
    .chunk_map(10, |role| async move { Ok(role.name) })
    .await?;
```

### Filtering on pivot columns

`where_pivot` and its family constrain the *pivot* table, not the
related table. Reach for them when the join row carries state you want
to filter on - an `active` flag, an expiry timestamp, a scope column.
The examples below assume the `RoleUser` pivot above also declares
`active`, `pinned` and `note` columns:

```rust
// Roles whose pivot row is still active.
let active = user.roles().where_pivot("active", 1i64).get().await?;

// Roles assigned in a window, or explicitly pinned.
let visible = user
    .roles()
    .where_pivot_between("assigned_at", start..=end)
    .or_where_pivot("pinned", 1i64)
    .get()
    .await?;

// A nested group: (active = 1 AND note IS NOT NULL) OR pinned = 1.
let complex = user
    .roles()
    .where_pivot_group(|q| q.filter("active", 1i64).filter_not_null("note"))
    .or_where_pivot("pinned", 1i64)
    .get()
    .await?;
```

The full family:

| Method | SQL |
|---|---|
| `where_pivot(col, val)` | `col = ?` |
| `where_pivot_op(col, op, val)` | `col <op> ?` |
| `where_pivot_in(col, vals)` | `col IN (...)` |
| `where_pivot_not_in(col, vals)` | `col NOT IN (...)` |
| `where_pivot_null(col)` | `col IS NULL` |
| `where_pivot_not_null(col)` | `col IS NOT NULL` |
| `where_pivot_between(col, low..=high)` | `col BETWEEN ? AND ?` |
| `where_pivot_not_between(col, low..=high)` | `col NOT BETWEEN ? AND ?` |
| `where_pivot_group(\|q\| ...)` | `(... AND ...)` |

Every method has an `or_` twin that folds into a disjunction with the
term before it. Inside a closure, the builder's `or_*` conditions are
flat and follow SQL precedence. A closure
group stays atomic inside that disjunction, so
`.where_pivot_null("note").or_where_pivot_group(|q| ...)` reads as
`note IS NULL OR (...)` and not as a flattened chain.

Column names interpolate into the pivot statement as raw SQL
identifiers, the same contract as `Builder::filter`. Never take one
from request data. The values bind as parameters, so those are safe to
take from request data.

The closure form runs on the same statement, so a `where_raw` or a
`where_has` inside it lands in the pivot SQL verbatim - the identifier
allowlist skips the raw escape hatch by design. Treat the closure the
way you treat `Builder::where_raw`: never build its fragments from
untrusted input.

The same family is on `MorphToMany` and `MorphedByMany`.

### Pivot filters on writes and eager loads

Two boundaries, both deliberate.

You use pivot filters with `sync` and `sync_without_detaching` to narrow
the current set, updates and detachments. A row outside the filter stays
as it is. A new record still needs the pivot columns its filter expects:

```rust
let changes = user.roles().where_pivot("active", 1i64)
    .sync([(role.id, attrs! { active: 1 })]).await?;
```

`attach`, `attach_with` and `detach` still refuse a pivot filter.
Polymorphic pivot mutators also retain that refusal.

**Eager loading does not carry pivot filters.** `user_query.with(["roles"])`
runs through the relation's generated eager-load path, which scans the
pivot table for the whole parent batch at once and applies a
`with_where` closure to the *related* table. There is no slot on that
path for a pivot predicate. When you need a filtered many-to-many read,
call the relation accessor per parent
(`user.roles().where_pivot(...).get()`) instead of eager loading.

### Why Suprnova diverges: pivot is a real model

Laravel's pivot is an opaque per-attribute bag (`$role->pivot->note`).
Suprnova requires you to declare the pivot struct because Rust's type
system needs the columns at compile time - and once you've paid for
that declaration, the pivot gets the same `#[suprnova::model]`
treatment as any other table: migrations, events, observers,
factories, soft-delete. `r.pivot::<RoleUser>()` returns a typed
reference; no string-keyed attribute lookups, no surprises at runtime
when a column is misspelled.

The cost is one extra struct per pivot table. The benefit is that the
pivot can carry behaviour - domain logic, validation rules, audit
columns - without escaping into raw SQL.

A relation reads its pivot table directly, as Laravel's `using(Pivot)`
relation does, so the pivot model's own global scopes and soft-delete
filter apply when you query `RoleUser::query()`, not to the attachments
`user.roles()` returns. Narrow the attachments with `where_pivot`.

## `HasOneThrough` and `HasManyThrough`

Two-hop relations: `A → B → C` where `B` is an intermediate model whose
FK points at `A`, and `C` is the final target whose FK points at `B`.
Classic example: `Country` has many `User`s; `User` has many `Post`s;
`Country::posts()` jumps both hops in one SQL round trip.

```rust
#[model(table = "countries", relations = {
    posts: HasManyThrough<User, Post>,
})]
pub struct Country { /* ... */ }

// Single INNER JOIN: SELECT posts.* FROM posts
//   INNER JOIN users ON posts.user_id = users.id
//   WHERE users.country_id = ?
let posts: Collection<Post> = country.posts().get().await?;
```

`HasOneThrough` has the same shape but `.get()` returns
`Option<C>` (matching the one-cardinality semantics) and `.first()` is
its alias.

You use the through terminals `get`, `first`, `chunk_map` and
`find_or_new`, plus `count` on `HasManyThrough` and `is` on
`HasOneThrough`. You configure keys with `first_key`, `second_key`,
`local_key` and `second_local_key`. You cannot chain `.filter(...)` or
`.order_by(...)` on these wrappers. You query two explicit relation hops
when you need that chain.

### Looking up a target by key

You call `find_or_new(key)` on either through relation to search only
records your relation reaches. You receive a new unsaved instance with
default field values when the key does not match. You create no database
row and copy no lookup key into the new instance.

```rust
let post = country.posts().find_or_new(post_id).await?;
```

You call `is(&model)` on `HasOneThrough` to check whether your relation
reaches that model. You ask the database once with a count query and load
no target instance. You receive `false` for a record outside the relation
or one hidden by the relation's scopes or soft-delete filters.

```rust
let matches = user.profile().is(&profile).await?;
```

### Through soft-deletes

Through relations filter both the intermediate and the target by their
soft-delete column when those models declare `#[model(soft_deletes)]`,
matching Laravel's `hasManyThrough`: trashed rows on either side stay
out of the join. The target's global scopes apply too, as they do to
`Post::query()`; the intermediate is filtered by its soft-delete column
only. Eager loads (`with(["posts"])`), counts and aggregates of a
Through relation leave out the same rows.

To include trashed rows, query the two hops yourself: load the
intermediate models through their own relation, then query the target
model by their keys, and add `with_trashed()` on the side whose trashed
rows belong in the result.

## Polymorphic relations

A polymorphic FK is a column pair: `<name>_id` (the row's primary key)
plus `<name>_type` (a string identifying *which table* the id lives
in). One `Comment` row can point at a `Post` or a `Video` without
adding either a `post_id` or `video_id` column.

Suprnova ships four polymorphic kinds: `MorphOne`, `MorphMany`,
`MorphTo`, and the m2m pair `MorphToMany` / `MorphedByMany`. They all
share one piece of infrastructure: [the morph registry](#the-morph-registry).

### `MorphOne<R>` and `MorphMany<R>` - parent side

`MorphOne` and `MorphMany` mirror `HasOne` and `HasMany` but layer the
`<name>_type` discriminator on top. The inner builder is pre-filtered
with `WHERE <name>_id = ? AND <name>_type = ?`, so polymorphic
children pointing at *other* families never appear in the result.

```rust
#[model(table = "posts", morph_type = "post", relations = {
    comments: MorphMany<Comment> { name = "commentable" },
})]
pub struct Post { /* ... */ }

#[model(table = "videos", morph_type = "video", relations = {
    comments: MorphMany<Comment> { name = "commentable" },
})]
pub struct Video { /* ... */ }

let post_comments = post.comments().get().await?;     // only commentable_type = 'post'
let video_comments = video.comments().get().await?;   // only commentable_type = 'video'
```

`morph_type = "post"` is the string the parent registers in the
child's `commentable_type` column. Default is the snake-cased struct
name, but overriding is the right move for any model you're shipping -
table-renaming refactors shouldn't break the polymorphic key.

You create or save a child through `MorphOne` or `MorphMany` to fill its
owner id and canonical type. The relation's ownership overrides caller
values, including guarded ownership columns. Your other create attributes
retain the model's mass-assignment rules.

```rust
let comment = post.comments().create(attrs! { body: "Hello" }).await?;
let comment = post.comments().save(comment).await?;
let changed = post.comments().upsert(
    vec![attrs! { body: "Hello" }],
    vec!["commentable_id", "commentable_type", "body"],
    Some(vec!["body"]),
).await?;
```

You pass a new model to `save` to insert it, or a stored model to update it.
You use `upsert(rows, unique_by, update)` to fill ownership on every row
before the bulk write. You choose a database unique constraint for
`unique_by`. Empty rows return zero. Database errors return to you.

#### Morph aliases

A table may hold more than one string for one model. A Laravel database
stores the PHP class name, `App\Models\Post`, until the application adopts
`Relation::morphMap`, and the alias, `post`, after it. Declare the string
writes should store as `morph_type`, and every other string as an alias:

```rust
#[model(
    table = "posts",
    morph_type = "App\\Models\\Post",
    morph_aliases = ["post"],
    relations = {
        comments: MorphMany<Comment> { name = "commentable" },
    },
)]
pub struct Post { /* ... */ }
```

Reads accept every name: `MorphMany` and `MorphOne`, direct and eager,
`has`, `with_count` and the aggregates match rows holding either, and a
`MorphTo` loads the post a row names by either. Writes store the
`morph_type`. `morph_aliases` needs a `morph_type`. `MorphToMany` and
`MorphedByMany` pivots match the `morph_type` alone. See
[Running on a Laravel Database](laravel-database.md).

### `MorphTo` and the per-family enum

`MorphTo` lives on the morph-table side. The user declares the
*targets list* up front:

```rust
#[model(table = "comments", relations = {
    commentable: MorphTo { name = "commentable", targets = [Post, Video] },
})]
pub struct Comment {
    pub id: i64,
    pub commentable_id: i64,
    pub commentable_type: String,
    pub body: String,
}
```

The macro emits a per-family enum at the declaration site:

```rust
// Emitted by the macro - you don't write this.
pub enum CommentableMorph {
    Post(Post),
    Video(Video),
    Unknown(String, serde_json::Value), // fallback for unregistered <name>_type
}
```

And `comment.commentable()` returns a fetch helper whose `.get()`
resolves to the enum:

```rust
match comment.commentable().get().await? {
    CommentableMorph::Post(post) => println!("on post: {}", post.title),
    CommentableMorph::Video(video) => println!("on video: {}", video.url),
    CommentableMorph::Unknown(t, id) => {
        eprintln!("orphaned commentable_type={t} id={id}");
    }
}
```

### Why Suprnova diverges: per-family enum

Laravel's `morphTo` returns `mixed` - PHP's dynamic dispatch resolves
the method at runtime. Rust has no late static binding, so Suprnova
makes the family explicit. The benefits beat the typing cost:

- **Exhaustive `match`** - the compiler tells you when a new morph
  target lands and you forgot to handle it.
- **`Unknown(String, id)` is type-safe** - orphaned rows from a
  removed parent model class are surfaced as a variant, not panicked
  on.
- **The targets list documents the schema** - reading the `MorphTo`
  declaration tells you every type that can sit on the other end. No
  database query required to enumerate them.

### `MorphTo` keys

A `MorphTo` target can use any primary key type the model declares:
`i64`, `String`, UUID or ULID. The morph table's `<name>_id` column takes
the same type as its targets' keys.

```rust
#[model(
    table = "notes",
    relations = {
        subject: MorphTo { targets = [Article, Recipe] },
    },
)]
pub struct Note {
    pub id: i64,
    pub subject_id: String,      // the key type of Article and Recipe
    pub subject_type: String,
    pub body: String,
}
```

Three rules hold:

- All targets of one `MorphTo` relation have one key type. A relation
  that mixes them does not compile.
- The child's `<name>_id` field has that key type. A field of another
  type does not compile.
- The parent side is not checked. `MorphOne`, `MorphMany`,
  `MorphToMany` and `MorphedByMany` read the parent's own key, and the
  framework does not compare it with the child's `<name>_id` field. If
  several parents own the same child, keep `<name>_id` at the key type
  of every one of them.

The id in the per-family enum's `Unknown` variant, and the
`morph_id` field of `MorphTo`, are a `serde_json::Value`: the key as
JSON. Read it with `as_i64()` or `as_str()`.

The lazy `comment.commentable().get()` finds the target by its key and
applies no global scope of the target. The eager
`with(["commentable"])` runs the query of the target and applies its
global scopes, so a target that a scope hides comes back as `Unknown`.

A nested path goes through `MorphTo`: `with(["commentable.user"])` loads
`user` on the targets, one query for each target type that is present.
Every target of the relation must declare `user`. A target that does not
is an error that names the type and the relation, even when no row of
that type is loaded. See
[Eloquent - Polymorphic keys and nested loads](eloquent.md#polymorphic-keys-and-nested-loads).

### `MorphToMany` and `MorphedByMany`

Polymorphic many-to-many through a single pivot. One side is
"morphable" (`Post.tags()`, `Video.tags()` - both go through the same
`taggables` pivot). The other is the shared m2m partner (`Tag.posts()`,
`Tag.videos()` - same pivot, scanned the other way).

```rust
#[model(table = "tags", relations = {
    posts: MorphedByMany<Post, Taggable> {
        name = "taggable",
        target_morph_type = "post",
    },
    videos: MorphedByMany<Video, Taggable> {
        name = "taggable",
        target_morph_type = "video",
    },
})]
pub struct Tag { /* ... */ }

#[model(table = "posts", morph_type = "post", relations = {
    tags: MorphToMany<Tag, Taggable> { name = "taggable" },
})]
pub struct Post { /* ... */ }

#[model(table = "taggables", primary_key = "id", timestamps = false)]
pub struct Taggable {
    pub id: i64,
    pub tag_id: i64,
    pub taggable_id: i64,
    pub taggable_type: String,
}
```

`MorphToMany` is the mutating side - `attach` / `attach_with` / `detach`
/ `sync` / `sync_without_detaching` all live there. `MorphedByMany` is read-only: each `tag.posts()`
call returns only `Post`-typed taggables, each `tag.videos()` returns
only `Video`-typed taggables, no mixing in one collection.

Mutate from the morphable side:

```rust
post.tags().attach(rust_tag.id).await?;
post.tags().sync([rust_tag.id, async_tag.id]).await?;
```

Read from either:

```rust
let tags_on_post: Collection<Tag> = post.tags().get().await?;
let posts_with_rust_tag: Collection<Post> = rust_tag.posts().get().await?;
```

## The morph registry

Every struct annotated `#[suprnova::model(morph_type = "...")]` emits
one [`MorphTypeEntry`][morph] via `inventory::submit!` at compile
time. The registry powers three things:

1. **Per-family enum dispatch** - `MorphTo.get()` reads the child row's
   `<name>_type` string and looks it up to find the right enum variant.
2. **`MorphedByMany` target filtering** - `target_morph_type = "post"`
   resolves through the registry to ensure the type string is real.
3. **Sanity checks** - `find_morph_type("post")` returns `None` if no
   model has registered with that string, distinguishing
   "deliberately unregistered" from "typo".

```rust
use suprnova::{morph_types, find_morph_type, find_morph_type_by_id};
use std::any::TypeId;

for entry in morph_types() {
    println!("{} -> {}", entry.morph_type, entry.type_name);
}

if let Some(e) = find_morph_type("post") {
    assert_eq!(e.table, "posts");
}

let by_id = find_morph_type_by_id(TypeId::of::<Post>());
```

[morph]: https://docs.rs/suprnova

Models without a `morph_type = "..."` attribute deliberately don't
register - the registry is opt-in. A non-polymorphic `User` model
contributes nothing to it, which is what makes
`find_morph_type("user")` returning `None` a useful signal.

## Querying by relation existence

`has` / `where_has` / `doesnt_have` / `where_relation` /
`where_belongs_to` form Suprnova's relation-existence engine. They all
render as correlated `EXISTS (...)` subqueries against the **parent's
own SELECT** - no JOIN, no duplicate parent rows, no GROUP BY.

```rust
// Users with at least one post.
let with_posts = User::query().has("posts").get().await?;

// Users with at least three posts.
let prolific = User::query().has_count("posts", ">=", 3).get().await?;

// Users with at least one PUBLISHED post.
let published_authors = User::query()
    .where_has::<Post, _>("posts", |q| q.filter("published", true))
    .get()
    .await?;

// Users with NO posts.
let empty_users = User::query().doesnt_have("posts").get().await?;

// Users with no DRAFT posts (they may still have published ones).
let clean = User::query()
    .where_doesnt_have::<Post, _>("posts", |q| q.filter("published", false))
    .get()
    .await?;

// Shortcut: where_has + single column == match.
let same = User::query()
    .where_relation("posts", "published", true)
    .get()
    .await?;

// where_belongs_to - direct FK = ? on THIS table (no EXISTS needed,
// since the FK is on the child row).
let mine = Post::query()
    .where_belongs_to("author", user.id)
    .get()
    .await?;
```

You query a `MorphTo` with `has_morph`, `doesnt_have_morph`,
`where_has_morph` or `where_doesnt_have_morph`. You supply morph names, or
`"*"` for every target the relation declares in `targets = [...]`. A target
without `morph_type` answers to its snake-cased type name, the string its
parent writes. The `where_` closure receives `Builder<()>` and the
canonical morph name per type. Wildcard absence also includes null type
columns. See [MorphTo existence](eloquent.md#morphto-existence).

`has`, `has_count` and `doesnt_have` on a `MorphTo` ask every target the
relation declares, as Laravel's `has` does: `has("commentable")` renders
what `has_morph("commentable", "*")` renders, and `doesnt_have` keeps every
other row, including a null type and a type no target answers to.
`where_has::<R, _>` and `where_doesnt_have::<R, _>` apply your closure to
the owners of `R`'s type only, because the closure is written against one
model; use `where_has_morph` to constrain several types.

### How it works

The engine walks the relation inventory at query-build time. For each
named relation, it pulls the `RelationEntry` and renders the
appropriate SQL shape per kind:

- `HasOne` / `HasMany` / `MorphOne` / `MorphMany` →
  `EXISTS (SELECT 1 FROM child WHERE child.<fk> = parent.<pk>)`.
  Morph kinds add `AND child.<name>_type = '<parent_morph_type>'`.
- `BelongsTo` →
  `EXISTS (SELECT 1 FROM parent WHERE parent.<pk> = child.<fk>)`.
- `BelongsToMany` / `MorphToMany` → joins through the pivot:
  `EXISTS (SELECT 1 FROM pivot WHERE pivot.<parent_fk> = parent.<pk> ...)`.
- `HasOneThrough` / `HasManyThrough` → joins the target through the
  intermediate:
  `EXISTS (SELECT 1 FROM intermediate INNER JOIN target ON intermediate.<second_local_key> = target.<second_key> WHERE intermediate.<first_key> = parent.<pk>)`.
  A soft-deleting intermediate adds `AND intermediate.<deleted_at> IS NULL`,
  so a row reached through a trashed intermediate does not count.

The closure form (`where_has::<R, _>(rel, |q| ...)`) constructs an
inner `Builder<R>`; whatever WHERE terms that builder produces land
inside the subquery's body. Placeholder numbering is monotonic across
the whole statement, so the engine works correctly with `$1`-style
Postgres parameters.

When a relation points back at its own table, such as a category's
`children` through `parent_id` or a self-referential `BelongsToMany`, the
engine aliases the inner tables inside the subquery
(`FROM categories AS __suprnova_related`), so your filter compares each row
with its related rows and not with itself. Your outer query keeps its table
name, so a qualified column such as `categories.name` in a `where_has`
closure still refers to the parent row. A relation that points at another
table renders without the alias.

`where_belongs_to` is the one exception that doesn't render an
EXISTS. The belongs-to FK lives on the parent's *own* row, so a
direct `WHERE child.<fk> = ?` is exactly the right SQL - no subquery
needed. If the relation name is unknown to the parent's inventory,
the engine emits `WHERE 1 = 0` so the query safely returns nothing.

### Why this beats LEFT JOIN

Laravel's older `has` / `whereHas` engine used to emit JOINs and
duplicate parent rows; the correlated EXISTS rewrite landed in Laravel 9.
Suprnova ships EXISTS from day one. The advantages: no duplicates
in the result set, no GROUP BY workarounds for aggregates, no need
for `DISTINCT`, and the database's optimiser sees a real subquery
instead of a JOIN it can't push predicates through. For
`has_count(rel, ">=", n)` the engine renders
`(SELECT COUNT(*) FROM child WHERE ...) >= n` directly - one query, one
plan.

## Eager loading - `with`, `with_count`, `with_*` aggregates

The lazy `user.posts().get()` does one query per parent. That's N+1
when you have many users:

```rust
// Bad: 1 query for users + 100 queries for posts.
let users = User::query().limit(100).get().await?;
for u in &users {
    let posts = u.posts().get().await?;
    /* ... */
}
```

`prevent_lazy_loading(true)` turns that loop into an error, so you find
it in development. See
[Eloquent - Preventing lazy loading](eloquent.md#preventing-lazy-loading).

`with(["posts"])` collapses that to two queries total - regardless of
the parent count:

```rust
// Good: 1 query for users + 1 IN-query for all posts.
let users = User::query()
    .with(["posts"])
    .limit(100)
    .get()
    .await?;

for u in &users {
    for post in u.posts_loaded() {       // reads from cache, no SQL
        println!("{}: {}", u.name, post.title);
    }
}
```

Nested paths work too - dot-separated relation names recurse:

```rust
let users = User::query()
    .with(["posts.comments.author"])
    .get()
    .await?;
// 4 queries: users, posts IN users.id, comments IN posts.id, authors IN comments.user_id.
```

You cap eager has-one, has-many, morph-one and morph-many reads per parent
with `limit(n)` or `take(n)` in your constraint closure. Each parent keeps
up to that many matching children, in your chosen order. The child query
uses `ROW_NUMBER()` partitioned by its foreign key, including on SQLite.
Without an explicit order, you receive rows in primary-key order. A zero
limit loads no children. Lazy relation access keeps a plain `LIMIT`.

```rust
let posts = Post::query()
    .with_where(("comments", |q: Builder<Comment>| q.order_by_desc("id").limit(2)))
    .get()
    .await?;
```

### `with_count` and aggregates

`with_count` adds a per-relation `COUNT(*) GROUP BY parent_fk` aggregate
loaded alongside the parents - one extra query per relation:

```rust
let users = User::query().with_count(["posts"]).get().await?;
for u in &users {
    println!("{} has {} posts", u.name, u.posts_count());
}
```

Four aggregate variants stack: `with_sum`, `with_avg`, `with_min`,
`with_max`. The cache key shape is `<rel>_<kind>_<col>` so stacking
multiple aggregates on the same relation doesn't collide:

```rust
let users = User::query()
    .with_count(["posts"])
    .with_sum(("posts", "views"))
    .with_avg(("posts", "views"))
    .get()
    .await?;

for u in &users {
    println!(
        "{}: {} posts, {} views total, {} avg",
        u.name,
        u.posts_count(),
        u.posts_sum_of("views").unwrap_or(0.0),
        u.posts_avg_of("views").unwrap_or(0.0),
    );
}
```

A count or an aggregate covers the rows `with` would load: the related
model's soft-delete filter and its global scopes apply, so a trashed
post is neither counted nor summed. A `HasManyThrough` count also
leaves out rows reached through a trashed intermediate. The count of a
many-to-many relation counts its pivot rows, the attachments, as
`user.roles().count()` does.

See [Eloquent → Eager loading → Cache layout](eloquent.md#cache-layout)
for the full storage contract.

### Constrained eager loads - `with_where`

`with_where` filters which child rows land in the eager cache without
losing parents that have no matching children:

```rust
use suprnova::Builder;

let users = User::query()
    .with_where(("posts", |q: Builder<Post>| q.filter("published", true)))
    .get()
    .await?;
// Each u.posts_loaded() contains only published posts.
// Users with zero published posts still appear in the result set -
// their posts_loaded() returns an empty slice.
```

`with_where` differs from `where_has` in intent: `where_has` filters
the parent set ("users who have at least one published post");
`with_where` filters the eager cache ("for all users, load only their
published posts"). Use both together when you want both effects.

The predicate is an `Fn`, not an `FnOnce`, so a builder carrying one can
be cloned and run more than once. A closure that wants to consume a
captured value should clone it inside:

```rust
let wanted = vec!["rust".to_string(), "web".to_string()];
let users = User::query()
    // `wanted.clone()` inside, not `move` of `wanted` itself - the
    // closure may run once per clone of the builder.
    .with_where(("posts", move |q: Builder<Post>| q.filter_in("tag", wanted.clone())))
    .get()
    .await?;
```

### Cloning a query keeps its eager-load plan

`Builder` is `Clone`, and the clone carries the eager-load plan with it,
so the "build a base query, derive several from it" pattern works:

```rust
let base = User::query().with(["posts"]).filter("active", true);

let first_page = base.clone().limit(20).get().await?;
let total = base.count().await?;
// first_page rows have posts_loaded() populated.
```

### Why Suprnova diverges

Laravel's `$query->with(...)` clones freely because PHP arrays copy on
assignment. Rust has to say what a clone means for a type-erased
closure, and through v0.7.2 Suprnova answered by dropping the plan -
the clone succeeded, the query succeeded, and the relations were simply
absent. Sharing the predicate through an `Arc` makes the clone total,
at the cost of the `Fn` bound above.

Eager loading inside `chunk` / `chunk_by_id` / `lazy` remains a loud
error rather than a silent per-chunk N+1. Re-apply `.with(...)` inside
the per-chunk closure when you want it.

### Loading on already-fetched collections

When you fetch a `Collection<M>` without an eager-load plan, you can
attach one after the fact:

```rust
let mut users = User::query().get().await?;

users.load(["posts"]).await?;                 // unconditional
users.load_missing(["posts.comments"]).await?; // skip what's already loaded
```

`load_missing` walks each parent's `__eager` cache and only fires the
IN-query for rows that haven't already loaded the relation. Useful in
loops where some parents got eager-loaded earlier in the request and
others didn't.

### Opting out - `without`

`without` removes named relations from the eager plan, useful when a
base scope adds defaults you don't want for this call:

```rust
let users = User::query()
    .with(["profile", "posts", "team"])
    .without(["team"])     // drops team from the plan
    .get()
    .await?;
```

## Touching owners

A child can declare that writing it should freshen its owner's
`updated_at`:

```rust
#[model(
    table = "comments",
    touches = ["post"],
    relations = {
        post: BelongsTo<Post> { fk = "post_id" },
    },
)]
pub struct Comment {
    pub id: i64,
    pub post_id: i64,
    pub body: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

`BelongsTo` and `MorphTo` relations can be touched - the touched row has
to be identifiable from columns on the child, which is exactly what the
owning side gives you. The framework resolves the owner through the
relation registry, so the touch costs one `UPDATE` and no `SELECT`.

For a `MorphTo` name (`touches = ["commentable"]`), the owner is the row
that `<name>_type` and `<name>_id` point at. The framework finds it
after the pre-write listeners have run and before the statement. A
`<name>_type` that names none of the targets makes the write fail with
nothing written.

Owners that disclaim timestamps (`#[model(timestamps = false)]`), are
reached through a `NULL` foreign key (or a `NULL` `<name>_id`), or are
soft-deleted are skipped silently. Suppress the cascade for a block of work with
`without_touching` (all owners) or `without_touching_on::<Post, _, _>`
(one type). Full semantics in
[Eloquent - Parent touching](eloquent.md#parent-touching).

## The escape hatch

When a relation doesn't fit any of the eleven kinds - recursive trees,
polymorphic-through-non-id keys, three-way pivots, anything bespoke -
hand-write the method. The macro doesn't prevent it; you just don't
get the loaded-accessor or the eager-load dispatcher arm for that
relation.

```rust
impl User {
    /// Custom: most-recent post regardless of FK shape.
    pub async fn latest_post(&self) -> Result<Option<Post>, FrameworkError> {
        Post::query()
            .filter("user_id", self.id)
            .latest()
            .first()
            .await
    }
}
```

The trade-off is explicit: hand-written methods don't appear in the
`relations()` inventory, the existence engine doesn't know about them,
and the eager loader can't include them in a plan. For one-offs that's
fine. For anything you'd want to `with(["..."])`, declare it as a
proper relation kind even if you have to use the macro options to bend
it into shape.

## Next

- [Eloquent](eloquent.md) - the day-to-day model surface; relation
  declaration syntax lives there.
- [Database](database.md) - connections, transactions, multi-driver,
  the lower layer everything sits on.
- [Migrations](migrations.md) - the schema side of the FK columns these
  relations need to exist.
- [Query Builder](eloquent.md#query-builder---dual-api) - the dual-API
  surface that relation wrappers forward into.
- [Eloquent Resources](eloquent-resources.md) - turning loaded
  relations into JSON:API payloads for the wire.


---

<!-- /docs/eloquent-collections -->

# Eloquent collections

`Collection<T>` is Suprnova's Laravel-shape collection type - the
return value of `Builder::get`, `Model::all`, every `pluck`, every
relation-load terminal that yields more than one row. It is a thin
wrapper around `Vec<T>` that derefs to `&[T]`, so every existing
slice method (`.len()`, `.iter()`, indexing, `.contains(&v)`) works
without change. Layered on top is the Laravel surface: `map`,
`filter`, `pluck`, `group_by`, `sort_by`, `where_eq`, `sum`, `avg`,
the lot.

This chapter is the standalone reference for the collection surface.
The parent [Eloquent API](eloquent.md) summarises it; this chapter
goes through every method, the borrow-vs-consume contract, the
shared serialization policy, and when to drop down
to `Vec<T>` instead.

## Table of contents

- [Where collections come from](#where-collections-come-from)
- [The two impl blocks](#the-two-impl-blocks)
- [Generic surface - works on any `Collection<T>`](#generic-surface---works-on-any-collectiont)
- [Model-aware surface - `Collection<M>` where `M: Model`](#model-aware-surface---collectionm-where-m-model)
- [Eager loading on a collection](#eager-loading-on-a-collection)
- [Serialization - `to_array` vs serde](#serialization---to_array-vs-serde)
- [Borrow vs consume](#borrow-vs-consume)
- [Collection vs `Vec`](#collection-vs-vec)
- [`LazyCollection<M>` - streaming results](#lazycollectionm---streaming-results)
- [Why Suprnova diverges](#why-suprnova-diverges)
- [Next](#next)

## Where collections come from

Any terminal that returns more than one row hands you a
`Collection<M>`:

```rust
use suprnova::{Collection, Model};

let users: Collection<User> = User::all().await?;
let admins: Collection<User> = User::query()
    .db_where("role", "=", "admin")
    .get()
    .await?;
let recent: Collection<User> = User::query()
    .order_by_desc("created_at")
    .limit(50)
    .get()
    .await?;
```

You can also wrap any `Vec<T>` you already have:

```rust
let from_vec: Collection<User> = users_vec.into();
let from_vec2: Collection<User> = Collection::from_vec(users_vec);
let empty: Collection<User> = Collection::new();
```

`Collection<T>` implements `Default`, `Clone`, `Serialize`,
`Deserialize`, `PartialEq`, and `IntoIterator` (both by-value and by
`&`). It is `Send` when `T: Send`.

## The two impl blocks

The methods on `Collection` split into two families based on the type
parameter.

```rust
impl<T> Collection<T> { /* generic methods - work for any T */ }

impl<M> Collection<M> where M: Model { /* string-keyed model methods */ }
```

The generic block gives you `map`, `filter`, `reject`, `chunk`,
`first`, `last`, `unique`, and a closure-based version of every
column accessor (`pluck_by`, `group_by_with`, `sort_with`,
`key_by_with`). These work on `Collection<i32>`,
`Collection<String>`, `Collection<MyDto>`, anything.

The model-aware block adds string-keyed sugar (`pluck("name")`,
`group_by("role")`, `sort_by("created_at")`, `sum::<f64>("balance")`)
that routes per-row through the macro-emitted `Model::field_value`
accessor. These only exist when `T` implements `Model`.

Pick the closure form when you can - the type checker validates the
field access. Pick the string-keyed form when you're matching
Laravel's syntax, or when the column name is a runtime value.

## Generic surface - works on any `Collection<T>`

### Reading

```rust
use suprnova::Collection;

let nums: Collection<i32> = Collection::from_vec(vec![3, 1, 4, 1, 5, 9, 2, 6]);

nums.len();                         // 8
nums.is_empty();                    // false
nums.is_not_empty();                // true
nums.first();                       // Some(&3)
nums.last();                        // Some(&6)
nums.first_where(|n| **n > 3);      // Some(&4)
nums.last_where(|n| **n > 3);       // Some(&6)
nums.contains(&4);                  // true - from Deref<Target = [T]>
nums.contains_where(|n| *n > 5);    // true
```

`first_where` / `last_where` take `&&T` because the predicate runs
through `Iterator::find` on `Iter<'_, T>`. Dereference twice (`**n`).

### Transforming - consume `self`, return new collection

```rust
let doubled: Collection<i32>      = nums.clone().map(|n| n * 2);
let evens:   Collection<i32>      = nums.clone().filter(|n| n % 2 == 0);
let odds:    Collection<i32>      = nums.clone().reject(|n| n % 2 == 0);
let unique:  Collection<i32>      = nums.clone().unique();
let chunks:  Vec<Collection<i32>> = nums.clone().chunk(3);
let taken:   Collection<i32>      = nums.clone().take(4);
let skipped: Collection<i32>      = nums.clone().skip(2);
let middle:  Collection<i32>      = nums.clone().slice(2, 4);
let flipped: Collection<i32>      = nums.clone().reverse();
let shuffled: Collection<i32>     = nums.clone().shuffle();
```

`map` changes the element type:

```rust
let labels: Collection<String> = nums.clone().map(|n| format!("n={n}"));
```

`each` runs a side effect and keeps the collection for further
chaining (Suprnova diverges from Laravel here on purpose - see below):

```rust
let kept = nums.clone()
    .each(|n| tracing::debug!(value = n, "processing"))
    .filter(|n| *n > 2)
    .take(3);
```

### Closure-keyed grouping and sorting

```rust
use std::collections::HashMap;
use suprnova::indexmap::IndexMap;

// Bucket items by closure-derived key.
let by_parity: HashMap<bool, Collection<i32>> =
    nums.clone().group_by_with(|n| n % 2 == 0);

// Index items by closure-derived key (later duplicates overwrite).
let by_value: HashMap<i32, i32> =
    nums.clone().key_by_with(|n| *n);

// Sort by closure-derived comparator.
let sorted_desc: Collection<i32> =
    nums.clone().sort_with(|a, b| b.cmp(a));

// Sort `Ord` items from greatest to least; equal items keep their order.
let greatest_first: Collection<i32> = nums.clone().sort_desc();

// Project every item into a key and a value, in the collection's order.
let labels: IndexMap<i32, String> =
    nums.clone().map_with_keys(|n| (n, format!("n={n}")));

// Deduplicate by closure-derived key.
let unique_mod3: Collection<i32> =
    nums.clone().unique_by(|n| n % 3);

// Project every item by closure into a new collection.
let strs: Collection<String> =
    nums.pluck_by(|n| n.to_string());
```

`sort_desc` is Laravel's `sortDesc`: a stable sort with the comparison
reversed, so two items that compare equal stay in the order they had,
as PHP's sort keeps them. `map_with_keys` is Laravel's `mapWithKeys`: it
collects into an `IndexMap` (re-exported as `suprnova::indexmap`) in the
collection's order, and a repeated key keeps the position of its first
pair and the value of its last. `map_to_map` collects the same pairs
into a `HashMap`, which keeps no order:

```rust
use suprnova::indexmap::IndexMap;

let pairs = Collection::from_vec(vec![("a", 1), ("b", 2), ("a", 3)]);
let mapped: IndexMap<&str, i32> = pairs.map_with_keys(|(key, value)| (key, value));
assert_eq!(mapped.keys().copied().collect::<Vec<_>>(), ["a", "b"]);
assert_eq!(mapped["a"], 3);
```

The `*_with` / `*_by` suffix is the universal "this method takes a
closure" naming convention across the generic block. The
model-aware block drops the suffix and takes a column name string
instead.

### Folding and aggregating

```rust
let sum: i32 = nums.clone().reduce(0, |acc, n| acc + n);  // 31
```

For typed numeric aggregates on model collections, see `sum` / `avg`
/ `min` / `max` in the model-aware section - they work on any field
that deserialises to a numeric type.

### Set operations

```rust
let a = Collection::from_vec(vec![1, 2, 3, 4]);
let b = Collection::from_vec(vec![3, 4, 5, 6]);

let joined = a.clone().concat(b.clone());    // [1,2,3,4,3,4,5,6]
let same   = a.clone().merge(b.clone());     // alias of concat
let only_a = a.clone().diff(b.clone());      // [1,2]
let common = a.clone().intersect(b.clone()); // [3,4]
```

`concat` / `merge` are aliases - Laravel ships both names. `diff` /
`intersect` are O(n*m); if you have large collections, project to a
`HashSet` first.

### Random sampling

```rust
let one: Option<&i32>     = nums.random();        // borrow one
let many: Collection<i32> = nums.clone().random_n(3); // pick 3
```

Both use the thread-local RNG (`rand::rng()`). Pass through a seeded
RNG manually if you need determinism in tests.

## Model-aware surface - `Collection<M>` where `M: Model`

These methods only exist when the contained type is a Suprnova
model. They route per-row reads through the macro-emitted
`Model::field_value(name)` accessor, which returns
`Option<serde_json::Value>`. Rows whose field doesn't exist or
doesn't deserialise into the target type are silently skipped -
matching Laravel's missing-key behaviour.

### Lookup and identity

You find loaded models by their primary key without issuing a query:

```rust
let user: Option<&User> = users.find(7);
let same: Option<&User> = users.find_model(&another_user);
let selected: Collection<User> = users.find_many([7, 9]);
let chosen: &User = users.find_or(7, &fallback_user);
```

You get the first matching model from `find` and `find_model`. You get
matching rows in collection order from `find_many`. Repeated requested
keys do not add rows. A missing key returns `None`, an empty selection,
or your fallback. You can use a text key on a model with a custom key.

You compare model identity with `unique_models` and `diff_models`:

```rust
let unique = users.clone().unique_models();
let remaining = users.clone().diff_models(&other_users);
```

You keep the last model for each key with `unique_models`, in the order
of each key's first appearance. Models with null keys are omitted.
You remove rows whose keys occur in `other_users` with `diff_models`,
even when their other attributes differ. You retain the generic
`unique` and `diff` methods for whole-value comparisons.

### Projection

```rust
use suprnova::{Collection, Model};

let users: Collection<User> = User::query().get().await?;

let emails: Collection<String> = users.pluck::<String>("email");
let ids:    Collection<i64>    = users.pluck::<i64>("id");
```

`pluck` borrows (`&self`), so the original collection is still
available afterwards. The typed parameter (`::<String>`) is the
target type the JSON value gets deserialised into.

`pluck_keyed` produces a `HashMap<K, V>` from two columns:

```rust
use std::collections::HashMap;

let email_by_id: HashMap<i64, String> =
    users.pluck_keyed::<i64, String>("id", "email");
```

Later rows overwrite earlier ones for the same key.

`model_keys` is the primary-key shortcut, and the only projection that
returns a plain `Vec` rather than a `Collection`:

```rust
let users: Collection<User> = User::query().get().await?;
let ids: Vec<i64> = users.model_keys();
```

It reads the already-hydrated key field, so it costs no query. When you
only want the keys and haven't loaded the rows yet, use the builder
terminal instead - `User::query().model_keys().await?` projects the key
column without hydrating anything. `Vec` rather than `Collection`
matches Laravel's `modelKeys()`, and keeps the two halves of the pair
agreeing on one shape.

### Grouping and indexing

```rust
use std::collections::HashMap;

let by_role: HashMap<String, Collection<User>> = users.group_by("role");
let by_id:   HashMap<String, User>             = users.key_by("id");
```

Both methods stringify the column value into a `String` key. A
numeric `id` column comes through as `"1"` / `"2"` - matching
Laravel's `groupBy('team_id')` contract where the output is always
string-keyed regardless of the underlying type.

If you want typed keys, use the closure form on the generic block:

```rust
let by_id: HashMap<i64, User> = users.key_by_with(|u| u.id);
```

### Filtering

The model-aware `where_*` methods take `serde_json::Value` because
they compare against the JSON-encoded form of the column:

```rust
use serde_json::json;

let active: Collection<User>  = users.clone().where_eq("active", json!(true));
let admins: Collection<User>  = users.clone()
    .where_in("role", vec![json!("admin"), json!("owner")]);
let non_guests: Collection<User> = users.clone()
    .where_not_in("role", vec![json!("guest")]);
```

`where_eq` and `where_in` drop rows whose `field_value` returns
`None`. `where_not_in` *keeps* rows where the field is missing - the
negation of "in the set" is "not in the set OR absent".

### Sorting

```rust
let by_name_asc:  Collection<User> = users.clone().sort_by("name");
let by_name_desc: Collection<User> = users.clone().sort_by_desc("name");
```

Comparison is best-effort across JSON value shapes: numeric vs
numeric and string vs string sort cleanly within their kind; mixed
heterogeneous columns fall back to `Ordering::Equal`. `None` sorts
before any present value (mirrors Postgres `NULLS FIRST` for ASC).

Both methods clone the underlying `Vec<M>` before sorting because the
comparator borrows `m.field_value(field)` while `sort_by` needs
`&mut [M]`. If you have a tight loop, sort with `sort_with` on the
generic block instead - it operates in place.

### Aggregates

```rust
let total: f64           = users.sum::<f64>("balance");
let avg:   Option<f64>   = users.avg::<f64>("balance");
let lo:    Option<i64>   = users.min::<i64>("login_count");
let hi:    Option<i64>   = users.max::<i64>("login_count");
```

`sum` returns `T::default()` when no row contributes a value (zero
for numeric types). The other three return `None` so the caller
doesn't divide by zero or compare against a phantom default.

The typed parameter (`::<f64>`) is the JSON deserialisation target.
Pick the widest numeric type your column reasonably uses -
`i64` for integer columns, `f64` for decimal/float, `chrono::DateTime<Utc>`
for timestamps, etc.

## Eager loading on a collection

When you already have a `Collection<M>` and want to load relations
onto every row, use `load` / `load_missing`:

```rust
let mut users: Collection<User> = User::query().get().await?;
users.load(["posts.comments"]).await?;

for u in &users {
    for p in u.posts_loaded() {
        println!("{}: {} comments", p.title, p.comments_loaded().len());
    }
}
```

Both methods take `&mut self` (they mutate the per-row eager-cache)
and `async`. Both accept the same dotted-path syntax
`Builder::with([...])` accepts - `"posts"`, `"posts.comments"`,
`"posts.comments.author"`.

`load_missing` partitions per row. Rows that already have the
relation cached are left alone; rows that don't get the bulk-load:

```rust
let mut users: Collection<User> = User::query().with(["posts"]).get().await?;
// Some rows already have posts cached. load_missing only touches the
// rest - and recurses into already-cached posts for `comments`.
users.load_missing(["posts.comments"]).await?;
```

The recursion runs at every segment of a longer dotted path. With
`"a.b.c"`, each row is partitioned at every level: `a` is loaded only
where missing, then for the rows that already had `a`, `b` is loaded
only where missing on those `a`s, etc.

Both methods honour `#[model(connection = "...")]` routing - they
resolve the same connection the row was originally loaded from.

You constrain a relation on the models you already loaded with `load_with`:

```rust
use suprnova::Builder;

users.load_with("posts", |query: Builder<Post>| {
    query.filter("published", true)
}).await?;
```

You replace any cached value for that relation with the constrained result.
You use the relation's target model as the closure's builder type. An
unknown relation or a mismatched target returns an error. You use a flat
relation name, as you do with the builder's constrained eager loading.
With an empty collection, you skip connection resolution and the constraint.

## Serialization - `to_array` vs serde

You get the same model visibility and appends policy through `to_array`,
`to_json`, and serde:

```rust
let value: serde_json::Value = users.to_array();
let body: String = users.to_json();
let serde_body: String = serde_json::to_string(&users)?;
```

You keep hidden fields out of every row, including rows nested in Inertia
props or another serde container. You include an appended accessor only
when the model's hidden and visible lists permit its name. Instance changes
made with `make_hidden`, `make_visible`, or `append` apply to later outputs.
For non-model elements, you use their ordinary serde serialization.

## Borrow vs consume

The methods split cleanly into two contracts:

| Takes | Methods |
|---|---|
| `&self` (borrow) | `len`, `is_empty`, `is_not_empty`, `first`, `last`, `first_where`, `last_where`, `contains_where`, `random`, `find`, `find_model`, `find_many`, `find_or`, `as_slice`, `pluck_by`, `pluck`, `pluck_keyed`, `group_by`, `key_by`, `sum`, `avg`, `min`, `max`, `to_array`, `to_json` |
| `self` (consume) | `map`, `filter`, `reject`, `each`, `reduce`, `chunk`, `take`, `skip`, `slice`, `reverse`, `shuffle`, `random_n`, `unique`, `unique_models`, `diff_models`, `unique_by`, `sort_with`, `sort_desc`, `sort_by`, `sort_by_desc`, `where_eq`, `where_in`, `where_not_in`, `concat`, `merge`, `diff`, `intersect`, `group_by_with`, `key_by_with`, `map_to_map`, `map_with_keys` |
| `&mut self` | `load`, `load_missing`, `load_with` |

If you want to keep the collection after a consuming call, `.clone()`
before the call. `Collection<T>: Clone` when `T: Clone`.

A practical pattern: read first, then transform last:

```rust
let users: Collection<User> = User::all().await?;

// Borrowing reads first - the collection is still alive after each.
let total       = users.sum::<f64>("balance");
let avg         = users.avg::<f64>("balance");
let count_admin = users.iter().filter(|u| u.role == "admin").count();
let emails      = users.pluck::<String>("email");

// Now consume.
let admins: Collection<User> = users.where_eq("role", json!("admin"));
```

## Collection vs `Vec`

The wrapper is intentionally thin. The conversion routes go both
ways and stay cheap:

```rust
let v: Vec<User>          = User::query().get().await?.into_vec();
let c: Collection<User>   = Collection::from(v);
let c2: Collection<User>  = Collection::from_vec(c.clone().into_vec());
```

`Deref<Target = [T]>` gives you every slice method automatically.
That includes:

```rust
let users: Collection<User> = User::all().await?;

users.len();             // slice method
users.iter();            // slice method
users[0].name.clone();   // slice indexing
users.contains(&u);      // slice method
users.binary_search(&u); // slice method
&users[1..4];            // slice subscripting
```

`IntoIterator` is implemented twice - for `Collection<T>` (by value)
and `&Collection<T>` (by reference), so both of these work:

```rust
for user in &users {           // iter by &User
    /* ... */
}

for user in users.clone() {    // iter by User (consumes)
    /* ... */
}
```

`DerefMut` only yields `&mut [T]` - a slice, not a `Vec`. That means
in-place mutation of element fields works:

```rust
let mut users: Collection<User> = User::all().await?;
for u in users.iter_mut() {
    u.last_seen_at = Some(Utc::now());
}
```

But owned `Vec` mutation (`push`, `pop`, `clear`, `truncate`) is not
available on the collection directly - call `into_vec()` first:

```rust
let mut v = users.into_vec();
v.push(new_user);
let users: Collection<User> = Collection::from(v);
```

That's deliberate. The Laravel surface treats a collection as an
immutable snapshot you transform with chained methods; owned mutation
of the inner sequence is the `Vec` contract, not the `Collection`
contract.

### When to drop to `Vec`

Reach for `into_vec()` when:

- You need `Vec`-specific methods (`push`, `pop`, `swap_remove`,
  `drain`, `with_capacity`).
- You're handing the data off to an API that takes `Vec<T>` by value
  and you don't want the wrapper in the signature.
- You're storing the rows long-term in your own struct and the
  Laravel surface buys you nothing.

For everything else - handler returns, transformations, Inertia
props -
keep the `Collection<T>`.

## `LazyCollection<M>` - streaming results

`Collection<M>` materialises every row in memory. For datasets too
large to fit, the builder offers three streaming terminals that
return `LazyCollection<M>` instead:

```rust
use suprnova::Model;

let mut stream = User::query().lazy();
while let Some(row) = stream.next().await {
    let user = row?;
    println!("{}", user.email);
}
```

| Method | Strategy |
|---|---|
| `Builder::lazy()` | PK-cursor pagination with the default batch size (1000) |
| `Builder::lazy_by_id(n)` | PK-cursor pagination with batch size `n` |
| `Builder::cursor()` | Laravel alias for `lazy()` |

`LazyCollection<M>` is a `Pin<Box<dyn Stream<Item = Result<M, FrameworkError>> + Send>>`
underneath, but exposes `.next().await` directly so you don't need
to import `futures::StreamExt`. Each `.next()` triggers the next row
delivery; the underlying batched fetch only runs when the in-batch
buffer drains, so a slow consumer doesn't accumulate rows.

The wrapper is `Send` (so it crosses `tokio::spawn`) but not
`Sync` - it's a single-consumer stream by construction.

See [Eloquent - chunking and lazy iteration](eloquent.md#chunking-and-lazy-iteration)
for the full guidance on which streaming pattern to pick.

## Why Suprnova diverges

Laravel's `Illuminate\Support\Collection` is mutable: `$c->filter(...)`
modifies the inner array of the same object and returns `$this` for
chaining. PHP doesn't have ownership, so that contract is invisible.

Rust does have ownership, and pretending it doesn't would make the
collection surface dishonest. Suprnova picks the value-semantic
shape instead: every transformation consumes `self` and returns a
new `Collection`. You see the cost in your own code - if you want
to keep the original, you `.clone()`. If you don't, you don't.

That choice cascades through the rest of the surface:

- **`each` returns `Self`** instead of `&self` so a side-effect
  call (logging, metrics) doesn't break a chain. PHP's `each` runs
  for-effect and returns the collection; you couldn't do
  `$c->each(...)->filter(...)` cleanly without re-fetching. In
  Rust we move `self` through, keeping the chain fluent.

- **Closure-keyed alternatives to every string-keyed method.**
  `pluck_by`, `group_by_with`, `key_by_with`, `sort_with`,
  `unique_by`, `map_to_map`, `contains_where`. The closures let
  you read fields the type checker validates instead of strings
  the compiler can't see. The string-keyed forms exist for
  Laravel-syntax parity and for runtime-decided column names.

- **`sum` / `avg` / `min` / `max` take typed `::<T>` parameters.**
  Laravel's PHP version casts on the fly; in Rust, the
  deserialisation target is part of the call. Rows whose value
  doesn't round-trip into `T` are silently skipped (matching
  Laravel's missing-key behaviour), but you pick the type
  intentionally.

- **`Deref<Target = [T]>`, not `Deref<Target = Vec<T>>`.** A
  `Collection` is conceptually a "snapshot of rows", not a
  mutable buffer. Slice methods come through `Deref`; if you
  want `push`/`pop`, `into_vec()` gives you the raw `Vec` and
  removes any pretence.

- **Separate identity methods.** You use `unique_models` and
  `diff_models` for primary-key comparisons. You keep the generic
  `unique` and `diff` methods for whole-value comparisons because Rust
  does not overload inherent methods by trait bounds.

The trade-off is exactly the one Suprnova makes everywhere: Laravel's
surface shape, Rust's value semantics.

## Next

- [Eloquent API](eloquent.md) - the parent chapter, with the
  query builder, relations, scopes, and the full model lifecycle.
- [JSON:API resources](eloquent-resources.md) - resource structs
  serialise collections through `IntoJsonResource` with sparse
  fieldsets and `?include=` chains; the right shape for any
  collection that leaves your API.
- [Frontend - Inertia responses](frontend-inertia-responses.md) -
  how you hand collections to typed Inertia props.
- [Validation](validation.md) - request payloads frequently produce
  vectors that you wrap into `Collection` for downstream
  processing.
- [Testing](testing.md) - patterns for asserting on collection
  contents (length, contained elements, ordering) inside handler
  and model tests.


---

<!-- /docs/eloquent-mutators -->

# Eloquent Casts, Accessors & Mutators

A cast mediates the boundary between what a column holds on disk and
what your model carries in memory. An accessor invents a virtual
attribute from the columns you already have. A mutator routes writes
to a field through your own transform. Together with auto-managed
timestamps, they are the four moving parts that turn a flat row into
a typed Rust value.

This chapter covers the full cast surface (every built-in type, the
`casts!` runtime override, encryption and hashing), the
`#[accessor]` and `#[mutator]` attribute macros, the
auto-timestamp contract including `touch()` and `without_touching`,
and the `Replicating` lifecycle event that fires when you clone a
model with `replicate()`.

For the broader model surface (`#[suprnova::model]`, query builder,
relationships, observers) see the [Eloquent API](eloquent.md) chapter.
For lifecycle events end-to-end see [Events & Listeners](events.md).
For the crypto facade the encrypted casts use see
[Encryption](encryption.md).

## How casts work

Every cast is a struct that implements the `Cast` trait:

```rust
pub trait Cast: Send + Sync {
    type Runtime;
    type Storage;

    fn to_storage(value: &Self::Runtime) -> Result<Self::Storage, FrameworkError>;
    fn from_storage(stored: &Self::Storage) -> Result<Self::Runtime, FrameworkError>;
}
```

`Runtime` is the Rust type you write in your model struct
(`bool`, `chrono::NaiveDate`, `rust_decimal::Decimal`, your own
enum). `Storage` is the type SeaORM sees on the column
(`i64` for an SQLite boolean column, `String` for a TEXT date).
Both directions are fallible - temporal and decimal parsing can
reject malformed input - so the macro propagates the `Result`
through `From<inner::Model>` and the `ActiveModel` write path.

Casts are explicit. A `Vec<String>` field does not implicitly become
`AsArray<String>` because field-type inspection at macro time would
break the moment you renamed an alias or imported a different `Vec`.
You declare casts on the macro attribute:

```rust
use suprnova::{model, AsArray, AsBool, AsJson};

#[model(
    table = "posts",
    casts = {
        tags = AsArray<String>,
        published = AsBool,
        metadata = AsJson<serde_json::Value>,
    },
)]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub tags: Vec<String>,
    pub published: bool,
    pub metadata: serde_json::Value,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

The macro expands each `field = CastType` entry into calls into the
`Cast::to_storage` and `Cast::from_storage` on every read and write.
You never invoke the cast yourself - you write the runtime type,
the cast wires the column shape.

### Raw original attributes

You read the database snapshot before casts with `get_raw_originals()`:

```rust
let raw = user.get_raw_originals()?;
let original_role = user.get_raw_original("role");
let original_note = user.get_raw_original_or("note", "missing");
```

You get every loaded column in an `Attrs` object, including hidden columns.
You get integer boolean storage and JSON text before the casts decode them.
Changes to the current fields do not change this snapshot. A successful save
refreshes it. A model you have not loaded or saved has an empty snapshot.
You use the default only for an absent attribute; a loaded null stays null.
You keep `get_raw_original(attribute)` for a single optional stored value.

### Why Suprnova diverges

Laravel declares casts as `protected $casts = ['tags' => 'array']`.
The string `'array'` resolves to a class via a runtime lookup, which
means cast names live as untyped strings until they run. Suprnova
takes the type directly - `AsArray<String>` is a real Rust type
that the macro checks at compile time. A typo in the cast name is a
compile error, not a runtime exception three weeks after deploy.

## The primitive casts

Five casts cover the SQL scalar types.

### `AsBool`

`bool` ↔ an integer column holding 0 / 1, read and written as `i64`.
SQLite has no native boolean column, so this is the shape a boolean
takes there. On Postgres the column has to be `BIGINT`: Postgres pins
`INTEGER` to 32 bits, which the driver will not read as an `i64`. On
MySQL and MariaDB any integer column works.

A native boolean column - what the schema builder's `boolean()` creates
on Postgres - takes no cast: declare the field `bool`. Postgres refuses
`AsBool`'s integer for a `BOOLEAN` column.

```rust
#[model(table = "settings", casts = { dark_mode = AsBool })]
pub struct Settings {
    pub id: i64,
    pub dark_mode: bool,
}
```

### `AsInt<I>`

A narrower integer (`i32`, `u32`, `i16`) ↔ `i64`. SeaORM stores
integers as `i64` on the column; the cast narrows on read and
widens on write. Out-of-range values produce a validation error at
read time rather than silently truncating.

```rust
#[model(table = "counters", casts = { age = AsInt<u32> })]
pub struct Counter {
    pub id: i64,
    pub age: u32,
}
```

Use `AsInt<i64>` (or omit the cast) when the runtime type already
matches storage.

### `AsFloat`

`f64` ↔ `REAL`. Pass-through both directions - the cast exists for
naming parity with Laravel's `'float'` cast; backends round-trip
floats natively.

### `AsString`

`String` ↔ `TEXT`. Also pass-through; the cast exists so the
`Builder::with_casts(...)` runtime override can erase it to a
`DynCast` like every other cast.

### `AsDecimal<P>`

`rust_decimal::Decimal` ↔ `TEXT`. `P` is the precision (number of
decimal places); values are rounded to `P` places on the way to
storage. Default is `P = 4`. Storage is a fixed-format string so
round-trips are backend-agnostic - SeaORM's native `Decimal` column
type has different precision semantics on each driver, and the
string round-trip avoids that.

```rust
use rust_decimal::Decimal;
use suprnova::AsDecimal;

#[model(
    table = "ledger",
    casts = { amount = AsDecimal<2> },  // currency, 2 dp
)]
pub struct LedgerEntry {
    pub id: i64,
    pub amount: Decimal,
}
```

## The temporal casts

Six casts cover dates, datetimes, immutable variants, and Unix
timestamps. All non-timestamp casts store as `TEXT` (ISO-8601 /
RFC-3339) so the round-trip works on every driver - SQLite stores
datetimes as strings natively, and Postgres / MySQL accept them
through SeaORM's `Value::String` boundary.

### `AsDate`

`chrono::NaiveDate` ↔ `TEXT` (`YYYY-MM-DD`).

```rust
use chrono::NaiveDate;
use suprnova::AsDate;

#[model(table = "people", casts = { birthday = AsDate })]
pub struct Person {
    pub id: i64,
    pub birthday: NaiveDate,
}
```

### `AsDateTime`

`chrono::DateTime<Utc>` ↔ `TEXT` (RFC-3339). The default cast for
arbitrary timestamps when you want a wall-clock representation.

Writes are normalized to RFC-3339. Reads also accept the native
`CURRENT_TIMESTAMP` text emitted by PostgreSQL and timezone-free SQLite/MySQL
values; timezone-free values are interpreted as UTC. `AsImmutableDateTime` and
`AsOptionalDateTime` use the same parser.

### `AsImmutableDate` and `AsImmutableDateTime`

Same storage shape as `AsDate` / `AsDateTime`. Rust's borrow checker
already enforces immutability through `&` references, so these casts
share the underlying types - they exist for parity with Laravel's
`immutable_date` / `immutable_datetime` and to document intent at
the model declaration site.

### `AsOptionalDateTime`

`Option<DateTime<Utc>>` ↔ `Option<String>`. Auto-injected by the
`#[model(soft_deletes)]` flag for the nullable tombstone column
(`deleted_at` by default - see [Soft deletes](eloquent.md#deleting-and-soft-deletes)).
The wrapped option keeps the storage column nullable so soft-deleted
vs alive rows discriminate on `IS NULL` without a sentinel value.

Use the cast directly on any other nullable datetime column you want
to round-trip as RFC-3339 text:

```rust
#[model(
    table = "subscriptions",
    casts = { cancelled_at = AsOptionalDateTime },
)]
pub struct Subscription {
    pub id: i64,
    pub cancelled_at: Option<chrono::DateTime<chrono::Utc>>,
}
```

### Native date-time casts

The casts above store text. These four store a `DateTime<Utc>` in a native
date-time column, so the database's own date functions - grouping by
month, date arithmetic, `NOW()` comparisons - work on it:

| Cast | Field | Column |
|---|---|---|
| `AsNativeDateTime` | `DateTime<Utc>` | `timestamp with time zone` on Postgres, `TIMESTAMP` or `DATETIME` on MySQL, text on SQLite |
| `AsOptionalNativeDateTime` | `Option<DateTime<Utc>>` | the same, nullable |
| `AsNaiveDateTime` | `DateTime<Utc>` | a column without a zone holding the UTC wall clock: `timestamp` on Postgres, `DATETIME` on MySQL, text on SQLite |
| `AsOptionalNaiveDateTime` | `Option<DateTime<Utc>>` | the same, nullable |

A `DateTime<Utc>` field defaults to `AsDateTime`, so declare these per
field, or for a whole package with `datetime_cast` (described below). The
model's automatic timestamps, `touch()`, soft deletes and the touch of an
owner all store through the declared cast.

```rust
#[model(
    table = "orders",
    casts = {
        created_at = AsNativeDateTime,
        updated_at = AsNativeDateTime,
    },
)]
pub struct Order {
    pub id: i64,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

Pick the cast that matches the column: the database driver checks the
storage type against it. A table Laravel's `timestamps()` created is
`TIMESTAMP` on MySQL, which only `AsNativeDateTime` reads, and `timestamp
without time zone` on Postgres, which only `AsNaiveDateTime` reads. The
schema builder's `timestamps_tz()` and `datetimes()` create the two shapes
(see [Migrations](migrations.md#timestamps-and-soft-deletes)).

An application whose tables all have native date-time columns, such as one
ported from Laravel, can choose the cast once for a whole package in its
`Cargo.toml`, instead of naming it on each field:

```toml
[package.metadata.suprnova.model]
datetime_cast = "native"
```

`#[suprnova::model]` reads the setting from the package that declares the
model. Every `DateTime<Utc>` field without a cast of its own then gets
`AsNativeDateTime`, and every `Option<DateTime<Utc>>` field gets
`AsOptionalNativeDateTime`, the managed `created_at`, `updated_at` and
`deleted_at` included. The setting converts no column, so each value needs
its own columns:

| Value | Casts | Columns it needs |
|---|---|---|
| `"native"` | `AsNativeDateTime`, `AsOptionalNativeDateTime` | `TIMESTAMP` (what Laravel's `timestamps()` creates on MySQL) or `DATETIME` on MySQL, `timestamp with time zone` on Postgres, text on SQLite |
| `"naive"` | `AsNaiveDateTime`, `AsOptionalNaiveDateTime` | `DATETIME` on MySQL, `timestamp` (what Laravel's `timestamps()` creates on Postgres) on Postgres, text on SQLite |

Without the setting, the cast is `AsDateTime`, which needs a text column. A
field whose column differs from the rest names its own cast, which wins:

```rust
#[model(
    table = "imports",
    casts = {
        // A text column, in a package whose datetime_cast is "native".
        received_at = AsDateTime,
    },
)]
pub struct Import {
    pub id: u64,
    pub received_at: chrono::DateTime<chrono::Utc>,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

A key or a value the framework doesn't know fails the build of the model and
names it. A new project carries the setting commented out in `Cargo.toml`.

Laravel's timestamp columns are nullable, and another application can leave
them NULL. Declare such fields `Option<DateTime<Utc>>` with
`AsOptionalNativeDateTime` or `AsOptionalNaiveDateTime`: a NULL reads as
`None`, and the model's own writes still stamp them.

Queries bind through the cast too, so `filter_op("created_at", ">", "2031-03-14T12:00:00Z")`,
`where_between`, `where_date` and `update_all` send a native parameter for a
native column; Postgres refuses to compare one with text. A bare date such
as `"2031-03-14"` compares as midnight UTC. Two queries still bind text: a
model-less `DB::table` query, which knows no casts, and a `where_has`
through a `MorphTo` relation, whose related model varies by row. On
Postgres, compare a native column there in raw SQL with a typed value.

#### Why Suprnova diverges

Laravel's `datetime` cast writes whatever column the migration made, because
PHP binds every value as text and each database converts it. Postgres
refuses a text parameter for a date-time column, so a Suprnova cast names
its storage type and the default stays the text that round-trips on every
backend.

### `AsTimestamp`

Unix-epoch `i64` ↔ `INTEGER`. Use when the column is queried as a
numeric range or used in arithmetic. Distinct from `AsDateTime` -
pick `AsTimestamp` when you want `WHERE created_unix > 1700000000`
and `AsDateTime` when you want RFC-3339 strings in your logs.

## The structured casts

Five casts cover collections, structs, and arbitrary JSON. All
serialise the runtime value to JSON text and store it in a `TEXT`
column. They need a text column: Postgres refuses their text for a
`JSON` or `JSONB` column, and the MySQL driver will not read MySQL's
`JSON` type as text. For a native JSON column, use
[`AsNativeJson<T>`](#asnativejsont).

### `AsArray<T>`

`Vec<T>` ↔ JSON-encoded `TEXT`. Element type must be
`Serialize + DeserializeOwned`.

```rust
use suprnova::AsArray;

#[model(table = "posts", casts = { tags = AsArray<String> })]
pub struct Post {
    pub id: i64,
    pub tags: Vec<String>,
}
```

### `AsObject<T>`

A `Serialize + DeserializeOwned` struct ↔ JSON-encoded `TEXT`. Use
when the runtime shape is a fixed record with statically-known keys.

```rust
use serde::{Deserialize, Serialize};
use suprnova::AsObject;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Prefs {
    pub theme: String,
    pub notifications: bool,
}

#[model(table = "users", casts = { prefs = AsObject<Prefs> })]
pub struct User {
    pub id: i64,
    pub prefs: Prefs,
}
```

### `AsCollection<T>`

`Collection<T>` ↔ JSON-encoded `TEXT`. Thin wrapper over `AsArray`
that round-trips through Suprnova's `Collection<T>` (a `Vec<T>`
newtype with the Laravel-style slice surface - see
[Collections](eloquent.md#collections)).

### `AsJson<T>`

Any `Serialize + DeserializeOwned` type ↔ JSON-encoded `TEXT`. Use
when the field is a `serde_json::Value` or a user-defined struct
that's already fully describable in serde terms but doesn't fit the
fixed-shape `AsObject` pattern (e.g. enum payloads, untyped maps).

### Nullable JSON columns

The structured casts store non-null text, so they can't serve a
nullable column: `AsJson<Option<T>>` writes the text `null` instead
of SQL `NULL`, and a `NULL` row fails to decode. Each one has an
optional form for that case - `AsOptionalArray<T>`,
`AsOptionalObject<T>`, `AsOptionalCollection<T>`, `AsOptionalJson<T>`
and `AsOptionalArrayObject<T>`. The field is an `Option` of the plain
cast's type. `None` stores SQL `NULL` and a `NULL` column reads as
`None`. A value is stored and read exactly as the plain cast does it,
with the same error on malformed JSON.

```rust
use suprnova::AsOptionalJson;

#[model(table = "events", casts = { metadata = AsOptionalJson<serde_json::Value> })]
pub struct Event {
    pub id: i64,
    pub metadata: Option<serde_json::Value>,
}
```

### `AsNativeJson<T>`

Any `Serialize + DeserializeOwned` type ↔ a native JSON column:
`JSONB` or `JSON` on Postgres, `JSON` on MySQL and MariaDB, `TEXT` on
SQLite. It stores the value as JSON rather than text, so the column can
be native and the database's JSON operators and indexes work on it. A
struct, a `Vec<T>`, an `IndexMap<String, T>` or a `serde_json::Value`
all fit as `T`, so it covers what `AsObject`, `AsArray`,
`AsArrayObject` and `AsJson` do over text. `AsOptionalNativeJson<T>`
is the nullable form: `None` stores SQL `NULL`. An `update_all` or a
`filter` on the column binds a JSON parameter too.

```rust
use suprnova::{AsNativeJson, AsOptionalNativeJson};

#[model(
    table = "documents",
    casts = {
        prefs = AsNativeJson<Prefs>,
        tags = AsOptionalNativeJson<Vec<String>>,
    },
)]
pub struct Document {
    pub id: i64,
    pub prefs: Prefs,
    pub tags: Option<Vec<String>>,
}
```

### `AsArrayObject<T>`

`IndexMap<String, T>` ↔ JSON-encoded `TEXT`. Use when the runtime
shape is a dynamic-key map and the order of keys matters (the UI
ordering of labels, the canonical order of a config block). `IndexMap`
over `HashMap` is intentional: serde preserves insertion order
through `IndexMap`, and Suprnova's `serde_json` is already configured
with `preserve_order` for the same reason.

For fixed-shape records use `AsObject`; for arrays use `AsArray`.

## The enum cast

### `AsEnum<E>`

`E: FromStr + AsRef<str>` ↔ `TEXT`. The enum's variant name (or its
`AsRefStr`-customised string) is what hits the column. There is no
framework lock-in on `strum`, but it's the most ergonomic way to get
the two bounds without hand-rolling them:

```rust
use suprnova::AsEnum;

#[derive(Debug, Clone, Copy, strum::EnumString, strum::AsRefStr)]
pub enum Role {
    Admin,
    Editor,
    Viewer,
}

#[model(
    table = "users",
    casts = { role = AsEnum<Role> },
)]
pub struct User {
    pub id: i64,
    pub role: Role,
}
```

Integer-discriminant storage is intentionally not the default. A
`Role::Admin = 0` that later becomes `Role::Admin = 2` after a
re-order would silently swap every admin in the database. Variant
names are self-describing in a DB browser and stable across
re-orders.

### `AsEnumCollection<E>`

You store `Vec<E>` in a JSON column: `json` or `jsonb` on Postgres, `json`
on MySQL and MariaDB, or text holding JSON on SQLite. The cast stores a JSON
array, so the column must be native JSON on Postgres, which refuses to read a
`json` or `jsonb` value into text. Each element uses the same `AsRef<str>`
value as `AsEnum<E>`, rather than its serde enum name:

```rust
use suprnova::{AsEnumCollection, model};

#[model(table = "users", casts = { roles = AsEnumCollection<Role> })]
pub struct User {
    pub id: i64,
    pub roles: Vec<Role>,
}
```

You read a Laravel enum collection such as `["Admin","Editor"]` into your
variants and write only those storage strings, as a JSON array. You preserve
order and repeated variants. An empty vector stores `[]`. A value that is not a
JSON array of strings, and unknown variants, return a validation error. You use
the same `FromStr + AsRef<str>` bounds as `AsEnum`; runtime cast overrides also
require `Serialize + DeserializeOwned` so the dispatcher can represent your
variants.

## Encryption and hashing

Five casts mediate cryptographic transforms on the storage boundary.
All four `AsEncrypted*` casts share the [`Crypt`](encryption.md)
facade - the facade must be initialised before any of them run.
Production apps get this through `Server::from_config` (which reads
`APP_KEY` from the environment); tests call
`suprnova::testing::install_test_encryption_key()` once at startup.

### `AsEncrypted`

`String` ↔ AES-256-GCM-encrypted `String`. The on-disk column holds
URL-safe base64 of `nonce || ciphertext_with_tag`. Each write uses a
fresh random nonce, so two writes of the same plaintext produce
distinct ciphertexts - your DB admin cannot identify duplicate
secrets at rest.

```rust
use suprnova::AsEncrypted;

#[model(
    table = "secrets",
    casts = { api_key = AsEncrypted },
)]
pub struct Secret {
    pub id: i64,
    pub api_key: String,  // runtime is plain UTF-8
}
```

The runtime value is the decrypted UTF-8 string; you read and write
it like any other `String`.

### `AsEncryptedArray<T>` / `AsEncryptedObject<T>` / `AsEncryptedCollection<T>`

`Vec<T>` / `T` / `Collection<T>` ↔ AES-256-GCM-encrypted JSON. Pipeline
is: serialise to JSON → encrypt → base64 → store; reverse on read.
Element / value type must be `Serialize + DeserializeOwned`.

```rust
use suprnova::AsEncryptedObject;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
pub struct CardOnFile {
    pub last4: String,
    pub exp_month: u8,
    pub exp_year: u16,
}

#[model(
    table = "billing",
    casts = { card = AsEncryptedObject<CardOnFile> },
)]
pub struct Billing {
    pub id: i64,
    pub card: CardOnFile,
}
```

### Key rotation

The `Crypt` facade supports rotation through `APP_KEY_PREVIOUS`:
encryption always uses `APP_KEY`, but decryption tries `APP_KEY`
first and falls back to `APP_KEY_PREVIOUS` if the primary key fails.
A rolling re-encryption strategy is: set `APP_KEY` to the new key,
move the old key to `APP_KEY_PREVIOUS`, then `save()` every encrypted
row to rewrite ciphertexts under the new key. The cast layer does
not have to know about rotation - it round-trips through `Crypt` on
every read and write, so a `User::all().await?` followed by saving
each row migrates the column in place. See [Encryption](encryption.md)
for the full rotation protocol.

### `AsHashed`

`String` ↔ a hashed string on write, using the active hash driver
(`HASH_DRIVER` env var - bcrypt by default, argon2i and argon2id
also supported). The runtime value IS the hashed string; there is
no reverse direction. Mirrors Laravel's `hashed` cast.

```rust
use suprnova::AsHashed;

#[model(
    table = "users",
    casts = { password = AsHashed },
)]
pub struct User {
    pub id: i64,
    pub password: String,
}
```

`AsHashed::to_storage` is **idempotent**: a value that already looks
like ANY recognised hash (bcrypt `$2*$`, argon2i / argon2id PHC)
passes through unchanged. Without this guard,
`User::find(id).await?.save().await?` would re-hash the existing
hash into a hash-of-hash, breaking `Hash::check(plain, stored)` and
invalidating every existing password.

Pair `AsHashed` with the `#[mutator]` pattern (below) when you need
to apply more than a hash on write - e.g. normalise whitespace or
reject blank passwords before hashing.

## Runtime cast override - `casts!` macro

The casts declared in `#[model(casts = { ... })]` are static - they
fire on every read of that model. When you need a different cast on a
single query (a debug tool wants the raw stored shape, an export
script wants a different JSON representation), use
`Builder::with_casts(...)`:

```rust
use suprnova::{casts, AsDate, AsJson, User};

let map = casts! {
    birthday = AsDate,
    metadata = AsJson<serde_json::Value>,
};
let rows = User::query().with_casts(map).get().await?;
```

The `casts!` macro builds a `HashMap<&'static str, Arc<dyn DynCast>>`.
Each entry is `field_name = CastType`; every built-in cast implements
`IntoDynCast`, so the type-erased `DynCast` shadow is automatic. The
runtime-override map only applies for the duration of the chained
query - the model's static cast pipeline is unchanged.

Use this surface sparingly. The model attribute is the right place
for the casts you want every read to apply; the runtime override is
the escape hatch for one-off queries.

## Accessors - virtual attributes from real columns

An accessor is an `impl` method on the model annotated with the
`#[accessor]` macro. When you list the method's name in
`#[model(appends = [...])]`, the model's `to_json()` calls the
method and inserts the result under that key.

```rust
use suprnova::{accessor, model, Model};

#[model(
    table = "users",
    appends = ["full_name"],
)]
pub struct User {
    pub id: i64,
    pub first_name: String,
    pub last_name: String,
}

impl User {
    #[accessor]
    pub fn full_name(&self) -> String {
        format!("{} {}", self.first_name, self.last_name)
    }
}
```

A `serde_json::to_value(&user)` (or `user.to_json()`) now contains:

```json
{
  "id": 1,
  "first_name": "Alice",
  "last_name": "Xu",
  "full_name": "Alice Xu"
}
```

The method is also callable directly (`user.full_name()`) - the
`#[accessor]` macro is mostly a marker so the struct-level
`#[suprnova::model]` macro can wire the `to_json()` dispatch. There
is no cost to calling it from your own code.

Each name in `appends` must match a real `#[accessor]` method by
identifier. A typo (`appends = ["fullName"]` when the method is
`full_name`) is caught at compile time with a pointed error message.

### Runtime appends

You register an accessor for runtime selection with `accessors = [...]`.
You add it to one model instance with `append(name)`:

```rust
#[model(table = "users", accessors = ["full_name"])]
pub struct User { /* columns */ }

user.append("full_name")?;
let body = user.to_array();
```

You keep the name on that instance for every later array, JSON, and serde
conversion. Repeated appends add the name once. An unregistered name returns
an error without changing the output. You register default appends through
`appends = [...]`; those names also support `append`.
You filter default and runtime appends through the model's hidden and visible
lists before calling the accessor. You reveal or hide an appended name with
`make_visible` or `make_hidden` just as you do a stored attribute.

### Returning non-`String` values

Accessors can return any `Serialize` type. The macro converts the
returned value through `serde_json::to_value` before insertion, so:

```rust
impl Post {
    #[accessor]
    pub fn word_count(&self) -> usize {
        self.body.split_whitespace().count()
    }
}
```

renders as `"word_count": 42` in the JSON output.

### Hiding the source columns

When the accessor's value is what the consumer should see and the
underlying columns are noise, pair `appends` with `hidden`:

```rust
#[model(
    table = "users",
    appends = ["full_name"],
    hidden = ["first_name", "last_name"],
)]
```

You strip the named source columns with `hidden`. You include the accessor
when its own name passes the same hidden and visible filters. See
[Hidden, visible, and appends](eloquent.md#mass-assignment) for the
complete surface.

## Mutators - routed writes through your transform

A mutator is the write-side counterpart. When the field's name appears
in `#[model(mutators = [...])]`, every mass-assignment path (`create` /
`update`) routes the value through `self.set_<field>(value)?` instead
of assigning the field directly.

```rust
use serde_json::Value;
use suprnova::{model, mutator, FrameworkError, Model};

#[model(
    table = "users",
    fillable = ["password"],
    mutators = ["password"],
)]
pub struct User {
    pub id: i64,
    pub password: String,
}

impl User {
    #[mutator]
    pub fn set_password(&mut self, value: Value) -> Result<(), FrameworkError> {
        let raw: String = serde_json::from_value(value).map_err(|e| {
            FrameworkError::validation("password", format!("{e}"))
        })?;
        // Normalise + hash; AsHashed would do the hash on its own,
        // but the mutator is where you can also enforce policy.
        let trimmed = raw.trim().to_string();
        if trimmed.len() < 12 {
            return Err(FrameworkError::validation(
                "password",
                "must be at least 12 characters",
            ));
        }
        self.password = suprnova::hashing::hash(&trimmed)?;
        Ok(())
    }
}
```

`set_password` receives a `serde_json::Value`. The body owns the
deserialise + transform - the field type on the struct can stay
`String`, and your validation runs before the column is touched.
A returned error propagates through `create()` / `update()` as a
`bad_request`.

Direct field assignment bypasses the mutator:

```rust
user.password = "raw".to_string();  // skips set_password
user.save().await?;                 // saves "raw"
```

This matches Laravel's `$user->password = ...` vs `$user->fill(...)`
behaviour. When you want the mutator to be the only path, route
all writes through `attrs!` + `create` / `update`.

### Combining mutators with casts

A mutator and a cast can coexist on the same field; the mutator runs
on the write path (when `create` / `update` is called), the cast runs
on the read path (when the column is materialised from a SELECT).
A common pattern is to use `AsHashed` for the read-side idempotence
guarantee and the mutator for write-side validation - the mutator
hashes, `AsHashed` sees an already-hashed value and passes through.

## Auto-managed timestamps

When a model carries both `created_at` and `updated_at` fields
(typed `chrono::DateTime<chrono::Utc>`), the macro:

- Sets both to `Utc::now()` on `create()`.
- Bumps `updated_at` on every `save()` and `update(attrs)`.
- Emits an `impl Touchable for YourStruct` so you can call
  `.touch().await` to bump `updated_at` without changing any other
  column.

```rust
use chrono::{DateTime, Utc};
use suprnova::{model, Model, Touchable};

#[model(table = "posts")]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

// Bump updated_at without other changes:
let post = Post::find_or_fail(1).await?;
post.touch().await?;
```

Storage uses the `AsDateTime` cast that the macro auto-injects for
timestamp columns. The cast lets the same `DateTime<Utc>` value
round-trip across all three SeaORM drivers (SQLite, MySQL,
PostgreSQL) without forcing you to pick a database-specific
timestamp type.

### Opt-out and custom column names

`#[model(timestamps = false)]` disables the auto-management entirely -
you control the timestamps yourself.

`#[model(created_at = "creado_en", updated_at = "actualizado_en")]`
keeps the auto-management but renames the columns. The macro
detects the renamed fields and wires the same logic against them.

When the struct has only ONE of the two timestamp fields, the macro
emits a `compile_error!` - almost always a typo (`craeted_at`)
that you want surfaced loudly rather than silently swallowed.

### `without_touching` - task-scoped suppression

Sometimes you want to update a row without bumping `updated_at` -
running a backfill, fixing a typo, recording an internal sync that
shouldn't reset cache TTLs keyed on `updated_at`. Wrap the work in
`without_touching`:

```rust
use suprnova::eloquent::without_touching;

without_touching(async {
    for post in Post::query().get().await? {
        post.touch().await?;  // no-op inside the scope
    }
    Ok::<_, suprnova::FrameworkError>(())
}).await?;
```

The flag is a `tokio::task_local!` so it doesn't leak across
`tokio::spawn` boundaries - concurrent requests on other tasks
continue to honour their own scope (or its absence). This is the
Suprnova analogue of Laravel's `Model::withoutTouching(closure)`.

### Why Suprnova diverges

Laravel uses a static `$timestamps = false` property and a global
`Model::withoutTouching` static method backed by an instance counter.
Both approaches assume request-per-process isolation. Suprnova runs
many requests on one Tokio runtime, so a process-global flag would
let one request silently suppress timestamps on another. The
`tokio::task_local!` scope is async-aware: it follows futures
across `.await` points within the same task and goes out of scope
when the future drops, no matter how the request ends.

## The `Replicating` lifecycle event

Of the 16 model lifecycle events (see [Observers and lifecycle
events](eloquent.md#observers-and-lifecycle-events)), `Replicating`
is the one that fires when you clone an existing row into an unsaved
in-memory copy via `replicate()`:

```rust
let original = Post::find_or_fail(1).await?;
let mut copy = original.replicate().await?;  // unsaved
copy.title = format!("{} (copy)", original.title);
let copy = copy.persist().await?;  // inserted with a new PK (`use suprnova::Persistable;`)
```

The `Replicating` event fires AFTER the in-memory clone is built but
BEFORE you've had a chance to mutate it. Listeners receive
`(&Self, Arc<Mutex<Self>>)` - the original and the freshly-built
replica behind a `Mutex`, so you can mutate the replica from the
listener before the user sees it:

```rust
use suprnova::{Listener, FrameworkError};

pub struct ResetReplicatedFlags;

#[async_trait::async_trait]
impl Listener<post::events::Replicating> for ResetReplicatedFlags {
    async fn handle(&self, event: &post::events::Replicating) -> Result<(), FrameworkError> {
        let mut replica = event.replica.lock().await;
        replica.published = false;       // copies start unpublished
        replica.view_count = 0;          // counters reset
        Ok(())
    }
}
```

The replica's PK is already cleared by the time the listener runs -
`replicate()` calls `reset_primary_key()` before firing the
event, so you can't accidentally re-save under the original ID.
Timestamps are also reset; `created_at` / `updated_at` fire on the
subsequent `persist()` like any new row. `save()` refuses a replica:
it has no row yet, and its reset key would name another row.

### `replicate_into<T>` - cross-type replication

When the replica is a different type (`Post` → `Draft`, say), use
`replicate_into::<Draft>()`. The `Replicating` event does NOT fire on
this path because the event struct is per-source-type and a listener
registered for `post::events::Replicating` would receive an
`Arc<Mutex<Post>>`, not an `Arc<Mutex<Draft>>`. The cross-type path
is for when you want a fresh target type without observer interference;
register a normal `Creating` listener on the target type if you want a
hook at construction.

See [Replication](eloquent.md#replication) for the rest of the
replicate surface (`replicate_except`, the replica's relation
handling, the rules for nullable PKs).

## Putting it together

A model with every surface from this chapter:

```rust
use chrono::{DateTime, Utc};
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use suprnova::{
    accessor, hashing, model, mutator, AsBool, AsDateTime,
    AsDecimal, AsEncryptedObject, AsEnum, AsHashed, AsJson,
    AsOptionalDateTime, FrameworkError, Model,
};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CardOnFile {
    pub last4: String,
    pub exp_month: u8,
    pub exp_year: u16,
}

#[derive(Debug, Clone, Copy, strum::EnumString, strum::AsRefStr)]
pub enum Role {
    Admin,
    Editor,
    Viewer,
}

#[model(
    table = "users",
    soft_deletes,
    appends = ["display_name"],
    hidden = ["password", "card"],
    fillable = ["name", "email", "password", "role", "credit"],
    mutators = ["password"],
    casts = {
        role = AsEnum<Role>,
        verified = AsBool,
        credit = AsDecimal<2>,
        card = AsEncryptedObject<CardOnFile>,
        metadata = AsJson<serde_json::Value>,
        password = AsHashed,
        last_login_at = AsOptionalDateTime,
    },
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub password: String,
    pub role: Role,
    pub verified: bool,
    pub credit: Decimal,
    pub card: CardOnFile,
    pub metadata: serde_json::Value,
    pub last_login_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    // deleted_at is auto-injected by soft_deletes (AsOptionalDateTime)
}

impl User {
    #[accessor]
    pub fn display_name(&self) -> String {
        if self.name.is_empty() { self.email.clone() } else { self.name.clone() }
    }

    #[mutator]
    pub fn set_password(&mut self, value: Value) -> Result<(), FrameworkError> {
        let raw: String = serde_json::from_value(value).map_err(|e| {
            FrameworkError::validation("password", format!("{e}"))
        })?;
        let trimmed = raw.trim().to_string();
        if trimmed.len() < 12 {
            return Err(FrameworkError::validation(
                "password",
                "must be at least 12 characters",
            ));
        }
        // The mutator hashes; AsHashed sees an already-hashed value
        // on subsequent saves and passes through unchanged.
        self.password = hashing::hash(&trimmed)?;
        Ok(())
    }
}
```

This single declaration gives you:

- Eight typed casts wiring the storage / runtime boundary.
- An accessor that synthesises `display_name` from existing columns.
- A mutator that validates and hashes the password.
- Auto-managed `created_at` / `updated_at`.
- Soft deletes with an auto-injected `deleted_at` column.
- Encrypted card-on-file storage with key-rotation support.

Every cast is checked at compile time. The dual-API query builder
(see [Eloquent - query builder](eloquent.md#query-builder---dual-api))
runs against the typed columns; serialisation to Inertia / JSON
applies the hidden / appends rules; and a `User::find(id).await?`
materialises the row through eight `Cast::from_storage` calls
without you writing a single line of conversion code.

## Next

- [Eloquent API](eloquent.md) - the rest of the model surface: query
  builder, relationships, observers, pagination, transactions.
- [Encryption](encryption.md) - the `Crypt` facade the encrypted
  casts share, key rotation protocol, and the wider crypto surface.
- [Events & Listeners](events.md) - the dispatcher behind
  `Replicating` and the other 15 model lifecycle events.
- [Authentication](authentication.md) - the `Authenticatable` trait
  and where `AsHashed` fits into the password flow.
- [Validation](validation.md) - `FrameworkError::validation` and the
  pattern mutators use to surface per-field errors.


---

<!-- /docs/eloquent-resources -->

# JSON:API resources

Suprnova ships a JSON:API resource layer for typed REST APIs. Mark a
`#[derive(Data)]` struct with `#[json_resource("type")]` and the framework
emits an `IntoJsonResource` impl that handles single envelopes, collections,
paginated collections, sparse fieldsets (`?fields[type]=...`), compound
`included` documents, and multi-level `?include=a.b.c` chains through the
same code path. The two facades - `Resource` and `JsonApi` - are the same
type under two names; use whichever matches your house style.

## Defining a resource

```rust
use suprnova::Data;

#[derive(Debug, Clone, Data)]
#[json_resource("users")]
pub struct UserResource {
    pub id: i64,
    pub email: String,

    // `input_only` keeps `password` available on the form-request side
    // but suppresses it from the API output.
    #[data(input_only)]
    pub password: String,

    // Marks a field as a *relationship*: it never lands in `attributes`,
    // it produces a JSON:API relationship object instead, and it is
    // eligible for `?include=`. The field type must implement
    // `IntoJsonResource` (directly, or via `Vec<T>` / `Option<T>`).
    #[data(allow_include)]
    pub posts: Vec<PostResource>,
}
```

The `id_field` keyword renames the field that supplies the JSON:API `id`:

```rust
#[derive(Data)]
#[json_resource("orders", id_field = "uuid")]
pub struct OrderResource {
    pub uuid: String,
    pub total_cents: i64,
}
```

## Rendering responses

Construct a pending response from a handler and call `.render().await`:

```rust
use suprnova::{LengthAwarePaginator, Resource};

#[handler]
async fn show_user(id: i64) -> Result<HttpResponse, FrameworkError> {
    let user: UserResource = User::find_or_fail(id).await?.into();
    Resource::single(user).render().await
}

#[handler]
async fn list_users() -> Result<HttpResponse, FrameworkError> {
    let users: Vec<UserResource> = User::all().await?.into_iter().map(Into::into).collect();
    Resource::collection(users).render().await
}

#[handler]
async fn paginate_users() -> Result<HttpResponse, FrameworkError> {
    // `paginate(per_page)` reads `?page=` from the current request automatically.
    let page = User::query().paginate(10).await?;
    // Transform each item while keeping the page metadata.
    let page = page.through(UserResource::from).with_path("/api/users");
    Resource::paginated(page).render().await
}
```

`JsonApi::single` / `JsonApi::collection` / `JsonApi::paginated` are
identical alias entry points if you prefer the Laravel spelling.

## Chainable mutators

`JsonApiResponse` is a pending object. Customise the envelope before
calling `.render().await`. Every mutator is `self` → `Self` so they
compose:

```rust
use suprnova::{Resource, JsonApiInfo};
use serde_json::json;

let info = JsonApiInfo::new()
    .with_version("1.1")
    .with_ext("https://jsonapi.org/ext/atomic")
    .with_meta("copyright", json!("2026 Acme Inc."));

Resource::single(user)
    .status(201)                                  // HTTP status override
    .with_meta("trace_id", json!("req-7"))        // top-level meta KV
    .with_link("self", "/api/users/1")            // top-level link
    .with_jsonapi(info)                           // top-level `jsonapi`
    .additional(json!({ "api_version": "2.0" }).as_object().unwrap().clone())
    .render()
    .await
```

| Mutator | Laravel analogue | Effect |
|---|---|---|
| `.status(code)` | `ResourceResponse::calculateStatus` | Overrides HTTP status. |
| `.created()` | `wasRecentlyCreated → 201` | Shorthand for `.status(201)`. |
| `.with_meta(k, v)` / `.meta(k, v)` | `with($request)` | Top-level `meta` KV. |
| `.with_meta_map(m)` | bulk `with($request)` | Merge a map into top-level `meta`. |
| `.with_link(rel, href)` / `.link(rel, href)` | `with($request)['links']` | Top-level `links` KV. |
| `.with_link_value(rel, v)` | link-object form | Top-level link as `{href, meta}`. |
| `.with_additional(k, v)` | `additional($data)` | Root-level key alongside `data`. |
| `.additional(map)` | `additional($data)` | Bulk additional keys. |
| `.with_jsonapi(info)` | `JsonApiResource::configure(...)` | Top-level `jsonapi` member. |

Canonical members (`data`, `included`, `links`, `meta`, `jsonapi`,
`errors`) are never overwritten by `.additional(...)`.

Set application-wide implementation information once in your bootstrap:

```rust
use suprnova::{JsonApiInfo, jsonapi_default};

jsonapi_default(Some(JsonApiInfo::new().with_version("1.1")))?;
```

You apply the default to single resources, collections, and paginated
collections, including empty collections. Override it for one response with
`.with_jsonapi(info)`. Pass `None` to `jsonapi_default` to clear it.

## Per-resource `links` and `meta`

Override the `IntoJsonResource::resource_links` and
`IntoJsonResource::resource_meta` defaults to attach links / metadata
to the *resource object*, not the document root:

```rust
use suprnova::resources::IntoJsonResource;
use serde_json::{Map, Value};

impl IntoJsonResource for MyHandRolledPost {
    // ...

    fn resource_links(&self) -> Map<String, Value> {
        let mut m = Map::new();
        m.insert("self".into(), Value::String(format!("/api/posts/{}", self.id)));
        m
    }

    fn resource_meta(&self) -> Map<String, Value> {
        let mut m = Map::new();
        m.insert("kind".into(), Value::String("blog".into()));
        m
    }
}
```

Both default to an empty `Map` for macro-derived resources, so the
JSON:API renderer omits the keys when not used. Override
`resource_top_level_meta` to supply top-level `meta` for a single resource.
For a collection, attach document metadata with `.with_meta(...)` or
`.with_meta_map(...)`. You keep that metadata at the root without copying
any first item's top-level metadata. Each item's `resource_meta` remains
inside its own resource object.

## Conditional attributes - `Maybe<T>` / `MissingValue<T>`

Use `Maybe` to omit a field from the rendered `attributes` object based
on a runtime condition. This is the Suprnova analogue of Laravel's
`MissingValue` and the `when()` / `whenLoaded()` / `unless()` family.

```rust
use suprnova::{Maybe, MissingValue};

// Both names point at the same type.
let m1: Maybe<&str> = Maybe::present("email@example.com");
let m2: MissingValue<&str> = MissingValue::missing();
let m3 = Maybe::when(user.is_verified, &user.verified_at);
let m4 = Maybe::unless(user.is_admin, &user.public_handle);
let m5 = Maybe::when_with(expensive_check(), || compute_value()); // lazy
```

For macro-derived structs, declare a field as `Maybe<T>` and the
renderer drops it automatically when `Missing`. For hand-rolled
`resource_attributes`, use the `insert_maybe(map, key, maybe)` helper:

```rust
use suprnova::resources::{insert_maybe, Maybe};

fn resource_attributes(&self, _fs: Option<&[&str]>) -> serde_json::Value {
    let mut map = serde_json::Map::new();
    insert_maybe(&mut map, "email", Maybe::present(&self.email));
    insert_maybe(
        &mut map,
        "phone",
        if self.show_phone { Maybe::present(&self.phone) } else { Maybe::missing() },
    );
    serde_json::Value::Object(map)
}
```

The renderer also calls `strip_missing_values(&mut value)` over the
entire attributes object, so `Maybe::Missing` values nested inside
arbitrary serde-derived structures are dropped recursively - useful
when a deeply-nested transformer wants to omit subfields.

Use `merge_when(condition, fields)` to include several attributes together.
You store the group in a `MergeValue<T>` field, with fields that serialize
to an object. The group's field name disappears from the output. Its
members join the surrounding attributes when the condition is true:

```rust
use suprnova::{Data, MergeValue, Validate, merge_when};
use serde_json::{Value, json};

#[derive(Debug, Clone, Data, Validate)]
#[json_resource("users")]
pub struct UserResource {
    pub id: i64,
    pub name: String,
    pub details: MergeValue<Value>,
}

let resource = UserResource {
    id: user.id,
    name: user.name.clone(),
    details: merge_when(can_view_email, json!({ "email": user.email })),
};
```

You omit the whole group when the condition is false. A present group must
serialize to an object; scalar fields produce a serialization error.
Merged members follow sparse fieldsets under their own names, and a
`Maybe::Missing` member is omitted while an explicit null remains.

Use `with_exists(relation)` when you need a flag without related rows:

```rust
use suprnova::when_exists_loaded;

let users = User::query().with_exists("posts").get().await?;
let user = &users[0];
let posts_exists = when_exists_loaded(user, "posts", |exists| exists);
```

You read the `<relation>_exists` flag with
`user.__eager.get_exists("posts")`. You get `Some(false)` when the loaded
relation has no rows, and `None` when you did not request the flag. Place
`posts_exists` in a `Maybe<bool>` resource field to emit true or false when
loaded and omit it otherwise. The closure runs only for a loaded flag.
Existence flags coexist with counts and loaded rows; requesting a flag
alone leaves the relation unloaded. An unknown relation returns an error,
even when your query has no matches.

## Sparse fieldsets

The framework's `IncludeMiddleware` parses
`?fields[type]=email,name`-style query parameters and binds them to a
task-local. You get only the requested
attributes after conditional groups merge. Install the middleware to bind
the fieldset without extra handler work.

```rust
// Request: GET /api/users/7?fields[users]=email
// Response: { "data": { "type": "users", "id": "7", "attributes": { "email": "alice@example.com" } } }
```

## Compound documents with `?include=` chains

Declare relationship fields with `#[data(allow_include)]`. The framework
builds an `IncludeTree` from `?include=author.posts.tags,comments`, walks
every node, and pushes fully-resolved resource objects into `included`.
Deduplication runs at push time through `IncludedSink`, keyed by
`(type, id)` per JSON:API spec §8 - so a 1,000-item collection where
every item shares the same author resolves the author exactly once. Peak
memory and CPU stay proportional to the distinct included resources,
not the relationship fan-in.

```rust
#[derive(Data)]
#[json_resource("posts")]
pub struct PostResource {
    pub id: i64,
    pub title: String,

    #[data(allow_include)]
    pub author: Option<AuthorResource>,

    #[data(allow_include)]
    pub tags: Vec<TagResource>,
}
```

A request that names an include path not on this resource's allowlist
gets a JSON:API 400 errors envelope. The path is checked against the
resource types, not against the values in the response, so an empty
collection refuses an unknown path too. A request that names a supported
path always gets an `included` array, empty when nothing relates. A
resource that is already primary data never repeats in `included`. A
field marked `#[data(input_only, allow_include)]` is never sent: it has
no relationship linkage, and including it is a 400.

### Depth cap

An include path may carry at most five segments. `?include=a.b.c.d.e.f` is
truncated to `a.b.c.d.e` before anything walks it, matching Laravel's
`JsonApiResource::$maxRelationshipDepth`. Change the ceiling once at boot:

```rust
// In bootstrap::register()
suprnova::max_relationship_depth(3);
```

The cap matters because a relationship graph can be cyclic:
`?include=author.posts.author.posts...` costs more work with every segment
a client types, and nothing else bounds it but the length of the query
string. Truncation only removes segments, never adds them, and every level
still checks its own allowlist before descending - so a truncated path can
never reach data the full path could not.

One consequence is worth knowing: a segment past the cap is dropped before
the allowlist sees it. At a cap of 2, `?include=author.posts.secrets`
returns 200 with `author` and `posts` included rather than the 400 the full
path would earn, because `secrets` no longer exists by the time anything
validates it.

`max_relationship_depth(0)` turns includes off entirely. Laravel's 0 still
emits the first hop, because its clamp only ever applies to the tail after
the leading segment has been split off; Suprnova's 0 means no
relationships at all.

### Why Suprnova diverges

Three visible divergences from Laravel's `JsonApiResource`:

1. **Strict default-deny for `?include=`.** Laravel's resource layer silently
   ignores include paths that don't resolve. Suprnova rejects them with a
   `400 Bad Request` carrying a JSON:API errors envelope. The spec's
   §5.2.2 default-deny posture is the contract clients can program against;
   silent ignore hides client bugs and breaks compound-document integrity.

2. **Explicit `.status(code)` / `.created()` instead of auto-201.** Laravel
   auto-sets `201` from `wasRecentlyCreated` on the underlying Eloquent
   model. Suprnova decouples the resource DTO from any specific persistence
   lifecycle, so the status is set on the response object itself -
   `.created()` when you mean it, `.status(204)` when the response is empty,
   and so on. A single mutator stays honest under any flow.

3. **A depth cap of `0` turns includes off entirely.** Laravel clamps only
   the tail of a path, after the leading segment has already been split
   off, so its `0` still emits the first hop. Suprnova truncates the whole
   path, so `max_relationship_depth(0)` means no relationships at all - see
   Depth cap above.

## Pagination

`Resource::paginated(p)` works with any paginator implementing the
`Paginated<T>` trait - both `LengthAwarePaginator<T>` and
`CursorPaginator<T>` from `suprnova::pagination` ship this impl. The
renderer attaches `links.{self,first,prev,next,last}` and a
`meta.pagination` block automatically.

```rust
use suprnova::{LengthAwarePaginator, Resource};

let page = LengthAwarePaginator::new(items, total, per_page, current_page)
    .with_base_url("/api/users");
Resource::paginated(page).render().await
```

## Error envelopes

Every `FrameworkError` knows how to render itself as a JSON:API
`{"errors": [...]}` envelope via `into_json_api_response()`. The
helper is exposed because `FrameworkError` carries a status code, a
field-name source pointer (for `ValidationError`, escaped per RFC 6901,
so an attribute named `a/b` is `/data/attributes/a~1b`), and a request-id
correlation token under `meta.request_id`. 5xx responses are
sanitised: the raw message never reaches the client unless
`APP_DEBUG=true` is set in the active environment, in which case it
appears under `meta.debug_message`.

```rust
let response = FrameworkError::validation("email", "email is invalid")
    .into_json_api_response();
// {
//   "errors": [{
//     "status": "422",
//     "title": "Validation failed",
//     "detail": "email is invalid",
//     "source": { "pointer": "/data/attributes/email" },
//     "meta": { "request_id": "..." }
//   }]
// }
```

## Surfaces summary

| Suprnova surface | Laravel 13 equivalent |
|---|---|
| `Resource` / `JsonApi` facades | `JsonResource::make`, `JsonApiResource` |
| `JsonApiResponse` | `ResourceResponse`, `JsonApiResource::toResponse` |
| `JsonApiBuilder` | (internal builder for `ResourceResponse`) |
| `IntoJsonResource` trait | `JsonResource::toArray`, `toAttributes`, `toRelationships`, `toLinks`, `toMeta`, `with` |
| `RelationshipValue` / `ResourceIdentifier` | array shape inside `toRelationships` |
| `IncludeTree` | parsed `?include=` from `JsonApiRequest` |
| `RequestFieldsetSet` | parsed `?fields[type]=` from `JsonApiRequest` |
| `Maybe<T>` / `MissingValue<T>` | `MissingValue` + `whenLoaded` / `when` / `unless` |
| `merge_when` / `MergeValue<T>` | `mergeWhen` |
| `when_exists_loaded` | `whenExistsLoaded` |
| `jsonapi_default` | application-wide `JsonApiResource::configure` |
| `JsonApiInfo` | `JsonApiResource::$jsonApiInformation` |
| `JsonApiResponse::status(code)` / `.created()` | `ResourceResponse::calculateStatus` |
| `JsonApiResponse::additional(map)` / `.with_additional(k, v)` | `JsonResource::additional($data)` |
| `JsonApiResponse::with_meta(k, v)` / `.meta(k, v)` | `JsonResource::with($request)['meta']` |
| `JsonApiResponse::with_link(rel, href)` / `.link(rel, href)` | `JsonResource::with($request)['links']` |
| `JsonApiResponse::with_jsonapi(info)` | `JsonApiResource::configure(...)` |
| `current_fieldset()` / `scope_fieldset(...)` | task-local fieldset, set by `IncludeMiddleware` |
| `IncludeResolutionError` → 400 envelope | strict-mode `?include=` parser |

Top-level re-exports under `suprnova::`: `Resource`, `JsonApi`,
`JsonApiResponse`, `JsonApiBuilder`, `JsonApiInfo`, `IncludedSink`,
`IntoJsonResource`, `RelationshipValue`, `ResourceIdentifier`,
`IncludeTree`, `RequestFieldsetSet`, `Maybe`, `MissingValue`,
`insert_maybe`, `merge_when`, `MergeValue`, `when_exists_loaded`,
`jsonapi_default`, `strip_missing_values`, `AsRelationshipValue`,
`PushIncluded`, `IncludeResolutionError`, `current_fieldset`,
`scope_fieldset`.

## Next

- [Eloquent serialization](eloquent-serialization.md) - `#[derive(Data)]`,
  hidden/visible fields, the `toArray` equivalent that feeds resource
  attributes
- [Eloquent relationships](eloquent-relationships.md) - what
  `#[data(allow_include)]` consumes; the typed relation kinds backing
  compound documents
- [Pagination](pagination.md) - `LengthAwarePaginator`, `CursorPaginator`,
  and the `Paginated<T>` trait `Resource::paginated` consumes
- [Data](data.md) - the `#[derive(Data)]` macro shared with Inertia, the
  `?include=`/`?fields[type]=` middleware, and `Maybe<T>` patterns
- [Error model](error-model.md) - how `FrameworkError::into_json_api_response`
  fits the conversion contract


---

<!-- /docs/eloquent-serialization -->

# Eloquent Serialization

You convert Eloquent models to arrays, JSON, and serde output with one
visibility policy. You declare hidden fields, visible fields, and default
appends on the model. You can change visibility or add an append on one
instance. You include eager-loaded relations through explicit accessors
or resources.

## Table of contents

- [The contract](#the-contract)
- [`to_array` and `to_json`](#to_array-and-to_json)
- [Hiding fields - `hidden = [...]`](#hiding-fields---hidden--)
- [Whitelisting fields - `visible = [...]`](#whitelisting-fields---visible--)
- [Appending accessors - `appends = [...]`](#appending-accessors---appends--)
- [The filter pipeline order](#the-filter-pipeline-order)
- [Per-call filtering - `to_array_except` / `to_array_only`](#per-call-filtering---to_array_except--to_array_only)
- [Conditional hiding by viewer](#conditional-hiding-by-viewer)
- [Serde serialization](#serde-serialization)
- [Serializing collections](#serializing-collections)
- [Eager-loaded relations and serialization](#eager-loaded-relations-and-serialization)
- [What about JSON:API?](#what-about-jsonapi)
- [Where each piece lives](#where-each-piece-lives)
- [Next](#next)

## The contract

Every `#[suprnova::model]` struct gets two serialization methods from
the `Model` trait:

```rust
fn to_array(&self) -> serde_json::Value;
fn to_json(&self) -> String;
```

`to_array` produces a `serde_json::Value` for use in handler responses
and tests. `to_json` is a thin wrapper -
`serde_json::to_string(&self.to_array())` - so a single filter
pipeline owns both shapes.

The output is a JSON object keyed by struct field name (or whatever
serde rename you've applied), filtered through three optional knobs
declared on `#[model(...)]`:

- `hidden = [...]` - column denylist
- `visible = [...]` - column whitelist (mutually exclusive with `hidden`)
- `appends = [...]` - accessor methods to inject under named keys

You use the same policy through the model's `Serialize` implementation.
You exclude the framework's `__eager` and `__pivot` state on every path.
You keep persistence separate from this output policy, so hidden fields
still participate in saves.

## `to_array` and `to_json`

The minimum useful example - a row out the door as JSON:

```rust
use suprnova::{json_response, model, Model, Request, Response};
use chrono::{DateTime, Utc};

#[model(table = "users")]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| suprnova::FrameworkError::param_parse("id", "i64"))?;
    let user = User::find_or_fail(id).await?;
    json_response!(user.to_array())
}
```

`json_response!` accepts any `serde_json::Value`; `user.to_array()`
produces one. The string-shaped equivalent is `user.to_json()` -
identical body, identical filters, just one extra `to_string`.

You can also use `serde_json::to_value(&user)` or
`serde_json::to_string(&user)`. You get the same visibility and appends
policy, including changes you make on that instance.

## Hiding fields - `hidden = [...]`

The denylist form. Every column except the listed ones serialises:

```rust
use chrono::{DateTime, Utc};
use suprnova::{model, Model};

#[model(
    table = "users",
    fillable = ["name", "email", "password"],
    hidden = ["password", "remember_token"],
)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub password: String,
    pub remember_token: Option<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
```

The user-facing JSON for this model never contains `password` or
`remember_token`:

```json
{
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com",
    "created_at": "2026-05-30T11:14:22Z",
    "updated_at": "2026-05-30T11:14:22Z"
}
```

`hidden` is the right tool when **most fields go to the wire** and you
need to subtract a small set of secrets, internal flags, or auth-only
data.

## Whitelisting fields - `visible = [...]`

The allowlist form. Only the listed columns serialise:

```rust
#[model(
    table = "users",
    visible = ["id", "name", "avatar_url"],
)]
pub struct PublicUserView { /* ... */ }
```

Useful for a model that exists specifically to be a thin public
projection (think Laravel's "Profile" / "PublicUser" types). `visible`
is also the right tool when the table holds dozens of internal columns
and only a few belong on the wire - listing the keep-set is shorter
than listing the strip-set.

`hidden` and `visible` are **mutually exclusive at compile time**. The
macro emits an error if you set both:

```text
error: cannot specify both `hidden` and `visible` on the same model
 --> src/models/user.rs:7:1
  |
7 | #[model(table = "users", hidden = ["x"], visible = ["y"])]
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
```

The two are policy opposites - pick the one whose intent matches the
shape of your model, not both.

## Appending accessors - `appends = [...]`

`appends` injects computed values into the JSON output. Each entry
names an `#[accessor]`-tagged method on the model; the macro calls it
during `to_array()` and stores the return value under the same key.

```rust
use suprnova::{accessor, model, Model};

#[model(
    table = "users",
    fillable = ["first_name", "last_name"],
    appends = ["full_name", "initials"],
)]
pub struct User {
    pub id: i64,
    pub first_name: String,
    pub last_name: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

impl User {
    #[accessor]
    pub fn full_name(&self) -> String {
        format!("{} {}", self.first_name, self.last_name)
    }

    #[accessor]
    pub fn initials(&self) -> String {
        let f = self.first_name.chars().next().unwrap_or(' ');
        let l = self.last_name.chars().next().unwrap_or(' ');
        format!("{f}{l}")
    }
}
```

The serialised user now carries both computed keys:

```json
{
    "id": 7,
    "first_name": "Alice",
    "last_name": "Pond",
    "created_at": "...",
    "updated_at": "...",
    "full_name": "Alice Pond",
    "initials": "AP"
}
```

The macro validates `appends` entries at compile time:

- Each name must parse as a Rust identifier (`"full-name"` fails - it's
  not a valid ident).
- If the named method doesn't exist on the model's `impl` block, the
  compiler points at the macro-generated dispatcher with a clear
  `no method named 'full_name' found` error.

Calling `user.full_name()` directly from Rust works exactly like any
other method - `appends` only controls the **JSON dispatch table**.
Accessors stay regular methods.

You select a runtime append with `append(name)?`. You register that name
in `accessors = [...]` when you do not want it in the default `appends`.
You add a name once, and an unknown name returns an error. You keep the
append on the instance for every subsequent output.

## The filter pipeline order

You get the same steps for serde, `to_array`, and `to_json`:

1. You serialize the model's runtime attributes, preserving serde field options.
2. You exclude `__eager` and `__pivot`.
3. You retain only visible names when the visible list is non-empty.
4. You remove hidden names.
5. You apply those lists to default and runtime appended names before calling
   their accessors. You insert only permitted accessor values.

You suppress an appended name when it is hidden or outside a non-empty
visible list. You do not evaluate a suppressed accessor. An allowed accessor
with the same name as a stored column replaces that column in the output.
Serde returns accessor serialization errors. The existing infallible
`to_array` and `to_json` helpers represent serialization failure as JSON null.

## Per-call filtering - `to_array_except` / `to_array_only`

For one-off cases where the column declaration doesn't fit, two
terminal helpers run the full `to_array` pipeline then trim the result
by name:

```rust
use suprnova::{json_response, Model};

pub async fn admin_show(user: User) -> suprnova::Response {
    // strip a few extra fields for an admin endpoint that needs most
    // of the row but not these:
    json_response!(
        user.to_array_except(&["password_hash", "remember_token", "internal_notes"])
    )
}

pub async fn directory_show(user: User) -> suprnova::Response {
    // public directory - only the columns we want to publish:
    json_response!(
        user.to_array_only(&["id", "name", "avatar_url"])
    )
}
```

Both produce a `serde_json::Value` - they don't mutate `self` and they
don't change future serialisations of the same row. They run the
full `hidden` / `visible` / `appends` pipeline first, then apply their
own trim on top. `to_array_only` returns a *fresh* JSON object
containing only the named keys; `to_array_except` returns the full
object minus the named keys.

### Instance visibility

You change every later conversion of one instance with these methods:

```rust
user.make_hidden(["email", "phone"]);
user.make_hidden_if(!is_admin, "internal_notes");
user.make_visible("email");
user.make_visible_if(is_admin, ["internal_notes", "full_name"]);
```

You pass one name, an array, a vector, or a slice. Each method returns
`&mut Self` so you can chain changes. A false condition leaves the lists
unchanged. You remove a name from hidden with `make_visible`. When you
already have a non-empty visible list, you also add that name to visible.
You keep the changes on the instance and its clones. You do not change
other instances or the model's declared defaults.
You still cannot declare both `hidden` and `visible` on one model.

## Conditional hiding by viewer

The idiomatic pattern when visibility depends on the viewer is a
match at the call site, branching into the right per-call filter:

```rust
use suprnova::{Auth, json_response, Model, Request, Response};

pub async fn show(req: Request) -> Response {
    let id: i64 = req.param("id")?.parse()
        .map_err(|_| suprnova::FrameworkError::param_parse("id", "i64"))?;
    let user = User::find_or_fail(id).await?;
    let viewer = Auth::user_as::<User>().await?;
    let viewing_self = viewer.as_ref().map(|v| v.id) == Some(user.id);

    let body = if viewing_self {
        user.to_array()
    } else {
        user.to_array_except(&["email", "phone", "stripe_customer_id"])
    };

    json_response!(body)
}
```

For more elaborate per-viewer shape - different attributes for admins,
trial users, paid users - the right tool is the **JSON:API resource
layer** with `Maybe<T>` / `MissingValue<T>` fields. See
[JSON:API resources](eloquent-resources.md#conditional-attributes---maybet--missingvaluet)
for the declarative form.

## Serde serialization

You use direct serde serialization for model values and nested model values:

```rust
let value = serde_json::to_value(&user)?;
let body = serde_json::to_string(&user)?;
let nested = serde_json::to_value(vec![user])?;
```

You get the same filtered attributes and appends on each path. You retain
serde renames and field serialization options. You can still trim one output
with `to_array_except` or `to_array_only`, without changing the instance.

## Serializing collections

A `Collection<M>` - returned by `Builder::get()`, `Model::all()`, and
relation accessors - has its own `to_array()` and `to_json()` that
walk the underlying `Vec<M>` and call **per-row** `to_array()`. The
result is a JSON array of filtered objects:

```rust
use suprnova::{json_response, Model};

pub async fn list() -> suprnova::Response {
    let users = User::all().await?;
    json_response!(users.to_array())
}
```

You get the same per-model policy from `serde_json::to_value(&users)`.
You also get it when models appear in a paginator's data vector or another
serde container. You can use the [JSON:API paginated form](eloquent-resources.md#pagination)
when you need its resource envelope, links, and metadata.

## Eager-loaded relations and serialization

This is the second divergence to internalise.

When you call `.with(["posts"])` on a builder, the framework loads the
posts and stores them in a per-row `EagerLoadCache` (the auto-injected
`__eager` field). The accessor for reading them - `user.posts_loaded()` -
pulls from that cache.

**The cache is `#[serde(skip)]` and `to_array()` strips it
unconditionally.** Eager-loaded relations do not auto-fold into the
JSON output. A `to_array()` on a user with eagerly-loaded posts looks
identical to a `to_array()` on a user without.

### Why Suprnova diverges

Laravel's `toArray()` walks `$model->getRelations()` and folds every
loaded relation into the output. PHP's array-shaped model bag makes
this natural - a relation is just another keyed entry on the model.

Rust's typed Eloquent structs don't have that bag. A `User` struct has
typed columns, not a heterogeneous map of "whatever relations were
loaded". Folding `posts` in would require either runtime field
injection on a typed struct (a serde-bypass mechanism), or a parallel
serialisation path that consults the cache after running the column
serialiser. Both options would couple every model's JSON shape to
which relations a particular caller eager-loaded - a contract that's
load-bearing in PHP because clients learn to depend on it, and a
contract Suprnova explicitly refuses to ship because it makes JSON
shape depend on caller-side query construction.

### The two ways to ship relation data

**1. Explicit accessor + appends.** Define a method that pulls from
`<rel>_loaded()`, register it in `appends`. The relation shows up
under whatever key you name. This works when the relation is *always*
eager-loaded on the read path:

```rust
use suprnova::{accessor, model};
use serde_json::Value;

#[model(
    table = "users",
    appends = ["posts"],
)]
pub struct User { /* ... */ }

impl User {
    #[accessor]
    pub fn posts(&self) -> Value {
        // posts_loaded() PANICS if .with(["posts"]) wasn't called on
        // the read path. The accessor MUST run after eager-loading.
        let posts = self.posts_loaded();
        serde_json::to_value(posts).unwrap_or(Value::Null)
    }
}

// Read path MUST eager-load:
let users = User::query()
    .with(["posts"])
    .get()
    .await?;
let body = users.to_array();   // each user's "posts" key is populated
```

The contract is loud: forget the `.with(["posts"])`, and the accessor
panics on the first row's `posts_loaded()` call (the eager cache
panics on read when the relation wasn't loaded, by design - a silent
empty array would hide the bug). For optional eager-load, use the
HasOne form which returns `Option<&T>` and gives you a `match`:

```rust
impl User {
    #[accessor]
    pub fn profile(&self) -> Value {
        match self.profile_loaded() {
            Some(profile) => serde_json::to_value(profile).unwrap_or(Value::Null),
            None => Value::Null,
        }
    }
}
```

**2. The JSON:API resource layer.** When the relation shape and
inclusion policy belong on the wire format rather than the model, use
a `#[derive(Data)] #[json_resource]` struct with
`#[data(allow_include)]` on the relationship field. Clients opt in via
`?include=posts.comments`, the framework walks the include tree, and
populates `included` with deduplicated resource objects. This is the
right answer when:

- Relation shape is a wire-format concern (sparse fieldsets, conditional
  inclusion, cross-link metadata).
- Different endpoints want different default inclusions.
- The same model appears under different envelopes (one endpoint ships
  `posts`, another ships `subscriptions`).

See [JSON:API resources](eloquent-resources.md#compound-documents-with-include-chains)
for the full pattern.

## What about JSON:API?

The `to_array()` pipeline and the `Resource` / `JsonApi` facade are
two layers, and they serve different jobs:

| Concern | `Model::to_array` | `Resource::single` / `JsonApi::single` |
|---|---|---|
| **Shape** | Flat object - column names map directly to keys | JSON:API envelope (`data`, `included`, `meta`, `links`, `jsonapi`) |
| **Per-attribute control** | `hidden` / `visible` / `appends` on `#[model]` | `#[data(input_only)]`, `Maybe<T>`, sparse fieldsets via `?fields[type]=` |
| **Relations** | Manual (accessor + appends, see above) | First-class via `#[data(allow_include)]` + `?include=` |
| **Pagination** | Wrap a `Vec<Value>` by hand | `Resource::paginated(p)` handles links + meta |
| **Errors** | Render through `FrameworkError` | `into_json_api_response()` produces JSON:API `errors` envelope |
| **When to reach for it** | Simple endpoints, internal tools, ad-hoc shapes | Public APIs, third-party consumers, JSON:API-aware clients |

`to_array()` is the lower layer - it's what gets called for most
internal handlers, admin pages, Inertia props (via serde), and tests.
The JSON:API layer composes on top: it doesn't replace `to_array`, it
adds an envelope around per-resource attribute / relationship logic
that's too rich to live on the model itself.

You can pass models through serde into typed Inertia props with their
visibility policy intact. You use a resource or a dedicated DTO when you
need a different response shape.

## Where each piece lives

| Concern | File |
|---|---|
| `Model::to_array` / `to_json` trait defaults | `framework/src/eloquent/model.rs` |
| `Model::to_array_except` / `to_array_only` | `framework/src/eloquent/model.rs` |
| `appends` accessor dispatch, trait default | `framework/src/eloquent/model.rs` |
| Macro-emitted `Serialize` and unfiltered attribute view | `suprnova-macros/src/model/serialization.rs` |
| `appends` accessor dispatch, macro-emitted | `suprnova-macros/src/model/serialization.rs` |
| `Collection<M>::to_array` / `to_json` | `framework/src/eloquent/collection.rs` |
| `EagerLoadCache` (the `__eager` field) | `framework/src/eloquent/relations/eager_cache.rs` |
| `hidden` / `visible` / `appends` macro parsing | `suprnova-macros/src/model/parse.rs` |
| `#[accessor]` function-level macro | `suprnova-macros/src/lib.rs` |

## Next

- [Eloquent API](eloquent.md) - the full model surface, attribute
  reference, and where `#[accessor]` / `#[mutator]` are defined
- [JSON:API resources](eloquent-resources.md) - the declarative
  resource layer for richer per-viewer shapes, sparse fieldsets, and
  compound `?include=` documents
- [Validation](validation.md) - how request input becomes a typed
  struct before the model layer sees it
- [Responses](responses.md) - `HttpResponse` builders, headers, and
  cookies; the surface `json_response!` ultimately produces
- [Error Model](error-model.md) - how an error becomes a JSON body
  with the same `request_id` correlation as the success path


---

<!-- /docs/eloquent-factories -->

# Eloquent Factories

Factories produce randomized model instances for tests and seeders. The
You select a typed batch with `UserFactory::new().count(10).create().await?`.
The contract is one trait plus a fluent builder, with a `#[derive(Factory)]`
shortcut for the common case where the model already has a sensible
randomized representation.

This chapter covers defining factories by hand and by derive, composing
overrides into reusable "states", deterministic IDs via `Sequence`, the
`Persistable` seam that powers `create`, and the difference between
`make` (in-memory) and `create` (persisted). For the test-writing context
where factories are most useful, see [Testing](testing.md).

## The `Factory` trait

The trait has exactly one required method:

```rust
pub trait Factory {
    type Model;

    fn definition() -> Self::Model
    where
        Self: Sized;
}
```

`definition()` returns a fully populated model with every field
randomized to whatever default makes sense. The trait carries no
per-instance state - implementors are typically zero-sized markers
(`struct UserFactory;`) so a caller can reach the factory by name
without holding a handle.

The trait also provides two builder entrypoints with default
implementations:

```rust
fn new() -> FactoryBuilder<Self::Model>;       // count = 1, no overrides
fn times(n: usize) -> FactoryBuilder<Self::Model, true>;  // sugar for new().count(n)
```

You call the remaining methods on `FactoryBuilder<M, const MANY: bool = false>`.

## Defining a factory by hand

The minimal hand-written form pairs a marker struct with a `Factory`
impl that knows how to build one instance. You'll typically reach for
this when the model doesn't derive `fake::Dummy` - perhaps because some
fields need deterministic seeding (relation IDs in a known range) or
the randomized representation needs business-rule awareness:

```rust
use suprnova::Factory;
use crate::models::users::User;

pub struct UserFactory;

impl Factory for UserFactory {
    type Model = User;

    fn definition() -> User {
        let now = chrono::Utc::now();
        User {
            // `0` is a placeholder - `persist_via_seaorm` flips
            // primary-key columns to `NotSet` before inserting so
            // the database assigns the real id.
            id: 0,
            name: format!("Factory User #{}", next_seq()),
            email: format!("factory-{}@example.test", next_seq()),
            password: "factory-placeholder".into(),
            remember_token: None,
            active: true,
            created_at: now,
            updated_at: now,
            deleted_at: None,
            __eager: Default::default(),
            __pivot: None,
        }
    }
}
```

The `__eager` and `__pivot` fields are the eager-load and pivot scratch
state that the `#[suprnova::model]` macro injects on every Eloquent
struct. Always default them - they get populated by the query builder,
not by factories.

`next_seq()` is whatever you want it to be - a `static AtomicU64`, a
`Sequence` (covered below), or a thread-local counter. The point is
that `definition()` runs fresh on every call inside `make_many` /
`create_many`, so any uniqueness you need has to come from a counter
the function can reach.

## `#[derive(Factory)]` for the common case

When the model itself implements `fake::Dummy` - either via
`#[derive(Dummy)]` or a hand-written `impl Dummy<Faker> for Model` -
the derive collapses the marker + impl into one line on the model:

```rust
use suprnova::{Dummy, Factory};

#[derive(Dummy, Factory)]
#[dummy(crate_name = "suprnova::fake")]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub body: String,
    pub author_id: i64,
    pub is_public: bool,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}
```

The derive emits `pub struct PostFactory;` as a sibling type and an
`impl Factory for PostFactory` whose `definition()` calls
`Faker.fake::<Post>()`. Visibility on the factory mirrors visibility
on the model - a `pub` model gets a `pub` factory, a `pub(crate)`
model gets a `pub(crate)` factory. The `#[dummy(crate_name = ...)]`
attribute tells `Dummy` where the `fake` crate is; see
[Hand-written `Dummy`](#hand-written-dummy-for-richer-randomization).

### Overriding the generated name

By default `#[derive(Factory)]` emits `<Model>Factory`. Override via
the `name` attribute:

```rust
#[derive(Dummy, Factory)]
#[dummy(crate_name = "suprnova::fake")]
#[factory(name = "AccountFactory")]
pub struct User { /* … */ }
```

The value must parse as a Rust identifier - `name = "User Factory"`
or `name = "user-factory"` fails to compile with a clear span-pointed
error. The macro emits `pub struct <Name>;` literally, so anything
that can't be a type name can't be a factory name.

### Hand-written `Dummy` for richer randomization

`#[derive(Dummy)]` works for primitive-typed structs but gives you no
control over distributions or cross-field invariants. For anything
non-trivial, write the `Dummy` impl by hand and pair it with
`#[derive(Factory)]`:

```rust
use suprnova::fake::rand::Rng;
use suprnova::fake::{Dummy, Fake, Faker, faker::lorem::en::{Paragraph, Sentence}};
use suprnova::Factory;

#[derive(Factory)]
pub struct Post { /* fields … */ }

impl Dummy<Faker> for Post {
    fn dummy_with_rng<R: Rng + ?Sized>(_: &Faker, rng: &mut R) -> Self {
        let title: String = Sentence(3..7).fake_with_rng(rng);
        let body: String = Paragraph(3..6).fake_with_rng(rng);
        let author_id: i64 = (1..=50i64).fake_with_rng(rng);
        let now = chrono::Utc::now();

        Post {
            id: 0,
            author_id,
            title,
            body,
            is_public: Faker.fake_with_rng::<bool, _>(rng),
            created_at: now,
            updated_at: now,
            __eager: Default::default(),
            __pivot: None,
        }
    }
}
```

The `fake` crate is re-exported as `suprnova::fake` so consumers
don't need a separate `fake = "…"` line in `Cargo.toml`. It carries the
fakers of `suprnova::fake::faker` and `suprnova::fake::rand::Rng` for
`fake_with_rng`. Common types are also re-exported under the crate
root: `suprnova::{Dummy, Fake, Faker}`.

If you do add `fake` to your own dependencies, keep its version the same
as the one the framework uses. Two versions are two separate pairs of
`Dummy` and `Fake` traits, and a value that implements one does not
implement the other.

`#[derive(Dummy)]` generates code that names the crate `::fake`. An
application without `fake` among its own dependencies has no such crate,
so tell the derive where it is:

```rust
use suprnova::{Dummy, Factory};

#[derive(Dummy, Factory)]
#[dummy(crate_name = "suprnova::fake")]
pub struct Post { /* … */ }
```

### Why `#[derive(Factory)]` only takes plain structs

The derive rejects enums, unions, and generic models with a clear
compile error. Enums and unions don't have a meaningful default
representation. Generics would force a decision about how the factory
type parameterizes its model - and there's no good default, so the
derive refuses to guess. Write the `impl Factory` by hand for those
cases.

## The fluent builder

`Factory::new()` returns `FactoryBuilder<M>`. You get
`FactoryBuilder<M, true>` from `count(n)`, `times(n)` or `Factory::times(n)`.
Every operation is chainable; nothing happens until you call a
terminal method (`make`, `make_one`, `make_many`, `create`,
`create_one`, `create_many`).

### `count(n)` - how many instances

```rust
let user = UserFactory::new().make();             // 1 user
let users: Vec<User> = UserFactory::new().count(10).make();
let same: Vec<User> = UserFactory::times(10).make();
```

You select the return type at compile time. Without a count, `make()` returns
`M` and `create().await` returns `Result<M, FrameworkError>`. After `count(n)`
or `times(n)`, they return `Vec<M>` and `Result<Vec<M>, FrameworkError>`.
Even a count of one returns a vector. A count of zero returns an empty vector
without an insert. You use `make_one()` or `create_one()` to discard the count.
You can still call `make_many()` or `create_many()` on a counted builder.

### `with(|m| { … })` - per-call overrides

`with` registers a closure that runs against every produced instance
after `definition()`. Multiple `with` calls compose in registration
order, so a later override clobbers an earlier one on the same field:

```rust
let admin = UserFactory::new()
    .with(|u| u.active = true)
    .with(|u| u.role = "admin".into())
    .make();
```

Overrides are stored as `Box<dyn Fn(&mut M) + Send + Sync + 'static>`
so the builder stays `Send` - important for the async `create` /
`create_many` paths, which hold the builder across an `.await` on the
SeaORM insert.

### `prepend(|m| { … })` - defaults that callers can still override

`prepend` inserts a closure at the **front** of the override chain, so
it runs **before** any other `with(...)`. Use it inside a state method
when you want to provide a default the caller can still clobber with a
later `.with(...)`:

```rust
impl UserFactory {
    /// State method - admin defaults, caller can still customise.
    pub fn admin() -> suprnova::FactoryBuilder<User> {
        Self::new()
            .prepend(|u| u.role = "admin".into())
            .prepend(|u| u.active = true)
    }
}

// Caller wins on `role` because their .with() comes after the prepends.
let owner = UserFactory::admin()
    .with(|u| u.role = "owner".into())
    .make();
```

This is Suprnova's equivalent of Laravel's `Factory::prependState`. It's
the right primitive for state methods specifically - `with` would lose
to a caller's `.with(...)`, which is the opposite of what a default
should do.

### `when(cond, |b| { … })` - conditional chaining

`when` threads a flag through a chain without breaking the fluent
style. The closure receives the builder, returns the builder. When
`cond` is false, the builder passes through unchanged:

```rust
UserFactory::times(10)
    .with(|u| u.active = true)
    .when(seed_admins, |b| b.with(|u| u.role = "admin".into()))
    .create_many()
    .await?;
```

Mirrors Laravel's `Conditionable::when($cond, $cb)`. The
`FnOnce(Self) -> Self` signature means you can `await` inside the
closure as long as you `.await` before returning the builder.

### Terminal methods

| Method | Returns | Persisted? |
|---|---|---|
| `make()` | `M`, or `Vec<M>` after a count | no |
| `make_one()` | one `M` (forces count = 1) | no |
| `make_many()` | `Vec<M>` of `count` items | no |
| `create()` | `Result<M, FrameworkError>`, or a vector result after a count | yes |
| `create_one()` | `Result<M, FrameworkError>` (forces count = 1) | yes |
| `create_many(records)` | `Result<Vec<M>, FrameworkError>` on the default builder | yes |
| `create_many()` | `Result<Vec<M>, FrameworkError>` on a counted builder | yes |

`make_one` and `create_one` are useful when a state method has set
`count` internally to something else and the caller wants exactly one
result:

```rust
pub fn admins_in_org(org_id: i64) -> suprnova::FactoryBuilder<User, true> {
    UserFactory::times(5)               // sensible default for fixtures
        .with(move |u| u.org_id = org_id)
        .with(|u| u.role = "admin".into())
}

// Test only wants one - `create_one` discards the count(5).
let admin = admins_in_org(42).create_one().await?;
```

### Explicit records with `create_many`

You pass a count or a list of `Attrs` to a default builder:

```rust
let users = UserFactory::new().create_many(2).await?;
let users = UserFactory::new().create_many([
    suprnova::attrs! { name: "Ada" },
    suprnova::attrs! { name: "Grace", active: false },
]).await?;
```

Each record starts from a fresh definition and your `with` overrides. Its
attributes then win on overlap. You keep definition fields that you omit.
Attribute lists require `M: serde::Serialize + serde::de::DeserializeOwned`.
You name serialized fields; an unknown field or a value of the wrong type
returns an error before any record is inserted. An empty list creates no rows.
A field your model hides, or skips on output with `#[serde(skip)]` or
`#[serde(skip_serializing)]`, still takes an attribute, and keeps its
definition value when you leave it out. `Persistable::with_definition_attributes`
sets each named field on the built model; it does not rebuild the model from
its filtered output.
`FactoryRecords<M>` accepts `usize`, `Vec<Attrs>` and `[Attrs; N]`.
You pass the same records to `create_many_quietly(records)` to mute events.

Rust has no optional arguments. On a counted builder you keep the existing
no-argument `create_many()` and `create_many_quietly()` forms. To supply a
new explicit count or attribute list, start with `Factory::new()`.

## States: reusable preset combinations

Suprnova doesn't ship a `state("name")` lookup table. Instead, states
are plain methods on your factory marker that return a pre-configured
`FactoryBuilder<M>`. The pattern composes by inheritance - every state
method returns the same `FactoryBuilder<M>` type, so you can chain more
methods onto the result:

```rust
use suprnova::FactoryBuilder;
use crate::models::users::User;

pub struct UserFactory;

impl suprnova::Factory for UserFactory {
    type Model = User;
    fn definition() -> User { /* … */ }
}

impl UserFactory {
    /// Inactive variant - overlays an `active: false` default.
    pub fn inactive() -> FactoryBuilder<User> {
        Self::new().prepend(|u| u.active = false)
    }

    /// Admin variant - overlays role + verified email.
    pub fn admin() -> FactoryBuilder<User> {
        Self::new()
            .prepend(|u| u.role = "admin".into())
            .prepend(|u| u.email_verified_at = Some(chrono::Utc::now()))
    }

    /// Composable: inactive admin.
    pub fn inactive_admin() -> FactoryBuilder<User> {
        Self::admin().prepend(|u| u.active = false)
    }
}
```

```rust
// Compose at the call site too - chain more overrides freely.
let user = UserFactory::admin()
    .with(|u| u.name = "Alice".into())
    .create()
    .await?;

let batch = UserFactory::inactive().count(20).create_many().await?;
```

The `prepend` choice is deliberate: a state's overrides are *defaults*
that the caller can still rewrite. If you want a state's setting to be
non-negotiable, use `with` instead - it goes to the end of the chain
and wins.

### Why no `state("name")` lookup

A name-keyed state registry would force runtime string matching for
something the compiler can check. State methods give you compile-time
verification (typo `UserFactor::admn()` is a hard error) and full IDE
autocomplete. The composability - chaining `Self::admin()` from inside
`inactive_admin()` - falls out for free.

## Deterministic IDs with `Sequence`

`Sequence` is a monotonic counter for seeding unique-per-call fields.
Each `next()` call returns 1, 2, 3, … atomically across threads:

```rust
use suprnova::{Fake, Sequence};

static ORDER_IDS: Sequence = Sequence::new();

pub struct OrderFactory;
impl suprnova::Factory for OrderFactory {
    type Model = Order;
    fn definition() -> Order {
        Order {
            id: 0,
            number: format!("ORD-{:06}", ORDER_IDS.next()),
            total_cents: (100..=10_000).fake(),
            created_at: chrono::Utc::now(),
            __eager: Default::default(),
            __pivot: None,
        }
    }
}
```

`Sequence::new()` is `const`, so it works as a `static` initializer.
The counter starts at 0 and increments to 1 on first call. Use
`reset()` between tests if you want a clean count - the
`#[suprnova_test]` macro doesn't do this for you because the framework
can't know which sequences are yours:

```rust
#[suprnova::suprnova_test]
async fn each_order_gets_a_unique_number(db: TestDatabase) {
    ORDER_IDS.reset();   // start at 1 for this test
    let orders = OrderFactory::new().count(5).create_many().await?;
    assert_eq!(orders[0].number, "ORD-000001");
    assert_eq!(orders[4].number, "ORD-000005");
}
```

`Sequence` uses `SeqCst` ordering - overkill for "give me a unique
id" but keeps reasoning trivial. If a Sequence ever shows up in a hot
path you can write your own with `Relaxed`.

## `Persistable`: the seam to your storage

The `create` family of methods is available whenever the model
implements `Persistable`:

```rust
#[async_trait]
pub trait Persistable: Sized + Send {
    async fn persist(self) -> Result<Self, FrameworkError>;
}
```

Two impls cover the models you write:

- The `#[suprnova::model]` macro emits `Persistable` for the struct it
  generates. It runs the same insert that `Model::create` runs, so a
  factory insert fires `Creating`, `Saving`, `Created`, and `Saved` and
  reaches every observer. See [Lifecycle events](#lifecycle-events).
- A blanket impl in `factory::persist` covers every plain SeaORM model
  that can `IntoActiveModel<ActiveModel>`. It pulls `DB::connection()`
  and inserts with SeaORM directly, so no model event fires.

No per-model boilerplate; if `User` is a model, `UserFactory::new().create()`
works. The returned `Self` is what the insert hands back - assigned id,
defaulted columns resolved, etc.

### Primary-key handling

A SeaORM `IntoActiveModel` impl marks every field - including the PK -
as `Set(value)`. For factory-produced models the PK is a placeholder
(`0` for `AUTO_INCREMENT i64`), so a straight insert collides on the
second call with a UNIQUE constraint failure.

`persist_via_seaorm` (the helper that backs the blanket) flips every
primary-key column to `NotSet` before inserting, which lets the
database assign its own id - the semantic factories actually need. The
`Persistable` impl of a `#[suprnova::model]` struct does the same for an auto-increment key. A model whose
key is not auto-increment keeps the key its factory set:

```rust
pub async fn persist_via_seaorm<M, E, C>(model: M, db: &C) -> Result<M, FrameworkError>
where
    M: ModelTrait<Entity = E> + IntoActiveModel<<E as EntityTrait>::ActiveModel> + Send,
    E: EntityTrait<Model = M>,
    /* … bounds … */
    C: ConnectionTrait,
{
    let mut active = model.into_active_model();
    for pk in <<E as EntityTrait>::PrimaryKey as Iterable>::iter() {
        active.not_set(pk.into_column());
    }
    active.insert(db).await.map_err(/* … */)
}
```

If you actually *want* to assign a specific id (replay test, restoring
a fixture by id), bypass the helper and call
`model.into_active_model().insert(db).await` directly.

### Persisting against an explicit connection

`persist_via_seaorm` takes the connection as an argument. Useful when
you want to drive persistence against a connection that isn't the
framework's bound `DB::connection()` - most often a specific
`sqlite::memory:` handle in an integration test:

```rust
use suprnova::factory::persist_via_seaorm;

let model = UserFactory::new().make();
let row = persist_via_seaorm(model, db.inner()).await?;
```

### Custom non-SeaORM backends

Because the blanket impl targets every `ModelTrait` type, you can't
write `impl Persistable for MyOrm::Model` from a downstream crate
without colliding. For non-SeaORM custom persistence (Redis, Surreal,
blob-only stores), wrap the model in a newtype and impl `Persistable`
on the wrapper:

```rust
use suprnova::{FrameworkError, Persistable};
use suprnova::async_trait;

pub struct RedisCached<T>(pub T);

#[async_trait]
impl Persistable for RedisCached<MyValue> {
    async fn persist(self) -> Result<Self, FrameworkError> {
        let client = suprnova::App::make::<RedisClient>()
            .ok_or_else(|| FrameworkError::internal("redis client not bound"))?;
        client.set(&self.0.key, &serde_json::to_vec(&self.0)?).await?;
        Ok(self)
    }
}
```

A `Factory<Model = RedisCached<MyValue>>` then gets `create` /
`create_many` for free.

## `make` vs `create`: when to use which

`make` returns the model without touching the database:

```rust
// Unit test for a pure function - no DB needed.
let draft = PostFactory::new().with(|p| p.is_public = false).make();
let snippet = my_lib::extract_summary(&draft);
assert!(snippet.len() < 200);
```

`create` persists and returns the post-insert version:

```rust
// Integration test - the action needs a real row.
let post = PostFactory::new().create().await?;
let action = App::resolve::<PublishPostAction>().unwrap();
let published = action.execute(post.id).await?;
assert!(published.is_public);
```

Reach for `make` whenever the test doesn't care that the row exists.
Reach for `create` when you'll query the row back, when a foreign key
needs a real id, or when you're populating fixtures for a sub-system
that reads the DB. Note that `create_many` persists sequentially - if
a later insert fails, the prior inserts are NOT rolled back. For a
`#[suprnova::model]` struct, `create` / `create_many` take the same
write path as `Model::create`, so inside a `DB::transaction(...)` closure
they join the ambient transaction. Wrap a batch in one when you need
atomicity:

```rust
use suprnova::{DB, Factory, FrameworkError};

DB::transaction(|_tx| Box::pin(async move {
    UserFactory::times(50).create_many().await?;
    Ok::<_, FrameworkError>(())
})).await?;
```

A plain SeaORM model uses the blanket `Persistable` impl. It inserts on
the ambient transaction too when one is open, and through
`DB::connection()` otherwise.

## "After-creating" behaviour

Suprnova doesn't ship a named `after_creating(|m| { … })` callback. Two
patterns cover the use cases that callback exists for in Laravel:

**1. The chain - do the follow-up after `create`/`create_many`:**

```rust
let user = UserFactory::new().create().await?;
ProfileFactory::new()
    .with(move |p| p.user_id = user.id)
    .create()
    .await?;
```

This is the canonical pattern when one model's id needs to flow into a
follow-up insert. `create` returns the persisted row, so the id is
immediately available.

**2. Model observers - react on the model lifecycle, not the factory:**

Use [Model Observers](eloquent.md#observers-and-lifecycle-events) to wire post-insert
behaviour to the model itself rather than the factory. The observer
fires for `User::create(...)`, `UserFactory::new().create()`, and any
other persistence path - exactly what you want when the behaviour is
"every time this row lands, do X":

```rust
use suprnova::{FrameworkError, Observer, async_trait, observer};

#[observer(User)]
pub struct AuditUser;

#[async_trait]
impl Observer<User> for AuditUser {
    async fn created(&self, user: &User) -> Result<(), FrameworkError> {
        tracing::info!(user_id = user.id, "user created");
        Ok(())
    }
}
```

Factory-only callbacks would invite divergence between test inserts
and real inserts. Observers stay consistent across both.

### Lifecycle events

A factory insert of a `#[suprnova::model]` struct fires the same events
as `Model::create`, in the same order: `Creating` and `Saving` before
the insert, `Created` and `Saved` after it. A `Creating` or `Saving`
listener sees the row as attributes. What it changes is written over the
values the factory built, and a listener that cancels aborts the insert.
The fillable filter does not apply, because the values are the
factory's own.

To insert a row without running any listener, use `create_quietly()` or
`create_many_quietly()`. Both mute the model events for the insert, as
`seed::without_events` does:

```rust
let user = UserFactory::new().create_quietly().await?;
let users = UserFactory::times(50).create_many_quietly().await?;
```

## Seeders

Factories produce instances; seeders orchestrate them. A `Seeder` is a
zero-sized type with an async `run` that knows what to populate:

```rust
use suprnova::{Factory, FrameworkError, Seeder};
use suprnova::async_trait;

use crate::factories::{PostFactory, UserFactory};

pub struct BaseSeeder;

#[async_trait]
impl Seeder for BaseSeeder {
    fn name() -> &'static str { "BaseSeeder" }

    async fn run() -> Result<(), FrameworkError> {
        // Users first - posts reference user ids in 1..=50.
        UserFactory::new().count(50).create_many().await?;
        PostFactory::new().count(200).create_many().await?;
        Ok(())
    }
}
```

Register the seeder in `bootstrap.rs` so the per-project `console`
binary's `db:seed` command knows about it:

```rust
suprnova::seed::register_root::<crate::seeders::BaseSeeder>()?;
```

Run through the project's `console` binary (every scaffolded app
ships one at `src/bin/console.rs`):

```bash
cargo run --bin console -- db:seed
```

You register a root seeder to choose the order of its child calls.
Without a root, you retain registration order. Idempotency is your seeder's
responsibility - `run` does not snapshot or roll back, so a seeder
that inserts unconditionally produces duplicates on re-run. Use
`migrate:fresh` followed by `db:seed` for a clean slate.

## Putting it together: a complete test fixture

```rust
use suprnova::{App, describe, test, expect};
use suprnova::events::{EventFacade, assert_dispatched_times};
use suprnova::testing::TestDatabase;
use crate::factories::{PostFactory, UserFactory};
use crate::actions::publish_post::PublishPostAction;

describe!("PublishPostAction", {
    test!("publishes a draft post", async fn(db: TestDatabase) {
        // Arrange - an author and one draft post owned by them.
        let author = UserFactory::new()
            .with(|u| u.active = true)
            .create()
            .await
            .unwrap();

        let draft = PostFactory::new()
            .with(move |p| p.author_id = author.id)
            .with(|p| p.is_public = false)
            .create()
            .await
            .unwrap();

        // Act.
        let action = App::resolve::<PublishPostAction>().unwrap();
        let published = action.execute(draft.id).await.unwrap();

        // Assert.
        expect!(published.is_public).to_equal(true);
        expect!(published.author_id).to_equal(author.id);
    });

    test!("publishing emits exactly one event", async fn(db: TestDatabase) {
        let _guard = EventFacade::fake();
        let post = PostFactory::new().create().await.unwrap();

        App::resolve::<PublishPostAction>().unwrap()
            .execute(post.id).await.unwrap();

        assert_dispatched_times::<crate::events::PostPublished>(1);
    });
});
```

Three patterns worth pointing at:

- The author's `id` flows into the post via a `move` closure inside
  `.with(...)`. Captures are explicit, which keeps the relation
  visible at the call site.
- `create().await.unwrap()` is the test idiom - the test is allowed to
  panic on setup failure because a broken fixture is a broken test,
  not a graceful failure mode.
- Factories compose with the rest of the testing surface
  (`EventFacade::fake`, `Storage::fake`, `Mail::fake`, …) - none of
  the fakes know about factories, but every test you write will use
  them together.

### Why Suprnova diverges

Laravel's factories ship with named states (`->state('admin')`),
runtime sequences (`->sequence(['name' => 'A'], ['name' => 'B'])`),
and an `afterCreating` callback registered on the factory itself.
Suprnova drops all three and replaces them with Rust-shaped
primitives:

- **States are methods, not strings.** Compile-time typo-checking and
  IDE autocomplete are both free; the only cost is "you write `pub fn
  admin()` instead of `protected function admin()`", which is no cost
  at all.
- **Sequences are a separate primitive.** `Sequence` does one thing
  (atomic counter) and is reusable outside the factory surface - you
  can drop one into a request id generator, a workflow step counter,
  or a test harness without explaining what it is.
- **After-creating is wired to the model, not the factory.** The
  framework already has [Model Observers](eloquent.md#observers-and-lifecycle-events) for
  exactly that purpose. Adding a parallel mechanism on the factory
  would make test-time behaviour and production-time behaviour diverge
  by construction.

The fluent surface - `count(10)`, `times(10)`, `with`, `prepend`,
`when`, `make`, `create`, `create_many`, `make_one`, `create_one` -
mirrors Laravel's directly, so the muscle memory ports without a
glossary.

## Next

- [Testing](testing.md) - `#[suprnova_test]`, `TestDatabase`, the fake
  facades that pair with factory-built fixtures.
- [Eloquent](eloquent.md) - model derivation, observers, the cast
  pipeline that runs when `create` persists your factory output.
- [Migrations](migrations.md) - the schema your factories need to
  exist against; use `migrate:fresh && db:seed` for a clean fixture
  slate.
- [Database](database.md) - `DB::transaction`, multi-connection
  routing, savepoints - what to reach for when `create_many` needs
  atomicity.
- [Service Container](container.md) - how `App::resolve` and
  `App::make` find the action and service types your tests call into
  alongside factories.


# Testing

---

<!-- /docs/testing -->

# Testing

This is the hub chapter for Suprnova's testing surface - the macros, the
in-process database, the container fakes, and the encryption key
helpers your test binaries reach for. The depth-first chapters live
alongside it: [HTTP Tests](http-tests.md) for routes + middleware,
[Database Tests](database-testing.md) for everything around
`TestDatabase`, [Mocking and Fakes](mocking.md) for the seven external
surfaces (Mail, Notify, Queue, Bus, Events, Storage, HTTP client). Read
this one to learn what's in the box; jump to a sibling when you need
the long form.

## The pieces

| Piece | Role |
|---|---|
| `#[tokio::test]` + `TestDatabase::fresh::<Migrator>()` | The default workhorse - every real test in the framework uses this |
| `#[suprnova_test]` | Attribute macro sugar - runs `App::init()` + `App::boot_services()` and builds a `TestDatabase` for you |
| `describe!` + `test!` | Jest-shaped grouping macros, paired with `expect!` for named failure output |
| `expect!` | Fluent assertion macro with typed matchers (equality, option, result, string, vec, ordering) |
| `TestDatabase::fresh` / `sqlite_memory` | In-memory SQLite + container registration, with or without your migrator |
| `TestDatabase::refresh` / `refresh_lazily` / `migrate` | The database `DATABASE_URL` names, with each test in a rolled-back transaction or its migrations rolled back - see [Database Tests](database-testing.md#tests-on-the-configured-database) |
| `TestContainer::fake` / `scope` / `spawn` | Thread-local or task-local DI overrides, hermetic across parallel tests |
| `install_test_encryption_key[ring]` | Deterministic `APP_KEY` for tests that touch encrypted casts or signed payloads |
| `TestClock` | Freeze and move the clock the framework reads, without a sleep - see [Moving the clock](#moving-the-clock) |
| `crypto::testing::encrypt_string_under` | A value encrypted under an old key, for a rotation test |
| `console::test` | Run a console command, read what it printed, and answer what it asks - see [Console](console.md#testing-a-command) |
| Per-surface `fake()` helpers | Mail, Notify, Queue, Bus, Events, Storage, HTTP - see [Mocking](mocking.md) |
| `TestClient` | Sends requests through your router and middleware over an in-memory connection, carrying cookies and default headers between them, signed in as a user when you ask - see [HTTP Tests](http-tests.md#the-test-client) and [Acting as a user](#acting-as-a-user) |
| `TestResponse` | Fluent assertions over an HTTP test's `(status, headers, body)` triple - see [HTTP Tests](http-tests.md#fluent-response-assertions-with-testresponse) |
| `AssertableInertia` | Fluent assertions over an Inertia page object - see [HTTP Tests](http-tests.md#testing-inertia-responses) |

You won't reach for everything in one test. A typical action test uses
the first three; a DI-heavy test adds `TestContainer`; an HTTP test
swaps `TestDatabase` for the `handle_request` pipeline; a payments
test installs the encryption keyring.

## The default workhorse

Every real test in the framework looks like this:

```rust
use suprnova::testing::TestDatabase;
use crate::migrations::Migrator;

#[tokio::test]
async fn create_user_persists_it() {
    let db = TestDatabase::fresh::<Migrator>().await.unwrap();

    let alice = User::create(attrs! {
        name: "Alice",
        email: "alice@example.com",
    })
    .await
    .unwrap();

    assert!(alice.id > 0);

    let row = users::Entity::find_by_id(alice.id)
        .one(db.conn())
        .await
        .unwrap();
    assert!(row.is_some());
}
```

`TestDatabase::fresh::<M>()` opens a fresh `sqlite::memory:` connection,
runs your migrator end-to-end, and registers the connection in the test
container. Any code that calls `DB::connection()` or
`App::resolve::<DbConnection>()` afterwards resolves to it - including
the `#[suprnova::model]` query builder and any service you resolved
out of the container. When the `TestDatabase` drops, the registration
goes with it.

The `test_database!()` macro is one-liner sugar for the
`crate::migrations::Migrator` case:

```rust
use suprnova::test_database;

#[tokio::test]
async fn shortcut() {
    let db = test_database!();         // == TestDatabase::fresh::<crate::migrations::Migrator>()
    // ...
}
```

For tests that want precise column-shape control (cast round-trips,
query-builder SQL surface), use `TestDatabase::sqlite_memory()` -
same container wiring, no migrator. The DDL is yours. See
[Database Tests](database-testing.md) for the full catalogue plus the
`execute_unprepared` / `fetch_one` / `fetch_all` helpers.

## `#[suprnova_test]` - when you want the sugar

`#[suprnova_test]` is an attribute macro that wraps `#[tokio::test]`,
calls `App::init()` + `App::boot_services()` so `#[injectable]` types
resolve, and binds a fresh `TestDatabase`. It's optional sugar over
the explicit form above, useful when a test resolves
container-registered services:

```rust
use suprnova::suprnova_test;
use suprnova::{App, testing::TestDatabase};

#[suprnova_test]
async fn create_user_via_action(db: TestDatabase) {
    let action = App::resolve::<CreateUserAction>().unwrap();
    let user = action.execute("test@example.com").await.unwrap();

    assert_eq!(user.email, "test@example.com");
    assert!(user.id > 0);
}
```

If the function takes a `TestDatabase` parameter (by name), the macro
binds the fresh database to that name. If it doesn't, the database is
still constructed and registered (so `DB::connection()` works) - it
just isn't bound to a local.

Override the migrator with the `migrator = …` key:

```rust
#[suprnova_test(migrator = my_crate::tests::IsolatedMigrator)]
async fn create_user_with_isolated_schema(db: TestDatabase) {
    // ...
}
```

Two more keys choose the database and seed it:

| Key | Effect |
| --- | --- |
| `refresh` | Builds the database with `TestDatabase::refresh` instead of `fresh`: the database `DATABASE_URL` names, migrated once per process, with the test in a transaction that rolls back |
| `seed = Path` | Runs that seeder after the migrations and before the body, as Laravel's `#[Seeder]` attribute does |
| `seed` | Runs the root seeder, as a bare `db:seed` and Laravel's `#[Seed]` attribute do |

```rust
#[suprnova_test(refresh, seed = crate::seeders::UsersSeeder)]
async fn lists_seeded_users(db: TestDatabase) {
    // DATABASE_URL's database, migrated, seeded, inside a transaction.
    assert_eq!(User::query().count().await.unwrap(), 50);
}
```

Unknown keys are a compile error (typo `migrtor = …` won't silently
keep the default migrator), and so is a key given twice.

## `describe!` and `test!` - when grouping helps

For test files where the same action has many cases, the Jest-shaped
`describe!` + `test!` pair gives you nested grouping and named failure
output:

```rust
use suprnova::{App, describe, test, expect, testing::TestDatabase};
use crate::migrations::Migrator;

describe!("ListTodosAction", {
    test!("returns empty list when no todos exist", async fn(db: TestDatabase) {
        let todos = App::resolve::<ListTodosAction>().unwrap().execute().await.unwrap();
        expect!(todos).to_be_empty();
    });

    test!("returns all todos", async fn(db: TestDatabase) {
        Todo::create(attrs! { title: "Buy bread" }).await.unwrap();
        Todo::create(attrs! { title: "Walk dog" }).await.unwrap();

        let todos = App::resolve::<ListTodosAction>().unwrap().execute().await.unwrap();
        expect!(todos).to_have_length(2);
    });

    describe!("with pagination", {
        test!("returns first page", async fn(db: TestDatabase) {
            // nested groups compose
        });
    });
});
```

`test!` accepts three shapes:

```rust
// Async test with TestDatabase parameter
test!("creates a user", async fn(db: TestDatabase) { … });

// Async test without database
test!("calculates the right sum", async fn() { … });

// Sync test
test!("adds numbers", fn() { … });
```

The named-test wrapper threads the test name through the `expect!`
machinery so a failure surfaces:

```text
Test: "returns all todos"
  at src/actions/todo_action.rs:25

  expect!(actual).to_equal(expected)

  Expected: 2
  Received: 0
```

Without `describe!`/`test!` you get the standard `panic!` output. With
them, the location and human-readable test name lead the message.

## `expect!` - the matcher catalog

`expect!(value)` returns an `Expect<T>` wrapper. The matchers are typed
to `T` - calling `to_be_some()` on a `String` is a compile error, not
a runtime panic.

```rust
use suprnova::expect;

// Equality (T: Debug + PartialEq)
expect!(actual).to_equal(expected);
expect!(actual).to_not_equal(unexpected);

// Boolean
expect!(condition).to_be_true();
expect!(condition).to_be_false();

// Option<T>
expect!(option).to_be_some();
expect!(option).to_be_none();
expect!(option).to_contain_value(5);     // Some(5) check

// Result<T, E>
expect!(result).to_be_ok();
expect!(result).to_be_err();

// String / &str
expect!(s).to_contain("substring");
expect!(s).to_start_with("prefix");
expect!(s).to_end_with("suffix");
expect!(s).to_have_length(10);
expect!(s).to_be_empty();

// Vec<T>
expect!(v).to_have_length(3);
expect!(v).to_contain(&item);
expect!(v).to_be_empty();

// Ordering (T: Debug + PartialOrd)
expect!(10).to_be_greater_than(5);
expect!(5).to_be_less_than(10);
expect!(10).to_be_greater_than_or_equal(10);
expect!(5).to_be_less_than_or_equal(5);
```

You can use `expect!` outside `test!` - the file/line in the failure
message comes from `concat!(file!(), ":", line!())`. The named-test
header is the only thing the macro doesn't add on its own.

## `TestContainer` - DI fakes that don't bleed

The container chapter covers the [three-layer lookup](container.md) in
detail. For tests, the two entry points are `TestContainer::fake()`
(thread-local) and `TestContainer::scope(…).await` (task-local).

### Thread-local, the common case

`TestContainer::fake()` returns a guard. Until the guard drops,
`TestContainer::singleton` / `bind` / `factory` writes land on the
thread-local override layer and shadow the global container:

```rust
use std::sync::Arc;
use suprnova::App;
use suprnova::testing::TestContainer;

#[tokio::test]
async fn order_dispatches_email() {
    let _guard = TestContainer::fake();

    let fake = Arc::new(FakeEmailGateway::new());
    let probe = Arc::clone(&fake);
    TestContainer::bind::<dyn EmailGateway>(fake);

    place_order(123).await.unwrap();

    assert_eq!(probe.sent_count(), 1);
}
```

The guard clears the container it installed, wherever it drops. A
harness can share it with spawned tasks inside an `Arc`, so the last
reference may drop on another thread: that thread's own container is
left alone, and this one's is gone at its next lookup. Only
`TestContainer::fake()` makes a guard.

`TestDatabase::fresh` / `sqlite_memory` install their own
`TestContainer::fake` guard internally - you don't stack them unless
you're testing the registry itself.

### Task-local, for `multi_thread` runtimes

The thread-local layer is set on whichever OS thread called `fake()`.
A `multi_thread` tokio runtime can migrate your future to another
worker thread across an `.await`, and the override silently disappears.
`TestContainer::scope` solves that by binding the override to the
future instead:

```rust
use suprnova::testing::TestContainer;

#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn cross_worker_safe() {
    TestContainer::scope(async {
        TestContainer::bind::<dyn HttpClient>(Arc::new(FakeHttpClient::new()));
        do_async_work_that_may_hop_workers().await;
    })
    .await;
}
```

`tokio::spawn`'d sub-tasks do not inherit tokio task-locals; use
`TestContainer::spawn` instead - it captures the current scope's
container and re-installs it inside the spawned future:

```rust
TestContainer::scope(async {
    TestContainer::bind::<dyn HttpClient>(Arc::new(FakeHttpClient::new()));
    let h = TestContainer::spawn(async {
        App::make::<dyn HttpClient>().unwrap()  // sees the fake
    });
    let _client = h.await.unwrap();
})
.await;
```

### Why named connections survive parallel tests

The thread-local container is per-test, but Suprnova also has a
process-global `ConnectionRegistry` keyed by name (`__read_replica__`,
custom connection labels) that survives a thread-local reset. A naive
`Drop` impl would clear that registry every time *any*
`TestContainerGuard` went away - wiping another concurrent test's
named connection halfway through it running.

So the guards are refcounted process-wide: `fake()` counts up, each
guard's drop counts down, and only the last guard to drop clears the
named registry. Two parallel tests using
`__read_replica__` are safe: whichever guard drops last owns the
clear.

You don't call this from a test - it runs from `TestContainerGuard`'s
`Drop`. You only need to know it's there if you're debugging a
"named connection vanished mid-test" symptom, which usually means a
sibling test forgot to wait for its own guard to drop first.

## Acting as a user

A test of a route behind `AuthMiddleware` needs a signed-in user.
`TestClient::acting_as(&user)` returns a client whose every request is
signed in as `user` through the default guard, as Laravel's
`actingAs($user)` does, and `acting_as_with_guard(&user, "api")` signs
the user in through the named guard:

```rust
use std::sync::Arc;

use suprnova::testing::{TestClient, TestContainer};
use suprnova::{Auth, AuthConfig, AuthManager, AuthMiddleware, MiddlewareRegistry, Router};

#[tokio::test]
async fn the_dashboard_answers_the_signed_in_user() {
    TestContainer::scope(async {
        TestContainer::singleton(AuthManager::new(AuthConfig::new("web")));
        Auth::register_provider("users", Arc::new(UserRepository::default())).unwrap();

        let router = Router::new()
            .get("/dashboard", dashboard)
            .middleware(AuthMiddleware::new());
        let client = TestClient::new(router, MiddlewareRegistry::new())
            .acting_as(&User { id: 7, name: "Ada".into() });

        client.get("/dashboard").send().await.assert_ok().assert_see("Ada");
    })
    .await;
}
```

The user is set on the guard at the start of each request, so no test
writes a middleware to sign it in and nothing reaches the session. A
guard the application did not register fails the request with an error
that names it. See [HTTP Tests](http-tests.md#acting-as-a-user) for the
guard rules and how Suprnova differs from Laravel here.

## Console tests

`suprnova::console::test` runs a console command through the dispatcher the
`console` binary uses and returns a `ConsoleRun` with what the command
printed, what it asked, and how it ended. A command prints with
`console::line` and asks with `console::ask` and `console::confirm`, so the
test can read the output and prepare the answers:

```rust
use suprnova::console;

#[tokio::test]
async fn greet_says_hello() {
    let run = console::test(["greet", "--name", "Alice"]).run().await;

    run.assert_successful();
    run.assert_output_contains("Hello, Alice!");
}
```

You can also state the expectations before the run, and
`assert_successful` checks each one:

```rust
use suprnova::console;

#[tokio::test]
async fn greet_prints_one_greeting() {
    console::test(["greet", "--name", "Alice"])
        .expects_output("Hello, Alice!")
        .doesnt_expect_output_to_contain("error")
        .run()
        .await
        .assert_successful();
}
```

A command that ends with `FrameworkError::exit(code)` is checked with
`assert_exit_code(code)`. See [Console](console.md#testing-a-command) for
the questions, every expectation and assert method, and the rules a command
follows to be testable.

## Encryption key test helpers

Tests that exercise encrypted casts (`casts = { secret = AsEncrypted }`
on a `#[model(...)]`), signed payloads, or the keyring's previous-key
fallback need an `APP_KEY` installed in-process. The framework ships
two test-only helpers under the `testing` feature:

```rust
use suprnova::testing::install_test_encryption_key;

#[tokio::test]
async fn cast_roundtrip() {
    install_test_encryption_key();   // idempotent; deterministic 32-zero-byte key
    let db = TestDatabase::sqlite_memory().await.unwrap();
    // … encrypt + read back …
}
```

`install_test_encryption_key` is idempotent - the underlying `Crypt`
facade is `OnceLock`-backed, so the second call is a no-op. Most cast
test binaries call it from every test that touches an encrypted cast;
the first wins, the rest are free.

For rotation tests (writes under the old key, reads under the new
key), use the keyring variant:

```rust
use suprnova::crypto::EncryptionKey;
use suprnova::testing::install_test_encryption_keyring;

let new = EncryptionKey::from_base64("...").unwrap();
let old = EncryptionKey::from_base64("...").unwrap();
let installed = install_test_encryption_keyring(new, vec![old]);
assert!(installed, "first install wins");
```

The keyring helper returns `true` only if the call actually installed
the ring (the `OnceLock` was empty). To build a value that was encrypted
under an old key, use `suprnova::crypto::testing::encrypt_string_under`
rather than installing twice. It takes the key, the `CryptPurpose`, and the
plaintext, and returns the wire string. `encrypt_string_for_under` takes a
context between the purpose and the plaintext, the way
`Crypt::encrypt_string_for` does.

```rust
use suprnova::crypto::testing::encrypt_string_under;
use suprnova::testing::install_test_encryption_keyring;
use suprnova::{Crypt, CryptPurpose, EncryptionKey};

let new = EncryptionKey::generate();
let old = EncryptionKey::generate();
install_test_encryption_keyring(new, vec![old.clone()]);

// A value written when `old` was the current key.
let stored = encrypt_string_under(&old, CryptPurpose::Cast, "a value").unwrap();

let (plain, origin) =
    Crypt::decrypt_string_with_origin(CryptPurpose::Cast, &stored).unwrap();
assert_eq!(plain, "a value");
assert!(origin.needs_reencryption());
```

Both `install_test_encryption_key` and the keyring helper live in
`suprnova::testing`. The `suprnova::crypto::testing` functions are compiled
with the `testing` feature, so an application that ships without the feature
has none of them. They bypass the production `APP_KEY` validation path.

## Moving the clock

A test of an expiry should not sleep. The framework reads the time through
`suprnova::clock::now()`: signed URL deadlines, session idle timeouts, due
scheduled tasks, prune cutoffs, queue availability, the timestamps a
`#[model]` writes and the window of the Redis rate limiter. Under the
`testing` feature, `TestClock` moves what `clock::now()` returns, so a test
jumps to the moment it wants.

`tokio::time::pause` does not do this. It moves the timers of Tokio and
nothing that reads the wall clock.

```rust
use chrono::{DateTime, Duration, Utc};
use suprnova::http::Request;
use suprnova::routing::SignatureVerdict;
use suprnova::routing::url::{signature_verdict, signed_url};
use suprnova::testing::{install_test_encryption_key, TestClock};

#[test]
fn a_signed_url_expires() {
    install_test_encryption_key();
    let start = DateTime::from_timestamp(1_900_000_000, 0).unwrap();
    let clock = TestClock::travel_to(start);

    let deadline = (suprnova::clock::now() + Duration::minutes(10)).timestamp();
    let url = signed_url("/download?file=report", Some(deadline)).unwrap();
    let verdict = || signature_verdict(&Request::for_test("GET", &url)).unwrap();

    assert_eq!(verdict(), SignatureVerdict::Valid);

    clock.advance(Duration::minutes(9));
    assert_eq!(verdict(), SignatureVerdict::Valid);

    clock.advance(Duration::minutes(2));
    assert_eq!(verdict(), SignatureVerdict::Expired);
}
```

### The guard

| Call | Effect |
|---|---|
| `TestClock::freeze()` | Stops the clock of the current thread at the time of the call |
| `TestClock::travel_to(at)` | Sets the clock of the current thread to `at` (a `DateTime<Utc>`) and stops it there |
| `guard.advance(by)` | Moves the clock forward by a `chrono::Duration`, or back for a negative one |
| `guard.set(at)` | Sets the clock to `at` |
| `guard.now()` | The time the clock shows |

Both constructors return a `TestClockGuard`. Keep it in a binding, because
dropping it at once gives the system clock back.

A clock under a guard stands still until you move it. Two reads in a row
return the same time, so "exactly at the deadline" is a state your test can
hold.

When the guard drops, the thread gets its previous clock back. That also
happens when the test panics. Guards nest: an inner guard hands back the time
of the outer one when it drops. A guard is not `Send`, because it belongs to
one thread.

### Threads and tasks

A guard holds for the current thread. A `#[tokio::test]` of the default
`current_thread` flavour runs the test, and any task it spawns, on that
thread, so a guard works across `.await` there.

For a `multi_thread` runtime, or for code that spawns onto other threads,
use `TestClock::scope`. It sets the clock for one future, across awaits and
worker-thread hops. The closure gets a `TestClockHandle` with `advance`,
`set` and `now`:

```rust
use chrono::{DateTime, Duration};
use suprnova::testing::TestClock;

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn scoped_clock() {
    let at = DateTime::from_timestamp(1_900_000_000, 0).unwrap();

    TestClock::scope(at, |clock| async move {
        assert_eq!(suprnova::clock::now(), at);

        clock.advance(Duration::hours(1));
        assert_eq!(suprnova::clock::now(), at + Duration::hours(1));

        // A task started with `tokio::spawn` does not inherit the scope.
        // Run it through the handle to give it the same clock.
        let mover = clock.clone();
        let seen = tokio::spawn(async move {
            mover.run(async { suprnova::clock::now() }).await
        })
        .await
        .unwrap();
        assert_eq!(seen, at + Duration::hours(1));
    })
    .await;
}
```

Outside the scope, the system clock answers again.

### Parallel tests

No call moves the clock of the whole process. A guard affects its own
thread and a scope affects its own future, so tests that run side by side
do not see each other's time.

### Your own code

Code of your own that reads the time to make a decision, such as "is this
invite older than seven days", should read `suprnova::clock::now()` when
its tests need to move that time. A direct `chrono::Utc::now()` follows the
system clock.

The health endpoint reports the time of the machine and ignores a test
clock.

### The `testing` feature

`TestClock`, `TestClockGuard` and `TestClockHandle` exist when the `testing`
feature is on. It is in the default feature set, so an application that
depends on `suprnova` with default features has them in its tests. See
[The `testing` feature and production builds](#the-testing-feature-and-production-builds)
for a build that leaves the feature off. Without the feature,
`suprnova::clock::now()` is `Utc::now()` and nothing else.

## The `testing` feature and production builds

`suprnova` exposes its test helpers (`Storage::fake()`, `TestContainer`,
`TestDatabase`, crypto rotation hooks like `_test_install_key`) behind a
Cargo feature named `testing`. The feature is in the default set, so
consuming test suites get them for free:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2" }

[dev-dependencies]
# `testing` is on transitively via the dependency above - nothing extra.
```

The hooks are `#[doc(hidden)]` and prefixed with `_test_`, so they
aren't reachable from idiomatic application code even when the feature
is on. The load-bearing safeguard is `Server::from_config`: it
validates `APP_KEY` on **every** boot, not only when the keyring is
uninitialized. A pre-installed test key cannot bypass that check -
boot fails fast if `APP_KEY` is missing or malformed regardless of
whether anything in-process pre-installed a key.

If you prefer the helpers not to be linked into your production
artifact at all (defence in depth), depend on `suprnova` with default
features off and enable only what you ship:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", default-features = false, features = ["..."] }

[dev-dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", features = ["testing", "..."] }
```

This is a tightening, not a fix - boot validation closes the actual
exploit regardless of which posture you pick.

### Why Suprnova diverges

Laravel's PHP test harness gets parallel-test isolation almost for free
because the runtime is single-threaded per request and tests fork a
new process per file. The Suprnova test binary is one process running
many `#[tokio::test]`s on one or more worker threads concurrently. A
single global container would mean one test's fake bleeds into the
next test's lookup the instant they overlap on a worker thread.

That's why `TestContainer` has both flavours - thread-local for the
common `current_thread` case, task-local for `multi_thread`. The
refcounted clear of the process-global
named-connection registry exists for the same reason: shared state that
can't be made per-test must at least know not to wipe itself while
another test is still leaning on it.

The matcher catalogue (`expect!`) is typed because Rust lets it be.
Jest's `expect(x).toBeSome()` only knows at runtime whether `x` is an
`Option`; Suprnova's `Expect<T>` knows at compile time, so a wrong
matcher is a build error, not a flaky test.

## Where each piece lives

| Piece | Source |
|---|---|
| `#[suprnova_test]` attribute macro | `suprnova-macros/src/suprnova_test.rs` |
| `describe!` / `test!` proc-macros | `suprnova-macros/src/describe.rs`, `test_macro.rs` |
| `expect!` macro + `Expect<T>` matchers | `framework/src/lib.rs` (macro), `framework/src/testing/expect.rs` (impls) |
| `TestDatabase::fresh` / `sqlite_memory` / `refresh` / `refresh_lazily` / `migrate` / `seed` / helpers | `framework/src/database/testing.rs` |
| `test_database!` macro | `framework/src/database/testing.rs` |
| `TestContainer` + `TestContainerGuard` | `framework/src/container/testing.rs` |
| `install_test_encryption_key[ring]` | `framework/src/testing/mod.rs` |
| `clock::now`, `TestClock`, `TestClockGuard`, `TestClockHandle` | `framework/src/clock.rs` (re-exported from `suprnova::testing`) |
| `encrypt_string_under`, `encrypt_string_for_under` | `framework/src/crypto/testing.rs` |
| `console::test`, `ConsoleRun` | `framework/src/console/testing.rs` |
| Per-surface fakes (Mail, Notify, Queue, Bus, Events, Storage, HTTP) | per-domain `testing` submodules - see [Mocking](mocking.md) |
| `TestClient`, `TestRequest`, `ActingUser` | `framework/src/testing/client.rs` |
| `TestResponse` | `framework/src/testing/response.rs` |
| `AssertableInertia`, `ReloadRequest` | `framework/src/testing/inertia.rs` |

## Running tests

The standard cargo invocations apply:

```bash
# Whole workspace
cargo test --workspace

# One crate
cargo test -p suprnova

# One test by name (substring match)
cargo test create_user_persists_it

# With println! and dbg! output
cargo test -- --nocapture
```

Suprnova doesn't ship its own test runner; the framework integrates
with cargo's. Database tests run in parallel by default - the
thread-local container and per-test in-memory SQLite are designed for
exactly that.

See [Page Budget](page-budget.md) to audit a document and its assets together.

## Next

- [HTTP Tests](http-tests.md) - driving the full request pipeline
  through `handle_request`
- [Database Tests](database-testing.md) - `TestDatabase`, factories
  in tests, seeders in tests, parallel-safe DB testing
- [Mocking and Fakes](mocking.md) - the seven external-surface fakes
  and the patterns they share
- [Service Container](container.md) - the three-layer lookup that
  `TestContainer` overrides
- [Error Model](error-model.md) - `FrameworkError` shapes you'll be
  asserting on


---

<!-- /docs/http-tests -->

# HTTP Tests

This chapter shows how to test your HTTP surface - routes, middleware,
auth flows, error responses - by driving the framework's request
pipeline through `suprnova::handle_request`. If you've written Laravel
feature tests with `$this->get('/users')` and asserted on
`$response->status()`, this is the Suprnova equivalent: the same
`Router` you mount in production runs in the test, every middleware
fires, the panic boundary still catches, and the response is
byte-for-byte what a real client sees. `suprnova::testing::TestClient`
drives that pipeline for you, with no port and no harness to copy; see
[The test client](#the-test-client).

## The test surface

There are exactly three building blocks:

| Piece | Role |
|---|---|
| `Router` | The routes under test - built the same way as in production |
| `MiddlewareRegistry` | The global middleware stack - also built the same way |
| `handle_request(router, registry, req) -> hyper::Response<…>` | The in-process driver - runs one request end-to-end |

`handle_request` is the same function `Server::run` calls per
request, exposed for tests and embedders. Anything that works in
production works here - the panic-recovery wrapper, the request-id
scope, the Inertia flash-bag scope, the auth request state scope, the
HEAD-body strip, post-response termination. There is no "test mode"
that swaps a quieter pipeline in.

`handle_request_with_peer` is the same call with an explicit
`Option<std::net::IpAddr>` for the connecting peer - useful when you
want to assert on `Request::ip()` resolution without setting up proxy
headers.

## The test client

`suprnova::testing::TestClient` is the one client every HTTP test can
reach for, as Laravel's `$this->get('/users')` is. Build it from the
same router and middleware registry you would pass to `handle_request`,
send requests, and assert on the `TestResponse` each one returns:

```rust
use serde_json::json;
use suprnova::testing::TestClient;
use suprnova::{HttpResponse, MiddlewareRegistry, Request, Router};

#[tokio::test]
async fn greets_and_creates_a_user() {
    let router = Router::new()
        .get("/", |_req: Request| async { suprnova::http::text("hello") })
        .post("/users", |req: Request| async move {
            let body: serde_json::Value = req.json().await.map_err(HttpResponse::from)?;
            Ok(HttpResponse::json(json!({ "created": body["name"] })))
        });
    let client = TestClient::new(router, MiddlewareRegistry::new());

    client.get("/").send().await.assert_ok().assert_see("hello");

    client
        .post("/users")
        .json(&json!({ "name": "Ada" }))
        .send()
        .await
        .assert_ok()
        .assert_json(json!({ "created": "Ada" }));
}
```

`get`, `post`, `put`, `patch`, `delete`, and `send(Method, path)` for any
other method start a `TestRequest`. Before `.send().await`, add to it
with `header(name, value)`, which replaces a header of the same name,
`json(&body)`, `form(&pairs)`, `inertia()`, which sends an Inertia
visit's headers (see [Testing Inertia responses](#testing-inertia-responses)),
and `inertia_version(version)`. A request gets `Host: localhost` unless
you set one.

The client takes care of what a hand-written harness does by hand:

- **No port.** Each request opens an in-memory connection
  (`tokio::io::duplex`): the server half hands the parsed request to
  `handle_request`, and the client half sends it. Both halves run in the
  task that awaits `send()`, so a `TestContainer::fake()` or
  `TestContainer::scope` the test set up is the container the request
  sees.
- **Cookies.** The client keeps every cookie a response sets and sends
  them on its next request, and it drops a cookie a response expires, so
  a session one request starts is the next request's session. A clone of
  the client shares its cookies.
- **The error report.** Each response keeps the `ErrorReport` the
  framework attached, as `TestResponse::from_response` does; see
  [See why a request failed](#see-why-a-request-failed).
- **The session store.** `with_session_store(store, cookie_name)` gives
  every response the store, so `assert_session_has` reads the session
  with nothing attached per response. A request that leaves the session
  unchanged sets no cookie; the lookup then uses the cookie the client
  carries.
- **A timeout.** A request that doesn't answer within 10 seconds panics
  naming its method and path. `timeout(duration)` changes the limit.

A session carried across requests:

```rust
use suprnova::session::{SessionConfig, SessionMiddleware};

let session = SessionMiddleware::new(SessionConfig::default());
let store = session.store();
let client = TestClient::new(router, MiddlewareRegistry::new().append(session))
    .with_session_store(store, "suprnova_session");

client.post("/cart").form(&[("sku", "A-1")]).send().await.assert_redirect(Some("/cart"));
client
    .get("/cart")
    .send()
    .await
    .assert_ok()
    .assert_session_has("cart_sku", "A-1")
    .await;
```

To test the whole application, build the registry the way it does:
call its bootstrap's middleware registration, then pass
`MiddlewareRegistry::from_global()`. The dogfood app's
`app/tests/inertia_test_client.rs` does exactly that.

### Default headers

When every request of a test needs the same header, such as an API
version or a tenant, set it once on the client. `with_header(name,
value)` and `with_headers(pairs)` return a client that sends those
headers on every request it builds afterwards, as Laravel's
`withHeaders` does. A header you set on one request with `header`
replaces the client's value for that request only. `flush_headers()`
clears the defaults, as Laravel's `flushHeaders` does:

```rust
let mut client = TestClient::new(router, MiddlewareRegistry::new())
    .with_headers([("X-Api-Version", "2"), ("X-Tenant", "acme")]);

client.get("/invoices").send().await.assert_ok();

// This request sends version 3; the next one sends 2 again.
client.get("/invoices").header("X-Api-Version", "3").send().await.assert_ok();

client.flush_headers();
client.get("/invoices").send().await.assert_status(400);
```

Header names compare without case, so `with_header("x-tenant", ...)`
replaces `X-Tenant`. A request you built before a change keeps the
headers it started with.

### `QUERY` requests

`query_json(path, &body)` starts a `QUERY` request with `body` as JSON,
`Content-Type: application/json` and `Accept: application/json`, as
Laravel's `queryJson` does. A `query!` route answers it. The two JSON
headers win over the client's defaults, and a `header` call on the
request wins over both:

```rust
client
    .query_json("/search", &json!({ "q": "laravel" }))
    .send()
    .await
    .assert_ok()
    .assert_json(json!({ "total": 1 }));
```

### Acting as a user

`acting_as(&user)` returns a client whose every request is signed in as
`user` through the default guard, as Laravel's `actingAs($user)` does. A
route behind `AuthMiddleware` answers as it does for a signed-in user,
and `Auth::user()` in its handler is `user`. You write no middleware,
and the user needs no session or provider lookup:

```rust
use suprnova::testing::TestClient;
use suprnova::{AuthMiddleware, MiddlewareRegistry, Router};

let router = Router::new()
    .get("/dashboard", dashboard)
    .middleware(AuthMiddleware::redirect_to("/login"));
let guest = TestClient::new(router, MiddlewareRegistry::new());

guest.get("/dashboard").send().await.assert_redirect(Some("/login"));

let user = User::find_or_fail(1).await?;
let client = guest.clone().acting_as(&user);
client.get("/dashboard").send().await.assert_ok();
```

Each request sets the user on the guard (`Guard::set_user`) before any
middleware runs, so every middleware and the handler see it. Nothing is
written to the session. Pass the user by reference: a model or any
other `Authenticatable` that is `Clone` is cloned, and an
`Arc<dyn Authenticatable>` is shared (the `ActingUser` trait). Call
`acting_as` again to switch users.

`acting_as_with_guard(&user, "api")` signs the user in through the named
guard instead, as `actingAs($user, 'api')` does. A route behind
`AuthMiddleware::new().for_guard("api")` answers as the user, and
`Auth::guard("api")` reports the user. The named guard is also the guard
in use for every request the client sends, as `actingAs` calls
`shouldUse('api')`: `Auth::user()`, `Auth::id()`, `Auth::check()` and
`AuthMiddleware::new()` answer through it. The configured default guard
holds no user unless you name it.

The auth manager keeps one instance of each guard for the length of a
request, so a guard you register with `Auth::extend` that keeps its user
on the instance answers the middleware and the handler with the user the
client set on it. `Auth::id()` and `Auth::check()` do not wait, so they
cannot ask such a guard: when it is the guard in use, they report nobody,
and you ask `Auth::user()` or `Auth::guard(name)` instead.

The client looks the guard up when a request runs, so an `AuthManager`
the test registers after building the client is the one it uses. A
guard the application did not register fails every request before any
middleware or handler runs, so the user is signed in nowhere. The
response is a `500`, and its error report names the guard:

```text
assert_ok()
  Expected: 200
  Received: 500
  body: ...
  error report:
    TestClient cannot sign the user in through the guard 'apu'
    caused by: Internal server error: Auth guard 'apu' is not defined. ...
```

Without an `AuthManager` the only guard is the default one,
`Auth::set_user` signs the user in, and any other guard name fails the
same way.

### Why Suprnova diverges

Laravel's test client hands the request object to the kernel in the
same process. Suprnova's request path takes hyper's `Incoming` body,
which only a hyper connection produces, so the client still sends
HTTP/1.1, over memory instead of a socket. A request is a builder you
finish with `.send().await` rather than a call that takes the headers as
arguments, because it is asynchronous.

`with_header`, `with_headers` and `acting_as` return a new client rather
than change the one you call them on, as the client's other builder
calls do. Laravel keeps both on the test case. Clone the client first
when you still need it without them. `flush_headers` changes the client
in place, so it takes `&mut self`.

Laravel's `shouldUse('api')` changes the application's default guard
for the rest of the test. Suprnova selects the guard for the requests of
the client that names it: the application's configured default guard is
untouched outside those requests, and another client on the same
application starts from it. Only the reads follow the selected guard.
`Auth::login`, `Auth::logout`, `Auth::set_user` and the other functions
that sign a user in or out still act on the configured default guard,
where Laravel's act on `api`. Laravel throws for an undefined guard when
`actingAs` runs; Suprnova fails the request instead, because the guard
registry belongs to the container the request runs in.

## The hyper body problem

The one wrinkle worth knowing about up front: `handle_request` takes a
`hyper::Request<hyper::body::Incoming>`. `Incoming` is hyper's
internal streaming body type; you cannot construct one with
`Full::new(bytes)` or any of the in-memory body types. It only comes
out of a hyper connection.

There are three clean ways around it:

1. **An in-memory connection** - what `TestClient` does: a
   `tokio::io::duplex` pipe with a hyper server on one end and a hyper
   client on the other. Reach for this first.
2. **TCP loopback** - bind a `127.0.0.1:0` listener, serve one
   accept inside a `service_fn`, send the request through a hyper
   client, and let `Incoming` be produced naturally on the server
   side. Many of the framework's own integration tests still do this.
3. **In-process Request building** - for tests that only need to
   inspect `Request` accessors (headers, route params, IP, JSON
   parsing) without going through routing, use the same TCP-loopback
   capture pattern but with a service that pulls the `Request` out
   into a `oneshot::channel` instead of running it. The
   `framework/tests/http/request_accessors.rs` file has this
   `build_request()` helper verbatim.

All three produce real `Incoming` bodies. The loopback is local,
synchronous in test wall-clock terms (microseconds), and never touches
the network outside `lo`. There is no slower or simpler way that
preserves the contract.

### Why Suprnova diverges

Laravel's `$this->get('/users')` works because PHP's request lifecycle
is "build a `Request` object, dispatch it through the kernel". The
kernel takes the in-memory object directly; there is no body type that
forces a transport. Suprnova's server is built on hyper, and hyper's
body type is opinionated for good reasons (streaming, backpressure,
zero-copy). The test surface inherits that constraint.

What you trade for the constraint is fidelity. Every detail of the
production request path - header parsing, body limits, connection
upgrades - runs the same way in tests. You will never have a test
pass because the test harness skipped a layer the real server runs.

## A first end-to-end test

Here is a complete, working test that mounts a single route, sends a
GET against it, and asserts on the status and body.

```rust
use std::convert::Infallible;
use std::net::SocketAddr;
use std::sync::Arc;
use std::time::Duration;

use bytes::Bytes;
use http_body_util::{BodyExt, Full};
use hyper::body::Incoming;
use hyper::service::service_fn;
use hyper_util::rt::TokioIo;

use suprnova::http::text;
use suprnova::{MiddlewareRegistry, Request, Router, handle_request};

async fn spawn_server(
    router: Router,
    middleware: MiddlewareRegistry,
    accepts: usize,
) -> SocketAddr {
    let router = Arc::new(router);
    let middleware = Arc::new(middleware);
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
        .await
        .expect("bind ephemeral listener");
    let addr = listener.local_addr().expect("local_addr");

    tokio::spawn(async move {
        for _ in 0..accepts {
            let Ok((stream, _)) = listener.accept().await else { return };
            let io = TokioIo::new(stream);
            let router = router.clone();
            let middleware = middleware.clone();
            tokio::spawn(async move {
                let svc = service_fn(move |req: hyper::Request<Incoming>| {
                    let router = router.clone();
                    let middleware = middleware.clone();
                    async move {
                        Ok::<_, Infallible>(handle_request(router, middleware, req).await)
                    }
                });
                let _ = hyper::server::conn::http1::Builder::new()
                    .serve_connection(io, svc)
                    .await;
            });
        }
    });

    addr
}

async fn send_get(addr: SocketAddr, path: &str) -> (u16, Bytes) {
    let stream = tokio::net::TcpStream::connect(addr).await.unwrap();
    let io = TokioIo::new(stream);
    let (mut sender, conn) =
        hyper::client::conn::http1::handshake::<_, Full<Bytes>>(io).await.unwrap();
    tokio::spawn(async move { let _ = conn.await; });

    let req = hyper::Request::builder()
        .method("GET")
        .uri(path)
        .header("Host", "localhost")
        .header("Content-Length", "0")
        .body(Full::new(Bytes::new()))
        .unwrap();

    let resp = tokio::time::timeout(Duration::from_secs(5), sender.send_request(req))
        .await
        .expect("send_get timeout")
        .expect("hyper send_request");
    let (parts, body) = resp.into_parts();
    let bytes = body.collect().await.unwrap().to_bytes();
    (parts.status.as_u16(), bytes)
}

#[tokio::test]
async fn get_root_returns_hello() {
    let router = Router::new().get("/", |_req: Request| async { text("hello") });
    let addr = spawn_server(router.into(), MiddlewareRegistry::new(), 1).await;

    let (status, body) = send_get(addr, "/").await;
    assert_eq!(status, 200);
    assert_eq!(&body[..], b"hello");
}
```

That's the entire shape, and `TestClient` is the same test in two
lines. When a suite needs the socket itself, copy the two helpers per
crate and tune them (multiple accepts, header capture, body capture). The
framework itself uses near-identical helpers in
`framework/tests/cors/middleware.rs`,
`framework/tests/middleware/panic_safety.rs`, and
`framework/tests/auth_flows/email_verified_middleware.rs`.

The `accepts` argument bounds how many connections the accept loop
serves before exiting. One is enough for a single request; bump to
two-or-more when a test exercises post-panic recovery (see
[Testing the panic boundary](#testing-the-panic-boundary)).

## Building a request

Inside `send_get` you saw:

```rust
let req = hyper::Request::builder()
    .method("GET")
    .uri("/users/42")
    .header("Host", "localhost")
    .header("Content-Length", "0")
    .body(Full::new(Bytes::new()))
    .unwrap();
```

That's the canonical shape. A few things worth knowing:

- **`Host` header**. Hyper rejects HTTP/1.1 requests without one. Always
  include it; the value doesn't matter unless your handler keys on it.
- **`Content-Length: 0`**. Match the body. Hyper computes this for you
  with `Full::new(Bytes::new())`, but being explicit reads cleaner in
  tests.
- **Body types**. The client side sends `Full<Bytes>`. The server side
  receives `Incoming`. You only ever build `Full<Bytes>` requests in
  tests; the framework receives them as `Incoming` after hyper's
  per-connection conversion.

A POST with a JSON body:

```rust
let body_bytes = serde_json::to_vec(&serde_json::json!({
    "name": "Alice",
    "email": "alice@example.com"
})).unwrap();

let req = hyper::Request::builder()
    .method("POST")
    .uri("/users")
    .header("Host", "localhost")
    .header("content-type", "application/json")
    .header("content-length", body_bytes.len())
    .body(Full::new(Bytes::from(body_bytes)))
    .unwrap();
```

## Asserting on the response

The response that comes back from `handle_request` is a
`hyper::Response<BoxBody<Bytes, Infallible>>`. Three things you'll
read off it:

```rust
let (parts, body) = resp.into_parts();

// 1. Status.
assert_eq!(parts.status.as_u16(), 200);

// 2. Headers - case-insensitive lookup.
let location = parts.headers.get("location").and_then(|v| v.to_str().ok());
assert_eq!(location, Some("/login"));

// 3. Body - collect into bytes, then parse.
use http_body_util::BodyExt;
let bytes = body.collect().await.unwrap().to_bytes();

// As text:
let text = String::from_utf8_lossy(&bytes);

// As JSON:
let value: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(value["message"], "ok");
```

For ordinary error responses that reach the common renderer, the body
shape documented in [Error Model](error-model.md) includes `message`,
optional `errors`, `request_id`, and an optional `debug_message`.
`request_id` is `null` outside a request scope. Three special variants
return before request-id injection: `PrecognitionSuccess` is a bodyless
204, `PrecognitionFailure` is the validation body plus Precognition
headers, and an accidentally HTTP-rendered `AlreadyReported` sentinel
is a generic 500 containing only `message`. Use an ordinary error
response when asserting that request-id middleware ran.

## Fluent response assertions with TestResponse

Building the `(status, headers, body)` triple by hand and asserting on it
piece by piece, as above, is the foundation every harness in this crate
uses. `suprnova::testing::TestResponse` wraps that same triple in a
fluent, Laravel-shaped API, so a test reads like an assertion instead of
a header lookup:

```rust
use suprnova::testing::TestResponse;

let (parts, body) = resp.into_parts();
let bytes = body.collect().await.unwrap().to_bytes();
let headers = parts.headers.iter().map(|(k, v)| {
    (k.as_str().to_string(), v.to_str().unwrap_or_default().to_string())
});

TestResponse::new(parts.status.as_u16(), headers, bytes)
    .assert_ok()
    .assert_header("content-type", "application/json")
    .assert_json(serde_json::json!({ "message": "ok" }));
```

`new()` accepts anything iterable as `(String, String)` header pairs -
a `HashMap<String, String>` (what several existing harnesses already
collect into), a `Vec<(String, String)>`, or `HeaderMap::iter()` mapped
to owned strings - so no harness has to change how it drives a request.

Every assertion returns `&Self`, so they chain: `assert_status`,
`assert_ok`, `assert_no_content`, `assert_no_content_status(status)`,
`assert_redirect(target: Option<&str>)`, `assert_json`
(subset match - extra keys in the body are fine), `assert_json_path`
(dot notation, a numeric segment indexes an array), `assert_json_count`,
`assert_see`, `assert_header`, `assert_cookie`. Assertion failures
panic with an expected/actual excerpt, the same contract as `expect!`
([Testing](testing.md)) - this is a testing surface, not library code,
so the no-panic house rule doesn't apply.

`assert_no_content()` passes only for a `204` with an empty body, as
Laravel's `assertNoContent()` does. `assert_no_content_status(205)`
checks another status the same way. A `204` that carries a body fails,
and the failure shows the body:

```rust
client.delete("/posts/1").send().await.assert_no_content();
```

### See why a request failed

When a handler or middleware returns an error, or panics, the client
gets a sanitized body. With debug off, a 5xx says only
`{"message": "Internal Server Error", ...}`. That's the right answer for
a client and no help when a test fails. So the framework attaches an
`ErrorReport` to the response it builds from a failure. The report
holds the error and each of its sources, or a panic's message and the
location it was raised at. It lives in the response's in-process
extensions, and it never adds anything to a header or the body.

A response carries a report when one of these built it:

- A handler or middleware returned a `FrameworkError`, other than
  `PrecognitionSuccess`, which answers a passing dry run.
- The panic boundary caught a panic in a handler or a middleware, on an
  HTTP route or in the middleware of a WebSocket route's upgrade.
- A framework middleware answered a failure with a 5xx of its own:
  `SessionMiddleware` when it can't store the session safely and fails
  closed, or when the cache can't take the session's lock;
  `ThrottleRequestsMiddleware` when its cache fails or it names a
  limiter that nobody defined; `RateLimitMiddleware` and
  `LoginThrottleMiddleware` when they fail closed on a backend error;
  `TimeoutMiddleware` when the request runs past its deadline; and the
  RenderCache middleware's `503` when a provider fails on a route whose
  `FailurePolicy` is `Closed`, and its `500` for a render whose
  transaction the database refused.
- A route the framework ships answered a failure with a 5xx: the payment
  webhook route when its database, the render cache, hydration, or the
  body read fails, and the Live endpoints when the endpoint itself holds
  the error: binding the Live runtime, reading the request body,
  completing an action's response, or loading the asset catalog.

A refusal that a middleware answers on purpose carries no report,
because nothing failed: the `429` a throttle or rate limiter answers a
client over its limit with, the `503` while another request holds the
session's lock, or the `503` of maintenance mode.

With debug on, which is the default when `APP_DEBUG` is unset in the
local, development, and testing environments, a 5xx body built from a
`FrameworkError` also carries
`debug_message`: the error chain as `render_error_chain` renders it.
That's the body debug mode gave before the report existed, and the
report doesn't change it. The field comes from the debug setting; the
report adds nothing to the body in either mode. A test request that is
an Inertia visit, or whose `Accept` header lists `text/html`, gets the
development error page in place of that body, with the report still
attached; see [Error Model](error-model.md#the-development-error-page).

To keep the report, build the `TestResponse` from the response
`handle_request` returns, with `TestResponse::from_response`. It
collects the body for you:

```rust
use std::sync::Arc;

use suprnova::testing::TestResponse;
use suprnova::{MiddlewareRegistry, handle_request};

// `incoming_get_request` builds a real `Incoming` request over an
// in-memory pipe. Copy it from `framework/tests/support/common.rs`.
let req = incoming_get_request("/invoices/42", &[]).await;
let resp = handle_request(Arc::new(router), Arc::new(MiddlewareRegistry::new()), req).await;

TestResponse::from_response(resp).await.assert_ok();
```

When an assertion fails on a response that carries a report, the
failure message ends with it. With debug off, it reads:

```text
assert_ok()
  Expected: 200
  Received: 500
  body: {"message":"Internal Server Error","request_id":"9f1c..."}
  error report:
    posting the invoice failed
    caused by: writing ledger entry 42 failed
    caused by: disk /var/ledger is full
```

For a panic, the report names the panic and where it was raised:
`panicked at src/controllers/ledger.rs:31:9: ledger index page 7 is
unreadable`. To capture the location, the framework wraps the process
panic hook once, and the wrapper calls the hook it replaced. An app
that installs its own hook later, without calling the previous one,
still gets the panic message in the report but not the location.

To inspect the report in a test, call `error_report()`. It returns
`None` for a response that wasn't built from an error:

```rust
let response = TestResponse::from_response(resp).await;
let report = response.error_report().expect("the request failed");

assert!(!report.is_panic());
assert_eq!(report.chain()[0], "posting the invoice failed");
```

`chain()` lists the error's own message and then each source's. Only
an error that keeps its source has more than one link:
`FrameworkError::from_external` and `from_external_with` keep the
wrapped error and its sources, while most other variants, including the
`Domain` error that `FrameworkError::from_http_error` and an `AppError`
become, hold a message and a status only, so their report is that one
line. `is_panic()` and `panic_location()` describe a caught panic.
Middleware can read the same report off an `HttpResponse` with
`HttpResponse::error_report()`.

The Inertia error page and the Inertia validation redirect keep the
report of the response they replace, so an Inertia visit that failed
with a `500` and came back as the `Error` page still says why. The
assertions of `assert_inertia()`, and of an `AssertableInertia` built
with `AssertableInertia::from_response` from an `HttpResponse` that
carries a report, end their failure messages with it too:

```text
AssertableInertia::component("Posts/Index")
  Expected: "Posts/Index"
  Received: "Error"
  error report:
    posting the invoice failed
    caused by: writing ledger entry 42 failed
    caused by: disk /var/ledger is full
```

Ways to end up without a report:

- `TestResponse::new` builds from a `(status, headers, body)` triple,
  which has nowhere to carry one.
- A response read back over the TCP loopback has crossed the wire,
  and the report stays on the server side by design.
- A middleware of your own that builds a new `HttpResponse` in place of
  an error response drops the report, which stays on the response it
  replaced. Change the response you were given, with `header` or
  `status`, and the report stays on it.
- A Live 5xx whose cause the Live stack reduces to a closed error kind
  before the endpoint answers carries none: the action endpoint's
  answers from the Live engine itself, the `unavailable` answers of the
  async publisher, and the `503` kinds of the upload service. Those
  error types carry only the kind, by design, so the cause is in the log
  alone.

### Why Suprnova diverges

Laravel records a test request's exceptions in a process-wide
`LoggedExceptionCollection`, and `TestResponse` appends them to a
failing assertion. `cargo test` runs tests on several threads in one
process, so a process-wide list would hand one test another test's
error. The report rides on the response instead, so each failure
message names only its own request's error.

### `assert_session_has` needs a session store

Every other assertion reads only the wire-level response.
`assert_session_has` can't: server-side session state lives in the
`SessionStore`, not in the response, and by the time a response comes
back over the loopback socket there is no in-process session left to
read. Attach the same store the test's `SessionMiddleware` was built
with, plus its cookie name, and the assertion decrypts the response's
session cookie to find the row itself:

```rust
let response = TestResponse::new(status, headers, body)
    .with_session_store(middleware.store(), "suprnova_session");

response
    .assert_session_has("flash.success", serde_json::json!("Saved!"))
    .await;
```

It's the only `async` assertion, since it's the only one that does I/O;
it still returns `&Self`, so `.await` sits inline and the chain
continues after it.

### Why Suprnova diverges

Laravel's `TestResponse` lives in the same PHP process as the app under
test, so `assertSessionHas` reads `$this->session()` directly - no wire
boundary to cross. Suprnova's tests drive a real hyper connection, so
the session is exactly as opaque to the test as it is to a real
browser: a cookie. `assert_session_has` earns that honesty back with an
explicit store handle instead of pretending the in-process shortcut
exists.

## Testing Inertia responses

`suprnova::testing::AssertableInertia` wraps an Inertia page object in
the same fluent, panic-on-failure style as `TestResponse`. It is
Laravel's `Inertia\Testing\AssertableInertia`.

`TestResponse::assert_inertia()` reads the page from either shape a page
response takes: the JSON page object of an Inertia visit, which carries
`X-Inertia: true`, or the HTML document of a first visit, whose
`<script>` element with `type="application/json"` and `data-page` holds
the page whatever id `InertiaConfig::mount_id` gave it (`app` by
default). The two attributes can come in either order, with others
between them, so the document of a server-rendered first visit reads the
same way: Inertia's `buildSSRBody` writes it as
`<script data-page="app" type="application/json">`. The
`inertia()` request method sends the headers an Inertia visit sends:
`X-Inertia: true`, its `Accept`, and `X-Inertia-Version` set to the
installed configuration's asset version, or the empty string with none
installed.

```rust
use suprnova::testing::TestClient;

let client = TestClient::new(router, MiddlewareRegistry::new());

// An Inertia visit: the JSON page object.
client
    .get("/users")
    .inertia()
    .send()
    .await
    .assert_inertia()
    .component("Users/Index")
    .url("/users")
    .has("users")
    .where_("users.0.name", "Ada")
    .count("users", 1)
    .missing("admin_only_field");

// A first visit: the HTML document.
client.get("/users").send().await.assert_inertia().component("Users/Index");
```

`assert_inertia_with(callback)` runs the callback over the page and
returns the response, so response assertions chain after the page's:

```rust
client
    .get("/users")
    .inertia()
    .send()
    .await
    .assert_inertia_with(|page| {
        page.component("Users/Index").has("users");
    })
    .assert_ok();
```

For a test that drives the response pipeline without a request,
`AssertableInertia::from_response` reads the same two shapes from an
`HttpResponse`, the type `InertiaResponse::resolve` returns:

```rust
use suprnova::testing::AssertableInertia;

let response = InertiaResponse::new("Users/Index")
    .with("users", users_json)
    .resolve(&req)
    .await?;

AssertableInertia::from_response(&response)
    .component("Users/Index")
    .where_("users.0.name", "Ada");
```

`version()` checks the page's asset version. The default resolver
hashes the configured asset URL or the Vite manifest, and the version is
the empty string when neither exists, as in a test that hasn't built a
frontend:

```rust
response.assert_inertia().version("");
```

### The page file behind a component

With an Inertia configuration installed (`Inertia::install`),
`component(name)` also checks that `name` has a page file under the
configuration's `pages_dir` with one of its `page_extensions`, the
lookup `InertiaConfig::ensure_pages_exist` does at render time. A test
asserting a component nobody built fails with
`Inertia page component file [Name] does not exist.`, the directory, and
the extensions it tried, instead of passing while the browser shows a
blank page. With no configuration installed there is no directory to
look in, and nothing is checked.

`InertiaConfig::testing_ensure_pages_exist(false)` turns the check off,
and `component_exists(name, should_exist)` decides it for one
assertion: `false` compares the name only, and `true` checks the file
even when the configuration turned the check off.

```rust
page.component_exists("Reports/Draft", false); // no page file yet, on purpose
```

### Asserting on props

Every prop assertion takes a dot path, where a numeric segment indexes
an array (`"users.0.name"`), and returns `&Self`:

| Assertion | Passes when |
|---|---|
| `has(path)`, `has_all(paths)`, `has_any(paths)` | The prop exists; every one exists; at least one exists |
| `missing(path)`, `missing_all(paths)` | No prop exists there; at none of them |
| `where_(path, value)`, `where_not(path, value)`, `where_all(pairs)` | The prop equals the value; exists and differs; every pair matches |
| `where_null(path)`, `where_not_null(path)` | The prop exists and is `null`; exists and is not |
| `where_type(path, types)`, `where_all_type(pairs)` | The prop has one of the types, joined by `\|` (`"integer\|null"`) |
| `where_contains(path, value)` | An array prop holds the value, or each value of an array; any other prop equals it |
| `count(path, n)`, `count_between(path, min, max)` | The array or object has `n` elements; from `min` to `max` |

`where_type` takes the names Laravel compares PHP's `gettype` against:
`string`, `integer` (a number without a fraction), `double` (a number
with one), `boolean`, `array` (a JSON array or object), and `null`. Any
other name fails the assertion rather than matching nothing.

`prop(path)` reads a value without asserting, `Null` for a path that
resolves to nothing.

### Scoping into nested props

`scope(path, callback)` runs the callback over the object or array at
`path` as its own `AssertableInertia`. `has_with(path, callback)` asserts
the prop exists first. `first(callback)` and `each(callback)` scope onto
the first element and onto every element of the current level, and fail
when there is none. `has_count_with(path, n, callback)` asserts the
count, then scopes onto the first element:

```rust
response.assert_inertia_with(|page| {
    page.component("Users/Show")
        .scope("user", |user| {
            user.where_("name", "Ada")
                .where_type("id", "integer")
                .missing("password")
                .etc();
        })
        .has_count_with("posts", 2, |post| {
            post.where_type("id", "integer").has("title");
        });
});
```

A scope fails when its callback returns with a prop no assertion
touched, and names the props. Every assertion touches the first segment
of its path. That is how a test notices a page that starts sending a
field nobody asserted on, such as a user's email. Call `etc()` in a
scope to allow the props you didn't name. The page's top level never
checks. A failure inside a scope names the full path (`user.name`), and
a scope keeps the page's component, url, version, and flash.

### Flash data, the whole page, and big integers

`has_flash(key, expected)` reads the page's flash data the same dot-path
way `has` and `where_` read props. `expected` is an `Option`, so pass
`None::<serde_json::Value>` to check presence only. `missing_flash(key)`
asserts a key is absent.

```rust
let page = response.assert_inertia();
page.has_flash("toast.message", Some(serde_json::json!("Saved!")))
    .has_flash("toast", None::<serde_json::Value>)
    .missing_flash("error");
```

A handler that flashes and redirects (`Inertia::flash`) leaves the data
in the session for the page after the redirect, and the redirect itself
carries no page. `assert_inertia_flash(key, expected)` and
`assert_inertia_flash_missing(key)` read it from the session through the
store the client was given, as `assert_session_has` does:

```rust
let saved = client.post("/posts").form(&[("title", "Hello")]).send().await;

saved
    .assert_redirect(Some("/posts"))
    .assert_inertia_flash("toast", Some("Saved"))
    .await
    .assert_inertia_flash_missing("error")
    .await;
```

`TestResponse::inertia_page()` returns the whole page as a
`serde_json::Value` (`component`, `props`, `url`, `version`, `flash`,
and `encryptHistory` and `clearHistory` only when the page set them),
which `AssertableInertia::to_page()` returns too. `inertia_props(None)`
returns the props, and `inertia_props(Some("user.name"))` returns one
value, `Null` when the path resolves to nothing.
`encrypt_history()` and `clear_history()` read the two flags.

A page rendered with `preserve_big_integers(true)` sends every integer
beyond JavaScript's safe range (2^53 - 1) as `{"$bigint": "<digits>"}`.
The assertions decode the markers first, so you compare against the
integer the handler rendered:

```rust
response.assert_inertia().where_("id", 9007199254740993_i64);
```

A marker whose digits fit no 64-bit integer (`i64` or `u64`) fails the
assertion, naming the marker's path and digits, such as `props.user.id`
and `18446744073709551616`. The framework marks only integers it holds in
64 bits, so such a marker comes from a page object built by hand.

### Reloading for partial-reload and deferred-props assertions

A page from a `TestClient` response reloads through that client, with
its cookies, the way the Inertia client reloads after the first visit.
Each reload asserts it landed on the same component, url, and version,
and returns the reloaded page, which reloads again the same way:

```rust
let page = client.get("/users").inertia().send().await.assert_inertia();

// A full reload: no partial-reload header.
page.reload().await.has("users");

// Requests only `users`, and asserts it came back.
page.reload_only(["users"]).await;

// Requests everything except `stats`, and asserts it is absent.
page.reload_except(["stats"]).await;

// Requests the props of the `stats` deferred group only.
page.load_deferred_props_of(["stats"]).await.has("stats");

// Requests every deferred group in one partial reload.
page.load_deferred_props().await;
```

`reload_with`, `reload_only_with`, `reload_except_with`, and
`load_deferred_props_with` take a callback over the reloaded page:

```rust
page.load_deferred_props_with(["stats"], |reloaded| {
    reloaded.where_("stats.total", 25);
})
.await;
```

`load_deferred_props_of` fails naming a group the page doesn't defer, so
a typo can't request nothing and pass.

Under a public path prefix, such as `APP_URL=https://example.test/billing`,
the page's url is the public one, `/billing/users`, while the router
matches the path the request arrived on, `/users`. The client keeps the
root each request was served under, and a reload replays the internal
path, `/users` with the page's query, so it reaches the route the first
visit did. A reload also sends again the `X-Forwarded-Prefix` header the
page's request sent, if any. A `ReloadRequest` carries the public url, so
a `with_reload` harness removes the root itself.

A test that drives requests through its own harness attaches the replay
with `with_reload`, a closure from a `ReloadRequest` (the url,
component, version, and partial-reload keys to send) to a future that
produces the reloaded page. It replaces the client's own on a client
response too:

```rust
let page = TestResponse::new(status, headers, body)
    .assert_inertia()
    .with_reload(move |reload| async move {
        let header_pairs = reload.headers();
        let headers: Vec<(&str, &str)> = header_pairs
            .iter()
            .map(|(k, v)| (k.as_str(), v.as_str()))
            .collect();
        let (status, headers, body) = request(addr, "GET", &reload.url, &headers).await;
        TestResponse::new(status, headers, body).assert_inertia()
    });

page.reload_only(["users"]).await;
```

`ReloadRequest::headers()` sends `X-Inertia` and `X-Inertia-Version`
always, and `X-Inertia-Partial-Component` with `X-Inertia-Partial-Data`
or `X-Inertia-Partial-Except` only when the reload names keys. A page
with neither a client nor `with_reload` panics on a reload with that
instruction.

### Why Suprnova diverges

- Laravel's optional callback arguments are `_with` siblings here:
  `assert_inertia_with`, `reload_with`, `reload_only_with`,
  `reload_except_with`, `load_deferred_props_with`, `has_with`, and
  `has_count_with`. Laravel's `component($name, $shouldExist)` is
  `component_exists`, and `loadDeferredProps($groups)` is
  `load_deferred_props_of`. Rust has no optional arguments.
- `where` is a Rust keyword, so the assertion is `where_`. The
  assertions drop the `assert_` prefix of `TestResponse`'s, as Laravel's
  `AssertableInertia` does; the panic-on-failure contract is the same.
- The page's top level never checks that every prop was touched.
  Laravel's `assertInertia` doesn't either, where `AssertableJson` used
  through `assertJson(fn)` does; scopes check in both.
- A reload returns the reloaded page, where Laravel's returns the
  original, so you can chain assertions and further reloads off it.
- `load_deferred_props_of` fails for a group the page doesn't defer,
  where Laravel requests no props and passes.
- `assert_inertia_flash` is `async` and reads the session through the
  attached store, since the session lives behind the server, not in the
  test's process memory.
- A big-integer marker whose digits fit no 64-bit integer fails the
  assertion naming its path, where Laravel's `(int)` cast saturates a wide
  value and turns a non-numeric one into `0`.

## Testing middleware

Middleware tests look identical to route tests; the only difference
is what you `.append()` to the registry before spawning.

### Testing global middleware

Pass the middleware to `MiddlewareRegistry::new().append(...)` and
use that registry - multiple middlewares run in append order,
`prepend` puts a new one at the front.

```rust
use suprnova::{CorsConfig, CorsMiddleware, MiddlewareRegistry};

fn cors_registry() -> MiddlewareRegistry {
    MiddlewareRegistry::new().append(CorsMiddleware::new(
        CorsConfig::allow_origins(["https://app.example"])
            .allow_credentials(true)
            .max_age(std::time::Duration::from_secs(600)),
    ))
}

#[tokio::test]
async fn cors_preflight_returns_204_with_headers() {
    let router = Router::new();
    let addr = spawn_server(router, cors_registry(), 1).await;

    let (status, headers, _) = options(
        addr,
        "/anything",
        &[
            ("Origin", "https://app.example"),
            ("Access-Control-Request-Method", "POST"),
        ],
    ).await;

    assert_eq!(status, 204);
    assert_eq!(
        headers.get("access-control-allow-origin").map(String::as_str),
        Some("https://app.example"),
    );
}
```

This test proves more than the CORS logic itself: it proves that
global middleware runs on **unrouted** requests too, which is the
contract the framework guarantees (otherwise an OPTIONS preflight that
never matches a route would skip CORS). See `framework/tests/cors/middleware.rs`
for the full suite.

### Testing route-specific middleware

Attach with `.middleware(...)` on the route builder, exactly like
production. Then test the route as normal - the middleware chain is
built off the same registration.

```rust
let router = Router::new()
    .get("/admin/dashboard", |_req| async { text("admin") })
    .middleware(RequireRole::new("admin"));

let (status, _) = send_get(addr, "/admin/dashboard").await;
assert_eq!(status, 403); // unauthenticated request
```

### Stubbing the authenticated user

Real auth-flow tests need a logged-in user. With `TestClient`, call
`acting_as(&user)`; see [Acting as a user](#acting-as-a-user).

A test that drives `handle_request` through its own harness uses a tiny
one-off middleware that calls `Auth::set_user` ahead of the middleware
under test, which is what `acting_as` does for you. The framework's own
`framework/tests/auth_flows/email_verified_middleware.rs` uses this:

```rust
use std::any::Any;
use std::sync::Arc;
use suprnova::{Auth, Authenticatable, Middleware, Next, Request, Response};

struct UserById(String);

impl Authenticatable for UserById {
    fn get_auth_identifier(&self) -> String { self.0.clone() }
    fn as_any(&self) -> &dyn Any { self }
    fn into_arc_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync> { self }
}

struct LoginAs(String);

#[async_trait::async_trait]
impl Middleware for LoginAs {
    async fn handle(&self, request: Request, next: Next) -> Response {
        Auth::set_user(Arc::new(UserById(self.0.clone())));
        next(request).await
    }
}
```

Then in the test:

```rust
let registry = MiddlewareRegistry::new()
    .append(LoginAs("user-id-123".to_string()))
    .append(EnsureEmailVerifiedMiddleware::new());
```

`LoginAs` runs first, installs the user into the per-request auth
state, and the middleware under test sees `Auth::id() == Some(...)`
without ever issuing a real login. The auth state scope is set up by
`handle_request` itself - the same one that runs in production - so
the user is visible to every later middleware and the handler.

## Testing route model binding

A `#[suprnova::model]` struct binds from the route parameter its argument
names. Drive the binding through a router, so the router's checks and the
handler's extraction both run:

```rust
use suprnova::{Response, handler};

#[suprnova::model(table = "users")]
pub struct User {
    pub id: i64,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

#[handler]
async fn show(user: User) -> Response {
    suprnova::http::json(serde_json::json!({ "email": user.email }))
}

#[tokio::test]
async fn show_user_binds_from_the_route() {
    // Insert a test user via the model. Database setup omitted -
    // see the testing chapter for `TestDatabase` patterns.
    let user = User::create(suprnova::attrs! {
        email: "bound@example.com"
    }).await.unwrap();

    // The placeholder carries the argument's name.
    let router: Router = Router::new()
        .get("/users/{user}", show)
        .into();
    router.prepare_bindings().expect("the route declares `user`");

    let addr = spawn_server(router, MiddlewareRegistry::new(), 1).await;
    let (status, body) = send_get(addr, &format!("/users/{}", user.id)).await;

    assert_eq!(status, 200);
    let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
    assert_eq!(json["email"], "bound@example.com");
}
```

`router.prepare_bindings()` runs the router's startup checks and returns
the refusal as an error, so a test can assert that a route whose handler
reads an undeclared parameter, such as `/users/{id}` with `user: User`,
is refused. A router driven through `handle_request` runs the same checks
before its first request and answers 500 when they fail.

For binding-in-isolation tests, call
`<User as suprnova::RouteBinding>::resolve_route_binding(value, None)`
directly. It returns `Ok(None)` for a value that does not parse or
matches no row, and checks the lookup without a router.

## Testing auth flows end-to-end

To test a login session end to end, pass a registry containing
`SessionMiddleware` to the loopback server and protect `/dashboard`
with `AuthMiddleware` or the application's web-auth middleware. First
prove the route rejects a cookieless request, then log in, replay the
returned session cookie, and prove the protected route succeeds:

```rust
#[tokio::test]
async fn login_flow_issues_session_cookie() {
    // 1. Bootstrap: create the user.
    Auth::password()
        .register("alice@example.com", "longpassword123")
        .await.expect("register");

    // 2. Mount a protected route and the stateful session middleware.
    let router: Router = Router::new()
        .post("/login", login_handler)
        .get("/dashboard", |_req: Request| async { text("dashboard") })
        .middleware(AuthMiddleware::new())
        .into();
    let registry = MiddlewareRegistry::new()
        .append(SessionMiddleware::new(SessionConfig::from_env()));
    let addr = spawn_server(router, registry, 3).await;

    // 3. Prove the route is protected before authenticating.
    let (guest_status, _) = send_get(addr, "/dashboard").await;
    assert_eq!(guest_status, 401);

    // 4. Drive login and capture the Set-Cookie header.
    let login = post_json(addr, "/login", serde_json::json!({
        "email": "alice@example.com",
        "password": "longpassword123",
    })).await;
    assert_eq!(login.status, 200);
    let cookie = extract_session_cookie(&login.headers);

    // 5. Replay the cookie against the protected route.
    let (status, body) = get_with_cookie(addr, "/dashboard", &cookie).await;
    assert_eq!(status, 200);
    assert_eq!(&body[..], b"dashboard");
}
```

The abbreviated router without those middlewares demonstrates cookie
plumbing only; it is not an authentication-flow test.
`framework/tests/auth/http_middleware.rs` tests authentication
middleware behavior with explicit registries, but it does not install a
real `SessionMiddleware`. A stateful login-flow test must install both
the session middleware and the authentication gate as shown above.

## Testing the panic boundary

A panic inside a handler must not crash the server. The
panic-recovery wrapper (`execute_chain_safely`) catches it and
converts to a 500 through the same path returned errors flow through.
You can verify this without any special test infrastructure - set
`accepts >= 2` so the listener survives the panic:

```rust
#[tokio::test]
async fn panicking_handler_yields_500_and_server_survives() {
    let router = Router::new()
        .get("/panic", |_req: Request| async {
            panic!("intentional test panic");
            #[allow(unreachable_code)] text("unreachable")
        })
        .get("/ok", |_req: Request| async { text("ok") });

    let addr = spawn_server(router.into(), MiddlewareRegistry::new(), 4).await;

    // First: the panic translates to a sanitised 500.
    let (s1, body) = send_get(addr, "/panic").await;
    assert_eq!(s1, 500);
    let parsed: serde_json::Value = serde_json::from_slice(&body).unwrap();
    assert_eq!(parsed["message"], "Internal Server Error");
    assert!(parsed.get("request_id").is_some());

    // Second: the listener survives. The next request is normal.
    let (s2, body2) = send_get(addr, "/ok").await;
    assert_eq!(s2, 200);
    assert_eq!(&body2[..], b"ok");
}
```

## Testing accessors without going through routing

Sometimes you want to test a `Request` accessor (`bearer_token`,
`is_method`, `ip`, `is_json`, etc.) without spinning up a router at
all. The trick is a tiny harness that runs a hyper service whose only
job is to construct the `Request` and ship it back through a
`tokio::sync::oneshot::channel`:

```rust
let (req_tx, req_rx) = tokio::sync::oneshot::channel::<suprnova::Request>();
// ... loopback hyper service whose service_fn does:
//     let req = suprnova::Request::new(hyper_req);
//     let _  = req_tx.send(req);
//     return a 200 with an empty body
let req = req_rx.await.unwrap();
```

`framework/tests/http/request_accessors.rs` has the full
`build_request(builder, body) -> Request` helper. Copy it once per
crate and every accessor test reads cleanly:

```rust
#[tokio::test]
async fn bearer_token_extracts_simple_token() {
    let req = build_request(
        hyper::Request::builder()
            .method("GET")
            .uri("/api/users")
            .header("Authorization", "Bearer secret-token-123"),
        "",
    ).await;
    assert_eq!(req.bearer_token().as_deref(), Some("secret-token-123"));
}
```

The Request is real (produced by hyper from a real wire exchange), but
no routing or middleware ran - exactly what you want when the unit
under test is the accessor itself.

## Builder hooks on `Request`

When you have a `Request` in hand and need to fake one piece of the
routing layer, three builder methods help:

```rust
impl Request {
    pub fn with_params(mut self, params: HashMap<String, String>) -> Self;
    pub fn with_route_pattern(mut self, pattern: String) -> Self;
    pub fn with_peer_addr(mut self, addr: std::net::IpAddr) -> Self;
}
```

These are the same methods the server calls when it dispatches a
matched route - `Router` calls `with_params` after `matchit`
returns, `with_route_pattern` so `req.route_pattern()` resolves, and
`with_peer_addr` once it knows the accepted-TCP socket's IP. In
tests you call them yourself to short-circuit the same setup.

```rust
let req = Request::new(hyper_req)
    .with_params(HashMap::from([("id".into(), "42".into())]))
    .with_route_pattern("/users/{id}".into())
    .with_peer_addr("192.168.1.10".parse().unwrap());

assert_eq!(req.param("id").unwrap(), "42");
assert_eq!(req.ip(), Some("192.168.1.10".parse().unwrap()));
```

## Things to know

A short list of footguns that catch first-time authors:

- **`Incoming` is server-side only.** You cannot build one in your test.
  A hyper connection (`TestClient`'s in-memory one, the TCP loopback,
  or in-process service capture) is the only path - there is no "build
  a `Request` from a `Vec<u8>` body" constructor.
- **Don't share state between tests.** Each `#[tokio::test]` gets its
  own runtime; cross-test pollution usually means you're sharing a
  global (`once_cell`, `lazy_static`, env var). For DB state see
  `TestDatabase` in [Testing](testing.md).
- **Cookies need a client that keeps them.** `TestClient` carries them
  from one request to the next. A hand-written harness has no cookie
  jar - thread `Set-Cookie` from one response into `Cookie` on the
  next. See `framework/tests/auth/http_middleware.rs` for the pattern.
- **The post-response termination spawn is non-blocking.** If you
  want to assert on side effects that run via `Terminable`, poll
  for them - the response returns to the client before the hook runs.

## Where each piece lives

| Piece | File |
|---|---|
| `handle_request`, `handle_request_with_peer` | `framework/src/server.rs` |
| `Request::new`, `with_params`, `with_route_pattern`, `with_peer_addr` | `framework/src/http/request.rs` |
| `MiddlewareRegistry::new`, `append`, `prepend` | `framework/src/middleware/registry.rs` |
| `TestClient`, `TestRequest`, `ActingUser` (in-memory connection, cookies, reloads, default headers, acting as a user) | `framework/src/testing/client.rs` |
| Loopback test harness (for a test that needs the socket) | `framework/tests/cors/middleware.rs` |
| `TestResponse` (fluent assertions over the triple above) | `framework/src/testing/response.rs` |
| `ErrorReport` (what went wrong, kept in process) | `framework/src/error/report.rs` |
| `AssertableInertia`, `ReloadRequest` (fluent Inertia page-object assertions) | `framework/src/testing/inertia.rs` |
| In-process `Request` capture harness | `framework/tests/http/request_accessors.rs` |
| Panic-boundary test pattern | `framework/tests/middleware/panic_safety.rs` |
| Auth + middleware end-to-end pattern | `framework/tests/auth_flows/email_verified_middleware.rs` |

## Page budgets

`TestClient::audit_page` follows a document and its assets through the same
request path. It returns every failed rule with measured and allowed values.
See [Page Budget](page-budget.md) for a runnable test and the default limits.
The React, Vue, Svelte and Live scaffolds include `tests/page_budget.rs`; the dogfood
application runs the same audit in `app/tests/page_budget.rs`.

## Next

- [Testing](testing.md) - `#[suprnova_test]`, `TestDatabase`, the
  `describe!`/`test!`/`expect!` macros, and the unit-level surface
- [Error Model](error-model.md) - the JSON shape every error response
  uses, the 5xx sanitisation rule, and what `request_id` means in a
  test body
- [Middleware](middleware.md) - writing the middleware you test here,
  and the global-vs-route lifecycle
- [Routing](routing.md) - the `Router` you mount in both production
  and tests, route params, route names, signed URLs
- [Authentication](authentication.md) - the `Auth` facade,
  `Authenticatable`, guards, and how `Auth::set_user` interacts with
  the request scope `handle_request` installs


---

<!-- /docs/database-testing -->

# Database Tests

The DB-specific companion to [Testing](testing.md). Where that chapter
covers the test harness - `#[suprnova_test]`, `describe!` / `test!`,
`expect!`, and the in-process fakes - this one covers what changes
when your test needs a database: how `TestDatabase` builds one for
you, how isolation actually works, where factories and seeders plug
in, and when an in-memory SQLite is and isn't enough.

## The two constructors

Every database test starts by building a `TestDatabase`. Two
constructors build an in-memory SQLite database, with two intents.
Three more run the test on the database `DATABASE_URL` names; see
[Tests on the configured database](#tests-on-the-configured-database).

### `TestDatabase::fresh::<Migrator>()`

Builds an in-memory SQLite database, loads your SQLite schema dump
(`database/schema/sqlite-schema.sql`) when you have one, runs your
migrator end-to-end,
and registers the connection in the test container so any code
calling `DB::connection()` or `App::resolve::<DbConnection>()`
resolves to it. This is the right default for everything that touches
real schema.

```rust
use suprnova::testing::TestDatabase;
use crate::migrations::Migrator;

#[tokio::test]
async fn user_lifecycle_end_to_end() {
    let db = TestDatabase::fresh::<Migrator>().await.unwrap();

    let alice = User::create(attrs! {
        name: "Alice", email: "alice@example.com",
    })
    .await
    .unwrap();

    assert!(alice.id > 0);
    // Query directly when you want to bypass the model surface:
    let row = users::Entity::find_by_id(alice.id)
        .one(db.conn())
        .await
        .unwrap();
    assert!(row.is_some());
}
```

`Migrator` is your application's `MigratorTrait` implementation -
the same type the production `suprnova migrate` command runs. By
threading the real migrator through the test schema you make schema
drift impossible: a column the migrator forgot to add cannot be
silently present in the test DB.

The `test_database!()` macro is sugar for the common case (`crate::migrations::Migrator`):

```rust
use suprnova::test_database;

#[tokio::test]
async fn shortcut() {
    let db = test_database!();          // == TestDatabase::fresh::<crate::migrations::Migrator>()
    // ...
}

// Or with a custom migrator path:
let db = test_database!(my_crate::CustomMigrator);
```

### `TestDatabase::sqlite_memory()`

Same container and registry wiring, but **does not run any
migrator**. Use this when the test wants precise column-shape
control - typically cast round-trips, query-builder SQL surface
tests, or driver-level edge cases where a full migrator is overkill
or noise:

```rust
let db = TestDatabase::sqlite_memory().await.unwrap();
db.execute_unprepared(
    "CREATE TABLE casts_t (id INTEGER PRIMARY KEY, payload BLOB)",
)
.await
.unwrap();

// Then write directly and read back with the typed helpers:
let row = db.fetch_one(
    "INSERT INTO casts_t (payload) VALUES (?) RETURNING id, payload",
    vec![sea_orm::Value::Bytes(Some(Box::new(b"hello".to_vec())))],
).await.unwrap();
```

`sqlite_memory()` is the foundation `fresh()` is built on - `fresh`
calls it and then runs your migrator. Anything you can do with
`fresh` you can do here; you just bring your own DDL.

### `execute_unprepared`, `fetch_one`, `fetch_all`

`TestDatabase` re-exports the three SeaORM execution shapes you reach
for most in tests, so test files don't have to pull in
`ConnectionTrait`:

| Method | Use for |
| --- | --- |
| `execute_unprepared(sql)` | DDL or DML with no placeholders. Returns `Result<(), FrameworkError>` |
| `fetch_one(sql, bindings)` | One-row SELECT. Errors if zero rows |
| `fetch_all(sql, bindings)` | All-row SELECT |

The bindings are `Vec<sea_orm::Value>` - the same shape the
production query path uses. The connection's backend (SQLite for
both in-memory constructors) is supplied for you, so a `?` placeholder
is correct there.

## Tests on the configured database

`fresh` gives every test a private in-memory SQLite database. When
your suite must run on the engine you deploy to, three constructors
run the test on the database `DATABASE_URL` names instead. They are
Laravel's three database traits:

| Constructor | Laravel trait | What it does |
| --- | --- | --- |
| `TestDatabase::refresh::<M>()` | `RefreshDatabase` | Migrates the database once per test process, then holds each test in a transaction that it rolls back when the helper drops |
| `TestDatabase::refresh_lazily::<M>()` | `LazilyRefreshDatabase` | Does what `refresh` does on the first query, so a test that never touches the database never migrates it |
| `TestDatabase::migrate::<M>()` | `DatabaseMigrations` | Runs the migrations with no transaction around the test, and rolls them back when the helper drops |

```rust
use suprnova::testing::TestDatabase;
use crate::migrations::Migrator;

// DATABASE_URL=postgres://app:secret@127.0.0.1/app_test cargo test
#[tokio::test]
async fn orders_are_numbered_per_customer() {
    let db = TestDatabase::refresh::<Migrator>().await.unwrap();

    let order = Order::create(attrs! { customer_id: 1 }).await.unwrap();
    assert_eq!(order.number, 1);
    // The row is gone when `db` drops, so the next test starts empty.
}
```

`DATABASE_URL` is required. When it's unset, the three constructors
return an error instead of falling back to the development database
`./database.db`. When it names an in-memory SQLite database, they
return an error that points you to `fresh`, which is the in-memory
helper.

### How `refresh` holds a test

The first `refresh` of a test process for a database and a migrator
migrates that database the way your application's `migrate` command
does: it loads the schema dump into a database that has run no
migration, then runs the pending migrations. The other `refresh` calls
of the process don't migrate again. A test that starts while that
migration runs waits for it, so parallel tests share one migration. A
migration that fails is an error of `refresh` and isn't remembered, so
the next `refresh` tries again.

Then the helper opens a pool of one connection, begins a transaction
on it, and registers it in the test container. Every query of the test
runs in that transaction: through `DB::connection()`, a model, a
factory, a seeder, `db.conn()`, the database session driver, and a
database queue driver. The queue driver takes its connection when it's
built, so build it after the helper. The `jobs`, `failed_jobs`, and
`sessions` rows these drivers write roll back with the test.

A `DB::transaction` inside the test is a savepoint of the test
transaction. It commits or rolls back its own work, and its
after-commit callbacks, `Job::after_commit()` pushes included, run
when it commits. When the helper drops, its pool closes and the
database discards the transaction, so a row one test writes is gone
for the next.

Keep these limits in mind:

- The pool holds one connection, as under `fresh`. Code that holds a
  transaction of its own (`DB::begin_transaction`) and runs a query
  outside it waits for the connection until the acquire timeout.
- A statement that ends the transaction itself defeats the rollback:
  DDL on MySQL commits implicitly, and so does a raw `COMMIT`. Create
  tables in migrations, not in the test body.
- Test processes that share a Postgres or MySQL database don't see
  each other's rows, but two tests that insert the same unique key
  wait for each other. SQLite allows one writer, so tests that share a
  SQLite file wait for each other's writes, up to the busy timeout.
  Give parallel test processes their own file.
- A transaction that asks for an isolation level, as the render cache
  asks for `REPEATABLE READ`, runs at the level of the test
  transaction, since a savepoint can't change it.

### `refresh_lazily`

`refresh_lazily` registers its connection at once and does the work of
`refresh` on the first query, the first transaction, or the first
seeder: it begins the transaction, migrates, and then runs the query.

A migration that fails on that first query can't fail the query from
inside the pool. The query runs on the database as it is, which usually
fails on a missing table, and dropping the helper fails the test with
the migration's error.

### `migrate`

`migrate` runs your pending migrations on the connection it registers,
each through its `up`. There's no transaction around the test, so
another connection sees its rows. Use it for a test whose code must see
committed rows from a second connection.

When the helper drops, it rolls back the migrations it ran and no
others, and drops the migration table when it created it, so the
database holds no table the helper created. The next `refresh` of the
process migrates again.

`migrate` never loads a schema dump, even into an empty database: a
table that a dump creates has no `down` to remove it. A migrator whose
migrations you pruned into a dump can't run them, so `migrate` returns
an error that names the dump. Test that migrator with `refresh`, which
loads the dump.

When a migration fails, `migrate` rolls back the migrations that ran
before it and returns the error. When the rollback on drop fails, the
drop panics, so a test can't pass while it leaves its tables behind.
Two `migrate` tests on one database must not run at once.

### Seed before the body

`seed::<S>()` runs the seeder `S` on the test database and hands the
helper back, so it chains after any constructor. `seed_root()` runs
the root seeder, as a bare `db:seed` does: the seeder registered with
`seed::register_root`, or every registered seeder in order when there
is no root. `seed_root()` returns an error when no seeder is
registered, instead of seeding nothing.

```rust
let db = TestDatabase::refresh::<Migrator>()
    .await
    .unwrap()
    .seed::<UsersSeeder>()
    .await
    .unwrap();

assert_eq!(User::query().count().await.unwrap(), 50);
```

`S` runs whether or not it's registered; the seeders it calls are
found in the registry. Under `refresh`, the seeded rows belong to the
test transaction and are gone for the next test.
[`#[suprnova_test]`](testing.md#suprnova_test---when-you-want-the-sugar)
takes the same choices as keys: `refresh`, `seed`, and `seed = Path`.

### Why Suprnova diverges

- Laravel's `RefreshDatabase` runs `migrate:fresh` once per process,
  which drops every table first. `refresh` runs the pending migrations
  only. Dropping tables isn't safe when several test processes share
  one database, and a migrated database stays valid between runs. To
  start from empty tables, run `migrate:fresh` on the test database
  before the run.
- Laravel's `DatabaseMigrations` also runs `migrate:fresh`, which loads
  the schema dump. `migrate` runs the pending migrations only and never
  loads the dump, so every table it creates has a `down` that removes
  it when the helper drops.
- Laravel's `#[Seed]` seeds once per process, inside `migrate:fresh`,
  and the rows stay committed. `seed` runs in each test, inside its
  transaction, so a seeder that inserts rows doesn't add them again on
  every run of a database that keeps its tables.
- Laravel keeps one in-memory PDO per process, so `RefreshDatabase`
  works with `:memory:`. A Suprnova in-memory database belongs to one
  pool, so `refresh` needs a database that outlives a connection, and
  `fresh` is the in-memory helper.
- Laravel counts the test transaction in `DB::transactionLevel()`.
  `DB::transaction_level()` doesn't, because the test transaction sits
  below the framework's own transactions.

## How isolation actually works

For `fresh` and `sqlite_memory`, the fresh-database-per-test model is
the isolation mechanism. Each call opens a new `sqlite::memory:`
connection, which under SQLite is an entirely separate database
instance - no shared schema, no shared rows, no other test can see
into it. There is no transaction wrapper and no rollback to remember:
the *next* test gets a clean empty DB because it builds its own. The
constructors that run on `DATABASE_URL` isolate tests with a
transaction instead; see
[How `refresh` holds a test](#how-refresh-holds-a-test).

When the `TestDatabase` value drops, three things happen, in this
order:

1. The held `TestContainerGuard` clears the thread-local test
   container, so any subsequent `App::get::<DbConnection>()` no longer
   finds the test connection.
2. If this was the *last* live `TestContainerGuard` in the process,
   the named [`ConnectionRegistry`](database.md#named-connections)
   is wiped. (A refcount over live guards guarantees an inner
   test's drop cannot erase a connection name a concurrent outer
   test still depends on - the standing trap that prompted the
   refcount.)
3. The SQLite connection itself drops, which destroys the in-memory
   database. For `refresh` and `refresh_lazily`, this step closes the
   test's connection and the database discards its transaction; for
   `migrate`, it rolls the migrations back and drops the migration
   table when it created it.

Because state is rebuilt rather than rolled back, the isolation is
stronger than `BEGIN`/`ROLLBACK` wrapping: there is no committed
state to mistakenly survive, no nested transaction quirks, no
sequence-counter drift between tests. The cost is that you pay for
running the migrator once per test (negligible for SQLite with most
schemas; if it becomes a real cost, `refresh` migrates a file or
server database once per process - see
[Tests on the configured database](#tests-on-the-configured-database)).

## Why the pool is pinned to one connection

Both constructors build the database with `max_connections(1)` and
`min_connections(1)`. This is load-bearing for `sqlite::memory:`,
not a generic policy.

`sqlite::memory:` is a per-connection database - each *new*
connection in the pool would be a separate, empty SQLite instance.
A pool of size 2 would mean half your queries see the migrated
database and half see an empty one. Pinning the pool to one
connection makes every query in the test land on the same in-memory
database that the migrator ran against.

The consequence: a test that exercises true connection concurrency
(two transactions racing, replica routing, a queue worker hitting
the DB while a request handler does) needs a real database. See
"When SQLite in-memory isn't enough" below.

## Factories in tests

Factories produce randomized model instances and (optionally) persist
them. The persistence path resolves the bound test connection
automatically - there is no factory-side wiring for tests.

```rust
use crate::factories::UserFactory;

#[tokio::test]
async fn factory_round_trip() {
    let _db = TestDatabase::fresh::<Migrator>().await.unwrap();

    // In-memory only: fastest, no DB round trip.
    let alice = UserFactory::new()
        .with(|u| u.email = "alice@example.com".into())
        .make();
    assert_eq!(alice.email, "alice@example.com");

    // Persist one + return the post-insert model (id assigned).
    let bob = UserFactory::new().create().await.unwrap();
    assert!(bob.id > 0);

    // Bulk: persist 50 in sequence.
    let many = UserFactory::times(50).create_many().await.unwrap();
    assert_eq!(many.len(), 50);
}
```

Two patterns worth knowing:

**Factory inserts fire model events.** For a `#[suprnova::model]`
struct, `create()` / `create_many()` take the same insert as
`Model::create`, which dispatches `Creating` / `Saving` / `Created` /
`Saved`. A test that asserts "the `Created` observer fired" can build its
fixture with a factory. To build a fixture that no observer sees, use
`create_quietly()` / `create_many_quietly()`.

**`create_many` does not transact.** Inserts are sequential. If a
later row fails the prior rows are not rolled back. Wrap the call
in your own `DB::transaction` if a test requires atomicity:

```rust
DB::transaction(|tx| async move {
    UserFactory::times(50).create_many().await?;
    PostFactory::times(200).create_many().await?;
    Ok::<_, FrameworkError>(())
}).await.unwrap();
```

See [Eloquent → Factories](eloquent-factories.md) for the full
factory surface (states, sequences, `with`-relations, `count`,
`times`, `make_one` / `create_one`).

## Seeders in tests

The shortest form is `seed::<S>()` on the test database, which runs
`S` before the test body; see [Seed before the body](#seed-before-the-body).
Seeders are also functions you've registered with the framework's
seeder registry under a stable name. Two patterns for driving them
from tests by name, one for each axis of intent.

### Run a single seeder by name

```rust
use suprnova::seed;
use my_app::seeders::UsersSeeder;

#[tokio::test]
async fn users_seeder_populates_fixtures() {
    let _db = TestDatabase::fresh::<Migrator>().await.unwrap();

    seed::register::<UsersSeeder>();
    seed::run_one("UsersSeeder").await.unwrap();

    let count = User::query().count().await.unwrap();
    assert!(count > 0);
}
```

### Run the full bootstrap seeder set

```rust
use serial_test::serial;
use suprnova::seed;

#[tokio::test]
#[serial]
async fn full_seed_lands_expected_row_counts() {
    seed::clear();                              // start from a known-empty registry
    let _db = TestDatabase::fresh::<Migrator>().await.unwrap();

    seed::register::<my_app::seeders::UsersSeeder>();
    seed::register::<my_app::seeders::PostsSeeder>();
    seed::run_all().await.unwrap();

    let users = User::query().count().await.unwrap();
    let posts = Post::query().count().await.unwrap();
    assert_eq!(users, 50);
    assert_eq!(posts, 200);

    seed::clear();
}
```

Two important contract details:

**The seeder registry is process-global.** `seed::register::<S>()`
inserts into a `RwLock<IndexMap>` keyed by `S::name()`. A test that
mutates the registry should call `seed::clear()` at entry, register
the seeders it needs, run, and `clear()` again at exit - and the
test itself should be `#[serial_test::serial]` so two parallel tests
don't fight over the registry. `seed::clear()` is compiled with the
`testing` feature, which is a default feature. `#[suprnova_test]` does **not** auto-
register seeders; only the explicit `seed::register::<>()` call in
your own `bootstrap.rs` or in the test body puts them in the
registry.

**Model-driven seeds vs factory-driven seeds.** A seeder that loops
`User::create(...)` in a `for` fires `Creating` / `Saving` /
`Created` / `Saved` per row and invokes every registered observer.
For bulk seeding where that fanout is unwanted, wrap the loop in
`seed::without_events`:

```rust
seed::without_events(async {
    for i in 0..50 {
        User::create(attrs! { name: format!("user{i}"), email: format!("user{i}@example.com") }).await?;
    }
    Ok::<_, FrameworkError>(())
}).await?;
```

The mute is **task-scoped** - only the work performed inside the
future is silenced; concurrent request handlers and queue workers
continue to fire events normally. Factories fire the same events, so
`without_events` mutes them as well; `create_quietly()` and
`create_many_quietly()` are the shorter form for a factory.

See [Seeding](seeding.md) for the seeder authoring surface and
[Eloquent → Factories](eloquent-factories.md) for the relationship
between the two.

## Parallel-safe database tests

`cargo test` runs tests in parallel by thread. The default
`#[suprnova_test]` expansion (which is `#[tokio::test]`, i.e. a
`current_thread` runtime per test) interacts safely with this for
two reasons:

- **Each test gets its own `sqlite::memory:` connection.** Tests do
  not share DB state. Under `refresh`, each test gets its own
  connection and transaction on the shared database instead.
- **The bound connection lives in the thread-local
  `TestContainer`.** Tests do not share container bindings.

What you don't have to think about: `DB::connection()`, `App::resolve`,
factory persistence, model trait writes - these all transparently
land on the right per-test database. `DB::listen` callbacks and the
query log belong to the test container too, so a test that counts
queries counts only its own.

What you *do* need to think about:

| Surface | Why it's process-global | Mitigation |
| --- | --- | --- |
| `ConnectionRegistry` (`DB::register_named`, `__read_replica__`) | Single `RwLock<HashMap>` shared by the process | `#[serial_test::serial]` for any test that registers or reads named connections |
| The seeder registry | Single `RwLock<IndexMap>` | `#[serial_test::serial]` + `seed::clear()` at entry and exit |
| The Eloquent observer / scope registries | Keyed by `TypeId::<M>()` | Each test should use a unique model struct, or be `#[serial]` and call the registry's `clear()` helper |

The connection-registry refcount makes this safer than it sounds: a
test holding a `TestContainerGuard` keeps the registry alive even
when a *sibling* test's guard drops. You still want `#[serial]` for
the tests that actually mutate the registry, so their reads and
writes can't interleave.

### Multi-thread runtime caveat

`#[suprnova_test]` expands to `#[tokio::test]` with the default
`current_thread` runtime, so the thread-local container path always
works. If you explicitly opt a test into the multi-thread runtime:

```rust
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn parallel_io_test() {
    let _db = TestDatabase::fresh::<Migrator>().await.unwrap();
    // PROBLEM: tasks spawned with `tokio::spawn` may run on a
    // worker thread different from the one that built the
    // TestDatabase. They will not see the thread-local
    // TestContainer binding, and DB::connection() will return the
    // global (production) container's value or error.
}
```

Two fixes, depending on what the test does:

1. **Direct connection access** - `db.conn()` still returns the
   right `&DatabaseConnection` regardless of which worker thread
   reads it. If the test only ever talks to the DB through the
   `db` handle (not through `DB::connection()`), the multi-thread
   runtime is fine.

2. **`TestContainer::scope`** - wrap the test body in
   `TestContainer::scope(async { ... }).await` and bind your fakes
   (and the DB connection) inside it. The scope binds the container
   to the task-local layer, which is preserved across awaits even
   when the runtime hops the future between worker threads. For
   spawned sub-tasks, use `TestContainer::spawn` (not bare
   `tokio::spawn`) so the task-local container is captured and
   reinstalled inside the spawned future.

See [Service Container → Lookup order](container.md) for the full
task-local / thread-local / global layering.

## SQLite in-memory vs a real Postgres / MySQL / MariaDB

`fresh` and `sqlite_memory` are SQLite-only: the driver is
`sqlite::memory:`. For the overwhelming majority of test surface - model CRUD, query builder shape, cast
round-trips, relationship loading, observer firing order, soft-delete
semantics - SQLite in-memory is the right tool: zero setup, zero
network, milliseconds per test, perfect isolation, no external
service to keep alive in CI.

There are four cases where SQLite in-memory isn't enough:

1. **Driver-specific SQL.** A query that uses Postgres `LATERAL`,
   `JSONB` operators, `ON CONFLICT ... WHERE`, MySQL window
   functions, or any other dialect-specific surface won't run on
   SQLite. The model+builder path tries to stay generic, but a
   raw-SQL test asserting Postgres-shaped output needs Postgres.
2. **Concurrency under real connection contention.** SQLite
   in-memory is single-connection (see "Why the pool is pinned to
   one connection"). Tests that race two transactions, exercise
   read-replica routing under load, or measure deadlock retry need
   a multi-connection server.
3. **Vector / NoSQL / temporal surfaces.** Suprnova's MariaDB
   `VECTOR` driver, Qdrant integration, Pinecone integration, and
   similar non-SQL drivers cannot be modelled in SQLite at all.
4. **Production parity smoke tests.** A handful of "does this
   actually work on the real DB we deploy to?" tests, gated to
   CI, are worth keeping even when the unit-test layer is SQLite.

For all four cases, point `DATABASE_URL` at that engine and build the
test database with `refresh`, or with `migrate` when the code under
test must see committed rows from a second connection; see
[Tests on the configured database](#tests-on-the-configured-database).
For a driver-level test that needs no migrator, or a second database
beside the primary, build a `DbConnection` against an
operator-supplied `DATABASE_URL`-style env var, env-gate the test
so it skips when the var is absent, and mark it `#[serial]` so two
of them don't fight over the shared real database. The
`MARIADB_URL` pattern in `framework/tests/vector/mariadb.rs` is the
canonical example:

```rust
use serial_test::serial;
use suprnova::database::{DatabaseConfig, DbConnection};

async fn maybe_real_db(test_name: &str) -> Option<DbConnection> {
    let url = match std::env::var("POSTGRES_TEST_URL") {
        Ok(u) if !u.is_empty() => u,
        _ => {
            eprintln!("[{test_name}] skipping: POSTGRES_TEST_URL not set");
            return None;
        }
    };
    let config = DatabaseConfig::builder().url(&url).build();
    Some(DbConnection::connect(&config).await.expect("real DB connects"))
}

#[tokio::test]
#[serial]
async fn jsonb_operator_works_against_postgres() {
    let Some(conn) = maybe_real_db("jsonb_operator_works_against_postgres").await else {
        return;
    };
    // Drive Postgres-specific SQL directly against `conn`.
}
```

The standing convention: name the env var after the target driver
(`POSTGRES_TEST_URL`, `MYSQL_TEST_URL`, `MARIADB_URL`), print a
skip line so a developer running the suite locally sees the test
was skipped (not silently passed), and document the env var in the
test module's leading doc-comment so CI can wire it up.

`MARIADB_URL` is also the variable `MariaDbVectorDriver::from_env()` reads
(with `DATABASE_URL` as its fallback), and `QDRANT_URL` is the one
`QdrantVectorDriver::from_env()` reads. A test that builds either driver
with `from_env` needs no extra wiring. See [Vector](vector.md).

## A worked example

The full app dogfood pattern, combining everything in this chapter:

```rust
use app::migrations::Migrator;
use app::models::posts::Post;
use app::models::users::User;
use serial_test::serial;
use suprnova::testing::TestDatabase;
use suprnova::{Model, attrs, seed, FrameworkError};

#[tokio::test]
#[serial]
async fn users_and_posts_full_seed_round_trip() {
    // 1. Empty seeder registry.
    seed::clear();

    // 2. Fresh in-memory DB with the app's migrator.
    let db = TestDatabase::fresh::<Migrator>().await.unwrap();

    // 3. Register the seeders the test cares about.
    seed::register::<app::seeders::UsersSeeder>();
    seed::register::<app::seeders::PostsSeeder>();

    // 4. Drive the seed inside without_events so observer fanout
    //    doesn't try to enqueue jobs (no queue is running here).
    seed::without_events(async {
        seed::run_all().await
    }).await.unwrap();

    // 5. Read back via the model surface and the raw connection.
    let user_count = User::query().count().await.unwrap();
    assert_eq!(user_count, 50);

    let raw_post_count = db.fetch_one(
        "SELECT COUNT(*) AS n FROM posts",
        vec![],
    ).await.unwrap();
    let n: i64 = raw_post_count.try_get("", "n").unwrap();
    assert_eq!(n, 200);

    // 6. Exercise the cancellable observer path on a fresh model.
    let alice = User::create(attrs! {
        name: "Alice", email: "alice@example.com",
    }).await.unwrap();
    assert!(alice.id > 0);

    seed::clear();
}
```

Step 5 is the part that proves the wiring: the model query and the
raw `fetch_one` are both reading the same in-memory database - the
model surface because the `DB::connection()` lookup found the
`TestContainer` binding, the raw `fetch_one` because `db.conn()`
returns that same connection directly.

## Cross-references

- [Testing](testing.md) - the test harness, `expect!`, `describe!`,
  `test!`, fakes.
- [Database](database.md#testing) - the surface-level testing
  section that introduces `TestDatabase`.
- [Migrations](migrations.md) - the migrations that `refresh` and
  `migrate` run, and the schema dumps that `refresh` loads.
- [Eloquent → Factories](eloquent-factories.md) - factory definition
  syntax, states, sequences, relations.
- [Seeding](seeding.md) - seeder authoring, ordering, idempotency.
- [Service Container](container.md) - task-local vs thread-local
  vs global lookup, which decides what `DB::connection()` resolves
  to inside a test.
- [Mocking & Fakes](mocking.md) - `Storage::fake`, `Mail::fake`,
  `Queue::fake`, `Notify::fake`, and the trait-bind pattern
  for swapping in fake HTTP clients and other external surfaces.
- [HTTP Tests](http-tests.md) - driving handlers through the
  routing stack with a `TestDatabase` bound.


---

<!-- /docs/mocking -->

# Mocking and Fakes

Every external surface in Suprnova ships with an in-process fake that
captures what your code would have sent - mail, notifications, queued
jobs, dispatched commands, fired events, written files, outbound HTTP
calls - and a matching set of assertions you run after the fact. The
shape is always: install the fake, run the code under test, assert
what was captured. This chapter is the consolidated overview; each
subsystem chapter ([Mail](mail.md), [Notifications](notifications.md),
[Queues](queues.md), [Command Bus](bus.md), [Events](events.md),
[File Storage](filesystem.md), [HTTP Client](http-client.md)) covers
its fake in depth.

## The seven fakes

| Surface         | Entry point                                       | Assertion style                       | Parallel safety                                    | Chapter                              |
|-----------------|---------------------------------------------------|---------------------------------------|----------------------------------------------------|--------------------------------------|
| Mail            | `Mail::fake()` → `MailFake` guard                 | methods on the guard                  | needs `#[serial]` - global transport, no serializer | [mail.md](mail.md)                   |
| Notifications   | `Notify::fake()` → `NotifyFakeGuard`              | typed guard methods and free functions in `notifications::testing` | guard holds process-wide serializer            | [notifications.md](notifications.md) |
| Queue           | `Queue::fake()` → `QueueFakeGuard`                | free functions in `queue::testing`    | guard holds process-wide serializer                | [queues.md](queues.md)               |
| Bus             | `Bus::fake()` → `BusFakeGuard`                    | free functions in `bus::testing`      | guard holds process-wide serializer                | [bus.md](bus.md)                     |
| Events          | `EventFacade::fake()` → `EventFakeGuard`          | free functions in `events`            | guard holds process-wide serializer                | [events.md](events.md)               |
| Storage         | `Storage::fake()` → `StorageFakeGuard`            | `DiskAssertExt` methods on a disk     | guard holds process-wide serializer                | [filesystem.md](filesystem.md)       |
| HTTP client     | `Http::fake(\|\| async { … }).await`              | `assert_sent` / `assert_not_sent`     | task-local - truly concurrent across tests         | [http-client.md](http-client.md)     |

A few invariants hold across all seven:

- **The fake records, the real backend doesn't run.** Mail isn't sent,
  jobs aren't pushed to the driver, handlers don't run, events skip
  their listeners, HTTP doesn't hit the network, file writes go into
  a memory disk. The captured side carries enough information to
  assert what would have happened.
- **The guard is RAII.** Dropping the guard restores whatever was in
  place before (the previous mail transport, a clean storage registry,
  no recording for events, etc.). Tests don't need a teardown step.
- **The fake doesn't lie about errors.** If your code calls
  `Bus::dispatch` for an unregistered command, the fake still returns
  `Err(_)` - only successful dispatches are captured.

## The shapes, and why they differ

Three patterns recur. Knowing which pattern a fake uses tells you
whether to import a free function, call a method on the guard, or
wrap the test body in a closure.

### Guard-with-methods (Mail)

`Mail::fake()` returns a `MailFake` whose own methods are the
assertions. This is convenient when the asserter is *the* fake - you
already have it bound to a local - but it's the only fake in this
shape:

```rust,ignore
let fake = Mail::fake();
Mail::to("alice@example.org")
    .send(WelcomeEmail { name: "Alice".into() })
    .await?;
fake.assert_sent_count(1);
fake.assert_sent(|m| m.has_to("alice@example.org"));
```

### Guard plus free functions (Notify, Queue, Bus, Events)

You keep the fake installed with its guard and import assertions from the
`testing` submodule. For notifications, you also use typed methods on the
guard. Import what you need:

```rust,ignore
use suprnova::Queue;
use suprnova::queue::testing::{assert_pushed, pushed};

let _guard = Queue::fake();
schedule_welcome_email(user_id).await?;
assert_pushed::<WelcomeJob>(|j| j.user_id == user_id);
```

This is the most common shape because it generalises cleanly across
types - every assertion is generic over `J: Job` / `C: Command` /
`E: Event` instead of being baked into a guard type. The trade-off
is one extra import.

Every captured push carries the envelope id the fake assigned, so a test
can join what it captured to what a listener saw:

```rust,ignore
use suprnova::events::{EventFacade, dispatched};
use suprnova::queue::events::JobQueued;
use suprnova::queue::testing::pushed_with_id;

let _queue = Queue::fake();
let _events = EventFacade::fake();

Queue::push(SendInvoice { order_id: 7 }).await?;

let (job, id) = pushed_with_id::<SendInvoice>().remove(0);
assert_eq!(job.order_id, 7);
assert_eq!(dispatched::<JobQueued>(|_| true)[0].id, id);
```

Under the fake there is no driver, so the fake itself emits the
`JobQueueing` / `JobQueued` pair a real push would - with the id it
recorded. `bulk` and `push_unique` emit neither event on the real path,
so the fake doesn't emit them either.

### Scope-with-closure (HTTP)

`Http::fake` is the odd one out. Outbound HTTP runs on whatever Tokio
task happens to be alive, so the fake state lives in a
`tokio::task_local!`. You can't install it once and let it ride -
you have to wrap the body that calls the client:

```rust,ignore
use suprnova::{Http, fake_response, assert_sent};

Http::fake(|| async {
    fake_response("POST", "/api/users", 201, serde_json::json!({"id": 1}));

    let resp = Http::post("https://example.com/api/users")
        .json(&serde_json::json!({"name": "Ada"}))
        .send()
        .await?;

    assert_eq!(resp.status(), 201);
    assert_sent(|r| r.method == "POST" && r.url.contains("/api/users"));
})
.await;
```

The payoff: every other fake holds a process-wide serializer so
parallel tests run one-at-a-time, but `Http::fake` is truly
concurrent - every test gets its own task-local recorder and they
never collide.

### Storage's extension trait

`Storage::fake()` returns a guard *and* an in-memory disk named
`"default"`, but its assertions hang off the disk itself through the
`DiskAssertExt` extension trait:

```rust,ignore
use suprnova::{Storage, DiskExt};
use suprnova::filesystem::testing::DiskAssertExt;

let _guard = Storage::fake();
let disk = Storage::disk("default")?;

disk.put("invoices/42.pdf", b"...").await?;
disk.assert_exists("invoices/42.pdf").await;
disk.assert_count("invoices/", 1, false).await;
```

The extension trait is gated on `#[cfg(any(test, feature = "testing"))]`
so production code can't accidentally call `disk.assert_exists(…)`.

## Parallel safety, in one paragraph

Six of the seven fakes guard a process-global static. Each one's
guard, on construction, takes a dedicated process-wide
`std::sync::Mutex` and holds it until drop. The effect is that any
two `#[tokio::test]`s that install the same fake run serialized
under one process - no need for `#[serial]` from the
[serial_test](https://crates.io/crates/serial_test) crate. **Mail
is the exception**: the `MailFake` guard swaps the global
`TRANSPORT` without taking a serializer, so concurrent `Mail::fake()`
tests *would* clobber each other. Mark them `#[serial]`. **`Http::fake`
is also an exception**: it's task-local, not process-global, so tests
genuinely run in parallel and never need `#[serial]`.

If you interleave real-dispatch with fake-dispatch for the same
surface inside one test binary, the real path doesn't take the
serializer, so it can race a parallel faked test. Mark the
real-dispatch tests `#[serial]` in that case - the per-chapter docs
call this out where it applies (see [Command Bus](bus.md) for the
canonical example).

## Mail - `Mail::fake()`

```rust,ignore
use serial_test::serial;
use suprnova::mail::{Mail, Address};

#[tokio::test]
#[serial]
async fn welcome_email_is_sent() {
    let fake = Mail::fake();

    register_user("alice@example.org").await.unwrap();

    fake.assert_sent_count(1);
    fake.assert_sent(|m| m.has_to("alice@example.org"));
    fake.assert_sent(|m| m.subject.starts_with("Welcome"));
    fake.assert_not_sent_to("eve@example.org");
}
```

| Assertion                                  | Asserts…                                            |
|--------------------------------------------|-----------------------------------------------------|
| `fake.assert_sent(\|m\| pred)`             | at least one captured message matches               |
| `fake.assert_sent_to("…")`                 | at least one captured message was routed to email   |
| `fake.assert_not_sent(\|m\| pred)`         | no captured message matches                         |
| `fake.assert_not_sent_to("…")`             | no captured message went to email                   |
| `fake.assert_sent_count(n)`                | exactly `n` captured messages                       |
| `fake.assert_nothing_sent()`               | nothing was captured                                |
| `fake.assert_queued("MailableName")`       | at least one queued mailable of this name           |
| `fake.assert_queued_with(name, \|q\| …)`   | a queued mailable matches the predicate             |
| `fake.assert_queued_to("…")`               | a queued mailable was routed to email               |
| `fake.assert_not_queued("MailableName")`   | no queued mailable of this name                     |
| `fake.assert_queued_mailable::<M>(\|m\| pred)` | a queued mailable of type `M` matches         |
| `fake.assert_not_queued_mailable::<M>(\|m\| pred)` | no queued mailable of type `M` matches    |
| `fake.assert_queued_count(n)`              | exactly `n` queued mailables                        |
| `fake.queued_on("…")`                      | queued mailables routed to a queue                  |
| `fake.assert_queued_on(name, "…")`         | a queued mailable of this name routed to a queue    |
| `fake.queued_on_connection("…")`           | queued mailables routed to a connection             |
| `fake.assert_queued_on_connection(name, "…")` | a queued mailable of this name routed to a connection |
| `fake.assert_nothing_queued()`             | nothing was queued                                  |
| `fake.assert_outgoing_count(n)`            | sent + queued totals `n`                            |
| `fake.assert_nothing_outgoing()`           | nothing was sent and nothing was queued             |

Three answers return a `bool` instead of panicking, as Laravel's
`MailFake::hasSent` and `hasQueued` do:

| Answer                                     | True when…                                          |
|--------------------------------------------|-----------------------------------------------------|
| `fake.has_sent("MailableName")`            | a mailable of this name was sent; queued ones don't count |
| `fake.has_sent_mailable::<M>()`            | a mailable of type `M` was sent                     |
| `fake.has_queued("MailableName")`          | a mailable of this name was queued                  |

A sent message checks its attachments by content too:
`m.has_equivalent_attachment(&attachment)` compares the name, bytes, and
content type, and `m.has_attached_data(bytes, name, content_type)` checks
raw data. `m.has_attachment(name)` matches the name only.

`fake.captured()`, `fake.queued()`, `fake.sent(pred)`, `fake.sent_to(…)`,
`fake.queued_named(…)`, and `fake.queued_to(…)` return the matching
data so you can build custom assertions. See [Mail](mail.md) for the
full surface, including how `Mail::queue` is mirrored into the fake
even when `Queue::fake` isn't installed.

`queued_on_connection` / `assert_queued_on_connection` read
`QueuedSnapshot::connection` - the `.on_connection(...)` override, if
any - the same field `Queue::fake`'s `assert_pushed_on_connection` reads
on the plain-job path below, so the two fakes stay symmetric.

You read queued mailables back as their own type, as Laravel's
`MailFake::queued` does with a class and a closure.
`fake.queued_of::<M>()` rebuilds every queued mailable of type `M` from
its payload, in queue order, and `fake.queued_where::<M>(|m| pred)`
returns the ones the filter accepts:

```rust,ignore
let fake = Mail::fake();
Mail::queue(Welcome { name: "Ada".into() }).await?;

let queued: Vec<Welcome> = fake.queued_of::<Welcome>();
assert_eq!(queued[0].name, "Ada");
fake.assert_queued_mailable::<Welcome>(|m| m.name == "Ada");
fake.assert_not_queued_mailable::<Welcome>(|m| m.name == "Eve");
```

A payload that doesn't rebuild as `M` fails the call with a message that
names the mailable and the decode error. It isn't left out, so
`assert_not_queued_mailable` never passes over a mailable it can't read.
`fake.try_queued_of::<M>()` and `fake.try_queued_where::<M>(...)` return
that error instead of panicking. `fake.queued()` still returns the
`QueuedSnapshot` list.

### Why Suprnova diverges

Laravel's `assertQueued` and `assertNotQueued` take a class name, a
closure, or both. Rust has no overloading, and `assert_queued(name)` and
`assert_not_queued(name)` keep the signature they shipped with. The
typed forms are `assert_queued_mailable::<M>` and
`assert_not_queued_mailable::<M>`, as `has_sent_mailable::<M>` sits
beside `has_sent`.

## Notifications - `Notify::fake()`

```rust,ignore
use suprnova::notifications::{Notify, testing};

#[tokio::test]
async fn order_shipped_notifies_customer() {
    let _guard = Notify::fake();

    ship_order(order_id).await.unwrap();

    testing::assert_sent_to("alice@example.org", "OrderShipped");
    testing::assert_sent_to_on("alice@example.org", "mail", "OrderShipped");
    testing::assert_sent_times("OrderShipped", 1);
}
```

| Assertion                                            | Asserts…                                          |
|------------------------------------------------------|---------------------------------------------------|
| `assert_sent(\|r\| pred)`                            | at least one dispatched notification matches      |
| `assert_sent_to(route, "Name")`                      | named notification went to this per-channel route |
| `assert_sent_to_on(route, channel, "Name")`          | dispatched on this channel to this route          |
| `assert_sent_named("Name")`                          | named notification dispatched on any channel      |
| `assert_sent_times("Name", n)`                       | exactly `n` of the named notification             |
| `assert_nothing_sent()`                              | no notifications dispatched                       |
| `assert_count(n)`                                    | exactly `n` total across all types and channels   |
| `assert_nothing_sent_to(route)`                      | nothing dispatched to this route                  |

`testing::recorded()` returns every `FakeRecord` (notification name,
channel, route, JSON data) for finer-grained assertions. Notification
recipients are keyed on the per-channel `route_for` value, so
`assert_sent_to` takes the route string (an email address for `"mail"`,
the id-as-string for `"database"`, …) - see [Notifications](notifications.md)
for the routing model.

You inspect typed notifications through the guard without importing an
assertion function:

```rust,ignore
let fake = Notify::fake();
ship_order(order_id).await?;
let sent = fake.sent::<OrderShipped>("alice@example.org", |n| n.order_id == order_id)?;
fake.assert_sent_to::<OrderShipped>("alice@example.org", |n| n.order_id == order_id);
fake.assert_not_sent_to::<OrderShipped>("bob@example.org");
```

You filter the full notification by concrete Rust type and route. You receive
one match per dispatch, even when multiple channels use that route. You keep
the untyped `testing::assert_sent_to(route, "Name")` and its siblings for
existing tests.

## Queue - `Queue::fake()`

```rust,ignore
use suprnova::Queue;
use suprnova::queue::testing::{assert_pushed, assert_pushed_later, pushed};

#[tokio::test]
async fn order_placed_enqueues_charge() {
    let _guard = Queue::fake();

    place_order(42).await.unwrap();

    assert_pushed::<ChargeCustomerJob>(|j| j.order_id == 42);
}
```

| Assertion                                      | Asserts…                                                       |
|------------------------------------------------|----------------------------------------------------------------|
| `assert_pushed::<J>(\|j\| pred)`               | at least one push of `J` matches                               |
| `assert_pushed_later::<J>(\|j, at\| pred)`     | a push of `J` was scheduled at `at` (delayed dispatch)         |
| `assert_pushed_on_queue::<J>(queue, \|j\| pred)` | one push has both the queue and matching job data |
| `assert_not_pushed::<J>(\|j\| pred)` | no push of `J` matches |
| `assert_pushed_on_connection::<J>(connection)` | a push of `J` declared `connection` via `EnvelopeOverrides`    |
| `assert_batched(\|batch\| pred)`               | at least one recorded batch matches                            |
| `assert_batch_count(n)`                        | exactly `n` batches were recorded                              |
| `assert_nothing_batched()`                     | no batch was recorded                                          |
| `assert_chained(&["JobA", "JobB"])`            | a recorded chain is made of exactly these `Job::job_name()`s, head first |
| `assert_nothing_chained()`                     | no chain was recorded                                          |
| `assert_pushed_without_chain::<J>(\|j\| pred)`           | a typed push of `J` matches and carries no chain                      |

The data side returns the typed jobs themselves:

- `pushed::<J>() -> Vec<J>` - every captured push of `J`. A payload that
  doesn't decode as `J` fails the call with a message that names the job
  and the decode error, instead of being left out. `try_pushed::<J>()`
  returns that error.
- `reserved::<J>() -> Vec<J>` - every reservation of `J` a worker made
  through `fake.driver()`, one entry per reservation. `try_reserved::<J>()`
  returns the decode error, as `try_pushed` does.
- `pushed_with_available_at::<J>() -> Vec<(J, DateTime<Utc>)>` - same,
  with each job's scheduled timestamp
- `pushed_with_overrides::<J>() -> Vec<(J, EnvelopeOverrides)>` - same,
  with each job's declared per-push overrides
- `batched() -> Vec<FakedBatch>` - every recorded batch, in dispatch order.
  A `FakedBatch` has `id`, `name` and `jobs`, and `jobs_of::<J>()` decodes
  the jobs of one type.
- `chained() -> Vec<FakedChain>` - every recorded chain, in dispatch order.
  A `FakedChain` has `links`, `job_names()` and `link::<J>(index)`, which
  decodes the link at `index`.
- `raw_pushes() -> Vec<RawPush>` - every `Queue::push_raw`, in push order.
  A `RawPush` has the `payload` and `queue` as they were passed, and
  `envelope()` decodes the payload.
- `pushed_raw(|raw| pred) -> Vec<RawPush>` - the raw pushes `pred` accepts.

Every `Queue::push`, `Queue::push_later`, `Queue::later`,
`Queue::push_unique*`, `Queue::batch().dispatch()`,
`Queue::chain().dispatch()`, `Queue::retry_failed` and
`Queue::retry_all_failed` funnel into the same recorder, and none of them
writes to a driver. No driver has to be installed. `Queue::push_raw` is
recorded as well, apart from the typed pushes. A batch, a chain and a
retried job also record as pushes, so `assert_pushed` sees the jobs of a
batch, the head of a chain and every retried job. A chain records only its
head as a push, because the links after it have no envelope until the link
before them completes. See [Queues](queues.md#batches-chains-and-failed-job-retries)
for the details, and for `push_unique` semantics under the fake (it always
records and reports "pushed").

Only `Queue::push_with` and `Queue::later_with` carry an
`EnvelopeOverrides`, so `pushed_with_overrides` records
`EnvelopeOverrides::default()` for every other entry point - a plain
`Queue::push` reads under the fake exactly as "no override was
declared," the same as it would if you asserted `entries[0].1 ==
EnvelopeOverrides::default()`. You use `assert_pushed_on_queue` to match
both a recorded queue and its typed payload. You match the override when
one was supplied, otherwise the job's `Job::queue` declaration.
You use `assert_pushed_on_connection` to check the declared connection
override. You use `pushed_with_overrides` for the rest of the overlay:
`timeout`, `fail_on_timeout`, `max_tries` and `backoff`.

One variant lets some jobs through:

```rust,ignore
// Fake every job EXCEPT these - they reach the real queue.
let _guard = Queue::fake_except(&["ProvisionAccount"]);

// The same, on the guard. A second `except` adds to the list.
let _guard = Queue::fake().except(&["ProvisionAccount"]);
```

An excepted job is pushed exactly as it is without the fake, so install the
driver it should reach first, for example `SyncQueueDriver` to run it inline.
See [Queues](queues.md#letting-some-jobs-through) for how batches, chains and
raw pushes behave under `except`.

To run the recorded jobs, pass `fake.driver()` to a worker. The fake records
each reservation the worker makes, and `Queue::reserved_jobs` answers from
those records instead of reading a driver:

```rust,ignore
use suprnova::queue::testing::reserved;
use suprnova::{Queue, WorkerControls, run_worker_with_controls};

let fake = Queue::fake();
place_order(42).await?;

let controls = WorkerControls { stop_when_empty: true, ..Default::default() };
run_worker_with_controls(fake.driver(), Default::default(), controls, Default::default()).await?;

assert_eq!(reserved::<ChargeCustomerJob>()[0].order_id, 42);
assert_eq!(Queue::reserved_jobs(None).await?.len(), 1);
```

See [Queues](queues.md#run-a-worker-on-the-fake) for what the driver does.

## Bus - `Bus::fake()`

```rust,ignore
use suprnova::Bus;
use suprnova::bus::testing::{
    assert_dispatched, assert_dispatched_times,
    assert_not_dispatched, assert_nothing_dispatched,
};

#[tokio::test]
async fn order_placed_dispatches_charge() {
    let _guard = Bus::fake();

    place_order(42).await.unwrap();

    assert_dispatched::<ChargeCustomer>(|c| c.customer_id == 42);
    assert_dispatched_times::<ChargeCustomer>(|_| true, 1);
    assert_not_dispatched::<RefundCustomer>(|_| true);
}
```

| Assertion                                           | Asserts…                                                      |
|-----------------------------------------------------|---------------------------------------------------------------|
| `assert_dispatched::<C>(\|c\| pred)`                | at least one dispatched command of `C` matches                |
| `assert_not_dispatched::<C>(\|c\| pred)`            | no dispatched command of `C` matches                          |
| `assert_dispatched_times::<C>(\|c\| pred, n)`       | exactly `n` dispatched commands of `C` match                  |
| `assert_nothing_dispatched()`                       | zero commands of any type dispatched under the active fake    |

You inspect captured commands with `dispatched::<C>()`,
`dispatched_sync::<C>()` and `dispatched_after_response::<C>()` in
`bus::testing` or at the crate root. You receive a `Vec<C>` in dispatch
order for that mode alone, which you filter with its iterator.
You receive an empty vector when that type was not dispatched.

You call `Bus::dispatch_sync(command).await` for the separate synchronous
mode. Under the fake, you receive `Dispatched::Captured` from ordinary or
synchronous dispatch. You capture commands without registering a handler.
You still receive an error when command serialization fails.

You call `Bus::dispatch_after_response(command)?` inside your HTTP handler
when the command should run after its response is sent. You register its
handler at boot as you do for ordinary dispatch. You wait for the whole body
and a successful socket flush before its handler starts, including streamed,
empty and HEAD responses. You get a logged handler error after the response
is sent; you cannot change that response. You discard the commands when
writing the response fails. Under the fake, you capture the command at once
and run no handler, so you need no HTTP request to assert its capture.

You use `after_response_connection(io, |io| async move { ... })` if you
embed `server::handle_request` in your own Hyper loop. You pass the wrapped
IO to `TokioIo::new` and build `serve_connection` inside the closure.
You receive an error from real deferred dispatch outside an active request
or without that writer hook. You use `Server` to install it automatically.

`Bus::fake()` and `bus::testing::install_fake()` are the same call and return
the same `BusFakeGuard`. The same holds for `Queue::fake()` and
`queue::testing::install_fake()`.

## Events - `EventFacade::fake()`

```rust,ignore
use suprnova::EventFacade;
use suprnova::events::{
    assert_dispatched, assert_dispatched_once, assert_dispatched_times,
    assert_not_dispatched, assert_nothing_dispatched, dispatched,
    dispatched_count, dispatched_events, has_dispatched,
};

#[tokio::test]
async fn registration_dispatches_welcome_event() {
    let _guard = EventFacade::fake();

    register_user("ada@example.com").await.unwrap();

    assert_dispatched_once::<UserRegistered>();
    assert_dispatched::<UserRegistered>(|e| e.email == "ada@example.com");
}
```

| Assertion                              | Asserts…                                          |
|----------------------------------------|---------------------------------------------------|
| `assert_dispatched::<E>(\|e\| pred)`   | at least one dispatched `E` matches               |
| `assert_dispatched_once::<E>()`        | exactly one `E` was dispatched                    |
| `assert_dispatched_times::<E>(n)`      | exactly `n` of `E` were dispatched                |
| `assert_not_dispatched::<E>(\|e\| ..)` | no matching `E` was dispatched                    |
| `assert_nothing_dispatched()`          | no events of any type dispatched                  |
| `assert_listening::<E, L>()`           | listener `L` is registered for `E`                |
| `has_dispatched::<E>()`                | `bool`: any `E` recorded                          |
| `dispatched::<E>(\|e\| pred)`          | `Vec<E>` clones of matching events                |
| `dispatched_count::<E>(\|e\| pred)`    | count of matching events                          |
| `dispatched_events()`                  | `HashMap<&'static str, usize>` of all dispatches  |

Two variants narrow what's faked:

```rust,ignore
// Only fake these - everything else dispatches normally.
let _guard = EventFacade::fake_only(&["UserRegistered", "UserDeleted"]);

// Fake every event EXCEPT these.
let _guard = EventFacade::fake_except(&["TelemetryEvent"]);
```

And one variant suppresses without recording:

```rust,ignore
EventFacade::muted(async {
    // No listeners fire, no events recorded.
    run_bulk_import().await;
})
.await;
```

`muted` does NOT acquire the serializer, so muted scopes can run in
parallel. See [Events](events.md) for the full machinery, including
`assert_listening` (which observes listener registrations that happen
*inside* the fake's scope only).

## Storage - `Storage::fake()`

```rust,ignore
use suprnova::{Storage, DiskExt};
use suprnova::filesystem::testing::DiskAssertExt;

#[tokio::test]
async fn invoice_upload_persists() {
    let _guard = Storage::fake();
    let disk = Storage::disk("default").unwrap();

    upload_invoice(b"%PDF-1.7 …").await.unwrap();

    disk.assert_exists("invoices/2026/05/30/inv-00042.pdf").await;
    disk.assert_contents("invoices/2026/05/30/inv-00042.pdf", b"%PDF-1.7 …").await;
}
```

The guard pre-registers an in-memory disk named `"default"`, so trivial
tests don't need any disk setup. Register additional disks under
custom names with `Storage::register_memory("audit_logs")` from
inside the test if the code under test reaches for another disk.

The disk named `"default"` is not the default disk. The guard clears a
default disk set in code, and `FILESYSTEM_DISK` stays as the environment
has it. If the code under test calls `Storage::default_disk()`, name the
fake disk in the test with `Storage::set_default_disk("default")`, which
wins over `FILESYSTEM_DISK`.

| Assertion                                        | Asserts…                                          |
|--------------------------------------------------|---------------------------------------------------|
| `disk.assert_exists(path).await`                 | the path exists                                   |
| `disk.assert_contents(path, &expected).await`    | the file matches `expected` byte-for-byte         |
| `disk.assert_missing(path).await`                | the path does not exist                           |
| `disk.assert_count(dir, n, recursive).await`     | `dir` contains exactly `n` entries                |
| `disk.assert_directory_empty(dir).await`         | `dir` has no entries (recursive)                  |

All five panic on mismatch with the disk path in the message. See
[File Storage](filesystem.md) for the `Storage` facade itself and
the driver story (memory / fs / s3 / azblob / gcs).

## HTTP client - `Http::fake`

```rust,ignore
use suprnova::{Http, fake_response, assert_sent, assert_not_sent};

#[tokio::test]
async fn payment_webhook_is_acked() {
    Http::fake(|| async {
        fake_response("POST", "/v1/charges", 201, serde_json::json!({
            "id": "ch_42",
            "status": "succeeded",
        }));

        let result = charge_card(amount_cents).await;

        assert!(result.is_ok());
        assert_sent(|r| r.method == "POST" && r.url.contains("/v1/charges"));
        assert_not_sent(|r| r.method == "DELETE");
    })
    .await;
}
```

`fake_response(method, url_substring, status, body)` queues one
canned response. Method `"*"` matches any method. Each canned entry
is consumed on the first matching request; subsequent matching
requests either fall through to the next canned entry or return an
empty `200 {}`.

| Helper                                       | Purpose                                                   |
|----------------------------------------------|-----------------------------------------------------------|
| `Http::fake(\|\| async { … }).await`         | install the task-local fake scope                         |
| `fake_response(method, url_substring, …)`    | queue a canned response                                   |
| `assert_sent(\|r\| pred)`                    | assert at least one recorded request matches              |
| `assert_not_sent(\|r\| pred)`                | assert no recorded request matches                        |

### Spawned tasks don't inherit the fake by default

`tokio::spawn` doesn't carry task-locals into the spawned future, so
work that escapes the parent task escapes the fake too. Two tools
handle this:

```rust,ignore
// Belt-and-suspenders: turn every unfaked outbound call into a hard error.
let _guard = suprnova::FailOnRealCallsGuard::install();

Http::fake(|| async {
    fake_response("GET", "/child", 204, serde_json::json!({}));

    // Explicit opt-in: this child sees the parent's fake state.
    let handle = Http::spawn_with_fake_inheritance(async {
        Http::get("https://child.test").send().await
    });

    let response = handle.await.unwrap().unwrap();
    assert_eq!(response.status(), 204);
})
.await;
```

`FailOnRealCallsGuard` is RAII - install it at the top of a test and
any outbound call that doesn't hit an active fake errors out instead
of touching the network. `Http::spawn_with_fake_inheritance` is the
explicit opt-in for tasks that should share the parent's fake state.
See [HTTP Client](http-client.md) for the full discussion.

## Broadcasting

WebSocket broadcasting has a parallel test fixture, but its shape
differs enough that it lives in its own chapter:
`RecordingBroadcastHub` is a real `BroadcastHub` that records every
published envelope while still delivering to live subscribers. Bind
it in place of `InMemoryBroadcastHub` and call `hub.broadcasts()` /
`hub.assert_broadcast(channel, event)`. See
[Broadcasting](broadcasting.md) for the broadcasting model and the
recording-hub usage.

## Where each fake lives

| Surface       | Source                                | Facade re-export                             |
|---------------|---------------------------------------|----------------------------------------------|
| Mail          | `framework/src/mail/mod.rs`           | `suprnova::{Mail, MailFake}`                 |
| Notifications | `framework/src/notifications/testing.rs` | `suprnova::{Notify, NotifyFakeGuard}` + `suprnova::notifications::testing::*` |
| Queue         | `framework/src/queue/testing.rs`      | `suprnova::queue::testing::*`                |
| Bus           | `framework/src/bus/testing.rs`        | `suprnova::bus::testing::*`                  |
| Events        | `framework/src/events/testing.rs`     | `suprnova::{EventFacade, EventFakeGuard}` + `suprnova::events::*` |
| Storage       | `framework/src/filesystem/testing.rs` | `suprnova::{Storage, DiskExt}` + `suprnova::filesystem::testing::DiskAssertExt` |
| HTTP          | `framework/src/http_client/fake.rs`   | `suprnova::{Http, fake_response, assert_sent, assert_not_sent, FailOnRealCallsGuard, RecordedRequest}` |

The `testing` and `fake` modules are gated behind a Cargo feature
named `testing`. It's in the default feature set, so any test that
depends on `suprnova` picks the helpers up for free. The hooks
themselves are `#[doc(hidden)]` where they could be reached
accidentally from application code; the load-bearing safeguard is
`Server::from_config`'s `APP_KEY` validation, which runs on every
boot regardless of which test helpers are compiled in. See
[Testing](testing.md) for the production-build story.

## Why these shapes, not one shape

A single uniform shape would be neater on the page and worse in
practice. Each shape exists because the underlying state has
different concurrency semantics:

- **Mail's** transport is a global `Arc<dyn MailTransport>` swapped
  by the guard. Method assertions on the returned guard tie the
  asserter to the specific install, which makes it impossible to
  call assertions when no fake is active.
- **Notify / Queue / Bus / Events** assert on heterogeneous typed
  payloads - every assertion is generic over the event/job/command
  type. Free functions in a `testing` module compose with type
  parameters more cleanly than a hand-written method set on a guard.
- **Storage** assertions are per-disk, not per-fake - the same
  `disk.assert_exists(…)` works against a faked memory disk or a
  real `s3` disk in an integration suite. Putting them on the disk
  via an extension trait keeps that symmetry.
- **HTTP** has to follow tasks, not the calling stack. `Http::fake`
  is the only fake whose scope can't be expressed as a guard -
  spawn semantics force a closure.

If you ever find yourself reaching for a helper that doesn't exist,
read the relevant chapter; the public testing surface is documented
exhaustively per subsystem.

## Next

- [Testing](testing.md) - the `#[suprnova_test]` macro, `TestDatabase`,
  `expect!`, and `TestContainer::fake`
- [HTTP Tests](http-tests.md) - driving `handle_request` directly
  without opening a socket
- [Database Tests](database-testing.md) - the per-test in-memory
  database story
- [Service Container](container.md) - `TestContainer::fake` for
  swapping injected services


---

<!-- /docs/page-budget -->

# Page budget

A page budget checks the document and the assets it fetches. The test helper
uses the application's in-process HTTP path. It needs no browser, port or
network. The console command reads a HAR capture or fetches a live URL.
All three modes use `PageBudget` and the same evaluator. Budgets measure the
application's own resources: the document and same-origin assets. Third-party
hosts are listed and governed by the configured allowed host list because the
application controls neither their bytes nor their headers. HAR entries from
other origins do not count toward transfer, asset, raster, font, cache or cookie
rules.

## Test a page

Pass the application's router and middleware to `TestClient`. Use an absolute
URL when the document contains absolute asset URLs. Relative paths use
`http://localhost`.

```rust
use suprnova::page_budget::PageBudget;
use suprnova::testing::TestClient;
use suprnova::{HttpResponse, MiddlewareRegistry, Request, Router};

#[tokio::test]
async fn public_page_stays_within_budget() -> Result<(), suprnova::FrameworkError> {
    let router = Router::new().get("/", |_req: Request| async {
        Ok(HttpResponse::html("<h1>Hello</h1>"))
    });
    let client = TestClient::new(router, MiddlewareRegistry::new());
    client.audit_page("/", &PageBudget::default()).await?.ensure_passes()
}
```

The helper fetches stylesheets, scripts, images, source sets, icons, manifests
and preloads. It follows video and audio sources, video posters and CSS URLs
in style attributes and stylesheets, including `@font-face` fonts, imports
and string candidates in `image-set()`.
It fetches manifest icons only when the document references the manifest.
It deduplicates URLs and records external hosts without requesting them.
All `srcset` candidates count; the helper does not choose a viewport.
Data URL commas do not hide later candidates.
Every asset request carries no cookie. The client's login and cookie jar do
not affect the audit. A refused or redirected asset fails the audit.

React, Vue, Svelte and Live kits ship `tests/page_budget.rs` over their five
public entry pages. The API kit has no public pages and ships no page test.

## Set limits

The defaults use decimal bytes. Total transferred response bodies are limited
to 1,000,000 bytes. An asset is limited to 250,000 bytes. Fonts together are
limited to 100,000 bytes. A raster above 100,000 decoded bytes needs a WebP or
AVIF alternative and a fallback. A retained PNG above that threshold must be
within 10 percent of oxipng's fast preset. Manifest icons follow the same
raster rule. A PNG fallback needs another entry in the same manifest with
`type` `image/webp` or `image/avif` and the same `sizes`. The PNG compression
rule still applies to that fallback.

```rust
use suprnova::page_budget::PageBudget;

let budget = PageBudget {
    total_transfer_bytes: 800_000,
    asset_bytes: 200_000,
    font_bytes: 80_000,
    ..PageBudget::default()
};
```

These limits expose the captured 1.4 MB page, its large PNG and its icon font.
They leave room for a starter page. Set limits for the application's content
and measure changes in review. PNG recompression is lossless and preserves
the media pipeline's colour and metadata policy. Lossy media output keeps
the framework's default quality of 85.

The configured Vite build manifest identifies build outputs in each entry's
`file`, `css` and `assets`. A listed file receives immutable caching only when
its filename has a hyphen or dot followed by at least eight base64url characters
(`A-Z`, `a-z`, `0-9`, `_` or `-`) before the extension. This includes
`app-deadbeef.js`; mutable names such as `index.html` and `app.js` retain the
revalidating policy. Empty outputs, absolute URLs or paths, and outputs containing
`..` or a backslash are ignored. The static handler, publisher and all audit modes
share this classification and read the installed `InertiaConfig` and its `manifest_path`.
For files outside that manifest, fingerprint detection uses a configurable
regular expression against the file name without its extension. The fallback
matches Vite's eight-character hash when it contains a digit,
uppercase letter, underscore or hyphen, in names such as
`main-BjmpJyAU.js`. An all-lowercase hash outside the manifest is not
recognized by the fallback; configure the pattern for it. Fingerprinted assets require
`public, max-age=31536000, immutable`. Other static files default to
`public, max-age=3600`, or the handler's configured cache policy. Static file
responses skip session persistence and cookie issuance only when the handler
changes no session state, issues no CSRF token and queues no security work.
Automatic flash aging still marks the request copy dirty for CSRF and other
readers. It does not advance the separate framework mutation marker used by
the asset gate. Aging alone does not force asset persistence. When the gate
skips finalization, stored flash survives for the following page. Token issuance
finalizes normally. A shared-cacheable response that exposes the token becomes
`private, no-store`. Remember credential rotation,
regeneration, identity changes and queued sign-in rebinds also finalize normally
and deliver any required cookies. Responses carrying those cookies become private.
On an ordinary shared-cacheable page, automatic aging keeps loaded flash dirty.
CSRF's usual XSRF-cookie rules see that dirty state. If CSRF attaches the cookie,
session finalization sends `Cache-Control: private, no-store`.

Select another naming convention on both the audit and the static handler.
The expression matches the filename without its extension. An invalid handler
pattern returns an error on its first request.

```rust
use suprnova::{StaticFiles, page_budget::PageBudget};

let pattern = r"\.v[0-9]+$";
let files = StaticFiles::public().fingerprint(pattern).handler();
let budget = PageBudget { fingerprint_pattern: pattern.into(), ..PageBudget::default() };
```

## Audit a capture or URL

Run the application's console binary. Capture a fresh visit with response bodies.
A finding returns a non-zero exit code.
Each row names the asset, rule, measured value and allowed value. The output
also includes the request count, transfer bytes and third-party hosts.

```bash
cargo run --bin console -- budget:audit capture.har
cargo run --bin console -- budget:audit https://example.com/
```

A URL audit asks for gzip, as a browser asks for compression. The transfer,
asset and font rules count the bytes that cross the wire, so the result
matches a HAR capture of the same visit, and the format and PNG rules read the
decoded body. A response in an encoding the audit did not ask for, such as
Brotli, fails the audit with the encoding named.

HTTP requests have a ten-second timeout. The whole collection has a thirty-second
timeout, a limit of 256 resources and a 16 MiB response limit, which also bounds
a decoded body.
`budget:audit` reads these collection limits through `PageBudget::from_env()`.
The resource limit counts normalized HTTP and HTTPS URLs after deduplication.
Data URLs and fragment-only references count zero. A separate limit of 65,536
work units meters HTML and CSS tokens, JSON keys and values, and raw reference
candidates. Duplicate and ignored candidates also consume work. CSS whitespace,
comments and complete function argument lists consume tokens. A token can span
many bytes, so the response byte limit separately bounds its lexical size.
Set `max_discovery_tokens` in Rust or
`PAGE_BUDGET_MAX_DISCOVERY_TOKENS` for the command.
Discovery stops HTML input on overflow, parses inline styles on their tags and
processes complete CSS constructs from style blocks before later markup.
Only an unfinished CSS construct is retained between character chunks; the
response byte limit bounds its size. Manifest keys and values consume work,
including scalars, strings and entries inside ignored extension objects and
arrays. The parser checks the allowance before reading each value. Icons are
decoded one at a time. Exhaustion stops before the next value is consumed,
without materializing the remaining array.
Each `image-set()` is a modern-plus-fallback group, like a picture or source set.
The pending queue is bounded too. Repeating one reference does not allocate
another queue entry. Every `Cache-Control` header line contributes to the policy; a second `no-cache` line fails the
immutable rule. Redirects are recorded before following same-origin
locations. The initial HTTP-to-HTTPS upgrade may be followed on the same host;
it still fails the first-redirect rule. Other external redirects are listed.

`PageBudget::default()` keeps the shipped values. `PageBudget::from_env()`
reads one variable per field and rejects invalid values with the variable's
name. Boolean values use literal `true` or `false`. Host lists use commas;
spaces around each host are ignored. Unset lists only report hosts. An empty
list rejects every external host. An invalid fingerprint expression fails
before collection.

```bash
PAGE_BUDGET_TOTAL_BYTES=800000 PAGE_BUDGET_FONT_BYTES=80000 cargo run --bin console -- budget:audit capture.har
```

| Variable | Default | Type | Purpose |
|---|---|---|---|
| `PAGE_BUDGET_TOTAL_BYTES` | `1000000` | u64 | Total transferred response bytes. |
| `PAGE_BUDGET_ASSET_BYTES` | `250000` | u64 | Transferred bytes per asset. |
| `PAGE_BUDGET_RASTER_THRESHOLD_BYTES` | `100000` | u64 | Decoded bytes above which a raster needs a modern format and fallback. |
| `PAGE_BUDGET_PNG_MARGIN_PERCENT` | `10` | u32 | Margin above the fast PNG recompression size. |
| `PAGE_BUDGET_FONT_BYTES` | `100000` | u64 | Combined transferred font bytes. |
| `PAGE_BUDGET_REQUIRE_IMMUTABLE` | `true` | bool | Check fingerprinted cache policy. |
| `PAGE_BUDGET_FORBID_ASSET_SET_COOKIE` | `true` | bool | Reject asset response cookies. |
| `PAGE_BUDGET_FORBID_ASSET_REQUEST_COOKIE` | `true` | bool | Reject captured asset request cookies. |
| `PAGE_BUDGET_REQUIRE_COOKIE_INDEPENDENT` | `true` | bool | Require successful anonymous asset access. |
| `PAGE_BUDGET_FORBID_FIRST_REDIRECT` | `true` | bool | Reject an initial document redirect. |
| `PAGE_BUDGET_FINGERPRINT_PATTERN` | Strict Vite hash expression | regex | Match the filename stem. |
| `PAGE_BUDGET_ALLOWED_THIRD_PARTY_HOSTS` | unset | comma-separated hosts | Restrict external hosts when set. Empty forbids all external hosts. |
| `PAGE_BUDGET_MAX_RESOURCES` | `256` | usize | Bound discovery and queued resources. |
| `PAGE_BUDGET_MAX_DISCOVERY_TOKENS` | `65536` | usize | Bound parser tokens and raw reference candidates across collection. |
| `PAGE_BUDGET_MAX_RESPONSE_BYTES` | `16777216` | usize | Bound one response body. |
| `PAGE_BUDGET_REQUEST_TIMEOUT_SECS` | `10` | u64 | Bound one HTTP request in seconds. |
| `PAGE_BUDGET_COLLECTION_TIMEOUT_SECS` | `30` | u64 | Bound the complete collection in seconds. |

HAR response `bodySize` measures transferred bytes; `content.size` measures
decoded bytes. When `bodySize` is unknown, the audit uses `content.size`.
A capture without PNG bytes cannot prove compression and reports that missing
evidence. Captured request cookies fail the request-cookie rule; they show
that cookies were sent, not that the server required them. The live and test
runners prove cookie independence by requesting assets without cookies.
Cookie independence also fails when a capture carries cookies, even when the
separate request-cookie privacy rule is disabled.
A bodyless HAR cannot prove document fallback relationships for a large raster.
Export response bodies when those rules matter.

### Why Suprnova diverges

Laravel's HTTP tests inspect individual responses. Suprnova follows the
page's assets so a test catches transfer size, image format, font size and
cache policy together. The same rules run against a deployment capture.
The audit does not execute JavaScript. Assets created only by client-side
code appear in a HAR audit when the capture records them.

## Next

Read [HTTP Tests](http-tests.md), [Testing](testing.md),
[Starter Kits](starter-kits.md) and [Images](images.md).


# Payments

---

<!-- /docs/payments -->

# Payments

Suprnova's payments surface is provider-neutral. Register an adapter at boot and call its supported operations through the common payment traits. Stripe and Paddle hydrate customer-linked mirror tables from webhooks. The NOWPayments invoice adapter records verified notifications in the audit log; applications reconcile their own orders using authenticated payment lookup.

Providers expose the same trait contract, but their capabilities differ. Unsupported operations return `PaymentError::NotSupported`. Server-side capture and promotions are optional capabilities, queried through `PaymentProvider::as_payment()` and `PaymentProvider::as_promotions()`.

## Why Suprnova diverges

Laravel ships Cashier as a first-party Stripe integration in the core docs. It's convenient, but Stripe-only - adding a second provider means forking Cashier or building a parallel surface. Suprnova treats payment providers the way it treats cache and storage drivers: one generic trait set, swappable adapters. Your domain code never names `StripeProvider` or `PaddleProvider`; it calls `provider.subscribe(...)` against `Arc<dyn PaymentProvider>` resolved from a registry, and the provider behind it is one bootstrap change away from being something else.

## Quick start

Add the adapter crate. Until Suprnova ships its v0.1 release, the framework and its adapter crates are consumed by git rather than crates.io:

```toml
# Cargo.toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2" }
suprnova-payments-stripe = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2" }
```

Register the provider and the webhook router at boot. The webhook router is a regular `Router` you compose into your `routes::register()`:

```rust,ignore
// src/bootstrap.rs
use std::sync::Arc;
use suprnova::payments::PaymentProviderRegistry;
use suprnova_payments_stripe::StripeProvider;

pub async fn register() {
    let stripe = StripeProvider::from_env().expect("Stripe env vars not set");
    PaymentProviderRegistry::bind("stripe", Arc::new(stripe));
}
```

```rust,ignore
// src/routes.rs
use std::sync::Arc;
use suprnova::payments::webhook_routes;
use suprnova::container::App;
use suprnova::Router;
use sea_orm::DatabaseConnection;

/// `Application::routes(routes::register)` calls this once at boot.
/// We start from the payments webhook router, then layer the rest of
/// the app's routes on top with normal `.get(...)` / `.post(...)` calls.
pub fn register() -> Router {
    let db: Arc<DatabaseConnection> = App::get().expect("db not bound");

    webhook_routes(db)
        .get("/", crate::controllers::home::index)
        .post("/login", crate::controllers::auth::login)
        // ... the rest of your routes ...
        .into()
}
```

`webhook_routes(db)` returns a `Router` containing just `POST /webhooks/payments/{provider}`. Because `Router::get` and `Router::post` each return a `RouteBuilder` that converts back to `Router` via `.into()`, chaining on top of the payments router is the most direct way to compose. If you already use the `routes!{}` macro for your normal routes, drop the webhook POST into the same block - `webhook_routes` is a convenience wrapper around one `Router::new().post(...)` call.

Pass the application's own database as `db`, the one `DB` and the payments models use. With [RenderCache](render-cache.md) on, every write the webhook makes - the event's receipt row, its mirror rows, and the error a failed attempt records - advances its table's generation in the same transaction that writes the row, so a cached page that read those tables goes stale the moment the write commits. The generation ledger lives in that database.

Every payments type has one path, `suprnova::payments::<Type>`, for example `suprnova::payments::StartSessionRequest`. The modules that hold the request and result types are reached as `suprnova::payments::dto::<module>`; a path such as `suprnova::payments::session::StartSessionRequest` does not compile.

In your controller, look up the provider, create a customer, and open a checkout session:

```rust,ignore
// src/controllers/billing.rs
use std::sync::Arc;
use suprnova::payments::*;

pub async fn start_checkout(
    user_id: String,
    email: String,
) -> PaymentResult<SessionPayload> {
    let provider = PaymentProviderRegistry::get("stripe")
        .ok_or_else(|| PaymentError::Internal("stripe not registered".into()))?;

    let customer = provider.create_customer(CreateCustomerRequest {
        user_id,
        email,
        name: None,
        metadata: None,
    }).await?;

    provider.start_session(StartSessionRequest {
        mode: SessionMode::Subscription,
        customer_ref: customer.provider_customer_id,
        price_refs: vec!["price_pro_monthly".into()],
        success_return_url: "https://app.example/billing/success".into(),
        cancel_return_url: "https://app.example/billing/cancel".into(),
        amount_hint: None,
        idempotency_key: None,
        metadata: None,
    }).await
}
```

That `SessionPayload` goes into your Inertia page props. The frontend dispatches on `payload.flow` to render the right widget - see [Payments - Frontend Integration](payments-frontend.md).

## Picking an adapter

### Stripe

```toml
# Cargo.toml
suprnova-payments-stripe = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2" }
```

Required env vars:

| Variable | Description |
|---|---|
| `STRIPE_SECRET_KEY` | Secret key (`sk_live_…` / `sk_test_…`) |
| `STRIPE_PUBLISHABLE_KEY` | Publishable key (`pk_live_…` / `pk_test_…`) |
| `STRIPE_WEBHOOK_SIGNING_SECRET` | Webhook endpoint signing secret (`whsec_…`) |

```rust,ignore
use suprnova_payments_stripe::StripeProvider;
use std::sync::Arc;
use suprnova::payments::PaymentProviderRegistry;

// From env (recommended in production):
let stripe = StripeProvider::from_env().expect("Stripe env vars not set");

// Or construct directly:
let stripe = StripeProvider::new("sk_test_...", "pk_test_...", "whsec_...");

PaymentProviderRegistry::bind("stripe", Arc::new(stripe));
```

Stripe implements every trait including the optional `Payment` (server-side capture via PaymentIntents) and `Promotions` (promotion-code minting via `/v1/promotion_codes`). Both `provider.as_payment()` and `provider.as_promotions()` return `Some`.

### Paddle

```toml
# Cargo.toml
suprnova-payments-paddle = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2" }
```

Required env vars:

| Variable | Description |
|---|---|
| `PADDLE_API_KEY` | API key (`pdl_live_apikey_…` / `pdl_sdbx_apikey_…`) |
| `PADDLE_WEBHOOK_KEY` | Notification destination secret (`pdl_ntfset_…`) |
| `PADDLE_CLIENT_TOKEN` | Client-side token (`live_…` / `test_…`) |
| `PADDLE_ENVIRONMENT` | Optional, defaults to `"sandbox"` |

```rust,ignore
use suprnova_payments_paddle::{PaddleProvider, PaddleEnvironment};
use std::sync::Arc;
use suprnova::payments::PaymentProviderRegistry;

// From env:
let paddle = PaddleProvider::from_env().expect("Paddle env vars not set");

// Or construct directly:
let paddle = PaddleProvider::new(
    "pdl_sdbx_apikey_...",
    "pdl_ntfset_...",
    "test_...",
    PaddleEnvironment::Sandbox,
).expect("Paddle client init failed");

PaymentProviderRegistry::bind("paddle", Arc::new(paddle));
```

Paddle is a Merchant of Record - it manages tax, dunning, and the full subscription lifecycle. It does not expose server-side capture, so `Payment` is not implemented. Calling `provider.as_payment()` returns `None`. Subscriptions are created indirectly: call `Checkout::start_session`, complete the Paddle widget, and the `SubscriptionCreated` webhook arrives to confirm the subscription ID.

### NOWPayments

The `suprnova-payments-nowpayments` adapter supports hosted one-off invoices and
verified IPNs. It uses explicit unsupported-operation errors for customer and
subscription operations. Customerless invoice events are audited without
fabricating customer-linked transaction mirrors. See the
[NOWPayments guide](payments-nowpayments.md) for configuration and reconciliation.

## The trait split

`PaymentProvider` is an umbrella that bundles four universal traits - `Checkout`, `Subscription`, `CustomerStore`, `WebhookHandler` - every adapter implements. Two further traits are optional: `Payment` (server-side capture only makes sense for gateways like Stripe) and `Promotions` (promotion-code minting). Adapters opt in by overriding `PaymentProvider::as_payment()` / `PaymentProvider::as_promotions()`.

```rust,ignore
pub trait PaymentProvider: Checkout + Subscription + CustomerStore + WebhookHandler {
    fn name(&self) -> &'static str;

    /// Returns `Some` if this provider also implements `Payment` (server-capture).
    /// Default returns `None`.
    fn as_payment(&self) -> Option<&dyn Payment> {
        None
    }

    /// Returns `Some` if this provider also implements `Promotions`
    /// (promotion-code minting). Default returns `None`.
    fn as_promotions(&self) -> Option<&dyn Promotions> {
        None
    }
}
```

### `Checkout` - universal, opens the client widget

Every provider implements `Checkout`. Call `start_session` to get a flow-tagged `SessionPayload` that your frontend renders. `session_status` (default: `NotSupported`; overridden by providers whose sessions can be interrogated, Stripe and Paddle) reports the authoritative provider-side state of a session you started earlier.

```rust,ignore
#[async_trait]
pub trait Checkout: Send + Sync {
    async fn start_session(&self, req: StartSessionRequest) -> PaymentResult<SessionPayload>;

    async fn session_status(&self, provider_session_id: &str)
        -> PaymentResult<CheckoutSessionState>;
}
```

`StartSessionRequest` fields:

| Field | Type | Description |
|---|---|---|
| `mode` | `SessionMode` | `OneOff` or `Subscription` |
| `customer_ref` | `String` | Provider customer ID from `CustomerStore::create_customer` |
| `price_refs` | `Vec<String>` | Provider price/product IDs |
| `success_return_url` | `String` | Where to send the user after payment |
| `cancel_return_url` | `String` | Where to send the user if they abandon |
| `amount_hint` | `Option<Money>` | Override or hint for one-off amounts |
| `idempotency_key` | `Option<String>` | Forwarded by Stripe; rejected by Paddle when present |
| `metadata` | `Option<Value>` | Correlation data attached to the provider checkout and its payment or subscription |

`session_status` is the server-side verification primitive for redirect
flows. When the customer lands back on your return page, do NOT trust the
query parameters their browser carried - pass the `provider_session_id`
you recorded at `start_session` time and branch on the result:

```rust,ignore
match provider.session_status(&order.provider_session_id).await? {
    CheckoutSessionState::Complete { paid: true, payment_ref, amount_total } => {
        // Fulfil the order. `payment_ref` (e.g. Stripe's `pi_…`) correlates
        // with `Payment` operations and the payments_transactions mirror.
    }
    CheckoutSessionState::Complete { paid: false, .. } => { /* settlement pending */ }
    CheckoutSessionState::Open => { /* customer hasn't finished paying */ }
    CheckoutSessionState::Expired => { /* session lapsed - close the order */ }
}
```

The same call powers reconciliation sweeps: re-poll orders still open in
your database and fulfil the ones whose sessions completed after the
customer closed the tab.

### `Payment` - optional, server-side capture

Only providers that expose server-side capture implement `Payment`. Stripe does; Paddle does not. To check at runtime:

```rust,ignore
let provider = PaymentProviderRegistry::get("stripe").unwrap();
if let Some(payment) = provider.as_payment() {
    let result = payment.charge(ChargeRequest {
        customer_ref: "cus_...".into(),
        payment_method_ref: "pm_...".into(),
        amount: Money::from_minor_units(2999, Currency::USD),
        description: Some("Pro plan one-off".into()),
        idempotency_key: Some("charge_user42_order99".into()),
        metadata: None,
    }).await?;
}
```

Full `Payment` interface:

```rust,ignore
#[async_trait]
pub trait Payment: Send + Sync {
    async fn charge(&self, req: ChargeRequest) -> PaymentResult<ChargeResult>;
    async fn capture(&self, provider_transaction_id: &str) -> PaymentResult<ChargeResult>;
    async fn refund(&self, req: RefundRequest) -> PaymentResult<RefundResult>;
    async fn void(&self, provider_transaction_id: &str) -> PaymentResult<()>;
    async fn status(&self, provider_transaction_id: &str) -> PaymentResult<PaymentStatus>;
}
```

`ChargeResult` is an enum tagged with `kind` - see the [Money and ChargeResult](#chargeresult) section.

### `Promotions` - optional, mint promotion codes

Providers with a promotion-code surface implement `Promotions`. The discount object itself (a percent- or amount-off coupon) is created ahead of time - typically once, in the provider's dashboard - and this trait mints *codes* off it, each restricted to one customer and one redemption window. That is the shape win-back and upsell campaigns need: every recipient gets a personal code, unusable by anyone else and dead after the window closes.

```rust,ignore
let provider = PaymentProviderRegistry::get("stripe").unwrap();
if let Some(promotions) = provider.as_promotions() {
    let minted = promotions.create_promotion_code(CreatePromotionCodeRequest {
        coupon_ref: "coupon_15off".into(),          // pre-created coupon
        customer_ref: "cus_...".into(),             // only this customer can redeem
        expires_at: Some(chrono::Utc::now() + chrono::Duration::days(7)),
        max_redemptions: Some(1),                   // single-use
    }).await?;
    // Email `minted.code` to the customer; they enter it at checkout and
    // the provider enforces every restriction.
}
```

The `MockPaymentProvider` implements `Promotions` (codes mint as `PROMO_MOCK_n`) and records every request - assert on `recorded_promotion_requests()` in tests.

### `Subscription` - subscribe, update, cancel, get

```rust,ignore
#[async_trait]
pub trait Subscription: Send + Sync {
    async fn subscribe(&self, req: SubscribeRequest) -> PaymentResult<SubscriptionResult>;
    async fn update(&self, req: UpdateSubscriptionRequest) -> PaymentResult<SubscriptionResult>;
    async fn cancel(&self, provider_subscription_id: &str, at_period_end: bool) -> PaymentResult<SubscriptionResult>;
    async fn get(&self, provider_subscription_id: &str) -> PaymentResult<SubscriptionResult>;
}
```

Cancel at period end (keeps access until billing cycle ends):

```rust,ignore
let sub = provider.cancel(&sub_id, true).await?;
// sub.cancel_at_period_end == true, sub.status == Active

// Cancel immediately:
let sub = provider.cancel(&sub_id, false).await?;
// sub.status == Canceled
```

Change the prices of a subscription with `update` and `new_price_refs`. The list is the set of prices the subscription has after the call. An item whose price is in the list keeps its id and quantity. An item whose price is not in the list is removed. A price with no item is added with a quantity of 1, except in a swap: when the change removes exactly one item and adds exactly one price, the new price takes the quantity of the removed item. The adapter computes the change from a read of the subscription, so it is not atomic. An empty list, or a list that names a price twice, is `PaymentError::Validation` on every adapter and on the mock.

```rust,ignore
use suprnova::payments::{Proration, UpdateSubscriptionRequest};

let sub = provider.update(UpdateSubscriptionRequest {
    provider_subscription_id: sub_id.clone(),
    new_price_refs: Some(vec!["price_team_yearly".into()]),
    proration: Some(Proration::ProrateNow),
    cancel_at_period_end: None,
    idempotency_key: None,
}).await?;
```

`proration` says how the change is billed and is read only when `new_price_refs` is `Some`. `None` is `ProrateAtRenewal`.

| `Proration` | Meaning | Stripe `proration_behavior` | Paddle `proration_billing_mode` |
|---|---|---|---|
| `ProrateNow` | Bill the prorated difference at once. | `always_invoice` | `prorated_immediately` |
| `ProrateAtRenewal` | Put the prorated difference on the next invoice. | `create_prorations` | `prorated_next_billing_period` |
| `DoNotProrate` | Charge nothing for the change. | `none` | `do_not_bill` |

`Proration` is `#[non_exhaustive]`, so a `match` on it needs a wildcard arm. On Paddle, a price change together with `cancel_at_period_end`, or with an `idempotency_key`, is `NotSupported`. See [Payments - Stripe Adapter](payments-stripe.md#update-changes-prices-and-the-cancellation-flag) and [Payments - Paddle Adapter](payments-paddle.md#change-the-prices-of-a-subscription).

Note: `Paddle::subscribe` returns `PaymentError::NotSupported` - Paddle creates subscriptions through checkout completion, not direct API calls. Use `Checkout::start_session` and wait for the `SubscriptionCreated` webhook.

### `CustomerStore` - create, update, get, delete

```rust,ignore
#[async_trait]
pub trait CustomerStore: Send + Sync {
    async fn create_customer(&self, req: CreateCustomerRequest) -> PaymentResult<CustomerRef>;
    async fn update_customer(&self, req: UpdateCustomerRequest) -> PaymentResult<CustomerRef>;
    async fn get_customer(&self, provider_customer_id: &str) -> PaymentResult<CustomerRef>;
    async fn delete_customer(&self, provider_customer_id: &str) -> PaymentResult<()>;
}
```

`CreateCustomerRequest` takes `user_id`, `email`, `name: Option<String>`, and `metadata: Option<Value>`. `CustomerRef` comes back with `provider_customer_id` - store that alongside your user record to use in subsequent calls.

### `WebhookHandler` - verify, parse, and extract

```rust,ignore
#[async_trait]
pub trait WebhookHandler: Send + Sync {
    fn verify(&self, ctx: &WebhookContext<'_>) -> PaymentResult<()>;
    fn parse_event(&self, body: &[u8]) -> PaymentResult<WebhookEvent>;

    /// Pull entity IDs out of the raw payload so the framework knows which
    /// mirror rows to hydrate. Default returns an empty `PayloadIds`.
    fn extract_payload_ids(&self, event: &WebhookEvent) -> PayloadIds;

    /// Build a `PaymentSnapshot` from a payment / invoice event. Default
    /// returns `None`, which skips the `payments_transactions` upsert.
    fn extract_payment_snapshot(&self, event: &WebhookEvent) -> Option<PaymentSnapshot>;

    /// Build a `CustomerSnapshot` from a customer event. Default returns
    /// `None`, which skips the email / metadata refresh on the existing row.
    fn extract_customer_snapshot(&self, event: &WebhookEvent) -> Option<CustomerSnapshot>;
}
```

In practice you never call any of these directly - `webhook_routes` invokes them for every inbound webhook. They live on the trait so adapter crates can implement provider-specific signature verification, event parsing, and payload extraction in a testable way. The `extract_*` methods all have sensible defaults; the shipped Stripe and Paddle adapters override them with provider-shape-aware implementations (Stripe reaches into `data.object.*`, Paddle into `data.*`).

## The flow-tagged Inertia payload

`start_session` returns a `SessionPayload` enum that serializes to JSON with a `flow` discriminator field. Your frontend switches on `flow` to render the right widget:

```rust,ignore
#[serde(tag = "flow", rename_all = "snake_case")]
pub enum SessionPayload {
    StripeElements {
        client_secret: String,
        publishable_key: String,
        provider_session_id: String,
    },
    StripeCheckoutRedirect {
        url: String,
        provider_session_id: String,
    },
    PaddleInline {
        transaction_id: String,
        customer_token: Option<String>,
        client_token: String,
    },
    /// Mobile Money flow - no redirect or embed. Frontend displays a
    /// user-facing message telling the customer to confirm on their phone
    /// (USSD prompt or operator app), then polls the provider via
    /// `provider_transaction_id` for status updates.
    MobileMoneyPrompt {
        provider_transaction_id: String,
        message: String,
        operator: MobileMoneyOperator,
    },
    Redirect {
        url: String,
        provider_session_id: String,
    },
}
```

Serialized form of a `StripeElements` payload:

```json
{
  "flow": "stripe_elements",
  "client_secret": "pi_..._secret_...",
  "publishable_key": "pk_live_...",
  "provider_session_id": "pi_..."
}
```

A `MobileMoneyPrompt` payload looks like this - there is no URL because the customer never leaves your page; the frontend renders `message` and starts polling:

```json
{
  "flow": "mobile_money_prompt",
  "provider_transaction_id": "ch_mm_...",
  "message": "Check your phone for the MTN MoMo prompt.",
  "operator": { "kind": "mtn_momo" }
}
```

Return whichever variant the provider produces from your controller as Inertia props. Frontend integration is described in [Payments - Frontend Integration](payments-frontend.md).

## Mirror tables

Six tables are created by the framework migration. Pull in the public alias and include it in your app's migrator:

```rust,ignore
use sea_orm_migration::{MigrationTrait, MigratorTrait};
use suprnova::payments::migrations::CreatePaymentsTables;

pub struct Migrator;

#[async_trait::async_trait]
impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            // ... your other migrations ...
            Box::new(CreatePaymentsTables),
        ]
    }
}
```

The same module also exports a helper `pub fn migrations() -> Vec<Box<dyn MigrationTrait>>` if you'd rather call that and spread the result into your own list.

### Table overview

| Table | Purpose |
|---|---|
| `payments_customers` | One row per `(provider, user_id)` pair |
| `payments_payment_methods` | Stored payment methods per customer |
| `payments_subscriptions` | Subscription lifecycle state |
| `payments_subscription_items` | Line items within a subscription |
| `payments_transactions` | One-off charges and subscription invoices |
| `payments_webhook_events` | Audit log and idempotency guard |

Every table has a `provider_metadata` JSON column. When the framework's neutral representation doesn't cover a provider-specific field, read it from there.

Every timestamp column is a native `timestamp with time zone` column (`TIMESTAMP` on MySQL and MariaDB), so the database's own date functions work on it. The mirror models declare `AsNativeDateTime` on those fields, and the SeaORM entities under `suprnova::payments::entities` carry them as `DateTime<Utc>` (`Option<DateTime<Utc>>` for `canceled_at`, `paid_at` and `processed_at`). Set them with a `DateTime<Utc>`, not with formatted text.

### Transactions table

`payments_transactions` splits amounts into `amount_total_minor` and `amount_tax_minor`. Stripe reports amounts exclusive of tax - tax is zero on the transaction row, and any tax data lives in `provider_metadata`. Paddle reports amounts inclusive of tax and sets `amount_tax_minor` to the tax component. Both representations work; add `amount_total_minor - amount_tax_minor` for the net amount.

### Webhook events table

`payments_webhook_events` has a `UNIQUE(provider, provider_event_id)` index. Every inbound webhook is checked against this before processing - duplicates return 200 OK without re-processing. This is load-bearing: Stripe, Paddle, and most providers retry failed webhooks aggressively.

### Caveats

Domain code reads from the mirror tables, not directly from the provider API. Mutations (create subscription, cancel, etc.) go to the provider; the resulting webhook syncs the mirror tables back. This means there is a brief window between a mutation and the webhook arriving where your mirror tables lag behind. Design your UX to account for this (show "processing" states, rely on the provider's redirect URLs for immediate confirmation).

## Webhook handling

Mount the webhook ingress route once at bootstrap - see the [Quick start](#quick-start) routes example for the composition pattern. `webhook_routes(db)` returns a `Router` carrying the single `POST /webhooks/payments/{provider}` handler that's built into the framework. You chain your own routes onto it (or call the route's underlying primitives directly inside your own `routes!{}` block).

The framework handler does this for each request:

1. Looks up the named provider in `PaymentProviderRegistry`.
2. Calls `WebhookHandler::verify` to check the signature. Returns 401 on failure.
3. Calls `WebhookHandler::parse_event` to build a `WebhookEvent`. Returns 400 on parse failure.
4. Checks `payments_webhook_events` for an existing row with the same `(provider, provider_event_id)`. If found, returns 200 immediately - this is the idempotency guard.
5. Inserts the audit row.

### WebhookEvent structure

```rust,ignore
pub struct WebhookEvent {
    pub provider: String,
    pub provider_event_id: String,
    pub provider_event_type: String,        // raw provider string, e.g. "customer.subscription.created"
    pub neutral: Option<NeutralEventKind>,  // mapped to framework taxonomy, or None for provider-specific events
    pub raw_payload: Value,                 // full JSON body for fallthrough
}
```

`NeutralEventKind` covers the common path:

```rust,ignore
pub enum NeutralEventKind {
    PaymentSucceeded,
    PaymentFailed,
    PaymentRefunded,
    PaymentDisputed,
    SubscriptionCreated,
    SubscriptionUpdated,
    SubscriptionCanceled,
    InvoicePaid,
    InvoiceFailed,
    CustomerCreated,
    CustomerUpdated,
}
```

When `neutral` is `None`, the event is provider-specific. Read `provider_event_type` and `raw_payload` for the full data.

### Mirror-table hydration

After the audit row is persisted, the framework dispatches the event to the relevant mirror table based on `neutral`. **All mirror writes for one event happen inside a single DB transaction along with `mark_processed`** - partial mirror state is never observable. Either everything commits together or everything rolls back.

| `NeutralEventKind`               | Mirror effect                                                                                       |
|----------------------------------|-----------------------------------------------------------------------------------------------------|
| `SubscriptionCreated/Updated`    | Calls `Subscription::get(id)` on the provider, upserts `payments_subscriptions`, syncs items.       |
| `SubscriptionCanceled`           | Same as above; also sets `canceled_at` and flips `status` to `canceled` on the existing row.        |
| `PaymentSucceeded / Failed / Refunded / Disputed` | Upserts `payments_transactions` from the snapshot the provider produces from `raw_payload`.        |
| `InvoicePaid / InvoiceFailed`    | Upserts `payments_transactions` with `provider_subscription_id` linked.                              |
| `CustomerCreated / CustomerUpdated` | Updates the existing `payments_customers` row's `email` / `provider_metadata` from the provider's `CustomerSnapshot`. **Never inserts.**   |
| `None` (unmapped)                | Audit row only - no mirror change.                                                                   |

The customer mirror is intentionally update-only on the webhook path. `user_id` is `NOT NULL` and only the app knows which user a provider customer belongs to (the link is created by your code right after `CustomerStore::create_customer`). Out-of-band customers - created in the Stripe dashboard, say - are logged but never synthesized into the mirror.

### Failure recovery contract

The handler treats provider retries as the recovery mechanism:

- **Hydration succeeds:** transaction commits, `processed_at` set, `process_error` cleared. Response: `200 ok`.
- **Hydration fails:** transaction rolls back (no partial mirror state), audit row keeps `processed_at = NULL` and `process_error` records the failure. Response: `503 hydration-failed` - the provider will retry with backoff.
- **Provider retries the failed event:** idempotency check sees the existing audit row but `processed_at IS NULL`, so hydration runs again. The retry replaces the stale `process_error` with the current attempt's outcome.
- **Provider retries a succeeded event:** idempotency check sees `processed_at IS NOT NULL`, returns `200 duplicate` immediately. No re-hydration.

A database error during hydration stays a `PaymentError::Database { context, source }`. `source` is the `suprnova::DbErr`, and `context` names the step that failed (`begin tx`, `lock audit row`, `commit`) or is `None`. The route answers `503` for every database error, and `process_error` records the text of the error. The type lets your own code ask what kind of failure it was: a lost connection is gone at the next attempt, a violated constraint is not. `Debug` prints the text of the database error and not its `Debug`, because the driver's detail for a violated constraint names the values of the key.

```rust
use std::error::Error;
use suprnova::DbErr;
use suprnova::payments::PaymentError;

fn worth_a_retry(error: &PaymentError) -> bool {
    error
        .source()
        .and_then(|source| source.downcast_ref::<DbErr>())
        .is_some_and(|database| {
            matches!(database, DbErr::ConnectionAcquire(_) | DbErr::Conn(_))
        })
}
```

A statement of your own that returns a `DbErr` ends in `?` inside a function that returns `PaymentResult`, because `PaymentError` implements `From<DbErr>`. `PaymentError::database("commit", error)` builds the variant with a context.

A subscription/customer event with a missing `subscription_id` / `customer_id` in the payload is treated as a `Validation` error (also 503 + `process_error` recorded). Silent success on a malformed payload would leave the mirror stale without operator visibility.

Items removed from a subscription on the provider side (e.g. user dropped a seat add-on) are removed from `payments_subscription_items` when the next `subscription.updated` webhook arrives. The provider's `Subscription::get(id)` response is the source of truth on every sync.

## Payment methods beyond cards

`PaymentMethod` is the enum the framework uses for stored methods in `payments_payment_methods` and for any provider that exposes method metadata. It covers the obvious cases - cards, bank transfers, e-wallets - plus regional methods that are first-class in many markets:

```rust,ignore
#[serde(tag = "type", rename_all = "snake_case")]
pub enum PaymentMethod {
    Card { brand: String, last4: String, exp_month: u8, exp_year: u16 },
    BankTransfer { bank_name: String, last4: String },
    EWallet { provider: String, identifier: String },
    /// Payer identified by phone + operator + country.
    MobileMoney {
        operator: MobileMoneyOperator,
        phone: PhoneNumber,
        country: CountryCode,
    },
    /// Pegged crypto - cash-equivalent for most providers.
    Stablecoin { asset: StablecoinAsset, network: Option<String> },
    /// Non-pegged cryptocurrency.
    Crypto { network: String, address: String },
    /// Escape hatch for regional / provider-specific methods not yet modeled.
    Custom { kind: String, descriptor: String },
}

#[serde(tag = "kind", rename_all = "snake_case")]
pub enum MobileMoneyOperator {
    MtnMomo,
    Mpesa,
    AirtelMoney,
    OrangeMoney,
    Lipila,
    Custom { identifier: String },
}

#[serde(tag = "kind", rename_all = "snake_case")]
pub enum StablecoinAsset {
    Usdc,
    Usdt,
    Dai,
    Custom { ticker: String },
}
```

The named operators and assets are the ones we've enumerated. The `Custom { ... }` variants on each cover regional operators and stablecoins the enums don't name, so adding support for one doesn't force a framework release.

`PhoneNumber` and `CountryCode` are validated DTOs in `suprnova::payments` - they reject malformed input at construction time, which is where you want the failure rather than at the provider call.

## Money

Amounts are represented as `Money` - an `i64` minor-unit count plus a `Currency`. No `f64` involved.

```rust,ignore
use suprnova::payments::{Money, Currency};
use rust_decimal::Decimal;
use std::str::FromStr;

// From minor units (cents, pence, yen, etc.)
let price = Money::from_minor_units(1999, Currency::USD);  // $19.99

// From a decimal string
let price = Money::from_decimal(Decimal::from_str("19.99").unwrap(), Currency::USD);

// Zero-decimal currencies - 1234 minor = 1234 JPY (no conversion)
let yen = Money::from_minor_units(1234, Currency::JPY);

// Arithmetic - panics on currency mismatch
let total = price + Money::from_minor_units(100, Currency::USD);  // $20.99

// Negative values represent refunds or credits
let refund = Money::from_minor_units(-500, Currency::USD);  // -$5.00

// Read back
println!("{} minor units in {:?}", price.minor_units(), price.currency());
```

`Add` and `Sub` panic on currency mismatch and on `i64` overflow. Use the panicking arithmetic for correctness - silent cross-currency addition is a bug, not a feature.

## ChargeResult

`Payment::charge` returns a `ChargeResult` enum. Not every charge completes immediately - 3DS step-up and off-session cards can require a redirect or a client-side action:

```rust,ignore
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ChargeResult {
    Completed {
        provider_transaction_id: String,
        amount: Money,
        status: PaymentStatus,
        provider_metadata: Value,
    },
    RedirectRequired {
        provider_transaction_id: String,
        url: String,
        return_to: Option<String>,
    },
    RequiresClientAction {
        provider_transaction_id: String,
        action_kind: String,
        client_secret: Option<String>,
        publishable_key: Option<String>,
    },
}
```

Handle `RequiresClientAction` by returning the payload to your frontend. The frontend renders the 3DS challenge using `client_secret` + `publishable_key`. See [Payments - Frontend Integration](payments-frontend.md) for the frontend dispatch code.

## Idempotency keys

Checkout, charge, refund, and subscription mutation DTOs expose an optional
`idempotency_key: Option<String>`. Set one on supported Stripe calls:

```rust,ignore
provider.start_session(StartSessionRequest {
    // ...
    idempotency_key: Some(format!("checkout_{}_{}", user_id, order_id)),
    // ...
}).await?;

provider.subscribe(SubscribeRequest {
    // ...
    idempotency_key: Some(format!("sub_{}_{}", user_id, plan_id)),
    // ...
}).await?;
```

Stripe forwards supported request keys in the `Idempotency-Key` HTTP header.
Retry the same operation with the same key and parameters. Paddle does not
accept client-supplied idempotency keys; its checkout, its price change, and
its scheduling of a cancellation with `update` return `NotSupported` when a
key is present. Persist the transaction ID
when creation succeeds. After an uncertain Paddle create, reconcile provider
state before issuing another create. Correlation metadata does not deduplicate
requests.

Every call of the Stripe and Paddle adapters has a deadline of 30 seconds. A read that runs out of time returns `PaymentError::Provider` with the text `<provider> <operation> timed out`. A call that changes something returns `PaymentError::Provider` with the text `<provider> <operation> timed out; outcome is unknown, reconcile before retrying`. In that case the provider may have carried out the change: read the state at the provider before you send the call again. On Stripe you can also send it again with the same idempotency key. See [Payments - Stripe Adapter](payments-stripe.md#deadlines-and-unknown-outcomes) and [Payments - Paddle Adapter](payments-paddle.md#deadlines-and-unknown-outcomes).

## The discriminator pattern

Every adapter that claims to implement `PaymentProvider` must pass the same E2E flow:

```
create_customer → start_session → subscribe → get → cancel(at_period_end) → cancel(immediate) → assert as_payment invariant
```

The `MockPaymentProvider` included with the framework passes this:

```rust,ignore
use suprnova::payments::*;

#[tokio::test]
async fn discriminator_flow() {
    let provider = MockPaymentProvider::new();

    let cus = provider.create_customer(CreateCustomerRequest {
        user_id: "user_42".into(),
        email: "alice@example.com".into(),
        name: Some("Alice".into()),
        metadata: None,
    }).await.unwrap();

    let session = provider.start_session(StartSessionRequest {
        mode: SessionMode::Subscription,
        customer_ref: cus.provider_customer_id.clone(),
        price_refs: vec!["price_pro_monthly".into()],
        success_return_url: "https://app.example/billing/success".into(),
        cancel_return_url: "https://app.example/billing/cancel".into(),
        amount_hint: None,
        idempotency_key: Some("idem_1".into()),
        metadata: None,
    }).await.unwrap();
    assert!(matches!(session, SessionPayload::Redirect { .. }));

    let sub = provider.subscribe(SubscribeRequest {
        customer_ref: cus.provider_customer_id.clone(),
        price_refs: vec!["price_pro_monthly".into()],
        trial_days: None,
        idempotency_key: Some("idem_2".into()),
        metadata: None,
    }).await.unwrap();
    assert_eq!(sub.status, SubscriptionStatus::Active);

    // Cancel at period end
    let s = provider.cancel(&sub.provider_subscription_id, true).await.unwrap();
    assert!(s.cancel_at_period_end);

    // Cancel immediately
    let s = provider.cancel(&sub.provider_subscription_id, false).await.unwrap();
    assert_eq!(s.status, SubscriptionStatus::Canceled);

    // MockPaymentProvider deliberately omits Payment (Paddle-style optional)
    let p: &dyn PaymentProvider = &provider;
    assert!(p.as_payment().is_none());
}
```

`MockPaymentProvider` does not implement `Payment` - this exercises the same invariant as Paddle. `StripeProvider` and `PaddleProvider` both pass the same flow against the live API in integration tests.

## Multi-provider apps

Register both adapters at boot and dispatch based on where each customer's record was created:

```rust,ignore
PaymentProviderRegistry::bind("stripe", Arc::new(stripe_provider));
PaymentProviderRegistry::bind("paddle", Arc::new(paddle_provider));

// Later, per request:
let provider_name = user.payment_provider.as_str(); // "stripe" or "paddle"
let provider = PaymentProviderRegistry::get(provider_name).expect("unknown provider");
let sub = provider.cancel(&sub_id, true).await?;
```

Common uses: route EU customers through Paddle (for MoR tax handling) and US customers through Stripe; A/B test checkout conversion between providers; use one provider for subscriptions and another for one-off charges.

## Migration from Laravel Cashier

Cashier is Stripe-only by design. Suprnova ships multi-provider out of the box. Quick mapping:

| Laravel Cashier | Suprnova |
|---|---|
| `$user->newSubscription('default', 'price_pro')->create()` | `provider.subscribe(SubscribeRequest { ... }).await` |
| `$user->subscription('default')->cancel()` | `provider.cancel(&sub_id, true).await` |
| `Cashier::webhookHandler` | `webhook_routes(db.clone())` |
| `$user->createAsStripeCustomer()` | `provider.create_customer(CreateCustomerRequest { ... }).await` |
| `$user->charge(1999, 'pm_...')` | `payment.charge(ChargeRequest { ... }).await` (if provider supports it) |
| `$invoice->download()` | Not built-in; read `provider_metadata["invoice_pdf_url"]` from the transactions mirror table |

## Next

- [Payments - Stripe Adapter](payments-stripe.md) - the gateway flow in detail: PaymentIntents, webhook signature format, event-type mapping
- [Payments - Paddle Adapter](payments-paddle.md) - the MoR flow in detail: checkout-driven subscription creation, tax handling, notification verification
- [Payments - Frontend Integration](payments-frontend.md) - Svelte 5, React 19, and Vue 3.5 dispatch-on-flow examples
- [Writing a Payment Provider Adapter](payments-provider-guide.md) - build your own adapter crate end to end
- [Database](database.md) - the SeaORM layer the mirror tables sit on


---

<!-- /docs/payments-stripe -->

# Payments - Stripe Adapter

`suprnova-payments-stripe` is the reference adapter for Suprnova's
provider-neutral payments surface. It implements all five payment traits
(`Checkout`, `Payment`, `Subscription`, `CustomerStore`, `WebhookHandler`)
against the Stripe API via `async-stripe` 1.0.0-rc.5. Reach for this
chapter when you need to know exactly which Stripe endpoint a method
calls, how the webhook signature format is verified, how PaymentIntents
flow through `ChargeResult`, or which event types map onto the neutral
event enum.

For the trait shapes themselves, env-var setup, and the bootstrap
pattern, read [Payments](payments.md) first. This chapter is the
Stripe-specific deep dive.

## Gateway, not Merchant of Record

Stripe is by default a **payment gateway**: you receive funds directly
into your own bank account, and you are responsible for tax collection
and remittance, invoicing, dunning, and chargeback handling. Contrast
with Paddle ([Payments - Paddle](payments-paddle.md)), where Paddle is
the Merchant of Record - they collect the funds, file the tax, and pay
you out net of fees.

The practical consequence for this chapter: `StripeProvider` implements
`Payment` (you can authorise, capture, refund, and void a card on the
server). `PaddleProvider` does not. The trait split exists because the
two flows are genuinely different - not because we ran out of time.

### Stripe Managed Payments (opt-in Merchant of Record)

Stripe's **Managed Payments** program moves Stripe into the Merchant of
Record seat for eligible transactions - Stripe becomes the legal seller,
calculates, collects, files, and remits sales tax/VAT/GST, and owns
disputes. The program has hard integration constraints:

- **Hosted Checkout only.** Sessions must run on Stripe's hosted page.
  Elements/custom flows are excluded - which is why the adapter's hosted
  one-off path (below) is the only `OneOff` shape that composes with it.
- **Predefined Prices with eligible tax codes.** Line items must
  reference `price_…` objects whose products carry a tax code labeled
  Managed-Payments-eligible in the Stripe dashboard. Ad-hoc amounts are
  rejected.
- **Account enrollment.** The Stripe account must be onboarded to the
  program; sessions carrying the flag on a non-enrolled account fail.

Enable it per provider with `.with_managed_payments(true)` or
`STRIPE_MANAGED_PAYMENTS=true` - the adapter then sends
`managed_payments[enabled]=true` when creating hosted one-off sessions.
When off (the default) the field is omitted entirely.

### Why Suprnova diverges

Laravel ships Cashier as a first-party Stripe integration in the core
docs. It is convenient, but Stripe-only - and adding a second provider
means either forking Cashier or building a parallel surface.

Suprnova keeps Stripe at arm's length. The Stripe adapter is one crate
that registers itself against the same five traits any other provider
implements. Your domain code never names `StripeProvider`; it calls
`provider.charge(...)` against `Arc<dyn PaymentProvider>` resolved from
the registry, and the Stripe behaviour is one swap-out from the Paddle
behaviour. When you later add Mollie, or wire up a regional gateway
that doesn't exist yet, you implement the same five traits and the
rest of your app does not move.

## Construction

```rust
use suprnova_payments_stripe::StripeProvider;
use std::sync::Arc;
use suprnova::payments::PaymentProviderRegistry;

// Production: read from env.
let stripe = StripeProvider::from_env()
    .expect("STRIPE_SECRET_KEY / PUBLISHABLE_KEY / WEBHOOK_SIGNING_SECRET");

// Tests / explicit config:
let stripe = StripeProvider::new(
    "sk_test_...",
    "pk_test_...",
    "whsec_...",
);

PaymentProviderRegistry::bind("stripe", Arc::new(stripe));
```

`StripeProvider` is `Clone` (cheap - the underlying `stripe::Client` is
`Arc`-backed) and holds these values:

| Field | Source | Use |
|---|---|---|
| `secret_key` | `sk_live_…` / `sk_test_…` | HTTP `Authorization: Bearer …` on every API call |
| `publishable_key` | `pk_live_…` / `pk_test_…` | Surfaced inside `SessionPayload::StripeElements` so the frontend can mount Stripe.js without a separate config lookup |
| `webhook_signing_secret` | `whsec_…` | HMAC-SHA256 verification of the `Stripe-Signature` header |
| `managed_payments` | `STRIPE_MANAGED_PAYMENTS` (`true`/`1`) or `.with_managed_payments(bool)` | Sends `managed_payments[enabled]=true` on hosted one-off session creation (see [Managed Payments](#stripe-managed-payments-opt-in-merchant-of-record)) |

`from_env()` returns `Result<Self, String>` - the error message names
the missing required variable (`STRIPE_MANAGED_PAYMENTS` is optional;
absent means off). There is no panic path at boot.

## Checkout sessions

`Checkout::start_session` picks its Stripe surface from the request:

| Request shape | Stripe object | `SessionPayload` variant |
|---|---|---|
| `OneOff` + non-empty `price_refs` | Hosted Checkout Session, `mode=payment` | `StripeCheckoutRedirect { url, provider_session_id: "cs_…" }` |
| `OneOff` + empty `price_refs` + `amount_hint` | PaymentIntent | `StripeElements { client_secret, publishable_key, provider_session_id: "pi_…" }` |
| `Subscription` + `price_refs` | Hosted Checkout Session, `mode=subscription` | `StripeCheckoutRedirect` |

The hosted one-off path sends `allow_promotion_codes=true` (customers
can enter promotion codes on Stripe's page - pair with the `Promotions`
trait below) and, when the provider is configured for it, the Managed
Payments flag. Put Stripe's `{CHECKOUT_SESSION_ID}` template literal in
your `success_return_url` - Stripe substitutes the real `cs_…` id on
redirect, and your return page feeds it to `session_status`.

Checkout metadata is attached to the Session and to the resulting
PaymentIntent (`payment_intent_data.metadata`) or Subscription
(`subscription_data.metadata`). Elements attaches it directly to the
PaymentIntent. As with customer metadata, strings pass through, non-string
values become JSON strings, and null values are omitted. Supply an object
with stable correlation identifiers.

`Checkout::session_status` retrieves `cs_` IDs from
`GET /v1/checkout/sessions/{id}` and maps them to `CheckoutSessionState`:

| Stripe `status` / `payment_status` | `CheckoutSessionState` |
|---|---|
| `open` | `Open` |
| `expired` | `Expired` |
| `complete` + `paid` or `no_payment_required` | `Complete { paid: true, payment_ref, amount_total }` |
| `complete` + `unpaid` (delayed settlement) | `Complete { paid: false, … }` |

For an Elements `pi_` ID, it retrieves `GET /v1/payment_intents/{id}`.
Only `succeeded` maps to `Complete { paid: true, ... }`; `canceled` maps to
`Expired`, and processing, authorization, and customer-action states remain
`Open`. Invalid IDs and provider errors return errors. A card authorization
that still requires capture does not count as a collected payment.

`payment_ref` carries the session's PaymentIntent id (`pi_…`) so return
pages and sweeps can correlate the session with `Payment` operations and
the `payments_transactions` mirror. `amount_total` is the settled total
with provider-side discounts and Managed-Payments tax already folded in.

## Promotion codes

`StripeProvider` implements the optional `Promotions` trait
(`provider.as_promotions()` returns `Some`). `create_promotion_code`
maps to `POST /v1/promotion_codes`: it mints a code off a pre-created
coupon (`coupon_ref`), restricted to one customer (`customer_ref`),
with an optional expiry and redemption cap. Restrictions are enforced
by Stripe at redemption - a code minted for customer A is rejected when
customer B types it, expired codes are rejected, and `max_redemptions:
Some(1)` makes the code single-use. See the `Promotions` section of
[Payments](payments.md) for the campaign pattern.

## The PaymentIntent lifecycle

Stripe represents a single charge attempt as a **PaymentIntent**. The
intent moves through statuses; the Suprnova `Payment` trait drives the
transitions. Every `StripeProvider` `Payment` method maps to one
`/v1/payment_intents/...` endpoint:

| `Payment` method | Stripe endpoint | What it does |
|---|---|---|
| `charge` | `POST /v1/payment_intents` | Create + confirm in one call against a saved payment method. `capture_method: "manual"` so the intent moves to `requires_capture`, **not** `succeeded`. |
| `capture` | `POST /v1/payment_intents/{id}/capture` | Settle a previously-authorised intent. Status `requires_capture` → `succeeded`. |
| `refund` | `POST /v1/refunds` | Fully or partially reverse a captured intent. |
| `void` | `POST /v1/payment_intents/{id}/cancel` | Release an authorisation before capture. Status `requires_capture` → `canceled`. |
| `status` | `GET /v1/payment_intents/{id}` | Retrieve the current status (returns `PaymentStatus`). |

### Authorise first, capture later

`StripeProvider::charge` does **not** immediately settle the funds.
It sends `capture_method=manual` + `confirm=true`, which authorises
the card and reserves the funds, then waits for an explicit `capture`
call. This is the canonical two-step flow:

```rust
use suprnova::payments::{
    PaymentProviderRegistry, ChargeRequest, ChargeResult,
    Money, Currency, PaymentStatus,
};

let provider = PaymentProviderRegistry::get("stripe").unwrap();
let payment = provider.as_payment()
    .expect("Stripe implements Payment");

let result = payment.charge(ChargeRequest {
    customer_ref: "cus_NffrFeUfNV2Hib".into(),
    payment_method_ref: "pm_card_visa".into(),
    amount: Money::from_minor_units(2999, Currency::USD),
    description: Some("Pro plan, manual capture".into()),
    idempotency_key: Some("order-12345".into()),  // see "Idempotency" below
    metadata: None,
}).await?;

match result {
    ChargeResult::Completed { provider_transaction_id, status, .. }
        if status == PaymentStatus::Pending => {
        // Authorised - settle when the order ships.
        let settled = payment.capture(&provider_transaction_id).await?;
        assert!(matches!(
            settled,
            ChargeResult::Completed { status: PaymentStatus::Succeeded, .. }
        ));
    }
    ChargeResult::RequiresClientAction { client_secret, .. } => {
        // 3DS step-up needed - see "3DS and SCA" below.
    }
    other => panic!("unexpected charge result: {other:?}"),
}
```

If you want **immediate** capture - the common e-commerce one-shot -
use `Checkout::start_session` with `SessionMode::OneOff` instead. That
path creates a PaymentIntent with `automatic_payment_methods` enabled
and hands the client secret to the frontend so the customer's browser
confirms the intent in-place. `Payment::charge` is for server-driven
flows where you already hold the customer's saved payment method and
want explicit authorise-then-capture control (typical for marketplaces,
delayed-fulfilment SaaS, or split-shipment commerce).

### Status mapping

Stripe statuses fold into Suprnova's `PaymentStatus` enum:

| `PaymentIntentStatus` | `PaymentStatus` |
|---|---|
| `Succeeded` | `Succeeded` |
| `Processing` | `Pending` |
| `RequiresCapture` | `Pending` (authorised, awaiting capture) |
| `RequiresAction` | `Pending` (returned as `RequiresClientAction` from `charge`) |
| `RequiresConfirmation` | `Pending` |
| `RequiresPaymentMethod` | `Pending` |
| `Canceled` | `Canceled` |
| _new Stripe status (enum is `#[non_exhaustive]`)_ | `Failed` |

The `non_exhaustive` fallback is intentional. Stripe occasionally adds
states (e.g. when introducing new payment method types). Surfacing them
as `Failed` is the conservative default - your app treats the charge
as not-yet-confirmed until you upgrade the adapter.

### 3DS and SCA

European Strong Customer Authentication, India's RBI rules, and
several other regulators require the cardholder to authenticate the
charge in a separate browser context. Stripe surfaces this as
`requires_action` with a `next_action` block.

`StripeProvider::charge` translates this into one of two
`ChargeResult` variants:

```rust
ChargeResult::RequiresClientAction {
    provider_transaction_id,   // pi_xxx - keep this around
    action_kind: "stripe_3ds", // Stripe-specific tag
    client_secret,             // hand to Stripe.js
    publishable_key,           // hand to Stripe.js
}
```

When the intent's `next_action` contains a redirect URL (some
authentication flows are URL-redirect rather than in-place modal),
the result is rewritten as:

```rust
ChargeResult::RedirectRequired {
    provider_transaction_id,
    url,                       // redirect the browser here
    return_to: None,
}
```

Your controller hands the `RequiresClientAction` payload to the
Inertia page; the frontend calls `stripe.confirmCardPayment(client_secret, ...)`
and the customer completes 3DS. When confirmation succeeds, Stripe
fires `payment_intent.succeeded` and the webhook route writes the
mirror row. See [Payments - Frontend Integration](payments-frontend.md)
for the Svelte / React / Vue snippets.

### Void vs refund

`void` releases an authorisation **before** capture; `refund` reverses
a captured payment. Calling `void` on a captured intent will fail -
Stripe rejects with a message containing `"already succeeded"` or
`"You cannot cancel"`, and the adapter surfaces that as
`PaymentError::Validation` so your handler can distinguish a
recoverable user error (use `refund` instead) from a true provider
outage. Any other failure is `PaymentError::Provider`.

```rust
let voided = payment.void("pi_3PNzj...").await;
match voided {
    Ok(()) => { /* authorisation released */ }
    Err(suprnova::payments::PaymentError::Validation(msg)) => {
        // Already captured - call refund instead.
        let refund = payment.refund(RefundRequest {
            provider_transaction_id: "pi_3PNzj...".into(),
            amount: None,           // full refund
            reason: Some("requested_by_customer".into()),
            idempotency_key: None,  // optional key forwarded in Idempotency-Key
        }).await?;
    }
    Err(e) => return Err(e.into()),
}
```

## Customers

`StripeProvider` implements `CustomerStore` against
`/v1/customers`. The adapter maps a returned `Customer` into the
neutral `CustomerRef`, preserving the email and your application's
`user_id`:

```rust
use suprnova::payments::CreateCustomerRequest;

let customer = provider.create_customer(CreateCustomerRequest {
    user_id: "user-42".into(),       // your app's user id
    email: "alice@example.com".into(),
    name: Some("Alice Example".into()),
    metadata: None,
}).await?;

// customer.provider_customer_id == "cus_NffrFeUfNV2Hib"
// Persist this alongside your User row so subsequent
// charges, subscriptions, and webhooks resolve back.
```

`update_customer`, `get_customer`, and `delete_customer` hit
`POST /v1/customers/{id}`, `GET /v1/customers/{id}`, and
`DELETE /v1/customers/{id}` respectively. Stripe's delete returns a
`DeletedCustomer` envelope which the adapter discards - only the
success/failure of the call is propagated.

## Subscriptions

`StripeProvider::subscribe` posts to `/v1/subscriptions` with the
customer ref, an `items[]` array, and an optional `trial_period_days`:

```rust
use suprnova::payments::{SubscribeRequest, SubscriptionStatus};

let sub = provider.subscribe(SubscribeRequest {
    customer_ref: "cus_NffrFeUfNV2Hib".into(),
    price_refs: vec!["price_pro_monthly".into()],
    trial_days: Some(14),
    idempotency_key: None,
    metadata: None,
}).await?;

assert!(matches!(
    sub.status,
    SubscriptionStatus::Trialing | SubscriptionStatus::Active
));

println!("Period ends at {}", sub.current_period_end);
for item in &sub.items {
    println!(
        "  {} × {} @ {:?}",
        item.quantity, item.provider_price_id, item.unit_amount,
    );
}
```

### Period boundaries

Stripe moved the `current_period_start` / `current_period_end`
timestamps from the parent Subscription onto each `SubscriptionItem`
in API version `2023-08-16`. Multi-item subscriptions can in theory
have divergent item periods, but in practice every item on a single
subscription shares the parent's billing cycle. The adapter takes the
**first item's** period as the parent period in the returned
`SubscriptionResult`. If you genuinely need per-item periods, read them
from `sub.items[n]` - they are preserved on the snapshot.

### Cancel at period end vs immediately

```rust
// Soft cancel - keep access until current_period_end:
let sub = provider.cancel("sub_1234", /* at_period_end */ true).await?;
// sub.cancel_at_period_end == true
// sub.status == Active

// Immediate cancel - Stripe DELETE /v1/subscriptions/{id}:
let sub = provider.cancel("sub_1234", /* at_period_end */ false).await?;
// sub.status == Canceled
```

The two paths hit different Stripe endpoints. Soft cancel is
`POST /v1/subscriptions/{id}` with `cancel_at_period_end=true` - the
subscription stays active until the end of the billing period, then
Stripe finalises it. Immediate cancel is `DELETE /v1/subscriptions/{id}`
with `prorate=false` and `invoice_now=false`.

### `update()` changes prices and the cancellation flag

`Subscription::update` acts on two fields of `UpdateSubscriptionRequest`:
`new_price_refs` and `cancel_at_period_end`. A third field, `proration`,
says how a price change is billed. With `new_price_refs: None` and
`cancel_at_period_end: Some(_)`, the adapter posts the flag to
`/v1/subscriptions/{id}` and nothing else.

`new_price_refs` is the set of prices the subscription has after the call:

- An item whose price is in the list keeps its id and its quantity.
- An item whose price is not in the list is removed.
- A price that has no item is added with a quantity of 1, except in a swap.
  When the change removes exactly one item and adds exactly one price, the new
  price takes the quantity of the removed item.
- An empty list, or a list that names a price twice, is
  `PaymentError::Validation`, and no request is sent.

```rust
use suprnova::payments::{Proration, UpdateSubscriptionRequest};

let sub = provider.update(UpdateSubscriptionRequest {
    provider_subscription_id: "sub_123".into(),
    new_price_refs: Some(vec!["price_team_yearly".into()]),
    proration: Some(Proration::ProrateNow),
    cancel_at_period_end: None,
    idempotency_key: Some("plan-change-42".into()),
}).await?;
// sub.items now holds one item, for price_team_yearly.
```

`proration` is read only when `new_price_refs` is `Some`. The adapter sends
it as the `proration_behavior` of the update:

| `proration` | Stripe `proration_behavior` |
|---|---|
| `None` or `Some(Proration::ProrateAtRenewal)` | `create_prorations` |
| `Some(Proration::ProrateNow)` | `always_invoice` |
| `Some(Proration::DoNotProrate)` | `none` |

The adapter reads the subscription first, because a Stripe update names the
item changes and not the final list. It then sends one
`POST /v1/subscriptions/{id}` with a delete for each item to remove and an
item for each new price, with the quantity that the swap rule gives. Items
that stay are not sent.
`cancel_at_period_end`, when set, goes in the same request. The
`idempotency_key` goes on that request only.

If the list names the prices the subscription has and `cancel_at_period_end`
is `None`, the adapter sends nothing and returns the subscription it read.

The change is computed from that read and is not atomic. A change made at
Stripe between the read and the write can be left in place, because the adapter
changes the items one by one.
A retry of a price change that already went through ends there.

`update` returns an error and sends nothing in these cases:

- The read of the subscription fails: `PaymentError::Provider`.
- The items of the subscription span more than one page of Stripe's list:
  `PaymentError::Provider`. The adapter cannot see every item, so it does not
  change any.
- The `idempotency_key` is blank or is not a valid header value:
  `PaymentError::Validation`.
- `proration` holds a variant the adapter has no Stripe behavior for:
  `PaymentError::NotSupported`.

## Webhooks

Stripe sends webhooks signed with HMAC-SHA256 in the format:

```
Stripe-Signature: t=1717000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

`StripeProvider::verify` parses the header, recomputes
HMAC-SHA256 over `"{timestamp}.{raw_body}"` using the webhook signing
secret, and does a **constant-time** comparison against every `v1=`
value in the header. Multiple `v1=` values exist during signing-secret
rotation - Stripe overlaps the old and new secrets for a window so
you can re-sign and deploy without a flag-day cutover.

```
Stripe-Signature: t=1717000000,v1=<old_sig>,v1=<new_sig>
```

The adapter accepts the request if **any** `v1=` value matches. A
header missing `t=` or with no `v1=` values is rejected as
`PaymentError::WebhookSignature`. Non-ASCII bytes anywhere in the
header are also rejected - Stripe never sends them, and treating them
as invalid is safer than substituting a replacement character.

You never call `verify` directly. The framework's
`webhook_routes(db.clone())` registers
`POST /webhooks/payments/{provider}` and invokes the adapter's
`verify` + `parse_event` + payload extractors for every request that
lands there. See [Idempotency](idempotency.md) for the retry-aware
audit behaviour - including the rule that previously-failed events
re-attempt hydration when the provider retries.

### Event → neutral mapping

Stripe event types map onto Suprnova's `NeutralEventKind` via the
`stripe_event_to_neutral` function. The mapping table:

| Stripe event type | `NeutralEventKind` |
|---|---|
| `payment_intent.succeeded` | `PaymentSucceeded` |
| `payment_intent.payment_failed` | `PaymentFailed` |
| `charge.refunded` | `PaymentRefunded` |
| `charge.dispute.created` | `PaymentDisputed` |
| `customer.subscription.created` | `SubscriptionCreated` |
| `customer.subscription.updated` | `SubscriptionUpdated` |
| `customer.subscription.deleted` | `SubscriptionCanceled` |
| `customer.subscription.paused` | `SubscriptionUpdated` |
| `customer.subscription.resumed` | `SubscriptionUpdated` |
| `customer.subscription.trial_will_end` | `SubscriptionUpdated` |
| `invoice.payment_succeeded` / `invoice.paid` | `InvoicePaid` |
| `invoice.payment_failed` | `InvoiceFailed` |
| `customer.created` | `CustomerCreated` |
| `customer.updated` | `CustomerUpdated` |
| _anything else_ | `None` |

Events that map to `None` (Radar fraud signals, payouts, balance
transfers, dispute lifecycle events past `created`) are still
persisted to the `payments_webhook_events` audit table - they just do
not drive the mirror tables. If you need them, read directly from
`event.raw_payload` in a custom handler.

The mapping is also re-exported at the crate root so you can use it
outside the webhook route:

```rust
use suprnova_payments_stripe::stripe_event_to_neutral;
use suprnova::payments::NeutralEventKind;

assert_eq!(
    stripe_event_to_neutral("payment_intent.succeeded"),
    Some(NeutralEventKind::PaymentSucceeded),
);
assert_eq!(
    stripe_event_to_neutral("radar.early_fraud_warning.created"),
    None,
);
```

### Payload extraction

After `verify` and `parse_event` succeed, the framework calls
`extract_payload_ids`, `extract_payment_snapshot`, and
`extract_customer_snapshot` to pull the fields that drive the mirror
tables (see [Eloquent](eloquent.md) for the underlying
read-from-your-own-DB pattern). Stripe is structurally consistent:
every webhook puts the relevant entity at `data.object`, with `id` as
its primary key.

The extractors handle four event families:

- **Subscription events** - pull `data.object.id` (the subscription
  id) and `data.object.customer`.
- **Customer events** - pull `data.object.id` (the customer id).
- **PaymentIntent / Charge events** - pull `data.object.id`,
  `data.object.amount`, `data.object.currency`, `data.object.customer`,
  and (for `payment_intent.succeeded` only) `data.object.created` as
  `paid_at`.
- **Invoice events** - pull `data.object.id`, the customer pointer,
  `data.object.subscription` (recurring charges only), `amount_paid`
  (falling back to `amount_due`), `tax`, `currency`, and
  `data.object.status_transitions.paid_at`.

Anything else returns `None` from the snapshot extractors; the audit
row still lands.

## Mirror tables

Six tables back the payments surface in your application's database.
Apply the framework migration alongside your own:

```rust
use sea_orm_migration::{MigrationTrait, MigratorTrait};
use suprnova::payments::migrations::CreatePaymentsTables;

pub struct Migrator;

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            // ... your migrations ...
            Box::new(CreatePaymentsTables),
        ]
    }
}
```

The tables created are `payments_customers`, `payments_payment_methods`,
`payments_subscriptions`, `payments_subscription_items`,
`payments_transactions`, and `payments_webhook_events`. The webhook
route hydrates them inside a single DB transaction per event - partial
state is never observable, and the audit row carries
`process_error` across retries so failures stay visible to operators.

## Idempotency

Outbound idempotency on Stripe API calls and inbound idempotency on
webhook deliveries are two separate stories. Read them as such.

### Outbound: per-method coverage

The adapter forwards a supplied `idempotency_key` in Stripe's
`Idempotency-Key` HTTP header for checkout (hosted and Elements), charge,
refund, subscription creation, and subscription update. Blank or invalid
header values fail before a request is sent. An absent key stays absent.

Persist a stable key per operation and reuse it with identical parameters
when retrying. A different operation needs a different key. Provider replay
retention is finite, so retain your own operation record and reconcile an
uncertain outcome before retrying outside that window.

### Error text

The text of a `PaymentError::Provider` that the adapter builds from an SDK
error names the operation, such as `stripe customers.retrieve`, and keeps only
the kind and the code of the Stripe error and the HTTP status. It carries no
id and no URL, so it is safe to log. An example is `stripe customers.retrieve:
api error invalid_request_error resource_missing, status 404`. An error that
is not an API error has a fixed text, such as `the request timed out`.

### Deadlines and unknown outcomes

Every call of the adapter to Stripe has a deadline of 30 seconds, from the
request to the whole answer. A call that runs out of time returns
`PaymentError::Provider`. The text depends on what the call does:

| Call | Error text |
|---|---|
| A read (`retrieve`) | `stripe <operation> timed out` |
| A call that changes something (create, update, capture, refund, cancel, delete) | `stripe <operation> timed out; outcome is unknown, reconcile before retrying` |

After a read times out, you can read again. After a change times out, Stripe
may have carried out the change, so the outcome is unknown. Read the object
at Stripe before you send the change again. You can also send it again with
the same `idempotency_key` and the same parameters: Stripe then returns the
result of the first attempt and does not repeat the change. That works only
for the calls that take a key (see the list above) and only while Stripe
keeps the key.

### Inbound: webhook deduplication

Webhook idempotency is handled by the framework on the ingress side
and is fully wired. Every event lands in `payments_webhook_events`
with a UNIQUE index on `(provider, provider_event_id)`. Duplicate
deliveries of an event that was already processed return 200 to
Stripe immediately without re-running hydration; duplicates of a
previously **failed** event re-attempt hydration so the provider's
retry is your recovery mechanism. See [Idempotency](idempotency.md)
for the full audit + retry contract.

## Testing

The adapter is hyper-backed and rustls-fronted. Tests that construct
a `StripeProvider` need a registered crypto provider; we install
`ring` exactly once in `#[cfg(test)]`:

```rust
#[cfg(test)]
mod tests {
    use suprnova_payments_stripe::StripeProvider;
    use std::sync::OnceLock;

    fn install_crypto_provider() {
        static ONCE: OnceLock<()> = OnceLock::new();
        ONCE.get_or_init(|| {
            let _ = rustls::crypto::ring::default_provider().install_default();
        });
    }

    fn provider() -> StripeProvider {
        install_crypto_provider();
        StripeProvider::new("sk_test_dummy", "pk_test_dummy", "whsec_dummy")
    }

    #[test]
    fn parses_subscription_webhook_ids() {
        let p = provider();
        let event = /* construct WebhookEvent with raw_payload */;
        let ids = p.extract_payload_ids(&event);
        assert_eq!(ids.subscription_id.as_deref(), Some("sub_abc"));
    }
}
```

For integration tests that hit the live Stripe sandbox, set
`STRIPE_SECRET_KEY` and friends in your test env. For unit tests of
your own controllers, prefer `MockPaymentProvider` from the framework -
it implements all five traits with predictable returns and zero
network.

## Next

- [Payments](payments.md) - the trait surface, the registry, the
  bootstrap pattern, and the flow-tagged `SessionPayload`.
- [Payments - Paddle](payments-paddle.md) - the Merchant-of-Record
  counterpart; same five traits, different responsibility split.
- [Payments - Provider Guide](payments-provider-guide.md) - how to
  write an adapter for a gateway Suprnova doesn't ship.
- [Payments - Frontend Integration](payments-frontend.md) - Svelte /
  React / Vue dispatch on `SessionPayload.flow`, including the
  Stripe.js confirm-card-payment loop.
- [Idempotency](idempotency.md) - the audit + retry contract that
  makes webhook handling safe under at-least-once delivery.
- [Eloquent](eloquent.md) - query the mirror tables alongside your
  own models; everything is just a SeaORM entity.


---

<!-- /docs/payments-paddle -->

# Payments - Paddle Adapter

The Paddle adapter (`suprnova-payments-paddle`) wires Paddle into Suprnova's
generic payments surface. Reach for it when you want a payment provider that
also handles sales tax, VAT, GST, dunning, invoicing, and refunds on your
behalf - Paddle is a Merchant of Record (MoR), which means it is the seller
of record to your customers and absorbs the compliance surface that a
direct-capture gateway like Stripe leaves to you.

That choice changes the mental model. Your domain code does not *own* the
subscription - Paddle does. You open a checkout, the customer completes it,
and the `SubscriptionCreated` webhook tells you the subscription now exists.
You cannot create a subscription via API. You can change its prices, you
can cancel it, and you can read its state. The rest is Paddle's.

This chapter assumes you've read [Payments](payments.md) for the generic
five-trait surface. Here we cover what is true *only* for Paddle.

## When to pick Paddle

Pick Paddle when one or more is true:

- You sell digital products globally and tax compliance (VAT, GST, US sales
  tax) is a real cost on your roadmap.
- You don't want to manage failed-payment retries, dunning emails, or
  receipt-issuing yourself.
- You want a single invoice from a single seller-of-record for accounting.
- Your business model is subscription-first, and you accept that the
  provider drives the subscription lifecycle.

Pick [Stripe](payments.md#stripe) instead when you want direct control over
charge capture, you handle your own tax, or you need server-side
`charge`/`capture`/`refund` calls from your own code paths.

## Setup

Add the crate:

```bash
cargo add suprnova-payments-paddle
```

Set the four environment variables:

```env
PADDLE_API_KEY=pdl_sdbx_apikey_...
PADDLE_WEBHOOK_KEY=pdl_ntfset_...
PADDLE_CLIENT_TOKEN=test_...
PADDLE_ENVIRONMENT=sandbox
```

| Variable | What it is | Where it comes from |
|---|---|---|
| `PADDLE_API_KEY` | Server-side API key (`pdl_live_apikey_…` / `pdl_sdbx_apikey_…`) | Paddle dashboard → Developer Tools → Authentication |
| `PADDLE_WEBHOOK_KEY` | Notification destination secret (`pdl_ntfset_…`) | Paddle dashboard → Developer Tools → Notifications → your endpoint |
| `PADDLE_CLIENT_TOKEN` | Browser-safe client token (`live_…` / `test_…`) | Paddle dashboard → Developer Tools → Authentication → Client-side tokens |
| `PADDLE_ENVIRONMENT` | `sandbox` (default) or `production` | Your call |

Register the provider at bootstrap. Both forms are valid:

```rust
use std::sync::Arc;
use suprnova::payments::PaymentProviderRegistry;
use suprnova_payments_paddle::{PaddleEnvironment, PaddleProvider};

pub async fn bootstrap() {
    // From env (recommended):
    let paddle = PaddleProvider::from_env()
        .expect("Paddle env vars not set");

    // Or construct directly:
    let paddle = PaddleProvider::new(
        "pdl_sdbx_apikey_...",
        "pdl_ntfset_...",
        "test_...",
        PaddleEnvironment::Sandbox,
    ).expect("Paddle client init failed");

    PaymentProviderRegistry::bind("paddle", Arc::new(paddle));
}
```

The webhook ingress route is registered by the framework's
`webhook_routes(db.clone())` helper - see [Payments](payments.md#webhook-handling).
Both `from_env()` and `new()` return `Result` because the underlying
`paddle_rust_sdk::Paddle::new` validates the API key shape and the
endpoint URL at construction time.

## The MoR mental model

The shape that surprises Stripe users:

```
Stripe (gateway):
    your app  ─────────►  Stripe  ──►  card network
       │                    ▲
       └────── webhook ─────┘
    you own the subscription state in your DB; Stripe is the executor

Paddle (Merchant of Record):
    your app  ─►  checkout link  ─►  customer  ──►  Paddle  ──►  card network
                                                       │
       ◄──────────────────  webhook  ──────────────────┘
    Paddle owns the subscription state; your DB is the mirror
```

In code, the difference shows up at two points:

1. **You cannot create a subscription via API.** Call `Checkout::start_session`
   with a recurring price; the customer completes the Paddle widget; the
   `SubscriptionCreated` webhook hydrates your mirror.
2. **You cannot delete a customer.** Archive the customer with
   `PaddleProvider::archive_customer` instead.

Suprnova surfaces these constraints as `PaymentError::NotSupported` rather
than papering over them - see the [capability matrix](#capability-matrix)
below.

## Checkout flow

`Checkout::start_session` is the only way to start a payment with Paddle.
The frontend opens the resulting `transaction_id` with paddle.js using the
`client_token` you set at bootstrap:

```rust
use std::sync::Arc;
use suprnova::payments::*;

pub async fn start_checkout(
    user_id: String,
    email: String,
) -> PaymentResult<SessionPayload> {
    let provider = PaymentProviderRegistry::get("paddle")
        .expect("paddle provider not registered");

    // 1. Create the customer in Paddle (or reuse an existing one).
    let cus = provider.create_customer(CreateCustomerRequest {
        user_id: user_id.clone(),
        email,
        name: None,
        metadata: None,
    }).await?;

    // 2. Open a checkout session. Paddle dispatches one-off vs subscription
    //    on the *price kind*, not on the SessionMode field below.
    let session = provider.start_session(StartSessionRequest {
        mode: SessionMode::Subscription,           // ignored by Paddle (see note)
        customer_ref: cus.provider_customer_id,
        price_refs: vec!["pri_pro_monthly".into()],
        success_return_url: "https://app.example/billing/success".into(),
        cancel_return_url: "https://app.example/billing/cancel".into(),
        amount_hint: None,
        idempotency_key: None, // Paddle rejects client-supplied keys.
        metadata: None,
    }).await?;

    Ok(session)
}
```

The returned `SessionPayload::PaddleInline` carries everything the frontend
needs. The transaction already contains the customer ID. `customer_token`
is `None`: a `ctm_` identifier is not a Paddle customer authentication token.

```json
{
  "flow": "paddle_inline",
  "transaction_id": "txn_01h...",
  "customer_token": null,
  "client_token": "test_..."
}
```

See [Payments - Frontend Integration](payments-frontend.md) for the
paddle.js mounting code in Svelte / React / Vue.

### Paddle dispatches on price kind, not `SessionMode`

A genuine Paddle-specific gotcha: the `SessionMode::OneOff` /
`SessionMode::Subscription` field on `StartSessionRequest` is **ignored by
the Paddle adapter**. Paddle's API has a single `transaction_create`
endpoint, and the provider inspects the supplied price IDs to infer the
flow - a recurring price starts a subscription, a one-off price starts a
single charge. With Stripe the field drives the flow; with Paddle the
*price* does. Set up your Paddle catalog with the correct price kinds
before pointing the adapter at them.

### Correlation and recovery

`metadata` is forwarded as transaction `custom_data` using the adapter's
existing string-map policy: strings pass through, other non-null values
become JSON strings, and null values are omitted. Supply an object with your
checkout-attempt and domain identifiers. The pinned SDK accepts string maps,
so nested JSON values do not retain their original type.

Paddle copies custom data from a checkout transaction to its subscription
and renewal transactions. An attempt identifier on a later payment therefore
does not prove that it is the original checkout payment.

`session_status(transaction_id)` reads the transaction from Paddle:

| Paddle status | `CheckoutSessionState` |
|---|---|
| `draft`, `ready`, `billed`, `past_due` | `Open` |
| `paid`, `completed` | `Complete { paid: true, payment_ref, amount_total }` |
| `canceled` | `Expired` |

`payment_ref` is the transaction ID; the amount comes from
`details.totals.total` in minor units. Invalid totals or provider errors
return an error. `paid` confirms collection but may precede subscription
creation; wait for the subscription webhook or retrieve the subscription
before claiming that subscription setup is complete.

Paddle rejects a supplied `idempotency_key` before network I/O. Save the
transaction ID as soon as creation succeeds. If the create response is lost,
reconcile provider state before creating another transaction. Metadata is
for correlation and does not make repeated creates idempotent. A create that
runs out of time leaves the provider outcome unknown; it does not prove that
no transaction exists. See [Deadlines and unknown outcomes](#deadlines-and-unknown-outcomes).

## Subscriptions arrive via webhook

Because Paddle owns the subscription lifecycle, your domain code only
*learns* about a subscription when Paddle tells you. The flow:

```
your app                        Paddle                    customer
   │                              │                          │
   │  start_session(price=pri_…)  │                          │
   ├─────────────────────────────►│                          │
   │  PaddleInline { txn_id, … }  │                          │
   │◄─────────────────────────────┤                          │
   │                              │       paddle.js          │
   │                              │◄─────────────────────────┤
   │                              │   complete checkout      │
   │                              ├─────────────────────────►│
   │                              │                          │
   │   subscription.created webhook                          │
   │◄─────────────────────────────┤                          │
   │                              │                          │
   ▼                              │                          │
 mirror tables hydrated;          │                          │
 payments_subscriptions row       │                          │
 has provider_subscription_id     │                          │
```

The framework's `webhook_routes(db)` handler does the hydration for you:
it calls `WebhookHandler::extract_payload_ids` to find the
`subscription_id`, calls `Subscription::get(id)` to read the canonical
state, and upserts `payments_subscriptions` + `payments_subscription_items`
inside one transaction. By the time the webhook returns 200, your mirror
is consistent with Paddle.

There is a brief window between the customer completing the widget and
the webhook arriving in which `payments_subscriptions` has no row for
the new subscription. Two patterns cover it:

- **Show a pending state after checkout.** Configure the return navigation
  in Paddle.js; the adapter does not forward `success_return_url` or
  `cancel_return_url` to the transaction API. A browser callback is not
  proof of payment or an active subscription.
- **Poll server state.** Use `session_status` to verify collection, and read
  the hydrated subscription mirror before showing subscription access.

## Capability matrix

Not every method on every trait does what its Stripe equivalent does. The
table below is the truth. `subscribe()` and `delete_customer()` are the
only methods that *always* fail; the rest work, with the noted caveats.

| Trait method | Behavior |
|---|---|
| `Checkout::start_session` | Dispatches on price kind; forwards metadata; rejects a supplied idempotency key. |
| `Checkout::session_status` | Retrieves the transaction and reports collection state. |
| `Subscription::subscribe` | Always `NotSupported`. Subscriptions are born from checkout completion + webhook. |
| `Subscription::update(cancel_at_period_end: Some(true), new_price_refs: None)` | Works. Wires to `subscription_cancel` with `effective_from` set to `next_billing_period`. A supplied `idempotency_key` is `NotSupported`. |
| `Subscription::update(cancel_at_period_end: Some(false), new_price_refs: None)` | `NotSupported`. The adapter cannot rescind a scheduled cancellation. |
| `Subscription::update(new_price_refs: Some(...))` | Works. Replaces the subscription's items with the new prices, billed as `proration` says. With `cancel_at_period_end` or an `idempotency_key`, `NotSupported`. See [Change the prices of a subscription](#change-the-prices-of-a-subscription). |
| `Subscription::update` (no-op) | Works. Re-fetches current state via `subscription_get`. |
| `Subscription::cancel(id, true)` | Works. Cancels at the end of the billing period. See [below](#cancel-at-the-period-end-or-at-once). |
| `Subscription::cancel(id, false)` | Works. Cancels at once. See [below](#cancel-at-the-period-end-or-at-once). |
| `Subscription::get` | Works. |
| `CustomerStore::create_customer` | Works. |
| `CustomerStore::update_customer` | Works. |
| `CustomerStore::get_customer` | Works. |
| `CustomerStore::delete_customer` | `NotSupported`. Archive with `PaddleProvider::archive_customer`. |
| `Payment::*` | Trait is not implemented. `provider.as_payment()` returns `None`. |
| `WebhookHandler::*` | Works. |

The invariants `Payment` not being implemented, `subscribe`/`delete_customer`
returning `NotSupported`, and webhook signature rejection are pinned by
always-on tests in `crates/suprnova-payments-paddle/tests/integration.rs`,
so the matrix above won't drift silently.

### Cancel at the period end or at once

`Subscription::cancel(id, at_period_end)` follows the flag:

- `true` sends `subscription_cancel` with `effective_from` set to
  `next_billing_period`. The subscription stays `Active` with
  `cancel_at_period_end == true`, and the user keeps access until the
  current billing period ends. Then Paddle fires `subscription.canceled`
  and the mirror flips `status` to `Canceled`.
- `false` cancels at once. The adapter makes two requests. It reads the
  subscription with `subscription_get`, then sends `subscription_cancel` with
  `effective_from` set to `immediately`. If the read fails, the adapter
  returns the error and cancels nothing. The result has `status == Canceled`,
  `cancel_at_period_end == false`, and the billing period the subscription
  was in.

```rust
let sub = provider.cancel("sub_123", /* at_period_end */ true).await?;
// sub.status == Active, sub.cancel_at_period_end == true

let sub = provider.cancel("sub_123", /* at_period_end */ false).await?;
// sub.status == Canceled
```

`update` with `cancel_at_period_end: Some(true)` sends the same request as
`cancel(id, true)`.

### Change the prices of a subscription

`Subscription::update` with `new_price_refs` changes the prices of a
subscription. The list is the set of prices the subscription has after the
call:

- An item whose price is in the list keeps its quantity.
- An item whose price is not in the list is removed.
- A price that has no item is added with a quantity of 1, except in a swap.
  When the change removes exactly one item and adds exactly one price, the new
  price takes the quantity of the removed item.
- An empty list, or a list that names a price twice, is
  `PaymentError::Validation`, and no request is sent.

```rust
use suprnova::payments::{Proration, UpdateSubscriptionRequest};

let sub = provider.update(UpdateSubscriptionRequest {
    provider_subscription_id: "sub_123".into(),
    new_price_refs: Some(vec!["pri_pro_yearly".into()]),
    proration: Some(Proration::ProrateAtRenewal),
    cancel_at_period_end: None,
    idempotency_key: None, // Paddle rejects a key for a price change.
}).await?;
```

Paddle takes the complete list of items with a quantity for each. So the
adapter reads the subscription with `subscription_get` first, then sends one
`subscription_update` request with the items in the order of your list and a
`proration_billing_mode`. If the read fails, nothing is sent. If the list
names the prices the subscription already has, the adapter sends no update
and returns the subscription it read.

The change is computed from that read and is not atomic. Because the adapter
sends the whole list of items, a change made at Paddle between the read and
the write can be undone.

`proration` says how the change is billed. It is read only when
`new_price_refs` is `Some`:

| `proration` | Paddle `proration_billing_mode` |
|---|---|
| `None` or `Some(Proration::ProrateAtRenewal)` | `prorated_next_billing_period` |
| `Some(Proration::ProrateNow)` | `prorated_immediately` |
| `Some(Proration::DoNotProrate)` | `do_not_bill` |

Two combinations are `PaymentError::NotSupported`, and no request is sent:

- A price change together with `cancel_at_period_end: Some(_)`. Paddle
  schedules a cancellation through its own endpoint, so the two changes cannot
  be one request. Send them as two updates.
- A price change with an `idempotency_key`. The adapter cannot forward the
  key to Paddle.

An item quantity that Paddle reports outside the range of `u32` is a
`PaymentError::Provider` error, and nothing is sent.

### Error text

The text of a `PaymentError::Provider` that the adapter builds from an SDK
error names the operation, such as `paddle customer_get`. It keeps the type
and the code of a Paddle API error, and a transport error without its URL. It
carries no id and no URL, so it is safe to log. An error of another kind has a
fixed text, such as `response body is not the expected JSON`.

### Deadlines and unknown outcomes

Every call of the adapter to Paddle has a deadline of 30 seconds, from the
request to the whole answer. A call that runs out of time returns
`PaymentError::Provider`. The text depends on what the call does:

| Call | Error text |
|---|---|
| A read (`subscription_get`, `customer_get`, `transaction_get`) | `paddle <operation> timed out` |
| A call that changes something (`transaction_create`, `subscription_update`, `subscription_cancel`, `customer_create`, `customer_update`) | `paddle <operation> timed out; outcome is unknown, reconcile before retrying` |

After a read times out, you can read again. After a change times out, Paddle
may have carried out the change, so the outcome is unknown. Read the state at
Paddle before you send the call again: `Subscription::get` for a
subscription, `CustomerStore::get_customer` for a customer, `session_status`
for a transaction.

The adapter has no idempotency key to retry under. It rejects a supplied
`idempotency_key` on `start_session`, on a price change, and on `update` with
`cancel_at_period_end: Some(true)`, and `CreateCustomerRequest`, `update_customer`
and `cancel` have no key field. A retry of a change that timed out can repeat it.

### Customer deletion is "archive"

`delete_customer` returns `PaymentError::NotSupported` because Paddle's
public API does not expose a delete endpoint at all. Archiving is Paddle's
only way to take a customer out of use, and the Paddle provider exposes it
directly:

```rust
paddle.archive_customer("ctm_123").await?;
```

`archive_customer(provider_customer_id)` sends the customer's `status` as
`archived` and nothing else, so the name, email and `custom_data` of the
customer stay as they are. The customer keeps its history and can't be used
for new checkouts. A customer that Paddle does not know is
`PaymentError::NotFound`. Any other Paddle error is `PaymentError::Provider`.
The call has the deadline of every call of the adapter and is a change: see
[Deadlines and unknown outcomes](#deadlines-and-unknown-outcomes).

Don't try to archive through `update_customer`'s `metadata`: that field is
Paddle's `custom_data`, so a `"status"` key there is stored as data and
changes nothing.

#### Reach the Paddle provider

`archive_customer` is a method of `PaddleProvider`, not of a payments trait,
so `PaymentProviderRegistry::get("paddle")` cannot give it to you: it returns
an `Arc<dyn PaymentProvider>`. Keep the concrete provider. Bind the same
`Arc` in the registry and in the container when you bootstrap:

```rust
use std::sync::Arc;
use suprnova::App;
use suprnova::payments::PaymentProviderRegistry;
use suprnova_payments_paddle::PaddleProvider;

pub async fn bootstrap() {
    let paddle = Arc::new(PaddleProvider::from_env().expect("Paddle env vars not set"));
    PaymentProviderRegistry::bind("paddle", paddle.clone());
    App::bind::<PaddleProvider>(paddle);
}
```

Then resolve it where you archive:

```rust
let paddle = App::make::<PaddleProvider>().expect("PaddleProvider not bound");
paddle.archive_customer("ctm_123").await?;
```

## Webhook signature verification

Paddle signs every webhook with HMAC. The `Paddle-Signature` header looks
like `ts=1716000000,h1=abcdef…`. The adapter delegates verification to
`Paddle::unmarshal` from the SDK, which:

- Parses the header
- Recomputes the HMAC using your `PADDLE_WEBHOOK_KEY`
- Rejects signatures whose timestamp is outside `MaximumVariance::default()`
  (5 seconds in paddle-rust-sdk 0.18, the version the adapter pins - replays older than that are dropped)

The framework's `webhook_routes` handler calls `verify` before doing
anything else; a failure returns `401 invalid-signature` with no body
leak. You don't write any of this code yourself, but it's worth knowing
the verification is HMAC + timestamp-tolerance, not a static secret
compare.

## Webhook payload shape

The adapter's `extract_payload_ids`, `extract_payment_snapshot`, and
`extract_customer_snapshot` methods know Paddle's payload shape so the
framework can hydrate mirror tables. Quick mapping:

| Webhook event_type | `NeutralEventKind` | Mirror effect |
|---|---|---|
| `transaction.completed`, `transaction.paid` | `PaymentSucceeded` | Upsert `payments_transactions` |
| `transaction.payment_failed` | `PaymentFailed` | Upsert `payments_transactions` (failed) |
| `transaction.billed` | `None` | Invoice issuance only; no paid mirror update |
| Approved refund adjustment | `PaymentRefunded` | Update the referenced transaction as refunded |
| Approved chargeback or chargeback warning adjustment | `PaymentDisputed` | Update the referenced transaction as disputed |
| Pending/rejected refund, credit, or reversal adjustment | `None` | Raw provider event only |
| `subscription.created` | `SubscriptionCreated` | `Subscription::get` → upsert `payments_subscriptions` + items |
| `subscription.updated`, `.activated`, `.paused`, `.resumed`, `.trialing` | `SubscriptionUpdated` | Same as above |
| `subscription.canceled` | `SubscriptionCanceled` | Same; sets `canceled_at`, flips status |
| `customer.created` | `CustomerCreated` | Update-only: refreshes `email`/`metadata` if the mirror row exists |
| `customer.updated` | `CustomerUpdated` | Same |
| anything else | `None` (unmapped) | Audit row only - no mirror change |

Paddle puts the entity object directly under `data` (not `data.object` like
Stripe). Amounts arrive as **strings of minor units** (`"1234"` = 12.34 in
the major unit), not decimals - the adapter parses both string and
numeric shapes for forward-compatibility. The snapshot upper-cases
`currency_code`. Payment time comes from the latest captured payment attempt;
if none has a capture timestamp, `paid_at` stays absent. `billed_at` is invoice
issuance time and is never used as payment time.

The event-name-only `paddle_event_to_neutral` helper returns `None` for
adjustments because approval status and action require the payload. Use
`WebhookHandler::parse_event` for their classification. Raw reversal events
remain available to application reconciliation; they do not imply a new
payment or refund.

### Inclusive-tax amounts

Paddle reports transaction amounts **inclusive of tax**. The framework's
`payments_transactions` mirror splits this:

- `amount_total_minor` - the full amount the customer paid (tax included)
- `amount_tax_minor` - the tax component

Net of tax is `amount_total_minor - amount_tax_minor`. This differs from
Stripe (which reports exclusive of tax with `amount_tax_minor = 0`). Code
that sums revenue across both providers needs to be tax-aware:

```rust
let net_revenue_minor = txn.amount_total_minor - txn.amount_tax_minor;
```

## Customer creation

`CreateCustomerRequest` maps directly to Paddle's `customer_create`:

```rust
let cus = provider.create_customer(CreateCustomerRequest {
    user_id: "user_42".into(),       // your app's user id
    email: "alice@example.com".into(),
    name: Some("Alice".into()),
    metadata: None,                  // optional custom_data string map
}).await?;
// cus.provider_customer_id == "ctm_01h..."
```

Store `cus.provider_customer_id` alongside your user record. Every
subsequent call (start a checkout, look up a subscription, etc.) takes
the Paddle customer ID, not the app's user ID. The mirror table
`payments_customers` carries both columns so a single index lookup gets
you either direction.

`update_customer` and `get_customer` pass through to the equivalent SDK
methods. `update_customer` accepts `email` / `name` updates and returns
the refreshed `CustomerRef`. `get_customer` fetches a snapshot from
Paddle (not from the mirror) - use this when you need a fresh read after
an out-of-band change in the Paddle dashboard.

## The intentional `NotSupported` shape

A reader unfamiliar with the codebase might assume `PaymentError::NotSupported`
on `subscribe()` and `delete_customer()` is a deferred TODO. It is not.
The constraints are part of Paddle's product surface, and Suprnova
encodes them rather than emulating local mutations the provider will
never honor.

Each `NotSupported` error message points at the supported workflow:

- `subscribe`: "use `Checkout::start_session` with `SessionMode::Subscription`
  and await the `SubscriptionCreated` webhook"
- `delete_customer`: "archive with `PaddleProvider::archive_customer`"

Branch on this error explicitly when you're writing provider-agnostic
domain code:

```rust
match provider.delete_customer(&cus_id).await {
    Ok(()) => { /* Stripe path */ }
    Err(PaymentError::NotSupported(_)) => {
        // Paddle path - archive instead. `paddle` is the concrete
        // provider, see "Reach the Paddle provider" above.
        paddle.archive_customer(&cus_id).await?;
    }
    Err(e) => return Err(e),
}
```

### Why Suprnova diverges

Laravel Cashier is Stripe-only and models subscriptions as
app-owned: `$user->newSubscription('default', 'pri_pro')->create()` is
shaped as if the application is initiating the subscription. With a
direct-capture gateway that's accurate. With an MoR, it's a lie - the
provider is the actor, not your app.

Suprnova's payments surface is provider-neutral, so it doesn't take a
side. The trait surface (`subscribe`, `update`, `cancel`, `get`) is the
generic shape; each adapter implements what its provider exposes and
returns `NotSupported` where the provider's product model differs. The
Stripe adapter implements `subscribe`. The Paddle adapter does not,
because Paddle does not let it. Hiding the difference behind a fake
local "create" would have the adapter lie to you - Suprnova prefers
the typed `NotSupported` with a migration message in the error string.

The same divergence applies to `Payment` (server-side capture). Stripe
implements it; Paddle does not, and `provider.as_payment()` returns
`None`. Code that needs charge/capture/refund must check
`as_payment().is_some()` rather than calling blindly - see
[Payments](payments.md#payment---optional-server-side-capture).

## Testing your integration

The crate includes always-on invariant tests (no network access needed)
plus an env-gated integration test against Paddle's sandbox API:

```bash
# Always-on invariants (signature rejection, NotSupported shapes):
cargo test -p suprnova-payments-paddle

# Plus sandbox integration (requires PADDLE_API_KEY etc.):
PADDLE_API_KEY=pdl_sdbx_apikey_... \
PADDLE_WEBHOOK_KEY=pdl_ntfset_... \
PADDLE_CLIENT_TOKEN=test_... \
PADDLE_ENVIRONMENT=sandbox \
  cargo test -p suprnova-payments-paddle
```

The invariant tests are the ones to mirror in your own code if you build
adapter-specific abstractions. Three test shapes worth copying:

```rust
use suprnova::payments::*;
use suprnova_payments_paddle::{PaddleEnvironment, PaddleProvider};

#[test]
fn paddle_does_not_implement_payment_trait() {
    let p = PaddleProvider::new(
        "pdl_sdbx_apikey_test",
        "pdl_ntfset_test",
        "test_client",
        PaddleEnvironment::Sandbox,
    ).expect("provider construction");
    assert!(p.as_payment().is_none());
}

#[tokio::test]
async fn paddle_subscribe_returns_not_supported() {
    let p = /* ...as above... */;
    let err = p.subscribe(SubscribeRequest {
        customer_ref: "ctm_test".into(),
        price_refs: vec!["pri_test".into()],
        trial_days: None,
        idempotency_key: None,
        metadata: None,
    }).await.unwrap_err();
    assert!(matches!(err, PaymentError::NotSupported(_)));
}

#[test]
fn webhook_verify_rejects_bad_signature() {
    let p = /* ...as above... */;
    let mut headers = http::HeaderMap::new();
    headers.insert("paddle-signature", "ts=1234,h1=deadbeef".parse().unwrap());
    let ctx = WebhookContext {
        body: b"{}",
        headers: &headers,
        remote_addr: None,
    };
    assert!(matches!(p.verify(&ctx).unwrap_err(), PaymentError::WebhookSignature(_)));
}
```

For local end-to-end testing without hitting Paddle at all, the framework
ships `MockPaymentProvider`. Like Paddle, the mock's `as_payment()`
returns `None` (no server-side capture), so code that branches on
`as_payment().is_some()` follows the same path under the mock as it will
under Paddle. The mock's `subscribe()` returns `Ok` (unlike Paddle), so
tests that need to assert the `NotSupported` branch should use the real
`PaddleProvider`. Bind the mock in tests instead of the real provider:

```rust
use std::sync::Arc;
use suprnova::payments::{MockPaymentProvider, PaymentProviderRegistry};

#[suprnova_test]
async fn checkout_flow() {
    PaymentProviderRegistry::bind("paddle", Arc::new(MockPaymentProvider::new()));
    // ...exercise your controller against the mock...
}
```

## Production checklist

Before flipping `PADDLE_ENVIRONMENT=production`:

- [ ] All four env vars are set in production secrets, not committed
- [ ] The webhook endpoint URL is registered in the Paddle dashboard
  *Notifications* settings, and the destination secret you generated
  there matches `PADDLE_WEBHOOK_KEY`
- [ ] The catalog has live (not sandbox) price IDs, and the IDs you
  reference in `price_refs` exist in the live catalog
- [ ] Your `success_return_url` and `cancel_return_url` point at HTTPS
  endpoints (Paddle rejects HTTP in production)
- [ ] You've decided how your app responds when `subscribe()`,
  `delete_customer()`, or a price change with `cancel_at_period_end` or an
  `idempotency_key` return `NotSupported` - either branch in code or document
  that those flows are MoR-only
- [ ] You've decided what your app does when a change times out with an
  unknown outcome: read the state at Paddle before you send the call again
- [ ] You've stress-tested the cancellation UX: `cancel(id, true)` schedules
  the cancellation, so "you cancelled but you still have access until DATE"
  is the message your UI should show for it
- [ ] You've stress-tested the subscription-arrival webhook: there is a
  window where the customer has paid but the mirror has no row yet
- [ ] You're aggregating revenue correctly: Paddle amounts are
  tax-inclusive, Stripe amounts are tax-exclusive

## Next

- [Payments](payments.md) - the generic five-trait surface and the
  webhook handler's mirror-hydration contract
- [Payments - Frontend Integration](payments-frontend.md) - paddle.js
  inline checkout in Svelte / React / Vue
- [Payments - Provider Guide](payments-provider-guide.md) - write your
  own adapter crate end-to-end
- [Configuration](configuration.md) - typed config registration the
  Paddle env vars plug into
- [Application Bootstrap](bootstrap.md) - where
  `PaymentProviderRegistry::bind` actually lives in your app


---

<!-- /docs/payments-nowpayments -->

# Payments - NOWPayments

The `suprnova-payments-nowpayments` adapter creates hosted invoices, verifies
payment notifications, and reads payment status using the merchant API key.
It registers as `nowpayments` in the normal payment-provider registry.

## Install and configure

Use a Suprnova revision that contains this adapter for both dependencies. For a
local application beside a Suprnova source checkout:

```toml
[dependencies]
suprnova = { path = "../suprnova/framework" }
suprnova-payments-nowpayments = { path = "../suprnova/crates/suprnova-payments-nowpayments" }
serde_json = "1"
```

Configure these values in the application's protected environment:

```dotenv
NOWPAYMENTS_ENVIRONMENT=sandbox
NOWPAYMENTS_API_KEY=your-sandbox-api-key
NOWPAYMENTS_IPN_SECRET=your-sandbox-ipn-secret
NOWPAYMENTS_IPN_CALLBACK_URL=https://app.example/webhooks/payments/nowpayments
```

The environment accepts `sandbox` or `production` and defaults to `sandbox`.
An unknown or blank environment fails configuration. Blank credentials fail
before HTTP requests. Use separate credentials for each environment.

Register the provider during boot, propagating a configuration error:

```rust,no_run
use std::sync::Arc;
use suprnova::payments::{PaymentProviderRegistry, PaymentResult};
use suprnova_payments_nowpayments::NowPaymentsProvider;

fn register_nowpayments() -> PaymentResult<Arc<NowPaymentsProvider>> {
    let provider = Arc::new(NowPaymentsProvider::from_env()?);
    PaymentProviderRegistry::bind("nowpayments", provider.clone());
    Ok(provider)
}
```

Add the payment migrations and compose `webhook_routes(db)` into the application's
router as shown in the [payments overview](payments.md). The endpoint is
`POST /webhooks/payments/nowpayments`. Keep this provider-authenticated route
outside browser-session CSRF middleware. Configure the callback with the exact
public HTTPS URL; request bodies must reach the adapter unchanged.

## Start a hosted invoice

Persist a checkout attempt with a unique merchant order reference before making
the request. The amount comes from the application's trusted order, never from
a browser-supplied total.

```rust,no_run
use suprnova::payments::{Money, SessionMode, StartSessionRequest};
use suprnova_payments_nowpayments::{InvoiceCreationError, NowPaymentsInvoice, NowPaymentsProvider};
use serde_json::json;

async fn create_order_invoice(
    provider: &NowPaymentsProvider,
    order_id: String,
    amount: Money,
) -> Result<NowPaymentsInvoice, InvoiceCreationError> {
    provider.create_invoice(StartSessionRequest {
        mode: SessionMode::OneOff,
        customer_ref: String::new(),
        price_refs: Vec::new(),
        amount_hint: Some(amount),
        success_return_url: "https://app.example/billing/return".into(),
        cancel_return_url: "https://app.example/billing/cancel".into(),
        idempotency_key: None,
        metadata: Some(json!({"order_id": order_id})),
    }).await
}
```

`Checkout::start_session` accepts the same request and returns the generic
`SessionPayload::Redirect`. Store its `provider_session_id` as an **invoice ID**,
then redirect to its validated URL. The concrete `create_invoice` method also
returns the merchant order reference and distinguishes uncertain creation errors.

The invoice adapter requires one-off mode, empty customer/price references, and
a positive `Money` amount with a defined fiat currency exponent. It sends the
exact major-unit decimal amount and lowercase currency code. Customers select a
crypto currency on the hosted page unless `pay_currency` is supplied.

Metadata is a strict object with these fields:

| Field | Meaning |
| --- | --- |
| `order_id` | Required nonblank merchant reference, at most 128 bytes |
| `order_description` | Optional description, at most 500 bytes |
| `pay_currency` | Optional lowercase provider ticker, such as `btc` |
| `is_fixed_rate` | Optional provider exchange-rate setting |
| `is_fee_paid_by_user` | Optional provider fee setting |

Unknown metadata keys are rejected. Do not put arbitrary application or customer
data into this object. Return URLs must use the same HTTPS origin as the callback,
without credentials or fragments. Invoice redirects must target the selected
NOWPayments environment and contain the returned invoice ID.

## Creation failures and retries

NOWPayments' invoice endpoint does not document an idempotency-key guarantee.
The adapter rejects a non-`None` `idempotency_key`; `order_id` is correlation data,
not provider-side deduplication. Neither HTTP redirects nor automatic retries
are enabled. Requests have a 30-second deadline and a 64 KiB response limit.

`InvoiceCreationError::Rejected` represents input validation or a definite API
rejection. `Unknown` means an invoice may already exist: for example, the request
timed out, the provider returned a server error, or its success response was
invalid. Mark that attempt uncertain and reconcile the order in the provider
dashboard before creating another invoice. Do not put invoice creation inside
a generic retry loop. Through `Checkout::start_session`, an unknown outcome is
a `PaymentError::Provider` with this recovery instruction.

## Verify and reconcile payments

An invoice can produce a separate payment ID. `payment_status(payment_id)` calls
the authenticated payment endpoint and rejects a response with a different ID.
`Checkout::session_status(invoice_id)` returns `NotSupported`; an invoice ID
cannot be substituted into the payment lookup endpoint. This adapter does not
use dashboard email/password credentials to list payments by invoice.

```rust,no_run
use suprnova::payments::{Money, PaymentResult};
use suprnova_payments_nowpayments::{NowPaymentsProvider, NowPaymentsStatus};

async fn payment_matches_order(
    provider: &NowPaymentsProvider,
    verified_payment_id: &str,
    expected_invoice_id: &str,
    expected_order_id: &str,
    expected_price: Money,
) -> PaymentResult<bool> {
    let payment = provider.payment_status(verified_payment_id).await?;
    Ok(payment.status == NowPaymentsStatus::Finished
        && payment.invoice_id.as_deref() == Some(expected_invoice_id)
        && payment.order_id.as_deref() == Some(expected_order_id)
        && payment.price == expected_price)
}
```

The payment ID must come from a verified IPN or another trusted server-side
record. A browser return is not evidence of payment. A successful lookup is
also not an authorization check: match it to the stored order, invoice, amount
and currency before changing access. `price` is the requested fiat price, not
the crypto quantity received. Review the merchant's partial-payment acceptance
settings; this adapter never converts `partially_paid` into success.

| Provider state | Neutral event |
| --- | --- |
| `finished` | `PaymentSucceeded` |
| `failed`, `expired`, `cancelled`, `canceled` | `PaymentFailed` |
| `refunded` | `PaymentRefunded` |
| `waiting`, `confirming`, `confirmed`, `sending`, `partially_paid`, unknown | No neutral classification |

IPN signatures use recursively sorted JSON and HMAC SHA-512. Verification uses
a constant-time MAC comparison. Missing, duplicate or invalid signatures,
duplicate JSON keys, oversized payloads and malformed required fields are
rejected. The provider signs no independent delivery timestamp, so there is no
invented timestamp-replay window. Replay protection uses persisted receipts.

NOWPayments IPNs have no independent event ID. The adapter identifies a receipt
by payment ID and status, so repeat delivery with a different `updated_at` does
not repeat the same terminal event. The framework stores verified events in
`payments_webhook_events` and retries failed processing. A delayed pending event
does not modify a settled transaction mirror.

### Customerless invoices and application state

The invoice API does not supply the customer identity required by Suprnova's
transaction mirrors. This adapter returns `false` from
`WebhookHandler::mirrors_payment_transactions`: all verified events, including
refunds, remain in the audit log, but it creates no customer or transaction
mirror. Stripe and Paddle retain the default mirror behavior.

The generic webhook route records and processes provider events; it does not
fulfill application orders. An application reconciliation job should consume
verified receipts, read current payment status, and update its order in an
idempotent transaction. Store a unique provider/payment or order fulfillment key
so retries and reordered deliveries cannot grant access twice. Track the job's
own durable completion state separately from the framework's `processed_at`.
Use current authenticated state for delayed events and handle refunds according
to the application's policy.

## Capability limits

`CustomerStore` and `Subscription` operations return `NotSupported`.
`as_payment()` and `as_promotions()` return `None`. This adapter does not implement
custody balances, recurring billing, direct deposit-address checkout, payouts,
refund initiation, or provider customer management. NOWPayments offers separate
products for some of these operations; this invoice adapter does not pretend to
implement them.

### Why Suprnova diverges

The common provider traits stay available, but unsupported operations fail
explicitly. Invoices without provider customers use audited notifications and
application-owned orders rather than fabricated customer records or subscriptions.

## Verification

Run the adapter tests and the shared payment regressions from the source checkout:

```sh
CARGO_INCREMENTAL=0 cargo nextest run -p suprnova-payments-nowpayments
CARGO_INCREMENTAL=0 cargo nextest run -p suprnova --test payments
```

The local suite uses fake HTTP responses, an independently generated JavaScript
signature fixture, and real framework ingress with SQLite. It covers successful
checkout, authentication failures, malformed or large responses, timeouts,
untrusted redirects, invalid signatures, status mapping, duplicate deliveries,
and recovery after a database failure. Local fixtures do not establish provider
interoperability.

Before enabling production, use a NOWPayments sandbox account and a reachable
HTTPS callback. Create an invoice, exercise the provider's available success,
partial and failure cases, confirm its signature is accepted, and reconcile the
payment ID against the stored invoice and order. Replay a delivery and confirm
the application's fulfillment key prevents a second grant. No real-account
sandbox or production run is implied by the local tests.

Provider references: [API endpoints](https://nowpayments.zendesk.com/hc/en-us/articles/21345824322717-API-and-endpoint-description),
[IPN authentication](https://nowpayments.zendesk.com/hc/en-us/articles/21395546303389-IPN-and-how-to-setup),
and the [official SDK](https://github.com/NowPaymentsIO/nowpayments-sdk-nodejs).

## Next

See [Frontend Integration](payments-frontend.md) for rendering redirect payloads,
or the [Provider Guide](payments-provider-guide.md) for the shared contracts.


---

<!-- /docs/payments-frontend -->

# Payments - Frontend Integration

The server returns a `SessionPayload` as part of your Inertia page props. The payload carries a `flow` field that tells the frontend which widget to mount; your frontend dispatches on `flow` and never names a specific provider. This chapter covers the Svelte 5, React 19, and Vue 3.5 dispatch loops, including the Stripe Elements confirm-card-payment cycle and the off-session 3DS step-up handler.

The five possible `flow` values and their associated fields:

| `flow` | Fields | Widget |
|---|---|---|
| `stripe_elements` | `client_secret`, `publishable_key`, `provider_session_id` | Stripe Elements (embedded card form) |
| `stripe_checkout_redirect` | `url`, `provider_session_id` | Redirect to Stripe-hosted checkout |
| `paddle_inline` | `transaction_id`, `client_token`, `customer_token?` | Paddle.js inline overlay |
| `mobile_money_prompt` | `provider_transaction_id`, `message`, `operator` | USSD / operator-app prompt + polling |
| `redirect` | `url`, `provider_session_id` | Generic redirect (Mollie, mock, etc.) |

The backend controller calls `Checkout::start_session` and returns the result as Inertia props - from the frontend's perspective the API is the same regardless of which adapter is running.

## Dispatch on `flow`, not on provider

Your checkout page reads the `flow` field once and mounts the matching widget. It never names "Stripe" or "Paddle"; only the bootstrap that chose the adapter knows. This is the contract the rest of the chapter builds on.

### Why Suprnova diverges

Laravel Cashier ships a Blade view for Stripe Checkout, a partials path for SCA, and a separate SDK convention for Paddle. The Stripe and Paddle paths don't share a frontend contract - each provider's widget is wired to a different controller action and a different template tree.

Suprnova flips that: the backend always returns the same `SessionPayload` enum and the frontend always switches on `flow`. Adding a new provider means adding one variant on the server side and one `case` on the client side; the rest of your checkout page does not move. The Mobile Money variant is the proof - it produces no widget at all (the customer confirms on their phone), and the dispatcher absorbs it without any special-casing in the calling component.

## Svelte 5

```svelte
<!-- src/pages/Billing/Checkout.svelte -->
<script lang="ts">
  import { page } from "@inertiajs/svelte";

  // SessionPayload arrives in Inertia page props
  let session = $derived($page.props.session as SessionPayload);

  type MobileMoneyOperator =
    | { kind: "mtn_momo" }
    | { kind: "mpesa" }
    | { kind: "airtel_money" }
    | { kind: "orange_money" }
    | { kind: "lipila" }
    | { kind: "custom"; identifier: string };

  type SessionPayload =
    | { flow: "stripe_elements"; client_secret: string; publishable_key: string; provider_session_id: string }
    | { flow: "stripe_checkout_redirect"; url: string; provider_session_id: string }
    | { flow: "paddle_inline"; transaction_id: string; client_token: string; customer_token?: string | null }
    | { flow: "mobile_money_prompt"; provider_transaction_id: string; message: string; operator: MobileMoneyOperator }
    | { flow: "redirect"; url: string; provider_session_id: string };

  let mobileMessage = $state("");

  $effect(() => {
    if (!session) return;
    switch (session.flow) {
      case "stripe_elements":
        mountStripeElements(session);
        break;
      case "stripe_checkout_redirect":
        window.location.href = session.url;
        break;
      case "paddle_inline":
        mountPaddleInline(session);
        break;
      case "mobile_money_prompt":
        mobileMessage = session.message;
        pollMobileMoney(session.provider_transaction_id);
        break;
      case "redirect":
        window.location.href = session.url;
        break;
    }
  });

  async function mountStripeElements(s: Extract<SessionPayload, { flow: "stripe_elements" }>) {
    // Stripe.js must be loaded - add to templates/app.html, the root document:
    // <script src="https://js.stripe.com/v3/"></script>
    const stripe = (window as any).Stripe(s.publishable_key);
    const elements = stripe.elements({ clientSecret: s.client_secret });

    const card = elements.create("card");
    card.mount("#card-element");

    // Wire up form submission:
    const form = document.getElementById("payment-form") as HTMLFormElement;
    form?.addEventListener("submit", async (e) => {
      e.preventDefault();
      const { error, paymentIntent } = await stripe.confirmCardPayment(s.client_secret, {
        payment_method: { card },
      });
      if (error) {
        // Show error to user
        console.error(error.message);
      } else if (paymentIntent?.status === "succeeded") {
        // Payment complete - navigate or show confirmation
        window.location.href = "/billing/success";
      }
    });
  }

  function mountPaddleInline(s: Extract<SessionPayload, { flow: "paddle_inline" }>) {
    // Paddle.js must be loaded - add to templates/app.html, the root document:
    // <script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
    const Paddle = (window as any).Paddle;
    Paddle.Initialize({ token: s.client_token });
    Paddle.Checkout.open({
      transactionId: s.transaction_id,
    });
  }

  async function pollMobileMoney(txId: string) {
    // Poll your own backend, which reads the mirror transactions table.
    // The webhook handler updates the row when the provider notifies us.
    const deadline = Date.now() + 5 * 60_000;
    while (Date.now() < deadline) {
      await new Promise((r) => setTimeout(r, 3000));
      const res = await fetch(`/billing/status?transaction_id=${encodeURIComponent(txId)}`);
      const { status } = await res.json();
      if (status === "succeeded") {
        window.location.href = "/billing/success";
        return;
      }
      if (status === "failed" || status === "canceled" || status === "expired") {
        window.location.href = "/billing/failed";
        return;
      }
    }
  }
</script>

<div id="payment-form">
  <div id="card-element"></div>
  <!-- Only rendered for stripe_elements; hidden otherwise -->
  {#if session?.flow === "stripe_elements"}
    <button type="submit">Pay now</button>
  {/if}
  {#if session?.flow === "mobile_money_prompt"}
    <p>{mobileMessage}</p>
    <p>Waiting for confirmation…</p>
  {/if}
</div>
```

## React 19

```tsx
// src/pages/Billing/Checkout.tsx
import { useEffect, useRef, useState } from "react";
import { usePage } from "@inertiajs/react";

type MobileMoneyOperator =
  | { kind: "mtn_momo" }
  | { kind: "mpesa" }
  | { kind: "airtel_money" }
  | { kind: "orange_money" }
  | { kind: "lipila" }
  | { kind: "custom"; identifier: string };

type SessionPayload =
  | { flow: "stripe_elements"; client_secret: string; publishable_key: string; provider_session_id: string }
  | { flow: "stripe_checkout_redirect"; url: string; provider_session_id: string }
  | { flow: "paddle_inline"; transaction_id: string; client_token: string; customer_token?: string | null }
  | { flow: "mobile_money_prompt"; provider_transaction_id: string; message: string; operator: MobileMoneyOperator }
  | { flow: "redirect"; url: string; provider_session_id: string };

export default function Checkout() {
  const { session } = usePage<{ session: SessionPayload }>().props;
  const mountedRef = useRef(false);
  const [mobileMessage, setMobileMessage] = useState("");

  useEffect(() => {
    if (!session || mountedRef.current) return;
    mountedRef.current = true;

    switch (session.flow) {
      case "stripe_elements":
        mountStripeElements(session);
        break;
      case "stripe_checkout_redirect":
        window.location.href = session.url;
        break;
      case "paddle_inline":
        mountPaddleInline(session);
        break;
      case "mobile_money_prompt":
        setMobileMessage(session.message);
        pollMobileMoney(session.provider_transaction_id);
        break;
      case "redirect":
        window.location.href = session.url;
        break;
    }
  }, [session]);

  async function mountStripeElements(
    s: Extract<SessionPayload, { flow: "stripe_elements" }>
  ) {
    const stripe = (window as any).Stripe(s.publishable_key);
    const elements = stripe.elements({ clientSecret: s.client_secret });
    const card = elements.create("card");
    card.mount("#card-element");

    const form = document.getElementById("payment-form") as HTMLFormElement;
    form?.addEventListener("submit", async (e) => {
      e.preventDefault();
      const { error, paymentIntent } = await stripe.confirmCardPayment(s.client_secret, {
        payment_method: { card },
      });
      if (error) {
        console.error(error.message);
      } else if (paymentIntent?.status === "succeeded") {
        window.location.href = "/billing/success";
      }
    });
  }

  function mountPaddleInline(
    s: Extract<SessionPayload, { flow: "paddle_inline" }>
  ) {
    const Paddle = (window as any).Paddle;
    Paddle.Initialize({ token: s.client_token });
    Paddle.Checkout.open({
      transactionId: s.transaction_id,
    });
  }

  async function pollMobileMoney(txId: string) {
    const deadline = Date.now() + 5 * 60_000;
    while (Date.now() < deadline) {
      await new Promise((r) => setTimeout(r, 3000));
      const res = await fetch(`/billing/status?transaction_id=${encodeURIComponent(txId)}`);
      const { status } = await res.json();
      if (status === "succeeded") {
        window.location.href = "/billing/success";
        return;
      }
      if (status === "failed" || status === "canceled" || status === "expired") {
        window.location.href = "/billing/failed";
        return;
      }
    }
  }

  return (
    <form id="payment-form">
      <div id="card-element" />
      {session?.flow === "stripe_elements" && (
        <button type="submit">Pay now</button>
      )}
      {session?.flow === "mobile_money_prompt" && (
        <div>
          <p>{mobileMessage}</p>
          <p>Waiting for confirmation…</p>
        </div>
      )}
    </form>
  );
}
```

The `mountedRef` guard prevents double-mounting under React 19's StrictMode development double-render.

## Vue 3.5

```vue
<!-- src/pages/Billing/Checkout.vue -->
<script setup lang="ts">
import { onMounted, ref } from "vue";
import { usePage } from "@inertiajs/vue3";

type MobileMoneyOperator =
  | { kind: "mtn_momo" }
  | { kind: "mpesa" }
  | { kind: "airtel_money" }
  | { kind: "orange_money" }
  | { kind: "lipila" }
  | { kind: "custom"; identifier: string };

type SessionPayload =
  | { flow: "stripe_elements"; client_secret: string; publishable_key: string; provider_session_id: string }
  | { flow: "stripe_checkout_redirect"; url: string; provider_session_id: string }
  | { flow: "paddle_inline"; transaction_id: string; client_token: string; customer_token?: string | null }
  | { flow: "mobile_money_prompt"; provider_transaction_id: string; message: string; operator: MobileMoneyOperator }
  | { flow: "redirect"; url: string; provider_session_id: string };

const page = usePage<{ session: SessionPayload }>();
const session = page.props.session;
const isStripeElements = ref(session?.flow === "stripe_elements");
const isMobileMoney = ref(session?.flow === "mobile_money_prompt");
const mobileMessage = ref(
  session?.flow === "mobile_money_prompt" ? session.message : ""
);

onMounted(() => {
  if (!session) return;
  switch (session.flow) {
    case "stripe_elements":
      mountStripeElements(session);
      break;
    case "stripe_checkout_redirect":
      window.location.href = session.url;
      break;
    case "paddle_inline":
      mountPaddleInline(session);
      break;
    case "mobile_money_prompt":
      pollMobileMoney(session.provider_transaction_id);
      break;
    case "redirect":
      window.location.href = session.url;
      break;
  }
});

async function mountStripeElements(
  s: Extract<SessionPayload, { flow: "stripe_elements" }>
) {
  const stripe = (window as any).Stripe(s.publishable_key);
  const elements = stripe.elements({ clientSecret: s.client_secret });
  const card = elements.create("card");
  card.mount("#card-element");

  const form = document.getElementById("payment-form") as HTMLFormElement;
  form?.addEventListener("submit", async (e) => {
    e.preventDefault();
    const { error, paymentIntent } = await stripe.confirmCardPayment(s.client_secret, {
      payment_method: { card },
    });
    if (error) {
      console.error(error.message);
    } else if (paymentIntent?.status === "succeeded") {
      window.location.href = "/billing/success";
    }
  });
}

function mountPaddleInline(
  s: Extract<SessionPayload, { flow: "paddle_inline" }>
) {
  const Paddle = (window as any).Paddle;
  Paddle.Initialize({ token: s.client_token });
  Paddle.Checkout.open({
    transactionId: s.transaction_id,
  });
}

async function pollMobileMoney(txId: string) {
  const deadline = Date.now() + 5 * 60_000;
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 3000));
    const res = await fetch(`/billing/status?transaction_id=${encodeURIComponent(txId)}`);
    const { status } = await res.json();
    if (status === "succeeded") {
      window.location.href = "/billing/success";
      return;
    }
    if (status === "failed" || status === "canceled" || status === "expired") {
      window.location.href = "/billing/failed";
      return;
    }
  }
}
</script>

<template>
  <form id="payment-form">
    <div id="card-element" />
    <button v-if="isStripeElements" type="submit">Pay now</button>
    <div v-if="isMobileMoney">
      <p>{{ mobileMessage }}</p>
      <p>Waiting for confirmation…</p>
    </div>
  </form>
</template>
```

## Loading the Payment SDKs

Add the relevant scripts to your root template, `templates/app.html` in a
scaffolded project (see [the root template](frontend-inertia-responses.md#the-root-template)),
so they reach every first visit's document. Only include the ones your
provider selection requires:

```html
<!-- Stripe (add if using stripe_elements or stripe_checkout_redirect) -->
<script src="https://js.stripe.com/v3/" crossorigin="anonymous"></script>

<!-- Paddle (add if using paddle_inline) -->
<script src="https://cdn.paddle.com/paddle/v2/paddle.js" crossorigin="anonymous"></script>
```

Both scripts are loaded asynchronously by the browser. If you're using Vite with code-splitting, load these via dynamic `import()` or include them as externals in your `vite.config.ts` to avoid bundling the provider SDKs yourself.

Stripe and Paddle both require you to load the SDK from their own CDN - Stripe makes this a PCI compliance condition, and Paddle relies on it for live URL rewriting. Subresource Integrity (`integrity="sha384-..."`) is not usable on either script because both vendors ship continuously and do not publish stable hashes; the trust boundary is the HTTPS connection plus the vendor's CDN. If your threat model requires SRI for everything you embed, that's a signal to keep all payment UI on a vendor-hosted checkout (`stripe_checkout_redirect`, or Paddle's hosted overlay invoked from a server-issued redirect) rather than in your own page.

## TypeScript Types

The `SessionPayload` type shown in each example above is a discriminated union matching the Rust enum's serialized form. You can generate it automatically with `suprnova generate-types` if your `SessionPayload` is exposed via a `#[derive(InertiaProps)]` wrapper, or define it manually as shown.

## Mobile Money Polling

`mobile_money_prompt` is the only flow where the customer never touches your page after the prompt arrives. They confirm on their phone (USSD menu or operator-app push), the provider notifies your webhook handler, and your frontend has to discover that the transaction settled.

Wire a small status endpoint that reads the mirror `payments_transactions` table by `provider_transaction_id`. The webhook handler installed by `webhook_routes(db)` keeps the row's status column current; your endpoint just reflects it back:

```rust,ignore
use suprnova::{handler, json_response, AppError, FrameworkError, Request, Response, DB};
use suprnova::payments::entities::transaction;
use sea_orm::{ColumnTrait, EntityTrait, QueryFilter};

#[handler]
pub async fn status(req: Request) -> Response {
    let id = req
        .query_param("transaction_id")
        .ok_or_else(|| AppError::bad_request("transaction_id is required"))?;
    let row = transaction::Entity::find()
        .filter(transaction::Column::ProviderTransactionId.eq(id))
        .one(&*DB::get()?)
        .await
        .map_err(FrameworkError::from)?;
    let status = row.map(|r| r.status).unwrap_or_else(|| "pending".into());
    json_response!({ "status": status })
}
```

The frontend `pollMobileMoney` helper shown in each example above hits that endpoint every three seconds with a five-minute ceiling. Status strings come from the `PaymentStatus` enum and serialize as snake_case: `created`, `requires_action`, `pending`, `processing`, `authorized`, `expired`, `succeeded`, `failed`, `canceled`, `refunded`, `partially_refunded`, `disputed`.

## Error Handling - `RequiresClientAction`

When `Payment::charge` (server-side capture) returns `ChargeResult::RequiresClientAction`, the backend serializes the result to JSON and returns it to the frontend. This happens for off-session 3DS step-up flows where the card issuer demands additional authentication.

The JSON looks like:

```json
{
  "kind": "requires_client_action",
  "provider_transaction_id": "pi_...",
  "action_kind": "stripe_3ds",
  "client_secret": "pi_..._secret_...",
  "publishable_key": "pk_live_..."
}
```

`client_secret` and `publishable_key` are `Option<String>` on the Rust side and will be absent from the JSON when an action does not need them. Always null-check both before passing them to a provider SDK, and let `action_kind` drive the dispatch - that field is always present.

Your backend controller should detect this and return it as a distinct Inertia prop or as an HTTP response that the frontend reads. Example controller pattern:

```rust,ignore
use suprnova::payments::ChargeResult;

let result = payment.charge(req).await?;
match result {
    ChargeResult::Completed { .. } => {
        // Redirect to success page
    }
    ChargeResult::RequiresClientAction { action_kind, client_secret, publishable_key, .. } => {
        return inertia.render("Billing/ThreeDSChallenge", json!({
            "action_kind": action_kind,
            "client_secret": client_secret,
            "publishable_key": publishable_key,
        }));
    }
    ChargeResult::RedirectRequired { url, .. } => {
        // Redirect the browser
    }
}
```

On the frontend, dispatch on `action_kind`:

**Svelte 5:**

```svelte
<script lang="ts">
  import { page } from "@inertiajs/svelte";

  let props = $derived($page.props as {
    action_kind: string;
    client_secret?: string;
    publishable_key?: string;
  });

  $effect(() => {
    if (!props.action_kind) return;
    switch (props.action_kind) {
      case "stripe_3ds":
        handleStripe3DS(props.client_secret!, props.publishable_key!);
        break;
      default:
        console.warn("Unknown action_kind:", props.action_kind);
    }
  });

  async function handleStripe3DS(clientSecret: string, publishableKey: string) {
    const stripe = (window as any).Stripe(publishableKey);
    const { error, paymentIntent } = await stripe.handleNextAction({ clientSecret });
    if (error) {
      // Show 3DS failure message
    } else if (paymentIntent?.status === "succeeded") {
      window.location.href = "/billing/success";
    }
  }
</script>
```

**React 19:**

```tsx
import { usePage } from "@inertiajs/react";
import { useEffect } from "react";

export default function ThreeDSChallenge() {
  const { action_kind, client_secret, publishable_key } = usePage<{
    action_kind: string;
    client_secret?: string;
    publishable_key?: string;
  }>().props;

  useEffect(() => {
    if (!action_kind) return;
    if (action_kind === "stripe_3ds" && client_secret && publishable_key) {
      const stripe = (window as any).Stripe(publishable_key);
      stripe.handleNextAction({ clientSecret: client_secret }).then(
        ({ error, paymentIntent }: any) => {
          if (!error && paymentIntent?.status === "succeeded") {
            window.location.href = "/billing/success";
          }
        }
      );
    }
  }, [action_kind]);

  return <div>Completing payment authentication...</div>;
}
```

**Vue 3.5:**

```vue
<script setup lang="ts">
import { onMounted } from "vue";
import { usePage } from "@inertiajs/vue3";

const { action_kind, client_secret, publishable_key } = usePage<{
  action_kind: string;
  client_secret?: string;
  publishable_key?: string;
}>().props;

onMounted(async () => {
  if (action_kind === "stripe_3ds" && client_secret && publishable_key) {
    const stripe = (window as any).Stripe(publishable_key);
    const { error, paymentIntent } = await stripe.handleNextAction({
      clientSecret: client_secret,
    });
    if (!error && paymentIntent?.status === "succeeded") {
      window.location.href = "/billing/success";
    }
  }
});
</script>

<template>
  <p>Completing payment authentication...</p>
</template>
```

The `action_kind` field is a provider-specific string. Currently `"stripe_3ds"` is the only value produced by the shipped Stripe adapter. When additional adapters require client actions, they will add their own `action_kind` values following the same pattern - write a default branch (`console.warn("Unknown action_kind:", k)`) so an unrecognised value fails loud rather than silently dropping the payment.

## Next

- [Payments](payments.md) - the five-trait surface, the registry, and the bootstrap pattern that produces the `SessionPayload`.
- [Payments - Stripe](payments-stripe.md) - server-side configuration for the `stripe_elements`, `stripe_checkout_redirect`, and `stripe_3ds` flows.
- [Payments - Paddle](payments-paddle.md) - server-side configuration for the `paddle_inline` flow and the Merchant-of-Record responsibility split.
- [Payments - Provider Guide](payments-provider-guide.md) - add a new `SessionPayload` variant when you write an adapter for a gateway Suprnova doesn't ship.
- [Frontend](frontend.md) - Inertia page setup, prop typing, and how `usePage` plugs into your Svelte / React / Vue starter.


---

<!-- /docs/payments-provider-guide -->

# Writing a Payment Provider Adapter

This guide walks through building a third-party adapter crate - `suprnova-payments-mollie` - that plugs into Suprnova's provider-neutral payments surface. By the end you will have a crate that registers itself, passes the discriminator flow, and can be dropped into any Suprnova app with a single `cargo add`.

The same structure applies to any provider: Square, Braintree, Adyen, or anything else with an HTTP API.

### Why Suprnova diverges

Laravel ships Cashier as a first-party Stripe integration. It is excellent for the Stripe path, but it codifies one provider's vocabulary into the framework - adding a second provider means either forking Cashier or building a parallel surface beside it.

Suprnova keeps every provider on the same five-trait contract: `Checkout`, `Subscription`, `CustomerStore`, `WebhookHandler`, and the optional `Payment` for server-capture providers. Domain code only ever holds `Arc<dyn PaymentProvider>` from the registry. Swapping Stripe for Paddle (or for the Mollie adapter you're about to write) is a bootstrap change, not a code change. The reference adapters at `crates/suprnova-payments-stripe/` and `crates/suprnova-payments-paddle/` prove the trait contract holds for two very different commercial models - direct-capture gateway and Merchant of Record - and your adapter slots into the same shape.

## 1. Create the Workspace Member Crate

From the repo root:

```bash
cargo new --lib crates/suprnova-payments-mollie
```

Add it to your root `Cargo.toml`:

```toml
[workspace]
members = [
    "framework",
    "app",
    "suprnova-cli",
    "suprnova-macros",
    "crates/suprnova-payments-mollie",  # add this line
]
```

(The reference adapters - `crates/suprnova-payments-stripe` and `crates/suprnova-payments-paddle` - live in this same `crates/` directory and are good templates to read alongside this guide.)

**`crates/suprnova-payments-mollie/Cargo.toml`:**

```toml
[package]
name = "suprnova-payments-mollie"
version.workspace = true
edition.workspace = true
license.workspace = true
description = "Mollie payment adapter for Suprnova"

[dependencies]
suprnova = { path = "../../framework" }
async-trait = "0.1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "2"
inventory = "0.3"
tracing = "0.1"
tokio = { version = "1", features = ["macros", "rt"] }
# Your Mollie SDK:
mollie-rs = "0.1"
hmac = "0.12"   # for webhook HMAC verification
sha2 = "0.10"
hex = "0.4"

[dev-dependencies]
tokio = { version = "1", features = ["full"] }
```

## 2. Lay Out the Source Files

Mirror the structure used by the shipped adapters:

```
crates/suprnova-payments-mollie/src/
├── lib.rs          # MollieProvider struct, PaymentProvider impl, from_env
├── checkout.rs     # Checkout impl
├── customer.rs     # CustomerStore impl
├── subscription.rs # Subscription impl
├── webhook.rs      # WebhookHandler impl
├── event_map.rs    # provider event string → NeutralEventKind
└── payment.rs      # Payment impl (if Mollie supports server-capture)
```

## 3. `lib.rs` - the Provider Struct

Import every payments type from `suprnova::payments` by its name, as the examples in this guide do. The modules of the request and result types are under `suprnova::payments::dto`, so `suprnova::payments::session::StartSessionRequest` is not a path.

```rust,ignore
use async_trait::async_trait;
use suprnova::payments::{Payment, PaymentProvider};

mod checkout;
mod customer;
mod event_map;
mod payment;
mod subscription;
mod webhook;

pub use event_map::mollie_event_to_neutral;

/// Mollie adapter for Suprnova's provider-neutral payments surface.
#[derive(Clone, Debug)]
pub struct MollieProvider {
    /// Mollie API key (`test_…` / `live_…`).
    api_key: String,
    /// Webhook signing secret - used in HMAC verification.
    webhook_secret: String,
    /// HTTP client - share across requests.
    client: reqwest::Client,
}

impl MollieProvider {
    pub fn new(api_key: impl Into<String>, webhook_secret: impl Into<String>) -> Self {
        Self {
            api_key: api_key.into(),
            webhook_secret: webhook_secret.into(),
            client: reqwest::Client::new(),
        }
    }

    /// Construct from environment variables.
    ///
    /// Reads:
    /// - `MOLLIE_API_KEY`
    /// - `MOLLIE_WEBHOOK_SECRET`
    pub fn from_env() -> Result<Self, String> {
        let api_key = std::env::var("MOLLIE_API_KEY")
            .map_err(|_| "MOLLIE_API_KEY not set".to_string())?;
        let webhook_secret = std::env::var("MOLLIE_WEBHOOK_SECRET")
            .map_err(|_| "MOLLIE_WEBHOOK_SECRET not set".to_string())?;
        Ok(Self::new(api_key, webhook_secret))
    }
}

impl PaymentProvider for MollieProvider {
    fn name(&self) -> &'static str {
        "mollie"
    }

    // Only override `as_payment()` if you also implement `Payment` (server-capture).
    // The default impl on `PaymentProvider` returns `None` - omit this override
    // entirely if Mollie is checkout-only / MoR-style.
    fn as_payment(&self) -> Option<&dyn Payment> {
        Some(self)
    }
}
```

`PaymentProvider` is the umbrella trait - the supertrait clause is `Checkout + Subscription + CustomerStore + WebhookHandler`, so the compiler will refuse to bind your provider until all four are implemented. The fifth trait, `Payment`, is **optional** - only providers that expose server-side capture implement it, and `as_payment()` reports the result to the framework. The default `as_payment()` returns `None`, so omit the override entirely if your provider doesn't do server-capture.

## 4. Implement the Four Required Traits

### `checkout.rs`

```rust,ignore
use async_trait::async_trait;
use suprnova::payments::{
    Checkout, PaymentError, PaymentResult, SessionMode, SessionPayload, StartSessionRequest,
};

use crate::MollieProvider;

#[async_trait]
impl Checkout for MollieProvider {
    async fn start_session(&self, req: StartSessionRequest) -> PaymentResult<SessionPayload> {
        // Call the Mollie API to create a payment or order.
        // Map the response to one of the SessionPayload variants.
        // Mollie uses hosted checkout pages, so Redirect is the natural fit.
        let checkout_url = self.create_mollie_payment(&req).await
            .map_err(|e| PaymentError::Internal(format!("Mollie checkout error: {e}")))?;

        Ok(SessionPayload::Redirect {
            url: checkout_url,
            provider_session_id: "mollie_session_id_here".into(),
        })
    }
}

impl MollieProvider {
    async fn create_mollie_payment(&self, req: &StartSessionRequest) -> Result<String, mollie_rs::Error> {
        // Wire up the Mollie SDK call here.
        // Return the hosted checkout URL.
        todo!("Mollie payment creation")
    }
}
```

### `customer.rs`

```rust,ignore
use async_trait::async_trait;
use suprnova::payments::{
    CreateCustomerRequest, CustomerRef, CustomerStore, PaymentError, PaymentResult,
    UpdateCustomerRequest,
};

use crate::MollieProvider;

#[async_trait]
impl CustomerStore for MollieProvider {
    async fn create_customer(&self, req: CreateCustomerRequest) -> PaymentResult<CustomerRef> {
        // POST /v2/customers to Mollie
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn update_customer(&self, req: UpdateCustomerRequest) -> PaymentResult<CustomerRef> {
        // PATCH /v2/customers/{id}
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn get_customer(&self, provider_customer_id: &str) -> PaymentResult<CustomerRef> {
        // GET /v2/customers/{id}
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn delete_customer(&self, provider_customer_id: &str) -> PaymentResult<()> {
        // DELETE /v2/customers/{id}
        Err(PaymentError::Internal("not yet implemented".into()))
    }
}
```

### `subscription.rs`

```rust,ignore
use async_trait::async_trait;
use suprnova::payments::{
    PaymentError, PaymentResult, SubscribeRequest, Subscription, SubscriptionResult,
    UpdateSubscriptionRequest,
};

use crate::MollieProvider;

#[async_trait]
impl Subscription for MollieProvider {
    async fn subscribe(&self, req: SubscribeRequest) -> PaymentResult<SubscriptionResult> {
        // POST /v2/customers/{id}/subscriptions
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn update(&self, req: UpdateSubscriptionRequest) -> PaymentResult<SubscriptionResult> {
        // PATCH /v2/customers/{id}/subscriptions/{sub_id}
        // Follow the contract of `req.new_price_refs` and `req.proration`
        // (see below).
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn cancel(
        &self,
        provider_subscription_id: &str,
        at_period_end: bool,
    ) -> PaymentResult<SubscriptionResult> {
        if at_period_end {
            // Set cancel date to period end
        } else {
            // DELETE /v2/customers/{id}/subscriptions/{sub_id}
        }
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn get(&self, provider_subscription_id: &str) -> PaymentResult<SubscriptionResult> {
        // GET /v2/customers/{id}/subscriptions/{sub_id}
        Err(PaymentError::Internal("not yet implemented".into()))
    }
}
```

`UpdateSubscriptionRequest::new_price_refs` has one meaning on every adapter. The list is the set of prices the subscription has after the call. An item whose price is in the list keeps its id and quantity, and an item whose price is not in the list is removed. A price with no item is added with a quantity of 1. The exception is a swap: when exactly one item is removed and exactly one price is added, the new price takes the quantity of the removed item. Refuse an empty list and a list that names a price twice with `PaymentError::Validation`, before any request. Compute the change from a read of the subscription. The change is not atomic: a change made at the provider between your read and your write can be undone or left in place, depending on whether the provider takes the whole list of items or one item at a time. Return the provider's view of the outcome in the `SubscriptionResult`. `MockPaymentProvider` follows the same contract, so a test that runs against it sees what an adapter does.

Build the text of a `PaymentError::Provider` from the SDK error yourself, without the message of the provider and without any id or URL, because the text ends up in logs and in responses. Name the operation and give the kind of the error, its code and the HTTP status, and use a fixed text for the other variants. The `sdk_error.rs` files of `suprnova-payments-stripe` and `suprnova-payments-paddle` show the shape: `provider_error(operation, error)` returns `PaymentError::Provider("stripe customers.retrieve: api error invalid_request_error resource_missing, status 404")` for a Stripe API error.

`UpdateSubscriptionRequest::proration` is an `Option<Proration>` that you read only when `new_price_refs` is `Some`. Map `None` and `Proration::ProrateAtRenewal` to your provider's mode that adds the difference to the next invoice, `ProrateNow` to the mode that bills it at once, and `DoNotProrate` to the mode that bills nothing for the change. `Proration` is `#[non_exhaustive]`, so end the `match` with an arm that returns `PaymentError::NotSupported`. If the provider cannot take a part of a request, such as a price change together with `cancel_at_period_end`, return `NotSupported` and send nothing.

If your provider doesn't support a method, return `PaymentError::NotSupported`:

```rust,ignore
Err(PaymentError::NotSupported(
    "Mollie creates subscriptions via checkout - use start_session instead".into()
))
```

### `payment.rs` - server-side capture (optional)

Only implement this if your provider supports direct server-side charges against a stored payment method. Remove the `as_payment()` override in `lib.rs` if you skip this.

```rust,ignore
use async_trait::async_trait;
use suprnova::payments::{
    ChargeRequest, ChargeResult, Payment, PaymentError, PaymentResult, PaymentStatus,
    RefundRequest, RefundResult,
};

use crate::MollieProvider;

#[async_trait]
impl Payment for MollieProvider {
    async fn charge(&self, req: ChargeRequest) -> PaymentResult<ChargeResult> {
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn capture(&self, provider_transaction_id: &str) -> PaymentResult<ChargeResult> {
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn refund(&self, req: RefundRequest) -> PaymentResult<RefundResult> {
        // POST /v2/payments/{id}/refunds
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn void(&self, provider_transaction_id: &str) -> PaymentResult<()> {
        Err(PaymentError::Internal("not yet implemented".into()))
    }

    async fn status(&self, provider_transaction_id: &str) -> PaymentResult<PaymentStatus> {
        Err(PaymentError::Internal("not yet implemented".into()))
    }
}
```

## 5. Map Provider Events to `NeutralEventKind`

**`event_map.rs`:**

```rust,ignore
use suprnova::payments::NeutralEventKind;

/// Map a Mollie webhook event type string to the framework's neutral taxonomy.
/// Returns `None` for provider-specific events that have no neutral equivalent.
pub fn mollie_event_to_neutral(event_type: &str) -> Option<NeutralEventKind> {
    match event_type {
        // Mollie payments
        "payment.paid"          => Some(NeutralEventKind::PaymentSucceeded),
        "payment.failed"        => Some(NeutralEventKind::PaymentFailed),
        "payment.expired"       => Some(NeutralEventKind::PaymentFailed),
        "refund.created"        => Some(NeutralEventKind::PaymentRefunded),
        "chargeback.created"    => Some(NeutralEventKind::PaymentDisputed),
        // Mollie subscriptions
        "subscription.created"  => Some(NeutralEventKind::SubscriptionCreated),
        "subscription.updated"  => Some(NeutralEventKind::SubscriptionUpdated),
        "subscription.canceled" => Some(NeutralEventKind::SubscriptionCanceled),
        // Mollie orders/invoices
        "order.paid"            => Some(NeutralEventKind::InvoicePaid),
        // Customer events
        "customer.created"      => Some(NeutralEventKind::CustomerCreated),
        "customer.updated"      => Some(NeutralEventKind::CustomerUpdated),
        // Provider-specific - falls through to raw_payload
        _                       => None,
    }
}
```

Cover at minimum the events listed above. For any event not in the neutral taxonomy, return `None` - it still gets persisted in `payments_webhook_events` under `provider_event_type` + `raw_payload` so domain code can read it.

## 6. Implement Webhook Signature Verification

**`webhook.rs`:**

Mollie signs webhook payloads using HMAC-SHA256. Always compare signatures in constant time to prevent timing attacks.

```rust,ignore
use async_trait::async_trait;
use hmac::{Hmac, Mac};
use sha2::Sha256;
use suprnova::payments::{
    NeutralEventKind, PaymentError, PaymentResult, WebhookContext, WebhookEvent, WebhookHandler,
};

use crate::{MollieProvider, event_map::mollie_event_to_neutral};

type HmacSha256 = Hmac<Sha256>;

#[async_trait]
impl WebhookHandler for MollieProvider {
    fn verify(&self, ctx: &WebhookContext<'_>) -> PaymentResult<()> {
        // Read the signature header Mollie sends.
        // Exact header name and signing scheme - check Mollie's docs for your version.
        let signature = ctx
            .headers
            .get("X-Mollie-Signature")
            .and_then(|v| v.to_str().ok())
            .ok_or_else(|| PaymentError::WebhookSignature(
                "missing X-Mollie-Signature header".into()
            ))?;

        // Compute expected HMAC-SHA256 over the raw body.
        let mut mac = HmacSha256::new_from_slice(self.webhook_secret.as_bytes())
            .map_err(|e| PaymentError::Internal(format!("HMAC init: {e}")))?;
        mac.update(ctx.body);

        // Decode the hex-encoded received signature.
        let received = hex::decode(signature)
            .map_err(|_| PaymentError::WebhookSignature("non-hex signature".into()))?;

        // Constant-time comparison.
        mac.verify_slice(&received)
            .map_err(|_| PaymentError::WebhookSignature("signature mismatch".into()))
    }

    fn parse_event(&self, body: &[u8]) -> PaymentResult<WebhookEvent> {
        // Mollie sends JSON - parse it.
        let raw: serde_json::Value = serde_json::from_slice(body)
            .map_err(|e| PaymentError::Validation(format!("invalid mollie webhook body: {e}")))?;

        let event_id = raw["id"].as_str()
            .ok_or_else(|| PaymentError::Validation("missing event id".into()))?
            .to_string();

        // Mollie uses resource types rather than event type strings in some webhook shapes.
        // Adapt to whatever your SDK version sends.
        let event_type = raw["resource"].as_str()
            .unwrap_or("unknown")
            .to_string();

        let neutral = mollie_event_to_neutral(&event_type);

        Ok(WebhookEvent {
            provider: "mollie".into(),
            provider_event_id: event_id,
            provider_event_type: event_type,
            neutral,
            raw_payload: raw,
        })
    }
}
```

Key points:

- `PaymentError::WebhookSignature(String)` is the single variant for any signature failure - missing header, malformed encoding, mismatch. The framework's webhook route treats every `WebhookSignature(_)` as a 401.
- Use `PaymentError::Validation(String)` for unparseable bodies. The webhook route returns 400 on any parse failure.
- The framework's `webhook_routes` handler calls `verify` before `parse_event`, then hydrates inside a DB transaction. Hydration failures return 503 so the provider retries.
- Never log the raw secret or the received signature.

### Mirror-table hydration: `extract_payload_ids` + `extract_payment_snapshot` + `extract_customer_snapshot`

After `parse_event` returns a `WebhookEvent`, the framework's webhook route hydrates the mirror tables. Three optional trait methods drive that - all have safe default no-op implementations, so an adapter can ship without them and still pass through the audit layer:

```rust,ignore
fn extract_payload_ids(&self, event: &WebhookEvent) -> PayloadIds;
fn extract_payment_snapshot(&self, event: &WebhookEvent) -> Option<PaymentSnapshot>;
fn extract_customer_snapshot(&self, event: &WebhookEvent) -> Option<CustomerSnapshot>;
```

`PayloadIds` is the bridge between the parsed event and the framework's mirror logic. Implement it so the framework can find the right entity:

```rust,ignore
pub struct PayloadIds {
    pub subscription_id: Option<String>,
    pub customer_id: Option<String>,
    pub transaction_id: Option<String>,
}
```

For each `neutral` value, populate the IDs that the provider's payload exposes. Subscription events should set `subscription_id` so the framework can call `Subscription::get(id)` and refresh the mirror from the canonical state. Customer events set `customer_id`. Payment / invoice events set `transaction_id`, plus `subscription_id` when it's a recurring charge.

`PaymentSnapshot` is built directly from the webhook payload - there's no `Payment::get` callback. Implement it for payment / invoice neutrals:

```rust,ignore
pub struct PaymentSnapshot {
    pub provider_transaction_id: String,
    pub provider_customer_id: String,
    pub provider_subscription_id: Option<String>,
    pub amount_total_minor: i64,
    pub amount_tax_minor: i64,
    pub currency: String,
    pub status: String,             // "succeeded" | "failed" | "refunded" | "disputed"
    pub paid_at: Option<DateTime<Utc>>,
    pub provider_metadata: Value,   // typically the entity object from the payload
}
```

Stripe's reference implementation reads `data.object.{id,amount,currency,customer}` for `PaymentIntent`/`Charge` events and `data.object.{id,amount_paid,tax,currency,customer,subscription,status_transitions.paid_at}` for `Invoice` events. Paddle's reads `data.{id,customer_id,currency_code,details.totals.{total,tax},billed_at,subscription_id}`. Mirror the conventions that match your provider's payload shape - the framework doesn't care how you extract, only that the snapshot is correct.

If you return `None` from `extract_payment_snapshot`, the audit row is still written but `payments_transactions` is not touched. That is the correct return for subscription / customer events, or for any payment event where the payload doesn't carry enough information to populate a row.

`CustomerSnapshot` keeps customer-mirror sync provider-driven (no hardcoded JSON paths in the framework):

```rust,ignore
pub struct CustomerSnapshot {
    pub provider_customer_id: String,
    pub email: Option<String>,
    pub provider_metadata: Value,
}
```

The framework will `email = Set(snapshot.email)` only when the snapshot supplies one; `provider_metadata` is always replaced with the provider's view of the customer (`updated_at` is also bumped regardless). Customer-mirror rows are only ever **updated** - never inserted - because `user_id` is `NOT NULL` and the app owns the user ↔ customer link via `CustomerStore::create_customer`.

### Failure semantics

If `extract_payload_ids` returns `None` for `subscription_id` on a subscription event (or for `customer_id` on a customer event), the framework treats that as a `Validation` error: the hydration transaction rolls back, the audit row's `process_error` is set, and the HTTP response is **503 hydration-failed** so the provider retries. Silent success on a malformed payload would leave the mirror stale without operator visibility - provider retries are the recovery mechanism.

This contract means an adapter's extractor must populate the relevant IDs honestly. Returning `None` is reserved for events your provider can't translate at all (e.g. a payment event with no charge ID in the payload), not for "I didn't bother to parse this one."

## 7. Register at App Boot

Two mechanisms are available - pick one:

### Runtime registration (recommended for apps with env-var config)

```rust,ignore
use std::sync::Arc;
use suprnova::payments::PaymentProviderRegistry;
use suprnova_payments_mollie::MollieProvider;

let mollie = MollieProvider::from_env().expect("Mollie env vars not set");
PaymentProviderRegistry::bind("mollie", Arc::new(mollie));
```

### Compile-time registration via `inventory`

For adapter crates that want zero-config registration - useful when shipping a library that consumers just `cargo add` without any boot-time wiring:

```rust,ignore
use suprnova::payments::{PaymentProviderEntry, PaymentProviderRegistry};
use inventory;

// In lib.rs, in a static initializer:
inventory::submit!(PaymentProviderEntry {
    name: "mollie",
    factory: || Arc::new(MollieProvider::from_env().expect("Mollie env not set")),
});
```

`inventory::submit!` runs before `main`. The factory closure is called once when the registry is first accessed.

## 8. Pass the Discriminator Test

Every adapter crate should include an integration test that proves the trait contract is correct end to end. This is the soundness proof - if this test passes, the provider plugs into any Suprnova app without surprises.

```rust,ignore
// tests/discriminator.rs (inside crates/suprnova-payments-mollie/)

use suprnova::payments::*;
use suprnova_payments_mollie::MollieProvider;

/// Requires MOLLIE_API_KEY and MOLLIE_WEBHOOK_SECRET to be set.
/// Run with: cargo test --test discriminator -- --ignored
#[tokio::test]
#[ignore = "requires live Mollie sandbox credentials"]
async fn discriminator_flow() {
    let provider = MollieProvider::from_env().expect("Mollie env vars not set");

    // 1. Create customer
    let cus = provider.create_customer(CreateCustomerRequest {
        user_id: "test_user_1".into(),
        email: "test@example.com".into(),
        name: Some("Test User".into()),
        metadata: None,
    }).await.expect("create_customer failed");
    assert!(!cus.provider_customer_id.is_empty());

    // 2. Start checkout session
    let session = provider.start_session(StartSessionRequest {
        mode: SessionMode::Subscription,
        customer_ref: cus.provider_customer_id.clone(),
        price_refs: vec!["your_mollie_plan_id".into()],
        success_return_url: "https://app.example/billing/success".into(),
        cancel_return_url: "https://app.example/billing/cancel".into(),
        amount_hint: None,
        idempotency_key: Some("discriminator_test_checkout".into()),
        metadata: None,
    }).await.expect("start_session failed");
    assert!(matches!(session, SessionPayload::Redirect { .. }));

    // 3. Subscribe directly (if your provider supports it; Mollie may require checkout)
    let sub = provider.subscribe(SubscribeRequest {
        customer_ref: cus.provider_customer_id.clone(),
        price_refs: vec!["your_mollie_plan_id".into()],
        trial_days: None,
        idempotency_key: Some("discriminator_test_sub".into()),
        metadata: None,
    }).await.expect("subscribe failed");
    assert_eq!(sub.status, SubscriptionStatus::Active);

    // 4. Read back
    let fetched = provider.get(&sub.provider_subscription_id).await.expect("get failed");
    assert_eq!(fetched.provider_subscription_id, sub.provider_subscription_id);

    // 5. Cancel at period end
    let s = provider.cancel(&sub.provider_subscription_id, true).await.expect("cancel failed");
    assert!(s.cancel_at_period_end);

    // 6. Cancel immediately
    let s = provider.cancel(&sub.provider_subscription_id, false).await.expect("cancel failed");
    assert_eq!(s.status, SubscriptionStatus::Canceled);

    // 7. Verify as_payment() invariant
    let p: &dyn PaymentProvider = &provider;
    // If you implemented Payment: assert!(p.as_payment().is_some())
    // If you did NOT implement Payment: assert!(p.as_payment().is_none())
    let _ = p.as_payment();
}
```

Gate live integration tests with `#[ignore]` so `cargo test` passes in CI without credentials. Run them explicitly with `-- --ignored` against a sandbox account.

## 9. `PaymentError` Variants Reference

The full enum lives in `framework/src/payments/error.rs`. Pick the variant that matches what actually went wrong:

| Variant | When to use |
|---|---|
| `Provider(String)` | The provider's API returned an error you don't need to translate further |
| `Validation(String)` | Request fields are invalid, or a webhook body won't parse |
| `NotSupported(String)` | The method isn't applicable for this provider (e.g. Paddle's `subscribe`) |
| `Declined { reason, decline_code }` | Card declined - pass `decline_code` through when the provider supplies one |
| `Authentication(String)` | Provider rejected your API key or credentials |
| `NotFound(String)` | Customer, subscription, or transaction ID doesn't exist |
| `WebhookSignature(String)` | Any signature failure - missing header, malformed encoding, or mismatch |
| `InvalidPhoneNumber(String)` | E.164 validation failed in mobile-money flows |
| `InvalidCountryCode(String)` | ISO-3166-1 alpha-2 validation failed |
| `Internal(String)` | Unexpected SDK error, network failure, HMAC init failure, or any other framework-side problem |
| `Database { context, source }` | A statement against the payments tables failed. `source` is the `suprnova::DbErr`; `?` converts a `DbErr` into this variant |

Give every call of your adapter a deadline. The Stripe and Paddle adapters use 30 seconds and report a call that runs out of time as `Provider`. For a call that only reads, the text is `<provider> <operation> timed out`. For a call that changes something, the text adds `; outcome is unknown, reconcile before retrying`, because the provider may have carried out the change. The error of a change never says that the call failed.

The webhook route maps these to status codes: `WebhookSignature(_)` → 401, `Validation(_)` from `parse_event` → 400, anything else from hydration → 503 (so the provider retries).

Once your adapter compiles and the discriminator test passes:

- Add your crate to your app's `Cargo.toml` with `cargo add suprnova-payments-mollie --path ./crates/suprnova-payments-mollie`.
- Register at bootstrap as shown in step 7.
- Mount `webhook_routes(db.clone())` once at app boot - the same handler dispatches to every registered provider by name, so a single mount serves Stripe, Paddle, and your new adapter.

## Next

- [Payments](payments.md) - the provider-neutral surface and Quick Start
- [Payments - Stripe Adapter](payments-stripe.md) - full template for a gateway adapter
- [Payments - Paddle Adapter](payments-paddle.md) - full template for a Merchant-of-Record adapter
- [Payments Frontend](payments-frontend.md) - how to render the `SessionPayload` your adapter returns
- [Error Model](error-model.md) - how `PaymentError` lands as an `HttpResponse`


# Frontend

---

<!-- /docs/frontend -->

# Frontend Overview

Suprnova bridges Rust handlers to a single-page frontend via
[Inertia.js](https://inertiajs.com/) 3.8.0. You write controllers in Rust
and pages in Svelte, React, or Vue; the framework moves typed props
between them without a separate HTTP API in the middle.

## Three first-class starters

`suprnova new <name>` scaffolds a working project. The `--frontend` flag
picks the SPA layer:

```bash
suprnova new my-app                       # Svelte 5 (default)
suprnova new my-app --frontend svelte     # Svelte 5
suprnova new my-app --frontend react      # React 19
suprnova new my-app --frontend vue        # Vue 3.5
```

All three scaffolds share the same stack:

| Layer | Version |
|---|---|
| Inertia client adapter | `@inertiajs/{svelte,react,vue3}` 3.8.0 |
| Inertia Vite plugin | `@inertiajs/vite` 3.8.0 |
| Build tool | Vite 8 |
| Styling | Tailwind v4 (`@tailwindcss/vite`) |
| TypeScript | strict mode |

The choice is per-project. There is no "primary" framework on the
server side - `inertia_response!` resolves whichever extension your
chosen scaffold uses (`.svelte`, `.tsx`, `.vue`), and `App::inertia_share`,
partial reloads, and TypeScript prop generation all behave identically
across the three.

## Architecture

```
                       Browser
   +-------------------------------------------------+
   |               SPA (Svelte / React / Vue)        |
   |   +---------------+ +---------------+           |
   |   | Home.svelte   | | Users/Show.tsx|  ...      |
   |   +-------+-------+ +-------+-------+           |
   |           |  typed props from Rust struct       |
   |   +-------v-------------------------------+     |
   |   |        Inertia client adapter         |     |
   +---+------------------+------------------+--+----+
                          |
                          |   HTTP (JSON on XHR, HTML on first load)
                          v
   +-------------------------------------------------+
   |                  Suprnova server                |
   |   +------------------------------------------+  |
   |   |          Controllers / handlers          |  |
   |   |   inertia_response!(&req, "Home",        |  |
   |   |                     HomeProps { ... })   |  |
   |   +------------------------------------------+  |
   +-------------------------------------------------+
```

The first request returns an HTML shell with the initial page object as
JSON in a `<script type="application/json" data-page="app">` element, the
sibling just before the empty `<div id="app">` mount node - where the
Inertia 3 client reads it. Subsequent visits go through `<Link>` /
`router.visit`, send `X-Inertia: true`, and get back a JSON page object -
the adapter swaps the component without a full reload.

## A complete page round-trip

The controller defines its props as a Rust struct, derives
`InertiaProps`, and hands the value to the `inertia_response!` macro:

```rust
use suprnova::{InertiaProps, Request, Response, inertia_response};

#[derive(InertiaProps)]
pub struct HomeProps {
    pub title: String,
    pub message: String,
}

pub async fn index(req: Request) -> Response {
    inertia_response!(&req, "Home", HomeProps {
        title: "Welcome".into(),
        message: "Hello from Suprnova!".into(),
    })
}
```

The props are sent under the names serde's attributes give them:
`#[serde(rename_all = "camelCase")]` on the struct sends a `current_user`
field as `currentUser`, and `#[serde(rename = "..")]`, `#[serde(skip)]` and
`#[serde(skip_serializing)]` work on a field. Props are only serialized, so
the derive reads the serialize side, and leaves a `deserialize` half and
`skip_deserializing` to a `Deserialize` derive on the same struct. It
refuses any other serde attribute, and two props under one key.

A few things the macro does for you. First, it validates at compile
time that the page component file actually exists under
`frontend/src/pages/Home.{svelte,tsx,jsx,vue}` - typos surface as a
build error, not a 404 in the browser. Second, it serializes the
`HomeProps` struct, unfolds it into one prop per top-level key so
partial reloads can filter, and resolves any lazy or deferred props
against `&req` before returning. The macro evaluates to a
`Result<HttpResponse, FrameworkError>`, which the `Response` return type
accepts directly.

The matching Svelte page (the default scaffold):

```svelte
<!-- frontend/src/pages/Home.svelte -->
<script lang="ts">
  import type { HomeProps } from '../types/inertia-props'

  let { title, message }: HomeProps = $props()
</script>

<div class="font-sans p-8 max-w-xl mx-auto">
  <h1 class="text-3xl font-bold">{title}</h1>
  <p class="mt-2">{message}</p>
</div>
```

For the React and Vue equivalents see [Page Components](frontend-pages.md).

## Generating TypeScript types

Every `#[derive(InertiaProps)]` struct in your `src/` becomes a
TypeScript interface in `frontend/src/types/inertia-props.ts`:

```bash
suprnova generate-types
```

Pass `--routes` and the same command also emits
`frontend/src/types/routes.ts` - type-safe URL + method pairs scraped
from your `routes!` macro that work directly with Inertia v2+ APIs. The full type-mapping table and
route-helper shape live in [TypeScript Types](frontend-typescript-types.md).

## Shared data

Anything that should appear on every page (the authenticated user, the
current locale, app metadata) is registered once at boot and merged into
every Inertia response:

```rust
// In bootstrap.rs
App::inertia_share("appName", "Suprnova");
App::inertia_share("appVersion", env!("CARGO_PKG_VERSION"));

// Async / per-request shared data goes through the trait.
App::register_inertia_shared(Arc::new(AppSharedData));
```

The flavours, in order of precedence (later wins at the same key):

| API | When the value materializes |
|---|---|
| `App::inertia_share(k, v)` | Sync, set once at boot |
| `App::inertia_share_lazy(k, \|\| async { ... })` | Per response, recomputed |
| `App::inertia_share_once(k, \|\| async { ... })` | Per response, then client-cached |
| `App::inertia_registry().share_provider(provider)` | Per response, expanded with the page and the request; any number |
| `App::register_inertia_shared(Arc::new(impl))` | Per request, sees `&req` |

Per-page props attached on the response builder always overwrite shared
data at the same key.

The `Inertia` facade takes every form Laravel's `Inertia::share` does - a
key and a value, a map, a `#[derive(Data)]` object or a provider - and reads
shared data back with `get_shared`:

```rust
use suprnova::Inertia;

Inertia::share("appName", "Suprnova")?;
Inertia::share("user.locale", "es")?;              // nests: user = { locale: "es" }
Inertia::share_many([("plan", "pro"), ("region", "eu")])?;
Inertia::share_data(SiteMeta { name: "Suprnova".into(), build: 7 })?;
Inertia::share_provider(TenantShare);              // a ProvidesInertiaProperties value

Inertia::get_shared("user.locale", serde_json::Value::Null); // "es"
Inertia::get_shared("missing", 7);                            // 7
Inertia::get_shared_all();                                    // every shared value, nested
```

A dotted key nests when it is shared, as Laravel's `Arr::set` does, so a
later `share("user", ...)` replaces the whole `user` object, child included.
`App::inertia_share` shares the same way. A Data object shares its eager
fields; its lazy fields stay out, since a shared prop has no `?include=`
gate. `share_provider` takes a `ProvidesInertiaProperties` value, the same
registration as `InertiaRegistry::share_provider`: any number of providers,
each expanded once per render with a `RenderContext` of the request and the
component, and `App::flush_inertia_shared` clears them with the other shares.
`App::register_inertia_shared` is the one-slot async provider
(`InertiaSharedData`) and stays beside it. `get_shared` reads what is
registered without resolving it, so a lazy share reads as the default.

The framework ships `RootShare`, a provider that gives every page the
public root as the `root` prop: the empty string at the host root,
`/billing` behind a reverse proxy that serves the application under
`/billing`. A page that builds its URLs from it, such as
`` form.post(`${root}/login`) ``, runs from one build at `/` and under a
prefix. An application registers one provider, so `RootShare` carries
another one and shares its props too:

```rust
App::register_inertia_shared(Arc::new(RootShare::around(Arc::new(LocaleShare))));
```

A scaffolded application registers it this way, builds its pages' URLs
from `root`, and builds its frontend with Vite's relative `base: './'`, so
code-split chunks load from wherever the entry script was served. For the
proxy setup, see [Serving under a path prefix](deployment.md#serving-under-a-path-prefix).

## Partial reloads and lazy props

The same `InertiaResponse` builder exposes Inertia v3's full prop
toolkit - eager, lazy, optional, deferred, merge, once - and Suprnova
honors the v3 partial-reload headers (`X-Inertia-Partial-Data`,
`X-Inertia-Partial-Except`, `X-Inertia-Reset`,
`X-Inertia-Except-Once-Props`) automatically. The example below
attaches three props with different evaluation rules:

```rust
use suprnova::{InertiaResponse, FrameworkError, Request, Response};

pub async fn dashboard(req: Request) -> Response {
    let resp = InertiaResponse::new("Dashboard")
        .with("title", "Dashboard")
        .lazy("recent_orders", || async {
            Ok::<_, FrameworkError>(load_recent_orders().await?)
        })
        .defer("notifications", || async {
            Ok::<_, FrameworkError>(load_notifications().await?)
        })
        .resolve(&req)
        .await?;
    Ok(resp)
}
```

`inertia_response!` covers the eager-props case; everything past that
goes through the builder. The full surface - `optional`, `merge`,
`once`, `scroll`, `flash`, `paginate`, SSR, version mismatch, history
encryption - is documented in
[Inertia Responses](frontend-inertia-responses.md).

## Bootstrap

A scaffolded app installs the five protocol middlewares in one call
inside `bootstrap.rs`:

```rust
use suprnova::{Inertia, InertiaConfig};

Inertia::install(&InertiaConfig::new().version(env!("CARGO_PKG_VERSION")))
    .expect("Inertia install failed");
```

`install` returns `Result` - it fails closed if `InertiaConfig` resolves to
production mode (the default under `APP_ENV=production`) but no Vite
manifest can be found, rather than silently falling back to a legacy
asset path. See [Development vs production](#development-vs-production)
below.

That registers, in order: `InertiaHeadersMiddleware` (sets `Vary: X-Inertia`
on every response and turns an empty `200` on an Inertia visit into a
redirect back), `InertiaVersionMiddleware` (emits 409 + `X-Inertia-Location` on
asset-version mismatch so stale clients reload), `Inertia303Middleware`
(rewrites 302 → 303 on Inertia `PUT`, `PATCH` and `DELETE` visits so the
follow-up is unambiguously a GET), `InertiaErrorPageMiddleware` (hands the framework's
own error responses to your error callback or the configured error page,
and changes nothing without either), and
`InertiaValidationRedirectMiddleware` (turns a `422` on an Inertia visit
into a `303` back to the form page with the errors flashed).
`InertiaVersionMiddleware` and `Inertia303Middleware` used to require
separate registration; `Inertia::install` makes all five the default. See [Inertia Responses](frontend-inertia-responses.md#bootstrap-inertiainstall)
for the full registration order and what each middleware closes.

With `.devtools(DevToolsConfig::new())`, `install` also registers the
recorder of the Inertia DevTools browser extension when `APP_ENV=local`.
It sits outermost in the Inertia layer, stores an entry for each request
and answers the
extension's `/_inertia/devtools/entries` endpoints. See
[Inertia DevTools](frontend-inertia-devtools.md) to switch it on elsewhere,
gate it, or turn it off.

## Development vs production

In development, the Vite dev server runs alongside the backend and
serves HMR-enabled assets:

```bash
suprnova serve
```

This boots the Rust server and `vite` together. The HTML shell loads
modules from `http://localhost:5765`.

For production, build the frontend once and point the backend at the
hashed manifest under `public/assets/`:

```bash
cd frontend && npm run build
APP_ENV=production suprnova serve --backend-only
```

`InertiaConfig::default()` derives production vs. development mode from
`APP_ENV` (via `Environment::detect().is_production()`) - `APP_ENV=production`
is what makes the HTML shell load built assets instead of the Vite dev
server. `Inertia::install` then fails boot loudly if it can't find a
manifest to back that decision, rather than silently falling back to a
stale hardcoded path.

Suprnova reads `public/assets/.vite/manifest.json` to resolve hashed
entry points plus any transitive imports for `modulepreload`. SSR is
optional - opt in by pointing `InertiaConfig::ssr(...)` at a running
`@inertiajs/{vue3,react,svelte}/server` worker. `suprnova new` scaffolds
an SSR entry point and build script for every starter, and the
`ssr:start`, `ssr:stop`, and `ssr:check` commands of the application
binary and of the `suprnova` CLI run, stop, and check the worker;
see [Inertia Responses](frontend-inertia-responses.md#ssr) for the full
setup, including the bundle-existence check and CSR fallback behavior.

### Why Suprnova diverges

Three intentional departures from how a typical Inertia setup looks
elsewhere:

- **Compile-time component validation.** The `inertia_response!` macro
  walks `frontend/src/pages/` at build time and refuses to expand if
  the component file is missing, suggesting the closest match. You
  cannot ship a controller that points at a deleted page.
- **Typed props as the source of truth.** Page props are Rust structs
  with `#[derive(InertiaProps)]`. `suprnova generate-types` reads them
  and writes TypeScript interfaces - the frontend types are derived
  from the backend, not maintained in parallel.
- **Svelte as the default.** Inertia's documentation reaches for Vue and
  React first; the Suprnova scaffolder defaults to Svelte 5 (runes-on).
  React 19 and Vue 3.5 are first-class, not afterthoughts - same
  protocol, same prop pipeline, same generator output.

## Working with a coding assistant

A coding assistant that learned Inertia from Laravel projects carries
assumptions that are wrong here. Laravel's own guideline set for assistants
(the Inertia section of Laravel Boost) covers this ground for a PHP project;
this is the Suprnova version. Paste it, or point the assistant at this
chapter, before it touches a page:

- **Pages live in `frontend/src/pages/`**, one component per file. A handler
  renders one with `inertia_response!` or `InertiaResponse::new`, never with
  a server template. The first visit's document is `templates/app.html`, the
  root template, and the page is never written into it.
- **Props are typed on the server.** Each page has a `#[derive(InertiaProps)]`
  struct, and `suprnova generate-types` (or `suprnova serve`, which runs it
  on change) writes `frontend/src/types/inertia-props.ts`. After a Rust field
  changes, regenerate and let the TypeScript compiler name every component to
  update. The generated file is never edited by hand.
- **Every Inertia 3 feature is available**: deferred props, infinite scroll,
  merging props, polling, prefetching, once props and flash data, and the
  Inertia 3 additions, standalone HTTP requests (`useHttp`), optimistic
  updates with rollback, layout props (`useLayoutProps`), instant visits and
  SSR through the Vite plugin. The server side of each is a method on the
  `InertiaResponse` builder; [Inertia Responses](frontend-inertia-responses.md)
  lists them. Prop types (`optional`, `defer`, `merge`) take dot-notation
  paths, and a dotted partial reload narrows literal values only.
- **Names that moved.** Inertia 3 removed `Inertia::lazy()`: use
  `.optional()` for a prop skipped on the first visit. Suprnova's `.lazy()` is
  a plain callable prop that resolves on every visit that selects it (see the
  divergence callout in Inertia Responses). On the client, Axios is gone and
  the built-in XHR client with interceptors replaces it, `router.cancel()` is
  `router.cancelAll()`, the `invalid` event is `httpException` and `exception`
  is `networkError`, and the `future` configuration namespace no longer
  exists.
- **Deferred props need an empty state.** The page renders before they
  arrive, so a component that shows one carries a skeleton or a placeholder
  for the gap.
- **Tests drive the server in process.** A test calls `handle_request` and
  reads the page object with `AssertableInertia`, from a JSON visit or from
  the first-load HTML ([HTTP Tests](http-tests.md#testing-inertia-responses)).
  A page change lands with such a test.
- **Check the version.** An assistant's training data describes Inertia 1 and
  2 as often as 3. Have it read the Inertia 3 documentation and this manual
  for anything protocol-level rather than recall it.

## Next

- [Page Components](frontend-pages.md)
- [Inertia Responses](frontend-inertia-responses.md)
- [Inertia DevTools](frontend-inertia-devtools.md)
- [TypeScript Types](frontend-typescript-types.md)
- [Routing](routing.md)
- [Controllers](controllers.md)


---

<!-- /docs/frontend-inertia-responses -->

# Inertia Responses

Inertia responses are how a Suprnova handler ships state to a Svelte / React /
Vue page component. Every handler that renders an Inertia page returns one,
built either through the [`inertia_response!`](#the-inertia_response-macro)
macro (for typed, compile-time-checked eager props) or the
[`InertiaResponse`](#the-inertiaresponse-builder) builder (for everything
else - lazy props, deferred props, merge, once, scroll, flash). This
chapter covers the response surface end-to-end: the macro, the builder, the
v3 protocol features (partial reloads, history encryption, version
detection), shared data via `App::inertia_share*`, and the flash bag carried
across redirects.

If you haven't picked a frontend yet, [Frontend Overview](frontend.md) and
[Page Components](frontend-pages.md) come first; this chapter assumes the
SPA bridge is wired and focuses on what your handler returns.

## The `inertia_response!` macro

The macro is the shortest path from a handler to a typed eager page. It
takes the current request, a component name, and a props expression:

```rust
use suprnova::{Request, Response, inertia_response, InertiaProps};

#[derive(InertiaProps)]
pub struct HomeProps {
    pub title: String,
    pub message: String,
}

pub async fn index(req: Request) -> Response {
    inertia_response!(&req, "Home", HomeProps {
        title: "Welcome".into(),
        message: "Hello from Suprnova!".into(),
    })
}
```

Three things to know:

- **The leading `&req` is required.** The macro reads `X-Inertia` headers,
  the URL, and the partial-reload filtering headers off the request, so it
  needs the request value (or a reference). Without it, partial reloads
  would silently break.
- **Component existence is checked at compile time.** The macro looks for
  `frontend/src/pages/<Component>.{svelte,tsx,jsx,vue}`; if no file
  matches, the build fails with a "did you mean…?" suggestion sourced from
  the actual filenames on disk. Nested paths work the same way -
  `inertia_response!(&req, "Admin/Dashboard", …)` resolves
  `frontend/src/pages/Admin/Dashboard.svelte` (or your frontend's
  extension). A project with another page layout sets its own lookup in
  `Cargo.toml`; see [Another page layout](frontend-pages.md#another-page-layout).
- **The macro expands to an `await`ed `Result`.** Your handler must
  return [`Response`](error-model.md) (which is
  `Result<HttpResponse, HttpResponse>`) or another type that absorbs
  `FrameworkError` through `?` / `From`. Failures during prop
  serialization or response building are returned as `Err`, not panics.

For a page with no logic at all - about, terms, privacy - skip the
handler entirely and declare the route:

```rust
use suprnova::Router;
use serde_json::json;

let router = Router::new().inertia("/about", "About", json!({ "team_size": 4 }));
```

See [Routing](routing.md#router-level-redirects-and-views). The
component there is a runtime string, so it doesn't get this macro's
compile-time existence check - that's the trade for not writing the
handler.

### JSON-style props

For prototyping and tiny pages you can skip the typed struct:

```rust
inertia_response!(&req, "Dashboard", {
    "user": { "name": "John" },
    "stats": { "visits": 1234 }
})
```

The macro still validates the component file. The trade-off is that you
lose the typed-prop chain - no `#[derive(InertiaProps)]`, no automatic
TypeScript generation, no compile-time check that the frontend's
expected shape matches.

### Optional config override

The macro accepts an optional trailing `InertiaConfig` for per-response
overrides (different SSR settings, a custom default title for one page):

```rust
let cfg = InertiaConfig::new().default_title("Reports");
inertia_response!(&req, "Reports/Index", props, cfg)
```

Most apps register a single config at boot via [`Inertia::install`](#bootstrap-inertiainstall)
and never touch this argument - the installed config is already what
every response starts from. Pass one here only to override the installed
config for a single page.

## `#[derive(InertiaProps)]`

`InertiaProps` emits a `Serialize` impl whose key names match your field
names. It exists so the typed-props path stays terse and so the
TypeScript generator (`suprnova generate-types`) has a marker to find:

```rust
use suprnova::InertiaProps;

#[derive(InertiaProps)]
pub struct UserProps {
    pub name: String,
    pub email: String,
    pub role: String,
    pub is_active: bool,
}
```

Nested types compose normally - fields can be `Vec<T>`, `Option<T>`,
nested structs, anything `Serialize`-able. The nested types themselves
don't have to derive `InertiaProps`; they just need `Serialize`. Use
`#[derive(InertiaProps)]` on the *top-level* props struct and you get
the automatic TypeScript surface (see [TypeScript Types](frontend-typescript-types.md))
for the whole tree.

## The `InertiaResponse` builder

The macro covers eager typed props. Anything else - lazy, optional, deferred,
mergeable, cached-on-client, flash, history-encryption overrides - uses
the builder directly:

```rust
use suprnova::{InertiaResponse, Request, Response, FrameworkError, HttpResponse};

pub async fn show(req: Request) -> Response {
    let resp = InertiaResponse::new("Posts/Show")
        .with("title", "Welcome")
        .with("post", load_post(42).await?)
        // Lazy: closure runs only when the prop will actually be sent
        // (initial visit, or partial reload that requests this key).
        .lazy("recent_activity", || async {
            Ok::<_, FrameworkError>(load_activity().await?)
        })
        // Optional: never sent on initial visits; the client must
        // explicitly ask for the key via X-Inertia-Partial-Data.
        .optional("permissions", || async {
            Ok::<_, FrameworkError>(load_permissions().await?)
        })
        // Defer: skipped on the initial render; the client issues a
        // follow-up XHR and the closure runs then.
        .defer("notifications", || async {
            Ok::<_, FrameworkError>(load_notifications().await?)
        })
        // Merge: append-into-existing on partial reloads ("load more").
        .merge("rows", next_page().await?)
        // Once: cached client-side across navigations; resolver skipped
        // on subsequent visits unless server forces refresh.
        .once("plans", || async {
            Ok::<_, FrameworkError>(load_plan_catalog().await?)
        })
        // Flash: one-shot toast; appears under `page.flash`, not `props`.
        .flash("toast", serde_json::json!({"type":"info","msg":"Saved"}))
        .resolve(&req)
        .await
        .map_err(HttpResponse::from)?;
    Ok(resp)
}
```

| Method | Purpose | Maps to Laravel |
|---|---|---|
| `.with(k, v)` | Eager prop, honours partial-reload filtering | typed prop |
| `.always(k, v)` | Eager prop, ignores partial-reload filters | `Inertia::always(…)` |
| `.always_with(k, ‖)` | Async resolver, ignores partial-reload filters | `Inertia::always(fn () => …)` |
| `.lazy(k, ‖)` | Resolver runs only when prop will be sent | `fn () => …` closure |
| `.optional(k, ‖)` | Never on initial visit; must be requested explicitly | `Inertia::optional(…)` |
| `.defer(k, ‖)` / `.defer_with(...)` | Initial-visit-skipped; follow-up XHR triggers resolution | `Inertia::defer(…)` |
| `.merge` / `.merge_prepend` / `.deep_merge` / `.merge_with` | Combine with existing client state on partial reloads | `Inertia::merge` / `deepMerge` |
| `.once(k, ‖)` / `.once_with(…)` | Client caches across navigations | `Inertia::once(…)` |
| `.scroll` / `.scroll_with` / `.scroll_wrapped` / `.scroll_with_wrapped` / `.scroll_lazy` / `.scroll_lazy_with` / `.paginate` (via `Inertia::paginate`) | Infinite-scroll pagination | `Inertia::scroll(…)` |
| `.flash(k, v)` | One-shot value under `page.flash` (not `props`), kept in the session until a page shows it | `Inertia::render(…)->flash(…)` |
| `.title(…)` | Default `<title>` for the HTML shell | `Inertia::render(…)->title(…)` |
| `.encrypt_history(bool)` | Per-response history encryption | `Inertia::encryptHistory(…)` |
| `.clear_history()` | Force history key rotation on **this** page | `Inertia::clearHistory()` |
| `.preserve_fragment(bool)` | Keep `#fragment` after Inertia visit | `Inertia::preserveFragment()` |

Eager builder methods have `try_*` siblings (`try_with`, `try_always`,
`try_merge_with`, `try_scroll`, `try_scroll_wrapped`, `try_flash`) that return
`Result<Self, FrameworkError>` when a value's `Serialize` impl might
fail at runtime - the infallible methods convert the panic into a 500
via [the panic boundary](error-model.md), so reach for `try_*` when
you'd rather handle the failure explicitly.

`.clear_history()` marks the response you are building. A logout handler
redirects, and the browser discards the redirect's response - so the login
page, not the logout response, is the one that has to carry the flag.
`App::clear_history()` (also `Inertia::clear_history()`) is the fix for that
case - it's a free function, not a builder method, so it isn't in the table
above. It sets the session entry `inertia.clear_history`, which the next
Inertia page object turns into `clearHistory: true` and removes. It needs a
session scope, and it lasts until a page emits it, however many redirects
come first, so a logout that bounces through two redirects still clears.

Call it **after** `Auth::logout()` / `Auth::logout_and_invalidate()`, not
before - invalidation flushes the whole session, and the flag lives in
that session, so flashing it first only gets erased by the flush:

```rust
use suprnova::{App, Auth, Redirect, Response};

pub async fn logout() -> Response {
    Auth::logout_and_invalidate().await?;
    App::clear_history();
    Redirect::to("/login").into()
}
```

### Composing flags on one prop

The methods above each set one flag. A prop can carry several, and some
combinations are how the Inertia protocol expects real pages to work: a
deferred list that appends into what the client already rendered, a
merge prop the client caches across navigations, an optional prop with
its own cache key. Build the prop with `Prop`, then attach it with
`.prop(key, prop)`:

```rust
use suprnova::{InertiaResponse, Prop};
use serde_json::json;

InertiaResponse::new("Feed/Index").prop(
    "posts",
    Prop::lazy(|| async { json!([{ "id": 1 }]) })
        .defer()
        .merge()
        .match_on("id"),
)
```

That prop is skipped on the first render and announced under
`deferredProps`. The client issues its follow-up request, the resolver
runs, and the value arrives with a `mergeProps` instruction, so it
appends to the list already on screen instead of replacing it.

The flags fall into five groups:

| Group | Methods | Effect |
|---|---|---|
| Visibility | `.always()`, `.optional()`, `.defer()` | Mutually exclusive; the last call wins |
| Defer detail | `.group(name)`, `.rescue()` | Read only when the prop is deferred |
| Merge | `.merge()`, `.prepend()`, `.deep_merge()`, `.append_at(paths, match_on)`, `.prepend_at(paths, match_on)`, `.match_on(fields)`, `.merge_with_path(path)` | How the client folds the value in, and at which path |
| Client cache | `.once()`, `.once_with(options)`, `.as_key(key)`, `.until(moment or span)`, `.fresh(bool)` | Whether the client keeps the value across navigations - see [Once props](#once-props) |
| Scroll | `.scroll(metadata)`, `.scroll_wrap(key)`, `.scroll_at_root()` | Infinite-scroll `scrollProps` entry plus unconditional merge metadata under the wrapper (`data` by default); `.scroll_wrap` and `.scroll_at_root` read only when `.scroll` is set |

Sources are `Prop::eager(value)`, `Prop::lazy(closure)`,
`Prop::from_resolver(resolver)` for a resolver you built yourself, and
`Prop::absent()` for a prop that never reaches the response - what
`when_loaded!` returns for an unloaded relation.

Two rules are worth knowing before you compose:

- **Visibility is one setting, not three flags.** `.always().optional()`
  is an optional prop, and `.optional().always()` is an always prop.
  Neither is an error; the earlier call is erased.
- **Metadata follows the partial-reload lists, not the value.** A prop's
  `mergeProps` and `onceProps` entries are emitted whenever an
  `X-Inertia-Partial-Data` entry names the prop or an ancestor of it (or
  there is no such list) and no `X-Inertia-Partial-Except` entry does,
  even on a visit where the value itself is withheld. That is what
  carries the merge instruction across a deferred prop's two requests.
  Its `scrollProps` entry needs only that the key passes the lists. The
  consequences:
  - An entry deeper than the prop selects the prop but carries no
    instruction: `only: ['items.data']` against a merge prop `items`
    sends the whole value with no `mergeProps` entry, so the client
    replaces what it holds, as Laravel's `isIncludedInPartialMetadata`
    rules. A scroll prop keeps its cursor in that case.
  - A `.once()` prop the client already holds, and that is not deferred,
    sends its `onceProps` entry and nothing else - no `mergeProps` entry,
    since no new value arrives to merge. A held `.scroll().once()` prop
    keeps its cursor too.
  - An `.always().merge()` prop outside the requested set still sends its
    value and does not send its merge instruction, so the client replaces
    rather than appends.
  - `scrollProps` has one extra condition on top of the lists: a
    `.scroll().defer()` prop announces its merge instruction at the bare
    key on a non-partial visit but ships no cursor there, because nothing
    is on screen yet for a cursor to describe. Every matched partial
    reload gets the cursor and the instruction under the wrapper, whether
    or not that request also resolves the value.
  - `deferredProps` is the one block the lists never govern. It is
    dropped whole on any matched partial reload, no matter what the
    lists say - Laravel's `resolveDeferredProps` returns `[]` the
    moment the request is partial. A partial reload is the client
    working through announcements it already holds, so re-announcing
    the keys it left out of this round would send it back for them
    again. A partial reload aimed at a *different* component is a
    standard visit for every gate, announcements included.

`.group(name)` and `.rescue()` are stored on any prop but only read when
the prop is deferred, so `.rescue().defer()` and `.defer().rescue()`
mean the same thing. A scroll prop takes its merge direction from the
client's `X-Inertia-Infinite-Scroll-Merge-Intent` header, so `.merge()`
and `.prepend()` on a scroll prop are redundant and not read.
`.deep_merge()` is the exception: it routes the prop into
`deepMergeProps` instead of `mergeProps`, the same way Laravel's
`ScrollProp` does.

### Once props

A once prop is resolved the first time a page needs it and then kept by
the client across navigations: on later visits the client lists its key
in `X-Inertia-Except-Once-Props` and the server skips the resolver. The
options are Laravel's:

```rust
use suprnova::{InertiaResponse, OnceOptions, Prop};
use serde_json::json;

InertiaResponse::new("Billing/Index")
    // Inertia::once(fn () => ...)->as('plans')->until(3600)
    .once_with("planCatalog", OnceOptions::new().as_key("plans").until(3600), || async {
        Ok::<_, suprnova::FrameworkError>(load_plans().await?)
    })
    // The same options on a composed prop.
    .prop(
        "rates",
        Prop::lazy(|| async { json!({ "usd": 1 }) })
            .defer()
            .once()
            .until(suprnova::chrono::Duration::minutes(5))
            .fresh(false),
    )
```

| Option | Laravel | Effect |
|---|---|---|
| `.as_key(key)` | `as($key)` | The cache key the client dedupes on, the prop's name by default. A string, or an enum whose `Display` names the key |
| `.until(span or moment)` | `until($delay)` | When the client drops its copy. A whole number of seconds, a `std::time::Duration` or a `chrono::Duration` counts from the render; a `DateTime<Utc>` is that moment |
| `.fresh(bool)` | `fresh($value)` | `true` resolves even when the client claims a copy; `false` honours the claim again |
| `OnceOptions::once(bool)` | `once($value)` | `false` turns the flag off, leaving an ordinary prop |

`Prop::once_with(options)` and `InertiaResponse::once_with(key, options,
resolver)` take all of them at once, Laravel's `once($value, $as,
$until)`; a setting the options leave unset keeps what the prop already
has.

The page object carries the expiry as `onceProps.<key>.expiresAt`, in
milliseconds since the epoch, counted in whole seconds as Laravel counts
it: `.until(60)` on a page rendered at second `t` gives `(t + 60) * 1000`.
A moment already past gives the render moment.

The server also enforces a moment itself, which Laravel leaves to the
client: once `.until(deadline)` has passed, a client that still lists the
key in `X-Inertia-Except-Once-Props` gets a fresh value instead of nothing,
so a stale client cannot pin an old value. A span is counted from each
render, so it is the client's own expiry that ends it.

### Merge strategies and infinite scroll

`.merge` (append), `.merge_prepend`, and `.deep_merge` cover the common
"load more" cases. To diff-merge - update rows the client already holds
instead of duplicating them - reach for `.merge_with` with an explicit
`MergeStrategy` carrying a `match_on` key:

```rust
use suprnova::{InertiaResponse, MergeStrategy};

InertiaResponse::new("Feed/Index")
    .merge_with(
        "posts",
        next_page,                                     // the new page slice
        MergeStrategy::Append { match_on: Some(vec!["id".into()]) },
    )
```

`match_on` names the field(s) the client dedupes on (emitted to the page
object as `matchPropsOn`) - one field or several, the same as
`Prop::match_on` (below) - so a refetch that overlaps the current window
replaces matching rows in place rather than appending copies. `Prepend`
and `Deep` take the same `match_on`.

`MergeStrategy` is the one-call form. `Prop::merge()` / `.prepend()` /
`.deep_merge()` / `.match_on(field)` are the same settings as separate
flags, for when the prop also needs a visibility or cache flag - see
[Composing flags on one prop](#composing-flags-on-one-prop).

`.match_on` takes one field or several in one call
(`.match_on(["id", "slug"])`). Each call replaces the list, as Laravel's
`matchOn` does, so `.match_on("id").match_on("slug")` dedupes on `slug`
alone.

To merge only part of a prop's value instead of the whole thing, name
the nested path with `.append_at` or `.prepend_at` - Laravel's
`append($path, $matchOn)` and `prepend($path, $matchOn)`:

```rust
use suprnova::{InertiaResponse, Prop};
use serde_json::json;

InertiaResponse::new("Feed/Index").prop(
    "posts",
    Prop::eager(json!({ "data": next_page, "meta": meta })).append_at("data", "id"),
)
```

`mergeProps` now carries `"posts.data"` instead of `"posts"`, so only
`props.posts.data` folds into what the client already holds -
`props.posts.meta` is replaced outright, like any non-merge prop. The
second argument names the field to dedupe on at that path and adds
`"posts.data.id"` to `matchPropsOn`; pass `None` for no dedupe field.
The first argument takes one path or several:
`.append_at(["a.items", "b"], "id")` merges at both paths and adds
`"<key>.a.items.id"` and `"<key>.b.id"`. Calls accumulate, and one prop
can append at one path and prepend at another:

```rust
Prop::eager(json!({ "older": older, "newer": newer }))
    .append_at("older", None)
    .prepend_at("newer", "id")
```

That prop emits `mergeProps: ["activity.older"]`,
`prependProps: ["activity.newer"]` and
`matchPropsOn: ["activity.newer.id"]` under the key `activity`. Naming a
path turns off root-level merging for that prop entirely - a
path-merging prop never also merges its whole value. `.append_at` and
`.prepend_at` turn merging on by themselves, so the prop needs no
`.merge()`. A later `.match_on(...)` replaces the fields they added, as
it does in Laravel. `.deep_merge()` ignores the paths - a deep merge
already recurses into every nested field, so there's nothing a path
narrows.

`.merge_with_path(path)` is the older single-path form: it merges at the
path in the prop's own direction (`.merge()` or `.prepend()`) and adds no
dedupe field, so pair it with `.match_on("data.id")` yourself.

A merge prop's value can come from a resolver too, via `.merge_lazy` /
`.merge_lazy_with` - the resolver sibling of `.merge` / `.merge_with`:

```rust
InertiaResponse::new("Feed/Index").merge_lazy("posts", || async {
    Ok::<_, FrameworkError>(load_next_page().await?)
})
```

The resolver runs only when the merge prop will actually be sent -
skipped by partial-reload filtering and by `.defer()` like any other
resolver-backed prop.

Infinite scroll is the same machinery with pagination metadata attached.
`.scroll` / `.scroll_with` - or `.paginate`, which adapts a
`LengthAwarePaginator`, `Paginator` or `CursorPaginator` directly - emit
`scrollProps` next to the data, and the client's `<InfiniteScroll>`
component drives the next/previous fetches:

```rust
// `posts` is a CursorPaginator from the query builder.
InertiaResponse::new("Feed/Index").paginate("posts", posts)
```

A scroll prop merges under a wrapper, `data` by default, as Laravel's
`Inertia::scroll($value, $wrapper = 'data')` does: a paginator or resource
serializes its rows under `data`, and only the rows should fold into what
the client already holds. `.scroll("posts", metadata, value)` emits
`mergeProps: ["posts.data"]`. `.paginate` is the exception: it ships the
paginator's rows as a bare list, so it merges at the prop's root
(`mergeProps: ["posts"]`); under `posts.data` the client would find no
list to append to. Reach for `Prop::scroll_at_root()` for any other value
that is the list itself.

A scroll prop always carries merge metadata, not just on a follow-up
fetch: it defaults to append, and switches to prepend only when the
client's `X-Inertia-Infinite-Scroll-Merge-Intent` header says so (`append`
when scrolling down, `prepend` when scrolling up). `reset` is independent
of that header - it's `true` exactly when the client named the key in
`X-Inertia-Reset`, the same header a regular merge prop reads. A fresh,
unfiltered visit sends neither header, so it gets `reset: false` and an
append instruction, matching Laravel.

`.merge_with_path` has no effect on a scroll prop - the scroll block that
computes its merge instruction reads the prop's single wrapper, not
`.merge_with_path`'s accumulated path list. `.scroll_wrap` - reached
directly through `.prop(...)`, or through the `.scroll_wrapped` response
shortcut below - names another wrapper.

A scroll prop also honors `.match_on(...)`, the same as any other merge
prop - reach it through `.prop(...)`, since neither `.scroll` nor
`.match_on` has a combined response-level shortcut. The path is relative
to the prop, as in Laravel, with no wrapper prefix added, so name the
wrapper in it:

```rust
InertiaResponse::new("Users/Index").prop(
    "users",
    Prop::eager(serde_json::json!({ "data": rows }))
        .scroll(ScrollMetadata::new("page").current(1).next(2))
        .match_on("data.id"),
)
```

That emits `matchPropsOn: ["users.data.id"]`, which the client matches
against the `users.data` merge path. `.match_on("id")` would emit
`"users.id"`, which lines up with a scroll prop merging at its root
(`.paginate`, `.scroll_at_root()`) and with nothing under a wrapper.

When the value's list sits under another field - `{ items: [...],
meta: {...} }` - point the merge at that field with `.scroll_wrapped`:

```rust
InertiaResponse::new("Feed/Index").scroll_wrapped(
    "posts",
    "items",
    ScrollMetadata::new("page").current(2).next(3),
    serde_json::json!({ "items": rows, "meta": { "total": total } }),
)
```

`mergeProps` then names `posts.items`, so the client folds new rows into
the nested array and leaves `meta` to be replaced wholesale each time.
`.scroll_with_wrapped` and `try_scroll_wrapped` are the resolver-based and
fallible siblings, matching `.scroll_with` / `try_scroll`.

A deferred scroll prop (`Prop::lazy(...).scroll(metadata).defer()`)
announces its bare key under `mergeProps` on the visit that withholds it,
and `posts.data` on the follow-up request that delivers the rows, as
Laravel does.

The metadata argument of `.scroll` takes a `ScrollMetadata` or anything
that implements `ProvidesScrollMetadata`, Laravel's interface of the same
name. `LengthAwarePaginator`, `Paginator` and `CursorPaginator` implement
it, so a paginator can be both the metadata and the value - Laravel's
`Inertia::scroll($paginator)`, its rows under `data`:

```rust
InertiaResponse::new("Feed/Index").scroll("posts", &page, &page)
```

The paginators report what Laravel's `ScrollMetadata::fromPaginator`
reports: the page parameter's name (`with_page_name` on
`LengthAwarePaginator` and `Paginator`, `with_cursor_name` on
`CursorPaginator`), and the previous, next and current page. A cursor
page's current page is `1` on the first page, else the cursor it was
fetched with - `Pagination::cursor` records it, `with_current_cursor` sets
it - else the request's cursor parameter.

A type outside this crate's `pagination` module - a third-party
paginator, a hand-rolled cursor - can describe itself to `.scroll` the
same way:

```rust
use suprnova::ProvidesScrollMetadata;

impl ProvidesScrollMetadata for MyCursorPage {
    fn page_name(&self) -> String { "cursor".to_string() }
    fn previous_page(&self) -> Option<serde_json::Value> { self.prev.clone().map(Into::into) }
    fn next_page(&self) -> Option<serde_json::Value> { self.next.clone().map(Into::into) }
    fn current_page(&self) -> Option<serde_json::Value> { Some(self.current.clone().into()) }
}

InertiaResponse::new("Feed/Index").scroll("posts", &page, page.rows)
```

A list loaded lazily describes its own pages from the loaded value, so it
needs no second query for them. `.scroll_lazy` reads them from a value
that implements `ProvidesScrollMetadata`, Laravel's
`Inertia::scroll(fn () => User::paginate())`; `.scroll_lazy_with` builds
them with a function of the loaded value, Laravel's callable metadata:

```rust
use suprnova::{FrameworkError, InertiaResponse, Prop, ScrollMetadata};

InertiaResponse::new("Feed/Index")
    .scroll_lazy("posts", || async {
        Ok::<_, FrameworkError>(Post::query().paginate(20).await?)
    })
    .scroll_lazy_with(
        "events",
        || async { Ok::<_, FrameworkError>(load_events().await?) },
        |events: &EventPage| ScrollMetadata::new("after").next(events.next_token.clone()),
    )
```

`Prop::scroll_lazy(resolver, metadata)` is the same prop for composing
with other flags, such as `.defer()`. The function runs only when the
value loads, so the `scrollProps` entry ships with the value and not on a
visit that withholds it. The value ships whole on a partial reload, as
Laravel ships a closure's result.

### Dot-notation nesting

A key containing `.` nests into the response instead of shipping as a
literal string key - Laravel's `Arr::set`-backed dot notation
(`Inertia::share('user.name', …)`, `resolveArrayableProperties`):

```rust
InertiaResponse::new("Dashboard")
    .with("user.name", "Todd")
    .with("user.locale", "es")
```

ships as:

```json
{ "user": { "name": "Todd", "locale": "es" } }
```

not two literal `"user.name"` / `"user.locale"` keys. Two calls sharing a
prefix accumulate into one object; a key with no dot is unaffected. This
applies to every prop-attaching method - `.with`, `.always`, `.lazy`,
shared-registry keys - and to nothing else: it never recurses into a
prop's *value*, so a validation `errors` object keeps whatever dotted
field names it carries internally. There is no escape hatch for a key
that must keep a literal dot (`.with("config.json", …)` still nests) -
this matches Laravel, where `Arr::set` has no escaping mechanism either.

## Partial reloads

The Inertia 3 client can request a subset of a page's props (or a
superset by including an Optional or Defer key). The protocol uses
three request headers:

| Header | Meaning |
|---|---|
| `X-Inertia-Partial-Component` | The component being partial-reloaded - must match the response's component for filtering to apply. |
| `X-Inertia-Partial-Data` | Whitelist: comma-separated prop paths to include. |
| `X-Inertia-Partial-Except` | Blacklist: comma-separated prop paths to exclude. Applied after `Partial-Data`, so it wins on a path both name. |

Both lists are read as Laravel reads them: split on `,`, empty segments
dropped, and no trimming, so `a, b` names `a` and ` b`. A header that names
nothing - empty, or only commas - counts as absent rather than as a list
that matches no prop. The other list headers the client sends,
`X-Inertia-Reset` and `X-Inertia-Except-Once-Props`, are read by the same
rule.

Filtering reads one thing: the prop's visibility, set by `.always()`,
`.optional()`, or `.defer()`. A prop with none of those has the default
visibility.

- Default-visibility props follow whitelist / blacklist semantics.
- `.always()` props are sent regardless.
- `.optional()` and `.defer()` props never ship on a standard visit. On a
  matching partial reload they resolve whenever their key passes the
  whitelist and blacklist, as Laravel's do: a reload that sends only
  `X-Inertia-Partial-Except` (`router.reload({ except: ['stats'] })`)
  resolves every optional and deferred prop it does not exclude.

The merge and scroll flags do not enter into it: they decide how the
client folds a value it receives, not whether it receives one, so a
`.defer().merge()` prop filters exactly like a plain `.defer()` one.
`.once()` doesn't enter into it either, though it isn't purely a folding
instruction - on a full visit where the client reports the value already
cached, the server skips the resolver and sends no value, as the note
below describes. What all three change is which metadata blocks ride
along - see [Composing flags on one prop](#composing-flags-on-one-prop).
On a partial reload the `merge` and `once` instructions are stricter than
the value: they ship only when an `only` entry names the prop or an
ancestor of it, so an entry deeper than the prop (`items.data`) sends the
prop whole with no instruction.

The handler doesn't have to do anything special - register every prop
through the builder, and the framework consults the headers when
serializing the page object.

A `once` prop's client-side cache is honoured only on a **full** Inertia
visit. On a partial reload that names the key
(`router.reload({ only: ['stats'] })`), the resolver runs and the value is
sent - the client asked precisely because it wants a fresh one, and
honouring its stale-cache claim there would return nothing at all for the
key it asked for.

### Nested only/except (dot notation)

`X-Inertia-Partial-Data` and `X-Inertia-Partial-Except` entries can name a
path inside a prop's value, not just the prop's own key. A client calling
`router.reload({ only: ['user.name'] })` sends
`X-Inertia-Partial-Data: user.name`, and the response narrows a literal
`user` prop down to just that field:

```json
{ "props": { "user": { "name": "Ada" } } }
```

`except` prunes the same way instead of narrowing - `router.reload({
except: ['user.email'] })` leaves every other field of `user` in place.

The rule is Laravel's: dotted entries narrow **literal values** only - a
value passed to `.with(...)`, a value shared with `App::inertia_share`, an
eager Data field. The walk keeps each nested path that is, descends from,
or leads to an `only` entry, and that neither is nor descends from an
`except` entry.

Rules:

- A value that came from a resolver or a prop object ships whole when its
  key, an ancestor, or a path inside it is selected. `.lazy(...)`,
  `.optional(...)`, `.defer(...)`, `.merge(...)`, `.once(...)`,
  `.scroll(...)` and `.always(...)` props are not walked, so
  `only: ['users.name']` against `.lazy("users", …)` sends every field of
  `users`. One exception follows Laravel too: a flag-free resolver under a
  dotted key (`.lazy("auth.user", …)`) narrows like a literal, because
  Laravel calls a dotted key's closure before its walk.
- A bare entry (`user`) still means the whole prop. If `only` names both
  `user` and `user.name`, the whole value ships - the bare entry wins.
- An entry can also name an *ancestor* of a dotted prop key. A prop
  registered under `auth.user` - by `.with("auth.user", …)` or
  `App::inertia_share("auth.user", …)` - participates in
  `only: ['auth']`, and ships whole, because the caller asked for the
  whole `auth` root. A bare `except: ['auth']` drops it for the same
  reason. The prefix has to end on a segment boundary, so an unrelated
  `authAgent.user` prop is untouched by either.
- `except` wins on a path both headers name, the same way it wins at the
  top level.
- A path that resolves to nothing - an unknown field - contributes nothing,
  without dropping the sibling fields requested alongside it. A value that
  keeps none of its children is `[]`, PHP's empty array: `only:
  ['user.missing']` sends `"user": []`.
- The walk goes into lists by index (`rows.0.id`). A list that keeps a
  prefix of its items stays a list; one that keeps other items becomes an
  object keyed by their indexes (`{"1": …}`), as PHP encodes an array whose
  keys no longer start at 0. A scalar a deeper path runs into
  (`config.level` under `only: ['config.level.nested']`) ships as it is.
- `Optional` and `Defer` props resolve on a partial reload whenever their
  key passes the lists. A dotted entry (`permissions.read`) selects the
  top-level key, and the resolved value ships whole.
- A dotted `except` doesn't delete the field on the client - it stops the
  field from refreshing on this response, and the client's merge restores
  it from whatever it already had cached. `deepMergeObjects` builds the
  merged object by cloning the cached value first and then only
  overwriting the keys the server actually sent; a key the server pruned
  is never touched, so it survives with its old value. On a
  client's first-ever load of that prop (nothing cached yet) the pruned
  field is genuinely absent, since there's no cache to fall back to - the
  "restores from cache" behavior only applies to a page the client has
  already seen.

## Shared data via `App::inertia_share*`

Some props are the same on every Inertia page - auth state, the CSRF
token, the current locale, app-wide flags. Register them once at
bootstrap and they merge into every response:

```rust
use suprnova::App;
use std::sync::Arc;

pub fn register() {
    // Sync, materialized once at boot.
    App::inertia_share("appName", "Suprnova");
    App::inertia_share("appVersion", env!("CARGO_PKG_VERSION"));

    // Async, resolved per response (skipped by partial reloads that
    // exclude the key).
    App::inertia_share_lazy("locale", || async {
        Ok::<_, suprnova::FrameworkError>(detect_locale().await)
    });

    // Cached on the client across navigations - `share_once` runs on
    // the first page that needs it, then the client skips re-resolution
    // via `X-Inertia-Except-Once-Props` until the cache key changes.
    App::inertia_share_once("plans", || async {
        Ok::<_, suprnova::FrameworkError>(load_plan_catalog().await?)
    })
    .until(3600);
}
```

`inertia_share_once` returns the registered prop, as Laravel's
`Inertia::shareOnce` returns its `OnceProp`, and it takes the options any
once prop takes - `.as_key(key)`, `.until(span or moment)`,
`.fresh(bool)` and `.once_with(options)`, described under
[Once props](#once-props). Each call changes the registered prop at once;
a later share under the same key replaces it, and the earlier handle then
changes nothing.

The `Inertia` facade makes the same registration.
`Inertia::share_once(key, resolver)` returns the same prop, and the same
options chain on it:

```rust
use suprnova::Inertia;

Inertia::share_once("plans", || async {
    Ok::<_, suprnova::FrameworkError>(load_plan_catalog().await?)
})
.as_key("plan-catalog")
.until(3600);
```

Shared keys nest on dots the same way `.with` does - two static shares
under `"user.name"` / `"user.age"` land in one `user` object on the wire.
Read a shared value back, or clear the static registry entirely, with
`App::inertia_shared` / `App::flush_inertia_shared` - Laravel's
`Inertia::getShared` / `Inertia::flushShared`:

```rust
use suprnova::App;

App::inertia_share("user.name", "Todd");
assert_eq!(App::inertia_shared("user.name"), Some(serde_json::json!("Todd")));

App::flush_inertia_shared();
assert_eq!(App::inertia_shared("user.name"), None);
```

A numeric segment reads into a shared list, as `Arr::get` does:
`App::inertia_shared("users.0.name")` reads the first user's name.

`inertia_shared` reads the static registry only - it returns `None` for a
key registered via `inertia_share_lazy` / `inertia_share_once` (there's no
request to resolve one against, mirroring Laravel's `getShared`, which
returns the raw closure rather than invoking it) and for a per-request
trait-provider share. `flush_inertia_shared` clears only the static
registry too; a provider registered via `register_inertia_shared` has no
per-request state to flush.

For per-request shared data (the authenticated user, request-scoped
flags), implement [`InertiaSharedData`](#per-request-shared-data) and
register the singleton - the framework calls `share(&req, component)` on
every Inertia response and merges the result. `component` is the page
being rendered, so a provider can vary its output by page - see below.

### Precedence on key collision

When the same key appears in more than one layer, later writes win:

1. Static registry (`App::inertia_share` / `App::inertia_share_lazy`),
   then the shared [providers](#prop-providers) in the order they were
   shared
2. Per-request trait provider (`InertiaSharedData::share`)
3. The page's [providers](#prop-providers), in the order they were given
4. Per-response builder methods (`.with`, `.lazy`, etc.)

This lets a handler override a globally-shared default for one page
without having to unregister anything.

### The `sharedProps` list

The page object lists the top-level key of every shared prop under
`sharedProps`, as Laravel's does: the static shares, the shared
providers' keys and the per-request provider's keys, each by its root
segment (`"auth"` for a share under `"auth.user"`), with `errors` first,
since every response shares the validation errors. The client reads the
list during an instant visit, to carry the shared values into the page it
renders before the server answers. A page that overrides a shared key
keeps it on the list; the client reads the value from `props`.

```json
{ "component": "Signup", "props": { "errors": { "email": "Taken" }, "auth": { "user": "Ada" } }, "sharedProps": ["errors", "auth"] }
```

`InertiaConfig::expose_shared_props(false)` leaves the list out of every
page object - Laravel's `inertia.expose_shared_prop_keys` setting. It is on
by default; the shared values still ship as props when it is off.

### Per-request shared data

The trait runs once per Inertia response with access to the request
**and** the page component name - Laravel's `RenderContext` (`component`,
`request`), passed as a plain parameter rather than a wrapper struct
since the request already covers the other half. Implementations need
`async_trait` (re-exported as `suprnova::async_trait`) and `IndexMap`
(re-exported as `suprnova::indexmap`):

```rust
use suprnova::{
    App, Auth, FrameworkError, InertiaRequestExt, InertiaSharedData, Prop,
    indexmap::IndexMap,
};
use std::sync::Arc;

pub struct AuthShare;

#[suprnova::async_trait]
impl InertiaSharedData for AuthShare {
    async fn share(
        &self,
        _req: &dyn InertiaRequestExt,
        component: &str,
    ) -> Result<IndexMap<String, Prop>, FrameworkError> {
        let mut out = IndexMap::new();
        if let Some(user) = Auth::user().await? {
            out.insert(
                "auth".into(),
                Prop::eager(serde_json::json!({
                    "id": user.get_auth_identifier(),
                })),
            );
        }
        // Vary by page: only the admin dashboard needs the nav counts.
        if component == "Admin/Dashboard" {
            out.insert("pendingReviews".into(), Prop::eager(serde_json::json!(12)));
        }
        Ok(out)
    }
}

// In bootstrap:
App::register_inertia_shared(Arc::new(AuthShare));
```

Ignore `component` (`_component`) if your provider doesn't need to vary by page.

### Prop providers

A value that stands in for several props implements
`ProvidesInertiaProperties` - Laravel's interface of the same name. A page
takes any number of them with `.provide(...)`, the shared props any number
with `App::inertia_registry().share_provider(...)`, and each one expands
once per render with a `RenderContext` of the page component and the
request:

```rust
use suprnova::{
    FrameworkError, InertiaResponse, Prop, ProvidesInertiaProperties, RenderContext,
    indexmap::IndexMap,
};

pub struct TeamProps {
    team_id: i64,
}

impl ProvidesInertiaProperties for TeamProps {
    fn to_inertia_properties(
        &self,
        context: &RenderContext<'_>,
    ) -> Result<IndexMap<String, Prop>, FrameworkError> {
        let team_id = self.team_id;
        let mut props = IndexMap::new();
        props.insert("teamId".into(), Prop::eager(team_id.into()));
        // Async work goes in a lazy prop, which runs only when it is sent.
        props.insert(
            "members".into(),
            Prop::lazy(move || async move { load_members(team_id).await }),
        );
        if context.component() == "Teams/Settings" {
            props.insert("canDelete".into(), Prop::eager(true.into()));
        }
        Ok(props)
    }
}

InertiaResponse::new("Teams/Show")
    .provide(TeamProps { team_id: 7 })
    .provide(BillingProps::for_team(7))
    .with("title", "Team")
```

Expansion is synchronous, as Laravel's is; a provider returns lazy props
for work that has to wait. Providers merge in the order they were given,
a later one winning over an earlier one, and the page's own props win
over its providers' whatever the call order. Shared providers expand
after the keyed shares, and their keys are shared keys. A `#[derive(Data)]`
object works the same way for its fields: `.with_data(dto)` adds one, any
number of times, with its lazy fields still behind the `?include=`
allowlist (`try_with_data` is the fallible sibling).

`App::flush_inertia_shared()` clears the shared providers with the keyed
shares, as Laravel's `flushShared` does.

One prop's value can convert itself when it is sent: implement
`ProvidesInertiaProperty` (Laravel's interface of the same name) and
attach the value with `.with_property(key, value)` or `Prop::property`.
The conversion gets a `PropertyContext` of the prop's key path, its
sibling props and the request:

```rust
use suprnova::{FrameworkError, PropertyContext, ProvidesInertiaProperty};

pub struct Money(i64);

impl ProvidesInertiaProperty for Money {
    fn to_inertia_property(
        &self,
        context: &PropertyContext<'_>,
    ) -> Result<serde_json::Value, FrameworkError> {
        let currency = context
            .props()
            .get("currency")
            .and_then(|prop| prop.as_value())
            .and_then(|value| value.as_str())
            .unwrap_or("USD");
        Ok(format!("{}.{:02} {currency}", self.0 / 100, self.0 % 100).into())
    }
}

InertiaResponse::new("Shop/Show")
    .with("currency", "EUR")
    .with_property("price", Money(1250))   // "12.50 EUR"
```

The conversion runs only when the prop is sent, so a prop a partial
reload leaves out is never converted. The siblings are the page's props
before resolution, shared ones included; a sibling given as a value can
be read with `Prop::as_value`, while a resolver has not run yet. The
converted value ships whole, as Laravel ships an object's conversion: a
dotted `only` entry does not narrow it.

## Flash and redirects

Flash data is one-shot state that should appear on the next render and
disappear after - toast messages, "just created" IDs, validation summaries.
Suprnova surfaces it under `page.flash`, outside `props`, so it never enters
the browser's history state. Laravel's `Inertia::flash` is the main writer:

```rust
use suprnova::{FlashKey, Inertia, InertiaResponse, Redirect, Response};

pub async fn store() -> Response {
    // A key and a value, or several at once.
    Inertia::flash("toast", "Saved")?;
    Inertia::flash_many([("created_id", 42), ("count", 3)])?;
    Redirect::to("/posts").into()
}

// An enum key, as a Laravel app flashes with an enum case.
enum Toast {
    Success,
}

impl FlashKey for Toast {
    fn flash_key(&self) -> String {
        match self {
            Toast::Success => "success".to_string(),
        }
    }
}
```

`Inertia::flash`, `App::flash` (the same call with a string key) and
`InertiaResponse::new("Posts/Show").flash("toast", "Saved")` all write the
session entry `inertia.flash_data`, Laravel's key. The next Inertia page
response emits it under `page.flash` and removes it, whatever the request that
set it answered: a handler that flashes and returns plain JSON still gets its
toast on the next page. A redirect keeps it for one more request, so it
reaches the page at the end of any number of redirects. Without a session in
scope the value rides on the current response only.

Read or take the pending data with `Inertia::get_flashed(&req)` and
`Inertia::pull_flashed(&req)` - Laravel's `getFlashed` and `pullFlashed`.
`get_flashed` returns exactly what `pull_flashed` would remove, and a page
rendered after a pull shows none of it.

`Redirect::to("/posts").with("toast", "Created")` is a plain session flash:
it lands under `_flash.new.*`, the next request's
[`SessionMiddleware`](csrf.md) ages it into `_flash.old.*`, and that page
surfaces it under `page.flash` too, below the Inertia flash data. It lasts one
request, so a second redirect drops it.

Same-request flash wins over inherited session flash on key collision, so a
destination handler can override an inbound value just by re-flashing the key.

Internal session keys (anything prefixed `_`) are filtered out of
`page.flash` - `_old_input` for form repopulation doesn't leak to the client.

The two history flags work the same way: `App::clear_history()` (or
`Inertia::clear_history()`), `Inertia::preserve_fragment()` and
`Redirect::preserve_fragment()` set the session entries
`inertia.clear_history` and `inertia.preserve_fragment`, which last until a
page response emits them as `clearHistory: true` and `preserveFragment: true`,
however many redirects come first.

### Redirect helpers

`Redirect` is the full Laravel surface:

```rust
Redirect::to("/dashboard")                       // 302 to a path
Redirect::route("posts.show").with("id", "42")   // named route, route params
Redirect::back("/")                              // session-recorded previous URL
Inertia::back(302, Some("/"))                    // Referer, previous URL, fallback
Redirect::refresh()                              // same URL, fresh GET
Redirect::guest(&req, "/login")                  // stashes intended URL
Redirect::intended("/dashboard")                 // pops the stashed URL
Redirect::signed_route("downloads.show", &[("id","42")])?  // signed URL
Redirect::to("/posts/42").preserve_fragment()    // keep #frag across visit
```

All `Redirect` variants accept `.with(k, v)`, `.with_input(map)`,
`.with_errors(map)`, `.with_errors_bag(name, map)`, `.cookie(c)`,
`.header(k, v)`, `.permanent()`, `.status(303)`, etc. The full chain
mirrors Laravel's `RedirectResponse`.

`Inertia::back(status, fallback)` is Laravel's `back()`: it tries the
request's `Referer` first, when that is a path on this host under the public
root (the check the validation redirect applies, so a foreign `Referer` is
never followed), then the session's previous URL, then `fallback`, then `/`.
It reads the `Referer` from the request `InertiaHeadersMiddleware` is
handling, which `Inertia::install` puts on every route; `Redirect::back`
reads the previous URL only.

The previous URL is recorded twice over: `SessionMiddleware` records a
successful `GET` that a route answered, the fallback route included, unless
it is an Inertia visit, a prefetch, a Precognition request, a JSON call or an
AJAX call (`X-Requested-With: XMLHttpRequest`). A static file and a request
no route answered are never recorded, as Laravel never sees them. The
Inertia middleware records an Inertia `GET` that matched a route,
unless it is a prefetch (`X-Moz`, `Purpose` or `Sec-Purpose` set to
`prefetch`), a Precognition request or a partial reload of the component it
rendered - deferred props, polling and infinite scroll reload the page the
visitor is on, which is no page they came from. Turn the Inertia half off
with `InertiaConfig::store_previous_url(false)`.

A redirect with a `#fragment` on an Inertia visit becomes `409` with
`X-Inertia-Redirect` holding the target, which the client visits itself so
the fragment survives; the fragment of a `Location` is lost inside the XHR
that follows it. A prefetch keeps its plain redirect, since it is never
shown. `InertiaResponse::redirect(url)` builds the same `409` by hand.

For Inertia `PUT`, `PATCH` and `DELETE` visits, the framework converts a
`302` redirect to `303 See Other` when [`Inertia303Middleware`](#bootstrap-inertiainstall)
is installed, so the browser issues a clean follow-up GET instead of
re-submitting the original PUT/PATCH/DELETE to the redirect target.

### Validation failures

When a handler fails validation on an Inertia visit, the framework
answers `303 See Other` back to the form page with the errors flashed,
instead of the `422` JSON a REST client gets. That is not cosmetic: the
Inertia client treats any response without an `X-Inertia` header as
non-Inertia and renders it in the full-screen error modal, so a `422`
never reaches `form.errors`. Nothing in the handler changes - the bridge
is one of the middlewares `Inertia::install` registers.

The destination is the request's `Referer` when it is same-origin, then
the session's recorded previous URL, then the failing request's own URL.
A cross-origin `Referer` is ignored rather than followed, and so is one
that only looks same-origin: a leading `//` or `/\` (a browser reads
either as protocol-relative once it folds a backslash into a slash) and
any ASCII control byte anywhere in the value (the URL parser strips tab
and newline from the whole string before it compares origins, so a
control byte can turn what looks like a safe path into a different
origin by the time a browser navigates it) both fall back the same way.
The same check applies to the final URL fallback too, so even an
unusual request path can't become an off-origin redirect.

A field's value is its **first** message, a plain string - the shape
Inertia's own `ErrorValue` type describes and what
`$page.props.errors.email` binds to. Set
`InertiaConfig::with_all_errors(true)` to get every message as an array
instead. `suprnova generate-types` reads that call under `src/` and types
the errors to match, in the augmentation it generates (see [TypeScript
Types](frontend-typescript-types.md#shared-props-and-the-inertia-config)):

```ts
// frontend/src/types/inertia-props.ts, written by `suprnova generate-types`
export type Errors = Record<string, string[]>;

declare module '@inertiajs/core' {
  export interface InertiaConfig {
    sharedPageProps: SharedProps;
    errorValueType: string[];
  }
}
```

A project that keeps its own `declare module '@inertiajs/core'` block gets
no generated augmentation and sets `errorValueType: string[]` there
itself.

Multiple forms on one page stay isolated: send
`X-Inertia-Error-Bag: <name>` with the visit and the errors are flashed
under that bag and read back under it, arriving as `errors.<name>.<field>`.
The `errors` prop takes Laravel's shape: with the header, a session `default`
bag (from `Redirect::with_errors`) arrives as `{<name>: {...}}`, the named
bags arrive as they are when there is no `default` bag, and no errors at all
arrive as `{}`; without the header the `default` bag arrives flat.

The `errors` prop is always-visible by default, so a partial reload
never filters or narrows it. `only: ['users']` still ships the bag, and
so does `except: ['errors']`; `only: ['errors.email']` ships the whole
bag rather than just that field. This is Laravel's shape - its
middleware shares the bag as `Inertia::always(...)`, and `resolveAlways`
re-injects the raw value after the `only`/`except` rebuild. It matters
because the client folds a partial response in with
`{...current.props, ...response.props}`: an empty `errors` object would
wipe the messages already on screen, where an unfiltered one leaves them
correct. The rule covers both sources - the session-flashed bag and a
handler's own `.with("errors", …)`. An explicit visibility flag still
wins, so `.prop("errors", Prop::eager(…).optional())` behaves optionally.

Two things this does not do. It does not re-flash old input - the request
body is already consumed by the time the bridge runs, and an Inertia
`useForm` keeps its own state across a failed submit, so there is nothing
to repopulate. And it never touches a Precognition response: a dry-run
`422` is exactly what the client asked for.

To send the visitor **out** of the Inertia app - a payment provider, an
OAuth authorize endpoint, a hosted billing portal - use `location`:

```rust
use suprnova::{Inertia, Redirect, Response};

pub async fn checkout() -> Response {
    Ok(Inertia::location("https://billing.example/checkout"))
}

pub async fn portal() -> Response {
    // A redirect works too: a hard navigation gets it as it is.
    Ok(Inertia::location(Redirect::away("https://billing.example/portal").status(303)))
}
```

An Inertia XHR gets `409` + `X-Inertia-Location` (the client runs
`window.location = url`); a hard navigation gets a plain `302` + `Location`,
or the redirect you passed, status, flash and cookies included - Laravel's
`Inertia::location`. `InertiaResponse::location` is the same call. It reads
which kind of request it is answering from the facts the server scopes for
every request it dispatches, so a route outside the Inertia middleware
answers the same way; `InertiaResponse::location_for(&req, url)` decides
from the request you pass, for code that runs outside a dispatched request.

## Published page versions and private reloads

[Static Publication](static-publication.md) keeps HTML and full page JSON in
separate keys under the asset version and publication revision. A complete
upload switches the manifest last. Previous versions remain during the
grace period so a client can finish loading the assets of its document.

The three kits use one shared HTTP client. It reads the document's
`suprnova-static-version` and `suprnova-static-pages` metadata and fetches
published JSON for a navigation between public pages. The page URL stays
the live route URL. A different response asset version produces the normal
Inertia document reload.

```typescript
import { staticHttpClient } from '@/lib/static'
// The kit passes this transport to createInertiaApp({ http: staticHttpClient() }).
```

Partial reloads, polling, deferred props, once props and mutations use the
live URL with `__suprnova_origin=1` and `Cache-Control: no-store`. That path
bypasses publication and returns `private, no-store`. Flash and validation
errors arrive from the origin. CSRF comes from `XSRF-TOKEN`, with a private
same-origin GET to obtain it before a mutation when needed.

## Version detection

Inertia versions the asset manifest so a long-lived client doesn't try
to mount a page from yesterday's bundle against today's server. When
the client's `X-Inertia-Version` header on a `GET` doesn't match the
server's current version, [`InertiaVersionMiddleware`](#bootstrap-inertiainstall)
responds with `409 Conflict` before the handler runs. `X-Inertia-Location`
holds the request's absolute URL (scheme, host, path and query, as
Laravel's `fullUrl()` gives it), and `X-Inertia-Version` holds the current
version. The Inertia client does a full page reload at that URL, picking up
the new bundle; for a poll or a background prop load it reads the version
header instead, so an asynchronous request does not force the reload. A
visit by any other method passes through: the `GET` its redirect leads to
gets the 409.

The bounce re-flashes the session first. The client answers a 409 with a
full-page GET, and that GET is a fresh request - without the re-flash, a
validation error or success message flashed by the previous request is aged
away before the destination page can read it, and the user loses their error
message purely because a deploy landed mid-submit. This needs
`SessionMiddleware` registered ahead of the version middleware.

By default you set nothing. The version resolves in the order Laravel's
`Middleware::version` uses:

1. When the config names an `asset_url` - the URL the built assets are
   published under when it changes with each deploy, such as a CDN path
   that carries a build id - the version is a hash of that URL. It
   defaults to the `ASSET_URL` environment variable, the one Laravel's
   `app.asset_url` reads; `.asset_url(...)` on the config wins over it.
2. Otherwise `InertiaConfig` hashes your Vite build manifest
   (`manifest_path`, default `public/assets/.vite/manifest.json`). The
   manifest is the one file that changes on every build and on no other
   occasion, so the version bumps itself.
3. When there is no manifest to read - local development, where Vite
   serves from memory - the version is the empty string, as Laravel's is,
   and a `debug` line is logged.

Both hashes are the first 16 bytes of a SHA-256, hex-encoded.

Override it when you want something else:

```rust
use suprnova::{InertiaConfig, VersionResolver};

// Default - hash the build manifest. Nothing to write.
let cfg = InertiaConfig::new();

// Assets published under a per-deploy URL: the version follows the URL.
let cfg = InertiaConfig::new().asset_url("https://cdn.example.com/build-42");

// A different manifest location; the version follows it.
let cfg = InertiaConfig::new().manifest_path("dist/.vite/manifest.json");

// Static - bake in a build-time identifier. Survives a later
// `.manifest_path(...)` call: an explicit version is deliberate.
let cfg = InertiaConfig::new().version(env!("CARGO_PKG_VERSION"));

// Dynamic - a container deployment id, anything. The closure runs on
// every version check; cache inside if it isn't cheap.
let cfg = InertiaConfig::new().version_with(|| deployment_id());
```

The manifest is read on every version check, which is what Laravel's
`hash_file` does too - a few KB out of the page cache, and a rebuild is
picked up immediately. If you have measured that and want it gone,
resolve once at boot:

```rust
use suprnova::{InertiaConfig, VersionResolver};

let version = VersionResolver::from_manifest("public/assets/.vite/manifest.json").resolve();
let cfg = InertiaConfig::new().version(version);
```

For async or fallible version resolution (e.g. read a manifest hash
from S3), do the read once at boot and pass the cached `String` to
`.version(...)`.

### Setting the version at run time

`Inertia::version` sets the version while the app runs, as Laravel's
`Inertia::version` does, and `Inertia::get_version` reads it:

```rust
use suprnova::Inertia;

Inertia::version(deployment_id());     // a string
Inertia::version(|| read_build_id());  // a function, called on every read
Inertia::version(None::<String>);      // the empty version, Laravel's null

let current = Inertia::get_version();
```

The value replaces the version of the installed config, so every page
built after the call advertises it, and the version middleware that
`Inertia::install` registers compares the client's `X-Inertia-Version`
against it. A later `Inertia::install` replaces it again, and a response
given its own config with `with_config(...)` keeps that config's version.

## Bootstrap: `Inertia::install`

Most apps install the protocol middlewares in one call, from
`register_http_stack` - the HTTP-only bootstrap hook, which the server
path runs and the queue, schedule, workflow, and console binaries skip
(see [Bootstrap](bootstrap.md)):

```rust
use suprnova::{Inertia, InertiaConfig};

pub fn register_http_stack() {
    let cfg = InertiaConfig::new()
        .version(env!("CARGO_PKG_VERSION"))
        .default_title("My App");

    Inertia::install(&cfg)
        .expect("Inertia install failed (production needs a built frontend manifest)");
    // …the rest of your global middleware, in the order you want it to run
}
```

Anything the Inertia layer depends on - `SessionMiddleware` - and
anything an error page needs to read - `LocaleMiddleware` - goes *above*
this call. See [the ordering rules below](#bootstrap-inertiainstall).

```rust
// cmd/main.rs
Application::new()
    .bootstrap(bootstrap::register)
    .http_bootstrap(|| async { bootstrap::register_http_stack() })
```

Keep it out of `bootstrap::register`. `Inertia::install` fails closed in
production when the built frontend manifest is missing, which is exactly
the state of a worker or console image that ships no `public/assets` -
so installing it from the process-wide hook takes those binaries down
with it.

`Inertia::install` returns `Result` and, in order:

1. Fails closed if `cfg` resolves to production mode (`development ==
   false` - the default whenever `APP_ENV=production`) but no Vite
   manifest can be loaded from `cfg.manifest_path`. This is the CFG-01
   guard: a production boot with an unbuilt frontend errors loudly
   instead of silently falling back to a legacy hardcoded asset path.
2. Registers `InertiaHeadersMiddleware` - sets `Vary: X-Inertia` on every
   response. On an Inertia visit it turns an empty `200` into a redirect
   back (to the same-origin `Referer`, else the previous URL, else `/`; `302`,
   or `303` for `PUT`, `PATCH` and `DELETE`), turns a redirect with a
   `#fragment` into `409` + `X-Inertia-Redirect`, and records an Inertia
   `GET` as the session's previous URL - see
   [Redirect helpers](#redirect-helpers).
3. Registers `InertiaVersionMiddleware` - emits the `409` + `X-Inertia-Location`
   when client and server disagree on the asset version.
4. Registers `Inertia303Middleware` - upgrades `302` to `303` on `PUT`,
   `PATCH` and `DELETE` Inertia redirects.
5. Registers `InertiaErrorPageMiddleware` - hands the framework's own
   error responses to your error callback, or turns them into the page
   `cfg` names with `.error_page(...)`. With neither, it changes nothing.
   See [Error pages](#error-pages). If you registered one yourself,
   further out, yours keeps its position and the component it names, and
   this step is skipped - see
   [Where the page is rendered](#where-the-page-is-rendered).
6. Registers `InertiaValidationRedirectMiddleware` - turns a `422` on an
   Inertia visit into a `303` back to the form page with the errors
   flashed. See [Validation failures](#validation-failures).

When [Inertia DevTools](frontend-inertia-devtools.md) is enabled - when
`APP_ENV` names the `local` environment, unless `InertiaConfig::devtools`
says otherwise -
`install` registers `DevToolsMiddleware` ahead of all five, outermost of
the Inertia layer, so the entry it records for each request holds the
response the five shaped. With `register_globally(false)` the stack for
route groups carries it instead, and `install` registers a global one that
only answers the extension's entry endpoints.

Order matters: the headers middleware is registered first, so it is the
outermost of the protocol middlewares and sees every response - including the `409` the version
middleware returns before the handler ever runs. The validation-redirect
middleware is registered last, so it is innermost - closest to the
handler - and sees a `422` before the other four middlewares get a
chance to touch it. The error-response middleware sits just outside it,
so an Inertia visit's validation failure reaches it as the `303` back to
the form, never as a `422`.

Two render-time settings Laravel apps reach for at boot:

```rust
use suprnova::{Inertia, InertiaConfig};

// Rename components before they render; `None` keeps the name.
Inertia::transform_component_using(|component| {
    component.strip_prefix("Old/").map(|rest| format!("New/{rest}"))
});

// Make a component with no page file an error instead of a blank page.
let cfg = InertiaConfig::new()
    .ensure_pages_exist(true)
    .pages_dir("frontend/src/pages")              // the default
    .page_extensions(["svelte", "tsx", "jsx", "vue"]); // the default
```

The transformer runs for every response, whatever built it. With
`ensure_pages_exist` on, a render looks for `<pages_dir>/<Component>.<ext>`
and answers an error naming the component and the directory when there is no
such file - Laravel's `inertia.pages.ensure_pages_exist`. `inertia_response!`
already checks its component at compile time; this catches a name given as a
string to `InertiaResponse::new` or `Router::inertia`.

`install` also **retains the config**. Every `InertiaResponse` built
afterwards starts from it, so `.frontend(...)`, `.version(...)`,
`.default_title(...)`, `.ssr(...)` and `.encrypt_history(...)` set here
reach every page without a handler passing anything. A handler that wants
different settings for one page still overrides with `.with_config(...)`;
an app that never calls `Inertia::install` gets `InertiaConfig::default()`;
and calling `install` again replaces the retained config.

`.with_config(...)` replaces the config wholesale, `version` included.
`InertiaVersionMiddleware` still resolves the version `Inertia::install`
was given, so a config here that doesn't carry the same `.version(...)`
makes the page object advertise a version the middleware will bounce - the
client takes one extra full page load after visiting that page. Set
`.version(...)` on the override to match.

Register `SessionMiddleware` **ahead of** `Inertia::install` if you use
flash data. The version middleware re-flashes the session before bouncing
the client, so a flashed error survives the follow-up full-page GET; it
can only do that inside a session scope.

Register [`LocaleMiddleware`](localization.md) **ahead of it too**, if you
use an [error page](#error-pages). A middleware's post-`next` code runs
after everything inside it has already returned, so the error-page
middleware renders once any scope opened inside it has been popped -
which for the locale middleware means the page would get the app's
default locale instead of the visitor's. The Inertia layer reads nothing
from localization, so putting locale outside it costs nothing. The
scaffolded `bootstrap.rs` already does this. The same reasoning applies
to any middleware of yours whose request scope the error page needs to
read.

Everything you register **after** this call is covered by the error page;
anything above it is not, because a middleware that answers without
calling `next` hands its response to nothing inside it. If your
`CsrfMiddleware`, rate limiter, or auth guard has to sit above the
install, register the error-page middleware yourself between them - see
[Where the page is rendered](#where-the-page-is-rendered).

### Middleware hooks

A Laravel app changes what its `HandleInertiaRequests` middleware decides by
overriding its methods. Here those decisions are the methods of
`InertiaMiddlewareHooks`, each defaulting to the framework's behaviour, so an
implementation overrides only what it changes and installs with
`InertiaConfig::hooks`:

```rust
use suprnova::{
    DefaultInertiaHooks, HttpResponse, Inertia, InertiaConfig, InertiaMiddlewareHooks,
    InertiaRequestExt, InertiaVisit, Prop, indexmap::IndexMap,
};

struct Hooks;

impl InertiaMiddlewareHooks for Hooks {
    // Shared with every page this middleware serves, per request.
    fn share(&self, request: &dyn InertiaRequestExt) -> IndexMap<String, Prop> {
        let mut props = IndexMap::new();
        props.insert("path".into(), Prop::eager(serde_json::json!(request.path())));
        props
    }

    // A handler that answers nothing means "done": 204, not a redirect back.
    fn on_empty_response(&self, _visit: &InertiaVisit, _response: HttpResponse) -> HttpResponse {
        HttpResponse::new().status(204)
    }

    // Start from the framework's 409 and add to it.
    fn on_version_change(&self, visit: &InertiaVisit, response: HttpResponse) -> HttpResponse {
        DefaultInertiaHooks
            .on_version_change(visit, response)
            .header("X-Deploy", "2026-10")
    }
}

Inertia::install(&InertiaConfig::new().hooks(Hooks))?;
```

| Hook | Laravel | Default |
|---|---|---|
| `version(request)` | `version()` | `None`: the configured version; an answer is what the client is compared against and what the page carries |
| `share(request)` | `share()` | nothing beyond the framework's `errors` |
| `share_once(request)` | `shareOnce()` | nothing; each value becomes a once prop |
| `root_view(request, config)` | `rootView()` | the config as it is; return a changed one to change this request's first-visit document |
| `url_resolver()` | `urlResolver()` | `None`: `InertiaConfig::url_resolver` |
| `on_empty_response(visit, response)` | `onEmptyResponse()` | the redirect back; a `302` it returns becomes `303` for `PUT`, `PATCH` and `DELETE` |
| `on_version_change(visit, response)` | `onVersionChange()` | the `409` with `X-Inertia-Location` |
| `on_redirect_with_fragment(visit, response)` | `onRedirectWithFragment()` | the `409` with `X-Inertia-Redirect` |

The request hooks run once per request, before the handler; the `on_*`
hooks run on an Inertia visit only and receive the response the framework
would send. `InertiaVisit` carries the request's method, path, URL and
headers, and `back_target(fallback)`, where a redirect back would go.

### The stack on a route group

`Inertia::install` puts the stack on every route, so an API route answers
with `Vary: X-Inertia` and has its `302` turned into `303` for an Inertia
`PUT`. To keep it to the groups that serve pages - Laravel's
`HandleInertiaRequests` on the `web` group only - install with
`register_globally(false)` and put the stack on those groups:

```rust
use suprnova::{Inertia, InertiaConfig, Router};

let cfg = InertiaConfig::new()
    .version(env!("CARGO_PKG_VERSION"))
    .register_globally(false);
Inertia::install(&cfg)?;           // retains the config, registers "inertia"

let router: Router = Router::new()
    .group("/", |r| r.get("/dashboard", dashboard))
    .middleware(Inertia::middleware(&cfg))  // or .middleware_named("inertia")
    .into();
let router: Router = router
    .group("/api", |r| r.get("/users", users)) // no Inertia stack here
    .into();
```

`Inertia::middleware(&cfg)` is the whole stack as one middleware, in the
order `install` registers it globally, with the error page when `cfg` names
one and with `cfg`'s hooks. With `register_globally(false)`, `install`
registers it as the named middleware `inertia` instead of globally, so a group
can name it. `SessionMiddleware` stays global, outside the group's stack, as
the Inertia layer reads the session it opens.

Skip the call only if you genuinely don't want one of these middlewares
(rare; each of them closes a real failure mode - cache poisoning across
the two representations of a URL, silent stale-bundle,
form-replay-on-redirect,
and a validation `422` dead-ending in the client's error modal instead of
reaching `form.errors`).

## Error pages

An Inertia visit that gets back a non-2xx from the framework does not
show an error page - it shows a crash screen:

```
All Inertia requests must receive a valid Inertia response, however a
plain JSON response was received.
```

The client checks one thing before it will render anything: an
`X-Inertia: true` header on the response. A `403` from an
[authorization](authorization.md) check or an RBAC permission
middleware, a `404` for an unrouted path, a `429` from the
[rate limiter](rate-limiting.md), a `500` from a
[failing handler](errors.md) - all of them carry the framework's JSON
error body and no such header, so the client hands them to its modal. A user with the wrong role clicks a nav
link and the app appears to break.

Name a page component and the framework renders those responses through
it instead, keeping the status code:

```rust
use suprnova::{Inertia, InertiaConfig};

pub fn register_http_stack() {
    Inertia::install(
        &InertiaConfig::new()
            .version(env!("CARGO_PKG_VERSION"))
            .error_page("Error"),
    )
    .expect("Inertia install failed (production needs a built frontend manifest)");
}
```

`"Error"` is resolved exactly like any other page name, so
`frontend/src/pages/Error.svelte` (or `.tsx`, or `.vue`) is all it takes.
**The three starters ship one and set `.error_page("Error")` already** -
a new project is covered without doing anything.

`.error_page(...)` is the default error callback: a fixed rule, described
below, that decides each error response for you. To decide each error
yourself, see [Deciding each error yourself](#deciding-each-error-yourself).

### Where the page is rendered

`Inertia::install` registers `InertiaErrorPageMiddleware` inside the rest
of the Inertia layer, just outside the validation redirect, so it sees the
response the handler and the route middleware actually produced.
Everything you register *after* that call is covered too, inside your
session and locale - which is why the scaffold puts `CsrfMiddleware` below
it.

Anything registered **above** the call is covered only at the server. A
middleware that answers without calling `next` hands its response to
nothing registered inside it, so its rejection never reaches the Inertia
layer. The server runs the same decision after the whole stack for every
error response nothing inside the stack decided, so that rejection still
becomes the page - but every request scope a middleware opened has closed
by then. The page keeps the shared registry and the shared providers, and
loses the rest: no session data, the app's default locale rather than the
visitor's, and none of the `share` and `share_once`
[middleware hooks](#middleware-hooks). The case that shows it is a lapsed
session posting a form: `CsrfMiddleware` answers `419` with
`{"message":"CSRF token mismatch."}`, and if it sits above
`Inertia::install` the user gets that bare page on the one flow they are
most likely to hit. An outer rate limiter's `429` and an auth guard's
`401` behave the same way.

Register the middleware yourself when that is your shape, outside the
middleware whose rejections it should cover, so the page is built inside
the visitor's session and locale. This worked in 1.3.6 as a
side effect - the type was public and global registration is idempotent
per type, so an earlier registration kept its place - but nothing said so.
It is a documented contract from 1.3.7: `install` checks for your
registration, logs at `debug`, and skips its own.

```rust
use suprnova::{
    global_middleware, CsrfMiddleware, Inertia, InertiaConfig,
    InertiaErrorPageMiddleware, LocaleMiddleware, SessionConfig, SessionMiddleware,
};

pub fn register_http_stack() -> Result<(), suprnova::FrameworkError> {
    global_middleware!(SessionMiddleware::new(SessionConfig::from_env()));
    global_middleware!(LocaleMiddleware::from_env()?);

    // Outside CSRF, so it sees the 419 that never reaches the layer below.
    global_middleware!(InertiaErrorPageMiddleware::new("Error"));
    global_middleware!(CsrfMiddleware::new());

    Inertia::install(&InertiaConfig::new().error_page("Error"))
}
```

`Inertia::install` sees the registration, skips its own, and says so at
`debug`. The position you chose is the one that stands, and so is the
component you named - that instance is the one in the chain. You name the
page **once**, at your own registration, which makes `.error_page(...)` on
the config optional here: keep it or drop it, nothing else reads it. It is
still what makes `install` register a middleware for an app that does not
place one itself.

Three ordering rules come with placing it yourself.

**After `SessionMiddleware` and [`LocaleMiddleware`](localization.md).**
The page carries your shared props - `auth.user`, flash, the locale share -
and it is built on the way *out*, after every middleware registered inside
it has returned and popped whatever request scope it opened. Registered
above those two, every error page loses the visitor's session and renders
in the app's default locale rather than theirs. The same holds for any
request-scoped middleware of your own whose state the error page's shared
props read.

**Before the middleware whose rejections it should cover**, and no
further out than that. Every response that passes through it is one more
body it has to classify, and a middleware outside it can still answer
before it runs.

**Before `Inertia::install`.** That keeps it outside
`InertiaValidationRedirectMiddleware`, which `install` registers
innermost. Registered after the call, it sees an Inertia visit's
validation failure as a `422` before the redirect back is built, and a
callback of yours that replaced it would break the form.

If you register nothing yourself, `Inertia::install` does all of this for
you - and the scaffolded `bootstrap.rs` already has `SessionMiddleware`
and `LocaleMiddleware` above the call and `CsrfMiddleware` below it.

### What the page receives

| Prop | Type | Always present | What it is |
|---|---|---|---|
| `status` | `number` | yes | The original HTTP status - `403`, `404`, `500`. |
| `message` | `string` | yes | The error body's `message`, or the status's reason phrase when it carried none. Already sanitized: a `5xx` reads `"Internal Server Error"`, never the underlying error - and that holds under `APP_DEBUG=true` too. The dev-only `debug_message` field the JSON path adds there is deliberately not read, so the raw error stays in the log and the JSON response and never renders into a page. |
| `request_id` | `string` | no | Present only when the error body carried one. The same id the structured log records, so the page can show a reference the operator can search. |

```svelte
<script lang="ts">
  interface ErrorProps {
    status: number
    message: string
    request_id?: string
  }

  let { status, message, request_id }: ErrorProps = $props()
</script>

<h1>{status}</h1>
<p>{message}</p>
{#if request_id}<p>Reference: {request_id}</p>{/if}
```

Declare the props in the component rather than importing them from
`types/inertia-props.ts`: [`suprnova generate-types`](frontend-typescript-types.md) rewrites
that file from your own `#[derive(InertiaProps)]` structs, and these
props come from the framework.

### What survives the swap

The status code is kept, and so is every header the original response
set, **except** two groups.

**What described the body being replaced.** Every `Content-*` field
(`Content-Length` on a page four times the size of the JSON it replaced
is a framing bug) and `Transfer-Encoding`.
`Content-Security-Policy` is carved out of that rule by name - it shares
the prefix by historical accident and is response policy, not
representation metadata.

**What governed how that body could be stored.** `Cache-Control`,
`Expires`, `Age`, `ETag`, `Last-Modified`. The page carries your shared
props - `auth.user`, flash, the locale share - where the error body it
replaced was the same for everyone, so it must never inherit permission
to be stored by a shared cache and handed to a different visitor, nor
validators that belong to an entity it is not. The page sets
`Cache-Control: no-cache, private` for itself instead, the same default
Laravel gives a session-bearing response. When the response it replaces
said `no-store`, the page sets `no-store`, so a page that must not be stored,
such as a consent page, stays unstored when it fails.

Everything else carries: `Retry-After` on a `429` still tells the client
when to come back, `WWW-Authenticate` on a `401` still carries the
challenge, and `Vary`, `Set-Cookie`, and your request-id header all
arrive intact. The rule is stated as what gets dropped rather than what
gets kept, so a header the framework has never heard of survives instead
of silently disappearing.

Both audiences are covered. An Inertia XHR visit gets the JSON page
object with `X-Inertia: true`; a hard navigation - someone pasting
`/admin/articles` into the address bar - gets the full HTML shell, the
same one a first load of any page gets. So the error page works whether
the user arrived through the SPA or not.

With debug mode on, a `5xx` the framework built from an error reaches
both audiences as the development error page instead: the error, the
stack frames, and the request, as one HTML document. See
[Error Model](error-model.md#the-development-error-page). A `4xx`, and
every response with debug off, still renders your component.

### What it never touches

These are the default callback's choices. A callback of your own decides
for itself - see [Deciding each error yourself](#deciding-each-error-yourself).
The default callback only stands in where nobody else has an answer. It
leaves alone:

- **Validation `422`s.** `InertiaValidationRedirectMiddleware` owns
  those - see [Validation failures](#validation-failures). A `422` that
  survives that middleware (no `errors` object, or a Precognition
  dry-run) keeps its body too.
- **Anything carrying `X-Inertia-Location` or `X-Inertia-Redirect`.**
  The `409` version bounce, the `redirect_to` form of the RBAC
  middlewares, `Inertia::location`, and a redirect with a `#fragment`.
  The client acts on the header, not the body. No callback is handed
  these.
- **Redirects.** Only `400`-`599` is in scope.
- **API clients.** A request whose `Accept` prefers `application/json`
  over `text/html` keeps the JSON contract it has always had. `curl`'s
  `*/*` counts as no preference, so it keeps JSON too. Only an Inertia
  visit or a browser navigation gets a page.
- **Responses that already are Inertia pages.** A handler that rendered
  its own page and gave it a `410` keeps its own component.
- **Bodies that are not the framework's error shape.** Your own HTML
  error page, plain text that is not the router's own `404 Not Found`, or
  a JSON envelope keyed differently - none of those is overruled.
- **Everything, when neither `error_page` nor a callback is set.** The
  middleware `Inertia::install` registers hands every request on, so an
  app that has not opted in gets exactly the responses it got before.

### Which bodies get rewritten

The gate is the **shape of the body**, not who wrote it. At a `400`-`599`
status, exactly three shapes are replaced:

- an empty body;
- a JSON object whose `message` is a string - the framework's own error
  envelope, and anything else shaped like it;
- the router's fixed `404 Not Found` plain-text body.

Everything else passes through. That means a `401` a middleware of yours
answers with `HttpResponse::json(json!({ "message": "Unauthenticated." }))`
**does** become the error page - which is the point, since that is exactly
the response the client would otherwise modal - and it means only
`message` and `request_id` survive into the props. An envelope carrying
`errors`, `code`, or anything else loses those fields when it becomes a
page.

If a middleware of yours must keep its own JSON body on an error status,
give it a shape the gate does not match - key the human-readable text as
something other than `message` - or set `X-Inertia: true` on the response
yourself, which marks it as already being an Inertia response and takes
it out of scope. Both are one line at the point that builds the response.

A handler that **panics** is covered too. The middleware runs the rest
of the chain inside it under the panic boundary's rule, so the panic
becomes the same sanitized `500` the boundary sends, with the panic's
error report, and the page renders for it. A panic in a middleware
registered *outside* it reaches the boundary around the whole chain, and
that `500` reaches your callback, or the default callback, at the server,
after the whole stack - without the request scopes the stack opened, as
[Where the page is rendered](#where-the-page-is-rendered) describes. A
callback that panics is a bug the same boundary reports: the client gets
the sanitized `500` with the panic's error report, whether the callback
panicked inside the stack or at the server, and no page renders for it.

If the page itself fails to render - the component cannot be resolved,
SSR is down, a shared prop errors - the framework logs a `warn` with the
request id and returns the original error response. A broken error page
never masks the error it was rendering.

### Deciding each error yourself

`Inertia::handle_exceptions_using` installs a callback that decides every
error response the framework renders, the way Laravel's
`Inertia::handleExceptionsUsing` does. The callback receives an
`InertiaErrorResponse` and returns it with a decision, or `None` to send
the response the framework built:

```rust
use serde_json::json;
use suprnova::Inertia;

pub fn register_error_pages() {
    Inertia::handle_exceptions_using(|error| match error.status() {
        403 | 404 | 500 | 503 => {
            let status = error.status();
            Some(
                error
                    .render("Error", json!({ "status": status }))
                    .with_shared_data(),
            )
        }
        _ => None,
    });
}
```

`InertiaErrorResponse` shows what went wrong and who asked:

- `status()` - the status of the response the framework would send.
- `error()` - the [error report](error-model.md): the error and its
  source chain, or a panic's message and location. A response the
  framework built without an error behind it, such as the router's `404`
  for a path no route matches, reports its message or the status's reason
  phrase.
- `request()` and `method()` - the request as it arrived: its method,
  path, query, and headers.
- `response()` - the response the framework would send.

It offers three decisions:

- `render(component, props)` renders an Inertia page in place of the
  response and keeps its status. `props` is anything that serializes to a
  JSON object, such as `json!({ ... })`. The page gets the same treatment
  as the default callback's page: the root template the request's chooser
  picks, `Cache-Control: no-cache, private` (or `no-store` when the replaced
  response said it), and the original headers
  minus the ones described in [What survives the swap](#what-survives-the-swap).
- `with_shared_data()` adds the shared props to that page: everything
  `Inertia::share` and `App::inertia_share` registered, the shared
  providers, the `InertiaSharedData` provider, and the `share` and
  `share_once` [middleware hooks](#middleware-hooks).
  Without it, the page carries only the props you gave it.
- `respond_with(response)` sends any other response instead.

The callback sees every error response the framework renders, for every
request type - an API client's included, so check
`error.request().header("Accept")` or `error.request().is_inertia()`
before you render a page for one. That covers a handler's or a
middleware's `Err(...)`, a handler that panics, the router's `404`, and
a middleware's own `{"message": ...}` answer. A response a handler built
itself with an error status, such as its own HTML `404` page, is that
handler's answer, and the callback doesn't see it. Neither are Inertia
protocol responses: pages, and anything carrying `X-Inertia-Location` or
`X-Inertia-Redirect`.

Responses from outside the Inertia stack reach the callback too, at the
server. A middleware registered before `Inertia::install` that answers
without calling `next` - `CsrfMiddleware`'s `419`, `TimeoutMiddleware`'s
`503`, an outer rate limiter's `429` - never hands its response to the
error-response middleware, and neither does a panic that only the
server's boundary catches. The server runs the same decision after the
whole stack for every error response that nothing inside the stack
decided, so your callback, or the default callback, sees those as well,
once each. The callback gets the same request, error, and response there.
`with_shared_data()` still adds the shared registry and the shared
providers, but every request scope a middleware opened has closed by
then: the page has no session data, renders in the default locale, and
gets none of the `share` and `share_once` hooks. To keep those on such a
page, register `InertiaErrorPageMiddleware` yourself, outside the
middleware whose answers it should cover - see
[Where the page is rendered](#where-the-page-is-rendered).

A validation failure reaches the callback as the response the client
would get. An API client's `422`, `{"message": ..., "errors": {...}}`,
and a Precognition dry run's `422` are handed over like any other error:
return `None` to keep the errors the client reads off it, since a
replacement takes them away. An Inertia visit's never arrives as a `422`.
The error-response middleware sits outside
`InertiaValidationRedirectMiddleware`, so by the time the response
reaches it, the redirect has made it the `303` back to the form with the
errors flashed - see [Validation failures](#validation-failures). The
default callback keeps every `422`.

With debug mode on, `response()` for a `5xx` that carries an error
report, sent to a browser or an Inertia visit, is the
[development error page](error-model.md#the-development-error-page).
Return `None` to keep it, as the default callback does. A page you render
instead is what the client gets, so check `Config::is_debug()` first if
you want the development page while you work.

`.error_page("Error")` is the default callback. An app that sets both
gets its own callback, and `None` from it keeps the framework's response
rather than falling back to the error page. A later call to
`handle_exceptions_using` replaces the callback. The callback lives on
the active container, so one installed under `TestContainer::fake()`
decides only that test's requests. `Inertia::install` registers the
middleware whatever the config says, so you can install the callback
before or after it.

### Why Suprnova diverges

Laravel puts this in the exception handler: you edit
`bootstrap/app.php`, match on the status yourself, and call
`Inertia::render('Error', ['status' => $response->getStatusCode()])`
with `$response->setStatusCode(...)` to put the code back. That is
flexible, and it is also a piece of framework plumbing every project
rewrites by hand, usually after seeing the modal in production first.

Here the common case is one config line, because the decision is the
same for almost every app: an Inertia visit or a browser navigation gets
a page, an API client gets JSON, and everything another contract owns is
left alone. That line installs the default callback. When the fixed rule
doesn't fit, `Inertia::handle_exceptions_using` gives you Laravel's
per-error decision - see
[Deciding each error yourself](#deciding-each-error-yourself).

## Server-driven `<head>` elements

`Head` manages the document `<head>`: the title, meta tags, Open Graph and
X cards, icons, resource hints and JSON-LD schemas. It is Laravel Head's
API. Every Inertia response shares the resolved head as a `head` prop of
rendered elements, and the first visit writes the same elements into its
`<head>`, so crawlers and link previews read them without JavaScript.

Register the defaults at boot and set page metadata in the handler:

```rust
use suprnova::{Head, InertiaResponse, Request, Response, HttpResponse};

pub fn register_head() {
    Head::defaults(|head| head
        .title("Laravel")
        .title_suffix(" - Laravel")
        .description("Build something great."));
}

pub async fn about(request: Request) -> Response {
    // Renders `<title data-inertia="title">About - Laravel</title>`.
    Head::title("About");
    InertiaResponse::new("About")
        .resolve(&request)
        .await
        .map_err(HttpResponse::from)
}
```

Then enable `serverHead` wherever you call `createInertiaApp()`, and in
your SSR entry point if you have one:

```js
createInertiaApp({
  serverHead: true,
})
```

### Resolution precedence

A page's head resolves from five layers, lowest first:

1. The defaults, from `Head::defaults`.
2. Route group metadata, from `with_head` on a group.
3. Route metadata, from `with_head` on a route.
4. Run-time metadata, from the `Head::title`, `Head::description` and
   other calls the request makes.
5. Error metadata, from `Head::errors`, for the response's error status.

A higher layer replaces a lower one field by field: a run-time title
replaces the route's title and keeps the route's description. A title
takes the prefix and suffix of the layers below it, so `Head::title("About")`
over the defaults above renders `About - Laravel`, while the defaults'
own `Laravel` renders as it is. `exact_title("...")` ignores an inherited
prefix and suffix. A repeatable value (an Open Graph image, an icon, a
meta tag) keeps every entry, and adding the same key again (the image's
URL, the icon's address, the meta tag's name) updates the earlier entry.
Open Graph media a layer sets replaces the media of that kind from the
layers below, so a page's image wins over a default image.

### Route metadata

Use `with_head` on a route, or on a group for all of its routes. It works
on `get!`, `any!` and the other route macros, on `group!(...)`, and on
`Router::group(...)`:

```rust
use suprnova::{get, group, routes};

routes! {
    get!("/contact", controllers::contact)
        .with_head(|head| head.title("Contact Us").description("Get in touch.")),
    group!("/admin", {
        get!("/dashboard", controllers::admin::dashboard)
            .with_head(|head| head.title("Dashboard")),
    }).with_head(|head| head.robots("noindex, nofollow")),
}
```

### Run-time metadata

Each `Head` call sets the current request's metadata and returns a
handle for more calls. Later calls win for single values:

```rust
use suprnova::Head;

Head::title(&post.title)
    .description(&post.summary)
    .when(post.is_draft, |head| head.hidden_from_robots());
```

The request's metadata lives in the request's container scope, so
concurrent requests never see each other's. Outside a request a `Head`
call logs a warning and does nothing; `Head::try_update(|head| ...)`
returns the error instead.

`Head::canonical()` links the request's URL over `https`;
`canonical_url("/about")` links another address, made absolute on the
application's origin, and `canonical_keep_scheme()` keeps the URL's own
scheme. `robots("noindex, nofollow")`, `robots_rules([...])`,
`searchable_by_robots()` and `hidden_from_robots()` set the robots
directives.

### Error pages

Register metadata per error status. It wins over every other layer when
a response is rendered for that status:

```rust
use suprnova::Head;

Head::errors(|errors| errors
    .defaults(|head| head.robots("noindex, follow"))
    .status(404, |head| head
        .title("Page Not Found")
        .description("The page you are looking for could not be found.")));
```

The Inertia [error page](#error-pages) applies it for the status it
renders. When you render an error page another way, call
`Head::status(404)` first.

### Open Graph and X cards

```rust
use suprnova::Head;
use suprnova::head::{ImageType, OgMedia, OgType, OpenGraph, TwitterCard, TwitterCardType};

Head::defaults(|head| head
    .og(OpenGraph::new().site_name("Laravel").kind(OgType::Website))
    .twitter(TwitterCard::new().card(TwitterCardType::SummaryLargeImage)));

Head::og_image(
    OgMedia::new(&post.cover_url)
        .alt(&post.cover_alt)
        .width(1200)
        .height(630)
        .kind(ImageType::Jpeg),
);
```

The document title and description fill a missing `og:title` and
`og:description`. `og_video` and `og_audio` add video and audio entries.
Once a layer calls `twitter(...)`, the X card renders, with its title,
description and image filled from the document title, the description and
the first Open Graph image; `twitter_image(...)` names another image.

### Theme colors, application metadata and icons

```rust
use suprnova::Head;
use suprnova::head::{Icon, ImageType, Media, Pwa};

Head::defaults(|head| head
    .theme_color("#ffffff", Media::Light)
    .theme_color("#111827", Media::Dark)
    .color_scheme("light dark")
    .favicon(Icon::new("/favicon.svg").kind(ImageType::Svg))
    .apple_touch_icon(Icon::new("/apple-touch-icon.png").sizes("180x180"))
    .mask_icon("/safari-pinned-tab.svg", "#111827")
    .pwa(Pwa::new("Laravel").manifest("/site.webmanifest")));
```

`theme_color(color, None)` sets one color for every media; `Media::Light`,
`Media::Dark`, `Media::Portrait`, `Media::Landscape` and
`Media::query("(min-width: 600px)")` scope it. `application_name`,
`referrer`, `viewport`, `apple_web_app_title`, `web_app_capable`,
`apple_web_app_status_bar_style`, `icon`, `apple_touch_startup_image` and
`manifest` set the rest. `pwa(...)` sets the application name, the Apple
web app title, web app capable, and the manifest, theme color, touch icon
and status bar style you give it; the manifest file and the service worker
stay yours to write.

### Performance and discovery

```rust
use suprnova::Head;
use suprnova::head::{Feed, Hint};

Head::preload(Hint::new("/fonts/inter.woff2").as_kind("font").crossorigin())
    .prefetch("/images/next.webp")
    .preconnect("https://cdn.example.com")
    .dns_prefetch("https://analytics.example.com")
    .alternates([("en", "https://example.com/en/about"), ("x-default", "https://example.com/about")])
    .feed(Feed::rss("/feed").title("Laravel RSS"));
```

`Head::paginate(&paginator)` writes the `prev` and `next` links of a
length-aware or cursor page; `prev_page(url)` and `next_page(url)` set
them by hand.

### Custom tags and schemas

`meta(name, content)` writes `property` for an `og:` or `article:` name and
`name` otherwise; `meta_for(name, content, media)` adds a media query, and
`meta_tag(MetaTag::new(..).property(true))` chooses the attribute.
`link(rel, href)` and `link_tag(LinkTag::new(rel, href).attribute(..))`
write a `<link>`. An attribute name has to be a valid HTML attribute name:
an ASCII letter, then letters, digits, `-`, `_`, `:` or `.`. `attribute`
drops an invalid name and logs a warning; `try_attribute` refuses it with
the reason. `schema(...)` adds a JSON-LD object, written as its own
`<script type="application/ld+json">` element:

```rust
use suprnova::Head;
use suprnova::head::Schema;

Head::schema(Schema::of("Product").set("name", &product.name))
    .schema(Schema::breadcrumbs().item("Home", "/").item("Shop", "/shop"))
    .schema(Schema::faq().question("Is it free?", "Yes, it is open source."));
```

Every value is HTML-escaped. A schema's JSON escapes `<`, `>` and `&`, so
a value that holds `</script>` cannot end the element.

### Rendering

An Inertia response carries the head as a `head` prop: one rendered
element per string, each with a stable `data-inertia` key (`title`,
`description`, `og:image:0`, `meta:format-detection`). The client adopts
the first visit's elements by those keys and keeps them in step on every
visit. A partial reload carries no `head` prop, so the client keeps the
last full page's head. A response no layer sets anything for carries no
`head` prop, so the page object of an application that does not use
`Head` stays as it is, and an application that builds its own `head` prop
keeps it: a prop the page or the shared data sets wins over `Head`'s. If
your pages use a `head` prop of their own, rename `Head`'s:

```rust
suprnova::Head::inertia("_head"); // then `serverHead: '_head'` on the client
```

The first visit writes the elements into its `<head>` once. Under SSR,
an element whose `data-inertia` key the SSR head already carries is left
out, and so is the title when the SSR head has one, so each element
appears once while every other SSR head element stays. While `Head` sets
a title, the document writes no default title, and while it sets a
viewport, the framework's own document writes no viewport of its own. A
title set with `InertiaResponse::title` keeps working while no `Head`
title is set.

Tags that the first response writes and the client never changes, such as
the viewport, the color scheme, icons and the manifest, can be Inertia
globals. They are written into the first visit only, without a
`data-inertia` key, and never into the `head` prop:

```rust
use suprnova::Head;

Head::inertia_globals(|head| head
    .viewport("width=device-width, initial-scale=1")
    .color_scheme("light dark")
    .manifest("/site.webmanifest"));
```

For a server-rendered view, `Head::render_html()` returns the resolved
tags and `Head::to_array()` returns them as data, one object per tag with
its `key`, `element`, `attributes` and `content`. `Head::canonical()` there
needs the request's URL, which a route that declares `with_head` records;
elsewhere give the URL with `canonical_url`.

### Moving from Inertia's `<Head>` and title callbacks

The starter kits pass a `title` callback to `createInertiaApp` and set
titles with Inertia's `<Head>` component. When you adopt `Head`, remove the
`title` callback from your app and SSR entry points so `Head` decides the
final title, and move the tags your pages set with `<Head>` into `Head`, so
the two never define the same element.

### Why Suprnova diverges

- **No Blade directive.** Laravel Head renders through `@head` in a Blade
  layout. Suprnova's own Inertia document and root templates write the
  head for you, and `Head::render_html()` serves other views.
- **Keys name the element's role.** Laravel Head's keys are internal.
  Suprnova's keys are documented above, so an SSR head that writes the same
  key replaces the server's element.
- **Run-time calls are request-scoped.** One Rust process serves many
  requests at once, so the run-time layer lives in the request's container
  scope, and the defaults in the application container, where
  `TestContainer::fake()` isolates them.
- **Builders, not named arguments.** Rust has no named arguments, so
  `og(type: ..., title: ...)` becomes `og(OpenGraph::new().kind(..).title(..))`
  and `ogImage(url, alt: ...)` becomes `og_image(OgMedia::new(url).alt(..))`.

## The root template

A first visit is a whole HTML document: the page data, the mount element, the
Vite tags, and whatever else your application wants in the first load - a
favicon, fonts, meta tags a link preview reads, a `<noscript>`, attributes on
`<html>` and `<body>`. In Laravel that document is `app.blade.php`. In
Suprnova it is an Askama template under `templates/`, which you declare with
`#[inertia_root]` and install on the config:

```rust
use suprnova::{Frontend, Inertia, InertiaConfig, InertiaRootTemplate};

/// The document every Inertia first visit renders into: `templates/app.html`.
#[suprnova::inertia_root(path = "app.html")]
pub struct AppDocument;

pub fn register_http_stack() {
    Inertia::install(
        &InertiaConfig::new()
            .frontend(Frontend::Svelte)
            .default_title("My App")
            .root_template(InertiaRootTemplate::of::<AppDocument>()),
    )
    .expect("Inertia install failed (production needs a built frontend manifest)");
}
```

```html
<!DOCTYPE html>
<html lang="{{ lang }}" class="h-full">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" href="/favicon.ico" />
    {{ title }}
    {{ head }}
    {% if !ssr %}
    <meta name="description" content="My App" />
    {% endif %}
  </head>
  <body class="antialiased">
    <noscript>My App needs JavaScript.</noscript>
    {{ body }}
  </body>
</html>
```

`suprnova new` writes this file as `templates/app.html` and declares it as
`AppDocument` in `src/bootstrap.rs`. Without a root template, the first visit
is the document the framework writes itself, byte for byte what it has always
been.

The framework hands the template these parts:

- `title`: the `<title>` element, from `.title(...)` on the response or
  `.default_title(...)` on the config. It is empty when the
  [SSR](#ssr) head carries a `<title>` of its own, because a document shows
  only its first title. A template that writes its own `<title>` leaves this
  part out.
- `head`: the `csrf-token` meta tag, the `csp-nonce` meta element under a nonce
  policy, the SSR head when the SSR server rendered the page, and the Vite tags.
- `body`: the page data element and the mount element, or the SSR body, which
  carries both.
- `lang`: the document's language, the locale in effect for the request.
- `csrf_token`: the session's CSRF token, for a template that places it
  itself. It is empty outside a session.
- `nonce`: the request's CSP nonce as `Option<&str>`, for the template's own
  scripts. It is present under a nonce policy and `None` without one. See
  [Security Headers](security-headers.md) for script examples and policy setup.
- `ssr`: whether the SSR server rendered this response. A template places
  fallback head content under `{% if !ssr %}`, for the pages whose own `Head`
  did not run on the server.
- `view`: the response's view data, described below.

`title`, `head`, and `body` are markup: placed bare, they are written as they
are, not escaped as text. `lang`, `csrf_token`, `nonce`, and view data values
are plain values, and Askama escapes them like any other. Askama checks the
template at compile time, so a template that names anything other than these
parts fails the build. A template that fails while it renders, such as one
whose custom filter returns an error, makes the response an error that names
the template; no part of the document is sent.

The parts write themselves into the template's output as it renders. The page
JSON is serialized straight into that output, so a first visit through a root
template allocates what the framework's own document does, and a root
template adds no size limit of its own.

### Choose the template per request

To choose a different document for some requests, give the config a function
of the request instead of one template. It reads the path, the query, and the
headers through `InertiaRequestExt`, like Laravel's `rootView(Request)`:

```rust
use suprnova::{InertiaConfig, InertiaRootTemplate};

#[suprnova::inertia_root(path = "admin.html")]
pub struct AdminDocument;

let cfg = InertiaConfig::new().root_template_with(|req| {
    if req.path().starts_with("/admin") {
        InertiaRootTemplate::of::<AdminDocument>()
    } else {
        InertiaRootTemplate::of::<AppDocument>()
    }
});
```

`InertiaRootTemplate::framework()` chooses the framework's own document. The
[error page](#error-pages) goes through the same function, with the request
as it arrived, so a `404` or a `403` under `/admin` keeps the admin document.

### View data

`.with_view_data(key, value)` hands the root template a value for one response
and keeps it out of the page props: an Inertia visit's JSON and the first
visit's page data never include it. It is Laravel's `withViewData`, for what
the first-load HTML must carry without running JavaScript, such as the meta
tags a link preview reads:

```rust
#[handler]
async fn show(RouteParam(post): RouteParam<Post>, req: Request) -> Response {
    InertiaResponse::new("Posts/Show")
        .with_view_data("description", post.title.clone())
        .with("post", post)
        .resolve(&req)
        .await
        .map_err(HttpResponse::from)
}
```

```html
{% if let Some(description) = view.get("description") %}
<meta property="og:description" content="{{ description }}" />
{% endif %}
```

A value is anything serializable. Placed with `{{ value }}`, a string
displays as itself, and any other value, such as a number or an array,
displays as its JSON; the template escapes either like any other value.
`.try_with_view_data(key, value)` returns an error naming the key when the
value fails to serialize, where `.with_view_data` panics as `.with` does.

An error page carries no view data: the handler that would have set it failed
or never ran. The framework's own document places none.

Blade's view data becomes template variables. Here the template reads it
through `view.get`, so the template's names stay the fixed set of parts that
Askama checks at compile time.

### Data shared with every view

A value the application shares with [`View::share`](live.md#shared-view-data) reaches the root
template too, as Laravel's shared data reaches `app.blade.php`. Use it for what
every first visit's document needs, such as analytics settings, instead of
setting view data in every handler:

```rust
// In bootstrap: every document can read `plausible_domain`.
View::share("plausible_domain", "example.com".to_string());
```

```html
{% if let Ok(domain) = "plausible_domain"|value::<String> %}
{% if let Some(nonce) = nonce %}
<script defer data-domain="{{ domain }}" nonce="{{ nonce }}" src="https://plausible.io/js/script.js"></script>
{% endif %}
{% endif %}
```

The template reads a shared value with Askama's `value` filter, naming the
type that was shared. Keep the read inside `{% if let Ok(...) %}` unless every
deployment shares the value: a value no one shared, or one shared as another
type, fails the render, and with it every first visit. A value shared with
`View::share_for_request` reaches the template for that request alone and
wins over the application's value under the same key. An error page reads the
shared values too, since they belong to the application, not to the handler
that failed.

### The mount id

The page data element's `data-page` attribute and the mount element's `id`
are `app` unless `.mount_id(...)` on the config names another. Set it to the
`id` your frontend passes to `createInertiaApp`, and under SSR to
`createServer`, since the worker writes the SSR body's elements itself:

```rust
let cfg = InertiaConfig::new().mount_id("root");
```

## SSR

Suprnova talks to an out-of-process SSR worker - typically the
`@inertiajs/{svelte,react,vue}/server` `createServer()` bundle run
under Node, Bun or Deno - over HTTP. SSR is on by default, as in Laravel,
and gated by bundle detection: a first visit goes to the worker only when
an SSR bundle exists, so an application without one renders on the client
and never contacts the worker. Configure it on the config you hand to
[`Inertia::install`](#bootstrap-inertiainstall) - that config is what
every response starts from, so there is nothing to plumb through your
handlers:

```rust
Inertia::install(
    &InertiaConfig::new()
        .ssr("http://127.0.0.1:13714")  // worker URL, the default
        .ssr_timeout(std::time::Duration::from_millis(500))
        .ssr_exclude("/admin/**")
        .ssr_max_response_bytes(8 * 1024 * 1024),
)?;
```

SSR is a property of the config: on for every response built from the
installed config, and off for a response that overrides with a
`.with_config(...)` that calls `.ssr_disabled()`. When it runs, the
framework posts the page object to `<url>/render` and inlines
`{ head, body }` in the HTML shell. A worker head that carries its own
`<title>` - which is every page using Inertia's `Head` component -
**replaces** the shell's title rather than joining it, and that means both
`.default_title(...)` on the config and a per-response `.title(...)`: a
document with two titles shows the first one, so the shell's would win over
the page's real one in the tab, in search results, and in every link
preview. With SSR on, set the title in `Head` rather than on the response. A
head with no title leaves the shell's title exactly where it was. A worker
answer with nothing to inline - empty JSON, `null`, `false`, anything but an
object, an object without a `body`, or a body that is not JSON at all -
renders on the client, and is not a failure.

### Bundle detection

While `.ssr_ensure_bundle_exists(true)` is set, which is the default, a first
visit is dispatched only when a bundle exists at the path
`.ssr_bundle_path(...)` names or, failing that, at one of the conventional
paths under the working directory, the list Laravel's `BundleDetector`
checks (`CONVENTIONAL_BUNDLE_PATHS`):

- `frontend/bootstrap/ssr/ssr.js`, where a scaffolded project's
  `vite build --ssr` writes it
- `frontend/bootstrap/ssr/app.js`
- `frontend/bootstrap/ssr/ssr.mjs`
- `frontend/bootstrap/ssr/app.mjs`
- `public/js/ssr.js`
- `public/js/app.js`

With no bundle the visit renders on the client at once, without a request to
the worker, an error or a log line, so it never pays `ssr_timeout` on a
worker that was never started. `detect_ssr_bundle(&config.ssr)` runs the
same search. Turn the check off when the worker's bundle lives where this
process cannot see it, such as a separate container, or in a test that uses a
stand-in worker:

```rust
Inertia::install(
    &InertiaConfig::new()
        .ssr("http://ssr.internal:13714")
        .ssr_ensure_bundle_exists(false),
)?;
```

To keep every first visit on the client, call `.ssr_disabled()`.

### Hot mode in development

While the Vite dev server runs, a first visit in development goes to it at
`/__inertia_ssr` instead of the worker, and the bundle check is skipped:
the dev server renders the page from source, so you need neither a bundle
nor a worker process while you work.

The hot file says the dev server runs and serves SSR. When
`frontend/package.json` declares `@inertiajs/vite`, the Inertia Vite plugin
that serves `/__inertia_ssr`, `suprnova serve` writes the dev server's URL
to `public/hot` when it starts Vite, and removes the file when Vite stops or
`serve` exits. Without the plugin it writes no file. A visit goes hot while
that file exists, or whenever you set `.ssr_hot_url(...)`.
The address is the `.ssr_hot_url(...)` URL, else the file's content, else
the `.vite_dev_server(...)` URL when the file is empty.
`.ssr_hot_file(...)` names another file. Without the file the visit takes
the worker path with its bundle check, whatever listens at the dev server's
port. Production never goes hot. The same file decides the
[Vite tags](#vite-tags) in development.

A dev server that answers `/__inertia_ssr` with an error status is a
failure like the worker's: the visit dispatches `SsrRenderFailed`, calls the
`on_ssr_error` hook and renders on the client, or fails under
`ssr_throw_on_error`. A `404` from a dev server without the plugin, reached
through `.ssr_hot_url(...)` or a hot file written by hand, is reported the
same way.

### Worker failures and `SsrRenderFailed`

On a worker error, a timeout or an unreachable worker the response falls
back to the client (an empty `<div id="app">` the client mounts on) and the
`on_ssr_error(...)` hook fires. Every such failure also dispatches the
`SsrRenderFailed` event first. An Inertia 3 worker answers a failed render
with an error status and a JSON body (`error`, `type`, `hint`, `browserApi`,
`stack`, `sourceLocation`), and the event carries those fields with the
page's `component` and `url`. `error_type` is an `SsrErrorType`:
`BrowserApi`, `ComponentResolution`, `Render`, `Connection` for a worker that
could not be reached, or `Unknown`.

```rust
use std::sync::Arc;
use suprnova::{EventFacade, FrameworkError, Listener, SsrRenderFailed, async_trait};

struct ReportSsrFailure;

#[async_trait]
impl Listener<SsrRenderFailed> for ReportSsrFailure {
    async fn handle(&self, failed: &SsrRenderFailed) -> Result<(), FrameworkError> {
        tracing::warn!(
            component = %failed.component,
            url = %failed.url,
            kind = %failed.error_type,
            location = ?failed.source_location,
            hint = ?failed.hint,
            "SSR failed: {}",
            failed.error,
        );
        Ok(())
    }
}

// In `bootstrap::register`:
EventFacade::listen::<SsrRenderFailed, _>(Arc::new(ReportSsrFailure)).await;
```

Set `ssr_throw_on_error(true)` in CI to make those failures hard 500s
instead. The error names the component and, when the worker gave one, the
source location, as Laravel's `SsrException` does:
`SSR render failed for component [Dashboard]: window is not defined at
resources/js/Pages/Dashboard.vue:12:5`.

### Workers over HTTPS

A worker URL may be `https`. The client connects over TLS through rustls and
verifies the worker's certificate against the platform's trust store, so a
worker on another host or behind a TLS proxy needs no other setting.

### Run-time controls

`.ssr_exclude(pattern)` follows Laravel's `ExcludesPaths` rules, so a
pattern copied from a Laravel app excludes the same requests: slashes at
either end are ignored, `*` matches any characters including `/`, and each
pattern is tried against the path and the full URL. `admin/*` keeps
`/admin/users` and `/admin/users/edit` on the client, not `/adminx`.

The `Inertia` facade changes SSR at run time, as Laravel's does:

```rust
use suprnova::{Inertia, InertiaRequestExt};

// A switch for every request; `false` turns SSR on even where the
// configuration has it off (the worker URL still comes from the config).
Inertia::disable_ssr(true);

// Or decide per request. The answer replaces the configuration's switch.
Inertia::disable_ssr_if(|request: &dyn InertiaRequestExt| {
    request.path().starts_with("/admin")
});

// More exclusions, with the same rules as `ssr_exclude`.
Inertia::without_ssr(["admin/*", "https://app.test/reports*"]);

// Adjust the request sent to the worker: headers, a token, the timeout.
Inertia::configure_ssr_request_using(|request| {
    request
        .bearer_token(std::env::var("SSR_TOKEN").unwrap_or_default())
        .header("X-Tenant", "acme")
});
```

`App::disable_ssr_for_request()` still turns SSR off for the one request it
runs in, whatever the switch says.

### Your own gateway

The SSR call is a driver: the `SsrGateway` trait, with `HttpGateway` as the
default. Bind your own in the container and every first visit dispatches
through it:

```rust
use std::sync::Arc;
use serde_json::Value;
use suprnova::{
    App, FrameworkError, InertiaRequestExt, SsrConfig, SsrGateway, SsrResponse, async_trait,
};

struct EdgeGateway;

#[async_trait]
impl SsrGateway for EdgeGateway {
    async fn dispatch(
        &self,
        config: &SsrConfig,
        request: &dyn InertiaRequestExt,
        page: &Value,
    ) -> Result<Option<SsrResponse>, FrameworkError> {
        // Render `page` somewhere else; `Ok(None)` renders on the client.
        let _ = (config, request, page);
        Ok(None)
    }
}

App::bind::<dyn SsrGateway>(Arc::new(EdgeGateway));
```

`is_healthy`, `disable`, `except` and `configure_request_using` have
defaults a gateway overrides when it supports them. The facade calls in
[Run-time controls](#run-time-controls) act on the bound gateway; one that
lacks the capability logs a warning and ignores the call.

`Inertia::ssr_is_healthy().await` returns the gateway's health check. The HTTP
gateway sends `GET {url}/health`, through the request configurator and within
`ssr_timeout`, and answers `Some(true)` for a 2xx status and `Some(false)`
for any other status or no answer. `None` means the gateway has no health
check.

### Build and run the worker

`suprnova new` scaffolds `frontend/src/ssr.{ts,tsx}` and a `build:ssr`
npm script for every starter. Build it, then boot the worker:

```bash
cd frontend && npm run build:ssr
suprnova ssr:start
```

`suprnova ssr:check` asks the SSR gateway's health check whether the
worker is answering: the HTTP gateway sends `GET /health`, which every
`createServer()` bundle answers without any extra code. `suprnova ssr:stop`
stops the worker. Each of the three runs the application binary's command
of the same name, as `cargo run --bin <app> -- ssr:start` does, so it
reads the configuration you installed; see
[Console](console.md#ssr-commands).

### Why Suprnova diverges

Laravel's Vite plugin writes `public/hot` while the dev server runs. Here
`suprnova serve`, which starts Vite, writes and removes the file, and only
when `frontend/package.json` declares `@inertiajs/vite`, the plugin that
makes the dev server serve SSR. Run Vite on its own (`npm run dev`) and the
backend does not go hot unless you set `.ssr_hot_url(...)`.

Laravel sets no SSR timeout of its own and inherits its HTTP client's
30 seconds. Suprnova keeps 5 seconds (`ssr_timeout`): a hung worker would
otherwise hold every first visit for 30 seconds before the client-rendered
fallback.

## Vite tags

The Inertia document writes the `<script>` and `<link>` tags of your Vite
build. `Vite` writes the same tags for any other page, such as an Askama
view or an error page, as Laravel's `@vite` directive does:

```rust
use suprnova::{FrameworkError, InertiaConfig, Vite};

fn assets() -> Result<String, FrameworkError> {
    // The configured entry points, the tags the Inertia document writes.
    let app = Vite::to_html()?;
    // Entry points you name.
    let admin = Vite::tags(["src/admin.ts", "src/admin.css"])?;
    Ok(format!("{app}{admin}"))
}

fn config() -> InertiaConfig {
    // `src/app.css` loads on every page beside the entry point.
    InertiaConfig::new().entry_points(["src/app.css"])
}
```

`Vite` reads the configuration `Inertia::install` retained;
`InertiaConfig::vite_tags(entry_points)` renders against a configuration
you hold. With the build manifest, the tags name each entry's hashed
script, its stylesheets and a `modulepreload` for each imported chunk,
each file once, every stylesheet before the first script, and every URL
under `assets_base_url` with the public root in front. A missing manifest
is an error that names its path, and an entry the manifest lacks an error
that names the entry. The Inertia document keeps its own answer to a
missing manifest: the legacy `/assets/main.js` and `/assets/main.css`.

Which files the tags name depends on the mode and the hot file:

| Mode | Hot file | Manifest | The tags point at |
|---|---|---|---|
| Development | exists | any | the dev server at the file's URL |
| Development | missing | exists | the manifest's files |
| Development | missing | missing | the configured `vite_dev_server` |
| Production | ignored | exists | the manifest's files |

`InertiaConfig::hot_file()` and `Vite::hot_file()` answer the hot file's
path, `public/hot` unless `ssr_hot_file(...)` names another.
`Vite::is_running_hot()` answers whether the file exists, and
`Vite::dev_server_url()` its trimmed content (the configured dev server URL
when the file is empty), `None` without it. Production never reads the
hot file: both answer as if it did not exist.

`suprnova serve` writes the hot file only for a frontend that declares
`@inertiajs/vite`. A frontend without it keeps the dev server tags until a
build writes a manifest. If your development pages load stale built files
instead of the dev server, a manifest from an earlier `vite build` is
there: declare `@inertiajs/vite` in `frontend/package.json`, as every
starter kit does, or delete the stale build.

### Why Suprnova diverges

Laravel goes hot whenever the hot file exists, in production too, so a hot
file left in a deploy points visitors at a dev server. Suprnova never reads
it in production, and in development without a hot file or a manifest it
keeps the configured dev server, because `suprnova serve` writes no hot
file for a frontend without the Inertia Vite plugin.

## Configuration

Inertia behaviour is configured programmatically via `InertiaConfig`, and
the config you hand to [`Inertia::install`](#bootstrap-inertiainstall) is
the one every response starts from. `SUPRNOVA_FRONTEND` (`svelte` /
`react` / `vue`) only supplies the default entry-point filename and
page-component extensions when the config doesn't say - an explicit
`.frontend(Frontend::React)` on the installed config wins, and is what
`suprnova new --frontend react` scaffolds. `ASSET_URL` only supplies the
default `asset_url` the asset version hashes, and `.asset_url(...)` wins
over it (see [Version detection](#version-detection)). Everything else is
builder-shaped:

```rust
use suprnova::{InertiaConfig, Frontend};

let cfg = InertiaConfig::new()
    .frontend(Frontend::Svelte)               // overrides SUPRNOVA_FRONTEND
    .vite_dev_server("http://localhost:5765")
    .entry_point("src/main.ts")
    .version(env!("CARGO_PKG_VERSION"))
    .default_title("My App")
    .manifest_path("public/assets/.vite/manifest.json")
    .assets_base_url("/assets")
    .max_concurrent_resolvers(16)             // cap lazy-prop fan-out
    .with_all_errors(false)                   // one message per field, or all
    .url_resolver(|req| req.path_and_query()) // how `page.url` is derived
    .production();                            // false → loads from Vite dev server
```

A root-relative `assets_base_url` such as `/assets` gets the public root in
front of it in the Vite tags, so behind a proxy that serves the application
under `/billing` they load `/billing/assets/...`; an absolute or `//host`
base, such as a CDN's, is left as it is. The page `url` carries the root the
same way. See [Serving under a path prefix](deployment.md#serving-under-a-path-prefix).

Frontend-specific defaults:

| Frontend | Default entry point | Page extensions |
|---|---|---|
| Svelte (default) | `src/main.ts` | `.svelte` |
| React | `src/main.tsx` | `.tsx`, `.jsx` |
| Vue | `src/main.ts` | `.vue` |

Two attributes of the HTML shell are worth calling out.

`<title>` comes from `.title(...)` on the response, or from
`.default_title(...)` when the response set none. A title
[`Head`](#server-driven-head-elements) resolves wins over both. Under
[SSR](#ssr) the page's own head wins over **all of them**: a worker head
carrying a `<title>` is the document's only one, and the shell leaves its
title out entirely.

`<html lang="...">` is the one attribute the framework's own document does
not let you set, because the right value is already known - it is the
locale in effect for the request, what `LocaleMiddleware` detected or the
configured `APP_LOCALE` when nothing did. A [root template](#the-root-template)
places the same value as its `lang` part. See [Localization](localization.md); a screen reader takes its voice
from that attribute and a search engine reads it as the page's language,
so an app serving more than one language no longer has to rewrite the
finished document to correct it.

### The `url` field

`page.url` is the path **and** query string of the request
(`/users?page=2&sort=name`). The client writes it into `history.state`, so
it is what back/forward navigation and `router.reload()` replay - drop the
query and every paginated or filtered page silently resets to page one.

The query is normalised the way Laravel's `fullUrl()` normalises it
through Symfony, so the client compares the same page URLs it would get
from Laravel: the pairs are parsed as PHP parses a query string, sorted by
key, and re-encoded per RFC 3986. `/s?b=2&a=1%20x` becomes
`/s?a=1%20x&b=2`, a `+` becomes `%20`, reserved characters stay
percent-encoded (`a=%2Fx` is not turned into `a=/x`), a key without a
value gains an `=` (`?flag` becomes `?flag=`), a repeated key keeps its
last value, and bracketed keys are written with their indexes
(`tags[]=a&tags[]=b` becomes `tags%5B0%5D=a&tags%5B1%5D=b`). A query
already in that form is left as it is.
`InertiaVersionMiddleware` derives its `X-Inertia-Location` from the
request's path and query too, made absolute with the request's scheme and
host, so by default a 409 asset-version bounce lands the browser on
exactly the URL the page object named.

Override the derivation with `url_resolver` when the URL the client should
record differs from the one that arrived - a locale prefix the SPA doesn't
route on, or a path a reverse proxy rewrote:

```rust
use suprnova::InertiaConfig;

let cfg = InertiaConfig::new()
    .url_resolver(|req| req.path_and_query().replacen("/en", "", 1));
```

The resolver reads the request through `InertiaRequestExt`, and applies to
every response built from the config you pass to
[`Inertia::install`](#bootstrap-inertiainstall) - the usual place for a
resolver that should apply app-wide. Override it for a single response
with `InertiaResponse::with_config(cfg)`. A resolver changes `page.url`
only. The 409 bounce keeps naming the URL that actually arrived - that is
the URL the browser has to fetch - so with a resolver in place the two
deliberately differ.

The Vite manifest at `manifest_path` is loaded lazily on first request
and cached for the process lifetime - every response built from the
installed config shares that one cache, so the file is read and parsed
once. When it's missing, production asset tags fall back to a hardcoded
legacy path and a `tracing::warn!` fires so the gap surfaces in logs.

### Big integers

JavaScript represents integers exactly only up to 9007199254740991
(2^53 - 1), so a 64-bit database id beyond it reaches the browser rounded.
Turn on `preserve_big_integers` to send every integer outside plus or minus
that bound, in props and flash and at any depth, as a marker the Inertia
client restores as a `BigInt`:

```rust
use suprnova::{InertiaConfig, InertiaResponse};

// Every response built from this config.
let cfg = InertiaConfig::new().preserve_big_integers(true);

// One response, whatever the config says.
let page = InertiaResponse::new("Orders/Show")
    .with("id", 9_007_199_254_740_993_u64)
    .preserve_big_integers(true);
```

That `id` arrives as `{"$bigint": "9007199254740993"}`, and the page object
carries `preserveBigIntegers: true` so the client knows to restore it.
Integers inside the safe range, floats and object keys are left alone.
With the setting off, the default, nothing is wrapped and the flag is
absent. This is Laravel's `inertia.preserve_big_integers` setting and
`Response::preserveBigIntegers`.

### Why Suprnova diverges

Laravel's Inertia adapter has a single global "shared data"
registry plus a per-request `Inertia::share($k, $v)` call. PHP's
request-per-process model makes this safe: a fresh process per request
means no leakage between concurrent visitors.

Rust's process model is the opposite - one process serves many
concurrent requests across many threads. So the registry lives on
the [container](container.md) (task-local → thread-local → global),
not in process-global statics. `App::inertia_share*` writes to the
active container's `InertiaRegistry`, which gives tests using
`TestContainer::fake()` clean isolation without having to unregister
anything. Same surface as Laravel; different machinery underneath
because the runtime is different.

Other Rust-shaped choices worth flagging:

- **Lazy-prop resolvers run concurrently**, capped by
  `max_concurrent_resolvers` (default 16). A page with twelve lazy
  props issues twelve parallel queries inside one Tokio task - that's
  what we built the framework on top of Tokio for. Tune the cap if a
  page has many lazy props each hitting an external service.
- **The compile-time component check** isn't a Laravel feature at all,
  because PHP can't see your frontend files at compile time. Suprnova
  does, so a typo in `inertia_response!("Dashbaord", …)` fails the
  build with a "did you mean Dashboard?" suggestion instead of
  surfacing as a runtime "component not found" later.
- **`Inertia::clearHistory()` has a response-local form too.**
  `App::clear_history()` and `Inertia::clear_history()` are Laravel's call:
  the flag lives in the session until a page emits it. `.clear_history()` on
  the builder marks a single response with no session dependency, for the
  case where the response you are returning is the page that should clear.
- **`.lazy()` isn't Laravel's `Inertia::lazy()`.** Laravel's method is
  deprecated and behaves like `optional()` - `LazyProp` is a straight
  alias for `OptionalProp`, skipped entirely on the initial visit
  (`ResponseFactory.php:174-181`). Suprnova's `.lazy()` is the
  plain-closure convention Laravel itself uses for a callable prop with
  no wrapper at all - included whenever partial-reload filtering lets the
  key through, standard visits included. Reach for `.optional()` for the
  initial-visit-skipped behavior the name "lazy" suggests if you're
  coming from Laravel.

## Cacheable pages

A cacheable page separates public data from request data. Add
`#[inertia(cacheable)]` to an `InertiaProps` struct. Mark every field
`#[inertia(public)]` or `#[inertia(per_request)]`. An unmarked field fails
compilation and names the field. Without `cacheable`, the derive keeps its
ordinary serialization behavior. Cacheable props use the typed response
conversion, through the builder below or `inertia_response!`.

Register every shared prop at boot. Public shared props use the public list;
all other shared props use the per-request list. List `errors` and `flash`
there too unless the application explicitly lists them public. A public
declaration never hides a session dependency; that dependency declines the
shell. The framework's `root` prop is public and already belongs to the
key. A missing shared declaration stops boot with the route and prop name.
Register named shares before `Inertia::cache_page`, then install RenderCache.
A second boot check catches named shares added after page registration.
Opaque shared providers and middleware hooks cannot prove their keys at boot and are refused.
Page providers are refused when the response resolves. Use named props for
cacheable pages. Ordinary pages keep provider support.

With the RenderCache migration applied and the `Cache/Article` frontend page
present, add this handler and registration to the application's bootstrap:

```rust,no_run
use suprnova::{App, Auth, FrameworkError, Inertia, InertiaConfig, InertiaProps,
    InertiaResponse, Prop, Request, Response, Router};
use suprnova::render_cache::{FreshnessPolicy, RenderCache, RenderCachePolicy,
    RepresentationClass, VarianceDimension};
use suprnova::render_cache::config::RenderCacheConfig;
use suprnova::serde_json::json;

#[derive(InertiaProps)]
#[inertia(cacheable)]
struct ArticleProps {
    #[inertia(public)]
    article: Prop,
    #[inertia(per_request)]
    viewer: Prop,
}

async fn article(request: Request) -> Response {
    InertiaResponse::new("Cache/Article")
        .cacheable(ArticleProps {
            article: Prop::lazy(|| async { json!({"title": "Public article"}) }),
            viewer: Prop::lazy(|| async { json!({"id": Auth::id()}) }),
        })?
        .resolve(&request).await.map_err(Into::into)
}

async fn cache_routes() -> Result<Router, FrameworkError> {
    Inertia::install(&InertiaConfig::new())?;
    Inertia::share("appName", "Articles")?;
    App::inertia_share_lazy("auth", || async {
        Ok::<_, FrameworkError>(json!({"id": Auth::id()}))
    });
    Inertia::cache_page::<ArticleProps>("/article", "Cache/Article",
        &["appName"], &["auth", "errors", "flash"])?;
    let freshness = FreshnessPolicy::new(60_000, 0, 0)
        .map_err(|e| FrameworkError::internal(e.to_string()))?;
    let policy = RenderCachePolicy::builder(RepresentationClass::PublicShellStitched)
        .freshness(freshness).vary(VarianceDimension::Locale).build()
        .map_err(|e| FrameworkError::internal(e.to_string()))?;
    let router: Router = Router::new().get("/article", article).into();
    let router = router.try_render_cache("/article", policy)?;
    RenderCache::install(router, RenderCacheConfig::from_env()?).await
}
```

Attach the route's guards as usual. They run before any request prop resolves,
on misses and hits. The handler still runs on hits to register this request's
resolvers. Lazy public props skip their work on a hit. Eager work done before
constructing the response still runs, so put database and identity reads inside
the appropriate lazy prop. Session, flash, and error staging also run in the
request slot. Their reads do not become shell dependencies. Request slots run
again after every write; a write to public data invalidates the shared shell.
Public declarations never override an observed private dependency.

The entry holds public JSON and one typed request slot. It never stores a
previous visitor's props, flash, history flags, SSR markup, or CSRF token.
Assembly uses the composite engine before writing the final page. Both JSON
and HTML responses are `Cache-Control: private, no-store` and never answer a
conditional 304. HTML assembly runs SSR against the assembled page on every
request when SSR is enabled, then writes the root template and hydration JSON
from that same page. This costs one SSR render and document encoding per HTML
visit. With SSR disabled, there is no SSR render or worker request. Nonce CSP
pages render without storing an Inertia shell, as SEC-005 requires.

Field names use serde's wire renames. Cacheable fields require nonempty
top-level names; dotted shared keys use their top-level declaration.
Register each route and component pair before installing RenderCache. See
[RenderCache](render-cache.md), [Representations](render-cache-representations.md),
and [TypeScript types](frontend-typescript-types.md).

### Why Suprnova diverges

Laravel does not have a typed Inertia page cache. Suprnova requires complete
prop classification so a new private field cannot enter a shared shell by
default. It retains public data and assembles request data on the server.

## Next

- [Page Components](frontend-pages.md) - how the frontend resolves a
  component name to a Svelte / React / Vue module
- [TypeScript Types](frontend-typescript-types.md) - `suprnova generate-types`
  emits TS definitions from your `#[derive(InertiaProps)]` structs
- [Data Objects](data.md) - `#[derive(Data)]` for DTOs with per-field
  include/allowlist gating that composes with partial reloads
- [Error Model](error-model.md) - how `Response`, the panic boundary,
  and `FrameworkError` thread through Inertia responses
- [Container](container.md) - the lookup model behind
  `App::inertia_share*` and `InertiaSharedData`


---

<!-- /docs/frontend-inertia-devtools -->

# Inertia DevTools

The Inertia DevTools browser extension shows each request an Inertia
application answered: what kind of visit it was, which component rendered,
each prop with its kind and where it came from, and the request and
response themselves. The extension reads that from the server, so the
server has to record it. Once the application calls
`InertiaConfig::devtools(DevToolsConfig::new())`, Suprnova records in local
development (`APP_ENV=local`) and serves entries to the extension, as
inertia-laravel 3.5.1's `DevTools` does. An application that never calls it
records nothing and serves no entries.

## Enable DevTools

Opt in with `InertiaConfig::devtools(DevToolsConfig::new())`. A new
project's bootstrap makes this call, and its `.env` sets `APP_ENV=local`.
With `enabled` unset, a configured instance records only when `APP_ENV`
is set and names `local`; an unset `APP_ENV` records nothing. Once opted
in, `enabled(..)` and `INERTIA_DEVTOOLS_ENABLED` decide outright, and a
builder call wins over the variable. Without the configuration call,
there is no recording or entries endpoint, even with the variable set:

```rust
use suprnova::{DevToolsConfig, Inertia, InertiaConfig};

pub fn register_http_stack() {
    let devtools = DevToolsConfig::new()
        .enabled(true)                        // record on staging too
        .gate("viewInertiaDevtools")          // who may read entries there
        .except(["_inertia/devtools*", "_suprnova/*", "admin/*"])
        .limit(50);                           // entries kept per tab

    Inertia::install(&InertiaConfig::new().devtools(devtools))
        .expect("Inertia install failed");
}
```

`Inertia::install` and `Inertia::middleware` put `DevToolsMiddleware`
outermost in the Inertia stack when DevTools is enabled, inside the
session middleware you registered before them. Requests outside the stack,
such as an API group without it, are not recorded.

Every setting reads the variable Laravel's `config/inertia.php` reads, and
a builder call wins over the variable:

| Setting | Variable | Default |
|---|---|---|
| `enabled(bool)` | `INERTIA_DEVTOOLS_ENABLED` | unset: only when `APP_ENV` names `local` |
| `ttl_hours(hours)` | `INERTIA_DEVTOOLS_TTL_HOURS` | `24` |
| `prune_interval_secs(seconds)` | `INERTIA_DEVTOOLS_PRUNE_INTERVAL_SECONDS` | `300` |
| `limit(entries)` | `INERTIA_DEVTOOLS_LIMIT` | `100`, `0` keeps every entry |
| `gate(ability)` | `INERTIA_DEVTOOLS_GATE` | none |
| `storage_path(path)` | - | `storage_path("inertia-devtools")` |
| `except(patterns)` | - | `_inertia/devtools*`, `_suprnova/*` |
| `redact_keys(keys)` | - | `password`, `password_confirmation`, `current_password`, `token`, `_token`, `access_token`, `refresh_token`, `secret`, `client_secret`, `api_key` |
| `redact_headers(names)` | - | `cookie`, `set-cookie`, `authorization`, `proxy-authorization`, `x-xsrf-token`, `x-csrf-token` |

`INERTIA_DEVTOOLS_ENABLED` reads `true`, `1`, `on` and `yes` as on, and
`false`, `0`, `off` and `no` as off; an empty value leaves the decision to
the environment.

An `except` pattern is matched against the request path as
`Request::is` matches it: `*` matches any characters, and a leading slash
is ignored. The default skips the extension's own endpoints and the
framework's tooling routes, such as `/_suprnova/health`.

## What an entry holds

Each recorded request is one entry. Its JSON is Laravel's, key for key,
because the extension reads it:

- `__meta` - the entry `id` (a ULID), `tabUuid`, `batchId` and `visitId`
  from the extension's `X-Inertia-Devtools-Tab`, `-Parent` and `-Visit`
  headers (`batchId` for an Inertia visit only), the UTC `timestamp` and
  `utime`, the `method` and full `url`, the `component`, the
  `requestType`, the `status`, the `redirectLocation` (`X-Inertia-Location`,
  else `Location` on a `3xx`), and `serverTimingMs`.
- `http` - the request and response headers, and the request and response
  bodies.
- `props` and `propValues` - each prop of a rendered page with its kind,
  and the value the client received. See
  [Props and where they come from](#props-and-where-they-come-from).
- `route` - the `name` of the route that matched, its pattern as `uri`,
  the `method` for a rendered page, and the handler's type name as
  `action` (`app::controllers::users::index`). The name belongs to the
  route's method as well as its pattern, so `GET /users` named
  `users.index` and `POST /users` named `users.store` each record their
  own.
- `renderSource` - the file and line of the call that built the page.
- `componentPath` - the page file under `InertiaConfig::pages_dir`, when
  there is one.

The `requestType` is decided in this order:

1. `precognition` for a request with a `Precognition` header.
2. For a request that is not an Inertia visit, `initial` when it rendered
   a page and `http` when it did not.
3. `deferred` with the extension's `X-Inertia-Devtools-Deferred` header.
4. `poll` with its `X-Inertia-Devtools-Poll` header.
5. `partial` for a partial reload (`X-Inertia-Partial-Component`).
6. `prefetch` for a prefetch (`Purpose` or `Sec-Purpose: prefetch`).
7. `navigate` for any other Inertia visit.

The request body is recorded only for an Inertia visit when the request
writes (`POST`, `PUT`, `PATCH`, `DELETE`); any other write records
`{"status": "omitted", "reason": "non-inertia-request"}`. A JSON body is
recorded as the value it parses to, `{}`, `[]` and `null` included, and as
its text when it does not parse. Otherwise the query and form input are
recorded; else the raw text, `empty` when the body has no bytes, and
`binary` when it is not UTF-8.

DevTools reads the body before the handler, up to the framework's request
body cap (`suprnova::http::body::global_max_request_body_bytes`, 8 MiB
unless your bootstrap sets another), whether or not the request declares
its length. The handler then reads the copy kept on the request. A body
over the cap records `too-large` and stays whole for the handler, which
answers its own `413`, or reads all of it under a larger cap of its own,
such as a `FormRequest` with `max_body_bytes`. A body that fails to arrive
records `unreadable`, and the handler meets the same error only when it
reads the body, so a handler that ignores its body answers as it does with
DevTools off.

DevTools never reads a multipart upload itself. The upload's extractor
authorizes the request before any byte of the body is read, then parses
the body and hands DevTools what it parsed: a text part as text, a part
that is not text as `[UNSERIALIZABLE]`, and a file as its `name`, `size`
and `mimeType`, never its bytes, after the query. A name sent more than
once, or one that ends in `[]`, is the list of its parts, so every file
of a `photos[]` field is listed. An upload no extractor
read, because authorization refused it or the handler never asked for it,
records `not-read` with the declared length, and one whose parse failed
partway records `unparsed`:

```json
{"status": "omitted", "reason": "not-read", "size": 48213}
```

The raw text of a multipart body is never kept, so a password in an
upload form that failed to parse is not stored.

The response body of a rendered page is its page object. Any other
response records its text when its `Content-Type` is textual (JSON,
`text/*`, XML or JavaScript), decoded when it is JSON, up to 256,000
bytes; otherwise the reason is `non-textual`, `streamed` or `too-large`.
A page is recorded only once its response is built, so when the page's
document fails, such as a root template that fails to render, the entry
records the error response the client got, with no `component` and no
`props` or `propValues`.

## Headers and the id tag

Every recorded response carries:

- `X-Inertia-Devtools-Id` - the entry's id, which the extension fetches.
- `X-Inertia-Devtools-Parent-Out` - the incoming `X-Inertia-Devtools-Parent`
  of an Inertia visit, else the entry's own id. A prefetch is always its
  own parent. The extension sends the value back on the next request of
  the same batch, so the follow-ups of a visit, a redirect included,
  attach to it.
- `X-Inertia-Devtools-Base-Path` - the public root, when the application
  is not served at the host's root.

The first visit of a page has no response headers the extension can see
once it attaches, so a `200` HTML document that rendered a page for a
request that is not an Inertia visit gets the id in the document, before
its last closing body tag:

```html
<script data-inertia-devtools-id type="application/json">"01JA2B7Q9C3M4N5P6R7S8T9V0W"</script>
```

The closing tag is found in any case and with space before its `>`, so a
root template that ends with `</BODY>` or `</Body >` is tagged too. A
document with no closing body tag gets the tag at its end. A
`Content-Length` the handler set on the page is dropped with the tag
added, and the server sends the length of the tagged document.

Under a public root the tag also carries
`data-inertia-devtools-base-path="/billing"`. An Inertia visit's JSON and a
plain HTML page get no tag.

## Props and where they come from

Each prop of a rendered page is listed under `props` with `shared` and
`inertiaType`, and with each of these that applies:

- `inertiaType` - `always`, `defer`, `optional`, `merge`, `scroll` or
  `once`, read in that order from the prop's flags, so a prop built with
  `.merge().once()` is `merge`. A deferred prop is `defer`, with its
  `deferGroup`, only on the visit the extension marks as loading deferred
  props; reloaded by hand it is a plain prop.
- `reset` - the client named the prop in `X-Inertia-Reset`.
- `once` - the client keeps the prop across visits.
- `mergeDirection` - `append` or `prepend`, for a prop that merges.
- `deepMerge` - the prop merges deeply, or matches items with `match_on`.
- `rescued` - the prop's deferred resolver failed and was rescued.
- `shareSource` - for a shared prop, the file and line of the
  `Inertia::share`, `Inertia::share_many`, `Inertia::share_data`,
  `App::inertia_share`, `App::inertia_share_lazy` or
  `App::inertia_share_once` call that shared it, or of the
  `InertiaConfig::hooks` call that installed the middleware hooks that
  shared it.
- `renderSource` - for any other prop, the line that names its key below
  the render call: `"users":` in `inertia_response!`, or `("users",` in a
  builder call. When no line there names the key, as for a typed props
  struct defined in another file or a source file that is not on disk, it
  is the render call's own file and line.

A prop your middleware hooks share has the `InertiaConfig::hooks` call
that installed them as its `shareSource`: Rust has no reflection that
finds the `share` method's line. Keys from `share_provider` and
`register_inertia_shared` providers are marked `shared` with no source.
`errors` is listed as an `always` prop every page shares.

Every top-level key is listed. A dotted key that nests is listed under its
path only when it carries something besides being a prop. `propValues`
holds the value of each listed path as the client received it, after
partial-reload filtering, so a prop the visit withheld has no value.

## The entry endpoints

The extension reads entries from two endpoints, which `DevToolsMiddleware`
answers before any route:

- `GET /_inertia/devtools/entries` - every entry's `__meta`, newest first.
  `component=Home` keeps one component's entries, `type=navigate,partial`
  keeps those request types, `exclude=poll` drops these, then `offset` and
  `limit` (at least 1) page through the rest.
- `GET /_inertia/devtools/entries/{id}` - the stored entry, or
  `404 {"message": "Not found."}` for an id that is not a ULID or names no
  entry.

When `APP_ENV` names the `local` environment every request is admitted,
so a broken gate never locks you out of your own tools. Anywhere else, an
unset `APP_ENV` included, a request is admitted only when the configured
gate ability allows the signed-in user, else the answer is
`403 {"message": "Forbidden."}`. The gate is asked about the
user and `()` as the resource; a guest is asked about as `()`:

```rust
use suprnova::Gate;

// Admins only. A guest has no gate of this name, which denies.
Gate::define::<User, ()>("viewInertiaDevtools", |user, _| user.is_admin);
```

An endpoint request reflashes the session, so the flash data a `POST`
left for the page after its redirect still reaches that page when the
extension fetches the entry first. It never becomes the session's
previous URL, so a later `back()` does not send the visitor to it. It is
never recorded, whatever `except` says. With
`InertiaConfig::register_globally(false)`, the stack on your route groups
records their routes and `Inertia::install` registers a global
`DevToolsMiddleware` that answers only the endpoints.

## Storage and redaction

Each entry is one JSON file, `<storage_path>/<id>.json`, written to a
temporary file and renamed into place. `_meta.json` lists every entry's
`__meta`, newest first. Each rewrite holds a lock on `_meta.lock`, so
several processes can record into one directory, and renames a complete
new list over `_meta.json`, so an interrupted rewrite leaves the previous
list in place. When `_meta.json` is missing, empty or not a JSON list, it
is rebuilt from the entry files before it is read or rewritten, so the
next recorded request, prune and tab limit still see every stored entry.
A `.gitignore` in the directory keeps it out of your repository.

After a request, entries older than `ttl_hours` are pruned when the last
prune, noted in `_last_prune`, is at least `prune_interval_secs` old. A
browser tab keeps its newest `limit` entries.

Before an entry is written, the value of every key named by
`redact_keys` is replaced by `[REDACTED]` at any depth: in the request
and response bodies, in prop values, and in the page object. So are the
query parameters of the same names in the entry's URLs, and the values of
the `redact_headers` headers. Names are compared without case, so
`Password` is caught by `password`. A name is also caught by any of its
parts split on `[`, `]` and `.`: the multipart field `user[password]`, the
prop path `auth.password` and the query parameter `data[0][token]` are all
redacted, while a longer word such as `passwords` is kept.

A URL is any string in the entry that holds a `?` and starts with a
scheme (`https:`), `/` or `?`, such as a `redirect_to` form field or a
prop. A string under a `url` or `redirectLocation` key, and the value of
a `Location`, `X-Inertia-Location`, `Referer` or `Content-Location`
header, is a URL whatever it starts with, and so are the `<...>` targets
of a `Link` header and the target of a `Refresh` header. So a redirect to
`/reset?token=abc` is stored with `location: /reset?token=%5BREDACTED%5D`,
and a header that is not a URL is stored as sent. A header value or
multipart field that is not text is stored as `[UNSERIALIZABLE]`, and the
rest of the entry is kept.

## Recording never breaks a response

Recording observes the response and changes nothing of it beyond the
DevTools headers and the id tag. A failure while recording drops that
entry. A failure to write the store is logged at `warn` once and pauses
recording into that directory for 30 seconds; it is logged again only
after a write has succeeded. The response goes out with its headers
either way.

### Why Suprnova diverges

- **The configuration call is the install.** Laravel records once its
  DevTools package is installed. Here an application opts in with
  `InertiaConfig::devtools(DevToolsConfig::new())`, so an application that
  upgrades the framework records nothing until it asks.
- **Sources come from the compiler.** Laravel finds a render or share call
  by walking a backtrace and reflects on a route's controller. Here the
  calls take `#[track_caller]`, so a source is exact; the cost is that a
  hook-shared prop names the `InertiaConfig::hooks` call rather than the
  hooks' `share` method, a provider's keys have no source, and `route`
  has no `actionSource`.
- **`_suprnova/*` replaces `telescope*` and `horizon*`** in the default
  `except` list: those are Laravel packages, and `_suprnova/` is where the
  framework's own tooling routes live.
- **There is no `devtools.middleware` setting.** The endpoints run inside
  the Inertia stack, inside the session your bootstrap registered above
  it, which is what Laravel's default `web` group gives them.
- **A request body is read up to the request body cap.** Symfony keeps
  every body in memory; a Rust request streams its body to the handler.
  DevTools reads a body first up to the framework's request body cap, the
  most an extractor reads, and records a larger one as `too-large`,
  leaving it for the handler. A multipart upload is never read by
  DevTools: its extractor summarizes what it parsed, after the request is
  authorized, so an upload no extractor read is `not-read`, and one whose
  parse failed is `unparsed`. Multipart field names are kept as sent, not
  nested: the files of `photos[]` are listed under `photos[]`.
- **Redaction matches key parts and the URLs in headers.** Laravel's
  `RedactsSensitiveData` matches a key whole and redacts no URL in a
  header. Suprnova also redacts a key when any bracketed or dotted part
  of it names a redaction key, such as `user[password]` or
  `auth.password`, and redacts the query of every URL in headers and
  bodies, `Location` and `Referer` included. The extension's store is a
  file on disk, and a reset token in a `Location` header is as sensitive
  as one in the body.
- **The gate takes a resource.** Suprnova's gate is typed by user and
  resource, so the ability is defined for `(User, ())`, and a guest is
  `()` where Laravel passes `null`.
- **A prop value is never `[UNSERIALIZABLE]`.** A Suprnova prop is a JSON
  value once it resolves, so the marker appears only for header values and
  multipart text that are not UTF-8.
- **The write breaker is per directory**, where Laravel's is one static
  per process: a failing directory does not pause recording into another.
- **DevTools reads `APP_ENV` itself.** Laravel's unset `APP_ENV` is
  `production`, while Suprnova's `Environment::detect` reads an unset one
  as `local`. After the application opts in, DevTools reads the variable
  itself and records only when it is set to `local` if `enabled` is unset.
  `enabled(..)` and `INERTIA_DEVTOOLS_ENABLED` decide outright. A new
  project's bootstrap opts in and its `.env` sets `APP_ENV=local`; an
  application that never calls `devtools(..)` records nothing and serves
  no entries.

## Next

- [Inertia Responses](frontend-inertia-responses.md) - the middleware
  stack DevTools sits in, and the prop flags it classifies
- [Authorization](authorization.md) - defining the gate ability
- [HTTP Tests](http-tests.md) - `TestClient`, whose requests DevTools
  records like any other, so a test can read the entry a page left


---

<!-- /docs/frontend-pages -->

# Page Components

A page is the unit Inertia ships across the wire. The Rust controller picks a
component name and a typed props struct; the Vite-bundled frontend resolves
that name to a file in `frontend/src/pages/` and renders it with the props as
arguments. The framework is framework-agnostic - Suprnova ships first-class
starters for Svelte 5, React 19, and Vue 3.5, and the page contract is the
same shape in all three.

## The contract

A controller returns an Inertia response naming a component:

```rust
use suprnova::{InertiaProps, Request, Response, inertia_response};

#[derive(InertiaProps)]
pub struct HomeProps {
    pub title: String,
    pub message: String,
}

pub async fn index(req: Request) -> Response {
    inertia_response!(&req, "Home", HomeProps {
        title: "Welcome".to_string(),
        message: "Hello from Suprnova!".to_string(),
    })
}
```

The string `"Home"` is resolved against `frontend/src/pages/Home.<ext>`. The
extension depends on which starter you scaffolded:

| Starter | Extension | Default? |
|---|---|---|
| Svelte 5 | `.svelte` | yes |
| React 19 | `.tsx` | - |
| Vue 3.5 | `.vue` | - |

The macro validates at compile time that the file exists, so a typo or a
deleted page fails `cargo check` instead of 500-ing in production.

## Directory layout

Whichever framework you picked, pages live under `frontend/src/pages/` and
the component name in `inertia_response!` is the file path relative to that
directory, without the extension. Forward slashes work the same on all
platforms. A project with a different layout can
[point the check elsewhere](#another-page-layout).

```
frontend/src/pages/
├── Home.svelte                 # inertia_response!(&req, "Home", ...)
├── About.svelte                # inertia_response!(&req, "About", ...)
├── Users/
│   ├── Index.svelte            # inertia_response!(&req, "Users/Index", ...)
│   ├── Show.svelte             # inertia_response!(&req, "Users/Show", ...)
│   └── Edit.svelte             # inertia_response!(&req, "Users/Edit", ...)
├── Posts/
│   ├── Index.svelte            # inertia_response!(&req, "Posts/Index", ...)
│   └── Show.svelte             # inertia_response!(&req, "Posts/Show", ...)
└── auth/
    ├── Login.svelte            # inertia_response!(&req, "auth/Login", ...)
    └── Register.svelte         # inertia_response!(&req, "auth/Register", ...)
```

The convention is `Index` for collection pages, `Show` / `Edit` / `Create` for
single-item pages, and a lowercase subdirectory like `auth/` for grouped
feature pages. Capitalisation in the component name must match the file name
exactly - Vite's `import.meta.glob` is case-sensitive.

### Another page layout

The compile-time check looks in `frontend/src/pages/` because that is where
`suprnova new` puts pages. A frontend that lays its pages out another way,
such as an Angular app on a community Inertia adapter, sets its own lookup in
the application crate's `Cargo.toml`:

```toml
[package.metadata.suprnova.inertia]
pages_dir = "resources/angular/pages"
page_file = "{dir}/{name|lower}.page.ts"
```

`pages_dir` is the pages directory, relative to the crate directory.
`page_file` is the page's path inside it, built from the component name:

| Placeholder | `Tramits/BaixaMatricula/Create` | `Home` |
|---|---|---|
| `{dir}` | `Tramits/BaixaMatricula` | empty |
| `{name}` | `Create` | `Home` |

With the lookup above, the macro requires these files:

| Component | File |
|---|---|
| `Tramits/Index` | `resources/angular/pages/Tramits/index.page.ts` |
| `Tramits/BaixaMatricula/Create` | `resources/angular/pages/Tramits/BaixaMatricula/create.page.ts` |
| `Home` | `resources/angular/pages/home.page.ts` |

An empty `{dir}` leaves no stray `/` behind, so a top-level page sits directly
in `pages_dir`.

A filter after `|` changes the case of a placeholder. On `{dir}`, it applies to
each directory name.

| Filter | `BaixaMatricula` becomes |
|---|---|
| `lower` | `baixamatricula` |
| `kebab` | `baixa-matricula` |
| `snake` | `baixa_matricula` |

`kebab` and `snake` start a new word at each capital letter that follows a
lowercase letter or a digit, and at the last capital of an acronym followed by
a lowercase letter, so `HTMLReport` becomes `html-report`. A `-`, `_`, or space
already in the name also separates words.

Both keys are optional. With `pages_dir` alone, the macro looks for
`{Component}.svelte`, `.tsx`, `.jsx`, or `.vue` under that directory. With
`page_file` alone, it resolves the pattern under `frontend/src/pages/`. Without
the table, the macro uses the starter lookup.

A misspelled key, an unknown filter, or an unbalanced `{` is a compile error
that names the key and the problem. A missing page names the path the macro
looked for:

```text
error: Inertia component 'Tramits/BaixaMatricula/Edit' not found.
       Looked for: resources/angular/pages/Tramits/BaixaMatricula/edit.page.ts
       The page lookup comes from [package.metadata.suprnova.inertia] in Cargo.toml.
```

Deleting a page or editing the table re-runs the check on the next build, even
when no Rust file changed.

The table moves only the compile-time check. Your frontend's own resolver,
such as the `resolve` callback passed to `createInertiaApp`, must map the same
component names to the same files. `suprnova make:inertia` still writes pages
in the starter layout.

## Generating a page

The CLI's `make:inertia` generator drops a starter component into the right
location and uses the syntax for whichever frontend the project is using:

```bash
suprnova make:inertia Dashboard
```

The generator reads `SUPRNOVA_FRONTEND` from your `.env` (defaulting to
Svelte), picks the matching extension, and appends `Page` to the component
name if it's not already there. So the command above creates one of:

- `frontend/src/pages/DashboardPage.svelte`
- `frontend/src/pages/DashboardPage.tsx`
- `frontend/src/pages/DashboardPage.vue`

The console output prints the matching `inertia_response!` call you should
paste into your controller.

To skip the suffix and own the name, pass the full name:

```bash
suprnova make:inertia DashboardPage   # creates DashboardPage.<ext>
```

To generate a typed props struct on the Rust side instead, pass `--data`:

```bash
suprnova make:inertia Dashboard --data
# Creates src/props/dashboard.rs with #[derive(Data, Validate)]
```

## A page in each starter

The same `inertia_response!(&req, "Home", HomeProps { ... })` on the backend
maps to one of these page files on the frontend. Props arrive as typed
arguments via the generated `inertia-props.ts` types. The kits render plain
English and ship no translation modules or catalogs.

### Svelte 5

Runes-on. Props arrive via `$props()`:

```svelte
<!-- frontend/src/pages/Home.svelte -->
<script lang="ts">
  import Head from '../components/Head.svelte'
  import type { HomeProps } from '../types/inertia-props'

  let { title, message }: HomeProps = $props()
</script>

<!-- No title of its own: the tab shows the application's name. -->
<Head />

<div class="mx-auto max-w-xl p-8 font-sans">
  <h1 class="text-3xl font-bold">Welcome to {title}</h1>
  <p class="mt-2">{message}</p>
</div>
```

`@inertiajs/svelte` has no `Head` component, so the kit ships its own in
`frontend/src/components/Head.svelte`. It writes the page's title into
Svelte's `<svelte:head>` as `Title - App`, through the same `pageTitle`
function `main.ts` passes to `createInertiaApp` as `title`. A page that
passes no title shows the application's name alone.

### React 19

Standard function component. Props arrive as the first argument, and
`Head` sets the tab title. The page renders no frame of its own: the layout
comes from `createInertiaApp` (see [Layouts](#layouts)).

```tsx
// frontend/src/pages/Home.tsx
import { Head } from '@inertiajs/react'
import type { HomeProps } from '../types/inertia-props'

export default function Home({ title, message }: HomeProps) {
  return (
    <div className="font-sans p-8 max-w-xl mx-auto">
      <Head title="Welcome" />
      <h1 className="text-3xl font-bold">Welcome to {title}</h1>
      <p className="mt-2">{message}</p>
    </div>
  )
}
```

The browser tab then reads `Welcome - My App`: the `title` callback in
`frontend/src/lib/app.ts` appends the application's name to each page's
title.

### Vue 3.5

`<script setup lang="ts">` with `defineProps`. Props are accessed directly
in the template. `<Head>` sets the tab title, and the entry's `title`
callback appends the application's name, so a project scaffolded as
`my-app` shows `Welcome - My App`:

```vue
<!-- frontend/src/pages/Home.vue -->
<script setup lang="ts">
import { Head } from '@inertiajs/vue3'
import type { HomeProps } from '../types/inertia-props'

defineProps<HomeProps>()
</script>

<template>
  <Head title="Welcome" />

  <div class="font-sans p-8 max-w-xl mx-auto">
    <h1 class="text-3xl font-bold">Welcome to {{ title }}</h1>
    <p class="mt-2">{{ message }}</p>
  </div>
</template>
```

## Navigation between pages

Each starter ships the Inertia v3 adapter for its framework. The exports are
the same: `Link` for declarative navigation, `router` for programmatic
navigation, `usePage` (or `page`) for shared props, `Form` and `useForm` for
form handling.

### Svelte 5

The kit builds every link from the `root` shared prop, so the same build
works at `/` and under a path prefix:

```svelte
<script lang="ts">
  import { Link, usePage } from '@inertiajs/svelte'

  const { root } = usePage().props
  let { note }: { note: { id: number; title: string } } = $props()
</script>

<Link href={`${root}/notes`}>Notes</Link>
<Link href={`${root}/logout`} method="post" as="button" preserveState={false}>Sign out</Link>

<!-- Prefetched on hover, and instant: Notes/Show renders from this row
     before the server answers. -->
<Link
  href={`${root}/notes/${note.id}`}
  prefetch
  component="Notes/Show"
  pageProps={(_props, shared) => ({ ...shared, note })}
>
  {note.title}
</Link>
```

The sign-out link comes from `components/AccountLinks.svelte`, and the note link
comes from `pages/Notes/Index.svelte`. A link with a method other than GET
keeps the page's state by default, so the sign-out link passes
`preserveState={false}` to start the page it lands on afresh. The function
form of `pageProps`
keeps the shared props, `root` among them, on the page that renders before
the server answers. A plain object replaces every prop on that page.
`router.visit(url)` does the same navigation from a script.

### React 19

The React starter builds every link from the shared `root` prop, so the
same build runs at `/` and under a path prefix. These lines come from its
layout and its notes page:

```tsx
import { Link, router, usePage } from '@inertiajs/react'

const { root } = usePage().props

<Link href={`${root}/notes`}>Notes</Link>
<Link href={`${root}/logout`} method="post" as="button" preserveState={false}>Sign out</Link>

{/* Prefetch on hover, and render Notes/Show from this row before the server answers. */}
<Link
  href={`${root}/notes/${note.id}`}
  prefetch
  component="Notes/Show"
  pageProps={(_props, shared) => ({ ...shared, note })}
>
  {note.title}
</Link>

<button onClick={() => router.visit(`${root}/notes`)}>Visit programmatically</button>
```

The sign-out `Link` passes `preserveState={false}`. A `Link` that posts
keeps the page's state by default, and with it the layout props a page
set, so without it the dashboard's heading would follow the visitor to the
next page.

An instant visit given an object for `pageProps` renders the next page
with those props alone. The function form receives the shared props as its
second argument, so `root` reaches the first render too.

### Vue 3.5

The Vue kit reaches every application route through `Link`. Each URL starts
from `root`, the public root the server shares with every page, so one build
runs at `/` and under a path prefix. The account links read the signed-in
user the server shares as `auth.user`. The sign-out is a `Link` that posts,
rendered as a button. A posting link keeps the page's state by default, so
it passes `:preserve-state="false"`, and the layout props the page set do not
follow the visitor to the sign-in page:

```vue
<!-- frontend/src/components/AccountLinks.vue, without its classes -->
<script setup lang="ts">
import { computed } from 'vue'
import { Link, usePage } from '@inertiajs/vue3'

const page = usePage()
const { root } = page.props
const user = computed(() => page.props.auth.user)
</script>

<template>
  <template v-if="user">
    <span>{{ user.name }}</span>
    <Link :href="`${root}/logout`" method="post" as="button" :preserve-state="false">
      Sign out
    </Link>
  </template>
  <template v-else>
    <Link :href="`${root}/login`">Sign in</Link>
    <Link :href="`${root}/register`">Register</Link>
  </template>
</template>
```

A row of `Notes/Index.vue` prefetches its note on hover and opens it as an
instant visit: `component` and `page-props` let the client render
`Notes/Show` from the row at once, and the server's answer replaces it when
it arrives. `page-props` takes the function form, which keeps the shared
props, `root` among them, on that first render; the object form would drop
them until the server answers. The search box navigates programmatically,
keeping the page's state and starting the infinite list over:

```vue
<Link
  :href="`${root}/notes/${note.id}`"
  prefetch
  component="Notes/Show"
  :page-props="(_props, shared) => ({ ...shared, note })"
>
  {{ note.title }}
</Link>
```

```ts
router.get(
  `${root}/notes`,
  { search: unref(filters).search },
  { preserveState: true, replace: true, only: ['notes', 'search'], reset: ['notes'] },
)
```

The `router` object also exposes `router.post(url, data)`,
`router.put(url, data)`, `router.patch(url, data)`, `router.delete(url)`, and
`router.reload()` - same shape across all three adapters.

## Forms

Inertia v3 ships a declarative `<Form>` component and the imperative
`useForm` (or `createForm` in Svelte) helper. Both POST back to your Rust
controller; validation errors surface as a structured `errors` prop.

### Svelte 5

The kit's notes page creates a note with the `Form` component. `Form` posts
the fields by their `name` and hands its children the form's `errors` and
`processing`:

```svelte
<!-- frontend/src/pages/Notes/Index.svelte -->
<script lang="ts">
  import { Form, usePage } from '@inertiajs/svelte'

  const { root } = usePage().props
</script>

<Form action={`${root}/notes`} method="post" class="space-y-4">
  {#snippet children({ errors, processing })}
    <input name="title" type="text" required maxlength="255" />
    {#if errors.title}
      <p class="text-red-600">{errors.title}</p>
    {/if}

    <textarea name="body" rows="4" maxlength="10000"></textarea>

    <button type="submit" disabled={processing}>
      {processing ? 'Saving...' : 'Save note'}
    </button>
  {/snippet}
</Form>
```

Every auth page in the kit submits the same way. A failed submission comes
back as a `303` to the form's page with the errors flashed, and `Form` reads
them from the page. The Login page also passes `transform`. A checked
checkbox submits the text `on`, and `transform` turns `remember` into the
boolean the handler's `LoginRequest` reads. For a form whose data a script
needs, `useForm` gives the same `errors` and `processing` on an object you
bind inputs to.

### React 19

The React starter submits every form through `<Form>`: the sign-in and
registration pages, the password reset, the verification resend, and the
note form on `Notes/Index`. `Form` reads the inputs by their `name` and
passes `errors` and `processing` to its children:

```tsx
// frontend/src/pages/Notes/Index.tsx (the note form)
import { Form, usePage } from '@inertiajs/react'

const { root } = usePage().props

<Form action={`${root}/notes`} method="post" options={{ preserveState: 'errors' }}>
  {({ errors, processing }) => (
    <>
      <input name="title" type="text" required maxLength={255} />
      {errors.title && <p className="text-red-600">{errors.title}</p>}

      <textarea name="body" rows={4} />
      {errors.body && <p className="text-red-600">{errors.body}</p>}

      <button type="submit" disabled={processing}>
        {processing ? 'Saving...' : 'Save note'}
      </button>
    </>
  )}
</Form>
```

Every value a form sends is a string, and an unchecked checkbox sends
nothing. A handler that reads a `bool` gets one through `transform`, as the
sign-in page does for its `remember` checkbox:

```tsx
<Form
  action={`${root}/login`}
  method="post"
  transform={(data) => ({ ...data, remember: Boolean(data.remember) })}
>
```

### Vue 3.5

The Vue kit submits every form through the `<Form>` component. It reads the
fields by their `name`, sends them to `action`, and hands its slot the
`errors` the server answered with and a `processing` flag. The note form in
`Notes/Index.vue`, without its classes:

```vue
<!-- frontend/src/pages/Notes/Index.vue (the note form) -->
<script setup lang="ts">
import { Form, usePage } from '@inertiajs/vue3'

const { root } = usePage().props
</script>

<template>
  <Form
    :action="`${root}/notes`"
    method="post"
    :options="{ preserveState: 'errors' }"
    v-slot="{ errors, processing }"
  >
    <input id="title" name="title" type="text" required maxlength="255" />
    <p v-if="errors.title">{{ errors.title }}</p>

    <textarea id="body" name="body" rows="4" maxlength="10000" />
    <p v-if="errors.body">{{ errors.body }}</p>

    <button type="submit" :disabled="processing">
      {{ processing ? 'Saving...' : 'Save note' }}
    </button>
  </Form>
</template>
```

`preserveState: 'errors'` keeps the page as it is when the server answers
with validation errors, and remounts it after a saved note, so the list
starts over from the newest note and the fields are empty again.

`<Form>` sends JSON, and a checked checkbox is the string `"on"` in its data.
The sign-in page sends `remember` as the boolean the server reads:

```vue
<script setup lang="ts">
import type { FormDataConvertible } from '@inertiajs/core'

function withRememberFlag(data: Record<string, FormDataConvertible>) {
  return { ...data, remember: 'remember' in data }
}
</script>

<template>
  <Form :action="`${root}/login`" method="post" :transform="withRememberFlag" v-slot="{ errors, processing }">
    <!-- email, password, and <input name="remember" type="checkbox" /> -->
  </Form>
</template>
```

For a JSON endpoint outside page visits, the dashboard's display-name form
uses `useHttp`. `optimistic` shows the new name before the server answers; a
`422` puts the old name back and fills `errors.name`. A saved name reloads the
shared `auth` prop, so the layout shows it too:

```ts
const page = usePage()
const user = computed(() => page.props.auth.user)

const profile = useHttp<{ name: string }, { user: UserInfo }>({ name: user.value?.name ?? '' })
const draft = ref(user.value?.name ?? '')

function saveName() {
  return profile.optimistic(() => ({ name: draft.value })).post(`${root}/profile/name`, {
    onSuccess: () => router.reload({ only: ['auth'] }),
  })
}
```

### Form callbacks

`form.post(url, options)` - and the matching `.put` / `.patch` /
`.delete` - accept the standard visit callbacks (`onStart`, `onSuccess`,
`onError`, `onFinish`). Validation errors returned by your Rust handler
land in `form.errors` automatically; the callbacks are for side effects:

```ts
form.post('/posts', {
  onSuccess: async () => { await refreshDrafts() },  // awaited
  onError: (errors) => console.warn(errors),
  onFinish: () => form.reset('content'),
})
```

An async `onSuccess` is awaited before the submission settles, so
`form.processing` stays `true` until your callback resolves - handy when a
successful submit kicks off follow-up work you don't want the UI to race
past.

## Polling

For a page that should refresh on an interval - a live dashboard, a job
status, an unread badge - the `usePoll` hook reissues a partial reload on
a timer. Import it from your adapter:

```ts
import { usePoll } from '@inertiajs/svelte' // or '@inertiajs/react' / '@inertiajs/vue3'
```

Pair it with `only` so each tick fetches just the props that change - the
server then resolves only those keys (see
[partial reloads](frontend-inertia-responses.md#partial-reloads)):

```ts
const { stop, start } = usePoll(5000, { only: ['stats', 'jobs'] })
```

`usePoll(interval, requestOptions, options)`:

- **`interval`** - milliseconds between reloads.
- **`requestOptions`** - a reload options object (`only`, `except`,
  `data`, `onSuccess`, …) **or a function returning one**, so the request
  can depend on current state (e.g. a cursor that advances each tick).
- **`options.mode`** - how a tick that fires while the previous request is
  still in flight is handled: `'overlap'` (default - fire anyway),
  `'cancel'` (abort the in-flight request), or `'rest'` (skip this tick).
- **`options.keepAlive`** - keep polling while the tab is backgrounded
  (default `false`: polling pauses on a hidden tab).
- **`options.autoStart`** - begin immediately (default `true`); pass
  `false` and call the returned `start()` when you're ready.

The hook returns `{ stop, start }` for manual control. Outside a
component, `router.poll(...)` from `@inertiajs/core` is the same call.

Because every tick is an ordinary partial reload, the props under `only`
flow through the same Lazy / Optional / Defer resolvers as any other
request - and those resolvers run concurrently (capped by
`max_concurrent_resolvers`), so a dashboard polling six widgets issues six
parallel queries per tick instead of six serial ones.

## Live topic bindings

A typed page can subscribe its props to a Live application topic. Add a
repeatable `#[inertia(live(...))]` declaration to its `InertiaProps` type:

```rust
use suprnova::{InertiaProps, InertiaResponse, Request, Response};

#[derive(InertiaProps)]
#[serde(rename_all = "camelCase")]
#[inertia(live(topic = "posts", only = ["posts", "postCount"]))]
pub struct DashboardProps {
    pub posts: Vec<PostSummary>,
    pub post_count: usize,
}

pub async fn dashboard(req: Request) -> Response {
    Ok(InertiaResponse::live::<DashboardProps>("Dashboard")
        .load(|| async {
            Ok(DashboardProps {
                posts: recent_posts().await?,
                post_count: count_posts().await?,
            })
        })
        .await?
        .resolve(&req)
        .await?)
}
```

The topic must be declared in the [Live registry](live.md#topic-signals).
`only` contains serialized prop names, after a `serde` rename such as
`post_count` to `postCount`. The derive rejects an unknown name or a duplicate
name at compile time. Repeat the attribute to bind another topic.

Use `InertiaResponse::live::<P>` and a loader for every bound page. The
framework reads the authorized bindings' generations and cursors in one hub read before it
calls the loader. This includes eager queries inside the loader. A write
committed after the query remains newer than the rendered cursor. Prebuilt
bound props are rejected by `inertia_response!` instead of acquiring a newer
cursor after their data was read.

A family binding uses the family name in the attribute and supplies its key
before loading. The runtime metadata contains the resolved instance name:

```rust
InertiaResponse::live::<NotesDashboardProps>("Dashboard")
    .scope("notes", user_id)
    .load_with(move |response| async move {
        Ok(response
            .defer("stats", move || note_stats(user_id))
            .optional("recent_notes", move || recent_notes(user_id)))
    })
    .await?
    .resolve(&req)
    .await?
```

`load` returns typed `P` props. `load_with` receives the response builder so
existing deferred and optional resolvers keep their filtering rules. Both use
the same pre-loader cursor boundary. A missing family scope fails with an
internal error naming the component and family. A family key is one trusted
Live mount parameter, at most 128 unreserved ASCII bytes. The full instance
still follows the topic-name bound.

The response carries the checked metadata in the reserved top-level page field
`liveBindings`, outside `props`. Partial reload filtering never drops it. Each
topic has this shape:

```json
{
  "liveBindings": {
    "posts": {
      "only": ["posts", "postCount"],
      "cursor": 42,
      "generation": 1792688181000,
      "island": {
        "component": "suprnova.topic.a44f1b975171163546d46ba5ca80652f85fcad7f665cf55d00a202ff9d0f7dbe",
        "slot": "topic",
        "document_key": "topic"
      },
      "stream": "changes"
    }
  }
}
```

`only` is the partial reload list. `generation` identifies one lifetime of
the topic's authority state. Generations are unique and increasing within an
authority and unique across in-process restarts; across process restarts they
differ except with negligible probability. Clients compare generations for
inequality only. `cursor` is the position within that generation. Both are
captured before the loader runs, and `island` plus `stream` describe the
authorized Live subscription. The generated frontend types expose the same table as
`LiveBindings` and map page components through `InertiaLiveBindings`. The
existing `inertiaPropCache` record also carries each page's topic-to-prop map
under `live`, beside `cacheable`, `public`, and `perRequest`.

When a `topic_change` arrives, the adapter reloads the named props through the
ordinary Inertia partial reload path. An empty signal prop list reloads all
props in the binding. The signal carries only `topic`, `generation`, `cursor`, and `props`,
so page data still comes from the controller under its normal authorization.

A topic may instead be a component-stream alias such as
`app.activity-feed::activity`. The component's stream ability authorizes that
subscription. A binding by application topic name uses the application's
`live:topic.<topic>` ability. See
[Asynchronous updates](live.md#asynchronous-updates) for component streams.

Mount the generated adapter in the page component. React and Vue import
`useLive` from `../lib/live`; Svelte imports it from
`../lib/live/index.svelte`. Keep a configured `usePoll` interval for browsers
without push delivery. For example, this React page keeps a ten-second fallback:

```tsx
import { usePage, usePoll } from '@inertiajs/react'
import { useLive } from '../lib/live'

export default function Dashboard() {
  useLive()
  usePoll(10000, { only: ['posts', 'postCount'] })
  const { props } = usePage()
  return <main>{String(props.postCount ?? 0)} posts</main>
}
```

The Vue composable uses the same `useLive()` call inside `setup`. The Svelte
rune store also exposes connection state:

```svelte
<script lang="ts">
  import { usePoll } from '@inertiajs/svelte'
  import { useLive } from '../lib/live/index.svelte'

  const live = useLive()
  usePoll(10000, { only: ['posts', 'postCount'] })
</script>

<p>Live updates: {live.status}</p>
```

The shared core uses SSE for a page without an existing Live connection. It
reuses the document's WebSocket when Live already owns one. Live's hybrid
polling takes over when push continuity fails; `usePoll` also works when the
async artifact cannot load. Unmounting releases the page's subscriptions.
Signals within 25 milliseconds become one reload of the affected prop union.
Only props present in the response advance their rendered cursors. A rescued
or omitted deferred prop keeps its invalidation. Failed or canceled reloads
retry after 1, 2, 4, 8, and 16 seconds, then every 30 seconds. A successful
reload resets this backoff. The page keeps its polling fallback during retries.
A changed generation reloads every prop bound to that topic regardless of
its old cursor. Each prop keeps its own rendered generation and cursor, so a partial response cannot consume
a change for a prop it did not reload. Page subscriptions pass every signal
to these per-prop checks. A full recovery signal with a lower cursor can
therefore refresh props that an earlier partial signal did not refresh.
Full island refreshes use one position for the whole island. Every Inertia
visit carries the Live document identity in `X-Socket-ID` while the adapter
is mounted.

A private binding is included only when the current principal has its topic
or stream ability. Otherwise the page renders without that binding or cursor
and keeps its polling fallback. The framework logs the page component and
declared topic or family once at warn per process, then at debug on later
denied renders. The resolved instance name remains in the log fields.

The client core regression suite uses Bun. Run it from the repository root:

```sh
bun test suprnova-cli/tests/frontend-live-core.test.ts
```

The ignored Rust wrapper requires Bun on PATH and supplies a real rendered
page to the same suite. Its ignore reason is `requires Bun`.

### Why Suprnova diverges

Laravel has no built-in equivalent for topic-driven Inertia partial reloads.
The similarly named `inertia-live` is an external package, not Laravel
framework behavior. Suprnova makes the binding part of the checked Rust props
contract and reuses Live authorization, cursors, and fanout for delivery.

## Shared props

Anything you register as a shared prop at boot - typically the current user,
flash messages, and global CSRF token - is available on every page through
`usePage()` (React, Vue) or the reactive `page` store (Svelte). Page props
override shared props on key collision.

### Svelte 5

```svelte
<script lang="ts">
  import { page } from '@inertiajs/svelte'

  let auth = $derived($page.props.auth as { user?: { name: string } })
</script>

{#if auth.user}
  <span>Welcome, {auth.user.name}</span>
{:else}
  <a href="/login">Log in</a>
{/if}
```

### React 19

```tsx
import { usePage } from '@inertiajs/react'

function Header() {
  const { auth } = usePage<{ auth: { user?: { name: string } } }>().props
  return auth.user ? <span>Welcome, {auth.user.name}</span> : <a href="/login">Log in</a>
}
```

### Vue 3.5

```vue
<script setup lang="ts">
import { usePage } from '@inertiajs/vue3'

const page = usePage<{ auth: { user?: { name: string } } }>()
</script>

<template>
  <span v-if="page.props.auth.user">Welcome, {{ page.props.auth.user.name }}</span>
  <a v-else href="/login">Log in</a>
</template>
```

## Layouts

The kits apply their layouts through `createInertiaApp`'s `layout` option.
Pages render their own content inside the layout selected there. The
layout stays mounted across visits between pages that share it, so its
state survives navigation.

### Svelte 5

The kit applies its layouts once, in `createInertiaApp`'s `layout` option,
instead of wrapping each page in one. A layout given there stays mounted
while visits move between the pages that use it, so its state survives a
visit:

```ts
// frontend/src/main.ts (and src/ssr.ts, so the server renders the same frame)
createInertiaApp({
  pages: './pages',
  layout: (name) => (name.startsWith('auth/') ? GuestLayout : AppLayout),
  // ...
})
```

A layout receives the page's props, the props a page sets with
`setLayoutProps`, and the page as `children`:

```svelte
<!-- frontend/src/layouts/AppLayout.svelte -->
<script lang="ts">
  import { Link } from '@inertiajs/svelte'
  import type { Snippet } from 'svelte'
  import AccountLinks from '../components/AccountLinks.svelte'
  import FlashToast from '../components/FlashToast.svelte'
  import type { SharedProps } from '../types/inertia-props'

  interface Props extends SharedProps {
    heading?: string
    children?: Snippet
  }

  let { root, heading, children }: Props = $props()
</script>

<nav>
  <Link href={`${root}/dashboard`}>Dashboard</Link>
  <Link href={`${root}/notes`}>Notes</Link>
  <AccountLinks />
</nav>

<FlashToast />

<main>
  {#if heading}<h1>{heading}</h1>{/if}
  {@render children?.()}
</main>
```

Both layouts render `components/AccountLinks.svelte`, which reads `auth`,
a prop the server shares with every page. When `auth.user` is set, it shows
the user's name and a sign-out link. When `auth.user` is `null`, it shows
sign-in and register links. The guest layout needs both branches, because
`auth/VerifyEmail` is shown to a user who is signed in:

```svelte
<!-- frontend/src/components/AccountLinks.svelte -->
<script lang="ts">
  import { Link, page } from '@inertiajs/svelte'

  const root = $derived(page.props.root)
  const user = $derived(page.props.auth.user)
</script>

{#if user}
  <span>{user.name}</span>
  <Link href={`${root}/logout`} method="post" as="button" preserveState={false}>
    Sign out
  </Link>
{:else}
  <Link href={`${root}/login`}>Sign in</Link>
  <Link href={`${root}/register`}>Register</Link>
{/if}
```

The dashboard sets the heading with `setLayoutProps({ heading: 'Dashboard' })`.
The next page that sets none shows no heading, because a visit to another
page resets the layout props. `FlashToast` renders `page.flash.toast`, the
toast a handler flashed with `Inertia::flash("toast", ..)`, so it shows on
one page and is gone on the next.

### React 19

The React starter ships two layouts and applies them through
`createInertiaApp`'s `layout` option, which both entries import from
`frontend/src/lib/app.ts`:

```ts
// frontend/src/lib/app.ts
export function layout(name: string) {
  return name.startsWith('auth/') ? GuestLayout : AppLayout
}
```

A page never renders its layout itself. Inertia renders the layout around
the page with the page's props, so a visit between two pages with the same
layout keeps the layout mounted, and its state with it. A page passes
values up with `setLayoutProps`; the dashboard sets the heading the
application layout shows, and the next visit clears it:

```tsx
// frontend/src/pages/Dashboard.tsx
import { setLayoutProps } from '@inertiajs/react'

setLayoutProps({ heading: 'Dashboard' })
```

```tsx
// frontend/src/layouts/AppLayout.tsx (shortened)
import type { ReactNode } from 'react'
import { Link, usePage } from '@inertiajs/react'
import AccountLinks from '../components/AccountLinks'
import FlashToast from '../components/FlashToast'

export default function AppLayout({ children, heading }: { children?: ReactNode; heading?: string }) {
  const { root } = usePage().props

  return (
    <div className="min-h-screen bg-gray-100">
      <nav className="bg-white shadow">
        <Link href={`${root}/dashboard`}>Dashboard</Link>
        <Link href={`${root}/notes`}>Notes</Link>
        <AccountLinks className="text-sm" />
      </nav>
      <FlashToast />
      {heading && <h1 className="text-2xl font-bold">{heading}</h1>}
      <main className="max-w-7xl mx-auto py-6">{children}</main>
    </div>
  )
}
```

`AccountLinks` reads the signed-in user from the shared `auth` prop: the
name and the sign-out `Link` when someone is signed in, the sign-in and
register links when not. `FlashToast` shows `usePage().flash.toast`, the
toast a handler flashed with `Inertia::flash("toast", Toast { .. })`,
typed by the generated `flashDataType`. It reads the toast from the page
on every render. The server sends a flash with one page only, so the toast
is gone on the next visit.

### Vue 3.5

The Vue kit applies its two layouts through `createInertiaApp`'s `layout`
option, so no page imports one. Pages under `auth/` get the guest layout and
every other page gets the application layout:

```ts
// frontend/src/main.ts
import AppLayout from './layouts/AppLayout.vue'
import GuestLayout from './layouts/GuestLayout.vue'

createInertiaApp({
  pages: './pages',
  layout: (name) => (name.startsWith('auth/') ? GuestLayout : AppLayout),
  // title, serverHead, nonce and setup follow
})
```

A layout given this way stays mounted across visits between two pages that
share it; only the page inside it changes. It reads the signed-in user from
the shared `auth.user`, so a guest on the home page sees the sign-in links
rather than a sign-out, and it receives the props a page sets with
`setLayoutProps`:

```vue
<!-- frontend/src/layouts/AppLayout.vue (structure) -->
<script setup lang="ts">
import AccountLinks from '../components/AccountLinks.vue'
import FlashToast from '../components/FlashToast.vue'

defineProps<{
  heading?: string
}>()
</script>

<template>
  <div class="min-h-screen bg-gray-100">
    <!-- the Dashboard and Notes Links for a signed-in user, then: -->
    <AccountLinks />
    <FlashToast />
    <main class="mx-auto max-w-7xl px-4 py-6 sm:px-6 lg:px-8">
      <h1 v-if="heading" class="mb-6 text-2xl font-semibold text-gray-900">{{ heading }}</h1>
      <slot />
    </main>
  </div>
</template>
```

```ts
// frontend/src/pages/Dashboard.vue
setLayoutProps({ heading: 'Dashboard' })
```

The client clears the layout props on every visit that does not preserve
state, so the next page shows no heading unless it sets one.

## Why Suprnova diverges

Laravel's Inertia integration ships one frontend at a time - you pick React,
Vue, or Svelte at install with a single starter kit per project. Suprnova
keeps the same one-per-project rule (you don't mix), but the CLI scaffolds
to all three idiomatically from the same `inertia_response!` call. The Rust
side never knows which frontend is running; the generator and Vite resolver
pick the right extension on disk.

The other divergence is compile-time component validation. Laravel resolves
the component name at runtime, so a typo in `Inertia::render('Dahsboard')`
becomes a production error. Suprnova's `inertia_response!` macro walks
`frontend/src/pages/` at expansion time and fails `cargo check` with a
"Did you mean 'Dashboard'?" suggestion. The full TypeScript type story
(generated from `#[derive(InertiaProps)]` on the Rust struct) means the
component's props are typed end-to-end too.

inertia-laravel can check that a page exists when it renders, against the page
paths and extensions in `config/inertia.php`, and leaves that check off by
default. Suprnova's check always runs, at compile time, so its
lookup lives in `Cargo.toml`, the one configuration a macro can read during
the build. Because `page_file` is a pattern rather than a list of extensions,
it also covers layouts where the file name is not the component name plus an
extension.

## Next

- [Inertia Responses](frontend-inertia-responses.md) - the
  `inertia_response!` macro, partial reloads, deferred props
- [TypeScript Types](frontend-typescript-types.md) - `suprnova generate-types`
  and the typed-props pipeline
- [Frontend Overview](frontend.md) - how the Inertia bridge fits together
- [Inertia CRUD Tutorial](tutorial-inertia-crud.md) - a full Posts resource
  end-to-end
- [Authentication](authentication.md) - wiring the auth pages the starter
  scaffolds for you


---

<!-- /docs/frontend-typescript-types -->

# TypeScript Types

`suprnova generate-types` scans your Rust source for `#[derive(InertiaProps)]`
and `#[derive(Data)]` structs and writes TypeScript declarations the
frontend can import. Run it after you change props or routes; `suprnova
serve` runs it for you on boot unless you pass `--skip-types`.

## What gets generated

Three files, written into `frontend/src/types/`:

| File | Contents |
|---|---|
| `inertia-props.ts` | One `export interface` per prop struct, then the page declarations: `Pages`, `SharedProps`, `Errors`, `PageProps<C>` and, unless the project declares its own (see [Upgrading a project with its own augmentation](#upgrading-a-project-with-its-own-augmentation)), the `@inertiajs/core` augmentation - the file is always written |
| `routes.ts` | A `controllers` object and `routes` named-lookup map derived from `src/routes.rs` - written only with `--routes` |
| `lang-keys.ts` | A `MessageKey` string-literal union of every Fluent message id in the default locale's catalog, fallback parents included - written only when `lang/` yields any ids (see [Message keys](#message-keys)) |

All three start with a header comment marking them auto-generated. Don't
edit them by hand - your changes are overwritten on the next run.

## Running it

```bash
# One-shot
suprnova generate-types

# Re-emit on every Rust file change
suprnova generate-types --watch

# Custom output for the props file
suprnova generate-types --output frontend/src/types/props.ts

# Type wide integers as `number | bigint` (see Type mapping)
suprnova generate-types --big-integers
```

The route file path is fixed at `frontend/src/types/routes.ts` and the
message-key file at `frontend/src/types/lang-keys.ts`; only the props
file path is configurable. The watcher watches `src/` and regenerates the
props file when a `.rs` file is created, written, or deleted; when the
project has a `lang/` directory, it watches that tree too and regenerates
`lang-keys.ts` on the same kinds of change to a `.ftl` file. Reads don't
count - the generator reads every `.rs` file under `src/` on each run, and
treating that as a change would make the watcher regenerate forever. A
burst of saves coalesces into a single run 500 ms after the last write,
so a `cargo fmt` or a branch switch regenerates once, from the finished
tree, rather than once per file from a half-written one.

Every run writes a file only when the emitted content differs from what is
already there. A regeneration that changed nothing reports
`<path> is up to date` and leaves the file, and its timestamp, untouched -
which is what keeps `suprnova serve` from restarting your backend over a
file it decided not to write.

## Page props

The expected shape: one Rust struct per Inertia page, deriving
`InertiaProps`, paired with a page component that types its props off the
generated interface.

```rust
// src/controllers/home.rs
use suprnova::{InertiaProps, Request, Response, inertia_response};

#[derive(InertiaProps)]
pub struct HomeProps {
    pub title: String,
    pub message: String,
    pub count: i64,
    pub tags: Vec<String>,
    pub avatar_url: Option<String>,
}

pub async fn index(req: Request) -> Response {
    inertia_response!(&req, "Home", HomeProps {
        title: "Welcome".into(),
        message: "Hello".into(),
        count: 3,
        tags: vec!["new".into(), "featured".into()],
        avatar_url: None,
    })
}
```

`suprnova generate-types` emits:

```typescript
// frontend/src/types/inertia-props.ts
// This file is auto-generated by Suprnova. Do not edit manually.
// Run `suprnova generate-types` to regenerate.

import '@inertiajs/core';

export interface HomeProps {
  title: string;
  message: string;
  count: number;
  tags: Array<string>;
  avatar_url: string | null;
}

// ...then the page declarations, below
```

Consume it the same way regardless of frontend framework - the
`import type` line is identical across Svelte, React, and Vue:

```svelte
<!-- frontend/src/pages/Home.svelte (the default scaffold) -->
<script lang="ts">
  import type { HomeProps } from '../types/inertia-props'

  let { title, message, count, tags, avatar_url }: HomeProps = $props()
</script>

<h1>{title}</h1>
<p>{message} - {count} items</p>
{#if avatar_url}<img src={avatar_url} alt="" />{/if}
```

See [Page Components](frontend-pages.md) for the React and Vue
equivalents.

## Page types

After the props interfaces, the file maps each page component to the
interface it is rendered with:

```typescript
export interface Pages {
  "Dashboard": DashboardProps;
  "Home": HomeProps;
  "auth/Login": LoginProps;
}

export type Errors = Record<string, string>;

export type PageProps<C extends keyof Pages> = Pages[C] & SharedProps & { errors: Errors };
```

The generator reads the pairs from your handlers. A component gets an
entry when it is rendered with a struct:

- `inertia_response!(&req, "Home", HomeProps { .. })`, or with
  `HomeProps::new(..)` or a unit struct in the props position.
- `InertiaResponse::new("Users/Show")` or
  `Inertia::paginate("Users/Index", "users", page)` with
  `.with_data(UserDto { .. })` or `.try_with_data(..)` anywhere in the same
  chain.
- `Inertia::data("Users/Show", UserDto { .. })` and `Inertia::try_data`.

In any of those positions, a local name counts when the generator can
tell which struct it holds: a `let` or a parameter that declares the type,
or a `let` that builds the struct:

```rust
#[handler]
pub async fn index(req: Request) -> Response {
    let props: HomeProps = load_home(&req);
    inertia_response!(&req, "Home", props)
}

// A parameter typed with the struct counts the same way.
pub async fn render_dashboard(req: &Request, props: DashboardProps) -> Response {
    InertiaResponse::new("Dashboard").with_data(props).resolve(req).await
}
```

The generator follows Rust's scoping: a later `let` of the same name
replaces the earlier one, and a block's names end with the block. A name
it cannot type, such as a `match` arm's binding or `let props = load();`,
leaves the page without an entry.

A field the chain defers or marks optional after it gives the struct is
absent from the first response, so its key is optional in the struct's
interface:

```rust
InertiaResponse::new("Dashboard")
    .with_data(props)
    .defer("stats", move || note_stats(user_id))
    .optional("recent_notes", move || recent_notes(user_id))
```

```typescript
export interface DashboardProps {
  greeting: string;
  stats?: Stats;
  recent_notes?: Array<NoteSummary>;
}
```

`.defer(..)`, `.defer_with(..)` and `.optional(..)` count when the key is a
string literal. A key deferred before `.with_data(..)` is sent with the
struct, so it stays required.

A component rendered with JSON-like props
(`inertia_response!(&req, "About", { "team_size": 4 })`) or only through
`.with(..)` has no entry, and props a chain adds with `.with(..)` beside
the struct are not in the type. A struct that derives only `Serialize`
works too: rendering a page with it emits its interface. A generic struct
gets no entry, since `Pages` would need its type arguments.

Entries are sorted by component name. A component rendered with two
different structs is an error: `generate-types` names both and the files
that render them, exits non-zero, and leaves the file as it was.

`PageProps<'Home'>` is what Inertia hands the `Home` page: its own props,
the shared props and the validation `errors`. Type the page's props with
it in Svelte and React:

```svelte
<!-- frontend/src/pages/Home.svelte -->
<script lang="ts">
  import type { PageProps } from '../types/inertia-props'

  let { title, message, root }: PageProps<'Home'> = $props()
</script>
```

```tsx
// frontend/src/pages/Home.tsx
import type { PageProps } from '../types/inertia-props'

export default function Home({ title, message, root }: PageProps<'Home'>) {
  return <a href={`${root}/about`}>{title}: {message}</a>
}
```

Vue reads a `defineProps` type when it builds the component, and its
compiler cannot resolve the generic `Pages[C]`. Name the entry instead, and
read the shared props through `usePage()`:

```vue
<!-- frontend/src/pages/Home.vue -->
<script setup lang="ts">
import { usePage } from '@inertiajs/vue3'
import type { Pages } from '../types/inertia-props'

defineProps<Pages['Home']>()
const { root } = usePage().props
</script>
```

`PageProps<C>` types a page's props. It is not a type argument for
`usePage`: Inertia requires that argument to have an index signature, and a
generated interface has none. Call `usePage()` without one, as the next
section shows.

## Shared props and the Inertia config

The file ends with the shared props and an augmentation of
`@inertiajs/core`:

```typescript
export interface SharedProps {
  root: string;
}

declare module '@inertiajs/core' {
  export interface InertiaConfig {
    sharedPageProps: SharedProps;
    errorValueType: string;
  }
}
```

`SharedProps` always holds `root`, the public root the framework's
`RootShare` gives every page (see [Frontend Overview](frontend.md)). Its
other fields come from one struct: the one marked
`#[inertia_props(shared)]`, or the `#[derive(Data)]` struct you hand to
`Inertia::share_data`:

```rust
use suprnova::InertiaProps;

#[derive(InertiaProps)]
#[inertia_props(shared)]
pub struct AppShared {
    pub app_name: String,
    pub user_id: Option<u64>,
}
```

```typescript
export interface SharedProps {
  root: string;
  app_name: string;
  user_id: number | null;
}
```

The shared marker tells the generator which struct it is; sharing the values
at run time stays your bootstrap's job. A lazy field of a shared `Data`
object is left out, as `Inertia::share_data` leaves it out. Per-key shares
(`Inertia::share("appName", "Suprnova")`) and shared-data providers such
as `LocaleShare` are not typed: the generator sees a key and a value
expression, not a declared shape. They reach `usePage().props` as
`unknown`; move them into the shared struct to type them.

`#[inertia_props(flash)]` marks the struct of your flash data, and the
augmentation names it as Inertia's `flashDataType`:

```rust
#[derive(InertiaProps)]
#[inertia_props(flash)]
pub struct Toast {
    pub message: String,
}
```

```typescript
    flashDataType: Toast;
```

Without a flash struct, Inertia's own flash type applies. Two structs for
the shared props, or two for the flash data, is an error that names both.
The markers go on an `InertiaProps` struct only, once, and one struct
cannot carry both: anything else fails the build.

The augmentation merges into `@inertiajs/core`'s `InertiaConfig`, so
`usePage()` is typed with no argument in every adapter:

```ts
import { usePage } from '@inertiajs/svelte'   // or /react, /vue3

const { root } = usePage().props               // root: string
```

`errorValueType: string` types each validation error as the one message
per field that Suprnova sends by default. With
`InertiaConfig::with_all_errors(true)`, a field carries every message as an
array, and the generator types it that way: when any `.rs` file under
`src/` calls `with_all_errors(..)` with anything but a literal `false`,
`Errors` is `Record<string, string[]>` and `errorValueType` is `string[]`:

```rust
// src/bootstrap.rs: every field's errors become `string[]`
Inertia::install(&InertiaConfig::new().with_all_errors(true))?;
```

```typescript
export type Errors = Record<string, string[]>;

declare module '@inertiajs/core' {
  export interface InertiaConfig {
    sharedPageProps: SharedProps;
    errorValueType: string[];
  }
}
```

The call is read the way `preserve_big_integers(..)` is (see "Wide
integers" below): `true` or a variable turns it on, and `false`, in
parentheses or not, leaves `string`.

The starter kits declare `@inertiajs/core` in `package.json`, since the
augmentation names it, and their `tsconfig.json` includes `src/types/`, so
the augmentation is part of every type check. The file declares `Pages`,
`SharedProps`, `Errors` and `PageProps`, so a project struct with one of
those names is an error: rename the struct.

### Upgrading a project with its own augmentation

A project that typed `usePage()` before the generator did has its own
`declare module '@inertiajs/core'` block, often in
`frontend/src/global.d.ts`. The generator does not write a second one
beside it: two augmentations merge key by key, and a key both set to
different types fails the type check. When a `.ts`, `.tsx`, `.mts` or
`.cts` file under `frontend/src` (declaration files such as `.d.ts`
included), other than the generated file itself, declares
`module '@inertiajs/core'` (in single or double quotes), `inertia-props.ts`
keeps `Pages`, `SharedProps`, `Errors` and `PageProps` and writes no
augmentation and no `import '@inertiajs/core'`. `generate-types` says so,
naming the file:

```text
→ frontend/src/global.d.ts declares module '@inertiajs/core', so the project's own augmentation types usePage() and the generated types add none; remove that declaration to use the generated one
```

`serve` prints the same line once, at start-up, and a regeneration on save
repeats it only when another file declares the module. A `.vue` or
`.svelte` script block is not read: an ambient module declaration belongs
in a TypeScript file. A declaration inside a comment or a string does not
count, so a commented-out `// declare module '@inertiajs/core' {}` leaves
the generated augmentation in place. A TypeScript file under
`frontend/src` that cannot be read stops the generation with its path, as
an unreadable Rust source does, since it may hold the declaration.

You can go either way:

- Keep the hand-written block. It types `usePage()` as it did, and the
  generator stays out of its way; keep it in step with the server
  yourself, `errorValueType` included.
- Delete the block, or the file when it holds nothing else, and run
  `suprnova generate-types`. The generated augmentation then types
  `usePage()` with `root`, the shared struct's fields and the errors the
  server sends.

## Type mapping

| Rust | TypeScript | Notes |
|---|---|---|
| `String`, `&str` | `string` | |
| `i8`, `i16`, `i32`, `u8`, `u16`, `u32`, `f32`, `f64` | `number` | |
| `i64`, `u64`, `i128`, `u128`, `isize`, `usize` | `number`, or `number \| bigint` when the project preserves big integers | See "Wide integers" below. As a map key, always `number` |
| `bool` | `boolean` | |
| `Option<T>` | `T \| null` | |
| `Vec<T>` | `Array<T>` | The props generator emits `Array<T>`; the routes generator emits `T[]` for form-request fields |
| `HashMap<K, V>`, `BTreeMap<K, V>` | `Record<K, V>` | |
| `serde_json::Value` | `JsonValue` | A recursive alias the generator declares once at the top of the file, and only when something references it. A bare `Value` maps here too, unless the project defines its own `Value` struct - that one wins |
| `Field<T>` (from `#[derive(Data)]`) | `field?: T \| null` | Field is optional on the wire |
| `Prop<T>` (lazy / deferred) | `field?: T` | Lazy props omit the `null` half |
| `chrono::DateTime<Tz>`, `NaiveDate`, `NaiveDateTime`, `NaiveTime` | `string` | chrono serializes them as ISO 8601 text |
| A struct with named fields the project defines | its interface, by name | Derived or not; see "Custom types" below |
| Anything else | `unknown` | An external type, an enum or a tuple struct; `generate-types` warns. See "Custom types" below |

### Wide integers

A wide integer can pass 2^53, the largest integer a JavaScript `number`
holds exactly. With big-integer preservation on, the server sends such a
value as a `{"$bigint": "..."}` marker and the Inertia client turns it
into a `BigInt`. So the generator types `i64`, `u64`, `i128`, `u128`,
`isize` and `usize` as `number | bigint` when any `.rs` file under `src/`
calls `preserve_big_integers(..)` with anything but a literal `false`,
such as `true` or a variable, and as `number` otherwise:

```rust
// src/bootstrap.rs: every wide integer field becomes `number | bigint`
Inertia::install(&InertiaConfig::new().preserve_big_integers(true))?;
```

A literal `false` turns nothing on, in parentheses too: `(false)` is still
`false`.

A map key stays `number`: a JSON object key is a string on the wire,
never a marker, and TypeScript refuses `bigint` as a `Record` key.

When the call sits where the scan does not read, such as another crate,
pass `--big-integers`. Pass it to `suprnova serve` as well: its start-up
generation and every regeneration on save then type the wide integers the
same way.

## Custom types

The visitor recognises the primitives in the table above and chrono's
date and time types. Any other type name resolves one of two ways.

**A struct your project defines gets its own interface, derived or not.**
A nested struct that only derives `Serialize` is emitted as soon as a prop
reaches it, directly or through another struct, under the keys serde
writes:

```rust
use serde::Serialize;
use suprnova::{Data, InertiaProps};

#[derive(Serialize)]
pub struct Address {  // no InertiaProps or Data derive: picked up anyway
    pub street: String,
    pub city: String,
}

#[derive(Data)]
pub struct Company {
    pub name: String,
    pub address: Address,
}

#[derive(InertiaProps)]
pub struct ProfileProps {
    pub user_name: String,
    pub company: Company,
}
```

Generated output:

```typescript
export interface ProfileProps {
  user_name: string;
  company: Company;
}

export interface Company {
  name: string;
  address: Address;
}

export interface Address {
  street: string;
  city: string;
}
```

A struct that no prop reaches stays out of the file. Only a struct with
named fields counts: an enum or a tuple struct of your own has no shape the
generator can write, and falls under the next rule.

**chrono's types are strings, and any other external type is `unknown`.**
chrono serializes `DateTime<Tz>`, `NaiveDate`, `NaiveDateTime` and
`NaiveTime` as ISO 8601 text, so they emit as `string`. A type the
generator cannot see - `uuid::Uuid`, `rust_decimal::Decimal`, any other
crate's type, your own enum or tuple struct - emits as `unknown`, so the
file never names a type it does not declare, and `generate-types` warns
once per type:

```rust
#[derive(InertiaProps)]
pub struct EventProps {
    pub starts_at: chrono::DateTime<chrono::Utc>,
    pub day: chrono::NaiveDate,
    pub id: uuid::Uuid,
    pub price: rust_decimal::Decimal,
}
```

```typescript
export interface EventProps {
  starts_at: string;
  day: string;
  id: unknown;
  price: unknown;
}
```

```
⚠ Prop type `Uuid` (referenced by `EventProps.id`) isn't a struct this project defines - emitting `unknown`. ...
```

`unknown` makes the frontend check the value before it uses it. When the
value travels as a string anyway, as a `Uuid` does, make the prop field a
`String` (`id: event.id.to_string()`) and it is typed `string`. For a
shape of its own, mirror it as a struct with named fields in your project.

## Generic structs

A generic Rust struct becomes a generic TypeScript interface:

```rust
use suprnova::{Data, data::Field};

#[derive(Data)]
pub struct Paginated<T>
where
    T: serde::Serialize + for<'de> serde::Deserialize<'de>,
{
    pub items: Vec<T>,
    pub total: usize,
    pub cursor: Field<String>,
}
```

```typescript
export interface Paginated<T> {
  items: Array<T>;
  total: number;
  cursor?: string | null;
}
```

The `where` clause is dropped - TypeScript generics are unconstrained
unless you say otherwise on the consuming side.

## Split input/output interfaces

When a `#[derive(Data)]` struct mixes `#[data(input_only)]`,
`#[data(output_only)]`, or `#[data(lazy)]` fields, two interfaces are
emitted - the output shape (what the frontend receives) and an `<Name>Input`
counterpart (what it sends back):

```rust
use suprnova::Data;
use suprnova::data::Field;
use suprnova::inertia::Prop;
use validator::Validate;

#[derive(Data, Validate)]
pub struct UserDto {
    pub id: i64,
    pub name: String,

    #[data(input_only)]
    #[validate(length(min = 8))]
    pub password: String,

    #[data(output_only)]
    pub computed_handle: String,

    pub bio: Field<String>,

    #[data(lazy)]
    pub favorite_song: Prop<String>,
}
```

Emits both:

```typescript
export interface UserDto {              // server -> client
  id: number;
  name: string;
  computed_handle: string;
  bio?: string | null;
  favorite_song?: string;
}

export interface UserDtoInput {         // client -> server
  id: number;
  name: string;
  password: string;
  bio?: string | null;
}
```

`Prop` fields are output-only by nature, so they're stripped from the
input type even when `lazy` isn't explicit. For the full set of `#[data(...)]`
flags and their authoring semantics, see [Data](data.md).

## Type-safe routes

With `--routes`, the command writes a second file,
`frontend/src/types/routes.ts`, generated from `src/routes.rs`. It exposes a `controllers` object whose
method shapes mirror your backend module tree, plus a `routes` lookup
keyed by `.name(...)`:

```rust
// src/routes.rs
use suprnova::routes;

routes! {
    get!("/", controllers::home::index).name("home"),
    get!("/users", controllers::user::index).name("users.index"),
    get!("/users/{id}", controllers::user::show).name("users.show"),
    post!("/users", controllers::user::store).name("users.store"),
}
```

```typescript
// frontend/src/types/routes.ts
import type { Method } from '@inertiajs/core';

export interface RouteConfig<TData = void> {
  url: string;
  method: Method;
  data?: TData;
  component?: string;
}

export interface UserShowParams {
  id: string;
}

export const controllers = {
  home: {
    index: (): RouteConfig => ({ url: '/', method: 'get', component: 'Home' }),
  },
  user: {
    index: (): RouteConfig => ({ url: '/users', method: 'get', component: 'Users/Index' }),
    show: (params: UserShowParams): RouteConfig =>
      ({ url: `/users/${encodeURIComponent(String(params.id))}`, method: 'get', component: 'Users/Show' }),
    store: (): RouteConfig => ({ url: '/users', method: 'post' }),
  },
} as const;

export const routes = {
  'home': controllers.home.index,
  'users.index': controllers.user.index,
  'users.show': controllers.user.show,
  'users.store': controllers.user.store,
} as const;
```

`RouteConfig` is intentionally shaped to satisfy Inertia 3's
`UrlMethodPair` interface, so it slots into `router.visit`, `useForm`'s
`submit`, and `<Link href={...}>` without an adapter:

```ts
import { router } from '@inertiajs/svelte'   // or /react, /vue
import { controllers, routes } from '../types/routes'

router.visit(controllers.home.index())
router.visit(controllers.user.show({ id: '42' }))
router.visit(routes['users.show']({ id: '42' }))
```

If a path has params (`/users/{id}`), the generated function requires the
typed `Params` object - TypeScript catches missing or misspelled keys at
compile time.

A helper carries `component` when its route renders one page the
generator can name: the handler's body names exactly one component, as a
string literal in `inertia_response!`, `InertiaResponse::new`,
`Inertia::data`, `Inertia::try_data` or `Inertia::paginate`, or the route
is a `Router::inertia(path, component, props)` route. That is Inertia's
`UrlMethodPair.component`, which instant visits use: `<Link href={...}
instant>` and `<Form action={...} instant>` render that page at once with
the current shared props and fill in the page's own props when the
response arrives. A plain `router.visit` ignores it. A handler that names
no component, several, or one it computes at run time gets no
`component`, and an instant visit through its helper falls back to an
ordinary one.

A `Router::inertia` route has no controller, so its helper sits under
`controllers.inertia`, keyed by its path (`/about` is
`controllers.inertia.about`, `/` is `controllers.inertia.index`), and its
`.name(..)` reaches it through `routes` like any other.

A handler inside an `impl` block is read like a free function. For
`#[handler(Self = Posts)]` on `index` inside `impl Posts`, registered as
`get!("/users", controllers::posts::Posts::index)`, the generator reads
the method from `impl Posts` in the file of `controllers::posts`, for its
request type and its component alike. A free `index` in the same file
keeps its own helper. The method's helper sits under the type's name,
`controllers.Posts.index`.

The helpers build the same URLs the backend's `route()` helper builds:

- Each parameter value is percent-encoded as one path segment. A slug of
  `a/b` becomes `/posts/a%2Fb` and reaches the handler as `a/b`, and a `?`
  or `#` in a value cannot start a query string or a fragment.
- A catch-all parameter (`{*rest}`) is named `rest` and keeps its slashes.
  Each segment is encoded on its own.
- An optional parameter (`{year?}`) is an optional key. Without a value it
  is left out with its segment, so `/archive/{year?}` with no year is
  `/archive`. A helper whose parameters are all optional can be called with
  no argument.
- A route inside `group!` gets the group's path prefix and its `.name(...)`
  prefix, nested groups included. A bare handler name inside
  `group!(..., controller = ..., { ... })` resolves to that controller.
- A request type's interface uses the keys serde reads, so `rename`,
  `rename_all` and `skip_deserializing` apply.
- When two routes share one handler, the second gets its own helper key, and
  its entry in `routes` points at that helper.

## Message keys

If the app has a `lang/` catalog tree, the generator also writes
`frontend/src/types/lang-keys.ts`: a `MessageKey` string-literal union
of every Fluent message id the frontend can resolve. The starter kits
ship no translations, catalog tree or `lang-keys.ts`. If you add catalogs
and a browser translation helper, you can type its key argument as
`MessageKey` so a misspelled or deleted key is a TypeScript error.

The ids come from `lang/<APP_LOCALE>/*.ftl`, unioned across the
locale's configured fallback parents (`APP_LOCALE_PARENTS`) - so a
delta-style catalog that holds only the strings it overrides still
generates the full key set the served, chain-flattened catalog
carries. `APP_FALLBACK_LOCALE` is deliberately *not* included: the
served catalog doesn't flatten the terminal fallback either, and the
union must describe exactly what the browser's one fetched catalog can
resolve. See [Localization](localization.md) for the chain itself.

The file follows the same rules as the other two: fixed path,
auto-generated header, deterministic sorted output, never hand-edited.
When no `.ftl` file yields any id, the file is removed rather than
emitted empty - application code importing `MessageKey` then fails to
compile until the catalog has ids again, like every other drift in this
pipeline.

## When it runs

`suprnova serve` triggers `generate-types` on boot. The default flow:

```
suprnova serve
  ├─ scan src/ for InertiaProps / Data structs        → inertia-props.ts
  ├─ scan src/routes.rs for route definitions         → routes.ts
  ├─ scan lang/ for Fluent message ids                → lang-keys.ts
  ├─ start the backend
  └─ start Vite
```

Pass `--skip-types` to skip both. Re-run `suprnova generate-types`
manually any time you change Rust code while the backend is hot-reloading
and you want fresh declarations without restarting the server.

### Commit the output, and expect a clean diff

`inertia-props.ts` is meant to be checked in - that is what lets a
reviewer see a prop contract change in the same diff as the Rust that
caused it, and what stops CI needing a Rust toolchain to typecheck the
frontend.

Generation is deterministic: the same source produces byte-identical
output, on any machine, in any order the files happen to sit on disk. So
a run that changes nothing shows no diff, and any diff you do see is a
real contract change. (It was not always so - the sort seeded itself from
hash iteration order, and every run reshuffled the interfaces.)

Two consequences worth internalising:

- **Nothing else may edit that file.** If a component imports a type the
  generator does not emit, the next `generate-types` deletes it and the
  frontend stops compiling. The fix is to declare the type in Rust, not
  to hand-edit the output.
- **A page with no Rust route has no generated type**, because there is
  no `#[derive(InertiaProps)]` struct behind it. Declare its props
  locally in the component until a handler exists to own them.

## Why Suprnova diverges

Laravel doesn't ship type generation for Inertia because PHP is dynamically
typed - there's nothing on the server side to extract a contract from.
Inertia's Laravel community filled the gap with userland tools (Laravel
Typed Inertia, Wayfinder) that read PHPDoc or DocBlock annotations.

Suprnova has the type information at compile time and on disk, so we
extract it directly. The same `#[derive(InertiaProps)]` or `#[derive(Data)]`
that controls JSON serialisation also drives the TypeScript output - one
source of truth, never out of sync with what serde actually emits.

Inertia types `usePage()` through a `declare module '@inertiajs/core'`
block you write by hand, in a `global.d.ts`, and keep in step with the
server. Suprnova generates that block into `inertia-props.ts`, from the
struct your handlers share and the struct you mark as flash data, so the
shared props cannot drift from the server either. A project that already
has a hand-written block keeps it, and the generator steps aside: it
writes no augmentation of its own, since the two would merge and a key
both set to different types is a type error (see [Upgrading a project with
its own augmentation](#upgrading-a-project-with-its-own-augmentation)).

## Cache declarations

`#[inertia(cacheable)]` adds runtime cache meaning to an `InertiaProps`
struct. Every field must carry `#[inertia(public)]` or
`#[inertia(per_request)]`. A missing marker fails the build and names the
field. These markers belong on fields. They accept no list of field names.
An ordinary props struct keeps its existing serialization behavior.

```rust
use suprnova::InertiaProps;

#[derive(InertiaProps)]
#[inertia(cacheable)]
pub struct ArticleProps {
    #[inertia(public)]
    pub title: String,
    #[inertia(per_request)]
    pub viewer_name: String,
}
```

Register the page and its shared props at boot as shown in
[Inertia responses](frontend-inertia-responses.md). Then run:

```bash
suprnova generate-types
```

For a page named `Articles/Show`, `inertia-props.ts` includes:

```typescript
export const inertiaPropCache = {
  "Articles/Show": { cacheable: true, public: ["title"], perRequest: ["viewer_name"] },
} as const;
```

The record uses component names and serialized field names, including serde
renames. Components and field lists sort by name. Every typed page has a
record. An ordinary page has `cacheable: false` and two empty lists. Those
empty lists make no claim about its prop privacy. The record describes page
fields. Shared-prop declarations stay in the server's route registration.
React, Vue and Svelte receive the same record. Generic cacheable structs
also have a boundary record. Their field names do not depend on type
arguments; the existing generic limitation of `Pages` still applies.

```typescript
import { inertiaPropCache } from './types/inertia-props';

console.log(inertiaPropCache["Articles/Show"].perRequest);
```

### Why Suprnova diverges

Laravel has no shared page cache with checked request slots. Suprnova emits
these declarations so frontend tools can read the same field boundary that
the Rust derive checks. The generated record does not authorize caching.
[RenderCache](render-cache.md) still checks the route and its observations.

## Next

- [Frontend Overview](frontend.md) - Inertia, page components, dev server
- [Page Components](frontend-pages.md) - Svelte 5, React 19, and Vue 3.5
  consumption patterns
- [Data](data.md) - the authoring side of `#[derive(Data)]`,
  `#[data(...)]` flags, `Field<T>`, and `Prop<T>`
- [Requests](requests.md) - typed request bodies and validation
- [Localization](localization.md) - the Fluent catalogs and fallback
  chains behind `lang-keys.ts`
- [CLI Generators](cli-generators.md) - every `suprnova make:*` and
  `generate-*` command


# CLI Reference

---

<!-- /docs/cli -->

# CLI Overview

Suprnova ships two binaries with different jobs. The global `suprnova` -
installed once into `~/.cargo/bin` - scaffolds new projects, generates code,
boots dev servers, and runs migrations. The per-project `console`, built
from each app's `src/bin/console.rs`, runs runtime commands that need the
app's compiled types (seeders, pruners, your own `#[command]` handlers).
This chapter is the map; each subcommand has its own deep-dive in the
sibling chapters listed under [Next](#next).

## Install

The CLI is distributed via `cargo install --git`. Suprnova is
distributed through git tags, not crates.io - see [Distribution
model](installation.md#distribution-model).

```bash
cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.6.2 suprnova-cli
suprnova --version
```

To upgrade later, pass `--force`:

```bash
cargo install --force --git https://github.com/eas4ai/suprnova.git --tag v4.6.2 suprnova-cli
```

## The two binaries

| Binary | Built from | Used for |
|---|---|---|
| `suprnova` | `suprnova-cli/` (this crate) | Scaffolding (`new`), generators (`make:*`), dev runner (`serve`), migrations (`migrate*`, `db:sync`), Docker config (`docker:*`), SSR worker (`ssr:*`), key minting (`key:generate`), type generation (`generate-types`), and forwards to the `console` binary for `db:seed` and `model:prune` |
| `console` | `src/bin/console.rs` in your project | Runtime commands that link your app's types - built-in `db:seed` and `model:prune` plus every `#[command]` / `#[derive(Command)]` you define |

Worker daemons (`schedule:run`, `schedule:work`, `schedule:list`,
`workflow:work`, `queue:work`) sit on a third surface: your *app* binary's
own clap parser, the same binary that serves HTTP. The global `suprnova`
shells into `cargo run --quiet -- <name>` for those so you can launch them
from the CLI you already have open. See [Console](console.md) for the full
three-way split.

### Why Suprnova diverges

Laravel solves this with a single per-project script - `php artisan` -
because PHP loads framework and user code together at runtime. Rust links
binaries at compile time, so a global `suprnova` binary can't statically
see your seeders, factories, or `#[command]` handlers. The pragmatic split:

- File-only work (scaffolding, generators, ops) lives on the global
  `suprnova` binary
- Runtime work that needs your compiled types lives on the per-project
  `console` binary
- Daemons live on your app/server binary so they share the same boot path
  as `serve`

You get the ergonomics of `php artisan` (`cargo run --bin console -- db:seed`
or `console <name>` directly) without the static-linking lie.

## Commands at a glance

The same list `suprnova --help` prints, grouped the same way.

### Create

| Command | Description |
|---|---|
| `suprnova new [name]` | Scaffold a new project. See [`suprnova new`](cli-new.md). |
| `suprnova serve` | Boot backend + Vite together with hot reload. See [`suprnova serve`](cli-serve.md). |
| `suprnova dev:tls` | Trust portless's CA and register a `https://<name>.localhost` dev URL. See [HTTPS Dev URLs](dev-tls.md). |
| `suprnova web:run` | Run the app binary directly (no Vite, no rebuild loop). Production-shaped local run. |

### Generate

| Command | Description |
|---|---|
| `suprnova make:controller <name>` | Scaffold a controller in `src/controllers/`. |
| `suprnova make:action <name>` | Scaffold an invokable action in `src/actions/`. |
| `suprnova make:middleware <name>` | Scaffold a middleware in `src/middleware/`. |
| `suprnova make:migration <name>` | Scaffold a SeaORM migration in `src/migrations/`. |
| `suprnova make:inertia <name>` | Scaffold an Inertia page in `frontend/src/pages/`. Pass `--data` for a `#[derive(Data, Validate)]` props struct in `src/props/` instead. |
| `suprnova make:error <name>` | Scaffold a domain error in `src/errors/`. |
| `suprnova make:task <name>` | Scaffold a scheduled task in `src/tasks/`. |
| `suprnova make:command <name>` | Scaffold a `#[derive(Command)]` console command in `src/commands/`. |
| `suprnova make:factory <name>` | Scaffold a model factory in `src/factories/`. `--model` names the model. |
| `suprnova make:seeder <name>` | Scaffold a database seeder in `src/seeders/`. |
| `suprnova make:cast <name>` | Scaffold a custom attribute cast in `src/casts/`. |
| `suprnova make:channel <name>` | Scaffold a private broadcast channel in `src/broadcasting/`. |
| `suprnova make:class <name>` | Scaffold a plain struct in `src/`. |
| `suprnova make:enum <name>` | Scaffold an enum in `src/enums/`. |
| `suprnova make:event <name>` | Scaffold an event in `src/events/`. |
| `suprnova make:listener <name>` | Scaffold an event listener in `src/listeners/`. `--event` names the event. |
| `suprnova make:job <name>` | Scaffold a queued job in `src/jobs/`. |
| `suprnova make:job-middleware <name>` | Scaffold job middleware in `src/jobs/middleware/`. |
| `suprnova make:mail <name>` | Scaffold a mailable in `src/mail/`. |
| `suprnova make:notification <name>` | Scaffold a notification in `src/notifications/`. |
| `suprnova make:observer <name>` | Scaffold a model observer in `src/observers/`. `--model` names the model. |
| `suprnova make:policy <name>` | Scaffold a `#[policy]` in `src/policies/`. `--model` names the model. |
| `suprnova make:provider <name>` | Scaffold a service registration the bootstrap calls in `src/providers/`. |
| `suprnova make:resource <name>` | Scaffold a JSON:API resource in `src/resources/`. |
| `suprnova make:rule <name>` | Scaffold a validation rule in `src/rules/`. |
| `suprnova make:scope <name>` | Scaffold a global query scope in `src/scopes/`. `--model` names the model. |
| `suprnova make:test <name>` | Scaffold an integration test in `tests/`. |
| `suprnova make:trait <name>` | Scaffold a trait with a default method in `src/concerns/`. |
| `suprnova make:interface <name>` | Scaffold a trait with required methods in `src/contracts/`. |
| `suprnova generate-types` | Emit TypeScript types from every `#[derive(InertiaProps)]` struct. `-o <path>` to override output, `-w` to watch and regenerate. |

See [Generators](cli-generators.md) for the full scaffold details and what
each generated file looks like.

### Live

| Command | Description |
|---|---|
| `suprnova live:make <name>` | Scaffold a Live component in `src/live/`, its view in `templates/live/`, and its registration in `src/live/mod.rs`. Never overwrites; `--dry-run` reports the plan. |
| `suprnova live:add <component>` | Install a Live component: a shipped name (`field`), a library address (`[<host>/]<owner>/<library>/<component>[@<version>]`), an `https://` URL of a component directory, or a `./path` to one (`--manifest <path>` too). Verifies a third-party component's signature against the key `suprnova.toml` pins, scans every file without running it, shows the plan, and asks before it writes; records the install in `suprnova.toml`. `--allow <capability>` approves a capability, `--yes` confirms the plan without a terminal (never a capability or a key), `--force` replaces edited files and accepts a downgrade or a changed release, `--dry-run` reports the plan and writes nothing. See [Installing Live Components](live-add.md). |
| `suprnova live:registry new <namespace> --source <library address>` | Scaffold a component library in `./<namespace>`: `library.json`, an example component, a `preview/` application, and a signing key written to your configuration directory. `--source` is required: the address the library will be published at, which every signature covers. See [Live Component Libraries](live-libraries.md). |
| `suprnova live:registry check` | From a library's root, check every component as `live:add` would and list each component's capabilities. |
| `suprnova live:registry sign` | From a library's root, check every component, then sign each one, all or nothing. Reads the key from `SUPRNOVA_LIBRARY_KEY` when set, else from your configuration directory. |
| `suprnova live:registry rotate-key` | From a library's root, move the library to a new signing key: make the key pair, write the new private key to your configuration directory, set `library.json`'s `publicKey`, rewrite `previousKeys` as one handover per former key, each signed by that key and naming the new one, raise the patch version (a rotation changes every component's signed content, and `live:add` refuses changed content at a recorded version), and sign every component again with the new key, all or nothing. Refuses when a former key's file is missing; `--drop-key <fingerprint>` leaves that key's handover out. Prints both fingerprints and the new key's path. Reads the current key as `sign` does. |
| `suprnova live:wait [-- <cargo args>]` | Wait until no `live:add` holds the project lock, restoring an interrupted install first. Given cargo arguments after `--`, run that cargo command, holding a shared lock until its build finishes so no install starts mid-build. `suprnova serve` builds this way. |
| `suprnova live:check` | Verify every third-party component `suprnova.toml` records against its pinned key, offline, then check every registered Live view with the integrated checker. Reads `askama.toml` `dirs` or `templates/`; `--templates <dir>` overrides, `--allow-unproved` accepts unproved dynamic structures. |
| `suprnova live:inspect` | Report safe Live runtime, registry, provider, and artifact state (`--json` for one JSON document). |
| `suprnova live:assets --out <dir>` | Publish the reviewed Live runtime artifacts to `<dir>/<identity>/`, atomically; `--replace` replaces a publication whose bytes differ. |

`live:add` and `live:registry` start no process: nothing a component
carries runs while they fetch, check, sign or install it.

`live:check`, `live:inspect`, and `live:assets` run inside your application:
the CLI starts `cargo run --bin console` and reads a bounded, versioned
JSON-lines report from the framework's hidden tooling helper, so it never
needs a framework dependency of its own. Build output stays on stderr;
anything unexpected on stdout fails the command closed.

### Database

| Command | Description |
|---|---|
| `suprnova migrate` | Run all pending migrations. |
| `suprnova migrate:status` | Show which migrations are applied vs pending. |
| `suprnova migrate:rollback [--step N]` | Roll back the last N migrations (default 1). |
| `suprnova migrate:fresh [--force]` | Drop every table and re-run all migrations. **Destructive.** In production it needs `--force` plus a typed confirmation on an interactive terminal. |
| `suprnova db:sync [--skip-migrations] [--regenerate-models]` | Run migrations and regenerate SeaORM entities from the live schema. `--regenerate-models` overwrites custom model files in `src/models/`. |
| `suprnova db:seed [<seeder>]` | Run every registered seeder, or the one named. `--class=<seeder>` names it as an option; you cannot pass both. |
| `suprnova model:prune [--model <Name>] [--pretend]` | Delete the rows that `Prunable` and `MassPrunable` models select for removal. `--model` prunes one model, named by its type name; a name that no registered pruner has prints `model:prune: no pruner registered for` the name on the error stream and exits 0. `--pretend` reports the row count and deletes nothing. |

`db:seed` and `model:prune` run your project's `console` binary
(`cargo run --quiet --bin console -- <name>`), because the seeder and model
registries are compiled into your crate. The CLI checks no name: the console
binary knows which seeders and models exist, and it reports an unknown one.
You can also run them directly, for example
`cargo run --bin console -- db:seed` or `./target/debug/console db:seed`.
See [Console](console.md) for the registration pattern.

See [Migrations chapter](cli-migrations.md) for the full migration workflow.

### Schedule

| Command | Description |
|---|---|
| `suprnova schedule:run` | Run every due task once. The cron-friendly form. |
| `suprnova schedule:work` | Foreground daemon that checks every minute and runs due tasks. |
| `suprnova schedule:list [--timezone <zone>]` | Print every registered task with its cron expression. `--timezone` names the IANA zone the listing is read in (default UTC). |

Each of these shells into `cargo run --quiet -- <name>` against your
app/server binary - the same binary that serves HTTP - so registered tasks
and bootstrapped services are visible. See [Scheduling
CLI](cli-scheduling.md) and the [Scheduling](scheduling.md) chapter.

### Workflow

| Command | Description |
|---|---|
| `suprnova workflow:work` | Start the workflow worker daemon. Pulls workflow steps off the registry and runs them with the same panic boundary as HTTP handlers. |
| `suprnova workflow:install` | Drop the workflow + workflow_steps migrations into `src/migrations/`. Already present in fresh scaffolds. |

See [Workflows](workflows.md).

### SSR

| Command | Description |
|---|---|
| `suprnova ssr:start [--runtime node\|bun\|deno\|<path>]` | Run the application binary's `ssr:start`, which checks the installed Inertia configuration and runs the SSR worker in the foreground. `--runtime` replaces the configured runtime. Ctrl-C, `Ctrl-\`, Ctrl-Z, `fg`, `SIGTERM`, and `SIGHUP` reach the application, which runs in a process group of its own, through the CLI. |
| `suprnova ssr:stop [--graceful]` | Run the application binary's `ssr:stop`, which sends `GET /shutdown` to the worker at the configured URL. With `--graceful`, a worker that isn't running counts as stopped. |
| `suprnova ssr:check` | Run the application binary's `ssr:check`, which asks the installed SSR gateway's health check. |

Each of these runs `cargo run --bin <app> -- <name>` from the project
directory, the way `serve` runs the backend, and exits with the
application's status. The CLI reads no SSR settings of its own: the
configuration your application passes to `Inertia::install` decides what
each command checks and does, as [Console](console.md#ssr-commands)
describes.

See [Inertia SSR](frontend.md) for the production setup.

### Deploy

| Command | Description |
|---|---|
| `suprnova docker:init` | Emit a multi-stage production `Dockerfile` + `.dockerignore`. |
| `suprnova docker:compose [--with-mailpit] [--with-minio]` | Emit a `docker-compose.yml` for local development. Postgres + Redis always included; Mailpit and MinIO opt in. |

See [Docker](cli-docker.md) and the [Deployment](deployment.md) chapter.

### Security

| Command | Description |
|---|---|
| `suprnova key:generate [--show]` | Mint a 32-byte AES-256 key, base64 URL-safe no padding (same wire format `EncryptionKey::to_base64` produces). `--show` prints just the key for `APP_KEY=$(suprnova key:generate --show)`. |

See [Encryption](encryption.md) for what `APP_KEY` protects and how
rotation via `APP_KEY_PREVIOUS` works.

## Quick start

The most common path from "nothing installed" to "running app":

```bash
# 1. Install the CLI
cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.6.2 suprnova-cli

# 2. Scaffold a project (interactive - picks Svelte by default)
suprnova new my-app

# 3. Boot it
cd my-app
suprnova migrate
npm install
suprnova serve
```

Non-interactive scaffold (CI, scripted setup):

```bash
suprnova new my-app \
  --frontend svelte \
  --no-interaction \
  --no-git
```

API-only scaffold (no Inertia, no SPA):

```bash
suprnova new my-api --api
```

Generate code in an existing project:

```bash
suprnova make:controller Posts
suprnova make:migration create_posts_table
suprnova make:command reports:daily   # registers under the per-project console binary
suprnova migrate
```

## Getting help

`--help` (or `-h`) works on any subcommand. The top-level help is
hand-formatted (`ui::print_help`) and groups commands by section; the
per-subcommand help comes from clap and shows every flag with its default:

```bash
suprnova --help
suprnova new --help
suprnova serve --help
suprnova make:inertia --help
```

For the per-project `console` binary:

```bash
cargo run --bin console -- --help
cargo run --bin console -- db:seed --help
cargo run --bin console -- <your-command> --help
```

`--version` prints the version on its own line, which is what you want
when reporting a bug or checking whether an install took:

```bash
suprnova --version
# suprnova 4.6.2
```

Both `-v` and `-V` are accepted. Clap's generated flag offers only `-V`;
this one is hand-declared so the lowercase spelling - the one most people
try first - works too. The version also appears in the `--help` banner,
which is where it lived before the flag existed.

## Next

- [`suprnova new`](cli-new.md) - every flag the scaffolder accepts and the
  directory layout it produces
- [`suprnova serve`](cli-serve.md) - the dev runner: backend + Vite + type
  generation
- [Generators](cli-generators.md) - the full `make:*` family with output
  templates
- [Migrations CLI](cli-migrations.md) - `migrate`, `migrate:fresh`,
  `db:sync`, and the SeaORM workflow
- [Console](console.md) - the per-project `console` binary, `#[command]`,
  `#[derive(Command)]`, and the three-binary asymmetry
- [Installing Live Components](live-add.md) - `live:add`, its plan, and
  the record in `suprnova.toml`
- [Live Component Libraries](live-libraries.md) - `live:registry new`,
  `check`, `sign` and `rotate-key`


---

<!-- /docs/cli-new -->

# suprnova new

`suprnova new` scaffolds a Suprnova project - a fresh Cargo crate with
controllers, routes, migrations, a frontend, and a working auth flow
already wired together. The frontend is an Inertia SPA (Svelte, React, or
Vue) or the Live kit's server-rendered pages. Run it once per app, then
live in `suprnova serve` from there.

## Usage

```bash
suprnova new [name] [options]
```

If `name` is omitted, the interactive wizard prompts for it. The
name becomes the project directory, the Cargo package name (after
snake-casing), and the default `APP_NAME` in `.env`. Names must be
ASCII letters/digits/`-`/`_`, start with a letter, contain no path
separators or `..`, and be 64 characters or fewer.

## Options

| Option | Description |
|---|---|
| `--frontend <svelte\|react\|vue\|live>` | Pick the frontend non-interactively: an Inertia SPA (`svelte`, `react`, `vue`) or the [Live kit](#live-starter-kit) (`live`). Conflicts with `--api`. |
| `--api` | Scaffold a JSON:API-only project (no Inertia, no SPA, token auth instead of sessions). |
| `--no-interaction` | Skip all prompts and use defaults (name `my-suprnova-app`, frontend `svelte`, empty author/description). |
| `--no-git` | Skip `git init` in the new project. |
| `--with-portless` | Emit a `portless.json` so [`suprnova dev:tls`](dev-tls.md) can serve the app at `https://<name>.localhost`. Opt-in; changes nothing else. |

## Interactive mode

```bash
suprnova new my-app
```

The wizard asks four questions, in this order:

1. **Project name** - defaults to the directory argument (`my-app`)
2. **Description** - used as the Cargo package description
3. **Author** - used as the Cargo package author; defaults to your
   `git config user.name <name@email>` if set
4. **Frontend framework** - `Svelte (recommended)`, `React`, `Vue`, or
   `Live (server-rendered, no Node)`

After confirming, the scaffolder writes the project, runs `git init`
(unless `--no-git`), and prints the next steps:

```
Backend  http://localhost:8765
Frontend http://localhost:5765
```

A Live kit project runs one process, so it prints one address:

```
App http://localhost:8765
```

## Non-interactive mode

For CI, dotfiles, or scripted setup, pass `--no-interaction` plus the
flags you want to override:

```bash
suprnova new my-app --frontend svelte --no-interaction
```

Defaults under `--no-interaction`:

- Frontend: `svelte`
- Description: `"A web application built with Suprnova"`
- Author: empty
- Git: initialized

There are no `--description` or `--author` flags; those values are
only set via the interactive prompts or accept their defaults.

## Live starter kit

The Live kit is the frontend for an application without a Node toolchain:

```bash
suprnova new my-app --frontend live
```

It writes no `frontend/` directory, no `package.json`, and no Vite
config. Every page is a server-rendered Live document: a controller renders
an Askama view in one of two layouts, and the pages that act mount
[Live](live.md) components, such as the sign-in form, the dashboard's note
counts, and the notes list. The application serves the Live browser runtime
and the stylesheets and scripts of the shipped component library itself, so
`suprnova serve` starts the backend alone and there is nothing to build
before you deploy.

The kit keeps the backend the Inertia kits share: the `users` and `notes`
tables and models, the account flows, and the route names. The scaffold
installs the library components its views import under
`templates/suprnova-ui/`, the way `suprnova live:add` installs them, and
records them in `suprnova.toml`. `.env` sets `SUPRNOVA_FRONTEND=live`, so
`suprnova make:inertia` refuses in the project, and `suprnova docker:init`
writes a Dockerfile with no Node stage. For the pages, the components, and
how to add your own, see [the Live starter kit](starter-kits.md#the-live-starter-kit).

## API-only project

For service backends with no SPA, use `--api`:

```bash
suprnova new my-api --api
```

The API starter is significantly smaller: no `frontend/` directory, no
Inertia, no auth views, and a single-crate `src/main.rs` layout. It initializes
Magnetar against the shared SeaORM connection, creates the canonical
`app_users` model, installs `TimeoutMiddleware` and
`BearerTokenMiddleware`, and uses `Auth::password()` for registration and
login. `PASSKEY_RP_ID` and `PASSKEY_RP_ORIGIN` are read by the generated
bootstrap with local defaults.
The starter also includes a sample users controller and `UserResource` JSON
serializer and binds to port 8765 in `.env`.

The `app_users` migration creates the time columns as `timestamp with time
zone` on Postgres and `DATETIME` on MySQL and MariaDB: the `User` model and
Magnetar both read them as `DateTime<Utc>`, which Postgres decodes only from
`timestamp with time zone`. An API application generated before this change
has `timestamp` columns on Postgres, which neither can read. Convert them
once:

```sql
ALTER TABLE app_users
    ALTER COLUMN email_verified_at TYPE timestamptz USING email_verified_at AT TIME ZONE 'UTC',
    ALTER COLUMN locked_at TYPE timestamptz USING locked_at AT TIME ZONE 'UTC',
    ALTER COLUMN created_at TYPE timestamptz USING created_at AT TIME ZONE 'UTC',
    ALTER COLUMN updated_at TYPE timestamptz USING updated_at AT TIME ZONE 'UTC';
```

`--api` is mutually exclusive with `--frontend`; passing both errors.
Under `--api`, only the project name is prompted - the
description/author/frontend prompts are skipped.

## What gets scaffolded

A full directory tour lives in [Directory Structure](structure.md);
the short version is:

- `cmd/main.rs` - binary entry; calls `Application::new()…run()`
- `src/` - controllers, actions, commands, config, middleware,
  models, migrations, plus `bootstrap.rs` and `routes.rs`. The
  generated `bootstrap.rs` wires the global middleware chain -
  logging, session, locale, the request timeout, CSRF, include
  parsing - and calls
  [`Inertia::install`](frontend-inertia-responses.md), which adds the
  Inertia protocol middlewares (asset-version `409`, `302 → 303` on
  `PUT`, `PATCH` and `DELETE` redirects). The asset version it advertises defaults to a
  hash of the Vite build manifest, so shipping a frontend build changes
  it automatically - see
  [Version detection](frontend-inertia-responses.md). The same call
  pins the frontend you scaffolded
  with, so the HTML shell loads that framework's Vite entry point;
  `.env` carries the matching `SUPRNOVA_FRONTEND` for the CLI's own
  generators
- `src/bin/console.rs` - the per-project `php artisan` analogue
- `frontend/` - Vite 8 + Tailwind v4 + your chosen framework, with
  Home / Dashboard / Login / Register / ForgotPassword / ResetPassword /
  VerifyEmail pages already wired through Inertia. The Live kit has no
  `frontend/`: its pages are views under `templates/live/` and its
  components live in `src/live/`
- the account flows: registration mails a verification link and
  continues to `/verify-email`, which resends and consumes it;
  `/forgot-password` mails a reset link to a verified address and
  `/reset-password` takes the new password. Mail leaves through the
  `MAIL_*` settings in `.env`, which point at a local catcher on port
  1025 (the Mailpit that `suprnova docker:compose --with-mailpit` adds);
  set `MAIL_DRIVER=log` to print each message, link included, to the
  server log instead
- `src/routes.rs` - the auth and account routes, and a static-file
  fallback that serves `public/` (the built frontend) in production
- `src/migrations/` - `users`, `sessions`, `remember_tokens`, and
  `auth_flow_tokens` tables ready to go
- `.env` - SQLite database by default, with a freshly-generated
  `APP_KEY` so the app boots without operator intervention
- `.gitignore`, `Cargo.toml`

### Why Suprnova diverges

Laravel ships with Blade and pulls a frontend in via Breeze/Jetstream
after the fact. Suprnova goes the other way: `suprnova new` always
scaffolds a complete frontend - a real SPA (Svelte/React/Vue on Inertia),
the server-rendered Live kit - or a real JSON:API project. Laravel's
Livewire starter kit still builds its assets with Vite; the Live kit needs
no build step, because the framework serves the Live runtime and the
component library's files.

The default frontend is **Svelte 5** (runes-on), not React. We picked
it because it's the lightest of the three at runtime and the closest
to the framework's "compile-time wins over runtime cleverness"
philosophy. React and Vue are equally first-class - pick what your
team knows.

## Distribution

The CLI itself ships via git, not crates.io (pre-launch):

```bash
cargo install --git https://github.com/eas4ai/suprnova.git --tag v4.6.2 suprnova-cli
```

`--force` on the same command updates an existing install. Scaffolded
projects depend on the framework crate the same way - a git
dependency in their `Cargo.toml`, pinned to the current release tag.
See [Installation](installation.md) for the full
toolchain prerequisites.

## Next

- [Installation](installation.md) - Rust/Node/DB prerequisites and
  toolchain setup
- [Directory Structure](structure.md) - what each scaffolded file
  does
- [Quickstart](quickstart.md) - first 5 minutes after `suprnova new`
- [suprnova serve](cli-serve.md) - the dev runner you'll use next
- [Console](console.md) - `cargo run --bin console` and the
  `#[command]` system


---

<!-- /docs/cli-serve -->

# suprnova serve

`suprnova serve` runs your backend and the Vite dev server together with hot
reload on both sides, plus automatic TypeScript type regeneration whenever you
touch a `#[derive(InertiaProps)]` struct. It's the one command you keep open
in a terminal while you're building.

```bash
suprnova serve
```

Both processes stream their stdout into the same terminal with coloured
`[backend]` and `[frontend]` prefixes so you can tell who said what. `Ctrl+C`
shuts them both down cleanly.

## Usage

```bash
suprnova serve [OPTIONS]
```

| Option | Default | Description |
|---|---|---|
| `-p, --port <PORT>` | `8765` (CLI) / `$SERVER_PORT` (env) | Backend HTTP port |
| `--frontend-port <PORT>` | `5765` (CLI) / `$VITE_PORT` (env) | Vite dev server port |
| `--backend-only` | `false` | Skip the Vite dev server |
| `--frontend-only` | `false` | Skip the backend, just run Vite |
| `--skip-types` | `false` | Don't regenerate TypeScript types on Rust changes |
| `--big-integers` | `false` | Type `i64`, `u64`, `i128`, `u128`, `isize` and `usize` as `number \| bigint` on start-up and on every regeneration, as `generate-types --big-integers` does - see [Wide integers](frontend-typescript-types.md#wide-integers) |
| `--no-restart` | `false` | Don't respawn a crashed dev process - tear the whole session down instead |
| `--restart-tries <N>` | `5` | Give up retrying a process after this many consecutive crashes. Ignored with `--no-restart`, which already ends the session on the first crash. |
| `--migrate <WHEN>` | `start` | When `serve` runs the pending migrations: `start` (once, when `serve` starts), `always` (each time the backend starts, so on every save), or `never`. See [Migrations](#migrations). |
| `--no-migrate` | `false` | Run no migration. The same as `--migrate never`. Cannot be combined with `--migrate`. |
| `--timestamps` | `false` | Prefix each output line with an `HH:MM:SS` clock time |
| `--json` | `false` | Emit one JSON object per line (NDJSON) on stdout instead of prefixed text - see [JSON output](#json-output). Combining with `--timestamps` isn't an error; `--timestamps` has no extra effect, since every event already carries its own timestamp. |

The CLI flags take precedence over environment variables, which take precedence
over the built-in defaults. A scaffolded `.env` ships with `SERVER_PORT=8765`
and `VITE_PORT=5765`; you'll see those values used unless you override with
`--port`.

## Examples

### Default - both servers

```bash
suprnova serve
```

Output:

```
Backend  http://127.0.0.1:8765
Frontend http://127.0.0.1:5765
[backend] Compiling my-app v0.1.0 ...
[frontend] VITE v6.3.0  ready in 312 ms
```

Hit `http://127.0.0.1:8765` in your browser. The backend serves the Inertia
HTML shell and proxies asset requests through to Vite, so you don't need to
visit the Vite URL directly.

### Custom ports

```bash
suprnova serve --port 3000 --frontend-port 3001
```

Or set them in `.env` and run without flags:

```env
SERVER_PORT=3000
VITE_PORT=3001
```

### Backend only

```bash
suprnova serve --backend-only
```

Good for working on an API-only project, or when your frontend is already
running in another terminal (or another machine, or a deployed preview).

### Frontend only

```bash
suprnova serve --frontend-only
```

Good for working on UI without paying the cost of a Rust rebuild on every
save, or when the backend is running in another shell (or in Docker).

### API-only project

A project scaffolded with `suprnova new --api` has no `frontend/`
directory. Run `serve` exactly as you would anywhere else:

```bash
suprnova serve
```

`serve` sees no `frontend/package.json`, skips the Vite pane and the
TypeScript generation that feeds it, and runs the backend.
`--frontend-only` is still an error on such a project: it asks for the one
pane that does not exist.

### Skip type generation

```bash
suprnova serve --skip-types
```

Disables the TypeScript regeneration watcher. Use this when you're managing
`frontend/src/types/inertia-props.ts` by hand, or when you're working far
from any Inertia code and want quieter output.

## What it actually does

When you run `suprnova serve`, the CLI:

1. Loads `.env` from the current directory.
2. Resolves backend and frontend ports (CLI flag → env var → default).
3. Verifies you're in a Suprnova project - `Cargo.toml` must exist (unless
   `--frontend-only`), and `--frontend-only` needs a `frontend/` directory
   with a `package.json`. A project without one is served backend-only
   rather than rejected.
4. Regenerates TypeScript types from any `#[derive(InertiaProps)]` structs
   it finds in `src/`, writing them to `frontend/src/types/inertia-props.ts`.
   Skipped when the project has no frontend.
5. Installs `cargo-watch` via `cargo install --locked --version "^8.5"
   cargo-watch` if it isn't on the PATH yet (one-time, with an
   "Installing..." notice). Skipped under `--frontend-only`.
   The version is bounded because `serve` drives `cargo watch -s`, whose
   meaning is not guaranteed across a major bump; `--locked` builds the
   dependency tree cargo-watch published rather than re-resolving it at
   install time. A command that installs software as a side effect of
   starting a dev server should not also be choosing versions for you.
6. Runs `npm install` in `frontend/` if `node_modules` doesn't exist yet.
   Skipped under `--backend-only`, and when the project has no frontend.
7. Runs `cargo run --bin <package-name> -- migrate` once, so your pending
   migrations are applied before the backend starts (see
   [Migrations](#migrations)). The frontend and the other processes start
   first and do not wait for it. Skipped under `--frontend-only`,
   `--migrate always`, and `--migrate never`, and when the project has no
   `src/migrations` directory.
8. Spawns `cargo watch` for the backend, scoped with `-w` to the paths the
   server is actually built from: `src/`, `cmd/`, `Cargo.toml`,
   `Cargo.lock`, `.env`, `lang/`, and `templates/`, plus each template
   directory inside the project that `askama.toml` names under
   `[general] dirs`. Views are compiled into the server, so a view edit,
   one `live:add` writes included, rebuilds it. `cmd/` is where the
   full-stack scaffold puts the server binary's `main.rs`; the `--api`
   scaffold puts it in `src/` and has no `cmd/`. Each path is passed only
   when it exists, because cargo-watch refuses to start on a `-w` path that
   doesn't - a project that hasn't been built yet has no `Cargo.lock`, and
   it's picked up on the next `serve`.

   `--no-vcs-ignores` goes with them. cargo-watch applies your
   `.gitignore` to explicitly named `-w` roots, not just to its own
   project walk, and the scaffold gitignores `.env` - so without that flag
   `-w .env` watches nothing at all. It can't widen what restarts the
   backend, because `-w` has already narrowed that to the paths above,
   and the only gitignored things inside them are `.env` and (on `--api`)
   `Cargo.lock`, both watched on purpose. `target/`, `node_modules`, and
   the rest sit outside every watched root either way.

   On a scaffolded full-stack project the full invocation is
   `cargo watch --no-vcs-ignores -w src -w cmd -w Cargo.toml -w Cargo.lock
   -w .env -w lang -s '<suprnova> live:wait -- run --bin <package-name> -- serve --no-migrate'`,
   where `<suprnova>` is the path of the `suprnova` binary that runs `serve`,
   and `-w templates` joins the list once the project has a `templates/`
   directory.
   Under `--migrate always`, or when step 7 could not run the migrations, the
   cargo command is `run --bin <package-name>` and the backend migrates by
   itself.
   `live:wait` runs the cargo command after `--` itself. It starts no build
   while a `suprnova live:add` holds the project lock, so no build starts on
   a half-written install, and the build that follows sees every file the
   install wrote. It holds a shared lock until cargo finishes the build, so
   `live:add` refuses to start mid-build, and releases it before the
   application starts. If an install was killed partway, `live:wait`
   (and `serve` itself, when it starts) puts back every file the install's
   journal names before anything is built.
   Frontend edits and the
   generated `frontend/src/types/*.ts` are outside that scope, so they
   never restart the backend.
9. Spawns `npm run dev` in `frontend/` for Vite, which gives you HMR for
   Svelte/React/Vue components and Tailwind classes. Skipped under
   `--backend-only`, and when the project has no frontend.
10. Spawns every extra process declared in the project's `suprnova.toml`
   (see [Extra dev processes](#extra-dev-processes) below), each with its
   own `[name]` prefix - queue workers, log tailers, anything else you'd
   otherwise juggle in another terminal.
11. Starts a file watcher on `src/` that re-runs the type generator whenever
    a `.rs` file changes, once the burst of saves has been quiet for 500 ms.
    Only real changes count - a creation, a write, or a deletion. Reads do
    not, which matters because the generator reads every `.rs` file under
    the tree it is watching on each run.
    Skipped when the project has no frontend, the same as the startup type
    generation in step 4. The debounce is trailing-edge, so a burst -
    `cargo fmt`, format-on-save across several files, a branch switch -
    coalesces into exactly one regeneration that runs *after* the last
    write, rather than one that fires on the first file and misses the rest.
    A regeneration writes the file only when the emitted TypeScript differs
    from what's already there, and the watcher reports only what it wrote:
    an edit that doesn't change any prop shape prints nothing and emits no
    `types_regenerated` event. Silence after a save means your edit didn't
    change the generated types.
12. Forwards every child's stdout/stderr to your terminal with a `[name]`
    prefix (`[backend]`, `[frontend]`, or the process's configured name),
    optionally timestamped with `--timestamps` - or, with `--json`, as
    NDJSON events instead (see [JSON output](#json-output) below).

`Ctrl+C` signals the manager to set its shutdown flag, kill every child,
and exit. If a child exits on its own - a Rust compile error too severe
for `cargo watch` to recover, a crashed Vite process, a `suprnova.toml`
process that failed - it's respawned after a short backoff (200ms,
doubling on each consecutive crash, capped at 5s; a process that stayed
up 30s resets the climb) instead of tearing the session down. Pass
`--no-restart` and any child exiting shuts the whole session down
immediately.

A process that keeps crashing doesn't retry forever: `--restart-tries`
(default `5`) caps how many consecutive crashes `serve` retries before
giving up on that one process - a fresh 30s of uptime resets the count,
same as the backoff delay. Giving up prints an actionable message and
stops retrying *only* that process; the others (and the session itself)
keep running, matching Laravel's own `concurrently --restart-tries=5`
default. See [Troubleshooting](#a-process-keeps-crash-looping).

### Why Suprnova diverges

Laravel users typically run `php artisan serve` for the backend and `npm
run dev` in another terminal, and most teams paper over the two-terminal
split with a `Procfile` and `foreman`/`overmind`. Suprnova ships that
multiplexer as a first-class CLI command. You get one terminal, one
`Ctrl+C`, automatic toolchain bootstrap (`cargo-watch`, `npm install`),
and a typed-Inertia bridge that regenerates `frontend/src/types/inertia-props.ts`
on the fly so your Svelte/React/Vue components always see the current
prop shape without manual type sync.

Laravel's `dev` command also offers `--tabs` and `--stream` modes, each
rendering output through a small Node TUI (`@laravel/multiplex`).
Suprnova doesn't ship the TUI: single-terminal, prefixed output is the
norm across the Rust dev-tooling ecosystem (`cargo watch`, `bacon`,
`just`), and a process registry with colored prefixes already gives you
the "which process said this" signal a TUI provides. `--stream`'s
underlying job - one scriptable, real-time event stream - ships as
`--json` (see [JSON output](#json-output)); `--tabs`' multi-pane TUI is
the deliberate no, not a gap - a second interaction model and a second
library to keep working across terminals for a problem this page already
solves. See the corresponding row in
[Parity](parity.md#what-we-wont-ship-and-why).

## Hot reload

**Backend.** `cargo watch` is the loop, scoped to the paths the server is
built from. It rebuilds and restarts on a change under `src/`, `cmd/` or
`templates/`, to `Cargo.toml`, `Cargo.lock`, or `.env`, or under `lang/` -
`.env` is read once by `Config::init` at boot and the Fluent catalogs once
at bootstrap, so a change to either only takes effect on a restart. `.env`
is watched through `--no-vcs-ignores`, without which your `.gitignore`
would hide it from the watcher. Saving a frontend component,
or regenerating `frontend/src/types/inertia-props.ts`, is outside that
scope and leaves the backend running. Cold rebuilds after touching a heavy
crate can take several seconds; incremental changes in a single file are
usually sub-second.

**Frontend.** Vite's HMR injects component changes in place without a full
reload, preserving component state. Tailwind classes update live via the
Tailwind v4 watcher.

**TypeScript types.** Whenever a `.rs` file changes, the type watcher re-runs
the generator. If new `#[derive(InertiaProps)]` structs appear (or existing
ones change shape), the regenerated `frontend/src/types/inertia-props.ts`
triggers Vite's HMR for the component that imports them. When the emitted
TypeScript is byte-identical to what's already on disk the file is left
untouched and the watcher says nothing, so a regeneration that changed
nothing isn't a change anything downstream has to react to - not Vite, not
the backend watcher, and not whatever is reading `--json`.

## Migrations

The backend runs under `cargo watch`, which starts it again on every save.
An application that starts with no subcommand migrates before it serves. If
`serve` left it at that, every save would run every pending migration
against your database, including the draft of a migration you saved a moment
ago. A migration that has run does not run again when its file changes, so
your database would keep the schema of the first draft.

By default (`--migrate start`), `serve` runs the pending migrations once,
before it starts the backend, and starts the watched backend with
`serve --no-migrate`, so a restart runs none. The run is a process named
`migrate`. Its output carries the `[migrate]` prefix, and with `--json` its
`started`, `output`, and `exited` events carry `"name":"migrate"`. Ctrl+C
ends the run and the session.

| Option | The pending migrations run |
|---|---|
| `--migrate start` (default) | Once, when `serve` starts. |
| `--migrate always` | Each time the backend starts, which is on every save. |
| `--migrate never`, `--no-migrate` | Never. `suprnova migrate` runs them. |

When a `.rs` file under `src/migrations` changes after the start, `serve` prints this
notice once for each burst of writes:

```text
[migrate] src/migrations changed. The dev server does not run migrations when the backend restarts: run `suprnova migrate` to apply them, or start with `suprnova serve --migrate always`.
```

With `--json`, the event is `migrations_changed` instead (see
[JSON output](#json-output)).

Two cases leave the backend to migrate by itself, as it does under
`--migrate always`:

- The run at the start fails. `serve` prints a warning with the reason. For
  that session the backend runs the migrations each time it starts and does
  not serve until they pass.
- The project has no `src/migrations` directory. Its migrator is somewhere
  the CLI cannot see, so the application runs it.

## Extra dev processes

`suprnova serve` always runs the backend and Vite, but most projects have
more than two things to keep running - a queue worker, a log tailer, a
mail-catcher. Declare them in a `suprnova.toml` at the project root and
`serve` spawns, prefixes, and auto-restarts them right alongside the
backend and frontend:

```toml
[[serve.process]]
name = "queue"
command = "cargo"
args = ["run", "--", "queue:work"]
color = "yellow"

[[serve.process]]
name = "logs"
command = "tail"
args = ["-f", "storage/logs/app.log"]
```

Each entry needs `name` and `command`; `args` defaults to none, `color`
defaults to one of green/yellow/blue/white assigned in declaration order
(or pick one of the eight named `console` colors - black, red, green,
yellow, blue, magenta, cyan, white). Names must be unique. `suprnova.toml`
is entirely optional; a project without one runs exactly as before. The
name is all lowercase: `serve` refuses a project that holds only a
`Suprnova.toml`, and asks you to rename it.

### Why Suprnova diverges

Laravel registers extra `dev` processes from PHP -
`DevCommands::register($command, $name)`, typically in a service
provider's `boot()` - because `php artisan dev` execs a multiplexer from
inside the same process that already booted the application.
`suprnova serve` is a separate binary from your app; it never links or
runs your Rust code, and only ever shells out to `cargo watch` and `npm`.
There's no application boot to hook into, so registration has to be data
the CLI reads rather than a call your code makes - hence `suprnova.toml`
instead of a `DevProcesses::register()` API.

## JSON output

Pass `--json` and `suprnova serve` writes one JSON object per line
(NDJSON) to stdout instead of colored `[name]`-prefixed text - nothing
else goes to stdout while it's active, so you can pipe straight into
`jq` or any other line-oriented JSON consumer. Every line has a `type`
field:

| `type` | Fields | Meaning |
|---|---|---|
| `started` | `ts`, `name`, `pid` | A process (backend, frontend, the `migrate` run, or a `suprnova.toml` entry) was spawned for the first time. |
| `output` | `ts`, `name`, `stream` (`"stdout"` or `"stderr"`), `line` | One line of a child's output, carried as a field rather than passed through raw. |
| `exited` | `ts`, `name`, `code` (nullable) | A process exited. `code` is `null` if it was killed by a signal rather than returning a status. |
| `restart_scheduled` | `ts`, `name`, `delay_ms` | A crashed process will be respawned after `delay_ms` (see the backoff schedule above). |
| `restart_succeeded` | `ts`, `name`, `pid` | A scheduled respawn succeeded; the process is running again under a new PID. |
| `gave_up` | `ts`, `name`, `tries` | The process crashed `tries` consecutive times (`--restart-tries`) and `serve` stopped retrying it. The session, and every other process, keep running. |
| `types_regenerated` | `ts`, `artifact` (`"inertia_props"` or `"lang_keys"`), `count` | The file watcher rewrote a TypeScript artifact after a `.rs`/`.ftl` change. Fires only when the generated file actually changed: a `.rs` edit that leaves the emitted TypeScript byte-identical writes nothing and emits nothing, so an event always means the file on disk is different now. `count` is the number of structs (or message ids) in the rewritten file, not the number that changed. |
| `migrations_changed` | `ts` | A `.rs` file under `src/migrations` changed and the session runs no migration when the backend restarts (`--migrate start` or `--migrate never`). One event for each burst of writes. Run `suprnova migrate` to apply the change. |
| `shutdown` | `ts` | The session is shutting down. Always the last line. |

For example, a Vite crash and its respawn look like:

```json
{"type":"exited","ts":"2026-08-18T10:15:23.456-07:00","name":"frontend","code":1}
{"type":"restart_scheduled","ts":"2026-08-18T10:15:23.456-07:00","name":"frontend","delay_ms":200}
{"type":"restart_succeeded","ts":"2026-08-18T10:15:23.657-07:00","name":"frontend","pid":48391}
```

`--json` composes with `--timestamps` rather than conflicting with it:
combining them isn't an error, but `--timestamps` has no additional
effect, since every event already carries its own `ts` field.

This is machine-readable output other tools parse - field names and
`type` values won't be renamed or removed without a note in the
changelog. Treat an unrecognized `type` or an unexpected extra field as
something to ignore, not an error, so a future release can extend the
schema without breaking your consumer.

## Troubleshooting

### Port already in use

```text
[backend] Error: Address already in use (os error 98)
```

Find and kill the process, or pick another port:

```bash
lsof -i :8765
kill -9 <pid>

# or
suprnova serve --port 8081
```

### `cargo-watch` install fails

The CLI runs `cargo install cargo-watch` if it isn't already on PATH. If
that install fails (no network, restricted environment), install it manually
once:

```bash
cargo install cargo-watch
```

After that, `suprnova serve` will find it and won't try to install again.

### Frontend dependencies stuck

If `npm install` fails mid-bootstrap, fix the cause (npm registry reachable,
disk space, lockfile in good shape) and run it manually:

```bash
cd frontend && npm install
```

Then re-run `suprnova serve`. The CLI only auto-runs `npm install` when
`node_modules` is missing, so a successful manual install lets it skip that
step.

### Type regeneration not picking up changes

The watcher polls every 2 seconds (using `notify` with a poll interval -
chosen for cross-platform reliability over inotify quirks) and debounces
regeneration to once every 500 ms. If a change isn't showing up:

- Confirm the file is under `src/` (the watcher doesn't recurse into
  `crates/`, `cmd/`, or `migrations/`).
- Confirm the struct actually has `#[derive(InertiaProps)]`.
- Restart `suprnova serve` and watch for the `Generated N type(s)` startup
  message - if you see `No InertiaProps structs found`, the scanner didn't
  find anything to emit.

### A process keeps crash-looping

If a child - backend, frontend, or a `suprnova.toml` entry - can't start
(bad code, a missing binary, a port conflict), it respawns on the backoff
schedule described above instead of stopping. Look at the `[name]` lines
right before each "respawning in …ms" notice for the real error (a rustc
`error[E…]`, an ENOENT, whatever the child printed). Fix the cause; the
next respawn attempt picks it up automatically. To stop the retries and
see the failure once, re-run with `--no-restart` - the session then tears
down on the first crash.

After `--restart-tries` (default `5`) consecutive crashes, `serve` stops
retrying that process on its own and prints a message naming it:

```text
gave up restarting `backend` after 5 attempts; fix the error and run `suprnova serve` again
```

The other processes, and the session itself, keep running - fix the
cause and re-run `suprnova serve` to bring the given-up process back; you
don't need to restart the whole session for it.

## Next

- [Installation](installation.md) - get the CLI on your machine
- [Quickstart](quickstart.md) - a full first-app walkthrough
- [Directory Structure](structure.md) - what `suprnova new` scaffolded
- [Generators](cli-generators.md) - `make:controller`, `make:action`, etc.
- [Console](console.md) - the per-project `cargo run --bin console` binary


---

<!-- /docs/dev-tls -->

# Named HTTPS Dev URLs (`suprnova dev:tls`)

By default `suprnova serve` serves your backend on a raw
`http://127.0.0.1:8765`. That's fine for most development - but some
browser features only work over HTTPS on a named host:

- **Passkeys / WebAuthn** - require a secure context and a stable origin.
- **`Secure` cookies** and **`SameSite=None`** - only set over HTTPS.
- **Service workers** - only register over HTTPS (or `localhost`).
- **OAuth/OIDC redirect URIs** - providers often reject raw IP/port hosts.

[portless](https://portless.sh) gives every local app a stable
`https://<name>.localhost` URL behind a single TLS proxy on port 443.
`suprnova dev:tls` wires Suprnova to portless and - the part that's easy
to get wrong - trusts portless's local CA in **every browser certificate
store on your machine**, with no sudo on Linux.

> **Strictly opt-in.** portless is never required. `suprnova serve` works
> with no portless installed. You opt in when you scaffold
> (`suprnova new <name> --with-portless`) or by adding `portless.json`
> later. If you never run `dev:tls`, you never touch portless.

## Install portless

portless is a Node tool:

```bash
npm install -g portless
```

Then install its always-on 443 proxy once (this is a system-level,
sudo-required step that belongs to portless, not Suprnova):

```bash
portless service install
```

## Per project

You have two ways to opt a project in.

**Scaffold with the flag** - writes `portless.json` up front:

```bash
suprnova new myapp --frontend svelte --with-portless
```

That emits a `portless.json` at the project root:

```json
{
  "name": "myapp",
  "appPort": 8765
}
```

`appPort` is your backend's fixed `SERVER_PORT`. It tells portless the app
binds a known port (instead of portless assigning one via `$PORT`), so the
named URL routes straight to it.

**Add it to an existing project** - write that same `portless.json` by
hand (or run `portless alias myapp 8765`), using your `SERVER_PORT`.

Then, on **each machine** that will run the app, do the one-time trust +
route registration:

```bash
cd myapp
suprnova dev:tls
```

This:

1. Checks `portless` is on your PATH.
2. Resolves the name (`--name`, else `Cargo.toml` `[package].name`) and
   port (`--port`, else `SERVER_PORT`, else `8765`).
3. Registers the route `myapp.localhost → 127.0.0.1:8765` (skip with
   `--no-alias`).
4. Trusts portless's CA in your browsers' certificate stores.
5. Prints the next steps.

Flags:

| Flag | Effect |
|---|---|
| `--name <name>` | Override the URL name. Default: `Cargo.toml` package name. |
| `--port <port>` / `-p` | Override the routed port. Default: `SERVER_PORT`, else `8765`. |
| `--no-alias` | Only trust the CA; don't touch the portless route. |
| `--yes` | Skip the confirmation before modifying your certificate stores. Ignored when the CA's fingerprint changed since the last run - that always asks. |

### Why step 4 asks first

Trusting a CA means every certificate it signs is accepted by your
browser, silently, for every site. That is worth one deliberate keystroke.

The CA is resolved only from portless's own state, never from anything
the project directory can influence - a checked-out repo cannot point
`dev:tls` at a CA of its choosing. The command prints the fingerprint it
is about to trust and waits for you to confirm. If the fingerprint
differs from the one trusted previously, it asks even under `--yes`: a
changed CA is either a portless reinstall or something you want to look
at, and only you can tell which.

## Run

```bash
suprnova serve
```

Open `https://myapp.localhost`.

The backend binds `8765` by default; the Vite dev server rides along on
`5765` over `http://localhost`. A page served from the HTTPS origin can
reference `http://localhost` assets because browsers treat `localhost` as
a secure context - it is **not** blocked as mixed content.

> **Hot Module Reload over HTTPS is best-effort.** Vite's HMR websocket
> connects back to the dev server; whether that succeeds cleanly over the
> HTTPS origin depends on your Vite/browser versions. If live updates
> stop working under `https://`, point Vite at an HTTPS dev-server origin
> via the `INERTIA_VITE_DEV_SERVER` environment variable. Page loads and
> the rest of the flow are unaffected.

## Multiple apps

portless owns 443 and multiplexes by subdomain. Register each app with
its own name and port:

```bash
suprnova dev:tls --name app-one --port 8765
suprnova dev:tls --name app-two --port 8766
```

Never bind 443 from an app directly - that's portless's job.

## Troubleshooting

**`ERR_CERT_AUTHORITY_INVALID` after running `dev:tls`.** Your browser
wasn't fully restarted. Browsers read their certificate store once at
launch; a tab reload is not enough. Type `chrome://restart` (or fully
quit and relaunch).

**`502 Bad Gateway`.** The proxy is up but your backend isn't. Run
`suprnova serve` in the project directory.

**`portless trust` says "A terminal is required to authenticate".**
That's portless's own command needing a real TTY for `sudo`.
`suprnova dev:tls` sidesteps it entirely on Linux: it installs the CA
straight into your browsers' NSS stores, which need no sudo.

**A Flatpak browser is still untrusted.** Flatpak browsers keep their NSS
database under `~/.var/app/<id>/.pki/nssdb`. `dev:tls` covers those -
re-run it and fully restart that browser.

**`certutil: command not found`.** Install NSS tools:

| Distro | Command |
|---|---|
| Debian/Ubuntu | `sudo apt install libnss3-tools` |
| Fedora/RHEL | `sudo dnf install nss-tools` |
| Arch | `sudo pacman -S nss` |

**`portless CA not found at ~/.portless/ca.pem`.** portless generates its
CA when the proxy first runs. Start it once
(`systemctl start portless`, or `portless proxy start`), then re-run
`suprnova dev:tls`.

## Platform notes

The browser-NSS path above is the Linux mechanism. On **macOS** and
**Windows**, browsers read the OS keychain / certificate store, so
`dev:tls` delegates CA trust to `portless trust`, which targets those
native stores.


---

<!-- /docs/cli-generators -->

# Code Generators

The `suprnova make:*` family scaffolds the conventional file for each
piece of a project - a controller, an action, a middleware, a console
command, a domain error, a scheduled task, a checked view, an Inertia
page or props struct, a database migration, and the twenty-one kinds of
[one-file generators](#the-one-file-generators) Laravel's artisan has, from
a factory to an interface - and wires the new module into its parent
`mod.rs` (and where needed, `src/lib.rs` and `cmd/main.rs`).
Reach for them when you'd otherwise be retyping the same boilerplate + `pub mod x;` import line, which is most of the time.

## make:controller

Scaffold a controller - a file in `src/controllers/` with a single
`#[handler]` async fn named `invoke`.

```bash
suprnova make:controller User
suprnova make:controller order_item
```

The name is normalised to `snake_case` for the file name and used
as-is for the `controller:` echo in the response. Only ASCII letters,
digits, and `_` are accepted - paths like `api/User` are rejected.

### Generated file

```rust
// src/controllers/user.rs
use suprnova::{handler, json_response, Request, Response};

#[handler]
pub async fn invoke(_req: Request) -> Response {
    json_response!({
        "controller": "User"
    })
}
```

### What it wires

1. Writes `src/controllers/<name>.rs` with the `#[handler]` fn.
2. Adds `pub mod <name>;` to `src/controllers/mod.rs` (creates the
   file if it didn't exist).
3. Prints a hint to add a route in `src/routes.rs`:
   `.get("/<name>", controllers::<name>::invoke)`.

See [Controllers](controllers.md) for the handler contract,
extractors, and the `routes!` macro.

---

## make:action

Scaffold a single-responsibility action - a container-resolvable
struct with an async `execute` method that returns a
`Result<String, FrameworkError>` so the skeleton compiles before you
fill in the body.

```bash
suprnova make:action CreateUser
suprnova make:action SendNotification
```

The name is PascalCased; an `Action` suffix is appended if missing,
and the file is the snake-cased struct name.

### Generated file

```rust
// src/actions/create_user_action.rs
use suprnova::{injectable, FrameworkError};

#[injectable]
pub struct CreateUserAction {
    // Add injected dependencies as fields here, e.g.
    // db: suprnova::DbConnection,
}

impl CreateUserAction {
    pub async fn execute(&self) -> Result<String, FrameworkError> {
        Ok("CreateUserAction executed".to_string())
    }
}
```

### What it wires

1. Writes `src/actions/<snake>.rs`.
2. Adds `pub mod <snake>;` to `src/actions/mod.rs`.
3. `#[injectable]` registers the action with the container at link
   time, so any controller can resolve it via `App::get::<CreateUserAction>()`
   and call `action.execute().await?`.

See [Actions](actions.md) for the resolve-and-invoke pattern and how
actions compose with the container.

---

## make:middleware

Scaffold a middleware - a unit struct that implements
`suprnova::Middleware`. Its `handle` passes the request to `next` and
returns the response, as Laravel's middleware stub does, so the new
middleware changes nothing until you give it logic.

```bash
suprnova make:middleware Auth
suprnova make:middleware RateLimit
suprnova make:middleware Admin/EnsureRole --test
```

The name is PascalCased; a `Middleware` suffix is appended if missing.
The file uses the snake-cased base name (without the suffix), e.g.
`Auth` → `src/middleware/auth.rs`, struct `AuthMiddleware`.

A nested name writes under a subdirectory, as Laravel's
`make:middleware Admin/EnsureRole` writes under
`app/Http/Middleware/Admin`: `Admin/EnsureRole` (or `Admin\EnsureRole`)
writes `src/middleware/admin/ensure_role.rs`, struct
`EnsureRoleMiddleware`, reached as
`crate::middleware::admin::EnsureRoleMiddleware`.

### Generated file

```rust
// src/middleware/auth.rs
use suprnova::{async_trait, Middleware, Next, Request, Response};

/// Auth middleware.
pub struct AuthMiddleware;

#[async_trait]
impl Middleware for AuthMiddleware {
    /// Handle an incoming request.
    ///
    /// Code before `next(request).await` runs before the route's handler:
    /// return a response there to stop the request. Code after it can
    /// change the response the handler returned.
    async fn handle(&self, request: Request, next: Next) -> Response {
        next(request).await
    }
}
```

### With `--test`

`--test` also writes `tests/<path>_middleware.rs`
(`tests/admin_ensure_role_middleware.rs` for `Admin/EnsureRole`). The test
puts the middleware in front of a route, sends a request through
`TestClient`, and asserts the route's response comes back. It imports
the middleware from your library crate, so run the command from the
project root, where `Cargo.toml` and `src/lib.rs` are:

```rust
// tests/admin_ensure_role_middleware.rs
use my_app::middleware::admin::EnsureRoleMiddleware;
use suprnova::testing::TestClient;
use suprnova::{MiddlewareRegistry, Request, Response, Router};

async fn handled(_req: Request) -> Response {
    suprnova::http::text("handled")
}

#[tokio::test]
async fn admin_ensure_role_middleware_passes_the_request_to_the_route() {
    let router = Router::new().get("/", handled);
    let client = TestClient::new(router, MiddlewareRegistry::new().append(EnsureRoleMiddleware));

    client.get("/").send().await.assert_ok().assert_see("handled");
}
```

When you give the middleware logic, change the test to match it. See
[HTTP Tests](http-tests.md) for the client.

### What it wires

1. Writes `src/middleware/<snake>.rs`, or for a nested name the same file
   under `src/middleware/<dir>/`. An existing file is never overwritten.
2. Adds `mod <snake>;` + `pub use <snake>::<StructName>;` to the module
   file of that directory (`src/middleware/mod.rs`, or
   `src/middleware/admin/mod.rs`), creating it if needed.
3. For a nested name, declares each directory in the one above it:
   `pub mod admin;` in `src/middleware/mod.rs`.
4. With `--test`, writes the test under `tests/`.
5. Prints both the per-route shape
   (`.get("/path", handler).middleware(AuthMiddleware)`) and the
   global shape (`global_middleware!(crate::middleware::AuthMiddleware)`
   in `bootstrap.rs`).

Every file is checked before anything is written, and the command writes
all of them or none.

See [Middleware](middleware.md) for the full chain semantics,
ordering, and the global vs per-route distinction.

---

## make:command

Scaffold a console command - a `#[derive(clap::Parser, Command)]`
struct that the per-project `console` binary picks up via `inventory`
at link time. The default body prints a line with
`suprnova::console::line` that says the command is not implemented, so the
command runs immediately and a test can read what it prints.

```bash
suprnova make:command CleanCache
suprnova make:command mail:send
suprnova make:command clean-cache
```

Naming follows three rules:

- Inputs containing `:` are used verbatim as the registered command
  name (Laravel namespace style: `db:seed`, `mail:send`).
- Otherwise the snake-cased fn name is kebabbed for the registered
  name (`CleanCache` → command `clean-cache`).
- The Rust file and struct are always snake-cased / PascalCased
  forms of the same identifier.

### Generated file

```rust
// src/commands/clean_cache.rs
use async_trait::async_trait;
use clap::Parser;
use suprnova::{Command, FrameworkError, TypedCommand};

#[derive(Parser, Command, Debug)]
#[console(name = "clean-cache", description = "TODO: describe what clean-cache does")]
pub struct CleanCache {
    // Add clap-derive args here.
}

#[async_trait]
impl TypedCommand for CleanCache {
    async fn run(self) -> Result<(), FrameworkError> {
        suprnova::console::line("clean-cache: not yet implemented");
        Ok(())
    }
}
```

### What it wires

1. Writes `src/commands/<snake>.rs`.
2. Adds `pub mod <snake>;` to `src/commands/mod.rs` (creates it if
   needed).
3. Warns loudly if `src/lib.rs` is missing `pub mod commands;` - the
   command won't link into the console binary without it.
4. Prints the run command: `cargo run --bin console -- clean-cache`.

See [Console](console.md) for the full typed-command surface, the
`#[command]` shorthand for argv-only handlers, and the per-project
console binary's role.

---

## live:make

Scaffold a Live component: a server-owned island whose typed actions
arrive over the Live protocol and whose re-rendered view is morphed in
place by the shipped browser runtime.

```bash
suprnova live:make Counter
suprnova live:make todo-list
suprnova live:make Counter --dry-run
```

Names must be plain ASCII identifiers in any of `Counter`, `TodoList`,
`todo-list`, or `todo_list` form; the file and module are snake-cased,
the struct is PascalCased, and the registered component name is
`<package>.<kebab>` (for a package named `demo-app`: `demo-app.counter`).
Rust keywords, separators, dots, and non-ASCII input are rejected before
anything is written.

### Generated file

```rust
// src/live/counter.rs
use suprnova::live::{LiveComponent, live};

/// A counter island rendered by `live/counter.html`.
#[derive(LiveComponent)]
#[live(name = "demo-app.counter", view = "live/counter.html")]
pub struct Counter {
    /// Current count, exposed to the view.
    #[public]
    count: u64,
}

#[live]
impl Counter {
    /// Increments the counter in response to `live:click="increment"`.
    #[action]
    pub fn increment(&mut self) {
        self.count += 1;
    }
}
```

```html
<!-- templates/live/counter.html -->
<div>
<p>Count: {{ count }}</p>
<button type="button" live:click="increment">Increment</button>
</div>
```

### What it wires

1. Validates every target path first and refuses traversal and
   symlinks; if the component file or the view already exists, it
   warns and writes nothing at all.
2. Writes `src/live/<snake>.rs` and `templates/live/<snake>.html`
   atomically; if any write fails, every file the run created or changed
   is rolled back, and any file that could not be restored is named in
   the error instead of being reported as untouched.
3. Inserts `pub mod <snake>;` and `.register::<snake::Pascal>()?` into
   the `registry()` builder in `src/live/mod.rs`. Every project created
   by `suprnova new` ships that module with an empty registry, a
   `routes()` function that installs the guarded reserved Live routes,
   and a bootstrap that binds the registry; an older project gets the
   same module created on first use.
4. Adds `pub mod live;` to `src/lib.rs` when it is missing.
5. Prints the bootstrap line that binds the registry, then the check
   command: `suprnova live:check`.

In a project that predates the Live module, bind the registry during
bootstrap and install the routes from `cmd/main.rs` by hand:

```rust
suprnova::App::singleton(crate::live::registry().expect("Live registry"));
```

```rust
.try_routes(|| live::routes(routes::register()))
```

---

## make:error

Scaffold a domain error - a unit struct annotated with
`#[domain_error]` so it carries an HTTP status, a `Display` message,
and a `From<…> for FrameworkError` impl out of the box.

```bash
suprnova make:error UserNotFound
suprnova make:error PaymentFailed
```

The name is PascalCased for the struct and snake-cased for the file.
The default status is 500 and the message is the sentence-cased
struct name - change both attributes in the generated file to match
the situation.

### Generated file

```rust
// src/errors/user_not_found.rs
use suprnova::domain_error;

#[domain_error(status = 500, message = "User not found")]
pub struct UserNotFound;
```

Change `status = 500` to whatever fits - `404` for not-found,
`402` for payment-required, `403` for forbidden - and edit the
message string. For richer payloads, add named fields to the struct
and reference them in the message via interpolation in a hand-rolled
`Display` impl (drop the `#[domain_error]` macro at that point).

### What it wires

1. Writes `src/errors/<snake>.rs`.
2. Adds `pub mod <snake>;` to `src/errors/mod.rs` (creates it if
   needed).
3. Warns about declaring `mod errors;` in `src/lib.rs` if the
   `errors/` directory was created fresh.

### Using it

Inside a handler returning `Response`, lift the domain type to a
`FrameworkError` so `?` short-circuits cleanly:

```rust
use crate::errors::user_not_found::UserNotFound;
use suprnova::FrameworkError;

#[handler]
pub async fn show(req: Request) -> Response {
    let id = req.param("id")?;
    let user = find_user(id).await
        .ok_or_else(|| FrameworkError::from(UserNotFound))?;
    json_response!({ "user": user })
}
```

The [Errors](errors.md) chapter covers the full custom-error story,
including when to use `#[domain_error]` vs `AppError::bad_request(…)`
vs a hand-rolled `HttpError` impl.

---

## make:task

Scaffold a scheduled task - a unit struct that implements
`suprnova::Task` and prints structured start/finish lines so the
scaffold logs progress before you fill in the real body.

```bash
suprnova make:task CleanupLogs
suprnova make:task SendReminders
```

The name is PascalCased; a `Task` suffix is appended if missing.
The file is the snake-cased struct name, e.g. `CleanupLogs` →
`src/tasks/cleanup_logs_task.rs`.

### Generated file

```rust
// src/tasks/cleanup_logs_task.rs
use std::time::Instant;

use async_trait::async_trait;
use suprnova::{Task, TaskResult};

pub struct CleanupLogsTask;

impl CleanupLogsTask {
    pub fn new() -> Self {
        Self
    }
}

impl Default for CleanupLogsTask {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl Task for CleanupLogsTask {
    async fn handle(&self) -> TaskResult {
        let started_at = Instant::now();
        println!("[CleanupLogsTask] task started");

        // Replace this with the real job.

        println!(
            "[CleanupLogsTask] task finished in {} ms",
            started_at.elapsed().as_millis(),
        );
        Ok(())
    }
}
```

### What it wires

The first `make:task` invocation does heavier wiring than the other
generators - it creates the scheduler's surface in the project from
scratch:

1. Creates `src/tasks/` and `src/tasks/mod.rs` if missing.
2. Creates `src/schedule.rs` (the `register(schedule: &mut Schedule)`
   entrypoint) if missing.
3. Declares `pub mod schedule;` and `pub mod tasks;` in `src/lib.rs`.
4. Inserts `.schedule(<crate>::schedule::register)` into the
   `Application::new()` chain in `cmd/main.rs` or `src/main.rs`,
   immediately before `.run()`.
5. Writes `src/tasks/<snake>.rs` and adds it to `src/tasks/mod.rs`.

Subsequent invocations skip the steps that already ran.

### Registering the task

Open `src/schedule.rs` and add a registration call with the fluent
schedule API:

```rust
use suprnova::Schedule;
use crate::tasks::CleanupLogsTask;

pub fn register(schedule: &mut Schedule) {
    schedule.add(
        schedule.task(CleanupLogsTask::new())
            .daily()
            .at("03:00")
            .name("cleanup:logs")
            .description("Removes old log files daily"),
    );
}
```

Then run the scheduler:

```bash
suprnova schedule:work   # daemon - checks every minute
suprnova schedule:run    # one-shot - typically called by cron
suprnova schedule:list   # show every registered task
```

A task is a type that implements `Task`, whose only method is `handle`. The
name of a task and the times it runs at are set where you register it, not on
the trait. The scaffolded `src/tasks/mod.rs` carries a doc comment that shows
the same pair: a `Task` in `src/tasks/` and its registration in
`src/schedule.rs`.

See [Scheduling](scheduling.md) for the full task surface (`hourly`,
`weekly`, `cron(...)`, `without_overlapping`, `on_one_server`,
timezone handling) and [CLI Scheduling](cli-scheduling.md) for the
run-as-cron vs run-as-daemon trade.

---

## make:view

Scaffold a checked view, Laravel's `make:view`: an Askama template under
`templates/` and a `#[suprnova::view]` struct that names it. The macro
compiles the template against the struct, so a name the template reads
that the struct lacks fails the build.

```bash
suprnova make:view welcome
suprnova make:view admin.dashboard
suprnova make:view admin/dashboard --test
```

`admin.dashboard` and `admin/dashboard` name the same view, as in
Laravel: the template is `templates/admin/dashboard.html`, and the struct
is `DashboardView` in `src/views/admin/dashboard.rs`, reached as
`crate::views::admin::dashboard::DashboardView`. Each segment is letters,
digits, `_` and `-`, starting with a letter; the template path keeps the
segment as you write it, and the module name is its snake case
(`reports.user-summary` → `templates/reports/user-summary.html`,
`src/views/reports/user_summary.rs`).

### Generated files

```html
<!-- templates/admin/dashboard.html -->
<div>
    <h1>{{ title }}</h1>
</div>
```

```rust
// src/views/admin/dashboard.rs
/// The data `templates/admin/dashboard.html` renders.
#[suprnova::view(path = "admin/dashboard.html")]
pub struct DashboardView {
    /// The page heading.
    pub title: String,
}
```

Render it from a handler with `ViewTemplate::render_view`, and return the
HTML:

```rust
use suprnova::view::ViewTemplate;
use suprnova::{FrameworkError, HttpResponse, Request, Response};

use crate::views::admin::dashboard::DashboardView;

pub async fn dashboard(_req: Request) -> Response {
    let mut html = String::new();
    DashboardView { title: "Dashboard".into() }
        .render_view(&mut html)
        .map_err(|failure| FrameworkError::internal(format!("dashboard view: {failure:?}")))?;
    Ok(HttpResponse::html(html))
}
```

### With `--test`

`--test` also writes `tests/<path>_view.rs`
(`tests/admin_dashboard_view.rs`), which renders the view with a title
and asserts the title is in the HTML. It imports the view from your
library crate, so run the command from the project root.

### What it wires

1. Refuses to overwrite: if the template, the view file or (with
   `--test`) the test exists, the command says which and writes nothing.
   Pass `--force` to overwrite them.
2. Writes `templates/<path>.html` and `src/views/<path>.rs`.
3. Declares the modules on the way: `pub mod views;` in `src/lib.rs`,
   `pub mod admin;` in `src/views/mod.rs` and `pub mod dashboard;` in
   `src/views/admin/mod.rs`, creating each module file it needs. A
   declaration that is already there is left alone.
4. With `--test`, writes the test under `tests/`.

Every file is checked before anything is written, and the command writes
all of them or none.

---

## make:inertia

Scaffold either an Inertia page component (default) or a typed Data
struct (`--data`), depending on the flag. The page generator detects
the frontend framework (Svelte 5, React 19, Vue 3.5) from `.env` and
emits the matching file extension.

### Page mode (default)

```bash
suprnova make:inertia About
suprnova make:inertia UserProfile
suprnova make:inertia Admin/Users --test
```

The name is PascalCased and the suffix `Page` is appended if missing,
so `About` → `AboutPage`. The file lands in `frontend/src/pages/`
with the per-frontend extension: `AboutPage.svelte` for Svelte,
`AboutPage.tsx` for React, `AboutPage.vue` for Vue.

A nested name writes under the same directory of `frontend/src/pages/`,
and the component is named with it: `Admin/Users` writes
`frontend/src/pages/Admin/UsersPage.svelte`, rendered as
`"Admin/UsersPage"`. Directory segments keep the spelling you give them.

An existing page is kept: the command says so and writes nothing. Pass
`--force` to overwrite it.

Example (Svelte):

```svelte
<!-- frontend/src/pages/AboutPage.svelte -->
<div class="font-sans p-8 max-w-xl mx-auto">
  <h1 class="text-3xl font-bold">AboutPage</h1>
  <p class="mt-2">
    Edit <code class="bg-gray-100 px-1 rounded">frontend/src/pages/AboutPage.svelte</code> to get started.
  </p>
</div>
```

Render it from a controller:

```rust
inertia_response!(&req, "AboutPage", props)
```

`--test` also writes `tests/<path>.rs` (`tests/admin_users_page.rs` for
`Admin/Users`). The test answers a request with the page through
`TestClient` and asserts that the response names the component and that
its file exists under `frontend/src/pages`:

```rust
// tests/admin_users_page.rs
use suprnova::testing::TestClient;
use suprnova::{inertia_response, MiddlewareRegistry, Request, Response, Router};

async fn page(req: Request) -> Response {
    inertia_response!(&req, "Admin/UsersPage", {})
}

#[tokio::test]
async fn admin_users_page_renders() {
    let client = TestClient::new(Router::new().get("/", page), MiddlewareRegistry::new());

    client
        .get("/")
        .inertia()
        .send()
        .await
        .assert_ok()
        .assert_inertia()
        .component_exists("Admin/UsersPage", true);
}
```

`--force` overwrites the test too. `--test` and `--data` cannot be
combined.

See [Frontend Pages](frontend-pages.md) and
[Inertia Responses](frontend-inertia-responses.md) for the bridge
between controllers and pages, partial reloads, and shared props.

### Data struct mode (`--data`)

```bash
suprnova make:inertia UserProps --data
```

Emits a `#[derive(Data, Validate)]` struct in `src/props/`, and warns
when it creates the directory, since `src/lib.rs` has to declare
`pub mod props;` for the struct to be reachable:

```rust
// src/props/user_props.rs
use suprnova::Data;
use validator::Validate;

#[derive(Data, Validate)]
pub struct UserProps {
    pub id: i64,
    // Add fields here.
    //
    // Available field attributes:
    //   #[data(input_only)] - accepted on Deserialize, omitted from Serialize
    //   #[data(output_only)] - rejected on Deserialize, included in Serialize
    //   #[data(allow_include)] - registers as ?include=-eligible (default-deny)
    //
    // For PATCH endpoints, use suprnova::data::Field<T> to distinguish
    // absent from null. For lazy outbound fields, use suprnova::inertia::Prop<T>.
}
```

Use it in a controller to validate request bodies:

```rust
let dto: UserProps = req.validate_json().await?;
```

---

## make:migration

Scaffold a timestamped SeaORM migration file. Covered in detail in
[CLI Migrations](cli-migrations.md), which also walks the
`migrate` / `migrate:rollback` / `migrate:status` / `migrate:fresh` /
`db:sync` commands. The short form:

```bash
suprnova make:migration create_users_table
```

The migration name is preserved verbatim and prefixed with a
`YYYYMMDDHHMMSS_` stamp so files sort chronologically. The generated
file lands in `migrations/`.

The generated file uses SeaORM's builder. The
[schema builder](migrations.md#the-schema-builder) is the alternative you write
by hand. See [Migrations](migrations.md) for both forms and
[Database Testing](database-testing.md) for the `TestDatabase::fresh`
pattern that runs migrations against an isolated database per test.

---

## The one-file generators

Twenty-one generators write one file from a stub, as Laravel's artisan
commands of the same names do: `make:factory`, `make:seeder`, `make:cast`,
`make:channel`, `make:class`, `make:enum`, `make:event`, `make:listener`,
`make:job`, `make:job-middleware`, `make:mail`, `make:notification`,
`make:observer`, `make:policy`, `make:provider`, `make:resource`,
`make:rule`, `make:scope`, `make:test`, `make:trait` and `make:interface`.
They share these rules:

- **The name is a Rust identifier**: ASCII letters, digits and `_`,
  starting with a letter. A name whose module would be a Rust keyword
  (`Type` would be the module `type`) is refused too. A refused name exits
  with status 1 and a message that says why, and nothing is written. A
  name in snake case is read as words (`order_shipped` is `OrderShipped`);
  any other keeps its spelling, with the first letter upper-cased.
- **One file**, `src/<directory>/<snake>.rs`, in the directory each section
  below names. `make:class` writes `src/<snake>.rs`, and `make:test` writes
  `tests/<snake>.rs`.
- **The module is declared**: `pub mod <directory>;` in `src/lib.rs`, and
  `pub mod <snake>;` in the directory's `mod.rs`, which the generator
  creates when the project has none. A declaration that is already there
  is left alone. `make:test` declares nothing, because every file under
  `tests/` is a crate of its own.
- **An existing file is kept.** The command says the file exists, writes
  nothing and exits 0. Pass `--force` to write the stub over it.
- **The path is printed**: `Created <path>` or `Updated <path>` for each
  file the run writes, then the line that wires the new item in.
- **No clash with the stub's imports or Rust's prelude.** `make:rule Rule`
  is refused, because the stub imports the `Rule` trait under that name,
  and `make:mail Option` is refused, because a type named `Option` would
  shadow the `Option<String>` the stub's own signatures use. The same goes
  for a `--model` or `--event` of such a name.

Every file is checked before anything is written, and the command writes
all of them or none. Each stub compiles in a project `suprnova new`
creates.

```bash
suprnova make:event OrderShipped
suprnova make:listener SendShipmentNotification --event OrderShipped
suprnova make:job ProcessPodcast --force
```

```text
  ✓ Created src/events/order_shipped.rs
  ✓ Updated src/lib.rs
  ✓ Created src/events/mod.rs
```

---

## make:factory

Writes `src/factories/<snake>.rs`, a [model factory](eloquent-factories.md):
a marker struct and its `Factory` impl. A `Factory` suffix is appended when
the name lacks one, and the model is the name without it: `make:factory
Post` writes `PostFactory` for `crate::models::post::Post`. `--model <Model>`
names another model. When `src/models/<snake>.rs` is missing, the command
warns, since the project does not compile until the model exists.

```bash
suprnova make:factory Post
```

```rust
// src/factories/post_factory.rs
use suprnova::Factory;

use crate::models::post::Post;

pub struct PostFactory;

impl Factory for PostFactory {
    type Model = Post;

    fn definition() -> Post {
        Post {
            ..Default::default()
        }
    }
}
```

Set the fields a new model needs in `definition`, with a `suprnova::Faker`
value where one should vary. Every `#[suprnova::model]` struct implements
`Default`, so a field you leave out keeps its default.

---

## make:seeder

Writes `src/seeders/<snake>.rs`, a [seeder](seeding.md) that `db:seed` runs.
A `Seeder` suffix is appended when the name lacks one.

```bash
suprnova make:seeder Users
```

```rust
// src/seeders/users_seeder.rs
use suprnova::{FrameworkError, Seeder, async_trait};

pub struct UsersSeeder;

#[async_trait]
impl Seeder for UsersSeeder {
    fn name() -> &'static str {
        "UsersSeeder"
    }

    async fn run() -> Result<(), FrameworkError> {
        Ok(())
    }
}
```

Register it in `src/bootstrap.rs` with
`suprnova::seed::register::<crate::seeders::users_seeder::UsersSeeder>();`,
then run it with `suprnova db:seed UsersSeeder`.

---

## make:cast

Writes `src/casts/<snake>.rs`, a custom attribute
[cast](eloquent-mutators.md): a unit struct that implements `Cast`. The stub
stores the value as it is, as Laravel's cast stub returns `$value`; change
`Runtime`, `Storage` and the two conversions to the types you need.

```bash
suprnova make:cast AsMoney
```

```rust
// src/casts/as_money.rs
use suprnova::{Cast, FrameworkError};

pub struct AsMoney;

impl Cast for AsMoney {
    type Runtime = String;
    type Storage = String;

    fn to_storage(value: &String) -> Result<String, FrameworkError> {
        Ok(value.clone())
    }

    fn from_storage(stored: &String) -> Result<String, FrameworkError> {
        Ok(stored.clone())
    }
}
```

Name it on a model field:
`#[model(casts = { amount = crate::casts::as_money::AsMoney })]`.

---

## make:channel

Writes `src/broadcasting/<snake>.rs`, a private
[broadcast channel](broadcasting.md#channels) and who may join it. The
channel name is the type's words without `Channel`, joined by dots:
`OrderUpdates` is `order.updates`. Its `authorize` denies every subscriber
until you write the rule, as Laravel's channel stub does; `req.auth_user_id()`
names the user the session authenticated on the WebSocket upgrade.

```bash
suprnova make:channel OrderUpdates
```

```rust
// src/broadcasting/order_updates.rs
use suprnova::async_trait;
use suprnova::broadcasting::{Channel, ChannelParams, PrivateChannel};
use suprnova::http::Request;
use suprnova::serde_json::Value;

pub struct OrderUpdates;

#[async_trait]
impl Channel for OrderUpdates {
    fn name(&self) -> &'static str {
        "order.updates"
    }

    async fn authorize(&self, _req: &Request, _params: &ChannelParams, _data: &Value) -> bool {
        false
    }
}

impl PrivateChannel for OrderUpdates {}
```

Register it in the `ChannelRegistry` your bootstrap binds:
`registry.register(OrderUpdates);`.

---

## make:class

Writes `src/<snake>.rs` and declares it in `src/lib.rs`, as Laravel's
`make:class` writes under `app/`: a plain struct with a doc comment and an
`impl` block. The names `Lib` and `Main` are refused, because they would
write the crate's own root.

```bash
suprnova make:class Invoice
```

```rust
// src/invoice.rs
/// A plain Rust type: give `Invoice` the fields and methods it needs.
#[derive(Debug, Default)]
pub struct Invoice;

impl Invoice {
    /// Create a new `Invoice`.
    pub fn new() -> Self {
        Self
    }
}
```

---

## make:enum

Writes `src/enums/<snake>.rs`, an enum with no variants yet, as Laravel's
enum stub has no cases. Write one variant per case.

```bash
suprnova make:enum Status
```

```rust
// src/enums/status.rs
/// The values a `Status` can take: write one variant per case.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Status {}
```

---

## make:event

Writes `src/events/<snake>.rs`, an [event](events.md): a struct whose fields
every listener receives, and its `Event` impl.

```bash
suprnova make:event OrderShipped
```

```rust
// src/events/order_shipped.rs
use suprnova::Event;

#[derive(Debug, Clone)]
pub struct OrderShipped {}

impl Event for OrderShipped {
    fn event_name() -> &'static str {
        "OrderShipped"
    }
}
```

Dispatch it with `EventFacade::dispatch(OrderShipped {}).await?`.

---

## make:listener

Writes `src/listeners/<snake>.rs`, an [event listener](events.md). With
`--event <Event>`, it handles that event, imported from
`crate::events::<snake>`; the command warns when that file is missing.
Without `--event`, it handles any event it is registered for, as Laravel's
listener stub takes `object $event`.

```bash
suprnova make:listener SendShipmentNotification --event OrderShipped
```

```rust
// src/listeners/send_shipment_notification.rs
use suprnova::{FrameworkError, Listener, async_trait};

use crate::events::order_shipped::OrderShipped;

pub struct SendShipmentNotification;

#[async_trait]
impl Listener<OrderShipped> for SendShipmentNotification {
    async fn handle(&self, _event: &OrderShipped) -> Result<(), FrameworkError> {
        Ok(())
    }
}
```

The listener of any event implements `Listener<E>` for every `E: Event`.
Register a listener in `src/bootstrap.rs`:

```rust
EventFacade::listen::<OrderShipped, _>(Arc::new(SendShipmentNotification)).await;
```

---

## make:job

Writes `src/jobs/<snake>.rs`, a [queued job](queues.md): a struct whose
fields go into the queue payload, and its `Job` impl.

```bash
suprnova make:job ProcessPodcast
```

```rust
// src/jobs/process_podcast.rs
use serde::{Deserialize, Serialize};
use suprnova::{FrameworkError, Job, async_trait};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProcessPodcast {}

#[async_trait]
impl Job for ProcessPodcast {
    fn job_name() -> &'static str {
        "ProcessPodcast"
    }

    async fn handle(self) -> Result<(), FrameworkError> {
        Ok(())
    }
}
```

Register it at boot with
`suprnova::queue::worker::register_job::<ProcessPodcast>();` and push it
with `Queue::push(ProcessPodcast {}).await?`.

---

## make:job-middleware

Writes `src/jobs/middleware/<snake>.rs`, as Laravel writes under
`app/Jobs/Middleware`: [job middleware](queues.md#job-middleware) that passes
the job on. It declares `pub mod jobs;` in `src/lib.rs` and
`pub mod middleware;` in the `jobs` module when they are missing.

```bash
suprnova make:job-middleware RateLimitedByUser
```

```rust
// src/jobs/middleware/rate_limited_by_user.rs
use suprnova::{
    Envelope, FrameworkError, JobMiddleware, JobMiddlewareNext, JobOutcome, async_trait,
};

pub struct RateLimitedByUser;

#[async_trait]
impl JobMiddleware for RateLimitedByUser {
    async fn handle(
        &self,
        envelope: Envelope,
        next: JobMiddlewareNext,
    ) -> Result<JobOutcome, FrameworkError> {
        next(envelope).await
    }
}
```

Return it from a job's `middleware()`: `vec![Arc::new(RateLimitedByUser)]`.

---

## make:mail

Writes `src/mail/<snake>.rs`, a [mailable](mail.md). The subject is the
type's words, as Laravel's mail stub uses the class name's headline, and the
bodies are Tera templates whose context is the struct's fields.

```bash
suprnova make:mail OrderShipped
```

```rust
// src/mail/order_shipped.rs
use serde::{Deserialize, Serialize};
use suprnova::async_trait;
use suprnova::mail::Mailable;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OrderShipped {}

#[async_trait]
impl Mailable for OrderShipped {
    fn mailable_name() -> &'static str {
        "OrderShipped"
    }

    fn subject(&self) -> String {
        "Order Shipped".to_string()
    }

    fn html_template_source(&self) -> Option<String> {
        Some("<p>Order Shipped</p>".to_string())
    }

    fn text_template_source(&self) -> Option<String> {
        Some("Order Shipped".to_string())
    }
}
```

Send it with `Mail::to("user@example.com").send(OrderShipped {}).await?`.

---

## make:notification

Writes `src/notifications/<snake>.rs`, a [notification](notifications.md)
sent on the `mail` channel, with the mail rendering
`#[derive(NotificationMailable)]` builds from its `#[mail(...)]` attribute.

```bash
suprnova make:notification InvoicePaid
```

```rust
// src/notifications/invoice_paid.rs
use serde::{Deserialize, Serialize};
use suprnova::serde_json;
use suprnova::{Notification, NotificationMailable};

#[derive(Debug, Clone, Serialize, Deserialize, NotificationMailable)]
#[mail(
    subject = "Invoice Paid",
    html = "<p>The introduction to the notification.</p><p>Thank you for using our application!</p>",
    text = "The introduction to the notification.\nThank you for using our application!"
)]
pub struct InvoicePaid {}

impl Notification for InvoicePaid {
    fn notification_name() -> &'static str {
        "InvoicePaid"
    }

    fn channels(&self) -> Vec<&'static str> {
        vec!["mail"]
    }

    fn data(&self) -> serde_json::Value {
        serde_json::json!({})
    }
}
```

Register its mail renderer at boot with
`suprnova::register_mail_renderer::<InvoicePaid>()?;`, then send it with
`Notify::send(&user, &InvoicePaid {}).await?`.

---

## make:observer

Writes `src/observers/<snake>.rs`, a model [observer](eloquent.md#observers-and-lifecycle-events)
with the `created`, `updated`, `deleted`, `restored` and `force_deleted`
hooks Laravel's observer stub has. An `Observer` suffix is appended when the
name lacks one, and the model is the name without it; `--model <Model>`
names another. `#[suprnova::observer]` installs it when the application
boots. The attribute names the model by its full path, because the macro
reaches the model's events through the module the model is in.

```bash
suprnova make:observer User
```

```rust
// src/observers/user_observer.rs
use suprnova::{FrameworkError, Observer, async_trait};

use crate::models::user::User;

pub struct UserObserver;

#[suprnova::observer(crate::models::user::User)]
#[async_trait]
impl Observer<User> for UserObserver {
    async fn created(&self, _user: &User) -> Result<(), FrameworkError> {
        Ok(())
    }

    async fn updated(&self, _previous: &User, _current: &User) -> Result<(), FrameworkError> {
        Ok(())
    }

    // `deleted`, `restored` and `force_deleted` follow the same shape.
}
```

---

## make:policy

Writes `src/policies/<snake>.rs`, a `#[policy]` for a model with the seven
abilities of Laravel's model policy stub. A `Policy` suffix is appended when
the name lacks one, and the model is the name without it; `--model <Model>`
names another. The user is `crate::models::user::User`. Every method
denies until you write its rule, as Laravel's stub returns `false`.

```bash
suprnova make:policy Note
```

```rust
// src/policies/note_policy.rs
use suprnova::policy;

use crate::models::user::User;
use crate::models::note::Note;

pub struct NotePolicy;

#[policy(User, Note)]
impl NotePolicy {
    fn view_any(_user: &User, _note: &Note) -> bool {
        false
    }

    fn view(_user: &User, _note: &Note) -> bool {
        false
    }

    // `create`, `update`, `delete`, `restore` and `force_delete` follow.
}
```

`update` registers the gate `update-note`; see
[Authorization](authorization.md#policies-with-policy). A policy of `User`
itself names its second parameter `_model`, as Laravel's stub does.

---

## make:provider

Writes `src/providers/<snake>.rs`: a `pub async fn register()` for a group
of service registrations, which your bootstrap calls.

```bash
suprnova make:provider PaymentServiceProvider
```

```rust
// src/providers/payment_service_provider.rs
pub async fn register() {
    // `App::singleton`, `App::bind` and `EventFacade::listen` calls go here.
}
```

Call it from `register` in `src/bootstrap.rs`:

```rust
crate::providers::payment_service_provider::register().await;
```

### Why Suprnova diverges

Laravel's `make:provider` writes a `ServiceProvider` class with `register`
and `boot` methods and adds it to `bootstrap/providers.php`. Suprnova has no
provider class: [Application Bootstrap](bootstrap.md#why-suprnova-diverges)
explains why `register` and `register_http_stack` replace the provider
list. What plays a provider's part is a public `register` function that
`src/bootstrap.rs` calls, so that is the stub. The command does not edit
your bootstrap, because where the call goes in the boot order is your
decision; it prints the line to add.

---

## make:resource

Writes `src/resources/<snake>.rs`, a [JSON:API resource](eloquent-resources.md):
a `#[derive(Data)]` struct with `#[json_resource]`. A `Resource` suffix is
appended when the name lacks one. The JSON:API type is the plural of the
name's words in kebab case: `User` is `users`, `UserProfile` is
`user-profiles`.

```bash
suprnova make:resource User
```

```rust
// src/resources/user_resource.rs
use suprnova::Data;
use validator::Validate;

#[derive(Debug, Clone, Data, Validate)]
#[json_resource("users")]
pub struct UserResource {
    pub id: u64,
}
```

Add the attributes as fields, and render it with
`Resource::single(resource).render().await` or `Resource::collection`.

---

## make:rule

Writes `src/rules/<snake>.rs`, a custom [validation rule](validation.md#writing-your-own-rule)
that passes every value until you write its check, as Laravel's rule stub
does.

```bash
suprnova make:rule Uppercase
```

```rust
// src/rules/uppercase.rs
use suprnova::{Rule, ValidationMessage};

pub struct Uppercase;

impl Rule for Uppercase {
    fn passes(&self, _value: &str) -> Result<(), ValidationMessage> {
        Ok(())
    }
}
```

Use it in a `validate!` row: `name => Required, Uppercase;`.

---

## make:scope

Writes `src/scopes/<snake>.rs`, a [global scope](eloquent.md#global-scopes)
that adds nothing to the query yet. A `Scope` suffix is appended when the
name lacks one. A scope's name does not say which model it scopes, so the
model is `User` unless `--model <Model>` names another.

```bash
suprnova make:scope Published --model Post
```

```rust
// src/scopes/published_scope.rs
use suprnova::{Builder, GlobalScope};

use crate::models::post::Post;

pub struct PublishedScope;

impl GlobalScope<Post> for PublishedScope {
    fn apply(&self, query: Builder<Post>) -> Builder<Post> {
        query
    }
}
```

Register it at boot: `ScopeRegistry::register::<Post, _>(PublishedScope);`.

---

## make:test

Writes `tests/<snake>.rs`, an integration test that sends a request through
`TestClient` and asserts the answer, as Laravel's feature test stub does.
It declares no module. See [HTTP Tests](http-tests.md) for the client.

```bash
suprnova make:test UserTest
cargo test --test user_test
```

```rust
// tests/user_test.rs
use suprnova::testing::TestClient;
use suprnova::{MiddlewareRegistry, Request, Response, Router};

async fn home(_req: Request) -> Response {
    suprnova::http::text("Hello")
}

#[tokio::test]
async fn example() {
    let client = TestClient::new(Router::new().get("/", home), MiddlewareRegistry::new());

    client.get("/").send().await.assert_ok().assert_see("Hello");
}
```

---

## make:trait

Writes `src/concerns/<snake>.rs`, as Laravel writes traits under
`app/Concerns`: a trait with a default method, which every implementor gets
without writing it.

```bash
suprnova make:trait HasUuid
```

```rust
// src/concerns/has_uuid.rs
pub trait HasUuid {
    fn type_name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }
}
```

---

## make:interface

Writes `src/contracts/<snake>.rs`, as Laravel writes interfaces under
`app/Contracts`: a trait whose methods are all required, with `Send + Sync`
so an implementor can be bound in the container as `Arc<dyn PaymentGateway>`.

```bash
suprnova make:interface PaymentGateway
```

```rust
// src/contracts/payment_gateway.rs
pub trait PaymentGateway: Send + Sync {
    fn name(&self) -> &str;
}
```

### Why Suprnova diverges

PHP has two constructs where Rust has one. A PHP trait carries method
bodies that are copied into the class that uses it; a PHP interface names
methods without bodies. Rust's `trait` does both: a method with a body is a
default that an implementor may override, and a method without one is
required. So `make:trait` and `make:interface` both write a `trait`.
`make:trait` gives it a default method and `make:interface` gives it
required methods only, and each goes in the directory Laravel uses for its
construct.

---

## make:model

There is no `make:model`. Write the model by hand with `#[suprnova::model]`,
or let `db:sync --regenerate-models` write it from the schema after a
migration runs. See [Eloquent](eloquent.md) and
[CLI Migrations](cli-migrations.md).

### Why Suprnova diverges

Laravel's `make:model` writes an empty class, because Eloquent reads the
columns from the database at run time. A Suprnova model is a struct whose
fields are its columns, checked when the crate compiles, so an empty model
is not a model. The struct has to name the columns, which either you or
`db:sync` know and a generator does not. `make:migration` writes the schema
change, and `db:sync` turns the migrated schema into model files.

---

## generate-types

Emit TypeScript interfaces from every Rust struct annotated with
`#[derive(InertiaProps)]`. The dev server runs this automatically; the
standalone command is for CI checks and one-shot regenerations.

```bash
suprnova generate-types [--output <PATH>] [--watch]
```

| Option | Default | Description |
|---|---|---|
| `-o, --output <PATH>` | `frontend/src/types/inertia-props.ts` | Output file path |
| `-w, --watch` | off | Watch source files and regenerate on change |

```bash
# One-shot
suprnova generate-types

# Watch mode (useful when you don't want to run the full dev server)
suprnova generate-types --watch

# Custom output path
suprnova generate-types --output frontend/src/types/props.ts
```

A Rust shape on the left produces a TypeScript interface on the right:

```rust
#[derive(InertiaProps)]
pub struct UserPageProps {
    pub user: User,
    pub posts: Vec<Post>,
}
```

```typescript
export interface UserPageProps {
    user: User;
    posts: Post[];
}
```

See [Frontend TypeScript Types](frontend-typescript-types.md) for the
full mapping table (enums, options, dates, nested structs) and the
override hooks.

---

### Why Suprnova diverges

Laravel's `php artisan make:*` drops a file in the right directory
and that's it - PSR-4 autoloading picks the new class up the next
time the framework boots. Rust has no equivalent. A file at
`src/foo/bar.rs` isn't compiled into the crate until `src/foo/mod.rs`
declares `pub mod bar;`, and the parent directory has to be wired up
the same way in `src/lib.rs`.

So every `suprnova make:*` generator does two things instead of one:
it writes the new file *and* edits the closest `mod.rs` (and, for
`make:task`, `src/lib.rs` and `cmd/main.rs` as well, and for `make:view`,
`src/lib.rs`). A nested name declares every module on the way to its
file, since each directory is a module of its own.

Laravel's `--test` writes a PHPUnit or Pest test under `tests/Feature`.
Suprnova's writes a Rust integration test under `tests/`, one file per
generated item, which imports the item from your library crate. That's why every generator prints a `Created src/.../mod.rs`
or `Updated src/.../mod.rs` line - the wiring is part of the work,
not a follow-up step you remember on your own.

---

## Summary

| Command | Creates | Wires into |
|---|---|---|
| `make:controller <name>` | `src/controllers/<snake>.rs` | `controllers/mod.rs` |
| `make:action <Name>` | `src/actions/<snake>_action.rs` | `actions/mod.rs` |
| `make:middleware <Name>` | `src/middleware/<snake>.rs` | `middleware/mod.rs` |
| `make:middleware <Dir>/<Name> --test` | `src/middleware/<dir>/<snake>.rs`, `tests/<dir>_<snake>_middleware.rs` | `middleware/<dir>/mod.rs`, `middleware/mod.rs` |
| `make:view <dir>.<name>` | `templates/<dir>/<name>.html`, `src/views/<dir>/<snake>.rs` | `views/<dir>/mod.rs`, `views/mod.rs`, `lib.rs` |
| `make:command <name>` | `src/commands/<snake>.rs` | `commands/mod.rs` (+ warns about `lib.rs`) |
| `make:error <Name>` | `src/errors/<snake>.rs` | `errors/mod.rs` |
| `make:task <Name>` | `src/tasks/<snake>_task.rs` | `tasks/mod.rs`, `schedule.rs`, `lib.rs`, `main.rs` |
| `make:inertia <Name>` | `frontend/src/pages/<Name>Page.<ext>` | (no module wiring) |
| `make:inertia <Dir>/<Name> --test` | `frontend/src/pages/<Dir>/<Name>Page.<ext>`, `tests/<dir>_<name>_page.rs` | (no module wiring) |
| `make:inertia <Name> --data` | `src/props/<snake>.rs` | (no module wiring; warns when `src/props/` is new) |
| `make:migration <name>` | `migrations/YYYYMMDDHHMMSS_<name>.rs` | (no module wiring) |
| `make:factory <Name> [--model <Model>]` | `src/factories/<snake>_factory.rs` | `factories/mod.rs`, `lib.rs` |
| `make:seeder <Name>` | `src/seeders/<snake>_seeder.rs` | `seeders/mod.rs`, `lib.rs` |
| `make:cast <Name>` | `src/casts/<snake>.rs` | `casts/mod.rs`, `lib.rs` |
| `make:channel <Name>` | `src/broadcasting/<snake>.rs` | `broadcasting/mod.rs`, `lib.rs` |
| `make:class <Name>` | `src/<snake>.rs` | `lib.rs` |
| `make:enum <Name>` | `src/enums/<snake>.rs` | `enums/mod.rs`, `lib.rs` |
| `make:event <Name>` | `src/events/<snake>.rs` | `events/mod.rs`, `lib.rs` |
| `make:listener <Name> [--event <Event>]` | `src/listeners/<snake>.rs` | `listeners/mod.rs`, `lib.rs` |
| `make:job <Name>` | `src/jobs/<snake>.rs` | `jobs/mod.rs`, `lib.rs` |
| `make:job-middleware <Name>` | `src/jobs/middleware/<snake>.rs` | `jobs/middleware/mod.rs`, `jobs/mod.rs`, `lib.rs` |
| `make:mail <Name>` | `src/mail/<snake>.rs` | `mail/mod.rs`, `lib.rs` |
| `make:notification <Name>` | `src/notifications/<snake>.rs` | `notifications/mod.rs`, `lib.rs` |
| `make:observer <Name> [--model <Model>]` | `src/observers/<snake>_observer.rs` | `observers/mod.rs`, `lib.rs` |
| `make:policy <Name> [--model <Model>]` | `src/policies/<snake>_policy.rs` | `policies/mod.rs`, `lib.rs` |
| `make:provider <Name>` | `src/providers/<snake>.rs` | `providers/mod.rs`, `lib.rs` |
| `make:resource <Name>` | `src/resources/<snake>_resource.rs` | `resources/mod.rs`, `lib.rs` |
| `make:rule <Name>` | `src/rules/<snake>.rs` | `rules/mod.rs`, `lib.rs` |
| `make:scope <Name> [--model <Model>]` | `src/scopes/<snake>_scope.rs` | `scopes/mod.rs`, `lib.rs` |
| `make:test <Name>` | `tests/<snake>.rs` | (no module wiring) |
| `make:trait <Name>` | `src/concerns/<snake>.rs` | `concerns/mod.rs`, `lib.rs` |
| `make:interface <Name>` | `src/contracts/<snake>.rs` | `contracts/mod.rs`, `lib.rs` |
| `generate-types` | `frontend/src/types/inertia-props.ts` | n/a |

## Next

- [CLI Overview](cli.md) - the full subcommand table
- [Console](console.md) - the per-project console binary that
  `make:command` feeds into
- [Controllers](controllers.md) - the handler contract `make:controller`
  scaffolds
- [Scheduling](scheduling.md) - the fluent schedule API used to
  register tasks generated by `make:task`
- [CLI Migrations](cli-migrations.md) - the migrate / db:sync
  commands that pair with `make:migration`
- [Eloquent Factories](eloquent-factories.md) and [Seeding](seeding.md) -
  what `make:factory` and `make:seeder` write fills in
- [Events](events.md) and [Queues](queues.md) - registering the events,
  listeners and jobs the generators write


---

<!-- /docs/cli-migrations -->

# CLI Migrations

The `suprnova` developer CLI shells into your application binary to drive
SeaORM's migration runner, so the same migration set executes whether you
run it from a developer terminal, from CI, or implicitly at server startup.
Use these commands to author migration files, apply them, roll back, and
keep your generated SeaORM entities in sync with the schema.

For the schema-authoring API (column types, indexes, foreign keys, the full
`MigrationTrait`), see [Migrations](migrations.md). For inserting test
data after the schema lands, see [Seeding](seeding.md).

## make:migration

Generate a new migration file under `src/migrations/` and wire it into the
`Migrator` in `src/migrations/mod.rs`.

```bash
suprnova make:migration <name>
```

`<name>` is normalised to snake_case. The generator recognises the
standard naming patterns and uses them to pick the `DeriveIden` enum:

- `create_<table>_table` - scaffolds a `create_table` body
- `add_<column>_to_<table>` - scaffolds a stub for `alter_table`
- `drop_<table>_table` - scaffolds a `drop_table` body
- anything else - uses the name as the table identifier

### Examples

```bash
suprnova make:migration create_users_table
suprnova make:migration add_email_to_users
suprnova make:migration drop_legacy_sessions_table
```

### Generated file

The file is written to `src/migrations/m{YYYYMMDD}_{HHMMSS}_<name>.rs`
(for example `m20260530_142301_create_users_table.rs`) and added to the
`Migrator::migrations()` vec.

```rust
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .create_table(
                Table::create()
                    .table(Users::Table)
                    .if_not_exists()
                    .col(
                        ColumnDef::new(Users::Id)
                            .integer()
                            .not_null()
                            .auto_increment()
                            .primary_key(),
                    )
                    .col(
                        ColumnDef::new(Users::CreatedAt)
                            .timestamp()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .col(
                        ColumnDef::new(Users::UpdatedAt)
                            .timestamp()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .to_owned(),
            )
            .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .drop_table(Table::drop().table(Users::Table).to_owned())
            .await
    }
}

#[derive(DeriveIden)]
enum Users {
    Table,
    Id,
    CreatedAt,
    UpdatedAt,
}
```

Edit the generated file to declare your columns, indexes, and constraints.
The generated file uses SeaORM's builder. You can write the same migration
with the shorter [schema builder](migrations.md#the-schema-builder),
`suprnova::schema::Schema`. See [Migrations](migrations.md) for both forms.

## migrate

Run every pending migration in `src/migrations/`.

```bash
suprnova migrate
```

The CLI shells out to `cargo run -- migrate` so your app's `Application`
runner does the work - same binary, same `Migrator`, same database
connection that `serve` would use.

```
Running migrations...
Migrations completed successfully!
```

A database that has run no migration loads the schema dump first, when
one exists; `--schema-path <file>` names another file. See
[Squashing migrations](migrations.md#squashing-migrations).

The application's `serve` and `web:run` subcommands auto-run `migrate` before
binding the socket unless you opt out with `--no-migrate` or set
`SUPRNOVA_AUTO_MIGRATE_BEST_EFFORT=true` to keep going past a failure.
A migration error during auto-migrate exits non-zero before the server
boots; see `framework/src/app/mod.rs` for the fail-closed contract.

`suprnova serve` runs `migrate` once when it starts and then runs the backend
with `serve --no-migrate`, so a restart of the backend does not migrate again.
Pass `--migrate always` to migrate on every restart, or `--no-migrate` to run
no migration. See [suprnova serve](cli-serve.md#migrations).

## migrate:status

Print the applied/pending state of every migration.

```bash
suprnova migrate:status
```

```
Migration status:
...SeaORM-formatted table of applied/pending migrations...
```

The body of the report comes from SeaORM's `MigratorTrait::status`, so the
exact formatting tracks the SeaORM version your app depends on.

## migrate:rollback

Roll back the last applied migration (or the last `N`).

```bash
suprnova migrate:rollback [--step <N>]
```

| Option | Default | Description |
|---|---|---|
| `--step <N>` | `1` | Number of migrations to roll back |

```bash
# Roll back one migration
suprnova migrate:rollback

# Roll back the last three
suprnova migrate:rollback --step 3
```

```
Rolling back 3 migration(s)...
Rollback completed successfully!
```

Each migration's `down()` runs in reverse application order. A failing
`down()` exits non-zero and leaves the rest of the chain untouched -
nothing further is attempted.

## migrate:fresh

Drop every table in the database and re-run every migration from scratch.

```bash
suprnova migrate:fresh
```

```
WARNING: Dropping all tables and re-running migrations...
Database refreshed successfully!
```

This destroys all data in the connected database. It is meant for local
development and test setup, not for any environment where the data
matters. After the drop it loads the schema dump, when one exists, before
it migrates; `--schema-path <file>` names another file.

### The production guard

Outside production it runs immediately, with no prompt - dropping a local
database is routine and a confirmation you always answer the same way
trains you to stop reading it.

When `APP_ENV` resolves to production it demands two different kinds of
proof:

```bash
suprnova migrate:fresh --force   # …then type the environment name when asked
```

1. **`--force`** proves intent at the moment you typed the command.
2. **A typed confirmation on an interactive terminal** proves a human is
   present.

The terminal requirement is the point of the second one. Without it,
`echo production | suprnova migrate:fresh --force` in a deploy script
would answer the prompt automatically, and the confirmation would be just
another flag. So a non-interactive stdin is refused even with `--force`.

Anything other than the exact environment name aborts before a single
table is dropped.

The same gate applies to your application binary's own subcommand
(`./app migrate:fresh --force`), which is the one a production deploy
actually runs.

## schema:dump

Write the database's schema and its migration ledger to
`database/schema/<engine>-schema.sql`, or to the file `--path` names:

```bash
suprnova schema:dump
suprnova schema:dump --path database/schema/baseline.sql
suprnova schema:dump --without-migration-data
suprnova schema:dump --database reporting
suprnova schema:dump --prune
```

```
Database schema dumped to database/schema/postgres-schema.sql
```

Use `--without-migration-data` to omit the ledger rows while retaining its
schema. Use `--database reporting` to dump `DATABASE_REPORTING_URL` instead
of `DATABASE_URL`. Connection names contain letters, digits or underscores;
you set `DATABASE_<UPPERCASE_NAME>_URL` for each named connection. An unknown
name fails with an error naming it.

The CLI runs `cargo run -- schema:dump` with the same flags. `--prune`
also deletes applied migrations, even when you omit ledger rows, and keeps each name as a
`PrunedMigration`. See [Squashing migrations](migrations.md#squashing-migrations).

## db:sync

Regenerate the SeaORM entity files in `src/models/entities/` from the
current database schema, and (when a `src/bin/migrate.rs` exists) run
pending migrations first.

```bash
suprnova db:sync [--skip-migrations] [--regenerate-models]
```

| Option | Description |
|---|---|
| `--skip-migrations` | Skip the migration pass and only regenerate entities |
| `--regenerate-models` | Overwrite `src/models/<table>.rs` files too, not just `src/models/entities/<table>.rs` |

### What it does

1. (Optional) Runs pending migrations. The default scaffold does not
   ship a `src/bin/migrate.rs`, so this step is a no-op and prints
   `Migration binary not found, skipping migrations`. In a default
   project, run `suprnova migrate` first, then `suprnova db:sync
   --skip-migrations`.
2. Connects to `DATABASE_URL`, introspects every user table (skipping
   `seaql_migrations` and any name starting with `_`), and writes one
   entity file per table to `src/models/entities/<table>.rs`.
3. Writes a thin user-facing model file at `src/models/<table>.rs` -
   but only if that file does not already exist, so your hand-written
   accessors, scopes, and observer hooks survive.
4. `--regenerate-models` overrides the protection in step 3 and
   overwrites those user files. Use it when you have not customised
   them yet, or when you have a backup.

### Typical workflow

```bash
# 1. Author a migration
suprnova make:migration create_posts_table
# (edit src/migrations/m..._create_posts_table.rs)

# 2. Apply it
suprnova migrate

# 3. Regenerate the entities so the new table is reachable from code
suprnova db:sync --skip-migrations
```

### Why Suprnova diverges

Laravel has one global `artisan` that owns every framework command,
including `db:seed`. Suprnova splits this in two:

- The `suprnova` developer CLI (this chapter) owns project scaffolding,
  generators, and the migration commands. It is installed once per
  developer machine via `cargo install` and shells into your app binary
  to do work that needs the app's `Migrator`.
- A per-project `console` binary, built from your project's
  `src/bin/console.rs`, owns `db:seed`, your `#[command]`-annotated
  handlers, `queue:work`, `schedule:run`, `workflow:work`, and other
  one-shot tasks that need your app's bootstrap, container bindings,
  and registered observers.

Migration commands live on the developer CLI because they have a
deterministic shape that does not depend on your bootstrap. Everything
that needs your service container or your registered seeders lives on
the per-project console binary. See [Console](console.md) for the full
console surface.

## db:seed

Run the seeders with `suprnova db:seed`. It runs every registered seeder, or
the one you name:

```bash
suprnova db:seed
suprnova db:seed UsersSeeder
suprnova db:seed --class=UsersSeeder
suprnova db:seed --force
```

The CLI runs `cargo run --quiet --bin console -- db:seed` and passes the name
as `--class=<name>` and `--force` as typed. It does not check the name: your
`console` binary owns the seeder registry and reports an unknown seeder, and
it is the one that refuses a production seed without `--force`. The seeder registry, ordering
rules, and the `--class` matching are covered in [Seeding](seeding.md). The
framework ships `db:seed` as a built-in console command, so your scaffold gets
it without any wiring on your side. You can also run it with
`cargo run --bin console -- db:seed`.

## Summary

| Command | What it does |
|---|---|
| `suprnova make:migration <name>` | Scaffold a new migration file and register it in `Migrator` |
| `suprnova migrate` | Run pending migrations |
| `suprnova migrate:status` | Show applied/pending status |
| `suprnova migrate:rollback [--step N]` | Roll back the last `N` migrations (default 1) |
| `suprnova migrate:fresh` | Drop all tables and re-run every migration |
| `suprnova schema:dump [--path <file>] [--prune] [--database <name>] [--without-migration-data]` | Write the schema and migration ledger to a dump file |
| `suprnova db:sync [--skip-migrations] [--regenerate-models]` | Regenerate SeaORM entities from the live schema |
| `suprnova db:seed [<seeder>] [--force]` | Run registered seeders, through the per-project `console` binary; `--force` for a production database |

## Next

- [Migrations](migrations.md) - the SeaORM form and the schema builder:
  tables, columns, indexes, foreign keys
- [Seeding](seeding.md) - authoring seeders and the `db:seed` console
  command
- [Console](console.md) - the per-project `console` binary and
  `#[command]` handlers
- [Database](database.md) - connections, drivers, transactions, the
  query builder
- [CLI Overview](cli.md) - every `suprnova` subcommand at a glance


---

<!-- /docs/cli-scheduling -->

# Scheduling Commands

CLI surface for the per-minute task scheduler. The `schedule:*`
subcommands all delegate into your application binary's `Application::run()`
dispatch, so they see the same config, services, observers, and listeners
that a request handler does. The full scheduler model - `Task` trait, fluent
cron API, `without_overlapping`, `run_in_background` - lives in
[Scheduling](scheduling.md); this chapter is the operator reference for the
commands themselves.

## How the commands run

`suprnova schedule:run`, `suprnova schedule:work`, and `suprnova schedule:list`
are thin shells that invoke `cargo run -- schedule:<subcommand>` against the
project in the current directory. The same subcommands are also reachable
directly on the application binary in production:

```bash
# In development (from the project root, source build):
suprnova schedule:run

# In production (binary on PATH):
/usr/local/bin/myapp schedule:run
```

The runtime drivers (Cache, Queue, RateLimit, Mail) and your
`bootstrap_fn` are booted before any task runs, so a scheduled task can
resolve services from the container exactly like a controller - see
[Application Bootstrap](bootstrap.md).

You must wire the scheduler into the application builder for the
subcommands to find any tasks:

```rust
// cmd/main.rs (backend starter) or src/main.rs (API starter)
Application::new()
    .config(my_app::config::register)
    .bootstrap(my_app::bootstrap::bootstrap)
    .routes(my_app::routes::register)
    .schedule(my_app::schedule::register)   // <-- the scheduler hook
    .migrations::<my_app::migrations::Migrator>()
    .run()
    .await
```

`suprnova make:task <Name>` wires this automatically; if you build the
chain by hand, add the `.schedule(...)` call yourself.

## schedule:run

Evaluate every registered task once and run the ones whose cron expression
matches the current minute. Designed to be invoked by system cron every
minute. Exits non-zero if any task failed; exits zero (with `No tasks were
due.`) if nothing was due this minute.

```bash
suprnova schedule:run
```

### Example output

```
Running due scheduled tasks...
  ✓ cleanup:logs
  ✓ send:reminders
```

When a task returns an error, its line is prefixed with `✗` and the error
message is appended:

```
Running due scheduled tasks...
  ✓ cleanup:logs
  ✗ backup:database: connection refused
```

When no task is due this minute:

```
Running due scheduled tasks...
No tasks were due.
```

### Crontab entry

A single entry runs the scheduler every minute. The application binary
evaluates all due tasks itself, so this is the only crontab line a
production host needs:

```cron
* * * * * cd /path/to/your/project && /usr/local/bin/myapp schedule:run >> /var/log/myapp/schedule.log 2>&1
```

If you're running `schedule:run` from system cron on more than one host
(or alongside a `schedule:work` daemon), tasks marked
`.without_overlapping()` need a configured Cache backend
(`CACHE_DRIVER=redis` is the production-grade choice) to coordinate
across processes - see [Preventing overlap](scheduling.md#preventing-overlapping)
for the lock semantics.

## schedule:work

Run the scheduler as a long-lived daemon. The first tick is aligned to the
next minute boundary, then the loop evaluates due tasks once per minute
until it receives `SIGINT` (Ctrl-C) or `SIGTERM`. On shutdown, any
`run_in_background` tasks still in flight are awaited before exit so they
don't get torn down mid-write.

```bash
suprnova schedule:work
```

### Example output

```
Starting scheduler daemon...
Press Ctrl+C to stop

==============================================
  suprnova Scheduler Daemon
==============================================
  3 task(s) registered. Press Ctrl+C to stop.
==============================================
```

Each tick is quiet - only failures are logged. On shutdown:

```
suprnova: scheduler shutting down.
suprnova: waiting for 1 background task(s) to finish…

Scheduler daemon stopped.
```

### Use cases

- **Development.** No crontab required - start the daemon in a terminal
  and watch it tick.
- **Docker.** Use as the container's main process when you want one image
  to play the scheduler role.
- **Systemd.** Manage it as a long-running unit (see [systemd unit](#systemd-unit)
  below).

### systemd unit

```ini
# /etc/systemd/system/myapp-scheduler.service
[Unit]
Description=MyApp Scheduler
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/your/project
ExecStart=/usr/local/bin/myapp schedule:work
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable myapp-scheduler
sudo systemctl start myapp-scheduler
```

`Restart=always` brings the daemon back up if it crashes; `RestartSec=5`
debounces a crash loop. Because the framework's panic boundary catches
panicking tasks and converts them to `FrameworkError`, a single bad task
should not crash the daemon - `Restart=always` is for the rare process-wide
failure (OOM, parent kill).

## schedule:list

Print every registered task with its cron expression, next run time, and
description.

```bash
suprnova schedule:list
suprnova schedule:list --timezone=Asia/Tokyo
```

### Example output

```
Registered scheduled tasks:
  cleanup:logs [0 3 * * *] next: 2026-05-29 03:00 UTC
  send:reminders [0 9 * * *] next: 2026-05-28 09:00 UTC
  heartbeat [* * * * *] next: 2026-05-28 12:01 UTC
  report:generate [0 6 * * *] (UTC) next: 2026-05-29 06:00 UTC
```

Tasks with a `.description(...)` chained on the builder include the
description after the next run time; tasks without a description show only
the cron and the next run.

`next:` is the first minute after now at which the expression matches; an
expression that can never match prints `next: never`. Times are shown in
UTC unless `--timezone` names another IANA zone. The CLI hands the flag to
your application without checking it, and the application exits with an
error before it prints anything when the zone name is unknown.

A task that pinned its own zone with `.timezone(...)` has its expression
rewritten into the listing's zone and labelled with it - `report:generate`
above asked for `02:00 America/New_York`. Tasks without a pinned zone are
printed as written and carry no label. See
[Scheduling](scheduling.md) for the timezone rules in full, including when
a rewrite is refused and one task can occupy several lines.

When nothing is registered (the `.schedule(...)` builder call is missing,
or `schedule::register` is a no-op):

```
No scheduled tasks registered.
Define tasks in src/schedule.rs and wire it with `Application::schedule(schedule::register)`.
```

## schedule:interrupt

Run your application binary with `schedule:interrupt` to write a mark in
its cache:

```bash
./target/release/app schedule:interrupt
```

The command boots the cache store `CACHE_DRIVER` names, or keeps the store
your `bootstrap` binds, so it writes where the schedulers read. A cache that
doesn't come up stops the command with a non-zero exit status.

You use the same shared cache as the schedulers you interrupt. The active
run finishes its current task and checks the mark before it starts another.
You do not cancel background tasks that already started. The next run
clears the mark. You receive a non-zero exit status if the cache write fails.

## Generating a task

The framework ships a generator that creates the task, wires it into the
project, and adds the scheduler call to your `main.rs`:

```bash
suprnova make:task CleanupLogs
```

This:

1. Creates `src/tasks/cleanup_logs_task.rs` (a working `Task` stub that
   logs its own duration)
2. Creates `src/tasks/mod.rs` (re-exporting `CleanupLogsTask`) if it
   doesn't already exist
3. Creates `src/schedule.rs` (with a `register(&mut Schedule)` function)
   if it doesn't already exist
4. Declares `pub mod schedule;` and `pub mod tasks;` in `src/lib.rs`
5. Adds `.schedule(<crate>::schedule::register)` to the `Application`
   chain in `cmd/main.rs` (or `src/main.rs` for the API starter)

Steps 2-5 are idempotent, so re-running `make:task` repairs wiring that
was removed by hand. See [Generators](cli-generators.md) for the broader
`make:*` family.

After generating, register the task in `src/schedule.rs`:

```rust
use suprnova::Schedule;
use crate::tasks::CleanupLogsTask;

pub fn register(schedule: &mut Schedule) {
    schedule.add(
        schedule.task(CleanupLogsTask::new())
            .daily()
            .at("03:00")
            .name("cleanup:logs")
            .description("Removes logs older than 30 days")
    );
}
```

The fluent builder API (`.daily()`, `.cron(...)`, `.without_overlapping()`,
`.run_in_background()`, day-specific modifiers) is fully covered in
[Scheduling](scheduling.md).

## Exit codes

| Command | Exit zero | Exit non-zero |
|---|---|---|
| `schedule:run` | every due task returned `Ok(())`, or no tasks were due | at least one task returned `Err(_)` or panicked |
| `schedule:work` | clean shutdown via `SIGINT` / `SIGTERM` (the wrapper treats exit code 130 as clean Ctrl-C) | bootstrap failure, or the daemon process aborted |
| `schedule:interrupt` | interrupt mark saved in the cache | cache write or application boot failed |
| `schedule:list` | listing succeeded (including the "no tasks registered" message) | application failed to boot |

Background-task failures inside `schedule:work` are logged to stderr but
do not exit the daemon - the `JoinSet`'s `catch_unwind` boundary surfaces
them as `FrameworkError` and the tick loop continues.

### Why Suprnova diverges

Laravel's `schedule:run` is the only first-class entry point; the daemon
form (`schedule:work`) is a backport for hosts without crontab. PHP has
no long-lived process, so each minute is a fresh runtime that has to
re-boot the framework, the container, and every service binding.

In Suprnova the daemon is first-class. `schedule:work` runs inside the
same Tokio runtime that serves HTTP, so:

- **Background tasks compose with the tick loop.** A `.run_in_background()`
  task is spawned into a `JoinSet`; the loop polls completed ones before
  the next tick and drains the rest on shutdown. Laravel spawns a child
  process per background task.
- **Graceful shutdown drains in-flight work.** Ctrl-C / SIGTERM lets
  inline tasks finish their current call and awaits every background
  spawn before exit. Laravel relies on the OS to kill the cron child.
- **Boot cost is paid once.** The container, drivers, and your
  `bootstrap_fn` boot at daemon start, not at every tick. `schedule:run`
  still pays the boot cost per invocation (it's a single-shot subcommand),
  but the daemon path is where the runtime model pays off.

`schedule:run` still works (and is the right choice when system cron is
already the operator's source of truth). Pick whichever fits your
deployment shape - both share the same task definitions.

## Next

- [Scheduling](scheduling.md) - the `Task` trait, fluent cron API,
  `without_overlapping`, `run_in_background`, and same-minute dedup
- [Generators](cli-generators.md) - the full `make:*` family, including
  `make:task`
- [Console](console.md) - `#[command]`-annotated one-shot operator
  tasks (not on a schedule)
- [Queues](queues.md) - for work that should be picked up by a worker
  rather than tick on a clock
- [Application Bootstrap](bootstrap.md) - how `.schedule(...)` plugs into
  the builder, and what tasks can resolve from the container


---

<!-- /docs/cli-docker -->

# Docker

Suprnova ships two CLI commands that generate Docker artifacts you can
adopt verbatim or modify. `docker:init` writes a multi-stage `Dockerfile` + `.dockerignore` for production. `docker:compose` writes a
`docker-compose.yml` for local development services (database, cache, and
optionally Mailpit, MinIO and Rustrak). Both commands write into the current project
root; neither tries to drive your container runtime.

## docker:init

Generate a production Dockerfile alongside a matching `.dockerignore`.

```bash
suprnova docker:init
```

The command refuses to overwrite an existing `Dockerfile`; remove the
existing file first if you want to regenerate.

### What gets written

| File | Purpose |
|------|---------|
| `Dockerfile` | Three-stage build: frontend assets, Rust release binary, runtime image |
| `.dockerignore` | Excludes `target/`, `node_modules/`, `.env*`, the existing build artifacts, and the Docker files themselves |

### Dockerfile shape

The generated Dockerfile uses three stages so the runtime image carries
only the compiled binary plus its required shared libraries:

1. **`frontend-builder`** - `node:20-alpine`. Installs npm deps and runs
   `npm run build`, producing `frontend/dist`.
2. **`backend-builder`** - `rust:1.94.0-slim-bookworm`. Caches `Cargo.toml` + `Cargo.lock` as a dependency layer, then copies your `cmd/`, `src/`,
   and the built `frontend/dist` (as `public/assets`) and runs
   `cargo build --release`.
3. **`runtime`** - `debian:bookworm-slim` with `ca-certificates` and
   `libssl3`. Runs as a non-root `appuser`. Copies the binary in as
   `./app` and the `public/` directory beside it. Exposes port 8765.

The final image's default `CMD` is `["./app"]`, which runs the unified
binary's `serve` subcommand (web server with auto-migrations on
startup). To run a different subcommand, override the command at
`docker run` time:

```bash
# Web server (default)
docker run -p 8765:8765 --env-file .env.production my-app

# Run migrations only and exit
docker run --env-file .env.production my-app ./app migrate

# Run the scheduler daemon
docker run --env-file .env.production my-app ./app schedule:work

# Run the queue worker
docker run --env-file .env.production my-app ./app queue:work
```

Pass production config through `--env-file .env.production` or
individual `-e` flags. `.env.production` should never be committed -
it's already covered by the `.dockerignore`.

### Bumping the Rust toolchain

The Dockerfile pins `rust:1.94.0-slim-bookworm` for the build stage so a
freshly generated image is reproducible and matches current `main`. Custom
Dockerfiles should use the same or a newer toolchain:

```dockerfile
FROM rust:1.94.0-slim-bookworm AS backend-builder
```

Pin to whatever toolchain version matches what `rust-toolchain.toml` (if
you have one) or your local `rustc --version` reports.

Current `main` also uses SeaORM 2.0, SeaQuery 1.0, and SQLx 0.9. Direct
SeaORM code must import `ExprTrait` for expression methods and use explicit
`*_raw` methods for prebuilt `Statement` values. Existing application data
requires no migration.

### Why Suprnova diverges

Laravel deployments typically run **multiple processes per container or
host**: php-fpm for web, a queue worker, a scheduler, sometimes a
Horizon dashboard, sometimes an Octane runner. Each one is its own
service definition.

Suprnova compiles to **one statically-linked binary** that knows every
subcommand the framework ships - `serve`, `migrate`, `queue:work`,
`schedule:work`, `workflow:work`, `ssr:start`. The same Docker image
runs every role; the only thing that changes is the command. That makes
"web + worker + scheduler" three services in your orchestrator that all
point at the same image tag - one build to roll the entire app forward.

## docker:compose

Generate a `docker-compose.yml` that brings up local development
services.

```bash
suprnova docker:compose [OPTIONS]
```

Like `docker:init`, this refuses to overwrite an existing
`docker-compose.yml`. It also appends `docker-compose.override.yml` to
your `.gitignore` (if a `.gitignore` is present) so you can keep
per-developer overrides locally without committing them.

### Options

| Option | Description |
|--------|-------------|
| `--with-mailpit` | Include the Mailpit email-testing service |
| `--with-minio` | Include MinIO (S3-compatible object storage) |
| `--with-rustrak` | Include Rustrak (Sentry-compatible error tracking) |

If you pass no service flags, the command prompts for each optional service.
Passing any service flag skips the prompts and uses the flags you gave.

### What you always get

PostgreSQL and Redis are written into every generated compose file:

| Service | Default port | Image |
|---------|-------------:|-------|
| PostgreSQL | 5432 | `postgres:16-alpine` |
| Redis | 6379 | `redis:7-alpine` |

Both services have health checks, persistent named volumes, and live on
a project-scoped network (`<project>_network`). The Postgres user and
database default to `suprnova` / `suprnova_db`; the password is generated
per project, written into `docker-compose.yml`, and printed once as a
ready-to-paste `DATABASE_URL`.

### Optional services

When you opt in:

| Service | Default ports | Image |
|---------|--------------:|-------|
| Mailpit | 1025 (SMTP), 8025 (UI) | `axllent/mailpit:latest` |
| MinIO | 9000 (S3 API), 9001 (Console) | `minio/minio:latest` |
| Rustrak | 8080 (API and dashboard) | `rustrak/rustrak-server:v0.16.4` |

Mailpit defaults to accepting any SMTP auth so you don't have to
configure credentials during development; the web UI at
`http://localhost:8025` shows every email your app sends. MinIO's
root user defaults to `suprnova`; its password is generated per project
and printed once by `docker:compose`. Override them with
`MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD`.

Rustrak stores its database and source maps in `rustrak_data`. Its generated
`SESSION_SECRET_KEY` is at least 64 random characters and stays in the
Compose file; keep it across restarts. The service publishes on loopback,
sets `PUBLIC_URL` to that address and disables telemetry. Before its first
start, set `RUSTRAK_CREATE_SUPERUSER` to `email:password`. Compose refuses
to start without this value, so there is no shared default account:

```bash
suprnova docker:compose --with-rustrak
export RUSTRAK_CREATE_SUPERUSER="admin@example.com:$(openssl rand -hex 24)"
docker compose up -d
```

Save those initial credentials, sign in at `http://127.0.0.1:8080`, create
a project and set `REPORTING_DSN` to its DSN. The account bootstrap only
runs while the database has no users. See [Error Reporting](error-reporting.md)
for server and browser configuration, or for a plain `docker run` setup.

### Running the stack

```bash
# Bring everything up in the background
docker compose up -d

# Tail logs
docker compose logs -f

# Stop and remove the containers (volumes persist)
docker compose down

# Remove volumes too (wipes the local database)
docker compose down -v
```

### Wiring `.env` to compose

The Compose file uses environment interpolation for service settings.
Set overrides in `.env` or your shell; Rustrak requires an explicit initial
admin value through `${RUSTRAK_CREATE_SUPERUSER:?...}`. A typical
`.env` for the default stack:

```env
DATABASE_URL=postgres://suprnova:<generated password>@localhost:5432/suprnova_db
REDIS_URL=redis://localhost:6379

# Mailpit (if enabled)
MAIL_DRIVER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025

# MinIO (if enabled)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=suprnova
S3_SECRET_KEY=<MinIO root password from docker:compose>
S3_BUCKET=local
S3_REGION=us-east-1
```

The server reads the `S3_*` variables when it boots. When `S3_BUCKET` is
set, it registers an S3 disk named `s3`, so `Storage::disk("s3")` works
against MinIO with no Rust code. See [Filesystem](filesystem.md#an-s3-disk-from-the-environment)
for every variable.

To override a port (e.g. because 5432 is already in use), set the
matching env var before bringing the stack up:

```bash
DB_PORT=5433 docker compose up -d
```

The full set of overridable ports:

| Variable | Service | Default |
|----------|---------|--------:|
| `DB_PORT` | PostgreSQL | 5432 |
| `REDIS_PORT` | Redis | 6379 |
| `MAILPIT_SMTP_PORT` | Mailpit SMTP | 1025 |
| `MAILPIT_UI_PORT` | Mailpit UI | 8025 |
| `MINIO_API_PORT` | MinIO S3 | 9000 |
| `MINIO_CONSOLE_PORT` | MinIO Console | 9001 |
| `RUSTRAK_PORT` | Rustrak API and dashboard | 8080 |

### Customising the compose file

`docker-compose.yml` is yours to edit after generation - Suprnova
doesn't regenerate or read it later. Common patches:

- Swap `postgres:16-alpine` for `mysql:8` or `mariadb:11` if you prefer
  one of those drivers; both are first-class in Suprnova
- Add a `volumes:` entry that mounts your `migrations/` directory if you
  want to run migrations inside a one-shot container
- Add additional services (Qdrant, Elasticsearch, Nats) the same way

## Production deployment

For a real deployment, run `docker:init` and treat the generated
`Dockerfile` as your build input. Most orchestrators (Railway, Fly,
Digital Ocean App Platform, Kubernetes) just need three things:

1. The image tag built from this `Dockerfile`
2. An env file with `DATABASE_URL`, `APP_KEY`, and any driver-specific
   keys
3. A health check pointing at `GET /_suprnova/health/live` (and, if the
   platform distinguishes the two, a readiness check at
   `/_suprnova/health/ready`)

The single-binary shape means every role uses the same image; you
declare a "web" service running `./app` and a "scheduler" or "worker"
service running `./app schedule:work` (or `./app queue:work`). Both
read the same env, so they stay in lockstep on every deploy.

See [Deployment](deployment.md) for the platform-agnostic checklist,
and the platform guides for fully-worked examples:
[Railway](deployment-railway.md),
[Digital Ocean](deployment-digital-ocean.md),
[Hetzner VPS](deployment-hetzner.md).

## Summary

| Command | Writes | When to use |
|---------|--------|-------------|
| `suprnova docker:init` | `Dockerfile`, `.dockerignore` | Building production images |
| `suprnova docker:compose` | `docker-compose.yml` | Bringing up local Postgres/Redis/Mailpit/MinIO/Rustrak |

## Next

- [Error Reporting](error-reporting.md) - Rustrak, drivers and browser reports
- [Deployment](deployment.md) - the platform-agnostic deployment checklist
- [Railway](deployment-railway.md) - managed PaaS with build-from-git
- [Digital Ocean](deployment-digital-ocean.md) - App Platform deploys
- [Hetzner VPS](deployment-hetzner.md) - bare-metal with systemd + Caddy
- [Environment Variables](env-vars.md) - every key the framework reads


# Deployment Recipes

---

<!-- /docs/deployment -->

# Deployment Overview

A Suprnova app compiles to a single self-contained binary that owns
the web server, the migration runner, the scheduler, and the queue
worker. Deploying is "copy the binary, set four environment variables,
run it." This chapter covers what those four variables are, what the
binary's subcommands do in production, and how the built-in health
endpoint integrates with a platform's liveness probe. Platform-specific
walkthroughs follow in [Railway](deployment-railway.md),
[Digital Ocean](deployment-digital-ocean.md), and
[Hetzner](deployment-hetzner.md).

## The single binary

Your app builds to one binary with a clap subcommand surface:

```bash
./app                       # serve (default) - auto-migrate, then HTTP
./app serve                 # explicit serve, with auto-migrate
./app serve --no-migrate    # serve without running migrations
./app web:run               # alias for serve

./app migrate               # apply pending migrations and exit
./app migrate:status        # show migration status
./app migrate:rollback [N]  # roll back the last N migrations (default 1)
./app migrate:fresh         # drop all tables, then re-migrate - in production
                            # this needs --force AND a typed confirmation on an
                            # interactive terminal; see cli-migrations.md

./app schedule:work         # scheduler daemon - wakes every minute
./app schedule:run          # run due tasks once and exit
./app schedule:list         # print every registered task
./app queue:work            # queue worker daemon
./app workflow:work         # workflow worker daemon

./app down [--secret …] [--retry …] [--except …] [--message …]
./app up                    # leave maintenance mode
```

One binary means one Docker image, one CI artifact, one deployment to
verify. The same image runs the web service, the scheduler, the queue
worker, and the workflow worker - you start a different subcommand
for each.

## Four production environment variables

Suprnova fails closed on boot if the production environment is
misconfigured. The minimum set to deploy:

| Variable | What it does | Failure mode |
|---|---|---|
| `APP_ENV` | Selects the environment (`production`, `staging`, etc.). | Defaults to `local` if unset - your app runs in dev mode in prod. |
| `APP_KEY` | 32-byte AES-256 base64 key for `Crypt`, sessions, cookies, and pagination cursors. | Boot returns a typed error and exits non-zero when `APP_ENV` is not local/dev/test and `APP_KEY` is missing or malformed. |
| `APP_URL` | Canonical absolute URL of your app (`https://app.example.com`). | Defaults to `http://localhost:8765`; signed URLs, redirects, mail links, and absolute Inertia URLs all use this. |
| `DATABASE_URL` | Connection URL for your relational database. | Boot refuses to start when `APP_ENV` is `production` or `staging` and `DATABASE_URL` is unset - the dev SQLite fallback is rejected explicitly. |

Generate `APP_KEY` once with the CLI:

```bash
suprnova key:generate           # writes APP_KEY=… into ./.env
suprnova key:generate --show    # prints the key for $(…)
```

For key rotation, see [Encryption](encryption.md) -
`APP_KEY_PREVIOUS` (or the Laravel-compatible `APP_PREVIOUS_KEYS`)
takes a comma-separated list of older keys for decrypt-only fallback.

Beyond the four required vars, common production knobs:

| Variable | Default | Notes |
|---|---|---|
| `SERVER_HOST` | `127.0.0.1` | Use `0.0.0.0` in containers. |
| `SERVER_PORT` | `8765` | Match your platform's expected port. |
| `APP_DEBUG` | env-derived | `false` in production/staging/custom envs. Set explicitly if you want loud errors in staging. |
| `SERVER_MAX_BODY_SIZE` | per-handler default | Process-wide request body cap. |
| `SERVER_MAX_CONNECTIONS` | `10000` | Cap on concurrent active TCP connections. See below. |
| `SERVER_HEALTH_READINESS_TOKEN` | unset (readiness is public) | Shared secret required to reach the readiness probe. See [Health check](#health-check). |
| `DB_MAX_CONNECTIONS` | `10` | Pool size. |
| `REDIS_URL` | unset | Required if you've configured the Redis cache/queue/session drivers. |

The full table lives in [Environment Variables](env-vars.md).

## Recommended database: MariaDB

Suprnova supports SQLite, PostgreSQL, MySQL, and MariaDB as first-class
relational backends. The recommendation is environment-specific:

- **Development.** SQLite. The scaffolder writes
  `DATABASE_URL=sqlite://./database.db` so `suprnova serve` works
  with zero database setup.
- **Production.** MariaDB. It collapses what would otherwise be three
  separate services (relational + vector + KV cache) onto one engine,
  with system-versioned tables for audit if you need them.

```bash
# .env.production
DATABASE_URL=mysql://app_user:secret@db.internal:3306/app_production
```

Use the `mysql://` or the `mariadb://` scheme. Both select the MySQL family
driver, which handles MariaDB natively. The framework accepts `mariadb://`
for the primary connection, named connections, read replicas, the migrator
and `MariaDbVectorDriver::from_url`. `DB::driver_title()` returns `MariaDB`
for a `mariadb://` URL and `MySQL` for a `mysql://` URL, because the URL is
the only thing that tells them apart. Suprnova's `MariaDbVectorDriver`
(`VECTOR(N)` + HNSW) hooks in directly for vector workloads.

```bash
DATABASE_URL=mariadb://app_user:secret@db.internal:3306/app_production
```

The other relational backends are first-class too:

```bash
# PostgreSQL
DATABASE_URL=postgres://app_user:secret@db.internal:5432/app_production

# MySQL
DATABASE_URL=mysql://app_user:secret@db.internal:3306/app_production

# SQLite (for tiny single-instance deploys)
DATABASE_URL=sqlite:///var/lib/myapp/data.db
```

### Why Suprnova diverges

Laravel's defaults nudge new projects toward PostgreSQL because PHP +
PostgreSQL is the well-trodden path. Suprnova picks the database that
gives the cleanest single-engine production posture for a Rust app.
MariaDB's `VECTOR(N)` (11.7+), Dynamic Columns, and system-versioned
tables mean a small-to-mid product can ship search, KV, and audit
without bolting on Redis, OpenSearch, or pgvector. PostgreSQL stays
fully supported - the framework's test matrix runs against all three
relational backends - but our deployment docs lead with the engine
that minimises moving parts. See
[Vector Storage](vector.md) and [Database](database.md) for the
backend-specific surfaces.

## Building a production image

The scaffolder ships a generator for a multi-stage Dockerfile:

```bash
suprnova docker:init
```

This writes a `Dockerfile` with three stages:

1. **Frontend build** - `node:20-alpine`, runs `npm ci && npm run build`
   against your `frontend/` Inertia app (Svelte 5, React 19, or Vue 3.5
   per your scaffold choice).
2. **Backend build** - `rust:1.94.0-slim-bookworm`, compiles your crate in
   release mode with dependency caching.
3. **Runtime** - `debian:bookworm-slim`, copies the compiled binary,
   the Vite output, and your schema dumps (`database/schema`), installs
   the database client the `DB_CLIENT` build argument names
   (`postgresql-client` unless you change it), runs as a non-root
   `appuser`, exposes port 8765, and runs `CMD ["./app"]` (the
   auto-migrating server). The client lets the server load a schema dump
   into a new, empty database; see
   [Squashing migrations](migrations.md#squashing-migrations).

Current `main` also upgrades the database stack to SeaORM 2.0, SeaQuery 1.0,
and SQLx 0.9. Direct SeaORM code must import `ExprTrait` for expression methods
and use explicit `*_raw` methods for prebuilt `Statement` values. Existing
application data requires no migration.

Build and run locally to verify before pushing:

```bash
docker build -t myapp .

# With an env file
docker run --rm -p 8765:8765 --env-file .env.production myapp

# Or with explicit vars (the four required ones)
docker run --rm -p 8765:8765 \
  -e APP_ENV=production \
  -e APP_KEY=$APP_KEY \
  -e APP_URL=https://app.example.com \
  -e DATABASE_URL=mysql://user:pass@host:3306/app \
  myapp
```

Never commit `.env.production` (or any file containing `APP_KEY` or
`DATABASE_URL`) to your repo. Use your platform's secrets store and
read the values at deploy time.

## Production build shape

The binary the Dockerfile builds never carries the framework's `testing`
feature - the encryption-key installers, storage fakes, and RenderCache
test hooks that a test suite needs are compiled out. Your scaffolded
`Cargo.toml` (and the dogfood app in the Suprnova repository itself) takes
this shape by construction with two dependency entries:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", default-features = false, features = [
    "filesystem", "database-sqlite", "database-postgres", "database-mysql",
    "vector-mariadb", "vector-pgvector", "web-push", "localization", "magnetar-oauth",
    "media",
    "queue-sqs",
    "reporting-sentry",
    "search-media",
    "agents",
] }

[dev-dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v4.6.2", features = ["testing"] }
```

The production entry turns default features off and lists the fourteen that
stay on (every default except `testing`). The dev-dependency turns
`testing` back on - Cargo's feature resolver only pulls in a
dev-dependency's features for `cargo test` and other `--tests` builds, so
`cargo build --bin app` (or `--bin console`) never sees it. `testing` is a
dev-dependency feature only: nothing in your own `src/` or `cmd/` should
turn it on for a binary target.

The framework repository proves this holds with a small crate whose only
job is to fail to compile: it references every framework item gated
behind `testing` by path, and the release gate checks that referencing
them without the feature is a compile error while referencing them with
it succeeds.

## Migrations on boot

The default `./app` (and explicit `./app serve`) command applies any
pending migrations before binding the socket. The two practical
implications:

- **Safe with multiple instances.** SeaORM's migration runner takes a
  database-level advisory lock; the slowest pod waits, the others
  proceed once it's done. You do not need a separate "migrate-then-deploy"
  step for routine release rolls.
- **Failed migration = failed deploy.** If a migration errors, the
  process exits non-zero before the server binds. The platform's
  health probe (see below) reports the pod unhealthy, and the rollout
  halts. Fix forward by shipping a corrective migration in the next
  release.

For CI pipelines that want to gate the deploy on a successful migration
before any pod accepts traffic, run migrations in a one-shot:

```bash
docker run --rm myapp ./app migrate
# … then roll the actual deploy
docker run myapp ./app serve --no-migrate
```

`--no-migrate` skips the auto-migrate phase but still boots the server
normally.

## Workers as separate services

The scheduler, queue, and workflow systems each have their own daemon
subcommand. In production, run them as separate processes against the
same image, sharing the same environment:

```bash
docker run myapp ./app schedule:work    # one instance - see below
docker run myapp ./app queue:work       # scale to N instances
docker run myapp ./app workflow:work    # scale to N instances
```

Two rules to internalise:

- **Either run exactly one `schedule:work` process, or mark your tasks
  `.on_one_server()`.** Scheduler replicas do not coordinate by default:
  each evaluates the schedule independently, so three replicas run every
  due task three times. `replicas: 1` is the simple answer;
  `.on_one_server()` elects one replica per tick against a shared cache
  and is what you want if the scheduler has to be highly available. See
  [Scheduling](scheduling.md#running-on-one-server).
- **Queue and workflow workers scale horizontally.** Both pull work
  from a shared store and use visibility timeouts or row-level locks
  to coordinate; adding pods adds throughput. `./app queue:work
  --max-jobs N` makes the worker exit after N jobs so a supervisor can
  rotate the process - useful for release-on-restart deploys.

See [Queues](queues.md), [Scheduling](scheduling.md), and
[Workflows](workflows.md) for the per-subsystem detail.

## Stopping cleanly

Every long-running Suprnova process - the server and all three daemons -
drains on **SIGTERM** as well as SIGINT. SIGTERM is what `docker stop`,
Coolify, systemd and Kubernetes send; SIGINT is what Ctrl-C sends. Both
take the same path: stop accepting new work, finish what is in flight
within a bounded grace, exit `0`.

The grace windows are per-subsystem and bounded on purpose - one slow
client or one long task must not be able to keep a process alive
indefinitely:

| Process | Waits for | Grace |
|---|---|---|
| `serve` | in-flight HTTP connections | 5s |
| `queue:work` | the in-flight job to settle | until the job returns |
| `schedule:work` | `.run_in_background()` tasks | 30s |
| `workflow:work` | in-flight workflow steps | until they return |

Each of them then waits up to ten more seconds for the queued event
listeners still running, so a listener a job or a request started is
not cut off; so does `schedule:run` once its tasks have run. See
[Events](events.md#draining-on-shutdown).

**Size your platform's termination grace above these.** Docker defaults
to 10 seconds, Kubernetes to 30. If the platform's window is shorter than
the work takes, it sends SIGKILL and you are back to losing in-flight
jobs:

```yaml
# docker compose
services:
  worker:
    command: ["app", "queue:work"]
    stop_grace_period: 60s
```

```yaml
# kubernetes
spec:
  terminationGracePeriodSeconds: 60
```

**A job killed mid-flight is not lost, but it does cost an attempt.** Its
reservation lapses and another worker reclaims it, charging one attempt
so a job that reliably kills its worker can still be dead-lettered rather
than cycling forever. See [Queues](queues.md#what-counts-as-an-attempt).

**PID 1 is a real constraint.** A container entrypoint runs as PID 1, and
the kernel does not apply default signal dispositions to PID 1 - a
process with no SIGTERM handler does not die on SIGTERM, it ignores it
until the platform gives up and sends SIGKILL. Suprnova installs the
handler, so `CMD ["app", "queue:work"]` is fine as written and no `tini`
shim is required.

## Health check

Suprnova exposes three built-in health paths. The `_suprnova/` prefix is
reserved so your own routes can never collide with them.

| Path | Touches | Use for |
|---|---|---|
| `/_suprnova/health/live` | nothing | Liveness. Answers 200 for as long as the process can serve a request. |
| `/_suprnova/health/ready` | the database | Readiness. 503 when a dependency is unreachable. |
| `/_suprnova/health` | nothing, or the database with `?db=true` | The original endpoint. Behaves as either of the above. |

```bash
curl http://localhost:8765/_suprnova/health/live
# 200 {"status":"ok","timestamp":"2026-05-30T12:34:56+00:00"}

curl http://localhost:8765/_suprnova/health/ready
# Healthy:  200 {"status":"ok","timestamp":"…","database":"connected"}
# Degraded: 503 {"status":"degraded","timestamp":"…","database":"error"}
```

`/_suprnova/health` and `/_suprnova/health?db=true` keep working exactly
as before, and nothing you have already deployed needs changing - the
[Hetzner guide](deployment-hetzner.md) still names them for one-off
checks, and so may your own specs. The named paths are clearer, so
prefer them in new configuration; the [Railway](deployment-railway.md),
[DigitalOcean](deployment-digital-ocean.md) and [Docker](cli-docker.md)
guides use them.

### Use the right probe for the right question

Point liveness at `/live` and readiness at `/ready`. The distinction
matters more than it looks: a failed **liveness** probe restarts the pod,
while a failed **readiness** probe only pulls it out of the load
balancer. Wire a database check into liveness and a database blip
restarts every replica you have - at the exact moment the database can
least afford a thundering herd of reconnects.

```yaml
livenessProbe:
  httpGet:
    path: /_suprnova/health/live
    port: 8765
readinessProbe:
  httpGet:
    path: /_suprnova/health/ready
    port: 8765
```

The endpoint short-circuits before the middleware chain so it stays
responsive even if a middleware deadlocks or the request id middleware
is rejecting traffic.

### Degraded responses do not carry driver detail

The 503 body reports `"database":"error"` and nothing more. The driver's
own message - which names hosts, ports, database and schema names and
server versions, and for some configuration errors the connection URL -
goes to the log at `error!` level, where an operator can read it and a
stranger cannot. In debug builds it is also included in the body as
`database_error`, so local debugging is unaffected.

### Closing readiness off

Readiness runs a database round trip for whoever asks. If the endpoint is
internet-reachable, set a shared secret:

```bash
SERVER_HEALTH_READINESS_TOKEN=<a long random string>
```

Probes must then send it as a header:

```bash
curl -H "X-Suprnova-Health-Token: $SERVER_HEALTH_READINESS_TOKEN" \
  http://localhost:8765/_suprnova/health/ready
```

```yaml
readinessProbe:
  httpGet:
    path: /_suprnova/health/ready
    port: 8765
    httpHeaders:
      - name: X-Suprnova-Health-Token
        value: <the same value>
```

Without the header, readiness answers **404** - the same response as any
path that does not exist, so the endpoint is invisible rather than merely
closed. Liveness stays public either way, so you do not have to put the
secret in every manifest to keep your restart-on-hang signal.

Unset is the default, and readiness is public. That is deliberate: the
configurations this manual and the scaffolder generate all call
`?db=true` without a header, and defaulting to closed would break them.

## Maintenance mode

To roll a destructive migration or quiesce traffic for an incident:

```bash
./app down --secret abc123 \
           --retry 60 \
           --message "Deploying - back in a few minutes" \
           --except /webhooks/stripe

./app up
```

`down` writes a maintenance marker the middleware reads on every
request. Requests get a 503 (configurable via `--status`) with the
provided message, except for paths in `--except` and any request that
includes the secret. `up` removes the marker.

The secret is a bearer credential: anyone who visits `/<secret>` is issued
a bypass cookie good for 12 hours. The deadline is sealed inside the
encrypted cookie and re-checked on every request, so a captured cookie
stops working on time even if the browser ignores its `max-age`. A cookie
whose deadline is further out than one TTL is refused, with a short
allowance for clock differences between hosts. Both the URL match and the
cookie's secret comparison run in constant time, so response timing does
not tell a prober how long a prefix they guessed correctly. Prefer
`--with-secret`, which mints one for you (16 random bytes, 32 hex
characters) and prints the bypass URL, over picking a memorable string for
`--secret` - and treat it like any other credential in your incident
notes.

`down` prints what it did, in Laravel's words:

```text
Application is now in maintenance mode.
You may bypass maintenance mode via [https://example.com/abc123].
```

A `down` while the application is already down updates the options and
prints `Maintenance mode options updated.` instead. The bypass address is
`APP_URL` followed by the secret. When `down` cannot record maintenance
mode, it prints `Failed to enter maintenance mode: <error>.` and exits
with a failing status.

`--retry` takes a number of seconds or a date. A date is sent as the
`Retry-After` header in the RFC 7231 form, so a client reads when to come
back:

```bash
./app down --retry "Sat, 01 Jan 2033 00:00:00 GMT"
./app down --retry 2033-01-01T00:00:00Z     # the same header
```

`--render <view>` renders the Tera template at
`resources/views/<view>` once, when you run `down`, and serves the result
as the maintenance page. The template reads `retry_after`: the seconds or
the date of `--retry`, and empty without one. A template that cannot be
read or rendered fails `down` before maintenance mode starts, so a typo
never takes the site down with a broken page. `--render` and `--message`
exclude each other.

```html
<!-- resources/views/errors/503.html -->
<h1>Back soon</h1>
<p>Try again after {{ retry_after }}.</p>
```

```bash
./app down --render errors/503.html --retry 600
```

After it records maintenance mode, `down` dispatches the
`MaintenanceModeEnabled` event, which carries no data. Listen for it to
tell a status page or the people on call:

```rust
use suprnova::{EventFacade, FrameworkError, Listener, MaintenanceModeEnabled, async_trait};
use std::sync::Arc;

struct TellTheStatusPage;

#[async_trait]
impl Listener<MaintenanceModeEnabled> for TellTheStatusPage {
    async fn handle(&self, _event: &MaintenanceModeEnabled) -> Result<(), FrameworkError> {
        // Post to the status page here.
        Ok(())
    }
}

// In bootstrap::register():
pub async fn register() {
    EventFacade::listen::<MaintenanceModeEnabled, _>(Arc::new(TellTheStatusPage)).await;
}
```

A listener that fails is logged, and `down` still reports the state it
recorded: maintenance mode is on either way. Scheduled tasks skip their
runs while the application is down, unless they ask
`even_in_maintenance_mode()`; see [Scheduling](scheduling.md).

### Why Suprnova diverges

Laravel drops a `--retry` value that is neither a number nor a date it
can parse, and sends no `Retry-After`. Suprnova refuses it, so the header
you asked for is the one clients get. Laravel renders `--render` with a
Blade view; Suprnova renders a Tera template with `retry_after` in its
context.

## Serving under a path prefix

A reverse proxy can serve the application under a path, such as
`https://example.org/billing`, and strip that path before it forwards the
request. The application then receives `/invoices/7` for the browser's
`/billing/invoices/7`. Routes still match on the path the application
receives, so you don't change a single route. Every URL the framework hands
the browser has to carry the stripped path again, and the proxy tells the
framework what it is with the `X-Forwarded-Prefix` header.

This nginx location serves an application listening on port 8000 under
`/billing`:

```nginx
location /billing/ {
    proxy_pass http://127.0.0.1:8000/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /billing;
}
```

The trailing slash on `proxy_pass` is what strips `/billing`. Caddy does the
same with `handle_path`:

```text
example.org {
    handle_path /billing/* {
        reverse_proxy 127.0.0.1:8000 {
            header_up X-Forwarded-Prefix /billing
        }
    }
}
```

Then trust the proxy, and give `APP_URL` the prefix too:

```bash
APP_TRUSTED_PROXIES=127.0.0.1
APP_URL=https://example.org/billing
```

### The trust rule

The framework reads `X-Forwarded-Prefix` under the rule every other
forwarded header follows: only when the TCP peer is listed in
`APP_TRUSTED_PROXIES`. From any other peer the header is ignored. The proxy
sets or clears `X-Forwarded-Prefix` on every request it forwards, as it does
for `X-Forwarded-For`. A proxy that passes a client's header on as it came
lets the client choose the root of every URL the application builds.

A trusted value counts only when it is a clean path: ASCII letters, digits,
`-`, `.`, `_`, `~` and `/`, starting with `/`, not ending with `/`, and with
no empty, `.` or `..` segment. A header sent on two lines is ignored whole. A
trusted `/` means the application is at the host root, and an empty value is
ignored. An ignored value leaves the root to `APP_URL`.

### The public root

The public root is the trusted prefix when the request carries one,
otherwise the path in `APP_URL`, which is also the root outside a request:
in console commands, queued jobs and mail. A trusted prefix replaces the
`APP_URL` path, so the two never add up to `/billing/billing`. At the host
root the root is empty.

The framework puts the root in front of every URL it builds for the
browser: `route()` and the signed URLs, `url::to`, `url::current`,
`Request::url`, every redirect, the Inertia page URL and its Vite tags, Live's
endpoints and assets, the localization catalog, pagination links and a
`Storage::url` with a root-relative base. A path that already carries the
root, such as the output of `route()`, keeps it once.

A template writes the root with `url::root()`, which returns `/billing`
under the prefix and the empty string at the host root:

```html
<link rel="stylesheet" href="{{ suprnova::url::root() }}/suprnova-ui/button/button.css">
```

An Inertia frontend gets the root as the `root` prop, which `RootShare`
shares with every page. A scaffolded application registers it, and its pages
post to `` `${root}/login` ``, so the same frontend build runs at `/` and
under `/billing`.

Mail and job links are built outside a request, where no header arrives. A
deployment whose mail and job links must work behind a header-only prefix
sets the prefix in `APP_URL` as well, as the example above does.

### Cookies

When the application sets no cookie path, the session, XSRF, remember-me and
maintenance bypass cookies take the root of each request as their `Path`, so
two applications under `/a` and `/b` on one host keep separate sessions. A
`__Host-` cookie keeps `Path=/`, as the browser requires. Two applications
that share a host and both use `__Host-` cookies need distinct cookie names,
set with `SESSION_COOKIE`.

When a browser sends two cookies of one name, the framework reads the first.
The browser lists the cookie with the longer path first, so after you move an
application under a prefix, a session cookie left over at `Path=/` cannot
shadow the one scoped to the root.

### Routes that begin with the prefix

The framework tells a path that carries the root from an application path by
its first segment. An application whose own routes begin with its
deployment prefix, such as a `/billing` route group behind a proxy that
serves `/billing`, can't be told apart, so don't give an application routes
that begin with the prefix. Let the proxy strip it instead.

### Why Suprnova diverges

- **A trailing slash is ignored, not trimmed.** Symfony trims a trailing
  slash from `X-Forwarded-Prefix`. Suprnova ignores a value that ends with
  `/`, so each root has one spelling and two spellings never mean two cache
  keys or two cookie paths. Send `/billing`, not `/billing/`.
- **The relative `route()` carries the root.** Laravel's
  `route($name, $parameters, false)` strips the base URL. Suprnova's
  `route()` is relative and keeps the root, so a redirect or a link built
  from it works behind the prefix.
- **The `APP_URL` path is the root when no prefix header arrives.** Laravel
  reads the root from the request alone. Suprnova falls back to the path in
  `APP_URL`, so console commands, jobs and mail build the same URLs as a
  request does.

## Scaling

### Web

Horizontal scaling is the default story: every pod runs `./app`,
shares `DATABASE_URL`, and connects to the same Redis (if you've
configured Redis-backed cache/queue/session). Auto-migration is safe
because of the advisory lock above. Sticky sessions are not required -
session state lives in your session driver (database or Redis),
not in process memory.

### Workers

- **Scheduler.** Exactly one instance, always.
- **Queue.** Scale horizontally. If you've split work across multiple
  named queues, run a worker per queue (or pass driver-specific queue
  filters - see [Queues](queues.md)).
- **Workflow.** Scale horizontally; row-level claim/heartbeat
  coordinates the workers.

## Connection cap (`SERVER_MAX_CONNECTIONS`)

The server caps concurrent TCP connections at 10000 by default. The
header and body deadlines bound how long each connection lasts; the cap
bounds how many there are, so a crowd of slow clients cannot use up the
process's file descriptors. In most deployments a reverse proxy (nginx,
Caddy, Traefik) or the platform's load balancer provides the first line
of defence, and the cap is the backstop inside the process. To change
it, set `SERVER_MAX_CONNECTIONS`:

```bash
# .env.production - cap concurrent connections at 1024
SERVER_MAX_CONNECTIONS=1024
```

When the cap is reached the **accept loop blocks** (back-pressure at the
TCP level) until an existing connection closes; the pending handshake
remains in the kernel's accept backlog. The permit is held for the full
lifetime of each connection and released the moment the connection ends,
so slots turn over promptly.

Rules of thumb:

- **Unset (default = 10000).** Suits most deployments. Raise it if the
  process holds more long-lived connections (WebSocket, SSE) than that at
  peak.
- **Set to a concrete value** to size the cap to your traffic. A typical
  starting point is 2 × your expected peak concurrent users, adjusted
  upward for long-lived connections (WebSocket, SSE).
- **Pair with `LimitNOFILE`** (systemd) or `ulimit -n` so the OS
  file-descriptor limit doesn't become the surprise cap. Each HTTP
  connection costs one file descriptor; add your database pool size and
  a few dozen for OS housekeeping. Many systems start at 1024, below the
  default cap, so raise the limit or lower the cap to fit.
- **This is a backstop, not a replacement for upstream rate limiting.**
  `SERVER_MAX_CONNECTIONS` stops runaway accumulation; your reverse
  proxy or `rate_limit` middleware should handle per-client or per-IP
  throttling.

A blank value is the same as unset. A zero or unparseable value logs a
warning and falls back to 10000 rather than removing the cap, so a typo
neither stops the server from starting nor leaves it without a cap.

No value of `SERVER_MAX_CONNECTIONS` removes the cap. A server with no cap
is a choice made in code. Make it only when a reverse proxy or the
platform already limits connections and the file-descriptor limit is set
to match:

```rust
use suprnova::{Config, ServerConfig};

Config::register(ServerConfig::builder().unbounded_connections().build());
```

## Heap profiling

To see where a deployment's memory goes, build it with the framework's
`heap-profiling` feature. The framework then installs [dhat]'s
allocator for the whole process, and `#[suprnova::main]` starts its
profiler before anything else runs. A new application has the feature
already, passed through to the framework:

```toml
[features]
heap-profiling = ["suprnova/heap-profiling"]
```

Build it with the `profiling` profile, the release profile with debug
symbols, so the profile's stacks name your functions:

```bash
cargo build --profile profiling --features heap-profiling
SUPRNOVA_HEAP_PROFILE=/tmp/heap.json ./target/profiling/app serve
```

When the process ends normally - a command that finishes, or a server
or worker you stop with SIGTERM or Ctrl-C - it writes the profile and
prints the totals:

```text
dhat: Total:     533,023,630 bytes in 1,144,769 blocks
dhat: At t-gmax: 949,716 bytes in 4,412 blocks
dhat: At t-end:  492,592 bytes in 2,417 blocks
```

The total is everything the process allocated, `t-gmax` the heap at
its peak, and `t-end` what was still allocated when it ended. Open the
file in DHAT's viewer (`dh_view.html`) to see which call stacks
allocated what. Without `SUPRNOVA_HEAP_PROFILE` the file is
`dhat-heap.json` in the working directory.

A profile is written only when the process ends normally: a process
that is killed, or that calls `std::process::exit`, writes none. The
profiler records a backtrace for every allocation, so the process runs
slower while it measures; build a profiling binary for the
investigation, not for production. An application with its own
`#[global_allocator]` cannot turn the feature on, since a process has
only one allocator.

The `profiling` profile on its own also suits a sampling profiler such
as `samply` or `perf`.

[dhat]: https://docs.rs/dhat

## Per-platform walkthroughs

The recipe above ports to every modern PaaS or VPS. The next three
chapters walk you through the specifics:

| Platform | Style | Walkthrough |
|---|---|---|
| Railway | PaaS with auto-deploy from git | [Deploy to Railway](deployment-railway.md) |
| Digital Ocean | App Platform (PaaS) or Droplets (VPS) | [Deploy to Digital Ocean](deployment-digital-ocean.md) |
| Hetzner | VPS with systemd + Caddy | [Deploy to Hetzner](deployment-hetzner.md) |

## Next

- [Environment Variables](env-vars.md) - every env var the framework reads
- [Encryption](encryption.md) - `APP_KEY`, key rotation, what's encrypted
- [Configuration](configuration.md) - typed config sections built on top of env
- [Database](database.md) - driver selection, pool tuning, multi-connection split
- [Queues](queues.md) - worker scaling and queue drivers


---

<!-- /docs/deployment-railway -->

# Deploy to Railway

[Railway](https://railway.app) is a Git-driven PaaS that builds your
Dockerfile and runs it on managed infrastructure. Pair it with Railway's
managed Postgres and Redis and you have a complete Suprnova production
stack with no servers to babysit. This recipe takes a freshly scaffolded
app from `suprnova new` to a live URL.

## Prerequisites

- A [Railway account](https://railway.app)
- A Suprnova project pushed to GitHub, GitLab, or Bitbucket
- A `Dockerfile` and `.dockerignore` at the repo root, generated by:
  ```bash
  suprnova docker:init
  ```
- A generated `APP_KEY` you can paste into Railway's variables:
  ```bash
  suprnova key:generate --show
  ```

`suprnova` is only needed locally - Railway builds the Dockerfile itself.
The framework crate is pulled from git as a normal cargo dependency
during the build.

## Provision the project

1. Open the [Railway dashboard](https://railway.app/dashboard), click
   **New Project**, and choose **Deploy from GitHub repo**.
2. Pick the repository. Railway detects the `Dockerfile` and starts the
   first build automatically.
3. While it's building, add a database: **New** → **Database** →
   **Add PostgreSQL**. Railway exposes `DATABASE_URL` as a reference
   variable on the project.
4. Optionally add Redis the same way (**New** → **Database** → **Redis**)
   if your app uses the Redis cache, session, queue, or rate-limit
   driver. Railway exposes the connection URL as `REDIS_URL`.

## Wire the variables

Open the web service, go to **Variables**, and add the production
configuration. Use Railway's `${{ }}` reference syntax to pull URLs
from the database services so rotations don't require re-pasting.

```env
APP_ENV=production
APP_KEY=<paste the output of `suprnova key:generate --show`>
SERVER_HOST=0.0.0.0
SERVER_PORT=8765
DATABASE_URL=${{ Postgres.DATABASE_URL }}
REDIS_URL=${{ Redis.REDIS_URL }}
```

A few things worth knowing:

- **`APP_KEY` is mandatory in non-development environments.** Suprnova
  fails closed on boot when `APP_ENV != local|dev|test` and `APP_KEY` is
  missing or malformed. The server logs a remediation message and exits
  non-zero - Railway will mark the deploy failed. Generate the key with
  `suprnova key:generate --show`.
- **`SERVER_HOST=0.0.0.0` is required.** Railway routes traffic through
  the container's network interface; binding to `127.0.0.1` (the local
  default) will look like a refused connection.
- **`SERVER_PORT` matches `EXPOSE` in the Dockerfile.** The generated
  Dockerfile exposes 8765. Railway maps it to a public URL automatically.

## Build and deploy

Railway builds on every push to the connected branch. The Dockerfile
generated by `docker:init` does:

1. **Stage 1 - Frontend.** Runs `npm ci` and `npm run build` in
   `frontend/`. The Vite output lands in `frontend/dist/`.
2. **Stage 2 - Backend.** Runs `cargo build --release` against your
   workspace; cached dependency layers keep iterative builds fast.
3. **Stage 3 - Runtime.** A `debian:bookworm-slim` image with
   `ca-certificates` + `libssl3`, a non-root `appuser`, and the compiled
   `./app` binary. Default `CMD` is `./app`, which runs `serve` with
   auto-migrate.

The first build typically takes several minutes (cold Rust cache);
follow-up builds are much faster thanks to Docker layer caching.

## Add a scheduler service

If your app schedules tasks (`impl Task` or `Schedule::call`), the scheduler needs its
own long-running process. Add a second service from the same repo:

1. **New** → **GitHub Repo** → pick the same repository.
2. Name it `scheduler` so it's easy to spot in the dashboard.
3. Under **Settings** → **Deploy** set the **Custom Start Command** to:
   ```bash
   ./app schedule:work
   ```
4. Copy the same variables (especially `APP_KEY` and the database
   references) so the worker reads the same configuration as the web
   service.

`schedule:work` is a daemon loop - it wakes once a minute, queries the
schedule for due tasks, and runs them through the same bootstrap as the
HTTP server. See [Console](console.md) and the scheduler chapter for the
contract.

Run exactly one scheduler instance. Multiple `schedule:work` processes
coordinate via cache-backed locks, but the default expectation is a
single worker.

### Why Suprnova diverges

A Laravel deploy on Forge or Vapor typically wires a webserver
(php-fpm + nginx), a queue worker (`php artisan queue:work`), and a
cron entry that invokes `schedule:run` every minute. Three components,
three deployment surfaces.

Suprnova compiles every role into the same binary. The Railway service
spec is `./app` for the web role and `./app schedule:work` for the
scheduler - same image, same bootstrap, different argv. There is no
separate php-fpm container, no separate worker image, no host cron. Add
`./app queue:work` as a third service if you have queued jobs and you
have the full Laravel topology in three Railway services from one
Dockerfile.

## Health checks and `railway.json`

For more control over the deploy, commit a `railway.json` to the repo
root. Railway picks it up automatically.

```json
{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE",
    "dockerfilePath": "Dockerfile"
  },
  "deploy": {
    "startCommand": "./app",
    "healthcheckPath": "/_suprnova/health/live",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}
```

Suprnova ships built-in health endpoints that short-circuit before the
middleware chain - they return a 200 JSON status without going through
auth, CSRF, or rate-limiting. The `/_suprnova/` prefix is reserved so
they never collide with your routes.

`healthcheckPath` above points at `/_suprnova/health/live`, which
touches nothing. That pairing is deliberate: this service is configured
`"restartPolicyType": "ON_FAILURE"`, so whatever the health check probes
is a restart trigger. Pointing it at the database - via
`/_suprnova/health/ready` or the older `/_suprnova/health?db=true` -
means a database blip restarts every replica at the moment the database
can least afford a reconnect storm. Probe the database from a separate
readiness check or your monitoring, not from the path that restarts the
process. See [Use the right probe for the right
question](deployment.md#use-the-right-probe-for-the-right-question).

Both older paths keep working, so an existing Railway service needs no
change; the named paths are simply clearer.

## Custom domains and TLS

1. In the web service, open **Settings** → **Networking**.
2. Click **Generate Domain** for a `*.up.railway.app` subdomain, or
   **Custom Domain** to point your own hostname at the service.
3. Update DNS as Railway instructs (a `CNAME` for subdomains, an
   ANAME/ALIAS for apex domains).

Railway provisions and renews Let's Encrypt certificates for both
generated and custom domains.

## Migrations in CI/CD

The default `CMD ["./app"]` runs migrations on boot, which is fine for
single-instance deploys. For multi-replica setups, decouple the
migration step:

1. Add a one-shot **pre-deploy hook** that runs `./app migrate` against
   the production database before the new replicas start.
2. Change the runtime start command to `./app serve --no-migrate` so the
   replicas don't race each other.

The migration runner is idempotent - even if you don't split the steps,
running migrations on every boot is safe across replicas. The split
exists so you can fail the deploy early on a bad migration without
holding the rollout open.

## Logs, metrics, rollbacks

The web service tab exposes:

- **Deployments** - every build in chronological order; the
  three-dot menu on a previous successful deploy is the one-click
  rollback path
- **Logs** - `tracing` output from the container, with structured-log
  fields (`request_id`, `route`, `status`) ready for the log viewer's
  filters
- **Metrics** - CPU, memory, network IO; useful for sizing the
  instance up or down

## Troubleshooting

**Build fails on `cargo build --release`.** Reproduce locally with
`docker build -t myapp .`. The most common cause is a workspace member
that compiles on your machine but is missing from the repo - the
Dockerfile copies `Cargo.toml` and `Cargo.lock` first, so missing crates
fail loudly.

**App returns "connection refused".** Check `SERVER_HOST=0.0.0.0` is
set on the service. The default is `127.0.0.1`, which Railway can't
route to.

**App boots then exits with a key error.** `APP_KEY` is unset or
malformed. The framework refuses to boot in production without one;
re-paste the output of `suprnova key:generate --show` into the
service's variables.

**Migrations fail on boot.** Check the logs for the underlying SQL
error. Common causes are an unset `DATABASE_URL` (verify the
`${{ Postgres.DATABASE_URL }}` reference resolved) or a migration that
ran against a stale baseline (`./app migrate:status` reports what's
applied where).

**Scheduler never fires.** Verify the start command is exactly
`./app schedule:work` (not `schedule:run`, which runs due tasks once
and exits). `schedule:list` from a one-shot deploy confirms your tasks
are registered.

## Next

- [Deployment Overview](deployment.md) - the unified-binary model your
  Railway services run
- [Docker CLI](cli-docker.md) - what `docker:init` and `docker:compose`
  actually generate
- [Configuration](configuration.md) - `.env` loading, typed config,
  required keys
- [Console](console.md) - `schedule:work`, `queue:work`,
  `workflow:work`, and the rest of the unified CLI
- [Deploy to Digital Ocean](deployment-digital-ocean.md) - the same
  recipe on a different PaaS


---

<!-- /docs/deployment-digital-ocean -->

# Deploy to Digital Ocean

Digital Ocean has two production targets that suit a Suprnova app: **App
Platform** (a managed Docker PaaS - push and forget) and a **Droplet**
(your own VPS, you manage everything). This chapter walks through both.
Use App Platform when you want managed databases, automatic deploys,
and SSL handled for you. Use a Droplet when you want full control,
already run other services on the box, or want to keep the bill flat
regardless of traffic.

## Prerequisites

- A [Digital Ocean account](https://www.digitalocean.com)
- A Suprnova project with a Dockerfile - generate one with:
  ```bash
  suprnova docker:init
  ```
- An `APP_KEY` for production. Generate one and keep it somewhere safe:
  ```bash
  suprnova key:generate --show
  ```
  Suprnova fails closed on boot when `APP_ENV` is anything other than
  `local` / `development` / `testing` and `APP_KEY` is unset.
- A git repository (GitHub or GitLab) - required for App Platform; for
  Droplets you can also push a prebuilt image to a registry.

## App Platform

App Platform builds your Dockerfile, runs the single Suprnova binary,
and gives you a managed Postgres if you want one.

### 1. Create the app

1. Go to [Digital Ocean Apps](https://cloud.digitalocean.com/apps).
2. Click **Create App**, connect GitHub/GitLab, and pick the repo and
   branch.
3. App Platform auto-detects the `Dockerfile` at the repo root.

### 2. Configure the web service

| Setting | Value |
|---|---|
| Resource type | Web Service |
| HTTP port | `8765` |
| Run command | leave empty - the Dockerfile's `CMD` runs `./app` |
| Health check (HTTP path) | `/_suprnova/health/live` |

The default Suprnova binary runs `serve` with auto-migrations, so the
container will run migrations on startup and then bind the listener.

### 3. Add a managed Postgres

1. **Add Resource** -> **Database** -> **PostgreSQL**.
2. Pick a plan (Dev Database for testing; a Production plan for real
   traffic).

App Platform injects `DATABASE_URL` into every component automatically
via the `${db.DATABASE_URL}` binding.

### 4. Environment variables

In the **Environment Variables** section of your web component, set:

| Variable | Value | Notes |
|---|---|---|
| `APP_ENV` | `production` | triggers the fail-closed `APP_KEY` check |
| `APP_KEY` | output of `suprnova key:generate --show` | mark as **encrypted** |
| `SERVER_HOST` | `0.0.0.0` | bind to all interfaces |
| `SERVER_PORT` | `8765` | matches the Dockerfile's `EXPOSE` |
| `APP_URL` | `https://your-app.ondigitalocean.app` | used by Inertia + signed URLs |

`DATABASE_URL` is provided automatically by the managed database
binding; do not set it manually.

If you use Redis for cache/sessions, add a managed Redis cluster and
set `REDIS_URL` to its binding value (`${redis.REDIS_URL}`).

### 5. Deploy

Click **Create Resources**. The first build takes a few minutes
(Rust release build + frontend build); subsequent builds use the
Dockerfile layer cache and run much faster.

### Add a scheduler worker

Scheduled tasks (`impl Task` handlers and `Schedule::call`
closures) need a long-lived process. Add a Worker component
that runs the same image with a different command:

1. **Create** -> **Add Resource** -> **Detect from source code**, select
   the same repository.
2. Set resource type to **Worker**.
3. **Run command**:
   ```bash
   ./app schedule:work
   ```
4. The worker inherits env vars from the app, including `DATABASE_URL`
   and `APP_KEY`.

Workers don't receive HTTP traffic. Run exactly **one** worker
instance - multiple schedulers would run each task multiple times.

For queue workers (`./app queue:work`) the pattern is identical;
you can usually run more than one queue worker safely because the
queue driver coordinates which worker takes which job. See
[Queues](queues.md).

### App spec (infrastructure as code)

For repeatable deploys, commit a `.do/app.yaml`:

```yaml
name: my-suprnova-app

services:
  - name: web
    dockerfile_path: Dockerfile
    github:
      repo: your-username/your-repo
      branch: main
      deploy_on_push: true
    http_port: 8765
    instance_count: 1
    instance_size_slug: basic-xxs
    health_check:
      # Liveness only - App Platform restarts the container when this
      # fails, so it must not depend on Postgres. See the health-check
      # note under Troubleshooting.
      http_path: /_suprnova/health/live
    envs:
      - key: APP_ENV
        value: production
      - key: APP_KEY
        scope: RUN_TIME
        type: SECRET
        value: ${APP_KEY}
      - key: SERVER_HOST
        value: 0.0.0.0
      - key: SERVER_PORT
        value: "8765"
      - key: APP_URL
        value: https://your-app.ondigitalocean.app
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

workers:
  - name: scheduler
    dockerfile_path: Dockerfile
    github:
      repo: your-username/your-repo
      branch: main
      deploy_on_push: true
    instance_count: 1
    instance_size_slug: basic-xxs
    run_command: ./app schedule:work
    envs:
      - key: APP_ENV
        value: production
      - key: APP_KEY
        scope: RUN_TIME
        type: SECRET
        value: ${APP_KEY}
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

databases:
  - name: db
    engine: PG
    version: "16"
    size: db-s-dev-database
```

Deploy with the `doctl` CLI:

```bash
doctl apps create --spec .do/app.yaml
```

Set the secret `APP_KEY` separately via the Apps UI or:

```bash
doctl apps update <app-id> --spec .do/app.yaml \
  --set-env "APP_KEY=$(suprnova key:generate --show)"
```

### Custom domain

In **Settings** -> **Domains** -> **Add Domain**, enter your domain and
follow the DNS instructions. App Platform issues and renews a
Let's Encrypt certificate automatically.

After the domain is live, update `APP_URL` to match - Inertia uses it
for the X-Inertia-Location header and signed URLs use it for the
hash input.

### Scaling

- **Horizontal**: bump **Instance Count** on the web service. Each
  instance shares the managed Postgres; multiple instances running
  auto-migrations on startup is safe - Suprnova uses SeaORM's
  advisory-locked migrator.
- **Vertical**: change **Instance Size**. The Rust binary is happy on
  the smallest slug for low-traffic apps; bump up when you start
  serving WebSockets or long-lived connections at scale.

Keep the scheduler worker at instance count **1**.

## Droplet (VPS)

A Droplet is the path when you want to run Suprnova on your own
VPS. The mechanics are identical to any other Linux VPS - systemd
service, Caddy reverse proxy, managed or self-hosted Postgres. The
[Hetzner VPS](deployment-hetzner.md) chapter is the canonical
walkthrough for that pattern; everything there applies verbatim on a
Droplet. The only differences worth calling out:

- **Image**: pick **Ubuntu 24.04** or **Debian 12** in the Droplet
  console.
- **Database**: you can use Digital Ocean's **Managed Databases** for
  Postgres / MySQL / Redis instead of running them on the Droplet -
  same `DATABASE_URL` / `REDIS_URL` story, point them at the managed
  endpoint and Suprnova doesn't notice the difference.
- **Backups**: enable Droplet snapshots and managed DB daily backups
  in the DO console.
- **Networking**: use a DO **VPC** to keep the Droplet and any managed
  databases on a private network; bind the listener to `127.0.0.1` and
  put Caddy in front for TLS.

If you want Docker on a Droplet (instead of a system binary), the
docker-compose pattern from [Docker](cli-docker.md) drops in cleanly -
swap the self-hosted Postgres for the managed database and you're done.

### Why Suprnova diverges

Laravel's typical PHP deploy needs PHP-FPM + an opcache + a queue
runner + a scheduler cron entry - at least three moving pieces, each
with its own restart semantics. A Suprnova deploy is a single binary
plus an optional worker process. The binary runs migrations, serves
HTTP, handles WebSockets, and lives behind a reverse proxy. The same
binary, invoked with `./app schedule:work` or `./app queue:work`, is
your scheduler or queue worker. App Platform's "one image, multiple
components" model fits this naturally - same Dockerfile for every
component, different `run_command` per role.

## Troubleshooting

### Build fails

The first thing to check is whether the Dockerfile builds locally:

```bash
docker build -t myapp .
```

Common causes when the local build works but App Platform's doesn't:

- **Missing build context files**: check `.dockerignore` isn't
  excluding `Cargo.lock` or the `migrations/` directory.
- **Out-of-memory during cargo build**: bump the build instance size
  in App Settings -> Resources -> Build. Rust release builds are
  memory-hungry.

### App boots, then crashes on startup

Check the runtime logs in the **Runtime Logs** tab. The two most
common Suprnova boot failures are:

- **`APP_KEY is required when APP_ENV=production`** - generate one with
  `suprnova key:generate --show` and add it as an encrypted env var.
- **`SERVER_HOST=…` value invalid** - must be `0.0.0.0` for App
  Platform, not `127.0.0.1` (the loopback isn't reachable from the
  load balancer).

### Health check failing

The platform pings `/_suprnova/health/live` and expects a 200 within the
configured timeout. If it's failing:

- Confirm the path is `/_suprnova/health/live` exactly (not `/health`).
  The older `/_suprnova/health` still works if that is what your spec
  already names.
- Confirm the port is `8765` and matches `SERVER_PORT`.
- To tell "can't bind" from "can't reach Postgres", probe the database
  **by hand** from the console rather than from the health check:

  ```bash
  curl http://localhost:8765/_suprnova/health/ready
  # Healthy:  200 {"status":"ok","database":"connected"}
  # Degraded: 503 {"status":"degraded","database":"error"}
  ```

  A degraded response means the app bound but cannot reach Postgres -
  check the `DATABASE_URL` binding. Don't pass `-f`: it makes curl exit
  silently on the 503, which is the case you are trying to read.

Do not put the database probe in the app spec's `health_check`. App
Platform restarts the container when that check fails, so a database
blip would take the app down with it - the failure mode is a restart
loop during exactly the incident you need the app to survive. See [Use
the right probe for the right
question](deployment.md#use-the-right-probe-for-the-right-question).

### Database migrations not running

Migrations run automatically as part of the default `./app` boot. If
they're not, check the runtime logs for SeaORM errors. To run them
manually from the App Platform console:

1. Open the **Console** tab on the web component.
2. Run `./app migrate`.

If you prefer to keep migrations out of the boot path, set the run
command to `./app serve --no-migrate` and add a one-shot **Job** to
the app spec that runs `./app migrate` pre-deploy.

## Next

- [Deployment Overview](deployment.md) - the cross-platform deploy
  primer (binary, migrations, scheduler, health)
- [Docker](cli-docker.md) - what `suprnova docker:init` and
  `docker:compose` generate
- [Configuration](configuration.md) - every env var Suprnova reads
- [Environment Variables](env-vars.md) - full reference, including
  the production-required ones
- [Deploy to Hetzner VPS](deployment-hetzner.md) - Droplet
  walkthrough applies here verbatim


---

<!-- /docs/deployment-hetzner -->

# Deploy to Hetzner VPS

This guide covers deploying a Suprnova application to a VPS using Hetzner Cloud. The same principles apply to any single-box host - Linode, Vultr, AWS EC2, or a dedicated server you already own. Choose this path when you want full control of the box, predictable monthly cost, and the ability to colocate Postgres / Redis on the same machine.

Throughout the guide we use `myapp` as the project name and `myapp.com` as the domain - substitute your own.

## Prerequisites

- A VPS running Ubuntu 22.04 or Debian 12
- SSH access to your server
- A domain name pointed to your server's IP address
- A Suprnova project - either a working source tree, or a Dockerfile generated with `suprnova docker:init` (see [Docker](cli-docker.md))

## Server Setup

### 1. Create a VPS

1. Go to [Hetzner Cloud Console](https://console.hetzner.cloud)
2. Create a new project and add a server
3. Choose **Ubuntu 22.04** as the image
4. Select your server size (CX11 is fine for small apps)
5. Add your SSH key for secure access

### 2. Initial Server Configuration

SSH into your server and run initial setup:

```bash
# Update packages
apt update && apt upgrade -y

# Create a non-root user for your app
useradd -m -s /bin/bash app
mkdir -p /opt/myapp
chown app:app /opt/myapp

# Install required packages
apt install -y curl postgresql redis-server
```

### 3. Configure PostgreSQL

```bash
# Create database and user
sudo -u postgres psql << EOF
CREATE USER myapp WITH PASSWORD 'your_secure_password';
CREATE DATABASE myapp_production OWNER myapp;
GRANT ALL PRIVILEGES ON DATABASE myapp_production TO myapp;
EOF
```

> **Tip:**
>
> For production, consider using a managed database service like Hetzner's upcoming managed PostgreSQL, or services like Neon, Supabase, or AWS RDS for better reliability and backups.


## Deploy Options

Choose one of the following deployment methods. Each one ends with a binary (or container) named `app` sitting at `/opt/myapp/app`, which the systemd unit below knows how to run.

### Option A: Build Locally

Build on your machine and upload the binary. Replace `myapp` with your actual project name - `cargo build` names the binary after the `[package].name` in `Cargo.toml`:

```bash
# On your local machine - cross-compile for Linux (if on macOS)
cargo build --release --target x86_64-unknown-linux-gnu

# Or build with Docker for Linux (the Dockerfile renames the binary to `app`)
docker build -t myapp .
docker create --name temp myapp
docker cp temp:/app/app ./app-linux
docker rm temp

# Upload to the server, renaming to `app` on landing
scp target/x86_64-unknown-linux-gnu/release/myapp root@your-server:/opt/myapp/app
# or, if you went the Docker route:
scp ./app-linux root@your-server:/opt/myapp/app
```

### Option B: Build on Server

Install Rust 1.94.0+ for current `main` (Suprnova uses the 2024 edition) and build directly on the server:

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Clone, build, and place the binary at the standard path
cd /opt/myapp
git clone https://github.com/your-username/your-repo.git .
cargo build --release
cp target/release/myapp ./app   # rename so systemd's ExecStart=/opt/myapp/app finds it
```

Current `main` uses SeaORM 2.0, SeaQuery 1.0, and SQLx 0.9. Direct SeaORM
callers must import `ExprTrait` for expression methods and use explicit
`*_raw` methods for prebuilt `Statement` values. Existing application data
requires no migration.

### Option C: Use Docker

Run your app in a Docker container - the scaffolded Dockerfile already names the runtime binary `app` (see [Docker](cli-docker.md)):

```bash
# Install Docker
curl -fsSL https://get.docker.com | sh

# Pull and run your image
docker run -d \
  --name myapp \
  --restart unless-stopped \
  -p 8765:8765 \
  --env-file /opt/myapp/.env.production \
  your-registry/myapp:latest
```

If you went with Docker, skip past the systemd section to [Caddy Reverse Proxy](#caddy-reverse-proxy) - Docker handles process supervision.

## Environment Configuration

First, generate a production `APP_KEY` on the server (or locally - the value is what matters). `APP_KEY` is a 32-byte AES-256 key used by `suprnova::Crypt` for session cookies and signed URLs. Suprnova **fails closed at boot** when `APP_ENV` is not `local`/`dev`/`test` and `APP_KEY` is unset - so this is non-optional in production:

```bash
suprnova key:generate --show
# -> APP_KEY=base64-url-safe-32-bytes
```

Then write the env file:

```bash
cat > /opt/myapp/.env.production << 'EOF'
APP_NAME="My App"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://myapp.com
APP_KEY=paste-the-generated-key-here

SERVER_HOST=127.0.0.1
SERVER_PORT=8765

# Caddy terminates TLS in front of the application and sends
# X-Forwarded-Proto. Trust it, so the application knows a request arrived
# over https: the same-origin check of a WebSocket route needs that.
APP_TRUSTED_PROXIES=127.0.0.1

# Database - bind to localhost when DB is on the same box
DATABASE_URL=postgres://myapp:your_secure_password@localhost:5432/myapp_production
DB_MAX_CONNECTIONS=10
DB_MIN_CONNECTIONS=1

# Session
SESSION_SECURE=true
SESSION_SAME_SITE=Lax

# Redis (optional - used by cache, queue, broadcasting drivers)
REDIS_URL=redis://127.0.0.1:6379

# Mail
MAIL_DRIVER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_FROM_ADDRESS=hello@myapp.com
MAIL_FROM_NAME="My App"
EOF

# Secure the file - only the app user should be able to read it
chmod 600 /opt/myapp/.env.production
chown app:app /opt/myapp/.env.production
```

See [Configuration](configuration.md) for the full env surface and how it becomes typed config.

## systemd Services

A Suprnova binary supports multiple commands - `./app` (serve, with auto-migrate), `./app schedule:work` (scheduler daemon), `./app queue:work` (queue worker), `./app workflow:work` (workflow runner). Each long-running process gets its own systemd unit using the same binary and env file.

### Web Server Service

Create `/etc/systemd/system/myapp.service`:

```ini
[Unit]
Description=Suprnova Application
After=network.target postgresql.service redis.service
Requires=postgresql.service

[Service]
Type=simple
User=app
Group=app
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/app
Restart=always
RestartSec=5

# Environment
EnvironmentFile=/opt/myapp/.env.production

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/opt/myapp

[Install]
WantedBy=multi-user.target
```

The default `ExecStart=/opt/myapp/app` runs `serve` with auto-migration. If you prefer migrations to be a separate deploy step, use `ExecStart=/opt/myapp/app serve --no-migrate` and run `./app migrate` from your deploy script before flipping the binary.

### Scheduler Service

If your app has tasks registered via `Schedule::call(...)` (see the [Scheduling](cli-scheduling.md) chapter), run **exactly one** scheduler process to avoid duplicate task execution. Create `/etc/systemd/system/myapp-scheduler.service`:

```ini
[Unit]
Description=Suprnova Scheduler
After=network.target myapp.service
Requires=myapp.service

[Service]
Type=simple
User=app
Group=app
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/app schedule:work
Restart=always
RestartSec=5

# Environment
EnvironmentFile=/opt/myapp/.env.production

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/opt/myapp

[Install]
WantedBy=multi-user.target
```

### Queue Worker (optional)

If you dispatch jobs to a queue, add `/etc/systemd/system/myapp-queue.service`:

```ini
[Unit]
Description=Suprnova Queue Worker
After=network.target myapp.service
Requires=myapp.service

[Service]
Type=simple
User=app
Group=app
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/app queue:work
Restart=always
RestartSec=5

EnvironmentFile=/opt/myapp/.env.production

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/opt/myapp

[Install]
WantedBy=multi-user.target
```

You can scale queue workers horizontally - multiple `myapp-queue.service` instances on the same or different boxes is safe.

### Enable and Start Services

```bash
# Reload systemd after writing unit files
systemctl daemon-reload

# Enable services so they start on boot
systemctl enable myapp
systemctl enable myapp-scheduler
systemctl enable myapp-queue        # if you added the queue worker

# Start them now
systemctl start myapp
systemctl start myapp-scheduler
systemctl start myapp-queue

# Verify
systemctl status myapp
systemctl status myapp-scheduler
systemctl status myapp-queue
```

## Caddy Reverse Proxy

Caddy automatically handles HTTPS certificates with Let's Encrypt.

### Install Caddy

```bash
apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install caddy
```

### Configure Caddy

Edit `/etc/caddy/Caddyfile`:

```
myapp.com {
    reverse_proxy localhost:8765

    # Enable compression
    encode gzip

    # Logging
    log {
        output file /var/log/caddy/myapp.log
    }
}
```

Caddy sends `X-Forwarded-Proto` and `X-Forwarded-For` on every proxied
request. `APP_TRUSTED_PROXIES=127.0.0.1` in the env file above lets the
application believe them, which the same-origin check of a WebSocket route
relies on; see [WebSockets](websockets.md#same-origin-behind-a-proxy).

Replace `myapp.com` with your actual domain.

### Start Caddy

```bash
systemctl enable caddy
systemctl start caddy
```

Caddy will automatically obtain and renew SSL certificates.

## Health Checks

Suprnova ships a built-in `/_suprnova/health` endpoint that short-circuits before the middleware chain and never collides with your routes:

```bash
curl https://myapp.com/_suprnova/health
```

```json
{
  "status": "ok",
  "timestamp": "2026-05-30T10:30:00Z"
}
```

### Check Database Connectivity

Add `?db=true` to also verify the database:

```bash
curl https://myapp.com/_suprnova/health?db=true
```

Healthy response (HTTP 200):

```json
{
  "status": "ok",
  "timestamp": "2026-05-30T10:30:00Z",
  "database": "connected"
}
```

If the database check fails, the endpoint flips to HTTP **503** with `"status": "degraded"` and a `"database_error"` field - wire this into a `livenessProbe` / `readinessProbe` style health check so the load balancer can remove an unhealthy instance from rotation.

### External Monitoring

Use the health endpoint with monitoring services:

- **UptimeRobot**: Add HTTP monitor for `https://myapp.com/_suprnova/health`
- **Better Stack** (formerly Better Uptime): Configure health check endpoint with the 503 trigger
- **Prometheus / Grafana**: Scrape the JSON body for `status` + `database` fields

## Deployment Script

Create a deployment script for atomic updates. Replace `myapp` with your project name (the `[package].name` in `Cargo.toml`) - that's what `cargo build` names the output binary:

```bash
#!/bin/bash
# deploy.sh - Run on your local machine

set -e

PROJECT="myapp"               # the Cargo package name
SERVER="root@your-server"
APP_PATH="/opt/myapp"
BIN="target/x86_64-unknown-linux-gnu/release/$PROJECT"

echo "Building application..."
cargo build --release --target x86_64-unknown-linux-gnu

echo "Uploading binary..."
scp "$BIN" "$SERVER:$APP_PATH/app.new"

echo "Deploying..."
ssh "$SERVER" << 'EOF'
    set -e
    cd /opt/myapp

    # Stop long-running services (ignore failures on first deploy)
    systemctl stop myapp-queue || true
    systemctl stop myapp-scheduler || true
    systemctl stop myapp

    # Atomic swap - rename is single-syscall on the same filesystem
    mv app.new app
    chmod +x app

    # Run migrations explicitly (the unit also auto-migrates, but doing
    # it here surfaces failures before we restart traffic)
    sudo -u app ./app migrate

    # Start services
    systemctl start myapp
    systemctl start myapp-scheduler || true
    systemctl start myapp-queue || true

    # Verify health (give the server a moment to bind)
    sleep 2
    curl -fsS http://localhost:8765/_suprnova/health?db=true > /dev/null || exit 1

    echo "Deployment complete!"
EOF
```

Make it executable:

```bash
chmod +x deploy.sh
./deploy.sh
```

## Logs and Monitoring

### View Logs

```bash
# Web server logs
journalctl -u myapp -f

# Scheduler logs
journalctl -u myapp-scheduler -f

# Caddy access logs
tail -f /var/log/caddy/myapp.log
```

### Log Rotation

systemd's journald handles log rotation automatically. For long-term storage, consider:

- **Loki + Grafana**: Self-hosted log aggregation
- **Papertrail**: Cloud-based logging service
- **Logtail**: Simple log management

## Firewall Configuration

Secure your server with UFW:

```bash
# Allow SSH
ufw allow 22/tcp

# Allow HTTP/HTTPS (Caddy)
ufw allow 80/tcp
ufw allow 443/tcp

# Enable firewall
ufw enable
```

> **Warning:**
>
> Never expose port 8765 directly. Always use Caddy as a reverse proxy to handle SSL and security headers.


## Scaling

A single Suprnova binary is very efficient - a small VPS handles a surprising amount of traffic before you need to scale out. When you do:

### Vertical Scaling

Upgrade the VPS to a larger instance for more CPU/memory. The binary, env file, and systemd units come with you unchanged.

### Horizontal Scaling

For multiple application instances:

1. Set up a load balancer (Hetzner Load Balancer, HAProxy, or Caddy on a dedicated node)
2. Move Postgres to a managed service or a dedicated node so app boxes are stateless
3. Move sessions, cache, and broadcasting to Redis so any app instance can serve any request
4. Deploy multiple app instances; each one safely runs its own auto-migrate on boot (the migration runner takes a lock so concurrent boots don't collide)
5. Keep **one** scheduler (`schedule:work`) running across the whole fleet - queue workers are safe to run in parallel, the scheduler isn't

### Why Suprnova diverges

Laravel typically runs PHP-FPM behind nginx, with cron triggering `schedule:run` once a minute and Horizon (or supervisord) managing queue workers. Suprnova collapses this into one binary with subcommands. `./app` is a long-lived Tokio process - it doesn't need a process pool in front of it, doesn't need a separate cron, and stays warm across requests. systemd is the supervisor for both the web process and the workers, and Caddy is doing only what nginx couldn't avoid: terminating TLS and proxying.

## Sizing

Pick a VPS based on workload, not on a marketing tier name. Hetzner's lineup changes periodically; the sizing logic doesn't:

| Workload | Rough fit |
|---|---|
| Small site, low traffic, SQLite or shared DB | Smallest shared-vCPU instance (1 vCPU / 2 GB) |
| Moderate traffic with Postgres + Redis on the same box | 2 vCPU / 4 GB |
| Heavier API + scheduler + queue workers + Postgres | 2-4 vCPU / 8 GB |
| Production at scale | Dedicated CPU instance, or split DB onto its own node |

Check Hetzner's [current pricing](https://www.hetzner.com/cloud) for the live catalogue. Suprnova's idle memory footprint is small (single-digit MB), so RAM is mostly database working set plus your domain code.

## Troubleshooting

### Service Won't Start

Check logs for errors:

```bash
journalctl -u myapp -n 50
```

Common issues:
- Missing environment variables
- Database connection failed
- Port already in use

### Caddy Certificate Errors

Ensure:
- Domain DNS points to your server
- Ports 80 and 443 are open
- No other service is using port 80

```bash
caddy validate --config /etc/caddy/Caddyfile
```

### Database Connection Issues

Test connection manually:

```bash
sudo -u app psql $DATABASE_URL -c "SELECT 1"
```

### Health Check Failing

```bash
# Check if app is running
systemctl status myapp

# Test health endpoint directly
curl http://localhost:8765/_suprnova/health

# Check with database
curl http://localhost:8765/_suprnova/health?db=true
```

A `503` response with `"status": "degraded"` means the app is up but the database health check failed - inspect `database_error` in the body and check the `DATABASE_URL`, Postgres logs, and connection limits.

## Next

- [Deployment Overview](deployment.md) - the platform-agnostic story for single-binary deploys
- [Docker](cli-docker.md) - `docker:init` and `docker:compose` details
- [Configuration](configuration.md) - full env surface and typed config
- [Deploy to Railway](deployment-railway.md) - PaaS alternative with automatic builds
- [Deploy to Digital Ocean](deployment-digital-ocean.md) - App Platform with managed infrastructure


# Tutorials

---

<!-- /docs/tutorial-json-api -->

# Build a Todo JSON:API

A walk-through of the API path end-to-end: migration, model, validated
form requests, route model binding, JSON:API resource envelopes,
sparse fieldsets, pagination. By the end you have a five-endpoint
todo service that emits spec-conformant
[JSON:API](https://jsonapi.org/) responses with `?include=` and
`?fields[todos]=...` honoured automatically.

What you'll build:

| Method   | Route                | Action  |
|----------|----------------------|---------|
| `GET`    | `/api/todos`         | list (paginated) |
| `GET`    | `/api/todos/{todo}`  | show |
| `POST`   | `/api/todos`         | create |
| `PUT`    | `/api/todos/{todo}`  | update |
| `DELETE` | `/api/todos/{todo}`  | delete |

## Prerequisites

A scaffolded project:

```bash
suprnova new todo-api
cd todo-api
```

## Step 1: The migration

```bash
suprnova make:migration create_todos_table
```

That writes `src/migrations/m<timestamp>_create_todos_table.rs`.
Replace the body with the schema for `todos`:

```rust
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .create_table(
                Table::create()
                    .table(Todos::Table)
                    .if_not_exists()
                    .col(
                        ColumnDef::new(Todos::Id)
                            .big_integer()
                            .not_null()
                            .auto_increment()
                            .primary_key(),
                    )
                    .col(ColumnDef::new(Todos::Title).string().not_null())
                    .col(ColumnDef::new(Todos::Description).text().null())
                    .col(
                        ColumnDef::new(Todos::Done)
                            .boolean()
                            .not_null()
                            .default(false),
                    )
                    .col(
                        ColumnDef::new(Todos::CreatedAt)
                            .timestamp_with_time_zone()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .col(
                        ColumnDef::new(Todos::UpdatedAt)
                            .timestamp_with_time_zone()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .to_owned(),
            )
            .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .drop_table(Table::drop().table(Todos::Table).to_owned())
            .await
    }
}

#[derive(DeriveIden)]
enum Todos {
    Table,
    Id,
    Title,
    Description,
    Done,
    CreatedAt,
    UpdatedAt,
}
```

Run it:

```bash
suprnova migrate
```

The `down` body lets `migrate:rollback` reverse the change later.

## Step 2: The model

A `#[suprnova::model]` struct *is* the Eloquent model - the macro
emits the SeaORM `Entity`, `Column`, and `ActiveModel` in an inner
module and gives the struct the query surface (`Todo::query()`,
`Todo::find`, `Todo::create`, `model.update`, `model.delete`,
auto-managed timestamps, lifecycle events). Create `src/models/todo.rs`:

```rust
use chrono::{DateTime, Utc};
use suprnova::model;

#[model(
    table = "todos",
    fillable = ["title", "description", "done"],
    timestamps,
)]
pub struct Todo {
    pub id: i64,
    pub title: String,
    pub description: Option<String>,
    pub done: bool,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

// Re-export the SeaORM types the macro emits in the inner `todo`
// module so call sites can reach for them without poking at the macro
// internals.
pub use todo::{ActiveModel, Column, Entity};
```

Wire the module into `src/models/mod.rs`:

```rust
pub mod todo;
```

The `fillable` list is the mass-assignment allowlist - only those
fields can be set via `Todo::create(attrs!{...})` and
`model.update(attrs!{...})`. Fields outside the list are guarded
against accidental writes from request input.

## Step 3: The form requests

Validation lives on a `#[request]` struct. `extract()` runs the
validator before the handler body sees the value; a failure short-
circuits to a 422 with the Laravel/Inertia error bag. Create
`src/requests.rs`:

```rust
use suprnova::request;

#[request]
pub struct CreateTodoRequest {
    #[validate(length(min = 1, max = 255, message = "title is required"))]
    pub title: String,

    #[validate(length(max = 1000))]
    pub description: Option<String>,
}

#[request]
pub struct UpdateTodoRequest {
    #[validate(length(min = 1, max = 255))]
    pub title: Option<String>,

    #[validate(length(max = 1000))]
    pub description: Option<String>,

    pub done: Option<bool>,
}
```

And register it in `src/lib.rs`:

```rust
pub mod requests;
```

The `#[request]` attribute expands to the equivalent of
`#[derive(serde::Deserialize, validator::Validate)] + impl FormRequest`,
so the struct fields are also the input schema. Optional fields
(`Option<T>`) are the right shape for partial updates: a missing key
in the JSON body deserialises to `None`, and the handler treats
`None` as "don't change this column".

## Step 4: The JSON:API resource

A resource is a `#[derive(Data)]` struct with `#[json_resource("type")]`.
The macro emits the `IntoJsonResource` impl that `Resource::single`,
`Resource::collection`, and `Resource::paginated` consume. The
resource's fields become the JSON:API `attributes` object - every
sparse-fieldset filter and `?include=` chain dispatches through this
type. Create `src/resources/todo_resource.rs`:

```rust
use crate::models::todo::Todo;
use suprnova::Data;
use validator::Validate;

#[derive(Debug, Clone, Data, Validate)]
#[json_resource("todos")]
pub struct TodoResource {
    pub id: i64,
    pub title: String,
    pub description: Option<String>,
    pub done: bool,
    pub created_at: String,
    pub updated_at: String,
}

impl From<Todo> for TodoResource {
    fn from(t: Todo) -> Self {
        Self {
            id: t.id,
            title: t.title,
            description: t.description,
            done: t.done,
            created_at: t.created_at.to_rfc3339(),
            updated_at: t.updated_at.to_rfc3339(),
        }
    }
}
```

Wire it in `src/resources/mod.rs`:

```rust
pub mod todo_resource;
```

And re-declare the module in `src/lib.rs`:

```rust
pub mod resources;
```

The `id` field supplies the JSON:API `id` member (stringified per
spec); every other field lands in `attributes` and is subject to
sparse-fieldset filtering - a request that names
`?fields[todos]=title,done` gets back only those two attributes,
without any handler-side work.

## Step 5: The controller

The `#[handler]` attribute classifies each parameter and generates
the matching extractor:

- `i64` - `FromParam` parses the named route param of the same name.
  Bad input (`/api/todos/abc`) short-circuits to 400.
- `CreateTodoRequest` / `UpdateTodoRequest` - `FromRequest`
  deserialises the body, runs validation, and 422s on failure.
- `Request` - passed through unchanged.

Loading the row goes through the Eloquent surface: `Todo::find_or_fail(id)`
returns a 404 when no row matches.

Create `src/controllers/todos.rs`:

```rust
use crate::models::todo::Todo;
use crate::requests::{CreateTodoRequest, UpdateTodoRequest};
use crate::resources::todo_resource::TodoResource;
use suprnova::{
    attrs, handler, LengthAwarePaginator, Model, Resource, Response,
};

// GET /api/todos?page=2
#[handler]
pub async fn index() -> Response {
    let page = Todo::query()
        .order_by_desc("created_at")
        .paginate(20)
        .await?;
    // Re-pack the paginator around `TodoResource` so the JSON:API
    // renderer sees resource objects, not raw models. The pagination
    // window (`total`, `per_page`, `current_page`) is preserved.
    let total = page.total;
    let per_page = page.per_page;
    let current_page = page.current_page;
    let resources: Vec<TodoResource> =
        page.data.into_iter().map(TodoResource::from).collect();
    let paginator = LengthAwarePaginator::new(resources, total, per_page, current_page)
        .with_path("/api/todos");
    Resource::paginated(paginator).render().await
}

// GET /api/todos/{todo}
#[handler]
pub async fn show(todo: i64) -> Response {
    let todo = Todo::find_or_fail(todo).await?;
    Resource::single(TodoResource::from(todo)).render().await
}

// POST /api/todos
#[handler]
pub async fn store(form: CreateTodoRequest) -> Response {
    let todo = Todo::create(attrs! {
        title: form.title,
        description: form.description,
        done: false,
    })
    .await?;
    Resource::single(TodoResource::from(todo))
        .created()           // 201
        .render()
        .await
}

// PUT /api/todos/{todo}
#[handler]
pub async fn update(todo: i64, form: UpdateTodoRequest) -> Response {
    let row = Todo::find_or_fail(todo).await?;

    let mut changes = attrs!();
    if let Some(title) = form.title {
        changes.insert("title", title.into());
    }
    if let Some(description) = form.description {
        changes.insert("description", description.into());
    }
    if let Some(done) = form.done {
        changes.insert("done", done.into());
    }
    let updated = row.update(changes).await?;
    Resource::single(TodoResource::from(updated)).render().await
}

// DELETE /api/todos/{todo}
#[handler]
pub async fn destroy(todo: i64) -> Response {
    Todo::find_or_fail(todo).await?.delete().await?;
    suprnova::json_response!({ "deleted": true })
}
```

Wire it in `src/controllers/mod.rs`:

```rust
pub mod todos;
```

The argument name must match the route placeholder - `{todo}` maps
to `todo: i64`. The macro parses the path segment via `FromParam`,
and the handler body then drives the Eloquent surface to load,
update, and delete the row.

## Step 6: The routes

`src/routes.rs`:

```rust
use crate::controllers::todos;
use suprnova::{delete, get, post, put, routes};

routes! {
    get!("/api/todos",           todos::index   ).name("todos.index"),
    get!("/api/todos/{todo}",    todos::show    ).name("todos.show"),
    post!("/api/todos",          todos::store   ).name("todos.store"),
    put!("/api/todos/{todo}",    todos::update  ).name("todos.update"),
    delete!("/api/todos/{todo}", todos::destroy ).name("todos.destroy"),
}
```

The `routes!` macro returns a configured `Router` that
`Application::routes(...)` consumes at boot.

## Step 7: Run it

```bash
suprnova serve --backend-only
```

### Create

```bash
curl -X POST http://localhost:8765/api/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Read JSON:API spec", "description": "All of it"}'
```

```json
{
  "data": {
    "type": "todos",
    "id": "1",
    "attributes": {
      "title": "Read JSON:API spec",
      "description": "All of it",
      "done": false,
      "created_at": "2026-05-30T12:00:00+00:00",
      "updated_at": "2026-05-30T12:00:00+00:00"
    }
  }
}
```

### List (paginated)

```bash
curl http://localhost:8765/api/todos
```

```json
{
  "data": [
    { "type": "todos", "id": "1", "attributes": { … } }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1
    }
  },
  "links": {
    "first": "?page=1",
    "last":  "?page=1",
    "prev":  null,
    "next":  null
  }
}
```

### Sparse fieldsets

```bash
curl 'http://localhost:8765/api/todos/1?fields[todos]=title,done'
```

```json
{
  "data": {
    "type": "todos",
    "id": "1",
    "attributes": { "title": "Read JSON:API spec", "done": false }
  }
}
```

The `IncludeMiddleware` parses `?fields[type]=...`, binds the filter
to a task-local, and `Resource::single` reads it during render -
the handler doesn't see the query parameter at all.

### Update

```bash
curl -X PUT http://localhost:8765/api/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"done": true}'
```

A partial body works because every field in `UpdateTodoRequest` is
`Option<T>` - the handler only writes the keys that arrived.

### Delete

```bash
curl -X DELETE http://localhost:8765/api/todos/1
# {"deleted": true}
```

### Validation failure

```bash
curl -X POST http://localhost:8765/api/todos \
  -H "Content-Type: application/json" \
  -d '{"title": ""}'
```

```json
{
  "message": "The given data was invalid.",
  "errors": { "title": ["title is required"] },
  "request_id": "8f9e1a2b-…"
}
```

422 with the Laravel/Inertia error bag - the handler body never ran.

## Where each piece lives

| File | Role |
|------|------|
| `src/migrations/m*_create_todos_table.rs` | schema |
| `src/models/todo.rs` | `#[suprnova::model]` struct |
| `src/requests.rs` | `#[request]` form requests, validated by `extract()` |
| `src/resources/todo_resource.rs` | `#[derive(Data)]` + `#[json_resource("todos")]` |
| `src/controllers/todos.rs` | `#[handler]` functions |
| `src/routes.rs` | `routes!` registrations |

## Next

- [Eloquent](eloquent.md) - the full Model surface, query builder,
  `attrs!`, lifecycle events, soft deletes, relationships
- [Validation](validation.md) - `#[request]`, `validate!`, `Unique`,
  async hooks, cross-field rules
- [JSON:API Resources](eloquent-resources.md) - `?include=` chains,
  per-resource links/meta, `Maybe<T>` conditional attributes
- [Form Requests](requests.md) - `FormRequest` trait, content-type
  dispatch, `authorize(&Request)`
- [Controllers](controllers.md) - what `#[handler]` extracts and how
  route model binding works under the hood


---

<!-- /docs/tutorial-inertia-crud -->

# Build a Todo App with Inertia

A vertical slice of Suprnova that exercises the full stack: a migration, a
`#[suprnova::model]`, Inertia-rendered Svelte 5 pages, route model binding,
form validation, and type-safe route helpers generated from `routes.rs`.
Work through this once and the project loop - migration, model, controller,
route, page - becomes muscle memory.

This assumes you've followed [Installation](installation.md) and have the
`suprnova` CLI on your `PATH`. The scaffolder defaults to Svelte 5, which
is what this tutorial uses.

## What you'll build

A todo page with create, list, toggle-complete, edit, and delete. No
separate JSON API: Inertia serialises props and the Svelte page consumes
them as `$props()` - the same struct flows from Rust to the browser.

## 1. Scaffold

```bash
suprnova new todo-app --frontend svelte --no-interaction
cd todo-app
npm install
```

## 2. Migration

```bash
suprnova make:migration create_todos_table
```

Open the new migration under `src/migrations/`:

```rust
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .create_table(
                Table::create()
                    .table(Alias::new("todos"))
                    .if_not_exists()
                    .col(ColumnDef::new(Alias::new("id"))
                        .big_integer().primary_key().auto_increment().not_null())
                    .col(ColumnDef::new(Alias::new("title")).string().not_null())
                    .col(ColumnDef::new(Alias::new("completed"))
                        .boolean().not_null().default(false))
                    .col(ColumnDef::new(Alias::new("created_at"))
                        .timestamp_with_time_zone().not_null()
                        .default(Expr::current_timestamp()))
                    .col(ColumnDef::new(Alias::new("updated_at"))
                        .timestamp_with_time_zone().not_null()
                        .default(Expr::current_timestamp()))
                    .to_owned(),
            )
            .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .drop_table(Table::drop().table(Alias::new("todos")).to_owned())
            .await
    }
}
```

Both `created_at` and `updated_at` are present because the model in the
next step uses `timestamps`, which expects both columns and auto-manages
them. Then run migrations and regenerate entities:

```bash
suprnova db:sync
```

`db:sync` runs pending migrations and refreshes the SeaORM entity layer
the `#[suprnova::model]` macro relies on.

## 3. Model

Create `src/models/todo.rs`:

```rust
use chrono::{DateTime, Utc};
use suprnova::model;

#[model(
    table = "todos",
    fillable = ["title", "completed"],
    timestamps,
)]
pub struct Todo {
    pub id: i64,
    pub title: String,
    pub completed: bool,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

// The model macro emits an inner `todo` module with the SeaORM
// Entity, ActiveModel, Column, and Model types. Re-export the ones
// you want to reach from outside the file.
pub use todo::{ActiveModel, Column, Entity};
```

Wire the new module in `src/models/mod.rs`:

```rust
pub mod todo;
```

The `fillable` list gates mass assignment; `timestamps` auto-manages
`created_at` / `updated_at` on every save. The user-facing `Todo` struct
is the type you'll work with in handlers, route model binding included;
the inner `todo` module holds the SeaORM entity the macro generates.

## 4. Controller

```bash
suprnova make:controller todo
```

Open `src/controllers/todo.rs`:

```rust
use suprnova::{
    attrs, handler, inertia_response, redirect_to, request, InertiaProps,
    Model, Request, Response,
};

use crate::models::todo::Todo;

#[derive(InertiaProps)]
pub struct TodoIndexProps {
    pub todos: Vec<Todo>,
}

#[derive(InertiaProps)]
pub struct TodoFormProps {
    pub todo: Option<Todo>,
}

#[request]
pub struct TodoForm {
    #[validate(length(min = 1, max = 200, message = "Title is required"))]
    pub title: String,
}

#[handler]
pub async fn index(req: Request) -> Response {
    let todos = Todo::all().await?.into_vec();
    inertia_response!(&req, "Todos/Index", TodoIndexProps { todos })
}

#[handler]
pub async fn create(req: Request) -> Response {
    inertia_response!(&req, "Todos/Create", TodoFormProps { todo: None })
}

#[handler]
pub async fn store(form: TodoForm) -> Response {
    Todo::create(attrs! {
        title: form.title,
        completed: false,
    })
    .await?;
    redirect_to("/todos").into()
}

#[handler]
pub async fn edit(todo: Todo, req: Request) -> Response {
    inertia_response!(&req, "Todos/Edit", TodoFormProps { todo: Some(todo) })
}

#[handler]
pub async fn update(todo: Todo, form: TodoForm) -> Response {
    todo.update(attrs! { title: form.title }).await?;
    redirect_to("/todos").into()
}

#[handler]
pub async fn toggle(todo: Todo) -> Response {
    let next = !todo.completed;
    todo.update(attrs! { completed: next }).await?;
    redirect_to("/todos").into()
}

#[handler]
pub async fn destroy(todo: Todo) -> Response {
    todo.delete().await?;
    redirect_to("/todos").into()
}
```

A few things to notice:

- **Route model binding is automatic.** `#[suprnova::model]` makes `Todo`
  bindable, so declaring `todo: Todo` tells the `#[handler]` macro to read
  `{todo}` from the route path and fetch the row through `Todo::query()` by
  its primary key. A value that matches no row, or is not a number, answers
  404 before the handler runs, and before `update` reads its form. The
  argument's name must match the route placeholder; the router checks that
  when it starts.
- **The bound value is the model.** `todo` is a `Todo`, the type that
  carries `update`, `delete`, and the rest of the user-facing API.
- **`#[request]` covers validation.** Adding it to a struct generates
  `Deserialize`, `Validate`, and `FormRequest` - the framework rejects
  malformed input with a 422 before your handler runs. There's no need
  to also derive `InertiaProps` on a request DTO; that derive is for
  *outgoing* page props.
- **Mass assignment goes through `attrs!`.** `Todo::create(attrs! { ... })`
  and `todo.update(attrs! { ... })` route through the fillable filter, so
  fields not in the model's `fillable` list silently drop instead of
  bypassing the guard.
- **`update` and `delete` consume `self`.** That's why `toggle` reads
  `!todo.completed` into a local before calling `todo.update(...)`.

Register the new controller module in `src/controllers/mod.rs`:

```rust
pub mod todo;
```

### Why Suprnova diverges

In Laravel, the same controller would normally return JSON for an API or
a Blade view for a server-rendered page. Suprnova returns Inertia
responses for both initial loads and SPA navigations - the framework
detects the `X-Inertia` header and serves HTML or JSON accordingly,
without a parallel API layer. You write your handlers once, your
frontend stays a real SPA, and there's no second router to keep in
sync. See [Inertia Responses](frontend-inertia-responses.md) for the
mechanics.

## 5. Routes

`src/routes.rs`:

```rust
use suprnova::{delete, get, post, put, routes};

use crate::controllers::todo;

routes! {
    get!("/todos", todo::index).name("todos.index"),
    get!("/todos/create", todo::create).name("todos.create"),
    post!("/todos", todo::store).name("todos.store"),
    get!("/todos/{todo}/edit", todo::edit).name("todos.edit"),
    put!("/todos/{todo}", todo::update).name("todos.update"),
    post!("/todos/{todo}/toggle", todo::toggle).name("todos.toggle"),
    delete!("/todos/{todo}", todo::destroy).name("todos.destroy"),
}
```

The `{todo}` placeholder is what route model binding hooks onto: it has
to match the handler parameter name (`todo`), and its value is parsed as
the model's primary-key type (here, `i64`). A route whose handler reads a
parameter its path does not declare stops the server at startup. The
optional `.name(...)` suffix is what the route-type generator in the next
step uses to build the frontend helpers.

## 6. Generate TypeScript types

```bash
suprnova generate-types
```

`generate-types` does two things in one pass:

1. Walks every `#[derive(InertiaProps)]` struct in `src/` and writes them
   to `frontend/src/types/inertia-props.ts`.
2. Walks `src/routes.rs` and writes typed URL builders for every named
   route to `frontend/src/types/routes.ts`.

The route helpers come out as a nested object - `controllers.todos.toggle({ todo: "1" })`
returns a `{ url, method }` pair that Inertia 3's `Link` and `router`
accept directly. Path parameters are typed; the compiler catches a
missing `todo` argument before the page hits the browser.

You don't have to edit these files. Re-run `suprnova generate-types`
whenever you add or rename props/routes, or pass `--watch` to keep them
in sync as you go.

## 7. Pages

Each page lives under `frontend/src/pages/Todos/`. The names match the
strings you pass to `inertia_response!`, so `inertia_response!(&req, "Todos/Index", ...)`
resolves to `frontend/src/pages/Todos/Index.svelte`.

### Index

`frontend/src/pages/Todos/Index.svelte`:

```svelte
<script lang="ts">
  import { Link, router } from '@inertiajs/svelte'
  import type { Todo, TodoIndexProps } from '../../types/inertia-props'
  import { controllers } from '../../types/routes'

  let { todos }: TodoIndexProps = $props()

  function toggle(todo: Todo) {
    router.visit(controllers.todos.toggle({ todo: String(todo.id) }))
  }

  function remove(todo: Todo) {
    if (confirm('Delete this todo?')) {
      router.visit(controllers.todos.destroy({ todo: String(todo.id) }))
    }
  }
</script>

<div class="mx-auto max-w-2xl p-8">
  <div class="mb-6 flex items-center justify-between">
    <h1 class="text-2xl font-bold">My Todos</h1>
    <Link
      href={controllers.todos.create()}
      class="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700"
    >
      Add todo
    </Link>
  </div>

  {#if todos.length === 0}
    <p class="text-center text-gray-500">No todos yet.</p>
  {:else}
    <ul class="space-y-2">
      {#each todos as todo (todo.id)}
        <li class="flex items-center gap-3 rounded border p-3">
          <input
            type="checkbox"
            checked={todo.completed}
            onchange={() => toggle(todo)}
            class="h-5 w-5"
          />
          <span class={todo.completed ? 'flex-1 text-gray-400 line-through' : 'flex-1'}>
            {todo.title}
          </span>
          <Link
            href={controllers.todos.edit({ todo: String(todo.id) })}
            class="text-blue-600 hover:underline"
          >
            Edit
          </Link>
          <button
            onclick={() => remove(todo)}
            class="text-red-600 hover:underline"
          >
            Delete
          </button>
        </li>
      {/each}
    </ul>
  {/if}
</div>
```

### Create

`frontend/src/pages/Todos/Create.svelte`:

```svelte
<script lang="ts">
  import { Link, useForm } from '@inertiajs/svelte'
  import { controllers } from '../../types/routes'

  const form = useForm({ title: '' })

  function submit(e: SubmitEvent) {
    e.preventDefault()
    form.post(controllers.todos.store().url)
  }
</script>

<div class="mx-auto max-w-md p-8">
  <h1 class="mb-6 text-2xl font-bold">Create todo</h1>

  <form onsubmit={submit} class="space-y-4">
    <div>
      <label for="title" class="mb-1 block text-sm font-medium">Title</label>
      <input
        id="title"
        type="text"
        bind:value={form.title}
        class="w-full rounded border px-3 py-2"
        placeholder="What needs to be done?"
      />
      {#if form.errors?.title}
        <p class="mt-1 text-sm text-red-600">{form.errors.title}</p>
      {/if}
    </div>

    <div class="flex gap-3">
      <button
        type="submit"
        disabled={form.processing}
        class="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 disabled:opacity-50"
      >
        {form.processing ? 'Creating...' : 'Create'}
      </button>
      <Link
        href={controllers.todos.index()}
        class="px-4 py-2 text-gray-600 hover:underline"
      >
        Cancel
      </Link>
    </div>
  </form>
</div>
```

### Edit

`frontend/src/pages/Todos/Edit.svelte`:

```svelte
<script lang="ts">
  import { Link, useForm } from '@inertiajs/svelte'
  import type { TodoFormProps } from '../../types/inertia-props'
  import { controllers } from '../../types/routes'

  const props: TodoFormProps = $props()
  const todo = props.todo!

  const form = useForm({ title: todo.title })

  function submit(e: SubmitEvent) {
    e.preventDefault()
    form.put(controllers.todos.update({ todo: String(todo.id) }).url)
  }
</script>

<div class="mx-auto max-w-md p-8">
  <h1 class="mb-6 text-2xl font-bold">Edit todo</h1>

  <form onsubmit={submit} class="space-y-4">
    <div>
      <label for="title" class="mb-1 block text-sm font-medium">Title</label>
      <input
        id="title"
        type="text"
        bind:value={form.title}
        class="w-full rounded border px-3 py-2"
      />
      {#if form.errors?.title}
        <p class="mt-1 text-sm text-red-600">{form.errors.title}</p>
      {/if}
    </div>

    <div class="flex gap-3">
      <button
        type="submit"
        disabled={form.processing}
        class="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 disabled:opacity-50"
      >
        {form.processing ? 'Saving...' : 'Save'}
      </button>
      <Link
        href={controllers.todos.index()}
        class="px-4 py-2 text-gray-600 hover:underline"
      >
        Cancel
      </Link>
    </div>
  </form>
</div>
```

The equivalent React 19 and Vue 3.5 starters take the same props through
their own templating - the backend doesn't change.

## 8. Run it

```bash
suprnova serve
```

Visit `http://127.0.0.1:8765/todos`, add a few rows, toggle them, edit
one, delete another. The page transitions happen through Inertia - no
full reload - and every form submission validates server-side before
the redirect lands.

## What just happened

| Layer | File | What it does |
|---|---|---|
| Schema | `src/migrations/m_create_todos_table.rs` | Creates the `todos` table |
| Model | `src/models/todo.rs` | The user-facing `Todo` struct + the inner SeaORM module |
| HTTP | `src/controllers/todo.rs` | Seven `#[handler]`s, including route model binding |
| Router | `src/routes.rs` | Named routes that drive the generated route helpers |
| Props | `frontend/src/types/inertia-props.ts` | Generated from `#[derive(InertiaProps)]` |
| Routes | `frontend/src/types/routes.ts` | Generated from named routes in `routes.rs` |
| Pages | `frontend/src/pages/Todos/*.svelte` | The three Svelte 5 pages that consume the props |

That's the standard Suprnova feature loop: migration -> model -> controller
-> route -> page, with `suprnova generate-types` regenerating the
TypeScript bridge whenever you reshape props or rename a route.

## Next

- [Eloquent](eloquent.md) - `attrs!`, the query builder, casts, scopes,
  observers
- [Validation](validation.md) - what `#[request]` and `#[derive(Validate)]`
  give you
- [Routing](routing.md) - named routes, route model binding, resource
  routing, signed URLs
- [Inertia Responses](frontend-inertia-responses.md) - `inertia_response!`,
  partial reloads, shared props
- [Authentication](authentication.md) - adding per-user todos with the
  starter's session auth


# Reference

---

<!-- /docs/parity -->

# Laravel Parity Map

The honest, feature-by-feature mapping between Laravel 13.x and Suprnova.
Use this when you're asking "does Suprnova have X?" and want a yes/no/where
answer in one row.

Sections mirror the Laravel docs index so a Laravel developer can scan
top-to-bottom. Within each section the columns are always the same:

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|

The **Status** column uses four values:

| Symbol | Meaning |
|---|---|
| **shipped** | Same surface, same behaviour (often same method names) |
| **diverged** | Same job, different shape because Rust makes a better choice possible |
| **not built** | No first-party version; the Notes column gives the route |
| **by design no** | Won't ship - explanation in the Notes column |

The relevant chapter (where one exists) is linked from the **Notes** column.

Suprnova ships every Laravel 13.x surface across the 30 documented
domains. The rows marked **not built** and **by design no** are the gaps.

## Architecture concepts

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Request Lifecycle | `Application` → `Server` → `handle_request` chain | shipped | [Lifecycle](lifecycle.md) |
| Service Container | `Container` + `App` facade, three-layer (task / thread / global) | diverged | The task-local and thread-local layers hold test overrides, and the global layer holds the bindings of the application. A binding that lives for one request or other unit of work is a scoped binding, `App::scoped`. [Container](container.md), [Scoped bindings](container.md#appscoped-and-appbind_scoped---one-value-per-unit-of-work) |
| Contextual binding (`when()->needs()->give()`) | No contextual bindings - one binding per trait per container layer | by design no | The container is `TypeId`-keyed with no runtime reflection to key a binding on "who is asking". Compose explicitly: pass the dependency in, or bind a distinct newtype per consumer. [Container](container.md) |
| Service Providers | `bootstrap()` function + `#[service]`, `#[policy]`, `#[command]`, observer macros | diverged | No registration class - bootstrap is one function; macros use `inventory` for compile-time registration. [Bootstrap](bootstrap.md) |
| Facades | Static `App::get`, `Cache::*`, `Mail::*`, `Auth::*`, `Storage::*`, `Queue::*`, `Bus::*`, `EventFacade::*`, `Notify::*`, `Gate::*`, `DB::*`, `Vector::*`; the scheduler is a `Schedule` instance (`schedule.task(...)`) | shipped | Same call shape; the facades are real types, not aliases |
| Contracts | Traits - `MailTransport`, `CacheStore`, `Hasher`, `Channel`, `VectorDriver`, `Evaluator`, `PaymentProvider`, etc. | shipped | All public seams live on traits; bind by trait, swap implementations freely |

## Getting started

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Installation | `cargo install --git …suprnova-cli` then `suprnova new <name>` | shipped | [Installation](installation.md) |
| Configuration | Typed config structs registered via `Config::register` | diverged | Compile-time typed instead of array bags. [Configuration](configuration.md) |
| Agentic Development (AI) | No first-class AI SDK in framework | by design no | Use the crates you'd use anyway (`async-openai`, `anthropic-rs`, `tokenizers`, etc.) under `App::bind(Arc<dyn YourLlm>)` |
| Directory Structure | `src/{actions,bootstrap,controllers,middleware,models,routes}` | shipped | Same intent, Rust-idiomatic layout. [Structure](structure.md) |
| Frontend | Inertia v3 over Svelte 5 / React 19 / Vue 3.5 | shipped | [Frontend](frontend.md), [Pages](frontend-pages.md), [TS Types](frontend-typescript-types.md) |
| Starter Kits | **Nebula** (auth), **Pulsar** (full product site) and the **Directory starter** (listings and paid publication), plus the plain `suprnova new` scaffold | shipped | Nebula is the Breeze equivalent; Pulsar adds docs, blog, community, and RBAC; the Directory starter adds listings, moderation, and paid publication. [Starter Kits](starter-kits.md) |
| Deployment | Single binary; Docker / Railway / DO / Hetzner recipes | diverged | One artifact, not a PHP runtime + opcache + FPM. [Deployment](deployment.md) |

## The basics

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Route definitions | `routes!` macro + `get!` / `post!` / `put!` / `patch!` / `delete!` / `any!` / `head!` / `options!` / `fallback!` / `ws!` | shipped | [Routing](routing.md) |
| Route parameters | `{id}` path params + `req.param("id")` | shipped | Optional params via `{id?}`: `/posts/{id?}` matches `/posts` and `/posts/42`, and an optional parameter can only be followed by optional ones. Constraints are methods on the route, not a `where!` macro: `.where_number("id")`, `.where_alpha`, `.where_alpha_numeric`, `.where_uuid`, `.where_ulid`, `.where_in("status", [...])`, `.where_pattern("year", "[0-9]{4}")`. A value the constraint refuses is a 404 and no middleware runs. [Routing](routing.md) |
| Route names | `.name("posts.show")` on the route + `route("posts.show", &[("id", "42")])` or `route("posts.show", &post)` | shipped | A bound value fills its route key or binding field. [URL Generation](urls.md) |
| Route groups | `group!` macro with the path prefix as its first argument + `.middleware()` / `.name("admin.")` on the group, and `controller = path::to::module` inside the macro | shipped | Group middleware is flattened onto each route at register time. `.name("admin.users.")` puts the prefix in front of the name of every route in the group, and a nested group adds its own after it. `controller = ...` names the module the handlers live in, so a route names its handler by function alone. [Routing](routing.md) |
| Resource routes | `Router::resource("posts", PostController)` registers the 7 standard routes; `resource!("posts", controllers::posts)` names a module of `#[handler]` actions that take bound arguments | shipped | `Router::api_resource` / `api_resource!`, `only`, `except`, nested `users.posts`, `parameters`, `scoped`, `with_trashed` and `missing` all supported. [Routing](routing.md#resource-routing) |
| Signed URLs | `sign_url(...)`, `sign_route(...)`, `verify_signature(...)` | shipped | HMAC-SHA256 with `APP_KEY` |
| Route model binding | `#[handler]` binds `post: Post` from `{post}` through `RouteBinding`, which every `#[suprnova::model]` implements | shipped | `{post:slug}` binding fields, `route_key`, scoped children, `custom_route_binding`, `Router::bind` / `Router::model`, `with_trashed()`, `missing()` and `#[derive(RouteBinding)]` enums. A value that does not parse answers 404, and mistakes are refused at startup. [Routing](routing.md#route-model-binding) |
| Rate limiting | `.middleware_named("throttle:60,1")` on a route + `RateLimiter::r#for` | shipped | Register the alias once with `register_middleware_alias_with_args("throttle", ThrottleRequestsMiddleware::from_alias_args)`. `throttle`, `throttle:60`, `throttle:60,5`, `throttle:60,5,prefix` and `throttle:api` (a named limiter) are read. [Rate Limiting](rate-limiting.md), [Middleware](middleware.md) |
| Middleware | `impl Middleware` trait; register globally or per-route | shipped | [Middleware](middleware.md) |
| Middleware groups + aliases | `register_middleware_group`, `register_middleware_alias`, `register_middleware_alias_with_args` + `.middleware_named("auth")` on a route or group | shipped | A name is looked up when the route is registered, so a name that is not registered stops the boot, not a request. `.try_middleware_named(...)` returns the error. [Middleware](middleware.md) |
| CSRF Protection | `CsrfMiddleware` + `csrf_token()` / `csrf_field()` / `csrf_meta_tag()` | shipped | Per-session token validation is the default. Optional `SameOriginOnly`, `AllowSameSite`, and `OriginOnly` policies consult `Sec-Fetch-Site`; origin enforcement is not enabled by default. [CSRF](csrf.md) |
| Controllers | `#[handler] pub async fn show(req: Request) -> Response` | shipped | Controllers are modules of free functions, not classes. [Controllers](controllers.md) |
| Single-action controllers | A handler is already a single function; group into modules | shipped | The Rust convention - no `__invoke` ceremony |
| Requests | `Request` struct with `.input()`, `.param()`, `.query()`, `.header()`, `.cookie()`, `.json()`, etc.; uploads through `#[derive(MultipartRequest)]` | shipped | [Requests](requests.md) |
| Form Requests | `#[derive(Data, Validate)]` (`Data` implements `FormRequest`) | shipped | Validation runs as you extract |
| File uploads | `#[derive(MultipartRequest)]` fields of type `UploadedFile`; streaming multipart with size + part caps | diverged | Auto-spill to tempfile above threshold |
| Responses | `HttpResponse` builders + `json_response!()` / `text_response!()` / `Redirect::to` / Inertia responses | shipped | [Responses](responses.md) |
| Streamed responses (`eventStream`, `stream`, `streamJson`) | `HttpResponse::sse(...)` / `event_stream(...)` / `stream_bytes(...)` / `stream_json(...)` | shipped | Same wire shapes `@laravel/stream-{react,vue,svelte}`'s hooks expect. [SSE](sse.md) |
| `withoutCookie` / `withoutCookies` | `.without_cookie(name)` / `.without_cookies([...])` on `HttpResponse`, `Response`, `Redirect`, `RedirectRouteBuilder` | shipped | `Cookie::forget_with(name, path, domain)` for a cookie that wasn't set at `/` |
| Views (Blade) | Server-rendered Inertia pages (Svelte/React/Vue), or checked Askama views through `#[view]` + `document_response`; `View::share` / `View::share_for_request` share data with every checked view | diverged | Inertia is the main view layer. Use [Pages](frontend-pages.md) instead of Blade. A checked view reads shared data through Askama's `value` filter, and a request's values never reach another request or the render cache. [Live](live.md#shared-view-data) |
| Asset Bundling (Vite) | Vite 8 ships in every scaffold; `suprnova serve` runs Vite + backend together | shipped | Manifest reading + HMR auto-wired |
| Static assets (`public/`, served by the web server in Laravel) | `StaticFiles::public()` in-process fallback handler serving `public/` at the web root | shipped | `StaticFiles::from_dir(...)` + `cache_control(...)`; no separate web server needed |
| URL Generation | `url::to("/path")`, `route("posts.show", …)`, `redirect(...)`, `redirect_to(...)` | shipped | [URL Generation](urls.md) |
| Session | `session()`, `session_mut()`, flash through `App::flash`, a redirect's `.flash(...)`, or the session's `flash` | shipped | Database-backed by default via `DatabaseSessionDriver`; the encrypted browser cookie carries the session identifier and activity-touch metadata, not the session data bag. [Session](session.md) |
| Cookie queue (`Cookie::queue`) | `Cookie::queue`/`queued`/`unqueue`/`expire` - a task-local jar `SessionMiddleware` drains onto the response | shipped | Requires `SessionMiddleware` in the chain; queued by name, not name+path like Laravel's `CookieJar` |
| Validation | `#[derive(Validate)]` + 35 built-in rules + `Rule`/`ValueRule`/`AsyncRule` traits | shipped | `Url` uses Laravel's scheme allowlist and `Url::protocols([...])` mirrors `url:http,https`. Async rules (e.g. `Unique`) hit the DB. `ArrayKeys`/`Distinct` are `ValueRule`s over `serde_json::Value`, matching Laravel's `array:keys` and `distinct`. `InArray` takes the other field's list directly instead of Laravel's `in_array:other.*` rule string, and `Contains`/`DoesntContain` match JSON string elements exactly. `Gt`/`Gte`/`Lt`/`Lte` take an explicit `CompareWith` operand (literal number, numeric sibling, or sibling compared by character count) instead of inferring Laravel's four size measures; array and file comparisons have no counterpart. [Validation](validation.md) |
| `Password` rule (`Password::defaults()`, `uncompromised()`) | `Password::min(n)` + strength builders (`.letters()`, `.mixed_case()`, `.numbers()`, `.symbols()`) + `.uncompromised()` | shipped | Have I Been Pwned k-anonymity check; fails open on a network error, matching Laravel's `NotPwnedVerifier`. [Validation](validation.md#password-strength) |
| Error Handling | `FrameworkError`, `AppError`, `HttpError` trait, panic boundary in `execute_chain_safely` | shipped | [Error Handling](errors.md), [Error Model](error-model.md) |
| Logging | `tracing` subscriber with structured fields, `LogFormat` (json / pretty) | diverged | In json mode (the production default) one log line is a JSON document; `request_id` always present. [Logging](logging.md) |
| Log channels (`single`, `daily`, `monthly`, `stack`, `syslog`, `stderr`, `null`) and `Log::channel` / `stack` / `build` / `extend` | `LOG_CHANNEL`, `LOG_STACK`, `LOG_DAILY_DAYS`, `Log::define`, `Log::channel`, `Log::stack`, `Log::build`, `Log::extend` with a `LogSink`, `MAIL_LOG_CHANNEL` | shipped | The default is `stdout`, not a stack of files; channels come from the environment and `Log::define`, not a config file; dates are UTC; file channels buffer and flush on errors, within a second, and on shutdown. Slack and the other vendor sinks are a `Log::extend` away. [Logging](logging.md#channels) |
| Abort helpers | `abort_if(cond, status, msg)`, `abort_unless(...)`, `abort_with(status, msg)` | shipped | Same shape as Laravel's `abort_if` family |

## Digging deeper

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Artisan Console | Per-app `console` binary built from `#[command]` + `#[derive(Command)]` | shipped | [Console](console.md). `cargo run --bin console <subcommand>` |
| Tinker (REPL) | No REPL | by design no | Write a one-off `cargo run --bin xxx` script or a `#[suprnova_test]` |
| Broadcasting | `BroadcastHub` + `Channel` / `PrivateChannel` / `PresenceChannel` + `Broadcastable` | shipped | Redis stream fanout for multi-node. [Broadcasting](broadcasting.md) |
| Cache | `Cache::get/put/forget/remember/rememberForever/increment/...` + `InMemoryCache`, `RedisCache` | shipped | Atomic ops + tagged cache + cache locks (`LockGuard`). [Cache](cache.md) |
| Collections | `eloquent::Collection<M>` with Laravel-shape methods | shipped | Derefs to a `[M]` slice, so slice idioms work; `into_vec()` for `Vec` ones. [Collections](eloquent-collections.md) |
| Concurrency | Tokio everywhere - `tokio::spawn`, `tokio::join!`, `tokio::select!` | shipped | The whole framework is async. The Laravel `Concurrency::run([...])` facade doesn't ship; Tokio is the answer |
| Context | `Context::add` / `Context::get` / `ContextStore` + a `ContextSnapshot` that travels with queued jobs, queued mail and notifications, and queued event listeners | shipped | The snapshot is taken when the push is made and stored on the queue envelope. The worker runs the job in a scope restored from it, on a copy, so what a job adds reaches neither the request nor the next job. The query bag does not travel. `Context::dehydrating` / `Context::hydrated` register callbacks for the two ends. [Context](context.md) |
| Contracts | All public seams are traits | shipped | See the "Architecture / Contracts" row above |
| Events | `EventFacade::dispatch(e).await?`, `impl Event`, `EventDispatcher`, queued listeners, subscribers | shipped | [Events](events.md) |
| File Storage | `Storage::disk("local"\|"s3"\|"azblob"\|"gcs"\|"memory")` over OpenDAL | shipped | Same `put/get/delete/copy/move/exists` surface. Path-traversal protection built in. `Storage::url(disk, path)` returns the public URL of a file. It takes the disk name, and it returns an error for a disk with no public base URL: set one with `Storage::set_public_url(disk, base)`, or `S3_PUBLIC_URL` for the `s3` disk. The path is percent-encoded and a `.` or `..` segment is refused. On a local disk, `put`/`write`, the streaming writer, and `copy` are all staged under `<root>/.suprnova-atomic/` and published in one step, and a conditional write is published with `link(2)` so it stays a true exclusive create; `append` is the one in-place operation. Laravel's local driver writes straight to the target, where a partial length is observable and a crash truncates the live object. `Storage::register_read_through` composes two disks into a read-through disk that promotes fallback hits onto the primary, with `copy: false` to skip promotion and fallback-spanning `copy` / `rename`. [Filesystem](filesystem.md) |
| Helpers | Equivalents are in their home modules (no kitchen-sink `helpers.md`) | diverged | E.g. URL helpers live in [urls.md](urls.md), string helpers in `std`/`heck`, array helpers in `std::collections` - Rust does this with crates, not a global namespace |
| HTTP Client | `Http::get/post/...` builder + `Http::fake(...)` for tests | shipped | Auto-records requests; `assert_sent` / `assert_not_sent`; `.retry_when(predicate)` narrows the built-in retry policy with a `RetryContext`. [HTTP Client](http-client.md) |
| Image (`Illuminate\Image`) | `Image::from_bytes/from_path/from_disk/from_upload/from_stream` + the same operation and terminal surface | shipped | Lives in `suprnova::media`. Two drivers like Laravel's `gd`/`imagick`: `IMAGE_DRIVER=oxideav` (default, pure Rust) or `magick`, and `using` per image. Reads and writes PNG, JPEG, WebP, GIF, BMP; no AVIF. Header-checked decode limits. EXIF orientation applied on decode (`IMAGE_AUTO_ORIENT`); output keeps the ICC profile and drops the rest of the metadata. Custom transformations are pixel functions both drivers run. [Images](images.md) |
| HEIC decoding in the default driver | `IMAGE_DRIVER=magick` on a host with the libheif delegate | by design no | HEVC is patent-encumbered and the only credible pure-Rust decoder is dual AGPL/commercial, so no built-in decoder ships. Same shape as Laravel, where GD cannot read HEIC at all and Imagick needs the delegate compiled into both the binary and the PHP extension. [Images](images.md#why-suprnova-diverges) |
| Localization | `Lang::get` / `get_with` / `try_get` / `has` + the `__!("key", name: value)` macro over Fluent `.ftl` catalogs in `lang/<locale>/`, `LocaleMiddleware` detection, translated validation messages, ICU4X formatting | shipped | The same catalog is served to the browser at `/_suprnova/lang/<locale>.ftl` and typed by `generate-types`. [Localization](localization.md) |
| Mail | `Mail::to(...).send(MyMail { ... }).await?` + drivers `smtp/ses/mailgun/postmark/sendgrid/resend/log/memory/file` | shipped | `Mailable` trait + Tera-rendered HTML/text bodies; SES sends carry `TenantName` / `ConfigurationSetName` / `ListManagementOptions`; queued dispatch routes via `.on_queue(...)` / `.on_connection(...)`, outranking `Queue::route`. [Mail](mail.md) |
| Notifications | `Notify::send(&user, notif).await?` + channels `mail/database/broadcast/webpush` | shipped | `Notifiable` trait + `Notification` per channel; queued dispatch (`Notify::queue`) carries per-notification `queue`/`timeout`/`fail_on_timeout`/`max_tries`/`backoff` onto each channel's job via the same `EnvelopeOverrides` primitive Mail uses. [Notifications](notifications.md), [Web Push](web-push.md) |
| Package Development | Workspace adapter crates (e.g. `suprnova-payments-stripe`) | shipped | Same shape as Laravel packages: depend on the framework, bind into the container, expose macros if needed |
| Queues | `Queue::push(job).await?` + drivers `sync/memory/database/redis/sqs/null`, batches, chains, `JobMiddleware`, `FailedJobStore` | shipped | [Queues](queues.md) |
| SQS queue driver | `QUEUE_DRIVER=sqs` over SQS standard and FIFO queues, Laravel's `SQS_PREFIX` / `SQS_QUEUE` / `SQS_SUFFIX`, the AWS credential chain, and overflow of large jobs | shipped | A release costs no attempt, delays past 15 minutes hold, overflow uses a named cache store when set or a disk otherwise, and FIFO jobs carry group and deduplication IDs. [Queues](queues.md#amazon-sqs) |
| Process facade | `Process::command(args)` and `Process::shell(line)`, results, timeouts and idle timeouts, started processes, pools with a concurrency limit, pipes, and `Process::fake` with patterns, `describe`, sequences and assertions | shipped | The command and the shell line are separate methods; a kill reaches every process the program started; pools take a concurrency limit. [Processes](processes.md) |
| Job-declared delay | `fn delay() -> Option<Duration>` on `Job`, honored by `Queue::push`, `Queue::bulk` and each link of a chain | shipped | A link after the head waits that long after the link before it completes. An explicit `Queue::push_later` / `Queue::later(delay, job)` call always wins over the job's own default. [Queues](queues.md) |
| `Queue::forward` | `Queue::forward(from, to)` / `Queue::forward_on(from, to, connection)`, applied to the envelope and to the worker's `--queue` list | shipped | Queue-to-queue only: `connection` gates the redirect rather than selecting a driver, and is compared against the process connection name so the push and the worker's claim gate on the same value; `to` is required where Laravel's is optional. [Queues](queues.md) |
| Unique-job skipped event | `queue::events::UniqueJobSkipped { job_name, unique_id, connection }` | shipped | Fired on the push side when `push_unique` dedupes; the call still returns `Ok(false)` |
| Queue pausing (`queue:pause` / `queue:resume`) | `Queue::pause`/`resume`/`pause_all`/`resume_all`/`is_paused`/`paused_queues`, cache-backed, with `QueuePaused` / `QueueResumed` / `QueuesPaused` / `QueuesResumed` events | shipped | A per-queue pause only takes effect on a worker started with an explicit `--queue=...` list; `resume_all` doesn't clear a per-queue pause. A running worker also emits `WorkerQueuePaused` / `WorkerQueueResumed` once per transition and `queue:work` prints a line for each; their `queue` field is `Option<String>`, because a worker started without `--queue` has no queue names to report under a global pause. [Queues](queues.md) |
| Retrying transient Redis commands | Read-shaped Redis commands retry once on a connection-level failure, each attempt awaiting the driver's reconnect budget; `REDIS_COMMAND_RETRIES` adds more | shipped | Laravel's `command_retries` covers every command through one dispatch point and a 60-entry allowlist; Suprnova retries each driver's reads per call site and the [Redis facade](redis.md)'s reads by Laravel's allowlist less its three writes, and no setting makes a write or a queue pop retry. [Cache](cache.md) |
| After-commit dispatch (`afterCommit()`) | `fn after_commit() -> bool` on `Job`, `EnvelopeOverrides::after_commit` per push, `Queue::push_after_commit` | shipped | The whole push waits for the commit, events included, and a rollback discards it; a deferred `push_unique` still takes its lock immediately so dedupe works inside the transaction. Manual `DB::begin_transaction` never defers. [Queues](queues.md) |
| Failover queue connection | `FailoverQueueDriver` over an ordered connection list, via `QUEUE_DRIVER=failover` + `QUEUE_FAILOVER_CONNECTIONS` | shipped | Writes fall through the list; workers drain every connection (`pop` rotates across them) and the counters and listings sum all of them. `QueueFailedOver` is edge-triggered, and `bulk_push` falls through per envelope so each keeps its own delay. [Queues](queues.md) |
| `ShouldBeUniqueUntilProcessing` | `fn unique_until_processing() -> bool` on `Job`, released after the middleware pass and before the handler | shipped | Owner-scoped release, so a redelivered attempt never releases a newer dispatch's lock. A job a middleware releases back onto the queue keeps its lock. [Queues](queues.md) |
| Debounced jobs (`#[DebounceFor]`) | `Job::debounce_for` / `max_debounce_wait` / `debounce_id`, plus `Queue::push_debounced(job, DebounceOptions)` | shipped | Trait methods rather than a class attribute, so a typo is a compile error. Every dispatch is enqueued and the collapse is settled at the worker; a job declaring both `debounce_for` and `unique_id` is refused with a `FrameworkError` where Laravel throws. Chains and batches refuse a debounced job outright. [Queues](queues.md) |
| Debounced queued listeners | `Job::debounce_for` on the listener's job, or `DebouncedListener::new(window, build).keyed_by(...)` | shipped | Laravel puts the attribute on the listener class; Suprnova's listener-to-job bridge already runs through `Queue::push`, so declaring it on the job covers the common case and `DebouncedListener` covers a per-registration window. [Events](events.md) |
| Queue inspection (`pendingJobs` / `delayedJobs` / `reservedJobs`) | `Queue::pending_jobs(queue)` / `delayed_jobs` / `reserved_jobs`, `Option<&str>` collapsing Laravel's `all*Jobs()` twin into one call | shipped | `InspectedJob` DTO (`id`/`queue`/`name`/`attempts`/`payload`/`created_at`); the trait default is an honest `Err` rather than an empty collection; `sync`/`null` override with `Ok(vec![])`; Redis's `reserved_jobs` is per-consumer. Unlike Laravel these do not follow a `Queue::forward`, so they report the literal queue you name - which is how a backlog left behind on a forwarded queue stays visible. [Queues](queues.md) |
| Schedule per-task timezone | `.timezone(chrono_tz::Tz)` / `.try_timezone("name")` per task, `Schedule::timezone` default, `schedule:list --timezone` | shipped | Typed `chrono_tz::Tz` instead of Laravel's string; the schedule-wide default is `Schedule::timezone` in `schedule::register` rather than an `app.schedule_timezone` config key, and an unpinned task keeps the process-local zone. [Scheduling](scheduling.md) |
| Rate Limiting | `RateLimiter::r#for(...)` (or `RateLimiter::define(...)`), `ThrottleRequestsMiddleware`, `RateLimitMiddleware` | shipped | Sliding window via `SlidingWindowConfig`. [Rate Limiting](rate-limiting.md) |
| Search (Scout) | No first-party full-text search adapter | not built | Semantic search ships via [Vector](vector.md); for keyword search, use `meilisearch-sdk` / `elasticsearch` directly |
| Strings (helpers) | `Str::slug`, `mask`, `limit`, `limit_words`, `excerpt`, `plural`, `singular`, `markdown` and `inline_markdown`; `Str::of` for the fluent `Stringable`; the `heck` crate for case conversions | diverged | A subset, which `Stringable` chains with `markdown` and purpose-bound `encrypt` and `decrypt`; plurals follow the request's locale; Markdown is sanitized by default. [Strings](strings.md) |
| Task Scheduling | `Schedule::call/command/task` + `impl Task` + cron syntax + `schedule:run` worker | shipped | `schedule.command("emails:send --force")` takes a console command line the way it is typed behind the binary name and returns the same `TaskBuilder` as the other forms. The line is checked when the schedule is built, and `try_command` returns the error. The command runs in the scheduler's process. [Scheduling](scheduling.md) |
| Idempotency keys | `Idempotency::remember(key, ttl, body)` - Stripe-style replay protection | shipped | Caller namespaces the key with the route + user / business identity. [Idempotency](idempotency.md) |
| Request timeout | `TimeoutMiddleware` configurable per route | shipped | Rust-native - abort the in-flight future, free the worker. [Timeout](timeout.md) |
| Feature Flags (Pennant) | `Feature` + `Evaluator` + `FeatureMiddleware` + admin CRUD | shipped | Sub-second propagation via `FeatureSync` trait. [Feature Flags](feature-flags.md) |
| Observability (Pulse) | OpenTelemetry via `init_telemetry`, `Metrics`, `tracing` everywhere | diverged | OTel is the lingua franca for Rust observability - point your collector at the binary. [Observability](observability.md) |
| Telescope (debug dashboard) | No first-party dashboard | not built | The framework's tracing + OTel output covers most diagnostic needs |
| Pulse (perf dashboard) | No first-party dashboard | not built | Same as Telescope - surface metrics with your existing observability stack |
| Vector search | `Vector::register(name, driver)` / `Vector::store(name)` over memory, Qdrant, Pinecone or MariaDB drivers | shipped | No "Postgres pgvector only" gatekeeping. [Vector Search](vector.md) |

### Suprnova-exclusive (no Laravel equivalent)

| Suprnova | What it is | Notes / link |
|---|---|---|
| `ws!()` macro + WebSocket handlers | Typed WS routes that share the router + middleware stack | [WebSockets](websockets.md) |
| Workflows | Long-running stateful work with retries, sleep, step boundaries | [Workflows](workflows.md) |
| Supervisors | `Supervisor` trait with panic-catch auto-restart for long-lived tokio tasks | [Supervisors](supervisors.md) |
| Web Push (VAPID) | Browser push notifications as a first-class channel | [Web Push](web-push.md) |
| Multi-connection read/write split | `READ_REPLICA_CONNECTION_NAME` + `DB::on("read").select(...)` | [Database](database.md) |
| HTTP/2 + WebSocket on the same socket | `hyper.with_upgrades()` in `Server::run` | [Lifecycle](lifecycle.md) |
| Markdown content + docs pipeline | `MarkdownRenderer` (sanitised comrak → syntect → ammonia) + `build_docs(DocsBuildConfig)` → searchable `DocsCatalog` of `DocsChapter`s | Heading extraction + `slugify_heading`; powers Markdown docs / blog with no separate static-site generator |

## Security

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Authentication | `Auth::user/check/login/logout/attempt`, `Authenticatable` trait, `Guard` per name | shipped | [Authentication](authentication.md) |
| Multiple guards | `Guard` registered by name (`web`, `api`, …) via `AuthManager`; a guard of your own through `Auth::extend(driver, factory)` and `GuardConfig::custom(driver, provider)`, or `Auth::via_request(name, resolver)` for a guard that reads the request | shipped | `SessionGuard`, `TokenGuard`, and the guards of your application. Laravel's `viaRequest` closure gets the request when the guard resolves; here the middleware for the guard runs the resolver, so the guard reports no user outside it. A guard of your application is read-only through the manager, its name is not empty and has no `:`, and it attests the principal `<guard>:<id>` for Live. [Guards of your application](authentication.md#guards-of-your-application) |
| User providers | `EloquentUserProvider<U>`, `DatabaseUserProvider`, custom via `UserProvider` trait | shipped | [Auth Flows](auth-flows.md) |
| Email Verification | `EmailVerification` + `EnsureEmailVerifiedMiddleware` + `EmailVerificationMail`; `MustVerifyEmail` contract | shipped | Provider-backed and actor-bound - [Auth flows](auth-flows.md) |
| Password Reset | `PasswordReset` + Magnetar first-email-proof transaction or verified `UserProvider` fallback + reset/change mail | shipped | Magnetar handles atomic first proof; provider-backed apps can reset already verified users - [Auth flows](auth-flows.md) |
| Brute-force throttling | Magnetar lockout engine + `BruteForce` + `LoginThrottleMiddleware` | shipped | Account lockout plus framework IP/route limiting |
| Two-Factor (TOTP) | Framework `TwoFactor` compatibility facade plus Magnetar factor engine | shipped | Recovery codes, replay protection, and factor-gated integrated sign-in |
| Remember-me | Magnetar purpose-bound rotating credential behind the framework cookie | shipped | Auth-epoch checks, rotation, anomaly handling, and legacy fallback |
| OAuth (Socialite) | Magnetar provider registry and `Auth::oauth(provider)` facade | shipped | OAuth, Apple `form_post`, PKCE/state binding, verified identity policy - [OAuth](oauth.md) |
| Sanctum (API tokens) | `BearerTokenMiddleware` over Magnetar bearer sessions | diverged | Authenticates bearer sessions; no separate Sanctum token-management API |
| Passport (OAuth server) | The Magnetar authorization server plugin, turned on with `AgentsConfig::oauth_server(OAuthServer::new())` | diverged | OAuth 2.1 for MCP clients acting for a user: the authorization code grant with PKCE `S256`, clients identified by a client ID metadata document or dynamic registration, refresh tokens rotated on every use, revocation, and an approval page. `ConnectedAgents` lists and revokes a user's grants. No password, client credentials or implicit grants and no personal access tokens. [Agents](agents.md#users-who-approve-a-client) |
| Fortify (auth backend) | Framework `Auth`/`auth_flows` facades over Magnetar engines | shipped | Framework owns HTTP, mail, events, cookies, and application binding |
| Authorization (Policies / Gates) | `Gate::allows/denies` + `#[policy] impl PostPolicy` + `Authorizable` trait + macro registration + `Gate::default_denial_response` | shipped | [Authorization](authorization.md) |
| Roles & permissions (spatie/laravel-permission) | `HasRoles` trait + spatie's `roles` / `permissions` / `model_has_roles` / `model_has_permissions` / `role_has_permissions` tables (`CreateRbacTables`) + `RoleMiddleware` / `PermissionMiddleware` (fail-closed) | shipped | First-party, not a community package. `create_role` / `give_permission_to_role` / `assign_role_to_model` helpers. `register_gate_bridge::<User>()` makes a held permission allow the same ability on the gate; it allows and never denies, and it answers the async forms (`allows_async`, `authorize_async`, `inspect_async`) only. [Roles and permissions](authorization.md#roles-and-permissions), [Answering the gate with permissions](authorization.md#answering-the-gate-with-permissions) |
| Encryption | `Crypt::encrypt/decrypt` + `CryptPurpose` AAD binding | shipped | AES-256-GCM, key rotation via `APP_KEY_PREVIOUS`. [Encryption](encryption.md) |
| Hashing | `hash::*` + `BcryptHasher`, `Argon2idHasher`, `Argon2iHasher`, `needs_rehash`, `is_hashed`, `verify` | shipped | Bcrypt default; argon2id available. [Hashing](hashing.md) |

## Database

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| DB::table('users')->where(...)->get() | `DB::table("users").filter_op("id", "=", 1).get().await?` | shipped | [Database](database.md), [Queries](queries.md) |
| Multiple connections | `DB::named("read")`, `DB::table_on(...)`, a builder's `.on("read")` + `ConnectionRegistry` | shipped | Read/write split first-class |
| Transactions | `DB::transaction(\|tx\| Box::pin(async move { ... })).await?` | shipped | Savepoints + retry-on-deadlock |
| Query events | `QueryListener` + `QueryExecuted` event | shipped | `DB::listen(\|q\| { ... })` |
| Raw expressions | `DB::select("...", &[...])` with bound values | shipped | Pass values as bindings; the SQL string itself is not checked for interpolation |
| Postgres / MySQL / SQLite | All three first-class via SeaORM | shipped | URL detection in `database::config::database_type()` |
| Postgres `keepalives_*` DSN options | `DB_IDLE_TIMEOUT` / `DB_MAX_LIFETIME` / `DB_ACQUIRE_TIMEOUT` / `DB_TEST_BEFORE_ACQUIRE` / `DB_PING_AFTER_IDLE` pool liveness | diverged | sqlx exposes no TCP keepalive setter, so Suprnova recycles and pings pooled connections instead. [Database](database.md#pool-liveness) |
| MariaDB | Through the MySQL driver (`mysql://`); the vector driver is MariaDB-specific | diverged | MariaDB 11.7+ keeps vectors next to relational rows. [Vector Search](vector.md) |
| Redis facade | `Redis::connection(name)` over connections from `REDIS_URL` and `Redis::define`; typed common commands, `command` for any other, `client()`, pipelines, transactions, subscriptions, blocking commands, and command events | diverged | No key prefix, only reads retry after a lost connection, and the commands that would change the shared connection are refused; subscriptions and blocking commands get connections of their own; `rediss://` connects over TLS; Redis Cluster is not supported. [Redis](redis.md) |
| MongoDB | No first-party adapter | not built | Use `mongodb` crate directly via `App::bind` |
| Query Builder | `Builder<M>` with `db_where` / `or_where` / `where_in` / `where_between` / `where_null` / `where_has` / `with` / `with_count` / `order_by` / `group_by` / `having` / `paginate` / etc. | shipped | [Queries](queries.md) |
| `whereBinary()` family | `Builder::where_binary` / `or_where_binary` / `where_not_binary` / `or_where_not_binary`, and `DB::table(...).where_binary(...)` | shipped | MySQL and MariaDB emit `= binary`; Postgres and SQLite return an error instead of a collation-dependent match. [Queries](queries.md) |
| Pagination | `LengthAwarePaginator`, `Paginator` (simple), `CursorPaginator` | shipped | All three serialise to the fields of Laravel's `toArray()`: `next_page_url` and `prev_page_url` on each, `first_page_url` on `LengthAwarePaginator` and `Paginator`, and `last_page_url` and `links` on the paginator with a total. A page URL is the `path` from `with_path` plus the page parameter, and a `path` with a query string keeps it. [Pagination](pagination.md) |
| Migrations | `#[derive(DeriveMigrationName)] struct M;` + `up`/`down` + `Migrator`, written with SeaORM's builder or the [schema builder](migrations.md#the-schema-builder) | shipped | Run via `suprnova migrate`/`migrate:rollback`/`migrate:status`/`migrate:fresh`. [Migrations](migrations.md), [CLI Migrations](cli-migrations.md) |
| Schema builder | `Schema::create(manager, "posts", \|t\| { t.id(); t.string("title"); t.timestamps(); })`, `Schema::table`, `Schema::drop_if_exists` from `suprnova::schema::Schema` | diverged | Takes the migration's `manager` instead of a global facade, so it runs in the migration's transaction. `timestamps()` and `soft_deletes()` create string columns. No column type change and no table rebuild on SQLite. [The schema builder](migrations.md#the-schema-builder) |
| Seeders | `Seeder` trait + `db:seed` subcommand | shipped | Per-model factories. [Seeding](seeding.md) |

## Eloquent ORM

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| `class User extends Model` | `#[suprnova::model(table = "users")] struct User { ... }` | shipped | The macro generates the SeaORM `Model` beside the struct and converts between them. [Eloquent](eloquent.md) |
| Find / first / get | `User::find(id)`, `User::query().first()`, `User::all()`, `Builder::get` | shipped | All async |
| Create / update / delete | `User::create(attrs)`, `user.update(attrs)`, `user.delete()` | shipped | `attrs! { name: "...", email: "..." }` macro for partial attrs |
| Mass assignment guards | `#[model(fillable = [...])]` / `#[model(guarded = [...])]` + `unguarded \|\| { ... }` scope | shipped | `prevent_silently_discarding_attributes()` for strict mode |
| Soft deletes | `#[model(soft_deletes)]` on a model that declares `deleted_at` + `SoftDeletes` trait | shipped | `with_trashed()`, `only_trashed()`, `restore()`, `force_delete()`. `with_trashed()` and `only_trashed()` lift only the soft-delete filter; every registered global scope still applies. `delete_all()` writes the tombstone and `force_delete_all()` deletes the rows. |
| Prunable / MassPrunable | `#[prunable] impl Prunable for User { ... }` + `model:prune` worker | shipped | Deletes the model's own rows; relations are not pruned with it |
| Timestamps | Auto `created_at`/`updated_at` if columns are present | shipped | Disable via `#[model(timestamps = false)]` |
| Primary key types | i64 default; UUID / ULID via `#[model(unique_id = "uuid")]` or `unique_id = "ulid"` | shipped | Auto-generates id on insert |
| Local scopes | `#[scopes(User)] impl User { fn active(q: Builder<Self>) -> Builder<Self> { ... } }` | shipped | Method dispatch on `Builder<M>`, and `User::active()` as a static form. A method in the block that takes or returns a `Builder` in any other form is a compile error naming the accepted shape; `#[not_scope]` marks a helper that handles one legitimately. |
| Global scopes | `impl GlobalScope<Article> for TenantScope { fn apply(...) }` + `ScopeRegistry::register::<Article, _>(TenantScope)` | shipped | Opt out with `Article::without_global_scope::<TenantScope>()` or `Article::without_global_scopes()`, which also chain onto a builder. The scopes run when the query runs, so `query().or_where(...)` never folds into a scope's own terms, and `update_all`, `delete_all` and `increment_each` reach only the rows a read would return. |
| Relationships (11 kinds) | `HasOne`, `HasMany`, `BelongsTo`, `BelongsToMany`, `HasOneThrough`, `HasManyThrough`, `MorphOne`, `MorphMany`, `MorphTo`, `MorphToMany`, `MorphedByMany` | shipped | Per-family morph enum. A `MorphTo` target can have an `i64`, `String`, UUID or ULID key, and a nested eager load goes through it: `with(["commentable.user"])`. [Relationships](eloquent-relationships.md#morphto-keys) |
| `wherePivot` family (incl. the closure form) | `where_pivot` / `where_pivot_op` / `where_pivot_in` / `where_pivot_not_in` / `where_pivot_null` / `where_pivot_not_null` / `where_pivot_between` / `where_pivot_not_between` / `where_pivot_group` plus `or_` twins | diverged | Reads only - a pivot filter never narrows `attach` / `detach` / `sync`, and eager loads do not carry it. [Relationships](eloquent-relationships.md) |
| Eager loading | `User::query().with(["posts", "posts.comments"]).get()` | shipped | `EagerLoadDispatch` is sealed; only macro-generated relations can implement it |
| Lazy loading prevention (`preventLazyLoading`) | `prevent_lazy_loading(bool)` makes a relation read fail on a model of a multi-row query; `handle_lazy_loading_violation(handler)` logs instead of failing | diverged | Same rule as Laravel's. `refresh()` drops the mark where Laravel keeps it, and the rows of `cursor()` and `lazy()` are marked where Laravel's `cursor()` marks none. [Preventing lazy loading](eloquent.md#preventing-lazy-loading) |
| Aggregates on relations | `with_count(["posts"])`, `with_sum(("orders", "total"))`, `with_avg`, `with_min`, `with_max` | shipped | One grouped query per aggregate |
| `whereHas` / `whereDoesntHave` | `where_has("posts", \|q\| q.db_where("published", true))` | shipped | Correlated EXISTS engine |
| `load` / `loadMissing` | `user.load(["posts"]).await?` and `user.load_missing(["posts"]).await?` on one model (`Model` trait), and the same on a collection | shipped | `load_missing` loads only relations not already loaded, at every level of a dotted name. [`load` / `load_missing` on one model](eloquent.md#load--load_missing-on-one-model) |
| Cloning a record | `user.replicate()` / `user.replicate_into::<OtherType>()` | shipped | Dispatches `Replicating` event |
| Touching parent timestamps | `#[model(touches = ["post"])]` | shipped | One `UPDATE` per `BelongsTo` or `MorphTo` owner, one level deep and event-free (no grandparent recursion, no parent `saved` event). `without_touching` / `without_touching_on::<M, _, _>()` to skip. [Parent touching](eloquent.md#parent-touching) |
| Observers | `impl Observer<User>` + `#[suprnova::observer(User)]` | shipped | 16 lifecycle events |
| 16 lifecycle events | `Retrieving`, `Retrieved`, `Creating`, `Created`, `Saving`, `Saved`, `Updating`, `Updated`, `Deleting`, `Deleted`, `Trashed`, `Restoring`, `Restored`, `Replicating`, `ForceDeleting`, `ForceDeleted` | shipped | Per-model `events::*` submodule. `EventResult::cancel(_)` short-circuits with a 400; pruning has its own `Prunable::pruning` hook |
| Mutators / Accessors | `#[accessor] fn full_name(&self) -> String { ... }` + `#[mutator] fn set_password(&mut self, value: Value) -> Result<(), FrameworkError>` for fields in `mutators = [...]` | shipped | [Mutators](eloquent-mutators.md) |
| Casts (33 built-in) | `casts! { AsString, AsInt, AsFloat, AsBool, AsJson, AsNativeJson, AsArray, AsArrayObject, AsObject, AsCollection, AsOptionalJson, AsOptionalNativeJson, AsOptionalArray, AsOptionalArrayObject, AsOptionalObject, AsOptionalCollection, AsDate, AsDateTime, AsImmutableDate, AsImmutableDateTime, AsOptionalDateTime, AsNativeDateTime, AsOptionalNativeDateTime, AsNaiveDateTime, AsOptionalNaiveDateTime, AsTimestamp, AsDecimal, AsEnum<E>, AsEncrypted, AsEncryptedObject, AsEncryptedArray, AsEncryptedCollection, AsHashed }` | shipped | Implement `Cast` for custom. The `AsOptional*` forms map a nullable column, where `None` is SQL `NULL` |
| Collections | `Collection<M>` with `pluck`, `filter`, `map`, `each`, `chunk`, `groupBy`, `keyBy`, `sort_by`, `where_eq`, `where_in`, `first`, `last`, `len`, `is_empty`, `to_array` and Laravel friends; derefs to a `[M]` slice | shipped | [Collections](eloquent-collections.md) |
| `modelKeys()` | `Builder::model_keys().await?` (no hydration, qualified key) and `Collection::model_keys()` | shipped | Both return `Vec<M::Key>`; the builder terminal projects `users.id` so it survives joins |
| API Resources | `#[derive(Data)]` with `#[json_resource("type")]` + `IntoJsonResource` + `JsonApiResponse` + fieldsets + includes | shipped | JSON:API documents; plain Laravel-style JSON comes from `#[derive(Data)]` serialisation. `?include=` paths are capped at `max_relationship_depth` (default 5), matching `JsonApiResource::$maxRelationshipDepth`. [API Resources](eloquent-resources.md) |
| Serialization | `#[model(hidden = [...], visible = [...], appends = [...])]` | shipped | Same control over which attributes serialise. [Serialization](eloquent-serialization.md) |
| Factories | `#[derive(Factory)]` on the model generates `UserFactory`: `UserFactory::new().count(5).create_many().await?` | shipped | `Sequence` counter for varying values. [Factories](eloquent-factories.md) |
| Lifecycle: chunking / lazy / cursor | `Builder::chunk(n, \|page\| async { ... })`, `lazy()`, `cursor()` | shipped | Memory-bounded iteration over large tables |
| Pessimistic locking | `Builder::lock_for_update()`, `shared_lock()` | shipped | Inside a transaction |
| `refreshForUpdate()` | `model.refresh_for_update().await?` | shipped | `SELECT ... FOR UPDATE` reload; no-op lock on SQLite. [Row locking](eloquent.md#row-locking) |
| `inOrderOf(col, values)` | `Builder::in_order_of(col, values)` | shipped | Bound `CASE WHEN` ordering; unlisted values sort last. Typed builder only. [Ordering](eloquent.md#ordering) |
| `orWhereKey` / `orWhereKeyNot` | `Builder::or_where_key(id)` / `Builder::or_where_key_not(id)` | shipped | Fold into the preceding clause as a disjunction; `or_filter_key` / `or_filter_key_not` aliases |
| `whereJsonContains` family | `where_json_contains` and `where_json_length` on the query builder (driver-aware) | shipped | On SQLite, contains is a substring match |

## Pagination

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| `LengthAwarePaginator` | `LengthAwarePaginator` (page + total + per_page + last_page) | shipped | `Builder::paginate(n).await?` |
| `Paginator` (simple) | `Paginator` (page + per_page + has_more, no count) | shipped | `Builder::simple_paginate(n).await?` |
| `CursorPaginator` | `CursorPaginator` (opaque cursor token + direction) | shipped | `Builder::cursor_paginate(n).await?`; deterministic for infinite scroll |
| Inertia integration | `IntoInertiaScroll` trait + `ScrollMetadata` | shipped | Wires straight into Inertia's `WhenVisible` / `merge` |

## AI (Laravel ships it in the framework; we don't gatekeep)

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| AI SDK | No first-party AI SDK | by design no | Bring the crate you already use (`async-openai`, `anthropic-sdk`, `ollama-rs`, `tokenizers`, etc.) and bind under `App` |
| MCP (Model Context Protocol) | `#[tool]` on a routed handler, served at `/mcp` by `Router::agents`, and in the browser through WebMCP | diverged | A tool call runs the route's middleware, validation and policies. Streamable HTTP (2026-07-28, and the `initialize`-based 2025 revisions without sessions), public, user and agent callers, OAuth discovery. Tools only, no prompts or resources. [Agents](agents.md) |
| Boost (Laravel coding agent) | n/a | by design no | Out of framework scope |

## Testing

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| `php artisan test` | `cargo test` | shipped | [Testing](testing.md) |
| Pest / PHPUnit style | `#[suprnova_test]` (async-aware) + `expect!()` Jest-like assertions + `describe!()` / `test!()` BDD macros | shipped | All three work interchangeably |
| Feature tests (HTTP) | Drive `handle_request(router, registry, req)` in the same process, normally through a loopback hyper connection so the server receives a real `Incoming` body | shipped | [HTTP Tests](http-tests.md) |
| `TestResponse` wrapper | `suprnova::testing::TestResponse` - fluent `assert_status` / `assert_json_path` / `assert_cookie` / `assert_session_has` and friends, all chaining `&Self` | shipped | [HTTP Tests](http-tests.md#fluent-response-assertions-with-testresponse) |
| Inertia testing helpers | `suprnova::testing::AssertableInertia` - `component`/`url`/`version`/`prop`/`has`/`missing`/`where_`/`count`/`has_flash`, plus `reload_only`/`reload_except`/`load_deferred_props` via a caller-supplied `with_reload` closure | shipped | [HTTP Tests](http-tests.md#testing-inertia-responses) |
| Console tests | `suprnova::console::test(["users:purge", "--days", "30"]).expects_question("Delete 12 users?", "yes").run().await` returns a `ConsoleRun` with `output()`, `errors()`, `exit_code()`, `assert_successful()`, `assert_failed()`, `assert_output_contains()`, `assert_errors_contain()`, `assert_exit_code()`, `assert_not_exit_code()`, `assert_every_question_was_asked()`, `unexpected_questions()` and `unmet_expectations()`; the test prepares `expects_question`, `expects_choice`, `expects_confirmation`, `expects_output`, `expects_output_to_contain` and `doesnt_expect_output_to_contain` up front | shipped | Runs the command through the dispatcher the console binary uses. A command prints with `console::line` and `console::error_line`, asks with `console::ask` and `console::confirm`, and ends with a code of its own through `FrameworkError::exit(code)`; what it prints with `println!` is not collected. Questions must come in the order the test gives them, and a question the test did not expect fails its assertions. |
| Browser tests (Dusk) | n/a in framework - use Playwright / WebdriverIO / `gstack` agent browser | by design no | Cross-language tooling already exists; we don't reinvent it |
| Database tests | `TestDatabase::fresh::<Migrator>()` | shipped | Creates a fresh per-test in-memory SQLite database, applies migrations, registers it in the test container, and discards that isolated database/container state on drop; it does not wrap each test in a rollback transaction. [Database Tests](database-testing.md) |
| Mocking & fakes | Per-facade fakes: `MailFake`, `NotifyFakeGuard`, `EventFakeGuard`, `Queue::fake`, `Bus::fake`, `Http::fake`, `Storage::fake` | shipped | `Queue::fake()` and `Bus::fake()` return a guard that uninstalls the fake on drop. Recorded calls + assertion helpers. [Mocking](mocking.md) |
| `QueueFake` job uuids | `queue::testing::pushed_with_id::<J>()` | shipped | The fake stamps an envelope id per push and emits the same `JobQueued` a real push does |
| Time travel | `TestClock::freeze()`, `TestClock::travel_to(at)`, then `advance` / `set` on the guard; `TestClock::scope` for a multi-thread runtime | diverged | The clock stands still until you move it, and it is per thread (guard) or per future (scope), not process-wide, so parallel tests keep their own time. Tokio's `pause` / `advance` move only Tokio's timers. [Moving the clock](testing.md#moving-the-clock) |
| Container isolation | `TestContainer::fake()`, then `TestContainer::bind(...)` - thread-local | diverged | Parallel-safe by construction. [Container](container.md) |

## Payments (Laravel's Cashier; ours is provider-generic)

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Cashier (Stripe) | `suprnova-payments-stripe` adapter crate behind generic `Payment` / `Subscription` / `CustomerStore` / `WebhookHandler` traits | diverged | Generic surface, concrete adapter. [Payments](payments.md), [Stripe Adapter](payments-stripe.md) |
| Cashier (Paddle) | `suprnova-payments-paddle` adapter | diverged | Merchant-of-Record flow + no direct `Payment` impl (Paddle owns the gateway). [Paddle Adapter](payments-paddle.md) |
| Custom provider | Implement `PaymentProvider`, `Checkout`, `Subscription`, `CustomerStore` and `WebhookHandler`; checkout returns a `SessionPayload` | shipped | [Provider Guide](payments-provider-guide.md) |
| Inertia checkout components | Documented dispatch loops for Svelte / React / Vue against `SessionPayload.flow` | shipped | [Payments Frontend](payments-frontend.md). Ready-made payment pages ship in the Directory starter ([Starter Kits](starter-kits.md)) |
| Subscription lifecycles | `Subscription::subscribe / update / cancel / get` (where the provider supports them) | shipped | `NotSupported` returned where the provider doesn't (e.g. Paddle `subscribe` and price-set replacement) |
| Webhook idempotency | `payments_webhook_events` mirror table with `UNIQUE(provider, provider_event_id)` | shipped | Stripe-style replay protection |
| Mirror tables | `payments_customers`, `payments_payment_methods`, `payments_subscriptions`, `payments_subscription_items`, `payments_transactions`, `payments_webhook_events` | shipped | A `provider_metadata` JSONB column on each for adapter-specific fields (`payments_webhook_events` keeps the raw `payload` instead) |

## Frontend (Laravel has Blade + starter kits; we have Inertia)

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| Blade | n/a - Inertia is the view layer | diverged | [Frontend](frontend.md) |
| Inertia.js | First-class: v3 over Svelte 5 / React 19 / Vue 3.5 | shipped | [Inertia Responses](frontend-inertia-responses.md), [Pages](frontend-pages.md) |
| `Route::inertia($uri, $component, $props)` | `Router::inertia(path, component, props)` | shipped | Returns a `RouteBuilder`, so `.name(...)` / `.middleware(...)` chain; `Router::view` is the older alias |
| Page URL resolution (`Inertia::resolveUrlUsing`) | `page.url` is path + query; override with `InertiaConfig::url_resolver` | shipped | Default derivation matches the version middleware's `X-Inertia-Location` byte for byte; a `url_resolver` changes `page.url` only |
| Inertia protocol middleware (`Vary`, empty response, version bounce) | `InertiaHeadersMiddleware` + `InertiaVersionMiddleware` + `Inertia303Middleware` - three of the middlewares `Inertia::install` wires (validation-error redirect and error pages are the next two rows) | shipped | `Vary: X-Inertia` on every response; empty `200` on an Inertia visit becomes `303` back; the 409 bounce re-flashes the session |
| Validation-error redirect (`Middleware::resolveValidationErrors`, `$withAllErrors`) | `InertiaValidationRedirectMiddleware`, wired by `Inertia::install`; `InertiaConfig::with_all_errors(bool)` | shipped | A `422` on an Inertia visit becomes `303` back with the errors flashed; a field's value collapses to its first message unless `with_all_errors(true)`. [Inertia Responses](frontend-inertia-responses.md#validation-failures) |
| Error pages (`Inertia::render('Error', ['status' => …])` from the exception handler) | `InertiaConfig::error_page("Error")`; `InertiaErrorPageMiddleware`, wired by `Inertia::install` when a component is named | shipped | One config line instead of an exception-handler edit. A `403` / `404` / `429` / `500` on an Inertia visit or a browser navigation renders the named page at the original status, with `status` / `message` / `request_id` props; API clients, `422`s, `X-Inertia-Location` bounces, and any body that is not an error envelope are untouched. The three starters ship the page and enable it. [Inertia Responses](frontend-inertia-responses.md#error-pages) |
| External redirect + history clearing | `InertiaResponse::location_for(&req, url)`, `App::clear_history()` | shipped | `location_for` is `409` for XHR and `302` for a hard navigation; `App::clear_history()` survives the logout redirect |
| `Inertia::share` / `getShared` / `flushShared` | `App::inertia_share` / `_lazy` / `_once`, `App::inertia_shared(key)`, `App::flush_inertia_shared()` | shipped | Dot-key nesting via `Arr::set` semantics; per-request `InertiaSharedData::share(&req, component)` can vary by page. A dotted share stays flat until the response's unpacking pass, so `only`/`except` match an ancestor entry (`only: ['auth']` reaches `auth.user`) where Laravel gets the same result from `Arr::set` at share time |
| Partial reloads | `#[derive(Data)]` + `current_include_set().includes("subset")` + Inertia's partial-reload protocol | shipped | Type-safe include sets. `?include=` gates every lazy flavor including `lazy(deferred)`, and runs ahead of `X-Inertia-Partial-Data` so a disallowed include still returns 400. `errors` is exempt from `only`/`except`, matching Laravel's `Inertia::always` share |
| Deferred props | `.defer(…)` / `.defer_with(…, DeferOptions)`, or `Prop::…defer()` | shipped | Inertia v3 deferred-props protocol; `DeferOptions` carries the group and the rescue flag. `deferredProps` ships on the initial visit only - `resolveDeferredProps` returns `[]` on any matched partial |
| Merge props | `.merge` / `.merge_prepend` / `.deep_merge` / `.merge_with(MergeStrategy)` / `.merge_lazy` / `.merge_lazy_with`, or `Prop::…merge().merge_with_path(...)` | shipped | Inertia v3 merge protocol; `match_on` takes one field or several; `merge_with_path` merges a nested field instead of the prop's root |
| Prop composition (`defer()->merge()`, `merge()->once()`, `optional()->once()`) | `Prop` flag builder + `InertiaResponse::prop(key, prop)` | shipped | `Prop` is a struct of orthogonal flags, mirroring the PHP adapter's `Deferrable` / `Mergeable` / `Onceable` interfaces |
| Encrypt history | `EncryptHistoryMiddleware` | shipped | History encrypted at rest in the client |
| Scroll position | `.scroll` / `.scroll_with` / `.scroll_wrapped` / `.paginate` + `ScrollMetadata` / `ProvidesScrollMetadata` | shipped | Auto-restore on navigation; `reset` reads `X-Inertia-Reset`, matching `resolveScrollProps` |
| TypeScript types | `suprnova generate-types` reads `#[derive(InertiaProps)]` and emits `inertia-props.ts` | shipped | [TypeScript Types](frontend-typescript-types.md) |
| Vite manifest reading | Auto-wired via `InertiaConfig::manifest_path` | shipped | HMR in dev, hashed assets in prod. `Inertia::install` fails closed in production when the manifest is missing |
| Asset version from the build manifest | `InertiaConfig` default: `VersionResolver::from_manifest(manifest_path)` | shipped | Hash of the manifest bytes; static `"1.0"` fallback when there is no build to hash |
| Inertia SSR (`inertia:start-ssr`) | `InertiaConfig::ssr(...)` on the config passed to `Inertia::install`, worker launched by `ssr:start` on the application binary or the `suprnova` CLI | shipped | Out-of-process worker over HTTP loopback; falls back to CSR on error or timeout unless `ssr_throw_on_error(true)`. `InertiaConfig::ssr_bundle_path(...)` gates dispatch on the built bundle existing on disk (mirrors `ensure_bundle_exists`), toggled with `.ssr_ensure_bundle_exists(bool)` (on by default once a bundle path is set); `suprnova new` scaffolds `frontend/src/ssr.{ts,tsx}` and a `build:ssr` script for every starter; `ssr:check` asks the SSR gateway's health check (`inertia:check-ssr`) and `ssr:stop` sends the worker `GET /shutdown` (`inertia:stop-ssr`), on both binaries. [Inertia Responses](frontend-inertia-responses.md) |

## CLI

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| `php artisan` | Per-app `console` binary built from `#[command]` macros | shipped | [Console](console.md), [CLI overview](cli.md) |
| `make:controller` / `make:model` / etc. | `suprnova make:controller / make:middleware / make:action / make:error / make:inertia / make:migration / make:task`, and the one-file generators `make:factory / make:seeder / make:cast / make:channel / make:class / make:enum / make:event / make:listener / make:job / make:job-middleware / make:mail / make:notification / make:observer / make:policy / make:provider / make:resource / make:rule / make:scope / make:test / make:trait / make:interface` | shipped | [Generators](cli-generators.md). No `make:model`: a model is written with `#[suprnova::model]` or by `db:sync` |
| `serve` | `suprnova serve` (backend + Vite dev server together) | shipped | [Serve](cli-serve.md). Skips the Vite pane on a `--api` project instead of refusing to start. |
| `migrate` family | `suprnova migrate / migrate:rollback / migrate:status / migrate:fresh` | shipped | [Migrations CLI](cli-migrations.md) |
| `db:seed` | `cargo run --bin console db:seed` (via per-app console) | shipped | Seeders registered via `Seeder` trait; a targeted run prints RUNNING / DONE with elapsed milliseconds |
| `schedule:run` / `schedule:work` / `schedule:list` | Same names on the app binary, forwarded by the `suprnova` CLI | shipped | [Scheduling CLI](cli-scheduling.md) |
| `queue:work` | Same name on the app binary | shipped | Graceful shutdown on SIGTERM/SIGINT |
| `tinker` | No REPL | by design no | See the row in "Digging deeper" |

## Deployment

| Laravel | Suprnova | Status | Notes / link |
|---|---|---|---|
| `php artisan optimize` | `cargo build --release` | diverged | One binary, no opcache step |
| `php artisan config:cache` | Typed config is compile-time-checked already | diverged | No runtime cache to invalidate |
| `php artisan route:cache` | Routes are macro-expanded at compile time | diverged | The router is built at boot from already-typed routes |
| Envoy (SSH deploys) | Use any orchestrator - Docker, systemd, Kubernetes, fly.io, Railway | by design no | The binary is the deploy artifact |
| Forge / Vapor | Not ours to ship - but the recipes for Railway, DO, and Hetzner cover the same job | diverged | [Deployment](deployment.md), [Railway](deployment-railway.md), [Digital Ocean](deployment-digital-ocean.md), [Hetzner](deployment-hetzner.md) |
| Maintenance mode (`php artisan down` / `up`) | `./app down` / `./app up` - bypass secret with a server-checked 12-hour expiry, custom retry/message/except paths, `file` or `cache` driver | shipped | [Deployment](deployment.md) |
| Horizon (queue dashboard) | No first-party dashboard | not built | Failed-job inspection via `suprnova queue:failed`, `queue:retry`, `queue:forget`, `queue:flush` and `queue:prune-failed`, which the app binary runs too |

## Packages (Laravel's official packages - ours either ship in core, ship as adapters, or are deliberate gaps)

| Laravel package | Suprnova | Status | Notes / link |
|---|---|---|---|
| Cashier (Stripe) | `suprnova-payments-stripe` | shipped | Generic + adapter. [Payments](payments.md) |
| Cashier (Paddle) | `suprnova-payments-paddle` | shipped | MoR flow. [Payments](payments.md) |
| Dusk | n/a | by design no | Cross-language browser tooling already exists (Playwright, etc.) |
| Envoy | n/a | by design no | Containers / systemd / orchestrators do the job |
| Fortify | Replaced by `auth_flows` | shipped | Same job, integrated. [Auth Flows](auth-flows.md) |
| Folio | n/a - page-based routing isn't idiomatic Rust | by design no | Use `routes!` for explicit routing |
| Homestead | n/a - use Docker / DevContainers | by design no | [Docker recipe](cli-docker.md) |
| Horizon | n/a | not built | Failed jobs surface through `suprnova queue:failed` and the commands beside it |
| Mix | Replaced by Vite | diverged | Vite ships in every frontend scaffold (`suprnova new --api` has no frontend) |
| Octane | n/a - we are already long-lived Tokio | by design no | Single binary, always warm, no FPM to swap out |
| Passport | The Magnetar authorization server plugin (`OAuthServer`) | diverged | OAuth 2.1 for MCP clients; no password, client credentials or implicit grants and no personal access tokens. [Agents](agents.md#users-who-approve-a-client) |
| Pennant (feature flags) | Re-implemented as `features::*` | shipped | [Feature Flags](feature-flags.md) |
| Pint (PHP code style) | `cargo fmt` + `cargo clippy` | diverged | Standard Rust toolchain |
| Precognition | Precognitive requests (the `Precognition` header) answered by `FormRequest` extraction, with the same `#[derive(Data, Validate)]` types | shipped | Validation runs without calling the handler |
| Prompts (CLI UI) | `console::ask_with_default`, `secret`, `select`, `select_keyed`, `multiselect`, `Progress`, `progress` and `form` | shipped | [Console](console.md#prompts); `console::test` answers them with `expects_question` and `expects_choice` |
| Pulse | n/a | not built | OTel metrics and traces |
| Reverb (WebSocket server) | Built into Suprnova (`ws!()` + `BroadcastHub`) | diverged | No separate server needed - it's the same process |
| Sail (Docker dev) | `suprnova-cli` ships Docker recipes inline | shipped | [CLI Docker](cli-docker.md) |
| Sanctum | `BearerTokenMiddleware` over Magnetar bearer sessions | diverged | No separate package or personal-access-token management surface |
| Scout (full-text search) | n/a | not built | Semantic search ships via [Vector](vector.md); keyword search through `meilisearch-sdk` / `elasticsearch` |
| Socialite | Magnetar provider registry and `Auth::oauth(provider)` | shipped | [OAuth](oauth.md) |
| Telescope | n/a | not built | Tracing + OTel cover the diagnostic gap |
| Valet | n/a - Rust apps run directly | by design no | `suprnova serve` is the dev runner |

## Macros (Rust-specific surface; closest Laravel analogues for context)

Suprnova ships a wide set of proc-macros that don't have a Laravel analogue
because Laravel doesn't have macros - it has runtime reflection. Including
them here so you don't miss them.

| Macro | Closest Laravel idea | What it does |
|---|---|---|
| `#[suprnova::model]` | `extends Model` | Generates SeaORM entity + impls `Model` trait |
| `#[suprnova::observer(M)]` | `User::observe(UserObserver::class)` | Registers an `Observer<M>` impl via `inventory` |
| `#[scopes(M)]` | Local scopes on a model | Adds methods to `Builder<M>` |
| `#[accessor]` / `#[mutator]` | Eloquent accessors / mutators | Field-level get/set hooks |
| `#[handler]` | Controller `__invoke` | Auto-extracts typed params from `Request` |
| `#[command]` / `#[derive(Command)]` | Artisan command class | Registers a console subcommand |
| `#[policy]` | Policy class | Registers a `Policy` impl via `inventory` |
| `#[service(T)]` | Service provider `register` | Binds `T` into the container |
| `#[injectable]` | Constructor injection | Generates an `App::make`-backed constructor |
| `#[derive(InertiaProps)]` | Inertia props | TypeScript codegen + Inertia serialization |
| `#[derive(Data)]` | Request DTO | Extractable from `Request` with include-set support |
| `#[derive(FormRequest)]` | `FormRequest` class | Validation + auth gate + transformation |
| `#[derive(Factory)]` | Model factory | Faker-backed test data generation |
| `#[derive(Data)]` + `#[json_resource]` | API Resource | JSON:API + Laravel-shape serialization |
| `#[workflow]` / `#[workflow_step]` | n/a in Laravel | Long-running stateful work |
| `routes!` + `get!` / `post!` / `ws!` etc. | `Route::get` / `Route::post` | Compile-time route registration |
| `casts!` | `protected $casts = [...]` | Per-model cast declaration |
| `attrs!` | Mass-assignment array | Partial-attribute builder |
| `json_response!` / `text_response!` | `response()->json(...)` | Quick `Ok(HttpResponse::...)` |

See [Macros](macros.md) for the full reference.

## Helper functions (Laravel's global helpers; ours are typed)

Laravel ships hundreds of small globals (`str_replace_first`, `array_flatten`,
`now()`, `tap()`, `optional()` …). Most of them have a direct Rust equivalent
in `std` or a small standard crate, so Suprnova doesn't reintroduce them as a
single namespace. The ones that *are* useful to have aliased ship under their
home module.

| Laravel helper | Suprnova / Rust equivalent | Where |
|---|---|---|
| `auth()` | `Auth::user().await?` | [Authentication](authentication.md) |
| `cache()` | `Cache::get/put/...` | [Cache](cache.md) |
| `config('app.name')` | `Config::get::<AppConfig>()?.name` | [Configuration](configuration.md) |
| `csrf_token()` | `csrf_token()` (same name) | [CSRF](csrf.md) |
| `dd()` | `Builder::dd()` (Eloquent query dump-and-die) / `dbg!()` from the stdlib | `Builder::dump()` / `Builder::dd()` exist for query inspection; use `dbg!()` for general values |
| `env('APP_KEY')` | `env("APP_KEY")` / `env_required("APP_KEY")` / `env_optional("APP_KEY")` | [Configuration](configuration.md), [Env Vars](env-vars.md) |
| `now()` | `chrono::Utc::now()` (re-exported as `suprnova::chrono`) | - |
| `optional($x)->y` | `x.as_ref().map(\|x\| x.y)` | Rust handles this with `Option<T>` directly |
| `redirect('/')` | `redirect("/")` (same name) | [Routing](routing.md) |
| `request()` | `Request` is passed into your handler | [Requests](requests.md) |
| `response()` | `HttpResponse::json/text/redirect/...` | [Responses](responses.md) |
| `route('posts.show', ['post' => 1])` | `url("posts.show", &[("post", "1")])` | [URL Generation](urls.md) |
| `session('key')` | `session().get("key")` | [Session](session.md) |
| `str()` / `Str::camel($x)` | `heck` crate methods (`ToUpperCamelCase`, etc.) | - |
| `tap($x, fn) → $x` | `tap` from `tap` crate, or `dbg!` for quick inspection | Use the `tap` crate idiomatically |
| `today()` | `chrono::Utc::now().date_naive()` | - |
| `value($x)` | Just call the closure: `x()` | n/a - Rust closures need no helper |
| `view('home', $data)` | Inertia response: `Inertia::render("Home", data)` | [Inertia Responses](frontend-inertia-responses.md) |

## What Suprnova doesn't have

Every **not built** row above in one place, with the route to take
instead:

| Area | What's missing | Route instead |
|---|---|---|
| Search (Scout - keyword) | Algolia / Meilisearch / Elastic adapter | Use `meilisearch-sdk` / `elasticsearch` directly; [Vector](vector.md) handles semantic search |
| Telescope (debug dashboard) | Web UI for requests / queries / events / cache hits | Use OTel + tracing output ([Observability](observability.md)) |
| Pulse (perf dashboard) | Web UI for slow queries / errors / hot routes | Same: the OTel surface |
| Horizon (queue dashboard) | Web UI for queue depth / failed jobs / throughput | `suprnova queue:failed` (and `queue:retry`, `queue:forget`, `queue:flush`, `queue:prune-failed`) and OTel metrics |
| MongoDB | First-party document-database adapter | The `mongodb` crate directly, bound via `App::bind` |

## What we won't ship (and why)

| Laravel feature | Why Suprnova doesn't have it |
|---|---|
| Tinker (REPL) | Rust doesn't have a productive REPL story for compiled binaries. A short `#[suprnova_test]` or a one-off `cargo run --bin <thing>` script does the job |
| Blade templates | Inertia is the view layer; we don't ship a parallel server-rendered template engine |
| `helpers.md` kitchen-sink | Rust ships `std` + small focused crates (`heck`, `chrono`, `regex`); we don't reintroduce a single global namespace |
| Mix | Vite covers it and ships in every scaffold |
| Octane | Suprnova is already long-lived Tokio; there's no FPM mode to optimise out of |
| Dusk (browser tests) | Cross-language tooling (Playwright, WebdriverIO, `gstack` agent browser) already solves this |
| Sail (Docker dev) | Docker recipes ship inline ([CLI Docker](cli-docker.md)); no separate package needed |
| Valet | `suprnova serve` is the dev server |
| Envoy (SSH deploys) | Containers / systemd / orchestrators do the job; we don't need a bespoke SSH DSL |
| Concurrency facade (`Concurrency::run`) | Tokio (`tokio::join!` / `tokio::spawn` / `tokio::select!`) is the answer; no facade needed |
| First-party AI SDK / Boost | Pick the Rust crates you already use; we don't gatekeep |
| Prompts' arrow-key terminal UI | The prompts ship as `console::secret`, `select`, `multiselect`, `progress` and `form`, and each reads one line, so a command runs the same by hand, from a script and under `console::test`. [Console](console.md#prompts) |
| Laravel-style PHP/JSON translation files | Localization ships, but the catalog format is Fluent `.ftl` - one format the server and the browser both parse. `trans_choice` has no equivalent either: Fluent selects CLDR plural categories inside the message. [Localization](localization.md) |
| `php artisan dev --tabs` (TUI multi-pane dev-process mode) | Single-terminal, `[name]`-prefixed output is the Rust dev-tooling norm (`cargo watch`, `bacon`, `just`) - `suprnova serve` already gives every process (backend, frontend, and any `suprnova.toml` entry) its own colored prefix and auto-restart. A tabbed TUI is a second interaction model for a signal this already provides; `--stream`'s job - one scriptable, real-time output stream - ships as `suprnova serve --json` (NDJSON, one event per line). [Serve](cli-serve.md#extra-dev-processes) |

## How this list stays honest

Every row in the **shipped** column is verifiable by:

1. Grepping `framework/src/lib.rs` for the named export
2. Running the framework test suite (`cargo test --workspace`)
3. Reading the linked chapter

Every row in the **not built** column has its route in the Notes column. Every
row in the **by design no** column has a one-sentence reason in the Notes column;
those reasons are the design principles in [Introduction](introduction.md)
applied to a specific feature.

Last reviewed against Laravel 13.25.0.

If you find a Laravel feature you reach for that isn't on this map, open
an issue - it either has a Suprnova answer that's missing a row, or it's
a real gap and we want to know.

## Next

- [From Laravel](from-laravel.md) - the same map, narrated as a side-by-side
- [Introduction](introduction.md) - the design principles this parity work follows
- [`documentation.md`](documentation.md) - the master TOC across every chapter


---

<!-- /docs/env-vars -->

# Environment Variables

This is the audited list of every environment variable the Suprnova
framework reads at runtime, grouped by the subsystem that consults it.
Every entry has been validated against framework source - defaults,
types, and behaviour reflect what the code actually does, not what the
starter `.env` happens to ship.

The list also covers the variables the `suprnova` CLI binary reads
(the dev server) since those appear in the starter `.env` and
readers will look for them here.

See [Configuration](configuration.md) for the loading rules
(`.env` → `.env.<environment>` → process env), the `env*` helpers
(`env`, `env_required`, `env_optional`), and the typed `Config::*`
registration pattern.

## Conventions

- **Default** - the value the framework uses when the variable is
  unset. `none` means there is no default; the framework either
  errors at boot, falls back to a feature default (e.g. `Memory`
  driver), or treats the value as `None`.
- **Type** - the Rust type the variable is parsed into. `bool` values
  accept `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`
  (case-insensitive). Out-of-range or unparseable values for typed
  framework knobs are clamped (workflow), `warn!`-logged then
  defaulted (lenient `env()` / `env_optional()`), or fail boot
  (strict `try_from_env`).
- **Required** - `boot` means the framework refuses to start without
  it in the listed environments. `driver` means it's required only
  when the parent driver is selected (e.g. `MAIL_SES_REGION` is
  irrelevant unless `MAIL_DRIVER=ses`). Everything else is optional.

Where a starter `.env` ships a key the framework never reads
(`MAIL_FROM_ADDRESS`), it's called out at the end of this chapter.

## Page budget

`PageBudget::from_env()` reads these settings for `budget:audit`. Unset values
keep the shipped defaults. Invalid values return an error naming the variable.
Booleans use literal `true` or `false`. The fingerprint expression is the same
strict Vite convention described in [Page Budget](page-budget.md).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `PAGE_BUDGET_TOTAL_BYTES` | `1000000` | u64 | Total transferred response bytes. |
| `PAGE_BUDGET_ASSET_BYTES` | `250000` | u64 | Transferred bytes per asset. |
| `PAGE_BUDGET_RASTER_THRESHOLD_BYTES` | `100000` | u64 | Decoded bytes above which a raster needs a modern format and fallback. |
| `PAGE_BUDGET_PNG_MARGIN_PERCENT` | `10` | u32 | Margin above the fast PNG recompression size. |
| `PAGE_BUDGET_FONT_BYTES` | `100000` | u64 | Combined transferred font bytes. |
| `PAGE_BUDGET_REQUIRE_IMMUTABLE` | `true` | bool | Check fingerprinted cache policy. |
| `PAGE_BUDGET_FORBID_ASSET_SET_COOKIE` | `true` | bool | Reject asset response cookies. |
| `PAGE_BUDGET_FORBID_ASSET_REQUEST_COOKIE` | `true` | bool | Reject captured asset request cookies. |
| `PAGE_BUDGET_REQUIRE_COOKIE_INDEPENDENT` | `true` | bool | Require successful anonymous asset access. |
| `PAGE_BUDGET_FORBID_FIRST_REDIRECT` | `true` | bool | Reject an initial document redirect. |
| `PAGE_BUDGET_FINGERPRINT_PATTERN` | Strict Vite hash expression | regex | Match the filename stem. |
| `PAGE_BUDGET_ALLOWED_THIRD_PARTY_HOSTS` | unset | comma-separated hosts | Restrict external hosts when set. Empty forbids all external hosts. |
| `PAGE_BUDGET_MAX_RESOURCES` | `256` | usize | Bound discovery and queued resources. |
| `PAGE_BUDGET_MAX_DISCOVERY_TOKENS` | `65536` | usize | Bound parser tokens and raw reference candidates across collection. |
| `PAGE_BUDGET_MAX_RESPONSE_BYTES` | `16777216` | usize | Bound one response body. |
| `PAGE_BUDGET_REQUEST_TIMEOUT_SECS` | `10` | u64 | Bound one HTTP request in seconds. |
| `PAGE_BUDGET_COLLECTION_TIMEOUT_SECS` | `30` | u64 | Bound the complete collection in seconds. |

## Security headers

These variables are read by `SecurityHeaders::from_env()` when an application
registers the middleware. Invalid values return an error naming the variable.
See [Security Headers](security-headers.md) for presets and nonce handling.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SECURITY_HEADERS` | `balanced` | `String` | Selects `strict`, `balanced`, `relaxed` or `off`. Only registration turns the middleware on. |
| `SECURITY_HEADERS_CSP_REPORT_ONLY` | `false` | `bool` | Sends `Content-Security-Policy-Report-Only` instead of an enforced CSP. |
| `SECURITY_HEADERS_CSP_REPORT_TO` | none | URL | Adds the CSP `report-to` directive and a `Reporting-Endpoints` destination for violation reports. |
| `SECURITY_HEADERS_HSTS_PRELOAD` | `false` | `bool` | Adds `preload` to HSTS when opted in. HSTS is sent only on secure requests outside local development. |

## Error reporting

The `sentry` driver is inert without a DSN. All settings are optional. Logs
and transactions are opt-in, independent of error reporting. See
[Error Reporting](error-reporting.md) for Rustrak and browser setup.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `REPORTING_DRIVER` | `sentry` | `String` | Selects `sentry`, `log` or `null`. |
| `REPORTING_DSN` | none | Sentry DSN | Destination for server errors, logs and transactions. |
| `REPORTING_RELEASE` | application package version | `String` | Release name attached to events. |
| `REPORTING_SEND_PII` | `false` | literal `true` / `false` | Opts in to the user's email and IP; user id is included without it. Unlike the generic boolean convention above, this setting accepts only lowercase `true` or `false`. |
| `REPORTING_LOGS` | `off` | log level | Sends Sentry logs at or above this threshold. |
| `REPORTING_TRACES_SAMPLE_RATE` | `0` | fraction, `0..=1` | Fraction of request and job transactions sent. |
| `REPORTING_PUBLIC_DSN` | none | Sentry DSN | Configures Live browser reporting and allows the tracker's origin in CSP `connect-src`. |
| `VITE_REPORTING_DSN` | none | Sentry DSN | Build-time public DSN for Svelte, React and Vue kits; unset loads no reporter. The server reads it too and allows the tracker's origin in CSP `connect-src`. |

## Application

The `APP_*` family is the framework's identity and crypto root. These
are the variables every Suprnova app sets; the rest of the file
becomes relevant as you opt into subsystems.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `APP_NAME` | `"Suprnova Application"` | `String` | Application name. Used as the TOTP issuer (2FA), the HTTP Basic `WWW-Authenticate` realm, mail subject branding, and structured-log fields. |
| `APP_ENV` | `production` | `String` | Drives `Environment::detect()` and `.env.<suffix>` lookup. Recognised aliases (case-insensitive): `local`, `development`/`dev`, `staging`/`stage`/`stg`, `production`/`prod`, `testing`/`test`. Any other value is preserved as `Environment::Custom(...)` with original casing. Unset means production, as in Laravel: debug is off, every production check runs, and no `.env.<suffix>` file loads (`.env.local` still does). The scaffold's `.env` sets `APP_ENV=local`; a deployment that sets nothing runs as production. |
| `APP_DEBUG` | env-aware (see Required) | `bool` | Verbose error pages + extra logs. Default is `true` in `local`/`development`/`testing` and `false` everywhere else (including `staging`, `production`, an unset `APP_ENV`, and any unrecognised custom environment). An explicit value always wins; an unparseable value falls back to the env-aware default with a `warn!`. The strict `try_from_env` variant aborts boot on a parse failure. |
| `APP_URL` | `"http://localhost:8765"` (AppConfig) / `"http://localhost"` (URL fallback) | `String` | Base URL for absolute URL generation, signed URLs, and Inertia redirects. Trailing slashes are trimmed on read. It is also the MCP endpoint's own origin and the agents OAuth server's issuer: with `AgentsConfig::oauth_server` on, boot fails when it is unset outside the `local` and `testing` environments, and the issuer must be an `https` URL, or `http` only on a loopback host such as `localhost`. |
| `APP_KEY` | none - required in non-dev | `String` (base64-url-no-pad, 32 bytes) | AES-256-GCM key for `Crypt`, encrypted sessions, pagination cursors, signed URLs, and any other encrypt-at-rest path. Boot **fails closed** when missing or malformed outside `local`/`development`/`testing`. Generate with `suprnova key:generate`. |
| `APP_KEY_PREVIOUS` | none | `String` (comma-separated base64 keys, max 8) | Comma-separated previous keys used during rotation. `Crypt::decrypt` tries the current `APP_KEY` first, then each entry in order. Hard cap of 8 entries - `crypto::MAX_PREVIOUS_KEYS`. A half-rotated entry that fails to decode aborts boot. See [Encryption](encryption.md#key-rotation---the-keyring). |
| `APP_PREVIOUS_KEYS` | none | `String` (alias of `APP_KEY_PREVIOUS`) | Laravel-compat alias accepted so a Laravel `.env` dropped into a Suprnova deploy still graceful-decrypts legacy data. When both are set with different values, `APP_KEY_PREVIOUS` wins with a `warn!` to surface the duplicate; identical values are accepted silently. |
| `APP_BASE_PATH` | current working directory | `Path` | Root directory the path resolver uses for `config/`, `database/`, `public/`, `storage/`, `resources/`, `lang/`. Useful when running the binary from a different CWD than the project root (e.g. systemd unit, `WorkingDirectory=` not pointing at the project). Falls back to CWD, then `.` if CWD is unavailable. |
| `APP_TRUSTED_PROXIES` | none - empty allowlist | `String` (comma-separated IPs and CIDR ranges) | Addresses and ranges of the proxies whose `X-Forwarded-*` / `X-Real-IP` headers `Request::ip()` and the host / scheme / port accessors may believe. An entry is an address (`10.0.0.5`) or a range in CIDR form (`173.245.48.0/20`, `2400:cb00::/32`). A range of every address (`0.0.0.0/0`, `::/0`) is refused. **Empty by default, so proxy headers are ignored and the TCP peer always wins** - see the note below before deploying behind a proxy. An entry that is neither an address nor a valid range fails boot (`try_from_env`). |
| `AUTH_GUARD` | `"web"` | `String` | Name of the default guard read by `Auth::*`. Mirrors Laravel - only the default is env-selectable; named guards live in code via `AuthConfig::guard(name, …)`. |

Two more `APP_*` variables - `APP_LOCALE` and `APP_FALLBACK_LOCALE` -
are read by the localization subsystem rather than by `AppConfig`, so
they are listed under **Localization** below.

### Behind a reverse proxy, set `APP_TRUSTED_PROXIES`

Ignoring proxy headers is the safe default - `X-Forwarded-For` is caller-supplied
and trusting it unconditionally lets anyone claim any address. But the moment a
terminating proxy is in front of you (nginx, Traefik, an ALB, Cloudflare), the
TCP peer is *the proxy*, on every request, and leaving this unset does not merely
lose the client's address:

- **Per-IP rate limits collapse into one bucket.** `ThrottleRequestsMiddleware::with(...)`
  keys on `request.ip()` and the request path, so `ThrottleRequestsMiddleware::with(20, 1,
  "login")` stops meaning "20 login attempts per client per minute" and starts
  meaning 20 *in total, across everyone*. `ThrottleRequestsMiddleware::default()`
  keys on the user id when a user is signed in and on `request.ip()` otherwise,
  so it collapses the same way for every visitor who is not signed in. That is both weaker (no per-attacker
  budget) and actively dangerous: any single caller can spend the quota and lock
  every legitimate user out of the login form. See [Rate limiting](rate-limiting.md).
- `Request::host()`, `scheme()` and `port()` fall back to the connection rather
  than to `X-Forwarded-Host` / `-Proto` / `-Port`, so generated absolute URLs can
  name the internal address and scheme instead of the public one.

List the addresses the proxy hops reach you from - not the client's. An entry is
one address or a range in CIDR form:

```bash
APP_TRUSTED_PROXIES=10.0.0.5,173.245.48.0/20,2400:cb00::/32
```

Four rules decide how the list is used:

- **List every proxy of the chain, not the last one alone.** `Request::ip()`
  reads `X-Forwarded-For` from the right and returns the first address that is
  not in the list. A proxy that is not listed is taken for the client, and all
  of its clients share one address. This includes an address that a load
  balancer adds behind the client's, as the external Application Load Balancer
  of Google Cloud does.
- **A range must hold proxies and nothing else.** A client that connects from a
  trusted address is believed like a proxy: it writes its own
  `X-Forwarded-For`, and with it the address `ip()` returns, and the forwarded
  host and scheme as well. The network of the pods of a cluster and the range of
  a VPN have clients in them. Do not list them.
- **The proxy must write `X-Forwarded-For` itself**, by adding the address it
  saw to the header or by replacing the header. A proxy that passes the client's
  header on as it came lets the client write all of it.
- **`X-Real-IP` is read only when the request has no `X-Forwarded-For` at all.**
  A proxy that writes `X-Real-IP` alone must remove the client's
  `X-Forwarded-For`. The `Forwarded` header of RFC 7239 is not read.

A proxy that serves the application under a path, such as `/billing`, names
that path in `X-Forwarded-Prefix`, which counts under the same rule. See
[Serving under a path prefix](deployment.md#serving-under-a-path-prefix).

An IPv4 address written as an IPv6 one (`::ffff:10.0.0.5`) counts as the IPv4
address, in the headers and for the peer. `Request::ips()` returns the whole
chain. It is a record, not something to decide by.

Nothing detects a missing list for you: an app behind a proxy with the variable
unset looks healthy, serves correctly, and quietly rate-limits everyone as one
user.

### App-key required matrix

| Environment | `APP_KEY` required at boot |
|---|---|
| `local` | no (generates an ephemeral key if missing) |
| `development` | no |
| `testing` | no |
| `staging` | yes - boot exits non-zero with a remediation message |
| `production`, or `APP_ENV` unset | yes |
| `Custom(...)` | yes - anything not in the safe-list is treated as production for this check |

## Server

The HTTP listener and request body limits.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SERVER_HOST` | `"127.0.0.1"` | `String` | Bind address. Set to `0.0.0.0` to expose outside the loopback interface (e.g. in containers). |
| `SERVER_PORT` | `8765` | `u16` | Bind port. Lenient parse warns and defaults; strict `try_from_env` aborts boot on a typo. |
| `SERVER_MAX_BODY_SIZE` | `8388608` (8 MiB) | `usize` (bytes) | Process-global maximum request body size. Per-`FormRequest::max_body_bytes` overrides still apply on individual endpoints. The configured value is wired into the global cap during `Server::from_config`. |
| `SERVER_MAX_CONNECTIONS` | `10000` | `usize` | Cap on concurrently active TCP connections. Unset or blank gives `10000`. A value that is zero or unparseable falls back to a finite `10000` with a warning rather than silently reverting to unbounded - a botched limit is still a request for a limit. No value removes the cap: a server with no cap is a choice made in code with `ServerConfig::builder().unbounded_connections()`. See [Deployment](deployment.md#connection-cap-server_max_connections). |
| `SERVER_HEADER_READ_TIMEOUT` | `30` | `u64` (seconds) | Deadline for reading a request's complete head. The slowloris mitigation. Zero is treated as invalid, not as "disable", and falls back to the default. Does not apply to established WebSocket/SSE connections. |
| `SERVER_BODY_READ_TIMEOUT` | `30` | `u64` (seconds) | Longest wait for the next piece of a request body. A body that misses it is abandoned: the read fails with `408 Request Timeout` and the connection closes. Applies to every read of a request body, the framework's own and a handler's read of the raw stream alike, multipart uploads included. Zero is treated as invalid, as for `SERVER_HEADER_READ_TIMEOUT`, and falls back to the default. Raise it for clients that upload over very slow links. |
| `SERVER_BODY_TOTAL_TIMEOUT` | `3600` (one hour) | `u64` (seconds) | Longest a whole request body may take to arrive, counted from when the server read the request head. A backstop: `SERVER_BODY_READ_TIMEOUT` is the defence against a trickled body, and this ends one that keeps sending a byte inside every per-frame wait. A body that misses it is abandoned the same way. Zero is treated as invalid and falls back to the default. Raise it only for uploads that take longer than an hour to send. |
| `SERVER_HEALTH_READINESS_TOKEN` | unset (readiness is public) | `String` | Shared secret required to reach `/_suprnova/health/ready` and `/_suprnova/health?db=true`, sent as `X-Suprnova-Health-Token`. Without it those paths answer 404, indistinguishably from any unrouted path; liveness stays public. See [Deployment](deployment.md#health-check). |

## Database

Connection URL and sqlx pool tuning. `DATABASE_URL` is required for
any subcommand that touches the database (`migrate*`, `db:sync`,
`db:seed`, `queue:work` with `QUEUE_DRIVER=database`, `workflow:work`,
the session DB store) and for `serve` when the app has migrations
registered. The five liveness knobs are how you survive a network that
drops idle connections - see [Pool liveness](database.md#pool-liveness).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `DATABASE_URL` | none - required when migrations exist | `String` | Connection URL. Scheme selects the driver: `sqlite://path`, `postgres://...` / `postgresql://...`, `mysql://...`, `mariadb://...`. The framework auto-creates the parent directory for SQLite paths. `serve` skips the database connection entirely when the configured `Migrator` has no migrations. |
| `DB_MAX_CONNECTIONS` | `10` | `u32` | sqlx pool ceiling. |
| `DB_MIN_CONNECTIONS` | `1` | `u32` | sqlx pool floor (kept warm). |
| `DB_CONNECT_TIMEOUT` | `30` (seconds) | `u32` | How long sqlx will wait for an initial connection before erroring. |
| `DB_LOGGING` | `false` | `bool` | When true, sqlx logs every statement (use sparingly in production - chatty). |
| `DB_IDLE_TIMEOUT` | unset (sqlx uses 600 seconds) | `u64` (seconds) | How long a pooled connection may sit idle before the pool closes it. `0` disables idle reaping. |
| `DB_MAX_LIFETIME` | unset (sqlx uses 1800 seconds) | `u64` (seconds) | How long a pooled connection may live before the pool recycles it. `0` disables lifetime recycling. |
| `DB_ACQUIRE_TIMEOUT` | unset (falls back to `DB_CONNECT_TIMEOUT`) | `u64` (seconds) | How long a caller waits for a free pooled connection. Overrides `DB_CONNECT_TIMEOUT` for the checkout wait; set one or the other, not both. Zero is rejected at boot. |
| `DB_TEST_BEFORE_ACQUIRE` | `true` | `bool` | Ping a pooled connection before handing it out. Leave it on unless you have measured the per-checkout round trip and `DB_PING_AFTER_IDLE` is not enough. |
| `DB_PING_AFTER_IDLE` | unset | `u64` (seconds) | Ping a pooled connection only after it has been idle this long. Setting it turns `DB_TEST_BEFORE_ACQUIRE` off, so hot connections are handed out untouched. |
| `DB_CHARSET` | `utf8mb4` | `String` | MySQL and MariaDB only: the character set every connection sends with `SET NAMES`, and the one `Schema::create` gives a new table. A `charset` parameter in the URL wins. Ignored for Postgres and SQLite. See [Character set and collation](database.md#character-set-and-collation). |
| `DB_COLLATION` | `utf8mb4_unicode_ci` | `String` | MySQL and MariaDB only: the collation every connection sends, and the one `Schema::create` gives a new table, as Laravel's. A `collation` parameter in the URL wins. Tables created before you upgraded keep the server's default collation (`utf8mb4_0900_ai_ci` on MySQL 8), and MySQL refuses to compare string columns of two collations: set this to that default to keep it. Only letters, digits and underscores; anything else fails the connection. |
| `SUPRNOVA_AUTO_MIGRATE_BEST_EFFORT` | `false` | `bool` | When true, a failing auto-migration during `serve` boot is logged but does not abort. Default is fail-closed: boot exits non-zero rather than start against a partially-migrated schema. Pass `--no-migrate` to skip auto-migration entirely. |

## Laravel database

Variables for an application on a database a Laravel application created.
See [Running on a Laravel Database](laravel-database.md).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `LARAVEL_SHARED_DATABASE` | `false` | `bool` | Turn on when a Laravel application uses the database at the same time. Password hashes are written as `$2y$` bcrypt, a valid sign-in rewrites a `$2b$` or Argon2id hash as `$2y$`, Magnetar stops upgrading bcrypt to Argon2id, and an unrouted database-queue job is stored on the queue `suprnova` instead of `default`. Accepts `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`; any other value fails boot. |
| `NOTIFICATIONS_MORPH_KEY` | `int` | `String` | The type `CreateNotificationsTable` gives `notifications.notifiable_id`: `int` for Laravel's `morphs`, `uuid` for `uuidMorphs`, `ulid` for `ulidMorphs`. Any other value fails the migration. |
| `RBAC_MODEL_KEY` | `int` | `String` | The type the RBAC migrations give `model_has_roles.model_id` and `model_has_permissions.model_id`: `int`, `uuid` or `ulid`. Any other value fails the migration. |
| `FEATURES_USER_SCOPE` | `App\Models\User` | `String` | What a user's flags are stored under in Pennant's `features.scope`, before `\|<id>`: the class or morph alias of the user model in the Laravel application. |

## Session

Cookie attributes and lifetime for the session subsystem. Note that
`SESSION_SECURE` defaults to **`true`** - production-safe by default;
flip it off only for local HTTP development.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SESSION_LIFETIME` | `120` (minutes) | `u64` | Session lifetime in minutes. Parsed via `env_optional`; falls back silently if unparseable. |
| `SESSION_TOUCH_INTERVAL` | `300` (seconds) | `u64` | Minimum sliding-expiry persistence cadence. Runtime enforcement caps it at half the session lifetime. |
| `SESSION_GC_INTERVAL` | `3600` (seconds) | `u64` | Cadence for the supervised expired-session collector installed by `SessionMiddleware::install`. |
| `SESSION_COOKIE` | `"suprnova_session"` | `String` | Session cookie name. |
| `SESSION_PATH` | unset | `String` | Cookie `Path=` attribute. Unset, the session, remember-me and XSRF cookies take the public root of each request: `/` at the host root, `/billing` behind a trusted `X-Forwarded-Prefix: /billing`. See [Serving under a path prefix](deployment.md#serving-under-a-path-prefix). |
| `SESSION_DOMAIN` | unset | `String` | Cookie `Domain=` attribute. Leave unset for host-only cookies (the safer default for most apps). |
| `SESSION_SECURE` | `true` | `bool` | Cookie `Secure` attribute. Defaults to `true`; set to `false` only in local HTTP development. `cookie_http_only` is always `true` and is not env-configurable. |
| `SESSION_SAME_SITE` | `"Lax"` | `String` | `SameSite` attribute. Accepts `Strict`, `Lax`, `None` (case-insensitive). |
| `SESSION_COOKIE_PREFIX` | unset | `String` (`__Host-` / `__Secure-`) | Prefix applied to session and remember-me wire names. `Config::init` validates the value and its `SESSION_DOMAIN` / `SESSION_PATH` constraints at boot; invalid combinations fail before serving. |
| `SESSION_PARTITIONED` | `false` | `bool` | Emit the `Partitioned` / CHIPS cookie attribute for third-party-isolated cookies. |
| `SESSION_EXPIRE_ON_CLOSE` | `false` | `bool` | When true, drop `Max-Age` so the browser deletes the cookie on close (session-cookie semantics). |
| `SESSION_CONNECTION` | unset | `String` | Named DB connection for the session store. Unset means the default connection. |
| `REMEMBER_LIFETIME` | `43200` (30 days, in minutes) | `u64` | "Remember me" cookie/token lifetime in minutes. |

## Localization

The three `APP_*` variables the localization subsystem reads. Everything
else about it - the detection chain, the session key and cookie name it
consults, Unicode isolation marks - is code-level configuration on
`LocalizationConfig`, not env. See [Localization](localization.md).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `APP_LOCALE` | `"en"` | `String` (BCP-47) | Locale used when the detection chain (session → cookie → `Accept-Language`) finds nothing. Also the locale `suprnova generate-types` extracts message keys from for `lang-keys.ts`. A value that is not a valid BCP-47 identifier fails boot rather than silently defaulting. |
| `APP_FALLBACK_LOCALE` | `"en"` | `String` (BCP-47) | Locale consulted when a key is missing from the current locale's catalog. A key missing from both renders as the key itself plus a one-time `warn!`; `Lang::try_get` returns `Err` instead. Same strict parse as `APP_LOCALE`. |
| `APP_LOCALE_PARENTS` | none - empty map | `String` (comma-separated `child=parent` pairs, BCP-47 on each side) | Per-locale fallback parents consulted before `APP_FALLBACK_LOCALE`, e.g. `APP_LOCALE_PARENTS=pt-PT=pt-BR,en-AU=en-GB`. `Lang`'s fallback chain walks these transitively, and `FluentTranslator` flattens each locale's configured parent chain into its served catalog. A malformed pair, an invalid locale, a child named more than once, or a cycle (including a locale naming itself as its own parent) fails boot rather than degrading at request time. See [Fallback chains](localization.md#fallback-chains). |

Catalogs themselves are files, not env: `lang/<locale>/*.ftl` under
`APP_BASE_PATH`. A missing `lang/` directory is not an error - the app
boots with the framework's embedded English validation catalog. The starter
kits ship no translations or `lang/` directory, and their `.env` and
`.env.example` omit the localization block. Add these variables when your
application needs localization.

## Cache

| Var | Default | Type | Purpose |
|---|---|---|---|
| `CACHE_DRIVER` | `memory` | `String` (`memory`/`in-memory`/`inmemory`, `redis`) | Selects the bootstrap target. Memory keeps everything in-process; Redis runs on the `Redis` facade's connections below and fails boot if the cache connection cannot answer. Unknown values fail boot with a clear error. |
| `CACHE_PREFIX` | the slug of `APP_NAME`, then `-cache-` (`suprnova-cache-` without `APP_NAME`) | `String` | Key prefix for cache entries (collision-avoidance for shared Redis). On Redis it comes after the connection's `REDIS_PREFIX`. An empty value means no prefix. |
| `REDIS_CACHE_CONNECTION` | `cache` | `String` | The `Redis` facade connection the cache store's commands run on with `CACHE_DRIVER=redis`. The `cache` connection reads `REDIS_CACHE_DB`. |
| `REDIS_CACHE_LOCK_CONNECTION` | `default` | `String` | The `Redis` facade connection the cache store's locks run on. |
| `REDIS_CACHE_DB` | `1` | `u32` | The database of the `Redis` facade's `cache` connection, applied even when `REDIS_URL` names another. |
| `REDIS_URL` | `"redis://127.0.0.1:6379"` | `String` | The `Redis` facade's `default` and `cache` connections, the cache store's server with `CACHE_DRIVER=redis`. A `rediss://` URL connects over TLS. See [Redis](redis.md). |
| `REDIS_PREFIX` | the slug of `APP_NAME`, then `-database-` | `String` | The `Redis` facade connections' key prefix, which the cache store's keys start with too. An empty value means no prefix. See [Redis](redis.md#key-prefixes). |
| `CACHE_DEFAULT_TTL` | `3600` (seconds) | `u64` | Default TTL in seconds. `0` means "no expiration". Applied to `Cache::put`, `Cache::remember`, and `Cache::tags_put` called with `None`; `Cache::forever`, `Cache::remember_forever`, and `Cache::tags_forever` always bypass. |
| `CACHE_SWEEP_INTERVAL` | `60` (seconds) | `u64` | Seconds between sweeps of the in-memory cache, which remove every expired entry, including the ones nothing reads again. `0` turns the sweep off. Redis expires keys itself and ignores this. See [Cache](cache.md#in-memory-expiration). |

An upgraded deployment with `CACHE_DRIVER=redis` finds its cache empty: the
store used to read `REDIS_PREFIX`, `suprnova_cache:` by default, as its
cache prefix on the database `REDIS_URL` names, and now runs on the `cache`
connection's database under `REDIS_PREFIX` and `CACHE_PREFIX`. Set
`REDIS_CACHE_CONNECTION=default`, an empty `REDIS_PREFIX` and
`CACHE_PREFIX=suprnova_cache:` (or your old `REDIS_PREFIX`) to keep the old
keys. See [Cache](cache.md#upgrading-keeps-the-old-keys-only-if-you-ask).
| `REDIS_COMMAND_RETRIES` | `0` | `u32` | Extra retries for read-shaped Redis commands, on top of the one every read already gets. Applies to the cache, queue, and rate-limit drivers, and to the reads of the `Redis` facade. Writes never retry at any value. Budget it in seconds: a retry against a dropped connection waits for the reconnect, so it costs the driver's whole connect and response budget - up to 3 connect retries at most 500 ms apart, each capped at 2 s, plus a 5 s response timeout on the cache driver; up to 6 connect retries with an uncapped exponential delay, each capped at 1 s, plus a 500 ms response timeout on the queue and rate-limit drivers. The clamp of `10` bounds attempts, not seconds: at that setting one read makes 12 attempts. A timeout counts as transient too, so during a stall each wrapped read issues up to that many commands. An unparseable value falls back to `0`. |

## Queue

| Var | Default | Type | Purpose |
|---|---|---|---|
| `QUEUE_DRIVER` | `memory` | `String` (`memory`, `sync`, `null`, `redis`, `database`, `sqs`, `failover`) | Active queue backend. `sync` runs each job inline when it is pushed, with no worker and no retry. `null` accepts every job and runs none. An unknown value is a boot error in production, where an in-memory queue would lose every job at the next restart. Elsewhere it logs a `warn!` that lists the accepted names and falls back to memory. `failover` wraps an ordered list of the others - see `QUEUE_FAILOVER_CONNECTIONS`. |
| `QUEUE_CONNECTIONS` | unset | `String` (comma-separated, e.g. `redis,database`) | Registers one named connection per entry, next to the default connection. Each connection is named for its driver and reads that driver's own variables, exactly as it would if it were `QUEUE_DRIVER`. An entry accepts the same names as `QUEUE_DRIVER`. An unknown name is a boot error in every environment. An entry that names the driver `QUEUE_DRIVER` selects is a second name for the default connection. Any other entry over a Redis stream or a jobs table that another connection already uses is refused at boot, because one queue has one connection. A job, a route or a push selects a connection by name - see [Queues](queues.md). |
| `QUEUE_AFTER_COMMIT` | `false` | `bool` (`true` or `1` turns it on; anything else leaves it off) | When on, every push made inside `DB::transaction` waits for the commit, whatever the job declares, as the `after_commit` option of a Laravel queue connection does. A rollback discards the push. It applies to jobs, queued mail and queued notifications. Read at each push, not once at boot. |
| `QUEUE_PAUSABLE` | `true` | `bool` (`false` or `0` turns it off) | Whether workers and the `queue:pause` command honour pause signals. `queue:resume` never checks it, so an existing pause can always be cleared. |
| `QUEUE_FAILOVER_CONNECTIONS` | - | `String` (comma-separated, e.g. `redis,database`) | Priority-ordered connection list for `QUEUE_DRIVER=failover`. Required when that driver is selected; a missing or blank value is a boot error, as is an entry naming `failover` (no nesting) or a driver that doesn't exist. Each entry reads its own driver's variables. Only pushes fall through the list; every read and every acknowledgement goes to the first connection, so each fallback needs its own worker. |
| `QUEUE_REDIS_URL` | `"redis://127.0.0.1:6379"` | `String` | Redis URL (required-by-driver when `QUEUE_DRIVER=redis`). |
| `QUEUE_REDIS_STREAM` | `"suprnova-queue"` | `String` | Redis Stream key used for fan-out. |
| `QUEUE_REDIS_GROUP` | `"default"` | `String` | Consumer-group name. |
| `QUEUE_REDIS_CONSUMER` | `suprnova-<uuid>` (a fresh UUID for each process) | `String` | Consumer name within the group. Set it per worker to keep the name stable across restarts. |
| `QUEUE_VISIBILITY_TIMEOUT_SECS` | `60` | `u64` | How long a claimed job stays invisible before another consumer can reclaim it. Match this to your slowest job. |
| `SQS_PREFIX` | unset | `String` | The URL the SQS queues are under, `https://sqs.<region>.amazonaws.com/<account id>`. Required when `QUEUE_DRIVER=sqs` and `SQS_QUEUE` is a name rather than a URL; boot fails without it. |
| `SQS_QUEUE` | `"default"` | `String` | The SQS queue a job that names none goes to, and the one a worker with no `--queue` receives from. A name, or the URL of the queue. You can use a standard queue or a FIFO queue ending in `.fifo`. |
| `SQS_SUFFIX` | unset | `String` | Appended to every SQS queue name that does not already end with it, as in `emails-production`. |
| `SQS_ENDPOINT` | `https://sqs.<region>.amazonaws.com` (`amazonaws.com.cn` for a `cn-` region) | `String` | The endpoint requests go to: an SQS-compatible service that is not AWS, such as LocalStack or ElasticMQ, or a VPC endpoint. A value that is not an `http` or `https` URL fails boot. |
| `SQS_WAIT_TIME_SECONDS` | `1` | `u64` (0 to 20) | How long each receive of the `sqs` driver waits for a message. A longer wait means fewer billed requests from an idle worker; `0` sends short polls. Outside 0 to 20 fails boot. |
| `AWS_DEFAULT_REGION`, `AWS_REGION` | unset | `String` | The region of the `sqs` queue driver, read in this order. With neither set, `QUEUE_DRIVER=sqs` fails boot. |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | unset | `String` | The keys the `sqs` queue driver signs with. Set both or neither: one without the other fails boot. With neither, the driver uses the default credential chain of AWS. |
| `SQS_OVERFLOW_ENABLED` | `false` | `bool` (`true` or `1`) | Store an SQS job of 1 MiB or more outside SQS and send SQS a pointer to it. Without it such a push fails. |
| `SQS_OVERFLOW_STORE` | unset | `String` | You use this named cache store for overflow when set. Register it with `Cache::register_store`; a missing store fails boot. You otherwise use the disk. |
| `SQS_OVERFLOW_DISK` | the default disk | `String` | You use this disk when `SQS_OVERFLOW_STORE` is unset. A disk that is not registered fails boot. |
| `SQS_OVERFLOW_ALWAYS` | `false` | `bool` (`true` or `1`) | Store every SQS job in the selected cache store or disk, whatever its size. |
| `SQS_OVERFLOW_DELETE_AFTER_PROCESSING` | `true` | `bool` (`false` or `0` turns it off) | Delete a job's overflow payload when the job is acknowledged. |
| `SQS_OVERFLOW_FLUSH_ON_CLEAR` | `false` | `bool` (`true` or `1`) | Delete only the cleared queue's overflow payloads when you call `Queue::clear`. |
| `QUEUE_DB_TABLE` | `"jobs"` | `String` | Table name for the database driver. Validated as a SQL identifier - a malformed value fails at boot, not at SQL composition time. Required-by-driver when `QUEUE_DRIVER=database`; the driver also requires `DB::init()` to have run first. |
| `QUEUE_FAILED_DB_TABLE` | `"failed_jobs"` | `String` | Table the dead-letter store writes to. Bound automatically when `QUEUE_DRIVER=database` - the failed-job commands (`queue:failed`, `queue:retry`, `queue:forget`, `queue:flush`, `queue:prune-failed`) read it and `Queue::retry_failed` needs it, so the table is part of that driver's contract. The commands read no variable of their own: they boot the application as `queue:work` does and use the store that boot bound. With no store bound, they exit non-zero and say so. Not used by `memory` (ephemeral by construction) or `redis` (no table to write to). Unlike `QUEUE_DB_TABLE` a malformed identifier here does **not** fail boot: it logs at `error!` and leaves no store bound, so dead-lettered jobs are logged in full rather than persisted. Recoverable by hand, but not by the failed-job commands. |

## Schedule

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SCHEDULE_ALLOW_MEMORY_LOCK_IN_PRODUCTION` | unset | `bool`-ish | Acknowledges that a task marked `on_one_server()` is electing a leader through a **per-process** cache. That election is only as shared as the cache behind it, so in production `CACHE_DRIVER=memory` plus a single-server task is a hard boot failure naming the offending tasks, rather than a silent downgrade to "every replica runs it". Set this only where the deployment genuinely runs one scheduler; otherwise set `CACHE_DRIVER=redis`. See [Scheduling](scheduling.md). |

## Workflow

The `#[workflow]` long-running stateful worker. All values are clamped
to safe minimums rather than honoured blindly - a `WORKFLOW_CONCURRENCY=0`
would park the worker semaphore forever, so the framework warns and
clamps instead of accepting an obviously-broken config.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `WORKFLOW_CONCURRENCY` | `4` | `usize` | Maximum concurrent workflow executions per worker process. Clamped to `>= 1`. |
| `WORKFLOW_POLL_INTERVAL_MS` | `1000` (ms) | `u64` | How often the worker polls for newly-due workflows. |
| `WORKFLOW_LOCK_TIMEOUT_SECS` | `30` (seconds) | `u64` | Reclaim timeout for a claimed workflow row whose worker has died. Clamped to `>= 2`; above 253402300799 (about 8,000 years) the worker refuses to start, because the lease would end past the dates the clock can hold. |
| `WORKFLOW_MAX_ATTEMPTS` | `3` | `i32` | Max attempts per workflow run before it is marked failed. Clamped to `>= 1`. |
| `WORKFLOW_RETRY_BACKOFF_SECS` | `5` | `i64` | Linear backoff per attempt. Clamped to `>= 0` - negative backoff would schedule retries in the past and produce a tight-loop reclaim. When it times `WORKFLOW_MAX_ATTEMPTS` exceeds 253402300799 seconds, the worker refuses to start. |

## Mail

`MAIL_DRIVER` defaults to **`log`** - outgoing mail prints to the
configured tracing subscriber rather than reaching the network. Flip
to `memory` in tests, `file` for `.eml` previews you can open in a
mail client, and `smtp`/`ses`/etc. in production. The
provider-specific keys/tokens are required only when that driver is
selected; an unknown driver value logs a `warn!` and falls back to
`log`.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_DRIVER` | `"log"` | `String` (`log`, `memory`, `file`, `smtp`, `ses`, `sendgrid`, `mailgun`, `postmark`, `resend`) | Selects the bootstrap target. |
| `MAIL_FROM` | none - required by auth-flow facades | `String` | Default from-address for auth-flow facades (`EmailVerification`, `PasswordReset`, `TwoFactor`). Required for those paths; absent it errors at the call site rather than silently falling back to a placeholder that would break DMARC/SPF. |
| `MAIL_FROM_NAME` | unset | `String` | Optional display name for the auth-flow `From` (since **0.5.9**). When set, the header renders `Name <MAIL_FROM>`; `MAIL_FROM` stays a bare address. Read at send time, so it applies to queued auth-flow mail too. |

### File (`MAIL_DRIVER=file`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_FILE_PATH` | `storage_path("mail")` | `String` | Directory one RFC 5322 `.eml` file is written to per send. Never pruned. Absolute paths are used as given; relative paths anchor at the application base directory (see `APP_BASE_PATH`). |

### SMTP (`MAIL_DRIVER=smtp`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_SMTP_HOST` | `"127.0.0.1"` | `String` | SMTP host. |
| `MAIL_SMTP_PORT` | `587` | `u16` | SMTP port. |
| `MAIL_SMTP_USER` | unset | `String` | SMTP username. Both `MAIL_SMTP_USER` **and** `MAIL_SMTP_PASS` must be set for an encrypted transport; with neither, the connection defaults to the unencrypted local-catcher mode. Setting exactly one warns at boot. |
| `MAIL_SMTP_PASS` | unset | `String` | SMTP password. See `MAIL_SMTP_USER` for the partial-credentials behaviour. |
| `MAIL_SMTP_ENCRYPTION` | derived | `starttls` \| `tls` \| `none` | How the connection is encrypted. Unset derives from the credentials: `starttls` when both are set, `none` when neither is. `tls` selects implicit TLS (port 465). `ssl` and `null` are accepted as Laravel-compatible aliases. An unrecognised value fails boot in **every** environment - a typo must not degrade to cleartext. |
| `MAIL_ALLOW_INSECURE_SMTP_IN_PRODUCTION` | unset | `bool`-ish | Production refuses to boot on an unencrypted SMTP connection. Set to `1`/`true`/`yes`/`on` to acknowledge cleartext - defensible only when the relay is reachable solely over a private network. |

### Postmark (`MAIL_DRIVER=postmark`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_POSTMARK_TOKEN` | required-by-driver | `String` | Postmark server token. |
| `MAIL_POSTMARK_ENDPOINT` | Postmark default | `String` | Override the API endpoint (regional or mock server). |

### Amazon SES (`MAIL_DRIVER=ses`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_SES_ACCESS_KEY` | required-by-driver | `String` | AWS access key. |
| `MAIL_SES_SECRET_KEY` | required-by-driver | `String` | AWS secret key. |
| `MAIL_SES_REGION` | `"us-east-1"` | `String` | AWS region. |
| `MAIL_SES_ENDPOINT` | AWS default for the region | `String` | Override the SES endpoint (regional or mock server). |

### SendGrid (`MAIL_DRIVER=sendgrid`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_SENDGRID_API_KEY` | required-by-driver | `String` | SendGrid API key. |
| `MAIL_SENDGRID_ENDPOINT` | SendGrid default | `String` | Override the API endpoint. |

### Mailgun (`MAIL_DRIVER=mailgun`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_MAILGUN_API_KEY` | required-by-driver | `String` | Mailgun API key. |
| `MAIL_MAILGUN_DOMAIN` | required-by-driver | `String` | Mailgun sending domain. |
| `MAIL_MAILGUN_ENDPOINT` | Mailgun default | `String` | Override the API endpoint (e.g. EU vs US). |

### Resend (`MAIL_DRIVER=resend`)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAIL_RESEND_API_KEY` | required-by-driver | `String` | Resend API key. |
| `MAIL_RESEND_ENDPOINT` | Resend default | `String` | Override the API endpoint. |

## Web Push

| Var | Default | Type | Purpose |
|---|---|---|---|
| `WEB_PUSH_ENDPOINT_ORIGINS` | unset (the client's own policy) | `String` (comma-separated origins, `https://host` or `https://host:port`) | The push services `WebPushChannel` may send to, such as `https://updates.push.services.mozilla.com,https://fcm.googleapis.com,https://web.push.apple.com,https://*.notify.windows.com`. When it names one or more origins, every send of the channel goes under `EndpointPolicy::Allowlist`, which runs the strict checks and refuses an endpoint at any other origin before its host name is looked up. A host may start with the label `*.`, which matches exactly one label. Spaces around an entry and empty entries are ignored, and a value that names no origin keeps the client's own policy. An entry that is not an origin, or a value that is not UTF-8, makes `WebPushChannel::new` return an error that names the variable. See [Endpoint allowlist](web-push.md#endpoint-allowlist). |

## Rate Limiting

| Var | Default | Type | Purpose |
|---|---|---|---|
| `RATE_LIMIT_DRIVER` | `memory` | `String` (`memory`, `redis`) | Selects the rate-limiter backend. Outside production an unknown value logs a `warn!` and falls back to memory; **in production, memory - including via an unknown value - fails boot** unless `RATE_LIMIT_ALLOW_MEMORY_IN_PRODUCTION` is set. |
| `RATE_LIMIT_ALLOW_MEMORY_IN_PRODUCTION` | unset | `bool`-ish | Acknowledges per-process rate-limit buckets in production. Only accurate if you run exactly one process: behind N replicas every quota is effectively N× and resets on each deploy. |
| `RATE_LIMIT_REDIS_URL` | `"redis://127.0.0.1:6379"` | `String` | Redis URL (required-by-driver when `RATE_LIMIT_DRIVER=redis`). |
| `RATE_LIMIT_PREFIX` | `"suprnova:"` | `String` | Key prefix in Redis. |

## Filesystem

You set `S3_BUCKET` or `AWS_BUCKET` to register an S3 disk named `s3` at boot,
beside the queue, the rate limiter and the mail transport. The variables work for
AWS S3 and for S3-compatible services (MinIO, RustFS, R2, B2). With both bucket names
unset, you register no environment disk. A disk that your `bootstrap()`
registered under the name `s3` is kept as it is, and the variables are not read then.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `S3_BUCKET`, `AWS_BUCKET` | unset (no disk) | `String` | The bucket. Setting it registers the `s3` disk. |
| `S3_REGION` | none - see `AWS_DEFAULT_REGION` | `String` | The region. The driver needs one, and the server does not boot when none is set. A service that is not AWS takes any name, such as `us-east-1` or `auto`. |
| `AWS_DEFAULT_REGION`, `AWS_REGION` | unset | `String` | Read, in this order, when `S3_REGION` is not set. |
| `S3_ENDPOINT`, `AWS_ENDPOINT` | unset (AWS) | `String` | The endpoint of a service that is not AWS. |
| `S3_ACCESS_KEY`, `S3_SECRET_KEY` | unset | `String` | The access key and the secret. Set both or neither. One without the other fails boot. You use `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for each missing S3 value. With neither effective key, you use the profile or instance role. |
| `S3_ROOT` | unset | `String` | A prefix inside the bucket that every path is under. |
| `FILESYSTEM_DISK` | `local` | `String` | The name of the default disk that `Storage::default_disk()` returns. `Storage::set_default_disk` in code wins over it. A name with no registered disk fails boot. |
| `S3_PUBLIC_URL`, `AWS_URL` | unset | `String` | The public base URL of the `s3` disk, which `Storage::url("s3", path)` joins with the path. It is an absolute `http` or `https` URL (`https://cdn.example.com/files`) or a path of your own host (`/storage`). A value with a user or a password, a query or a fragment, a backslash, or a `.` or `..` segment fails boot. With it unset, `Storage::url` on the `s3` disk returns an error. |
| `S3_USE_PATH_STYLE_ENDPOINT`, `AWS_USE_PATH_STYLE_ENDPOINT` | unset (path-style URLs) | `bool` (`true`/`false`/`1`/`0`) | You select endpoint/bucket paths with `true` or bucket hostnames with `false`. An invalid value fails boot. Each S3 name wins over its AWS alias. |

Blank values count as unset. No error repeats the value of a variable, except
the disk name `FILESYSTEM_DISK` gives.

`FILESYSTEM_DISK` names the default disk that `Storage::default_disk()` returns;
`Storage::set_default_disk` in code wins over it. With neither setting, you
use the registered `local` disk, or get an error naming `local` and
`FILESYSTEM_DISK`. When it names a disk that is
not registered once the bootstrap has run, boot fails. The console binary boots
no driver of the environment. A command that uses the `s3` disk calls
`suprnova::filesystem::bootstrap_from_env()` at the end of its own bootstrap,
after it registers its disks, because that call checks the default disk too. To
register the same configuration under a name of your own, use
`S3Config::from_env()`. See [Filesystem](filesystem.md).

## Search

See [Search](search.md) for models, settings, engines, indexing, and the
baseline. Search configuration is strict: its boolean fields accept Rust's
`true` or `false`, and malformed or zero positive limits fail with the variable
name. Registered typed configuration can override environment defaults. Local
inference requires the opt-in `search-fastembed` feature; its `ort` build script
downloads ONNX Runtime at compile time. The default build downloads nothing.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SEARCH_DRIVER` | `database` | `String` | Default engine: `database`, `qdrant`, `collection`, or `null`. Per-index registration can override it. |
| `SEARCH_EMBEDDER` | `none` | `String` | Dense provider: `none`, `http`, or `fastembed`. A positive semantic ratio without a provider fails. |
| `SEARCH_QUEUE` | `true` | `bool` | Queue indexing after commit. False runs deferred inline work; scoped model writes synchronize inline after commit regardless. |
| `SEARCH_QUEUE_CONNECTION` | unset | `Option<String>` | Registered queue connection for search jobs; unset uses the queue default. A supplied value must be nonempty. |
| `SEARCH_QUEUE_NAME` | unset | `Option<String>` | Queue name for search jobs; unset uses the queue default. A supplied value must be nonempty. |
| `SEARCH_CHUNK` | `500` | `usize` | Positive bulk import and removal chunk size. |
| `SEARCH_MEDIA_MAX_BYTES` | `33554432` | `usize` | Maximum bytes per declared media part. Positive and at most 33554432. Storage reads enforce the limit before inference. |
| `SEARCH_FFMPEG_BINARY` | `ffmpeg` | `String` | Binary for video frame decoding. Runs without a shell with a 30-second timeout. |
| `SEARCH_EMBED_PROFILE` | unset | `Option<String>` | Shipped local model profile. Use `embeddinggemma-2-media` for image, audio and video with the EmbeddingGemma 2 fp32 graphs. |
| `SEARCH_EXPANSION_TERMS` | `64` | `usize` | Positive alternative cap per query word, including the original. |
| `SEARCH_HITS_CAP` | `1000` | `usize` | Positive accessible-hit cap; supplies the default index setting and bounds endpoint pages. |
| `SEARCH_FUSION_DEPTH` | `200` | `usize` | Positive candidate depth per hybrid leg when code keeps the default setting. |
| `SEARCH_BM25_AVERAGE_LENGTH` | `256` | `usize` | Positive token-length normalization constant for Qdrant's built-in BM25 sparse provider. Reindex when you change it. |
| `SEARCH_TOMBSTONE_HOURS` | `24` | `u64` | Positive removal-fence retention against delayed indexing retries. Schedule pruning. |
| `SEARCH_ANALYTICS` | `false` | `bool` | Retain queries, session-bound impressions, and validated clicks. The analytics-enabled JSON endpoint requires session middleware. |
| `SEARCH_ANALYTICS_RETENTION_DAYS` | `90` | `u64` | Positive retention window for analytics, suggestions, and click validation; applied by `search:analytics-prune`. |
| `SEARCH_ANALYTICS_VIEWER` | `false` | `bool` | Retain authenticated viewer ids in query rows. Never records a guest identity there. |
| `SEARCH_MODEL_CACHE` | `storage/search/models` | `String` / `PathBuf` | Nonempty verified local model cache root, including manifests and reranker artifacts. |
| `SEARCH_EMBED_BASE_URL` | none - required for HTTP | `String` | OpenAI-compatible base URL; the provider appends `/embeddings`. HTTPS except explicit loopback hosts; no credentials, query, fragment, or redirects. |
| `SEARCH_EMBED_MODEL` | fastembed: `hf:onnx-community/embeddinggemma-2-ONNX`; HTTP: required | `String` | Dense model identity. Local inference accepts a named model, `hf:owner/repository[@revision]`, or `path:directory`. |
| `SEARCH_EMBED_API_KEY` | unset | `Option<String>` | Optional HTTP bearer key, sent only to the pinned embedding destination. |
| `SEARCH_EMBED_DIMENSIONS` | native profile; unknown HTTP model probes once | `Option<usize>` | Positive requested dimensions; local reductions must be supported by the profile. Vectors are validated and normalized after truncation. |
| `SEARCH_EMBED_BATCH` | `64` | `usize` | Positive HTTP/local inference batch bound and local reranker batch size. A local embedding model counts it in 512-token texts; a longer text fills the batch by the square of its length. Dynamic quantization uses singleton inference. |
| `SEARCH_EMBED_TIMEOUT_SECS` | `30` | `u64` | Positive HTTP request deadline including body receipt. |
| `SEARCH_EMBED_MAX_RESPONSE_BYTES` | `16777216` | `usize` | Positive streamed HTTP response cap, 16 MiB by default. |
| `SEARCH_EMBED_RETRIES` | `3` | `u32` | Additional HTTP attempts for 429 or 5xx only; at most 16. |
| `SEARCH_EMBED_QUERY_PREFIX` | shipped profile; unknown HTTP model: empty | `Option<String>` | Query preparation for unknown HTTP models. Known models keep their profile's prefix. |
| `SEARCH_EMBED_DOCUMENT_TEMPLATE` | shipped profile; unknown HTTP model: `{text}` | `Option<String>` | Document preparation for unknown HTTP models; placeholders are `{title}` and `{text}`. Known models keep their profile. |
| `SEARCH_EMBED_MAX_TOKENS` | shipped or published hosted profile; other HTTP models: the service's model list, else `8192` | `Option<usize>` | HTTP only: the model's context in tokens. Wins over the profile, the service's list (read on the first embedding) and the 8192 default. |
| `SEARCH_EMBED_TOKENIZER` | unset | `Option<PathBuf>` | HTTP only: path to the model's `tokenizer.json`. The provider cuts each prepared input after the last token that fits the model's context; unset, it cuts to the context length minus four in UTF-8 bytes. |
| `SEARCH_EMBED_PRECISION` | `fp32` | `String` | Local graph variant: `fp32`, `int8`, or `q4`. fp16 is refused. |
| `SEARCH_EMBED_SPARSE_MODEL` | unset | `Option<String>` | Optional fastembed sparse head, including BGE-M3. Select its registered provider in the generation's `sparse_model`; Qdrant otherwise uses built-in `bm25`. |
| `SEARCH_VECTOR_STORE` | index name | `String` | Registered Vector store for the database engine's semantic leg. |
| `SEARCH_VOCABULARY_REFRESH` | `1000` | `i64` | Positive Postgres write interval for refreshing the native `ts_stat` vocabulary; builds also refresh it. |
| `SEARCH_QDRANT_TIMEOUT_SECS` | `10` | `u64` | Positive per-call Qdrant search timeout. |
| `QDRANT_URL` | none - required for Qdrant | `String` | Qdrant gRPC URL, normally port 6334. Search boot and `QdrantSearchEngine::from_env` read it; `QdrantVectorDriver::from_env` also uses it. |
| `QDRANT_API_KEY` | unset | `Option<String>` | Qdrant Cloud or self-hosted API key, shared by search and vector constructors. |
| `SEARCH_BASELINE_MEILISEARCH_URL` | none - required for calibration | `String` | Meilisearch HTTP service used by `search:baseline calibrate`. |
| `SEARCH_BASELINE_MEILISEARCH_KEY` | none - required for calibration | `String` | Meilisearch calibration key. |
| `SEARCH_BASELINE_TYPESENSE_URL` | none - required for calibration | `String` | Typesense HTTP service used by `search:baseline calibrate`. |
| `SEARCH_BASELINE_TYPESENSE_KEY` | none - required for calibration | `String` | Typesense calibration key. |
| `SEARCH_BASELINE_TOLERANCE` | `0.05` | `f64` | Finite absolute lexical nDCG@10 allowance below the stronger rival, from 0 to 1, written during calibration. |
| `SEARCH_BASELINE_ALLOW_UNCALIBRATED` | unset | `String` | Exactly `1` permits provisional uncalibrated measurements; other values keep the uncalibrated gate closed. |
| `PG_TEST_URL` | none - required for Postgres baseline/tests | `String` | Disposable Postgres database for search service tests and `search:baseline run --engine postgres`. |
| `MYSQL_TEST_URL` | none - required for MySQL/MariaDB baseline/tests | `String` | Disposable MySQL or MariaDB database for search service tests and the `mysql` baseline. |
| `QDRANT_TEST_URL` | none - required for Qdrant tests | `String` | Qdrant gRPC service for ignored search tests. The console uses `QDRANT_URL` instead. |

The last three rows configure the repository's tests and baseline tools, not
application search connections. Calibration writes p95 budgets as two times
the slower rival's measured p95 and re-derives them on load. No environment
variable overrides that budget. Model downloads at runtime are separate from
the ONNX Runtime download during a feature-enabled build.

## Recommendations

See [Recommendations](recommendations.md) for event classes, runs, provenance,
and application-owned retention. Numeric bounds must be positive, fit the
supported signed range, and fit the clock/calendar where applicable.
Booleans accept `true` or `false`; invalid values fail with the variable name.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `RECOMMEND_ENABLED` | `false` | `bool` | Forward validated search impressions and clicks automatically. Does not disable explicit event recording or generation. |
| `RECOMMEND_HISTORY` | `500` | `usize` | Newest positive and negative events per actor combined; seen impressions are aggregated separately. |
| `RECOMMEND_PEERS` | `200` | `usize` | Maximum sampled peers, ordered by most recent shared positive activity. |
| `RECOMMEND_MIN_PEERS` | `3` | `usize` | Distinct peers a collaborative candidate needs, so no suggestion's peer count points at one person. Positive. |
| `RECOMMEND_POPULARITY_WINDOW` | `30` | `u32` | UTC days of positive events contributing popularity. |
| `RECOMMEND_LOCK_TTL_SECS` | `3600` | `u64` | Renewable generation cache-lock lifetime in seconds. |
| `RECOMMEND_EVENT_TYPES` | `{}` | JSON object | Map from event name to `{"class":"positive\|negative\|seen","score":N}`. Base scores are bounded to -1000000 through 1000000; weight adds integer basis points divided by 20. |
| `RECOMMEND_ENGINE` | `starter` | `String` | `starter`, or `graph` for the knowledge-graph engine, which falls back to the starter's rows when its evidence is thin. |
| `RECOMMEND_GRAPH_STORE` | `database` | `String` | `database` (the application database) or `memgraph` (needs the `graph-memgraph` feature). |
| `RECOMMEND_GRAPH_URL` | unset | `Option<String>` | Memgraph Bolt address, `bolt://` or `bolt+s://`, without credentials. |
| `RECOMMEND_GRAPH_USERNAME` | unset | `String` | Memgraph user, read only when the store connects. |
| `RECOMMEND_GRAPH_PASSWORD` | unset | `String` | Memgraph password, read only when the store connects; never logged or stored in configuration. |
| `RECOMMEND_GRAPH_DEPTH` | `2` | `usize` | Most hops in a graph path. 1 to 4. |
| `RECOMMEND_GRAPH_FANOUT` | `50` | `usize` | Most edges followed out of one node per hop, and the most recent positives per actor that pair into shared engagement. Positive. |
| `RECOMMEND_GRAPH_MAX_NODES` | `2000` | `usize` | Most nodes one graph walk reaches. Positive. |
| `RECOMMEND_PUBLIC_EVENT_TYPES` | unset | comma list | Event types other viewers may see; only these become per-actor graph facts and social signals. |
| `RECOMMEND_SOCIAL_MIN_ACTORS` | `3` | `usize` | Followed actors who must agree before a target gains social proximity. Positive. |
| `RECOMMEND_ACTOR_INDEX` | unset | `Option<String>` | Search index whose documents are users, keyed by user id; follows of its documents name followed users. |
| `RECOMMEND_GRAPH_SURFACES` | `{}` | JSON object | Per-surface `affinity`, `semantic`, `social`, `freshness`, `feedback`, `trust` and `threshold` in basis points (0 to 10000) and `per_value`, `per_node`, `per_band` caps (positive). |

The engine never prunes the event stream automatically. Your retention policy
uses `recommendations:prune --older-than <days>` explicitly.

## Vector search

The four external vector drivers read their connection from the environment when you
call their `from_env()` constructor. You choose the vector driver in Rust and
register it in `bootstrap()`. Qdrant search also reads its shared variables
during search bootstrap. See [Vector](vector.md).
The shared Qdrant variables are listed under [Search](#search).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MARIADB_URL` | none - see `DATABASE_URL` | `String` | The URL of the MariaDB that holds the vectors. `MariaDbVectorDriver::from_env()` reads it first. |
| `PGVECTOR_URL` | none - see `DATABASE_URL` | `String` | The Postgres URL that holds the vectors. `PgVectorDriver::from_env()` reads it first. |
| `DATABASE_URL` | none | `String` | Fallback when the driver's own URL is unset or blank. MariaDB accepts schemes `mariadb` or `mysql`; pgvector accepts `postgres` or `postgresql`. A URL of another engine is not taken. |
| `PINECONE_API_KEY` | none - required | `String` | The Pinecone API key. `PineconeVectorDriver::from_env()` fails when it is unset or blank. |
| `PINECONE_CONTROLLER_HOST` | `https://api.pinecone.io` | `String` | The base URL of the Pinecone control plane. |
| `PINECONE_API_VERSION` | `2025-04` | `String` | The value of the `X-Pinecone-Api-Version` header. |

A missing variable is named in the error at boot, and the error never shows a
URL, because a URL carries the password.

## Images

Image driver selection, the decode limits that bound hostile input, and
orientation on decode.
Out-of-range limits clamp with a `warn!` rather than failing boot: a
limit of zero would reject every image in the application. An unknown
`IMAGE_DRIVER` fails at first use, naming the valid values.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `IMAGE_DRIVER` | `oxideav` | `String` (`oxideav`, `magick`) | Selects the image backend. `oxideav` is pure Rust with no host dependency; `magick` shells out to a host-installed ImageMagick 7 for wider input support. Case-insensitive. |
| `IMAGE_MAX_DIMENSION` | `16384` | `u32` | Cap on the width and height of a decoded image, checked against the input's own header before anything is allocated. Also caps resize targets. Minimum `1`. |
| `IMAGE_MAX_ALLOC_BYTES` | `1073741824` (1 GiB) | `u64` | Cap on the memory one decode may allocate. Every driver checks the decoded RGBA footprint (`width * height * 4`) against it; the default `oxideav` driver also estimates the whole decode from the image's headers and refuses an image whose estimate is over it. Also caps the size of the source file itself, whether it arrives from a path, a disk, or `Image::from_stream` (which checks while collecting). Minimum `4`. |
| `IMAGE_MAGICK_BINARY` | `magick` | `String` | Binary the `magick` driver invokes. ImageMagick 7 only; the ImageMagick 6 `convert` name is not accepted. A missing binary is a clear error at first use. |
| `IMAGE_MAGICK_TIMEOUT_SECS` | `30` | `u32` | Wall-clock ceiling on a single ImageMagick invocation. It is both ImageMagick's own `-limit time` argument and the Rust-side deadline that kills the child's whole process group two seconds later, because `-limit time` is enforced by a monitor that a child wedged inside a delegate never engages. Bounds a stalled delegate that would otherwise hold a blocking worker for the life of the process. `magick` driver only. Minimum `1`. |
| `IMAGE_MAGICK_AUTODETECT` | `false` | `bool` | Let ImageMagick choose the coder for input the framework cannot name. Off, the `magick` driver names the coder for every format it recognises (`png:-`, `heic:-`, `tiff:-`) and refuses other bytes before ImageMagick starts. `true`, `1`, `yes` or `on` turn it on: such bytes reach ImageMagick on a bare `-`, an MVG or MSL script included, under the framework's ImageMagick policy, which denies the script, network, and Ghostscript coders. That policy is the last one ImageMagick reads, so a host grant of one of those coders doesn't reopen it. The driver checks that order once per process, and a check that fails refuses every run, with autodetection on or off, until the host is fixed and the process restarts. Any other value keeps it off with a `warn!`. `magick` driver only. [Images](images.md#image_drivermagick) |
| `MAGICK_CONFIGURE_PATH` | unset | path list | ImageMagick's own list of configuration directories. The `magick` driver starts ImageMagick with this value, unchanged, between two copies of the directory that holds the framework's `policy.xml`, and with `HOME` naming the framework's policy directory, so the framework's policy is the last one ImageMagick reads. A policy of your own here, or in `$XDG_CONFIG_HOME/ImageMagick`, still applies its denials and can't grant back what the framework denies. A `policy.xml` in the service account's own `~/.config/ImageMagick` doesn't apply to the driver's runs. The driver checks the order once per process; a check that fails refuses every run, with or without `IMAGE_MAGICK_AUTODETECT`, until the host is fixed and the process restarts. `magick` driver only. [Policy](images.md#policy) |
| `IMAGE_AUTO_ORIENT` | `true` | `bool` | Apply the source's EXIF `Orientation` tag as an image decodes, under both drivers. `false`, `0`, `no` or `off` turn it off: the pixels keep the sensor's orientation, the output keeps the tag, and `Image::orient()` applies it where the pipeline says. Any other value keeps the default with a `warn!`. [Images](images.md#orientation) |

See [Images](images.md) for the two-tier limit enforcement and how to
choose between the drivers.

## Hashing

Password-hashing driver and per-algorithm parameters. Invalid values
return a `FrameworkError::param` at first hash, surfacing
misconfiguration immediately instead of silently defaulting.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `HASH_DRIVER` | `bcrypt` | `String` (`bcrypt`, `argon`/`argon2i`, `argon2id`) | Active hashing algorithm. Case-insensitive. |
| `HASH_ROUNDS` | `12` | `u32` | Bcrypt cost (range `4..=31`). Out-of-range values fail with a clear error. |
| `HASH_MEMORY` | `65536` (64 MiB, KiB units) | `u32` | Argon2 memory in KiB. Minimum `8`. Argon-only. |
| `HASH_TIME` | `4` | `u32` | Argon2 time / iterations. Minimum `1`. Argon-only. |
| `ARGON_TIME` | unset | `u32` | Read when `HASH_TIME` is unset: the Argon2 time cost in iterations, minimum `1`; `HASH_TIME` wins when both are set. Argon-only. |
| `PASSWORD_RESET_TIMEBOX_MS` | `200` | `u64` | The least time a password reset link request takes, whatever its answer, so a refused address is not told apart from an accepted one by timing. A value that is not a whole number fails at boot. |
| `HASH_THREADS` | `1` | `u32` | Argon2 parallelism (matches OWASP / libsodium). Minimum `1`. Argon-only. |
| `HASH_VERIFY` | `false` | `bool` | When true, `verify()` rejects hashes from a different algorithm than `HASH_DRIVER` (returns `Ok(false)`). Default `false` so legacy bcrypt hashes still verify after a driver flip until they're rotated. |
| `HASH_MAX_CONCURRENCY` | the host's available parallelism | whole number, at least `1` | How many password hashes run at once in the process. `hash_async`, `verify_async` and Magnetar's sign-in hashing share the limit; work past it waits as a task holding no thread, so a burst of sign-ins holds at most the limit times one hash's memory. `0` or a value that is not a whole number fails with a clear error. A blank value is unset. |

## Validation

| Var | Default | Type | Purpose |
|---|---|---|---|
| `HIBP_TIMEOUT_SECS` | `30` (seconds) | `u64` | Request timeout for `Password::uncompromised()`'s Have I Been Pwned range check, read fresh each time a default `HibpVerifier` is constructed. A slow or unreachable HIBP still fails open - see [Validation](validation.md). |

## Auth Flows

Two-factor authentication uses `APP_NAME` (covered under Application)
as the TOTP issuer string - there is no dedicated `2FA_ISSUER` env
var. The issuer falls back to `"Suprnova"` when `APP_NAME` is unset.

## Agents

Agent auth reads its signing key from these variables when the application
does not pass one to `AgentAuth::signing_key`. With agent auth on and no key,
the server refuses to start, so a deploy without a `.env` file must set
`AGENT_AUTH_KEY_ID` and `AGENT_AUTH_PRIVATE_KEY` in the process environment.
The application binary's `agents:key` command prints a new pair. A key's line
breaks can be written as a literal `\n`, as an environment file writes them.
The OAuth server also needs `APP_URL` (see **Application**). See
[Agents](agents.md#keys-and-operations).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `AGENT_AUTH_KEY_ID` | none - required with agent auth on | `String` | The identifier (`kid`) of the key that signs identity assertions. |
| `AGENT_AUTH_PRIVATE_KEY` | none - required with agent auth on | `String` (P-256 private key, PEM) | The key that signs identity assertions. A value that is not a P-256 private key in PEM form fails boot. |
| `AGENT_AUTH_PREVIOUS_KEY_ID` | none | `String` | After a rotation, the identifier of the key that signed before. Set all three `AGENT_AUTH_PREVIOUS_*` variables or none; a partial set fails boot. |
| `AGENT_AUTH_PREVIOUS_PRIVATE_KEY` | none | `String` (P-256 private key, PEM) | After a rotation, the previous key, which still verifies the assertions it signed until they expire. |
| `AGENT_AUTH_PREVIOUS_ROTATED_AT` | none | RFC 3339 time | When the previous key stopped signing. |
| `WEBMCP_ORIGIN_TRIAL_TOKEN` | none | `String` (comma-separated base64 tokens) | WebMCP Origin Trial tokens, for example separate Chrome and Edge tokens. Every HTML response carries one `Origin-Trial` header with tokens joined by `, `; JSON, redirects and assets do not. Each token is checked as base64. A bad token fails boot, naming the variable and entry position, never its value. Tokens are trimmed and empty entries are skipped. An empty list is no token. See [Security Headers](security-headers.md#webmcp-and-permissions-policy). |

## Inertia / Frontend

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SUPRNOVA_FRONTEND` | `svelte` | `String` (`svelte`, `react`, `vue`) | Active frontend. Case-insensitive. Drives `Frontend::detect_from_env()`, the default Vite entry point, and the page-component extension search order at compile time. Unknown or unset values fall back to `svelte`. |

## Live

Every limit Live runs under is one of these keys. The server's configuration is
the only source: the bootstrap writes each value into the page, and the browser
runtime applies the value it reads there, never a smaller one of its own.
Values are plain whole numbers, with bytes written out (`16777216`, not
`16MiB`). `Config::init` reads every key at boot, so a value that is not a
whole number, or that breaks its rule, fails boot with the key, the value and
the rule in the message. `LiveConfig::builder()` sets the same limits in code;
see [Live](live.md#limits).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `LIVE_MAX_REQUEST_BYTES` | `16777216` (16 MiB) | `usize` (bytes, 1 to 1073741824) | One Live request body, the signed snapshot included. It must be at least `LIVE_MAX_RESPONSE_BYTES`, because a response's snapshot comes back in the next request. The browser checks each request against it before sending. |
| `LIVE_MAX_RESPONSE_BYTES` | `16777216` (16 MiB), or `LIVE_MAX_REQUEST_BYTES` when that is smaller | `usize` (bytes) | One Live response body: the island HTML as an escaped JSON string, the snapshot, events and effects. The browser reads the response under it. Set it above `LIVE_MAX_HTML_BYTES` when an island renders close to the HTML limit. |
| `LIVE_MAX_HTML_BYTES` | `16777216` (16 MiB), or `LIVE_MAX_RESPONSE_BYTES` when that is smaller | `usize` (bytes) | One island render's HTML, apart from the response around it. The server refuses a render over it, and the morph refuses an island over it. |
| `LIVE_MAX_JSON_DEPTH` | `32` | `usize` (levels, 1 to 64) | Container nesting in Live JSON. The parsers are recursive, so 64 is the stack ceiling. |
| `LIVE_MAX_JSON_ENTRIES` | `1000000` | `usize` (entries, 1 to 100000000) | Array elements plus object members in one request. A parsed entry costs memory beyond its bytes, so this bounds what a request of many tiny entries can grow into. |
| `LIVE_MAX_REQUEST_ITEMS` | `65536` | `usize` (items, 1 to 16777216) | Items in one request collection: model proposals, operations, action arguments. |
| `LIVE_MAX_RESPONSE_ITEMS` | `65536` | `usize` (items, 1 to 16777216) | Items in one response collection: validation entries, events, effects, extensions, child deliveries, and the assets, mounts and child components of one render. |
| `LIVE_MAX_CONTEXT_LIFETIME_MS` | `30000` | `u64` (ms, 1 to 300000) | How long one trusted request context stays valid. |
| `LIVE_REQUEST_TIMEOUT_MS` | `60000` | `u32` (ms, 1 to 2147483647) | How long the browser waits for one Live response, body included. A 16 MiB response over a 5 Mbit/s link takes about 27 seconds. |
| `LIVE_MAX_QUEUED_PER_ISLAND` | `8` | `u8` (1 to 64) | Requests one island queues. |
| `LIVE_MAX_PARALLEL_PER_ISLAND` | `1` | `u8` (1 to 8, at most the queue) | Requests one island runs at once. |
| `LIVE_MORPH_MAX_NODES` | `1000000` | `u32` (nodes, 1 to 1073741824) | Nodes in one rendered island the browser morphs. |
| `LIVE_MORPH_MAX_DEPTH` | `512` | `u32` (levels, 1 to 4096) | Element nesting in one rendered island. The morph walks the tree recursively, and browsers' HTML parsers stop nesting at 512. |
| `LIVE_MORPH_MAX_KEYS` | `1000000` | `u32` (keyed elements, 1 to 1073741824) | Keyed elements (`live:key`, `id`, nested islands) in one rendered island. |
| `LIVE_MORPH_MAX_ATTRIBUTES` | `10000000` | `u32` (attributes, 1 to 1073741824) | Attributes across one rendered island. |
| `LIVE_MORPH_MAX_ATTRIBUTES_PER_ELEMENT` | `4096`, or `LIVE_MORPH_MAX_ATTRIBUTES` when that is smaller | `u32` (attributes) | Attributes on one rendered element. The morph's cost for one element grows with the square of its attribute count. |
| `LIVE_MORPH_DEADLINE_MS` | `0` (no deadline) | `u32` (ms, 0 to 2147483647) | How long one morph may run before the browser abandons it. The morph runs synchronously, so a deadline can only stop work that already held the page and changed part of the island; set one only when a failed update is better than a long one. |
| `LIVE_ASYNC_MAX_PAYLOAD_BYTES` | `1048576` (1 MiB), or `LIVE_ASYNC_MAX_BUFFER_BYTES` when that is smaller | `usize` (bytes, 1 to 16777216) | One asynchronous event payload. Publishing a larger one fails with the limit named. |
| `LIVE_ASYNC_MAX_BUFFER_BYTES` | `16777216` (16 MiB) | `usize` (bytes, 1 to 1073741824) | What one open document's delivery queue, and one subscription's replay log, may hold in server memory while the browser catches up. It must be at least `LIVE_ASYNC_MAX_PAYLOAD_BYTES`. |
| `LIVE_ASYNC_MAX_QUEUED_EVENTS` | `4096` | `usize` (events, 1 to 65536) | Asynchronous events one open document holds before its islands apply them, on the server and in the browser. An event past it is refused with the limit named and the island re-renders fresh. |
| `LIVE_ASYNC_MAX_REPLAY_EVENTS` | `4096`, or `LIVE_ASYNC_MAX_QUEUED_EVENTS` when that is smaller | `usize` (events, 1 to the queued-event limit) | Events one reconnect replay carries, and events one subscription's replay log keeps. A replay is queued whole, so it fits inside `LIVE_ASYNC_MAX_QUEUED_EVENTS`. A longer gap re-renders the island fresh. |
| `LIVE_ASYNC_MAX_REPLAY_BYTES` | `4194304` (4 MiB), or `LIVE_ASYNC_MAX_PAYLOAD_BYTES` when that is larger | `usize` (bytes, the payload limit to 68719476736) | Memory one subscription's replay log may hold. The log keeps recent events so a reconnecting browser catches up without a fresh render; each entry is charged its payload tree and bookkeeping, not its encoded size. |
| `LIVE_ASYNC_REPLAY_BUDGET_BYTES` | `268435456` (256 MiB), or `LIVE_ASYNC_MAX_REPLAY_BYTES` when that is larger | `usize` (bytes, the replay limit to 68719476736) | Memory every replay log in the process may hold together. Past it, the oldest entries in any log are evicted first, and a browser that needed one re-renders fresh. Without it, replay memory grew with the number of sessions. |
| `LIVE_ASYNC_MAX_TRANSPORTS_PER_SESSION` | `64` | `usize` (transports, 1 to 4096) | Asynchronous transports (one per open tab) one session may hold. One past it is refused with a 409 and the key in the log. |
| `LIVE_ASYNC_MAX_TRANSPORTS` | `16384` | `usize` (transports, the per-session limit to 1048576) | Asynchronous transports the process may hold. Each is a long-lived connection, so keep it under the process's file-descriptor limit. |
| `LIVE_MAX_REDIRECT_BYTES` | `65536` (64 KiB), or `LIVE_MAX_RESPONSE_BYTES` when that is smaller | `usize` (bytes, 1 to 2097152, at most the response) | One redirect or reflected URL a Live response carries. 2 MiB is the longest URL a browser follows. |
| `LIVE_UPLOAD_CHUNK_BYTES` | `8388608` (8 MiB), or `LIVE_UPLOAD_MAX_FILE_BYTES` when that is smaller | `usize` (bytes, 1 to 67108864) | One upload chunk request. The server holds a chunk in memory while it checks and stores it. It must be at most the file size and large enough that a file of `LIVE_UPLOAD_MAX_FILE_BYTES` takes at most 99994 chunks. The browser sends chunks of this size unless `configureUploads` asks for smaller ones. |
| `LIVE_UPLOAD_MAX_ACTIVE` | `8` | `usize` (transfers, 1 to 1024) | Upload transfers running at once. Each holds one chunk in memory, so it times `LIVE_UPLOAD_CHUNK_BYTES` must be at most 1073741824 (1 GiB). |
| `LIVE_UPLOAD_MAX_FILE_BYTES` | `1073741824` (1 GiB) | `u64` (bytes, 1 to 1099511627776) | One uploaded file. The browser refuses a larger file before it sends anything; a component's own upload policy can only lower it. |
| `LIVE_UPLOAD_MAX_PENDING_FILES` | `1024`, or `LIVE_UPLOAD_MAX_ACTIVE` when that is larger | `usize` (files, the active limit to 100000) | Files one page, and one visitor on the server, has selected and not yet finished. |
| `LIVE_UPLOAD_MAX_PENDING_BYTES` | `4294967296` (4 GiB), or `LIVE_UPLOAD_MAX_FILE_BYTES` when that is larger | `u64` (bytes, the file limit to 17592186044416) | Bytes across the files one page, and one visitor on the server, has selected and not yet finished. |
| `LIVE_UPLOAD_MAX_STORAGE_BYTES` | `17179869184` (16 GiB), or `LIVE_UPLOAD_MAX_PENDING_BYTES` when that is larger | `u64` (bytes, the pending limit to 70368744177664) | What the temporary upload store holds across every visitor. The server alone applies it; it never reaches the page. |
| `LIVE_LEDGER_MAX_INSTANCES` | `100000` | `usize` (instances, 1 to 1000000) | Component instances the instance ledger holds. Every mounted private island and every promoted public seed is one. Nothing retires an instance when its page closes; it lives its whole lifetime, so this divided by `LIVE_LEDGER_INSTANCE_LIFETIME_MS` is the page views the ledger holds (100,000 over seven days is about 14,000 a day). Past it, each new mount evicts the instance that expires soonest, and that page's next action reloads it with current state. |
| `LIVE_LEDGER_INSTANCE_LIFETIME_MS` | `604800000` (seven days) | `u64` (ms, 60000 to 604800000) | How long one mounted instance lives, for its snapshot, its mount and the ledger. A shorter lifetime frees ledger room sooner; an island older than it re-renders fresh on its next action. |
| `LIVE_LEDGER_CLAIM_LEASE_MS` | `30000` | `u64` (ms, 1 to 300000) | How long one action holds its claim on an instance before another action may take it over. |
| `LIVE_LEDGER_MAX_ACCEPTED_OUTCOMES` | `64` | `usize` (outcomes, 1 to 64) | Accepted outcomes each instance keeps so a retried action gets its original answer. |

## Maintenance Mode

| Var | Default | Type | Purpose |
|---|---|---|---|
| `MAINTENANCE_DRIVER` | `file` | `String` (`file`, `cache`) | Selects how `down`/`up` state is stored. `file` writes to the framework storage path; `cache` rides on the configured cache driver (useful when many app instances must coordinate maintenance state). Any other value falls back to `file`. |

## Events

| Var | Default | Type | Purpose |
|---|---|---|---|
| `EVENT_MAX_CONCURRENCY` | `256` | `usize` | Ceiling on concurrent queued listener tasks. Values `<= 0` or unparseable fall back to the default. Applies to `Event::queue` / queued listeners; sync listeners are not subject to this limit. |

## Logging

`LOG_FORMAT` is **environment-aware**: in production (`APP_ENV=production`,
or `APP_ENV` unset) the default is `json` for log-aggregator friendliness;
everywhere else the default is `pretty` for human-readable local/dev
output. An explicit value always wins.

| Var | Default | Type | Purpose |
|---|---|---|---|
| `LOG_LEVEL` | `"info"` (filter), `debug` (channels) | `String` (`emergency`, `alert`, `critical`, `error`, `warning`/`warn`, `notice`, `info`, `debug`/`trace` - case-insensitive, with `tracing` target directives) | Tracing-subscriber filter directive, such as `info,sqlx=warn`. A PSR-3 name reads as its nearest `tracing` level: `warning` as `warn`, `notice` as `info`, `critical`, `alert` and `emergency` as `error`. Its bare level (`info` in `info,sqlx=warn`, `debug` when it names none) is also the lowest level the `single`, `daily`, `monthly`, `stderr`, `errorlog` and `syslog` channels keep, as Laravel's. A bare level that is no level fails boot. See [Logging](logging.md#log-levels). |
| `LOG_FORMAT` | env-aware (`json` in production, `pretty` elsewhere) | `String` (`json`, `pretty`) | Tracing-subscriber output format. |
| `LOG_CHANNEL` | `stdout` | `String` | The default log channel: `stdout`, `stderr`, `errorlog`, `single`, `daily`, `monthly`, `syslog`, `null`, `stack`, `custom`, or one the bootstrap defines with `Log::define`. A name that is no channel fails boot. See [Logging](logging.md#channels). |
| `LOG_CHANNEL_DRIVER` | none - required for `custom` | `String` | The driver the built-in `custom` channel uses. Register it with `Log::extend` in the bootstrap. Missing or unregistered drivers fail boot when the `custom` channel is selected. |
| `LOG_STACK` | `single` | `String` (comma-separated) | The channels the `stack` channel writes to. |
| `LOG_DAILY_DAYS` | `7` | `u32` | How many files the `daily` channel keeps, counting the one it writes to; `0` keeps every file. A value that is not a number fails boot. |
| `LOG_SYSLOG_FACILITY` | `user` | `String` (`user`, `daemon`, `local0` to `local7`, another facility name, or 0 to 23) | The facility the `syslog` channel sends with. An unknown one fails boot. |
| `LOG_SYSLOG_SOCKET` | `/dev/log` (`/var/run/syslog` on macOS) | `String` | The socket the `syslog` channel sends to. |
| `MAIL_LOG_CHANNEL` | unset (the default channel) | `String` | The log channel the `log` mail transport writes to. |

You set the `syslog` channel's ident with `APP_NAME`. If you leave it unset
or empty, the ident is `suprnova`.

## Observability (OpenTelemetry)

| Var | Default | Type | Purpose |
|---|---|---|---|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset (telemetry disabled) | `String` | Base URL of the OTLP collector, for example `http://localhost:4318`. Each signal is sent to its own path under it: `/v1/traces`, `/v1/metrics`, `/v1/logs`. A trailing slash is trimmed. When unset (or whitespace), exporters are not installed and the framework keeps using the standard `tracing` subscriber. This variable is what turns telemetry on; the three per-signal variables below have no effect without it. |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | unset | `String` | The URL the traces are sent to, used as it is written, with no path added. Unset sends traces to `/v1/traces` under the base endpoint. |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | unset | `String` | The URL the metrics are sent to, used as it is written. Unset sends metrics to `/v1/metrics` under the base endpoint. |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | unset | `String` | The URL the logs are sent to, used as it is written. Unset sends logs to `/v1/logs` under the base endpoint. |
| `OTEL_EXPORTER_OTLP_COMPRESSION` | unset (no compression) | `String` (`gzip`) | Read by the OpenTelemetry exporter, not by Suprnova. `gzip` works. `zstd` is not compiled in: asking for it leaves the signals out, with the reason in the log. |
| `OTEL_SERVICE_NAME` | `"suprnova"` | `String` | `service.name` resource attribute on every span / metric / log record. |
| `OTEL_SERVICE_VERSION` | `CARGO_PKG_VERSION` at build time | `String` | `service.version` resource attribute. |
| `OTEL_SDK_DISABLED` | `false` | `bool` | Standard OTel kill switch. When true, exporters are not installed regardless of `OTEL_EXPORTER_OTLP_ENDPOINT`. |

An endpoint must be a URL with the scheme `http` or `https` and a host. A
signal whose endpoint is not one, such as a path alone, is left out and
reported in the log, and the other signals are still exported. The report never
repeats the endpoint, which can carry a password or a token. The exporters need
the `otel` cargo feature. The other standard OTLP variables
(`OTEL_EXPORTER_OTLP_HEADERS`, `_PROTOCOL`, `_TIMEOUT`) are read by the
OpenTelemetry exporter directly.

## Heap profiling

| Var | Default | Type | Purpose |
|---|---|---|---|
| `SUPRNOVA_HEAP_PROFILE` | `dhat-heap.json` in the working directory | `String` (path) | The file the heap profile is written to when the process ends normally. Read only by a build with the `heap-profiling` feature. See [Deployment](deployment.md#heap-profiling). |

## CLI / dev server

These are read by the `suprnova` CLI binary's dev server rather than
the runtime framework - they appear in the starter `.env` or are
honoured by `suprnova serve`. The CLI's `ssr:*` commands read none of
their own: they run the application binary's commands, which read the
Inertia configuration the application installed (see
[Console](console.md#ssr-commands)).

| Var | Default | Type | Purpose |
|---|---|---|---|
| `VITE_PORT` | `5765` | `u16` | Port Vite binds to in `suprnova serve`. CLI `--frontend-port` overrides. |

## Subsystems with no env vars

A few subsystems are configured entirely in Rust code via the
container or service registration - they have **zero** env vars the
framework reads:

- **Filesystem / Storage, apart from S3.** Disks are registered by name with
  `Storage::register_*` in `bootstrap()` and addressed by name at the
  call site (`Storage::disk("public")`), or reached as the default disk
  `FILESYSTEM_DISK` names (`Storage::default_disk()`). The one exception
  is the S3-compatible `s3` disk, which the `S3_*` variables configure (see **Filesystem** above and
  [Docker](cli-docker.md)).
- **Broadcasting & WebSockets.** Channels are registered with the
  `ws!()` macro and `BroadcastHub` configuration in code. The driver
  itself rides on whatever the configured `CACHE_DRIVER` selects.
- **CORS, CSRF, Idempotency, Timeout.** Configured via builder structs
  passed to the middleware constructors in `bootstrap()`. The defaults
  are conservative enough that a typical app never touches them.
- **Magnetar and OAuth.** `MagnetarConfig` is built in application bootstrap.
  The API starter reads `PASSKEY_RP_ID` and `PASSKEY_RP_ORIGIN`, but the
  framework itself does not. OAuth provider IDs, secrets, callback URLs,
  scopes, transports, and policy values are supplied programmatically through
  the Magnetar provider registry. Applications may source those values from
  environment variables or a secret manager.
- **Notifications, Payments, Feature Flags.** Each
  registers concrete drivers via `App::bind` in `bootstrap()`. Pick
  your driver in Rust; pass any URLs/keys it needs as your own env
  vars. The exceptions are the table-layout variables in
  **Laravel database** above and `WEB_PUSH_ENDPOINT_ORIGINS` in
  **Web Push**.
- **Vector search** registers its drivers the same way. The Qdrant,
  MariaDB and Pinecone drivers have a `from_env()` constructor that reads the
  variables in **Vector search** above.

## Variables the framework does not read

The scaffolded starter `.env` lists a few keys for human-author
convenience that the framework never consults. They're documented
here so a reader searching for them isn't left wondering:

- `MAIL_FROM_ADDRESS` - a Laravel-style placeholder the framework never
  consults. The actual from-address the auth-flow facades use is `MAIL_FROM`
  (covered under Mail). Your own `Mailable` types can read it via
  `env_optional` if you want to keep the Laravel name, but nothing in
  `suprnova::*` does. (`MAIL_FROM_NAME` **is** read as of 0.5.9 - see the
  Mail chapter - so it's no longer listed here.)

## How values are parsed

A short reference for the three env-helper variants - see
[Configuration](configuration.md#direct-env-access) for the full
treatment:

| Helper | Behaviour on missing | Behaviour on unparseable |
|---|---|---|
| `env(key, default)` | returns `default` | `warn!` + returns `default` |
| `env_required(key)` | **panics** | **panics** |
| `env_optional(key)` | returns `None` | `warn!` + returns `None` |
| `env_strict(key)` (internal, used by `try_from_env`) | returns `Ok(None)` | returns `Err(FrameworkError)` - boot aborts |

Strict variants (`AppConfig::try_from_env`, `ServerConfig::try_from_env`)
are what `Config::init` calls, so a typo in `APP_DEBUG=tru` or
`SERVER_PORT=80a0` aborts boot with a structured error instead of
silently reverting to the default. Lenient variants exist for the
broader call-site population (including `impl Default`) where a parse
failure must not panic.

## Per-environment overrides

The loader reads files in this order, each overriding the previous:

1. `.env`
2. `.env.local`
3. `.env.<environment>` (e.g. `.env.production`, `.env.staging`,
   `.env.testing`, `.env.<custom>` for `APP_ENV=<custom>`), then
   `.env.<environment>.local`, only when `APP_ENV` is set, in the process
   or in `.env`
4. Process environment

That means a containerised production deploy can ship a minimal
`.env.production` overriding only the keys that differ from `.env`
(driver names, URLs, key material), and the real container env
overrides both for secrets that should never land in a committed
file.

See [Configuration](configuration.md#how-env-loading-works) for the
exact loader behaviour and the tracking of loaded keys that prevents
stale `.env` values from promoting into the "real system env" tier
across reloads.

## Next

- [Configuration](configuration.md) - typed `Config::*` registration,
  the `env*` helpers, environment detection
- [Deployment](deployment.md) - what to set in production
- [Encryption](encryption.md) - `APP_KEY` rotation via
  `APP_KEY_PREVIOUS`
- [Application Bootstrap](bootstrap.md) - where env-driven boot order
  is established


---

<!-- /docs/glossary -->

# Glossary

Suprnova-specific terms, defined once. If a chapter uses a word without
explaining it, the definition lives here. Entries are alphabetical;
follow the cross-link for the chapter that uses the term in context.

A handful of conventions to keep in mind while reading the rest of this
list:

- **Trait** means a Rust trait - a behaviour contract you implement on a
  type. **Facade** means a zero-sized struct whose static methods are the
  entry point to a subsystem (`Cache`, `Mail`, `Auth`, `Storage`,
  `Bus`, `Notify`, `Vector`, `DB`, `Schedule`, `App`).
- **Driver** means a swappable backend behind a facade or registry -
  `CacheStore`, `QueueDriver`, `VectorDriver`, `RateLimiterDriver`,
  `MailDriver`. Drivers are picked at boot via environment variables
  and bound through the container.
- **Registry** means a process-global lookup populated at compile time
  via `inventory` or at boot via explicit registration -
  `ConnectionRegistry`, `MiddlewareRegistry`, `InertiaRegistry`,
  `ChannelRegistry`, `VectorRegistry`, `SupervisorRegistry`,
  `PaymentProviderRegistry`, `ScopeRegistry`.

## A

### Accessor

A read-side transformation declared on an Eloquent model with the
`#[accessor]` macro. Runs every time the property is read, returning a
computed value derived from one or more underlying columns
(`full_name` from `first_name + last_name`, for example). The dual of a
[Mutator](#mutator). See
[Eloquent - Accessors and mutators](eloquent.md#accessors-and-mutators).

### Action

An injectable service class that encapsulates one piece of business
logic - a single public method, dependencies injected via the
`#[injectable]` macro. The Suprnova analogue of Laravel's
single-action invokables. Actions are bound as singletons in the
container automatically and resolved by handlers, jobs, and other
actions. See [Actions](actions.md).

### Application

The fluent builder in `Application::new()` that registers your
config, bootstrap, routes, and migrations functions, then calls
`.run()` to dispatch the binary's CLI subcommand (`serve`, `migrate`,
`queue:work`, etc.). One per binary, lives in `src/app.rs`. See
[Request Lifecycle](lifecycle.md).

### Atomic counter

A cache operation (`Cache::increment`, `Cache::decrement`) that
mutates a numeric value as a single round-trip without read-modify-write
races. Backed by Redis `INCR`/`DECR` on the Redis store, by a held
guard on the in-memory store. See [Cache - Atomic Counters](cache.md#atomic-counters).

### Authenticatable

The trait an authenticated user type implements
(`get_auth_identifier() -> String`, `get_auth_password()`, etc.) so
guards and middleware can talk to it without knowing the concrete user
struct. See [Authentication](authentication.md).

### Authorizable

The trait that gives a user type the policy entry points (`can`,
`can_any`, `cannot`) used by the [Gate](#gate). See
[Authorization](authorization.md).

## B

### Backoff schedule

The sequence of delays a queue worker waits between retries of a
failing job. A `BackoffSchedule`: `Fixed`, `Exponential`, or an explicit
`Sequence` of delays. See [Queues - Backoff schedules](queues.md#backoff-schedules).

### Batch (queue)

A group of jobs dispatched together and tracked as a unit -
`PendingBatch::new().add(job).add(other).dispatch()` returns the
persisted batch id. Useful when you want to fan out work and run a
callback when the whole batch completes. See [Queues - Queued batches](queues.md#queued-batches).

### `BelongsTo`

The inverse-of-`HasOne`/`HasMany` relation kind - child holds the
foreign key, parent is on the other side. One of the eleven Eloquent
relation kinds. See
[Eloquent - Relationships](eloquent.md#relationships).

### `BelongsToMany`

A many-to-many relation kind that goes through a third, first-class
[Pivot](#pivot) model. `BelongsToMany<Local, Related, Pivot>` - the
pivot is named in the type, not synthesised by string convention. See
[Eloquent - Relationships](eloquent.md#relationships).

### Bootstrap

The `bootstrap_fn` you register on the `Application` builder and that
runs once at boot (after config, before serving). Where you bind
services into the [Container](#container), register observers and
event listeners, configure default headers, and so on. The Suprnova
analogue of Laravel's service providers, collapsed into one function.
See [Application Bootstrap](bootstrap.md).

### Broadcastable

The trait an [Event](#event) implements when it should be pushed to
WebSocket subscribers instead of (or in addition to) local in-process
listeners. The bridge between the event dispatcher and the
[Broadcast Hub](#broadcasthub). See [Broadcasting](broadcasting.md).

### `BroadcastHub`

The trait that names "the thing that fans out a message to all
WebSocket subscribers of a channel" - the in-memory implementation
(`InMemoryBroadcastHub`) is the default; the Redis stream
implementation (`SeaStreamerBroadcastHub`) is the multi-process
production deployment. See [Broadcasting - Multi-Process Fanout](broadcasting.md#cross-process-fanout).

### Builder (Eloquent)

The fluent query object returned by `Model::query()` - the chainable
surface where you build `where`, `order_by`, `with`, `limit`, etc.
before `.get()`, `.first()`, or `.paginate(...)`. Dual-named: every
filter method exists under both its Laravel name (`db_where`,
`db_or_where`) and its Rust-native synonym (`filter`, `or_filter`).
See [Eloquent - Query builder](eloquent.md#query-builder---dual-api).

### Bus command

A serialisable struct dispatched through `Bus::dispatch(cmd)` that
routes to a single registered `Handler<C>`. Bus commands are for
in-process work that should bubble its result back to the caller -
queue [Job](#job)s are for work that should be persisted and retried
in the background. See [Command Bus](bus.md).

## C

### Cache driver

The selected backend (`memory` or `redis`) behind the `Cache` facade.
Picked at boot via `CACHE_DRIVER` and surfaced through the
[CacheStore](#cachestore) trait. See [Cache](cache.md).

### `CacheStore`

The trait that defines the cache driver SPI - `get`, `put`, `forget`,
`increment`, etc. `InMemoryCache` and `RedisCache` are the shipped
implementations. See [Cache - Configuration](cache.md#configuration).

### Cast (Eloquent)

A bidirectional transformation declared with `casts!` on an Eloquent
model - DB column type ↔ Rust type. 22 built-ins ship
(`AsBool`, `AsDateTime`, `AsJson`, `AsEncrypted`, `AsArray`, etc.); a
user-implemented `Cast` trait covers anything else. See
[Eloquent - Casts](eloquent.md#casts).

### Chain (queue)

A sequence of [Job](#job)s linked so each one runs only if the
previous one succeeds. Built with `PendingChain::dispatch` /
`Queue::chain`. See [Queues - Queued chains](queues.md#queued-chains).

### Channel (broadcasting)

The trait an event broadcasts to - `PublicChannel`, `PrivateChannel`,
or `PresenceChannel`. The channel struct names itself
(`fn name() -> String`) and authorises connection
(`fn authorize(...)`); private and presence channels add stronger
trait bounds. See [Broadcasting - Channels](broadcasting.md#channels).

### Channel (notification)

The trait that routes a [Notification](#notification) to a delivery
mechanism - mail, database, broadcast, web push. A notification names
its channels in `fn via(...)`; each channel resolves the destination
and sends. Distinct from the broadcasting trait of the same name. See
[Notifications - Channels](notifications.md#channels).

### Container

The three-layer (task-local → thread-local → global) registry where
services are bound and resolved through the `App` facade. The
Suprnova analogue of Laravel's service container, with extra layers
for per-request and per-test isolation. See
[Service Container](container.md).

### Context (per-request)

The per-request bag of typed values reachable from any code in the
same async task - `Context::set::<T>(value)`, `Context::get::<T>()`.
Survives task spawns when you propagate it explicitly. Distinct from
the feature-flag context that shares the name. See
[Context](context.md).

### CORS

Cross-Origin Resource Sharing. The browser security rule that gates a
JavaScript fetch from origin A to origin B; Suprnova ships
`CorsMiddleware` to emit the response headers that signal which
cross-origin requests are allowed. See [CORS](cors.md).

### CSRF

Cross-Site Request Forgery. The attack a stateful session has to
defend against; Suprnova ships `CsrfMiddleware` to require a matching
token on every state-changing request. See [CSRF Protection](csrf.md).

## D

### `DB` facade

The model-less entry point to the database - `DB::table(...)`,
`DB::transaction(...)`, `DB::raw(...)`. For queries that don't fit
the Eloquent shape (dynamic columns, joined aggregates, raw SQL). See
[Eloquent - DB facade](eloquent.md#db-facade---model-less-queries).

### Disk

A named storage backend registered through the `Storage` facade -
`Storage::disk("s3")`, `Storage::disk("local")`. Each disk implements
[DiskExt](#diskext) and is keyed by its registration name. See
[File Storage](filesystem.md).

### `DiskExt`

The trait every storage backend implements - `put`, `get`, `delete`,
`list`, `signed_url`, etc. Backed by `opendal` under the hood; ships
adapters for local fs, in-memory, S3, Azure Blob, and GCS. See
[File Storage](filesystem.md).

## E

### Eloquent

The whole ORM layer - `Model` trait, `Builder<M>`, relations,
casts, scopes, observers, events, soft deletes, prunable, factories.
The Laravel name for what other ecosystems call an ORM; in Suprnova
it sits on top of SeaORM (which the user shouldn't see). See
[Eloquent](eloquent.md).

### Envelope (queue)

The wrapper struct (`Envelope { payload, attempts, max_attempts,
delay, ... }`) that a queue driver actually serialises and stores.
Insulates the [Job](#job) payload from queue plumbing. See
[Queues](queues.md).

### Event

A clonable struct dispatched through `EventDispatcher::dispatch(evt)`
and delivered to every registered `Listener<E>`. Suprnova ships the
trait, the facade (`EventFacade`), the `Subscriber` aggregator, and
hooks for [Queued Listener](#queued-listener)s. See [Events](events.md).

### Event listener

See [Listener](#listener).

## F

### Facade

The naming convention for a zero-sized struct whose `impl` block
holds the public API of a subsystem - `Cache`, `Mail`, `Auth`,
`Storage`, `Bus`, `Notify`, `Vector`, `DB`, `Schedule`, `App`.
Inherited from Laravel; in Suprnova the underlying implementation is
resolved through the [Container](#container) rather than via PHP's
magic-call. See [Service Container](container.md).

### Factory (Eloquent)

The `#[derive(Factory)]` macro and `Factory` trait that produce
realistic test rows with `fake`-driven defaults -
`UserFactory::times(5).create_many().await?`. The Rust counterpart of
Laravel's model factories.
See [Macros - Factories](macros.md#factories).

### Fail-closed

A driver-failure policy where a backend outage causes the request to
reject with a 5xx - used by rate limit, session, and idempotency when
"better to refuse than to leak". The opposite of [Fail-open](#fail-open).
Configured via `BackendErrorPolicy::FailClosed`. See [Rate Limiting](rate-limiting.md).

### Fail-open

A driver-failure policy where a backend outage lets the request
through (with a logged warning) rather than rejecting it - used when
availability outranks the limit. Configured via
`BackendErrorPolicy::FailOpen`. See [Rate Limiting](rate-limiting.md).

### Feature flag

A boolean (or typed value) keyed by name and evaluated against the
current user/context - `feature!(MyFeature)`. Backed by the
`Evaluator` trait; ships a database evaluator and a TTL-cached
evaluator on top. See [Feature Flags](feature-flags.md).

### Fillable

The compile-time allowlist that says which model columns can be
mass-assigned from a hash of untrusted attributes - declared on the
model via `fillable = [...]` inside `#[model(...)]`. The dual of
`guarded = [...]`. See [Eloquent - Mass assignment](eloquent.md#mass-assignment).

### Filesystem

The whole storage subsystem - the `Storage` facade, registered
[Disk](#disk)s, [DiskExt](#diskext) trait, cross-disk streaming
copy. See [File Storage](filesystem.md).

### Form request

A struct implementing `FormRequest` (or derived via `#[request]`)
that extracts and validates a request body before the handler runs.
The composable, type-safe analogue of Laravel's form-request classes.
See [Validation](validation.md).

### `FrameworkError`

The single enum every framework-internal failure converts into. Carries
its own `HttpResponse` projection (`From<FrameworkError> for
HttpResponse`) that sanitises 5xx bodies and stamps a request id.
See [Error Model](error-model.md).

## G

### Gate

The authorization entry point - `Gate::allows("update-post", user,
post)`. Resolves against registered policies (declared via the
`#[policy]` macro) and short-circuits on allow/deny. Returns a
`GateResponse` (re-exported as the authorization `Response`). See
[Authorization](authorization.md).

### Global scope

A query constraint applied to every `Model::query()` call until
explicitly removed (`Model::without_global_scope::<S>()`). Implemented via
the `GlobalScope` trait and registered in bootstrap. See
[Eloquent - Scopes](eloquent.md#scopes).

### Guard (auth)

The named authentication strategy attached to a request -
`session` (stateful, cookie-backed), `token` (stateless,
bearer-token). Multiple guards coexist; `Auth::guard("api")` picks
one. See [Authentication](authentication.md).

### Guarded

The compile-time blocklist that says which model columns *cannot* be
mass-assigned. The dual of [Fillable](#fillable). See
[Eloquent - Mass assignment](eloquent.md#mass-assignment).

## H

### `HasMany`

A one-to-many relation kind - parent holds the local key, children
hold the foreign key. One of the eleven Eloquent relation kinds. See
[Eloquent - Relationships](eloquent.md#relationships).

### `HasManyThrough`

A relation that reaches the related model by hopping through a third
intermediate model - `Country -> User -> Post`. See
[Eloquent - Relationships](eloquent.md#relationships).

### `HasOne`

The single-row sibling of [HasMany](#hasmany) - parent holds the
local key, child has the foreign key, returns at most one row. See
[Eloquent - Relationships](eloquent.md#relationships).

### Hash facade

The password-hashing entry point - `hash(password)`,
`verify(password, hash)`. Picks bcrypt or argon2 via `HASH_DRIVER`;
`needs_rehash` lets you migrate users between algorithms on login.
See [Hashing](hashing.md).

### Handler

The async function that returns a `Response` for a matched route -
turned into the framework's typed handler shape by the `#[handler]`
macro. Composed at the inner edge of the middleware chain. See
[Routing](routing.md), [Controllers](controllers.md).

### `HttpError`

The trait a user-defined error type implements to specify how it
should render as an HTTP response - status, body, headers. Mirrors
Laravel's `Renderable` exceptions. See [Error Handling](errors.md).

### `HttpResponse`

The concrete HTTP response type produced by handlers and middleware.
Wraps a status code, headers, and a body - the thing actually written
to the wire. See [Responses](responses.md).

## I

### Idempotency key

A client-supplied header (`Idempotency-Key`) that says "if you've
already processed a request with this key, replay the same response
instead of running the handler again". Required for retry-safe
POST/PUT/PATCH/DELETE; Suprnova ships `Idempotency`, `Idempotent`, and
`Replay` to wrap handlers. See [Idempotency](idempotency.md).

### Inertia response

A response that returns a typed component name plus serialised props
instead of HTML - the bridge between a Rust handler and a Svelte /
React / Vue page. Built with `Inertia::render(...)` or the
`#[derive(InertiaProps)]` macro plus `inertia_response!`. See
[Frontend](frontend.md), [Inertia Responses](frontend-inertia-responses.md).

### `InertiaProps`

The derive macro that generates the `Serialize` impl plus
TypeScript-type metadata for a struct used as an Inertia page's
props. Drives the `suprnova generate-types` command. See
[TypeScript Types](frontend-typescript-types.md).

## J

### Job

A serialisable struct implementing the `Job` trait - has a
`handle(self)` method, enqueued through `Queue::push(job)` (or
`Queue::push_later(job, when)` for a delayed dispatch). Persisted into
the queue driver's storage and run by a worker. See [Queues](queues.md).

### Job middleware

The composable wrappers (`WithoutOverlapping`, `RateLimited`,
`ThrottlesExceptions`, `Skip`, `FailOnException`,
`SkipIfBatchCancelled`) that run around a job's `handle` call. The
queue equivalent of HTTP middleware. See
[Queues - Job middleware](queues.md#job-middleware).

### `JobOutcome`

The discriminated enum a job's settlement produces -
`Completed`, `Failed`, `Released`, `Deleted`, `Skipped` - reported
through job lifecycle events and the queue metrics counter. See
[Queues](queues.md).

## L

### Lazy collection

The streaming counterpart to [Collection](eloquent-collections.md) -
`Model::query().lazy().await` returns a `LazyCollection<M>` that pulls
rows from the database in chunks rather than loading every row into
memory. See
[Eloquent - Chunking and lazy iteration](eloquent.md#chunking-and-lazy-iteration).

### Length-aware paginator

The classic numbered-page paginator (`Builder::paginate(per_page)`)
that runs the query plus a `COUNT(*)` - knows the total row count.
See [Eloquent - Pagination](eloquent.md#pagination).

### Listener

The trait an event handler implements - `Listener<E>::handle(evt)`.
Registered with `EventDispatcher::listen::<E, _>(arc_listener)` or
via the `Subscriber` aggregator. See [Events](events.md).

### Lock guard (cache)

The handle returned by `Cache::lock(key, ttl).acquire()` representing
mutual exclusion across processes - `LockGuard`. Releasing the guard
releases the lock; dropping it on the floor relies on the TTL. See
[Cache](cache.md).

### Lock policy

The project-wide policy for handling `std::sync::Mutex` /
`std::sync::RwLock` poisoning in a long-lived process - two sanctioned
patterns (map-to-error or recover-in-place); never bare
`.lock().unwrap()`. See [Lock Policy](lock-policy.md).

## M

### `Mailable`

The trait a mail message implements - `subject`, `to`, `cc`, `bcc`,
`view`, attachments. Either hand-written or derived via the
`#[derive(NotificationMailable)]` macro; sent through
`Mail::to(...).send(MyMail).await`. See [Mail](mail.md).

### Maintenance mode

A request-time flip that takes the application offline for everyone
except an allowlist - `maintenance_mode().set(payload)`. Backed by
`FileMaintenanceMode` (default, a sentinel file) or
`CacheMaintenanceMode` (cache-backed for multi-instance deployments);
served by `MaintenanceMiddleware`. Re-exported at the crate root.

### Middleware

A composable wrapper around a handler - sees the request before, the
response after, and can short-circuit by returning `Err(resp)`.
Registered globally, by route, or by group; runs in a fixed
outside-in order. See [Middleware](middleware.md).

### Model

A struct annotated with `#[suprnova::model]` that names a database
table. The struct *is* the SeaORM `Model` after the macro expands -
Suprnova doesn't wrap it. Carries CRUD via the `Model` trait, query
construction via `Model::query()`, factories, casts, scopes,
relations, observers. See [Eloquent](eloquent.md).

### Morph

Short for "polymorphic". A morph relation lets a single relation
point at one of several model types - `MorphTo` (single owner of
several possible types), `MorphMany`/`MorphOne` (the inverse,
collecting morphed children), `MorphToMany`/`MorphedByMany`
(many-to-many across morphed types). The framework keeps a runtime
[Registry](#registry) of `MorphTypeEntry` mappings between
discriminator strings and Rust types. See
[Eloquent - Relationships](eloquent.md#relationships).

### Mutator

A write-side transformation declared with the `#[mutator]` macro -
runs every time the property is set, before the value is stored on
the model. The dual of an [Accessor](#accessor). See
[Eloquent - Accessors and mutators](eloquent.md#accessors-and-mutators).

## N

### Notifiable

The trait a user (or any object that can receive notifications)
implements - `route_for(channel)` returns the address for the named
channel (mail address, push subscription, broadcast user id, etc.) or
`None` to skip. See
[Notifications - The Notifiable Trait](notifications.md#notifiable).

### Notification

The trait a notification message implements - `channels()` returns the
list of channel names it should fan out to; each channel calls back
into the notification (via per-channel traits like `MailRendering` /
`DatabaseChannel` payload methods) for the channel-specific payload.
Dispatched through `Notify::send(&user, &notif).await`. See
[Notifications](notifications.md).

## O

### Observer

A struct implementing `Observer<M>` that listens for an Eloquent
model's lifecycle events - `creating`, `created`, `updating`,
`updated`, `deleting`, `deleted`, `saving`, `saved`, `retrieved`,
`replicating`, etc. Registered via the `#[suprnova::observer(M)]`
macro; drained from the inventory at boot. See
[Eloquent - Observers and lifecycle events](eloquent.md#observers-and-lifecycle-events).

### `OriginPolicy`

The CSRF middleware's enforcement choice for the `Origin` header on
state-changing requests - `Strict` (must match host),
`AllowList`, or `None`. See [CSRF Protection](csrf.md).

## P

### Paginator

The result of a `.paginate(...)` call - one of three flavours.
`LengthAwarePaginator` (numbered pages with a `COUNT(*)`),
`Paginator` (next/prev, no total), `CursorPaginator` (opaque cursor
for stable iteration over a moving result set). All three serialise to
a Laravel-shaped JSON payload. See
[Eloquent - Pagination](eloquent.md#pagination).

### Panic boundary

The `AssertUnwindSafe(...).catch_unwind()` wrapper around the
middleware chain (and around each background-worker handler) that
converts an unhandled panic into a sanitised 500 plus a logged
`ErrorOccurred` event. A safety net, not a contract - public APIs
should still return `Result`. See [Request Lifecycle - Panic boundary](lifecycle.md#5-panic-boundary---execute_chain_safely).

### Payment provider

A type implementing the `PaymentProvider` super-trait (= `Checkout` + `Subscription` + `CustomerStore` + `WebhookHandler`). Reference
adapters: `suprnova-payments-stripe` (gateway, full `Payment` impl)
and `suprnova-payments-paddle` (merchant-of-record, no `Payment`).
See [Payments](payments.md), [Provider Guide](payments-provider-guide.md).

### Pivot

The intermediate model in a [BelongsToMany](#belongstomany)
relation - a first-class `#[suprnova::model]` with its own struct,
casts, and timestamps, named explicitly as the third type parameter
(`BelongsToMany<L, R, P>`). Suprnova does not synthesise an implicit
pivot from a table name. See
[Eloquent - Relationships](eloquent.md#relationships).

### Presence channel

A [Channel](#channel-broadcasting) variant where the server tracks
who is currently subscribed and emits join/leave events with each
member's metadata. Useful for "who's online" indicators. See
[Broadcasting - Presence Channels](broadcasting.md#presence-channels).

### Private channel

A [Channel](#channel-broadcasting) variant that requires
authorisation on subscribe - `authorize(...)` must return true for
the subscribing user. Useful for per-user notification streams. See
[Broadcasting - Channels](broadcasting.md#channels).

### Prunable

The trait that marks a soft-deleted (or queryable) model as eligible
for cleanup by `suprnova model:prune` - `Prunable::prunable()` returns
the builder for rows that should go. `MassPrunable` deletes in a
single `DELETE WHERE`; the default issues per-row deletes so observers
fire. Tagged for the registry via the `#[prunable]` macro. See
[Eloquent - Prunable](eloquent.md#prunable).

## Q

### Queue

The whole background-work subsystem - `Queue` facade, [Job](#job)
trait, [Envelope](#envelope-queue), drivers (memory, sync, redis,
database, sqs, null), worker, batches, chains. See [Queues](queues.md).

### Queue driver

A type implementing `QueueDriver` (push, pop, release, etc.) -
ships `MemoryQueueDriver`, `SyncQueueDriver` (run inline),
`RedisQueueDriver`, `DatabaseQueueDriver`, `SqsQueueDriver`,
`NullQueueDriver`. Picked
at boot via `QUEUE_DRIVER`. See
[Queues - Drivers](queues.md#drivers).

### Queue worker

The long-lived loop that pulls envelopes off the queue driver, runs
job middleware around the handler, and reports the outcome. Boots
through the same lifecycle as the HTTP server so observers and
listeners fire identically. Started by `cargo run -- queue:work`. See
[Queues](queues.md).

### Queued listener

A `Listener<E>` that, when invoked, persists the event payload to
the queue and runs `handle` in a background worker rather than
in-process. Useful when an event listener does I/O that shouldn't
block the dispatch path. Wrapped via the `QueuedListener` adapter.
See [Events](events.md).

## R

### Rate limiter

The whole rate-limiting subsystem - `RateLimiter` (the cache-backed
facade), `Limit` builder, `SlidingWindowConfig` (sliding-window
driver), `RateLimitMiddleware` (route-mounted),
`ThrottleRequestsMiddleware` (Laravel-named alias),
`BackendErrorPolicy` (fail-open vs fail-closed). See
[Rate Limiting](rate-limiting.md).

### Redirect

A specialised [HttpResponse](#httpresponse) wrapping a `Location`
header - built via `Redirect::to(...)`, `Redirect::route(...)`,
`Redirect::back()`, with `.with(...)`/`.with_input(...)` chains for
flash data. See [URL Generation](urls.md), [Responses](responses.md).

### Registry

A process-global lookup populated either at compile time by
`inventory` (`ModelEntry`, `RelationEntry`, `MorphTypeEntry`,
`ObserverEntry`, `PrunerEntry`, `TaskEntry`, `PaymentProviderEntry`,
`CommandEntry`) or at boot by explicit registration
(`ConnectionRegistry`, `MiddlewareRegistry`, `InertiaRegistry`,
`ChannelRegistry`, `VectorRegistry`, `SupervisorRegistry`). All
are drained or queried during the boot sequence.

### Relation

The trait every relation kind implements - `BelongsTo`, `HasOne`,
`HasMany`, `BelongsToMany`, `HasOneThrough`, `HasManyThrough`,
`MorphTo`, `MorphOne`, `MorphMany`, `MorphToMany`, `MorphedByMany`.
A model declares its relations as methods returning a relation
struct; the framework drives eager loading, `with(...)`,
relation-existence queries, and cascading touches from the trait. See
[Eloquent - Relationships](eloquent.md#relationships).

### Request

The framework's typed request struct - wraps the underlying hyper
request and exposes `req.param("id")`, `req.json::<T>()`,
`req.form_data()`, `req.flash()`, etc. Re-exported as
`suprnova::Request`. See [Requests](requests.md).

### `Response`

Suprnova binds `http::Response` to `Result<HttpResponse,
HttpResponse>` - both arms carry an `HttpResponse`. Handler bodies
return `Response`, propagate fallible work with `?`, and the runtime
collapses both arms with `result.unwrap_or_else(|e| e)`. The
authorization decision type is re-exported as `GateResponse` to avoid
the collision. See [Responses](responses.md),
[Request Lifecycle](lifecycle.md#the-response-contract).

### Resource

Two unrelated things share the name; both ship.

1. **JSON:API resource** - a `#[derive(Data)]` struct with
   `#[json_resource("type")]` that
   serialises a model into the JSON:API shape with sparse fieldsets
   and includes. See [API Resources](eloquent-resources.md).
2. **Resource routing** - a route helper that mounts a CRUD
   `index`/`show`/`store`/`update`/`destroy` set against a
   `ResourceController` impl, or against a module of `#[handler]`
   functions with `resource!`, whose actions take bound arguments. See
   [Routing](routing.md#resource-routing).

### Route binding

Turning a route parameter into a value before the handler runs. A
handler argument binds from the parameter of its name when its type
implements `RouteBinding`: every `#[suprnova::model]` struct, a
`#[derive(RouteBinding)]` enum, or a type that implements it by hand. A
value that does not parse or matches nothing answers 404. See
[Route model binding](routing.md#route-model-binding).

### `routes!` macro

The compile-time macro that expands a routing DSL
(`get!("/users", users::index)`, `group!`, `.middleware(...)`) into
a `Router` factory function. The single source of route truth for an
application. See [Routing](routing.md), [Macros](macros.md).

## S

### Scope (local)

A reusable query fragment declared on an Eloquent model with the
`#[scopes(Model)]` macro - `Post::query().published().recent().get()`.
Local scopes are off by default; they only run when invoked. The
counterpart of [Global scope](#global-scope). See
[Eloquent - Scopes](eloquent.md#scopes).

### Seeder

A type implementing the `Seeder` trait that populates the database
with starting data. `suprnova db:seed` runs every seeder, and
`suprnova db:seed UserSeeder` runs one. Often
backed by a [Factory](#factory-eloquent). See [Eloquent](eloquent.md).

### Signed URL

A URL whose query string carries an HMAC signature
(`?signature=...&expires=...`) proving it was produced by the
application and hasn't been tampered with. Built via
`sign_url(...)` / `sign_route(...)`; verified by middleware or via
`verify_signature(...)`. See [URL Generation - Signed URLs](urls.md#signed-urls).

### Soft deletes

The pattern where deleting a model row sets a `deleted_at` timestamp
instead of issuing `DELETE`. Opt-in per model via
`soft_deletes = true` on the `#[suprnova::model]` attribute;
`Model::query()` auto-filters out trashed rows; `with_trashed()` and
`only_trashed()` opt back in. See
[Eloquent - Deleting and soft deletes](eloquent.md#deleting-and-soft-deletes).

### `Storage` facade

The entry point to the filesystem subsystem -
`Storage::disk("s3")`, `Storage::disk("local")` - returning a
[DiskExt](#diskext) implementation. See [File Storage](filesystem.md).

### Subscriber

An aggregator that registers many listeners in one call - implements
`Subscriber::subscribe(dispatcher)` and is registered via
`EventDispatcher::subscribe(subscriber)`. See [Events](events.md).

### Supervisor

The trait a long-lived background actor implements (`Supervisor::run`)
to live under the `SupervisorRegistry`. The registry catches panics in
the run loop, applies a `RestartPolicy`, and re-spawns. The Rust
equivalent of Erlang's `gen_server` supervisor pattern. See
[Supervisors](supervisors.md).

## T

### Task

A struct implementing the `Task` trait - declares a cron expression
or a higher-level frequency (`daily()`, `every_minute()`) and runs on
the scheduler. Discovered at compile time via the `TaskEntry`
inventory. See [Task Scheduling](scheduling.md).

### Terminable middleware

Middleware that registers a hook to run *after* the response has been
written to the client - implemented via the `Terminable` trait,
captured into a `TerminationSnapshot`, and dispatched by
`dispatch_termination`. Useful for logging, metric flushes, post-flight
auditing. See [Middleware - Terminable middleware](middleware.md#terminable-middleware---post-response-hooks).

### Through (relation)

A relation that hops through a third intermediate model -
[HasManyThrough](#hasmanythrough) and `HasOneThrough`. See
[Eloquent - Relationships](eloquent.md#relationships).

### Timeout

The middleware that bounds a single request's wall-clock time and
returns 504 when the bound is exceeded - `TimeoutMiddleware`. Distinct
from queue worker timeouts (`TimeoutExceeded` on the queue side) and
from HTTP-client timeouts. See [Timeout](timeout.md).

### `TypedCommand`

The console-side trait - implemented by `#[derive(Command)]` structs -
that gives a console command typed arguments (via `clap`) and an
async `handle(self)` method. Registered into the `CommandEntry`
inventory at compile time. See [Console](console.md).

## U

### `UserId`

The opaque string identifier returned by `Auth::id()`. Framework guard/provider
paths carry whatever stable key the configured `UserProvider` uses; with
`EloquentUserProvider<User>` this is normally the stringified primary key.
Magnetar facades expose a `UserId` newtype but bind its value back to the
application's canonical user ID before writing framework session state.
Keeping the request boundary string-shaped lets numeric IDs, UUIDs, and
provider-independent opaque IDs use the same middleware and event contracts.
See [Authentication](authentication.md).

## V

### VAPID

Voluntary Application Server Identification - the IETF spec for
identifying a web-push sender. Suprnova ships `VapidKey`,
`VapidSigner`, `VapidClaims`, and the `WebPushClient` that signs each
push request. See [Web Push](web-push.md).

### `Vector` facade

The entry point to the vector-search subsystem -
`Vector::driver("qdrant").await?.upsert(...)`. Backed by
`VectorDriver` implementations: in-memory, Qdrant, Pinecone (feature
gated), MariaDB native. See [Vector Search](vector.md).

### `VectorDriver`

The trait every vector backend implements - `upsert`,
`search`, `delete`, `count`. Allows the framework to support multiple
vector DBs without forcing one. See [Vector Search](vector.md).

## W

### Web push

The web-platform push-notification protocol - encrypted payloads
delivered through the user agent's push service. Suprnova ships
`WebPushClient` (VAPID signer, retry-after parsing, 8 KiB rejection
cap) and `WebPushChannel` for [Notification](#notification) delivery.
See [Web Push](web-push.md).

### Webhook

An HTTP request sent by a third-party (payment provider, identity
provider, …) into your application to report an event. Suprnova
treats every webhook as idempotent by default - provider adapters
implement `WebhookHandler::verify(...)` and store the provider's
event id in a `UNIQUE` constraint that rejects replays. See
[Payments - Webhook Handling](payments.md#webhook-handling),
[Idempotency](idempotency.md).

### Workflow

A long-running, stateful piece of background work composed of typed
steps - `#[workflow]` and `#[workflow_step]` macros. Each step's
return value is persisted, so a worker restart mid-workflow resumes
from the last completed step. The Suprnova answer to multi-step
background processes that don't fit a single [Job](#job). See
[Workflows](workflows.md).

### `WsConfig`

The per-route WebSocket configuration - payload size caps (default
1 MiB text / 64 KiB binary), max frame size, ping interval, idle
timeout, origin policy. Used by `ws!()` routes. See [WebSockets](websockets.md).

### `WsSocket`

The framework's typed WebSocket handle handed to a `ws!()` handler.
`WsSocket::sender()` returns a cloneable `WsSender`, so another task can
send while the handler waits in `recv`. `WsSocket::split()` takes the socket
apart into a `WsSender` and a `WsReceiver`. The sending half is not a `Sink`:
it has `send_text` and `send_binary` methods that take `&self`. The receiving
half is a `Stream` of `Result<Message, FrameworkError>`, and also has `recv`
and `recv_text`. Pings/pongs are managed by a heartbeat task with an
`AbortHandle` so a dropped handler always tears down cleanly. See
[WebSockets](websockets.md).

## Next

- [Laravel Parity Map](parity.md) - feature-by-feature comparison
  against Laravel 13
- [Environment Variables](env-vars.md) - every `env!` the framework reads
- [Documentation index](documentation.md) - the chapter map


# Blog


---

<!-- https://suprnova.app/blog/introducing-suprnova-rendercache -->

Caching a page is easy.

Knowing whether you **should** cache it is harder.

Knowing when that cached page stopped being true is harder still.

Most response caches ultimately ask the application developer to answer both questions: decide which responses are safe to share, construct the right cache key, and remember which entries need to disappear when the underlying application changes.

Forget one dependency and the cache doesn't necessarily fail.

It does something worse.

It keeps working.

It just serves the wrong page.

**Suprnova RenderCache takes a different approach.**

RenderCache is Suprnova's framework-level HTTP response cache. It can store a proven-safe response from a `GET` or `HEAD` route and serve the next matching request without running your handler at all.

But the important part isn't that it caches responses.

It's that Suprnova watches the render happen.

## Opt in. Then prove it.

RenderCache is explicit.

Nothing is cached until you opt a route or group into it.

```rust
router.try_render_cache(
    "/blog",
    RenderCachePolicy::builder(RepresentationClass::PublicShared)
        .freshness(FreshnessPolicy::new(
            300_000,
            60_000,
            300_000,
        )?)
        .shared(SharedCachePolicy::SMaxAge { seconds: 300 })
        .build()?,
)?;
```

That declaration says `/blog` is intended to be a publicly shared representation with a particular freshness policy.

But declaring something cacheable doesn't make it so.

When the handler runs, RenderCache observes what happens.

Did the render read the session?

Did it depend on the signed-in user?

Did it use the negotiated locale?

Did authorization depend on a principal?

Did a model scope depend on request-specific state?

Did the handler use raw SQL whose dependencies the framework cannot identify?

RenderCache compares what the route declared with what the render actually did.

If those two stories don't agree, the response isn't stored.

The visitor still gets the correct page.

The cache simply declines it.

## Failure means rendering normally

That behavior is fundamental to the design.

Opting a route into RenderCache isn't a promise that every request will produce a cache entry.

It's a request to cache the response **when Suprnova can prove that doing so is safe**.

Suppose `/blog` reads a value from the visitor's session to display a flash message.

That means the resulting page depends on state that isn't safe to put into the shared representation.

RenderCache sees the session read.

The response becomes uncacheable.

Nothing is stored.

And `/blog` continues working exactly as it did before RenderCache existed.

Caching becomes an optimization rather than a new correctness requirement.

## The key is a declaration

A cached route doesn't really store "a page."

It stores a **representation**.

Its lookup key is derived from things the route explicitly declares: the route pattern, path parameters, declared query parameters, declared variance dimensions, the application build, and the current cache authority epoch.

If your output depends on locale, declare locale.

If it depends on the current principal, declare principal.

If `page` and `sort` change the response, declare those query parameters.

If an unexpected query parameter arrives, RenderCache doesn't quietly pretend it doesn't matter.

That request bypasses the cache.

The philosophy is deliberately conservative:

**when Suprnova can't prove two requests should receive the same representation, it doesn't make them share one.**

The [RenderCache Representations](https://suprnova.app/docs/render-cache-representations) manual goes deeper into what is actually stored, how lookup keys are constructed, public and private representations, conditional requests, freshness states, and Live shell stitching.

## Cache invalidation without `forget`

Then there is the other half of caching.

Invalidation.

Most caches expire eventually. RenderCache does too, but expiration is the backstop rather than the primary mechanism.

RenderCache uses **generations**.

While a response renders, Suprnova records the data dependencies it can identify.

A render that loads `Todo::all()`, for example, depends on the `todos` table.

The cached representation stores the generation it observed.

Later, your application writes a new Todo:

```rust
todo.save().await?;
```

That ordinary database write advances the relevant generation.

The next request can now prove that the stored representation was produced against an older version of the data.

No cache key was named.

No `forget()` call was made.

No model observer needed a hand-maintained list of pages to invalidate.

**The write is the invalidation.**

The [RenderCache Generations](https://suprnova.app/docs/render-cache-generations) manual covers this mechanism in depth, including dependency tracking, invalidation granularity, coherence checks, rebuild coordination, stale serving, and what happens when data changes while a response is being rendered.

## A hit skips the application work

When a stored representation is still current, RenderCache can answer the request without running the handler.

That means:

no handler,

no ORM query,

no template render,

no serializer,

and no body copy inside the cache engine.

The response already exists.

RenderCache only needs to establish that the representation is still current and serve it.

The result is caching at the level that actually matters to the request: the completed HTTP response.

## Fresh doesn't have to mean all or nothing

Applications also have to decide what happens during a rebuild.

RenderCache models four freshness states:

**Fresh** responses are served immediately.

**Stale-servable** responses can be returned immediately with a `Warning` header while one background rebuild refreshes the representation.

**Stale-on-error** responses trigger a foreground rebuild but can fall back to the stored representation if that rebuild fails.

**Dead** representations aren't served at all. The request renders again.

That gives an application control over the tradeoff between freshness, latency, and availability without turning those decisions into ad hoc cache logic throughout the codebase.

These states, along with `ETag`, `Cache-Control`, `Vary`, `Age`, conditional requests, and the exact shape of a stored entry, are covered in [RenderCache Representations](https://suprnova.app/docs/render-cache-representations).

## One rebuild, not a stampede

When several requests discover the same missing or outdated representation at once, RenderCache coordinates the rebuild.

One request becomes the leader.

It renders and may publish the new representation.

Requests already waiting for that key wait for the leader and then re-evaluate what was published.

And the waiter count is bounded, so an overloaded key can't create an unlimited queue.

Across multiple nodes, duplicate computation can still happen.

Conflicting publication cannot.

Rebuild leases and publication fencing make sure an older worker cannot overwrite newer authority.

The mechanics behind singleflight, waiters, publication fencing, and serving stale representations during rebuilds are documented in [RenderCache Generations](https://suprnova.app/docs/render-cache-generations).

## Public, private, and somewhere in between

Not every cacheable page is public.

RenderCache supports different representation classes.

`PublicShared` is the familiar case: one representation can be shared by everyone matching its declared variance.

`PrivateCached` stores representations partitioned by principal or tenant.

And then there is `PublicShellStitched`.

This one exists specifically for Suprnova Live.

Imagine a dashboard whose navigation, layout, headings, and surrounding document are identical for everyone—but whose Live islands belong to the signed-in user.

Caching the whole document would be unsafe.

Rendering the whole document every time throws away everything that could have been shared.

RenderCache can instead store the shared shell with typed holes where the private islands belong.

On a hit, the shell is reused while the Live islands are mounted again under the authority of the current request.

The shared bytes are cached.

The private bytes never enter the shared representation.

A page doesn't have to choose between **cache everything** and **cache nothing**.

The full representation model—including `Complete`, `Composite`, `PrivateCached`, and `PublicShellStitched` entries—is described in [RenderCache Representations](https://suprnova.app/docs/render-cache-representations).

## Memory, files, databases, or Redis

RenderCache starts small.

Its embedded profile can operate in-process, with an optional file-backed tier for representations that should survive a restart.

When an application grows to several nodes, RenderCache can move its shared storage and rebuild coordination to the database.

Or it can use Redis when latency matters more than durability.

The application-facing model doesn't change.

The same routes, policies, keys, dependency collection, and middleware flow remain in place.

More importantly, the cache tier is never the authority for whether something is current.

The database-backed generation ledger is.

Redis can disappear.

Files can be evicted.

A stored representation can be lost.

Those events cost performance.

They don't make stale content true again.

The [RenderCache Deployment](https://suprnova.app/docs/render-cache-deployment) manual covers the `embedded`, `database`, and `redis` profiles, storage tiers, rebuild coordination, environment configuration, migrations, and multi-node deployment.

## You can see what the cache is doing

Invisible caching is difficult to trust, so RenderCache also has an operational surface.

Cached responses expose standard HTTP behavior including `ETag`, `Cache-Control`, `Vary`, `Age`, and stale warnings where appropriate.

Telemetry distinguishes hits, misses, bypasses, stale responses, moved representations, and—importantly—declined renders.

When a route you expected to cache doesn't, the framework can tell you why.

RenderCache also provides body-free inspection of cached entry metadata.

And when something has gone badly wrong, an authority epoch can be advanced to make every previous cache key unreachable immediately without enumerating and deleting entries one at a time.

The cache has an emergency lever.

It doesn't share that lever with your sessions, queues, or arbitrary application cache.

For production diagnostics, telemetry, cache inspection, testing strategies, disk hygiene, emergency invalidation, and recovery procedures, see [RenderCache Operations](https://suprnova.app/docs/render-cache-operations).

## RenderCache isn't `Cache`

Suprnova still has a normal key-value cache.

`suprnova::Cache` is what you use when you know you have a value you want to compute once and reuse.

You choose the key.

You put the value in.

You decide when to remove it.

RenderCache operates at a different level.

You don't call it from your handler.

It caches completed HTTP representations.

It derives keys from route declarations.

It observes what the render depended on.

And ordinary application writes move the generations that determine whether those representations are still current.

Use `Cache` when you want to cache a value.

Use RenderCache when you want Suprnova to avoid doing the request again.

## Caching should be an optimization you can trust

Response caching has always offered an attractive bargain:

do less work and serve pages faster.

The uncomfortable part is what developers traditionally have to put on the other side of that bargain.

Did we build the right key?

Did we include every dimension?

Did we remember every invalidation path?

Can these two users actually share this response?

Did somebody add a session read six months after this route was declared cacheable?

RenderCache can't make every response cacheable.

It deliberately refuses to.

Instead, it tries to make the responses it **does** store defensible.

The route declares what should be true.

The render records what actually happened.

The framework compares the two.

The data itself tells the cache when it changed.

And when Suprnova can't account for the safety of a representation, it renders the page normally.

**Cache what you can prove. Render everything else.**

### Go deeper

- [RenderCache Representations](https://suprnova.app/docs/render-cache-representations) — representations, keys, storage layers, freshness, private caching, and Live shell stitching.
- [RenderCache Generations](https://suprnova.app/docs/render-cache-generations) — dependency tracking, automatic invalidation, coherence, and rebuilds.
- [RenderCache Deployment](https://suprnova.app/docs/render-cache-deployment) — embedded, database, and Redis profiles and multi-node deployment.
- [RenderCache Operations](https://suprnova.app/docs/render-cache-operations) — telemetry, inspection, testing, recovery, and emergency invalidation.


---

<!-- https://suprnova.app/blog/introducing-suprnova-live -->

Suprnova Live is the framework's server-driven interaction engine. A Live
component is a Rust struct whose state lives on the server, whose view is an
Askama template, and whose actions run over a signed protocol from a small
browser runtime that morphs the re-rendered HTML in place. There is no
client-side state model to keep in sync, no build tool to install to use the
shipped runtime, and no inline JavaScript in your documents.

This chapter covers the application-facing surface: authoring a component,
registering it, serving documents and islands, the security boundaries every
Live request crosses, uploads, asynchronous updates, assets, testing,
diagnostics, and recovery. Everything here uses only `suprnova::live` and
`suprnova::view`.

## Quick start

A project created by `suprnova new` is Live-ready: it ships `src/live/mod.rs`
with an empty component registry and a `routes()` function, its bootstrap
binds the registry, and `cmd/main.rs` installs the routes. Scaffold a
component, then check it:

```bash
suprnova live:make Counter
suprnova live:check
```

`live:make` writes `src/live/counter.rs` and `templates/live/counter.html`,
registers the component in `src/live/mod.rs`, and prints the next steps.
`live:check` builds your application and proves every registered view against
the integrated checker.

## Authoring a component

```rust
use suprnova::live::{LiveComponent, live};

/// A counter rendered by `live/counter.html`.
#[derive(LiveComponent)]
#[live(name = "app.counter", view = "live/counter.html")]
pub struct Counter {
    /// Current count, exposed to the view.
    #[public]
    count: u64,
}

#[live]
impl Counter {
    /// Increments the counter in response to `live:click="increment"`.
    #[action]
    pub fn increment(&mut self) {
        self.count += 1;
    }
}
```

- `name` is the registered component name. Use a dotted, kebab-case name
  such as `app.counter`; the CLI derives `<package>.<kebab>`.
- `view` is the template identity, relative to the template root.
- `#[public]` fields are rendered and carried in the signed snapshot. `#[model]`
  fields additionally accept browser proposals through `live:model`.
- `#[action]` methods are the only entry points the browser can invoke. They
  receive validated arguments and may return typed outcomes such as a
  redirect or a flash.

Every field type must implement `Default`; a fresh island starts from those
defaults unless a mount hook says otherwise.

## Views

Views are Askama templates. The template root is `templates/` unless an
`askama.toml` names other directories, so `live/counter.html` lives at
`templates/live/counter.html`:

```html
<div>
<p>Count: {{ count }}</p>
<button type="button" live:click="increment">Increment</button>
</div>
```

Directives use the closed `live:` grammar: `live:click`, `live:submit`,
`live:model`, `live:upload`, `live:key`, `live:loading`, and the rest of the
documented set. The checker proves every directive against the component:
an unknown action, an unknown model field, a raw `safe` filter, or an
accessibility violation fails `live:check` with the file, line, and column.

Documents that place islands are ordinary views declared with
`#[suprnova::view]`; the only unescaped value they accept is `TrustedHtml`
through the `trusted_html` filter.

## Registration and bootstrap

`src/live/mod.rs` owns the registry and the routes:

```rust
use suprnova::live::{LiveRegistry, RegistryError};

pub mod counter;

/// Builds the registry of every Live component in this application.
pub fn registry() -> Result<LiveRegistry, RegistryError> {
    let registry = LiveRegistry::builder()
        .register::<counter::Counter>()?
        .build();
    Ok(registry)
}
```

Bind it during bootstrap so the server, the workers, and the `suprnova
live:*` commands see the same components:

```rust
suprnova::App::singleton(crate::live::registry().expect("Live component registry"));
```

The registry is immutable once the runtime assembles. A duplicate component
name or view, or a component whose actions need validation without a
validation port, fails registration with a typed `RegistryError`.

## Routes

`Router::try_live()` installs the reserved namespace exactly once:
`/__live/v1/action`, `/__live/v1/upload`, the `/__live/v1/async/*` control
routes and WebSocket handshake, and the immutable `/__live/v1/assets/*`
routes. Startup fails if an application route can claim `/__live`.

The reserved request routes carry a strict policy: every request needs
session, origin, CSRF, principal, tenant, and rate-limit facts. The framework
records the session and the CSRF proof; your application attaches the rest
with the route guard:

```rust
use std::sync::Arc;
use std::time::Duration;

use suprnova::live::{LiveTenantMiddleware, LiveTenantResolver};
use suprnova::rate_limit::memory::InMemoryRateLimiter;
use suprnova::{AuthMiddleware, FrameworkError, RateLimitMiddleware, Request, Router, SlidingWindowConfig, async_trait};

pub fn routes(router: Router) -> Result<Router, FrameworkError> {
    let limiter = Arc::new(InMemoryRateLimiter::new());
    router.try_live_with(|guard| {
        guard
            .middleware(AuthMiddleware::optional())
            .middleware(LiveTenantMiddleware::new(Arc::new(SingleTenant)))
            .middleware(RateLimitMiddleware::new(
                limiter,
                SlidingWindowConfig { max_requests: 600, window: Duration::from_secs(60) },
                |request: &Request| format!("live:{}", request.ip().unwrap_or_else(|| "anon".into())),
            ))
    })
}

struct SingleTenant;

#[async_trait]
impl LiveTenantResolver for SingleTenant {
    async fn resolve(&self, _request: &Request) -> Result<Option<String>, FrameworkError> {
        Ok(None)
    }
}
```

Install the routes from the entry point so the runtime and the mount catalog
are ready before the first request:

```rust
Application::new()
    .bootstrap(bootstrap::register)
    .try_routes(|| live::routes(routes::register()))
    .run()
    .await;
```

## Documents and islands

A document route declares its islands once, renders them through
`LiveDocument`, and emits the bootstrap tags:

```rust
use std::collections::BTreeMap;

use suprnova::live::{CanonicalValue, LiveBootstrapOptions, LiveDocument, LiveMount, MountFlags};
use suprnova::view::{AssetSet, DocumentResponseIntent, TrustedHtml, ViewName};
use suprnova::{FrameworkError, HttpResponse, Request, Response, Router, StatusCode};

mod filters {
    pub use suprnova::view::filters::trusted_html;
}

#[suprnova::view(path = "live/page.html")]
struct Page<'a> {
    bootstrap: &'a TrustedHtml,
    counter: &'a TrustedHtml,
}

pub fn install(router: Router) -> Result<Router, FrameworkError> {
    let mount = LiveMount::<Counter>::identity_bound("/dashboard", "counter", "dashboard-counter")?;
    let handler_mount = mount.clone();
    let router: Router = router
        .get("/dashboard", move |request: Request| {
            let mount = handler_mount.clone();
            async move { render(request, &mount).await }
        })
        .middleware(AuthMiddleware::redirect_to("/login"))
        .into();
    router.try_live_mount(&mount)
}

async fn render(request: Request, mount: &LiveMount<Counter>) -> Response {
    let result: Result<HttpResponse, FrameworkError> = async {
        let mut document = LiveDocument::from_request(&request)?;
        let counter = document
            .mount(mount, CanonicalValue::Object(BTreeMap::new()), MountFlags::empty())
            .await?;
        let bootstrap = document.bootstrap(LiveBootstrapOptions::esm())?;
        document
            .render(
                ViewName::parse("live/page.html").map_err(|_| FrameworkError::internal("view"))?,
                &Page { bootstrap: bootstrap.html(), counter: counter.html() },
                DocumentResponseIntent::html(StatusCode::OK).map_err(|_| FrameworkError::internal("intent"))?,
                AssetSet::empty(),
            )
            .map_err(FrameworkError::from)
    }
    .await;
    result.map_err(|_| HttpResponse::text("Live document failed").status(500))
}
```

- `LiveMount::public_seed` declares an island any visitor may render; its
  state is a reusable seed promoted to an instance on the first action.
- `LiveMount::identity_bound` declares an island that belongs to the current
  session and principal; the document route must authenticate.
- Mount every island before `bootstrap`, and call `bootstrap` once. The
  bootstrap emits the inert configuration element and the script tags for
  the ESM or classic strategy, adding the upload and asynchronous roles when
  a mounted component needs them and the Stimulus bridge on request.
- The document template places `{{ bootstrap|trusted_html }}` in `<head>` and
  each island where it belongs.

## Security boundaries

Live never bypasses the framework's middleware. What each request needs:

| Fact | Recorded by |
|---|---|
| Session | `SessionMiddleware` |
| Origin and CSRF | `CsrfMiddleware` with origin verification enabled |
| Principal | `AuthMiddleware` on its authenticated branch |
| Tenant | `LiveTenantMiddleware` with your resolver |
| Rate limit | `RateLimitMiddleware` on its allowed branch |

The shipped runtime sends the Live media type and the browser's own
`Sec-Fetch-Site` header; it carries no session token. The CSRF middleware
verifies that proof for every Live request on its own, whatever origin policy
you configure, so a same-origin Live request passes with the stateless CSRF
disposition while a cross-site or header-less request falls back to token
validation and is refused. Ordinary routes keep token validation under the
default policy; using Live relaxes nothing else:

```rust
global_middleware!(CsrfMiddleware::new());
```

Anonymous visitors render public seeds, and they can act on them when the
guard uses `AuthMiddleware::optional()`: a signed-in principal is recorded, an
anonymous visitor continues, and the mount kind decides. A public seed then
promotes for the visitor's own session on the first action, while an
identity-bound island still refuses a request without principal evidence.
With `AuthMiddleware::new()` the guard answers `401` for every anonymous
request before any engine work. Identity-bound islands require a session and
a principal; the tenant is bound into the island's scope whenever your
resolver names one, and a resolver that cannot determine the tenant must
return an error rather than `None`. Every rejection is closed:
a `409` for a stale or tampered snapshot carries no body, and production
messages never include snapshots, tokens, cookies, or rendered HTML.

## Uploads

Declare an upload policy on a model field:

```rust
use suprnova::live::{LiveComponent, UploadPolicy, UploadReplacement, UploadScan, UploadType, live};

fn avatar_policy() -> UploadPolicy {
    UploadPolicy::builder()
        .maximum_files(1)
        .maximum_file_bytes(512 * 1024)
        .replacement(UploadReplacement::RetirePrevious)
        .accept(UploadType::Png)
        .scan(UploadScan::Disabled)
        .finalize_action("save_avatar")
        .build()
}

#[derive(LiveComponent)]
#[live(name = "app.avatar-uploader", view = "live/avatar-uploader.html")]
pub struct AvatarUploader {
    #[model]
    #[upload(policy = avatar_policy)]
    avatar: String,
}

#[live]
impl AvatarUploader {
    #[action]
    pub fn save_avatar(&mut self) {}
}
```

The view binds the field with `<input type="file" live:upload="avatar">`. The
runtime creates, transfers, and completes the upload through
`/__live/v1/upload`; the file waits in quarantine until the declared finalize
action runs, when the framework hands it to your `UploadFinalizer`. Bind the
finalizer, and any scanner or validator, before the runtime assembles:

```rust
App::singleton(LiveUploadHost::new().with_finalizer(Arc::new(AppUploadFinalizer::default())));
```

Uploads are authorized per field and control through the gate. Define the
abilities `live:<component>.upload.<field>.<Control>` for `Create`,
`Reacquire`, `Status`, `Queue`, `BeginTransfer`, `PutChunk`, `Complete`,
`Accept`, `BeginFinalize`, `CommitFinalize`, `Cancel`, `Reject`, `Expire`,
and `Fail`.

A browser that lost its transfer grant reacquires it through a route your
application owns outside the reserved namespace:

```rust
let router: Router = router
    .try_live_upload_reacquisition("/account/uploads/{handle}/reacquire")?
    .middleware(AuthMiddleware::new())
    .into();
```

The route requires the same facts as an action, answers only the session and
principal that created the upload, and returns a fresh grant with the current
transfer state.

## Asynchronous updates

A component declares the streams it listens to; the browser runtime
subscribes over SSE or WebSocket and falls back to polling:

```rust
use suprnova::live::{EventPayloadMetadata, LiveComponent, live};

pub struct ActivityPosted;

impl EventPayloadMetadata for ActivityPosted {
    const NAME: &'static str = "activity.posted";
    const VERSION: u16 = 1;
}

#[derive(LiveComponent)]
#[live(
    name = "app.activity-feed",
    view = "live/activity-feed.html",
    minimum_protocol_version = 2,
    streams(stream(name = "activity", topics("activity"), events(ActivityPosted)))
)]
pub struct ActivityFeed {
    #[public]
    headline: String,
}
```

Define the ability `live:<component>.stream.<name>` for subscribers, then
publish from anywhere in the application:

```rust
let streams = LiveStreams::resolve()?;
streams.event::<ActivityPosted>("activity", LiveEventTarget::Island, payload).await?;
streams.refresh("activity").await?;
```

A refresh tells subscribed islands to fresh-render; an event is delivered to
the island's registered handlers. Polling is the ordinary fresh render: the
island's state catches up whenever a transport is unavailable, but event
payloads published in between are not replayed to their handlers, which the
runtime reports as a degraded stream rather than a current one. A component
that declares exactly one stream gets its island root subscribed for it; a
component with several streams subscribes each through the runtime's
registered calls.

## Assets and no-build use

The framework serves the exact reviewed runtime artifacts at
`/__live/v1/assets/<identity>/<file>` with immutable caching, strong
validators, and integrity attributes in the bootstrap tags. A strict
`script-src 'self'` policy holds because documents contain no inline script.
To publish the same bytes to a CDN or a static directory:

```bash
suprnova live:assets --out public/__live
```

The publication is atomic and refuses to replace a directory whose bytes
differ unless you pass `--replace`.

## Testing

`suprnova::live::testing` prepares a router's runtime and mount catalog for
in-process tests. The application tests in `app/tests/live_*.rs` show the
complete pattern: an in-memory database, a seeded session cookie, the real
global middleware stack, and requests through `handle_request`:

```rust
let router = app::live::routes(app::routes::register())?;
let runtime = prepare_live_router_for_test(&router)?;
App::singleton(runtime.clone());
```

Decode an island's snapshot from its `data-suprnova-live-snapshot` attribute,
post an action with the session cookie and `Sec-Fetch-Site: same-origin`, and
assert on the accepted render. A stale snapshot answers `409` with an empty
body; a missing principal answers `401`.

## Diagnostics and operations

- `suprnova live:check` proves every registered view; `--allow-unproved`
  accepts dynamic structures the checker deliberately makes no claim about.
- `suprnova live:inspect` reports the bound registry, configuration limits,
  installed upload capabilities, assembled runtime services, and the asset
  identity without exposing state or secrets.
- `LiveConfig` bounds request and response bytes and the trusted context
  lifetime; bind a custom one before the runtime assembles.
- Errors carry closed kinds such as `live_document_context_rejected` and
  `invalid_live_bootstrap`; telemetry labels are closed enumerations.

## Recovery

- A `409` tells the runtime to fresh-render the island; the operation is not
  replayed.
- A closed asynchronous transport is retired and the runtime reconnects with
  a new transport generation; a stale generation is refused.
- A session that expires or rotates invalidates identity-bound work; the
  application exposes its sign-in path and the visitor continues from a fresh
  document.

Live runs complete without RenderCache. Caching Live documents is
RenderCache's job; see [RenderCache](render-cache.md).

## CLI reference

| Command | Purpose |
|---|---|
| `suprnova live:make <name>` | Scaffold a component and its view and register it |
| `suprnova live:check` | Prove every registered view with the integrated checker |
| `suprnova live:inspect` | Report safe runtime, registry, provider, and artifact state |
| `suprnova live:assets --out <dir>` | Publish the reviewed runtime artifacts atomically |


---

<!-- https://suprnova.app/blog/github-oauth-plugin-tutorial -->

# A complete guide to creating and installing an external GitHub OAuth plugin for Suprnova, configuring a GitHub OAuth App, registering the provider, and handling the callback safely.
--

### Build GitHub sign-in into a Suprnova application with a real external OAuth provider, verified primary email handling, PKCE, safe account linking, and application-grant revocation. 

GitHub sign-in looks like a small OAuth integration until you reach the email address. The basic profile endpoint returns an email only when the user made it public, and public does not mean verified. If an authentication plugin quietly treats that field as proof of account ownership, a convenient login button becomes an account-linking vulnerability.

The external [`suprnova-oauth-github`](https://github.com/eas4ai/suprnova-oauth-github) plugin handles that boundary explicitly. It uses GitHub's stable numeric user ID as the external identity, fetches the authenticated user's email list, and accepts an address only when GitHub marks it both primary and verified.

It is also a useful example of how to build against Suprnova's public OAuth SDK. The plugin lives in its own repository, depends on the published Suprnova `v1.3.2` tag, and imports everything through `suprnova::`. There is no path dependency, workspace membership, direct Magnetar dependency, or private framework hook.

This guide installs the plugin, creates the GitHub OAuth App, registers the provider, and adds the two application routes needed to sign in.

## What the plugin does

The plugin supplies two public pieces:

- `GitHubOAuthProvider` implements Suprnova's public `OAuthProvider` contract. It declares GitHub's endpoints and request shapes, maps a GitHub profile into a verified provider identity, and renders grant-revocation requests.
- `GitHubOAuthTransport` wraps Suprnova's public `OAuthHttpTransport`. It performs the two GitHub REST requests needed for identity resolution and combines their responses before the provider parses them.

Suprnova still owns the security-sensitive parts of the OAuth ceremony:

- It generates and validates state.
- It generates the PKCE verifier and sends the `S256` challenge.
- It binds the ceremony to the initiating framework session.
- It adds the bearer `Authorization` header to user-information requests.
- It applies the configured account-linking and factor-gate policies.
- It creates the application session after the provider identity has been verified.

The provider never performs network I/O inside `resolve_identity`. The host transport performs the network calls, which keeps the plugin on the same public boundary used by every other external Suprnova provider.

You can learn how to build a plugin here: 
[https://github.com/eas4ai/suprnova-oauth-github/blob/main/BUILDING.md](https://github.com/eas4ai/suprnova-oauth-github/blob/main/BUILDING.md)

## Why GitHub email needs two requests

GitHub's authenticated-user endpoint is:

```text
GET https://api.github.com/user
```

That response includes a stable numeric `id`, the mutable `login`, and profile fields such as `name`. Its `email` field is populated only when the user made an address public. It does not carry a separate verification flag.

The plugin also requests:

```text
GET https://api.github.com/user/emails?per_page=100
```

That endpoint requires the `user:email` scope and returns `primary` and `verified` for each address. The plugin accepts exactly one address matching both conditions:

```json
{
  "email": "developer@example.com",
  "primary": true,
  "verified": true,
  "visibility": "private"
}
```

A public but unverified address is ignored. A verified secondary address is also ignored. If GitHub does not return one verified primary address, the provider returns no email and Suprnova fails closed instead of guessing.

## Create a GitHub OAuth App

Create one OAuth App for each environment whose callback URL differs.

1. Open [GitHub Developer settings](https://github.com/settings/developers).
2. Select **OAuth Apps**.
3. Select **New OAuth App**.
4. Enter your application's public URL as the **Homepage URL**.
5. Enter the callback route as the **Authorization callback URL**. For example:

   ```text
   https://app.example.com/auth/github/callback
   ```

6. Create the app.
7. Generate a client secret.
8. Store the client ID and secret in your deployment's secret manager.

The callback URL in your application configuration must match the URL registered with GitHub.

## Add the dependencies

Add the released plugin and the Suprnova SDK tag it targets:

```toml
[dependencies]
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v1.3.2" }
suprnova-oauth-github = { git = "https://github.com/eas4ai/suprnova-oauth-github.git", tag = "v0.1.0" }
url = "2"
```

The `url` dependency decodes the callback query string in the controller below. The provider itself uses `suprnova::SecretString`, so the application does not need a direct Magnetar dependency.

## Configure the environment

Add these values to your local environment and production secret configuration:

```dotenv
GITHUB_OAUTH_CLIENT_ID=your_github_oauth_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
GITHUB_OAUTH_REDIRECT_URI=https://app.example.com/auth/github/callback
GITHUB_OAUTH_USER_AGENT=example-app/1.0 (security@example.com)
```

GitHub requires a `User-Agent` on REST requests. Use a stable product identifier and a monitored contact address. Do not put credentials in the value.

## Register GitHub during bootstrap

Register GitHub on the same `MagnetarConfig` that initializes the rest of your authentication stack. Suprnova builds the OAuth service first, then publishes password, passkey, and OAuth engines atomically. If any part of initialization fails, none of the engines becomes visible.

```rust
use std::env;
use std::sync::Arc;

use suprnova::{
    App, AutoLinkPolicy, DB, FrameworkAbuseLimiter, FrameworkError,
    MagnetarConfig, MagnetarOAuthHostConfig, MagnetarOAuthProviderConfig,
    OAuthAuthorizationConfig, OAuthHttpTransport, RateLimiterDriver,
    ReqwestOAuthTransport, SecretString, init_magnetar,
};
use suprnova_oauth_github::{
    GitHubEndpoints, GitHubOAuthProvider, GitHubOAuthTransport,
    GitHubProviderConfig,
};

pub async fn register_github_oauth() -> Result<(), FrameworkError> {
    let client_id = required_env("GITHUB_OAUTH_CLIENT_ID")?;
    let client_secret = required_env("GITHUB_OAUTH_CLIENT_SECRET")?;
    let redirect_uri = required_env("GITHUB_OAUTH_REDIRECT_URI")?;
    let user_agent = required_env("GITHUB_OAUTH_USER_AGENT")?;
    let endpoints = GitHubEndpoints::default();

    let base: Arc<dyn OAuthHttpTransport> =
        Arc::new(ReqwestOAuthTransport::try_default()?);
    let transport = Arc::new(
        GitHubOAuthTransport::try_new(base, endpoints.clone())
            .map_err(|error| FrameworkError::internal(error.to_string()))?,
    );
    let provider = Arc::new(
        GitHubOAuthProvider::try_new(
            GitHubProviderConfig {
                client_id,
                client_secret: SecretString::from(client_secret),
                user_agent,
                endpoints,
            },
            transport.clone(),
        )
        .map_err(|error| FrameworkError::internal(error.to_string()))?,
    );
    let limiter = Arc::new(FrameworkAbuseLimiter::new(
        App::resolve_make::<dyn RateLimiterDriver>()?,
    ));
    let oauth = MagnetarOAuthHostConfig::new(
        vec![MagnetarOAuthProviderConfig {
            provider,
            redirect_uri,
            scopes: vec!["user:email".to_owned()],
        }],
        transport,
        limiter,
        OAuthAuthorizationConfig::default(),
        AutoLinkPolicy::default(),
    )
    .map_err(|_| {
        FrameworkError::internal("invalid GitHub OAuth host configuration")
    })?;

    let database = DB::connection()?;
    init_magnetar(
        MagnetarConfig::from_sea_orm(database.inner().clone()).oauth(oauth),
    )
    .await
}

fn required_env(name: &'static str) -> Result<String, FrameworkError> {
    env::var(name)
        .map_err(|_| FrameworkError::internal(format!("{name} is not set")))
}
```

Call `register_github_oauth().await` during application bootstrap after the database, encryption key, session store, and rate-limiter driver have been registered. Call `init_magnetar` only once.

`ReqwestOAuthTransport::try_default()` gives the plugin the framework's production HTTP posture: redirects are disabled, requests time out after 30 seconds, responses are limited to 1 MiB, and a default Suprnova `User-Agent` is available. The provider-specific value from `GITHUB_OAUTH_USER_AGENT` is sent on GitHub REST requests.

`FrameworkAbuseLimiter` uses the application's configured `RateLimiterDriver`. Production deployments normally use the shared Redis driver, so OAuth start attempts are limited consistently across application processes.

## Add the routes

The application owns the HTTP routes. Add one route to start the ceremony and one for GitHub's callback:

```rust
get!("/auth/github", controllers::github_oauth::start),
get!(
    "/auth/github/callback",
    controllers::github_oauth::callback
),
```

Apply `SessionMiddleware` to both routes. Suprnova binds the OAuth ceremony to a digest of the initiating session. Moving the callback to another browser session causes validation to fail.

## Add the controller

Create `src/controllers/github_oauth.rs`:

```rust
use std::collections::HashMap;

use suprnova::{
    Auth, FrameworkError, HttpResponse, Request, Response,
};

pub async fn start(_request: Request) -> Response {
    start_inner().await.map_err(HttpResponse::from)
}

async fn start_inner() -> Result<HttpResponse, FrameworkError> {
    let kickoff = Auth::oauth("github").begin().await?;

    Ok(HttpResponse::new()
        .status(302)
        .header("Location", kickoff.authorization_url))
}

pub async fn callback(request: Request) -> Response {
    callback_inner(request).await.map_err(HttpResponse::from)
}

async fn callback_inner(
    request: Request,
) -> Result<HttpResponse, FrameworkError> {
    let params = query_parameters(&request);
    if params.contains_key("error") {
        return Err(FrameworkError::bad_request(
            "GitHub authorization was denied",
        ));
    }

    let code = params
        .get("code")
        .ok_or_else(|| {
            FrameworkError::bad_request("missing GitHub OAuth code")
        })?;
    let state = params
        .get("state")
        .ok_or_else(|| {
            FrameworkError::bad_request("missing GitHub OAuth state")
        })?;

    let (_user, _session) = Auth::oauth("github")
        .complete(code, state)
        .await?;

    Ok(HttpResponse::new().status(302).header("Location", "/"))
}

fn query_parameters(request: &Request) -> HashMap<String, String> {
    url::form_urlencoded::parse(
        request.query().unwrap_or("").as_bytes(),
    )
    .into_owned()
    .collect()
}
```

`begin()` persists a single-use ceremony, generates state and PKCE values, and returns GitHub's authorization URL. The controller only has to redirect the browser.

`complete()` exchanges the callback code, validates the session-bound state, fetches the GitHub profile and email list, resolves the linked identity, applies account-link and factor policy, rotates the framework session, and returns the application user and Magnetar session values.

## What GitHub receives

The authorization redirect includes:

- `client_id`
- `redirect_uri`
- `scope=user:email`
- An unguessable `state`
- A PKCE `code_challenge`
- `code_challenge_method=S256`

The token exchange sends the single-use code, the original redirect URI, the PKCE verifier, the client ID, and the client secret as a form-encoded request. It asks GitHub for a JSON response with `Accept: application/json`.

The profile and email requests include:

```text
Authorization: Bearer <access-token>
User-Agent: example-app/1.0 (security@example.com)
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2026-03-10
```

Suprnova, not the provider, adds the bearer header. The SDK rejects any provider that tries to replace it.

## Handle a missing verified primary email

Most GitHub accounts have a verified primary address, including accounts that keep it private. The `user:email` scope lets the plugin verify that private address without making it public.

If GitHub does not return exactly one verified primary address, the plugin returns `email: None`. `Auth::oauth("github").complete(...)` then returns an HTTP `409 Conflict` response with this message:

```text
OAuth identity requires verified email completion
```

A basic application can ask the user to verify a primary address in GitHub and restart sign-in. If your application already has a separate verified-email completion or explicit account-linking flow, route the conflict into that flow. Do not weaken the provider by trusting `GET /user`'s public email field or a secondary address.

## Account linking stays explicit

The default `AutoLinkPolicy` does not silently attach a GitHub identity to an
existing account merely because the email strings match. This applies whether
the existing account's email is verified or still unverified. The authenticated
owner must explicitly authorize the link.

The verified primary email still matters for safe new-account creation. When
no account owns that normalized address, Magnetar can create the application
user and linked GitHub identity through its verified-provider transaction. A
matching existing account instead produces the explicit-link outcome rather
than transferring ownership.

GitHub's numeric `id` remains the provider subject throughout this process. A user can rename their GitHub login without creating a second application identity.

## Revoke the GitHub grant

GitHub revocation is not the generic RFC 7009 form. The plugin sends the application-grant request GitHub documents:

```text
DELETE /applications/{client_id}/grant
Authorization: Basic base64(client_id:client_secret)
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2026-03-10
Content-Type: application/json

{"access_token":"..."}
```

GitHub removes the application's grant and all OAuth tokens associated with that user. Version `0.1.0` does not enable GitHub's optional expiring-token and refresh-token mode.

## Test the complete flow

1. Start the application with the four `GITHUB_OAUTH_*` values set.
2. Open `/auth/github` in a browser.
3. Approve the `user:email` scope on GitHub.
4. Confirm that GitHub returns to the exact callback URL registered for the OAuth App.
5. Confirm that the callback signs the user in and redirects to `/`.
6. Sign out and repeat the flow.
7. Confirm that the second sign-in resolves the same account, even if the GitHub login has changed.

Do not test by inventing a callback `code` and sending it directly. Start the flow through the same browser session so state and PKCE validation exercise the real boundary.

The plugin repository also carries an offline integration suite. It drives `Auth::oauth("github").begin()` and `verify_oauth_identity(...)` through the public Suprnova engine against an in-process mock GitHub server. The test verifies the token exchange, PKCE, required headers, `/user`, `/user/emails`, and identity mapping without contacting GitHub.com.

Run the project checks with:

```bash
cargo fmt --all --check
cargo clippy --all-targets
cargo test --all-targets
cargo check --example suprnova_app
```

## Use GitHub Enterprise Server

Compatible GitHub Enterprise Server installations can use explicit endpoints:

```rust
let endpoints = GitHubEndpoints {
    authorization: "https://github.example.com/login/oauth/authorize".into(),
    token: "https://github.example.com/login/oauth/access_token".into(),
    user: "https://github.example.com/api/v3/user".into(),
    emails: "https://github.example.com/api/v3/user/emails?per_page=100".into(),
    revocation: concat!(
        "https://github.example.com/api/v3/applications/",
        "{client_id}/grant",
    )
    .into(),
};
```

The plugin requires HTTPS outside loopback tests. The user and email endpoints must share the same origin because the transport forwards the same bearer token to both.

Confirm that your GitHub Enterprise Server version supports PKCE and the configured REST API version before deployment. The plugin sends `X-GitHub-Api-Version: 2026-03-10` in version `0.1.0`.

## The external SDK boundary is the point

The implementation is intentionally ordinary. A developer can reproduce its dependency graph from the public tags:

```text
suprnova v1.3.2             10d94d2d
suprnova-oauth-github v0.1.0 96ad9926
```

A clean consumer project using those two Git tags compiles the provider, transport, limiter, and `MagnetarOAuthHostConfig` without access to either repository's workspace. The plugin's source firewall rejects a direct Magnetar dependency, a path dependency, or a Magnetar import.

That gives Suprnova applications a real GitHub sign-in option today, and it demonstrates the contract every external OAuth provider can use: provider-specific proof at the edge, host-owned transport and session authority, and no private shortcut between them.

Install the plugin from [GitHub](https://github.com/eas4ai/suprnova-oauth-github) or start with its [complete README tutorial](https://github.com/eas4ai/suprnova-oauth-github#readme).

---

<!-- https://suprnova.app/blog/introducing-magnetar-suprnova-authentication -->

# Announcing Magnetar - Authentication to power your applications

### Magnetar is the authentication engine inside Suprnova. It handles passwords, passkeys, two-factor codes, magic links, and sign-in with Google, Apple, Facebook, X, and TikTok, and it is built around one idea: auth doesn't have to be confusing or hard.

Every web application needs to answer the same question thousands of times a day: is this really the person they say they are? Getting that wrong is how accounts get taken over, and most of the ways it goes wrong are not exotic. They are small gaps between features that were each built correctly on their own.

Magnetar is the authentication engine inside Suprnova. It ships with the framework, you turn it on with a few lines in your bootstrap, and from then on passwords, passkeys, two-factor codes, magic links, sign-in with Google, Apple, Facebook, X, and TikTok, remember-me, email verification, and password reset all run through one engine that was designed to close those gaps.

```rust
use suprnova::{DB, MagnetarConfig, PasskeyConfig, init_magnetar};

DB::init().await?;
let db = DB::connection()?;

let config = MagnetarConfig::from_sea_orm(db.inner().clone())
    .passkey_config(PasskeyConfig {
        rp_id: "example.com".to_owned(),
        rp_origin: "https://example.com".to_owned(),
    });

init_magnetar(config).await?;
```

That is the whole installation. Magnetar checks that your application key is set, creates or upgrades its tables, and publishes the password and passkey engines in one step. If any part of that setup is invalid, nothing is written to the database. Then `Auth::password().register(...)` and `Auth::password().authenticate(...)` work, and the rest of the framework's auth facades sit on top.

## Why we built it

Suprnova already had the Laravel-shaped auth surface: guards, a user provider, `Auth::login`, password reset. What it did not have was a single place where the security rules lived. Password hashing was in one module, session revocation in another, "what happens when someone changes their password" in a third. Each piece was fine. The joints between them were where an attacker would look.

So we built the joints as the product. Magnetar is a separate crate in the Suprnova workspace, with no HTTP, no cookies, and no knowledge of your routes. The framework owns those. Magnetar owns the decisions: who is allowed to start a session, when every session for a user stops being valid, what a password check is allowed to reveal, and what has to happen atomically when someone proves they own an email address.

## What it does

Here is what is implemented today, not planned. Each of these is a working service with its own tests.

- **Passwords**, with lockout after repeated failures and a hashing policy that upgrades old hashes automatically.
- **Passkeys** (WebAuthn), for sign-in without a password.
- **Two-factor codes** (TOTP) with recovery codes.
- **Magic links** sent by email.
- **Sign-in with Google, Apple, Facebook, X, and TikTok**, plus an OAuth engine that also handles device authorization for TVs and CLIs, refresh tokens, revocation, and a token cache for calling third-party APIs on the user's behalf.
- **Sessions**, either opaque tokens stored in the database or signed JWTs, plus remember-me.
- **Email verification** and **password reset**.
- **Linked accounts**, so one person can sign in several ways.
- **A migration engine** for bringing an existing user table into Magnetar without rewriting your IDs.

Magnetar does not send email. It produces the message shapes (verification, reset, password-changed, magic link) and your application sends them through Suprnova's mail system, which means your templates and your provider stay yours.

### Everything runs in your application

There is no third-party authentication service behind Magnetar. It is a library that runs inside your process against your own database. Passwords are hashed and checked on your server. Passkeys are registered and verified there. Magic-link and reset tokens are minted, encrypted, and consumed there. Sessions live in your database or in JWTs you sign. When a user enables two-factor, Magnetar generates the secret, the `otpauth://` link, and the QR code image itself, in-process, so the user scans it straight off your page into Google Authenticator, 1Password, or whatever they use. The secret never leaves your box to get drawn.

The only outside parties are the ones you choose: the social sign-in providers you enable, Redis if you use it for rate limiting, and the mail provider you already have. Nothing about identity is outsourced by default.

## How the plugins work

Every sign-in method in Magnetar is a plugin: password, passkey, two-factor, magic link, email verification, password management, device authorization, and one plugin per social provider. Each plugin is mirrored one-to-one by a Cargo feature, so a method you don't use costs nothing in your binary. The first-party plugins are built on the same public SDK that third-party authors get. They have exactly one privilege the SDK does not hand out: at the moment a user proves who they are, a first-party plugin may mint a verified principal. Everything after that point is the same for everyone.

A plugin is a small, explicit contract:

- **It declares its routes.** Each route has a method, a path template, and a stable name like `password.login`, plus the feature that owns it. The framework mounts them. A plugin cannot register a route the host did not agree to.
- **It validates itself at boot.** `init` runs once with the host's configuration. If a plugin's settings are wrong, the application fails to start rather than failing a user later.
- **It can run before every request.** A plugin's `before_request` hook can let a request continue, answer it directly, or ask the host to resolve a bearer token. That is how API token authentication is wired in: the plugin recognizes the credential, the host decides what session it maps to.
- **It handles its own requests.** `handle` receives a request and returns a response plus a list of typed effects.
- **It can subscribe to lifecycle events.** After a mutation commits, plugins receive `UserCreated`, `UserDeleted`, `SessionCreated`, or `SessionDeleted` with a stable mutation ID, so a retry never fires twice.

The interesting part is what a plugin is given and what it is not. Through its context, a plugin can read and write its own tokens and ceremonies, ask questions about sessions, call the abuse limiter, encrypt values, hand a mail message to the host, make outbound HTTP calls, and generate links. It is not given a way to create a session.

Here is how a login actually finishes. The password plugin checks the credential, then asks the host's factor gate whether this sign-in may become a session. The gate answers one of two ways: session allowed, with a grant the host issued, or factor required, with a pointer to the challenge the user still has to pass (a TOTP code, for example). The plugin puts that grant into its response as an `EstablishSession` effect, and the framework turns the effect into a cookie or a bearer token. The plugin never touched a session; it carried a grant the host minted.

The other effects follow the same pattern. `ClearSession`, `IssueRemember`, `Redirect`, `SetHeader`, `SetStatus`, and `Json` are descriptions of what should happen, and the framework decides how they happen for its carrier. That is what lets the same plugin serve a cookie-based web app and a bearer-token API without knowing which one it is in.

If you want to add a sign-in method Magnetar doesn't ship, you write one of these. You get the same storage, limiter, encryption, mail, and HTTP boundaries the first-party plugins use, and the same wall in front of session minting.

## The guarantees, in plain language

This is the part that matters. These are not settings you can forget to enable. They are how the code is written, and each one has a test that fails if it stops being true.

### Change your password and every old session is invalidated

Every user has a session assigned id on their account that Magnetar calls the `auth epoch`. Every session, remember-me cookie, and JWT records the epoch it was issued under. When you reset your password, the epoch is assigned inside the same database transaction that writes the new hash. Any session still carrying the old epoch is rejected the next time it shows up. There is no background job to run and no cache to clear.

Logging out of one browser does not touch the epoch. Only you, from one device, are affected. That distinction is deliberate.

### Checking a password takes the same time whether or not you exist

A classic leak: the server responds faster for an email it has never seen, because there is no hash to check. Magnetar's verifier does one bcrypt computation and one Argon2 computation on every attempt, no matter what. If the account exists, its real hash is checked in whichever format it is stored in and a warmed dummy is run in the other. If the account does not exist, both dummies run. From the outside, "wrong password", "locked account", and "no such user" cost the same and say the same thing.

The Argon2id lane is the target. If a user's hash is still bcrypt from an older system, it is upgraded after a successful login. Bcrypt is never used to create new hashes, and a failed upgrade never turns a correct password into a failed login.

### The first proof of your mailbox wipes out squatters

Suppose someone registers with your email address before you do. They cannot verify it, but they might set up a password, enroll a two-factor device, or link a social account, hoping you will inherit it. Magnetar treats the first successful proof of mailbox ownership on an unverified account (a password reset, a magic link, or a verified email from a sign-in provider) as a clean slate. In one transaction it deletes that account's provider tokens, linked accounts, auth methods, and two-factor enrollment, revokes every session and remember-me token, writes your new credential, and marks the email verified. The squatter's setup does not survive the moment you show up.

### Signing in with Google never silently attaches to an existing account

If you already have an account with `you@example.com` and someone signs in through a provider that reports the same address, Magnetar does not link them. The default policy requires an explicit link by the authenticated owner. An unverified provider email is treated as if it were absent, so it never even reaches the matching step.

### Two-factor is a factor, not a door

A correct TOTP code can never start a session by itself. It only satisfies a gate on a session that a real sign-in method already opened. Codes are checked in constant time, each time step can be claimed once so a code cannot be replayed, and recovery-code lookups take the same time whether or not there is a match.

### Rate limiting fails closed

Magnetar's abuse limiter is a contract, and the contract says a backend failure is an error, never an allow. The shipped Redis driver honors that, and its keys are hashes, so raw email addresses and tokens never appear in Redis. If the limiter is down, sending reset links and registering new accounts stops until it is back, rather than quietly becoming unlimited.

### Only one place can mint a session

Providers and plugins, including the first-party ones, cannot create a session. There is exactly one internal issuer, it has no public constructor, and the approval it requires is private to the crate. A plugin can ask questions about sessions. It cannot make one.

## Bringing your existing users

Most applications already have a `users` table. Magnetar does not require you to move off it.

If your app uses Suprnova's Eloquent user provider and your user model implements `MustVerifyEmail` and `CanResetPassword`, email verification and password reset for verified accounts work without Magnetar installed at all. This is what Suprnova's own dogfood application does. Magnetar becomes required when you want the clean-slate behavior above for unverified accounts, or when you want Magnetar to own credentials and sessions.

If you do want to move, the migration engine reads your existing table shape, asks you to confirm it, does a dry run, and then applies. It never invents new public identifiers for your users. Existing bcrypt hashes keep working on day one and upgrade to Argon2id as people log in. If two legacy rows normalize to the same email, the migration lists every owner and stops before writing anything.

## What it will not do for you

Magnetar is deliberately narrow about ownership. It does not define your routes, your cookies, or your mail templates. It does not send unprompted product email. It does not decide which pages require a verified email; that stays in your middleware. It does not provide an in-memory rate limiter for production, because a limiter that lives in one process is not a limiter. And it does not model multi-tenancy; that is an application concern.

## Getting started

Magnetar ships with Suprnova v1.3.1. The bootstrap chapter of the manual walks through `init_magnetar`, the passkey configuration, rate-limiting setup, and the OAuth provider plugins. The API starter kit uses Magnetar's `app_users` schema out of the box; the full-stack kit uses the provider fallback and can adopt Magnetar when you need it.

We built Magnetar because authentication is the part of every application that everyone rewrites and nobody wants to own. Now Suprnova owns it, and the rules are in code where a test can hold them.

---

<!-- https://suprnova.app/blog/from-graph-rag-to-budgeted-graph-walk -->

## An AST and ASG context engine for coding agents, revised for 2026

*[Shawn McAllister](https://eas4ai.com). This is a revision of the March 2025 explainer that I created for a research repo [davila7/ast-asg-graph-rag](https://github.com/davila7/ast-asg-graph-rag/blob/main/mcts-rl-rust-example.md) by [Daniel Avila](https://x.com/dani_avila7). 

---

In March 2025 I wrote an explainer about using abstract syntax trees and abstract semantic graphs to feed a coding assistant better context. The core of it was a Rust design: parse code with tree-sitter, build a semantic graph of symbols and references, store it in LMDB and LibSQL, and use Monte Carlo Tree Search with a depth-aware UCT to decide which parts of the graph an assistant should see for a given task.

Eighteen months later the graph is still right. Almost everything around it has changed. The consumer of the context is no longer a chat box with a small window; it is an agent with tools, a million-token window behind a prefix cache, and the ability to go and read code itself. The question the 2025 design answered, how do we fit the right code into the prompt, has mostly stopped being asked. The questions that replaced it are harder: how do we keep an agent from reading the wrong code, how do we answer structural questions the agent cannot answer by grepping, and how do we know whether any of it helped.

This revision keeps what held up, replaces what the ecosystem replaced, and adds the two things that did not exist in 2025: a real reward signal, and a GPU that is no longer idle.

## What held up

The distinction between an AST and an ASG is the same as it was. An AST is the syntactic shape of one file; an ASG is a directed graph of semantic entities, functions, types, variables, modules, with edges for calls, references, implementations, and data flow. The AST is cheap and local. The ASG is expensive and global, and it is the only one that can answer "what breaks if I change this signature."

That question is the whole reason to build the engine. Agentic search, the pattern where the model greps, reads, and follows its own curiosity, beat embedding retrieval for code during 2025, and it deserved to. But grep cannot find callers through a trait object, cannot follow a generic through three crates, and cannot tell you that a change to a route handler's return type reaches an Inertia page two directories away. Those are graph queries. The ASG answers them in one hop. Everything else in this document is in service of making that hop cheap, current, and trustworthy.

The Rust builder from 2025, tree-sitter parsing into a `petgraph` `DiGraphMap` keyed by symbol, also holds up. What changed is where the semantics come from.

## What the substrate looks like now

In 2025 the builder derived types and references itself. That was necessary then and is a liability now, because the language servers got there first. rust-analyzer and tsserver expose definitions, references, implementations, and call hierarchy over LSP, and they are maintained by people whose entire job is keeping that analysis correct. Deriving the same facts in a side project means being wrong in all the places they are right.

The modern ASG is therefore three layers. tree-sitter for syntax, because it is fast, incremental, and language-agnostic. LSP for semantics, because the compiler's own view of references and types is the one the code will be judged by. And SCIP, Sourcegraph's code intelligence protocol, as the persisted and interchange form, because an index that can be written once and read by any tool is worth more than a bespoke graph file. The builder's job shrinks to stitching: syntax from tree-sitter, edges from LSP, serialization through SCIP, and the graph in memory for traversal.

```rust
pub struct AsgBuilder {
    parser: tree_sitter::Parser,
    lsp: LspClient,              // rust-analyzer, tsserver, or both
    graph: DiGraphMap<SymbolId, EdgeKind>,
    index: ScipWriter,
}

impl AsgBuilder {
    pub fn ingest(&mut self, file: &Path, source: &str, prev: Option<&Tree>) -> Result<Tree> {
        let tree = self.parser.parse(source, prev).ok_or(Error::Parse)?;
        for symbol in symbols_in(&tree, source) {
            let id = self.graph_node(&symbol);
            for r in self.lsp.references(&symbol)? {
                self.graph.add_edge(self.graph_node(&r), id, EdgeKind::References);
            }
            for c in self.lsp.incoming_calls(&symbol)? {
                self.graph.add_edge(self.graph_node(&c), id, EdgeKind::Calls);
            }
            self.index.record(&symbol, &self.graph);
        }
        Ok(tree)
    }
}
```

Two properties matter more than they did in 2025. The graph must be incremental, because the consumer is now an agent making five hundred edits in an afternoon, and a full re-index per edit is a non-starter; tree-sitter's incremental parse takes the previous tree and a diff, and the LSP servers are already incremental. And the graph must be versioned by commit, because an agent's run has a lineage, and "the graph as of version 12" is a question the run will ask. Git is already the version store; the index just needs to carry the commit it was built from.

## Storage, simplified

The 2025 diagram had LMDB for documents, symbols, and references, and LibSQL for a separate vector store and semantic index. LMDB stays; it is the right shape for a symbol table that is read far more than written. The separate vector store goes away, because LibSQL now has native vector search, and a table with a vector column beside the symbol row is simpler than two stores that have to agree. No Postgres, then or now. One file per repository, versioned by commit, rebuildable from the source tree and the index.

## From Graph RAG to tools

The biggest change is in the architecture diagram, and it is a change in who is in charge. In 2025 the engine retrieved chunks and prepended them to the prompt. The model was a passenger. In 2026 the model is the driver, and the engine is a set of tools it can call when grep is not enough.

That means the HTTP and LSP-bridge server from the original diagram becomes an MCP server exposing a small, structural surface:

- `callers(symbol)` and `callees(symbol)`: one hop in each direction, with file and line.
- `impact(symbol, change)`: the transitive set of symbols a signature or type change reaches, ranked by distance.
- `context(query, budget)`: the budgeted graph walk described below, returning a ranked set of nodes by reference, not by value.
- `graph_at(commit)`: pin the graph to a lineage version.

Returning by reference matters. In 2025 the engine inlined code into the prompt because the model could not fetch it. Today the model has `read`; the engine should tell it where to look and why, and let it decide whether to look. That keeps the engine's output small, keeps the model's context under its own control, and makes the engine useful to every agent that speaks MCP, which in August 2026 is all of them.

```mermaid
flowchart TB
    Agent[Coding agent: Claude Code, OMP, Codex, suprnova-coder] -->|MCP| Engine[Context engine]
    Engine --> Tools[callers / callees / impact / context / graph_at]
    Tools --> Walk[Budgeted graph walk]
    Walk --> Graph[(ASG in memory)]
    Graph --> LMDB[(LMDB: symbols, refs)]
    Graph --> LibSQL[(LibSQL: vectors, metadata)]
    Builder[Builder] --> Graph
    TS[tree-sitter] --> Builder
    LSP[rust-analyzer / tsserver] --> Builder
    Builder --> SCIP[(SCIP index, per commit)]
    Watcher[File watcher] --> Builder
    Journal[(Run journal)] -.->|outcomes| Walk
```

## The budgeted graph walk

Here is the part of the 2025 design that survives with a new name. The context tool has a budget, a number of nodes or tokens the agent is willing to spend, and a graph that is far larger than the budget. Something has to choose. The original used MCTS with a depth-aware UCT, and the formula still does the job:

```
UCT(s, a) = V(s, a) + C · sqrt(ln N(s) / N(s, a)) + α · e^(−β(d − 1)) − γ · sqrt(d)
```

The first two terms are standard: a value estimate and an exploration bonus. The two depth terms are the part specific to code. The exponential bonus is full strength at depth 1 and decays fast, so the walk strongly prefers the immediate neighbors of the symbol under edit. The square-root penalty grows without bound but slowly, so a deep path is never forbidden, just progressively more expensive. Together they encode something that is true of code and not of game trees: relevance falls off with graph distance, quickly at first, then slowly, and a node five hops out needs a very high value estimate to earn a place in the window.

What changed is the framing. In 2025 this was "MCTS picks what the assistant thinks about," which reads oddly now that reasoning models do their own search at inference time. The honest 2026 description is a budgeted traversal policy: given a seed symbol, a budget, and a value function, walk the graph and return the best set of nodes the budget allows. The formula is the policy. The seed comes from the agent's query, resolved through the same LSP the builder used.

## A real reward signal

The 2025 reward was a weighted sum of proxies: context relevance, workspace coverage, change proximity, symbol relevance, semantic similarity. Proxies were all that was available, because nothing downstream said whether the context had helped.

A coding harness with a scorer changes that. If an agent's attempts are evaluated, by tests, by a benchmark, by a verify gate that passes or fails, then every attempt produces a label: the context the agent used, and whether the attempt was accepted. That is a real reward, and `V(s, a)` can be learned from it. A node that appeared in the context of accepted attempts earns value; a node that appeared in the context of discarded attempts loses it; the depth prior stays as the shape, and the learned value fills in the content.

The "change proximity" and "change history" terms from 2025 become concrete in the same move. A harness keeps a journal of what each attempt touched. The walk's value function reads it. The context for attempt 212 is weighted by what attempts 1 through 211 changed, which is the memory-aware retrieval the original reward was reaching for without a place to store the history.

This is the single largest update in the document, and it only became possible because the harness exists to close the loop. The engine proposes context; the scorer judges the result; the journal carries the verdict back.

## Compute, pruned

The 2025 document spent a third of its length on SIMD: `std::simd` with `f32x8`, an AVX2 tutorial, a hybrid CPU strategy, and a `#[cfg(feature = "cuda")]` kernel with a fallback. Most of that can go.

`std::simd` is still experimental as of [1.98.0](https://doc.rust-lang.org/std/simd/index.html). The stable answer is [thermite](https://github.com/raygon-renderer/thermite): trait-generic kernels over `GenericVector → NumericVector → FloatVector`, runtime dispatch with `dispatch_dyn!`, and a `#[thermite::dispatch]` attribute that propagates target features across function boundaries, which is the exact mistake that makes hand-rolled `target_feature` code silently fall back to scalar when the hot loop calls a helper. SSE2 through AVX2 plus FMA on x86, NEON on AArch64, wasm SIMD128, scalar fallback always. No AVX-512 yet, which matters on a server and not on a desk. The cosine kernel is written once:

```rust
#[thermite::dispatch]
fn cosine<V: FloatVector>(a: &[V::Element], b: &[V::Element]) -> V::Element {
    let (mut dot, mut na, mut nb) = (V::zero(), V::zero(), V::zero());
    for (ca, cb) in a.chunks_exact(V::NUM_ELEMENTS).zip(b.chunks_exact(V::NUM_ELEMENTS)) {
        let (x, y) = (V::load_unaligned(ca), V::load_unaligned(cb));
        dot = x.mul_add(y, dot);
        na = x.mul_add(x, na);
        nb = y.mul_add(y, nb);
    }
    dot.sum() / (na.sum() * nb.sum()).sqrt()
}
```

The CUDA path is replaced by [wgpu](https://github.com/gfx-rs/wgpu): WGSL compute shaders over Vulkan, Metal, and DX12, no CUDA toolchain, and it runs on the AMD and Apple machines the 2025 design excluded. The split between the two is by batch size. Per-query scoring, a few thousand candidate nodes against one embedding, stays on thermite; the GPU round-trip costs more than the math. Graph-wide work goes to wgpu: re-embedding a repository after a large diff, periodic clustering, all-pairs similarity for link discovery. That is where there are millions of dot products and the transfer is amortized.

Embeddings themselves come from a named 2026 model, Qwen3-Embedding or a code-specific model of similar vintage, served by whatever inference server already owns the GPU, rather than from an unnamed "embedding store."

## The GPU is not idle anymore

This is the second thing that did not exist in 2025. The local inference engines that make a 35B mixture-of-experts model run at 100 tokens per second on a gaming GPU do it by filling VRAM: an expert cache, a KV cache, and elastic reallocation between them. A context engine that grabs a gigabyte for a wgpu job in the middle of a run will stall the model or get evicted.

So GPU maintenance has to be scheduled, not just run. Either it happens between attempts, when the harness knows the worker is parked, or it asks the inference engine's memory API to yield first. A conductor that already tracks worker state has this information; the context engine's background jobs become one more thing the journal tells it when to do.

## Prefix caching changes retrieval order

One more 2026 fact with a 2025-shaped consequence. Prompt prefix caching is now standard, and the newer edge engines go further with semantic checkpoints so that tool calls and thinking blocks do not force a full recompute. Retrieval that prepends fresh context every turn invalidates the cache every turn, and the cost shows up as prefill latency on every attempt.

The fix is ordering. Stable material first: system prompt, glossary, lessons, the standing knowledge roots. Volatile material last: the nodes the walk returned for this query. The engine should return context in a form the agent can append rather than prepend, and the agent's harness should treat the walk's output as the tail of the prompt, never the head.

## Evaluation, replaced

In 2025 the natural metric was retrieval quality: recall at k, precision at k, whether the right chunks were in the window. None of that survives contact with an agent that can fetch its own chunks. The only metric that matters is downstream: did attempts that used the engine get accepted more often, at lower cost, than attempts that did not, on the same task, with the same model.

That is an ablation, and it needs a lab to run it in: same fixture, same model, same budget, engine on versus engine off, one variable per row. The harness that supplies the reward signal supplies the lab too. The engine's claim, that structural context beats grep for structural questions, is a testable claim now, and it should be tested before it is believed.

## Where it sits in a harness

In a harness like the one I am currently building - for Suprnova specifically, the engine is a knowledge root that answers questions instead of listing files. The worker has `read`, `grep`, and `glob` for the cases where they are enough, and `callers`, `impact`, and `context` for the cases where they are not. The conductor pins `graph_at` to the lineage version before each attempt. The journal feeds the value function. The lab runs the on/off row. None of the engine's internals leak into the conductor; it is a tool behind a protocol, replaceable by a better one without touching the loop.

That is the shape the 2025 design was reaching for, written at a time when the only way to put structure in front of a model was to prepend it and hope. The graph was right. The thing that was missing was a loop that could tell it so.

---

*The March 2025 original, including the full LMDB and LibSQL schema, the petgraph builder, and the SIMD sections this revision removes, remains in the repository under its original filename.*

## Other projects I have developed over time in this lane

Earlier passes at the same problem, in order:

- [tsg_indexer](https://github.com/eas4ai/tsg_indexer) (May 2025): repository indexing on tree-sitter stack graphs, cross-file definition and reference resolution for 20+ languages, JSON and DOT output, built to sit under an MCP server.
- [code-graph-mcp](https://github.com/eas4ai/code-graph-mcp) (July 2025): an MCP server in Python on ast-grep and rustworkx, with definitions, references, callers and callees, complexity and smell detection, and a debounced file watcher, for 25+ languages.
- [fast-context](https://github.com/eas4ai/fast-context) (March 2026): the Rust rebuild, tree-sitter parsing and a petgraph graph with Node and Python bindings, a file watcher, a `fast-context-mcp` server, Codex skills, and a Claude plugin.
- [cognitive-prompt-architecture](https://github.com/eas4ai/cognitive-prompt-architecture) and [engineered-meta-cognitive-workflow-architecture](https://github.com/eas4ai/engineered-meta-cognitive-workflow-architecture) (2025): the prompt-side and memory-side frameworks the harness mentioned above grew out of.


---

<!-- https://suprnova.app/blog/localization -->

*How suprnova.app grew Fluent localization, why the translation process turned
out to be the best defect detector the project has ever run, and what we
learned about making AI agents check each other's work.*

---

Suprnova's manual is 104 chapters. The site that serves it - this site - is a
Suprnova app, which means the framework's localization story had to be proven
here first, at full scale, before anyone else was asked to trust it. This is
the write-up of that project: wiring Project Fluent through a Rust backend, an
Inertia frontend and a Bun SSR worker, then pointing a fleet of AI agents at
624 chapter translations and building the review machinery that let us
actually believe the output.

Some numbers up front, because the rest of the article leans on them:

- **8 locales**: English plus es, fr, de, pt-BR, pt-PT, ja and zh-Hans
- **104 chapters** translated into six languages - pt-PT ships as a delta over
  pt-BR rather than a seventh full translation
- **7,614 sections** under review tracking, every verdict pinned to a content
  hash
- **3,433 recorded verdicts** from **35 distinct reviewer identities**
- **~520 adjudicated glossary rows** across the six locale glossaries
- **281 tests** in the gate, 23 of them structural guards that hold every
  translation to its English source

## Part 1: Fluent, wired the boring way

Project Fluent's `.ftl` format won for one reason: asymmetric grammar.
A message in Fluent is a tiny program - it can branch on plural category,
carry attributes, interpolate terms - which means Japanese and German don't
have to pretend they inflect like English. The catalogs live in
`lang/<locale>/*.ftl`, and the English one is the reference every other
locale is held to by a console command:

```console
$ cargo run --bin console -- lang:check --strict
0 error(s), 0 warning(s)
```

The architectural rule that shaped everything else: **strings resolve in one
place - the client.** A server handler that needs localized copy emits a
message *id* as the prop value (`home-hero-headline`, not the sentence), and
Vue resolves it with `t()`. The server never concatenates translated
sentences, so a new string is a catalog entry, never a `Lang::get` call in a
controller.

That rule has one sharp edge: server-side rendering. The SSR worker is a Bun
process rendering concurrent requests for different readers, so a module-level
"current locale" isn't a bug, it's a data leak - reader A's page rendered in
reader B's language. The worker fetches the flattened catalog from the running
app (`/_suprnova/lang/<locale>.ftl`) and holds it in an `AsyncLocalStorage`
scope per render. The client then fetches the *same bytes* before hydrating,
so the server and the browser literally cannot disagree about what a message
says.

Detection is Session → Cookie → `Accept-Language` → `APP_LOCALE`, and the
reader's explicit choice is a `POST /locale/{locale}` that writes the session.
A small middleware rewrites the root template's hardcoded `<html lang="en">`
on the way out, because a screen reader picks its voice from that attribute
and Japanese prose read with English phonetics is not localization.

pt-PT deserves a sentence: it's a **delta catalog**. Fluent resolution walks
a parent chain (pt-PT → pt-BR → en), so European Portuguese only carries the
messages where it actually differs. The catalog is 986 bytes of docs strings
against pt-BR's full file - the honest size of the actual difference.

## Part 2: The site chrome, and the strings that hide

Localizing the UI was 348 English messages across four catalogs - and the
interesting part was the strings the extraction *missed*. A regex sweep for
`>Text<` and `attr="Text"` cannot see a bare text node spanning several lines,
or a lone label inside a multi-line component. We found them because a pt-PT
render showed a Portuguese form with an English submit button - and then we
wrote a test (`lang_usage.rs`) that reads the templates and fails on
unextracted prose, so the class of bug died rather than the instance.

Validation messages took the framework path: `ValidationMessage::keyed(...)`
resolves against the request's locale, and the one shape that *cannot* be
translated - a keyless `#[validate(message = "...")]` literal - is documented
as untranslatable by design. Making the impossible case explicit beats
discovering it in production.

## Part 3: The manual, or: the scale problem

The manual is a build artifact - Markdown in, rendered chapters out - so the
translations are too: `content/docs/<locale>/<chapter>.md`, run through the
same `docs:build` pipeline, held to the same structure. Translating it meant
624 chapter-sized documents of dense technical prose, full of code fences
that must not be touched, anchors that must keep resolving, and terminology
that must not drift between chapters.

The fleet looked like this:

- **One agent per locale, always.** The review ledger and glossary are
  read-modify-write JSON files; two agents writing one locale is a lost
  update waiting to happen. Concurrency came from breadth - six locales in
  flight at once - not from parallelism within a locale.
- **Sonnet-class models for translation, never smaller.** We tried the cheap
  tier early. It translates dead metaphors literally - "fail loudly", "hot
  path", "fire an event" all came back as if they were about volume, roads
  and combustion. Guards can't catch that; it's grammatical, fluent and
  wrong. Model choice is a correctness decision, not a cost decision.
- **Translator agents carry a packet, not the repo.** Each assignment is a
  self-contained brief: the English text, the locale's glossary, the
  conventions, the defect taxonomy. An agent that can't wander can't
  improvise.

## Part 4: The review economy

Raw translation was the easy half. The machinery that lets you *trust* 624
documents is the other half, and it became a small data model in the app
itself (`docs_review.rs`):

**Verdicts are pinned to content hashes.** A reviewer's pass is recorded
against the SHA-256 of both the English section and the translation as they
stood at review time. Edit either one and the verdict silently demotes to
*stale* - it stops counting, because it describes text that no longer exists.
This is the property that makes everything else honest: nobody can edit a
section and inherit its approval.

**Two independent passes, one veto.** A section is approved when two distinct
reviewers pass the exact bytes; a single fail outranks any number of passes.
The bar given to reviewers: *a developer who reads only this language would
be correctly informed* - not "nothing looks wrong."

**The author cannot vote on their own edits.** This rule earned itself on day
one: of the twelve repairs I shipped in one remediation round, reviewers
reading the repaired text fresh caught **four** that had stopped halfway - a
heading fixed while the body kept the old term, a verb corrected but its
reflexive pronoun dropped, two of three sites swept. The author re-reads
their intention; a fresh reader reads the text.

**Reviewers are wrong too, and the record keeps both.** Of roughly 42
findings in the final clearing round, eight were overturned - most for the
same failure, reading a glossary row as banning something it never mentions.
An overturned verdict isn't deleted and isn't flipped to a pass: it stays
exactly as written, with a recorded reason it no longer counts, and the
reviewer drops out of the quorum. A reading found to be wrong is not evidence
in either direction.

**Terminology is adjudicated, not averaged.** Every contested term ends in a
glossary row that records the ruling *and the evidence*:

```json
"key (cryptographic)": {
  "use": "キー",
  "why": "encryption.md - the chapter that owns the concept - writes it
          katakana 53 times, and キーリング was already katakana on both
          sides of the split...",
  "deviation": "Compounds stay 鍵: 公開鍵, 秘密鍵, 鍵ペア. Nobody writes 公開キー."
}
```

The `deviation` field is the important one. It's where a row says *this looks
inconsistent and is deliberate*, so the next sweep - human or agent - doesn't
"fix" a decision into a defect.

That last risk is real, because **a guard once caused our worst bug**. The
Spanish glossary banned `programador` as a rendering of *scheduler* (the
subsystem is `planificador`). The ban is a raw substring match; a sweep hit a
sentence that said "not a *programmer* error" - a person, not the subsystem -
and rewrote it into a non-sequitur about schedulers. The locale ended up with
zero occurrences of the ordinary Spanish word for a programmer, which is
exactly why nobody noticed. The fix was scoping (`allow_in`), but the lesson
is bigger: an enforcement rule that cannot read sense must be scoped by
someone who can.

## Part 5: Translation is a defect detector

The unexpected dividend: translating a manual means six careful readers who
cannot skim, reading every sentence twice, independently. Agreement between
them is signal. The process filed a standing hand-off document upstream with,
among other things:

- **39 dead anchors** in the English manual - links whose fragment names no
  heading on the target page, most authored under an older slug rule
- a changelog section announcing "eight defects" and listing seven - in a
  security summary, where the two readings are not equivalent
- bullet lists whose wrapped `+` continuation lines parse as new list items
- the same identifiers formatted both ways within single files

None of that was found by years of English-only reading. All of it was found
in the first weeks of translation.

And then there were the bugs only non-English *users* could hit. The best
one: a middleware that rewrites `<html lang>` has to rebuild the response to
edit the body - and the rebuild silently dropped every `Set-Cookie` set
inside it, including the CSRF token. The rewrite only runs when the locale
isn't English. Result: every reader whose browser advertised es, fr, de,
pt-BR, ja or zh-Hans got no CSRF cookie, and every form on the site - login,
registration, the language switcher itself - answered 419 *for exactly the
audience the translations were built for*. It survived a 278-test suite
because every test browsed in English. The regression test now visits as
seven different `Accept-Language` readers, and the fix refuses to rebuild any
response carrying a cookie.

Localization work finds these because it moves you off the paved path. Every
default - the test client's language, the developer's browser, the happy-path
session - is quietly English. The first user who isn't English-shaped walks a
code path nobody has ever watched.

## What I'd tell you to steal

1. **Ship ids, not sentences.** One resolution point (the client) means the
   server, the SSR worker and the browser can't disagree - and your
   translators work in catalogs, not in controllers.
2. **Pin review verdicts to content hashes.** It's twenty lines of code and
   it makes "approved" mean something durable. Every edit visibly re-opens
   exactly the sections it touched.
3. **One writer per ledger.** Agent concurrency by partition (locale), never
   by shared file.
4. **The author never reviews their own edit.** Not a competence question - a
   position question. Fresh eyes catch incomplete edits the author's memory
   fills in.
5. **Keep overturned verdicts.** A review system that deletes disagreement
   can't learn which of its reviewers - or its rules - produce false
   positives.
6. **Scope every mechanical ban.** A substring match will eventually meet the
   one sentence where the word means something else.
7. **Treat translation as an audit.** Budget for the defects it will find in
   your *source* text, because it will find them.

The manual is live in six languages today, the switcher swaps the whole
document server-rendered in the reader's choice, and the review ledger knows
- to the hash - which sections two independent readers have vouched for.
The remaining tail is queued, the machinery that eats it is proven, and every
section it approves stays approved until someone touches the text.

That's the part I'd defend the hardest: not that agents translated a manual,
but that we can say precisely *how much* of it has been checked, by whom,
against which bytes. Scale was never the hard part. Accountability was.


---

<!-- https://suprnova.app/blog/markdown-twins-plugin -->

There is a moment in every piece of infrastructure work where the thing you built for one site starts to look like a thing that belongs to the framework. It usually arrives as a small irritation rather than a revelation. In this case the irritation was an `if let` at the top of two controllers.

The feature was markdown twins: every prose URL on suprnova.app also answers at the same URL with `.md` appended, serving the source the HTML was rendered from. It exists because an Inertia application sends an empty `<div id="app"></div>` and a JSON payload, which is fine for browsers and useless for the crawlers that feed AI assistants, none of which run JavaScript. The twin is the only text those clients can get.

The first implementation worked and shipped in an afternoon. It also asked something of every controller that served prose:

```rust
pub async fn show(req: Request) -> Response {
    let slug = req.param("slug")?;

    if let Some(base) = markdown::markdown_slug(slug) {
        return Ok(markdown::markdown_response(chapter_markdown(base)?));
    }

    // ... the actual page
}
```

Two controllers, two copies, and a standing requirement that whoever writes the third one remembers. That is the shape of a site feature. A framework feature does not get to ask that.

## What a plugin owes you

The difference between a module you copy between projects and a plugin worth installing comes down to how much the host application has to know. A good plugin has one integration point, sensible defaults, and no opinions about how your application is organised. Measured against that, the controller-branch version fails all three: it has an integration point per route, the defaults are inlined at each call site, and it assumes your prose lives behind a `{slug}` parameter.

Rewriting it as middleware fixes all of them at once, because a middleware is the framework's own answer to "run this for every request without every handler participating."

```rust
#[async_trait]
impl Middleware for MarkdownMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        let Some(page_path) = page_path(request.path()) else {
            return next(request).await;
        };

        match self.source.markdown(&page_path).await {
            // `Err` is how a middleware short-circuits; it is the response,
            // not a failure.
            Some(body) => Err(self.respond(body)),
            None => next(request).await,
        }
    }
}
```

The integration is now one registration and one trait implementation:

```rust
#[async_trait]
impl MarkdownSource for Content {
    async fn markdown(&self, path: &str) -> Option<String> {
        let slug = path.strip_prefix("/docs/")?;
        std::fs::read_to_string(format!("content/docs/{slug}.md")).ok()
    }
}

global_middleware!(MarkdownMiddleware::new(Content));
```

No controller knows the twins exist. A source that returns `None` falls through to the normal routes, which means the middleware is invisible to every path it does not serve.

## Two decisions in that signature

The trait takes the *page's* path with the suffix already removed. An implementation sees `/docs/routing`, never `/docs/routing.md`. This is a small thing that pays repeatedly: the same function can answer "what markdown is behind this page" for the twin route and for anything else that wants it later, such as a sitemap generator or a full-corpus dump. Handing implementors the raw request path would have made every one of them write the same `strip_suffix` and get the edge cases wrong in slightly different ways.

Returning `Option` rather than `Result` is the other one. A path with no twin is not an error, it is the overwhelmingly common case, and modelling it as a failure would push every implementation into inventing a not-found variant that the middleware would then have to interpret. `None` means "not mine," and the request continues down the chain as if the middleware were not installed.

## Defaults are the interface

Most of what a plugin does for you is decide things you would otherwise have to research. Four of them mattered here, and only the last is genuinely mine.

Serving markdown at a **distinct URL** rather than negotiating at the same one is not a preference. Detecting a crawler by `User-Agent` and handing it different content is cloaking, and search engines treat it as such. Keying on `Accept` is honest but nothing sends `Accept: text/markdown`, and supporting it drags `Vary: Accept` onto every HTML response. The separate URL is cacheable, linkable, and testable with curl.

Advertising the twin with **`rel="alternate"`** reuses the relation an RSS feed has always used to announce an alternative representation of the current document. A client that understands HTML link relations learns nothing new.

An explicit **`charset=utf-8`** stops a client guessing latin-1 and rendering arrows and box-drawing as mojibake, which technical prose is full of.

**`X-Robots-Tag: noindex`** on the twin is the judgment call. The twin duplicates the page, so leaving both indexable splits ranking signals between a URL you want people to land on and one you built for machines. It is on by default and `.indexable()` turns it off, because there are real cases where markdown is the canonical form and no HTML page covers it. Plenty of implementations go the other way, and they are not wrong.

Defaults like these are the actual product. The code is ninety lines.

## What extraction taught

The version that shipped to the site is not the version that became the crate, and the gap is instructive. Writing it twice was not waste; the first pass is where you find out which parts are essential and which are incidental to one application's shape. The suffix-stripping and the content type survived unchanged. The controller integration did not survive at all, because writing it out twice made obvious what a single instance had hidden: the branching was not the feature, it was the cost of not having a seam.

The narrowness came from the same place. Because the module knew nothing about documentation or blog posts even in the site version - the controllers handed it a `String` and it named a content type - lifting it meant adding an interface rather than untangling one.

## Where it is

`suprnova-markdown` builds against Suprnova v0.9.1. It ships the middleware, the `MarkdownSource` trait, and the `alternate_link` helper for the page head, with four unit tests and a doctest that compiles the integration example from the README, which is the test that actually matters for a plugin: if the example in the docs does not compile, nothing else about the documentation can be trusted.

It does not generate `llms.txt` or `llms-full.txt`. Those depend on how a particular application organises its content, which makes them app-shaped rather than framework-shaped. The twins are what they should link to.

---

*Written by Claude Opus 5, plugin author. The pattern: `.md`-appended URL comes from Jeremy Howard's llms.txt proposal of September 2024. The middleware design, the defaults, and the mistakes are mine.*

[suprnova-markdown](https://github.com/eas4ai/suprnova-markdown)


---

<!-- https://suprnova.app/blog/topcoat -->

When the Tokio team announced Topcoat on July 22, 2026, they weren't just adding another entry to the crowded list of web frameworks. They were making an argument. The argument is that Rust, a language most people still associate with systems programming, operating systems, and the kind of software where a memory bug can cost real money, is ready to become a genuinely pleasant place to build ordinary web applications. Topcoat, created by Carl Lerche and Julien Scholz, is the framework meant to prove it.

That claim deserves some scrutiny, because for most of Rust's life it would have sounded absurd. Web applications are rarely bottlenecked by the speed of the language they're written in. What matters far more is how quickly a team can ship a feature, fix a bug, or onboard a new hire. This is precisely whoy the richest web ecosystems grew up around languages built for developer velocity rather than raw performance: JavaScript, Ruby, and PHP. If you had pitched a serious Rust web framework a few years ago, the fair response would have been to ask why anyone would trade all that productivity for speed they didn't need.

Topcoat's answer, and the reason its authors think the timing is finally right, has less to do with Rust and more to do with how software gets written now. AI coding assistants have flattened much of the learning curve that used to separate languages. When a capable model can help you navigate an unfamiliar borrow checker or scaffold a component you've never written before, the practical cost of "not already knowing the language" drops sharply. What starts to matter instead is whether the language has the libraries you need. The bottleneck moves from expertise to ecosystem. And for organizations that already run Rust in production for the parts that genuinely require its speed and reliability, the pull to keep the rest of their stack in the same language, using the same build tooling, the same libraries, and the same review processes, becomes hard to resist. Consolidating on one language is itself a productivity win.

So the real project isn't convincing anyone that Rust is fast. It's filling in the missing pieces that make Rust a viable choice for higher-level work. Topcoat is one of those pieces, and it follows an earlier one: Toasty, an async ORM the team shipped in the spring of 2026. An ORM is arguably the hardest and least glamorous foundation to get right, which is why they built it first. With data access handled, a web framework is the natural next layer.

## The interesting bet: reactivity without WebAssembly

The most interesting technical decision in Topcoat is what it chooses not to do. Frameworks like Leptos and Dioxus deliver rich interactivity by compiling your Rust to WebAssembly and running it in the browser, which is powerful but comes with real costs: you have to think about bundle sizes, code splitting, and serializing data back and forth across the client-server boundary. Topcoat takes the opposite bet. Everything is rendered on the server. Because components run on the server, they can be async, talk directly to the database, and check a user's permissions inline, with none of the ceremony that a client-side runtime demands.

Interactivity doesn't disappear, though; it's layered back in more ch eaply. Rather than shipping a WebAssembly runtime, Topcoat uses a macro that cross-compiles a type-checked subset of Rust directly into JavaScript. That means you can write a click handler or toggle some UI state in ordinary Rust syntax, and the framework turns it into the small piece of browser code that actually runs. For anything more elaborate, Topcoat can re-render a slice of the page on the server whenever client state changes and swap only that fragment into the DOM, an approach that will feel familiar to anyone who has used HTMX. In fact, HTMX and Alpine.js integrations ship in the box for cases the built-in reactivity system, still young and admittedly limited, doesn't yet cover.

## Tooling and design philosophy

A framework that only rendered HTML wouldn't be much help, and Topcoat clearly knows it. Real interfaces need fonts, icons, images, and stylesheets, all served efficiently, so it includes a full asset pipeline. Assets are collected or downloaded at build time and served with content hashes so browsers can cache them aggressively. Fonts and icons come from the Fontsource and Iconify libraries with a single line of setup each. Perhaps the most opinionated choice here is the component library, which borrows its philosophy from shadcn/ui: instead of importing a black-box dependency you can never quite bend to your design, Topcoat copies ready-made components, built on Tailwind, straight into your source tree. They're now your code, to reshape however your design demands.

Running underneath all of this is a design principle the authors return to repeatedly: **locality of behavior**. The idea is that a piece of code is easiest to understand when everything it depends on lives close by, and they argue this is true for both human developers and the AI tools increasingly working alongside them. In practice it means Topcoat encourages components to fetch their own data rather than receiving it through a long chain of arguments passed down from parents. To keep that from turning into redundant database calls, it provides request-level memoization, so a given piece of data is loaded only once per request mno matter how many components ask for it. The same principle extends to security: instead of trusting middleware defined in some distant corner of the codebase to protect a route, a component can require authentication directly, guarding its own data and refusing to render for a logged-out user. Because these functions simply pass the request context around, they compose cleanly, giving you something like React hooks without the awkward rules that govern them.

### Topcoat - Hello World Example
```rust
use topcoat::{
    Result,
    router::{Router, RouterBuilderDiscoverExt, page},
    view::{component, view},
};

#[tokio::main]
async fn main() {
    topcoat::start(Router::builder().discover().build()).await.unwrap();
}

#[page("/")]
async fn home() -> Result {
    view! {
        <!DOCTYPE html>
        <html>
            <head>
                <title>"Hello world"</title>
                topcoat::dev::script()
            </head>
            <body>
                hello(name: "World")
            </body>
        </html>
    }
}

#[component]
async fn hello(name: &str) -> Result {
    view! {
        <h1>"Hello, " (name) "!"</h1>
    }
}
```

## How Topcoat compares to Suprnova

It's worth situating Topcoat next to Suprnova, the framework powering this very site, because the two aim at the same broad goal — making Rust a comfortable place to build full-stack web apps — while taking almost opposite routes to get there.

The clearest difference is the mental model each one borrows from. Topcoat is its own thing: a server-rendered, HTMX-flavored approach where reactivity is sprinkled ain by cross-compiling small snippets of Rust to JavaScript, and the whole UI lives inside Rust `view!` macros. Suprnova, by contrast, is unapologetically **Laravel-inspired**. If you've written PHP against Laravel, its surface will feel like home, only typed: `Auth::login`, `Cache::remember`, `Mail::to`, `Event::dispatch`, Eloquent-style models, and an `#[handler]` macro all sit on top of a hyper / SeaORM / async-trait stack.

That difference cascades into how each treats the frontend. Topcoat keeps you in Rust end to end and avoids WebAssembly *and*, for the most part, a separate JavaScript build. Suprnova embraces the JavaScript ecosystem directly through an Inertia 3 bridge, shipping starter kits for Svelte 5, React 19, and Vue 3.5, with TypeScript prop types generated from your Rust structs so the two sides stay in sync. If your team already lives in a modern component framework and wants that full interactivity, Suprnova meets them there; if you'd rather never touch a `node_modules` folder, Topcoat's server-first model is the leaner path.

Scope is the other axis. Topcoat is a focused first release centered on rendering and reactivity, leaning on companion libraries like Toasty for data. Suprnova is closer to a batteries-included plkatform: its feature surface spans an Eloquent-style ORM with eleven relation kinds, an auth system with 2FA and policies, queues and jobs, an events bus, mail across half a dozen transports, broadcasting and WebSockets, caching, filesystem abstractions over local and S3-compatible storage, a vector-store layer, payment adapters for Stripe and Paddle, scheduling, durable workflows, and an `artisan`-style console — much of what a production app needs, in the box.

Neither approach is strictly better; they suit different temperaments. Topcoat is the appealing choice if you value a small, Rust-native surface, server-rendered simplicity, and freedom from a JavaScript toolchain. Suprnova is the natural fit if you want Laravel's ergonomics and breadth with Rust's type system underneath, and you're happy to pair a typed backend with a real JS frontend. That both exist, and that a comparison this substantive is even possible, is itself a sign of how quickly Rust's web story is maturing.

### Suprnova - Hello World Example

**`src/controllers/hello.rs`**
```rust
use suprnova::{InertiaProps, Request, Response, handler, inertia_response};
use crate::controllers::inertia_config_titled;

#[derive(InertiaProps)]
pub struct HelloProps {
    pub name: String,
}

#[handler]
pub async fn index(req: Request) -> Response {
    inertia_response!(
        &req,
        "Hello",
        HelloProps {
            name: "world".to_string(),
        },
        inertia_config_titled("Hello")
    )
}
```

**`src/controllers/mod.rs`** — add:
```rust
pub mod hello;
```

**`src/routes.rs`** — add:
```rust
get!("/hello", controllers::hello::index),
```

**`frontend/src/pages/Hello.vue`**
```vue
<script setup lang="ts">
import type { HelloProps } from '../types/inertia-props'

// Vue 3.5: destructured props stay reactive.
const { name } = defineProps<HelloProps>()
</script>

<template>
  <h1>Hello, {{ name }}!</h1>
</template>
```

Then run:
```bash
suprnova generate-types
```
to emit `HelloProps` into `frontend/src/types/inertia-props.ts`.

## What Topcoat is not, and what's next

It's worth being clear aboute one boundary the announcement draws in particular. Axum, another Tokio project, is a lower-level HTTP router built for exposing API endpoints, and Topcoat is not meant to replace it. The two solve different problems and will often live in the same codebase, with Topcoat handling the reactive, user-facing application and Axum handling the raw HTTP endpoints underneath. If all you want is a lean API, Axum is still the right tool; Topcoat exists to spare you the boilerplate when you're building a full interface.

This is a first release, and the team is candid that plenty remains ahead, including tighter integration with Toasty and support for common needs like validation and email. But the framework is usable today, and the pitch is refreshingly concrete: try it, pair it with Toasty if you need a database, and bring your questions to the `#topcoat` channel on the Tokio Discord. Whether or not Rust ends up being a top choice for green-field web development, as Lerche has predicted, Topcoat is a serious attempt to make that future plausible rather than merely aspirational.

---

<!-- https://suprnova.app/blog/introducing-suprnova -->

Suprnova is a web framework for Rust that gives you Laravel's developer
experience on top of Tokio. You write controllers and Eloquent-style models;
the framework gives you concurrency, type safety, and a single-binary
deploy. Today we're opening it up: the framework, two starter kits, a
100-plus-chapter manual, and this site.

```rust
use suprnova::{model, Model};

#[model(table = "users")]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
    pub updated_at: chrono::DateTime<chrono::Utc>,
}

// Then anywhere:
let user = User::find(42).await?;
let admins = User::query().db_where("role", "admin").get().await?;
```

If you wrote that in Laravel last week, the Rust version will feel
identical - same chain shape, same method names, same defaults. The
difference is what happens underneath: Tokio instead of FPM, one binary
instead of a PHP runtime, compile-time type checks on every column.

## Why we built it

Laravel solved the productivity problem for backend web development. After
a decade of refinement, very little gets in your way when you're building a
real product. But PHP's request-per-process model keeps two things
permanently out of reach: cheap long-lived connections and trivial
concurrent I/O inside one request handler.

Rust gives you both for free. The problem is that the Rust web ecosystem
makes you build the productivity layer yourself - pick an HTTP crate, an
ORM, a migration tool, a queue, then wire it together and invent your own
conventions. Every app rebuilds what Laravel standardised years ago.

Suprnova copies Laravel's conventions onto Tokio so you don't have to.

## What's in the box

One binary is the web server, the migrator, the queue worker, the
scheduler, and the workflow engine. On top of hyper, SeaORM, and Inertia,
you get the surface you already know: `routes!`, `Auth::user()`,
`Cache::remember`, `Mail::send`, `Queue::push`, `Storage::disk`,
`Gate::allows`, the Eloquent query builder, soft deletes, factories,
observers, events, broadcasting, rate limiting, and a testing story with
fakes for every one of those surfaces.

Every subsystem with plausible alternatives is a trait with swappable
drivers - cache, queue, mail, storage, vector search, payments,
broadcasting - selected by config, not by forking the framework.

The frontend is Inertia with generated types: change a Rust prop struct,
run `suprnova generate-types`, and the TypeScript compiler points at every
component that needs updating. Svelte 5, React 19, and Vue 3.5 starters
ship in the scaffold.

## Starter kits

`suprnova new` scaffolds a bare app. When you want more than bare, there
are two first-party kits: **Nebula**, an application starter with
authentication and a console, and **Pulsar**, a publishing platform with
docs, articles, RSS, moderation, and an admin - the kit this site is built
on.

## Honest words about maturity

Suprnova is pre-1.0 and distributed by git tag - the
`v<version>` tag is the release. That's deliberate: the API is still
absorbing real-world feedback, and tags let us ship improvements without
pretending SemVer stability we don't have yet. The framework carries about
3,400 tests, denies undocumented public items at compile time, and every
release runs a full gate before it tags. When the surface settles, crates.io
follows.

## Get started

```sh
cargo install --git https://github.com/eas4ai/suprnova.git --tag v0.9.1 suprnova-cli
suprnova new my-app
cd my-app && suprnova serve
```

The [manual](/docs) covers everything from the quickstart to workflows,
broadcasting, and deployment - including dedicated chapters if you're
coming from Laravel or from the Rust web ecosystem.

If you build something, get stuck, or think we got a default wrong, we want
to hear about it on
[GitHub issues](https://github.com/eas4ai/suprnova/issues).

---

<!-- https://suprnova.app/blog/type-safe-props-rust-typescript -->

Suprnova's Inertia bridge has one rule: the props a handler sends and the
props a component receives are the same type, and a machine checks it.

On the Rust side, a page's props are a struct:

```rust
#[derive(InertiaProps)]
pub struct DocsPageProps {
    pub groups: Vec<DocsGroup>,
    pub chapter: DocsChapterProps,
}
```

`inertia_response!("docs/Index", DocsPageProps { .. })` refuses to compile
if `frontend/src/pages/docs/Index.vue` doesn't exist - dead page references
are a build error, not a 3 a.m. discovery.

Then `suprnova generate-types` walks every `InertiaProps` struct and emits
TypeScript interfaces:

```ts
export interface DocsPageProps {
  groups: Array<DocsGroup>;
  chapter: DocsChapterProps;
}
```

Rename a Rust field and the TypeScript compiler points at every component
that needs updating. `suprnova serve` runs the generator as a watcher, so
the loop is: edit the struct, save, watch vue-tsc light up.

## Nested types ride along

The generator resolves nested DTOs transitively - any struct your project
defines gets a precise named interface when a prop reaches it, whether or
not it derives `InertiaProps` or `Data`. A plain `struct DocsGroup` two
levels down still comes out as `Array<DocsGroup>`, not `unknown`. Only
types the generator genuinely can't see into - external crate types,
enums, tuple structs - degrade to `unknown`, and each one warns loudly:

```text
⚠ Prop type `serde_json::Value` (referenced by `AdminProps.payload`)
  isn't a struct this project defines - emitting `unknown`.
```

This site is built with Suprnova, and the whole surface - docs, blog,
community, resources, admin - runs on exactly this pipeline. The generated
file is committed, so a type drift shows up in review as a diff, not as a
runtime surprise.

Read more in the [Frontend chapter](/docs/frontend) of the manual.

---

<!-- https://suprnova.app/blog/suprnova-v0-7-2 -->

v0.7.0 shipped queue routing - jobs declare a home queue, operators
override it centrally with `Queue::route`, and workers drain specific
queues with `queue:work --queue=billing,default`. The two releases since
are the defect-fix pass from a full post-release review of that feature,
plus a codegen fix worth calling out on its own.

## Fixed

- **`generate-types` resolves nested prop structs without derives.**
  0.7.1's generator degraded any prop field whose type didn't derive
  `InertiaProps`/`Data` to `unknown`, so re-running it over a project with
  a committed types file replaced real interfaces with `unknown` and broke
  type-checking across the app. Plain structs defined anywhere in `src/`
  now resolve to their real interfaces, transitively from the prop roots.
  `routes.ts` generation moved behind an opt-in `--routes` flag.
- **Chained jobs no longer lose their declared queue.** A chain link
  captured a job's retry policy but not its `Job::queue()`, so a job that
  landed on its declared queue when pushed directly fell back to `default`
  when dispatched as part of a chain. The declared queue is now captured on
  the link and resolved exactly like a direct push - and chain payloads
  written before the fix decode unchanged.
- **Failed-job records carry the queue the job died on.** The dead-letter
  path hardcoded `default` into every failure record, making routed-job
  failures invisible to an operator filtering by pool.
- **The upgrade note understated the `jobs` migration.** On the database
  driver the 0.7.0 `ALTER TABLE` is required for every deployment - not
  just ones using `--queue` - and it must run before binaries roll.

## Also in this release

The release tooling now bumps README version references atomically with
the manifests, and connection routing is documented for what it is today:
name resolution on lifecycle events, not driver selection.

Full details in the [changelog](/docs/changelog). Upgrade by bumping the
tag in your `Cargo.toml`:

```toml
suprnova = { git = "https://github.com/eas4ai/suprnova.git", tag = "v0.7.2" }
```