sourced-component 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 298693a66f5e1042dadbdc1ce6e772f3169dd858bdb1389316d8228e2daa4fa6
-  data.tar.gz: de5a5fa27a550d03b93b7fdfd00f82f54709258758915a8506516ba8c0fa38a8
+  metadata.gz: 2896fb5ddac45462754f578010d435045bdaef50926865591b21bc49f68f8127
+  data.tar.gz: 86e67b664260f455dd0c0d47d5ad7492d5164e408d4f580b00e17f4b46a2873e
 SHA512:
-  metadata.gz: 804e89d48a58add65d94afaab6866264915aab3dad53db19b6ba6a875c262775092de2403b50ed2b1e06c6ee28c04ea3d19e59762678816a0c5be0babee3c943
-  data.tar.gz: c5e7bdb7320e0845910f1d905c8d91bb1ae7b83b4ddbb981ba8b6a70b841c5ade7d017d5ebbd95c23c52759e4ecfc9acbef0e06550a9b47945ac0362dc6c9840
+  metadata.gz: 6fd436c2496d183ee205625cffdd0f8714835083d5e081713dbf012f20412e7d04d454fbdb0cf689154158425d0ef4f268c5a4c0c0d741870a20ef6b11671850
+  data.tar.gz: a2925c94cdc0fcfd6aafb5152ac051e9ed43680551e1e7891fb801c9e6b49e7d44597f7d269bda1950ac695a49c42f5e0dcca7e6cdac27874a25d95460957718

data/CHANGELOG.md

@@ -5,6 +5,14 @@
 - `#start_component!`, `#stop_component!` and `#restart_component!` start and stop components by key, following the dependency graph
 - `components.deferred`, `components.stopping` and `components.stopped` events, and `NotStartedError`
 - `#tree` and `#graph` show deferred and stopped components
+- `.__component_deps` on classes including an injector: every component injected into them, including inherited ones, as the key it's registered under mapped to the name it's injected as
+- `#factory(key, constructor)` implements a declared component from a class that injects, taking its dependencies and its constructor's keyword arguments from `.__component_deps`
+- `#recycle_component!`, `#recycle_components!` and `#recycle!` run a component's whole lifecycle again, leaving every affected component in the status it was in. A recycle that raises can be retried: components remember the status to restore until one completes
+- `root.recycling` and `root.recycled` events
+- `#reconfigure(key) { |branch| ... }` re-declares one branch of a booted tree from scratch: what the block doesn't declare is removed, unchanged components keep running, and the new declaration set is validated before anything is torn down, so a failure leaves the tree as it was
+- `root.reconfiguring`, `root.reconfigured` and `components.removed` events, and `RemovedComponentError`
+- Document forking after `#prepare!`, with `#build!` and `#start!` in each child
+- Fix: `#teardown!` left the rest of the tree running, and the root `:started`, when a hook raised something that wasn't a `StandardError` (ex. the `Interrupt` a signal handler raises). Every component is now torn down exactly once, and a component whose hooks already ran is never torn down again
 
 ## [0.1.0] - 2026-10-04
 

data/README.md

@@ -141,6 +141,8 @@ App.component!('with.deps', ['sourced.db']) { build { |db| Foo.new(db) } }
 App.component('now') { build { Time.now } }
 ```
 
+A class that injects its own dependencies can be implemented from them, without repeating the list: see [`#factory`](#factory).
+
 ### Aliases
 
 `#alias(key, target)` implements a declared node as an alias of another component: reading it reads the target. It's useful to wire one library's component to another's:
@@ -382,9 +384,81 @@ App.start_component!('dispatcher')  # starts dispatcher, then monitor
 - **If `stop` hooks raise,** every component is still stopped, and the first error is re-raised.
 - **`#teardown!`** runs `stop` on the started components and `teardown` on all of them, deferred or stopped ones included.
 
+### Recycling components
+
+`#recycle_component!(key, context = Thread.current)` runs a component's whole lifecycle again, from the top: it stops the component if it's running, tears it down, drops its value, then prepares and builds it from scratch. This is for class reloaders and the like — a file changes, and the components built from it are recycled.
+
+```ruby
+App.recycle_component!('sourced.store', task)
+App.recycle_components!('sourced.store', 'repos.users', context: task) # several at once
+App.recycle!(task)                                                     # the whole tree
+```
+
+- **Every component is left in the status it was in before.** A started one is started again with `context`, and one that was only built stops at built. Nothing changes the root's own status.
+- **The components depending on it are recycled too**, directly or not: their values were built from its old value, so they're stale. Its own dependencies are left alone, running.
+- **A component that was stopped by key, or deferred, comes back `:built` and still held.** Its fresh value has never run, so it waits to be started by `#start_component!`, exactly as it was waiting before.
+- **Order:** down in reverse dependency order, dependents first, then up in dependency order, one stage at a time — every affected component is prepared before any is built, as when the root boots.
+- **Keys are relative to the component** the method is called on, like `#component!`. Only the root can `#recycle!` the whole tree.
+- **Hooks:** a started component runs `stop` then `teardown` on the way down, and `prepare`, `build` and `start` on the way back up. A component that wasn't running only runs `teardown`.
+- **Events:** `root.recycling` and `root.recycled` wrap the operation, and each component publishes its usual stage events, so a reloader can follow along. As with `#teardown!`, the `stop` hooks of a started component run under its `components.tearing_down` event.
+
+```
+db <- store <- dispatcher
+
+App.recycle_component!('store')   # tears down dispatcher, then store
+                                  # then builds store, dispatcher, and starts both again
+                                  # db keeps running, with the same value
+```
+
+- **If a `stop` or `teardown` hook raises,** every affected component is still torn down and its value dropped, and the first error is re-raised before anything is prepared again. They're left `:open`, with no value: reading one raises `NotBuiltError`.
+- **If a `prepare`, `build` or `start` hook raises,** the component is left where it got to and the error is re-raised, along with the components the recycle hadn't reached: `:open` or `:prepared` with no value, where reading one raises `NotBuiltError`, or `:built` with the value it just built for them.
+- **Recycling again recovers, however it failed.** Each component remembers the status the first recycle meant to restore, until one completes, so a retry puts it back even when its own status no longer says it was running: a component a failed `start` left `:built` is started again, not left behind. A reloader can just retry on the next save.
+- **The root must be built, or started.** Before that there's nothing to recycle, and it raises `NotBuiltError`; once the root is torn down, `TornDownError`. Recycling while the root is booting raises `LockedComponentError`: mid-`#start!` there's no settled status to go back to.
+- **No code is reloaded.** Recycling re-runs the hooks a component was implemented with; it doesn't re-implement it. The tree is locked once prepared, so a class captured in a provider (`App.component!('store', Store)`) stays captured — only a block that resolves the constant when it builds (`build { Store.new }`) picks up a reloaded class.
+
+### Re-configuring a booted tree
+
+`#reconfigure(key, context = Thread.current)` re-declares one branch of the tree from scratch while it's running. The block declares the branch's new contents, and whatever it doesn't declare is removed. This is for file watchers: rescan a directory, re-register every file, and removal is a consequence of not declaring a key rather than an operation of its own.
+
+```ruby
+App.reconfigure('reactors') do |reactors|
+  files.each { |f| reactors.declare(f.key) }                        # idempotent: these are kept
+  changed.each { |f| reactors.component!(f.key, f.deps, &f.hooks) } # these recycle
+end
+```
+
+| In the block | Before | Result |
+| --- | --- | --- |
+| declared, not re-implemented | existed | kept, untouched: same value and status |
+| declared and re-implemented | existed | recycled |
+| declared with another type | existed | recycled |
+| declared | new | prepared, built, and started if the root is started |
+| not declared | existed | torn down and removed |
+
+- **Re-declaring is idempotent**, so a component whose declaration didn't change keeps its value and status, and runs no hooks. Only the ones the block re-implements, re-types or declares for the first time are recycled (see above), along with everything depending on them.
+- **Components elsewhere in the tree are recycled if their dependencies changed**, which is how a `config('runner', ['reactors.*'])` picks up an added or removed reactor: its memoized value listed the old ones.
+- **Nothing runs any hooks until the whole new declaration set has been validated.** A block that raises, a missing dependency, a cycle, a declaration with no implementation, or dropping a component something still depends on: each leaves the tree exactly as it was, still running. A broken file save is the normal case in a dev loop, so recovering from it is the point.
+- **Components stopped by key stay stopped**, and deferred ones stay deferred. Re-declaring doesn't start anything that wasn't running.
+- **Keys are relative to the branch**, and the block declares through the component `#reconfigure` was called on, so ownership comes out exactly as plain declaration would. The branch must be a namespace, and the tree is locked for anything outside the block as usual.
+- **Removed components are `:removed`**, which is terminal. They're gone from `#index`, `#tree` and `#graph`, so reading them by key raises `UndeclaredComponentError` — and anything still holding the node itself, ex. a class that injected it, raises `RemovedComponentError` rather than reading a dead value.
+- **Nested keys work the same**, since dotted keys build the tree. A namespace left with nothing under it is removed too, pruned bottom-up: dropping `billing.deep.x` leaves neither `deep` nor `billing` behind.
+- **A component that keeps declared children reverts to a namespace** instead of being removed. That's the `billing.rb` → `billing/` refactor: it's torn down and loses its implementation, but stays as the parent of its new children. Collapsing it back the other way re-implements it and removes the children.
+- **An open tree** reconfigures as plain declaration: nothing is built yet, so nothing is torn down or recycled, and `#prepare!` validates the whole set when it boots.
+- **Events:** `root.reconfiguring` and `root.reconfigured` wrap the operation, with `components.removed` for each removal and the usual stage and recycling events in between.
+- **No code is reloaded**, as with recycling: the block supplies the new implementations, and a class captured in a provider is only re-captured if the block passes it again.
+
+```ruby
+App.reconfigure('reactors') do |reactors|
+  reactors.declare('audit')              # kept, still running
+  reactors.declare('billing.invoices')   # kept
+  reactors.component!('billing.invoices', [], NewImpl)  # ... but re-implemented, so recycled
+  # 'billing.payments' isn't declared: torn down and removed
+end
+```
+
 ### Signal handlers
 
