Guides / Current release

# Caramel today.

What to do when you upgrade an application to Caramel 0.23.0, release by release since 0.8.0, and what the release supports and still lacks.

| Contract | Value |
| --- | --- |
| Release | 0.23.0 |
| Covers | Upgrade notes from 0.8.0 to 0.23.0, what the release supports and its current limits |
| Needs | An application whose `shard.lock` pins an earlier release, and the [machine setup of your first application](https://caramelize.dev/docs/0.23.0/getting-started/index.md) |
| Proved by | `frappe check` · `frappe corretto` · `frappe lint` |

## The guide in three stages {#c-releases-map}

29 sections · read in order the first time

- **1 · Upgrade notes**

  - [Upgrading to 0.23.0](#c-releases-upgrade-0230)
  - [Upgrading to 0.22.0](#c-releases-upgrade-0220)
  - [Upgrading to 0.21.0](#c-releases-upgrade-0210)
  - [Upgrading to 0.20.0](#c-releases-upgrade-0200)
  - [Upgrading to 0.19.0](#c-releases-upgrade-0190)
  - [Upgrading to 0.18.0](#c-releases-upgrade-0180)
  - [Upgrading to 0.17.0](#c-releases-upgrade-0170)
  - [Upgrading to 0.16.0](#c-releases-upgrade-0160)
  - [Upgrading to 0.15.0](#c-releases-upgrade-0150)
  - [Upgrading to 0.14.0](#c-releases-upgrade-0140)
  - [Upgrading to 0.13.0](#c-releases-upgrade-0130)
  - [Upgrading to 0.12.0](#c-releases-upgrade-0120)
  - [Upgrading to 0.11.0](#c-releases-upgrade-0110)
  - [Upgrading to 0.10.0](#c-releases-upgrade-0100)
  - [Upgrading to 0.9.0](#c-releases-upgrade-090)
  - [Upgrading to 0.8.0](#c-releases-upgrade-080)
  - [Earlier releases](#c-releases-earlier)
- **2 · Supported today**

  - [Runtime and local tools](#c-releases-tools)
  - [Dependencies move with the release](#c-releases-dependencies)
  - [Requests and responses](#c-releases-requests)
  - [Data and resource generation](#c-releases-data)
  - [Background work](#c-releases-work)
  - [Development and testing](#c-releases-checks)
  - [Internationalization](#c-releases-i18n)
  - [Multi-tenancy](#c-releases-tenancy)
  - [Domain-Driven Design](#c-releases-sweettalk)
  - [Observability](#c-releases-observability)
  - [Production](#c-releases-production)
- **3 · Limits**

  - [Current limits](#c-releases-limits)

Each upgrade section is written from the release’s entry in [CHANGELOG.md ↗](https://github.com/caramelizedev/caramel/blob/v0.23.0/CHANGELOG.md): what to run, what to edit, and what changes without an edit. Upgrade one release at a time and run the proof at the end after each.

Upgrade notes

## Upgrading to 0.23.0 {#c-releases-upgrade-0230}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; run `frappe db diff` and `frappe migrate` for the tables, columns and checks a domain that adopts the new words adds; the three changes marked **Breaking** need an edit.

- Frappé: `frappe help` prints the commands in groups, from getting started to shipping, one short line for each command or family of subcommands, then examples and where to learn more. `frappe help WORDS` and `frappe WORDS --help` print one command's description, usage and examples, or list a family's subcommands (`frappe help db branch`); a family run without a subcommand, such as `frappe db`, lists its subcommands on a terminal and exits 1. A usage error on a terminal ends with `Run frappe COMMAND --help for details.`, or with the family's commands. The commands that change state end with one aligned `Next:` block. `NO_COLOR` and `TERM=dumb` turn colour off. `frappe completion zsh|bash|fish` prints a completion script for commands, subcommands, options and their choices. Output when stdout is not a terminal and every MRDP block keep their format, and `frappe agent-manifest` keeps its format with the new `help [COMMAND...]` and `completion` lines ([ADR 0013](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0013-frappe-cli-check-mrdp.md)). A script that read an old one-line hint (`Run frappe migrate to apply the new schema.`, `Next: run frappe migrate and open /PLURAL/new.`) reads the `Next:` block instead.
- Frappé: `frappe words [WORD] [--json]` prints SweetTalk's vocabulary without an application: every word with its kind and a one-line summary, or one word's usage, each option with the forms it takes, its default and what it does, an example that compiles and its guide section. An unknown word exits 1 naming the nearest. It reads the doc comments and parameters of the macros of the release you run, so it cannot name an option a macro lacks, and `scripts/check` fails when a macro has no entry, an example does not compile, or the guide or the skill writes an option no word takes ([ADR 0013](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0013-frappe-cli-check-mrdp.md)).
- SweetTalk: the skill `frappe make domain` writes no longer says never to add up with `SugarORM.sql`. It says to prefer `sums` and `groups`, and to use `SugarORM.sql` only for what they cannot state, such as an average, a `Float64` or `Time` key or several keys, with the tenant predicate written out ([ADR 0049](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0049-sweettalk-sums-and-groups.md)). Refresh an application's copy with `cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/`.
- SugarORM: `field id : UUID, primary: true` is a `uuid` key with the default `uuidv7()`, minted by the insert changeset when it is built (`changeset.id`); a UUID-keyed table needs PostgreSQL 18. `field id : Int64, primary: true` keeps its identity column, so existing schemas change nothing ([ADR 0064](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0064-uuidv7-identity.md)).
- Frappé: `frappe make resource` and `frappe make tenancy` now write UUID keys; pass `--int64` to keep the Int64 identity key of earlier releases ([ADR 0064](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0064-uuidv7-identity.md)).
- **Breaking:** SweetTalk: a domain without a tenant now keys its aggregates and entities by UUID. Add `ids Int64` on the line after `include SweetTalk` to keep existing tables; without it `frappe db diff` halts on the changed key. A domain with a tenant follows the tenant's key type ([ADR 0064](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0064-uuidv7-identity.md)). The skill `frappe make domain` writes says so; refresh an application's copy with `cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/`.
- **Breaking:** SugarORM: `SugarORM::Page(R)` is now `SugarORM::Page(R, K)`, `K` the schema's `PrimaryKey`; update code that names the type ([ADR 0064](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0064-uuidv7-identity.md)).
- **Breaking:** SugarORM: `param id` on a changeset of an Int64-keyed schema fails compilation; a UUID key takes `param id : UUID`, the only way a client supplies an id. An update that changes the id adds `cannot be changed` (`errors.key_kept`) ([ADR 0064](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0064-uuidv7-identity.md)).
- Tenancy: a UUID tenant's cache and channel prefix is `t` + 25 base-36 characters + `:`, and its event channels hold at most 36 characters; an Int64 tenant keeps `t<digits>:` and 42 ([ADR 0064](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0064-uuidv7-identity.md)).
- SweetTalk: `within Picking do … end` continues context Picking, declared before it in the same domain module, in another file. It takes the words a context's body takes and no option, and every check reads every block: the context map joins their text, queries are checked once the program's top level is complete, and the event log and a `once_by:` unit work from any block. A `within` of no earlier context, of a kernel or inside a context, a `publishes` in two blocks of one context, and two borders with one context or outside system fail compilation. The guide's "Split a context across files" gives each context a directory and each aggregate a file; the skill `frappe make domain` writes says so, so refresh an application's copy with `cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/` ([ADR 0065](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0065-sweettalk-contexts-across-files.md)).
- SweetTalk: in `SweetTalk.preview`, a unit's `never` and `always` lines no longer end the run. Each that fails adds its sentence to the new `preview.blockers`, in the order they ran, and the preview keeps the run's events and changes; `preview.refusal` is the first blocker, so a screen that hides its confirm button on `refusal` still does. Once the run holds a blocker, a line whose block raises is skipped. A commit and a plain call still refuse with the first line that fails, and a preview with no failing line keeps its fingerprint. `SweetTalk.preview` now answers a `SweetTalk::Preview::Of(T)`, a `Preview` whose `value` is what the block returned, nil when the body was refused, and `to_json` adds `blockers` ([ADR 0060](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0060-sweettalk-preview-and-commit.md) decision 11). The skill `frappe make domain` writes says a screen that refreshes as a person types loads with `find` and calls a calculation instead of previewing; refresh an application's copy with `cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/`.
- SweetTalk: a `sums` or `groups` that adds up an entity's attribute takes conditions on each entity in `where:`, under the name of its list, as in `where: {member: member, state: :placed, lines: {tea: teas}}`, and `groups …, of: Line.price, by: :id` answers one total per aggregate, in id order; neither joins. `sums` of a `Money::Amount` answers `Hash(Currency, Amount)`, one total per currency in code order, in one statement; a `Minor(USD)` adds up as a number, and `groups` with `by:` an amount groups by its currency. A `groups` that adds up an `Amount`, and a `sums` or `groups` that filters a list of entities it does not add up, fail compilation ([ADR 0049](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0049-sweettalk-sums-and-groups.md), [ADR 0063](https://github.com/caramelizedev/caramel/blob/v0.23.0/docs/decisions/0063-sweettalk-money.md) decision 10). Existing queries are unchanged. The skill `frappe make domain` writes says so; refresh an application's copy with `cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/`.

## Upgrading to 0.22.0 {#c-releases-upgrade-0220}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; run `frappe db diff` and `frappe migrate` for the tables, columns and checks a domain that adopts the new words adds; the two changes marked **Breaking** need an edit.

- SweetTalk: `Billing.logged(…, before: moment)` reads a context's event log as it stood at a moment, on the typed, all-classes and `subject:` forms: the events whose `occurred_at` is earlier than `moment`, the bound left out, beside `since:`, which keeps it. It reads when an event was emitted, so what was known then; a log kept a number of days answers with what remains. The SweetTalk guide's "Read what was known at a time" shows the pattern for corrections: keep the result in effect on the aggregate, set by the command that finalises the correction, and read what was known before it from the log. Nothing changes for an application that does not pass `before:` ([ADR 0048](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0048-sweettalk-event-log.md) decision 3).
- SweetTalk: a value with `one_of:` also writes `enum Kind::Member`, one member per word in the listed order (`net_settlement` is `NetSettlement`), with `kind.member` and `Kind.new(member)` (or `Kind.new(:receipt)`) between the two; the column, its CHECK and the check's hash are unchanged, so nothing migrates. Write a branch over a kind as `case kind.member in .receipt? … end`, with no `else`: a member added to the list then fails compilation at every `case` that misses it, naming the member, where a `when … else` sent it to the default arm ([ADR 0058](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0058-sweettalk-closed-sets-on-the-screen.md)).
- SweetTalk: `moves` also writes `Order.moves_from(state)`, the states a mover may enter from `state` in the order `moves` first names them, and `order.may_become?(state)`; the movers stay private. A screen that offered commands by comparing `state` text can map each state of `moves_from(order.state)` to its command in a `case … in`, which fails compilation when a state is added.
- SweetTalk: `refuse "…", on: :tins`, and `on:` on `never`, `always` and a unit's rules, name the field a refusal is about (`refusal.on`, `"tins"`; a service raises `SweetTalk::Refusal.new("…", on: :tins)`). An action answers it under that field when its contract declares it, through the new `contract.field?(name)` (and `Contract.field?(name)`), and under `_base` otherwise, so a refusal without `on:` answers as before; an application that mapped refusal sentences to fields can name the field at the `refuse` instead. An `on:` that is not a symbol fails compilation.
- **Breaking:** SweetTalk: `SweetTalk.preview { … }` runs a body dry, with the commit's locks, in a transaction that always rolls back, and answers a `SweetTalk::Preview` (`events`, `changes` before and after, `warnings`, `refusal`, `summary`, `fingerprint`, `to_json`); `SweetTalk.commit(expected) { … }` runs the same body, compares its fingerprint before the transaction ends and raises `SweetTalk::Stale`, a refusal carrying the fresh preview, when the world moved, writing nothing ([ADR 0060](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0060-sweettalk-preview-and-commit.md)). `SweetTalk::Fingerprint` is a contract field value for the hidden field a form carries, and an unrescued `Stale` answers 422 through `render_stale(contract, stale)`, a JSON client getting the fresh preview under `preview`. A hand-kept preview path with its own hash can be replaced by the real body inside `preview` and `commit`. A unit's `warn "…" { … }` line refuses a plain call with its sentence and is confirmed by a fingerprint that holds it. A command, a factory or a unit body that names an `outside:` border's module no longer compiles: move the call into a `whenever` on the command's event, or before the change. `Caramel::Outbound` raises `Caramel::Outbound::Refused` while a preview runs. The aggregate, entity and event macros now define `__sweettalk_canon`, and `moves` defines `SWEETTALK_FINAL`, the states no move leaves.
- SweetTalk: `calculation share(total : Cents, parts : Int32), returns: Array(Cents), means: "…" do … end` in a context declares a typed function, `Billing.share`, with no transaction, repository, event or command, listed in the glossary with kind `calculation` and in `SweetTalk.calculations`, and nameable in `publishes`. A `never` or `always` line in its body is a rule on `result`; a broken one raises the new `SweetTalk::Broken`, a defect that rolls back its transaction and answers 500, not a refusal. A calculation whose body or rules reach `SugarORM`, `Repo`, `Rows`, `SweetTalk.lock`, an aggregate's class, `emit`, a service or a unit, or that takes or returns an aggregate, fails compilation. Nothing changes for an application that declares none, except that the `publishes` refusals now name "services, units and calculations" ([ADR 0062](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0062-sweettalk-calculations.md)). [ADR 0061](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0061-sweettalk-modules.md) states when a SweetTalk word gets a require of its own, as `caramel/sweet_talk/decimal` has.
- Corretto: `Corretto.property(Billing.share)` runs a SweetTalk calculation on 200 cases drawn from its argument types (bounds, `one_of:` members, decimal scale, days, parts, arrays of at most 8), outside a session and without a database; a case the calculation refuses is skipped, and a broken rule fails the example with the case, its arguments and `rerun with CORRETTO_SEED=N`. `frappe corretto` passes `CORRETTO_SEED` from the shell to its workers, the one shell setting they receive ([ADR 0010](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0010-corretto-harness.md) decision 11). Nothing changes for existing specs.
- SweetTalk: `require "caramel/sweet_talk/money"` (which requires `caramel/sweet_talk/decimal`) adds money words to a context or a kernel ([ADR 0063](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0063-sweettalk-money.md)). `currencies %w[USD EUR JPY], means: "…"` declares `Currency`, a closed set checked by PostgreSQL, with each code's minor units from ISO 4217 list one (2026-09-17) and `exponent: {XAU: 4}` for a code the list lacks or marks N.A.; `Minor(Currency::USD)` counts minor units and adds only its own currency, so `Minor(USD) + Minor(EUR)` and two `Amount`s added fail compilation, and `Money.same(a, b) { |x, y| x + y }` and `Money.by_currency` combine amounts whose currency is data. `has original : Money::Amount` stores `original_currency` and `original` (bigint); `Minor(USD).parse("12.345")` refuses and `round(text, rounding:)` rounds on purpose; `quote Rate, rounding: :half_up` keeps a dated rate as an exact fraction that `amount.convert(rate)` applies, with exact `inverse` and `through`. Nothing changes for a domain that does not require the module; one that stores money as a `Currency` and a `Cents` value side by side may move to `Money::Amount` and run `frappe db diff`, then `frappe migrate`, for its new columns and checks.
- SweetTalk: `allocation split, of: Money::Amount, by: Weight, remainder: :largest_fraction, means: "…"`, after `require "caramel/sweet_talk/money"`, declares the calculation `split(total, weights)` that shares an amount among the keys of a `Hash` (`Int64`, or the type `per:` names) in proportion to their weights, exactly: each key gets the floor of its share, and the units left go one each to the largest fractions, ties to the smaller key, or all to the first or last key with a weight (`:first`, `:last`) or to a key passed as a third argument (`:to`). Its rules on `result` say the parts add up to the total, each is the floor or ceiling of its share and a zero weight gets nothing, and `Corretto.property` now draws hashes and amounts to run them; a negative weight or weights summing to zero refuse, and `Float64`, `to_f` or a float literal in its types or block fails compilation ([ADR 0063](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0063-sweettalk-money.md) decision 8).
- **Breaking:** SweetTalk: a `follows: Catalogue` in a context whose text names no `Catalogue::` and calls no `Catalogue.verb` outside `border Catalogue`, and a `shares: Money` in a context or kernel that names nothing in Money, no longer compile; the error names the edge at the context's line ([ADR 0059](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0059-sweettalk-domain-report.md)). Remove each edge it names: `Catalogue` from `follows:`, or `Money` from `shares:` and the sharer from Money's `shared_by:`. An unused edge used to count in the cycle check.
- SweetTalk: `SweetTalk.report` returns every glossary term with the facts its declaration holds (a value's bounds and `one_of:` words, an aggregate's states and moves, an event's handlers in run order, a unit's `changes:` and `locks:`, a context's `follows:` and `shares:`), and the application answers `glossary` with it and the context map as JSON. `frappe glossary [--json]` prints it as Markdown and caches it in `.caramel/glossary.json`; `frappe contexts [--mermaid]` prints the context map ([ADR 0059](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0059-sweettalk-domain-report.md)). Nothing to change in an application.
- SweetTalk: the skill `frappe make domain` writes, `.claude/skills/sweettalk/SKILL.md`, now says an entity may hold entities ([ADR 0050](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0050-sweettalk-nested-entities.md)) and to add up with `sums` and `groups`, never `SugarORM.sql` ([ADR 0049](https://github.com/caramelizedev/caramel/blob/v0.22.0/docs/decisions/0049-sweettalk-sums-and-groups.md)); it also names `parts:`, `Created`, `once_by:`, `reached`, `pinned_at:` and `requirements`. `frappe make domain` never replaces an application's copy: refresh it with `cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/`.

## Upgrading to 0.21.0 {#c-releases-upgrade-0210}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; run `frappe db diff` and `frappe migrate` for the tables, columns and checks a domain that adopts the new words adds; the two changes marked **Breaking** need an edit.

- SweetTalk: a `whenever`, service, compensation or deadline may run any number of commands on the one aggregate it changes, and a `create` or a factory followed by a command on the new aggregate counts as one change; a command on a second aggregate still raises `SweetTalk::Boundary`. Two commands on two aggregates called in turn inside one `SugarORM::Repo.transaction` commit and roll back together: that seam is now documented and tested as supported.
- SweetTalk: a command named `finalize` no longer compiles (it would replace the garbage collector's `finalize`); name it for what it does, as in `to wind_up`. `has x : Array(String)` or of any scalar, an attribute named like the tenant association (`has account : …`) or, in an entity, like its parent or `<parent>_id`, and `has tenant`/`has tenant_id` on a tenanted aggregate all fail compilation with a refusal that names the fix.
- SweetTalk: an entity holds entities of its own, at any depth: `entity Mark, means: "…" do … end` inside `entity Slip` with `has marks : Array(Mark)` stores them in `<context>_<aggregate>_<slip>_marks` keyed by `slip_id` (composite with the tenant column in a tenanted context). They load one statement per list per level, save only when a column changed, are deleted children first in one `DELETE` per list per level when dropped, are checked with the aggregate's invariants, and ride in events with their ids. A table name or an entity's `fk_<table>_<parent>_id` over PostgreSQL's 63 bytes fails compilation instead of being truncated silently ([ADR 0050](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0050-sweettalk-nested-entities.md)).
- SweetTalk: every aggregate of a tenanted context has `tenant_id : Int64` and `tenant`, the tenant model's row, so rows read under `Caramel::Tenancy.without` say whose they are. An aggregate and an entity read `created_at` and `updated_at` from their rows, nil until the first save. An entity declares its own `never` and `always`, which a command checks after the aggregate's for every entity in its lists. `Line.new(tea: tea, quantity: quantity)` builds an entity by name, so a defaulted attribute may sit anywhere; the positional form stays and gives a default only to trailing attributes. An aggregate may refer to its own type (`has reversal_of : Entry?` inside `Entry`). `has flag : Bool` (not optional) also defines `flag?`; a `moves` state or a specification named like such an attribute fails compilation.
- SweetTalk: a projection's or a process's attribute may default to a value built from one literal (`Cents.new(0)`, `Tins.zero` or a closed-set member such as `Kind.payment`), whose literal becomes the column's SQL default; a default outside the value's bound stops the program at start, and a value with parts or a calendar day still takes no default there (make it optional). `frappe db diff` adds the default to an existing column.
- SweetTalk: `SweetTalk.emitted { … }` returns the events the block's commands dispatched, in dispatch order, and `SweetTalk.emitted(Order::Placed) { … }` those of one class, typed; specs that reopened `SweetTalk.dispatch` or declared a witness context can drop them. A command enqueues its jobs in declaration order (the contexts' and borders' policies, then projections, then processes); Cold Brew starts them in that order and finishes them in any. `whenever Event, attempts: 5, backoff: :linear, base: 2.seconds` on a context, border, projection or process handler, and on `deadline`, sets that job's retry rule for errors other than a refusal. A process declares `finds` and `counts` as a projection does; a process query named `all`, `new` or `allocate`, or with `satisfying:`, no longer compiles. Entities come back from a `find` by id, which is insertion order; an in-memory reorder is not persisted.
- `frappe corretto` takes a whole-run lock, `.caramel/corretto/run.lock`; a second run in the same project prints `Corretto: waiting for another run in this project` and starts when the first ends, so parallel runs no longer share workers and drop each other's databases.
- SweetTalk: a command's save writes the root and each entity only when a column changed, and deletes only the entity rows it loaded and dropped, in one statement per list and none when it dropped none, so a 300-line aggregate no longer costs one statement per line per command. `Order.find(id, entities: false)` and `find?` read the root in one statement; reading a list on it raises `SweetTalk::Unloaded`, naming the fix, and a command on it loads the lists under its lock as every command does.
- SweetTalk: an entity has `Line::Id` and `line.id` once its aggregate is saved. An entity in an event is packed when the command dispatches, after its save, so its JSON carries `"id"` and a handler reads `line.id`, for a factory's new lines too. A job queued before this release holds entities without `id`; `line.id` on one raises.
- SweetTalk: a context declares its own events, `event Renamed, name : String, means: "…"`, for a change no aggregate holds, and a service body emits them with `emit Renamed, name: name`, dispatched in the service's transaction on `sweettalk.<context>.<event>` (behind a tenant's `t<id>:` prefix); the subject is the bound tenant's id under `caramel/tenancy`, else nil, so `Event#__sweettalk_subject_id` is now `Int64?` and a policy job's `subject` param is optional. `emit` in a context anywhere but a service body, and `carries:` on a context event, fail compilation.
- `frappe check` now types every SweetTalk command, factory and service body, called or not: each `to`, `factory` and `service` emits a never-run `__sweettalk_touch_<name>` that `SweetTalk.boot` and the whole-program checks reference. `frappe make domain` writes `SweetTalk.boot` after `require "../app/domain/*"` in `config/application.cr`; an application generated before this release adds that line by hand, or `frappe check` keeps passing bodies nothing calls. A body that never compiled now fails `check` at its own line.
- A generated index name over PostgreSQL's 63 bytes is no longer refused by SweetTalk nor truncated by PostgreSQL: SugarORM names it `index_<table>_on_<cut>_<fnv8>`, the column list cut so the name fits and the FNV-1a hash of the whole name as eight hex digits, so `frappe db diff` plans it once; a database that already holds a PostgreSQL-truncated index gets it dropped and the shortened one created on the next diff.
- SweetTalk: `sums spent_by(member : Account), of: Line.price, where: {member: member, state: :placed}` and `groups priced_by_tea(member : Account), of: Line.price, by: Line.tea, where: {…}` are declared beside `finds` and `counts` on an aggregate, a projection or a process, and add one attribute up in one statement over the live rows of the bound tenant: `of:` names an attribute by symbol or a first-level entity's as `Line.price`, an `Int32`, `Int64` or `Float64` column or a value wrapping a whole number or a decimal with no bound a sum can break; `groups` returns `{by: key, total: sum}` rows ordered by the stored key, `by:` an attribute of the same model stored in one column, or `:state` ([ADR 0049](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0049-sweettalk-sums-and-groups.md)). The cookbook recipe *Sum and group a context's rows* (proved by `scripts/check page-sums`) now uses them. SugarORM gains `sum_text`, `group_sum_text` and `where_in(:field, parent_query)`.
- SweetTalk: `has label : String, unique: true` (or `unique: "sentence"`), `index: true` and `check: {"sql", "sentence"}`, and over several attributes `unique :a, :b, otherwise: "…"`, `index :a, :state` and `check :name, "sql", otherwise: "…"`, declare a unique index, a plain index or a CHECK PostgreSQL keeps ([ADR 0045](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0045-sweettalk-database-constraints.md)). A violation is a `SweetTalk::Refusal` with that sentence (an action answers 422); a constraint SweetTalk did not declare stays a `SugarORM::UniqueViolation` or `CheckViolation`. An entity's `unique` is unique within its parent; a projection or process refuses these words. In a tenanted context the tenant column joins every unique index. `frappe db diff` builds a new index `CONCURRENTLY` and adds a check `NOT VALID` then validates it; a table holding duplicates leaves an INVALID index that halts the next diff, so find them first with `GROUP BY … HAVING count(*) > 1`. A command's save now deletes the entity rows it dropped before it writes the root and the kept entities, so an entity replaced by one with the same unique value saves.
- SweetTalk: `value Cents, Int64, at_least: 0, otherwise: "A balance cannot go below zero.", means: "…"` refuses every value outside its bounds with that sentence, wherever the value is built, in place of the generated one; `otherwise:` goes with `at_least:`, `at_most:`, `within:`, `matches:`, `length:` and `one_of:`, and with a decimal's bounds, while a decimal's shape refusals keep theirs and a value without bounds, a day, a document or a value with parts refuses the word at compile time. The database check is unchanged ([ADR 0045](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0045-sweettalk-database-constraints.md) decision 8).
- SweetTalk: `unit post(journal : Journal::Id, segments : Array(Segment::Id)), changes: [Journal, Position, Segment], locks: [journal, segments], returns: Nil, means: "…" do … end` in a context declares a unit: one transaction that locks the rows `locks:` names first, one statement per table in table then id order, runs its commands on the aggregates `changes:` lists, then its own `never`/`always` lines over the set, and rolls everything back on any error, reloading every aggregate instance it touched. A command on a type outside `changes:`, or on an existing row that was not locked, raises `SweetTalk::Boundary`; a unit inside a command, a factory or another unit raises too; inside a service or a handler it counts as that handling's one change. `SweetTalk.lock(*ids)` is the same ordered lock for your own `SugarORM::Repo.transaction` and raises `ArgumentError` outside one. `unit` in an aggregate, entity, projection, process or kernel, without `means:`, or naming a foreign aggregate without `follows:` fails compilation ([ADR 0046](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0046-sweettalk-units.md)).
- SweetTalk: `SweetTalk::Unit` and `Fiber#__sweettalk_unit`, the row batch of a projection's or process's handler, are now `SweetTalk::Work` and `Fiber#__sweettalk_work`; a spec that called `SweetTalk.__sweettalk_unit { … }` calls `SweetTalk.__sweettalk_work { … }`. `publishes` may name a unit.
- SweetTalk: `value Rate, Decimal(20, 8), at_least: "0", at_most: "1", means: "…"` is a decimal value, a `BigDecimal` kept exact in a `numeric(20,8)` column through the new `SugarORM::DecimalCodec(P, S)` with its bounds as a CHECK named after them ([ADR 0047](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0047-sweettalk-decimal-and-json-values.md)). It is opt-in: `require "caramel/sweet_talk/decimal"` before the domain links GMP, and a program without it never does. Bounds are decimal text; a bound that is not, or written past S decimals, fails compilation. `Rate.new("0.05")` reads digits with a point and refuses other text, a value the column would round or overflow, then one outside the bounds; ranges, `order:`, `counts` and specifications read it as a number; in JSON, events, jobs and contract fields it is the string `"0.05"`. `value Evidence, Json(Snapshot), means: "…"` (a `JSON::Serializable` type) or `value Note, Json, means: "…"` (`JSON::Any`) is a JSON value kept whole in a `jsonb` column; `where:` asks only equality or `nil`, a range fails compilation and `order:` on it is refused. A projection's or process's decimal or JSON attribute takes no default, so make it optional. `value Grams, Float64` now fails with `wraps Int32, Int64, String, Date, Decimal(P, S) or Json(T)`.
- SugarORM: `require "sugar_orm/decimal"` adds `SugarORM::DecimalCodec(P, S)` (`field rate : BigDecimal, codec: SugarORM::DecimalCodec(20, 8)`), orderable, writing plain digits and raising `ArgumentError` at the write for a value past S decimals or P − S digits; `sugar_orm` itself does not require it, so GMP stays unlinked by default.
- SweetTalk: `context Billing, event_log: true, means: "…"` keeps every event of the context, and of the kernels it shares, in `billing_events`, one row written in the command's or service's transaction (`event_id`, `aggregate`, `name`, `subject_id`, `occurred_at`, `actor`, `cause_id`, `flow_id`, `fields` jsonb), part of the derived schema so `frappe db diff` creates it, tenanted like the context's rows. `Billing.logged(Invoiced, subject:, since:, limit:)` reads typed events oldest first, `Billing.logged(subject:)` every class as `SweetTalk::Event`, and `event_log: 90.days`, or any whole number of days or weeks, keeps each event that many days, pruned hourly by a Cold Brew schedule named `sweettalk:prune:billing_events`. A context without the keyword logs nothing ([ADR 0048](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0048-sweettalk-event-log.md), [ADR 0051](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0051-sweettalk-event-log-replay-and-retention.md)).
- SweetTalk: `SweetTalk.rebuild(Billing::Sales)` empties a projection and replays the events it follows from its context's log under `pg_advisory_xact_lock`, leaving an event a queued job of its handlers still has to apply to that job, and returns `SweetTalk::Rebuilt` (`replayed`, `deferred`, `oldest`); it covers only events logged since `event_log: true` was set, and a handler that reads present state replays against present state. A projection whose context keeps no log, or that follows an event the log does not keep, fails compilation. A projection whose context keeps its log a number of days does not compile. `whenever Order::Placed, after: Sales do … end` runs a handler only once the named projection's, process's or context's handler of the same event has committed: the command does not enqueue it; the predecessor's job enqueues it in its own transaction, and a refused or permanently failed predecessor never releases its followers. An `after:` naming an owner that does not follow the event, a predecessor with `each:`, or a circle of `after:` fails compilation.
- SweetTalk: `event Printed, number : String, till : String, older: {till: "front"}` gives the value a queued job or a logged row stored without the field reads ([ADR 0051](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0051-sweettalk-event-log-replay-and-retention.md)).
- **Breaking:** SugarORM: a foreign-key violation (SQLSTATE 23503) is now `SugarORM::ForeignKeyViolation` with `table` and `constraint`, a serialization failure (40001) `SerializationFailure` and a deadlock (40P01) `DeadlockDetected`, both `TransactionConflict`, each keeping PostgreSQL's error as its `cause`; a rescue of `PQ::PQError` for those codes rescues the new class instead. `Repo.transaction(retries: 2) { … }` runs the block again after a conflict, outside a transaction only. A `has_one` preload reads one row per owner, the lowest primary key. New terminals: `min_text`, `max_text`, `avg_text`, `group_count(:by)`, `joins(:parent)`, `joins(:parent, query)` with `order_by_joined(:parent, :field)` for a `belongs_to`, `each_batch(size)` and `page(size, after:, direction:)` ([ADR 0052](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0052-sugarorm-conflicts-retries-and-reads-at-scale.md)). `frappe make resource` generates a Destroy that answers 409 "… is still in use" when a foreign key stops the delete, with an `in_use` message in the resource's locale catalog; an app generated before this release adds the `rescue SugarORM::ForeignKeyViolation` and `conflict(…)` to its Destroy by hand.
- **Breaking:** SweetTalk: `create` now announces `Created` in the same transaction, an event of the aggregate on `sweettalk.<context>.<aggregate>.created` that carries every attribute, so a `whenever` follows it, an `event_log: true` context keeps it and `SweetTalk.emitted` lists it; the glossary gains a term per aggregate without a factory, and a `create` writes a log row. Declare `event Created, carries: [member], means: "…"` to carry some attributes only; a declared `Created` that lists fields, or a `Created` channel past PostgreSQL's 63 characters (42 with `caramel/tenancy`), fails compilation, and an aggregate with a factory has neither ([ADR 0053](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0053-sweettalk-create-announces-created.md)).
- SweetTalk: `has kind : Kind, parts: {payment: [payee], net_settlement: [payee, leg]}` ties optional attributes to the members of a closed-set value: one CHECK per member of the value, `check_<table>_<attribute>_<member>_<hash>`, holds the parts the member lists set and every other listed part null, a `never` refuses the same in Crystal with “Settlement kind payment holds payee and no leg”, and `as_payment` reads the member's parts as a named tuple, raising `TypeCastError` for another member. `frappe db diff` adds each check `NOT VALID`; find the rows that break one with `SELECT id FROM <table> WHERE NOT (<sql>)` first ([ADR 0054](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0054-sweettalk-kinds-with-parts.md)).
- SweetTalk: `unit post(key : String, …), once_by: key, otherwise: "…"` runs once per operation key: the first run keeps the key, a fingerprint of the other arguments and its result in `<context>_operations` (a new table `frappe db diff` creates, tenanted like the context's rows, kept forever), a repeat with the same arguments answers the first result without running, a repeat with other arguments is refused with the `otherwise:` sentence, and an error rolls the claim back so a retry runs again. An aggregate in the other arguments or in `returns:`, an `otherwise:` without `once_by:`, or a key that is not text fails compilation ([ADR 0055](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0055-sweettalk-units-that-run-once.md)).
- SweetTalk: `Books.reached(event)` returns the events that followed from an event, read from every context's log by `cause_id`, oldest first, as `SweetTalk::Reached` (`events`, and `by_subject` grouping by aggregate and id); the walk passes only through logged events and raises `ArgumentError` for an event its log does not keep. `has rules : Setup::Rules, pinned_at: :finalized` copies the referenced aggregate as JSON into a new column `rules_pinned` when a mover enters the state, read through `pinned_rules` as a read-only copy that raises `SweetTalk::Boundary` for a command; the column is added by `frappe db diff` ([ADR 0056](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0056-sweettalk-reached-events-and-pinned-references.md)).
- SweetTalk: `requirements "AC-01", "AC-02"`, in the domain module before its first context, lists requirement ids, and `assures: "AC-12"` (or a list) on a `never`, an `always`, a `specification`, a `unit` and a unit's own `never`/`always` says which ids a line answers; an id the module does not list fails compilation. `SweetTalk.declared_requirements` returns each id with what assures it, `frappe requirements [ID]` lists them (the application answers `requirements [ID|--ids]`), and a `frappe corretto` run with no paths now fails when every worker passed but an id appears in no example's full description, as in `it "refuses an unbalanced entry (AC-12)"`; each worker writes the descriptions it ran to `.caramel/corretto/w<N>.examples`. An application that declares no requirements is not checked ([ADR 0057](https://github.com/caramelizedev/caramel/blob/v0.21.0/docs/decisions/0057-sweettalk-requirements.md)).

## Upgrading to 0.20.0 {#c-releases-upgrade-0200}

Upgrade Caramel and Frappé together. Run `frappe migrate` once for a framework migration; nothing is removed; the three changes marked **Breaking** need an edit, and every user signs in again once.

- SweetTalk: `kernel Money, shared_by: [Pricing, Billing], means: "…" do … end` declares a shared kernel, a module of `value` and `aggregate` declarations that two or more named contexts or kernels share; each sharer says `shares: Money` (or `shares: [Money, Calendar]`), naming kernels declared before it. Only a sharer may name `Money::` types, run its aggregates’ commands or react to its events, a kernel may not name a context or reach `Caramel::Outbound`, and every value or aggregate of a kernel that nothing else in it uses must be named by two or more sharers; each refusal fails compilation at the line that causes it. A kernel stores like a context (`money_vouchers`), belongs to the tenant under `caramel/tenancy`, appears in the glossary with kind `kernel`, and draws a `kernel` edge in the context map ([ADR 0044 ↗](https://github.com/caramelizedev/caramel/blob/v0.20.0/docs/decisions/0044-sweettalk-shared-kernels.md)). Nothing changes for a program without one.
- `APP_ORIGIN` is normalised once: the host is lowercased and an explicit `:443` dropped, so `https://Example.com:443` works, and a request whose `Host` or `Origin` header differs from the origin only in case or by `:443` is accepted instead of answering 421 or 403. `Caramel::CSRF#origin` returns the normalised form (`https://example.com`).
- A session write that would take the `__Host-caramel_session` cookie past 4096 bytes (`session["key"] = value`, `merge!`, `update`, `put`, `put_if_absent` or `transform_values!`) raises `Caramel::Session::Overflow` at the write and leaves the session as it was, so an action fails there instead of answering 500 after the records it wrote committed. `session` is now a `Caramel::Session::Data`, a `Hash(String, String)` subclass; `Caramel::Session.fits?(data)` and `.cookie_bytes(data)` say whether and how big a hash would encode, and `Session#encode` still raises `Overflow` for a hash built some other way.
- An `update` whose changeset changes nothing no longer reports success without a query: it writes nothing (no `updated_at` bump, no version increment) but reads the row by key, tenant and loaded version, so a row deleted meanwhile adds `Record no longer exists` under `_base` and, on a versioned schema, a stale copy adds `Record changed since you loaded it` with `stale?` true. Code that relied on a no-change update of a missing row being `saved?` must handle the error.
- `SugarORM::Migrator#migrate` no longer lets a failing `pg_advisory_unlock` replace the migration’s own error: when the connection broke mid-run the statement’s exception (typically `DB::ConnectionLost`) propagates, and the unlock failure is one line on the migrator’s warnings IO; the session-level lock dies with its session anyway.
- Cold Brew’s schedule lease takes its advisory lock in Caramel’s two-key namespace (`Caramel::ColdBrew::Scheduler::LOCK_NAMESPACE`, `hashtext(name)`), so it no longer meets an application’s own `pg_advisory_lock(n)`. A schedule block that raises now counts its period as run, so the next attempt comes after its span instead of within a minute; a block that must retry sooner should enqueue a job.
- Crema’s metrics recorder upserts each window’s `caramel_metrics` rows in `(kind, key)` order, so a web process and a worker flushing the same minute no longer deadlock and drop a window.
- **Breaking:** `Caramel::Outbound` resolves the host of a direct call first and raises `Caramel::Outbound::Blocked` when any resolved address is loopback, private (RFC 1918, 100.64/10, fc00::/7), link-local, multicast or reserved, classifying v4-mapped and NAT64 addresses by their embedded IPv4; it then connects to the vetted address itself, so DNS rebinding cannot swap it. An application that calls a service on a private network sets `Caramel::Outbound.allow_private = true` at boot; calls through `Outbound.proxy`, such as Corretto’s wire proxy, are not checked. Every call reads at most 10 MiB of response (`Caramel::Outbound::TooLarge`) and finishes within 60 s in all (`IO::TimeoutError`), on top of the 5 s connect and 30 s read timeouts; `Outbound.max_response_bytes` and `Outbound.deadline` change those limits. Requests send `Accept-Encoding: identity` unless the caller sets one, and bodies are no longer decompressed.
- **Breaking:** the `__Host-caramel_session` cookie carries the second it was signed and reads as empty 14 days after its last write (`Caramel::Session::MAX_AGE`; `Caramel.build(..., session_max_age:)` or `Application.new(..., session_max_age:)` change it) or when signed more than a minute ahead of the clock. It is re-signed only when an action changes the session, so the window is absolute from the last write; it stays a browser-session cookie with no `Max-Age`. Cookies in the previous format read as empty, so every user signs in again once. `Session.new` takes the `Array(Bytes)` of `CSRF#derive_keys("session")`, and the largest session shrinks by 11 bytes.
- `APP_SECRET_PREVIOUS` (comma-separated, each at least 32 bytes) lists secrets `APP_SECRET` replaced: sessions and CSRF tokens they signed still verify, new ones are signed with the current secret, and a changed session is re-signed with it; unset it once 14 days have passed. `Caramel::CSRF.new(secret, origin, previous)` and `CSRF#derive_keys(purpose)` expose this; `derive_key` (Crema’s debug key) stays current-only. `.env.test` may not set `APP_SECRET_PREVIOUS`.
- `serve`, `work` and `seed` start when the database journal holds migrations the binary lacks, printing `WARNING: the database holds migrations this binary lacks (vN, …); starting anyway` on standard error, so an old process restarted after the new binary ran `migrate` keeps serving until cutover. A migration the binary has but the journal lacks still exits 1 with `Pending migrations. Run frappe migrate first.`; `migrate` and `lint` still refuse a journal ahead of them. `SugarORM::Migrator#pending` takes `allow_ahead : Bool = false` and `Migrator#ahead` lists the versions the binary lacks.
- The zero-lock linter gains rules `drop-table`, `truncate`, `rename-table`, `alter-column-type`, `set-not-null`, `constraint-not-valid`, `concurrent-drop-index`, `bulk-write` and `hidden-ddl`, and reads `DO $$…$$` bodies, `$tag$` quotes and `E'…'` escapes. `frappe migrate` and `frappe db diff` may now refuse hand-written migrations that passed before; each refusal names the rule, the statement and the remedy, a table created in the same migration stays exempt, and `--dev-override` is unchanged. A refusal the author means to overrule takes the line `-- caramel:allow RULE SUBJECT` above the statement (the table, `table.column`, or the index for `concurrent-drop-index`); `-- caramel:allow-drop` and `-- caramel:allow-rename` keep working. `frappe db diff` writes `-- caramel:allow alter-column-type table.column` above the checked text-to-date retype.
- Framework migration `20260927000007 index_caramel_jobs_locked_and_claim` adds `caramel_jobs_locked`, which the stale-lock release uses, and `caramel_jobs_claim`, which the claim walks instead of sorting the due backlog. A partitioned table refuses `CREATE INDEX CONCURRENTLY`, so `frappe migrate` builds them plainly, holding a SHARE lock on each job partition for the build; run it when the queue is quiet.
- A job lock whose database session is gone, or whose PID now belongs to a session started after the lock, is released by the next maintenance pass, within a minute, instead of after 15 minutes; `Maintenance.new(stale_after:)` defaults to zero. Maintenance runs every step of a pass even when one raises (reported as handled) and creates partitions first. `caramel_jobs.last_error` never holds NUL bytes or invalid UTF-8; when a failure write raises, Cold Brew stores the class alone, and if that raises too it clears the lock so the job runs again.
- Idle worker fibers poll every second (was 50 ms) and are woken at once by the enqueue’s `pg_notify('caramel_jobs', queue)` through the process’s PubSub broker; `Worker.new(idle:)` keeps the old interval, and a process without a broker polls only.
- `Caramel::SSE.relay(io, updates, event:, heartbeat:)` writes a subscription’s payloads as events and a `: ping` comment after each 15 seconds without one (`Caramel::SSE::HEARTBEAT`), so a stream whose client went away ends at the next heartbeat instead of at the next event; `Caramel::SSE.comment(io, text)` writes one comment line. Replace `loop { Caramel::SSE.write(io, event: …, data: updates.receive) }` with `Caramel::SSE.relay(io, updates, event: …)`; with `relay`, a subscription that closes ends the stream normally. The PubSub broker runs `SELECT 1` on its LISTEN connection every 30 s and reconnects when the acknowledgement does not arrive within 5 s.
- Crema redaction also removes the `user:password@` of any URL, `Cookie`/`Set-Cookie` lines and the values of PostgreSQL’s `Key (…)=(…)` detail from error messages and backtraces. The OTLP exporter normalises `db.query.text` before sending (strings and bare numbers become `?`, comments go, the text is cut to 500 bytes; `$n` binds stay). Text log lines escape control characters as `\n`, `\r`, `\e` or `\xNN` and quote the value, so client input cannot forge a line. `Caramel::Crema.trust_trace_context = false` (or `CARAMEL_TRUST_TRACE_CONTEXT=0`) ignores inbound `traceparent` and `X-Request-ID`, so a client cannot force sampling. An `http://` OTLP endpoint off the loopback interface with `OTEL_EXPORTER_OTLP_HEADERS` set logs `OTLP headers are sent in clear to HOST; use an https endpoint` at start.
- **Breaking:** a route inside the `tenant` block fails compilation unless its action, or a parent, declares `ingress authenticate: :method?`, or the action declares the new `ingress open: true`. Add one to every existing tenant action; `frappe routes` prints `[open]` for open routes. `ingress open: true` cannot combine with `authenticate:` and cannot be declared under a parent that authenticates.
- `frappe make tenancy` writes `member?` into `app/actions/application_action.cr` (true when `session["accounts"]`, the slugs this session signed up, names the tenant), guards the tenant home with `ingress authenticate: :member?`, and its sign-up action joins the session; the generated `tenant_session(slug)` signs up the slug through `/accounts`. `frappe make resource` in a multi-tenant application writes `ingress authenticate: :member?` into every tenant action, and its request spec proves 404 for another tenant’s member and 401 for a non-member. Replace `member?` with a membership table as the sessions recipe shows.
- Every git dependency in `shard.lock` is locked to the commit its tag pointed at, in Shards’ own form `version: 0.31.0+git.commit.<sha>`; `scripts/shards install` fails when a pinned shard was installed at another commit, and `scripts/check shard-pins` refuses an unpinned entry. An application generated from a release tag locks Caramel’s commit (`version: 0.20.0+git.commit.<sha>`) and copies the framework’s pinned entries. An existing application adopts the pins without `shards update`: copy the `pg`, `db`, `blueprint` and `lexbor` entries from this release’s `shard.lock` into yours, add `+git.commit.<sha>` (the release tag’s commit) to the caramel entry, then run `frappe setup`; `shards update` strips the pins, so update a dependency by writing its tag’s commit into the lock instead. `frappe lsp install` rebuilds crystalline once, with its `lsp` dependency pinned and verified.
- `frappe build` writes two files beside the artifact: `SHARD-….tar.gz.sha256`, which `sha256sum -c` or `shasum -a 256 -c` verifies, and `SHARD-….tar.gz.sbom.json`, a CycloneDX 1.5 bill of materials naming the application at its commit, the Crystal version, each shard with its version and commit, and the musl, gc, gmp, OpenSSL, pcre2 and zlib versions linked into the binary, with the image digest under `properties`. The artifact path is still the only line on standard output. `CARAMEL_BUILD_IMAGE`, set where `frappe build` runs, replaces the pinned build image, for example with one carrying a patched OpenSSL; it must name the image by digest (`…@sha256:<64 hex>`) or the build exits 1.
- `frappe corretto` reports each preparation phase with its duration (`Corretto: template checked in 0.0s`, `template migrated`, `worker databases cloned`, `workers finished`, `workers dropped`), whether each worker’s spec binary was reused or built, and ends with `Corretto: M of M workers passed in <total>`; a script that matches that line exactly needs the ` in <duration>` suffix. Worker output that stays on one line for five seconds, such as progress dots, is forwarded as far as it goes.
- Latte’s runtime directory moved from `/private/tmp/caramel-<uid>-<digest>` to `~/Library/Caches/Caramel/<digest>`, which another user cannot pre-create. Stop a daemon from an earlier release with that release’s `latte stop` before starting this one, and restart `frappe dev` sessions started under the old path. Latte refuses with `runtime_path_too_long` when a home directory would push a socket path past macOS’s 103 bytes. `scripts/crystal` keeps its OpenSSL alias under `$TMPDIR`. The trace collector answers 421 to a request whose `Host` is not `127.0.0.1`, `localhost` or `[::1]` with its port, and keeps at most 64 MiB of traces. `latte trust install` refuses, naming the file, when a key under `services/caddy/storage/pki/authorities/caramel/` is not an owned file of mode 0600.
- Latte’s DNS, HTTP and HTTPS listeners move with `CARAMEL_LATTE_DNS_PORT`, `CARAMEL_LATTE_HTTP_PORT` and `CARAMEL_LATTE_HTTPS_PORT` (1024 to 65535; defaults 15353, 18080, 18443). With `CARAMEL_HOME` a second Latte runs beside yours; the resolver and the relay serve the default ports only, and such a Latte’s HTTP listener redirects to its own HTTPS port. `frappe services start` refuses before starting anything when a listener a service needs is held, naming the owner (`DNS port 15353 is in use by coredns (pid 22064)`, `port_in_use`); a service already running keeps its port. `scripts/check latte-daemon` runs on free ports of its own, so no check needs your own Latte stopped.

## Upgrading to 0.19.0 {#c-releases-upgrade-0190}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; a SweetTalk domain that adopts the new word keeps its days in a `date` column.

- SweetTalk: `value Day, Date, means: "a calendar day"` is a real calendar day, from year 1 to 9999, over `SugarORM::Date` (`day.raw`), stored in a `date` column through `SugarORM::DateCodec`, so `has settled_on : Day`, `has returned_on : Day?` and a `part` of a value with parts each get one, and a text column that held a day, such as a former string value, is retyped by the check-first migration `frappe db diff` already derives. `where: {settled_on: from..to}` in `finds`, `counts` and `specification` takes a closed, beginless or endless range of days, `order: {settled_on: :desc}` sorts by day, and an event field and a Cold Brew job carry it as `YYYY-MM-DD`. A day is that text in JSON too, and a contract field binds it from that text with `Day must be a calendar day written YYYY-MM-DD, as in 2026-02-28` as its error. `Day.new("2026-02-30")` refuses, `Day.new(2026, 3, 1)` and `Day.of(time)` (the time’s own calendar day, with no conversion to UTC) build one, `day + 7`, `day - 7` and `day - other` move and count by days, and days compare and sort. There is no `Day.today`: a command takes the day it means as an argument. A `has` reaches a codec through a value’s `SWEETTALK_CODEC`: `Date`, `Decimal(P, S)` and `Json(T)` name one (ADR 0043, ADR 0047).

## Upgrading to 0.18.0 {#c-releases-upgrade-0180}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; a SweetTalk domain that adopts the new words gains table constraints, and one optional attribute changes its default.

- A codec may now name the `date` column type, and `SugarORM::Date` with `SugarORM::DateCodec` stores a calendar day in it: `field due_on : SugarORM::Date, codec: SugarORM::DateCodec`. A `Date` is a year, a month and a day with no time of day and no zone; `Date.parse` reads only `YYYY-MM-DD`. A `date` column read in a session whose `DateStyle` is not ISO, or holding `infinity` or a BC date, raises ArgumentError instead of guessing a day. `frappe db diff` creates and compares the column like any other. A codec that declares `ORDERABLE = true` before its schema, as `DateCodec` does, lets keyword `where` take a Range on that column (`where(due_on: first..last)`); the numeric, `jsonb` and `text` codecs still take only a value or `nil` (ADR 0042).
- A text column that the schema now declares `date` (a field with `SugarORM::DateCodec`) no longer halts `frappe db diff`: the diff derives a migration that locks the table, counts the values that are not a calendar day written `YYYY-MM-DD` and stops with that count and up to five of them if there are any, then drops the column’s default and runs `ALTER COLUMN … TYPE date USING "col"::date`. The retype rewrites the table under an exclusive lock, and the check needs PostgreSQL 16 or newer. Every other type change, including `date` back to `text`, still halts (ADR 0042).
- SweetTalk: a type followed by `?` makes a `has` attribute optional for every type it takes. `has owner : Setup::Owner?` stores a nullable `owner_id` foreign key and its getter returns the id or nil, `has settled_by : Teller?` a nullable column of its raw type, and `has leg : Money?`, a value with parts, one nullable column per part with a `CHECK` that every part is set or none is (`check_<table>_<attribute>_all_or_none_<hash>`, the hash of the value’s part names, so a part added replaces it), which loading such a row also enforces. A command points a reference with its new private writer, `self.owner = other` (the aggregate, the record or its id, or nil when optional); a projection’s `whenever` handler assigns `row.owner = other` on the row it holds, and `@owner = other`, `@owner ||= other` or a multiple assignment in a command, factory, process step, compensation or deadline, which would declare a stray instance variable, does not compile; a projection’s key has no writer. `where: {owner: nil}` in a `finds`, `counts` or `specification` asks for the rows where it is not set, and does not compile for an attribute that is not optional. A projection’s or a process’s `key` cannot be optional, and a factory takes an optional attribute declared before a required one. Use `?` for what a thing may lack: a column only some kinds have belongs in a value with parts or a state, and a rule that ties one attribute to another stays a `never` (ADR 0039).
- **Breaking:** a SweetTalk optional attribute now defaults to nil, including the existing `has note : String?`. A factory or `create` that did not set it used to fail with "factory does not set note" and now leaves it nil, so code that relied on that error no longer gets it. `order: {x: :desc}` on an optional column sorts the rows with no value first, and `:asc` last, as PostgreSQL does.
- **Upgrade, SweetTalk:** the new CHECKs and a new foreign key are added by `frappe db diff` `NOT VALID` and validated in a later step, so existing rows that break one stop `frappe migrate`. Find them first: for an optional value with parts, `SELECT id FROM <table> WHERE num_nonnulls("<attribute>_<part>", …) NOT IN (0, <parts>)`; for a foreign key added to a column that held ids, `SELECT t.id FROM <table> t LEFT JOIN <target> o ON o.id = t."<attribute>_id" WHERE t."<attribute>_id" IS NOT NULL AND o.id IS NULL`.
- SweetTalk: `value Kind, String, one_of: %w[payment receipt], means: "…"` is a string value that is one of a closed list, written once. It refuses another text, adds `Kind.all`, `Kind.includes?(text)`, `Kind.payment` and `kind.payment?`, and every column that stores it gets `check_<table>_<column>_one_of_<hash>`, which changes with the list, so `frappe db diff` replaces it when a word is added or removed; `database_check: false` keeps the list in Crystal only. The check is added `NOT VALID` like the others, so a row outside the list stops `frappe migrate`: find it with `SELECT id FROM <table> WHERE "<column>" IS NOT NULL AND "<column>" NOT IN (<words>)`. It takes neither `matches:` nor `length:`, and a word that names a method the value, every object or Crystal already has, such as `all`, `name` or `end`, does not compile. The compile error for a string value’s unknown options now names `one_of:` (ADR 0040).
- SweetTalk: `event Settled, carries: [kind, amount, owner], means: "…"` takes one field for each attribute or derived value named, of its type, and `emit Settled` reads them from the aggregate when it runs, so no command restates them. A name the aggregate lacks above the event, a name twice, or one named like the event’s metadata does not compile, and neither does an `emit` that gives a carried field, which would say what the aggregate does not hold. An optional field a job queued before it existed lacks reads as nil. `carries:` makes the event a snapshot of the aggregate, so renaming or retyping a carried attribute changes the payload of jobs already queued; a rename is safe only when the new attribute is optional, as the ADR says (ADR 0041).

## Upgrading to 0.17.0 {#c-releases-upgrade-0170}

Upgrade Caramel and Frappé together. There are no framework migrations; the toolchain changes, every model an action returns needs a `json` line, and direct callers of the ops socket send its key.

- Public files are now streamed with `Content-Length`, `ETag` and `Last-Modified`, answer 304 to a current `If-None-Match` or `If-Modified-Since`, and carry `Cache-Control: public, max-age=31536000, immutable` when the name has a three-part version (`htmx-4.0.0.min.js`) and `no-cache` otherwise. `public/.well-known/` files are served, and any other path with a hidden segment (`/.env`, `/.something`) now goes to the router instead of answering 404 in the static layer, so a route such as `/.well-known/change-password` is reachable. A file that cannot be read answers a 500 with the security headers. Ranges are not supported.
- Caramel now pins Crystal 1.22.1, which fixes io_uring event loop hangs, `OpenSSL::SSL::Options::ALL` and the `Content-Length` regressions of 1.22.0. Installing this release sets up a new toolchain directory, so its first builds start with an empty compiler cache. If you use the editor tools, run `frappe lsp install` again after installing. New applications declare `crystal: ">= 1.22.1"` in `shard.yml`, and `frappe build` compiles in `crystallang/crystal:1.22.1-alpine`. The toolchain also moves to OpenSSL 3.6.5, which fixes the advisories of 3.6.4.
- Cold Brew’s pool now holds four spare connections beside the worker fibers instead of one: one for maintenance, two for schedule blocks, and one for Crema’s recorder and console. A slow schedule block no longer makes maintenance and the other schedules fail their checkout. At most two schedule blocks run at once in a process, and a third due block waits for one to finish. A `serve` or `work` process may now hold three more connections, up to `CARAMEL_POOL_SIZE` + queues × `CARAMEL_WORKER_CONCURRENCY` + 5, so check the runtime role’s limit of 24 against the processes you run during a deploy. The most worker fibers across all queues is 28, down from 31, and `CARAMEL_WORKER_CONCURRENCY` above that limit now stops the process at start.
- Breaking for direct callers: every request to the ops socket must carry the per-start key in `<socket>.key` (mode 0600, new at each start, removed at stop). Anything that talks to the socket without `APP ops` (`curl --unix-socket`, scrapers) must send `Authorization: Bearer $(cat SOCKET.key)`; Prometheus uses `authorization: credentials_file: SOCKET.key`. A request without the key answers 401. `ops console` prints a URL containing the key, and a TCP forward without that URL gets 401.
- `frappe setup --no-migrate` installs dependencies and registers the site but leaves the development database unchanged, and prints that migrations were skipped and that `frappe migrate` applies them; `setup` without the flag still applies pending migrations.
- With `caramel/tenancy` and no tenant bound, a cache key or PubSub channel name that starts with `t<id>:` now raises ArgumentError (inside `Caramel::Tenancy.without` it is allowed), and `Caramel::Cache.clear` deletes only the bound tenant’s keys; with none bound it deletes only keys with no tenant prefix, and inside `without` every key. Wrap an app-wide clear in `without`.
- `APP db roles` (and `DatabaseRoles.role`) now validate role and database names themselves, keep a password out of the `DO $` body, and the script fails before any grant when a role that already exists has SUPERUSER, CREATEDB, CREATEROLE, BYPASSRLS or REPLICATION. Run it with `psql -v ON_ERROR_STOP=1`; the role that runs it stays a member of both roles until you revoke them.
- `frappe lint` and new applications’ `.ameba.yml` enable `Caramel/SourceTreeRead`, which reports a `File.read`, `File.open` or `Dir.glob` whose arguments contain `__DIR__`; a release artifact holds no source tree, so such a read fails only in production. Add the block to an existing application’s `.ameba.yml` to adopt it. The deploy guide now says what the artifact holds and how to embed a file with `read_file`.
- A record is written as JSON only with the columns its schema’s `json` line lists, such as `json :id, :title, :created_at, :updated_at`, where it wrote every column. Every model an action returns, or any other code writes as JSON, needs a `json` line; compilation fails without one and the error names the model. `frappe make resource` writes the line for new resources, listing the id, its fields and the timestamps, never the tenant column.
- `Caramel.content_security_policy` (in `config/application.cr`) changes the Content-Security-Policy of every response, `content_security_policy` in an action changes one response’s copy, and `csp_nonce` adds a per-response nonce to `script-src` and `style-src`. A header an action sets itself is kept. `serve` now sends `Strict-Transport-Security: max-age=31536000` when `CARAMEL_ENV` is production or unset, so a proxy that added it can stop; it is never sent in development or test.
- At the first SIGTERM or SIGINT, `serve` now stops claiming jobs and ends every PubSub subscription, so a server-sent events stream ends instead of holding the process for the whole drain. `serve` and `work` give requests and jobs in flight `CARAMEL_SHUTDOWN_TIMEOUT` seconds (1 to 3600, default 25) and log what was still running when it passes; `work` used to wait without limit, so raise the setting for jobs that run longer than 25 s. A second signal exits 1 at once. A supervisor allows `CARAMEL_SHUTDOWN_TIMEOUT` plus 5 s before it kills a process.
- `frappe dev` no longer hands the development session cookie to any client on the machine. The gateway sets it only on a single-use link, `/__caramel/dev/sign-in?nonce=…`, that `frappe dev` prints as `Toolbar and inspector sign-in (single use): URL` (also with `--no-open`) and opens, and `frappe open` mints a new one while `frappe dev` runs. The inspector pages answer 403 without the cookie, the toolbar says `Not signed in`, and `/__caramel/dev/status` shows an unsigned client only `generation` and `state`; the build-error page stays public. Open a new link after restarting `frappe dev`; Latte.app’s Open inspector item needs a signed-in browser.
- The TLS client contexts Caramel opens itself (the database connection, `Caramel::Outbound`, the OTLP exporter and Latte’s proxy probe) now clear the legacy OpenSSL 1.0 `SSL_OP_ALL` options that Crystal before 1.22.1 gives every `OpenSSL::SSL::Context` (GHSA-7jw4-6xx8-g2r9), so an application built with an older compiler is covered too: Shards only warns about the `crystal:` floor. A TLS 1.2 connection now uses the extended master secret, and a peer that closes without `close_notify` is an error. A server that cannot do secure renegotiation is refused.
- `frappe new` and `frappe setup` now run each dependency’s postinstall script themselves, after `shards install --skip-postinstall`, and keep what it writes in the toolchain’s `postinstall-cache`, keyed by the dependency’s name and version. The first install on a toolchain still builds lexbor’s parser (`cc`, `ar` and the network); the next application copies it, about 1.7 s instead of 11 s.

## Upgrading to 0.16.0 {#c-releases-upgrade-0160}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; the toolchain changes, and these changes can need an edit.

- `frappe db diff` keeps an index or foreign key whose name SugarORM did not generate and prints a note, where it dropped every undeclared one. A changed index is built under a temporary `_swap` name, then the old index is dropped and the new one renamed, so a unique index is never missing. `belongs_to` takes `on_delete: :cascade`, `:restrict` or `:set_null`.
- `frappe migrate` commits each transactional migration with its own journal row instead of one shared transaction, so a failure no longer rolls back the migrations before it. A migration that hits `lock_timeout` rolls back and runs again after 1, 2 and 4 s; a fourth timeout stops `migrate` with `Migrator::LockTimedOut`, which names the migration.
- `CARAMEL_POOL_SIZE` (1 to 32) and `CARAMEL_POOL_TIMEOUT` (1 to 300 seconds) set the connection pool of every command that opens one, which was fixed at 4 connections and a 5 s checkout wait. An invalid value exits 1 with one line naming it.
- Applications can use `BigDecimal`, `BigInt` and `BigRational` in every managed build: the toolchain now bundles GMP 6.3.0, and `frappe build` links it statically. Remove any `@[Link(ldflags: …)]` on `LibGMP` and any vendored `libgmp.a` an application added for this.
- The toolchain changed, so installing this release sets up a new toolchain directory and its first builds start with an empty compiler cache. If you use the editor tools, run `frappe lsp install` again after installing.

## Upgrading to 0.15.0 {#c-releases-upgrade-0150}

Upgrade Caramel and Frappé together. Run `frappe migrate` once for a framework migration; these changes can need an edit.

- Every database connection sets `statement_timeout` and `lock_timeout` when it opens, and the client’s read timeout follows the statement timeout, 5 seconds behind it. `serve`, `work`, `seed`, `lint` and `drift` default to 30 s and 5 s; `migrate` defaults to no statement timeout and 5 s. A statement that ran longer than 30 s now fails with `canceling statement due to statement timeout`. Raise `CARAMEL_STATEMENT_TIMEOUT` or `CARAMEL_LOCK_TIMEOUT` for a process that needs longer, and `CARAMEL_MIGRATION_STATEMENT_TIMEOUT` or `CARAMEL_MIGRATION_LOCK_TIMEOUT` for `migrate`: whole seconds, 0 to 86400, 0 for none. [The Crema reference lists the variables →](https://caramelize.dev/docs/0.23.0/crema/index.md)
- A job whose process dies or loses its connection is failed on its third release instead of being redelivered forever: maintenance records `Caramel::ColdBrew::AbandonedJob`, calls the `on_failed` hooks, and `jobs retry` runs it again. Released runs no longer count against `retry_on` attempts.
- The framework migration `20260927000006` adds `caramel_jobs.releases` and takes a lock on every `caramel_jobs` partition. Run `frappe migrate` while no job is running, or `migrate`’s 5 s lock timeout may refuse it; `CARAMEL_MIGRATION_LOCK_TIMEOUT` raises it.

## Upgrading to 0.14.0 {#c-releases-upgrade-0140}

Upgrade Caramel and Frappé together. There are no framework migrations; an application with a SweetTalk domain adds one of its own, and these changes can need an edit.

- With `caramel/sweet_talk`, a `SweetTalk::Refusal` that an action’s `handle` does not rescue answers 422 with its message under `_base`, shaped like a failed contract: `{"errors": {"_base": [message]}}` for JSON clients, the contract failure page for browsers and htmx, and text starting `ERR INVALID:422` for other clients. A `SweetTalk::Missing` answers 404. Neither is reported to Crema as an error. An action that rescues them itself is unchanged, and `SweetTalk::Boundary` still answers 500. Asking an aggregate for its id before `create`, or an event for its subject before it is emitted, raises `NilAssertionError` instead of `SweetTalk::Missing`.
- A contract field may take a SweetTalk value or an aggregate’s id: `field quantity : Ordering::Quantity` binds as an `Int32`, and the value’s refusal is the field’s error. `CARAMEL_FIELD_<NAME>` constants gain a sixth element, the declared type, so a macro of your own that destructures exactly five must take six.
- A lifecycle’s `state` column has a `CHECK` constraint named `check_<table>_state_<8 hex digits>`, and a state of two or more words is stored as `moves` spells it. 0.13.0 stored `awaiting_payment` as `awaitingpayment`: first add a migration that respells such rows, such as `UPDATE ordering_payments SET state = 'awaiting_payment' WHERE state = 'awaitingpayment'`, and migrate, then run `frappe db diff`, which adds each constraint as `NOT VALID` and validates it in the `_concurrently` migration. `frappe migrate` stops, naming the constraint, while a row holds any other text; the constraint stays `NOT VALID` until you fix those rows and migrate again. A lifecycle whose constraint name would pass PostgreSQL’s 63 bytes no longer compiles; give the context or the aggregate a shorter name, since `renamed_from:` keeps the old table and its long name.
- A `finds` that names an unknown attribute or state, or a list of entities, fails to compile even when nothing calls it. Code outside an aggregate can no longer call `__sweettalk_rows`; give the aggregate a `finds` with a block instead.
- Calling another context’s service, as in `Catalogue.price_of(tea)`, counts as naming `Catalogue::`: outside `border Catalogue` it compiles only where the context follows Catalogue. Move the call into the border, or declare `follows: Catalogue`. In a border the call draws a dependency edge, so two contexts whose borders call each other no longer compile: let one of them react to the other’s events instead. A context names `Caramel::Outbound` or `HTTP::Client` only inside a border with an outside system, `border Cards, outside: "…" do … end`.
- Additive, nothing to edit: `specification` names a rule once, `finds` and `counts` sort, limit and count, a context names its `subdomain:` and what it `publishes`. [The SweetTalk guide lists them →](https://caramelize.dev/docs/0.23.0/sweettalk/index.md)
- `frappe agent-manifest` prints a `GUIDES:` line after `DOCS:`, so a tool that reads the manifest by line number finds the commands one line later.
- For applications made earlier: to give agents the guides in Markdown, add `Every page of it in Markdown: https://caramelize.dev/docs/VERSION/llms.txt` after the documentation link in `AGENTS.md`. An application with a domain gets the SweetTalk skill with its next `frappe make domain`, or now with `mkdir -p .claude/skills/sweettalk && cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/`, which also refreshes it after a later upgrade; add `Domain rules: .claude/skills/sweettalk/SKILL.md, which frappe make domain writes` after `Domain:` in `AGENTS.md`.

## Upgrading to 0.13.0 {#c-releases-upgrade-0130}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; one call stops compiling, and these changes can need an edit.

- Keyword `where` no longer takes a value that may be nil, such as a `String?` variable, because nil matched the rows whose column IS NULL. The call fails to compile with `…MayBeNil` in the error. Narrow the value first (`if token = contract.token`), or use the new `where_null(:column)`; the literal `where(column: nil)` still works.
- A request may send at most 4,096 values and 128 files, and a multipart body’s boundaries and part headers count toward its size; more answers 413. Multipart files are stored only for a route whose contract has an `UploadedFile` field.
- A Crema sink or exporter that matches `Caramel::Crema::SpanKind` exhaustively must handle the new `domain` kind.
- `sudo scripts/install-local-integration apply` installs only a bundle that the user who ran `sudo` prepared, and refuses to run as root without `sudo`. A `CARAMEL_LATTE_SWIFT_CACHE` directory must be yours alone.
- SweetTalk arrives, experimental, and nothing changes until an application requires `caramel/sweet_talk`. `frappe make domain NAME CONTEXT --means=TEXT` starts a domain; a multi-tenant application names its tenant with `tenant App::Account` before its first context. Applications generated before this release add the `Lint/UnusedArgument` exclusion for `app/domain/**` to their `.ameba.yml` by hand, as `lib/caramel/templates/application/.ameba.yml` has it.

## Upgrading to 0.12.0 {#c-releases-upgrade-0120}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; one change can need an edit.

- On SIGTERM, `serve` now finishes in-flight requests for up to 25 s before it exits, and an open server-sent events stream holds it for the whole 25 s. Give a supervisor that stops `serve` at least 30 s.
- Applications can run in production on Linux: `frappe build` writes a static linux/amd64 artifact, `serve` reads public files from `CARAMEL_ROOT` and runs without workers with `--no-workers`, `APP jobs unknown` lists queued jobs a binary cannot run and `APP db roles` prints the role script. Nothing to edit. [The Production guide puts them in order →](https://caramelize.dev/docs/0.23.0/deployment/index.md)

## Upgrading to 0.11.0 {#c-releases-upgrade-0110}

Upgrade Caramel and Frappé together. There are no framework migrations and nothing is removed; these changes can need an edit.

- The schema document `frappe db diff` reads is now version 3, because it carries CHECK constraints.
- SugarORM owns the CHECK constraints named `check_…`. `frappe db diff` drops a `check_…` constraint that no schema declares; any other CHECK constraint stays and is noted. Declare a hand-written `check_…` constraint, or rename it, before you diff.
- Two schemas that name one table no longer compile. Remove the duplicate or give one a different table.
- Run `shards update` so your application takes crystal-db 0.15.0 and crystal-pg 0.31.0.
- After a job is renamed or moved, name its old class with `renamed_from "Old::Name"` in the job. `work` and `migrate` now log a warning naming queued class names that no job claims.

## Upgrading to 0.10.0 {#c-releases-upgrade-0100}

Upgrade Caramel and Frappé together. There are no migrations and no breaking changes; the change is in the development tools.

- The inspector’s request page shows each query as a card instead of a table row: the statement with one clause per line and coloured, and each bind listed beside its `$n`. Pointing at a placeholder or a bind lights up both. **Copy SQL** and **Copy with values** still write the statement as it ran.

## Upgrading to 0.9.0 {#c-releases-upgrade-090}

Upgrade Caramel and Frappé together. There are no migrations and no breaking changes; the changes are in the development tools.

- The development toolbar is redesigned: its route, status, time, query count and flags link to their place on the request’s page in the inspector, `` ` ``, `j` and `k` work from the keyboard, and **Copy for an agent** copies the request as Markdown.
- Each query on the inspector’s request page has **Copy SQL** and **Copy with values**. A query keeps its first 20 binds, and a literal over 2,000 bytes is not kept for copying: those placeholders stay as `$n` and the copy starts with a comment saying so. A `nil` bind is now recorded as `NULL` and shown bare in the Binds column; the text `NULL` stays quoted.
- The toolbar, the inspector and the production console follow the system’s light or dark appearance, with a Theme button to choose. The console keeps its own choice.
- The application binary’s `ops` commands now refuse a flag they would have ignored instead of dropping it silently.

## Upgrading to 0.8.0 {#c-releases-upgrade-080}

Upgrade Caramel and Frappé together. The schema document `frappe db diff` reads is now version 2, and `SugarORM::Catalog::ForeignKey` holds `columns` and `references_columns` so a key can span several columns. Two framework migrations and these edits apply.

- Run `frappe migrate`. Two framework migrations add `caramel_jobs.context` and `caramel_metrics`.
- Run `latte stop` once if Latte is running, so the next command starts the new one. Frappé, Corretto and Latte.app now use Latte’s control API 2. The managed PostgreSQL restarts once to preload `pg_stat_statements` and `auto_explain`.
- To keep per-minute aggregates, add `require "caramel/crema/recorder"` after `require "caramel"` in `config/application.cr`. New applications already have it.
- Add `Caramel/Dump` to an existing application’s `.ameba.yml`, as new applications have it, so `frappe lint` reports a leftover `dump`.
- Logging now sets itself up: JSON in production, text in development and test. The old `error_type` log line is gone; the `error` line carries `error_class` and `fingerprint`. `Caramel::DevelopmentError.response` now takes a `Caramel::Crema::ErrorReport`; `Caramel::Database::Config` gains `application_name`, and `SugarORM::Repo` the private hooks `observe` and `observe_checkout`, which `caramel/crema/sql` redefines.
- To adopt the agent files, copy `AGENTS.md` and `CLAUDE.md` from `lib/caramel/templates/application`; existing applications keep their own.
- Opt in as you need: `require "caramel/crema/otlp"` exports traces to the endpoint `OTEL_EXPORTER_OTLP_ENDPOINT` names; the ops socket opens beside `serve`, and for `work` when `CARAMEL_OPS_SOCKET` names a path; `frappe logs access` prints the site’s access log; `frappe make tenancy MODEL` makes the application multi-tenant.

[What Crema adds →](https://caramelize.dev/docs/0.23.0/observability/index.md)

## Earlier releases {#c-releases-earlier}

The notes start at 0.8.0, the release that first put its upgrade steps on this page. Each release’s guides stay published at `/docs/VERSION/` from 0.4.0 on, and CHANGELOG.md holds every release’s notes. The ones before 0.8.0 that still need an edit: 0.7.0 changes `html lang: "en"` in `app/views/layouts/application.cr` to `html lang: Caramel.language` and replaces `Caramel::Application::EXPIRED_FORM` with `Caramel::Wording.expired_form`; 0.6.0 adds Lexbor 3.6.4 under `development_dependencies`; 0.5.0 binds JSON bodies through the contract and gives specs a committed `.env.test`; 0.4.2 pins Crystal 1.21.1.

Supported today

## Runtime and local tools {#c-releases-tools}

Caramel is a source-built Crystal framework with a managed toolchain; the versions it pins and the machine it develops on are stated once, in [Your first application](https://caramelize.dev/docs/0.23.0/getting-started/index.md). Frappé creates projects, generates resources and supervises builds; Latte supplies managed services and named HTTPS. An application’s `shard.lock` selects its framework release, and Frappé dispatches to the matching installation; `frappe installations install VERSION` installs another release beside this one.

[Caramel 0.23.0 source release ↗](https://github.com/caramelizedev/caramel/releases/tag/v0.23.0)

## Dependencies move with the release {#c-releases-dependencies}

Four dependencies are held to one version. An upgrade of any of them waits for a Caramel release. The framework’s `shard.lock`, and the lock of every generated application, locks each git dependency to the commit its tag pointed at (`version: 0.31.0+git.commit.<sha>`), so a moved tag changes nothing; `scripts/check shard-pins` refuses an unpinned entry.

| Dependency | Held to | What an upgrade waits for |
| --- | --- | --- |
| Blueprint | `1.1.0`, exactly | Caramel reopens its attribute renderer (ADR 0018 decision 4), so a Blueprint upgrade waits for a Caramel release that re-verifies the patch |
| Crystal | `1.22.1` and newer in `shard.yml`, tested on `1.22.1` | A newer compiler is untested until a release names it; the pinned toolchain and the build image are `1.22.1`, stated in [Your first application](https://caramelize.dev/docs/0.23.0/getting-started/index.md) |
| htmx | `4.0.0`, copied into `app/assets/vendor/` | Your application owns that copy, but fragment negotiation is tested only against 4.x (ADR 0004) |
| Lexbor | `3.6.4`, development only | Corretto binds its native layout, so a Lexbor upgrade waits for a release; production installs omit it |

## Requests and responses {#c-releases-requests}

Typed action contracts bind route and query values, URL-encoded forms, multipart uploads, and JSON objects. The default policy checks CSRF for writes and limits ordinary request input to 2 MiB; multipart uploads have a separate 64 MiB budget. Use per-action `ingress` for a custom limit, authenticated APIs, or exact raw webhook bytes.

Actions return HTML or JSON according to the request. `render_errors` handles errors found after contract binding. Blueprint views write typed HTML with escaped text and attributes; htmx partial responses update selected page regions.

## Data and resource generation {#c-releases-data}

SugarORM provides typed schemas, codecs for any field type, changesets, queries, explicit preloads, row locks, upserts, version columns and CHECK constraints. Derive a migration with `frappe db diff`, review it, and apply it with `frappe migrate`; `frappe seed` runs `db/seeds.cr`. `frappe make resource` generates application-owned models, changesets, actions, views, routes, migrations, and request specs.

Use `:server` for fields populated by the action, `:unique` for unique indexes and constraint checks, and `:url` for URL validation and inputs. `--only=create,show` generates a smaller action set; create and show are required, and edit needs new and update.

[Read the SugarORM reference →](https://caramelize.dev/docs/0.23.0/sugarorm/index.md)

## Background work {#c-releases-work}

Cold Brew stores jobs in PostgreSQL and supports transactional enqueueing, retry policies, durable status, retry and failure hooks, renamed jobs, recurring schedules, PubSub, and cache. A job whose process died on three of its runs fails as `Caramel::ColdBrew::AbandonedJob` and can be retried. The application binary runs queues through `serve` or a worker-only `work` process with queue and concurrency options. External calls can repeat, so use a stable identifier for deduplication.

[Read the Cold Brew reference →](https://caramelize.dev/docs/0.23.0/cold-brew/index.md)

## Development and testing {#c-releases-checks}

Corretto drives in-process application requests against isolated test databases. Its client sends forms, multipart uploads, JSON, or exact raw bodies. Blueprint-shaped `have_html` expectations inspect decoded rendered HTML; `render_partial` can check an envelope’s target, swap, and content together.

Generated applications pin Lexbor 3.6.4 under development dependencies. Development installs need cc, ar, and network access for the verified native parser source. Production installs omit the parser. Put application-owned test settings in committed `.env.test`; development `.env` does not reach specs.

Every page of these guides has a Markdown edition at its address followed by `index.md`, listed in `https://caramelize.dev/docs/0.23.0/llms.txt`, and `frappe agent-manifest` prints that address on its `GUIDES:` line.

## Internationalization {#c-releases-i18n}

Caramel has opt-in, typed translations. Run `frappe make locale CODE` to add Crystal catalogs and enable translated resource generation. Views and actions use `t` for messages and `l` for number and time formatting. Language selection supports a switch, optional URL prefixes, cookies, and browser preferences.

Contract and changeset errors, JSON error messages, and framework pages use the request’s locale. Missing translations fall back, and `frappe translations` reports what remains. Background jobs carry their language explicitly.

[Translate your application →](https://caramelize.dev/docs/0.23.0/internationalization/index.md)

## Multi-tenancy {#c-releases-tenancy}

An application can be multi-tenant. `frappe make tenancy MODEL` adds the tenant schema, sign-up and home pages, and a `tenant` block in the routes; resources generated afterwards belong to the tenant, and `--central` makes one every tenant shares.

[Add tenants →](https://caramelize.dev/docs/0.23.0/multi-tenancy/index.md)

## Domain-Driven Design {#c-releases-sweettalk}

An application can model its domain in SweetTalk, an opt-in language whose contexts, values, aggregates, events, policies, projections and processes expand into SugarORM and Cold Brew. `frappe make domain NAME CONTEXT --means=TEXT` starts one in `app/domain/` and writes a skill that gives agents its rules. Since 0.14.0 a refusal answers 422 from an action, values and ids bind as contract fields, and a lifecycle’s states are held in a PostgreSQL check. Since 0.18.0 an attribute may be optional, a string value may be one of a closed list, and an event may carry the aggregate’s attributes. Since 0.19.0 a value may be a calendar day. The guide maps each Domain-Driven Design pattern to its word and states its experimental status; the Box Office path builds one domain end to end.

[Speak the domain’s language →](https://caramelize.dev/docs/0.23.0/sweettalk/index.md) [Build a box office →](https://caramelize.dev/docs/0.23.0/box-office/index.md)

## Observability {#c-releases-observability}

Every routed request, job and schedule run gets a request id, a trace and one canonical log line. In development, `frappe dev` adds an inspector, a toolbar, richer error pages and the `frappe traces`, `trace` and `errors` commands. In production, an owner-only ops socket serves status, Prometheus text, recent errors and a console; the recorder and the OTLP exporter are opt-in. Latte adds statement statistics, menu-bar error counts and notifications, per-site access logs and a local trace collector on `127.0.0.1:4318`.

[Read the observability guide →](https://caramelize.dev/docs/0.23.0/observability/index.md)

## Production {#c-releases-production}

An application runs in production on Linux: `frappe build` writes a static linux/amd64 artifact, `serve --no-workers` and `work` are the process roles, `GET /health` answers readiness, SIGTERM drains for up to `CARAMEL_SHUTDOWN_TIMEOUT` seconds (default 25), `APP db roles` prints the role script and `APP jobs unknown` checks the queue before cutover. Every connection carries the statement and lock timeouts of 0.15.0.

[Read the Production guide →](https://caramelize.dev/docs/0.23.0/deployment/index.md)

Limits

## Current limits {#c-releases-limits}

- Caramel ships no command that provisions servers or deploys; `frappe build` ends at the artifact.
- No generator for authentication: the sessions recipe shows the tables and actions to write by hand.
- Multipart files are parsed and bounded, but no recipe yet stores a file and removes it; `storage/` is generated empty.
- Frappé has no extension point for commands of its own; an application adds commands to its binary with `Caramel::Crema.command`.
- Installing a release still starts from a Git checkout of the framework: `frappe installations install VERSION` exists once one release is registered, and there is no installer for a machine without one.
- Recipes labelled Draft are written against 0.23.0 and not run end to end; the cookbook marks each.
- SweetTalk is experimental until an application has run it in production.
- Prometheus text is served only on the owner-only ops Unix socket (`/v1/metrics`), so a scraper needs a bridge on the host. [Read the socket rules →](https://caramelize.dev/docs/0.23.0/crema/index.md)
- One `APP_SECRET` signs sessions, CSRF tokens and debug tokens; `APP_SECRET_PREVIOUS` keeps sessions and CSRF tokens readable while it rotates, debug tokens end at once. [Read what a change ends →](https://caramelize.dev/docs/0.23.0/security/index.md)
- Errors on the ops socket live in memory only. [Read what a restart clears →](https://caramelize.dev/docs/0.23.0/observability/index.md)
- No API reference is published; API detail is in doc comments at the code.

Prove it

## Check an upgraded application {#c-releases-prove}

**Terminal · inside the application, after each release**

```bash
frappe migrate
frappe check
frappe corretto
frappe lint
```

**Passing:** `frappe migrate` ends with `The database matches the declared schema.`, `frappe check` exits 0, `frappe corretto` ends with `Corretto: N of N workers passed` and `frappe lint` exits 0.

[Take the application to production →](https://caramelize.dev/docs/0.23.0/deployment/index.md)

Caramel 0.23.0 · https://caramelize.dev/docs/0.23.0/releases/
