woods 1.6.1 → 2.0.0.beta2

data/lib/woods/storage/snapshotter/metadata.rb

@@ -5,6 +5,7 @@ require 'tempfile'
 require 'time'
 require 'msgpack'
 require 'woods/version'
+require 'woods/atomic_file'
 require 'woods/storage/metadata_store'
 require 'woods/mcp/errors'
 
@@ -33,7 +34,7 @@ module Woods
       # atomically via +Tempfile+ + +File.rename+.
       #
       # @see Snapshotter::Vector companion class for vector stores
-      module Metadata
+      module Metadata # rubocop:disable Metrics/ModuleLength
         # Magic string identifying a valid Woods Metadata Dump file.
         MAGIC = 'WMD1'
 
@@ -58,9 +59,28 @@ module Woods
         # @return [Woods::Storage::MetadataStore::InMemory]
         # @raise [Woods::MCP::UnsupportedArtifact] if magic is wrong or schema_version
         #   exceeds {MAX_SUPPORTED_SCHEMA_VERSION}
-        def self.load_or_empty(artifact, resolved_config: nil) # rubocop:disable Lint/UnusedMethodArgument
-          dump_path = dump_file_path(artifact)
-          return MetadataStore::InMemory.new unless dump_path&.exist?
+        def self.load_or_empty(artifact, resolved_config: nil)
+          load_dump_dir(artifact.latest_dump_path, resolved_config: resolved_config)
+        end
+
+        # Load from an EXPLICIT dump directory — the reload transaction's
+        # capture seam (M7). Candidates must hydrate from the dump identity
+        # captured before candidate construction, never from whatever
+        # +dumps/latest+ points at mid-build. By default this preserves
+        # {load_or_empty}'s boot semantics. Reload transactions pass
+        # +required: true+ so a missing promoted component fails closed rather
+        # than replacing a healthy store with an empty one.
+        #
+        # @param dump_dir [Pathname, String, nil] an explicit dump directory
+        # @param resolved_config [Object, nil] reserved for future validation
+        # @param required [Boolean] raise when the directory or dump file is absent
+        # @return [Woods::Storage::MetadataStore::InMemory]
+        # @raise [Woods::MCP::MissingArtifact] when +required+ and the dump is absent
+        # @raise [Woods::MCP::UnsupportedArtifact] if magic is wrong or schema_version
+        #   exceeds {MAX_SUPPORTED_SCHEMA_VERSION}
+        def self.load_dump_dir(dump_dir, resolved_config: nil, required: false) # rubocop:disable Lint/UnusedMethodArgument
+          dump_path = dump_dir.nil? ? nil : Pathname.new(dump_dir.to_s).join(FILENAME)
+          return missing_dump_store(required, dump_path) unless dump_path&.exist?
 
           store = MetadataStore::InMemory.new
           File.open(dump_path.to_s, 'rb') do |io|
@@ -69,12 +89,31 @@ module Woods
             validate_header!(header, dump_path)
             header['record_count'].times do
               record = unpacker.read
+              raise_corrupt(dump_path, 'record is not a hash') unless record.is_a?(Hash)
+
               store.store(record['id'], record['metadata'])
             end
+          # A stream shorter (or more corrupt) than the header promises is an
+          # interrupted dump, not a programming error: it fails closed with the
+          # typed error the Vector twin raises for the same shape (M3/STO-4),
+          # so the MCP bootstrapper's one artifact-error branch covers both.
+          rescue EOFError, MessagePack::MalformedFormatError => e
+            raise_corrupt(dump_path, "truncated or malformed dump (#{e.class})")
           end
           store
         end
 
+        def self.missing_dump_store(required, dump_path)
+          return MetadataStore::InMemory.new unless required
+
+          missing = dump_path&.to_s || FILENAME
+          raise Woods::MCP::MissingArtifact.new(
+            "Required metadata dump component is missing: #{missing}",
+            details: { path: missing }
+          )
+        end
+        private_class_method :missing_dump_store
+
         # Write the metadata store to +dump_dir/metadata.msgpack+ atomically.
         #
         # Streams header then one packed hash per record — no full in-memory copy
@@ -89,7 +128,7 @@ module Woods
         # @raise [ArgumentError] if +dump_dir+ is not under +artifact.dumps_root+
         def self.dump(store, artifact, dump_dir, resolved_config: nil) # rubocop:disable Lint/UnusedMethodArgument
           validate_store!(store)
