briefly 0.1.0 → 0.2.1

data/lib/briefly/builder.rb

@@ -1,23 +1,28 @@
 # frozen_string_literal: true
 
 module Briefly
-  # Receives the DSL. {Briefly.define}'s block and {Briefly::Facade#configure}'s block are
+  # Receives the DSL. {Briefly.define}'s block and {Briefly::Facade::Control#configure}'s block are
   # +instance_eval+'d here, never on the facade, so DSL verbs can never collide with shortcut names.
   #
-  # The block only collects; {#compile!} then validates, and {Briefly::Facade#configure} installs.
+  # The block only collects; {#compile!} then validates, and {Briefly::Facade::Control#configure} installs.
   class Builder
+    # A validated {#compile!} pass, ready for a {Briefly::Facade} to install. +child_plans+ holds one
+    # +[child_facade, child_plan]+ pair per namespace this pass collected, so +__commit+ can walk the
+    # tree children first.
+    Plan = Struct.new(:defs, :rescue_entries, :children, :child_plans)
+
     # @return [Briefly::Facade] the facade under construction, for packs that need lifecycle hooks
     attr_reader :facade
 
     # @api private
     # @param facade [Briefly::Facade]
-    # @param defs [Hash{Symbol => Briefly::Definition}] copies of the facade's current definitions
+    # @param defs [Hash{Symbol => Briefly::Shortcut}] copies of the facade's current shortcuts
     # @param children [Hash{Symbol => Briefly::Facade}] the facade's namespaces, by name
     def initialize(facade, defs, children)
       @facade = facade
       @defs = defs
       @children = children
-      @errors = []
+      @rescues = []
       @pending = {}
     end
 
@@ -38,10 +43,10 @@ module Briefly
     end
 
     # Declares a namespace: a shortcut returning a child facade, so +App.db.query+ works. The block is
-    # the child's own DSL — +shortcut+, +memoize+, +use+, +rescue_from+, and further namespaces.
+    # the child's own DSL — +shortcut+ (and the shortcut it returns), +use+, +rescue_from+, and namespaces.
     #
     # The child is created once and reused by later passes, so its memos survive +configure+.
-    # {Briefly::Facade#clear_memos!} cascades into it. Two limits, both deliberate: a child body cannot
+    # {Briefly::Facade::Control#clear_memos!} cascades into it. Two limits, both deliberate: a child body cannot
     # reach a root shortcut by bare name, and a root +rescue_from+ does not scope into the child.
     #
     # The child's pass is *collected*, not run: its builder is held until {#compile!} has validated the
@@ -70,66 +75,67 @@ module Briefly
       name
     end
 
-    # Declares a shortcut. Redeclaring a name (canonical or alias) silently overrides it.
+    # Declares a shortcut, or fetches an already-declared one to refine.
+    #
+    # With a block, declares the shortcut (redeclaring a name, canonical or alias, silently overrides it)
+    # and returns the {Briefly::Shortcut}, so you can chain +.memoize+ or +.rescue_from+ onto it. With no
+    # block, +shortcut(name)+ fetches the shortcut +name+ resolves to (canonical or alias) so a pack's
+    # shortcut can be refined; it never declares, purges, or overrides.
     #
     # @param canonical [Symbol] the primary method name; may end in +?+ or +!+
-    # @param aliases [Array<Symbol>] extra names sharing the body and the memo cell
+    # @param aliases [Array<Symbol>] extra names sharing the body and the memo cell (declare only)
     # @yield the implementation, bound to the facade at call time
-    # @return [Symbol] the canonical name
+    # @return [Briefly::Shortcut] the declared or fetched shortcut, ready to refine
+    # @raise [ArgumentError] if a bodiless call is given aliases — a fetch ignores them, so a
+    #   non-empty list means the block was forgotten
     # @raise [Briefly::ReservedNameError] if any name shadows a facade method
+    # @raise [Briefly::UnknownShortcutError] if a bodiless +name+ resolves to nothing
     def shortcut(canonical, *aliases, &body)
-      raise ArgumentError, "shortcut(#{canonical.inspect}) requires a block" unless body
+      unless body
+        # A bodiless `shortcut(name)` fetches an existing shortcut to refine; aliases are meaningless
+        # there, so a non-empty list means a block was forgotten — fail loudly, don't drop them silently.
+        raise ArgumentError, "shortcut(#{canonical.inspect}, ...) with aliases requires a block" unless aliases.empty?
 
