woods 1.6.1 → 2.0.0.beta2

data/lib/woods/reload_policy.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Woods
+  # What a resident, booted Woods process must do before a changed path can be
+  # re-extracted truthfully.
+  #
+  # Extraction reads the *runtime*: `ActiveRecord::Base.descendants`,
+  # `Rails.application.routes`, resolved `config` values, callback chains on
+  # loaded classes. So "the file changed" is not the same question as "what do
+  # I have to do before re-reading it is worth anything". Three answers matter,
+  # in increasing cost:
+  #
+  # * `:reextract` — Woods reads this file's bytes, not a constant.
+  #   Re-extract; no Rails machinery has to run first.
+  # * `:reload` — an autoloaded constant changed. Reload through
+  #   `Rails.application.reloader` first, or the extractor introspects the
+  #   class that is already gone.
+  # * `:restart` — boot-captured state changed. No reloader re-runs it, so
+  #   the process itself has to go.
+  #
+  # `:ignore` is the fourth answer and the common case: most of a repository
+  # is not extraction input at all.
+  #
+  # ## Why `:restart` is a real category
+  #
+  # Rails' reloader replaces autoloaded constants. It does not re-run
+  # initializers, re-read `config/*`, re-resolve `Rails.application.config`,
+  # or rebuild the schema cache. Woods captures all of those:
+  # `BehavioralProfile` introspects resolved config, `MiddlewareExtractor`
+  # reads the built middleware stack, model extraction reads column
+  # information. `rails/spring`'s well-documented staleness bugs came from
+  # exactly this — under-scoping the restart set — so the boundary here is
+  # drawn on the generous side.
+  #
+  # ## Version notes (railties >= 6.0)
+  #
+  # The classification is deliberately version-independent. Zeitwerk is the
+  # only autoloader from 6.0 on, and every path class below has meant the same
+  # thing throughout that range. Two version-sensitive behaviours sit *behind*
+  # the classification rather than in it, and belong to whoever implements the
+  # reload step:
+  #
+  # * `ActiveSupport::DescendantsTracker` internals changed across 6.0–8.x, so
+  #   a reload can leave stale entries in a descendants set. Discovery-based
+  #   extraction should re-read descendants *after* the reload completes, never
+  #   across it.
+  # * A schema change needs `reset_column_information` plus schema-cache
+  #   invalidation to be visible. That is classified `:restart` here rather
+  #   than `:reload` because getting it right in-process is subtle and the
+  #   payoff is small — schema changes are rare and already expensive.
+  #
+  # @example Deciding what a batch of file events requires
+  #   policy = Woods::ReloadPolicy.new
+  #   policy.classify_all(%w[app/models/user.rb config/initializers/redis.rb])
+  #   # => :restart
+  #
+  class ReloadPolicy
+    # Ordered least to most disruptive. {#classify_all} returns the last one
+    # any path in the set demands.
+    ACTIONS = %i[ignore reextract reload restart].freeze
+
+    # Exact paths whose change invalidates boot-captured state.
+    RESTART_PATHS = %w[
+      Gemfile
+      Gemfile.lock
+      .ruby-version
+      config/application.rb
+      config/boot.rb
+      config/environment.rb
+      config/database.yml
+      config/credentials.yml.enc
+      config/master.key
+      db/schema.rb
+      db/structure.sql
+    ].freeze
+
+    # Boot-captured configuration that is not under an initializer directory.
+    #
+    # `BehavioralProfile` introspects *resolved* `Rails.application.config`, and
+    # these are the files that feed it outside `config/initializers`: the
+    # `config` gem's settings, and the per-adapter YAML Rails reads at boot.
+    # They were classified `:ignore`, which is precisely the Spring-style
+    # under-scoping this file's own commentary warns against — a daemon that
+    # ignores them keeps serving a profile derived from the previous values.
+    #
+    # `.env` files are matched by prefix rather than listed, because dotenv
+    # conventionally ships `.env`, `.env.local`, `.env.development` and friends.
+    # They also have to survive the watcher's dotfile filter to be seen at all.
+    # Named rather than wildcarded, deliberately. `config/*.yml` also catches
+    # files Woods reads as *bytes* — `config/recurring.yml` and
+    # `config/sidekiq_cron.yml` are scheduled-job sources, and escalating
+    # either to `:restart` would stop the daemon for a change it could simply
+    # re-extract. The boot-captured set is small and knowable; guessing at it
+    # costs more than listing it.
+    RESTART_PATH_PATTERNS = [
+      %r{\Aconfig/settings\.ya?ml\z},
+      %r{\Aconfig/settings/[^/]+\.ya?ml\z},
+      # Note what is absent: `config/recurring.yml` and `config/sidekiq_cron.yml`
+      # are scheduled-job *sources* that Woods reads as bytes
+      # (`ScheduledJobExtractor::SCHEDULE_FILES`), so they stay `:reextract`.
+      # `spec/reload_policy_spec.rb` asserts that, which is how the first draft
+      # of this list got caught.
+      %r{\Aconfig/(cable|storage|sidekiq|puma|cache|queue)\.ya?ml\z},
+      /\A\.env(\..+)?\z/
+    ].freeze
+
+    # Directory prefixes whose change invalidates boot-captured state.
+    RESTART_DIRECTORIES = %w[
+      config/initializers
+      config/environments
+      config/credentials
+    ].freeze
+
+    # Directories holding autoloaded application code. A `.rb` change here
+    # redefines a constant the extractors introspect.
+    RELOAD_DIRECTORIES = %w[app lib].freeze
+
+    # Route definitions. Reloading the route set is cheaper than a full
+    # reload (`Rails.application.reload_routes!`), but it is still a runtime
+    # refresh rather than a file re-read, so it lands in the same bucket.
+    ROUTE_PATHS = %w[config/routes.rb].freeze
+    ROUTE_DIRECTORIES = %w[config/routes].freeze
+
+    # Directories Woods reads as bytes. No constant is involved, so no Rails
+    # machinery has to run before re-extraction.
+    REEXTRACT_DIRECTORIES = %w[
+      app/views
+      config/locales
+      db/migrate
+      db/views
+      lib/tasks
+      spec
+      test
+    ].freeze
+
+    # Schedule files, which are data rather than code.
+    REEXTRACT_PATHS = %w[
+      config/recurring.yml
+      config/sidekiq_cron.yml
+      config/schedule.rb
+    ].freeze
+
+    # Packwerk boundary files, read as bytes by PackageExtractor (#280).
+    REEXTRACT_BASENAMES = %w[package.yml packwerk.yml].freeze
+
+    # What has to happen before this path can be re-extracted truthfully.
+    #
+    # @param relative_path [String] Rails.root-relative path
+    # @return [Symbol] one of {ACTIONS}
+    def classify(relative_path)
+      path = relative_path.to_s
+      return :restart if restart?(path)
+      return :reload if reload?(path)
+      return :reextract if reextract?(path)
+
+      :ignore
+    end
+
+    # The strongest action any path in the set demands.
+    #
+    # @param relative_paths [Enumerable<String>]
+    # @return [Symbol] one of {ACTIONS}
+    def classify_all(relative_paths)
+      Array(relative_paths).reduce(:ignore) do |strongest, path|
+        stronger_of(strongest, classify(path))
+      end
+    end
+
+    # Paths in the set that demand a given action.
+    #
+    # @param relative_paths [Enumerable<String>]
+    # @param action [Symbol] one of {ACTIONS}
+    # @return [Array<String>]
+    def paths_requiring(relative_paths, action)
+      Array(relative_paths).select { |path| classify(path) == action }
+    end
+
+    private
+
+    def stronger_of(left, right)
+      ACTIONS.index(left) >= ACTIONS.index(right) ? left : right
+    end
+
+    def restart?(path)
+      RESTART_PATHS.include?(path) || under?(path, RESTART_DIRECTORIES) ||
+        RESTART_PATH_PATTERNS.any? { |pattern| pattern.match?(path) }
+    end
+
+    def reload?(path)
+      return true if ROUTE_PATHS.include?(path) || under?(path, ROUTE_DIRECTORIES)
+      # lib/tasks and lib/generators are read as files, never autoloaded.
+      return false if under?(path, %w[lib/tasks lib/generators])
+
+      path.end_with?('.rb') && under?(path, RELOAD_DIRECTORIES)
+    end
+
+    def reextract?(path)
+      REEXTRACT_PATHS.include?(path) || under?(path, REEXTRACT_DIRECTORIES) ||
+        REEXTRACT_BASENAMES.include?(File.basename(path))
+    end
+
+    def under?(path, directories)
+      directories.any? { |dir| path.start_with?("#{dir}/") }
+    end
+  end
+end

