jade-lang 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b817b13aad1b314b6a8bf578f8a604246d19091712a77375376515732b6dcbc
-  data.tar.gz: 7be6b4091ac7c57c6befe21fb0ffbea302b9e33bd2940479b7c4227dd37cd1b6
+  metadata.gz: 9b0d9367dd2a235c282b3e7bbeabc2ee7874fa6899fdbdd746c66d546279cf30
+  data.tar.gz: cf83815353b341a4834b5b17712148db973f96a3a914ac6aa2ae019a00ae84df
 SHA512:
-  metadata.gz: 9b758da80e8b9033dd6b5ce840188f7d69a8d482cf496a3731c4a4f7b5bcb90ddd0119e5b5eb6e9b1763bddffca4f3df49b6cba7d6a26d9304538efde7a8aa49
-  data.tar.gz: 22abc8374f37d7f9ff3c03f5f2a35861322f234227c3d0932e80c56e17bb49de5ce6ac67dc7c1f0b1896ce2b9a5c3562a2d8197f697f74fdd5d18e5db64094f6
+  metadata.gz: 1551750ffbca65f37071206e6eccc559f2d7ae81b5ecf0545c089bc3b0f8d36ba3cc3d98c4c33ce3b2c572c8a650d494c40c9d926f210a1f449c478257ca084c
+  data.tar.gz: 2ec0e124c2057bd34cf99728253b5dbd93765c77694a7f6ca0799be1c56eb1baa6d79e4cbc8268ad56a38fa811877defb5ccbd2f7538ce24e33958754ee90aa6

data/CHANGELOG.md

@@ -4,27 +4,438 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.10.1] - 2026-09-11
 
 ### Added
 