-      # A `&:upcase`-style Proc carries no location of its own; fall back to this call site so the compiled
-      # method points at the user's declaration, never a fabricated file. `namespace` overwrites it anyway.
-      location = body.source_location || caller_locations(1, 1).first.then { |l| [l.path, l.lineno] }
-      defn = Definition.new(canonical, aliases, body, location)
+        return fetch(canonical)
+      end
+
+      defn = Shortcut.new(canonical, aliases, body, source_location_for(body))
       defn.names.each { |name| validate_name!(name) }
       purge(defn.names, except: canonical)
       @defs[canonical] = defn
-      canonical
-    end
-
-    # Marks an already-declared shortcut as memoized: computed once, cached for the process lifetime.
-    #
-    # @param name [Symbol] a canonical name or an alias
-    # @param opts [Hash] reserved for future use; none are accepted
-    # @return [Symbol] the canonical name
-    # @raise [Briefly::UnknownShortcutError] if +name+ does not resolve
-    def memoize(name, **opts)
-      raise ArgumentError, "memoize(#{name.inspect}) got unknown options: #{opts.keys.join(", ")}" unless opts.empty?
-
-      defn = fetch(name)
-      defn.memoize!
-      defn.canonical
     end
 
-    # Registers an error handler. The handler's return value becomes the shortcut's return value.
+    # Registers a facade-wide error handler: one applying to every shortcut, consulted after each
+    # shortcut's own handlers. The handler's return value becomes the shortcut's return value. To guard a
+    # single shortcut, chain onto it instead — +shortcut(name).rescue_from(error_class) { ... }+ — which
+    # is why this verb takes no shortcut names.
     #
     # Because +{}+ binds to the nearest token, +rescue_from StandardError { }+ is a call to a method
-    # named +StandardError+. Use +rescue_from Err, :name do |e| ... end+ or +rescue_from(Err, :name) { |e| ... }+.
+    # named +StandardError+. Use +rescue_from Err do |e| ... end+ or +rescue_from(Err) { |e| ... }+.
     #
     # @param error_class [Class] matched against the raised error and its subclasses
-    # @param names [Array<Symbol>] shortcuts to scope to; none means facade-wide
+    # @param names [Array<Symbol>] must be empty; any name is refused because the shortcut expresses it
     # @yield [error, shortcut_name] the recovery block
     # @return [self]
-    def rescue_from(error_class, *names, &handler)
-      unless error_class.is_a?(Class)
-        raise ArgumentError, "rescue_from expects the error class first, e.g. rescue_from(StandardError, :name) { }"
+    # @raise [ArgumentError] if any shortcut names are given
+    def rescue_from(error_class, *names, &block)
+      Briefly.send(:validate_rescue!, error_class, block)
+      unless names.flatten.empty?
+        raise ArgumentError, "rescue_from(#{error_class}) takes no shortcut names — scope one to its " \
+                             "shortcut with shortcut(name).rescue_from(#{error_class}) { ... }, or omit " \
+                             "names for a facade-wide handler"
       end
-      raise ArgumentError, "rescue_from(#{error_class}) requires a block" unless handler
 
-      scoped = names.flatten.map { |name| fetch(name).canonical }
-      @errors << [error_class, (scoped.empty? ? nil : scoped), handler]
+      @rescues << [error_class, block]
       self
     end
 
     # Validates everything collected in this pass, and recursively every namespace pass it collected.
-    # {Briefly::Facade#configure} installs the result. Validation of the whole tree finishes before any
+    # {Briefly::Facade::Control#configure} installs the result. Validation of the whole tree finishes before any
     # of it is installed.
     #
     # @api private
-    # @return [Array] +[definitions, error_entries, children, child_plans]+
+    # @return [Briefly::Builder::Plan]
     # @raise [Briefly::Error] if a memoized shortcut's body takes arguments
     def compile!
       @defs.each_value do |defn|
@@ -138,11 +144,21 @@ module Briefly
 
         raise Error, "cannot memoize #{defn.canonical}: its body takes arguments"
       end
-      [@defs, @errors, @children, @pending.map { |name, builder| [@children[name], builder.compile!] }]
+      Plan.new(@defs, @rescues, @children, @pending.map { |name, builder| [@children[name], builder.compile!] })
     end
 
     private
 
