strict_lazy 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e9db46fd9beb35a23ac710e80c9ae7fddebdc576e399bcc4c249bc22a8acb7b
+  data.tar.gz: 3eb3eb6e31b616914a06accca417608e62919d20b0ec8768f12d538fd0874479
+SHA512:
+  metadata.gz: 34d9415e1488ca61c7a8476cf372fd14e52aba5c6e67b33a863a15d9ee05386dc406b143648ef0278427938d9eb6d61c2e7691cecadf4487aa6b62d3febd0a91
+  data.tar.gz: d808ab15745e130af97ad8ba0dca0c5189e8e274fdb0a5455dda2cd64378f172faf77c99b5548080e82f17b92d15e1d4fa359520d8ed36c6d2e062a0a02f6986

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-06-14
+
+### Added
+
+- `StrictLazy.with_violation(mode) { ... }` — scope the violation policy to a
+  block, restoring the previous state afterward (exception-safe). Overrides
+  nest and are isolated per Fiber/Thread, so parallel test processes never
+  interfere. Useful for relaxing the policy per test type, e.g. `:ignore` in
+  model specs while keeping `:raise` in system specs.
+- `StrictLazy.violation=` and `with_violation` now raise `ArgumentError` for
+  modes other than `:raise` / `:log` / `:ignore`.
+
+### Changed
+
+- `StrictLazy.violation` is now a reader that returns the **effective** policy
+  for the current execution context (the innermost `with_violation` override,
+  else the global baseline). The global baseline moved to
+  `StrictLazy.default_violation`; `StrictLazy.violation=` still sets it, so the
+  public API and the Railtie are unchanged.
+
+## [0.2.0] - 2026-06-14
+
+### Added
+
+- Support predicate reader names (`lazy_load :published?`), read via
+  `record.lazy.published?`. A reader must be a bare name or a `?` predicate; the
+  read-only `.lazy` namespace rejects setter (`=`), bang (`!`), and operator
+  reader names at declaration time.
+
+## [0.1.0] - 2026-06-07
+
+### Added
+
+- Initial release.
+- `include StrictLazy` concern with `lazy_load` declarations (`from:` or block, xor).
+- `StrictLazy.preload(records, *readers)` with eager (`sync: true`) and lazy resolution.
+- `.lazy` namespace access (`record.lazy.x`) that never grows bare methods.
+- Strict detection via `StrictLazy.violation` (`:raise` / `:log` / `:ignore`),
+  defaulting to `:raise` in development/test and `:ignore` in production through a Railtie.
+- Per-record callable `default:` for unfulfilled records.
+
+[Unreleased]: https://github.com/aki77/strict_lazy/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/aki77/strict_lazy/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/aki77/strict_lazy/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/aki77/strict_lazy/releases/tag/v0.1.0

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,201 @@
+# StrictLazy
+
+Strict, explicit preloading for **computed values** — values that `includes` /
+`preload` cannot express (external APIs, window functions, cross-table
+aggregates). `strict_lazy` applies the spirit of Rails' `strict_loading` to those
+values: it forces you to preload them explicitly in the controller, and **raises
+in development/test** if you read one without preloading — instead of silently
+falling back to N+1.
+
+No `batch-loader` / `N1Loader` / `ar_lazy_preload` dependency. Just
+`activesupport`.
+
+## Why
+
+A naive view helper can't "register before the first access", so it quietly
+degrades to N+1. Auto-batching gems fix the N+1 but hide the missing preload.
+`strict_lazy` takes the opposite stance — **make the preload mandatory and make
+forgetting it loud** — so every query stays in the controller and view rendering
+issues no hidden queries.
+
+| Tool | Target | On unloaded access |
+| --- | --- | --- |
+| `includes` / `preload` | associations only | lazy load (can N+1) |
+| `strict_loading` (Rails) | associations only | **raise** |
+| batch-loader | general | auto-batch, no detection |
+| N1Loader (+ar_lazy_preload) | computed values | auto-batch; plain setup silently N+1s |
+| **`strict_lazy`** | **computed values** | **raise (immediate detection)** |
+
+## Installation
+
+```ruby
+gem "strict_lazy"
+```
+
+## Quick start
+
+Define a resolver, declare the value with `lazy_load`, preload in the
+controller, and read via `.lazy`.
+
+```ruby
+class Post < ApplicationRecord
+  include StrictLazy
+
+  # Block resolver: receives (records, loader); call loader.call(record, value)
+  # for each record you fulfill. Posts with zero comments never appear in the
+  # GROUP BY, so they fall back to default: 0.
+  lazy_load :comments_count, default: 0 do |posts, loader|
+    by_id = posts.index_by(&:id)
+    Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+      loader.call(by_id[post_id], n)
+    end
+  end
+
+  # from: resolver — a named class method, defined BEFORE the lazy_load. Good for
+  # complex/reusable resolvers; dedup FKs yourself.
+  def self.resolve_avatar(posts, loader)
+    urls = AvatarService.bulk_fetch(posts.map(&:author_id).uniq)
+    posts.each { |p| loader.call(p, urls[p.author_id]) }
+  end
+  lazy_load :avatar, from: :resolve_avatar, sync: true
+end
+```
+
+```ruby
+# controller
+@posts = Post.recent.to_a
+StrictLazy.preload(@posts)            # all declared loaders
+# StrictLazy.preload(@posts, :avatar) # or just some
+```
+
+```erb
+<%= post.lazy.comments_count %>
+<img src="<%= post.lazy.avatar %>">
+```
+
+## Eager vs lazy (`sync:`)
+
+- `sync: false` (default): resolution is deferred to the first `.lazy` read, then
+  the whole preloaded group is resolved in one shot and memoized.
+- `sync: true`: resolved eagerly at `StrictLazy.preload` time.
+
+## Strict detection & `violation`
+
+Reading a value that was never preloaded triggers the `violation` policy:
+
+| mode | behavior |
+| --- | --- |
+| `:raise` | raise `StrictLazy::UnloadedError` (no wasted query) |
+| `:log` | `Rails.logger.warn`, then degrade to a single-record resolve |
+| `:ignore` | silently degrade to a single-record resolve (N+1) |
+
+Environment defaults (via the Railtie):
+
+- development / test → `:raise`
+- production → `:ignore`
+
+Override globally with `StrictLazy.violation = :log`, or in Rails with
+`config.strict_lazy.violation = :log`.
+
+### Scoped overrides — `with_violation`
+
+`StrictLazy.with_violation(mode) { ... }` overrides the effective policy for the
+duration of the block, then restores the previous state — even if the block
+raises. Overrides nest (an inner call shadows the outer one) and are scoped to
+the current Fiber/Thread, so parallel test processes never interfere.
+
+```ruby
+StrictLazy.with_violation(:ignore) do
+  record.lazy.x  # degrades to a single-record resolve instead of raising
+end
+```
+
+The three APIs relate as: `StrictLazy.violation=` sets the global **baseline**,
+`with_violation` applies a **scoped** override, and the `StrictLazy.violation`
+reader returns the **effective** value (innermost override, else the baseline).
+
+### Per-test policy in RSpec
+
+`strict_lazy` ships no implicit RSpec hook — wire it up explicitly so the policy
+is visible where it applies. A common setup: model specs don't need preloads
+(`:ignore`), while system/request specs keep the strict baseline (`:raise`).
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.around(:each, type: :model) do |example|
+    StrictLazy.with_violation(:ignore) { example.run }
+  end
+end
+```
+
+To relax only a few examples, drive the `around` off a tag instead:
+
+```ruby
+RSpec.configure do |config|
+  config.around(:each, :ignore_lazy) do |example|
+    StrictLazy.with_violation(:ignore) { example.run }
+  end
+end
+
+it "computes something", :ignore_lazy do
+  # ...
+end
+```
+
+## Defaults
+
+`default:` is written for any record the resolver does not fulfill. Pass a
+**callable** for per-record defaults so mutable values are never shared:
+
+```ruby
+lazy_load :tags, default: -> { [] } do |records, loader| ... end       # arity 0
+lazy_load :slug, default: ->(record) { "p-#{record.id}" } do ... end   # arity 1
+```
+
+A static value (`default: 0`) is written as-is.
+
+## Design notes
+
+- **Preload is mandatory.** Detection happens on first access; dev/test raise so
+  you catch it immediately.
+- **Resolvers are set-level.** A resolver runs over the whole group, not one
+  record. FK dedup/mapping is the resolver's responsibility (there is no `key:`).
+- **Scope the records.** `preload` should cover the collection once; the same
+  loader preloaded on overlapping groups resolves more than once.
+- **Definition order (for `from:`).** Define the referenced class method before
+  the `lazy_load` declaration. Block resolvers have no such constraint.
+- Values live on the record (`@_lazy_<reader>`) and are GC'd with the request —
+  no thread-local cache, no middleware.
+- **Predicate readers.** `lazy_load :published?` is supported and read as
+  `record.lazy.published?`; the `?` is encoded in the ivar (`@_lazy_published_pred`)
+  so it does not collide with a plain `published` reader. A reader must be a bare
+  name or a `?` predicate — the read-only `.lazy` namespace rejects setter (`=`),
+  bang (`!`), and operator reader names at declaration time.
+
+## Non-Rails usage
+
+Works without Rails: `include StrictLazy`, declare with `lazy_load`, call
+`StrictLazy.preload(records)`, read via `record.lazy.x`. Set the policy yourself
+with `StrictLazy.violation = :raise` (the default).
+
+## Where it fits
+
+Use `includes` / `strict_loading` for **associations**, `bullet` to detect N+1
+in associations, and `strict_lazy` for **computed values** you want preloaded
+explicitly and checked strictly.
+
+## Development
+
+After checking out the repo, run `bin/setup`. Then `bundle exec rake` runs specs
+and RuboCop. `bundle exec appraisal install && bundle exec appraisal rake spec`
+runs the full Rails matrix.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/aki77/strict_lazy.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/strict_lazy/batch.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  # A single +StrictLazy.preload+ × single loader unit of work, shared by every
+  # record in the group via +@_batch_<reader>+. The resolver runs exactly once;
+  # values are written straight onto each record's +@_lazy_<reader>+ ivar, so the
+  # batch keeps no intermediate Hash and never relies on record hash-equality
+  # (unsaved records work fine).
+  class Batch
+    def initialize(model, records, loader)
+      @model = model
+      @records = records
+      @loader = loader
+      @resolved = false
+    end
+
+    # Resolve the value for one record, resolving the whole group on first touch.
+    def value_for(record)
+      resolve! unless @resolved
+      record.instance_variable_get(@loader.value_ivar)
+    end
+
+    # Run the resolver once and write defaults for any record it skipped.
+    def resolve!
+      return if @resolved
+
+      @resolved = true
+      fulfilled = {}.compare_by_identity
+      fulfill = lambda do |record, value|
+        fulfilled[record] = true
+        record.instance_variable_set(@loader.value_ivar, value)
+      end
+
+      @loader.resolve(@model, @records, fulfill)
+
+      @records.each do |record|
+        next if fulfilled.key?(record)
+
+        record.instance_variable_set(@loader.value_ivar, @loader.default_for(record))
+      end
+    end
+  end
+end

data/lib/strict_lazy/errors.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  # Base error for the gem.
+  class Error < StandardError; end
+
+  # Raised when a lazy value is read without a preceding StrictLazy.preload
+  # while +violation+ is +:raise+ (the default in development/test).
+  class UnloadedError < Error; end
+end

data/lib/strict_lazy/facade.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  # The +.lazy+ namespace. Reading +record.lazy.x+ resolves a declared lazy
+  # value without ever growing a bare +x+ method on the record itself.
+  #
+  # Read order:
+  #   1. +@_lazy_<reader>+ already set  -> return it (resolved / eager / group-resolved)
+  #   2. +@_batch_<reader>+ present     -> resolve the whole group once, return it
+  #   3. no batch and violation :raise  -> UnloadedError (no wasted query)
+  #   4. no batch and non-strict        -> degraded single-record resolve (fallback)
+  class Facade
+    def initialize(record)
+      @record = record
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      loaders.key?(name) || super
+    end
+
+    def method_missing(name, *args)
+      loader = loaders[name]
+      return super unless loader
+
+      return @record.instance_variable_get(loader.value_ivar) if @record.instance_variable_defined?(loader.value_ivar)
+
+      batch = @record.instance_variable_get(loader.batch_ivar)
+      return batch.value_for(@record) if batch
+
+      unloaded(loader)
+    end
+
+    private
+
+    def loaders
+      @record.class.lazy_loaders
+    end
+
+    # No preceding preload reached this record. Consult the effective policy
+    # (a with_violation override, else the global baseline).
+    def unloaded(loader)
+      case StrictLazy.violation
+      when :raise
+        raise UnloadedError, "#{@record.class}##{loader.reader} was read without a preceding " \
+                             "StrictLazy.preload. Add it to the controller, or set " \
+                             "StrictLazy.violation to :log/:ignore."
+      when :log
+        logger&.warn("[StrictLazy] #{@record.class}##{loader.reader} read without preload (degraded to N+1)")
+      end
+
+      # :log and :ignore fall through to a degraded single-record resolve.
+      Batch.new(@record.class, [@record], loader).value_for(@record)
+    end
+
+    def logger
+      defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+    end
+  end
+end

data/lib/strict_lazy/loader.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  # Immutable definition produced by a +lazy_load+ declaration.
+  #
+  # It holds the reader name, the resolver (a +from:+ method symbol or a block),
+  # whether resolution is eager (+sync:+), and the +default+ used for records the
+  # resolver does not fulfill.
+  #
+  # Resolution always goes through +#resolve+, which is handed the model class so
+  # a +from:+ symbol can be dispatched as a class method. A block resolver is
+  # +instance_exec+'d on the model class for the same lookup semantics.
+  class Loader
+    # Internal ivar names are reserved per reader: +@_lazy_<reader>+ holds the
+    # resolved value, +@_batch_<reader>+ holds the shared Batch reference.
+    attr_reader :reader, :sync, :default
+
+    def initialize(reader:, sync:, default:, from: nil, block: nil)
+      @reader = reader
+      @sync = sync
+      @default = default
+      @from = from
+      @block = block
+      # The ivar name may not contain `?`, so a predicate reader is encoded
+      # (not stripped): +commented?+ and +commented+ get distinct ivars. (A bare
+      # reader literally named +commented_pred+ would collide, but reader names
+      # are validated to a bare-name/`?` form, making that pairing a non-idiom.)
+      ivar_key = reader.to_s.sub(/\?\z/, "_pred")
+      @value_ivar = :"@_lazy_#{ivar_key}"
+      @batch_ivar = :"@_batch_#{ivar_key}"
+    end
+
+    def sync? = @sync
+
+    attr_reader :value_ivar, :batch_ivar
+
+    # Invoke the resolver once over +records+. +loader+ is the
+    # +loader.call(record, value)+ callable supplied by the Batch.
+    def resolve(model, records, loader)
+      if @from
+        model.public_send(@from, records, loader)
+      else
+        model.instance_exec(records, loader, &@block)
+      end
+    end
+
+    # Compute the default for a record the resolver did not fulfill.
+    # A callable default acts as a per-record factory so mutable values
+    # (+[]+, +{}+) are never shared; arity 1 receives the record.
+    def default_for(record)
+      return @default unless @default.respond_to?(:call)
+
+      @default.arity.zero? ? @default.call : @default.call(record)
+    end
+  end
+end

data/lib/strict_lazy/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  # Sets the environment-appropriate +violation+ default: +:raise+ in
+  # development/test (catch missing preloads), +:ignore+ in production
+  # (degrade to N+1 rather than crash). Override with
+  # +config.strict_lazy.violation+. No middleware: values and batches live on
+  # the records and are GC'd with the request.
+  class Railtie < Rails::Railtie
+    config.strict_lazy = ActiveSupport::OrderedOptions.new
+
+    initializer "strict_lazy.set_violation" do |app|
+      default = Rails.env.production? ? :ignore : :raise
+      StrictLazy.violation = app.config.strict_lazy.violation || default
+    end
+  end
+end

data/lib/strict_lazy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StrictLazy
+  VERSION = "0.3.0"
+end

data/lib/strict_lazy.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/module/attribute_accessors_per_thread"
+
+require_relative "strict_lazy/version"
+require_relative "strict_lazy/errors"
+require_relative "strict_lazy/loader"
+require_relative "strict_lazy/batch"
+require_relative "strict_lazy/facade"
+
+# strict_lazy applies the spirit of Rails' +strict_loading+ to computed values.
+# Include it in a model, declare values with +lazy_load+, prepare them in the
+# controller with +StrictLazy.preload+, and read them via +record.lazy.x+.
+# Reading without a preceding preload raises in development/test.
+module StrictLazy
+  extend ActiveSupport::Concern
+
+  # The baseline policy, set globally (StrictLazy.violation=) or by the Railtie
+  # from the environment. with_violation overrides it for the current execution
+  # context only; the +violation+ reader returns the override-aware effective
+  # value. :raise (dev/test default), :log, or :ignore.
+  mattr_accessor :default_violation, default: :raise
+
+  # Fiber/Thread-local override stack for with_violation. thread_mattr_accessor
+  # is the public API (it honors config.active_support.isolation_level and
+  # isolates parallel test processes); we avoid the :nodoc:
+  # ActiveSupport::IsolatedExecutionState. Each thread starts at nil, so readers
+  # guard with `|| []`.
+  thread_mattr_accessor :violation_overrides, instance_accessor: false
+
+  # The accepted violation policies.
+  VALID_VIOLATIONS = %i[raise log ignore].freeze
+
+  # A valid reader is a bare name, optionally a `?` predicate. Setter (`=`),
+  # bang (`!`), and operator readers are rejected: the `.lazy` namespace is
+  # read-only, and any other form has no valid ivar to back it.
+  READER_FORMAT = /\A[A-Za-z_][A-Za-z0-9_]*\??\z/
+
+  included do
+    # Inherited by STI subclasses; merged (not mutated) on each declaration.
+    class_attribute :lazy_loaders, instance_writer: false, default: {}
+  end
+
+  class_methods do
+    # Declare a lazy-loaded value.
+    #
+    #   lazy_load :comments_count, default: 0 do |posts, loader|
+    #     ...
+    #   end
+    #
+    #   lazy_load :avatar, from: :resolve_avatar, sync: true
+    #
+    # Exactly one of +from:+ or a block is required (xor). +sync: true+ resolves
+    # eagerly at preload time; otherwise resolution is deferred to first read.
+    # +default+ is written for records the resolver does not fulfill; pass a
+    # callable for per-record (e.g. mutable) defaults.
+    def lazy_load(reader, from: nil, sync: false, default: nil, &block)
+      validate_lazy_load!(reader, from, block)
+
+      loader = Loader.new(reader: reader, sync: sync, default: default, from: from, block: block)
+      self.lazy_loaders = lazy_loaders.merge(reader => loader)
+    end
+
+    private
+
+    def validate_lazy_load!(reader, from, block)
+      raise ArgumentError, "lazy_load #{reader.inspect}: pass either `from:` or a block, not both" if from && block
+      raise ArgumentError, "lazy_load #{reader.inspect}: pass either `from:` or a block" unless from || block
+      unless READER_FORMAT.match?(reader.to_s)
+        raise ArgumentError, "lazy_load #{reader.inspect}: reader must be a bare name or a `?` predicate; " \
+                             "the `.lazy` namespace is read-only (no setters, bang, or operator readers)"
+      end
+
+      validate_from_defined!(reader, from)
+    end
+
+    def validate_from_defined!(reader, from)
+      return if from.nil? || respond_to?(from)
+
+      raise ArgumentError, "lazy_load #{reader.inspect}: `from: #{from.inspect}` is not defined on #{name}. " \
+                           "Define the class method before the lazy_load declaration."
+    end
+  end
+
+  # The +.lazy+ namespace facade (memoized per record).
+  def lazy
+    @_lazy_facade ||= Facade.new(self)
+  end
+
+  # The effective policy for the current execution context: the innermost
+  # with_violation override if any, otherwise the global baseline. The facade
+  # consults this — never read +default_violation+ directly.
+  def self.violation
+    (violation_overrides || []).last || default_violation
+  end
+
+  # Backward-compatible global setter. Sets the baseline only; it does not touch
+  # any active with_violation override. Existing callers (and the Railtie) keep
+  # working unchanged.
+  def self.violation=(mode)
+    self.default_violation = validate_violation!(mode)
+  end
+
+  # Run the block with +mode+ as the effective policy, restoring the previous
+  # state afterward (exception-safe). Overrides nest; an inner call shadows an
+  # outer one and unwinds cleanly. Scoped to the current Fiber/Thread, so
+  # parallel test processes never interfere.
+  #
+  #   StrictLazy.with_violation(:ignore) { ... }   # never raises inside
+  def self.with_violation(mode)
+    # Validate first: an invalid mode raises here, before the stack is touched,
+    # so the begin/ensure only ever runs against a successfully pushed frame.
+    validated = validate_violation!(mode)
+    begin
+      pushed = (violation_overrides || []) + [validated]
+      self.violation_overrides = pushed
+      yield
+    ensure
+      self.violation_overrides = pushed[0...-1]
+    end
+  end
+
+  def self.validate_violation!(mode)
+    return mode if VALID_VIOLATIONS.include?(mode)
+
+    raise ArgumentError, "StrictLazy violation must be one of #{VALID_VIOLATIONS.inspect}, got #{mode.inspect}"
+  end
+  private_class_method :validate_violation!
+
+  # Prepare lazy values for a group of records. With no readers, prepares every
+  # declared loader. +sync: true+ loaders resolve immediately; others on first read.
+  def self.preload(records, *readers)
+    records = Array(records)
+    return records if records.empty?
+
+    model = records.first.class
+    loaders_for(model, readers).each do |loader|
+      batch = Batch.new(model, records, loader)
+      records.each { |record| record.instance_variable_set(loader.batch_ivar, batch) }
+      batch.resolve! if loader.sync?
+    end
+
+    records
+  end
+
+  def self.loaders_for(model, readers)
+    all = model.lazy_loaders
+    readers.empty? ? all.values : readers.map { |r| all.fetch(r) }
+  end
+  private_class_method :loaders_for
+end
+
+require_relative "strict_lazy/railtie" if defined?(Rails::Railtie)