data/lib/woods/resilience/circuit_breaker.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Woods
+  # Same conditional-define pattern used elsewhere in the gem (pgvector,
+  # metadata_store) so this file can be required in isolation without
+  # tripping NameError on the CircuitOpenError superclass below.
+  class Error < StandardError; end unless defined?(Woods::Error)
+
   module Resilience
     # Raised when the circuit breaker is open and calls are being rejected.
     #
@@ -65,30 +70,64 @@ module Woods
       # @raise [StandardError] re-raises any error from the block
       def call(&block)
         probing = admit_call!
+        handled = false
 
         begin
           result = block.call
+          handled = true
         rescue CircuitOpenError
           # A nested breaker tripped — release our probe slot but don't count
           # it as this breaker's own failure.
-          @mutex.synchronize { @half_open_probe_in_flight = false if probing }
+          handled = true
+          release_probe(probing)
           raise
         rescue StandardError => e
-          @mutex.synchronize do
-            @half_open_probe_in_flight = false if probing
-            record_failure(probing)
-          end
+          handled = true
+          finish_failure(probing)
           raise e
+        ensure
+          # A non-StandardError hits neither rescue above (Interrupt,
+          # Thread#raise-delivered exceptions, a custom Exception subclass).
+          # Release only the probe slot here — deliberately no
+          # record_failure, matching pre-existing state-transition rules.
+          release_probe(probing) unless handled
         end
 
