briefly 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06a4a7f10ae74a9abd66fd882812d0af1a469d09916da7f898375b659bbdbdf
-  data.tar.gz: a72ed9ae644fa4bca67fa2f671486945ddd90872a78171864fa896b33d778443
+  metadata.gz: b2caa5442969820b1605dee751c3e544987d5edc7d89e701ef7a66b222ba1e20
+  data.tar.gz: b4aa66328b61c6fe4e56f9b7b4fec9798ad396fd486b3957152aecb227aa7244
 SHA512:
-  metadata.gz: 72e7861ca614204a8536bdd8b0c40c48c480981c9cd494dc5d4de6b14bdbca1e016c0c658e728843b29afcf5b878020ae7e511869ad5ec666d825938afdfc885
-  data.tar.gz: ed27d0120874e0ff825a0ac0859b71c75947bccbe5c9dadf70b20de8d7f7eb46b3212e1f23b52e924e2a8b46b4c31b8950944875fcc94b341039e21b80c816c4
+  metadata.gz: ebe66d5820348b8a635abd9f2870458aca11a905c6718399001099ae60e7a340b75c5f0af0f5cb096f7f0482ef7ddb99b7856d3efefdf9437cd4401fdead04a2
+  data.tar.gz: 8b3b5ecd63e4b14ca45d614f55214d2fd22abadb107d57e320758058d7d402819e08e8e0614548fd6805646dfecb6e0dbf60f5cb9d6d2dc023b1620452d9951b

data/CHANGELOG.md