-The lifecycle methods, and anything else that takes the root's lock (declaring, implementing and mounting components, `#graph`, `#tree`), can't be called from a `trap` block: Ruby doesn't allow locking a `Monitor` in trap context, so they raise `ThreadError: can't be called from trap context` and nothing is torn down. Reading values doesn't take the lock.
+The lifecycle methods, and anything else that takes the root's lock (declaring, implementing and mounting components, `#recycle_component!` and friends, `#reconfigure`, `#graph`, `#tree`), can't be called from a `trap` block: Ruby doesn't allow locking a `Monitor` in trap context, so they raise `ThreadError: can't be called from trap context` and nothing is torn down. Reading values doesn't take the lock.
 
 Instead, have the trap wake up the main thread, and tear down from there, as in the example above:
 
@@ -398,10 +472,31 @@ trap('TERM') { Thread.main.raise(Interrupt) }
 
 Any other way out of trap context works too, ex. pushing to a `Queue` or writing to a self-pipe that a thread waits on.
 
+### Forked processes
+
+`#prepare!` resolves dependencies, computes the boot order and runs the `prepare` hooks, but builds no values. That makes it the point to fork from: the parent holds no connections, sockets or threads, and each child builds and starts its own.
+
+```ruby
+App.prepare!                 # once, in the parent: requires, validation, dependency order
+
+workers.times do
+  fork do
+    App.build!
+    App.start!(task)         # this process' own values, from here on
+    ...
+  end
+end
+```
+
+- **Don't fork a built or started tree.** Threads don't survive `fork`, so a long-running component would report `:started` in the child with nothing running, and file descriptors *do* survive, shared: the child and the parent would write to the same connection. Tearing down or recycling in the child would then run `stop` and `teardown` hooks on resources the parent still owns.
+- **Fork from the main thread**, with no lifecycle call in flight. The root's `Monitor` is copied as-is, so forking while another thread holds it leaves the child's copy locked forever.
+- **A reconfigured branch comes up to where the tree already is**, and no further: on a prepared tree its new components are prepared but not built, so children forked afterwards build them for themselves. Deferring lowers that ceiling to `:built`, it never raises it.
+- **Everything else is per-process.** `#recycle_component!` and `#reconfigure` act on one process' tree, in memory, with no coordination between them: a file watcher has to run in each process that should react to it, as `ActiveSupport::FileUpdateChecker` and Zeitwerk do. Driving one from a signal has the `trap` restriction above, since it takes the root's lock.
+
 ### Errors while starting and tearing down
 
 - If a `start` hook raises, the components already started are torn down in reverse order, the component is left `:torn_down`, and the error is re-raised.
-- If `teardown` hooks raise, every component is still torn down, and the first error is re-raised.
+- If `stop` or `teardown` hooks raise, every component is still torn down, exactly once, and the first error is re-raised. This holds for anything they raise, `Interrupt` included: a signal handler interrupting the shutdown can't leave part of the tree running, and the root still ends `:torn_down`. A component whose hooks already ran is never torn down again, so `#teardown!` is safe to call once more after one failed.
 
 ## Mounting components
 