+    # A `&:upcase`-style Proc carries no location of its own; fall back to the caller's declaration site
+    # so the compiled method points at the user's code, never a fabricated file. `namespace` overwrites it
+    # anyway. Depth 2 skips this helper and `shortcut` to land on the DSL block — or a pack's `install`.
+    #
+    # @param body [Proc]
+    # @return [Array(String, Integer)]
+    def source_location_for(body)
+      body.source_location || caller_locations(2, 1).first.then { |l| [l.path, l.lineno] }
+    end
+
     def validate_name!(name)
       raise ArgumentError, "shortcut names must be Symbols, got #{name.inspect}" unless name.is_a?(Symbol)
       raise ReservedNameError, "#{name} is reserved by Briefly::Facade" if Facade::RESERVED.include?(name)
@@ -152,7 +168,7 @@ module Briefly
       raise ReservedNameError, "#{name} is reserved: #{Candor::BODY_PREFIX}* names hold compiled shortcut bodies"
     end
 
-    # Frees the incoming names from any definition that currently owns them, so a redeclaration
+    # Frees the incoming names from any shortcut that currently owns them, so a redeclaration
     # never leaves a stale alias pointing at the old body.
     def purge(names, except:)
       @defs.delete_if { |canonical, _| canonical != except && names.include?(canonical) }

data/lib/briefly/errors.rb

@@ -4,7 +4,7 @@ module Briefly
   # Base class for every error raised by Briefly.
   class Error < StandardError; end
 
-  # Raised when +memoize+ or +rescue_from+ names a shortcut that does not exist.
+  # Raised when a bodiless +shortcut+ names a shortcut that does not exist.
   class UnknownShortcutError < Error; end
 
   # Raised when a shortcut name or alias would shadow a facade method.

data/lib/briefly/facade.rb

@@ -14,29 +14,75 @@ module Briefly
       @__aliases = {}
       @__memos = {}.freeze
       @__monitor = Monitor.new
-      @__errors = ErrorRegistry.new
-      @__public = [].freeze
+      @__rescues = Rescues.new
+      @__installed = [].freeze
       @__children = {}
     end
 
+    # The single public door to a facade's management operations, so those five names stay free for
+    # shortcuts. A fresh {Control} each call is stateless and thread-safe — nothing to race on — and an
+    # allocation is trivial next to how rarely management runs; identity across calls is not guaranteed.
+    #
+    # @return [Control]
+    def briefly = Control.new(self)
+
+    # @return [String] a summary listing shortcut names; never dumps memo internals
+    def inspect = "#<#{self.class.name} shortcuts=#{__shortcuts.inspect}>"
+    alias to_s inspect
+
+    # The management surface, forwarded to the facade's private +__+-prefixed methods. Mutators return
+    # the facade so +Briefly.define+-style chaining and the return-self contract hold; readers return
+    # their values. It forwards via +send+, matching the +child.send(:__commit, …)+ pattern +__commit+
+    # already uses to cross the private boundary.
+    class Control
+      # @param facade [Facade]
+      def initialize(facade) = @facade = facade
+
+      # @return [Array<Symbol>] canonical shortcut names, sorted; aliases excluded
+      def shortcuts = @facade.send(:__shortcuts)
+
+      # @param name [Symbol] a canonical name or an alias
+      # @return [Boolean]
+      def shortcut?(name) = @facade.send(:__shortcut?, name)
+
+      # Drops every memoized value, here and in every namespace. Thread-safe.
+      #
+      # @return [Facade] the facade
+      def clear_memos! = @facade.send(:__clear_memos!)
+
+      # Reopens the facade for another builder pass and recompiles.
+      #
+      # @yield [] evaluated against a {Briefly::Builder}
+      # @return [Facade] the facade
+      def configure(&) = @facade.send(:__configure, &)
+
+      # Names the management operations, so typing `App.briefly` at a console self-describes what the
+      # door offers instead of echoing the facade's shortcut list. Keep in sync with the methods above.
+      #
+      # @return [String]
+      def inspect = "#<#{self.class.name} shortcuts shortcut? clear_memos! configure>"
+      alias to_s inspect
+    end
+
+    private
+
     # @return [Array<Symbol>] canonical shortcut names, sorted; aliases excluded
