jade-lang 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cb9527b610f268fc9ae7d784abcbf41018cf99f91b0bdaea462a655a8f12bfb
-  data.tar.gz: d888ed1e08771d41147879b5576c0b894f94795af1e4f849f6ca31044661366b
+  metadata.gz: ec12f8f9ca54c6ac59b3d8d521a9ad192eb87dd5a2a5e62620f3abe00b636cee
+  data.tar.gz: 940c0c3e78b8dcbd013050b298508323e5c0f60f8ddcb4749ede2416b14d9e16
 SHA512:
-  metadata.gz: 95f7b32d5542bb1d386d18a7e1e8749de7a7f5c6ecfffaacee351dcb0d4205d698269954fe4fc023f2fed3cc7fe9f32c0f6344f9415770916ea6237be3f16e8f
-  data.tar.gz: 897851f20e95afe86c92a7c4fe104299b46a4239644f06ea26c5580f5d47660834560e5c218336efc3d569f56e5754b8c68e45b1e68524166d347bdf5d178bb6
+  metadata.gz: e2f05e1f66e7b893e547a2ccb4d31a9678705daecd35c4c806a94f65c47444ad8b69b334c14b18a3a67417963870debdc4f28530ac334c0106699ee278c1f199
+  data.tar.gz: 5711c4a232e7728699e89ddcf168e7dc5b1b86913e34579c7b0b1b2d3df6e069f2f4a12aeb35a800619fdb945169c142a2434f322ce582b1415c524259ab2646

data/AGENTS.md