+        finish_success(probing)
+        result
+      end
+
+      private
+
+      # Release the half_open probe slot without recording an outcome.
+      # Used by the CircuitOpenError rescue (a nested breaker's failure
+      # isn't this breaker's own) and the ensure fallback (a non-StandardError
+      # that skipped both rescue clauses).
+      #
+      # @param probing [Boolean] whether this call was admitted as the probe
+      def release_probe(probing)
+        @mutex.synchronize { @half_open_probe_in_flight = false if probing }
+      end
+
+      # Release the probe slot and record a failure, atomically.
+      #
+      # @param probing [Boolean] whether this call was admitted as the probe
+      def finish_failure(probing)
         @mutex.synchronize do
           @half_open_probe_in_flight = false if probing
-          record_success(probing)
+          record_failure(probing)
         end
-        result
       end
 
-      private
+      # Release the probe slot and record a success, atomically.
+      #
+      # @param probing [Boolean] whether this call was admitted as the probe
+      def finish_success(probing)
+        @mutex.synchronize do
+          @half_open_probe_in_flight = false if probing
+          record_success(probing)
+        end
+      end
 
       # Decide whether this call may proceed, transitioning open→half_open when
       # the reset timeout has elapsed. Runs entirely under the mutex.

data/lib/woods/resilience/index_validator.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 require_relative '../filename_utils'
+require_relative '../atomic_file'
+
+require_relative '../generation'
 
 module Woods
   module Resilience
@@ -13,11 +17,22 @@ module Woods
     # - Content hashes (source_hash) match the actual source_code
     # - No stale unit files exist that aren't listed in the index
     #
+    # **This class knows nothing about vectors or embedding dimensions.** Six
+    # documents used to credit it with detecting dimension mismatches; it never
+    # did (#214). That check is {Woods::MCP::DimensionMismatch}, raised by
+    # `Tasks.verify_store_dimensions!` before a durable embed run and by
+    # {Woods::Storage::Snapshotter::Vector} at MCP boot.
+    #
+    # Consumed by `spec/integration/multi_worktree_spec.rb` as a per-worktree
+    # integrity oracle. The `woods:validate` rake task performs an overlapping
+    # check inline rather than calling this — deliberate duplication left alone
+    # for now, since the task's output format is user-facing.
+    #
     # @example
     #   validator = IndexValidator.new(index_dir: "tmp/woods")
     #   report = validator.validate
     #   puts report.errors if !report.valid?
-    class IndexValidator
+    class IndexValidator # rubocop:disable Metrics/ClassLength
       include Woods::FilenameUtils
 
       # Report produced by {#validate}.
@@ -30,9 +45,31 @@ module Woods
       #   @return [Array<String>] fatal integrity issues
       ValidationReport = Struct.new(:valid?, :warnings, :errors, keyword_init: true)
 