-- **`Jade::Extensions`, where a gem hooks into compilation.** Two kinds, both
-  read-only: a *deriver* builds an implementation for an interface it owns,
-  and a *check* reads a call site and returns errors. Checks register against
-  a named phase — `:call` today — and receive the call's AST node alongside
-  its resolved argument types, because types alone cannot see a raw SQL
-  string's placeholders or a constant predicate. Only gems named in
-  `Extensions::ALLOWED` may register, so the compiler knows who extends it and
-  nothing about what they do.
+- **`Decode.decoder`, the derived decoder as a value.** `Decode.from_json` has
+  always picked a decoder off the return type, but there was no way to name
+  that decoder and hand it to a combinator — every project ended up with a
+  `uuid_decoder` and a `date_decoder` per module, reimplementing an instance
+  that already existed. `Decode.field("on", Decode.decoder)` now resolves the
+  `Decodable` instance from the position the decoder stands in, including
+  derived ones, and a type without an instance is a compile error naming the
+  type.
+
+- **`jade init`.** Writes `jade.json`, which is how every tool that runs
+  outside the app finds your sources, creates the source directory, and adds
+  `.jade/` to a `.gitignore` that has one. It refuses to overwrite an existing
+  manifest rather than discarding a source root and extension list that cannot
+  be recovered from the directory. Until now the first thing a new project met
+  was the error telling it to write that file by hand.
+
+### Fixed
+
+- **A function type printed as `(a) -> b`, which means something else.**
+  `Type::Function#to_s` parenthesised its parameters unconditionally, so
+  `jade q api` printed `List.fold : (List(a), b, (b, a) -> b) -> b`, a
+  signature whose outer parentheses read as a tuple argument. It prints the
+  bare form now, `List(a), b, (b, a -> b) -> b`, which is what the formatter
+  writes and what you can paste back into a file.
+
+  Parentheses around a comma list are a tuple everywhere, and a parameter
+  list is bare. A nested function type keeps parentheses of its own, told
+  apart from a tuple by the arrow inside them. `(Int) -> Int` also parses
+  now, which it did not: one element is not a tuple.
+
+- **A record update that does not fit crashed the compiler.** The unification
+  that closes an update was the one call with no error block, and
+  `State#unify` calls the block unconditionally when unification fails, so a
+  mismatch reached `nil.call` and took the compiler out with a `NoMethodError`
+  naming a line in `state.rb`. Changing a field's type is the usual way in;
+  anything the surrounding code cannot accept arrives the same way. It now
+  reads `This update produces Box(Int), but String was expected`.
+
+## [0.10.0] - 2026-09-02
+
+### Breaking
+
+- **Division cannot divide by zero.** `a / b` used to raise Ruby's
+  `ZeroDivisionError` straight through Jade, so `Int -> Int -> Int` was not as
+  total as it read. `/` now takes a `NonZero`, which only `non_zero(n)`
+  produces, and it hands back a `Maybe` so the caller decides what an absent
+  answer means. A literal divisor is already known: `cents / 100` is unchanged,
+  and `n / 0` is a compile error rather than an expression that type checks.
+  `NonZero` has no constructor and is erased at runtime, so division costs what
+  it costs in Ruby.
+
+  ```jade
+  def each(total: Int, people: Int) -> Maybe(Int)
+    Maybe.map(non_zero(people), (d) -> { total / d })
+  end
+  ```
+
+  Implementing `Numeric` for your own type means `(/): a -> NonZero(a) -> a`,
+  with `Number.unwrap` to unwrap the divisor. `Decimal.div` takes a `NonZero`
+  for the same reason.
+
+### Added
+
+- **An anonymous record crosses to Ruby.** `def origin -> { x: Int, y: Int }`
+  returned `NotExposed`: `Encodable` derived for a `struct` but not for the
+  same shape written inline, so a function returning one was unreachable from
+  Ruby though every field was encodable. It now derives structurally, the way
+  `Decodable` already did, and a record with a field that has no instance
+  still refuses.
+
+- **`type alias Name = T`.** A structural name for a type that already exists:
+  `type alias UserId = Int`, `type alias Point = (Float, Float)`,
+  `type alias User = { name: String, age: Int }`. The alias and its body are
+  the same type, so a record literal satisfies a record alias directly and no
+  constructor is introduced. Aliases take parameters
+  (`type alias Pair(a) = (a, a)`). An alias without parameters is expanded
+  during forward declaration and a parameterised one when its arguments are
+  known, which is what makes `UserId` and `Int` interchangeable everywhere.
+
+  An alias has no identity of its own, so it carries no implementations:
+  `implements Show(UserId)` is rejected rather than silently attaching to
+  `Int`, where it would collide with every other alias over `Int`. What an
+  alias *inherits* needs no declaring — `Encode.encode` on a `UserId` is
+  `Encode.encode` on an `Int`. A recursive alias is rejected too. Reach for
+  `struct` when you want a distinct type, or a single-variant `type` for a
+  newtype around an inner shape.
+
+  `jade fmt` breaks a record alias past one field the way it breaks the
+  `struct` beside it, and `alias` is a contextual keyword — read as one only
+  directly after `type` — so a record field or argument may still be called
+  `alias`.
+
+  Expansion reaches the edges too: an alias over a `Task` is a port return
+  type and cannot hide a nested one, a function type behind an alias is still
+  refused for interop, an alias cannot stand between a type and itself and
+  hide that there is no way to build one, `implements` on an *imported* alias
+  is reported rather than reaching codegen, and `exposing (UserId(..))` says
+  an alias has no constructors instead of accepting it silently.
+
+  The name survives expansion for the sake of reading: a mismatch against a
+  `UserId` says `should be UserId (= Int)` rather than `should be Int`, and
+  keeps the short name in a nested position (`List(UserId)`). `jade api`
+  reports an alias as an alias rather than as a function, and hovering one in
+  an editor gives its declaration — on the declaration itself and on every use
+  in a signature.
+
+- **`jade eject`.** Writes the project as Ruby that runs without the gem: every
+  compiled module, the runtime they call, and requires pointing at each other
+  rather than at a load path. What it vendors is whatever a booted runtime
+  loads, asked at eject time rather than kept as a list, so it cannot drift.
+  The exit was a promise before this; now it is a command with a spec that
+  runs the ejected tree in a process that has no jade on its load path.
+
+- **A guard on what the runtime loads.** Compiled code requires
+  `jade/runtime` and nothing else, so whatever that pulls in ships in every
+  production image and has to be vendored by an eject. A spec now pins the
+  set to seven files and fails if the parser, the AST, the frontend, the
+  formatter, the LSP or the CLI appear. Booting the intrinsics still does
+  pull the compiler in, and that example is pending rather than passing.
+
+- **The LSP indents while you type.** It advertised `documentFormattingProvider`
+  and nothing else, so an editor without the tree-sitter grammar left the cursor
+  at column 0 after every Enter. `documentOnTypeFormatting` now indents the line
+  Enter opened, and puts `end` back where its opener sits, from the text above
+  the cursor rather than a parse, which a half-written file will not give.
+
+- **`_` works in a tuple or record literal.** `5 |> (_, "five")` and
+  `{ w: _, h: 2 }` make a function of the hole, the way `f(_, y)` already did.
+  A variant carrying a record gets it too, since that is what a keyed call
+  lowers to: `Rect(w: _, h: 4)` was the one shape with no way to express it
+  short of writing the lambda out.
+
+- **`(x, y) = p` destructures a tuple.** A tuple's arity is fixed by its type,
+  so the binding is irrefutable exactly as `T(x, y) = t` already was; the
+  workaround was a three-line `case` for a destructure that cannot fail. The
+  pattern was accepted all along, but a `(` opening a line was read as a call
+  on whatever the line above ended with, so the binding never got the chance.
+
+- **`List.sum` and `List.product`.** Both fold over `Numeric`, which gained
+  `from_int : Int -> a` so the seed can come from the interface rather than the
+  list: `sum([])` is `0`, not "nothing", so a `Maybe` return would have modelled
+  a non-problem as a failure. `Int` implements it with `identity`, `Float` with
+  `to_float`, `Decimal` by scaling. A type of your own that implements `Numeric`
+  needs the new member.
+
+- **A call short of its arguments says so.** `Rec(id: 1, status: Issued)`,
+  where `Issued` carries an `Int`, reported `expected (Int, Status) -> Rec but
+  found (Int, (Int) -> Status) -> Rec` and left the reader to notice which slot
+  had become a function. It now adds ``help: `Issued` needs 1 argument``, and a
+  call with the wrong number of arguments outright reads ``help: `add` takes 2
+  arguments, 1 given``.
+
+- **A call with a hole and one argument too many says so.** `xs |> f(_, y)`
+  reads as though the `_` marks where the piped value goes, but `|>` has
+  already put it in front. The message now names the shape and the fix
+  instead of leaving a unification failure to be decoded.
+
+- **The `module` snippet fills in the name.** A module's name is fixed by its
+  path, so the placeholder was offering a decision with one right answer;
+  completion now derives it from the document URI, turning `sql/mutation.jd`
+  into `module Sql.Mutation exposing (...)`.
 
 ### Changed
 
