woods 1.6.1 → 2.0.0.beta2

data/lib/woods/atomic_file.rb

@@ -19,10 +19,36 @@ module Woods
 
     # Atomically write +content+ to +path+, creating parent directories.
     #
+    # Permissions are explicit per artifact (O1): the default is the
+    # restrictive 0600 Tempfile already uses, and only an artifact with a
+    # documented cross-boundary consumer passes a wider mode (today exactly
+    # one: the watch daemon's +watch_status.json+, read by host-side hooks
+    # through a bind mount).
+    #
+    # +durable:+ chooses when the bytes are forced to the disk, never whether
+    # the write is atomic. Both paths go tempfile, chmod, rename, so a reader
+    # sees the old content or the new content and never a torn partial.
+    # +durable: false+ drops the two forced flushes (the temp file's own
+    # +fsync+ and the containing directory's), which is the whole cost of the
+    # write on a journalling filesystem: roughly 8.9ms per file against
+    # 0.11ms without, measured on btrfs.
+    #
+    # It is only safe for a file with no reader until something else commits
+    # it. Woods' payload files qualify: every reader resolves through
+    # +generation.json+, and that pointer is written durably after
+    # {.sync_directory_tree} has flushed the payload it names. A file whose
+    # readers do not go through the pointer (the watch daemon's status, the
+    # update check's cache, an export, an embedding checkpoint) must stay
+    # durable.
+    #
     # @param path [String, Pathname] destination path
     # @param content [String] file content
+    # @param mode [Integer] permissions for the written file (default 0600)
+    # @param durable [Boolean] force the bytes to disk before returning
+    #   (default true). Pass false only for a file that something else makes
+    #   durable before any reader can resolve it.
     # @return [void]
-    def write(path, content)
+    def write(path, content, mode: 0o600, durable: true)
       path = path.to_s
       FileUtils.mkdir_p(File.dirname(path))
       tmp = Tempfile.new('.woods-', File.dirname(path))
@@ -31,13 +57,156 @@ module Woods
       tmp.binmode
       tmp.write(content)
       tmp.flush
-      tmp.fsync
+      tmp.fsync if durable
       tmp.close
+      # Chmod the temp file so the destination is born with its final
+      # permissions — never observed more open or more closed in between.
+      File.chmod(mode, tmp.path)
       File.rename(tmp.path, path)
+      fsync_directory(File.dirname(path)) if durable
     rescue StandardError
       tmp&.close
       tmp&.unlink
       raise
     end
