woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/source_inputs/status.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'woods/generation'
+require 'woods/source_inputs/verifier'
+
+module Woods
+  module SourceInputs
+    # Shared CLI/hook/MCP reader. A caller serving an older immutable payload
+    # passes its own directory and generation, never the newest marker's proof.
+    class Status
+      BUDGETS = { 'quick' => 0.25, 'deep' => 5.0 }.freeze
+
+      def self.from_transport(encoded)
+        raise ArgumentError, 'source status options are too large' if encoded.to_s.bytesize > 16_384
+
+        options = encoded.nil? ? {} : JSON.parse(Base64.strict_decode64(encoded))
+        unless options.is_a?(Hash) && (options.keys - %w[output root mode]).empty? && options.values.all?(String)
+          raise ArgumentError, 'source status options must contain only output, root and mode strings'
+        end
+
+        new(output_dir: options.fetch('output', ENV.fetch('WOODS_OUTPUT', 'tmp/woods')),
+            root: options['root'], mode: options.fetch('mode', 'quick')).call
+      rescue JSON::ParserError
+        raise ArgumentError, 'invalid source status options'
+      end
+
+      def initialize(output_dir:, payload_dir: nil, generation: nil, root: nil, mode: 'quick')
+        raise ArgumentError, 'source status mode must be quick or deep' unless BUDGETS.key?(mode)
+
+        @output = File.expand_path(output_dir.to_s)
+        @root = root
+        @mode = mode
+        @generation = generation
+        @payload = payload_dir
+      end
+
+      def call
+        return unknown(@resolution_error || 'atomic_source_manifest_unavailable') unless resolve_payload
+
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        manifest = File.open(File.join(@payload, Manifest::FILE_NAME), flags) do |file|
+          return unknown('invalid_source_manifest') unless file.stat.file?
+          return unknown('source_manifest_too_large') if file.stat.size > Manifest::MAX_BYTES
+
+          Manifest.parse(file.read(Manifest::MAX_BYTES + 1))
+        end
+        Verifier.new(manifest: manifest, output_dir: @output, root: @root,
+                     generation: @generation, max_seconds: BUDGETS.fetch(@mode)).call.merge('check' => @mode)
+      rescue Errno::ENOENT
+        unknown('source_manifest_unavailable')
+      rescue Manifest::Invalid, SystemCallError, IOError
+        unknown('invalid_source_manifest')
+      end
+
+      private
+
+      def resolve_payload
+        generation = Generation.new(output_dir: @output)
+        marker = if @payload
+                   Generation::Marker.new(payload: @payload.to_s)
+                 else
+                   generation.current.tap { |current| @generation = current.number }
+                 end
+        return false unless marker.payload.is_a?(String)
+
+        resolved = generation.payload_dir(marker)
+        return false if resolved == generation.root
+
+        @payload = resolved
+        true
+      rescue TypeError, NoMethodError
+        @resolution_error = 'invalid_generation'
+        false
+      end
+
+      def unknown(reason)
+        { 'state' => 'unknown', 'mode' => 'content', 'check' => @mode, 'generation' => @generation,
+          'checked_at' => Time.now.utc.iso8601, 'complete' => false, 'reasons' => [reason] }
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/verifier.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'woods/source_inputs/scanner'
+require 'woods/source_inputs/manifest'
+
+module Woods
+  module SourceInputs
+    # Bounded, byte-verifying source evidence. No stat-only result is called
+    # current: the same-size/same-mtime case is deliberately read and hashed.
+    class Verifier
+      DEFAULT_SECONDS = 0.25
+      SUMMARY_LIMIT = 30
+
+      # rubocop:disable Metrics/ParameterLists -- caller chooses identity, served generation and bounded scan
+      def initialize(manifest:, output_dir:, root: nil, generation: nil, max_seconds: DEFAULT_SECONDS, **limits)
+        @manifest = manifest.is_a?(Manifest) ? manifest : Manifest.new(manifest)
+        @output_dir = output_dir
+        @root = root || @manifest.data.fetch('root')
+        @generation = generation
+        @limits = limits.merge(max_seconds: max_seconds)
+      end
+
+      # rubocop:enable Metrics/ParameterLists
+
+      def call # rubocop:disable Metrics/AbcSize -- cheap refusal checks precede the only source scan
+        return unknown('generation_mismatch') if @generation && @generation != @manifest.data['generation']
+        return unknown('source_root_unavailable') unless File.directory?(@root)
+
+        key = PrivateKey.new(output_dir: @output_dir)
+        return unknown('identity_key_mismatch') unless key.identifier == @manifest.data.fetch('key_id')
+
+        scopes = Scopes.new(extra_roots: @manifest.data.fetch('extra_roots'))
+        return unknown('input_rules_changed') unless scopes.fingerprint == @manifest.data.fetch('rules')
+
+        current = Scanner.new(root: @root, output_dir: @output_dir, key: key, scopes: scopes, **@limits).call
+        compare(current)
+      rescue PrivateKey::Unavailable => e
+        unknown(e.message)
+      rescue SystemCallError, IOError
+        unknown('source_root_unavailable')
+      end
+
+      private
+
+      def compare(current)
+        previous = @manifest.expanded
+        changes = { 'added' => [], 'changed' => [], 'removed' => [] }
+        previous.each { |scope, paths| compare_scope(scope, paths, changes, current) }
+        add_new_scopes(previous, changes, current) if complete?(current)
+        reasons = coverage_reasons(current)
+        summarized(changes, reasons, current)
+      end
+
+      def complete?(current)
+        @manifest.data['complete'] && current['complete']
+      end
+
+      def compare_scope(scope, paths, changes, current)
+        paths.each do |path, identity|
+          now = current.fetch('files')[path]
+          changes['changed'] << path if now && now != identity
+          changes['removed'] << path if now.nil? && current['complete']
+        end
+        return unless complete?(current)
+
+        changes['added'].concat(current.fetch('scope_paths').fetch(scope, []) - paths.keys)
+      end
+
+      def add_new_scopes(previous, changes, current)
+        new_scopes = current.fetch('scope_paths').keys - previous.keys
+        new_scopes.each { |scope| changes['added'].concat(current.fetch('scope_paths').fetch(scope)) }
+      end
+
+      def coverage_reasons(current)
+        reasons = (@manifest.data.fetch('errors') + current.fetch('errors')).map { |error| error['reason'] }.compact
+        reasons << 'incomplete_capture' unless @manifest.data['complete']
+        reasons << 'incomplete_verification' unless current['complete']
+        reasons << 'unverified_boot_boundary' unless @manifest.data['boot_verified']
+        reasons << 'unverified_consumption_scopes' unless @manifest.data.fetch('unverified_scopes').empty?
+        reasons.uniq
+      end
+
+      def summarized(changes, reasons, current)
+        changes.transform_values! { |paths| paths.uniq.sort }
+        counts = changes.transform_values(&:size)
+        { 'state' => state_for(counts, reasons), 'mode' => 'content', 'generation' => @manifest.data['generation'],
+          'checked_at' => Time.now.utc.iso8601, 'reasons' => reasons,
+          'complete' => current['complete'] && @manifest.data['complete'],
+          'counts' => counts, 'truncated' => counts.values.any? { |count| count > SUMMARY_LIMIT },
+          'changes' => changes.transform_values { |paths| paths.first(SUMMARY_LIMIT) },
+          'metrics' => current.fetch('metrics') }
+      end
+
+      def state_for(counts, reasons)
+        return 'drifted' if counts.values.any?(&:positive?)
+
+        reasons.empty? ? 'current' : 'unknown'
+      end
+
+      def unknown(reason)
+        { 'state' => 'unknown', 'mode' => 'content', 'generation' => @manifest.data['generation'],
+          'checked_at' => Time.now.utc.iso8601, 'reasons' => [reason], 'complete' => false }
+      end
+    end
+  end
+end