-- **The `Sql.Assignable` deriver moves to jade-sql.** The deriver list named
-  jade-sql's interface outright, with a comment apologising for it; it now
-  holds only the built-ins and whatever an allowed gem registers.
+- **A crossing does less on the way in.** An argument with a specialized
+  decoder now carries its own name, in a string constant it was passing
+  anyway, so the wrapper no longer opens a block per argument just to label a
+  failure. And a hash is no longer scanned for symbol keys before its fields
+  are read: symbol keys make every field missing at once, which the rescue
+  around the fields already notices, so the message is unchanged and the check
+  is gone from the success path. A struct argument goes from 772ns to 724ns, a
+  scalar argument from 158ns to 127ns, and decoding a list of 1500 structs
+  from 940us to 820us.
+
+- **A dictionary built from concrete implementations is built once.** Calling
+  a function with an interface constraint at a known type emitted the whole
+  dictionary as a literal at the point of use, so `List.sum(xs)` on a
+  `List(Int)` allocated a 5-entry Hash, an Array and two lambdas on every
+  call, 522ns before any adding happened. Inside a fold the literal landed in
+  the block and was rebuilt per element. Dictionaries that name no dict
+  parameter now become frozen module constants, shared by every call site
+  that wants the same one, and referencing an interface method as a value no
+  longer builds a Hash to index it once. A fold over 5000 values goes from
+  7.3x the equivalent Ruby to 3.3x, a per-row `List.sum` from 2.8x to 2.0x.
+
+- **A variant with no fields is one object, not a new one per construction.**
+  `compare` allocated a fresh `GT` on every call, which cost more than the
+  comparison: 214ns against Ruby's 23ns for `<=>`. Nullary variants carry no
+  state, so nothing can tell two instances apart, and every construction now
+  hands back the same object. `compare` drops to 87ns, and a function
+  returning a three-arm enum over 5000 values goes from 5.7x the equivalent
+  Ruby to 2.7x. Applies to `Maybe.Nothing`, `Result` arms, `Order` and every
+  user enum.
+
+- **A rejected value says where in the value the problem is.** A field that
+  did not decode reads `Shop.total(items)[0].cents: expected Int, got String
+  ("lots")` rather than blaming the argument as a whole, and a field the hash
+  never had reads `missing field \`cents\`` rather than `expected Int, got
+  nil`. Paths cost nothing on the way in: the segments are constants in the
+  generated code, and the index of a bad element is found only when one is.
+
+- **A build left by another version of the compiler is rebuilt.** Generated
+  Ruby calls the runtime by name, so a build made by a different version can
+  call a helper this one no longer has. `.jade/build` now carries the
+  fingerprint that `.jade/cache` already used, and is dropped when it does not
+  match. No source changes in that case, so mtimes could not see it.
+
+- **A value Ruby cannot pass says which call and which argument rejected it.**
+  `Ruby passed a value that failed to decode at value: expected Int, got null
+  (nil)` is now `Shop.price(item): expected Int, got nil`. The caller may not
+  know Jade, so the message names the function, the argument it came in as, and
+  types in Ruby's vocabulary rather than the wire's.
+
+- **`jade fmt` hugs a trailing block argument.** A call whose last argument is
+  a lambda, list or record literal keeps its head on one line and lets that
+  argument grow a body, the way a Ruby block reads:
+
+  ```jade
+  describe("Math", [
+    it("adds", -> { Expect.equal(1 + 1, 2) }),
+  ])
+  ```
+
+  It previously broke every argument onto its own line, burying the call the
+  body belonged to. The head still breaks when it cannot fit, or when an
+  earlier argument is the one that grew.
+
+  Two shapes that left output hanging go with it: a lambda whose inline body
+  broke anyway (`-> { Decode.map(` … `}) }`) now uses the block form, and a
+  `|>` or `++` operand that breaks across lines keeps its continuation under
+  the operator that introduced it rather than at column zero. **Formatted
+  output differs from 0.4.0** — a format check in CI reports diffs on the
+  first run after upgrading. Over 65 real modules, 25 reformat; formatting is
+  idempotent on all of them.
+
+- **A `(` that opens a line starts a statement rather than continuing the one
+  above.** `foo` on one line and `(1, 2)` on the next is now two statements, not
+  a call. The same rule applies to a type's arguments, so a return type no
+  longer reaches across a newline to swallow the body's first line.
+
+### Removed
+
+- The error saying a record literal has no placeholder, which is no longer
+  true. `Name(field: _)` on a *positional* variant still reports: there are no
+  field names there to refer to.
 
 ### Fixed
 
