briefly 0.1.0 → 0.2.1

data/README.md

@@ -1,27 +1,27 @@
 # briefly
 
-[![Gem Version](https://badge.fury.io/rb/briefly.svg)](https://rubygems.org/gems/briefly)
-[![CI](https://github.com/svyatov/briefly/actions/workflows/main.yml/badge.svg)](https://github.com/svyatov/briefly/actions/workflows/main.yml)
-[![codecov](https://codecov.io/gh/svyatov/briefly/branch/main/graph/badge.svg)](https://codecov.io/gh/svyatov/briefly)
-[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/briefly)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D.svg)](https://www.ruby-lang.org)
-[![Types: RBS](https://img.shields.io/badge/types-RBS-8A2BE2.svg)](https://github.com/svyatov/briefly/tree/main/sig)
+A terse, curated facade over your application's most reached-for objects.
 
-A terse, curated facade over your application's most reached-for objects — **thread-safe**,
-**reload-correct**, with a batteries-included Rails pack.
+[![gem](https://img.shields.io/gem/v/briefly)](https://rubygems.org/gems/briefly)
+[![CI](https://github.com/svyatov/briefly/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/briefly/actions/workflows/main.yml)
+[![coverage](https://codecov.io/gh/svyatov/briefly/branch/main/graph/badge.svg)](https://app.codecov.io/gh/svyatov/briefly)
 
-Every app grows an `App` module full of `def self.config = Rails.configuration`. `briefly` gives
-you that module without writing it, as **real methods** — no `method_missing`, so `respond_to?`,
-console tab-completion and test stubbing all just work. Each shortcut carries its body's `arity` and
-parameter kinds — keyword names are exact, positionals get generated ones — and its `source_location`
-is the block you declared, so jump-to-definition lands in your initializer rather than inside the gem.
-That fabrication is [candor](https://github.com/svyatov/candor), extracted from this gem and its only
-runtime dependency; candor itself has none.
+- **Ruby 3.2 and up.** Rails is optional: the gem does not declare it, and `Briefly::Rails` is
+  autoloaded only when you name it. The Rails packs themselves need Rails 7.2 or newer.
+- **25 shortcuts across six packs.** Config, env, view, db, instrument and reload, each usable on
+  its own or taken together through the `"rails"` umbrella.
+- **One runtime dependency.** [candor](https://github.com/svyatov/candor), which is itself
+  dependency-free.
+
+```bash
+bundle add briefly
+```
+
+Then, in `config/initializers/app.rb`:
 
 ```ruby
-# config/initializers/app.rb
 App = Briefly.define do
-  use Briefly::Rails
+  use "rails"
   shortcut(:redis) { REDIS_POOL }
 end
 
@@ -32,27 +32,35 @@ App.redis                    # => REDIS_POOL
 App.local?                   # => true in development and test
 ```
 
-## Installation
+Every app grows an `App` module full of `def self.config = Rails.configuration`. `briefly` gives
+you that module without writing it, as real methods. There is no `method_missing`, so `respond_to?`,
+console tab-completion and test stubbing all work. Each shortcut carries its body's `arity` and
+parameter kinds (keyword names are exact, positionals get generated ones), and its `source_location`
+is the block you declared, so jump-to-definition lands in your initializer rather than inside the gem.
+That fabrication is [candor](https://github.com/svyatov/candor), extracted from this gem.
 
-```ruby
-gem "briefly"
-```
+## The Rails generator
 
-Ruby >= 3.2. The one runtime dependency is `candor`. Rails is **optional**: the gem does not declare
-it, and `Briefly::Rails` is autoloaded only when you name it.
+In a Rails app, `rails g briefly:install` writes `config/initializers/briefly.rb`: a working `App`
+facade plus a commented, concern-grouped map of every shortcut the `rails` pack gives you. Pass a
+name (`rails g briefly:install Facade`) to call the constant something else. Re-run it after upgrading
+to refresh the map; Rails prompts before overwriting. The generator loads only under `rails generate`,
+so it adds no runtime dependency.
 
 ## Core concepts
 
 A **facade** is the object `Briefly.define` returns. You assign it to a constant of your choosing;
-`briefly` never installs one for you. Multiple independent facades share no state:
+`briefly` never installs one for you. Multiple independent facades share no state, so an initializer
+can declare as many as it needs:
 
 ```ruby
-App   = Briefly.define { use Briefly::Rails }
+App   = Briefly.define { use "rails" }
 Admin = Briefly.define { shortcut(:audit_log) { AuditLog } }
 ```
 
-A **shortcut** is a name plus a body. The body is always attached to `shortcut` — one block, one
-place — and runs bound to the facade, so it can reach the facade's other shortcuts:
+A **shortcut** is a name plus a body. The body is always attached to `shortcut`, one block in one
+place, and runs bound to the facade, so it can reach the facade's other shortcuts. Inside the
+initializer's `Briefly.define` block:
 
 ```ruby
 Briefly.define do
@@ -64,66 +72,90 @@ end
 ```
 
 Aliases are real methods delegating to the same body and the same memo cell. Redeclaring a name
-overrides it silently — that is how you override a pack's shortcut.
+overrides it silently; that is how you override a pack's shortcut.
 
 ## `memoize`
 
-Annotate an already-declared shortcut by name, on its own line:
+`shortcut` returns the shortcut you refine. Chain `.memoize` onto it in your initializer to cache the
+value, computed once, then reused for the process lifetime:
 
 ```ruby
 Briefly.define do
-  shortcut(:catalog) { Catalog.load_from_disk }
-  memoize :catalog
+  shortcut(:catalog) { Catalog.load_from_disk }.memoize
 end
 ```
 
-Memoization is **permanent for the process** — the core has no idea what a "reload" is. It caches
-`nil` and `false` correctly, and a body that takes any parameter — positional, keyword, or block —
+To memoize a shortcut you didn't declare yourself, one a pack installed, say, call `shortcut(name)`
+with no block to fetch it, then chain onto that. A bodiless `shortcut` never re-declares, so this
+also belongs in the initializer:
+
+```ruby
+Briefly.define do
+  use "rails"
+  shortcut(:cache).memoize
+end
+```
+
+Memoization is permanent for the process; the core has no idea what a "reload" is. It caches
+`nil` and `false` correctly, and a body that takes any parameter (positional, keyword, or block)
 cannot be memoized (raises at build time). The compiled method takes no arguments either, so
 `App.catalog(:x)` is an `ArgumentError`, never a silent cache hit. If a memoized body raises and a
-handler supplies a fallback, **that shortcut's own cell is not filled**: the transient failure is
+handler supplies a fallback, that shortcut's own cell is not filled: the transient failure is
 retried on next call.
 
 That guarantee is per-cell, and does not compose. A memoized shortcut whose body *reads* a
-rescue-backed shortcut succeeds, so its own value — containing the fallback — is cached for the
-process lifetime, even after the inner shortcut recovers:
+rescue-backed shortcut succeeds, so its own value (containing the fallback) is cached for the
+process lifetime, even after the inner shortcut recovers. Two initializer declarations that trap
+you:
 
 ```ruby
-shortcut(:flaky) { external_call }        # rescue_from(..., :flaky) { "unknown" }
-memoize :flaky
-shortcut(:summary) { "build #{flaky}" }   # caches "build unknown" forever
-memoize :summary                          # <- don't memoize over a rescue-backed shortcut
+shortcut(:flaky) { external_call }.rescue_from(SomeError) { "unknown" }.memoize
+shortcut(:summary) { "build #{flaky}" }.memoize   # <- caches "build unknown" forever
 ```
 
-Clearing is a neutral primitive:
+Clearing is a neutral primitive. Management lives behind one accessor, `App.briefly`, so names like
+`configure`, `shortcuts`, `shortcut?` and `clear_memos!` stay yours to use as shortcuts. Call it
+from application code:
 
 ```ruby
-App.clear_memos!   # => App     (thread-safe; `reset!` is an alias)
+App.briefly.clear_memos!   # => App     (thread-safe)
 ```
 
+Reclaim one of those names and `App.configure` calls *your* shortcut; the old management call now
+lives only at `App.briefly.configure`. Worth knowing when porting pre-0.2.0 code: a leftover
+`App.configure { ... }` won't raise if a `configure` shortcut exists, it just runs the shortcut and,
+like any non-yielding method, drops the block.
+
 *When* to clear is a pack's business. See [Reloading](#reloading-and-thread-safety).
 
 ## `rescue_from`
 
-Error class first, shortcut names optional and trailing. The handler's **return value becomes the
-shortcut's return value**:
+The handler's return value becomes the shortcut's return value. To guard one shortcut, chain
+`.rescue_from(error_class) { |e, name| ... }` onto it. The top-level `rescue_from` verb is for what a
+single shortcut can't voice: a facade-wide handler, consulted after each shortcut's own. Error class
+first, always. Both forms belong in the initializer:
 
 ```ruby
 Briefly.define do
-  use Briefly::Rails
-  shortcut(:redis) { REDIS_POOL }
-  rescue_from(Redis::BaseError, :redis) { |e| Sentry.capture_exception(e); nil }
-  rescue_from(StandardError) { |e, name| Rails.logger.warn("#{name}: #{e.message}"); raise }
+  use "rails"
+  shortcut(:redis) { REDIS_POOL }.rescue_from(Redis::BaseError) { |e| Sentry.capture_exception(e); nil }
+  rescue_from(StandardError) { |e, name| Rails.logger.warn("#{name}: #{e.message}"); raise }  # facade-wide
 end
 ```
 
-Unlike a shortcut body, a handler is **not** bound to the facade — it is called as
+The top-level `rescue_from` takes no shortcut names. Pass any and it raises `ArgumentError`, pointing
+you at `shortcut(name).rescue_from(...)`. Scoping a handler to a shortcut lives in one channel, the
+shortcut itself, so its name is never written twice to annotate it. To share one handler across a few
+shortcuts, chain `.rescue_from` onto each; to cover them all, register it facade-wide.
+
+Unlike a shortcut body, a handler is not bound to the facade. It is called as
 `handler.call(error, name)`, so `self` stays whatever it was where you wrote the block. Reach for
 constants (`Rails.logger`, `Sentry`) rather than bare shortcut names inside a handler.
 
-> **A facade-wide `rescue_from(StandardError)` catches your own bugs, not just your app's.**
-> `briefly` cannot tell an error raised *by* a shortcut body from one raised *about* the call — a
-> typo and a dead Redis both arrive as a `StandardError`:
+> [!WARNING]
+> A facade-wide `rescue_from(StandardError)` catches your own bugs, not just your app's.
+> `briefly` cannot tell an error raised *by* a shortcut body from one raised *about* the call; a
+> typo and a dead Redis both arrive as a `StandardError`. Written in an initializer:
 >
 > ```ruby
 > shortcut(:host) { Rails.aplication.config.host }   # typo -> NoMethodError
@@ -134,23 +166,28 @@ constants (`Rails.logger`, `Sentry`) rather than bare shortcut names inside a ha
 >
 > Three ways out, in order of preference: scope handlers to the shortcuts that can actually fail;
 > match the narrowest error class you mean; and if you do want a facade-wide handler, make it log
-> and `raise` — a bare `raise` inside a handler re-raises the original, backtrace intact.
+> and `raise`. A bare `raise` inside a handler re-raises the original, backtrace intact.
 >
 > A bad *call* from outside the facade is not affected. Every shortcut carries its body's arity, so
 > `App.env(1)` raises `ArgumentError` at the call site, before any handler is consulted. One shortcut
 > body calling another with a bad argument list is a different matter: that raises *inside* the
 > calling body, where the calling shortcut's own handler sees it like any other error.
 
-> **⚠️ `{}` needs parentheses.** `rescue_from StandardError { ... }` binds the block to
-> `StandardError`, not to `rescue_from`, and raises `NoMethodError`. Use **either** form:
+> [!IMPORTANT]
+> `{}` needs parentheses, on the standalone `rescue_from` only. `rescue_from StandardError { ... }`
+> binds the block to `StandardError`, not to `rescue_from`, and raises `NoMethodError`. Use either
+> form inside your `Briefly.define` block:
 >
 > ```ruby
-> rescue_from StandardError, :redis do |e| ... end   # do/end, no parens
-> rescue_from(StandardError, :redis) { |e| ... }     # braces REQUIRE parens
+> rescue_from StandardError do |e| ... end   # do/end, no parens
+> rescue_from(StandardError) { |e| ... }     # braces REQUIRE parens
 > ```
+>
+> Scoping to the shortcut sidesteps this: `shortcut(:redis) { ... }.rescue_from(Redis::BaseError) { |e| ... }`
+> already has a receiver and parens, so `{ }` binds where you mean it.
 
 Handlers are plain procs, so `{ |e| }` and `{ |e, name| }` both work. Re-raising propagates. If no
-handler matches, the original error propagates unchanged — never silently swallowed. Only
+handler matches, the original error propagates unchanged, never silently swallowed. Only
 `StandardError` and its descendants participate.
 
 `Briefly.rescue_from(error_class, &handler)` registers a global default across every facade. It
@@ -162,23 +199,23 @@ For a raised error, the first `is_a?` match wins, searching in this order:
 
 | # | Level | Within the level |
 |---|-------|------------------|
-| 1 | Facade handlers scoped to this shortcut | last registered first |
-| 2 | Facade handlers with no names | last registered first |
+| 1 | This shortcut's own handlers | last registered first |
+| 2 | Facade-wide handlers | last registered first |
 | 3 | Global handlers (`Briefly.rescue_from`) | last registered first |
 
-No match → the error propagates.
+With no match, the error propagates.
 
 ## `namespace`
 
-`namespace` groups shortcuts behind a name, so the root keyspace stays yours:
+`namespace` groups shortcuts behind a name, so the root keyspace stays yours. In the initializer,
+and then anywhere in the app:
 
 ```ruby
 App = Briefly.define do
   shortcut(:redis) { REDIS_POOL }
 
   namespace :db do
-    shortcut(:pool) { ActiveRecord::Base.connection_pool }
-    memoize :pool
+    shortcut(:pool) { ActiveRecord::Base.connection_pool }.memoize
   end
 end
 
@@ -187,9 +224,9 @@ App.db        # => #<Briefly::Facade shortcuts=[:pool]>
 App.db.pool   # => the pool
 ```
 
-A namespace is a child `Briefly::Facade`, reached by a real method like any other shortcut — so
+A namespace is a child `Briefly::Facade`, reached by a real method like any other shortcut, so
 `App.db` is a value you can pass around, and `App.db.pool` is not a `method_missing` trick. It takes
-the whole DSL: `shortcut`, `memoize`, `rescue_from`, `use`, and further namespaces.
+the whole DSL: `shortcut` (and the shortcut it returns), `rescue_from`, `use`, and further namespaces.
 
 `clear_memos!` cascades, so one `Briefly::Rails::Reload` on the root clears the whole tree. The child
 is created once and reused, so its memos survive a later `configure`.
@@ -206,8 +243,9 @@ Two limits, both deliberate:
 
 ## Packs
 
-A pack is **any object responding to `#install(builder, **opts)`**. That's the whole protocol. Options
-are optional: Ruby drops an empty `**` splat, so a pack taking none needs no keyword parameter.
+A pack is any object responding to `#install(builder, **opts)`. Options are optional: Ruby drops an
+empty `**` splat, so a pack taking none needs no keyword parameter. Put the pack in a file your
+app already loads, such as `lib/redis_pack.rb`, and `use` it from the initializer:
 
 ```ruby
 module RedisPack
@@ -215,21 +253,21 @@ module RedisPack
 
   def install(builder)
     builder.shortcut(:redis) { ConnectionPool.new { Redis.new } }
-    builder.memoize(:redis)
-    builder.rescue_from(Redis::CannotConnectError, :redis) { nil }
+           .memoize
+           .rescue_from(Redis::CannotConnectError) { nil }
   end
 end
 
 Api = Briefly.define { use RedisPack }
 ```
 
-Packs may `use` other packs, and may reach `builder.facade` to wire lifecycle hooks — that is
+Packs may `use` other packs, and may reach `builder.facade` to wire lifecycle hooks, which is
 exactly what `Briefly::Rails::Reload` does. The core stays framework-agnostic; packs do not have to.
 
 ### Options
 
 Keywords passed to `use` reach the pack's `install`. Ruby drops an empty `**` splat, so a pack that
-takes no options needs no keyword parameter:
+takes no options needs no keyword parameter. The same pack file, now taking a `url:`:
 
 ```ruby
 module RedisPack
@@ -246,7 +284,8 @@ Api = Briefly.define { use RedisPack, url: "redis://cache:6379" }
 ### Short names
 
 `Briefly.register` maps a name to a pack, so `use` can take a string or symbol. There is no
-inflection and no path guessing — the registry is the only source of truth:
+inflection and no path guessing; the registry is the only source of truth. Register in the
+initializer, before the `define` that names it:
 
 ```ruby
 Briefly.register("myapp/redis", RedisPack)          # a pack object
@@ -256,7 +295,8 @@ Api = Briefly.define { use "myapp/redis", url: "redis://cache:6379" }
 ```
 
 An unregistered name raises `Briefly::UnknownPackError`. The packs this gem ships are registered as
-`"rails"`, `"rails/config"`, `"rails/env"`, `"rails/view"`, `"rails/db"` and `"rails/reload"`.
+`"rails"`, `"rails/config"`, `"rails/env"`, `"rails/view"`, `"rails/db"`, `"rails/instrument"` and
+`"rails/reload"`.
 
 ### `Briefly::Rails`
 
@@ -265,42 +305,55 @@ An unregistered name raises `Briefly::UnknownPackError`. The packs this gem ship
 | `config` | `c` | `Rails.configuration` |
 | `config_x` | `x` | `Rails.configuration.x` |
 | `env` | | `Rails.env` |
-| `production?` `development?` `test?` `local?` | | `Rails.env.*` |
+| `production?` `development?` `test?` `local?` | `prod?` `dev?` | `Rails.env.*` |
 | `root` | | `Rails.root` |
 | `cache` | | `Rails.cache` |
 | `logger` | `log` | `Rails.logger` |
 | `credentials` | `cred` | `Rails.application.credentials` |
+| `error` | | `Rails.error` |
+| `config_for` | | `Rails.application.config_for(name, **opts)` |
 | `helpers` | `h` | `ApplicationController.helpers` |
 | `routes` | `r` | `Rails.application.routes.url_helpers` |
 | `renderer` | | `ApplicationController.renderer` |
 | `render` | | forwards to `renderer.render` |
+| `instrument` | | `ActiveSupport::Notifications.instrument(name, payload) { }` |
 
 Plus `db`, a namespace holding `Briefly::Rails::DB`.
 
+`prod?` and `dev?` alias `production?` and `development?`. `error` is the framework's handled-error
+reporter, so `App.error.report(e)` and `App.error.handle { }` reach it off one live lookup.
+`config_for` reads a per-environment YAML config on every call and forwards any extra keyword (such
+as `env:`) to `Rails.application.config_for`: it takes an argument, so it never memoizes; compose one
+that does by chaining `.memoize` onto a shortcut: `shortcut(:payments) { config_for(:payments) }.memoize`.
+
 Requires Rails >= 7.2. There is no `secrets` shortcut: `Rails.application.secrets` was removed in
 7.2. Use `credentials`.
 
-**Nothing in the pack is memoized.** `helpers`, `routes` and `renderer` are live lookups: Rails
+Nothing in the pack is memoized. `helpers`, `routes` and `renderer` are live lookups: Rails
 already caches them on objects it refreshes on reload, so caching them again would only go stale.
 It still composes `Briefly::Rails::Reload`, because *your* memoized shortcuts need clearing.
 
-Need a custom renderer? Override it — last declaration wins:
+Need a custom renderer? Override it in the initializer; last declaration wins:
 
 ```ruby
 App = Briefly.define do
-  use Briefly::Rails
+  use "rails"
   shortcut(:renderer) { ApplicationController.renderer.new(http_host: x.domain, https: !development?) }
 end
 ```
 
-`Briefly::Rails` is an umbrella over four packs, each usable on its own:
+`Briefly::Rails` is an umbrella over six packs, each usable on its own:
 
 | pack | short name | shortcuts |
 |---|---|---|
-| `Briefly::Rails::Config` | `"rails/config"` | `config`, `config_x`, `root`, `cache`, `logger`, `credentials` |
+| `Briefly::Rails::Config` | `"rails/config"` | `config`, `config_x`, `root`, `cache`, `logger`, `credentials`, `error`, `config_for` |
 | `Briefly::Rails::Env` | `"rails/env"` | `env` and its predicates |
 | `Briefly::Rails::View` | `"rails/view"` | `helpers`, `routes`, `renderer`, `render` |
-| `Briefly::Rails::DB` | `"rails/db"` | `connection`, `transaction`, `query` |
+| `Briefly::Rails::DB` | `"rails/db"` | `connection`, `transaction`, `select`, `query`, `connected_to`, `reading`, `writing` |
+| `Briefly::Rails::Instrument` | `"rails/instrument"` | `instrument` |
+| `Briefly::Rails::Reload` | `"rails/reload"` | none; clears memos on every code reload |
+
+Take only the parts you want, in the initializer:
 
 ```ruby
 Worker = Briefly.define do
@@ -314,59 +367,101 @@ end
 
 | shortcut | aliases | value |
 |---|---|---|
-| `connection` | `conn` | `base.lease_connection` |
+| `connection` | `conn` | forwards keywords and the block to `base.with_connection`, yielding the connection and auto-releasing |
 | `transaction` | `txn` | forwards keywords and the block to `base.transaction` |
-| `query` | | `base.with_connection { \|c\| c.exec_query(sql) }` |
+| `select` | | `base.with_connection { \|c\| c.select_all(sql) }`, a read (SELECT) on the cache-aware path |
+| `query` | | `base.with_connection { \|c\| c.exec_query(sql) }`, arbitrary SQL, writes and DDL included |
+| `connected_to` | | forwards every argument to `base.connected_to` (`role:`, `shard:`, `prevent_writes:`) |
+| `reading` | | runs the block under the `:reading` role |
+| `writing` | | runs the block under the `:writing` role |
+
+Declare the namespace in the initializer, then call it from application code:
 
 ```ruby
 App = Briefly.define do
-  use Briefly::Rails
+  use "rails"
   namespace(:db2) { use "rails/db", base: "SecondaryApplicationRecord" }
 end
 
-App.db.txn { App.db.query("select * from users where id = ?", 1) }
-App.db2.conn
+App.db.txn { App.db.select("select * from users where id = ?", 1) }
+App.db.conn { |c| c.select_value("select count(*) from users") }
 ```
 
-`query(sql, *binds)` sanitizes through `base.sanitize_sql_array` when binds are given, and passes the
-statement through untouched when they are not. Positional and named binds both work:
+`select` and `query` are the two raw-SQL helpers, differing only in which adapter path they take.
+`select(sql, *binds)` runs a read through `select_all`, the path Rails recommends for a raw SELECT,
+returning an `ActiveRecord::Result` without clearing the query cache. `query(sql, *binds)` runs
+arbitrary SQL through `exec_query`: reads, writes, and DDL all execute. The name tells you which
+you're reaching for; neither polices the SQL it's handed, so `select` will happily run a write you
+give it. The split is name and cache-path, not a runtime guard.
+
+Both sanitize through `base.sanitize_sql_array` when binds are given, and pass the statement through
+untouched when they are not. Positional and named binds both work, from application code:
 
 ```ruby
-App.db.query("select * from users where name like '%ada%'")          # no binds, passed through
-App.db.query("select * from users where id = ?", 123)                # positional
-App.db.query("select * from users where id = :id", id: 123)          # named
+App.db.select("select * from users where name like '%ada%'")         # no binds, passed through
+App.db.select("select * from users where id = ?", 123)               # positional
+App.db.query("update users set active = true where id = :id", id: 1) # named, a write via `query`
 ```
 
 Binds are bound, never interpolated, so a value like `"x' OR '1'='1"` matches nothing. A bindless
-statement is deliberately *not* sanitized: `sanitize_sql_array` would fall through to its
-`statement % values` branch and raise on the literal `%` above.
+statement is not sanitized on purpose: `sanitize_sql_array` would fall through to its
+`statement % values` branch and raise on the literal `%` above. That makes binds a safety contract,
+not a convenience: always pass untrusted values as binds. The bindless path is unsanitized, and since
+`query` now runs writes and DDL, an interpolated statement is a destructive-write injection risk, not
+merely a read one.
+
+`connection`/`conn` mirrors `transaction`: it forwards to `with_connection`, yields the leased
+connection, and auto-releases at block exit, so nothing leaks outside a request. It requires a block;
+there is no bare-lease accessor. Anyone who genuinely needs a held raw lease calls `lease_connection`
+on their model directly.
+
+`reading` and `writing` *route* a block. Everything inside runs under that connection role, so from
+application code you send specific reads to a replica or pin a write to the primary:
+
+```ruby
+App.db.reading { App.db.select("select * from reports") }  # runs on the replica
+App.db.writing { Audit.create!(event: "export") }          # pinned to the primary
+```
+
+They're sugar over `connected_to`, which is also a shortcut in its own right and forwards the whole
+Rails surface: any role, not just reading and writing, plus `shard:` and `prevent_writes:`. Also
+from application code:
+
+```ruby
+App.db.connected_to(role: :analytics) { Report.all.to_a }   # a custom role
+App.db.connected_to(shard: :one) { Order.find(id) }         # a shard
+App.db.reading(shard: :two) { ... }                         # sugar forwards the rest too
+```
 
-`query` uses `with_connection`, so the connection returns to the pool; `connection`/`conn`
-necessarily leases one.
+The `reading`/`writing` sugar pins its role: a `role:` you pass through it can't win, so `reading`
+always reads. All of this needs a multi-database app: `base` must be `ActiveRecord::Base` or the
+abstract class that declared `connects_to(database: { ... })`. On a concrete model `connected_to`
+raises `NotImplementedError`, and in a single-database app with no matching connection
+`App.db.reading { ... }` raises `ActiveRecord::ConnectionNotDefined`. These are a multi-DB tool, not a
+role flag.
 
 **Pass `base:` as a String, not the class.** A pack is `use`d from an initializer, where naming an
 autoloadable constant is what Rails warns about, and the captured class would go stale on the first
-code reload — permanently, since `Reload` clears memos, not closures. A `Module` is accepted for
+code reload and stay stale, since `Reload` clears memos, not closures. A `Module` is accepted for
 applications outside the autoloader, with that caveat.
 
 The pack memoizes nothing and wires no lifecycle hook, so it works without a booted application.
 
 ### `Briefly::Rails::Reload`
 
-`Briefly::Rails` composes it. Use it alone for a facade with no framework shortcuts that still
-memoizes objects holding on to reloadable application classes:
+`Briefly::Rails` composes it. Use it alone, in an initializer, for a facade with no framework
+shortcuts that still memoizes objects holding on to reloadable application classes:
 
 ```ruby
 Admin = Briefly.define do
-  use Briefly::Rails::Reload
-  shortcut(:policy) { Admin::Policy.new }
-  memoize :policy
+  use "rails/reload"
+  shortcut(:policy) { Admin::Policy.new }.memoize
 end
 ```
 
-It registers `Rails.application.reloader.to_prepare { facade.clear_memos! }`, so memos are dropped
+It registers `Rails.application.reloader.to_prepare { facade.briefly.clear_memos! }`, so memos are dropped
 at boot and on every code reload in development. In production nothing reloads, so they persist for
-the process lifetime. It raises `Briefly::Error` outside a booted app — call it from an initializer.
+the process lifetime. It raises `Briefly::Error` outside a booted app, so call it from an initializer.
 
 The callback holds its facade for the process lifetime and cannot be deregistered. Install it on
 long-lived facades assigned to constants, not on facades built per request.
@@ -377,26 +472,26 @@ Memo reads are lock-free against a frozen snapshot; writes swap in a new frozen
 reentrant lock, so a memoized body may safely call another memoized shortcut. Under Puma, a
 memoized body runs exactly once no matter how many threads race for it.
 
-`clear_memos!` guarantees the *next* read recomputes. It does **not** undo in-place mutation of an
+`clear_memos!` guarantees the *next* read recomputes. It does not undo in-place mutation of an
 already-handed-out object, and it does not survive a process restart. Two facades whose memoized
 bodies call into each other can deadlock, like any pair of mutually-locking objects; don't do that.
 
 ## Testing
 
-Shortcuts are real methods, so nothing special is needed:
+Shortcuts are real methods, so nothing special is needed in a test file:
 
 ```ruby
 allow(App).to receive(:redis).and_return(fake_redis)   # rspec-mocks verifies it
 App.stub(:redis, fake_redis) { ... }                   # minitest
 ```
 
-Call `App.reset!` between examples if a memoized value would leak. `Briefly.errors.clear` resets
-globally registered handlers.
+Call `App.briefly.clear_memos!` between examples if a memoized value would leak. `Briefly.rescues.clear`
+resets globally registered handlers.
 
 ## Types
 
-`briefly` ships RBS signatures in [`sig/`](sig). Shortcuts are compiled at runtime, so **RBS cannot
-see them** — `Briefly.define`, `Facade`'s lifecycle API and the `Builder` DSL are fully typed, but
+`briefly` ships RBS signatures in [`sig/`](sig). Shortcuts are compiled at runtime, so RBS cannot
+see them. `Briefly.define`, `Facade`'s lifecycle API and the `Builder` DSL are fully typed, but
 `App.config` is invisible to Steep. Declare the ones you rely on in your own `sig/`:
 
 ```rbs
@@ -406,10 +501,12 @@ def App.config: () -> untyped
 def App.redis: () -> untyped
 ```
 
-We deliberately do not fake this with an RBS-only `method_missing`; the gem genuinely has none.
+We do not fake this with an RBS-only `method_missing`; the gem has none.
 
 ## Migrating a hand-rolled `App`
 
+What the initializer replaces, and what it becomes:
+
 ```ruby
 # before
 module App
@@ -426,19 +523,42 @@ end
 
 # after
 App = Briefly.define do
-  use Briefly::Rails
-  shortcut(:redis) { REDIS_POOL }
-  memoize :redis
+  use "rails"
+  shortcut(:redis) { REDIS_POOL }.memoize
 end
 ```
 
 `secrets` becomes `credentials`. `helpers`/`routes` stop going stale because they are no longer
-memoized, and `redis` — which you *do* want memoized — is cleared on every dev reload by the Reload
+memoized, and `redis` (which you *do* want memoized) is cleared on every dev reload by the Reload
 pack that `Briefly::Rails` composes.
 
+## Versioning
+
+`briefly` follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The public API it
+covers is what an application touches: `Briefly.define`, `Briefly.register`, `Briefly.pack`,
+`Briefly.rescue_from` and `Briefly.rescues`; the `Builder` DSL inside a `define` block (`shortcut`,
+`namespace`, `rescue_from`, `use`); the refinements `shortcut` returns (`memoize`, `rescue_from`);
+the management surface behind `App.briefly`; the canonical names and aliases every shipped pack
+installs; and the error classes under `Briefly::Error`.
+
+Outside that promise: anything a shortcut compiles to internally, every `__`-prefixed private method
+on `Facade`, and the RBS signatures in `sig/`, which describe the static surface and are revised
+alongside it.
+
+While the version stays below `1.0.0`, an incompatible change ships in a MINOR bump and a compatible
+fix in a PATCH, so a MINOR bump is the one that may need you to read the changelog.
+
 ## Contributing
 
-Bug reports and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), and
+[CHANGELOG.md](CHANGELOG.md) for what has changed between releases.
+
+Questions and bug reports both go to [GitHub Issues](https://github.com/svyatov/briefly/issues).
+
+## Maintenance
+
+One person maintains `briefly`, actively, in their spare time. Issues and pull requests get a reply,
+and a bug on a supported Ruby or Rails version gets a fix. A large feature request may not.
 
 ## License
 

data/briefly.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.2.0"
 
   spec.require_paths = ["lib"]
-  spec.files = Dir["lib/**/*.rb"] + Dir["sig/**/*"] +
+  spec.files = Dir["lib/**/*.{rb,tt}"] + Dir["sig/**/*"] +
                %w[.yardopts CHANGELOG.md LICENSE.txt README.md briefly.gemspec]
 
   spec.add_dependency "candor", "~> 0.2.0"