data/lib/woods/storage/metadata_store.rb

@@ -84,16 +84,19 @@ module Woods
         # adapter — they were substitutable in name only until the semantics
         # were written down):
         #
-        # - **Substring match**, not word or prefix match.
+        # - **Literal substring match**, including embedded NUL, not word or prefix match.
         # - **Case-insensitive.** InMemory used a case-sensitive
         #   `String#include?` while SQLite used `LIKE`, so the same query
         #   returned different results depending on the configured backend.
         #   Case-insensitive is both the search-like expectation and what the
-        #   durable adapter already did. (SQLite's `LIKE` folds ASCII only, so
+        #   durable adapter already did. (SQLite's `lower` folds ASCII only, so
         #   non-ASCII case folding remains backend-specific — do not rely on
         #   it either way.)
         # - **`fields: nil` searches the whole record**, including keys, as
         #   serialized JSON. A query can therefore match a field *name*.
+        # - **Field-scoped values use JSON spellings.** Strings are unquoted,
+        #   objects/arrays use JSON text, Booleans use `true`/`false`, and
+        #   numbers remain numeric text. Null and absent fields never match.
         # - **LIKE metacharacters are literal.** `%` and `_` in a query match
         #   themselves rather than acting as wildcards.
         # - Field names are validated against {SEARCH_FIELD_NAME} by every