@@ -0,0 +1,164 @@
+# Writing Jade
+
+Idiom and gotchas. This file is deliberately not a function list — that's
+what `jade q api` is for, and a copy here would rot.
+
+## Ask the compiler, not the source
+
+| Question | Command |
+|---|---|
+| Does this function exist? What does it take? | `jade q api List` / `jade q api List.fold` |
+| Which module has a `fold`? | `jade q find fold` |
+| How is a lambda / `implements` block written? | `jade q syntax lambda` |
+| Did what I just wrote compile? | `jade check path/to/file.jd` |
+
+**Grepping the stdlib does not work, and fails quietly.** Stdlib modules are
+written two ways — Jade in a heredoc (`Maybe`, `Result`, `Decimal`) and a Ruby
+DSL (`List`, `String`, `Dict`, `Decode`) — so half of them never spell `def`,
+and none contains the string `List.map` you would search for. Extension
+modules (`Sql.*`) live in a gem that isn't in the tree at all. A grep that
+comes back empty tells you nothing.
+
+Inside a project, `jade q api` covers the stdlib, your own modules, and any
+extension gem's, each tagged with an `origin`.
+
+## Reach for the combinator
+
+A `case` that just unwraps and rewraps is the long way round.
+
+| Instead of | Write |
+|---|---|
+| `case m in Just(x) then f(x) in Nothing then Nothing end` | `Maybe.map(m, f)` |
+| `case m in Just(x) then x in Nothing then d end` | `Maybe.with_default(m, d)` |
+| `case m in Just(x) then f(x) in Nothing then Nothing end` where `f` returns `Maybe` | `Maybe.and_then(m, f)` |
+| `case r in Ok(x) then Ok(f(x)) in Err(e) then Err(e) end` | `Result.map(r, f)` |
+| `case r in Ok(x) then x in Err(_) then d end` | `Result.with_default(r, d)` |
+| a hand-written `==` | nothing — `Eq` derives |
+| a hand-written decoder for a struct | nothing — `Decode.from_json` derives it |
+
+These read best piped:
+
+```jade
+def label(m: Maybe(User)) -> String
+  m
+    |> Maybe.map((u) -> { u.name })
+    |> Maybe.with_default("anonymous")
+end
+```
+
+`case` earns its place when you're actually distinguishing variants — the
+`Result` arm that reports a different error, the union with five constructors.
+Write one `in` branch per variant rather than an `else` fallback; `else` is for
+matching literals, where exhaustiveness isn't available.
+
+**`map` changes the element type.** `Maybe.map : (Maybe(a), (a) -> b) ->
+Maybe(b)`. If you were told otherwise, that was hover, which reports a
+collapsed `(a) -> a` for the stdlib functions backing an interface — a known
+bug, see `~/vault/claude/jade/bugs/hover-collapses-stdlib-type-vars.md`.
+`jade q api` reads the declaration and is right.
+
+## Imports
+
+Auto-imported, no `import` needed: **`Basics`, `Maybe`, `Tuple`, `List`,
+`Char`, `String`, `Result`, `Task`, `Bytes`**.
+
+Everything else needs an explicit `import`: **`Dict`, `Set`, `Decode`,
+`Decode.Params`, `Encode`, `Calendar`, `Clock`, `Decimal`, `Show`, `Debug`**.
+`Show.show(x)` without `import Show` is "I cannot find a `Show.show`
+variable" — the function exists, the import doesn't.
+
+`import Dict` gets you the module. To name its *type* unqualified you have to
+ask for it:
+
+```jade
+import Dict exposing (Dict)      -- then: def go -> Dict(String, Int)
+import Dict                      -- then: def go -> Dict.Dict(String, Int)
+```
+
+**Zero-argument entries are values, not calls.** `Dict.empty`, `Decode.bool`,
+`Encode.null` — no parentheses. `Dict.empty()` is a compile error.
+
+## Interfaces
+
+The built-ins live in `Basics`: `Eq`, `Comparable`, `Appendable`, `Mappable`,
+`Chainable`, `Numeric`. Plus `Show` (in `Show`), `Decodable` (in `Decode`),
+`Encodable` (in `Encode`).
+
+Declare and implement:
+
+```jade
+interface Sized(a) with
+  size : a -> Int
+end
+
+
+implements Sized(Basket) with
+  size: (b) -> { List.length(b.items) }
+end
+```
+
+The right-hand side is an inline lambda or a function reference
+(`size: basket_size`).
+
+Two things to keep straight:
+
+- **The interface parameter is the constructor, not the applied type.**
+  `Mappable f` has `map : f(a), (a -> b) -> f(b)` — `f` is `Maybe`, not
+  `Maybe(a)`. Getting this wrong is why the impl target reads
+  `Mappable(Maybe(a))`.
+- **`jade q api` tells you what already has an instance.** `jade q api
+  Decode.Decodable` lists every implementing type under `implemented_by`;
+  a struct's entry lists what it `implements`. Check before writing one.
+
+### What derives, what doesn't
+
+Verified against the compiler:
+
+| | Structs / unions |
+|---|---|
+| `Eq` (`==`) | derives |
+| `Show` | derives |
+| `Encodable` / `Decodable` | derives |
+| `Comparable` (`<`, `List.sort`) | **does not derive** |
+
+`List.sort` on a list of structs is `No implementation of Basics.Comparable
+for Point`. Write the instance, or sort by a projection with
+`List.sort_by`.
+
+## Encoding and decoding
+
+`Encode.encode(value)` derives the encoder from the value's type;
+`Decode.from_json(json)` derives the decoder from the **return type**. A
+struct round-trips with neither written by hand:
+
+```jade
+def parse(json: String) -> Result(User, DecodeError)
+  Decode.from_json(json)
+end
+```
+
+Derivation reaches through structural types, so anything built from encodable
+parts is encodable: `List(a)`/`Set(a)` → array, `Maybe(a)` → the value or
+`null`, tuples → positional array, `Dict(k, v)` → array of `[k, v]` pairs (a
+JSON object only admits string keys), a struct → object keyed by field name, a
+union whose variants take no arguments → the variant name in snake_case.
+
+Outside that list — a union carrying arguments, say — write
+`implements Encodable(T)` / `Decodable(T)` yourself; nothing but you knows the
+shape it should take.
+
+Reach for the explicit combinators (`Decode.field`, `Decode.required`,
+`Decode.index`) when the JSON doesn't match the struct one-to-one. Use
+`Decode.Params` for PATCH-style input, where a missing field means "don't
+touch" rather than an error.
+
+Full treatment: [docs/json.md](docs/json.md).
+
+## Where else to look
+
+- [docs/syntax.md](docs/syntax.md) — the language, form by form.
+- [examples/](examples/) — nine files, compiled and asserted by
+  `spec/examples_spec.rb`, so they're verified idiom rather than samples that
+  drifted. `interfaces.jd` and `pattern_matching.jd` earn their keep.
+- [docs/interop.md](docs/interop.md) — the Ruby boundary, ports, `uses`.
+- [docs/stdlib.md](docs/stdlib.md) — what each module is for.