-    def shortcuts = @__defs.keys.sort
+    def __shortcuts = @__defs.keys.sort
 
     # @param name [Symbol] a canonical name or an alias
     # @return [Boolean]
-    def shortcut?(name) = @__defs.key?(name) || @__aliases.key?(name)
+    def __shortcut?(name) = @__defs.key?(name) || @__aliases.key?(name)
 
     # Drops every memoized value, here and in every namespace. Thread-safe.
     #
     # @return [self]
-    def clear_memos!
+    def __clear_memos!
       @__monitor.synchronize { @__memos = {}.freeze }
       # Each namespace owns its memo store and its own lock, so a child clears outside our monitor.
       # One `Reload` on the root therefore clears the whole tree, including namespaces holding no pack.
-      @__children.each_value(&:clear_memos!)
+      @__children.each_value { |child| child.send(:__clear_memos!) }
       self
     end
-    alias reset! clear_memos!
 
     # Reopens the facade for another builder pass and recompiles. The builder starts from copies of the
     # current definitions, so a pass that raises leaves the live facade — and every namespace under it
@@ -44,7 +90,7 @@ module Briefly
     #
     # @yield [] evaluated against a {Briefly::Builder}
     # @return [self]
-    def configure(&block)
+    def __configure(&block)
       builder = __prepare
       builder.instance_eval(&block) if block
       # `compile!` validates the whole tree before `__commit` installs any of it. Splitting the two is
@@ -54,12 +100,6 @@ module Briefly
       self
     end
 
-    # @return [String] a summary listing shortcut names; never dumps memo internals
-    def inspect = "#<#{self.class.name} shortcuts=#{shortcuts.inspect}>"
-    alias to_s inspect
-
-    private
-
     # A builder seeded with copies of everything a pass may mutate. {Briefly::Builder#namespace} calls
     # this on the child it collects.
     #
@@ -68,25 +108,28 @@ module Briefly
 
     # Installs a validated pass, children first. Nothing here may raise: every check ran in +compile!+.
     #
-    # @param plan [Array] +compile!+'s +[defs, error_entries, children, child_plans]+
+    # @param plan [Briefly::Builder::Plan] a validated +compile!+ pass
     # @return [self]
     def __commit(plan)
-      defs, error_entries, children, child_plans = plan
-      child_plans.each { |child, child_plan| child.send(:__commit, child_plan) }
-      @__children = children
-      __install(defs, error_entries)
+      plan.child_plans.each { |child, child_plan| child.send(:__commit, child_plan) }
+      @__children = plan.children
+      __install(plan.defs, plan.rescue_entries)
     end
 
-    # Compiles definitions onto the singleton class and appends error registrations.
-    def __install(defs, error_entries)
+    # Compiles definitions onto the singleton class and appends rescue registrations.
+    #
+    # @param defs [Hash{Symbol => Briefly::Shortcut}] the validated shortcuts, keyed by canonical name
+    # @param rescue_entries [Array<Array(Class, Proc)>] facade-wide +[error_class, handler]+ pairs
+    # @return [self]
+    def __install(defs, rescue_entries)
       wanted = defs.each_value.flat_map(&:names)
-      __remove_methods(@__public - wanted)
+      __remove_methods(@__installed - wanted)
       defs.each_value { |defn| __define(defn) }
 
-      @__public = wanted.freeze
+      @__installed = wanted.freeze
       @__defs = defs
       @__aliases = defs.each_value.flat_map { |d| d.aliases.map { |a| [a, d.canonical] } }.to_h
-      error_entries.each { |klass, names, handler| @__errors.add(klass, names, handler) }
+      rescue_entries.each { |klass, handler| @__rescues.add(klass, handler) }
       self
     end
 
@@ -120,7 +163,7 @@ module Briefly
 
         send(defn.raw_name, ...)
       rescue StandardError => e
-        __handle(e, name)
+        __handle(e, defn)
       end
     end
 
@@ -140,15 +183,20 @@ module Briefly
       end
     end
 
