jade-sql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5b511ba76f20947fbccd7ebb7800746ca4ff7deaa7db27f02c0f9e0c2063fa5
+  data.tar.gz: 4f280996410b7a415c14ce431879074d3ea14db4da9305358595738a8f31f674
+SHA512:
+  metadata.gz: df9d4acfa3ac509e4a9730a727befae3197cdd9abb9959c60d107191fb574898e1d75ca23eb7814ab5a6b80a81b0e7e5e2d2131954a47053726c0a1e3354e720
+  data.tar.gz: 582f7bcacd1543c00d6efc7710762fe1b6b9a388c8e71c2fedaf006229d3ac7bce49510473e8ae3b97773314c6ead9445b5f38c8d6aeb678cfbc6c573adae763

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agustin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+# jade-sql
+
+Type-safe SQL for Jade. Builds queries and mutations from a generated
+schema, renders them to `(String, List(Value))`, and runs them against
+ActiveRecord via a Task port that auto-decodes rows into typed Jade
+structs.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'jade-sql'
+```
+
+Its dependency, the `jade-lang` gem (the Jade compiler/runtime), resolves
+from RubyGems automatically.
+
+To execute queries at runtime, opt into the AR-backed task port:
+
+```ruby
+# config/initializers/jade_sql.rb (or similar)
+require 'jade-sql/runtime'
+```
+
+To get the rake task for schema generation:
+
+```ruby
+# Rakefile (or lib/tasks/jade.rake)
+load Gem.find_files('jade-sql/tasks.rake').first
+```
+
+## At a glance
+
+Generate a typed schema from `db/structure.sql`, then build a query against
+it. The result is a `Q` you render with `to_sql` or run with `fetch_*`; rows
+decode straight into your struct.
+
+```jade
+import Sql exposing (Selector, eq, to_expr)
+import Sql.Query exposing (Q, field, from, join, select, where)
+import Schema exposing (patients, appointments)
+
+struct Visit = {
+  name: String,
+  reason: String
+}
+
+def scheduled_visits -> Q(Selector(Visit))
+  p <- from(patients)
+  a <- join(appointments, (a) -> { p.id |> eq(a.patient_id) })
+
+  select(Visit(_, _))
+    |> field(p.name)
+    |> field(a.reason)
+    |> where(a.status |> eq(to_expr("scheduled")))
+end
+```
+
+Run it with `scheduled_visits |> fetch_many` — a `Task(List(Visit), SqlError)`
+that decodes each row into `Visit`.
+
+## Documentation
+
+- [Building SQL](docs/building.md) — generate a schema, build queries
+  (joins, sorting/grouping, pagination, aggregates, arrays, JSONB) and
+  mutations (insert/update/delete, RETURNING, timestamps, UUIDs).
+- [Running queries and mutations](docs/running.md) — `fetch_*` / `execute`,
+  transactions, and testing without a database.

data/docs/building.md

@@ -0,0 +1,491 @@
+# Building SQL
+
+Generate a typed schema from your database, then build queries and
+mutations against it. To run what you build, see [running.md](running.md).
+
+## Generate `schema.jd` from `db/structure.sql`
+
+```bash
+bundle exec rake jade:schema
+```
+
+Reads `db/structure.sql`, writes `app/jade/schema.jd`. Knobs:
+
+| ENV     | Default              | What                                      |
+|---------|----------------------|-------------------------------------------|
+| INPUT   | `db/structure.sql`   | source DDL file                           |
+| OUTPUT  | `app/jade/schema.jd` | destination                               |
+| TABLES  | (all)                | comma-separated whitelist                 |
+| MODULE  | `Schema`             | module name in the generated file         |
+
+Multiple schemas in one app (e.g. for gradual migration):
+
+```bash
+bundle exec rake jade:schema \
+  TABLES=invoices,charges \
+  MODULE=Schema.Billing \
+  OUTPUT=app/jade/schema/billing.jd
+```
+
+Type map: `bigint`/`integer`/`smallint` → `Int`, `varchar`/`text`/`char` →
+`String`, `boolean` → `Bool`, `jsonb`/`json` → `Decode.Value`, `date` →
+`Calendar.Date`, `timestamp` → `Clock.Instant`, `uuid` → `Uuid` (from
+`Sql.Uuid`). Unknown types fail loudly with the table+column name.
+`bytea` and `decimal`/`numeric` aren't wired into the type map yet —
+`bytea` has a natural target in jade's `Bytes`, and a decimal can be
+modeled as a struct of `Int`s.
+
+For each table, the generator emits:
+
+```jade
+struct PatientsCols      = { id: Expr(Int), name: Expr(String), ... }
+struct MaybePatientsCols = { id: Expr(Maybe(Int)), name: Expr(Maybe(String)), ... }
+struct PatientsRow       = { id: Int, name: String, ... }
+
+def patients -> Table(PatientsCols, MaybePatientsCols)
+  table("patients", "patients", ..., ["id"])
+end
+```
+
+Strict cols mirror NOT NULL constraints; the maybe version wraps every
+field in `Maybe` for left-join projections. The default alias is the
+table name; override per-call with `aliased` (see joins below).
+
+## Build queries
+
+```jade
+import Sql exposing (Selector, eq, to_expr)
+import Sql.Query exposing (Q, field, from, join, select, where)
+import Schema exposing (patients, appointments)
+
+struct Visit = {
+  name: String,
+  reason: String
+}
+
+def scheduled_visits -> Q(Selector(Visit))
+  p <- from(patients)
+  a <- join(appointments, (a) -> { p.id |> eq(a.patient_id) })
+
+  select(Visit(_, _))
+    |> field(p.name)
+    |> field(a.reason)
+    |> where(a.status |> eq(to_expr("scheduled")))
+end
+```
+
+Notes:
+- `<-` is bind-chain — exposes each joined table's columns to the rest of
+  the chain. `p` and `a` are the projected column accessors.
+- `select(Visit(_, _))` uses placeholders. Each subsequent `field(...)`
+  fills one slot in declared order.
+- `to_sql(q)` returns `(String, List(Value))`.
+
+### Sorting and grouping
+
+`order(q, e)` appends an ASC term, `order_desc(q, e)` a DESC term, and
+`group(q, e)` a GROUP BY column. Repeated calls accumulate in declared
+order — e.g. counting visits per patient, busiest first:
+
+```jade
+import Sql exposing (column, count_all)
+import Sql.Query exposing (group, order, order_desc)
+
+struct VisitCount = {
+  name: String,
+  visits: Int
+}
+
+def visit_counts -> Q(Selector(VisitCount))
+  p <- from(patients)
+  a <- join(appointments, (a) -> { p.id |> eq(a.patient_id) })
+
+  select(VisitCount(_, _))
+    |> field(p.name)
+    |> field(count_all)
+    |> group(column("p", "name"))
+    |> order_desc(count_all)
+    |> order(column("p", "name"))
+end
+# ... GROUP BY p.name ORDER BY COUNT(*) DESC, p.name
+```
+
+`HAVING` and `CASE` aren't built in yet — for filtering aggregates or
+conditional expressions, fall back to the raw-SQL escape hatch
+(`execute_*`). Basic aggregates (`SUM`, `COUNT`) and the
+null-handling primitive (`coalesce`) are typed; see *Aggregates,
+COALESCE* below.
+
+### Pagination
+
+`limit(q, n)` and `offset(q, n)` append `LIMIT`/`OFFSET` clauses. Both
+take a plain `Int` and render inline (not as parameters), so the
+returned `List(Value)` is unaffected:
+
+```jade
+import Sql.Query exposing(limit, offset)
+
+def page(n: Int) -> Q(Selector(Visit))
+  scheduled_visits
+    |> limit(20)
+    |> offset(n * 20)
+end
+```
+
+Calling `limit`/`offset` more than once overrides the previous value
+(last call wins).
+
+### Self-joins
+
+The schema's default alias = table name. Override with `aliased`:
+
+```jade
+p <- from(patients)
+c <- patients |> aliased("c") |> join((c) -> { p.id |> eq(c.parent_id) })
+```
+
+### Left joins with nullable views
+
+`left_join` switches the joined table to its maybe-column view:
+
+```jade
+p <- from(patients)
+a <- left_join(appointments, (a) -> { p.id |> eq(a.patient_id) })
+# `a` is MaybeAppointmentsCols; field types are Expr(Maybe(String)) etc.
+```
+
+For predicates that lift a non-null column into the nullable side,
+`nullable`:
+
+```jade
+p.id |> nullable |> eq(a.patient_id)  # Expr(Int) → Expr(Maybe(Int))
+```
+
+### Phantom-type rewrap with `cast`
+
+`cast(e: Expr(a)) -> Expr(b)` widens a column's phantom type — useful
+for projecting a `VARCHAR` column into a typed enum field whose
+`Decodable(b)` instance does the actual parsing at row decode:
+
+```jade
+struct Appointment = { id: Int, status: Status, ... }
+
+# status column is VARCHAR; Status has a Decodable(Status) impl that parses
+# "scheduled" / "completed" into the variants.
+select(Appointment(_, _, ...))
+  |> field(a.id)
+  |> field(a.status |> cast)   # Expr(String) → Expr(Status)
+```
+
+Same shape as `nullable` — pure phantom-type rewrap, no runtime
+transformation. The runtime decoder (`Decodable(Status)`) is what
+actually converts the column value; `cast` just teaches the SQL
+builder that the projection is intended. If `Decodable(b)` can't
+parse the column's actual values, the failure surfaces at row
+decode time, not at type check.
+
+### Aggregates, COALESCE
+
+A small typed surface for SQL functions that would otherwise force you
+into hand-built `Expr` strings. All compose with the rest of the
+builder — params stitch in declaration order automatically.
+
+| Function                                       | SQL                | Notes                                  |
+|------------------------------------------------|--------------------|----------------------------------------|
+| `sum(Expr(Int)) -> Expr(Maybe(Int))`           | `SUM(e)`           | `NULL` on empty group → `Maybe`.       |
+| `count(Expr(a)) -> Expr(Int)`                  | `COUNT(e)`         | Counts non-null rows for the column.   |
+| `count_all -> Expr(Int)`                       | `COUNT(*)`         | Total row count.                       |
+| `coalesce(Expr(Maybe(a)), Expr(a)) -> Expr(a)` | `COALESCE(e, def)` | Drops the `Maybe` with a fallback.     |
+| `neg(Expr(Int)) -> Expr(Int)`                  | `-(e)`             | Unary minus.                           |
+
+Worked example — count visits and the most recent visit number,
+coalesced to 0 when a patient has none:
+
+```jade
+import Sql exposing (coalesce, column, count_all, sum, to_expr)
+
+select(Totals(_, _))
+  |> field(count_all)
+  |> field(coalesce(sum(column("a", "visit_no")), to_expr(0)))
+# SELECT COUNT(*), COALESCE(SUM(a.visit_no), ?)
+```
+
+For `CASE WHEN`, `HAVING`, and arithmetic, fall back to the raw-`Expr`
+escape hatch until they get a typed builder.
+
+### Postgres arrays
+
+Typed predicates on `text[]` / `int[]` / `uuid[]` columns. All bind
+the array as a single param (`$1`) — `pg` maps Ruby `Array` to a PG
+array natively, and PG infers the element type from the column on
+the other side of the operator. No `ARRAY[$1,...,$N]` expansion, no
+`ARRAY[]::t[]` cast needed for empty inputs.
+
+| Function                                                       | SQL                          |
+|----------------------------------------------------------------|------------------------------|
+| `array_overlaps(Expr(List(a)), List(a)) -> Expr(Bool)`         | `col && ?` (any-of)          |
+| `array_has(Expr(List(a)), a) -> Expr(Bool)`                    | `? = ANY(col)` (membership)  |
+| `array_contains(Expr(List(a)), List(a)) -> Expr(Bool)`         | `col @> ?` (all-of)          |
+| `array_contained_by(Expr(List(a)), List(a)) -> Expr(Bool)`     | `col <@ ?` (subset)          |
+| `array_length(Expr(List(a))) -> Expr(Int)`                     | `cardinality(col)`           |
+
+Example — filter appointments whose tag set overlaps any selected chip:
+
+```jade
+import Sql exposing (array_overlaps, column)
+
+def filter_by_tags(selected: List(String)) -> Expr(Bool)
+  array_overlaps(column("a", "tags"), selected)
+end
+# WHERE a.tags && ?    (param: ["urgent","followup"])
+```
+
+`array_length` uses `cardinality(col)` rather than Postgres'
+`array_length(col, 1)` because `cardinality` is non-null (returns 0
+on empty). Filter untagged rows with
+`array_length(column("a", "tags")) |> eq(to_expr(0))`.
+
+Mutation ops for partial array updates:
+
+| Function                                                            | SQL                          |
+|---------------------------------------------------------------------|------------------------------|
+| `array_append(Expr(List(a)), a) -> Expr(List(a))`                   | `array_append(col, ?)`       |
+| `array_remove(Expr(List(a)), a) -> Expr(List(a))`                   | `array_remove(col, ?)`       |
+| `array_concat(Expr(List(a)), Expr(List(a))) -> Expr(List(a))`       | `left ‖ right`               |
+
+Use these in `update_all` to avoid rewriting an array column wholesale:
+
+```jade
+appointments
+  |> update_all(
+       (a) -> { a.id |> eq(to_expr(aid)) },
+       (a) -> { [a.tags |> set_(array_append(a.tags, new_tag))] },
+     )
+# UPDATE appointments SET tags = array_append(tags, ?) WHERE id = ?
+```
+
+Out of scope: `unnest`, `array_agg`. Add when a caller hits them.
+
+### JSONB predicates
+
+| Function                                                  | SQL                |
+|-----------------------------------------------------------|--------------------|
+| `jsonb_contains(Expr(Value), a) -> Expr(Bool)`            | `col @> ?`         |
+| `jsonb_path_exists(Expr(Value), String) -> Expr(Bool)`    | `col @? ?::jsonpath` |
+
+`jsonb_contains` auto-encodes the value via its `Encodable` instance,
+so you can pass any record / scalar / list directly:
+
+```jade
+import Sql exposing (column, jsonb_contains, jsonb_path_exists)
+
+struct KindMatch = { kind: String }
+
+# WHERE r.meta @> ?       (param: { "kind": "referral" })
+def matches_kind(k: String) -> Expr(Bool)
+  jsonb_contains(column("r", "meta"), KindMatch(k))
+end
+
+# WHERE r.meta @? ?::jsonpath   (param: "$.priority ? (@ > 1)")
+def has_priority_gt(path: String) -> Expr(Bool)
+  jsonb_path_exists(column("r", "meta"), path)
+end
+```
+
+The `@?` operator requires `jsonpath` on the right; the param binds as
+text and gets cast at the SQL level.
+
+## Build mutations
+
+Define codec interfaces for your domain type:
+
+```jade
+import Sql exposing(Assignment, SqlMapper, Identified, assign)
+import Encode exposing(encode)
+import Decode exposing(Value)
+
+struct Patient = { id: Int, name: String, mrn: String }
+
+implements SqlMapper(Patient) with
+  to_assigns: encode_patient
+end
+
+implements Identified(Patient) with
+  pk_values: encode_patient_pk
+end
+
+def encode_patient(p: Patient) -> List(Assignment)
+  [
+    assign("name", p.name),
+    assign("mrn",  p.mrn)
+  ]
+end
+
+def encode_patient_pk(p: Patient) -> List(Value)
+  [encode(p.id)]
+end
+```
+
+`assign(col, value)` is shorthand for
+`Assignment(col, "?", [encode(value)])`. For non-`?` placeholders
+(e.g. `"visit_no + ?"` for increments) use the `Assignment(...)`
+constructor directly.
+
+Then the mutation API works on values directly:
+
+```jade
+import Sql.Mutation exposing(insert, update, delete, insert_all, update_all, delete_all, to_sql)
+
+p |> insert(patients) |> to_sql        # INSERT INTO patients (name, mrn) VALUES (?, ?)
+p |> update(patients) |> to_sql        # UPDATE patients SET name = ?, mrn = ? WHERE id = ?
+p |> delete(patients) |> to_sql        # DELETE FROM patients WHERE id = ?
+
+[p1, p2] |> insert_all(patients) |> to_sql
+
+appointments
+|> update_all((a) -> { a.status |> eq(to_expr("scheduled")) },
+              (a) -> { [a.cancelled |> set_(to_expr(True))] })
+|> to_sql
+
+appointments
+|> delete_all((a) -> { a.cancelled |> eq(to_expr(True)) })
+|> to_sql
+```
+
+### RETURNING
+
+`returning` is the mutation-side counterpart to `select` for queries.
+It takes a closure that receives the table's column accessors and
+builds a Q-wrapped selector projecting them into a target type. The
+Q wrapper is just to share the same `select`/`field` builders as
+queries — `returning` extracts the inner `Selector` and discards the
+empty Q state.
+
+```jade
+import Sql exposing(Selector)
+import Sql.Query exposing(select, field)
+import Sql.Mutation exposing(insert, returning, to_sql)
+
+# INSERT INTO patients (name, mrn) VALUES (?, ?) RETURNING id, name, mrn
+np
+|> insert(patients)
+|> returning((p) -> {
+  select(Patient(_, _, _))
+  |> field(p.id)
+  |> field(p.name)
+  |> field(p.mrn)
+})
+|> to_sql                    # or |> fetch_one to run
+```
+
+Bonus: the projector can be defined once and shared between SELECT
+queries and RETURNING — both contexts now take the same `cols ->
+Q(Selector(target))` shape, so a single `def patient_projector(p)`
+works for `from(patients) |> patient_projector` (query) and
+`... |> returning(patient_projector)` (RETURNING).
+
+Combined with `Sql.fetch_one`, the inserted row decodes into the
+target struct:
+
+```jade
+def create(np: NewPatient) -> Task(Patient, SqlError)
+  np |> insert(patients) |> returning((p) -> {
+    select(Patient(_, _, _))
+    |> field(p.id)
+    |> field(p.name)
+    |> field(p.mrn)
+  })
+  |> fetch_one
+end
+```
+
+`insert` / `update` / `delete` need `SqlMapper(a)` + `Identified(a)`.
+`insert_all` needs only `SqlMapper`. `update_all`/`delete_all` build
+the SET / WHERE clauses directly from the column accessors — no codec.
+
+`SqlMapper` is also implemented for `List(Assignment)` itself, so you
+can pass an assignment list to `insert` directly when you've already
+built it (e.g. from a sparse changeset):
+
+```jade
+sparse_changes
+|> List.and_then(field_to_assigns)
+|> insert(_, patients)
+```
+
+### Timestamps
+
+`Mutation.insert`/`update` emit only the columns you explicitly set —
+they don't auto-fill `created_at` / `updated_at`. Two ways to handle
+NOT NULL timestamp columns:
+
+**1. DB-side defaults (recommended).** Let the schema own timestamp
+policy:
+
+```sql
+ALTER TABLE patients ALTER COLUMN created_at SET DEFAULT now();
+ALTER TABLE patients ALTER COLUMN updated_at SET DEFAULT now();
+```
+
+The mutation builder stays a thin SQL emitter; the DB fills in
+defaults for any column the INSERT didn't list.
+
+**2. Explicit injection in app code.** When you want Jade to carry the
+timestamp values (Rails-style), tack assignments onto the list before
+the call:
+
+```jade
+def with_timestamps(assigns: List(Assignment), now: Instant)
+    -> List(Assignment)
+  assigns ++ [assign("created_at", now), assign("updated_at", now)]
+end
+
+def create(p: Patient, now: Instant) -> Mutation(Int, PatientsCols)
+  encode_patient(p)
+    |> with_timestamps(now)
+    |> insert(_, patients)
+end
+```
+
+### UUIDs
+
+`Sql.Uuid` defines an opaque `Uuid` type plus generation/parse helpers.
+The schema generator emits `Uuid` for `uuid` columns:
+
+```jade
+import Sql.Uuid exposing (Uuid, v4, v7, parse, to_string)
+
+# DB-side generation (recommended for PKs):
+# ALTER TABLE patients ALTER COLUMN id SET DEFAULT gen_random_uuid();
+
+# App-side generation (idempotency keys, child-row pre-linking, …):
+def make_request_id -> Task(Uuid, Never)
+  v7    # time-ordered, friendlier to DB index locality than v4
+end
+```
+
+`v4` and `v7` are zero-arg Tasks (`def v4 -> Task(Uuid, Never)`); call
+them without parens. `parse(String) -> Maybe(Uuid)` accepts the
+canonical 8-4-4-4-12 form (case-insensitive, stored lowercase).
+`to_string(Uuid) -> String` for the canonical text form.
+
+`Encodable(Uuid)` and `Decodable(Uuid)` impls are in the module, so
+Uuids flow through SQL params, RETURNING decoding, and JSON boundaries
+without extra wiring.
+
+#### Short (Base64) display form
+
+The canonical 36-char form is too noisy for URLs / admin UIs / logs.
+`to_b64` / `from_b64` round-trip a Uuid through 22-char url-safe
+Base64 (no padding), preserving the v7 time-ordering:
+
+```jade
+import Sql.Uuid exposing (to_b64, from_b64)
+
+to_b64(u)                              # "VQ6EAOKbQdSnFkRmVUQAAA"
+from_b64("VQ6EAOKbQdSnFkRmVUQAAA")     # Just(u)
+from_b64("nope")                       # Nothing
+```
+
+`from_b64` returns `Nothing` for non-base64 input or for valid base64
+that decodes to a length other than 16 bytes.

data/docs/running.md

@@ -0,0 +1,103 @@
+# Running queries and mutations
+
+`Sql` exposes `fetch_one` / `fetch_many` for reads and `execute` for
+writes — all polymorphic over anything `Renderable` (Q, Mutation, …) —
+plus `*_raw` siblings that take a `(String, List(Value))` pair for the
+escape hatch:
+
+```jade
+import Sql exposing (SqlError, execute, execute_raw, fetch_many, fetch_one)
+
+# Affected count for INSERT/UPDATE/DELETE
+def reschedule(a: Appointment) -> Task(Int, SqlError)
+  a |> update(appointments) |> execute
+end
+
+# A single row, decoded into Patient
+def find(id: Int) -> Task(Patient, SqlError)
+  patient_by_id_query(id) |> fetch_one
+end
+
+# Many rows, decoded
+def all -> Task(List(Patient), SqlError)
+  all_patients_query |> fetch_many
+end
+
+# Raw SQL escape hatch — bypass the typed builders
+def count_active -> Task(Int, SqlError)
+  execute_raw(("SELECT COUNT(*) FROM patients WHERE archived = ?", [Encode.encode(False)]))
+end
+```
+
+`fetch_one` / `fetch_many` / `execute` accept anything that implements
+`Sql.Renderable` (Q, Mutation). Internally they call `render(r) |> *_raw`,
+where `render` is the interface method that resolves to each container's
+`to_sql`. For raw SQL, skip the builder and call `fetch_one_raw` /
+`fetch_many_raw` / `execute_raw` directly with a `(String, List(Value))`
+pair.
+
+Row decoding is automatic — the caller's type (`Patient`, `List(Patient)`)
+threads its `Decodable` instance into the polymorphic port. The runtime
+returns plain Ruby hashes from AR, and they're decoded into typed structs
+at the boundary.
+
+`SqlError` variants:
+- `DbError(String)` — AR `StatementInvalid` message
+- `NotFound` — `fetch_one` with zero rows
+- `NotUnique` — `fetch_one` with more than one row
+
+A decode mismatch (column type doesn't match the field type) raises on
+the Ruby side rather than becoming a recoverable error — schema drift is
+a programmer bug.
+
+## Transactions
+
+`Sql.transaction` runs a `Task` inside a single DB transaction on the
+shared AR connection. Every `fetch_*` / `execute` the task performs
+participates in it; the transaction commits on `Ok` and rolls back —
+re-raising the error — on `Err`:
+
+```jade
+import Sql exposing (SqlError, execute, transaction)
+
+def book(visit: NewVisit, patient: Patient) -> Task(Int, SqlError)
+  record_visit(visit)
+    |> Task.and_then((_) -> { touch_last_seen(patient) })
+    |> transaction
+end
+```
+
+Because the wrapped task keeps its own decoding, `transaction` is fully
+polymorphic in the result — `transaction(t) : Task(a, SqlError)` for any
+`t : Task(a, SqlError)`.
+
+Transactions don't nest yet (no savepoints): wrapping a `transaction`
+inside another issues a second `BEGIN` on the same connection. Needs
+opt-in via `require 'jade-sql/runtime'`.
+
+## Testing without a DB
+
+The Task dispatcher can be stubbed. From RSpec:
+
+```ruby
+require 'jade/tasks/rspec'
+
+describe MyApp do
+  include Jade::Tasks::RSpec
+
+  it 'queries patients' do
+    all_calls_to(JadeSql::Runtime.port_execute_many) do |t, _pair|
+      t.ok([
+        { "id" => 1, "name" => "Paul", "mrn" => "MRN-001" }
+      ])
+    end
+
+    expect(MyApp.list.run).to be_ok
+  end
+end
+```
+
+The three ports are `port_execute_count`, `port_execute_one`,
+`port_execute_many` — `Sql.execute*` / `Sql.fetch_*` and their `*_raw`
+siblings ultimately dispatch through these. Stub them with
+`all_calls_to(JadeSql::Runtime.port_execute_*) { |t, pair| ... }`.