+
+    # Make every file under +directory+ durable with one filesystem flush.
+    #
+    # The counterpart to {.write}'s +durable: false+. Thousands of per-file
+    # +fsync+ calls and one +syncfs+ buy the same guarantee for a payload that
+    # is published all at once, and cost 71.3s against 1.0s for 8000 files on
+    # btrfs.
+    #
+    # Strategies, in order, first one that works wins:
+    #
+    # 1. +syncfs(2)+ on a descriptor for +directory+, through Fiddle. Linux
+    #    only, and flushes exactly the one filesystem the payload is on.
+    # 2. +sync -f <dir>+ (GNU coreutils), the same call through a subprocess.
+    # 3. +sync+ with no arguments (BSD/macOS), which flushes everything
+    #    mounted rather than one filesystem, but is still one call.
+    # 4. an +fsync+ on every file and directory in the tree.
+    #
+    # The last resort is what keeps the guarantee honest: the chain never
+    # silently does nothing, it only ever gets slower.
+    #
+    # Fiddle is a default gem through Ruby 3.4 and a bundled gem from 3.5, so
+    # the require lives inside a rescue and Fiddle is deliberately not in the
+    # gemspec. A host without it lands on +sync -f+.
+    #
+    # @param directory [String, Pathname] the tree to flush
+    # @return [Symbol, nil] the strategy that ran (+:syncfs+, +:sync_f+,
+    #   +:sync+, +:fsync_pass+), or nil when the directory does not exist
+    def sync_directory_tree(directory)
+      directory = directory.to_s
+      return nil unless File.directory?(directory)
+
+      strategy = syncfs(directory) || sync_f(directory) || plain_sync || fsync_pass(directory)
+      log_sync_strategy(strategy, directory)
+      strategy
+    end
+
+    # @return [Symbol, nil] +:syncfs+ when the libc call succeeded
+    def syncfs(directory)
+      call = syncfs_function
+      return nil unless call
+
+      succeeded = File.open(directory, File::RDONLY) { |dir| call.call(dir.fileno).zero? }
+      succeeded ? :syncfs : nil
+    rescue StandardError
+      nil
+    end
+
+    # Resolved once per process, and nil for the whole process when it cannot
+    # be. `dlopen` is not free, and a failed `require 'fiddle'` prints a
+    # bundled-gem warning on every attempt from Ruby 3.5 onward, and a publish
+    # must not emit one line of noise per generation.
+    #
+    # @return [Fiddle::Function, nil]
+    def syncfs_function
+      return @syncfs_function if defined?(@syncfs_function)
+
+      @syncfs_function = begin
+        require 'fiddle'
+        Fiddle::Function.new(Fiddle.dlopen(nil)['syncfs'], [Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+      rescue LoadError, StandardError
+        # No Fiddle in the bundle, no libc symbol (macOS has none), or the
+        # handle would not open. `sync -f` is next in the chain.
+        nil
+      end
+    end
+
+    # @return [Symbol, nil] +:sync_f+ when `sync -f` exited 0
+    def sync_f(directory)
+      :sync_f if system('sync', '-f', directory, out: File::NULL, err: File::NULL)
+    rescue StandardError
+      nil
+    end
+
+    # @return [Symbol, nil] +:sync+ when a bare `sync` exited 0
+    def plain_sync
+      :sync if system('sync', out: File::NULL, err: File::NULL)
+    rescue StandardError
+      nil
+    end
+
+    # @return [Symbol] always +:fsync_pass+; this is the floor of the chain
+    def fsync_pass(directory)
+      Dir.glob(File.join(directory, '**', '*'), File::FNM_DOTMATCH).each do |entry|
+        next if %w[. ..].include?(File.basename(entry))
+
+        fsync_path(entry)
+      end
+      fsync_path(directory)
+      # The directory entry that names this tree lives in the parent, so a
+      # freshly created (or renamed) payload directory is only durable once
+      # the parent is flushed too. The three faster strategies flush a whole
+      # filesystem and cover this for free; only the scoped pass has to say
+      # it.
+      fsync_path(File.dirname(directory))
+      :fsync_pass
+    end
+
+    # @param path [String] file or directory to flush
+    # @return [void]
+    def fsync_path(path)
+      File.open(path, File::RDONLY, &:fsync)
+    rescue Errno::EINVAL, Errno::ENOTSUP, Errno::EISDIR, Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    # @return [void]
+    def log_sync_strategy(strategy, directory)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.debug { "[Woods] payload sync via #{strategy} on #{directory}" }
+    end
+
+    def fsync_directory(directory)
+      File.open(directory, File::RDONLY, &:fsync)
+    rescue Errno::EINVAL, Errno::ENOTSUP, Errno::EISDIR
+      nil
+    end
+
+    # Read a file Woods wrote, as UTF-8.
+    #
+    # The counterpart to {.write}, and not a nicety. {.write} goes through
+    # `binmode` so the content's bytes land verbatim — but a plain `File.read`
+    # tags what comes back with the process's *default external encoding*, and
+    # a container with no locale set (`LANG=C`, the default in a plain Docker
+    # image — precisely where the watch daemon is documented to run) makes that
+    # US-ASCII. Any byte above 0x7F then raises
+    # `Encoding::InvalidByteSequenceError` on the first `JSON.parse`.
+    #
+    # That is not hypothetical for Woods' own artifacts: the daemon writes
+    # status reasons containing em dashes, so one ordinary lock contention
+    # under `LANG=C` used to break `woods:watch_status`, the hook sync's
+    # daemon-deference check and the `woods_status` tool until something
+    # rewrote the file with an ASCII-only reason.
+    #
+    # @param path [String, Pathname] file to read
+    # @return [String] UTF-8 content
+    def read(path)
+      File.read(path.to_s, encoding: Encoding::UTF_8)
+    end
   end
 end

data/lib/woods/builder.rb

@@ -8,6 +8,8 @@ require_relative 'storage/metadata_store'
 require_relative 'storage/graph_store'
 require_relative 'embedding/provider'
 require_relative 'embedding/openai'
+require_relative 'embedding/fake'
+require_relative 'resilience/retryable_provider'
 require_relative 'embedding/text_preparer'
 require_relative 'embedding/token_counter'
 require_relative 'token_utils'
@@ -69,7 +71,8 @@ module Woods
 
     # Build a {Configuration} populated with the named preset's adapter types.
     #
-    # @param name [Symbol] Preset name — one of :local, :postgresql, or :production
+    # @param name [Symbol] Preset name — one of :local, :shared_filesystem,
+    #   :postgresql, or :production
     # @return [Configuration] A new Configuration with preset values applied
     # @raise [ArgumentError] if the preset name is not recognized
     def self.preset_config(name)
@@ -107,13 +110,13 @@ module Woods
     #   on disk and passes the populated store here.
     # @return [Retriever, Cache::CachedRetriever] A fully wired retriever
     def build_retriever(vector_store: nil, metadata_store: nil, graph_store: nil)
-      provider = build_embedding_provider
+      provider = build_resilient_embedding_provider
       cache = build_cache_store
 
       provider = wrap_with_embedding_cache(provider, cache) if cache
 
       retriever = Retriever.new(
-        vector_store: vector_store || build_vector_store,
+        vector_store: vector_store || build_vector_store(dimensions: vector_dimensions(provider)),
         metadata_store: metadata_store || build_metadata_store,
         graph_store: graph_store || build_graph_store,
         embedding_provider: provider
@@ -124,19 +127,56 @@ module Woods
 
     # Instantiate the vector store adapter specified by the configuration.
     #
+    # The :pgvector branch also ensures the adapter's own schema exists —
+    # see {#build_pgvector_store}.
+    #
     # @return [Storage::VectorStore::Interface] Vector store adapter instance
     # @raise [ArgumentError] if the configured type is not recognized
-    def build_vector_store
+    # @raise [Woods::Error] if the pgvector schema cannot be created
+    def build_vector_store(dimensions: nil)
       case @config.vector_store
       when :in_memory then Storage::VectorStore::InMemory.new
-      when :pgvector then Storage::VectorStore::Pgvector.new(**(@config.vector_store_options || {}))
-      when :qdrant then Storage::VectorStore::Qdrant.new(**(@config.vector_store_options || {}))
+      when :pgvector then build_pgvector_store(dimensions)
+      when :qdrant then build_qdrant_store(dimensions)
       else raise ArgumentError, "Unknown vector_store: #{@config.vector_store}"
       end
     end
 
+    # The provider's advertised dimension count, when a durable store needs
+    # one to size its column or collection.
+    #
+    # Probed exactly like {#safe_max_input_tokens}: {#provider_object?}'s
+    # contract is that only +#embed+/+#embed_batch+ are required of an
+    # injected provider and the rest of the interface is checked at each call
+    # site, and a provider that merely includes {Embedding::Provider::Interface}
+    # answers +respond_to?+ with a +NotImplementedError+ stub (B-108). Either
+    # way the answer is "no dimensions", which lets
+    # {#resolve_pgvector_dimensions}/{#resolve_qdrant_dimensions} fall back to
+    # the explicit +vector_store_options[:dimensions]+ they document (STO-6).
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @return [Integer, nil]
+    def vector_dimensions(provider)
+      return nil unless %i[pgvector qdrant].include?(@config.vector_store)
+      return nil unless provider.respond_to?(:dimensions)
+
+      provider.dimensions
+    rescue NotImplementedError
+      nil
+    end
+    private :vector_dimensions
+
     # Instantiate the embedding provider specified by the configuration.
     #
+    # `embedding_provider` accepts three shapes (#178):
+    # - +:openai+ / +:ollama+ — the network-backed adapters.
+    # - +:fake+ — {Embedding::Provider::Fake}: deterministic, offline, for
+    #   CI/smoke runs. See {#build_fake_provider} for dimension resolution.
+    # - an already-constructed provider *object* — anything responding to
+    #   +#embed+ and +#embed_batch+ is returned as-is, so hosts can plug in
+    #   their own implementation without patching the Builder. It flows
+    #   through {#build_resilient_embedding_provider} like the built-ins.
+    #
     # Strips `embedding_options` keys that belong to the ResolvedConfig layer
     # (like `:dimension`) before splatting into the provider's constructor —
     # those keys are useful for the Snapshotter's schema header but
@@ -145,27 +185,148 @@ module Woods
     # @return [Embedding::Provider::Interface] Embedding provider instance
     # @raise [ArgumentError] if the configured type is not recognized
     def build_embedding_provider
-      opts = provider_kwargs
-      case @config.embedding_provider
+      configured = @config.embedding_provider
+      return configured if provider_object?(configured)
+
+      opts = provider_kwargs(configured)
+      case configured
       when :openai then Embedding::Provider::OpenAI.new(**opts)
       when :ollama then Embedding::Provider::Ollama.new(**opts)
-      else raise ArgumentError, "Unknown embedding_provider: #{@config.embedding_provider}"
+      when :fake then build_fake_provider(opts)
+      else
+        raise ArgumentError,
+              "Unknown embedding_provider: #{configured}. Valid: :openai, :ollama, :fake, " \
+              'or a provider object responding to #embed and #embed_batch'
       end
     end
 
-    # Kwargs accepted by embedding provider constructors — everything in
-    # `embedding_options` except metadata fields that live there for
-    # ResolvedConfig bookkeeping.
-    SNAPSHOT_ONLY_KEYS = %i[dimension].freeze
-    private_constant :SNAPSHOT_ONLY_KEYS
+    # Wrap an embedding provider in the resilience stack: retry with
+    # full-jitter exponential backoff (Retry-After aware) plus a dedicated
+    # {Resilience::CircuitBreaker}.
+    #
+    # This is the provider every pipeline entry point must hand to the
+    # Indexer or Retriever — with it, a transient 429/5xx burst degrades a
+    # run instead of aborting it (#188 / B-076). {#build_embedding_provider}
+    # deliberately keeps returning the *raw* provider: the MCP boot path
+    # ({MCP::ProviderProbe}) dispatches on the provider's concrete class and
+    # reads its internals, so the wrap happens here, one layer up.
+    #
+    # Each call constructs a fresh breaker — breaker state is per-instance
+    # and must never be shared across unrelated components.
+    #
+    # The wrap is harmless for providers that never raise transient
+    # failures ({Embedding::Provider::Fake}, most injected provider
+    # objects): nothing retryable ever fires, so the wrapper is a
+    # transparent pass-through.
+    #
+    # @param provider [Embedding::Provider::Interface] raw provider to wrap;
+    #   defaults to a freshly built one from the configuration
+    # @return [Resilience::RetryableProvider] the wrapped provider
+    def build_resilient_embedding_provider(provider = build_embedding_provider)
+      Resilience::RetryableProvider.new(
+        provider: provider,
+        circuit_breaker: Resilience::CircuitBreaker.new
+      )
+    end
+
+    PROVIDER_OPTION_KEYS = {
+      openai: %i[api_key model dimension dimensions],
+      ollama: %i[model host num_ctx read_timeout dimension dimensions],
+      fake: %i[model dims dimension dimensions]
+    }.freeze
+    private_constant :PROVIDER_OPTION_KEYS
 
-    def provider_kwargs
+    def provider_kwargs(configured)
       opts = (@config.embedding_options || {}).transform_keys(&:to_sym)
-      SNAPSHOT_ONLY_KEYS.each { |k| opts.delete(k) }
+      validate_provider_options!(configured, opts)
+      apply_embedding_model!(opts)
+      normalize_dimension_option!(configured, opts)
+      validate_required_provider_options!(configured, opts)
       opts
     end
     private :provider_kwargs
 
+    def validate_provider_options!(configured, opts)
+      allowed = PROVIDER_OPTION_KEYS[configured]
+      return unless allowed
+
+      unknown = opts.keys - allowed
+      return if unknown.empty?
+
+      provider_name = configured.to_s.capitalize
+      noun = unknown.one? ? 'option' : 'options'
+      raise ConfigurationError,
+            "Unknown #{provider_name} embedding #{noun}: #{unknown.join(', ')}. " \
+            "Valid options: #{allowed.join(', ')}"
+    end
+    private :validate_provider_options!
+
+    def validate_required_provider_options!(configured, opts)
+      return unless configured == :openai
+      return unless opts[:api_key].nil? || opts[:api_key].to_s.empty?
+
+      raise ConfigurationError,
+            'OpenAI requires embedding_options[:api_key]. Set it explicitly, typically from OPENAI_API_KEY.'
+    end
+    private :validate_required_provider_options!
+
+    def apply_embedding_model!(opts)
+      return if opts.key?(:model)
+      return unless @config.respond_to?(:embedding_model_explicit?) && @config.embedding_model_explicit?
+
+      opts[:model] = @config.embedding_model
+    end
+    private :apply_embedding_model!
+
+    def normalize_dimension_option!(configured, opts)
+      legacy_dimension = opts.delete(:dimension)
+      dimensions = opts.delete(:dimensions)
+      if conflicting_dimensions?(legacy_dimension, dimensions)
+        raise ConfigurationError, 'embedding_options dimension and dimensions must match when both are provided'
+      end
+
+      dimension = dimensions || legacy_dimension
+      return unless dimension
+
+      opts[configured == :fake ? :dims : :dimensions] ||= dimension
+    end
+    private :normalize_dimension_option!
+
+    def conflicting_dimensions?(legacy_dimension, dimensions)
+      !legacy_dimension.nil? && !dimensions.nil? && legacy_dimension != dimensions
+    end
+    private :conflicting_dimensions?
+
+    # True when the configured `embedding_provider` is not a Symbol naming a
+    # built-in adapter but an already-constructed provider object (#178).
+    # Duck-typed on the two methods every pipeline consumer calls; the rest
+    # of {Embedding::Provider::Interface} (+#dimensions+, +#model_name+,
+    # +#max_input_tokens+) is probed with +respond_to?+ at each call site,
+    # so an object that omits them still works where they are optional.
+    #
+    # @param candidate [Object]
+    # @return [Boolean]
+    def provider_object?(candidate)
+      !candidate.is_a?(Symbol) && candidate.respond_to?(:embed) && candidate.respond_to?(:embed_batch)
+    end
+    private :provider_object?
+
+    # Build the deterministic fake provider (#178).
+    #
+    # Dimension resolution: `embedding_options[:dims]` maps directly onto
+    # the {Embedding::Provider::Fake} constructor; failing that, the
+    # ResolvedConfig-level `embedding_options[:dimension]` key — normally
+    # snapshot-only bookkeeping stripped by {#provider_kwargs} — is
+    # honoured, so hosts that declare their dimension there (and the MCP
+    # boot path, which restores exactly that key from woods.json) get
+    # vectors of the recorded dimension.
+    #
+    # @return [Embedding::Provider::Fake]
+    def build_fake_provider(opts)
+      Embedding::Provider::Fake.new(**opts)
+    end
+    private :build_fake_provider
+
     # Build a {Embedding::TextPreparer} calibrated to a given provider.
     #
     # OpenAI embedders use tiktoken (cl100k_base) — 4.0 chars/token is a
@@ -184,7 +345,7 @@ module Woods
     # @return [Embedding::TextPreparer]
     def build_text_preparer(provider)
       chars_per_token = chars_per_token_for(provider)
-      budget = provider.respond_to?(:max_input_tokens) ? provider.max_input_tokens : nil
+      budget = safe_max_input_tokens(provider)
       max_tokens = budget || Embedding::TextPreparer::DEFAULT_MAX_TOKENS
 
       Embedding::TextPreparer.new(max_tokens: max_tokens, chars_per_token: chars_per_token)
@@ -215,7 +376,7 @@ module Woods
     # @param provider [Embedding::Provider::Interface]
     # @return [Chunking::SemanticChunker]
     def build_chunker(provider)
-      budget = provider.respond_to?(:max_input_tokens) ? provider.max_input_tokens : nil
+      budget = safe_max_input_tokens(provider)
       max_chars = ((budget * chars_per_token_for(provider)).floor - CHUNKER_PREFIX_ALLOWANCE if budget)
 
       # Guard against a budget so small that the prefix allowance leaves
@@ -256,7 +417,7 @@ module Woods
     # @param provider [Embedding::Provider::Interface]
     # @return [Embedding::TokenCounter, nil]
     def token_counter_for(provider)
-      return unless provider.is_a?(Embedding::Provider::Ollama)
+      return unless unwrap_provider(provider).is_a?(Embedding::Provider::Ollama)
 
       Embedding::TokenCounter.new
     end
@@ -268,16 +429,50 @@ module Woods
     # @param provider [Embedding::Provider::Interface]
     # @return [Float]
     def chars_per_token_for(provider)
-      symbol = case provider
+      symbol = case unwrap_provider(provider)
                when Embedding::Provider::Ollama then :ollama
                else :openai
                end
       TokenUtils.chars_per_token_for(symbol)
     end
 
+    # Provider input-token budget, or nil when the provider has none.
+    # `respond_to?` alone is the wrong guard here: {Embedding::Provider::Interface}
+    # *defines* +max_input_tokens+ as a +NotImplementedError+ stub, so a
+    # provider that merely includes the interface without overriding it
+    # still answers +respond_to?+ with +true+ (B-108) and raises when
+    # called. A provider with no such method at all still needs the
+    # +respond_to?+ guard to avoid a bare +NoMethodError+.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @return [Integer, nil]
+    def safe_max_input_tokens(provider)
+      return nil unless provider.respond_to?(:max_input_tokens)
+
+      provider.max_input_tokens
+    rescue NotImplementedError
+      nil
+    end
+
+    # Reach the concrete provider through the resilience wrapper.
+    # Tokenizer calibration dispatches on the provider's real class, so a
+    # {Resilience::RetryableProvider} handed to {#build_text_preparer} or
+    # {#build_chunker} must calibrate exactly like its inner provider —
+    # without this, a wrapped Ollama silently got OpenAI ratios.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @return [Embedding::Provider::Interface] the innermost provider
+    def unwrap_provider(provider)
+      provider.is_a?(Resilience::RetryableProvider) ? provider.provider : provider
+    end
+
     # Diagnostic for the build_chunker budget guard.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @param budget [Integer]
+    # @return [String]
     def chunker_budget_message(provider, budget)
-      "embedding model '#{provider.respond_to?(:model) ? provider.model : provider.class}' " \
+      "embedding model '#{provider.respond_to?(:model_name) ? provider.model_name : provider.class}' " \
         "reports a max_input_tokens of #{budget}, which leaves no room for " \
         "the chunk prefix (#{CHUNKER_PREFIX_ALLOWANCE} chars). Configure a " \
         'model with a larger native context, or set num_ctx explicitly.'
@@ -292,11 +487,18 @@ module Woods
     def build_metadata_store
       case @config.metadata_store
       when :in_memory then Storage::MetadataStore::InMemory.new
-      when :sqlite then Storage::MetadataStore::SQLite.new(**(@config.metadata_store_options || {}))
+      when :sqlite then Storage::MetadataStore::SQLite.new(**sqlite_metadata_options)
       else raise ArgumentError, "Unknown metadata_store: #{@config.metadata_store}"
       end
     end
 
+    def sqlite_metadata_options
+      opts = (@config.metadata_store_options || {}).transform_keys(&:to_sym)
+      opts[:database] ||= File.join(@config.output_dir.to_s, 'metadata.sqlite3')
+      opts
+    end
+    private :sqlite_metadata_options
+
     # Instantiate the graph store adapter specified by the configuration.
     #
     # @return [Storage::GraphStore::Interface] Graph store adapter instance
@@ -310,6 +512,92 @@ module Woods
 
     private
 
+    # Construct the pgvector adapter and ensure its schema exists.
+    #
+    # The adapter reads and writes its own `woods_vectors` table. The
+    # `woods:pgvector` generator can create it via a migration, but nothing
+    # guarantees that migration ran — so the builder calls the adapter's
+    # idempotent {Storage::VectorStore::Pgvector#ensure_schema!}
+    # (CREATE ... IF NOT EXISTS DDL) after construction. Without this, the
+    # first embed against a bare database fails with PG::UndefinedTable
+    # (#187 / B-075). Schema/connection failures are re-raised as
+    # {Woods::Error} with the original error preserved as the cause.
+    #
+    # @return [Storage::VectorStore::Pgvector]
+    # @raise [Woods::Error] when the schema cannot be created
+    def build_pgvector_store(provider_dimensions)
+      opts = (@config.vector_store_options || {}).transform_keys(&:to_sym)
+      validate_required_store_options!(:pgvector, opts, :connection)
+      opts[:dimensions] = resolve_pgvector_dimensions(provider_dimensions, opts[:dimensions])
+      store = Storage::VectorStore::Pgvector.new(**opts)
+      begin
+        store.ensure_schema!
+        verify_pgvector_dimensions!(store, opts[:dimensions])
+      rescue ConfigurationError
+        raise
+      rescue StandardError => e
+        raise Woods::Error,
+              "pgvector schema setup failed (#{e.class}: #{e.message}). " \
+              'Verify vector_store_options[:connection] is a live PostgreSQL ' \
+              'connection and that the pgvector extension is available ' \
+              '(`rails generate woods:pgvector && rails db:migrate` sets it up via migration).'
+      end
+      store
+    end
+
+    def verify_pgvector_dimensions!(store, expected)
+      actual = store.stored_dimensions
+      return if actual.nil? || actual == expected
+
+      raise ConfigurationError,
+            "Stored pgvector dimensions #{actual} do not match embedding provider dimensions #{expected}. " \
+            'Use a compatible table or rebuild the index.'
+    end
+
+    def resolve_pgvector_dimensions(provider_dimensions, configured_dimensions)
+      if provider_dimensions && configured_dimensions && provider_dimensions != configured_dimensions
+        raise ConfigurationError,
+              "pgvector dimensions #{configured_dimensions} do not match embedding provider dimensions " \
+              "#{provider_dimensions}"
+      end
+
+      provider_dimensions || configured_dimensions || raise(
+        ConfigurationError,
+        'pgvector requires vector_store_options[:dimensions] when built without an embedding provider'
+      )
+    end
+
+    def build_qdrant_store(provider_dimensions)
+      opts = (@config.vector_store_options || {}).transform_keys(&:to_sym)
+      validate_required_store_options!(:qdrant, opts, :url, :collection)
+      dimensions = resolve_qdrant_dimensions(provider_dimensions, opts[:dimensions])
+      opts[:dimensions] = dimensions
+      store = Storage::VectorStore::Qdrant.new(**opts)
+      store.ensure_collection!(dimensions: dimensions)
+      store
+    end
+
+    def validate_required_store_options!(adapter, opts, *keys)
+      missing = keys.select { |key| opts[key].nil? || opts[key].to_s.empty? }
+      return if missing.empty?
+
+      requirements = missing.map { |key| "vector_store_options[:#{key}]" }.join(' and ')
+      raise ConfigurationError, "#{adapter} requires #{requirements}"
+    end
+
+    def resolve_qdrant_dimensions(provider_dimensions, configured_dimensions)
+      if provider_dimensions && configured_dimensions && provider_dimensions != configured_dimensions
+        raise ConfigurationError,
+              "Qdrant dimensions #{configured_dimensions} do not match embedding provider dimensions " \
+              "#{provider_dimensions}"
+      end
+
+      provider_dimensions || configured_dimensions || raise(
+        ConfigurationError,
+        'Qdrant requires vector_store_options[:dimensions] when built without an embedding provider'
+      )
+    end
+
     # Build a cache store from configuration, or nil if caching is disabled.
     #
     # @return [Cache::CacheStore, nil]

data/lib/woods/cache/cache_middleware.rb

@@ -2,6 +2,11 @@
 
 require 'digest'
 require_relative 'cache_store'
+# CachedEmbeddingProvider includes Embedding::Provider::Interface at load
+# time, so the interface must be defined before this file's class bodies run
+# — otherwise a narrow `require 'woods/cache/cache_middleware'` raises
+# NameError (STO-5).
+require_relative '../embedding/provider'
 
 module Woods
   module Cache
@@ -364,8 +369,8 @@ module Woods
       # persistent shared backend (Redis/SolidCache) returns the previous
       # model's vector after a model switch or upgrade — different dimensions
       # error mid-batch, same dimensions silently corrupt similarity scores
-      # (which IndexValidator can't detect, since it checks provider-vs-store
-      # dims, not cache contents).
+      # (which the provider-vs-store dimension check can't detect, since it
+      # compares declared widths, not cache contents).
       #
       # model_name (a plain attribute) is used rather than dimensions on
       # purpose: for every supported provider the model uniquely determines

data/lib/woods/cache/cache_store.rb

@@ -25,7 +25,11 @@ module Woods
     # @param parts [Array<String>] Key components (will be SHA256-hashed if long)
     # @return [String] Namespaced key
     def self.cache_key(domain, *parts)
-      raw = parts.join(':')
+      raw = if parts.one?
+              parts.first.to_s
+            else
+              parts.map { |part| "#{part.to_s.bytesize}:#{part}" }.join
+            end
       suffix = raw.length > 64 ? Digest::SHA256.hexdigest(raw) : raw
       "woods:cache:#{domain}:#{suffix}"
     end
@@ -148,6 +152,10 @@ module Woods
       # @param max_entries [Integer] Maximum cached entries before LRU eviction
       def initialize(max_entries: 500)
         super()
+        unless max_entries.is_a?(Integer) && max_entries.positive?
+          raise ArgumentError, 'max_entries must be a positive Integer'
+        end
+
         @max_entries = max_entries
         @entries = {}
         @access_order = []