@@ -218,15 +221,14 @@ module Woods
         # @see Interface#search
         #
         # Matching is literal substring inclusion — `%` and `_` in the query
-        # have no special meaning here, and the SQLite adapter escapes them
-        # so the two adapters agree.
+        # have no special meaning here or in the SQLite adapter.
         #
         # @raise [ArgumentError] if a field name fails {SEARCH_FIELD_NAME}
         def search(query, fields: nil)
           fields = validate_search_fields!(fields)
           return [] if fields == []
 
-          # Case-insensitive, matching the SQLite adapter's `LIKE` (see the
+          # Case-insensitive, matching the SQLite adapter's `lower` (see the
           # contract note on {Interface#search}). This used to be a
           # case-sensitive `String#include?`, so the same query returned
           # different results depending on which backend a host had configured.
@@ -312,9 +314,9 @@ module Woods
           JSON.parse(JSON.generate(metadata))
         end
 
-        # The text SQLite's +json_extract(data, '$.field')+ would compare
-        # against for one field value: strings come back raw, structured
-        # values as their JSON text, scalars as their decimal form. A Ruby
+        # The searchable text for one field value: strings come back raw,
+        # structured values as JSON text, Booleans as true/false, and numbers
+        # as their decimal form. A Ruby
         # +Hash#to_s+ haystack used to leak `=>` and `:sym` syntax that no
         # JSON document contains (STO-8).
         #
@@ -425,23 +427,22 @@ module Woods
         # Field names are interpolated into a `json_extract` JSON-path
         # literal, so they are validated against {SEARCH_FIELD_NAME} first —
         # a crafted name could otherwise break out of the literal and alter
-        # the SQL shape. LIKE metacharacters (`%`, `_`, `\`) in the query are
-        # escaped (with an explicit ESCAPE clause) so they match literally,
-        # aligning with the InMemory adapter's substring semantics instead of
-        # silently broadening matches.
+        # the SQL shape. instr and lower perform literal, ASCII-case-insensitive
+        # substring matching without LIKE's truncation at embedded NUL bytes.
+        # Wildcard characters need no escaping.
         #
         # @raise [ArgumentError] if a field name fails the whitelist
         def search(query, fields: nil)
           fields = validate_search_fields!(fields)
           return [] if fields == []
 
-          pattern = "%#{escape_like(query)}%"
+          needle = query.to_s
           if fields