+      # The shared unit-type-directory contract, loadable without Rails:
+      # exactly the directories extraction publishes unit types into,
+      # derived from `Extractor::EXTRACTORS`. `woods/extractor` loads clean
+      # without a booted Rails app (the unit suite proves it), so this stays
+      # a plain require. A failure raises to the caller — it must convert
+      # the failure into a validation error rather than degrade to a
+      # silently empty allowlist, which would disable every structural
+      # type-directory check without saying so.
+      #
+      # @return [Array<String>]
+      # @raise [StandardError] when the extraction contract cannot be loaded
+      def self.unit_type_directories
+        require_relative '../extractor' unless defined?(Woods::Extractor::EXTRACTORS)
+
+        Woods::Extractor::EXTRACTORS.keys.map(&:to_s).freeze
+      end
+
       # @param index_dir [String] Path to the codebase index output directory
-      def initialize(index_dir:)
+      # @param app_root [String, nil] the host application root; when given,
+      #   a unit whose +file_path+ resolves neither as written nor under it
+      #   is reported (the #169 staleness class: extracted elsewhere, or the
+      #   source has since vanished)
+      def initialize(index_dir:, app_root: nil)
         @index_dir = index_dir
+        @app_root = app_root
       end
 
       # Validate the index directory and return a report.
@@ -47,20 +84,269 @@ module Woods
           return ValidationReport.new(valid?: false, warnings: warnings, errors: errors)
         end
 
-        type_dirs = Dir.children(@index_dir).filter_map do |name|
-          full_path = File.join(@index_dir, name)
-          full_path if File.directory?(full_path)
-        end
-
-        type_dirs.each do |type_dir|
+        payload_type_dirs(errors).each do |type_dir|
           validate_type_directory(type_dir, warnings, errors)
         end
+        validate_flow_artifacts(errors)
+        validate_against_manifest(warnings, errors)
 
         ValidationReport.new(valid?: errors.empty?, warnings: warnings, errors: errors)
       end
 
