Skip to content
carameldocs · 0.23.0
Browse documentation
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.

ContractValue
Release0.23.0
CoversUpgrade notes from 0.8.0 to 0.23.0, what the release supports and its current limits
NeedsAn application whose shard.lock pins an earlier release, and the machine setup of your first application
Proved byfrappe check · frappe corretto · frappe lint

Each upgrade section is written from the release’s entry in 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

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). 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).
  • 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). 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).
  • 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).
  • 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). 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).
  • 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).
  • 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).
  • 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).
  • 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 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, ADR 0063 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

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 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).
  • 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). 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). ADR 0061 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 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). 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 Amounts 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 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). 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). 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) and to add up with sums and groups, never SugarORM.sql (ADR 0049); 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

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).
  • 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). 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). 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 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).
  • 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). 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, ADR 0051).
  • 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).
  • 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). 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).
  • 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).
  • 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).
  • 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).
  • 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).

Upgrading to 0.20.0

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 ↗). 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

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

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

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

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

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 →
  • 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

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 →
  • 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

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

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 →

Upgrading to 0.11.0

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

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

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

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 →

Earlier releases

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

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. 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 ↗

Dependencies move with the release

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.

DependencyHeld toWhat an upgrade waits for
Blueprint1.1.0, exactlyCaramel reopens its attribute renderer (ADR 0018 decision 4), so a Blueprint upgrade waits for a Caramel release that re-verifies the patch
Crystal1.22.1 and newer in shard.yml, tested on 1.22.1A 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
htmx4.0.0, copied into app/assets/vendor/Your application owns that copy, but fragment negotiation is tested only against 4.x (ADR 0004)
Lexbor3.6.4, development onlyCorretto binds its native layout, so a Lexbor upgrade waits for a release; production installs omit it

Requests and responses

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

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 →

Background 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 →

Development and testing

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

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 →

Multi-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 →

Domain-Driven Design

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 → Build a box office →

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 →

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 →

Limits

Current 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 →
  • 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 →
  • Errors on the ops socket live in memory only. Read what a restart clears →
  • No API reference is published; API detail is in doc comments at the code.

Prove it

Check an upgraded application

Terminal · inside the application, after each release
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.