-            conditions = fields.map { "json_extract(data, '$.#{_1}') LIKE ? ESCAPE '\\'" }.join(' OR ')
-            params = Array.new(fields.size, pattern)
+            conditions = fields.map { "instr(lower(#{field_haystack_sql(_1)}), lower(?)) > 0" }.join(' OR ')
+            params = Array.new(fields.size, needle)
             rows = @db.execute("SELECT id, data FROM units WHERE #{conditions}", params)
           else
-            rows = @db.execute("SELECT id, data FROM units WHERE data LIKE ? ESCAPE '\\'", [pattern])
+            rows = @db.execute('SELECT id, data FROM units WHERE instr(lower(data), lower(?)) > 0', [needle])
           end
 
           rows.map { |row| parse_row(row) }
@@ -489,15 +490,14 @@ module Woods
           defined?(SQLite3::BusyException) && error.is_a?(SQLite3::BusyException)
         end
 
-        # Escape SQL LIKE metacharacters in a user query so they match
-        # literally under the `ESCAPE '\'` clause {#search} emits. Without
-        # this, `%` and `_` in a query act as wildcards and silently broaden
-        # matches (`"user_name"` would match `"userXname"`).
-        #
-        # @param query [String] Raw search query
-        # @return [String] Query safe for embedding in a LIKE pattern
-        def escape_like(query)
-          query.to_s.gsub(/[\\%_]/) { |ch| "\\#{ch}" }
+        # JSON1 extracts Boolean scalars as integers; use their JSON type to
+        # preserve true/false without conflating them with numeric 1/0.
+        # Field names have already passed validate_search_fields!.
+        def field_haystack_sql(field)
+          path = "$.#{field}"
+          "CASE json_type(data, '#{path}') " \
+            "WHEN 'true' THEN 'true' WHEN 'false' THEN 'false' " \
+            "ELSE json_extract(data, '#{path}') END"
         end
 
         # Parse a database row into a metadata hash with the id field injected.

data/lib/woods/storage/pgvector.rb

@@ -26,6 +26,7 @@ module Woods
       class Pgvector # rubocop:disable Metrics/ClassLength
         include Interface
 
+        MAX_HNSW_DIMENSIONS = 2000
         TABLE = 'woods_vectors'
         TABLE_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/
 
@@ -122,6 +123,9 @@ module Woods
           SQL
         end
 
+        # Native raw-ID eligibility is applied before ranking and the limit.
+        def supports_id_filter? = true
+
         # Search for similar vectors using cosine distance.
         #
         # The query vector is dimension-checked before SQL runs, mirroring the
@@ -136,19 +140,14 @@ module Woods
         # @raise [Woods::Error] if the query vector's length disagrees with the
         #   configured dimension
         # @see Interface#search
-        def search(query_vector, limit: 10, filters: {})
+        def search(query_vector, limit: 10, filters: {}, ids: nil)
           validate_vector!(query_vector)
           validate_dimensions!(query_vector) if @dimensions
           vector_literal = build_vector_literal(query_vector)
           where_clause = build_where(filters)
+          where_clause = append_id_filter(where_clause, ids) if ids
 
-          sql = <<~SQL
-            SELECT id, embedding <=> '#{vector_literal}' AS distance, metadata
-            FROM #{qualified_table}
-            #{where_clause}
-            ORDER BY distance ASC
-            LIMIT #{limit.to_i}
-          SQL
+          sql = search_sql(vector_literal, where_clause, limit, ids)
 
           rows = @connection.execute(sql)
           rows.map { |row| row_to_result(row) }
@@ -221,9 +220,12 @@ module Woods
         private
 
         def normalize_dimensions(value)
-          return value if value.is_a?(Integer) && value.positive?
+          raise ArgumentError, 'dimensions must be a positive Integer' unless value.is_a?(Integer) && value.positive?
+          return value if value <= MAX_HNSW_DIMENSIONS
 
-          raise ArgumentError, 'dimensions must be a positive Integer'
+          raise ArgumentError,
+                "pgvector HNSW vector dimensions must be at most #{MAX_HNSW_DIMENSIONS}, got #{value}. " \
+                'Request a supported provider output width or choose another vector backend.'
         end
 
         def validate_identifier!(name, value, original)