+- **Generated Ruby no longer makes Ruby complain.** An interop import emitted
+  its `rescue LoadError` indented as though it were part of the `begin` body,
+  which Ruby warns about under `-w`, and the runtime had a circular require
+  between `jade/task` and `jade/tasks` that neither file needed at load time.
+  The ejected examples are now loaded in a fresh process under `-w` and the
+  suite fails if Ruby says anything at all, which is the check that would have
+  caught a module and a type sharing a constant on its own.
+
+- **A type that contains itself no longer exhausts the stack at compile
+  time.** `type Tree = Leaf | Node(Tree, Tree)` compared with `==` raised
+  `SystemStackError` from the compiler, naming a Ruby frame rather than
+  anything you wrote: deriving an instance asks for its components'
+  instances, and `Tree`'s component is `Tree`. So did a struct that reaches
+  itself, `struct Pepe = { pepe: Maybe(Pepe) }`, on `==` or at the Ruby
+  boundary.
+
+  Equality now works on both: a derived `Eq` is structural, and Ruby's `==`
+  computes exactly that, dispatching to whatever each component defines — so a
+  component with a hand-written `implements Eq` is still asked. `Encodable`
+  and `Decodable` say `cannot be derived for Pepe because it contains itself`
+  and point at writing the implementation by hand, which was always the answer
+  and used to arrive as a crash.
+
+- **A recursive type with nothing to stop it is reported where it is written.**
+  `struct Pepe = { pepe: Pepe }` declared fine and read fine; you found out at
+  the use site, in a message about the argument you passed rather than about
+  the declaration that can never be satisfied. It now says so at the
+  declaration, along with the way out:
+
+  ```
+  error: `Pepe` can never be built: every `Pepe` needs a `Pepe` inside it first
+    --> src/pepe.jd:3:1
+    |
+  3 | struct Pepe = { pepe: Pepe }
+    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ nothing here stops the recursion
+    |
+    = note: a type may refer to itself; `Pepe` just has no case that stops,
+            so there is no smallest `Pepe` to start from
+    = help: wrap the field in something that has an empty case:
+            `Maybe(Pepe)` can be `Nothing`, `List(Pepe)` can be empty
+  ```
+
+  A type referring to itself is the point of a union, so what is checked is
+  whether there is a way out: `Maybe` has `Nothing`, `List` has `[]`, `Result`
+  has its `Err` arm, a union has any variant that does not lead back. All of
+  those still compile, `struct Pepe = { pepe: Maybe(Pepe) }` included, and so
+  does a field holding a function that returns the type, since the function
+  itself can be written. `type T = A(T)`, two declarations that need each
+  other, and a struct reaching itself through a tuple do not.
+
+- **A module may be named after a type in its parent.** `module Sql.Expr`
+  beside `type Expr` in `Sql` compiled without complaint and then emitted two
+  definitions of one Ruby constant, so whichever file loaded second silently
+  took the name and calls into the other failed with a `NoMethodError` and a
+  Ruby warning. The module now reopens the type's class rather than defining a
+  module beside it, which is what Ruby wants and what Elixir does with the
+  same pair. Constructing, pattern matching and the module's own functions all
+  work together.
+
+- **A list from Ruby is copied, not borrowed.** A `List(Int)` argument came
+  through as the caller's own Array, so pushing to it after the call changed a
+  value Jade had already taken. Lists of structs were copied already, by the
+  decoder that builds them; only the scalar fast path handed the object
+  straight through. The copy costs 0.3us for 1500 elements against the 46us
+  the element check already spends, so under 1% of a crossing that was already
+  paying to look at every element.
+
+- **A Jade name that is a Ruby keyword compiles.** `begin`, `next`, `class`,
+  `self`, `return` and 20-odd others are ordinary Jade identifiers, and
+  emitting them verbatim produced Ruby that would not parse — a local or
+  parameter called `next` was a syntax error in the generated file, not a
+  message from the compiler. Bindings now carry a trailing underscore
+  (`next_`), and a name that already ends in one gains another so `next` and
+  `next_` stay distinct.
+
+  Only bindings are rewritten. Ruby accepts its keywords as method names and
+  as `Data` members, so a function called `next` is still `Mod.next` from Ruby
+  and a field called `class` is still `class` on the wire.
+
+- **`examples/records.jd` compiles.** `update_email` built an anonymous record
+  where a `Person` was wanted, and nothing compiled the file: the examples
+  suite skipped it. It now uses a record update, and the suite covers it.
+
+- **A running app no longer loads the compiler.** `Runtime.boot!` read the
+  stdlib files for their implementations and got their declarations too, so
+  every production image carried the parser, the AST and the type checker:
+  301 files, 22k LOC, 171 ms. Those files are now read in a mode that
+  registers the intrinsics and skips the declarations, which is 53 files and
+  23 ms, and the compiler reads them again in full when it arrives. It also
+  fixes a latent break: `require 'jade/runtime'` followed by `boot!`, with no
+  `require 'jade'` first, used to raise.
+
+- **A mismatch spanning a mismatch already reported is dropped.** Cascade
+  suppression caught the case where both errors mention the same inference
+  variable; where the outer one had resolved to concrete types it named no
+  variable, and the same fault was still reported twice, at the call and at the
+  body around it.
+
+- **A module whose only declaration is half-written no longer crashes the
+  tolerant parser.** Recovery drops a declaration it cannot parse, and the
+  module node took its span from the last one, so a file with nothing left
+  raised `undefined method 'range' for nil` inside the parser. In the editor
+  that surfaced as a crash notice on a file you were part-way through typing,
+  which is the state it exists to cope with.
+
+- **The LSP reports errors in files you do not have open.** It compiled from
+  each open buffer, so a module nobody had opened was only ever reached as
+  someone else's import, and a broken one that nothing imports was reported
+  nowhere. Opening or closing a file now compiles every module under the source
+  root, starting from the modules nothing imports so the pass covers the project
+  once, and diagnostics published for a file are cleared when it is fixed even
+  if it was never open. Typing still recompiles only what is open, and the LSP
+  now reads and writes the project's compile cache the way the CLI does.
+
+- **`List.range` returns `List(Int)`.** Its signature said `List(a)`, with the
+  `a` free and bound by nothing, so `List.range(1, 3)` type-checked as a list
+  of anything the caller happened to want.
+
+- **Parse errors no longer name `lbrace` where a `{` could never go.** An
+  alternation reported whichever branch it tried last, and a record literal is
+  last in several chains, so `module Pepe exposing`, `def f -> Int end`, and
+  `(x, y) = p` all came back as "expected lbrace". A failure on the token the
+  alternation started from now says what the position wanted (an expression, a
+  type, a declaration), while a failure further in, which got somewhere, is
+  still the one reported. `exposing` also commits on its keyword, so a header
+  stopped after it asks for `(` rather than blaming the body.
+
+- **An empty body says so.** `def f -> Int end` reported `expected lbrace` and
+  underlined the `end`, the one token there that was certainly right. It now
+  reads `expected an expression (a body has to produce a value)` and underlines
+  the construct the body belongs to. Every function passes through that state
+  while it is being typed.
+
+- **`Name(field: _)` on a variant explains which variant you have.** The
+  message stated the rule; it now says whether the arguments have no names at
+  all (offering the `|>` form, which needs no placeholder) or carry a record
+  (offering the lambda). A positional variant no longer also reports every key as an
+  unknown field.
+
+- **The LSP reads `jade.json`.** `on_initialize` took the editor's root as the
+  source root, so in a project with `"source_roots": ["lib"]` every module was
+  named from the project root: the editor demanded `Lib.Test` while the
+  compiler compiled `Test`. Reading the manifest also loads the extension gems
+  whose modules a project imports.
+
+- **A crashed compile publishes a diagnostic instead of silence.** Zero
+  diagnostics is indistinguishable from a clean file, so an LSP bug looked
+  exactly like working code.
+
+- **One mistake, one message.** `t |> Plan(_, 150)` reported four errors: the
+  call that failed to unify, the expression around it, and the body that
+  returned it, each wearing the type the one below left behind. Mismatches on a
+  single span are now read as one failure: the most specific of them survives,
+  since a subclass exists for no other reason. A later error naming an
+  inference variable an earlier one already named is downstream of it, so it
+  goes too. Errors that share nothing still both appear.
+
+- **Inference ids no longer leak into messages.** `t8894` is a counter: it
+  means nothing to a reader, it changes between compiles, and two occurrences
+  of one variable look unrelated unless you notice the digits match. Within a
+  message they render as `a`, `b`, `c`, the letters the signature syntax
+  already uses. The ids stay internal.
+
+- **A module named after its principal type loads.** `module Plan` holding
+  `type Plan` emitted `Plan::Building` and `Plan::Internal`, which Ruby resolves
+  lexically: inside `module Plan` the constant `Plan` is the *type*, so those
+  became `Plan::Plan::Building` and died at load with `uninitialized constant`,
+  after compiling clean. Every reference to generated code is now rooted;
+  constructor calls already were, patterns and `Internal` calls were not.
+  Naming a module after its type (`Plan`, `Member`, `Money`) is ordinary, so
+  this would have kept happening.
+
+- **The same type declared twice is an error.** Two `type AgeTiers` blocks in
+  one module compiled, emitted both, and left the *Ruby interpreter* to mention
+  it with `warning: already initialized constant`, naming the generated file
+  rather than the `.jd`. The clash check only fired between kinds (a `struct` against a
+  `type`); it now fires within a kind too, and moved to the pass that can still
+  see both declarations, so the error lands on the second and points at the
+  first.
+
 - **A long chain of `Task.and_then` no longer exhausts the Ruby stack.** Each
   `and_then` ran the next task from inside the previous one's `run`, so depth
   cost a stack frame and anything built by recursion, a batch loop or a retry,