data/CHANGELOG.md

@@ -6,6 +6,183 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0]
+
+### Fixed
+
+- **A `Maybe` return encodes its element.** A function returning `Maybe(T)`
+  handed Ruby the internal `Data` object whenever `T` was a union, or a struct
+  holding one — no error, just an un-encoded value across the boundary. The
+  specialized encoder fell back to emitting the raw element when it couldn't
+  specialize it, instead of declining so the generic encoder could take over;
+  `decode`, five lines above it, already declined correctly. `Maybe(Int)` and
+  `Maybe(SomeStruct)` were unaffected, which is why it stayed hidden — identity
+  happens to be right for primitives. Both derived and hand-written
+  `Encodable` instances are now applied, and a `Maybe` field of a struct
+  unwraps the same way a `Maybe` return does.
+- **Boundary decode errors name the right side.** `DecodeError` reported
+  "Port returned a value that failed to decode" for every failure, including
+  values Ruby passed *into* an exposed function, where no port is involved —
+  sending you to look for a `uses` block that may not exist. Argument failures
+  now read "Ruby passed a value that failed to decode"; port returns are
+  unchanged.
+- **A symbol-keyed Hash says so.** Structs cross the boundary as a Hash with
+  string keys, so `Person.birthday(name: "Ada", age: 40)` used to fail with
+  `expected String, got null` — each field independently reading `nil`, naming
+  neither the cause nor the fix. It is now caught where the whole hash is in
+  scope, listing the offending keys and the correction. Hashes mixing string
+  and symbol keys are left alone; that is a real shape mismatch, and the
+  per-field errors describe it better than a guess would.
+- **A module declared under the wrong file name is now a compile error.** A
+  module is keyed by the name its file implies — imports resolve `Shop.Cart`
+  to `shop/cart.jd` and back — but nothing checked that against what the file
+  declared. `module Cart` in `orders.jd` compiled clean and emitted a `Cart`
+  module whose own type references pointed at `Orders`, so the first call
+  raised `NameError: uninitialized constant Cart::Internal::Orders` far from
+  the cause. It now fails at compile time, pointing at the declared name and
+  offering both the rename and the move.
+
+## [0.5.0]
+
+### Added
+
+- **`jade check [FILE...]`** type-checks and prints diagnostics without
+  generating anything — the same front end the language server runs, exiting 1
+  if there were errors. With no arguments it checks every `.jd` under the
+  source root. Closes the loop for editors, CI, and anything that just edited a
+  file and wants to know whether it invented a function.
+- **`jade q api [MODULE|NAME]`** and **`jade q find TERM`** report the public
+  surface of everything a module can call — signatures, interface constraints,
+  a struct's fields, a type's variants and what it implements, an interface and
+  what implements it — read out of the registry rather than the source. Source
+  is the wrong thing to read: stdlib modules are written two ways (Jade in a
+  heredoc, a Ruby DSL), so grepping `lib/jade/stdlib/` finds neither `List.map`
+  nor half the modules' functions at all, and an extension gem's modules aren't
+  in your tree to grep. Inside a project the listing spans the stdlib, the
+  project's own modules and any extension gem's, each tagged with its `origin`;
+  without a `jade.json` it falls back to the stdlib, so the query still answers
+  from any directory. A module that won't compile is reported under `skipped`
+  rather than silently missing.
+- **`jade q syntax [FORM]`** reports how a form is written — `lambda` is
+  `(args) -> { body }`, plus `def`, `type`, `struct`, `case`, `if`, `module`,
+  `import`, `interface`, `implements`, `uses`. Signatures answer "does this
+  function exist and what does it take", never "how is a lambda spelled", and
+  that second question has its own wrong answers. It serves the corpus the
+  editor already offers as completions, so the two can't drift; needs no
+  project and reads no files.
+
+- **`AGENTS.md`** — idiom and gotchas for writing Jade: reach for `Maybe.map` /
+  `with_default` over a `case` that only unwraps and rewraps, which stdlib
+  modules are auto-imported and which need an `import`, that zero-argument
+  entries are values and `Dict.empty()` is a compile error, what derives (`Eq`,
+  `Show`, `Encodable`, `Decodable`) and what doesn't (`Comparable`), and how
+  interfaces and encode/decode fit together. Deliberately not a function list —
+  that's `jade q api`, and a copy would rot. Every claim in it was checked
+  against the compiler.
+- The gem now ships `docs/` and `AGENTS.md`, so a project that installs
+  jade-lang gets them instead of README links pointing at nothing.
+
+### Changed
+
+- **Decoding a row returned from a port is roughly eight times cheaper.**
+  A derived decoder was a composition of combinators rebuilt and walked
+  for every row; a profile put 88% of the time inside the interpreter and
+  70 allocations on a four-field row. Deriving now emits one node
+  carrying every key, its decoder and the constructor, applied once
+  rather than curried through a closure per field; the interpreter
+  returns values unwrapped, with failures on a sentinel, so nothing
+  allocates a `Result` per node; and each descriptor decodes itself
+  instead of being matched out of a twenty-branch `case`. A four-field
+  row went 9.58 to 1.19 µs and 70 allocations to 5.
+- **`Decimal`, `Clock.Instant` and `Calendar.Date` read their text form
+  in Ruby** rather than parsing it through Jade-level combinators, which
+  cost a fresh decoder, two `Maybe`s and a tuple for every value. The
+  text forms are unchanged, so JSON output and existing ports are
+  unaffected. One input changes meaning: a trailing exponent marker
+  (`"825e-4e"`) used to read as `825e-4`, because splitting on every
+  `"e"` dropped the empty trailing piece, and is rejected now.
+- **Encoding a value back out to Ruby is cheaper by the same route.** A
+  derived record encoder built a pair per field and folded the list back
+  into a hash, with an intrinsic lookup for both per field per value; it
+  builds the hash directly. `Encodable(Instant)` writes its string in
+  Ruby next to the reader that parses it. Handing a four-field struct
+  back to a Ruby caller cost 2.26 µs/row over the internal form and now
+  costs 0.17 — what a caller waits for and what `Internal` measures have
+  converged.
+- **`Calendar.from_rata_die` is closed form.** It walked a year at a time
+  to find the year, then December backwards to find the month, allocating
+  a `Month` and a tuple per step through two twelve-branch `case`
+  statements. It is reached from `Clock.to_iso`, `Clock.on_date` and
+  `Calendar.add`, so this is not only an interop win — any Jade code
+  doing date arithmetic pays it.
+- The `case` completion snippet offers one `in` branch per variant instead of
+  an `else` fallback. `else` is for matching literals, where exhaustiveness
+  isn't available — not the default shape of a `case`.
+- **A missing qualified name now suggests the one you meant.** `List.fold_left`
+  answers ``help: did you mean `List.fold`?`` instead of a bare "not found" —
+  the candidates are the module's exposed values, so the suggestion is drawn
+  from what actually exists. Suggestions go through the alias the module was
+  imported under (`L.post`, not `Ledger.post`), since that's what the call site
+  can say. Local variables, types and constructors already did this;
+  module-qualified access was the gap.
+
+### Fixed
+
+- **Operator precedence was lost inside an infix chain's operands.**
+  `(1 + 2 * 3) + 0` was 9, `(10 - 4 / 2) + 0` was 3, and
+  `id(1 + 2 * 3) + 0` was 9. Shunting-yard ran on a chain's own operators
+  but treated every operand as an atom and returned it unfixed, so a
+  grouping, a call argument, a lambda body, a ternary branch or a record
+  value sitting in a chain kept the shape the parser built — left to
+  right, no precedence. Standing alone the same expression was fine,
+  which is why `1 + 2 * 3` and `(1 + 2 * 3)` both gave 7 and nothing
+  caught it. **This changes generated output for code that hit it**: a
+  project that commits generated artifacts and CI-checks them for drift
+  will see a diff, and the new bytes are the correct arithmetic.
+- **`Clock.on_date` reported the previous day for pre-1970 instants.**
+  `Clock.floor_div` subtracted one from the quotient for a negative
+  dividend with a remainder — the right correction when `/` truncates
+  toward zero, which Jade's doesn't; it already floors, so it floored
+  twice. `at_time` was unaffected, so `to_iso(-1)` read
+  `"1969-12-30T23:59:59Z"`: the time right, the date a day out. Exact
+  midnight was always correct, because the double correction only applies
+  when there is a remainder.
+- **Anonymous records decoded from the same shape now compare equal.**
+  The derived decoder built its constructor from a bare `Data.define`,
+  which mints a fresh class each time the decoder is built, so
+  `{ x: 1, y: "a" }` decoded twice compared false. It resolves through
+  the same interned registry record literals already used. Note this does
+  not unify decoded records with *literals* in the general case —
+  literals hoist to a per-module constant, so two modules with the same
+  shape still get different classes.
+- **The tuple decoders no longer build their constructor with
+  `Method#curry`.** A curried `Method` built once and called on every
+  decode corrupts the heap under GC compaction — a near-null "try to mark
+  T_NONE object" crash after enough rows. It is the pattern the
+  constructor-curry regression spec exists to prevent; that spec reads
+  generated code, so the stdlib's own copy was invisible to it.
+- **`Result.on_error` can change the error type**, as its signature has always
+  claimed. The `Ok` arm handed back the input rather than rebuilding it, which
+  unified the outgoing error type with the incoming one, so
+  `Result(Int, String) -> Result(Int, Int)` did not compile. Recovering into a
+  different error type is the reason the function takes `e -> Result(a, f)`.
+- **A signature no longer renders two distinct type variables as one.** Hover
+  reported `Maybe.map : (Maybe(a), (a) -> a) -> Maybe(a)` — a function unable
+  to change the element type, which is a different function from the one that
+  exists. Variables are identified by an id but print as a name, and nothing
+  upstream keeps names distinct; rendering now re-letters a clash instead of
+  emitting the same name twice. Declared names are kept where they don't
+  collide, so annotated signatures read as written.
+
+- **`docs/stdlib.md` named nine functions that don't exist.** `Char.is_digit`,
+  `is_alpha`, `is_alpha_num`, `is_upper`, `is_lower` were renamed to `digit?`,
+  `alpha?`, `alpha_numeric?`, `upper?`, `lower?` when predicates took the `?`
+  suffix and the doc never followed; `String.contains` is `contains?`,
+  `Dict.member` is `member?`, `Tuple.map_first` / `map_second` were never
+  implemented, and `Decode.at` doesn't exist (`Decode.index` does). Every
+  qualified name in `docs/stdlib.md` and `AGENTS.md` now checks out against the
+  registry.
+
 ## [0.4.0]
 
 ### Changed
