weft 0.1.0 → 0.2.0

data/lib/weft/dsl/actions.rb

@@ -12,12 +12,12 @@ module Weft
       module ClassMethods
         # Declare a user-initiated action on this component.
         #
-        #   performs :advance do |attrs|
-        #     order = Order.find(attrs.order_id)
+        #   performs :advance do |params|
+        #     order = Order.find(params.order_id)
         #     Oms::PrepareOrder.call(order)
         #   end
         #
-        #   performs method: :delete, swap: :delete do |attrs| ... end
+        #   performs method: :delete, swap: :delete do |params| ... end
         def performs(name = nil, method: :post, swap: :outer_html, target: nil, &block)
           action = Weft::Action.new(name: name, method: method, swap: swap,
                                     target: target, renders: self, callable: block)
@@ -26,19 +26,19 @@ module Weft
 
         # Sugar for performs with swap: :delete. Removes the component from
         # the DOM on success. The callable (if given) runs for side effects;
-        # the return value is rendered but htmx ignores the response body.
+        # the success response carries no body (OOB includes still ride).
         #
         #   dismisses :close                          # no side effects
-        #   dismisses :remove do |attrs|              # with side effects
-        #     Item.find(attrs.item_id).archive!
+        #   dismisses :remove do |params|             # with side effects
+        #     Item.find(params.item_id).archive!
         #   end
-        def dismisses(name = nil, method: :delete, &)
-          performs(name, method: method, swap: :delete, &)
+        def dismisses(name = nil, method: :delete, target: nil, &)
+          performs(name, method: method, swap: :delete, target: target, &)
         end
 
         # Declare a transfer — an action that renders a different component.
         #
-        #   transfers :edit, to: EditableOrderHeader do |attrs|
+        #   transfers :edit, to: EditableOrderHeader do |params|
         #     { mode: "full" }
         #   end
         def transfers(name = nil, to:, method: :post, swap: :outer_html, target: nil, &block)

data/lib/weft/dsl/inclusions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "weft/error"
+
 module Weft
   module DSL
     # Mixin for classes that declare OOB-swapped sibling components.
@@ -12,21 +14,42 @@ module Weft
       end
 
       module ClassMethods
+        # Contexts a `when:` filter may name. Only :transferred ships today;
+        # the vocabulary grows deliberately.
+        WHEN_VALUES = %i[transferred].freeze
+
         # Declare that another component should be OOB-swapped alongside
-        # this component's action responses and SSE pushes.
+        # this component's responses.
         #
-        #   includes OrderHeader                          # pass-through attrs
-        #   includes OrderHeader, on: :advance            # only on :advance action
-        #   includes OrderHeader do |attrs|               # explicit attr mapping
-        #     { order_id: attrs.order_id, compact: true }
+        #   includes OrderHeader                          # every response
+        #   includes OrderHeader, on: :advance            # own action(s) only
+        #   includes OrderHeader, on: %i[advance retreat]
+        #   includes OrderHeader, when: :transferred      # transfer arrivals only
+        #   includes OrderHeader, on: :save, when: :transferred   # union: either
+        #   includes OrderHeader do |params|              # companion delta
+        #     { order_id: params.order_id, compact: true }
         #   end
         #
-        # Without a block, the included component resolves from the same
-        # request params as the primary component. With a block, the block
-        # receives the primary component's resolved attrs and returns wire
-        # attrs for the included component's Resolver.
-        def includes(component_class, on: nil, &block)
-          own_inclusions << { component_class: component_class, on: on, block: block }
+        # Unfiltered inclusions ride every response this component renders in:
+        # its own actions, SSE pushes, and transfer arrivals. Filters
+        # enumerate contexts — `on:` names this component's OWN actions
+        # (never a transferring component's), `when: :transferred` fires when
+        # this component renders as a transfer target; declaring both is a
+        # union. The block's return is a DELTA overlaid on the request for
+        # this companion alone; blockless is exactly an empty delta.
+        #
+        # (`when` rides **options because it's a Ruby reserved word — call
+        # sites are unaffected, only this signature is.)
+        def includes(component_class, on: nil, **options, &block)
+          when_filter = options.delete(:when)
+          raise ArgumentError, "unknown keywords: #{options.keys.inspect}" unless options.empty?
+
+          site = caller_locations(1, 1).first
+          own_inclusions << { component_class: component_class,
+                              on: on.nil? ? nil : Array(on),
+                              when: validated_when(when_filter),
+                              block: block,
+                              source_location: [site.path, site.lineno] }
         end
 
         # All declared inclusions (own + inherited).