@@ -553,6 +648,53 @@ App.start!
 MyLib::Dispatcher.new.store # => #<DBStore ...>, the app's override
 ```
 
+### `.__component_deps`
+
+Including an injector also defines `.__component_deps` on the class: every component injected into it, including the ones injected into its ancestors, as the key it's registered under mapped to the name it's injected as.
+
+```ruby
+class Foo
+  include App.inject('logger', 'repos.users' => 'customers')
+end
+
+Foo.__component_deps # => { "logger" => :logger, "repos.users" => :customers }
+```
+
+- **Keys** are the ones components are **registered** under, never the names they're injected as. **Values** are those names, as symbols, so they can go straight into keyword arguments.
+- Inherited dependencies are included, the superclass' first, each class' own in the order they were injected. A component injected twice is listed once, under the name closest to the class: a subclass injecting `'logger' => 'app_logger'` over its parent's `'logger'` reports `:app_logger`.
+- Keys are paths from the root of the component's tree, so they follow mounting. `MyLib::Dispatcher` above reports `{ "store" => :store }` while the library is standalone, and `{ "my_lib.store" => :store }` once the app mounts it at `my_lib`: the key the app would use to read it.
+- An alias (see `#alias`) is listed under its own key, not its target's.
+- A class defining its own `def self.__component_deps` keeps it: unlike the injected readers, this one is never overwritten.
+- `Sourced::Component::Injector.deps_for(klass)` returns the same hash for any class or module, which is useful when an injector is included into a module rather than directly into a class: the module gets `.__component_deps`, but classes including it don't.
+
+### `#factory`
+
+Keys and values line up with a component's dependencies and its constructor's keyword arguments, so `#factory(key, constructor)` implements a declared component from a class that injects:
+
+```ruby
+class Dispatcher
+  include App.inject('logger', 'repos.users' => 'customers')
+end
+
+App.declare('dispatcher', Dispatcher)
+App.factory('dispatcher', Dispatcher)   # Dispatcher.new(logger:, customers:)
+```
+
+which is the same as writing out what the class already declares:
+
+```ruby
+deps = Dispatcher.__component_deps      # { "logger" => :logger, "repos.users" => :customers }
+App.config('dispatcher', deps.keys) { |*values| Dispatcher.new(**deps.values.zip(values).to_h) }
+```
+
+- **The injected components become the component's dependencies**, so it's built after them and [`#graph`](#graph) shows the edges.
+- **Values are passed to the constructor**, so each dependency is read once per build. The injector takes the keyword arguments it's given instead of reading the components itself, which matters for a dynamic dependency: the instance and the build see the same value.
+- **It's dynamic**, like `#config`: a new instance on every read. For one instance, built once, use `App.config!('dispatcher', deps.keys) { ... }` with the block above.
+- **Any class works.** One that injects nothing is built with `new` and no arguments, and so has no dependencies. One that needs positional arguments doesn't fit: `#factory` only passes keywords.
+- **Inherited injections are included**, since `.__component_deps` includes them.
+- **Declare the key first.** `#factory` implements an existing declaration, and the built instance is parsed through its declared type like any other value.
+- **Keys are paths from the root of the injector's tree** (see above), so call `#factory` on that root. Calling it on a component mounted inside that tree resolves them relative to itself instead, and `#prepare!` then raises `MissingDependencyError`.
+
 ## Inspecting the tree
 
 ```ruby
@@ -570,8 +712,10 @@ node.root            # => App
 node.owner           # => the component that declared it
 node.type            # => the declared type
 node.implementation  # => deps, mode (:singleton, :dynamic or :alias) and the implementing component
+node.dep_nodes       # => the components it depends on, wildcards included. See #graph for keys
 node.children        # => { segment => Component }
 node.namespace?      # => no type and no implementation
+node.removed?        # => whether a #reconfigure dropped it from the tree
 ```
 
 ### `#tree`
@@ -733,10 +877,13 @@ end
 | `components.stopping` / `components.stopped` | around a component's `stop` hooks, when stopped by key (on `#teardown!`, they're part of tearing down) | `key`, and `duration` when finished |
 | `components.tearing_down` / `components.torn_down` | around a component's `teardown` hooks | `key`, and `duration` when finished |
 | `components.deferred` | `#defer` | `key`, `deferrer` (the full path of the component that deferred it, `nil` for the root) |
+| `components.removed` | a component `#reconfigure` dropped from the tree | `key`, `remover` (the full path of the component that reconfigured, `nil` for the root) |
 | `components.failed` | a component's hook (or type check) raised | `key`, `stage`, `error_class`, `error_message`, `backtrace` |
 | `root.preparing` / `root.prepared` | around `#prepare!` | `duration` when finished |
 | `root.building` / `root.built` | around `#build!` | `duration` when finished |
 | `root.starting` / `root.started` | around `#start!` | `duration` when finished |
+| `root.recycling` / `root.recycled` | around `#recycle_component!`, `#recycle_components!` and `#recycle!` | `duration` when finished |
+| `root.reconfiguring` / `root.reconfigured` | around `#reconfigure` | `duration` when finished |
 | `root.tearing_down` / `root.torn_down` | around `#teardown!` | `duration` when finished |
 | `root.failed` | a lifecycle step raised | `stage`, `error_class`, `error_message`, `backtrace` |
 
@@ -744,7 +891,7 @@ end
 - **`key`** is the component's full path from the root, ex. `sourced.db`.
 - **`deps`** are relative to the `implementer`, the full path of the component that implemented the component (`nil` for the root).
 - **`duration`** is in seconds, measured with a monotonic clock.
-- **`stage`** is one of `:prepare`, `:build`, `:start`, `:stop` or `:teardown`.
+- **`stage`** is one of `:prepare`, `:build`, `:start`, `:stop`, `:teardown`, `:recycle` or `:reconfigure`.
 - **Errors are described, not attached:** `error_class`, `error_message` and `backtrace` are strings, so events stay serializable (see below). The error itself is re-raised to the caller of the lifecycle method.
 
 A few rules:
@@ -834,15 +981,16 @@ Plumb::ParseError: user: {age: "Must be a Integer"}
 | --- | --- |
 | `DeclarationOverrideError` | declaring or mounting on a key that's already declared |
 | `OwnershipError` | declaring or mounting under nodes owned by another component |
-| `LockedComponentError` | changing the tree after it's prepared, or mounting a component that isn't open |
+| `LockedComponentError` | changing the tree after it's prepared, mounting a component that isn't open, recycling or reconfiguring while the root is booting, or a nested `#reconfigure` |
 | `SubcomponentError` | booting a mounted component, or mounting a component that's already mounted |
 | `UndeclaredComponentError` | implementing or reading an undeclared key, or reading a namespace |
 | `UnimplementedComponentError` | preparing with declared (or deferred) components that have no implementation |
 | `MissingDependencyError` | preparing with dependencies that aren't declared or implemented |
 | `CircularDependencyError` | preparing with dependency cycles |
-| `NotBuiltError` | reading values before the component is built |
-| `TornDownError` | starting a component that's torn down, or starting or stopping a component by key once its root is torn down |
+| `NotBuiltError` | reading values before the component is built, reading one that was recycled away, or recycling before the root is built |
+| `TornDownError` | starting a component that's torn down, or starting, stopping or recycling a component by key once its root is torn down |
 | `NotStartedError` | starting or stopping a component by key before its root is started |
+| `RemovedComponentError` | reading a component that `#reconfigure` removed from the tree |
 | `InjectionError` | including an injector in a class that already has a method with an injected name, or already injects it |
 
 ## Thread safety

data/lib/sourced/component/errors.rb

@@ -14,6 +14,7 @@ module Sourced
     NotBuiltError = Class.new(ComponentError)
     TornDownError = Class.new(ComponentError)
     NotStartedError = Class.new(ComponentError)
+    RemovedComponentError = Class.new(ComponentError)
     InjectionError = Class.new(ComponentError)
   end
 end

data/lib/sourced/component/events.rb

@@ -49,7 +49,7 @@ module Sourced
 
       Completed = proc { attribute :duration, Float }
       Failed = proc do
-        attribute :stage, Symbol # :prepare, :build, :start, :stop or :teardown
+        attribute :stage, Symbol # :prepare, :build, :start, :stop, :teardown, :recycle or :reconfigure
         attribute :error_class, String
         attribute :error_message, String
         attribute :backtrace, Plumb::Types::Array[String]
@@ -61,6 +61,10 @@ module Sourced
       RootBuilt = RootEvent.define('root.built', &Completed)
       RootStarting = RootEvent.define('root.starting')
       RootStarted = RootEvent.define('root.started', &Completed)