+      # The checks `woods:validate` used to carry inline: manifest counts
+      # against the files on disk, every unit file parseable with an
+      # identifier and source, file paths that resolve, and a parseable
+      # dependency graph. Skipped when there is no manifest, so a bare
+      # type-directory tree (older fixtures, partial writes) still validates
+      # on the structural checks alone.
+      #
+      # @param warnings [Array<String>]
+      # @param errors [Array<String>]
+      def validate_against_manifest(warnings, errors)
+        payload = payload_dir
+        manifest_path = File.join(payload, 'manifest.json')
+        return unless File.exist?(manifest_path)
+
+        manifest = JSON.parse(Woods::AtomicFile.read(manifest_path))
+        unresolvable = Hash.new { |hash, key| hash[key] = [] }
+
+        (manifest['counts'] || {}).each do |type, expected_count|
+          validate_manifest_type(payload, type, expected_count, unresolvable, warnings, errors)
+        end
+
+        warn_unresolvable_paths(warnings, unresolvable)
+        validate_dependency_graph(payload, errors)
+      end
+
+      # Split each type's unresolvable units into app-tree paths and gem-owned
+      # paths, since only the first has a remedy the operator can act on.
+      #
+      # @param warnings [Array<String>]
+      # @param unresolvable [Hash{String => Array<Array(String, Boolean)>}]
+      def warn_unresolvable_paths(warnings, unresolvable)
+        unresolvable.each do |type, entries|
+          inside, outside = entries.partition { |_identifier, outside_root| !outside_root }
+          warn_unresolvable_app_paths(warnings, type, inside.map(&:first))
+          warn_unresolvable_gem_paths(warnings, type, outside.map(&:first))
+        end
+      end
+
+      # App-tree paths that do not exist under the app root: the index was
+      # extracted from a different tree, and re-extracting here fixes it.
+      def warn_unresolvable_app_paths(warnings, type, identifiers)
+        return if identifiers.empty?
+
+        warnings << "#{type}: #{identifiers.size} unit(s) whose file_path resolves nowhere " \
+                    "(e.g. #{identifiers.first(3).join(', ')}). Extracted in a different environment? " \
+                    'Re-run extraction.'
+      end
+
+      # Absolute paths outside the app root belong to a gem — an engine model,
+      # a framework source — and resolve only where that gem is installed at
+      # the extracting path. Re-running extraction here cannot change that,
+      # so the remedy is not offered.
+      def warn_unresolvable_gem_paths(warnings, type, identifiers)
+        return if identifiers.empty?
+
+        warnings << "#{type}: #{identifiers.size} unit(s) whose file_path lies outside the app root " \
+                    "and is absent here (e.g. #{identifiers.first(3).join(', ')}). Gem-owned units " \
+                    '(engine models, framework sources) resolve only where that gem is installed at ' \
+                    'the extracting path.'
+      end
+
+      # rubocop:disable-next Metrics/ParameterLists
+      def validate_manifest_type(payload, type, expected_count, unresolvable, warnings, errors)
+        type_dir = File.join(payload, type)
+        unless File.directory?(type_dir)
+          errors << "Missing directory: #{type}"
+          return
+        end
+
+        unit_files = Dir[File.join(type_dir, '*.json')].reject { |f| f.end_with?('_index.json') }
+        warnings << "#{type}: expected #{expected_count}, found #{unit_files.size}" if unit_files.size != expected_count
+        unit_files.each { |file| validate_unit_file(file, type, unresolvable, errors) }
+      end
+
+      # @param file [String] unit JSON path
+      # @param type [String] type directory name
+      # @param unresolvable [Hash{String => Array<Array(String, Boolean)>}]
+      #   `[identifier, outside_app_root]` pairs whose file_path resolves
+      #   nowhere, keyed by type
+      # @param errors [Array<String>]
+      def validate_unit_file(file, type, unresolvable, errors)
+        data = JSON.parse(Woods::AtomicFile.read(file))
+        errors << "#{file}: missing identifier" unless data['identifier']
+        errors << "#{file}: missing source_code" unless data['source_code']
+        file_path = data['file_path']
+        return if path_resolvable?(file_path)
+
+        unresolvable[type] << [data['identifier'] || File.basename(file), outside_app_root?(file_path)]
+      rescue JSON::ParserError => e
+        errors << "#{file}: invalid JSON - #{e.message}"
+      end
+
+      # True when the check is off (no +app_root+), the unit has no path, or
+      # the path exists as written or under the app root.
+      def path_resolvable?(file_path)
+        return true if @app_root.nil? || file_path.nil?
+
+        File.exist?(file_path) || File.exist?(File.join(@app_root, file_path))
+      rescue StandardError
+        false
+      end
+
+      # True for an absolute path that is not under the app root. Extraction
+      # relativizes every path under Rails.root, so an absolute path in the
+      # index is one that was never in the app tree: a gem's.
+      def outside_app_root?(file_path)
+        return false unless file_path.to_s.start_with?('/')
+
+        !file_path.start_with?("#{@app_root.to_s.chomp('/')}/")
+      end
+
+      def validate_dependency_graph(payload, errors)
+        graph_path = File.join(payload, 'dependency_graph.json')
+        unless File.exist?(graph_path)
+          errors << 'Missing dependency_graph.json'
+          return
+        end
+
+        JSON.parse(Woods::AtomicFile.read(graph_path))
+      rescue JSON::ParserError
+        errors << 'dependency_graph.json: invalid JSON'
+      end
+
+      def payload_dir
+        Woods::Generation.new(output_dir: @index_dir).payload_dir.to_s
+      end
+
       private
 