-    def __handle(error, name)
-      entry = @__errors.scoped(name).find { |e| error.is_a?(e.klass) } ||
-              @__errors.wide.find { |e| error.is_a?(e.klass) } ||
-              Briefly.errors.wide.find { |e| error.is_a?(e.klass) }
+    # Three tiers, most specific first: this shortcut's own handlers, then the facade-wide ones, then
+    # the global ones. Each container matches its own handlers (newest wins within a tier); this only
+    # picks the first tier that answers.
+    #
+    # @param error [StandardError]
+    # @param defn [Briefly::Shortcut]
+    # @return [Object] the matching handler's return value; if none matches, +error+ is re-raised
+    def __handle(error, defn)
+      handler = defn.handler_for(error) || @__rescues.handler_for(error) || Briefly.rescues.handler_for(error)
       # Kernel.raise, not bare raise: a shortcut may not be named `raise`, but a pack could still
       # define one on a subclass, and this must never dispatch back into the facade.
-      Kernel.raise(error) unless entry
+      Kernel.raise(error) unless handler
 
-      entry.handler.call(error, name)
+      handler.call(error, defn.canonical)
     end
   end
 

data/lib/briefly/rails/config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Briefly
+  module Rails
+    # Configuration, paths and the application-wide singletons.
+    #
+    #   App = Briefly.define { use Briefly::Rails::Config }
+    #   App.c      # => Rails.configuration
+    #   App.root   # => Rails.root
+    #
+    # +error+ is the framework's handled-error reporter: +App.error.report(e)+, +App.error.handle { }+.
+    # +config_for+ reads a per-environment YAML config on every call, forwarding any keyword (such as
+    # +env:+) to +::Rails.application.config_for+; it takes an argument and is therefore never memoized —
+    # compose one that is with +shortcut(:payments) { config_for(:payments) }.memoize+.
+    #
+    # Inside this file the framework is always +::Rails+ — bare +Rails+ would resolve to the parent module.
+    module Config
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:config, :c) { ::Rails.configuration }
+        builder.shortcut(:config_x, :x) { ::Rails.configuration.x }
+        builder.shortcut(:root) { ::Rails.root }
+        builder.shortcut(:cache) { ::Rails.cache }
+        builder.shortcut(:logger, :log) { ::Rails.logger }
+        builder.shortcut(:credentials, :cred) { ::Rails.application.credentials }
+        builder.shortcut(:error) { ::Rails.error }
+        builder.shortcut(:config_for) { |name, **opts| ::Rails.application.config_for(name, **opts) }
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/rails/db.rb

@@ -9,15 +9,22 @@ module Briefly
     #     namespace(:db2) { use Briefly::Rails::DB, base: "SecondaryApplicationRecord" }
     #   end
     #
-    #   App.db.txn { App.db.query("select * from users where id = ?", 1) }
+    #   App.db.txn { App.db.select("select * from users where id = ?", 1) }
     #
     # +base+ is a constant path, resolved on every call. Pass 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 applications outside the autoloader, with that caveat.
     #
-    # Nothing here memoizes: a connection is leased from the pool, and +query+ takes arguments. So the
-    # pack does not wire {Reload}, and works without a booted application.
+    # Nothing here memoizes: the block-form shortcuts can't be memoized, and +select+/+query+ take
+    # arguments. So the pack does not wire {Reload}, and works without a booted application.
+    #
+    # +connected_to+ forwards every argument to +base.connected_to+ — +role:+, +shard:+, +prevent_writes:+,
+    # and any custom role — so the full Rails multi-database surface is reachable. +reading+ and +writing+
+    # are sugar for the two common roles; they forward the rest (+shard:+, +prevent_writes:+) but pin the
+    # role, so +reading(role: :writing)+ still reads. Rails only allows +connected_to+ on +ActiveRecord::Base+
+    # or an abstract class — the one that declared +connects_to+ — so +base+ must be such a class; on a
+    # concrete model it raises +NotImplementedError+.
     #
     # Inside this file the framework is always +::Rails+ — bare +Rails+ would resolve to the parent module.
     module DB
@@ -29,22 +36,40 @@ module Briefly
       def install(builder, base: "ApplicationRecord")
         model = -> { base.is_a?(Module) ? base : Object.const_get(base) }
 
-        builder.shortcut(:connection, :conn) { model.call.lease_connection }
+        # `connection`/`conn` mirrors `transaction`: a `with_connection` passthrough that yields the
+        # leased connection and auto-releases at block exit, forwarding every keyword (`prevent_permanent_checkout:`
+        # today, anything Rails adds later). A bare lease would leak outside a request; there is no
+        # `release`, so the block form is the whole story. No block gives a `LocalJumpError` from
+        # Rails' own `with_connection`, which is exactly the "requires a block" contract — no guard needed.
+        builder.shortcut(:connection, :conn) { |**opts, &blk| model.call.with_connection(**opts, &blk) }
         builder.shortcut(:transaction, :txn) { |**opts, &blk| model.call.transaction(**opts, &blk) }
