woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/obsidian/note_builder.rb

@@ -28,12 +28,15 @@ module Woods
       ASSOCIATION_ORDER = %w[belongs_to has_one has_many has_and_belongs_to_many].freeze
 
       # @param name_mapper [NameMapper] resolves ids to wikilinks/paths
-      # @param nodes [Hash] graph nodes ({ id => { 'type' => , ... } }) for edge-endpoint types
+      # @param nodes [Hash] note-key => graph node for edge-endpoint types
       # @param pagerank [Hash{String=>Float}] persisted pagerank scores
       # @param analysis [Hash, nil] parsed graph_analysis.json (hubs/cycles/orphans/bridges) or nil
       # @param include_source [Boolean] embed scrubbed source code
       # @param scanner [#scan, nil] credential scanner (required when include_source)
-      def initialize(name_mapper:, nodes:, pagerank: {}, analysis: nil, include_source: false, scanner: nil)
+      def initialize(name_mapper:, nodes:, pagerank: {}, analysis: nil, include_source: false, scanner: nil,
+                     identifiers: {}, ambiguous_identifiers: Set.new)
+        @identifiers = identifiers
+        @ambiguous_identifiers = ambiguous_identifiers
         @mapper = name_mapper
         @nodes = nodes || {}
         @pagerank = pagerank || {}
@@ -45,10 +48,10 @@ module Woods
         @cycle_members = cycle_member_set(analysis)
       end
 
-      # @param id [String] bare unit identifier (graph node key)
+      # @param id [String, Array<String>] note key: bare id for standalone use, or [identifier, type]
       # @param unit [Hash] parsed unit JSON (used only for body facts)
       # @param depends_on [Array<Hash>] [{ target:, via: }] filtered to the emitted set
-      # @param used_by [Array<String>] unique dependent ids filtered to the emitted set
+      # @param used_by [Array<String, Array<String>>] unique dependent note keys filtered to the emitted set
       # @return [String] the rendered note. A failed source scrub omits the source
       #   section (the note is still written); build never returns nil.
       def build(id:, unit:, depends_on:, used_by:)
@@ -74,7 +77,7 @@ module Woods
       def frontmatter(id, unit, depends_on, used_by)
         fm = {
           'woods_managed' => true,
-          'id' => id,
+          'id' => @identifiers.fetch(id, id),
           'type' => unit['type'],
           'file' => unit['file_path'],
           'source_hash' => unit['source_hash'],
@@ -82,17 +85,23 @@ module Woods
           'dependency_count' => depends_on.size,
           'dependent_count' => used_by.size,
           'tags' => tags_for(id, unit),
-          'aliases' => [id]
+          'aliases' => [@identifiers.fetch(id, id)]
         }.compact
         "#{fm.to_yaml}---"
       end
 
+      def analysis_identifier(id)
+        identifier = @identifiers.fetch(id, id)
+        identifier unless @ambiguous_identifiers.include?(identifier)
+      end
+
       def pagerank_for(id)
-        score = @pagerank[id]
+        score = @pagerank[analysis_identifier(id)]
         score&.round(6)
       end
 
       def tags_for(id, unit)
+        id = analysis_identifier(id)
         tags = ['woods/unit', "woods/#{unit['type']}"]
         tags << 'woods/hub' if @hubs.include?(id)
         tags << 'woods/orphan' if @orphans.include?(id)
@@ -124,11 +133,11 @@ module Woods
       end
 
       def callout(id, used_by)
-        if @hubs.include?(id)
+        if @hubs.include?(analysis_identifier(id))
           pr = pagerank_for(id)
           suffix = pr ? " (PageRank #{format('%.4f', pr)})" : ''
           "> [!warning] Hub — high blast radius\n> #{used_by.size} units depend on this#{suffix}."
-        elsif @cycle_members.include?(id)
+        elsif @cycle_members.include?(analysis_identifier(id))
           "> [!warning] Part of a dependency cycle\n> This unit participates in a circular dependency."
         end
       end