data/sig/strict_lazy.rbs

@@ -0,0 +1,4 @@
+module StrictLazy
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/skills/strict-lazy/SKILL-ja.md

@@ -0,0 +1,82 @@
+---
+name: strict-lazy
+description: "preload/includes では表現できない「計算値」(外部API・ウィンドウ関数・クロステーブル集計) の N+1 を、明示プリロード必須＋dev/test で未プリロード読み取りを raise して潰す strict_lazy gem の使い方。使う: (1) 一覧の N+1 を直す依頼で原因が association でなく集計/外部API/計算メソッドのとき、(2) そうした値の事前読み込みを実装するとき。association で表現できる N+1 は対象外 (includes/preload/strict_loading を使う)。"
+---
+
+# strict_lazy
+
+`strict_loading` を **計算値** に持ち込む gem。association で表現できない値をコントローラで明示プリロードさせ、未プリロード読み取りを dev/test で raise する。依存は `activesupport` のみ。
+
+## まず適用可否を判断する
+
+その値が `belongs_to`/`has_many` で表現できるなら strict_lazy ではなく標準解を使う。誤用すると無駄な複雑さが増える。
+
+| N+1 の原因 | 使う道具 |
+| --- | --- |
+| association を辿る | `includes` / `preload` / `eager_load` |
+| association の未ロード検出 | `strict_loading` / `bullet` |
+| **association で表現できない計算値** | **strict_lazy** |
+
+strict_lazy が向くのは preload で書けない値のみ:
+- 外部API: `Svc.bulk_fetch(ids)` のようにまとめて引けるもの
+- ウィンドウ関数・生SQL: `ROW_NUMBER() OVER (...)` など
+- クロステーブル集計: `group(:post_id).count` など（`counter_cache` で済むならそちらを優先）
+
+## 使い方（4点セット、欠けると動かない）
+
+### 1. モデルで宣言
+
+リゾルバは **ブロック** か **`from:`（クラスメソッド名）** の排他。どちらも `(records, loader)` を受け、解決できた各レコードで `loader.call(record, value)` を呼ぶ。**グループ全体に1回だけ走る**ので、ここで1クエリ/1API にまとめる。
+
+```ruby
+class Post < ApplicationRecord
+  include StrictLazy
+
+  lazy_load :comments_count, default: 0 do |posts, loader|
+    by_id = posts.index_by(&:id)
+    Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+      loader.call(by_id[post_id], n)
+    end
+  end
+
+  # from: は lazy_load より前に定義。FK 重複排除はリゾルバの責任（key: は無い）。
+  def self.resolve_avatar(posts, loader)
+    urls = AvatarService.bulk_fetch(posts.map(&:author_id).compact.uniq)
+    posts.each { |p| loader.call(p, urls[p.author_id]) }
+  end
+  lazy_load :avatar, from: :resolve_avatar, sync: true
+end
+```
+
+`loader.call` されなかったレコードには `default:` が入る（GROUP BY に出ない 0件 Post が `default: 0` になる仕組み）。
+
+### 2. コントローラでプリロード
+
+```ruby
+@posts = Post.recent                   # ActiveRecord::Relation のままでよい（.to_a 不要）
+StrictLazy.preload(@posts)             # 全ローダー。preload(@posts, :avatar) で一部のみ
+```
+
+ビューで読むコレクションと一致させる。`sync: false`（既定）は初回 `.lazy` 読みで一括解決＆メモ化、`sync: true` は preload 時点で即解決。
+
+### 3. ビューで `.lazy.` 経由で読む
+
+```erb
+<%= post.lazy.comments_count %>
+```
+
+素のメソッドは生えない。必ず `.lazy.` を挟む。
+
+### 4. プリロード忘れは raise
+
+未プリロード読み取り時の `violation`: `:raise`（既定 dev/test、無駄クエリなし）/ `:log`（warn 後 1件解決）/ `:ignore`（既定 prod、静かに 1件解決＝N+1）。上書きは `StrictLazy.violation=` か `config.strict_lazy.violation`。
+
+## 落とし穴
+
+- `.lazy.` 付け忘れ → 普通のメソッド/カラムを読みプリロードが効かない
+- `from:` を `lazy_load` より後に定義 → 宣言時に raise（ブロックは制約なし）
+- リゾルバを1件ずつ書く → N+1 が消えない。`records` 全体を1回でまとめる
+- `default: []` のような mutable 共有 → callable にする: `-> { [] }`（arity 0）/ `->(r) { ... }`（arity 1）。静的値はそのまま
+- preload グループとビューのコレクションがずれる → 未プリロードのレコードが raise
+
+詳細な引数・挙動は [references/api.md](references/api.md)。