+      # Resolve the published generation's payload and list its unit-type
+      # directories (e.g. models/, controllers/). An index that publishes
+      # per-generation payloads keeps `payloads/`, `dumps/` and `tasks/`
+      # beside them at the root, none of which are type directories.
+      #
+      # The list is bounded by a type-directory allowlist (G-2): a directory
+      # the allowlist does not claim — `flows/` above all — is not a unit-type
+      # directory and never reaches {#validate_type_directory}, which demands
+      # an `_index.json` no auxiliary artifact can satisfy. Before the
+      # allowlist, every directory under the payload was treated as a unit
+      # type, so any index published with flow precomputation enabled failed
+      # validation with "Missing _index.json in flows/".
+      #
+      # @param errors [Array<String>] accumulated errors; appended to if the
+      #   payload directory named by the published generation isn't on disk,
+      #   or the shared type-directory allowlist cannot be derived (a
+      #   silently empty allowlist would disable every structural
+      #   type-directory check without saying so)
+      # @return [Array<String>] absolute paths to type directories
+      def payload_type_dirs(errors)
+        payload = payload_dir
+        allowlist = derive_type_directory_allowlist(errors)
+        return [] if allowlist.nil?
+
+        Dir.children(payload).filter_map do |name|
+          full_path = File.join(payload, name)
+          next unless File.directory?(full_path)
+          next unless allowlist.include?(name)
+
+          full_path
+        end
+      rescue Errno::ENOENT
+        # A published `generation.json` pointing at a payload directory
+        # that isn't actually on disk (e.g. a generation bump raced a
+        # promote, or the payload was manually removed) is an index
+        # integrity problem this validator exists to report — not a
+        # crash for its caller to catch.
+        errors << "Payload directory does not exist: #{payload}"
+        []
+      end
+
+      # The allowlist, or nil — with a validation error recorded — when the
+      # shared contract cannot be derived. A silently empty allowlist would
+      # disable every structural type-directory check without saying so.
+      #
+      # @param errors [Array<String>] accumulated errors
+      # @return [Array<String>, nil]
+      def derive_type_directory_allowlist(errors)
+        type_directory_allowlist
+      rescue StandardError, ScriptError => e
+        # ScriptError too: a require failure surfaces as LoadError, which
+        # `rescue StandardError` does not catch.
+        errors << 'Could not derive the unit-type directory allowlist ' \
+                  "(#{e.class}: #{e.message}); structural checks disabled"
+        nil
+      end
+
+      # @param name [String] directory basename under the payload
+      # @return [Boolean] true when extraction publishes unit types here
+      def unit_type_directory?(name)
+        type_directory_allowlist.include?(name)
+      end
+
+      # The shared allowlist: exactly the directories extraction publishes
+      # unit types into, derived from `Extractor::EXTRACTORS` so the two
+      # cannot drift. Required lazily — {IndexValidator} deliberately loads
+      # without Rails, and `woods/extractor` also loads clean. A derivation
+      # failure RAISES: {#payload_type_dirs} converts it to a validation
+      # error rather than degrading to a silently empty allowlist.
+      #
+      # `flows/` is deliberately absent: it holds `flow_index.json` and
+      # per-flow documents, which {#validate_flow_artifacts} owns.
+      #
+      # @return [Array<String>]
+      def type_directory_allowlist
+        @type_directory_allowlist ||= self.class.unit_type_directories
+      end
+
+      # Validate the flows/ artifact family (G-2): `flow_index.json` parses,
+      # and every entry points at a flow document that exists and parses.
+      #
+      # A payload from a run that never enabled flow precomputation has no
+      # flows directory at all, and an empty one holds nothing — both are
+      # absences. A POPULATED family with no index is corruption: the index
+      # is what defines which documents are live, so documents without it
+      # are unaccounted artifacts and are reported, not accepted.
+      #
+      # @param errors [Array<String>] accumulated errors
+      def validate_flow_artifacts(errors)
+        flows_dir = File.join(payload_dir, 'flows')
+        return unless File.directory?(flows_dir)
+        return if Dir.empty?(flows_dir)
+
+        index_path = File.join(flows_dir, 'flow_index.json')
+        unless File.exist?(index_path)
+          errors << 'flows/ is populated but flow_index.json is missing'
+          return
+        end
+
+        index = parse_artifact(index_path, 'flows/flow_index.json', errors)
+        return unless index.is_a?(Hash)
+
+        index.each_value do |relative|
+          filename = File.basename(relative.to_s)
+          document = File.join(flows_dir, filename)
+          unless File.exist?(document)
+            errors << "flow_index.json references missing document: flows/#{filename}"
+            next
+          end
+
+          parse_artifact(document, "flows/#{filename}", errors)
+        end
+      end
+
+      # @param path [String] artifact path
+      # @param label [String] how to name the artifact in an error
+      # @param errors [Array<String>] accumulated errors
+      # @return [Object, nil] parsed JSON, or nil when it does not parse
+      def parse_artifact(path, label, errors)
+        JSON.parse(Woods::AtomicFile.read(path))
+      rescue JSON::ParserError => e
+        errors << "#{label}: invalid JSON - #{e.message}"
+        nil
+      end
+
       # Validate a single type directory (e.g., models/, controllers/).
       #
       # @param type_dir [String] Absolute path to the type directory
@@ -75,7 +361,7 @@ module Woods
           return
         end
 
-        index_entries = JSON.parse(File.read(index_path))
+        index_entries = JSON.parse(Woods::AtomicFile.read(index_path))
         indexed_identifiers = Set.new
 
         index_entries.each do |entry|
@@ -126,7 +412,7 @@ module Woods
       # @param identifier [String] The unit identifier (for error messages)
       # @param errors [Array<String>] Accumulated errors
       def validate_content_hash(unit_file, identifier, errors)
-        data = JSON.parse(File.read(unit_file))
+        data = JSON.parse(Woods::AtomicFile.read(unit_file))
         source_code = data['source_code']
         stored_hash = data['source_hash']