woods 2.0.0.beta3 → 2.0.0

data/lib/woods/mcp/initialization_guidance.rb

@@ -11,7 +11,7 @@ module Woods
 
       WORKFLOW = <<~TEXT
         Start with woods_status: check index readiness, generation freshness and relevant type counts before relying on results.
-        For exact names, discover identifiers with search (prefer literal exact_prefix/exact_suffix), then inspect with lookup. For conceptual questions, use codebase_retrieve only when woods_status reports retrieval enabled. Otherwise use search and lookup.
+        For exact names, discover identifiers with search (prefer literal exact_prefix/exact_suffix), then inspect with lookup. For conceptual questions, check retrieval mode and data in woods_status before codebase_retrieve; structural readiness alone is insufficient. Otherwise use search and lookup.
         Follow dependencies or dependents at depth 1 or 2; narrow types and via before paging. Respect partial results and limits: a missing match is not proof of absence, and a partial traversal does not establish every dependent or leaf.
         Verify important conclusions against current source and tests. Recorded relationships and inferred downstream impact do not prove runtime execution or test coverage.
         Registration does not authorize extraction, configuration changes, or live Console access. Use only the tools registered here and operate within the user's authorized scope.

data/lib/woods/mcp/renderers/markdown_renderer.rb

@@ -152,11 +152,11 @@ module Woods
             - **units_indexed** (manifest.json, `structure` tool) — total
               ExtractedUnits written by the extractor. Canonical count.
             - **graph_nodes** (`pagerank`, `dependencies`, `dependents`) —
-              units present in the dependency graph. Excludes orphans
-              that have no incoming or outgoing edges.
+              units present in the dependency graph, including isolated units
+              with no incoming or outgoing edges.
             - **searchable_entries** (`codebase_retrieve`) — retriever-store
-              entries, including per-chunk rows for units long enough to
-              be chunked. Always ≥ units_indexed.
+              entries. Semantic mode may include per-chunk rows; lexical mode
+              ranks published units. Coverage depends on the configured store.
           GLOSSARY
         end
 
@@ -177,7 +177,7 @@ module Woods
 
           GRAPH_ANALYSIS_SECTIONS.each do |section|
             items = fetch_key(data, section)
-            next unless items.is_a?(Array) && items.any?
+            next unless items.is_a?(Array) && (items.any? || fetch_key(data, "#{section}_total"))
 
             lines << "### #{section.tr('_', ' ').capitalize}"
             lines << ''
@@ -194,11 +194,11 @@ module Woods
             end
 
             total_key = "#{section}_total"
-            if data[total_key]
+            if fetch_key(data, total_key)
               lines << ''
               offset = fetch_key(data, "#{section}_offset", 0)
               position = offset.positive? ? " from offset #{offset}" : ''
-              lines << "_Showing #{items.size} of #{data[total_key]}#{position} (truncated)_"
+              lines << "_Showing #{items.size} of #{fetch_key(data, total_key)}#{position} (truncated)_"
             end
             lines << ''
           end
@@ -417,6 +417,8 @@ module Woods
             return lines.join("\n").rstrip
           end
 
+          lines.concat(traversal_coverage_lines(data))
+
           nodes.each do |id, info|
             depth = fetch_key(info, :depth) || 0
             deps = fetch_key(info, :deps, [])
@@ -438,7 +440,11 @@ module Woods
           if fetch_key(data, :partial)
             lines << "Partial traversal (#{fetch_key(data, :partial_reason)}); narrow depth/types/via or increase max_nodes/max_edges."
           end
-          lines << '' << truncation_note(data, nodes.size) if fetch_key(data, :nodes_total)
+          if (note = traversal_lower_bound_note(data, nodes.size))
+            lines << '' << "_#{note}_"
+          elsif fetch_key(data, :nodes_total)
+            lines << '' << truncation_note(data, nodes.size)
+          end
 
           lines.join("\n").rstrip
         end

data/lib/woods/mcp/renderers/plain_renderer.rb

@@ -126,9 +126,9 @@ module Woods
           lines << 'Denominators:'
           lines << '  units_indexed     (manifest, structure): total ExtractedUnits written.'
           lines << '  graph_nodes       (pagerank, dependencies, dependents): units in the graph'