@@ -187,7 +364,9 @@ Initial release.
 - `jade` CLI dispatcher: `fmt`, `lsp`, `q`.
 - Language server and headless query interface for editor/agent tooling.
 
-[Unreleased]: https://github.com/agustinrhcp/jade/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/agustinrhcp/jade/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/agustinrhcp/jade/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/agustinrhcp/jade/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/agustinrhcp/jade/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/agustinrhcp/jade/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/agustinrhcp/jade/compare/v0.2.0...v0.3.0

data/README.md

@@ -333,7 +333,9 @@ Worst case: you wrote Ruby with a nicer authoring layer for a while.
 
 There's a language server — type errors, inferred types, and jump-to-definition
 in any editor that speaks LSP. For tools that don't, `jade q` answers the same
-questions as one-shot JSON (hover, definition, references, symbols).
+questions as one-shot JSON (hover, definition, references, symbols), `jade q
+api` reports the stdlib's signatures, and `jade check` type-checks a file and
+prints what's wrong.
 
 In our experience coding agents like Claude Code and Cursor handle Jade well:
 the syntax is close enough to the ML family (Elm, OCaml, Haskell) that models
@@ -346,9 +348,11 @@ for us so far.
 A single `jade` binary fronts the toolchain:
 
 ```
+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)
 jade q hover FILE:L:C     # headless JSON queries — hover/symbols/defn/refs
+jade q api List.fold      # stdlib signatures, read from the registry
 ```
 
 `jade fmt` is deterministic and idempotent; wire it into your editor or a

