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 |
| Proved by | frappe check · frappe corretto · frappe lint |
The guide in three stages
29 sections · read in order the first time
- 1 · Upgrade notes
- Upgrading to 0.23.0
- Upgrading to 0.22.0
- Upgrading to 0.21.0
- Upgrading to 0.20.0
- Upgrading to 0.19.0
- Upgrading to 0.18.0
- Upgrading to 0.17.0
- Upgrading to 0.16.0
- Upgrading to 0.15.0
- Upgrading to 0.14.0
- Upgrading to 0.13.0
- Upgrading to 0.12.0
- Upgrading to 0.11.0
- Upgrading to 0.10.0
- Upgrading to 0.9.0
- Upgrading to 0.8.0
- Earlier releases
- 2 · Supported today
- 3 · Limits
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 helpprints 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 WORDSandfrappe WORDS --helpprint one command's description, usage and examples, or list a family's subcommands (frappe help db branch); a family run without a subcommand, such asfrappe db, lists its subcommands on a terminal and exits 1. A usage error on a terminal ends withRun frappe COMMAND --help for details., or with the family's commands. The commands that change state end with one alignedNext:block.NO_COLORandTERM=dumbturn colour off.frappe completion zsh|bash|fishprints a completion script for commands, subcommands, options and their choices. Output when stdout is not a terminal and every MRDP block keep their format, andfrappe agent-manifestkeeps its format with the newhelp [COMMAND...]andcompletionlines (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 theNext: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, andscripts/checkfails 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 domainwrites no longer says never to add up withSugarORM.sql. It says to prefersumsandgroups, and to useSugarORM.sqlonly for what they cannot state, such as an average, aFloat64orTimekey or several keys, with the tenant predicate written out (ADR 0049). Refresh an application's copy withcp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/. - SugarORM:
field id : UUID, primary: trueis auuidkey with the defaultuuidv7(), minted by the insert changeset when it is built (changeset.id); a UUID-keyed table needs PostgreSQL 18.field id : Int64, primary: truekeeps its identity column, so existing schemas change nothing (ADR 0064). - Frappé:
frappe make resourceandfrappe make tenancynow write UUID keys; pass--int64to 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 Int64on the line afterinclude SweetTalkto keep existing tables; without itfrappe db diffhalts on the changed key. A domain with a tenant follows the tenant's key type (ADR 0064). The skillfrappe make domainwrites says so; refresh an application's copy withcp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/. - Breaking: SugarORM:
SugarORM::Page(R)is nowSugarORM::Page(R, K),Kthe schema'sPrimaryKey; update code that names the type (ADR 0064). - Breaking: SugarORM:
param idon a changeset of an Int64-keyed schema fails compilation; a UUID key takesparam id : UUID, the only way a client supplies an id. An update that changes the id addscannot 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 keepst<digits>:and 42 (ADR 0064). - SweetTalk:
within Picking do … endcontinues 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 aonce_by:unit work from any block. Awithinof no earlier context, of a kernel or inside a context, apublishesin 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 skillfrappe make domainwrites says so, so refresh an application's copy withcp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/(ADR 0065). - SweetTalk: in
SweetTalk.preview, a unit'sneverandalwayslines no longer end the run. Each that fails adds its sentence to the newpreview.blockers, in the order they ran, and the preview keeps the run's events and changes;preview.refusalis the first blocker, so a screen that hides its confirm button onrefusalstill 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.previewnow answers aSweetTalk::Preview::Of(T), aPreviewwhosevalueis what the block returned, nil when the body was refused, andto_jsonaddsblockers(ADR 0060 decision 11). The skillfrappe make domainwrites says a screen that refreshes as a person types loads withfindand calls a calculation instead of previewing; refresh an application's copy withcp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/. - SweetTalk: a
sumsorgroupsthat adds up an entity's attribute takes conditions on each entity inwhere:, under the name of its list, as inwhere: {member: member, state: :placed, lines: {tea: teas}}, andgroups …, of: Line.price, by: :idanswers one total per aggregate, in id order; neither joins.sumsof aMoney::AmountanswersHash(Currency, Amount), one total per currency in code order, in one statement; aMinor(USD)adds up as a number, andgroupswithby:an amount groups by its currency. Agroupsthat adds up anAmount, and asumsorgroupsthat filters a list of entities it does not add up, fail compilation (ADR 0049, ADR 0063 decision 10). Existing queries are unchanged. The skillfrappe make domainwrites says so; refresh an application's copy withcp 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 andsubject:forms: the events whoseoccurred_atis earlier thanmoment, the bound left out, besidesince:, 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 passbefore:(ADR 0048 decision 3). - SweetTalk: a value with
one_of:also writesenum Kind::Member, one member per word in the listed order (net_settlementisNetSettlement), withkind.memberandKind.new(member)(orKind.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 ascase kind.member in .receipt? … end, with noelse: a member added to the list then fails compilation at everycasethat misses it, naming the member, where awhen … elsesent it to the default arm (ADR 0058). - SweetTalk:
movesalso writesOrder.moves_from(state), the states a mover may enter fromstatein the ordermovesfirst names them, andorder.may_become?(state); the movers stay private. A screen that offered commands by comparingstatetext can map each state ofmoves_from(order.state)to its command in acase … in, which fails compilation when a state is added. - SweetTalk:
refuse "…", on: :tins, andon:onnever,alwaysand a unit's rules, name the field a refusal is about (refusal.on,"tins"; a service raisesSweetTalk::Refusal.new("…", on: :tins)). An action answers it under that field when its contract declares it, through the newcontract.field?(name)(andContract.field?(name)), and under_baseotherwise, so a refusal withouton:answers as before; an application that mapped refusal sentences to fields can name the field at therefuseinstead. Anon: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 aSweetTalk::Preview(events,changesbefore and after,warnings,refusal,summary,fingerprint,to_json);SweetTalk.commit(expected) { … }runs the same body, compares its fingerprint before the transaction ends and raisesSweetTalk::Stale, a refusal carrying the fresh preview, when the world moved, writing nothing (ADR 0060).SweetTalk::Fingerprintis a contract field value for the hidden field a form carries, and an unrescuedStaleanswers 422 throughrender_stale(contract, stale), a JSON client getting the fresh preview underpreview. A hand-kept preview path with its own hash can be replaced by the real body insidepreviewandcommit. A unit'swarn "…" { … }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 anoutside:border's module no longer compiles: move the call into awheneveron the command's event, or before the change.Caramel::OutboundraisesCaramel::Outbound::Refusedwhile a preview runs. The aggregate, entity and event macros now define__sweettalk_canon, andmovesdefinesSWEETTALK_FINAL, the states no move leaves. - SweetTalk:
calculation share(total : Cents, parts : Int32), returns: Array(Cents), means: "…" do … endin a context declares a typed function,Billing.share, with no transaction, repository, event or command, listed in the glossary with kindcalculationand inSweetTalk.calculations, and nameable inpublishes. Aneveroralwaysline in its body is a rule onresult; a broken one raises the newSweetTalk::Broken, a defect that rolls back its transaction and answers 500, not a refusal. A calculation whose body or rules reachSugarORM,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 thepublishesrefusals now name "services, units and calculations" (ADR 0062). ADR 0061 states when a SweetTalk word gets a require of its own, ascaramel/sweet_talk/decimalhas. - 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 andrerun with CORRETTO_SEED=N.frappe correttopassesCORRETTO_SEEDfrom 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 requirescaramel/sweet_talk/decimal) adds money words to a context or a kernel (ADR 0063).currencies %w[USD EUR JPY], means: "…"declaresCurrency, a closed set checked by PostgreSQL, with each code's minor units from ISO 4217 list one (2026-09-17) andexponent: {XAU: 4}for a code the list lacks or marks N.A.;Minor(Currency::USD)counts minor units and adds only its own currency, soMinor(USD) + Minor(EUR)and twoAmounts added fail compilation, andMoney.same(a, b) { |x, y| x + y }andMoney.by_currencycombine amounts whose currency is data.has original : Money::Amountstoresoriginal_currencyandoriginal(bigint);Minor(USD).parse("12.345")refuses andround(text, rounding:)rounds on purpose;quote Rate, rounding: :half_upkeeps a dated rate as an exact fraction thatamount.convert(rate)applies, with exactinverseandthrough. Nothing changes for a domain that does not require the module; one that stores money as aCurrencyand aCentsvalue side by side may move toMoney::Amountand runfrappe db diff, thenfrappe migrate, for its new columns and checks. - SweetTalk:
allocation split, of: Money::Amount, by: Weight, remainder: :largest_fraction, means: "…", afterrequire "caramel/sweet_talk/money", declares the calculationsplit(total, weights)that shares an amount among the keys of aHash(Int64, or the typeper: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 onresultsay the parts add up to the total, each is the floor or ceiling of its share and a zero weight gets nothing, andCorretto.propertynow draws hashes and amounts to run them; a negative weight or weights summing to zero refuse, andFloat64,to_for a float literal in its types or block fails compilation (ADR 0063 decision 8). - Breaking: SweetTalk: a
follows: Cataloguein a context whose text names noCatalogue::and calls noCatalogue.verboutsideborder Catalogue, and ashares: Moneyin 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:Cataloguefromfollows:, orMoneyfromshares:and the sharer from Money'sshared_by:. An unused edge used to count in the cycle check. - SweetTalk:
SweetTalk.reportreturns every glossary term with the facts its declaration holds (a value's bounds andone_of:words, an aggregate's states and moves, an event's handlers in run order, a unit'schanges:andlocks:, a context'sfollows:andshares:), and the application answersglossarywith 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 domainwrites,.claude/skills/sweettalk/SKILL.md, now says an entity may hold entities (ADR 0050) and to add up withsumsandgroups, neverSugarORM.sql(ADR 0049); it also namesparts:,Created,once_by:,reached,pinned_at:andrequirements.frappe make domainnever replaces an application's copy: refresh it withcp 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 acreateor a factory followed by a command on the new aggregate counts as one change; a command on a second aggregate still raisesSweetTalk::Boundary. Two commands on two aggregates called in turn inside oneSugarORM::Repo.transactioncommit and roll back together: that seam is now documented and tested as supported. - SweetTalk: a command named
finalizeno longer compiles (it would replace the garbage collector'sfinalize); name it for what it does, as into 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, andhas tenant/has tenant_idon 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 … endinsideentity Slipwithhas marks : Array(Mark)stores them in<context>_<aggregate>_<slip>_markskeyed byslip_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 oneDELETEper 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'sfk_<table>_<parent>_idover PostgreSQL's 63 bytes fails compilation instead of being truncated silently (ADR 0050). - SweetTalk: every aggregate of a tenanted context has
tenant_id : Int64andtenant, the tenant model's row, so rows read underCaramel::Tenancy.withoutsay whose they are. An aggregate and an entity readcreated_atandupdated_atfrom their rows, nil until the first save. An entity declares its ownneverandalways, 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?insideEntry).has flag : Bool(not optional) also definesflag?; amovesstate 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.zeroor a closed-set member such asKind.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 diffadds the default to an existing column. - SweetTalk:
SweetTalk.emitted { … }returns the events the block's commands dispatched, in dispatch order, andSweetTalk.emitted(Order::Placed) { … }those of one class, typed; specs that reopenedSweetTalk.dispatchor 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.secondson a context, border, projection or process handler, and ondeadline, sets that job's retry rule for errors other than a refusal. A process declaresfindsandcountsas a projection does; a process query namedall,neworallocate, or withsatisfying:, no longer compiles. Entities come back from afindby id, which is insertion order; an in-memory reorder is not persisted. frappe correttotakes a whole-run lock,.caramel/corretto/run.lock; a second run in the same project printsCorretto: waiting for another run in this projectand 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)andfind?read the root in one statement; reading a list on it raisesSweetTalk::Unloaded, naming the fix, and a command on it loads the lists under its lock as every command does. - SweetTalk: an entity has
Line::Idandline.idonce 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 readsline.id, for a factory's new lines too. A job queued before this release holds entities withoutid;line.idon 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 withemit Renamed, name: name, dispatched in the service's transaction onsweettalk.<context>.<event>(behind a tenant'st<id>:prefix); the subject is the bound tenant's id undercaramel/tenancy, else nil, soEvent#__sweettalk_subject_idis nowInt64?and a policy job'ssubjectparam is optional.emitin a context anywhere but a service body, andcarries:on a context event, fail compilation. frappe checknow types every SweetTalk command, factory and service body, called or not: eachto,factoryandserviceemits a never-run__sweettalk_touch_<name>thatSweetTalk.bootand the whole-program checks reference.frappe make domainwritesSweetTalk.bootafterrequire "../app/domain/*"inconfig/application.cr; an application generated before this release adds that line by hand, orfrappe checkkeeps passing bodies nothing calls. A body that never compiled now failscheckat 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, sofrappe db diffplans 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}andgroups priced_by_tea(member : Account), of: Line.price, by: Line.tea, where: {…}are declared besidefindsandcountson 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 asLine.price, anInt32,Int64orFloat64column or a value wrapping a whole number or a decimal with no bound a sum can break;groupsreturns{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 byscripts/check page-sums) now uses them. SugarORM gainssum_text,group_sum_textandwhere_in(:field, parent_query). - SweetTalk:
has label : String, unique: true(orunique: "sentence"),index: trueandcheck: {"sql", "sentence"}, and over several attributesunique :a, :b, otherwise: "…",index :a, :stateandcheck :name, "sql", otherwise: "…", declare a unique index, a plain index or a CHECK PostgreSQL keeps (ADR 0045). A violation is aSweetTalk::Refusalwith that sentence (an action answers 422); a constraint SweetTalk did not declare stays aSugarORM::UniqueViolationorCheckViolation. An entity'suniqueis unique within its parent; a projection or process refuses these words. In a tenanted context the tenant column joins every unique index.frappe db diffbuilds a new indexCONCURRENTLYand adds a checkNOT VALIDthen validates it; a table holding duplicates leaves an INVALID index that halts the next diff, so find them first withGROUP 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 withat_least:,at_most:,within:,matches:,length:andone_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 … endin a context declares a unit: one transaction that locks the rowslocks:names first, one statement per table in table then id order, runs its commands on the aggregateschanges:lists, then its ownnever/alwayslines over the set, and rolls everything back on any error, reloading every aggregate instance it touched. A command on a type outsidechanges:, or on an existing row that was not locked, raisesSweetTalk::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 ownSugarORM::Repo.transactionand raisesArgumentErroroutside one.unitin an aggregate, entity, projection, process or kernel, withoutmeans:, or naming a foreign aggregate withoutfollows:fails compilation (ADR 0046). - SweetTalk:
SweetTalk::UnitandFiber#__sweettalk_unit, the row batch of a projection's or process's handler, are nowSweetTalk::WorkandFiber#__sweettalk_work; a spec that calledSweetTalk.__sweettalk_unit { … }callsSweetTalk.__sweettalk_work { … }.publishesmay name a unit. - SweetTalk:
value Rate, Decimal(20, 8), at_least: "0", at_most: "1", means: "…"is a decimal value, aBigDecimalkept exact in anumeric(20,8)column through the newSugarORM::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:,countsand specifications read it as a number; in JSON, events, jobs and contract fields it is the string"0.05".value Evidence, Json(Snapshot), means: "…"(aJSON::Serializabletype) orvalue Note, Json, means: "…"(JSON::Any) is a JSON value kept whole in ajsonbcolumn;where:asks only equality ornil, a range fails compilation andorder:on it is refused. A projection's or process's decimal or JSON attribute takes no default, so make it optional.value Grams, Float64now fails withwraps Int32, Int64, String, Date, Decimal(P, S) or Json(T). - SugarORM:
require "sugar_orm/decimal"addsSugarORM::DecimalCodec(P, S)(field rate : BigDecimal, codec: SugarORM::DecimalCodec(20, 8)), orderable, writing plain digits and raisingArgumentErrorat the write for a value past S decimals or P − S digits;sugar_ormitself 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, inbilling_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,fieldsjsonb), part of the derived schema sofrappe db diffcreates it, tenanted like the context's rows.Billing.logged(Invoiced, subject:, since:, limit:)reads typed events oldest first,Billing.logged(subject:)every class asSweetTalk::Event, andevent_log: 90.days, or any whole number of days or weeks, keeps each event that many days, pruned hourly by a Cold Brew schedule namedsweettalk: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 underpg_advisory_xact_lock, leaving an event a queued job of its handlers still has to apply to that job, and returnsSweetTalk::Rebuilt(replayed,deferred,oldest); it covers only events logged sinceevent_log: truewas 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 … endruns 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. Anafter:naming an owner that does not follow the event, a predecessor witheach:, or a circle ofafter: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::ForeignKeyViolationwithtableandconstraint, a serialization failure (40001)SerializationFailureand a deadlock (40P01)DeadlockDetected, bothTransactionConflict, each keeping PostgreSQL's error as itscause; a rescue ofPQ::PQErrorfor those codes rescues the new class instead.Repo.transaction(retries: 2) { … }runs the block again after a conflict, outside a transaction only. Ahas_onepreload 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)withorder_by_joined(:parent, :field)for abelongs_to,each_batch(size)andpage(size, after:, direction:)(ADR 0052).frappe make resourcegenerates a Destroy that answers 409 "… is still in use" when a foreign key stops the delete, with anin_usemessage in the resource's locale catalog; an app generated before this release adds therescue SugarORM::ForeignKeyViolationandconflict(…)to its Destroy by hand. - Breaking: SweetTalk:
createnow announcesCreatedin the same transaction, an event of the aggregate onsweettalk.<context>.<aggregate>.createdthat carries every attribute, so awheneverfollows it, anevent_log: truecontext keeps it andSweetTalk.emittedlists it; the glossary gains a term per aggregate without a factory, and acreatewrites a log row. Declareevent Created, carries: [member], means: "…"to carry some attributes only; a declaredCreatedthat lists fields, or aCreatedchannel past PostgreSQL's 63 characters (42 withcaramel/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, aneverrefuses the same in Crystal with “Settlement kind payment holds payee and no leg”, andas_paymentreads the member's parts as a named tuple, raisingTypeCastErrorfor another member.frappe db diffadds each checkNOT VALID; find the rows that break one withSELECT 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 tablefrappe db diffcreates, 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 theotherwise:sentence, and an error rolls the claim back so a retry runs again. An aggregate in the other arguments or inreturns:, anotherwise:withoutonce_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 bycause_id, oldest first, asSweetTalk::Reached(events, andby_subjectgrouping by aggregate and id); the walk passes only through logged events and raisesArgumentErrorfor an event its log does not keep.has rules : Setup::Rules, pinned_at: :finalizedcopies the referenced aggregate as JSON into a new columnrules_pinnedwhen a mover enters the state, read throughpinned_rulesas a read-only copy that raisesSweetTalk::Boundaryfor a command; the column is added byfrappe db diff(ADR 0056). - SweetTalk:
requirements "AC-01", "AC-02", in the domain module before its first context, lists requirement ids, andassures: "AC-12"(or a list) on anever, analways, aspecification, aunitand a unit's ownnever/alwayssays which ids a line answers; an id the module does not list fails compilation.SweetTalk.declared_requirementsreturns each id with what assures it,frappe requirements [ID]lists them (the application answersrequirements [ID|--ids]), and afrappe correttorun with no paths now fails when every worker passed but an id appears in no example's full description, as init "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 … enddeclares a shared kernel, a module ofvalueandaggregatedeclarations that two or more named contexts or kernels share; each sharer saysshares: Money(orshares: [Money, Calendar]), naming kernels declared before it. Only a sharer may nameMoney::types, run its aggregates’ commands or react to its events, a kernel may not name a context or reachCaramel::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 undercaramel/tenancy, appears in the glossary with kindkernel, and draws akerneledge in the context map (ADR 0044 ↗). Nothing changes for a program without one. APP_ORIGINis normalised once: the host is lowercased and an explicit:443dropped, sohttps://Example.com:443works, and a request whoseHostorOriginheader differs from the origin only in case or by:443is accepted instead of answering 421 or 403.Caramel::CSRF#originreturns the normalised form (https://example.com).- A session write that would take the
__Host-caramel_sessioncookie past 4096 bytes (session["key"] = value,merge!,update,put,put_if_absentortransform_values!) raisesCaramel::Session::Overflowat the write and leaves the session as it was, so an action fails there instead of answering 500 after the records it wrote committed.sessionis now aCaramel::Session::Data, aHash(String, String)subclass;Caramel::Session.fits?(data)and.cookie_bytes(data)say whether and how big a hash would encode, andSession#encodestill raisesOverflowfor a hash built some other way. - An
updatewhose changeset changes nothing no longer reports success without a query: it writes nothing (noupdated_atbump, no version increment) but reads the row by key, tenant and loaded version, so a row deleted meanwhile addsRecord no longer existsunder_baseand, on a versioned schema, a stale copy addsRecord changed since you loaded itwithstale?true. Code that relied on a no-change update of a missing row beingsaved?must handle the error. SugarORM::Migrator#migrateno longer lets a failingpg_advisory_unlockreplace the migration’s own error: when the connection broke mid-run the statement’s exception (typicallyDB::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 ownpg_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_metricsrows in(kind, key)order, so a web process and a worker flushing the same minute no longer deadlock and drop a window. - Breaking:
Caramel::Outboundresolves the host of a direct call first and raisesCaramel::Outbound::Blockedwhen 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 setsCaramel::Outbound.allow_private = trueat boot; calls throughOutbound.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_bytesandOutbound.deadlinechange those limits. Requests sendAccept-Encoding: identityunless the caller sets one, and bodies are no longer decompressed. - Breaking: the
__Host-caramel_sessioncookie 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:)orApplication.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 noMax-Age. Cookies in the previous format read as empty, so every user signs in again once.Session.newtakes theArray(Bytes)ofCSRF#derive_keys("session"), and the largest session shrinks by 11 bytes. APP_SECRET_PREVIOUS(comma-separated, each at least 32 bytes) lists secretsAPP_SECRETreplaced: 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)andCSRF#derive_keys(purpose)expose this;derive_key(Crema’s debug key) stays current-only..env.testmay not setAPP_SECRET_PREVIOUS.serve,workandseedstart when the database journal holds migrations the binary lacks, printingWARNING: the database holds migrations this binary lacks (vN, …); starting anywayon standard error, so an old process restarted after the new binary ranmigratekeeps serving until cutover. A migration the binary has but the journal lacks still exits 1 withPending migrations. Run frappe migrate first.;migrateandlintstill refuse a journal ahead of them.SugarORM::Migrator#pendingtakesallow_ahead : Bool = falseandMigrator#aheadlists 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-writeandhidden-ddl, and readsDO $$…$$bodies,$tag$quotes andE'…'escapes.frappe migrateandfrappe db diffmay 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-overrideis unchanged. A refusal the author means to overrule takes the line-- caramel:allow RULE SUBJECTabove the statement (the table,table.column, or the index forconcurrent-drop-index);-- caramel:allow-dropand-- caramel:allow-renamekeep working.frappe db diffwrites-- caramel:allow alter-column-type table.columnabove the checked text-to-date retype. - Framework migration
20260927000007 index_caramel_jobs_locked_and_claimaddscaramel_jobs_locked, which the stale-lock release uses, andcaramel_jobs_claim, which the claim walks instead of sorting the due backlog. A partitioned table refusesCREATE INDEX CONCURRENTLY, sofrappe migratebuilds 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_errornever 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: pingcomment 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. Replaceloop { Caramel::SSE.write(io, event: …, data: updates.receive) }withCaramel::SSE.relay(io, updates, event: …); withrelay, a subscription that closes ends the stream normally. The PubSub broker runsSELECT 1on 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-Cookielines and the values of PostgreSQL’sKey (…)=(…)detail from error messages and backtraces. The OTLP exporter normalisesdb.query.textbefore sending (strings and bare numbers become?, comments go, the text is cut to 500 bytes;$nbinds stay). Text log lines escape control characters as\n,\r,\eor\xNNand quote the value, so client input cannot forge a line.Caramel::Crema.trust_trace_context = false(orCARAMEL_TRUST_TRACE_CONTEXT=0) ignores inboundtraceparentandX-Request-ID, so a client cannot force sampling. Anhttp://OTLP endpoint off the loopback interface withOTEL_EXPORTER_OTLP_HEADERSset logsOTLP headers are sent in clear to HOST; use an https endpointat start. - Breaking: a route inside the
tenantblock fails compilation unless its action, or a parent, declaresingress authenticate: :method?, or the action declares the newingress open: true. Add one to every existing tenant action;frappe routesprints[open]for open routes.ingress open: truecannot combine withauthenticate:and cannot be declared under a parent that authenticates. frappe make tenancywritesmember?intoapp/actions/application_action.cr(true whensession["accounts"], the slugs this session signed up, names the tenant), guards the tenant home withingress authenticate: :member?, and its sign-up action joins the session; the generatedtenant_session(slug)signs up the slug through/accounts.frappe make resourcein a multi-tenant application writesingress authenticate: :member?into every tenant action, and its request spec proves 404 for another tenant’s member and 401 for a non-member. Replacemember?with a membership table as the sessions recipe shows.- Every git dependency in
shard.lockis locked to the commit its tag pointed at, in Shards’ own formversion: 0.31.0+git.commit.<sha>;scripts/shards installfails when a pinned shard was installed at another commit, andscripts/check shard-pinsrefuses 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 withoutshards update: copy thepg,db,blueprintandlexborentries from this release’sshard.lockinto yours, add+git.commit.<sha>(the release tag’s commit) to the caramel entry, then runfrappe setup;shards updatestrips the pins, so update a dependency by writing its tag’s commit into the lock instead.frappe lsp installrebuilds crystalline once, with itslspdependency pinned and verified. frappe buildwrites two files beside the artifact:SHARD-….tar.gz.sha256, whichsha256sum -corshasum -a 256 -cverifies, andSHARD-….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 underproperties. The artifact path is still the only line on standard output.CARAMEL_BUILD_IMAGE, set wherefrappe buildruns, 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 correttoreports 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 withCorretto: M of M workers passed in <total>; a script that matches that line exactly needs thein <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’slatte stopbefore starting this one, and restartfrappe devsessions started under the old path. Latte refuses withruntime_path_too_longwhen a home directory would push a socket path past macOS’s 103 bytes.scripts/crystalkeeps its OpenSSL alias under$TMPDIR. The trace collector answers 421 to a request whoseHostis not127.0.0.1,localhostor[::1]with its port, and keeps at most 64 MiB of traces.latte trust installrefuses, naming the file, when a key underservices/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_PORTandCARAMEL_LATTE_HTTPS_PORT(1024 to 65535; defaults 15353, 18080, 18443). WithCARAMEL_HOMEa 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 startrefuses 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-daemonruns 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, overSugarORM::Date(day.raw), stored in adatecolumn throughSugarORM::DateCodec, sohas settled_on : Day,has returned_on : Day?and apartof 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 migrationfrappe db diffalready derives.where: {settled_on: from..to}infinds,countsandspecificationtakes 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 asYYYY-MM-DD. A day is that text in JSON too, and a contract field binds it from that text withDay must be a calendar day written YYYY-MM-DD, as in 2026-02-28as its error.Day.new("2026-02-30")refuses,Day.new(2026, 3, 1)andDay.of(time)(the time’s own calendar day, with no conversion to UTC) build one,day + 7,day - 7andday - othermove and count by days, and days compare and sort. There is noDay.today: a command takes the day it means as an argument. Ahasreaches a codec through a value’sSWEETTALK_CODEC:Date,Decimal(P, S)andJson(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
datecolumn type, andSugarORM::DatewithSugarORM::DateCodecstores a calendar day in it:field due_on : SugarORM::Date, codec: SugarORM::DateCodec. ADateis a year, a month and a day with no time of day and no zone;Date.parsereads onlyYYYY-MM-DD. Adatecolumn read in a session whoseDateStyleis not ISO, or holdinginfinityor a BC date, raises ArgumentError instead of guessing a day.frappe db diffcreates and compares the column like any other. A codec that declaresORDERABLE = truebefore its schema, asDateCodecdoes, lets keywordwheretake a Range on that column (where(due_on: first..last)); the numeric,jsonbandtextcodecs still take only a value ornil(ADR 0042). - A text column that the schema now declares
date(a field withSugarORM::DateCodec) no longer haltsfrappe db diff: the diff derives a migration that locks the table, counts the values that are not a calendar day writtenYYYY-MM-DDand stops with that count and up to five of them if there are any, then drops the column’s default and runsALTER 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, includingdateback totext, still halts (ADR 0042). - SweetTalk: a type followed by
?makes ahasattribute optional for every type it takes.has owner : Setup::Owner?stores a nullableowner_idforeign key and its getter returns the id or nil,has settled_by : Teller?a nullable column of its raw type, andhas leg : Money?, a value with parts, one nullable column per part with aCHECKthat 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’swheneverhandler assignsrow.owner = otheron the row it holds, and@owner = other,@owner ||= otheror 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 afinds,countsorspecificationasks 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’skeycannot 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 anever(ADR 0039). - Breaking: a SweetTalk optional attribute now defaults to nil, including the existing
has note : String?. A factory orcreatethat 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:asclast, as PostgreSQL does. - Upgrade, SweetTalk: the new CHECKs and a new foreign key are added by
frappe db diffNOT VALIDand validated in a later step, so existing rows that break one stopfrappe 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, addsKind.all,Kind.includes?(text),Kind.paymentandkind.payment?, and every column that stores it getscheck_<table>_<column>_one_of_<hash>, which changes with the list, sofrappe db diffreplaces it when a word is added or removed;database_check: falsekeeps the list in Crystal only. The check is addedNOT VALIDlike the others, so a row outside the list stopsfrappe migrate: find it withSELECT id FROM <table> WHERE "<column>" IS NOT NULL AND "<column>" NOT IN (<words>). It takes neithermatches:norlength:, and a word that names a method the value, every object or Crystal already has, such asall,nameorend, does not compile. The compile error for a string value’s unknown options now namesone_of:(ADR 0040). - SweetTalk:
event Settled, carries: [kind, amount, owner], means: "…"takes one field for each attribute or derived value named, of its type, andemit Settledreads 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 anemitthat 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,ETagandLast-Modified, answer 304 to a currentIf-None-MatchorIf-Modified-Since, and carryCache-Control: public, max-age=31536000, immutablewhen the name has a three-part version (htmx-4.0.0.min.js) andno-cacheotherwise.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-passwordis 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::ALLand theContent-Lengthregressions 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, runfrappe lsp installagain after installing. New applications declarecrystal: ">= 1.22.1"inshard.yml, andfrappe buildcompiles incrystallang/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
serveorworkprocess may now hold three more connections, up toCARAMEL_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, andCARAMEL_WORKER_CONCURRENCYabove 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 withoutAPP ops(curl --unix-socket, scrapers) must sendAuthorization: Bearer $(cat SOCKET.key); Prometheus usesauthorization: credentials_file: SOCKET.key. A request without the key answers 401.ops consoleprints a URL containing the key, and a TCP forward without that URL gets 401. frappe setup --no-migrateinstalls dependencies and registers the site but leaves the development database unchanged, and prints that migrations were skipped and thatfrappe migrateapplies them;setupwithout the flag still applies pending migrations.- With
caramel/tenancyand no tenant bound, a cache key or PubSub channel name that starts witht<id>:now raises ArgumentError (insideCaramel::Tenancy.withoutit is allowed), andCaramel::Cache.cleardeletes only the bound tenant’s keys; with none bound it deletes only keys with no tenant prefix, and insidewithoutevery key. Wrap an app-wide clear inwithout. APP db roles(andDatabaseRoles.role) now validate role and database names themselves, keep a password out of theDO $body, and the script fails before any grant when a role that already exists has SUPERUSER, CREATEDB, CREATEROLE, BYPASSRLS or REPLICATION. Run it withpsql -v ON_ERROR_STOP=1; the role that runs it stays a member of both roles until you revoke them.frappe lintand new applications’.ameba.ymlenableCaramel/SourceTreeRead, which reports aFile.read,File.openorDir.globwhose 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.ymlto adopt it. The deploy guide now says what the artifact holds and how to embed a file withread_file.- A record is written as JSON only with the columns its schema’s
jsonline lists, such asjson :id, :title, :created_at, :updated_at, where it wrote every column. Every model an action returns, or any other code writes as JSON, needs ajsonline; compilation fails without one and the error names the model.frappe make resourcewrites the line for new resources, listing the id, its fields and the timestamps, never the tenant column. Caramel.content_security_policy(inconfig/application.cr) changes the Content-Security-Policy of every response,content_security_policyin an action changes one response’s copy, andcsp_nonceadds a per-response nonce toscript-srcandstyle-src. A header an action sets itself is kept.servenow sendsStrict-Transport-Security: max-age=31536000whenCARAMEL_ENVis 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,
servenow stops claiming jobs and ends every PubSub subscription, so a server-sent events stream ends instead of holding the process for the whole drain.serveandworkgive requests and jobs in flightCARAMEL_SHUTDOWN_TIMEOUTseconds (1 to 3600, default 25) and log what was still running when it passes;workused 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 allowsCARAMEL_SHUTDOWN_TIMEOUTplus 5 s before it kills a process. frappe devno 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=…, thatfrappe devprints asToolbar and inspector sign-in (single use): URL(also with--no-open) and opens, andfrappe openmints a new one whilefrappe devruns. The inspector pages answer 403 without the cookie, the toolbar saysNot signed in, and/__caramel/dev/statusshows an unsigned client onlygenerationandstate; the build-error page stays public. Open a new link after restartingfrappe 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.0SSL_OP_ALLoptions that Crystal before 1.22.1 gives everyOpenSSL::SSL::Context(GHSA-7jw4-6xx8-g2r9), so an application built with an older compiler is covered too: Shards only warns about thecrystal:floor. A TLS 1.2 connection now uses the extended master secret, and a peer that closes withoutclose_notifyis an error. A server that cannot do secure renegotiation is refused. frappe newandfrappe setupnow run each dependency’s postinstall script themselves, aftershards install --skip-postinstall, and keep what it writes in the toolchain’spostinstall-cache, keyed by the dependency’s name and version. The first install on a toolchain still builds lexbor’s parser (cc,arand 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 diffkeeps 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_swapname, then the old index is dropped and the new one renamed, so a unique index is never missing.belongs_totakeson_delete: :cascade,:restrictor:set_null.frappe migratecommits 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 hitslock_timeoutrolls back and runs again after 1, 2 and 4 s; a fourth timeout stopsmigratewithMigrator::LockTimedOut, which names the migration.CARAMEL_POOL_SIZE(1 to 32) andCARAMEL_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,BigIntandBigRationalin every managed build: the toolchain now bundles GMP 6.3.0, andfrappe buildlinks it statically. Remove any@[Link(ldflags: …)]onLibGMPand any vendoredlibgmp.aan 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 installagain 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_timeoutandlock_timeoutwhen it opens, and the client’s read timeout follows the statement timeout, 5 seconds behind it.serve,work,seed,lintanddriftdefault to 30 s and 5 s;migratedefaults to no statement timeout and 5 s. A statement that ran longer than 30 s now fails withcanceling statement due to statement timeout. RaiseCARAMEL_STATEMENT_TIMEOUTorCARAMEL_LOCK_TIMEOUTfor a process that needs longer, andCARAMEL_MIGRATION_STATEMENT_TIMEOUTorCARAMEL_MIGRATION_LOCK_TIMEOUTformigrate: 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 theon_failedhooks, andjobs retryruns it again. Released runs no longer count againstretry_onattempts. - The framework migration
20260927000006addscaramel_jobs.releasesand takes a lock on everycaramel_jobspartition. Runfrappe migratewhile no job is running, ormigrate’s 5 s lock timeout may refuse it;CARAMEL_MIGRATION_LOCK_TIMEOUTraises 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, aSweetTalk::Refusalthat an action’shandledoes 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 startingERR INVALID:422for other clients. ASweetTalk::Missinganswers 404. Neither is reported to Crema as an error. An action that rescues them itself is unchanged, andSweetTalk::Boundarystill answers 500. Asking an aggregate for its id beforecreate, or an event for its subject before it is emitted, raisesNilAssertionErrorinstead ofSweetTalk::Missing. - A contract field may take a SweetTalk value or an aggregate’s id:
field quantity : Ordering::Quantitybinds as anInt32, 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
statecolumn has aCHECKconstraint namedcheck_<table>_state_<8 hex digits>, and a state of two or more words is stored asmovesspells it. 0.13.0 storedawaiting_paymentasawaitingpayment: first add a migration that respells such rows, such asUPDATE ordering_payments SET state = 'awaiting_payment' WHERE state = 'awaitingpayment', and migrate, then runfrappe db diff, which adds each constraint asNOT VALIDand validates it in the_concurrentlymigration.frappe migratestops, naming the constraint, while a row holds any other text; the constraint staysNOT VALIDuntil 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, sincerenamed_from:keeps the old table and its long name. - A
findsthat 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 afindswith a block instead. - Calling another context’s service, as in
Catalogue.price_of(tea), counts as namingCatalogue::: outsideborder Catalogueit compiles only where the context follows Catalogue. Move the call into the border, or declarefollows: 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 namesCaramel::OutboundorHTTP::Clientonly inside a border with an outside system,border Cards, outside: "…" do … end. - Additive, nothing to edit:
specificationnames a rule once,findsandcountssort, limit and count, a context names itssubdomain:and what itpublishes. The SweetTalk guide lists them → frappe agent-manifestprints aGUIDES:line afterDOCS:, 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.txtafter the documentation link inAGENTS.md. An application with a domain gets the SweetTalk skill with its nextfrappe make domain, or now withmkdir -p .claude/skills/sweettalk && cp lib/caramel/templates/skills/sweettalk/SKILL.md .claude/skills/sweettalk/, which also refreshes it after a later upgrade; addDomain rules: .claude/skills/sweettalk/SKILL.md, which frappe make domain writesafterDomain:inAGENTS.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
whereno longer takes a value that may be nil, such as aString?variable, because nil matched the rows whose column IS NULL. The call fails to compile with…MayBeNilin the error. Narrow the value first (if token = contract.token), or use the newwhere_null(:column); the literalwhere(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
UploadedFilefield. - A Crema sink or exporter that matches
Caramel::Crema::SpanKindexhaustively must handle the newdomainkind. sudo scripts/install-local-integration applyinstalls only a bundle that the user who ransudoprepared, and refuses to run as root withoutsudo. ACARAMEL_LATTE_SWIFT_CACHEdirectory must be yours alone.- SweetTalk arrives, experimental, and nothing changes until an application requires
caramel/sweet_talk.frappe make domain NAME CONTEXT --means=TEXTstarts a domain; a multi-tenant application names its tenant withtenant App::Accountbefore its first context. Applications generated before this release add theLint/UnusedArgumentexclusion forapp/domain/**to their.ameba.ymlby hand, aslib/caramel/templates/application/.ameba.ymlhas 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,
servenow 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 stopsserveat least 30 s. - Applications can run in production on Linux:
frappe buildwrites a static linux/amd64 artifact,servereads public files fromCARAMEL_ROOTand runs without workers with--no-workers,APP jobs unknownlists queued jobs a binary cannot run andAPP db rolesprints 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 diffreads is now version 3, because it carries CHECK constraints. - SugarORM owns the CHECK constraints named
check_….frappe db diffdrops acheck_…constraint that no schema declares; any other CHECK constraint stays and is noted. Declare a hand-writtencheck_…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 updateso 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.workandmigratenow 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,
`,jandkwork 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
$nand the copy starts with a comment saying so. Anilbind is now recorded asNULLand shown bare in the Binds column; the textNULLstays 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
opscommands 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 addcaramel_jobs.contextandcaramel_metrics. - Run
latte stoponce 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 preloadpg_stat_statementsandauto_explain. - To keep per-minute aggregates, add
require "caramel/crema/recorder"afterrequire "caramel"inconfig/application.cr. New applications already have it. - Add
Caramel/Dumpto an existing application’s.ameba.yml, as new applications have it, sofrappe lintreports a leftoverdump. - Logging now sets itself up: JSON in production, text in development and test. The old
error_typelog line is gone; theerrorline carrieserror_classandfingerprint.Caramel::DevelopmentError.responsenow takes aCaramel::Crema::ErrorReport;Caramel::Database::Configgainsapplication_name, andSugarORM::Repothe private hooksobserveandobserve_checkout, whichcaramel/crema/sqlredefines. - To adopt the agent files, copy
AGENTS.mdandCLAUDE.mdfromlib/caramel/templates/application; existing applications keep their own. - Opt in as you need:
require "caramel/crema/otlp"exports traces to the endpointOTEL_EXPORTER_OTLP_ENDPOINTnames; the ops socket opens besideserve, and forworkwhenCARAMEL_OPS_SOCKETnames a path;frappe logs accessprints the site’s access log;frappe make tenancy MODELmakes the application multi-tenant.
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.
| 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 |
| 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
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.
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.
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.
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.
Limits
Current limits
- Caramel ships no command that provisions servers or deploys;
frappe buildends 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 VERSIONexists 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_SECRETsigns sessions, CSRF tokens and debug tokens;APP_SECRET_PREVIOUSkeeps 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
frappe migrate
frappe check
frappe corretto
frappe lintPassing: 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.