-          lines << '                    (excludes orphans with no incoming/outgoing edges).'
-          lines << '  searchable_entries (codebase_retrieve): retriever-store entries including'
-          lines << '                    per-chunk rows. Always >= units_indexed.'
+          lines << '                    (includes isolated units with no incoming/outgoing edges).'
+          lines << '  searchable_entries (codebase_retrieve): retriever-store entries; semantic mode may include'
+          lines << '                    per-chunk rows; lexical mode ranks published units. Store coverage varies.'
 
           lines.join("\n").rstrip
         end
@@ -146,7 +146,7 @@ module Woods
 
           GRAPH_ANALYSIS_SECTIONS.each do |section|
             items = fetch_key(data, section)
-            next unless items.is_a?(Array) && items.any?
+            next unless items.is_a?(Array) && (items.any? || fetch_key(data, "#{section}_total"))
 
             lines << "#{section.tr('_', ' ').upcase}:"
             items.each do |item|
@@ -161,9 +161,9 @@ module Woods
 
             total_key = "#{section}_total"
             offset = fetch_key(data, "#{section}_offset", 0)
-            if data[total_key]
+            if fetch_key(data, total_key)
               position = offset.positive? ? " from offset #{offset}" : ''
-              lines << "  (showing #{items.size} of #{data[total_key]}#{position}; truncated)"
+              lines << "  (showing #{items.size} of #{fetch_key(data, total_key)}#{position}; truncated)"
             end
             lines << ''
           end
@@ -279,6 +279,8 @@ module Woods
             return lines.join("\n").rstrip
           end
 
+          lines.concat(traversal_coverage_lines(data))
+
           nodes.each do |id, info|
             depth = fetch_key(info, :depth) || 0
             deps = fetch_key(info, :deps, [])
@@ -294,7 +296,9 @@ module Woods
           if fetch_key(data, :partial)
             lines << "Partial traversal (#{fetch_key(data, :partial_reason)}); narrow depth/types/via or increase max_nodes/max_edges."
           end
-          if fetch_key(data, :nodes_total)
+          if (note = traversal_lower_bound_note(data, nodes.size))
+            lines << note
+          elsif fetch_key(data, :nodes_total)
             offset = fetch_key(data, :nodes_offset, 0)
             position = offset.positive? ? " from offset #{offset}" : ''
             lines << "  (showing #{nodes.size} of #{fetch_key(data, :nodes_total)}#{position}; truncated)"

data/lib/woods/mcp/server.rb

@@ -12,6 +12,7 @@ require_relative '../atomic_file'
 require_relative '../generation'
 require_relative '../tasks'
 require_relative '../watch/status'
+require_relative '../watch/supervision_status'
 require_relative '../filename_utils'
 require_relative '../update_check'
 require_relative '../retrieval/source_evidence'
@@ -27,6 +28,7 @@ require_relative 'tasks/request_capture'
 require_relative 'tasks/store'
 require_relative 'tool_contract'
 require_relative 'tool_response_renderer'
+require_relative 'traversal_response'
 require_relative 'version_aware_tool_dispatch'
 
 module Woods
@@ -73,6 +75,7 @@ module Woods
       # controls that actually shrink the answer are `depth`, `types` and
       # `via`; `limit` and `offset` only page what those leave (B-183).
       DEFAULT_TRAVERSAL_LIMIT = 50
+      DEFAULT_GRAPH_ANALYSIS_LIMIT = 20
 
       class << self
         # Build a configured MCP::Server with all tools and resources.
@@ -161,7 +164,8 @@ module Woods
                                              'Narrow with depth, types and via first: they shrink the answer, ' \
                                              'while limit and offset only page it. Returns a BFS tree with ' \
                                              "depth, paged to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default. " \
-                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff. ' \
+                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff and total_is_exact is false. ' \
+                                             'Published relationships are not exhaustive source-reference coverage. ' \
                                              'Use explain:true for recorded directed relationships and bounded witnesses; ambiguous types remain explicit.',
                                 reader_method: :traverse_dependencies,
                                 render_key: :dependencies)