@@ -345,6 +347,29 @@ module Woods
           )
         end
 
+        def search_sql(vector_literal, where_clause, limit, ids)
+          source = ids ? 'eligible' : qualified_table
+          prefix = if ids
+                     'WITH eligible AS MATERIALIZED (SELECT id, embedding, metadata ' \
+                       "FROM #{qualified_table} #{where_clause})\n"
+                   else
+                     ''
+                   end
+          prefix + <<~SQL
+            SELECT id, embedding <=> '#{vector_literal}' AS distance, metadata
+            FROM #{source}
+            #{where_clause unless ids}
+            ORDER BY distance ASC#{', id ASC' if ids}
+            LIMIT #{limit.to_i}
+          SQL
+        end
+
+        # Raw IDs work with old vectors that have no identifier/package payload.
+        def append_id_filter(where_clause, ids)
+          condition = ids.empty? ? 'FALSE' : "id IN (#{ids.map { |id| @connection.quote(id.to_s) }.join(', ')})"
+          where_clause.empty? ? "WHERE #{condition}" : "#{where_clause} AND #{condition}"
+        end
+
         # Build a WHERE clause from metadata filters.
         #
         # @param filters [Hash] Metadata key-value pairs

data/lib/woods/storage/qdrant.rb

@@ -332,6 +332,9 @@ module Woods
           request(:put, "/collections/#{@collection}/points#{WAIT_FOR_WRITE}", body)
         end
 
+        # Native raw-ID eligibility is applied before ranking and the limit.
+        def supports_id_filter? = true
+
         # Search for similar vectors.
         #
         # The query vector is dimension-checked before the request, mirroring
@@ -348,14 +351,11 @@ module Woods
         # @raise [Woods::Error] if the query vector's length disagrees with the
         #   configured dimension
         # @see Interface#search
-        def search(query_vector, limit: 10, filters: {})
+        def search(query_vector, limit: 10, filters: {}, ids: nil)
+          return [] if ids == []
+
           validate_dimensions!(query_vector) if @dimensions
-          body = {
-            vector: query_vector,
-            limit: limit,
-            with_payload: true
-          }
-          body[:filter] = build_filter(filters) unless filters.empty?
+          body = search_body(query_vector, limit, filters, ids)
 
           response = request(:post, "/collections/#{@collection}/points/search", body)
           results = response['result'] || []
@@ -579,6 +579,16 @@ module Woods
                 "Vector dimension mismatch#{where}: got #{got}, expected #{@dimensions}"
         end
 
+        def search_body(query_vector, limit, filters, ids)
+          body = { vector: query_vector, limit: limit, with_payload: true }
+          body[:filter] = build_filter(filters) unless filters.empty? && ids.nil?
+          if ids
+            body[:filter][:must] << { key: IDENTIFIER_KEY, match: { any: ids } }
+            body[:params] = { exact: true }
+          end
+          body
+        end
+
         # Build a Qdrant filter from metadata key-value pairs.
         #
         # @param filters [Hash] Metadata filters

data/lib/woods/storage/vector_store.rb

@@ -90,12 +90,17 @@ module Woods
         # @param limit [Integer] Maximum number of results to return
         # @param filters [Hash] Optional metadata filters — values may be
         #   scalars or Arrays
+        # @param ids [Array<String>, nil] Raw vector IDs eligible before ranking;
+        #   optional capability advertised by #supports_id_filter?. Empty matches none.
         # @return [Array<SearchResult>] Results sorted by descending similarity
         # @raise [NotImplementedError] if not implemented by adapter
-        def search(query_vector, limit: 10, filters: {})
+        def search(query_vector, limit: 10, filters: {}, ids: nil)
           raise NotImplementedError
         end
 
+        # Whether native raw-ID eligibility is supported before the result limit.
+        def supports_id_filter? = false
+
         # Delete a vector by ID.
         #
         # @param id [String] The identifier to delete