data/docs/interop.md

@@ -0,0 +1,208 @@
+# Interop with Ruby
+
+Jade has no implicit side effects. All interaction with the outside world goes
+through `uses` blocks, and every port returns a `Task`.
+
+## Declaring a port
+
+The `uses` block declares the boundary types; the names come into scope
+unqualified. **Declarations are separated by commas** — a newline alone ends
+the block, so a second entry without a comma before it reads as a parse error
+(`Unexpected token "entries", expected end`).
+
+A port takes as many arguments as its type says: `A, B -> Task(…)` is a
+two-argument port, called `entries(key, limit)`. Parenthesising the arguments
+means something else — `(A, B) -> Task(…)` is a *one*-argument port taking a
+tuple, called `entries((key, limit))`.
+
+```jade
+module Store exposing (page)
+
+uses KeyValue with
+  members : String -> Task(List(String), String),
+  entries : String, Int -> Task(List(String), String)
+end
+
+
+def page(key: String) -> Task(List(String), String)
+  entries(key, 20)
+end
+```
+
+On the Ruby side, register the port with `Jade::Port`. The block receives a
+helper `t` for `t.ok(value)` / `t.err(error)`, then one parameter per declared
+argument:
+
+```ruby
+module KeyValue
+  extend Jade::Port
+
+  task :members do |t, key|
+    t.ok(REDIS.smembers(key))
+  end
+
+  task :entries do |t, key, limit|
+    t.ok(REDIS.lrange(key, 0, limit - 1))
+  end
+end
+```
+
+The block must return `t.ok(value)` or `t.err(error)` — never another `Task`.
+Composition (`map`, `and_then`, `sequence`) lives in Jade. (Pick a port module
+name that doesn't shadow a Ruby constant you rely on — `task :members` defines
+`KeyValue.members`.)
+
+## What crosses the boundary
+
+A port is the same boundary as a Jade function called from Ruby, pointed the
+other way, and it converts in both directions: **arguments are encoded on the
+way out, and the return value is decoded on the way back**. Ruby sees wire
+values — strings, numbers, hashes, arrays — never Jade's internal
+representation.
+
+```jade
+uses Scheduling with
+  shift_months : Instant, Int -> Task(Instant, Never)
+end
+```
+
+```ruby
+module Scheduling
+  extend Jade::Port
+
+  task :shift_months do |t, iso, months|
+    # iso is "2026-08-01T12:00:00Z", not a Jade::Clock::Instant
+    t.ok(Time.iso8601(iso).then { |at| (at << -months).iso8601 })
+  end
+end
+```
+
+Every argument type therefore needs an `Encodable` instance, the same way every
+`Task` arm needs a `Decodable` one. A type with neither is a compile error
+naming the argument:
+
+```
+Port `shift_months` cannot encode argument 1 (`Shape`): no Encodable instance
+```
+
+Declare the argument as `Decode.Value` to opt out and hand Ruby the value
+untouched — the arg-side counterpart of a `Decode.Value` return arm. `Value` has
+instances on both sides, so the opt-out holds when it's nested too: a
+`List(Value)` argument, or a struct with a `Value` field, crosses element by
+element with each one left alone.
+
+## Calling Jade from Ruby
+
+An exposed function gets two callable forms:
+
+```ruby
+# Boundary form — args decoded, return encoded, Task runs eagerly
+Store.page("recent")     # => ["ok", ["a", "b"]]
+Store.page!("recent")    # => ["a", "b"]   (bang form unwraps, raises on err)
+
+# Internal form — keeps the Task as a value you can compose
+task = Store::Internal.page("recent")
+task.run                 # => Jade::Result::Ok[["a", "b"]]
+```
+
+At the boundary, Ruby values are **decoded into Jade values** on the way in and
+**encoded back to Ruby** on the way out. For `Task` functions the ok-arm decoder
+runs against whatever the port returned, so a signature like `Task(User, String)`
+keeps its declared error type — you don't thread a separate `DecodeError`
+through every call.
+
+## When a function is callable from Ruby
+
+The unit here is the **function**, not the type. A function is exposed to Ruby
+only when **all of its parameters are `Decodable` and its return type is
+`Encodable`**. If any parameter can't be decoded, or the return can't be
+encoded, that whole function isn't exposed — it compiles fine and its `Internal`
+form still works, but calling the public `Module.fn` from plain Ruby raises
+`Jade::Interop::NotExposed`. The error names the part that disqualified it
+(e.g. `argument 1 of type Shape has no Decodable instance`).
+
+What takes a function out of Ruby's reach is a parameter or return type with no
+`Decodable` / `Encodable` instance — a function value, an unbound type variable,
+or a custom union you haven't given an instance.
+
+If a port returns something that doesn't decode to the declared type, the
+boundary raises `Jade::Interop::DecodeError`. This is on purpose: a port
+returning the wrong shape is a programming bug, not a runtime condition to
+recover from, so the boundary raises rather than pass on a malformed value.
+
+```jade
+module Users exposing (fetch)
+
+struct User = {
+  id: Int,
+  name: String
+}
+
+
+uses Backend with
+  raw_fetch : Int -> Task(User, String)
+end
+
+
+def fetch(id: Int) -> Task(User, String)
+  raw_fetch(id)
+end
+```
+
+```ruby
+module Backend
+  extend Jade::Port
+
+  task :raw_fetch do |t, id|
+    t.ok({ name: "Paul" })   # oops — missing :id
+  end
+end
+
+Users.fetch(1)
+# => raises Jade::Interop::DecodeError:
+#    Port returned a value that failed to decode at value: missing field `id` ({name: "Paul"})
+```
+
+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.
+
+## What the compiled boundary looks like
+
+For a function with a primitive argument:
+
+```jade
+module Sample exposing (absolute)
+
+def absolute(n: Int) -> Int
+  n < 0 ? 0 - n : n
+end
+```
+
+the compiler emits:
+
+```ruby
+module Sample
+  extend self
+
+  module Internal
+    extend self
+
+    def absolute(n)
+      if ((n < 0))
+        (0 - n)
+      else
+        n
+      end
+    end
+  end
+
+  def self.absolute(n)
+    Internal.absolute(Jade::Interop::Boundary.integer("Int", n))
+  end
+end
+```
+
+Two surface methods — `Internal.absolute` (pure) and `self.absolute` (the
+boundary). `Int` has a specialized fast-path coercion; richer types decode
+through cached `Decode` constants instead. Either way the boundary work is
+visible in the file, not hidden inside a runtime hook.