data/skills/strict-lazy/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: strict-lazy
+description: "How to use the strict_lazy gem to eliminate N+1 for 'computed values' (external APIs, window functions, cross-table aggregations) that cannot be expressed with preload/includes — by requiring explicit preloads and raising on unpreloaded reads in dev/test. Use when: (1) fixing N+1 in a list where the cause is aggregation/external API/computed methods rather than associations, (2) implementing pre-loading for such values. Out of scope: N+1 expressible via associations (use includes/preload/strict_loading instead)."
+---
+
+# strict_lazy
+
+A gem that brings `strict_loading` to **computed values**. Forces controllers to explicitly preload values that cannot be expressed as associations, and raises on unpreloaded reads in dev/test. Only depends on `activesupport`.
+
+## First: determine applicability
+
+If the value can be expressed via `belongs_to`/`has_many`, use the standard solution instead of strict_lazy. Misuse adds unnecessary complexity.
+
+| N+1 cause | Tool |
+| --- | --- |
+| Traversing associations | `includes` / `preload` / `eager_load` |
+| Detecting unloaded associations | `strict_loading` / `bullet` |
+| **Computed values not expressible as associations** | **strict_lazy** |
+
+strict_lazy is only for values that can't be written with preload:
+- External APIs: things that can be fetched in bulk like `Svc.bulk_fetch(ids)`
+- Window functions / raw SQL: e.g. `ROW_NUMBER() OVER (...)`
+- Cross-table aggregations: e.g. `group(:post_id).count` (prefer `counter_cache` when it suffices)
+
+## Usage (4 required pieces — missing any one breaks it)
+
+### 1. Declare in the model
+
+The resolver is either a **block** or **`from:` (class method name)** — mutually exclusive. Both receive `(records, loader)` and call `loader.call(record, value)` for each resolved record. **Runs exactly once for the whole group**, so consolidate into 1 query/1 API call here.
+
+```ruby
+class Post < ApplicationRecord
+  include StrictLazy
+
+  lazy_load :comments_count, default: 0 do |posts, loader|
+    by_id = posts.index_by(&:id)
+    Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+      loader.call(by_id[post_id], n)
+    end
+  end
+
+  # from: must be defined before lazy_load. FK deduplication is the resolver's responsibility (no key: option).
+  def self.resolve_avatar(posts, loader)
+    urls = AvatarService.bulk_fetch(posts.map(&:author_id).compact.uniq)
+    posts.each { |p| loader.call(p, urls[p.author_id]) }
+  end
+  lazy_load :avatar, from: :resolve_avatar, sync: true
+end
+```
+
+Records not called with `loader.call` receive the `default:` value (how Posts with 0 comments get `default: 0` when absent from GROUP BY results).
+
+### 2. Preload in the controller
+
+```ruby
+@posts = Post.recent                   # an ActiveRecord::Relation is fine (no .to_a needed)
+StrictLazy.preload(@posts)             # all loaders. preload(@posts, :avatar) for a subset
+```
+
+Match the collection you read in the view. `sync: false` (default) resolves lazily on first `.lazy` read and memoizes; `sync: true` resolves immediately at preload time.
+
+### 3. Read via `.lazy.` in the view
+
+```erb
+<%= post.lazy.comments_count %>
+```
+
+No plain method is defined. Always go through `.lazy.`.
+
+### 4. Forgotten preloads raise
+
+`violation` on unpreloaded reads: `:raise` (default dev/test — no wasted queries) / `:log` (warn then resolve 1 record) / `:ignore` (default prod — silently resolves 1 record = N+1). Override with `StrictLazy.violation=` or `config.strict_lazy.violation`.
+
+## Pitfalls
+
+- Forgetting `.lazy.` → reads a normal method/column, preload has no effect
+- Defining `from:` after `lazy_load` → raises at declaration time (no restriction for blocks)
+- Writing the resolver one record at a time → N+1 persists. Use `records` to consolidate into one call
+- `default: []` and other mutable shared objects → use callable: `-> { [] }` (arity 0) / `->(r) { ... }` (arity 1). Static values are fine as-is
+- Preload group and view collection don't match → unpreloaded records raise
+
+For full argument details and behavior, see [references/api.md](references/api.md).