-          validate_dump_dir!(artifact, dump_dir)
+          artifact.validate_dump_dir!(dump_dir, allow_root: true)
           target = Pathname.new(dump_dir.to_s).join(FILENAME)
           target.dirname.mkpath
           write_atomic(target, store)
@@ -106,6 +145,17 @@ module Woods
             latest.join(FILENAME)
           end
 
+          # @param path [Pathname] the dump being read
+          # @param reason [String] what was wrong with it
+          # @raise [Woods::MCP::UnsupportedArtifact] always
+          def raise_corrupt(path, reason)
+            raise Woods::MCP::UnsupportedArtifact.new(
+              "metadata.msgpack at #{path}: #{reason} — dump may have been interrupted " \
+              'mid-write; re-run woods:embed',
+              details: { path: path.to_s, reason: reason }
+            )
+          end
+
           def validate_header!(header, path)
             unless header.is_a?(Hash) && header['magic'] == MAGIC
               raise Woods::MCP::UnsupportedArtifact,
@@ -114,6 +164,8 @@ module Woods
                     "expected #{MAGIC.inspect}). The file may be corrupt or from an incompatible tool."
             end
 
+            validate_header_types!(header, path)
+
             version = header['schema_version']
             return if version <= MAX_SUPPORTED_SCHEMA_VERSION
 
@@ -123,12 +175,30 @@ module Woods
                   'Upgrade the woods gem or re-run woods:embed to regenerate.'
           end
 
+          # Both integer fields are load-bearing: the version gates the read
+          # and the count drives the record loop. A header missing or
+          # mistyping either one used to reach a raw NoMethodError one frame
+          # later (STO-4).
+          #
+          # @param header [Hash]
+          # @param path [Pathname]
+          # @return [void]
+          # @raise [Woods::MCP::UnsupportedArtifact]
+          def validate_header_types!(header, path)
+            %w[schema_version record_count].each do |field|
+              value = header[field]
+              next if value.is_a?(Integer) && !value.negative?
+
+              raise_corrupt(path, "header #{field} is #{value.inspect}, expected a non-negative integer")
+            end
+          end
+
           # Write +store+ contents to +target+ atomically via a sibling Tempfile + rename.
           # Streams header then one record hash per entry.
           #
           # @param target [Pathname] final destination
           # @param store [#count, #each_entry] populated metadata store
-          def write_atomic(target, store)
+          def write_atomic(target, store) # rubocop:disable Metrics/AbcSize
             tmp = Tempfile.new([FILENAME, '.tmp'], target.dirname.to_s)
             begin
               tmp.binmode
@@ -142,6 +212,9 @@ module Woods
               tmp.fsync
               tmp.close
               File.rename(tmp.path, target.to_s)
+              # Match AtomicFile: the directory entry itself must survive a
+              # crash after the rename, or the dump is not durable (M11).
+              Woods::AtomicFile.fsync_directory(target.dirname.to_s)
             rescue StandardError
               tmp.close
               tmp.unlink
@@ -155,16 +228,6 @@ module Woods
             raise InapplicableBackend,
                   "backend #{store.class} is already durable — Snapshotter should not have been invoked"
           end
-
-          def validate_dump_dir!(artifact, dump_dir)
-            dump_path = Pathname.new(dump_dir.to_s).expand_path
-            root = artifact.dumps_root.expand_path
-
-            return if dump_path.to_s.start_with?("#{root}/") || dump_path == root
-
-            raise ArgumentError,
-                  "dump_dir #{dump_path} is not under artifact.dumps_root #{root}"
-          end
         end
       end
     end

data/lib/woods/storage/snapshotter/vector.rb

@@ -2,6 +2,7 @@
 
 require 'pathname'
 require 'tempfile'
+require 'woods/atomic_file'
 require 'woods/storage/vector_store'
 require 'woods/mcp/errors'
 require 'woods/version'
@@ -43,16 +44,51 @@ module Woods
         # @raise [Woods::MCP::UnsupportedArtifact] if magic or schema_version is invalid
         # @raise [Woods::MCP::DimensionMismatch] if stored dimension ≠ +resolved_config.dimension+
         def self.load_or_empty(artifact, resolved_config: nil)