+      RootReconfiguring = RootEvent.define('root.reconfiguring')
+      RootReconfigured = RootEvent.define('root.reconfigured', &Completed)
+      RootRecycling = RootEvent.define('root.recycling')
+      RootRecycled = RootEvent.define('root.recycled', &Completed)
       RootTearingDown = RootEvent.define('root.tearing_down')
       RootTornDown = RootEvent.define('root.torn_down', &Completed)
       RootFailed = RootEvent.define('root.failed', &Failed)
@@ -77,6 +81,9 @@ module Sourced
       ComponentDeferred = ComponentEvent.define('components.deferred') do
         attribute :deferrer, Plumb::Types::String.nullable # the full path of the component that deferred it. nil for the root
       end
+      ComponentRemoved = ComponentEvent.define('components.removed') do
+        attribute :remover, Plumb::Types::String.nullable # the full path of the component that removed it. nil for the root
+      end
       ComponentPreparing = ComponentEvent.define('components.preparing')
       ComponentPrepared = ComponentEvent.define('components.prepared', &Completed)
       ComponentBuilding = ComponentEvent.define('components.building')
@@ -97,6 +104,8 @@ module Sourced
       prepare: [Events::RootPreparing, Events::RootPrepared],
       build: [Events::RootBuilding, Events::RootBuilt],
       start: [Events::RootStarting, Events::RootStarted],
+      reconfigure: [Events::RootReconfiguring, Events::RootReconfigured],
+      recycle: [Events::RootRecycling, Events::RootRecycled],
       teardown: [Events::RootTearingDown, Events::RootTornDown]
     }.freeze
 

data/lib/sourced/component/injector.rb

@@ -11,16 +11,33 @@ module Sourced
     # Values are read from the nodes themselves, so a class injecting from a library's component
     # gets the overrides of the application that mounts it.
     class Injector < Module
-      attr_reader :names
+      # Extended into whatever includes an Injector, see #included
+      module ComponentDeps
+        # Every component injected into this class, including inherited ones, by key.
+        # See Injector.deps_for
+        def __component_deps = Injector.deps_for(self)
+      end
+
+      # Every component injected into mod, as the key it's registered under (a path from the root of
+      # its tree) mapped to the name it's injected as, in injection order, with the ones injected
+      # into mod's ancestors first. Injecting a key again under another name replaces the name, so
+      # the one closest to mod wins.
+      #   { 'logger' => :logger, 'repos.users' => :customers }
+      def self.deps_for(mod)
+        mod.ancestors.grep(Injector).reverse.reduce({}) { |deps, injector| deps.merge(injector.mapping) }
+      end
+
+      attr_reader :names, :nodes
 
       # nodes: { 'component.key' => <Component node> }
       # names: { 'component.key' => :kwarg_name }
       def initialize(nodes, names)
         super()
         @names = names.freeze
+        @nodes = names.keys.map { |key| nodes.fetch(key) }.freeze
 
         # Instance variable names are computed once, not on every #new
-        entries = names.map { |key, name| [nodes.fetch(key), name, :"@#{name}"] }.freeze
+        entries = @nodes.zip(names.values).map { |node, name| [node, name, :"@#{name}"] }.freeze
 
         initializer = Module.new do
           define_method(:initialize) do |*args, **kwargs, &block|
@@ -50,9 +67,20 @@ module Sourced
         define_singleton_method(:included) do |base|
           base.prepend(initializer)
           base.attr_reader(*names.values)
+          base.extend(ComponentDeps)
         end
       end
 
+      # The keys as passed to Component#inject, relative to the component they were injected from
+      def keys = names.keys
+
+      # The keys the injected components are registered under, as paths from the root of their tree.
+      # Computed on each call: a node's path changes when its root is mounted into another component.
+      def paths = nodes.map(&:path)
+
+      # Those keys, mapped to the names the components are injected as
+      def mapping = paths.zip(names.values).to_h
+
       def inspect = "#<#{self.class} #{names.map { |key, name| "#{key} => #{name}" }.join(', ')}>"
     end
   end

data/lib/sourced/component/reconfiguration.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # A re-declaration of one branch of a booted tree, driven by Component#reconfigure: it records
+    # what the block declares, and snapshots what's needed to roll back if anything raises.
+    #   Branch        what the block declares through, see below
+    #   #snapshot!    everything the block or the validation can touch
+    #   #declared!    one per key the block declares, from Component#declare
+    #   #implemented! one per key it re-implements, from Component#implement_node
+    #   #retyped!     one per surviving node whose type changed, from Component#declare
+    class Reconfiguration
+      # What a reconfiguration can change about one node: captured before its block runs, restored
+      # if anything raises. The members drive both the capture and the restore, so a new one can't
+      # be captured and then forgotten on the way back
+      NodeState = Data.define(
+        :implementation, :type, :implicit, :deps, :dep_nodes, :deferred, :held, :status, :value,
+        :recycle_to, :children, :index
+      )
+
+      # The tree as it was before the block: every node's state, and the root's order
+      Snapshot = Data.define(:order, :nodes)
+
+      # Declares into +branch+ on behalf of +owner+, the component #reconfigure was called on: keys
+      # are prefixed and passed on, so the owner declares them as it would itself. That's what makes
+      # nested keys work, since a branch node can't declare under namespaces the root created.
+      class Branch
+        def initialize(owner, prefix)
+          @owner = owner
+          @prefix = prefix
+        end
+
+        def declare(ckey, ...) = @owner.declare(key(ckey), ...)
+        def component!(ckey, ...) = @owner.component!(key(ckey), ...)
+        def component(ckey, ...) = @owner.component(key(ckey), ...)
+        def config!(ckey, ...) = @owner.config!(key(ckey), ...)
+        def config(ckey, ...) = @owner.config(key(ckey), ...)
+        def alias(ckey, ...) = @owner.alias(key(ckey), ...)
+        def defer(ckey) = @owner.defer(key(ckey))
+        def node(ckey) = @owner.node(key(ckey))
+        def declared?(ckey) = @owner.declared?(key(ckey))
+
+        def inspect = "#<#{self.class} #{@prefix}>"
+
+        private def key(ckey) = "#{@prefix}.#{ckey}"
+      end
+
+      # branch: the namespace node being re-declared. owner: the component #reconfigure was called on
+      def initialize(branch, owner)
+        @branch = branch
+        @owner = owner
+        @declared = Set.new # nodes the block declared, new and surviving
+        @changed = Set.new  # nodes it re-implemented, or declared with another type
+        @before = Set.new   # the nodes under the branch before the block
+        @snapshot = nil
+      end
+
+      def branch_handle = Branch.new(@owner, @branch.path)
+
+      def snapshot!
+        root = @branch.root
+        @before = @branch.index.values.to_set
+        nodes = [root, *root.index.values]
+        @snapshot = Snapshot.new(order: root.order&.dup, nodes: nodes.to_h { |n| [n, n.capture_state] })
+        self
+      end
+
+      # Put it all back. Nothing has run any hooks yet, so this is all it takes
+      def rollback!
+        @snapshot.nodes.each { |n, state| n.restore_state!(state) }
+        @branch.root.restore_order!(@snapshot.order)
+        self
+      end
+
+      def declared!(node) = @declared << node
+      def changed!(node) = @changed << node
+
+      # Whether the tree didn't have this component before the block. Component#declare asks, to
+      # announce only those
+      def new?(node) = !@before.include?(node)
+
+      # The order before the block ran, to tear removed components down in reverse
+      def order_before = @snapshot.order || []
+
+      # What the block changed, plus every node whose resolved deps are no longer the same nodes
+      def affected
+        redeps = @snapshot.nodes.filter_map { |n, state| n unless state.dep_nodes == n.dep_nodes }
+        (@changed | created | redeps).reject { |n| n.removed? || n.namespace? }
+      end
+
+      # Components the tree didn't have: new nodes, and namespaces the block implemented
+      def newly_components
+        was_namespace = @snapshot.nodes.filter_map do |n, state|
+          n if state.implementation.nil? && !n.implementation.nil?
+        end
+        (created | was_namespace).reject(&:namespace?)
+      end
+
+      # Components the block declared that the tree didn't have before
+      def created = @declared - @before
+
+      # Dropped components that still have declared descendants, ex. one at 'billing' whose file
+      # became a 'billing/' directory. They revert to namespaces: removing them would orphan those
+      def reverting = dropped.fetch(:reverting)
+
+      # Everything to take out of the tree: dropped components with no declared descendants left,
+      # plus the namespaces that leaves empty, pruned bottom-up until stable (dropping
+      # 'billing.deep.x' can empty 'deep', which can empty 'billing')
+      def removing
+        gone = dropped.fetch(:removing).dup
+        loop do
+          empty = @before.select do |n|
+            n.namespace? && !gone.include?(n) && n.children.any? && (n.children.values - gone).empty?
+          end
+          break gone if empty.empty?
+
+          gone.concat(empty)
+        end
+      end
+
+      # The nodes the block didn't declare, split into the ones to take out of the tree and the ones
+      # that revert to namespaces. Computed once: the block has finished by the time anything asks
+      private def dropped
+        @dropped ||= begin
+          kept, gone = (@before - @declared).partition { |n| keeps_children?(n) }
+          { removing: gone, reverting: kept.reject(&:namespace?) }
+        end
+      end
+
+      private def keeps_children?(node)
+        node.index.values.any? { |d| @declared.include?(d) }
+      end
+    end
+  end
+end