+        builder.shortcut(:connected_to) { |**opts, &blk| model.call.connected_to(**opts, &blk) }
+        # `**opts` first, `role:` last: the pinned role wins over any `role:` in `opts`, so `reading`
+        # always reads, while `shard:` and `prevent_writes:` still forward.
+        builder.shortcut(:reading) { |**opts, &blk| connected_to(**opts, role: :reading, &blk) }
+        builder.shortcut(:writing) { |**opts, &blk| connected_to(**opts, role: :writing, &blk) }
+        # `select` and `query` share one closure, differing only by the adapter method. `select` runs a
+        # read through `select_all` — the read-optimized path for a raw SELECT, returning an
+        # `ActiveRecord::Result` without clearing the query cache. `query` runs arbitrary SQL through
+        # `exec_query` — writes and DDL included. Neither polices the SQL it's given; the split is name
+        # and cache-path, not a runtime read/write guard.
+        #
         # `with_connection`, not `connection`: the latter is soft-deprecated, and raises outright under
         # `ActiveRecord.permanent_connection_checkout = :disallowed`.
         #
         # A bindless statement must skip `sanitize_sql_array`, which would fall through to its
         # `statement % values` branch and raise on any literal `%` — `... like '%foo%'`.
         #
-        # No `**` parameter here, deliberately: taking no keywords is what makes Ruby pack
-        # `query(sql, id: 1)` into `binds` as a trailing Hash, which is how named binds reach
+        # No `**` parameter on either shortcut, deliberately: taking no keywords is what makes Ruby pack
+        # `select(sql, id: 1)` into `binds` as a trailing Hash, which is how named binds reach
         # `sanitize_sql_array`. A `**opts` would swallow them and send the statement unbound.
-        builder.shortcut(:query) do |sql, *binds|
+        run = lambda do |method, sql, binds|
           record = model.call
           statement = binds.empty? ? sql : record.sanitize_sql_array([sql, *binds])
-          record.with_connection { |connection| connection.exec_query(statement) }
+          record.with_connection { |connection| connection.public_send(method, statement) }
         end
+        builder.shortcut(:select) { |sql, *binds| run.call(:select_all, sql, binds) }
+        builder.shortcut(:query) { |sql, *binds| run.call(:exec_query, sql, binds) }
         builder
       end
     end

data/lib/briefly/rails/env.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Briefly
+  module Rails
+    # The environment and its predicates.
+    #
+    #   App = Briefly.define { use Briefly::Rails::Env }
+    #   App.env           # => Rails.env
+    #   App.production?   # => Rails.env.production?
+    #
+    # Inside this file the framework is always +::Rails+ — bare +Rails+ would resolve to the parent module.
+    module Env
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:env) { ::Rails.env }
+        builder.shortcut(:production?, :prod?) { ::Rails.env.production? }
+        builder.shortcut(:development?, :dev?) { ::Rails.env.development? }
+        builder.shortcut(:test?) { ::Rails.env.test? }
+        builder.shortcut(:local?) { ::Rails.env.local? }
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/rails/instrument.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Briefly
+  module Rails
+    # ActiveSupport::Notifications instrumentation, as a one-shortcut pack.
+    #
+    #   App = Briefly.define { use Briefly::Rails::Instrument }
+    #   App.instrument("sql.query", model: "User") { run_the_query }
+    #
+    # A lean worker can +use "rails/instrument"+ on its own; the umbrella +use "rails"+ pulls it in too.
+    # +payload+ is an optional trailing hash, so +instrument("evt", key: 1) { }+ threads +{ key: 1 }+
+    # through to the subscribers, and the block's return value is preserved.
+    #
+    # +::ActiveSupport+ is fully qualified to match the sibling packs' +::Rails+ discipline; unlike
+    # +Rails+ under +Briefly::Rails+, nothing here shadows the name, so it is style, not necessity.
+    module Instrument
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:instrument) do |name, payload = {}, &blk|
+          ::ActiveSupport::Notifications.instrument(name, payload, &blk)
+        end
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/rails/reload.rb