-          dump_dir = artifact.latest_dump_path
-          return VectorStore::InMemory.new if dump_dir.nil?
+          load_dump_dir(artifact.latest_dump_path, resolved_config: resolved_config)
+        end
+
+        # Load from an EXPLICIT dump directory — the reload transaction's
+        # capture seam (M7). Candidates must hydrate from the dump identity
+        # captured before candidate construction, never from whatever
+        # +dumps/latest+ points at mid-build; +load_or_empty+ re-reads the
+        # +latest+ pointer on every call and would mix halves from two dumps.
+        # By default this preserves {load_or_empty}'s boot semantics: a nil
+        # directory or a directory without the dump files yields an empty
+        # store. Reload transactions pass +required: true+ so a partially
+        # promoted dump fails closed instead of replacing a healthy store with
+        # an empty one.
+        #
+        # @param dump_dir [Pathname, String, nil] an explicit dump directory
+        # @param resolved_config [#dimension, nil] used for dimension validation
+        # @param required [Boolean] raise when the directory or either dump file is absent
+        # @return [Woods::Storage::VectorStore::InMemory]
+        # @raise [Woods::MCP::MissingArtifact] when +required+ and a dump component is absent
+        # @raise [Woods::MCP::UnsupportedArtifact] if magic or schema_version is invalid
+        # @raise [Woods::MCP::DimensionMismatch] if stored dimension ≠ +resolved_config.dimension+
+        def self.load_dump_dir(dump_dir, resolved_config: nil, required: false)
+          return missing_dump_store(required, []) if dump_dir.nil?
 
+          dump_dir = Pathname.new(dump_dir.to_s)
           bin_path = dump_dir.join('vectors.bin')
           idx_path = dump_dir.join('vectors.idx')
-          return VectorStore::InMemory.new unless bin_path.exist? && idx_path.exist?
+          missing = [bin_path, idx_path].reject(&:exist?)
+          return missing_dump_store(required, missing) if missing.any?
 
           load_from(bin_path, idx_path, resolved_config)
         end
 
+        def self.missing_dump_store(required, paths)
+          return VectorStore::InMemory.new unless required
+
+          message = if paths.empty?
+                      'No promoted vector dump is available'
+                    else
+                      "Required vector dump component is missing: #{paths.join(', ')}"
+                    end
+          raise Woods::MCP::MissingArtifact.new(message, details: { paths: paths.map(&:to_s) })
+        end
+        private_class_method :missing_dump_store
+
         # Writes +vectors.bin+ and +vectors.idx+ into +dump_dir+ atomically.
         #
         # @param store [#each_entry, #bulk_load] in-memory vector store adapter
@@ -64,7 +100,7 @@ module Woods
         # @raise [ArgumentError] if +dump_dir+ is not under +artifact.dumps_root+
         def self.dump(store, artifact, dump_dir, resolved_config: nil)
           validate_store!(store)
-          validate_dump_dir!(artifact, Pathname.new(dump_dir.to_s))
+          artifact.validate_dump_dir!(dump_dir, allow_root: true)
           model_name = resolved_config.respond_to?(:model_name) ? resolved_config.model_name.to_s : ''
           entries = store.each_entry.to_a
           write_bin_and_idx(Pathname.new(dump_dir.to_s), entries, Woods::VERSION, model_name)
@@ -79,11 +115,25 @@ module Woods
             header, data_offset = parse_header(bin_data, bin_path)
             validate_magic!(header[:magic], bin_path)
             validate_schema_version!(header[:schema_version], bin_path)
-            dim = resolved_config.respond_to?(:dimension) ? resolved_config.dimension : nil
-            validate_dimension!(header[:dimension], dim, bin_path) if dim
-            floats = bin_data.byteslice(data_offset, header[:vector_count] * header[:dimension] * 4)
-                             .unpack("e#{header[:vector_count] * header[:dimension]}")
-            hydrate_store(parse_idx(idx_path), floats, header[:dimension])
+            validate_dimension_if_present!(header, resolved_config, bin_path)
+            floats = read_float_blob(bin_data, header, data_offset, bin_path)
+            ids = parse_idx(idx_path)
+            validate_idx_count!(ids.size, header[:vector_count], idx_path, bin_path)
+            hydrate_store(ids, floats, header[:dimension])
+          end
+
+          # A valid header over a truncated float payload used to unpack
+          # straight through: byteslice pads the missing tail with nil, so
+          # nil-floated vectors hydrated into the live store, crashed search
+          # with TypeError, and re-published as zeros on the next dump (M10).
+          # Unpack never invents data — the blob must be complete, and a
+          # truncated dump is an interrupted dump.
+          def read_float_blob(bin_data, header, data_offset, path)
+            float_count = header[:vector_count] * header[:dimension]
+            needed = float_count * 4
+            raise_truncated(path, bin_data.bytesize, data_offset + needed) if bin_data.bytesize - data_offset < needed
+
+            bin_data.byteslice(data_offset, needed).unpack("e#{float_count}")
           end
 
           def parse_header(bin_data, bin_path) # rubocop:disable Metrics/AbcSize