data/lib/sourced/component/version.rb

@@ -2,6 +2,6 @@
 
 module Sourced
   class Component
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/sourced/component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'monitor'
+require 'set'
 require 'tsort'
 require 'plumb'
 require_relative 'component/version'
@@ -14,6 +15,7 @@ require_relative 'component/graph'
 require_relative 'component/events'
 require_relative 'component/notifier'
 require_relative 'component/tree'
+require_relative 'component/reconfiguration'
 
 module Sourced
   # A tree of components. Every node is a Component: it can declare a type, be implemented with
@@ -31,8 +33,9 @@ module Sourced
 
     # Lifecycle statuses, in order. Shared by the root (boot status) and every node.
     # Only nodes are ever :stopped: a started node stopped by key (see #stop_component!),
-    # which can be started again.
-    STATUSES = %i[open prepared built started stopped torn_down].freeze
+    # which can be started again. Only nodes are ever :removed either: a component a
+    # reconfiguration dropped from the tree (see #reconfigure), which is terminal.
+    STATUSES = %i[open prepared built started stopped torn_down removed].freeze
 
     # What #mount takes: anything that returns a Component from #to_component
     MountableInterface = Plumb::Types::Interface[:to_component]
@@ -57,6 +60,8 @@ module Sourced
       @value = nil
       @deferred = false # skipped by the root's #start!, see #defer
       @held = false     # not started with the tree or its dependencies: deferred, or stopped by key
+      @recycle_to = nil # the status to come back to while recycling, see #recycle_component!
+      @reconfiguration = nil # the reconfiguration in progress, on the root only. See #reconfigure
       @deps = [].freeze      # resolved deps: a node, or { segment => node } for a wildcard
       @dep_nodes = [].freeze # every node in @deps, for sorting
       @children = {}
@@ -87,8 +92,18 @@ module Sourced
 
     # Whether the root's #start! skips it (see #defer)
     def deferred? = @deferred
+    # Whether the tree is past :open. #mount asks this of the component being mounted
     def locked? = root.boot_status != :open
 
+    # Whether a reconfiguration's block is running. Only ever true on the root
+    def reconfiguring? = !@reconfiguration.nil?
+
+    # Whether the tree refuses declarations: locked, unless a #reconfigure block is open
+    private def declarations_locked? = locked? && !root.reconfiguring?
+
+    # The Reconfiguration in progress, which records what its block declares
+    protected def reconfiguration = @reconfiguration
+
     def inspect
       details = namespace? ? '(namespace)' : "#{type_name} (#{[implementation&.mode || 'not implemented', status, ('deferred' if deferred?)].compact.join(', ')})"
       "#<#{self.class} #{path || '(root)'} #{details}>"
@@ -99,20 +114,28 @@ module Sourced
     #   comp.declare('sourced.db.logger', Logger) { Logger.new(STDOUT) }
     def declare(ckey, type = T::Any, &default)
       synchronize do
-        raise LockedComponentError, "can't declare #{ckey} in a locked component" if locked?
+        raise LockedComponentError, "can't declare #{ckey} in a locked component" if declarations_locked?
 
+        reconf = root.reconfiguration
         branch, leaf = walk(ckey)
         node = branch.children[leaf]
         if node.nil?
           node = branch.attach(leaf, Component.new(owner: self, type:))
         elsif !node.owner.equal?(self)
           raise OwnershipError, ownership_message(node)
-        elsif !node.implicit?
+        elsif !node.implicit? && reconf.nil?
           raise DeclarationOverrideError, "#{node.path} is already declared"
         else
+          # Idempotent while reconfiguring: an unchanged component keeps its value and status,
+          # and a changed type marks it to be recycled
+          was = node.implicit? ? nil : node.type_name
           node.declare_type!(type) # an implicit namespace this component created, now with a type
+          reconf&.changed!(node) if was && was != node.type_name
         end
-        emit(Events::ComponentDeclared, key: node.path, type_name: node.type_name)
+        new_to_the_tree = reconf.nil? || reconf.new?(node)
+        reconf&.declared!(node)
+        # While reconfiguring, only new components are announced: re-declaring the rest is noise
+        emit(Events::ComponentDeclared, key: node.path, type_name: node.type_name) if new_to_the_tree
 
         implement_node(node, Implementation.from_block([], implementer: self, mode: :singleton) { build(&default) }) if default
         self
@@ -180,7 +203,7 @@ module Sourced
     # and the alias follows it like any other dependent.
     def alias(ckey, target)
       synchronize do
-        raise LockedComponentError, "can't implement #{ckey} in a locked component" if locked?
+        raise LockedComponentError, "can't implement #{ckey} in a locked component" if declarations_locked?
 
         implement_node(node(ckey), Implementation.alias(target, implementer: self))
         self
@@ -203,7 +226,7 @@ module Sourced
       end
 
       synchronize do
-        raise LockedComponentError, "can't implement ENV components in a locked component" if locked?
+        raise LockedComponentError, "can't implement ENV components in a locked component" if declarations_locked?
 
         builders = mapping.map do |source, ckey|
           target = node(ckey)
@@ -217,6 +240,22 @@ module Sourced
       end
     end
 