@@ -6,6 +6,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+## v0.2.0 (2026-07-14)
+
+### Added
+- `rails g briefly:install` — a Rails generator that writes `config/initializers/briefly.rb`: a
+  working `App` facade plus a commented, concern-grouped map of every shortcut `use "rails"` installs.
+  Pass a name (`rails g briefly:install Facade`) to rename the constant; re-run it after upgrading to
+  refresh the map, as Rails prompts before overwriting. It loads only under `rails generate`, so no
+  Rails runtime dependency is added.
+- `Briefly::Rails::Config` gains `error` (`Rails.error`, the framework's handled-error reporter) and
+  `config_for` (per-environment YAML via `Rails.application.config_for`). Both are live lookups;
+  `config_for` takes an argument, so it never memoizes — compose one that does by chaining `.memoize`
+  onto a shortcut: `shortcut(:x) { config_for(:x) }.memoize`.
+- `Briefly::Rails::DB` gains `connected_to`, `reading` and `writing` for multi-database routing.
+  `connected_to` forwards the full Rails surface (`role:`, `shard:`, `prevent_writes:`, custom roles);
+  `reading`/`writing` are sugar that pin their role and forward the rest. `base` must be
+  `ActiveRecord::Base` or an abstract connection class; a concrete model raises `NotImplementedError`.
+- `Briefly::Rails::DB` gains `select` — a raw-SQL read through `select_all`, returning an
+  `ActiveRecord::Result` on the query-cache-preserving path, with the same positional and named
+  bind-safety as `query`. `query` keeps running arbitrary SQL (writes and DDL included) via `exec_query`.
+- `Briefly::Rails::Env` gains `dev?` and `prod?`, aliases of `development?` and `production?`.
+- `Briefly::Rails::Instrument` — a new `"rails/instrument"` pack with one `instrument` shortcut over
+  `ActiveSupport::Notifications.instrument(name, payload) { }`. Usable on its own; `use "rails"`
+  includes it, so `App.instrument` comes for free.
+
+### Changed
+- **BREAKING:** Facade management moved behind a single `App.briefly` accessor —
+  `App.briefly.configure`, `App.briefly.shortcuts`, `App.briefly.shortcut?` and
+  `App.briefly.clear_memos!`. This frees `configure`, `shortcuts`, `shortcut?` and `clear_memos!` for
+  use as your own shortcut names; only `briefly`, `inspect` and `to_s` stay reserved on the facade's
+  public surface.
+- **BREAKING:** `Briefly::Rails::DB#connection`/`#conn` is now an auto-releasing block that forwards to
+  `base.with_connection`, yielding the leased connection and releasing it at block exit — the shape of
+  `transaction`. It requires a block; the old bare `base.lease_connection` accessor (held on the thread
+  and never released, a leak outside a request) is gone, with no compatibility shim. Anyone needing a
+  held raw lease calls `lease_connection` on their model directly.
+- The DB pack's tests now run against real Active Record on in-memory SQLite, so its Active Record
+  calls are verified rather than mocked. `activerecord` and `sqlite3` join `activesupport` as dev-only
+  dependencies; the gem still declares no Rails runtime dependency.
+- **BREAKING:** `shortcut` now returns the `Briefly::Shortcut` it declares instead of the canonical
+  name Symbol. Refine it in place — `shortcut(:x) { ... }.memoize`, `.rescue_from(Error) { fallback }`,
+  in any order — so a shortcut's name is never written twice to annotate it. A bodiless `shortcut(:x)`
+  fetches an already-declared shortcut (canonical or alias) to refine, raising
+  `Briefly::UnknownShortcutError` on an unknown name; it never re-declares. A shortcut's memoization
+  and its own error handlers live on the shortcut itself, so refining it after a redeclaration affects
+  the declaration you named, exactly as its body does.
+- **BREAKING:** The top-level `rescue_from(error_class)` verb is now facade-wide only and takes no
+  shortcut names; passing any raises `ArgumentError` pointing at `shortcut(name).rescue_from(...)`.
+  Scope a handler to a shortcut by chaining `.rescue_from` onto it. Global `Briefly.rescue_from` is
+  unchanged.
+- **BREAKING:** the rescue-handler registry is now `Briefly::Rescues` (was
+  `Briefly::ErrorRegistry`), reached through `Briefly.rescues` (was `Briefly.errors`) — it holds
+  `rescue_from` handlers, not errors. `Briefly.rescues.clear` still resets globally registered
+  handlers; the internal `#wide` enumerator is gone, replaced by `#size` for counting registrations.
+
+### Removed
+- **BREAKING:** `App.reset!` — use `App.briefly.clear_memos!`. It was a pure alias for `clear_memos!`
+  with no internal callers.
+- **BREAKING:** The top-level `memoize` DSL verb — chain `.memoize` onto the shortcut `shortcut`
+  returns (`shortcut(:x) { ... }.memoize`), or `shortcut(:x).memoize` for one declared elsewhere.
+- **BREAKING:** Scoping `rescue_from` by shortcut name on the top-level verb — both single-name
+  `rescue_from(Error, :x)` and multi-name `rescue_from(Error, :a, :b)`. Scope on the shortcut instead:
+  `shortcut(:x).rescue_from(Error) { ... }`, chaining onto each of several.
+
 ## v0.1.0 (2026-07-10)
 
 ### Added

data/README.md

@@ -1,19 +1,12 @@
-# briefly
+# 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)
 
-[![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 — **thread-safe**,
-**reload-correct**, with a batteries-included Rails pack.
+A terse, curated facade over your application's most reached-for objects. Thread-safe, reload-correct,
+with a Rails pack included.
 
 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`
+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 and its only
 runtime dependency; candor itself has none.
@@ -21,7 +14,7 @@ runtime dependency; candor itself has none.
 ```ruby
 # config/initializers/app.rb
 App = Briefly.define do
-  use Briefly::Rails
+  use "rails"
   shortcut(:redis) { REDIS_POOL }
 end
 
@@ -38,21 +31,27 @@ App.local?                   # => true in development and test
 gem "briefly"
 ```
 
-Ruby >= 3.2. The one runtime dependency is `candor`. Rails is **optional**: the gem does not declare
+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:
 
 ```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:
 
 ```ruby
 Briefly.define do
@@ -64,65 +63,85 @@ 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 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 here — one a pack installed, say — call `shortcut(name)`
+with no block to fetch it, then chain onto that. A bodiless `shortcut` never re-declares:
+
+```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
+rescue-backed shortcut succeeds, so its own value (containing the fallback) is cached for the
 process lifetime, even after the inner shortcut recovers:
 
 ```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:
 
 ```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:
 
 ```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
+> `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`:
 >
 > ```ruby
@@ -134,23 +153,26 @@ 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:
+> **⚠️ `{}` needs parentheses (standalone `rescue_from` only).** `rescue_from StandardError { ... }`
+> binds the block to `StandardError`, not to `rescue_from`, and raises `NoMethodError`. Use either form:
 >
 > ```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,8 +184,8 @@ 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.
@@ -177,8 +199,7 @@ 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 +208,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 +227,8 @@ 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.
 
 ```ruby
 module RedisPack
@@ -215,15 +236,15 @@ 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
@@ -246,7 +267,7 @@ 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:
 
 ```ruby
 Briefly.register("myapp/redis", RedisPack)          # a pack object
@@ -256,7 +277,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 +287,52 @@ 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; 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 five 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` |
 
 ```ruby
 Worker = Briefly.define do
@@ -314,39 +346,79 @@ end
 
 | shortcut | aliases | value |
 |---|---|---|
-| `connection` | `conn` | `base.lease_connection` |
+| `connection` | `conn` | forwards keywords and the block to `base.with_connection` — yields the connection, auto-releases |
 | `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 |
 
 ```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:
 
 ```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 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
+```
 
-`query` uses `with_connection`, so the connection returns to the pool; `connection`/`conn`
-necessarily leases one.
+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/writing), plus `shard:` and `prevent_writes:`:
+
+```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
+```
+
+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.
@@ -358,15 +430,14 @@ 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,7 +448,7 @@ 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.
 
@@ -390,13 +461,13 @@ 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,7 +477,7 @@ 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`
 
@@ -426,19 +497,18 @@ 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.
 
 ## 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).
 
 ## 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"