@@ -43,6 +454,25 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   only arise within one module: the orphan rule and cycle detection between
   them rule out the cross-module case.
 
+## [0.9.0] - 2026-08-21
+
+### Added
+
+- **`Jade::Extensions`, where a gem hooks into compilation.** Two kinds, both
+  read-only: a *deriver* builds an implementation for an interface it owns,
+  and a *check* reads a call site and returns errors. Checks register against
+  a named phase — `:call` today — and receive the call's AST node alongside
+  its resolved argument types, because types alone cannot see a raw SQL
+  string's placeholders or a constant predicate. Only gems named in
+  `Extensions::ALLOWED` may register, so the compiler knows who extends it and
+  nothing about what they do.
+
+### Changed
+
+- **The `Sql.Assignable` deriver moves to jade-sql.** The deriver list named
+  jade-sql's interface outright, with a comment apologising for it; it now
+  holds only the built-ins and whatever an allowed gem registers.
+
 ## [0.8.0]
 
 ### Added

data/README.md

@@ -348,6 +348,7 @@ for us so far.
 A single `jade` binary fronts the toolchain:
 
 ```
+jade init                 # write jade.json and the source directory
 jade check [file...]      # type-check; exits 1 on errors, generates nothing
 jade fmt [-i|-c] [file]   # format .jd source (stdin or file)
 jade lsp                  # language server over stdio (hover, defn, refs, diagnostics)

data/docs/interop.md

@@ -166,6 +166,21 @@ Users.fetch(1)
 The Jade caller never sees a malformed `User` — the bug is caught at the entry
 point, and the error arm (here `String`) stays meaningful for real failures.
 
+## Reading a rejection
+
+A value that does not cross is reported at the path where it went wrong,
+starting from the call the Ruby caller made:
+
+```
+Shop.price(item).cents: expected Int, got String ("lots")
+Shop.total(items)[0].cents: missing field `cents`
+```
+
+`missing field` means the key was absent, as opposed to present and holding
+something of the wrong type. Only the failing call pays for any of this: the
+path segments are constants in the generated code, and the index of a bad
+element is searched for only once an element has failed.
+
 ## What the compiled boundary looks like
 
 For a function with a primitive argument:
@@ -197,7 +212,9 @@ module Sample
   end
 
   def self.absolute(n)
-    Internal.absolute(Jade::Interop::Boundary.integer("Int", n))
+    Internal.absolute(
+      Jade::Interop::Boundary.arg("Sample.absolute(n)") { Jade::Interop::Boundary.integer("Int", n) },
+    )
   end
 end
 ```