+    # Implement a declared component by building +constructor+ on each read, from the components it
+    # injects: #__component_deps maps each one's key to the keyword argument it's injected as, so the
+    # component's dependencies and the constructor's arguments come from the same place.
+    # A constructor that injects nothing is built with no arguments.
+    #   class Dispatcher
+    #     include App.inject('logger', 'repos.users' => 'customers')
+    #   end
+    #   app.declare('dispatcher', Dispatcher)
+    #   app.factory('dispatcher', Dispatcher) # Dispatcher.new(logger:, customers:)
+    # Keys are paths from the root of the injector's tree, so call this on that root.
+    def factory(ckey, constructor)
+      deps = constructor.respond_to?(:__component_deps) ? constructor.__component_deps : {}
+      config(ckey, deps.keys) { |*values| constructor.new(**deps.values.zip(values).to_h) }
+      self
+    end
+
     # Defer a node under this component: the root's #start! skips it, and every component that
     # depends on it, directly or not, since they can't start before it. Start it by key instead,
     # ex. when its process is elected to run it (see #start_component!).
@@ -227,7 +266,7 @@ module Sourced
     # implemented again. Any component can defer a node below it, like implementing one.
     def defer(ckey)
       synchronize do
-        raise LockedComponentError, "can't defer #{ckey} in a locked component" if locked?
+        raise LockedComponentError, "can't defer #{ckey} in a locked component" if declarations_locked?
 
         target = node(ckey)
         target.defer!
@@ -271,7 +310,7 @@ module Sourced
       raise ArgumentError, "#{mountable.inspect}.to_component must return a Component, got #{sub.inspect}" unless sub.is_a?(Component)
 
       synchronize do
-        raise LockedComponentError, "can't mount #{ckey} in a locked component" if locked?
+        raise LockedComponentError, "can't mount #{ckey} in a locked component" if declarations_locked?
         raise SubcomponentError, "#{sub.inspect} is already mounted in another component" unless sub.root?
         raise SubcomponentError, "can't mount a component into its own tree" if sub.equal?(root)
         raise LockedComponentError, "can't mount a #{sub.boot_status} component: it must be open" if sub.locked?
@@ -300,6 +339,7 @@ module Sourced
     def [](ckey) = node(ckey).read
 
     def read
+      raise RemovedComponentError, "#{path} was removed from the tree" if removed?
       raise NotBuiltError, 'component is not built yet' unless root.readable?
       raise UndeclaredComponentError, "#{path} is a namespace, not a component" unless implementation
 
@@ -317,6 +357,9 @@ module Sourced
 
         instrument_root(:prepare) do
           @order = resolve_order
+          # Holds start from the declarations, on a first boot only: #reresolve! must leave the ones
+          # #stop_component! set alone, or a reconfiguration would start a stopped component again
+          @order.each { |n| n.release!; n.hold! if n.deferred? }
           @order.each { |n| instrument_component(n, :prepare) { n.prepare_node! } }
           @boot_status = :prepared
         end
@@ -463,6 +506,94 @@ module Sourced
       end
     end
 
+    # ---- Recycling components -------------------------------------------------------
+
+    # Run a component's whole lifecycle again, by key relative to this component: stop it if it's
+    # running, tear it down, drop its value, then prepare and build it from scratch.
+    # Every component depending on it, directly or not, is recycled too: their values were built
+    # from its old one. Its own dependencies are left alone.
+    # Each one is left in the status it had before, so a started component is started again with
+    # +context+, and one that was only built stops at built. A component that was stopped by key
+    # (or deferred) comes back built and still held: the fresh value has never run, so it waits to
+    # be started by key, as it was.
+    # If a stop or teardown hook raises, every component is still torn down and its value dropped,
+    # and the first error is re-raised before anything is prepared again. A prepare, build or start
+    # hook leaves the component where it got to. Either way, recycling again recovers: each one
+    # remembers the status to restore until a recycle completes, so a retry puts it back even when
+    # its own status no longer says it was running.
+    # The root must be built, or started, and not booting.
+    #   app.recycle_component!('sourced.store')
+    def recycle_component!(ckey, context = Thread.current)
+      recycle_components!(ckey, context:)
+    end
+
+    # #recycle_component! for several keys at once: a component depending on more than one of them
+    # is recycled once, not once per key.
+    #   app.recycle_components!('sourced.store', 'repos.users')
+    def recycle_components!(*ckeys, context: Thread.current)
+      synchronize do
+        nodes = ckeys.flatten.map { |ckey| recyclable_node(ckey) }
+        # Recycling nothing resolves no nodes, so it checks the tree itself, and does nothing
+        if nodes.empty?
+          check_recyclable!('components')
+          return self
+        end
+
+        recycle_nodes!(nodes, context)
+      end
+    end
+
+    # #recycle_component! for every component in the tree, in dependency order. Only the root
+    # can recycle the whole tree.
+    #   app.recycle!
+    def recycle!(context = Thread.current)
+      raise_mounted!
+      synchronize do
+        check_recyclable!('the tree')
+        recycle_nodes!(order, context)
+      end
+    end
+
+    # ---- Re-configuring a booted tree ----------------------------------------------
+
+    # Re-declare one branch of a booted tree, by key relative to this component. The block declares
+    # the branch's new contents, and whatever it doesn't declare is removed.
+    # Re-declaring a key is idempotent, so a component that didn't change keeps its value and status.
+    # Re-implementing it, re-typing it, or declaring a new key recycles it (see #recycle_component!),
+    # along with its dependents and anything whose resolved deps changed, ex. a wildcard over the branch.
+    # Nothing runs any hooks until the new set is validated, so a block that raises, or a set with a
+    # missing dep or a cycle, leaves the tree as it was. Holds survive: stopped stays stopped.
+    #   app.reconfigure('reactors') do |reactors|
+    #     files.each { |f| reactors.declare(f.key) }
+    #     changed.each { |f| reactors.component!(f.key, f.deps, &f.implementation) }
+    #   end
+    def reconfigure(ckey, context = Thread.current, &block)
+      raise ArgumentError, "reconfigure #{ckey}: a block must declare the branch's contents" unless block
+
+      synchronize do
+        branch = reconfigurable_branch(ckey)
+        reconf = Reconfiguration.new(branch, self)
+        root.reconfiguring!(reconf)
+
+        begin
+          instrument_root(:reconfigure) do
+            reconf.snapshot!
+            plan = begin
+              block.call(reconf.branch_handle)
+              validate_reconfiguration!(reconf)
+            rescue Exception # rubocop:disable Lint/RescueException -- nothing has run yet: put the tree back, whatever it was. Always re-raised
+              reconf.rollback!
+              raise
+            end
+            commit_reconfiguration!(reconf, plan, context)
+          end
+        ensure
+          root.reconfiguring!(nil)
+        end
+        self
+      end
+    end
+
     # A Component::Graph describing the components under this component, by full path from the root.
     # Components are listed in dependency order once the tree is prepared, and in declaration order before that.
     # Namespaces without an implementation are left out.
@@ -519,7 +650,7 @@ module Sourced
         type:,
         type_name:,
         namespace: namespace?,
-        mounted: !root? && owner.equal?(self),
+        mounted: mounted?,
         implemented: !implementation.nil?,
         mode: implementation&.mode,
         status:,
@@ -540,11 +671,18 @@ module Sourced
 
     # ---- Node internals -------------------------------------------------------------
 