@@ -123,15 +173,48 @@ module Woods
             pairs = []
             pos = 0
             while pos < idx_data.bytesize
+              # Fail closed on truncation (M3), the same contract as the bin
+              # side's float-blob guard: a record that would read past EOF is
+              # an interrupted dump, and byteslice would otherwise pad it into
+              # a garbage (short) id that silently hydrates.
+              raise_truncated(idx_path, idx_data.bytesize, pos + 4) if idx_data.bytesize - pos < 4
               id_len = idx_data.byteslice(pos, 4).unpack1('L<')
+              record_end = pos + 4 + id_len + 8
+              raise_truncated(idx_path, idx_data.bytesize, record_end) if idx_data.bytesize < record_end
               pos += 4
-              id = idx_data.byteslice(pos, id_len)
+              # The idx format stores ids as UTF-8 bytes (build_idx writes
+              # id.encode('UTF-8').b), but byteslice on a binread buffer
+              # yields ASCII-8BIT. Left untagged, a non-ASCII id is not eql?
+              # to its UTF-8 twin, so every hash lookup keyed on a hydrated
+              # id misses: the Indexer's checkpoint self-heal re-embedded the
+              # unit on every incremental run, and InMemory#store appended a
+              # duplicate live entry each time (B-080 / #192).
+              id = idx_data.byteslice(pos, id_len).force_encoding(Encoding::UTF_8)
               pos += id_len + 8 # skip the u64 offset (not needed for load)
               pairs << id
             end
             pairs
           end
 
+          # The idx record count and the bin header's vector_count describe
+          # the same dump; the idx maps ids onto the blob the header counts.
+          # When the halves disagree, hydration either crashed with a bare
+          # NoMethodError (idx longer: nil vectors reach InMemory#store) or
+          # silently served fewer vectors than the dump claims (idx shorter).
+          # Promotion ordering makes live exposure post-promotion-corruption-
+          # only, but the fail-closed-with-typed-error contract is the
+          # file's own standard — a mismatched dump is an interrupted or
+          # corrupted dump, never one to hydrate from.
+          def validate_idx_count!(idx_count, bin_count, idx_path, bin_path)
+            return if idx_count == bin_count
+
+            raise Woods::MCP::UnsupportedArtifact.new(
+              "#{idx_path}: vectors.idx holds #{idx_count} id records but #{bin_path} header declares " \
+              "#{bin_count} vectors — dump halves disagree; re-run woods:embed",
+              details: { path: idx_path.to_s, idx_count: idx_count, bin_vector_count: bin_count }
+            )
+          end
+
           def hydrate_store(ids, floats, dim)
             store = VectorStore::InMemory.new
             entries = ids.each_with_index.map do |id, idx|
@@ -160,6 +243,18 @@ module Woods
             )
           end
 
+          # An empty dump writes dimension=0 in the header (build_header has
+          # no vector to measure) — that's not a real mismatch against the
+          # provider's dimension, just the absence of data. Skip the check
+          # rather than raising DimensionMismatch on every embed of an
+          # empty payload.
+          def validate_dimension_if_present!(header, resolved_config, path)
+            return unless header[:vector_count].positive?
+
+            dim = resolved_config.respond_to?(:dimension) ? resolved_config.dimension : nil
+            validate_dimension!(header[:dimension], dim, path) if dim
+          end
+
           def validate_dimension!(stored, expected, path)
             return if stored == expected
 
@@ -210,26 +305,42 @@ module Woods
             tmp.fsync
             tmp.close
             File.rename(tmp.path, path.to_s)
+            # Match AtomicFile: the directory entry itself must survive a
+            # crash after the rename, or the dump is not durable (M11).
+            Woods::AtomicFile.fsync_directory(path.dirname.to_s)
           rescue StandardError
             tmp&.close
             tmp&.unlink
             raise
           end
 