@@ -31,7 +31,7 @@ module Briefly
         end
 
         facade.instance_variable_set(INSTALLED, true)
-        app.reloader.to_prepare { facade.clear_memos! }
+        app.reloader.to_prepare { facade.briefly.clear_memos! }
         builder
       end
     end

data/lib/briefly/rails/view.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Briefly
+  module Rails
+    # Helpers, routes and rendering outside a controller.
+    #
+    #   App = Briefly.define { use Briefly::Rails::View }
+    #   App.h             # => ApplicationController.helpers
+    #   App.render(...)   # => ApplicationController.renderer.render(...)
+    #
+    # Inside this file the framework is always +::Rails+ / +::ApplicationController+ — the bare names
+    # would resolve to the parent module.
+    module View
+      module_function
+
+      # @param builder [Briefly::Builder]
+      # @return [Briefly::Builder]
+      def install(builder)
+        builder.shortcut(:helpers, :h) { ::ApplicationController.helpers }
+        builder.shortcut(:routes, :r) { ::Rails.application.routes.url_helpers }
+        builder.shortcut(:renderer) { ::ApplicationController.renderer }
+        builder.shortcut(:render) { |*args, **kwargs, &blk| renderer.render(*args, **kwargs, &blk) }
+        builder
+      end
+    end
+  end
+end

data/lib/briefly/rails.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require "briefly"
+require "briefly/rails/config"
+require "briefly/rails/env"
+require "briefly/rails/view"
 require "briefly/rails/db"
+require "briefly/rails/instrument"
 require "briefly/rails/reload"
 
 module Briefly
@@ -12,8 +16,8 @@ module Briefly
   #   App.render(...)  # => ApplicationController.renderer.render(...)
   #   App.db.txn { }   # => ApplicationRecord.transaction { }
   #
-  # An umbrella over {Config}, {Env}, {View} and {Reload}, plus {DB} under the +db+ namespace. Each is
-  # a pack in its own right, so a facade can take only the parts it wants:
+  # An umbrella over {Config}, {Env}, {View}, {Instrument} and {Reload}, plus {DB} under the +db+
+  # namespace. Each is a pack in its own right, so a facade can take only the parts it wants:
   #
   #   Admin = Briefly.define do
   #     use "rails/env"
@@ -36,56 +40,9 @@ module Briefly
       builder.use(Config)
       builder.use(Env)
       builder.use(View)
+      builder.use(Instrument)
       builder.namespace(:db) { use DB }
       builder
     end
-
-    # Configuration, paths and the application-wide singletons.
-    module Config
-      module_function
-
-      # @param builder [Briefly::Builder]
-      # @return [Briefly::Builder]
-      def install(builder)
-        builder.shortcut(:config, :c) { ::Rails.configuration }
-        builder.shortcut(:config_x, :x) { ::Rails.configuration.x }
-        builder.shortcut(:root) { ::Rails.root }
-        builder.shortcut(:cache) { ::Rails.cache }
-        builder.shortcut(:logger, :log) { ::Rails.logger }
-        builder.shortcut(:credentials, :cred) { ::Rails.application.credentials }
-        builder
-      end
-    end
-
-    # The environment and its predicates.
-    module Env
-      module_function
-
-      # @param builder [Briefly::Builder]
-      # @return [Briefly::Builder]
-      def install(builder)
-        builder.shortcut(:env) { ::Rails.env }
-        builder.shortcut(:production?) { ::Rails.env.production? }
-        builder.shortcut(:development?) { ::Rails.env.development? }
-        builder.shortcut(:test?) { ::Rails.env.test? }
-        builder.shortcut(:local?) { ::Rails.env.local? }
-        builder
-      end
-    end
-
-    # Helpers, routes and rendering outside a controller.
-    module View
-      module_function
-
-      # @param builder [Briefly::Builder]
-      # @return [Briefly::Builder]
-      def install(builder)
-        builder.shortcut(:helpers, :h) { ::ApplicationController.helpers }
-        builder.shortcut(:routes, :r) { ::Rails.application.routes.url_helpers }
-        builder.shortcut(:renderer) { ::ApplicationController.renderer }
-        builder.shortcut(:render) { |*args, **kwargs, &blk| renderer.render(*args, **kwargs, &blk) }
-        builder
-      end
-    end
   end
 end