data/skills/strict-lazy/references/api-ja.md

@@ -0,0 +1,195 @@
+# strict_lazy API リファレンス
+
+SKILL.md の補足。`lazy_load` の全引数、`StrictLazy.preload`、`violation`、callable default の
+詳細挙動をまとめる。SKILL.md で全体像をつかんだ上で、引数の細部を確認したいときに読む。
+
+## 目次
+
+- [`lazy_load` の宣言](#lazy_load-の宣言)
+- [リゾルバ — ブロック vs `from:`](#リゾルバ--ブロック-vs-from)
+- [`sync:` — 遅延 vs 即時解決](#sync--遅延-vs-即時解決)
+- [`default:` — 未充足レコードの値](#default--未充足レコードの値)
+- [`StrictLazy.preload`](#strictlazypreload)
+- [`record.lazy` の読み取り順序](#recordlazy-の読み取り順序)
+- [`violation` ポリシー](#violation-ポリシー)
+- [ライフサイクルと内部 ivar](#ライフサイクルと内部-ivar)
+- [完全な実装例](#完全な実装例)
+
+## `lazy_load` の宣言
+
+```ruby
+lazy_load(reader, from: nil, sync: false, default: nil, &block)
+```
+
+- `reader` — `.lazy.<reader>` で読む名前 (Symbol)。同名の AR カラムがあっても衝突しない
+  (素のメソッドを生やさないため)。
+- `from:` と `&block` は **排他 (xor)**。両方渡す/どちらも渡さないと宣言時に `ArgumentError`。
+- `from:` に渡したメソッドが未定義だと宣言時に `ArgumentError` (「Define the class method
+  before the lazy_load declaration.」)。
+
+宣言は `class_attribute :lazy_loaders` にマージされ、**STI サブクラスに継承** される。
+
+## リゾルバ — ブロック vs `from:`
+
+どちらも **`(records, loader)` を受け取り、解決できた各レコードについて `loader.call(record, value)`
+を呼ぶ**。リゾルバはグループ全体に対して **1回** 実行される (1レコードずつではない)。
+
+ブロックリゾルバはモデルクラス上で `instance_exec` される (= `self` がモデルクラス):
+
+```ruby
+lazy_load :comments_count, default: 0 do |posts, loader|
+  by_id = posts.index_by(&:id)
+  Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+    loader.call(by_id[post_id], n)
+  end
+end
+```
+
+`from:` リゾルバはクラスメソッドとして `public_send` される。複雑/再利用するときに向く。
+**宣言より前に定義** すること:
+
+```ruby
+def self.resolve_avatar(posts, loader)
+  urls = AvatarService.bulk_fetch(posts.map(&:author_id).compact.uniq)
+  posts.each { |p| loader.call(p, urls[p.author_id]) }
+end
+lazy_load :avatar, from: :resolve_avatar, sync: true
+```
+
+FK の重複排除・ID→値のマッピングは **リゾルバの責任**。gem 側に `key:` のような仕組みはない。
+
+## `sync:` — 遅延 vs 即時解決
+
+- `sync: false` (デフォルト) — 最初の `.lazy` 読み取りまで解決を遅延。最初の読み取り時に
+  グループ全体を一気に解決してメモ化。一覧で1つも読まれなければクエリは0。
+- `sync: true` — `StrictLazy.preload` の時点で即解決。外部APIを早めに叩く/レスポンス前に
+  確実に取得しておきたいときに使う。
+
+どちらも結果はレコードの `@_lazy_<reader>` に乗り、2回目以降の読み取りはクエリ0。
+
+## `default:` — 未充足レコードの値
+
+リゾルバが `loader.call` を呼ばなかったレコードに書かれる値。
+
+- **静的値** (`default: 0`、`default: "n/a"`) — そのまま全レコードに書かれる。
+- **callable** — レコードごとに呼ばれる **ファクトリ**。mutable な値 (`[]`, `{}`) を共有しないために使う。
+  - arity 0: `default: -> { [] }` — 毎回新しいインスタンス。
+  - arity 1: `default: ->(record) { "post-#{record.id}" }` — レコードを受け取る。
+
+```ruby
+lazy_load :tags, default: -> { [] } do |records, loader| ... end       # 各レコードに別の []
+lazy_load :slug, default: ->(record) { "p-#{record.id}" } do ... end   # レコード依存の既定値
+```
+
+`default: []` のように mutable をそのまま渡すと全レコードで同一オブジェクトを共有してしまうので、
+必ず callable を使う。
+
+## `StrictLazy.preload`
+
+```ruby
+StrictLazy.preload(records, *readers)
+```
+
+- `records` — レコード配列 (単体も `Array()` でラップされる)。`ActiveRecord::Relation` もそのまま渡せる（内部の `Array()` が評価するので `.to_a` 不要）。空なら何もしない。
+- `readers` 省略時は **宣言済みの全ローダー** を準備。指定すると一部だけ。
+- 各ローダーについて `Batch` を作り、全レコードの `@_batch_<reader>` にセット。
+  `sync: true` のものはここで即 `resolve!`。
+- モデルは `records.first.class` から決まる。**同一モデルのレコード群** を渡す前提。
+
+注意: 同じローダーを **重複するグループに2回 preload** すると、その分リゾルバが複数回走る。
+ビューで読むコレクションを1回でカバーするように呼ぶ。
+
+### Relation をそのまま渡してよい理由
+
+`preload` は各レコードオブジェクトに `@_batch_<reader>` ivar を書き込むため、preload するレコードとビューで読むレコードは **同一オブジェクト** である必要がある。`Relation` はこれを満たす:
+
+1. `Array(relation)` が `relation.to_a` を発火させ、Relation をロードして **結果をキャッシュ** する（`relation.loaded? == true`）。
+2. ロード済みの同じ `Relation` を再列挙しても（ビューでの `@posts.each` など）、**キャッシュされた同一オブジェクト** が返る ── 再クエリも新規インスタンス生成も起きない。
+
+よって `@posts = Post.recent; StrictLazy.preload(@posts)` のあとビューで `@posts.each` すれば、batch ivar が仕込まれたまさにそのオブジェクトを読む。`preload` 内の `Array()` 呼び出しが副作用で Relation のキャッシュを温めるので、明示的な `.to_a` は要らない。
+
+唯一の注意点（上の「ビューで読むコレクションと一致させる」と同じ）: ビューで **別の Relation** を評価する ── 例えば `Post.recent` を preload したのにビューで再び `Post.recent` を新たなクエリとして回す ── と、batch ivar を持たない新規オブジェクトが生成され、`violation: :raise` では raise する。preload した Relation は変数に保持して使い回すこと。
+
+## `record.lazy` の読み取り順序
+
+`record.lazy.x` の解決は次の順 (`Facade#method_missing`):
+
+1. `@_lazy_<reader>` が既にセット済み → それを返す (解決済み/即時/グループ解決済み)。
+2. `@_batch_<reader>` がある → グループ全体を1回解決して返す (遅延解決)。
+3. batch がなく `violation: :raise` → `UnloadedError` (無駄クエリなし)。
+4. batch がなく非 strict → 1レコード解決に退化 (フォールバック、N+1)。
+
+`record.lazy` 自体は `Facade` を1回だけ生成してメモ化 (`@_lazy_facade`)。
+`record.lazy.respond_to?(:x)` は宣言済みローダーを反映する。
+
+## `violation` ポリシー
+
+プリロードなしで `.lazy.x` を読んだときの挙動 (上記の 3/4)。
+
+| mode | 挙動 |
+| --- | --- |
+| `:raise` | `StrictLazy::UnloadedError` を raise。無駄なクエリは出さない。 |
+| `:log` | `Rails.logger.warn("[StrictLazy] ... read without preload (degraded to N+1)")` の後、1レコード解決。 |
+| `:ignore` | 静かに1レコード解決 (N+1)。 |
+
+設定方法:
+
+- グローバル: `StrictLazy.violation = :log`
+- Rails: `config.strict_lazy.violation = :log` (Railtie が初期化時に反映)
+- Railtie の環境デフォルト: production → `:ignore`、それ以外 (development/test) → `:raise`
+
+`:raise` の狙いは「開発中にプリロード忘れで即落として気づかせる」、`:ignore` の狙いは
+「本番ではクラッシュさせず N+1 に退化させて動かし続ける」。
+
+## ライフサイクルと内部 ivar
+
+- `@_lazy_<reader>` — 解決済みの値。
+- `@_batch_<reader>` — グループ共有の `Batch` 参照。
+- `@_lazy_facade` — `.lazy` の `Facade` (メモ化)。
+
+すべてレコードのインスタンス変数なので、**リクエストと共に GC** される。thread-local キャッシュも
+ミドルウェアもグローバルなレジストリもない。`Batch` は値を各レコードの ivar に直接書くので
+中間 Hash を持たず、レコードの hash 等価性にも依存しない (= **未保存レコードでも動く**)。
+
+## 完全な実装例
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  include StrictLazy
+
+  # クロステーブル集計 (GROUP BY を1クエリに)
+  lazy_load :comments_count, default: 0 do |posts, loader|
+    by_id = posts.index_by(&:id)
+    Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+      loader.call(by_id[post_id], n)
+    end
+  end
+
+  # 外部API (ID をまとめて bulk_fetch、即時解決)
+  def self.resolve_avatar(posts, loader)
+    urls = AvatarService.bulk_fetch(posts.map(&:author_id).compact.uniq)
+    posts.each { |p| loader.call(p, urls[p.author_id]) }
+  end
+  lazy_load :avatar, from: :resolve_avatar, sync: true
+end
+```
+
+```ruby
+# app/controllers/posts_controller.rb
+def index
+  @posts = Post.recent         # ActiveRecord::Relation のままでよい（.to_a 不要）
+  StrictLazy.preload(@posts)   # comments_count と avatar を準備
+end
+```
+
+```erb
+<%# app/views/posts/index.html.erb %>
+<% @posts.each do |post| %>
+  <span><%= post.lazy.comments_count %></span>
+  <img src="<%= post.lazy.avatar %>">
+<% end %>
+```
+
+プリロードを忘れて `post.lazy.comments_count` を読むと、development/test では
+`StrictLazy::UnloadedError` が raise され、コントローラへの `StrictLazy.preload` 追加を促される。

data/skills/strict-lazy/references/api.md

@@ -0,0 +1,182 @@
+# strict_lazy API Reference
+
+Supplement to SKILL.md. Covers all `lazy_load` arguments, `StrictLazy.preload`, `violation`, and callable default behavior in detail. Read SKILL.md first for the big picture, then come here to check argument specifics.
+
+## Table of Contents
+
+- [`lazy_load` declaration](#lazy_load-declaration)
+- [Resolver — block vs `from:`](#resolver--block-vs-from)
+- [`sync:` — deferred vs immediate resolution](#sync--deferred-vs-immediate-resolution)
+- [`default:` — value for unresolved records](#default--value-for-unresolved-records)
+- [`StrictLazy.preload`](#strictlazypreload)
+- [Read order of `record.lazy`](#read-order-of-recordlazy)
+- [`violation` policy](#violation-policy)
+- [Lifecycle and internal ivars](#lifecycle-and-internal-ivars)
+- [Complete implementation example](#complete-implementation-example)
+
+## `lazy_load` declaration
+
+```ruby
+lazy_load(reader, from: nil, sync: false, default: nil, &block)
+```
+
+- `reader` — the name read via `.lazy.<reader>` (Symbol). No conflict with AR columns of the same name (because no plain method is defined).
+- `from:` and `&block` are **mutually exclusive (xor)**. Passing both or neither raises `ArgumentError` at declaration time.
+- If the method passed to `from:` is undefined, raises `ArgumentError` at declaration time ("Define the class method before the lazy_load declaration.").
+
+Declarations are merged into `class_attribute :lazy_loaders` and **inherited by STI subclasses**.
+
+## Resolver — block vs `from:`
+
+Both **receive `(records, loader)` and call `loader.call(record, value)` for each resolved record**. The resolver runs **once** for the whole group (not per record).
+
+Block resolvers are `instance_exec`'d on the model class (i.e., `self` is the model class):
+
+```ruby
+lazy_load :comments_count, default: 0 do |posts, loader|
+  by_id = posts.index_by(&:id)
+  Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+    loader.call(by_id[post_id], n)
+  end
+end
+```
+
+`from:` resolvers are called as class methods via `public_send`. Better for complex or reusable cases. **Must be defined before the declaration**:
+
+```ruby
+def self.resolve_avatar(posts, loader)
+  urls = AvatarService.bulk_fetch(posts.map(&:author_id).compact.uniq)
+  posts.each { |p| loader.call(p, urls[p.author_id]) }
+end
+lazy_load :avatar, from: :resolve_avatar, sync: true
+```
+
+FK deduplication and ID→value mapping are **the resolver's responsibility**. The gem has no `key:` mechanism.
+
+## `sync:` — deferred vs immediate resolution
+
+- `sync: false` (default) — defers resolution until the first `.lazy` read. At first read, resolves the entire group at once and memoizes. If nothing is read in the list, zero queries.
+- `sync: true` — resolves immediately at `StrictLazy.preload` time. Use when you want to hit an external API early or guarantee retrieval before the response.
+
+Either way, the result is stored in the record's `@_lazy_<reader>` ivar; subsequent reads are zero queries.
+
+## `default:` — value for unresolved records
+
+The value written to records that `loader.call` was never called for.
+
+- **Static values** (`default: 0`, `default: "n/a"`) — written to all records as-is.
+- **Callable** — a **factory** called per record. Use to avoid sharing mutable values (`[]`, `{}`) across records.
+  - arity 0: `default: -> { [] }` — new instance every time.
+  - arity 1: `default: ->(record) { "post-#{record.id}" }` — receives the record.
+
+```ruby
+lazy_load :tags, default: -> { [] } do |records, loader| ... end       # separate [] per record
+lazy_load :slug, default: ->(record) { "p-#{record.id}" } do ... end   # record-dependent default
+```
+
+Passing a mutable value directly like `default: []` shares the same object across all records — always use a callable instead.
+
+## `StrictLazy.preload`
+
+```ruby
+StrictLazy.preload(records, *readers)
+```
+
+- `records` — array of records (single records are wrapped with `Array()`). An `ActiveRecord::Relation` can also be passed directly — the internal `Array()` evaluates it (no `.to_a` needed). Does nothing if empty.
+- When `readers` is omitted, **all declared loaders** are prepared. Specify to prepare only a subset.
+- Creates a `Batch` for each loader and sets it on `@_batch_<reader>` for all records. Loaders with `sync: true` are immediately `resolve!`'d here.
+- The model is determined from `records.first.class`. Assumes a **group of records of the same model**.
+
+Note: **preloading the same loader for overlapping groups twice** causes the resolver to run multiple times. Call it once to cover the collection you read in the view.
+
+### Why passing a `Relation` directly works
+
+`preload` writes the `@_batch_<reader>` ivar onto each record object, so the records you preload and the records you read in the view must be the **same objects**. A `Relation` satisfies this:
+
+1. `Array(relation)` triggers `relation.to_a`, which loads the relation and **caches the result** (`relation.loaded? == true`).
+2. Re-iterating the same loaded `Relation` (e.g. `@posts.each` in the view) returns the **same cached objects** — not a re-query, not new instances.
+
+So `@posts = Post.recent; StrictLazy.preload(@posts)` then `@posts.each` in the view reads the very objects that got the batch ivar. The `Array()` call inside `preload` warms the relation's cache as a side effect, so no explicit `.to_a` is needed.
+
+The one caveat (same as the "match the collection" rule above): evaluating a **different** relation in the view — e.g. preloading `Post.recent` but iterating `Post.recent` again as a fresh query — produces new objects without the batch ivar, which then raise under `violation: :raise`. Keep the preloaded relation in a variable and reuse it.
+
+## Read order of `record.lazy`
+
+Resolution order for `record.lazy.x` (`Facade#method_missing`):
+
+1. `@_lazy_<reader>` already set → return it (already resolved / sync / group-resolved).
+2. `@_batch_<reader>` present → resolve the whole group once and return (lazy resolution).
+3. No batch and `violation: :raise` → raise `UnloadedError` (no wasted queries).
+4. No batch and non-strict → degrade to 1-record resolution (fallback, N+1).
+
+`record.lazy` itself generates a `Facade` once and memoizes it (`@_lazy_facade`).
+`record.lazy.respond_to?(:x)` reflects declared loaders.
+
+## `violation` policy
+
+Behavior when `.lazy.x` is read without a preload (cases 3/4 above).
+
+| mode | behavior |
+| --- | --- |
+| `:raise` | Raises `StrictLazy::UnloadedError`. No wasted queries. |
+| `:log` | `Rails.logger.warn("[StrictLazy] ... read without preload (degraded to N+1)")`, then resolves 1 record. |
+| `:ignore` | Silently resolves 1 record (N+1). |
+
+Configuration:
+
+- Global: `StrictLazy.violation = :log`
+- Rails: `config.strict_lazy.violation = :log` (Railtie applies at initialization)
+- Railtie environment defaults: production → `:ignore`, everything else (development/test) → `:raise`
+
+The intent of `:raise` is "fail fast during development when a preload is missing"; `:ignore` is "don't crash in production, degrade to N+1 and keep running".
+
+## Lifecycle and internal ivars
+
+- `@_lazy_<reader>` — the resolved value.
+- `@_batch_<reader>` — shared `Batch` reference for the group.
+- `@_lazy_facade` — the `Facade` for `.lazy` (memoized).
+
+All are instance variables on the record, so they are **GC'd with the request**. No thread-local cache, no middleware, no global registry. `Batch` writes values directly to each record's ivar, so it holds no intermediate Hash and does not depend on record hash equality (= **works with unsaved records**).
+
+## Complete implementation example
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  include StrictLazy
+
+  # Cross-table aggregation (1 query via GROUP BY)
+  lazy_load :comments_count, default: 0 do |posts, loader|
+    by_id = posts.index_by(&:id)
+    Comment.where(post_id: by_id.keys).group(:post_id).count.each do |post_id, n|
+      loader.call(by_id[post_id], n)
+    end
+  end
+
+  # External API (bulk_fetch IDs together, immediate resolution)
+  def self.resolve_avatar(posts, loader)
+    urls = AvatarService.bulk_fetch(posts.map(&:author_id).compact.uniq)
+    posts.each { |p| loader.call(p, urls[p.author_id]) }
+  end
+  lazy_load :avatar, from: :resolve_avatar, sync: true
+end
+```
+
+```ruby
+# app/controllers/posts_controller.rb
+def index
+  @posts = Post.recent         # an ActiveRecord::Relation is fine (no .to_a needed)
+  StrictLazy.preload(@posts)   # prepares comments_count and avatar
+end
+```
+
+```erb
+<%# app/views/posts/index.html.erb %>
+<% @posts.each do |post| %>
+  <span><%= post.lazy.comments_count %></span>
+  <img src="<%= post.lazy.avatar %>">
+<% end %>
+```
+
+If you forget the preload and read `post.lazy.comments_count`, development/test raises
+`StrictLazy::UnloadedError`, prompting you to add `StrictLazy.preload` in the controller.

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: strict_lazy
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- aki77
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: |
+  strict_lazy applies the spirit of Rails' strict_loading to computed values
+  (external APIs, window functions, cross-table aggregates) that associations
+  cannot express. It forces explicit preloading and raises on unloaded access
+  in development/test, so hidden per-record queries never slip into views.
+  No batch-loader / N1Loader / ar_lazy_preload dependency — activesupport only.
+email:
+- aki77@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/strict_lazy.rb
+- lib/strict_lazy/batch.rb
+- lib/strict_lazy/errors.rb
+- lib/strict_lazy/facade.rb
+- lib/strict_lazy/loader.rb
+- lib/strict_lazy/railtie.rb
+- lib/strict_lazy/version.rb
+- sig/strict_lazy.rbs
+- skills/strict-lazy/SKILL-ja.md
+- skills/strict-lazy/SKILL.md
+- skills/strict-lazy/references/api-ja.md
+- skills/strict-lazy/references/api.md
+homepage: https://github.com/aki77/strict_lazy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aki77/strict_lazy
+  source_code_uri: https://github.com/aki77/strict_lazy
+  changelog_uri: https://github.com/aki77/strict_lazy/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Strict, explicit preloading for computed values — raise on unloaded access
+  instead of silent N+1.
+test_files: []