+          # +respond_to?+ is the wrong question here: {VectorStore::Interface}
+          # *defines* both +#each_entry+ and +#bulk_load+ (as stubs — the
+          # former raises +NotImplementedError+, the latter delegates to
+          # +#store_batch+), and every adapter includes that module. Durable
+          # adapters (Pgvector, Qdrant) therefore answered +respond_to?+ with
+          # +true+ despite implementing neither, passed this guard, and hit
+          # the bare +NotImplementedError+ from +#each_entry+ instead of the
+          # typed error this method promises (B-108, see
+          # `Indexer#implements_own?`). Ask who *owns* the method instead.
           def validate_store!(store)
-            return if store.respond_to?(:each_entry) && store.respond_to?(:bulk_load)
+            return if implements_own?(store, :each_entry) && store.respond_to?(:bulk_load)
 
             raise InapplicableBackend,
                   "backend #{store.class} is already durable — Snapshotter should not have been invoked"
           end
 
-          def validate_dump_dir!(artifact, dump_path)
-            expanded = dump_path.expand_path
-            root = artifact.dumps_root.expand_path
-            return if expanded.to_s.start_with?("#{root}/") || expanded == root
+          # Does +object+ define +method_name+ itself, rather than inheriting
+          # {VectorStore::Interface}'s default stub?
+          #
+          # @param object [Object] the adapter under test
+          # @param method_name [Symbol]
+          # @return [Boolean]
+          def implements_own?(object, method_name)
+            return false unless object.respond_to?(method_name)
+            return true unless defined?(VectorStore::Interface)
 
-            raise ArgumentError,
-                  "dump_dir #{expanded} is not under artifact.dumps_root #{root}"
+            object.method(method_name).owner != VectorStore::Interface
           end
         end
       end

data/lib/woods/storage/snapshotter.rb

@@ -9,15 +9,33 @@ module Woods
     # storage adapters to/from disk.
     #
     # Two adapters live here:
-    # - {Snapshotter::Vector} — handles {VectorStore::InMemory} round-trips via +pack("e*")+.
-    # - {Snapshotter::Metadata} — handles {MetadataStore::InMemory} round-trips via MessagePack.
+    # - {Snapshotter::Vector} — handles {VectorStore::InMemory} round-trips via
+    #   a raw +pack("e*")+ binary format (+vectors.bin+ / +vectors.idx+).
+    # - {Snapshotter::Metadata} — handles {MetadataStore::InMemory} round-trips
+    #   via MessagePack (+metadata.msgpack+).
     #
     # Persistent backends (pgvector, Qdrant, SQLite) never touch the Snapshotter.
     # Passing one to {Snapshotter::Vector.dump} or {Snapshotter::Metadata.dump} raises
-    # {InapplicableBackend} immediately.
+    # {InapplicableBackend} immediately — see each adapter's +validate_store!+.
     #
-    # PR 2 ships stub implementations: +load_or_empty+ always returns an empty store
-    # and +dump+ is a validated no-op. PR 3 wires in the real serialization paths.
+    # The two checks are deliberately different, because the two interfaces
+    # are:
+    # - {Snapshotter::Vector.validate_store!} checks *ownership* of
+    #   +#each_entry+ rather than +respond_to?+ (B-108), because
+    #   {VectorStore::Interface} defines it as a raising stub, so a durable
+    #   adapter that merely includes the interface would otherwise pass.
+    # - {Snapshotter::Metadata.validate_store!} can use plain +respond_to?+
+    #   only because {MetadataStore::Interface} defines neither +#each_entry+
+    #   nor +#bulk_load+ — the seams exist on +InMemory+ alone. Adding either
+    #   stub to that interface would silently convert this check into the
+    #   B-108 bug, so the ownership check must move with it (STO-12).
+    #
+    # {Woods::Embedding::Indexer#persist_snapshot} is the write-side caller,
+    # invoked at the end of a successful {Woods::Embedding::Indexer#index_all}
+    # or +#index_incremental+ run when the configured vector store is
+    # in-memory. {Snapshotter::Vector.load_or_empty} is the read-side
+    # counterpart, used both by an incremental run (to hydrate before
+    # embedding) and by the MCP server at boot.
     module Snapshotter
     end
   end

data/lib/woods/storage/vector_store.rb

@@ -52,6 +52,25 @@ module Woods
           raise NotImplementedError
         end
 