data/docs/json.md

@@ -61,9 +61,23 @@ DecodeJson::Internal.user('{"name":"Ada"}')
 # => Err(MissingField("age"))
 ```
 
-The struct decoder is `Decode.succeed(User(_, _))` piped through one
-`Decode.required` per field — the `_` placeholders are the constructor's holes,
-filled left to right as each field decodes.
+The struct decoder is `Decode.succeed(User(_, _))` piped through one step per
+field — the `_` placeholders are the constructor's holes, filled left to right
+as each field decodes. `Decode.required` fails on a missing key;
+`Decode.optional` takes what a missing key stands for instead, which is a
+`Maybe` when that is the field's type:
+
+```jade
+Decode.succeed(Note(_, _, _))
+  |> Decode.required("body", Decode.nullable(Decode.string))
+  |> Decode.optional("kind", Decode.string, "note")
+  |> Decode.optional("archived_on", Decode.map(Decode.decoder, Just), Nothing)
+```
+
+A nullable field is a required one: the key has to be there, and `null` is a
+value the decoder admits. Pick the step at the field — once a step has run the
+pipeline holds the constructor's remaining arguments, so nothing downstream
+reaches back into one field.
 
 ## Encoding
 
@@ -146,6 +160,23 @@ end
 Reach for the explicit combinators above when the JSON shape doesn't match the
 struct one-to-one — renamed keys, nested lookups, optional fields.
 
+Those combinators still take derived decoders for the leaves. `Decode.decoder`
+is the instance for whatever type is expected of it, so a hand-built shape can
+be filled with types that already know how to read themselves:
+
+```jade
+def decoder -> Decoder(Movement)
+  Decode.succeed(Movement(_, _, _))
+    |> Decode.and_map(Decode.field("from_id", Decode.decoder))
+    |> Decode.and_map(Decode.field("to_id", Decode.decoder))
+    |> Decode.and_map(Decode.field("occurred_on", Decode.decoder))
+end
+```
+
+Two of those fields are `Uuid` and one is a `Date`; each resolves from the
+position it stands in. A type with no instance is a compile error naming the
+type, not a decoder that fails at runtime.
+
 Derivation reaches through the structural types to their elements, so anything
 built out of encodable parts is itself encodable:
 

data/docs/stdlib.md

@@ -47,6 +47,7 @@ readable Ruby. This is a map of the territory; `jade q api` is the atlas.
 |--------|--------------|
 | `Basics` | The built-in interfaces — `Eq`, `Comparable`, `Appendable`, `Mappable`, `Chainable` — plus the `Ordering` type (`LT` / `EQ` / `GT`) and `Never`. `++` works on `String`, `List`, and `Bytes` via `Appendable`. |
 | `Maybe` | Optional values without `nil`: `Just(a)` / `Nothing`, with `map`, `and_then`, `with_default`. |
+| `Number` | `non_zero(n)`, the only way to hold the `NonZero` that `/` asks for. A literal divisor other than zero is one already, so `cents / 100` needs nothing; a divisor that is a value goes through `non_zero` and comes back a `Maybe`. `unwrap` gives back the plain number, for anyone implementing `Numeric` themselves. |
 | `Result` | Errors as values, no exceptions: `Ok(a)` / `Err(e)`, with `map`, `and_then`, `map_error`, `on_error`, `sequence`. |
 | `List` | Immutable lists: `map`, `filter`, `fold`, `zip`, `sort`, `length`, `range`, `head`, `tail`, `take`, `drop`, … |
 | `String` | Text: `length`, `reverse`, `split`, `trim`, `to_int`, `contains?`, `uncons`, `cons`, `from_char`, `map`. |
@@ -63,7 +64,8 @@ readable Ruby. This is a map of the territory; `jade q api` is the atlas.
 | `Clock` | Timestamps and monotonic timing: `Instant`, `now`. Sub-second precision; the bridge to wall-clock time. |
 | `Show` | Renders a value the way Jade writes it: `show(Just(7))` is `"Just(7)"`, `show(Point(3, 4))` is `"Point { x: 3, y: 4 }"`. Instances for the primitives; derives for unions, structs, records and lists. A function shows as `<function>`, and `Never` raises — it has no values. |
 | `Debug` | `log(label, value)` prints `label: value` to stderr and returns the value untouched, so it drops into a pipeline. Unconstrained, unlike `Show`. |
-| `Decimal` | Exact base-10 decimals (`coefficient * 10 ^ exponent`) — money and rates without `Float` rounding. Opaque; build with `of` / `scaled` / `parse`. Arithmetic via `Numeric` (`+` `-` `*` `/`), plus `div` (scaled, half-up), `round`, `to_i`, `to_float`. JSON-encodes to a `<mantissa>e<exponent>` string. |
+| `Decimal` | Exact base-10 decimals (`coefficient * 10 ^ exponent`) — money and rates without `Float` rounding. Opaque; build with `of` / `scaled` / `parse`. Arithmetic via `Numeric` (`+` `-` `*` `/`), plus `div` (scaled, half-up, taking a `NonZero`), `round`, `to_i`, `to_float`. JSON-encodes to a `<mantissa>e<exponent>` string. |
+| `Range` | An inclusive span over any `Comparable`, open at either end or both. Opaque; build with `a..b` or `between` / `from` / `to` / `empty` / `all`, where `between` reads a descending pair as `empty` rather than as a range. Ask with `contains?`, `overlaps?`, `intersect`, `clamp`, `lower`, `upper`, `bounded?`, `empty?`. Not the same thing as a range pattern: `in 0..3` is checked for coverage when the code is compiled, and a `Range` is a value. |
 
 Stdlib operations compile inline rather than through a runtime dispatch layer,
 so the generated Ruby calls the underlying operation directly.