@@ -220,8 +225,10 @@ module Woods
           end
         end
 
+        def supports_id_filter? = true
+
         # @see Interface#search
-        def search(query_vector, limit: 10, filters: {})
+        def search(query_vector, limit: 10, filters: {}, ids: nil)
           return [] if @dim.nil?
 
           unless query_vector.length == @dim
@@ -229,8 +236,8 @@ module Woods
                   "Vector dimension mismatch (#{query_vector.length} vs #{@dim})"
           end
 
-          scored = gather_candidates(query_vector, filters)
-          scored.sort_by! { |r| -r.score }
+          scored = gather_candidates(query_vector, filters, ids)
+          scored.sort_by! { |r| ids ? [-r.score, r.id] : [-r.score] }
           scored.first(limit)
         end
 
@@ -300,15 +307,20 @@ module Woods
           @metadata[idx] = metadata
         end
 
+        def excluded_index?(idx, allowed_ids)
+          @tombstones.include?(idx) || (allowed_ids && !allowed_ids.include?(@ids[idx]))
+        end
+
         # Walk every non-tombstoned index, apply filters, score survivors.
         # Filter check runs BEFORE the cosine kernel — avoids computing
         # 12k dot products only to discard most of them.
-        def gather_candidates(query_vector, filters)
+        def gather_candidates(query_vector, filters, ids)
           scored = []
+          allowed_ids = ids&.to_set
           len = @ids.size
           idx = 0
           while idx < len
-            if @tombstones.include?(idx)
+            if excluded_index?(idx, allowed_ids)
               idx += 1
               next
             end

data/lib/woods/tasks.rb

@@ -27,6 +27,7 @@ module Woods
     # @return [Embedding::Indexer]
     def build_embed_indexer
       config = Woods.configuration
+      output_dir = ENV.fetch('WOODS_OUTPUT', config.output_dir)
       builder = Builder.new(config)
       provider = builder.build_embedding_provider
 
@@ -56,11 +57,11 @@ module Woods
         provider: resilient_provider,
         text_preparer: builder.build_text_preparer(provider),
         vector_store: vector_store,
-        metadata_store: config.metadata_store ? builder.build_metadata_store : nil,
+        metadata_store: config.metadata_store ? builder.build_metadata_store(output_dir: output_dir) : nil,
         resolved_config: build_resolved_config(config, provider: provider),
         chunker: builder.build_chunker(provider),
         dump_retention_count: config.dump_retention_count,
-        output_dir: ENV.fetch('WOODS_OUTPUT', config.output_dir)
+        output_dir: output_dir
       )
     end
 

data/lib/woods/temporal/json_snapshot_store.rb

@@ -22,7 +22,8 @@ module Woods
     #
     # Implements the same public interface as SnapshotStore so the MCP server
     # tools work identically.
-    # Malformed retained snapshots are warned about and treated as absent:
+    # Malformed, invalidly shaped, or unreadable retained snapshots (including files
+    # removed during retention) are warned about and treated as absent:
     # +find+ returns nil, +diff+ returns an empty result, and history/list scans
     # omit the corrupt file.
     #
@@ -94,7 +95,6 @@ module Woods
         snapshots = load_all_with_units
                     .sort_by { |s| s[:extracted_at] || '' }
                     .reverse
-                    .first(limit)
 
         entries = snapshots.flat_map do |snap|
           snap[:units].values.select { |unit| unit[:identifier] == identifier }.map do |unit|
@@ -122,9 +122,9 @@ module Woods
         value.positive? ? value : PayloadStore::DEFAULT_RETENTION
       end
 
-      # Delete snapshots beyond the retention count, oldest by extracted_at
-      # first. +protect+ names the snapshot just captured; it is the newest
-      # anyway, and a tie on extracted_at must not delete it.
+      # Delete snapshots beyond the retention count, corrupt/unreadable files
+      # first, then oldest by extracted_at. +protect+ names the snapshot just
+      # captured; even an older timestamp must not cause its deletion.
       #
       # Failures are non-fatal: retention is housekeeping, and a failed
       # prune leaves the store growing as it did before rather than
@@ -133,7 +133,7 @@ module Woods
       # @param protect [String] git SHA of the just-captured snapshot
       # @return [void]
       def prune_snapshots(protect:)
-        summaries = load_all_summaries
+        summaries = retention_summaries
         overflow = summaries.size - @retention
         return unless overflow.positive?
 
@@ -142,7 +142,19 @@ module Woods
         warn "[Woods] Snapshot retention failed: #{e.message}"
       end
 
-      # Oldest `overflow` snapshots by extracted_at, never the protected one.
+      # Include unreadable snapshots in the bound. Only files named like a
+      # snapshot are eligible; the filename owns identity, not JSON content.
+      def retention_summaries
+        Dir.glob(File.join(@dir, '*.json')).filter_map do |path|
+          sha = File.basename(path, '.json')
+          next unless sha.match?(/\A[0-9a-f]+\z/i) && File.file?(path)
+
+          data = read_snapshot(path)
+          { git_sha: sha, extracted_at: data&.[]('extracted_at') || '', corrupt: data.nil? }
+        end
+      end
+
+      # Corrupt files, then oldest `overflow` snapshots, never the protected one.
       # The protected SHA is rejected before sorting and slicing: it is
       # captured last, so its extracted_at can tie or precede older entries,
       # and letting it occupy the victim slice would leave the store one file
@@ -154,7 +166,7 @@ module Woods
       # @return [Array<String>]
       def retention_victims(summaries, overflow, protect)
         summaries.reject { |summary| summary[:git_sha] == protect }
-                 .sort_by { |summary| summary[:extracted_at] || '' }
+                 .sort_by { |summary| [summary[:corrupt] ? 0 : 1, summary[:extracted_at], summary[:git_sha]] }
                  .first(overflow)
                  .map { |summary| summary[:git_sha] }
       end
@@ -264,10 +276,47 @@ module Woods
       end
 
       def read_snapshot(path)
-        JSON.parse(AtomicFile.read(path))
+        data = JSON.parse(AtomicFile.read(path))
+        validate_snapshot_shape!(data)
+        unless data['git_sha'] == File.basename(path, '.json')
+          raise JSON::ParserError, 'git_sha does not match the snapshot filename'
+        end
+
+        data
       rescue JSON::ParserError => e
         warn "[Woods] Skipping corrupt snapshot #{File.basename(path)}: #{e.message}"
         nil
+      rescue SystemCallError => e
+        warn "[Woods] Skipping unreadable snapshot #{File.basename(path)}: #{e.message}"
+        nil
+      end
+
+      # Guard only shapes consumed by conversion, sorting, and the next capture.
+      # Legacy files can omit units/timestamps and optional per-unit hashes;
+      # bare unit keys still supply identifiers when the record does not.
+      def validate_snapshot_shape!(data)
+        raise JSON::ParserError, 'expected a JSON object' unless data.is_a?(Hash)
+
+        sha = data['git_sha']
+        unless sha.is_a?(String) && sha.match?(/\A[0-9a-f]+\z/i)
+          raise JSON::ParserError, 'expected git_sha to be a hexadecimal string'
+        end
+
+        timestamp = data['extracted_at']
+        unless timestamp.nil? || timestamp.is_a?(String)
+          raise JSON::ParserError, 'expected extracted_at to be a string or null'
+        end
+
+        validate_snapshot_units!(data['units'])
+      end
+
+      def validate_snapshot_units!(units)
+        return if units.nil?
+
+        raise JSON::ParserError, 'expected units to be an object or null' unless units.is_a?(Hash)
+        return if units.each_value.all?(Hash)
+
+        raise JSON::ParserError, 'expected every unit record to be an object'
       end
 
       # @param exclude_sha [String, nil] SHA to leave out of the result