+        # Iterate over every stored id, yielding the raw embed id (which may
+        # carry a `#chunk_N` suffix). Vectors are NOT loaded.
+        #
+        # Reconciliation seam, and deliberately separate from {#each_entry}:
+        # the embed pipeline needs to know *what a durable store currently
+        # holds* so it can drop units the index no longer has, and pulling
+        # every vector back over the wire to answer a question about ids would
+        # be absurd. Durable adapters (pgvector, Qdrant) implement this one
+        # and not {#each_entry}.
+        #
+        # Adapters that do not implement it are simply not reconciled — see
+        # `Indexer#reconcilable?`.
+        #
+        # @yield [String] each stored id
+        # @return [Enumerator] when no block given
+        def each_id
+          raise NotImplementedError
+        end
+
         # Bulk-load pre-computed entries. Dual of {#each_entry} — the
         # Snapshotter hydrates a store by feeding this the dump contents.
         #
@@ -140,9 +159,6 @@ module Woods
           @tombstones = Set.new
         end
 
-        # @return [Integer, nil] dimension of stored vectors, nil if empty
-        attr_reader :dim
-
         # @see Interface#store
         def store(id, vector, metadata = {})
           @dim ||= vector.length
@@ -193,6 +209,17 @@ module Woods
           end
         end
 
+        # @see Interface#each_id
+        def each_id(&block)
+          return enum_for(:each_id) unless block
+
+          @ids.each_with_index do |id, idx|
+            next if @tombstones.include?(idx)
+
+            yield(id)
+          end
+        end
+
         # @see Interface#search
         def search(query_vector, limit: 10, filters: {})
           return [] if @dim.nil?
@@ -217,7 +244,7 @@ module Woods
         def delete_by_filter(filters)
           @ids.each_with_index do |id, idx|
             next if @tombstones.include?(idx)
-            next unless filters.all? { |key, value| @metadata[idx][key] == value }
+            next unless filters.all? { |key, value| filter_match?(value, metadata_value(@metadata[idx], key)) }
 
             @tombstones << idx
             @id_to_index.delete(id)
@@ -237,6 +264,16 @@ module Woods
           filter_value.is_a?(Array) ? filter_value.include?(meta_value) : filter_value == meta_value
         end
 
+        # Indifferent metadata lookup: vector metadata is symbol-keyed on the
+        # live embed path (Indexer#store_vectors) but callers may filter with
+        # string keys, and pre-fix dumps hydrated string-keyed records — the
+        # key form must never decide whether a filter matches (#150 item 5).
+        def metadata_value(meta, key)
+          return nil unless meta
+
+          meta.fetch(key) { key.is_a?(Symbol) ? meta[key.to_s] : meta[key.to_sym] }
+        end
+
         # Append a new entry to the flat buffer.
         def append(id, vector, metadata)
           idx = @ids.size
@@ -246,8 +283,13 @@ module Woods
           @id_to_index[id] = idx
         end
 
-        # Overwrite an existing entry in place. Tombstones the old slot's
-        # deletion marker (if any) so the new vector is live again.
+        # Overwrite an existing entry in place.
+        #
+        # Only reachable via +#store+ for an +idx+ still present in
+        # +@id_to_index+ — every path that tombstones an index (+#delete+,
+        # +#delete_by_filter+) removes its id from +@id_to_index+ in the same
+        # operation, so an idx looked up here can never also be in
+        # +@tombstones+. There is nothing to un-tombstone.
         def overwrite(idx, vector, metadata)
           base = idx * @dim
           i = 0
@@ -256,7 +298,6 @@ module Woods
             i += 1
           end
           @metadata[idx] = metadata
-          @tombstones.delete(idx)
         end
 
         # Walk every non-tombstoned index, apply filters, score survivors.
@@ -272,7 +313,7 @@ module Woods
               next
             end
             meta = @metadata[idx]
-            unless filters.empty? || filters.all? { |k, v| filter_match?(v, meta[k]) }
+            unless filters.empty? || filters.all? { |k, v| filter_match?(v, metadata_value(meta, k)) }
               idx += 1
               next
             end