@@ -40,6 +63,20 @@ module Weft
 
         private
 
+        def validated_when(value)
+          return nil if value.nil?
+
+          contexts = Array(value)
+          unknown = contexts - WHEN_VALUES
+          unless unknown.empty?
+            raise Weft::InvalidDefinition,
+                  "includes when: #{unknown.map(&:inspect).join(', ')} names no known context — " \
+                  "recognized: #{WHEN_VALUES.map(&:inspect).join(', ')}"
+          end
+
+          contexts
+        end
+
         def own_inclusions
           @own_inclusions ||= []
         end

data/lib/weft/dsl/params.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "weft/error"
+require "weft/params/assembly"
+
+module Weft
+  module DSL
+    # Mixin for classes that declare consumed inputs — the doors into `params`.
+    # Provides the `param` (wire), `receives` (caller hand-off), and `derives`
+    # (lazy server-side derivation) class DSL and the `params` instance reader.
+    # Used by Component (for partial route params) and Page (for page route params).
+    module Params
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Declare a wire param. `default:` fills the key when no source
+        # supplies it; `type:` coerces the wire's string into the declared
+        # type (see Resolver::TYPES). The two are orthogonal — an untyped
+        # param accepts any value uncoerced — but a non-nil default must
+        # already be an instance of the declared type.
+        #   param :page, type: :integer
+        #   param :status, default: "active", type: :string
+        def param(name, default: nil, type: nil)
+          validate_type!(name, type, default) unless type.nil?
+          meta = { default: default }
+          meta[:type] = type unless type.nil?
+          own_params[name] = meta
+        end
+
+        # Returns all declared params (own + inherited), preserving declaration order.
+        def params
+          if superclass.respond_to?(:params)
+            superclass.params.merge(own_params)
+          else
+            own_params.dup
+          end
+        end
+
+        # Declare a hand-off param: the caller provides the value as a builder
+        # kwarg at the call site; it lands in `params`, never in HTML chrome.
+        #   receives :order                  # required — absence raises
+        #   receives :page_num, default: 1   # optional — any declared default
+        #                                    # (even nil) softens absence
+        # Hand-offs are server-side values: they never serialize into URLs and
+        # don't make a component routable.
+        def receives(name, **options)
+          meta = {}
+          meta[:default] = options[:default] if options.key?(:default)
+          own_received_params[name] = meta
+        end
+
+        # All declared hand-offs (own + inherited), preserving declaration
+        # order. Kept separate from `params` — the wire door and the hand-off
+        # door differ in serialization and routability, even for dual keys.
+        def received_params
+          if superclass.respond_to?(:received_params)
+            superclass.received_params.merge(own_received_params)
+          else
+            own_received_params.dup
+          end
+        end
+
+        # Declare a lazy server-side derivation: the block runs (at most once
+        # per render) when `params.name` is first read, never if it isn't.
+        #   derives(:order) { |params| Order.find(params.order_id) }
+        # The block is a `(params) -> value` pure function with a void self.
+        # Derived values are server-side: never serialized, not
+        # routable-making.
+        def derives(name, &block)
+          unless block
+            raise Weft::InvalidDefinition,
+                  "derives #{name.inspect} requires a block — the derivation is the declaration"
+          end
+
+          own_derived_params[name] = { block: block, source_location: block.source_location }
+        end
+
+        # Sugar for statically-known derivations: each pair registers
+        # `derives(key) { value }`. This is just `derives` — identical
+        # priority, overridability, and laziness; only the value is fixed at
+        # declaration. For anything computed per render (queries, clocks),
+        # use `derives` — an interpolated value here would freeze at
+        # class-load time.
+        #   defines label: "Drivers", accent: "available"
+        def defines(pairs)
+          site = caller_locations(1, 1).first
+          pairs.each do |name, value|
+            own_derived_params[name] = { block: proc { |_p| value },
+                                         source_location: [site.path, site.lineno] }
+          end
+        end
+
+        # Every key this class declares, whichever door it came through —
+        # what a bag assembled for this class will hold entries for.
+        def declared_keys
+          params.keys | received_params.keys | derived_params.keys
+        end
+
+        # All declared derivations (own + inherited), preserving declaration
+        # order. A child redeclaring a parent's key replaces the block, like
+        # a method override.
+        def derived_params
+          if superclass.respond_to?(:derived_params)
+            superclass.derived_params.merge(own_derived_params)
+          else
+            own_derived_params.dup
+          end
+        end
+
+        private
+
+        def validate_type!(name, type, default)
+          entry = Weft::Resolver::TYPES[type]
+          unless entry
+            raise Weft::InvalidDefinition,
+                  "param #{name.inspect} declares unknown type #{type.inspect} — declarable " \
+                  "types are #{Weft::Resolver::TYPES.keys.map(&:inspect).join(', ')}"
+          end
+          return if default.nil? || entry[:classes].any? { |klass| default.is_a?(klass) }
+
+          raise Weft::InvalidDefinition,
+                "param #{name.inspect} declares type #{type.inspect} but its default " \
+                "#{default.inspect} is #{default.class} — make them agree, or drop one"
+        end
+
+        def own_params
+          @own_params ||= {}
+        end
+
+        def own_received_params
+          @own_received_params ||= {}
+        end
+
+        def own_derived_params
+          @own_derived_params ||= {}
+        end
+      end
+
+      # One-time chrome-collision warnings, keyed [class, key].
+      # See #warn_declared_chrome_collisions.
+      def self.warned_collisions
+        @warned_collisions ||= Set.new
+      end
+
+      # Instance access to the resolved bag.
+      # Returns a Weft::Params object with method-style and hash access.
+      attr_reader :params
+
+      # @api private
+      # The bag projected onto this class's own declared wire schema — the
+      # only slice that serializes (refresh/stream URLs, DOM ids, hx-vals).
+      # Hand-offs and inherited values are server-side and never ride the
+      # wire. Per-key reads, NOT to_h: serialization must never materialize
+      # non-wire derivations (a thunk on a wire-schema key — the rare
+      # param+derives dual — does force here; the refresh contract wins).
+      def serializable_params
+        return {} unless params
+
+        self.class.params.keys.to_h { |key| [key, params[key]] }
+      end
+
+      private
+
+      # Assemble the bag per the source stack: staged hand-off > own wire
+      # value > inherited bag value > declared default. Staging only happens
+      # under Weft::Context; in a plain Arbre context the hand-off door is a
+      # build-top fallback instead, so hand-off validation waits for it there.
+      def assembled_params
+        if arbre_context.respond_to?(:take_received!)
+          resolve_bag(received: arbre_context.take_received!(self.class) || {}, validate: true)
+        else
+          resolve_bag(received: {}, validate: false)
+        end
+      end
+
+      def resolve_bag(received:, validate:)
+        bag = Weft::Params::Assembly.call(self.class, wire_source,
+                                          hand_offs: received,
+                                          overlays: context_overlays, branched_from: inherited_bag)
+        validate_hand_offs!(bag) if validate
+        bag
+      end
+
+      def context_overlays
+        arbre_context.respond_to?(:overlays) ? arbre_context.overlays : {}
+      end
+
+      # Checks required_hand_off? before reading the key: a required hand-off
+      # is receives-only (never thunked), so the read can't force anything —
+      # and dual keys short-circuit without touching their lazy derivation.
+      def validate_hand_offs!(bag)
+        self.class.received_params.each_key do |key|
+          raise_not_received!(key) if required_hand_off?(key) && bag[key].nil?
+        end
+      end
+
+      def wire_source
+        arbre_context.respond_to?(:wire_params) ? arbre_context.wire_params : {}
+      end
+
+      # Branch a copy of the nearest tree-ancestor's bag — the in-page
+      # parent-child axis: a component sees everything above it, nothing
+      # beside it. At construction the current element IS the future parent,
+      # so the walk works before the tree links this instance in. Returns
+      # [data, provenance]; the copy is thunk-preserving (never forces the
+      # ancestor's lazy entries) and nil-dropping. A root with no tree
+      # ancestor falls back to the context's branch bag — how an OOB
+      # companion inherits from the primary it rides alongside, and how the
+      # state a request has already composed reaches the component it renders.
+      def inherited_bag
+        el = arbre_context.current_arbre_element
+        while el
+          return el.params if el.is_a?(Weft::DSL::Params) && el.params
+
+          el = el.parent
+        end
+        arbre_context.respond_to?(:branch_bag) ? arbre_context.branch_bag : nil
+      end
+
+      # A hand-off is required when `receives` is its only door and no
+      # default was declared — nothing else can satisfy the presumption.
+      def required_hand_off?(key)
+        meta = self.class.received_params[key]
+        meta && !meta.key?(:default) && !self.class.params.key?(key)
+      end
+
+      def raise_not_received!(key)
+        raise Weft::NotReceived,
+              "#{self.class.name} expects to receive #{key.inspect}: pass it as a builder kwarg " \
+              "at the call site, or declare a default: to make it optional"
+      end
+
+      # Build-top fallback for the hand-off door in plain Arbre contexts,
+      # where interception never runs: pull receives-declared kwargs out of
+      # the attributes hash (they're hand-offs, not chrome), overlay them on
+      # the bag, and run the validation construction had to defer. Handed
+      # nil counts as absence, like everywhere else in the stack.
+      def apply_received_fallback(attributes)
+        keys = self.class.received_params.keys & attributes.keys
+        handed = keys.to_h { |k| [k, attributes.delete(k)] }
+        @params = @params.overlay(handed.compact)
+        validate_hand_offs!(@params)
+      end
+
+      # A builder kwarg naming a declared param renders as an HTML attribute
+      # only (params arrive from the wire, not the call site). Warn once per
+      # (class, key): param names legitimately collide with HTML attribute
+      # names (height, title, size, ...), so a standing collision shouldn't
+      # spam every render. Set#add? races just double-warn; harmless.
+      def warn_declared_chrome_collisions(attributes)
+        attributes.each_key do |key|
+          next unless self.class.params.key?(key)
+          next unless Weft::DSL::Params.warned_collisions.add?([self.class, key])
+
+          Weft.logger.warn(
+            "#{self.class.name}: builder kwarg #{key.inspect} matches a declared param and " \
+            "renders as an HTML attribute only (params arrive from the wire, not the call site)"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/weft/dsl/recoveries.rb

@@ -15,22 +15,27 @@ module Weft
       module ClassMethods
         # Declare a recovery edge: how this class handles a specific error.
         #
-        #   recovers from: Weft::Unprocessable do |attrs, error|
+        #   recovers from: Weft::Unprocessable do |params, error|
         #     { error_messages: error.messages }
         #   end
         #
         #   recovers from: Weft::Unauthorized, with: LoginPage
+        #   recovers from: ActiveRecord::RecordNotFound, with: NotFoundPage, status: 404
         #
         # `from:` accepts a Class (subclass-inclusive), Integer (matched against
         # HTTPError#status), Range, or Array of any of the above.
         # `with:` accepts a Class (Page or Component) or Symbol (resolved against
         # Weft.configuration at error-handling time). Default: self.
-        # The optional block receives `|attrs, error|` and returns a hash of
-        # additional attrs that merge with the original on the recovery edge.
-        # Symmetric with performs/transfers contracts (attrs first; error is the
+        # `status:` declares what the error means on the wire — recoveries from
+        # errors that aren't Weft::HTTPErrors report 500 without it. Must be an
+        # HTTP error status (400..599); raises Weft::InvalidUsage otherwise.
+        # The optional block receives `|params, error|` and returns a hash of
+        # additional params that merge with the original on the recovery edge.
+        # Symmetric with performs/transfers contracts (params first; error is the
         # recovery-specific extra). The block never returns HTML.
-        def recovers(from:, with: nil, &block)
-          own_recoveries << { from: from, with: with, block: block }
+        def recovers(from:, with: nil, status: nil, &block)
+          validate_recovery_status!(status)
+          own_recoveries << { from: from, with: with, status: status, block: block }
         end
 
         # All declared recovery entries (own + inherited), in resolution order.
@@ -53,6 +58,18 @@ module Weft
           recoveries.find { |entry| recovery_matches?(entry[:from], exception) }
         end
 
+        # Like recovery_for, but skips entries whose target resolves to a Page —
+        # for contexts that can only render component fragments (an SSE push
+        # can't redirect or full-page swap). The gem-default StandardError
+        # entry at the bottom of every component chain resolves to a component,
+        # so StandardError-family exceptions always find a match.
+        def component_recovery_for(exception)
+          recoveries.find do |entry|
+            recovery_matches?(entry[:from], exception) &&
+              !page_recovery_target?(resolve_recovery_target(entry))
+          end
+        end
+
         # Resolve the recovery entry's `with:` value to a concrete target class.
         # Symbol values look up `Weft.configuration.<sym>` (resolved at error-handling
         # time so config reassignment propagates). Nil falls back to self.
@@ -70,6 +87,15 @@ module Weft
           @own_recoveries ||= []
         end
 
+        # Declarations raise (a bad status is a coding bug, visible at load);
+        # only error semantics are assignable — a recovery can't claim success.
+        def validate_recovery_status!(status)
+          return if status.nil? || (status.is_a?(Integer) && (400..599).cover?(status))
+
+          raise Weft::InvalidUsage,
+                "recovers status: must be an HTTP error status (400..599); got #{status.inspect}"
+        end
+
         def recovery_matches?(from_clause, exception)
           case from_clause
           when Array   then from_clause.any? { |f| recovery_matches?(f, exception) }
@@ -83,6 +109,10 @@ module Weft
         def recovery_status_of(exception)
           exception.is_a?(Weft::HTTPError) ? exception.status : 500
         end
+
+        def page_recovery_target?(target)
+          target.is_a?(Class) && defined?(Weft::Page) && target <= Weft::Page
+        end
       end
     end
   end

data/lib/weft/dsl/sandbox.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Weft
+  module DSL
+    # The `self` a verb block runs against — a "void context": empty of
+    # anything component-specific, so a block cannot reach local state and is
+    # portable to any process. Verb blocks (`derives`, `performs`, `transfers`,
+    # `recovers`, `includes`) are `(params) -> value` pure functions: their
+    # arguments and return value are explicit, constants resolve lexically, and
+    # Kernel stays reachable (raise, format, Integer()).
+    #
+    # Each execution runs in a fresh instance, dropped once the return value is
+    # captured — so a block may use scratch instance variables freely, but that
+    # scratch never leaks past its own execution. Instances are deliberately
+    # unfrozen (scratch is allowed) yet non-leaking (freshness, not freezing,
+    # is what isolates them); a future +register_helpers+ facility would add
+    # vocabulary here without changing that contract.
+    class Sandbox
+      # Run a block in a fresh sandbox and return its value. Extra arguments
+      # after +params+ ride through to the block (recovery blocks take
+      # +(params, error)+). Each call gets its own instance by construction, so
+      # no caller can reuse one across executions.
+      def self.run(...) = new.instance_exec(...)
+    end
+  end
+end

data/lib/weft/dsl/triggers.rb

@@ -12,23 +12,43 @@ module Weft
       end
 
       module ClassMethods
-        # Declare an event to trigger on all action responses for this component.
+        # Declare an event this component announces on its action responses.
         # Sets the HX-Trigger response header.
         #
-        #   triggers "order-updated"
-        def triggers(event_name)
-          own_triggers << event_name.to_s
+        #   triggers "order-updated"                     # every action
+        #   triggers "order-updated", on: :advance       # that action only
+        #   triggers "moved", on: %i[advance retreat]
+        #
+        # `on:` maps the event to the actions it belongs to. Without it an
+        # event is welded to every action the component has, which is rarely
+        # what a component with more than one action means.
+        #
+        # There is deliberately no `when:` counterpart: HX-Trigger announces
+        # what a callable did, so a render-context filter has nothing to say
+        # about it.
+        def triggers(event_name, on: nil)
+          own_triggers << { event: event_name.to_s, on: on.nil? ? nil : Array(on) }
         end
 
-        # All declared trigger events (own + inherited).
-        def trigger_events
-          if superclass.respond_to?(:trigger_events)
-            superclass.trigger_events | own_triggers
+        # All declared trigger entries (own + inherited), ancestry first.
+        def trigger_declarations
+          if superclass.respond_to?(:trigger_declarations)
+            superclass.trigger_declarations + own_triggers
           else
             own_triggers.dup
           end
         end
 
+        # The event names that fire for one action. Unfiltered declarations
+        # fire on every action, including the nameless one; a subclass can
+        # therefore widen an inherited filter by redeclaring the event
+        # unfiltered, and duplicates collapse.
+        def trigger_events(action_name = nil)
+          trigger_declarations.
+            select { |trigger| trigger[:on].nil? || trigger[:on].include?(action_name) }.
+            map { |trigger| trigger[:event] }.uniq
+        end
+
         private
 
         def own_triggers

data/lib/weft/dsl/updates.rb

@@ -30,19 +30,30 @@ module Weft
 
         # Declare that this component pushes updates via SSE.
         #
-        #   pushes every: 5.seconds   # server pushes on interval
+        #   pushes every: 5.seconds                  # server pushes on interval
+        #   pushes every: 5.seconds, attempts: 5     # custom failure budget
+        #   pushes every: 5.seconds, immediate: false # wait a full interval first
         #
-        # Generates hx-ext="sse", sse-connect, sse-swap on the wrapper element.
-        # The Router auto-generates a streaming endpoint at
+        # Generates hx-ext="sse", sse-connect, sse-swap, sse-close on the
+        # wrapper element. The Router auto-generates a streaming endpoint at
         # /component_path/_stream (the suffix is the stream_suffix config knob).
+        # `attempts:` overrides Weft.configuration.push_attempts — consecutive
+        # failed pushes tolerated before the Router closes the stream.
+        # `immediate:` defaults to true (new subscribers get a state snapshot
+        # right away); `immediate: false` opts back into polling-cadence
+        # semantics — first frame after one interval — for components whose
+        # current state would mislead a fresh subscriber.
         #
         # Future: pushes on: "event-name" for event-driven server push (v1.0).
-        def pushes(every: nil)
+        def pushes(every: nil, attempts: nil, immediate: nil)
           @push_config = {}
-          return unless every
-
-          ms = interval_in_ms(every, :pushes)
-          @push_config[:every] = (ms % 1000).zero? ? ms / 1000 : ms / 1000.0
+          if every
+            ms = interval_in_ms(every, :pushes)
+            @push_config[:every] = (ms % 1000).zero? ? ms / 1000 : ms / 1000.0
+          end
+          @push_config[:attempts] = validated_attempts(attempts) if attempts
+          # nil-guarded, not truthiness: `immediate: false` must persist.
+          @push_config[:immediate] = immediate unless immediate.nil?
         end
 
         # Push configuration (own or inherited). Returns nil if no pushes declared.
@@ -69,6 +80,18 @@ module Weft
           @own_refresh_triggers ||= []
         end
 
+        # A budget below one failed push makes no sense — the stream would
+        # close before its first recovery frame; rather than raise
+        # mid-declaration, clamp and say so.
+        def validated_attempts(attempts)
+          return attempts if attempts.is_a?(Integer) && attempts >= 1
+
+          Weft.logger.warn(
+            "#{name} declares `pushes attempts: #{attempts.inspect}`, not a positive integer; using 1"
+          )
+          1
+        end
+
         # htmx's smallest expressible interval is 1ms; rather than emit an
         # "every 0s" that polls flat-out, round up and say so.
         def interval_in_ms(every, verb)

data/lib/weft/error.rb

@@ -48,7 +48,7 @@ module Weft
   InvalidConfiguration = Class.new(Error)
 
   # Raised for semantic mistakes in class-body DSL declarations — e.g. a page
-  # declares attributes but no `page_path`, or `adds_children_to` receives a
+  # declares params but no `page_path`, or `adds_children_to` receives a
   # Symbol that does not start with `@`.
   InvalidDefinition = Class.new(Error)
 
@@ -57,8 +57,19 @@ module Weft
   # assets bundle named at `register_stylesheet`).
   InvalidUsage = Class.new(Error)
 
+  # Raised by the bang forms of the render-tree lookup (`closest!` / `enclosing!`)
+  # when no node matches the requested criteria — the component expected an
+  # ancestor that isn't there (it should usually be `dependent!` and rendered
+  # only inside that ancestor).
+  AncestorNotFound = Class.new(InvalidUsage)
+
   # Raised by the `adds_children_to :@ivar` macro when build returns without
   # ever assigning the named ivar and then a child is added — almost always
   # means the developer declared the macro but forgot the matching assignment.
   MissingContainerIvar = Class.new(InvalidDefinition)
+
+  # Raised at component construction when a `receives` key with no declared
+  # default ends resolution valueless — the call site didn't hand it over and
+  # no other source (wire dual, inherited bag) supplied it.
+  NotReceived = Class.new(InvalidUsage)
 end