@@ -181,7 +190,7 @@ module Woods
         return [] unless items
 
         items.filter_map do |assoc|
-          link = @mapper.wikilink(assoc[:target])
+          link = @mapper.wikilink_for_identifier(assoc[:target])
           next unless link
 
           assoc[:dependent] ? "#{link} (dependent: #{assoc[:dependent]})" : link

data/lib/woods/obsidian/vault_exporter.rb

@@ -10,6 +10,7 @@ require_relative 'errors'
 require_relative 'name_mapper'
 require_relative 'note_builder'
 require_relative 'vault_assets'
+require_relative 'destination_plan'
 
 module Woods
   module Obsidian
@@ -72,7 +73,7 @@ module Woods
       def export_all
         with_pinned_index do
           graph = @reader.raw_graph_data || {}
-          @nodes = graph['nodes'] || {}
+          prepare_graph(graph)
           @pagerank = graph['pagerank'] || {}
           analysis = safe_graph_analysis
           owned = vault_owned_at_start?
@@ -82,16 +83,24 @@ module Woods
           edge_map = build_edge_map(emitted.to_set, graph)
           builder = build_note_builder(mapper, analysis)
 
+          @planned_writes = {}
           written = Set.new
           errors = []
           exported = write_notes(emitted, mapper, edge_map, builder, written, errors)
           indexes = write_indexes(emitted, mapper, written)
           write_sidecar(emitted, mapper, graph, analysis, written)
           write_owned_assets(emitted) if owned
+          DestinationPlan.new(@vault, @planned_writes, managed_note: method(:managed_marker?)).commit
 
-          swept = owned && errors.empty? ? sweep(written) : 0
+          swept = owned && errors.empty? && skipped.zero? ? sweep(written) : 0
           warn_foreign unless owned
           { exported: exported, indexes: indexes, swept: swept, skipped: skipped, errors: cap_errors(errors) }
+        rescue StandardError => e
+          log "  Export stopped: #{e.class}: #{e.message}"
+          { exported: 0, indexes: 0, swept: 0, skipped: skipped || 0,
+            errors: cap_errors(Array(errors) + ["#{e.class}: #{e.message}"]) }
+        ensure
+          @planned_writes = nil
         end
       end
 
@@ -119,19 +128,35 @@ module Woods
 
       # ── Selection / mapping ──────────────────────────────────────────
 
+      # Keep typed identity local to the exporter. Public identifiers and graph
+      # artifacts retain their original shape; variants have their own outgoing
+      # relationships, while persisted edge targets remain bare identifiers.
+      def prepare_graph(graph)
+        @primary = graph['nodes'] || {}
+        @nodes = @primary.to_h { |id, node| [[id, node['type']], node] }
+        @forward = @nodes.keys.to_h { |key| [key, Array(graph.dig('edges', key.first))] }
+        Array(graph['variants']).grep(Hash).each do |record|
+          key = [record['identifier'], record['type']]
+          next if key.any?(&:nil?) || @nodes.key?(key)
+
+          @nodes[key] = record
+          @forward[key] = Array(record['edges'])
+        end
+        @identifiers = @nodes.keys.to_h { |key| [key, key.first] }
+        @keys_by_identifier = @nodes.keys.group_by(&:first)
+        @ambiguous = @keys_by_identifier.select { |_, keys| keys.size > 1 }.keys.to_set
+      end
+
       # The emitted set = graph nodes of an exportable type that have a loadable
       # unit file. Confirming the file loads (not just that the index lists it)
       # guarantees every wikilink target is backed by a real note — a node listed
       # in the index but with no readable unit is dropped (counted as skipped).
       #
-      # @return [Array(Array<String>, Integer)] [sorted emitted ids, skipped count]
+      # @return [Array(Array<Array<String>>, Integer)] [sorted typed keys, skipped count]
       def partition_emitted
-        known = known_ids
         candidates = @nodes.keys.select do |id|
           type = @nodes[id]['type']
-          next false if !@include_framework && FRAMEWORK_TYPES.include?(type)
-
-          known.include?(id)
+          @include_framework || !FRAMEWORK_TYPES.include?(type)
         end.sort
 
         # Load each candidate once and keep it: confirms the unit is readable
@@ -151,18 +176,20 @@ module Woods
       # Load a unit, treating an unreadable/corrupt file as absent rather than
       # letting one bad JSON parse abort the whole export.
       def load_unit(id)
-        @reader.find_unit(id)
+        unit = if @ambiguous.include?(id.first)
+                 @reader.find_unit(id.first, type: id.last)
+               else
+                 @reader.find_unit(id.first)
+               end
+        unit if unit && unit['identifier'] == id.first && unit['type'] == id.last
       rescue StandardError => e
         log "  skipped #{id}: #{e.class}: #{e.message}"
         nil
       end
 
-      def known_ids
-        @known_ids ||= @reader.list_units.to_set { |entry| entry['identifier'] }
-      end
-
       def build_mapper(emitted)
-        NameMapper.new(emitted.to_h { |id| [id, dir_for(@nodes[id]['type'])] })
+        NameMapper.new(emitted.to_h { |id| [id, dir_for(@nodes[id]['type'])] },
+                       identifiers: @identifiers, ambiguous_identifiers: @ambiguous)
       end
 
       def dir_for(type)
@@ -182,25 +209,37 @@ module Woods
 
       def build_note_builder(mapper, analysis)
         NoteBuilder.new(name_mapper: mapper, nodes: @nodes, pagerank: @pagerank,
-                        analysis: analysis, include_source: @include_source, scanner: scanner)
-      end
-
-      # The single edge source: per-id forward (depends_on) and reverse (used_by)
-      # edges from the graph, filtered to the emitted set, self-edges dropped.
-      def build_edge_map(emitted, graph)
-        edges = graph['edges'] || {}
-        reverse = graph['reverse'] || {}
-        emitted.each_with_object({}) do |id, map|
-          deps = Array(edges[id]).filter_map { |edge| forward_edge(edge, id, emitted) }
-                                 .uniq { |edge| [edge[:target], edge[:via]] }
-          used = Array(reverse[id]).select { |sid| sid != id && emitted.include?(sid) }.uniq
-          map[id] = { depends_on: deps, used_by: used }
+                        analysis: analysis, include_source: @include_source, scanner: scanner,
+                        identifiers: @identifiers, ambiguous_identifiers: @ambiguous)
+      end
+
+      # Reverse links must come from resolved forward edges: the legacy reverse
+      # index merges source types, and cannot assign them to a particular note.
+      # A bare target naming several graph types remains ambiguous even if only
+      # one sibling is exportable. Do not invent a typed relationship.
+      def build_edge_map(emitted, _graph)
+        @ambiguous_edges = Set.new
+        map = emitted.to_h { |id| [id, { depends_on: [], used_by: [] }] }
+        emitted.each do |id|
+          deps = @forward[id].filter_map { |edge| forward_edge(edge, id, emitted) }
+                             .uniq { |edge| [edge[:target], edge[:via]] }
+          map[id][:depends_on] = deps
+          deps.each { |edge| map[edge[:target]][:used_by] << id }
         end
+        map.each_value { |edges| edges[:used_by].uniq! }
+        log "  omitted #{@ambiguous_edges.size} ambiguous dependency relationships" unless @ambiguous_edges.empty?
+        map
       end
 
       def forward_edge(edge, source_id, emitted)
         edge = { 'target' => edge } unless edge.is_a?(Hash)
-        target = edge['target']
+        identifier = edge['target']
+        if @ambiguous.include?(identifier)
+          @ambiguous_edges << [source_id, identifier, edge['via']]
+          return nil
+        end
+
+        target = @keys_by_identifier[identifier]&.first
         return nil if target == source_id || !emitted.include?(target)
 
         { target: target, via: edge['via'] }
@@ -263,11 +302,22 @@ module Woods
       # ── Pass 3b: machine sidecar ─────────────────────────────────────
 
       def write_sidecar(emitted, mapper, graph, analysis, written)
-        notes = emitted.to_h do |id|
-          [id, { 'path' => mapper.path_for(id), 'type' => @nodes[id]['type'],
-                 'pagerank' => @pagerank[id]&.round(6) }.compact]
+        notes = {}
+        variants = []
+        emitted.each do |key|
+          id, type = key
+          info = { 'path' => mapper.path_for(key), 'type' => type }
+          info['pagerank'] = @pagerank[id].round(6) if @pagerank[id] && !@ambiguous.include?(id)
+          if @primary.dig(id, 'type') == type
+            notes[id] = info
+          else
+            variants << { 'identifier' => id }.merge(info)
+          end
         end
-        manifest = { 'schema_version' => 1, 'notes' => sort_hash(notes), 'paths' => sort_hash(mapper.paths_to_ids) }
+        paths = mapper.paths_to_ids.transform_values(&:first)
+        manifest = { 'schema_version' => @ambiguous.empty? ? 1 : 2,
+                     'notes' => sort_hash(notes), 'paths' => sort_hash(paths) }
+        manifest['variants'] = variants if manifest['schema_version'] == 2
         write_json(written, "#{SIDECAR_DIR}/manifest.json", manifest)
         write_json(written, "#{SIDECAR_DIR}/dependency_graph.json", graph)
         write_json(written, "#{SIDECAR_DIR}/graph_analysis.json", analysis) if analysis
@@ -282,6 +332,8 @@ module Woods
           safe_write(@vault.join('.obsidian', 'graph.json'), VaultAssets.graph_json(present_types(emitted)))
           safe_write(@vault.join('Units.base'), VaultAssets.units_base)
         end
+        return if @vault.join(SENTINEL).exist?
+
         safe_write(@vault.join(SENTINEL),
                    "woods-managed vault — regenerated by `rake woods:obsidian`. Safe to delete.\n")
       end
@@ -410,7 +462,11 @@ module Woods
       def safe_write(path, content)
         raise PathTraversalError, "refusing to write outside the vault: #{path}" unless safe_inside_vault?(path)
 
-        AtomicFile.write(path, content)
+        if @planned_writes
+          @planned_writes[path] = content
+        else
+          AtomicFile.write(path, content)
+        end
       end
 
       # ── Ownership ────────────────────────────────────────────────────

data/lib/woods/operator/pipeline_guard.rb

@@ -85,14 +85,18 @@ module Woods
 
       # Reset one supported operation or all supported operations atomically.
       #
+      # An explicit :all reset also repairs corrupt state; scoped resets leave it
+      # untouched so unknown cooldowns are not silently discarded.
+      #
       # @param operation [Symbol, String] `:extraction`, `:embedding`, or `:all`
-      # @return [Boolean] true when at least one cooldown was removed
+      # @return [Boolean] true when a cooldown was removed or corrupt state repaired
       # @raise [ArgumentError] when the operation is unsupported
       def reset!(operation)
         operations = reset_operations(operation)
-        return false unless requested_state_present?(operations)
+        repair_corrupt = operation.to_s == 'all'
+        return false unless requested_state_present?(operations, repair_corrupt: repair_corrupt)
 
-        with_existing_locked_state do |state|
+        with_existing_locked_state(repair_corrupt: repair_corrupt) do |state|
           changed = false
           operations.each do |key|
             next unless state.key?(key)
@@ -135,28 +139,29 @@ module Woods
         end
       end
 
-      def parse_state(content)
-        state = content.empty? ? {} : JSON.parse(content)
-        state.is_a?(Hash) ? state : {}
+      def parse_state(content, fallback: {})
+        state = JSON.parse(content)
+        state.is_a?(Hash) ? state : fallback
       rescue JSON::ParserError
-        {}
+        fallback
       end
 
-      def requested_state_present?(operations)
+      def requested_state_present?(operations, repair_corrupt:)
         File.open(@state_path, File::RDONLY) do |file|
           file.flock(File::LOCK_SH)
-          state = parse_state(file.read)
-          operations.any? { |key| state.key?(key) }
+          state = parse_state(file.read, fallback: nil)
+          state ? operations.any? { |key| state.key?(key) } : repair_corrupt
         end
       rescue Errno::ENOENT
         false
       end
 
-      def with_existing_locked_state
+      def with_existing_locked_state(repair_corrupt:)
         File.open(@state_path, File::RDWR) do |file|
           file.flock(File::LOCK_EX)
-          state = parse_state(file.read)
-          changed = yield(state)
+          parsed = parse_state(file.read, fallback: nil)
+          state = parsed || {}
+          changed = yield(state) || (repair_corrupt && parsed.nil?)
           if changed
             file.rewind
             file.write(JSON.generate(state))

data/lib/woods/path_dispatcher.rb

@@ -16,10 +16,9 @@ module Woods
   #
   # * {.file_rules} — file-based extractors, whose per-file method can be
   #   pointed straight at the new path.
-  # * {.whole_app_rules} — extractors with no per-file entry point (routes,
-  #   middleware, engines, scheduled jobs, state machines, factories,
-  #   events, framework sources). Their trigger paths map to a wholesale
-  #   re-run of that extractor, which is cheap in an already-booted process.
+  # * {.whole_app_rules} — extractors needing the complete runtime or source
+  #   set (routes, middleware, merged Rake tasks, scheduled jobs, etc.). Their
+  #   trigger paths map to a wholesale re-run of that extractor.
   #
   # Class-based extractors (models, controllers, mailers, components,
   # channels) are deliberately *absent* here. They are reconciled against
@@ -94,6 +93,11 @@ module Woods
     end
 
     class << self
+      # Runtime-discovered classes have no per-file extractor method.
+      def runtime_rules
+        @runtime_rules ||= [Rule.new(dirs: %w[app], extensions: %w[.rb])].freeze
+      end
+
       # Rules for extractors with a per-file entry point.
       #
       # @return [Array<Rule>]
@@ -147,6 +151,7 @@ module Woods
           # ConcernExtractor globs app/**/concerns, not just the two canonical
           # directories — match any .rb under app/ inside a concerns/ segment.
           file_rule(:concerns, :extract_concern_file, %w[app], require_segment: '/concerns/'),
+          file_rule(:concerns, :extract_model_mixin_file, %w[app lib], exclude: %w[/concerns/]),
           # GraphQL types sit outside FILE_BASED (they share one extractor
           # method across four unit types via GRAPHQL_TYPES), which is exactly
           # why the FILE_BASED-driven coverage guard never noticed they had no
@@ -155,7 +160,6 @@ module Woods
           file_rule(:graphql, :extract_graphql_file,
                     [ex::GraphQLExtractor::GRAPHQL_DIRECTORY], extensions: %w[.rb]),
           file_rule(:i18n, :extract_i18n_file, ex::I18nExtractor::I18N_DIRECTORIES, extensions: %w[.yml]),
-          file_rule(:rake_tasks, :extract_rake_file, ex::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
           file_rule(:view_templates, :extract_view_template_file,
                     ex::ViewTemplateExtractor::VIEW_DIRECTORIES, extensions: view_template_extensions),
           file_rule(:migrations, :extract_migration_file, %w[db/migrate], recursive: false),
@@ -182,6 +186,9 @@ module Woods
 
       def build_whole_app_rules
         [
+          # A task may combine definitions from several files; any change or
+          # deletion must reconcile the complete task set, not its primary file.
+          whole_app_rule(:rake_tasks, Woods::Extractors::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
           whole_app_rule(:routes, %w[config/routes], exact_paths: %w[config/routes.rb]),
           whole_app_rule(:engines, %w[config/routes], exact_paths: %w[config/routes.rb Gemfile.lock]),
           whole_app_rule(:middleware, %w[config/initializers config/environments],
@@ -258,7 +265,7 @@ module Woods
     # @param relative_path [String] Rails.root-relative path
     # @return [Boolean]
     def relevant?(relative_path)
-      return true if relative_path.start_with?('app/') && relative_path.end_with?('.rb')
+      return true if self.class.runtime_rules.any? { |rule| rule.matches?(relative_path) }
 
       file_rules_for(relative_path).any? || whole_app_keys_for(relative_path).any?
     end

data/lib/woods/payload_store.rb

@@ -2,7 +2,6 @@
 
 require 'pathname'
 require 'fileutils'
-require 'find'
 
 module Woods
   # Writer-side owner of the per-generation payload directories.
@@ -95,19 +94,19 @@ module Woods
     # @param target [Pathname, String] a directory returned by {#create}
     # @return [void]
     def clone(source, target)
-      from = Pathname.new(source.to_s)
-      return unless from.directory?
-
-      to = Pathname.new(target.to_s)
-      # The one directory `find` never offers: it yields the root as `.`, and
-      # a caller seeding a subtree (Extractor#seed_payload_from_flat_root)
-      # passes a target that does not exist yet.
-      FileUtils.mkdir_p(to.to_s)
-      from.find do |entry|
-        relative = entry.relative_path_from(from)
-        next if relative.to_s == '.'
-
-        replicate(entry, to.join(relative))
+      from = File.expand_path(source.to_s)
+      return unless File.directory?(from)
+
+      to = target.to_s
+      FileUtils.mkdir_p(to)
+      pending = [[from, to]]
+      until pending.empty?
+        source_dir, target_dir = pending.pop
+        Dir.each_child(source_dir) do |name|
+          entry = File.join(source_dir, name)
+          destination = File.join(target_dir, name)
+          replicate(entry, destination, pending)
+        end
       end
     end
 
@@ -172,7 +171,7 @@ module Woods
     # @param destination [Pathname, String] where it should land
     # @return [void]
     def link_or_copy(source, destination)
-      FileUtils.ln(source.to_s, destination.to_s)
+      File.link(source.to_s, destination.to_s)
     rescue Errno::EXDEV, Errno::EPERM, Errno::EMLINK, NotImplementedError
       FileUtils.cp(source.to_s, destination.to_s)
     end
@@ -215,19 +214,21 @@ module Woods
       end
     end
 
-    # `Pathname#find` is a pre-order walk: a directory is always visited
-    # before anything inside it. So the directory branch has already created
-    # every parent a file could need, and the `mkdir_p` the file branch used
-    # to run was one stat-heavy syscall chain per unit re-proving what the
-    # previous entry established. On a payload of 8000+ files that was the
-    # bulk of the incremental seed.
+    # Classify once: Find.find followed by File.directory? queried metadata
+    # twice per file, costly on FUSE/virtiofs mounts. Parents are created before
+    # their children, so regular files need no extra parent-directory checks.
+    # Preserve the old walk's symlink behavior: a directory symlink becomes an
+    # empty directory, never a traversal into another tree or generation.
     #
-    # @param entry [Pathname] source entry, as `find` yielded it
-    # @param destination [Pathname] where it belongs in the target
+    # @param entry [String] source entry
+    # @param destination [String] where it belongs in the target
+    # @param pending [Array] directories still to visit
     # @return [void]
-    def replicate(entry, destination)
-      if entry.directory?
-        FileUtils.mkdir_p(destination.to_s)
+    def replicate(entry, destination, pending)
+      stat = File.lstat(entry)
+      if stat.directory? || (stat.symlink? && File.directory?(entry))
+        FileUtils.mkdir_p(destination)
+        pending << [entry, destination] if stat.directory?
       else
         link_or_copy(entry, destination)
       end

data/lib/woods/published_index/typed_unit_reader.rb

@@ -21,10 +21,47 @@ module Woods
       # @return [Hash, nil] string-keyed unit, or nil when this type has no
       #   such identifier
       def self.call(payload_dir, reader, identifier, type)
-        dir = Woods::MCP::IndexReader::TYPE_TO_DIR[type]
+        dir = directory_for(type)
         return nil unless dir
-        return nil unless reader.list_units(type: type).any? { |entry| entry['identifier'] == identifier }
 
+        family = Woods::MCP::IndexReader::DIR_TO_TYPE.fetch(dir)
+        return nil unless reader.list_units(type: family).any? { |entry| entry['identifier'] == identifier }
+
+        unit = read_unit(payload_dir, dir, identifier)
+        unit if unit && (unit['type'] == type || type == family)
+      end
+
+      # Resolve actual published types as well as historical directory-family aliases.
+      #
+      # @param type [String]
+      # @return [String, nil]
+      def self.directory_for(type)
+        Woods::MCP::IndexReader::TYPE_TO_DIR[type] ||
+          Woods::MCP::IndexReader::UNIT_TYPES_BY_DIR.find { |_, types| types.include?(type) }&.first
+      end
+
+      # Preserve subtype identity in an index entry from a shared type directory.
+      #
+      # @param payload_dir [Pathname]
+      # @param entry [Hash] published index entry
+      # @param dir [String] type directory
+      # @param requested_type [String, nil] actual type or family alias
+      # @return [Hash, nil] entry with actual type, or nil when filtered out
+      def self.entry(payload_dir, entry, dir, requested_type)
+        family = Woods::MCP::IndexReader::DIR_TO_TYPE.fetch(dir)
+        actual_type = if Woods::MCP::IndexReader::UNIT_TYPES_BY_DIR.fetch(dir).size > 1
+                        read_unit(payload_dir, dir, entry['identifier'])&.fetch('type')
+                      else
+                        family
+                      end
+        return unless actual_type
+        return if requested_type && requested_type != family && requested_type != actual_type
+
+        entry.merge('type' => actual_type)
+      end
+
+      # Read a unit whose directory-index membership has already been established.
+      def self.read_unit(payload_dir, dir, identifier)
         path = payload_dir.join(dir, filename_for(identifier))
         return nil unless path.file?
 
@@ -42,7 +79,7 @@ module Woods
         "#{base}_#{digest}.json"
       end
 
-      private_class_method :filename_for
+      private_class_method :filename_for, :read_unit
     end
   end
 end

data/lib/woods/published_index.rb

@@ -167,14 +167,14 @@ module Woods
     # @return [Array<Hash>]
     def units(type: nil)
       dirs = if type
-               dir = Woods::MCP::IndexReader::TYPE_TO_DIR[type.to_s]
+               dir = TypedUnitReader.directory_for(type.to_s)
                dir ? [dir] : []
              else
                Woods::MCP::IndexReader::TYPE_DIRS
              end
       dirs.flat_map do |dir|
         @reader.list_units(type: Woods::MCP::IndexReader::DIR_TO_TYPE[dir])
-               .map { |entry| entry.merge('type' => Woods::MCP::IndexReader::DIR_TO_TYPE[dir]) }
+               .filter_map { |entry| TypedUnitReader.entry(@payload_dir, entry, dir, type&.to_s) }
       end
     end
 

data/lib/woods/railtie.rb

@@ -14,8 +14,8 @@ module Woods
   # flags and tokens set in `config/initializers/woods.rb` (the
   # generator-created location) do not exist yet when middleware arguments
   # are captured. Both guards are scoped to `console_mcp_path` — requests
-  # outside it pass through untouched — and while `console_mcp_enabled` is
-  # false the whole stack passes through, so an unconfigured host app is
+  # outside it pass through untouched — and while `console_mcp_enabled` or
+  # `console_mcp_http_enabled` is false the whole stack passes through, so an unconfigured host app is
   # completely unaffected. Boot-time validation of the settled configuration
   # happens in `after_initialize` via {Woods::RailtieSupport}.
   #
@@ -84,7 +84,7 @@ module Woods
       # BearerAuth next — requires `Authorization: Bearer <token>` at the
       # console path, failing closed (401) while no usable token is
       # configured. Both are scoped to the console path and inert while
-      # console_mcp_enabled is false.
+      # either console_mcp_enabled or console_mcp_http_enabled is false.
       app.middleware.use(
         Woods::MCP::OriginGuard,
         allowed_origins: Woods::RailtieSupport.console_allowed_origins_proc,