@@ -171,7 +175,8 @@ module Woods
                                              'Narrow with depth, types and via first: they shrink the answer, ' \
                                              'while limit and offset only page it. Returns a BFS tree with ' \
                                              "depth, paged to #{DEFAULT_TRAVERSAL_LIMIT} nodes by default. " \
-                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff. ' \
+                                             'max_nodes/max_edges bound the walk independently; partial_reason reports a budget cutoff and total_is_exact is false. ' \
+                                             'Published relationships are not exhaustive source-reference coverage. ' \
                                              'Use explain:true for recorded directed relationships and bounded witnesses; ambiguous types remain explicit.',
                                 reader_method: :traverse_dependents,
                                 render_key: :dependents)
@@ -247,9 +252,9 @@ module Woods
           !token.nil? && ids && !ids.empty?
         end
 
-        def text_response(text)
+        def text_response(text, data: nil)
           structured = { text: text }
-          structured[:data] = JSON.parse(text)
+          structured[:data] = data.nil? ? JSON.parse(text) : data
           ::MCP::Tool::Response.new(
             [{ type: 'text', text: text }],
             structured_content: structured
@@ -393,7 +398,7 @@ module Woods
 
           sliced = offset.positive? ? original.drop(offset) : original
           container[key] = limit ? truncate_section(sliced, limit) : sliced
-          if original.size > offset + (limit || original.size)
+          if offset.positive? || container[key].size < original.size
             container["#{key}_total"] = original.size
             container["#{key}_truncated"] = true
           end
@@ -403,12 +408,11 @@ module Woods
         # Page a traversal result's `nodes` hash in place, in BFS order.
         #
         # Mirrors {#paginate_section}'s metadata keys (`nodes_total`,
-        # `nodes_truncated`, `nodes_offset`) so both renderers print the one
-        # truncation line they already had for `graph_analysis`. A page that
-        # holds every node adds no keys at all, so a small result renders
-        # exactly as it did before the bound existed (B-183).
+        # `nodes_truncated`, `nodes_offset`). A page that holds every admitted
+        # node adds no pagination keys (B-183). TraversalResponse separately
+        # annotates scope and total exactness before pagination.
         #
-        # `nodes_total` marks *any* partial answer, not only one with more
+        # `nodes_total` marks *any* paged answer, not only one with more
         # behind it. Keying it on `total > offset + limit` left the last page
         # of a walk indistinguishable from a complete one: 21 nodes of 121,
         # with nothing saying 100 were skipped. `nodes_truncated` still means
@@ -656,9 +660,10 @@ module Woods
               result[:message] =
                 "Identifier '#{identifier}' not found in the index. Use 'search' to find valid identifiers."
             end
+            TraversalResponse.annotate(result)
             paginate_nodes.call(result, limit || DEFAULT_TRAVERSAL_LIMIT, offset || 0)
             TraversalEvidencePage.apply(result)
-            respond.call(renderer.render(render_key, result))
+            respond.call(renderer.render(render_key, result), data: result)
           end
         end
 
@@ -698,32 +703,20 @@ module Woods
                   enum: ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS + %w[all],
                   description: 'Which analysis to return. Default: all'
                 },
-                limit: { type: 'integer', description: 'Limit results per section (default: 20)' },
+                limit: { type: 'integer', description: "Limit results per section (default: #{DEFAULT_GRAPH_ANALYSIS_LIMIT})" },
                 offset: { type: 'integer', description: 'Skip this many results per section (default: 0)' }
               }
             }
           ) do |server_context:, analysis: nil, limit: nil, offset: nil|
-            limit = coerce_int.call(limit)
+            limit = coerce_int.call(limit) || DEFAULT_GRAPH_ANALYSIS_LIMIT
             offset = coerce_int.call(offset)
             data = reader.graph_analysis
             section = analysis || 'all'
             effective_offset = offset || 0
 