+    # The nodes this one depends on, resolved on #prepare!, wildcards included. See #graph for keys
+    def dep_nodes = @dep_nodes
+
+    # Every node in dependency order, or nil before #prepare!. #ordered_nodes is the checked version
+    def order = @order
+
+    # Whether a #reconfigure dropped this node. Terminal: reading it raises RemovedComponentError
+    def removed? = status == :removed
+
     protected def readable? = @readable
     protected def starting? = @starting
     protected def lock = @lock
-    protected def dep_nodes = @dep_nodes
-    protected def order = @order
 
     private def synchronize(&) = root.lock.synchronize(&)
 
@@ -553,6 +691,29 @@ module Sourced
       @type = Plumb::Composable.wrap(type)
     end
 
+    # Back to an implicit namespace: a dropped component that still has children (see #reconfigure).
+    # Returns the implementation it had, to tear it down with, and keeps its value until then.
+    # Clearing it before the order is resolved leaves it out, and fails validation for its dependents
+    protected def undeclare_type!
+      @implicit = true
+      @type = Plumb::Types::Any
+      @deps = [].freeze
+      @dep_nodes = [].freeze
+      @implementation.tap { @implementation = nil }
+    end
+
+    # Run a reverted component's hooks with the implementation it had, then leave it a bare namespace
+    protected def teardown_reverted!(implementation)
+      return self unless pending?(:teardown)
+
+      begin
+        implementation.stop(value) if started?
+      ensure
+        implementation.teardown(value)
+      end
+      recycle_node!
+    end
+
     protected def implement!(implementation)
       @implementation = implementation
     end
@@ -563,6 +724,48 @@ module Sourced
     protected def release! = @held = false
     protected def started? = status == :started
 
+    # A component mounted into another tree: it owns itself, and isn't the root of its own
+    protected def mounted? = !root? && owner.equal?(self)
+
+    # ---- Reconfiguration internals (see #reconfigure) -------------------------------
+
+    # Public because Component::Reconfiguration is a collaborator, not another Component
+
+    def reconfiguring!(reconf) = @reconfiguration = reconf
+    def restore_order!(order) = @order = order
+
+    # Re-resolve every node's deps and the order, leaving holds alone. Raises if the new set is invalid
+    def reresolve! = resolve_order
+
+    # Everything a reconfiguration can change about this node, as a frozen
+    # Reconfiguration::NodeState. #children and #index are the node's own mutable hashes, so they're
+    # copied; everything else is frozen, or a reference it has to keep as it is — its value above all
+    def capture_state
+      Reconfiguration::NodeState.new(
+        implementation:, type:, implicit: implicit?, deps:, dep_nodes:, deferred: deferred?,
+        held: held?, status:, value:, recycle_to:, children: children.dup, index: index.dup
+      )
+    end
+
+    # Every member, so a new one can't be captured and then forgotten on the way back
+    def restore_state!(state)
+      state.to_h.each { |member, value| send(:"#{member}=", value) }
+      self
+    end
+
+    # Only #capture_state and #restore_state! use these: a reconfiguration rolling back is the one
+    # thing that writes a node's state wholesale
+    private attr_reader :deps
+    private attr_writer :implementation, :type, :implicit, :deps, :dep_nodes, :deferred, :held,
+                        :status, :value, :recycle_to, :children, :index
+
+    # The status a recycle is bringing this node back to, remembered before anything is torn down.
+    # A recycle that raises leaves it set, so a retry restores what the first one meant to: the
+    # node's own status is no use by then, ex. :built for one a failed start never reached
+    protected def recycle_to = @recycle_to
+    protected def recycle_to!(status) = @recycle_to = status
+    protected def recycled! = @recycle_to = nil
+
     # Every node this one depends on, directly or not
     protected def transitive_dependencies
       dep_nodes.each_with_object([]) do |dep, all|
@@ -602,6 +805,22 @@ module Sourced
       parent&.index!("#{key}.#{ckey}", node)
     end
 
+    # The inverse of #index!: drop a descendant here and in every ancestor
+    protected def unindex!(ckey)
+      @index.delete(ckey)
+      parent&.unindex!("#{key}.#{ckey}")
+    end
+
+    # Drop a child and its descendants from this node's children, and from every index
+    protected def detach!(segment)
+      child = @children.delete(segment)
+      return nil unless child
+
+      child.index.each_key { |sub_key| unindex!("#{segment}.#{sub_key}") }
+      unindex!(segment)
+      child
+    end
+
     # Resolve deps through the implementer's index. Called on #prepare!, so declaration order doesn't matter.
     # A wildcard dep ('reactors.*') resolves to a hash of the components directly under its key, by segment,
     # and to an empty hash if there are none.
@@ -651,6 +870,7 @@ module Sourced
 
       implementation.start(value, context)
       @status = :started
+      recycled! # whatever a recycle meant to restore, this is the node's status now
       self
     end
 
@@ -662,25 +882,55 @@ module Sourced
         implementation.stop(value)
       ensure
         @status = :stopped
+        recycled! # ... and the same when a component is stopped by key
       end
       self
     end
 
-    # A started node runs its stop hooks first. Teardown hooks run even if those raise
+    # A started node runs its stop hooks first. Teardown hooks run even if those raise, and the node
+    # is torn down whatever they raise (incl. Interrupt): its hooks have had their turn either way,
+    # and running them again would tear the same value down twice
     protected def teardown_node!
       return self unless pending?(:teardown)
 
+      was_started = started?
+      @status = :torn_down
       begin
-        implementation.stop(value) if started?
+        implementation.stop(value) if was_started
       ensure
         implementation.teardown(value)
       end
-      @status = :torn_down
+      self
+    end
+
+    # Back to :open, so every hook runs again from the top (see #recycle_component!).
+    # Keeps the node's hold, its deps and its place in the root's order: the tree is locked,
+    # so nothing about the graph can have changed
+    protected def recycle_node!
+      @status = :open
+      @value = nil
+      self
+    end
+
+    # Whether the node has been built. A torn down node keeps its value, which stays readable;
+    # recycling drops it, back to :open, and removing it drops it for good
+    protected def built? = !%i[open prepared removed].include?(status)
+
+    # Drop the value and mark the node removed, once torn down: anything still holding it (an
+    # Injector, say) then fails loudly instead of reading a dead value. Terminal
+    protected def remove_node!
+      @value = nil
+      @status = :removed
       self
     end
 
     # Without the readable check: deps are read while the component is building, in dependency order
-    protected def current_value = memoized? ? value : build_value
+    protected def current_value
+      raise RemovedComponentError, "#{path} was removed from the tree" if removed?
+      raise NotBuiltError, "#{path} is not built: it was torn down or recycled" if memoized? && !built?
+
+      memoized? ? value : build_value
+    end
 
     # Whether the value is built once, on #build!: singletons, and aliases of memoized components.
     # Only known once deps are resolved, on #prepare!
@@ -735,11 +985,7 @@ module Sourced
         raise UnimplementedComponentError, "components are deferred but not implemented: #{deferred_namespaces.map(&:path).join(', ')}"
       end
 
-      nodes.each do |n|
-        n.resolve_deps!
-        n.release!
-        n.hold! if n.deferred?
-      end
+      nodes.each { |n| n.resolve_deps! }
 
       each_node = ->(&b) { nodes.each(&b) }
       each_child = ->(n, &b) { n.dep_nodes.each(&b) }
@@ -758,7 +1004,7 @@ module Sourced
         next if !include_built && n.status == :built
 
         instrument_component(n, :teardown) { n.teardown_node! }