data/lib/woods/storage_identity.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+module Woods
+  # Internal storage keys; public unit identifiers remain unchanged.
+  module StorageIdentity
+    PREFIX = '@woods-unit:'
+
+    def self.key(identifier, type)
+      PREFIX + Base64.urlsafe_encode64(JSON.generate([identifier.to_s, type.to_s]), padding: false)
+    end
+
+    def self.parts(key)
+      return unless key.to_s.start_with?(PREFIX)
+
+      value = JSON.parse(Base64.urlsafe_decode64(key.delete_prefix(PREFIX)))
+      value if value.is_a?(Array) && value.size == 2 && value.all?(String)
+    rescue ArgumentError, JSON::ParserError
+      nil
+    end
+
+    def self.identifier(key)
+      parts(key)&.first || key
+    end
+  end
+end

data/lib/woods/tasks.rb

@@ -30,6 +30,16 @@ module Woods
       builder = Builder.new(config)
       provider = builder.build_embedding_provider
 
+      # The Indexer gets the provider wrapped in the resilience stack
+      # (retry with backoff + per-instance circuit breaker) so a transient
+      # 429/5xx degrades the run instead of aborting it — on the :local /
+      # :shared_filesystem presets the dump only lands at end-of-run, so an
+      # unwrapped mid-run rate limit used to discard every embedding
+      # already paid for (#188 / B-076). The *raw* provider still feeds
+      # the tokenizer-calibration helpers and the ResolvedConfig probe,
+      # which key off the provider's concrete class.
+      resilient_provider = builder.build_resilient_embedding_provider(provider)
+
       # Wire the persistence-arc pieces (resolved_config, metadata_store,
       # dump_retention_count) so Indexer#persist_snapshot can write
       # woods.json, dump metadata, and honour the user's retention setting.
@@ -39,10 +49,13 @@ module Woods
       #
       # metadata_store and resolved_config are nil-safe — hosts that don't
       # configure metadata or that pre-date the persistence arc still work.
+      vector_store = builder.build_vector_store(dimensions: provider.dimensions)
+      verify_store_dimensions!(vector_store, provider)
+
       Embedding::Indexer.new(
-        provider: provider,
+        provider: resilient_provider,
         text_preparer: builder.build_text_preparer(provider),
-        vector_store: builder.build_vector_store,
+        vector_store: vector_store,
         metadata_store: config.metadata_store ? builder.build_metadata_store : nil,
         resolved_config: build_resolved_config(config, provider: provider),
         chunker: builder.build_chunker(provider),
@@ -51,6 +64,44 @@ module Woods
       )
     end
 
+    # Refuse to embed into a store built for a different vector width (#214).
+    #
+    # Durable stores are created once and reused: pgvector's `ensure_schema!`
+    # is `CREATE TABLE IF NOT EXISTS` and Qdrant treats its collection PUT as
+    # idempotent, so changing `embedding_model` leaves the old width in place.
+    # Without this check the run embedded everything first and only then hit a
+    # per-row server error — `PG::DataException: expected 384 dimensions, not
+    # 768`, or a Qdrant 400 — naming no remedy.
+    #
+    # The dump path has had this check since the persistence arc
+    # ({Storage::Snapshotter::Vector} validates the WVF1 header against
+    # `resolved_config.dimension`); this extends the same guarantee to the
+    # durable backends, which had none. It is a *pre-flight* check: adapters
+    # that cannot report a width, and stores that do not exist yet, return nil
+    # and are simply not checked.
+    #
+    # @param vector_store [Object] the configured store
+    # @param provider [#dimensions] the raw (unwrapped) embedding provider
+    # @raise [Woods::MCP::DimensionMismatch] when the widths disagree
+    # @return [void]
+    def verify_store_dimensions!(vector_store, provider)
+      return unless vector_store.respond_to?(:stored_dimensions)
+      return unless provider.respond_to?(:dimensions)
+
+      stored = vector_store.stored_dimensions
+      expected = provider.dimensions
+      return if stored.nil? || expected.nil? || stored == expected
+
+      require_relative 'mcp/errors'
+      raise Woods::MCP::DimensionMismatch.new(
+        "#{vector_store.class} holds #{stored}-dimension vectors but the configured provider " \
+        "produces #{expected}. Embedding into it would fail per-row. Re-index from scratch: " \
+        'drop the vector store (woods_vectors table / Qdrant collection), then run ' \
+        'woods:extract && woods:embed.',
+        details: { stored_dimension: stored, provider_dimension: expected, store: vector_store.class.to_s }
+      )
+    end
+
     # Build a ResolvedConfig snapshot from the live Woods::Configuration.
     # Returns nil if the configuration doesn't have enough to produce one
     # (pre-persistence-arc hosts) so the Indexer falls back to the legacy