-            result = if section == 'all'
-                       if limit || effective_offset.positive?
-                         truncated = data.dup
-                         ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS.each do |key|
-                           paginate.call(truncated, key, limit, effective_offset)
-                         end
-                         truncated
-                       else
-                         data
-                       end
-                     else
-                       single = { section => data[section] || [], 'stats' => data['stats'] }
-                       paginate.call(single, section, limit, effective_offset) if limit || effective_offset.positive?
-                       single
-                     end
+            result = section == 'all' ? data.dup : { section => data[section] || [], 'stats' => data['stats'] }
+            sections = section == 'all' ? ToolResponseRenderer::GRAPH_ANALYSIS_SECTIONS : [section]
+            sections.each { |key| paginate.call(result, key, limit, effective_offset) }
 
             respond.call(renderer.render(:graph_analysis, result))
           end
@@ -936,6 +929,7 @@ module Woods
           coerce = method(:coerce_array)
           stale_check = method(:stale_index_result?)
           degraded_response = method(:degraded_retrieval_response)
+          corpus_status = method(:retriever_corpus_status)
           retrieval_mode = retriever.respond_to?(:mode) ? retriever.mode : :semantic
           server.define_tool(
             name: 'codebase_retrieve',
@@ -962,13 +956,13 @@ module Woods
                                'rails_source, test_mapping, etc.). Overrides the default test_mapping exclusion. ' \
                                'Lexical mode and explicit package/path scopes filter before limits and omit the global rank table. ' \
                                'In semantic mode, when the unfiltered top-K has no requested type, the retriever ' \
-                               'falls back to rank-within-type so the response is populated whenever units of ' \
-                               'the requested type exist in the index. The response appends a "Type rank ' \
+                               'falls back to rank-within-type over the available vectors. The response appends a "Type rank ' \
                                'context" table with per-type: source, rank in unfiltered top-K, global_k, ' \
-                               'total_of_type. Read source to tell the cases apart: in_top_k (strong match), ' \
+                               'total_of_type (retrieval metadata records, not structural or embedded units). ' \
+                               'Read source to tell the cases apart: in_top_k (strong match), ' \
                                'within_type_fallback (weak match surfaced by the fallback), outside_top_k ' \
-                               '(index has this type but other requested types filled the result), absent ' \
-                               '(zero units of this type in the index).'
+                               '(retrieval metadata has this type but other requested types filled the result), absent ' \
+                               '(zero retrieval metadata records of this type; structural units may still exist).'
                 },
                 packages: { type: 'array', items: { type: 'string' },
                             description: 'Exact published nearest package owners. OR within the list; AND with paths and type eligibility.' },
@@ -1023,6 +1017,16 @@ module Woods
               )
             end
             if retriever
+              corpus = corpus_status.call(retriever, include_types: false)
+              if corpus && corpus[:state] == 'empty'
+                next respond_err.call(
+                  'Semantic retrieval has no vectors or retrieval metadata. The structural index may still be ready. ' \
+                  'Run `woods:embed` in the application environment and reload the index, or use ' \
+                  'explicit `WOODS_RETRIEVAL_MODE=lexical` and restart for retrieval without embeddings. ' \
+                  'Use `search` and `lookup` for structural discovery.',
+                  code: :empty_index, tool: 'codebase_retrieve', corpus: corpus
+                )
+              end
               begin
                 scope_options = if Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
                                   { packages: packages, source_paths: source_paths }
@@ -1072,6 +1076,8 @@ module Woods
                 'Semantic search is disabled — no embedding provider is configured. ' \
                 'To enable: set OPENAI_API_KEY, or run Ollama locally ' \
                 '(brew install ollama && ollama serve && ollama pull nomic-embed-text). ' \
+                'For ranked discovery with no embeddings, set WOODS_RETRIEVAL_MODE=lexical in the MCP process ' \
+                'environment and restart the server. See docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval. ' \
                 'Use the `search` tool for pattern-based matching in the meantime.',
                 code: :not_configured,
                 config_key: 'embedding_provider',
@@ -1144,12 +1150,15 @@ module Woods
 
           server.define_tool(
             name: 'trace_flow',
-            description: 'Trace execution flow from an entry point through the codebase',
+            description: 'Trace a source-derived flow from an exact indexed unit, optionally scoped by #method. ' \
+                         'Receiverless local calls may remain unexpanded; this is not proof of runtime execution.',
             input_schema: {
               properties: {
                 entry_point: {
                   type: 'string',
-                  description: 'Entry point (e.g., UsersController#create)'
+                  description: 'Exact UnitIdentifier, optionally followed by #method (e.g., UsersController#create ' \
+                               'or CheckoutService#order). Bare names identify units, including factories; ' \
+                               'a bare method name does not locate its owning class. Use search and lookup first.'
                 },
                 depth: {
                   type: 'integer',
@@ -2081,7 +2090,10 @@ module Woods
             name: 'woods_status',
             description: 'Diagnose whether the Woods index and server are healthy. Returns extraction metadata ' \
                          '(last run, unit counts, git SHA, staleness in seconds), retriever/embedding configuration, ' \
-                         'bootstrap state (hydrated / degraded / failed + reason), feature flags, and a ready flag. ' \
+                         'bootstrap state (hydrated / degraded / failed + reason), and feature flags. ' \
+                         'Top-level `ready` describes structural index availability. ' \
+                         'Semantic corpus diagnostics report local vector/metadata record counts separately; ' \
+                         'unknown counts are null, and nonempty counts do not prove complete embedding coverage. ' \
                          'Includes source-content freshness; quick scans have a 250ms budget, explicit deep scans have 5s. ' \
                          'Incomplete evidence is unknown. Call this first on cold connect.',
             input_schema: { type: 'object', properties: {
@@ -2145,10 +2157,11 @@ module Woods
             },
             index: index_section(manifest, extracted_at, staleness, index_dir, reader, source_check),
             watch: watch_section(index_dir),
+            supervision: index_dir ? Woods::Watch::SupervisionStatus.read(index_dir.to_s) : { records: [] },
             retriever: {
               configured: !retriever.nil?,
               class: retriever&.class&.name,
-              **(retriever.respond_to?(:mode) && retriever.mode == :lexical ? { mode: 'lexical' } : {})
+              **retriever_status_fields(retriever)
             },
             bootstrap: bootstrap_state&.to_h,
             features: retrieval_features(config, resolved, retriever)
@@ -2157,6 +2170,19 @@ module Woods
 
         private
 
+        def retriever_status_fields(retriever)
+          return { mode: 'lexical' } if retriever.respond_to?(:mode) && retriever.mode == :lexical
+
+          corpus = retriever_corpus_status(retriever)
+          corpus ? { corpus: corpus } : {}
+        end
+
+        def retriever_corpus_status(retriever, include_types: true)
+          return if retriever.respond_to?(:mode) && retriever.mode == :lexical
+
+          retriever.corpus_status(include_types: include_types) if retriever.respond_to?(:corpus_status)
+        end
+
         # Assemble the +index+ sub-hash of woods_status, including a staleness
         # gate that compares +manifest.git_sha+ against the current HEAD. The
         # manifest captures +git_sha+ / +gemfile_lock_sha+ / +schema_sha+ at

data/lib/woods/mcp/tool_contract.rb

@@ -27,7 +27,7 @@ module Woods
           text: { type: 'string' },
           data: {
             type: %w[object array string number boolean null],
-            description: 'Parsed JSON payload when the selected renderer emits JSON.'
+            description: 'Structured tool payload, including traversal data in every renderer; otherwise parsed JSON when available.'
           }
         },
         required: ['text'],

data/lib/woods/mcp/tool_response_renderer.rb

@@ -70,6 +70,22 @@ module Woods
 
       private
 
+      def traversal_coverage_lines(data)
+        coverage = fetch_key(data, :graph_coverage)
+        notice = fetch_key(coverage, :notice) if coverage.is_a?(Hash)
+        notice ? [notice] : []
+      end
+
+      def traversal_lower_bound_note(data, shown)
+        return unless fetch_key(data, :total_is_exact) == false
+
+        total = fetch_key(data, :nodes_total, shown)
+        offset = fetch_key(data, :nodes_offset, 0)
+        position = offset.positive? ? " from offset #{offset}" : ''
+        "Showing #{shown} of at least #{total}#{position} " \
+          "(total unknown: #{fetch_key(data, :partial_reason)})."
+      end
+
       def search_completeness_lines(data)
         evidence = fetch_key(data, :completeness)
         return [] unless evidence.is_a?(Hash)

data/lib/woods/mcp/traversal_evidence_text.rb

@@ -40,7 +40,7 @@ module Woods
         complete = value(witness, :typed_path_complete) ? 'yes' : 'no'
         context = value(witness, :context) ? 'yes' : 'no'
         "#{identifier}: #{value(witness, :impact)}; parent=#{parent}; edge=#{edge}; " \
-          "typed path complete=#{complete}; context only=#{context}"
+          "witness types unambiguous=#{complete}; context only=#{context}"
       end
 
       def self.value(hash, key)

data/lib/woods/mcp/traversal_response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Woods
+  module MCP
+    # Response scope is independent of traversal evidence and page selection.
+    module TraversalResponse
+      COVERAGE = {
+        scope: 'published_relationships',
+        source_references: 'not_exhaustive',
+        notice: 'Graph coverage: published relationships only. Arbitrary method-body constant references ' \
+                'are not exhaustively captured; missing relationships do not prove no callers or dependencies.'
+      }.freeze
+
+      def self.annotate(result)
+        return if result[:found] == false
+
+        result[:graph_coverage] = COVERAGE
+        result[:total_is_exact] = !result[:partial]
+      end
+    end
+  end
+end

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
@@ -161,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),
@@ -188,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],

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/rake_helpers.rb

@@ -183,11 +183,8 @@ module Woods
         woods_sweep_index_dir(output_dir, lock_name)
       end
 
-      # The lock was released (and its file removed) above; drop the guard so
-      # the directory can empty, then remove the now-empty directory. Another
-      # writer may legitimately have recreated content between release and here
-      # — a non-empty directory is left alone rather than forced.
-      woods_remove_if_empty(output_dir, lock_name)
+      # Retain the stable guard and directory: another writer may already hold
+      # the guard after release, before it has created its extraction.lock.
       :cleaned
     end
 
@@ -205,13 +202,6 @@ module Woods
       end
     end
 
-    def woods_remove_if_empty(output_dir, lock_name)
-      FileUtils.rm_f(output_dir.join(Woods::Coordination::PipelineLock.guard_filename(lock_name)))
-      Dir.rmdir(output_dir)
-    rescue SystemCallError
-      nil
-    end
-
     # The root containing the Rakefile that loaded this task file.
     #
     # `woods:watch_status` intentionally avoids Rails boot, so it cannot ask

data/lib/woods/retrieval/corpus_status.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Woods
+  module Retrieval
+    # Bounded, local diagnostics: never probe remote stores or providers.
+    # Nonempty counts establish presence, not alignment, completeness, or
+    # provider health. Metadata-only corpora can still serve non-vector paths.
+    module CorpusStatus
+      module_function
+
+      # @return [Hash] state and independently known local store statistics
+      def build(vector_store, metadata_store, include_types: true)
+        vectors = local_stats(vector_store, include_types: include_types)
+        metadata = local_stats(metadata_store, include_types: include_types)
+        { state: state(vectors[:count], metadata[:count]), vectors: vectors, metadata: metadata }
+      end
+
+      def local_stats(store, include_types:)
+        return unknown unless store.respond_to?(:local_corpus_stats)
+
+        stats = store.local_corpus_stats(include_types: include_types)
+        return unknown unless stats[:count].is_a?(Integer) && stats[:count] >= 0
+
+        stats
+      rescue StandardError, NotImplementedError
+        unknown
+      end
+      private_class_method :local_stats
+
+      def unknown
+        { count: nil, by_type: nil, untyped_count: nil }
+      end
+      private_class_method :unknown
+
+      def state(vectors, metadata)
+        return 'unknown' if vectors.nil? || metadata.nil?
+        return 'empty' if vectors.zero? && metadata.zero?
+        return 'metadata_only' if vectors.zero?
+        return 'vectors_only' if metadata.zero?
+
+        'nonempty'
+      end
+      private_class_method :state
+    end
+  end
+end