-      rescue StandardError => e
+      rescue Exception => e # rubocop:disable Lint/RescueException -- any error (incl. Interrupt) must still tear the rest down. The first is re-raised
         errors << e
       end
     end
@@ -784,6 +1030,137 @@ module Sourced
       target
     end
 
+    # A node to recycle by key: implemented, under a root that can be recycled
+    private def recyclable_node(ckey)
+      target = node(ckey)
+      raise UndeclaredComponentError, "#{target.path} is a namespace, not a component" if target.namespace?
+
+      check_recyclable!(target.path)
+      target
+    end
+
+    # A branch to reconfigure: a namespace, under a tree that isn't booting or torn down
+    private def reconfigurable_branch(ckey)
+      branch = node(ckey)
+      raise LockedComponentError, "can't reconfigure #{branch.path}: a reconfiguration is already running" if root.reconfiguring?
+      raise TornDownError, "can't reconfigure #{branch.path}: the component is torn down" if root.boot_status == :torn_down
+      if root.starting?
+        raise LockedComponentError, "can't reconfigure #{branch.path} while the root is booting"
+      end
+      unless branch.namespace?
+        raise UndeclaredComponentError, "#{branch.path} is a component, not a namespace: reconfigure the branch above it"
+      end
+
+      mounted = [branch, *branch.index.values].find { |n| n.mounted? }
+      raise SubcomponentError, "can't reconfigure #{branch.path}: #{mounted.path} is a mounted component" if mounted
+
+      branch
+    end
+
+    # Apply the new set structurally and re-resolve, before any hooks run: raises what a first boot
+    # would if it's invalid, with nothing torn down yet
+    private def validate_reconfiguration!(reconf)
+      reverting = reconf.reverting
+      removing = reconf.removing
+
+      # Each reverted component hands its implementation back, to tear down once validation passes
+      reverted = reverting.to_h { |n| [n, n.undeclare_type!] }
+      removing.each { |n| n.parent.detach!(n.key) }
+
+      # An open tree has nothing resolved or built: #prepare! validates the set when it boots
+      { reverted:, removing:, order: root.boot_status == :open ? nil : root.reresolve! }
+    end
+
+    # Past validation, so nothing here rolls back: tear down what's going, recycle what changed
+    private def commit_reconfiguration!(reconf, plan, context)
+      booted = !plan[:order].nil?
+      was = reconf.order_before.each_with_index.to_h
+      root.restore_order!(plan[:order]) if booted
+
+      # Dependents first. On an open tree every hook is pending?-skipped, so this only unindexes
+      going = plan[:removing] + plan[:reverted].keys
+      going.sort_by { |n| -(was[n] || -1) }.each do |n|
+        if (implementation = plan[:reverted][n])
+          instrument_component(n, :teardown) { n.teardown_reverted!(implementation) }
+          next
+        end
+
+        instrument_component(n, :teardown) { n.teardown_node! }
+        n.remove_node!
+        emit(Events::ComponentRemoved, key: n.path, remover: path)
+      end
+      return unless booted
+
+      # Nothing new has a status to go back to, so it comes up to where the root is: :prepared,
+      # :built or :started. Deferring lowers that ceiling to :built, never raises it
+      coming_up = root.boot_status
+      reconf.newly_components.each do |n|
+        n.hold! if n.deferred?
+        n.recycle_to!(n.deferred? && coming_up == :started ? :built : coming_up)
+      end
+      affected = reconf.affected
+      recycle_nodes!(affected, context) if affected.any?
+    end
+
+    # Whether the tree can be recycled: built or started, and not booting. +what+ names what
+    # the caller is recycling, for the error messages
+    private def check_recyclable!(what)
+      raise TornDownError, "can't recycle #{what}: the component is torn down" if root.boot_status == :torn_down
+      if root.starting?
+        raise LockedComponentError, "can't recycle #{what} while the root is booting: it has no status to go back to"
+      end
+      return if %i[built started].include?(root.boot_status)
+
+      raise NotBuiltError, "can't recycle #{what} before the root is built: build! it first"
+    end
+
+    # Tear the targets and their dependents down, drop their values, and prepare and build them
+    # again, leaving each one in the status it had before. See #recycle_component!
+    private def recycle_nodes!(targets, context)
+      # Nodes come after their dependencies in the order, so one forward pass seeded with every
+      # target reaches the same nodes as a closure per target, without the walk-per-target
+      reached = targets.to_set
+      root.order.each { |n| reached << n if n.dep_nodes.any? { |dep| reached.include?(dep) } }
+      ordered = root.order.select { |n| reached.include?(n) }
+      # What each node comes back to, remembered before anything is torn down. A node a previous
+      # recycle left part way through keeps the status that recycle meant to restore
+      ordered.each { |n| n.recycle_to!(n.recycle_to || n.status) }
+
+      instrument_root(:recycle) do
+        # Down, dependents first. Started nodes run their stop hooks, then their teardown hooks.
+        # Their values are dropped whatever a hook raises (incl. Interrupt): they've been torn down
+        errors = []
+        begin
+          ordered.reverse.each do |n|
+            instrument_component(n, :teardown) { n.teardown_node! }
+          rescue Exception => e # rubocop:disable Lint/RescueException -- as #teardown_nodes: the rest are still torn down
+            errors << e
+          end
+        ensure
+          ordered.each { |n| n.recycle_node! }
+        end
+        raise errors.first if errors.any?
+
+        # And up again, in dependency order, one stage at a time, as the root boots
+        ordered.each { |n| instrument_component(n, :prepare) { n.prepare_node! } }
+        ordered.each do |n|
+          # A tree that's only prepared stops there: its values are built by #build!, which is what
+          # a process forked after #prepare! runs for itself
+          next if n.recycle_to == :prepared
+
+          instrument_component(n, :build) { n.build_node! }
+        end
+        ordered.each do |n|
+          next unless n.recycle_to == :started && n.dep_nodes.all? { |dep| dep.started? }
+
+          instrument_component(n, :start) { n.start_node!(context) }
+        end
+        # Only once every node is back: a recycle that raises keeps the statuses for the retry
+        ordered.each { |n| n.recycled! }
+      end
+      self
+    end
+
     # ---- Telemetry ------------------------------------------------------------------
 
     # Publish root.<stage>ing, run the block, and publish root.<stage>ed with its duration,
@@ -864,7 +1241,7 @@ module Sourced
       raise ArgumentError, "#{ckey}: pass either a provider or a block, not both" if provider && block
 
       synchronize do
-        raise LockedComponentError, "can't implement #{ckey} in a locked component" if locked?
+        raise LockedComponentError, "can't implement #{ckey} in a locked component" if declarations_locked?
 
         target = node(ckey)
         implementation = if provider
@@ -880,6 +1257,7 @@ module Sourced
     private def implement_node(target, implementation)
       override = !target.implementation.nil?
       target.implement!(implementation)
+      root.reconfiguration&.changed!(target)
       emit(
         Events::ComponentImplemented,
         key: target.path,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sourced-component
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ismael Celis
@@ -75,6 +75,7 @@ files:
 - lib/sourced/component/injector.rb
 - lib/sourced/component/mermaid.rb
 - lib/sourced/component/notifier.rb
+- lib/sourced/component/reconfiguration.rb
 - lib/sourced/component/tree.rb
 - lib/sourced/component/version.rb
 licenses: