woods 1.6.2 → 2.0.0.beta1

data/lib/woods/obsidian/vault_exporter.rb

@@ -70,31 +70,53 @@ module Woods
       #
       # @return [Hash] { exported:, indexes:, swept:, skipped:, errors: }
       def export_all
-        graph = @reader.raw_graph_data || {}
-        @nodes = graph['nodes'] || {}
-        @pagerank = graph['pagerank'] || {}
-        analysis = safe_graph_analysis
-        owned = vault_owned_at_start?
+        with_pinned_index do
+          graph = @reader.raw_graph_data || {}
+          @nodes = graph['nodes'] || {}
+          @pagerank = graph['pagerank'] || {}
+          analysis = safe_graph_analysis
+          owned = vault_owned_at_start?
+
+          emitted, skipped = partition_emitted
+          mapper = build_mapper(emitted)
+          edge_map = build_edge_map(emitted.to_set, graph)
+          builder = build_note_builder(mapper, analysis)
+
+          written = Set.new
+          errors = []
+          exported = write_notes(emitted, mapper, edge_map, builder, written, errors)
+          indexes = write_indexes(emitted, mapper, written)
+          write_sidecar(emitted, mapper, graph, analysis, written)
+          write_owned_assets(emitted) if owned
+
+          swept = owned && errors.empty? ? sweep(written) : 0
+          warn_foreign unless owned
+          { exported: exported, indexes: indexes, swept: swept, skipped: skipped, errors: cap_errors(errors) }
+        end
+      end
 
-        emitted, skipped = partition_emitted
-        mapper = build_mapper(emitted)
-        edge_map = build_edge_map(emitted.to_set, graph)
-        builder = build_note_builder(mapper, analysis)
+      private
 
-        written = Set.new
-        errors = []
-        exported = write_notes(emitted, mapper, edge_map, builder, written, errors)
-        indexes = write_indexes(emitted, mapper, written)
-        write_sidecar(emitted, mapper, graph, analysis, written)
-        write_owned_assets(emitted) if owned
+      # Run the export against one index generation.
+      #
+      # Every public IndexReader accessor self-refreshes when the published
+      # generation moves, and the reader assigns pinning responsibility to
+      # direct callers. Unpinned, `raw_graph_data` and the per-unit reads can
+      # straddle two generations (EXP-5) — which the "byte-identical across
+      # runs" contract cannot survive, and which computes the sweep set against
+      # a mixture.
+      #
+      # Guarded by +respond_to?+: injected readers (specs, embedders) need not
+      # implement pinning.
+      #
+      # @yield the export body
+      # @return [Object] the block's value
+      def with_pinned_index(&block)
+        return yield unless @reader.respond_to?(:with_pinned_generation)
 
-        swept = owned && errors.empty? ? sweep(written) : 0
-        warn_foreign unless owned
-        { exported: exported, indexes: indexes, swept: swept, skipped: skipped, errors: cap_errors(errors) }
+        @reader.with_pinned_generation(&block)
       end
 
-      private
-
       # ── Selection / mapping ──────────────────────────────────────────
 
       # The emitted set = graph nodes of an exportable type that have a loadable
@@ -145,7 +167,17 @@ module Woods
 
       def dir_for(type)
         require 'woods/mcp/index_reader'
-        Woods::MCP::IndexReader::TYPE_TO_DIR[type] || "#{type}s"
+        Woods::MCP::IndexReader::TYPE_TO_DIR[type] || sanitize_dir_segment("#{type}s")
+      end
+
+      # Same character policy as NameMapper's basename sanitizer: an unknown
+      # graph node type reaches here verbatim (it isn't a fixed TYPE_TO_DIR
+      # value), so it gets the same treatment before being used as a path
+      # segment — otherwise a type of "../../escape" would flow straight into
+      # the vault-relative path NameMapper builds.
+      def sanitize_dir_segment(str)
+        out = str.to_s.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+        out.empty? ? 'unit' : out
       end
 
       def build_note_builder(mapper, analysis)
@@ -187,7 +219,7 @@ module Woods
           next if note.nil?
 
           rel = mapper.path_for(id)
-          AtomicFile.write(@vault.join(rel), note)
+          safe_write(@vault.join(rel), note)
           written << rel
           exported += 1
         rescue StandardError => e
@@ -245,13 +277,13 @@ module Woods
 
       def write_owned_assets(emitted)
         if can_write_obsidian_config?
-          AtomicFile.write(@vault.join('.obsidian', 'app.json'), VaultAssets.app_json)
-          AtomicFile.write(@vault.join('.obsidian', 'types.json'), VaultAssets.types_json)
-          AtomicFile.write(@vault.join('.obsidian', 'graph.json'), VaultAssets.graph_json(present_types(emitted)))
-          AtomicFile.write(@vault.join('Units.base'), VaultAssets.units_base)
+          safe_write(@vault.join('.obsidian', 'app.json'), VaultAssets.app_json)
+          safe_write(@vault.join('.obsidian', 'types.json'), VaultAssets.types_json)
+          safe_write(@vault.join('.obsidian', 'graph.json'), VaultAssets.graph_json(present_types(emitted)))
+          safe_write(@vault.join('Units.base'), VaultAssets.units_base)
         end
-        AtomicFile.write(@vault.join(SENTINEL),
-                         "woods-managed vault — regenerated by `rake woods:obsidian`. Safe to delete.\n")
+        safe_write(@vault.join(SENTINEL),
+                   "woods-managed vault — regenerated by `rake woods:obsidian`. Safe to delete.\n")
       end
 
       def can_write_obsidian_config?
@@ -284,12 +316,19 @@ module Woods
         end
       end
 
+      # Every managed note in the vault, vault-relative.
+      #
+      # `base:` keeps the vault's own path out of the pattern: "[", "]", "{",
+      # "}", "*" and "?" in a folder name (`my [work] vault` is an ordinary
+      # human folder name) are glob syntax, and interpolating the path matched
+      # nothing — the sweep saw zero managed notes and deleted nothing,
+      # silently, forever (EXP-6).
+      #
+      # @return [Array<String>] paths relative to the vault root
       def managed_notes
-        Dir.glob(@vault.join('**', '*.md')).filter_map do |abs|
-          next unless managed_marker?(abs)
+        return [] unless @vault.directory?
 
-          Pathname.new(abs).relative_path_from(@vault).to_s
-        end
+        Dir.glob(File.join('**', '*.md'), base: @vault.to_s).select { |rel| managed_marker?(@vault.join(rel)) }
       end
 
       # Only our notes carry this frontmatter flag. Reads just the frontmatter
@@ -339,13 +378,41 @@ module Woods
       end
 
       def safe_inside_vault?(path)
-        root = @vault.realpath.to_s
-        target = path.exist? ? path.realpath.to_s : path.expand_path.to_s
+        root = canonical(@vault)
+        target = canonical(path)
         target == root || target.start_with?(root + File::SEPARATOR)
       rescue StandardError
         false
       end
 
+      # realpath requires the target to exist, but a write target (and, on the
+      # very first write of a fresh export, the vault root itself) usually
+      # doesn't yet. Resolve symlinks on the nearest existing ancestor only,
+      # then reattach the not-yet-created suffix literally. Both root and
+      # target must go through this same resolution — comparing a realpath'd
+      # root against an expand_path'd target falsely disagrees the moment an
+      # ancestor (e.g. macOS's /tmp -> /private/tmp) is itself a symlink.
+      def canonical(path)
+        existing = Pathname.new(path.to_s)
+        suffix = []
+        until existing.exist? || existing.root?
+          suffix.unshift(existing.basename.to_s)
+          existing = existing.dirname
+        end
+        base = existing.exist? ? existing.realpath.to_s : existing.to_s
+        suffix.empty? ? base : File.join(base, *suffix)
+      end
+
+      # The single write chokepoint: every AtomicFile.write in this class goes
+      # through here so a future regression upstream (a bad dir_for fallback,
+      # a mapper bug, a crafted rel path) fails closed with a typed error
+      # instead of writing outside the vault.
+      def safe_write(path, content)
+        raise PathTraversalError, "refusing to write outside the vault: #{path}" unless safe_inside_vault?(path)
+
+        AtomicFile.write(path, content)
+      end
+
       # ── Ownership ────────────────────────────────────────────────────
 
       def vault_owned_at_start?
@@ -363,12 +430,12 @@ module Woods
       # ── Helpers ──────────────────────────────────────────────────────
 
       def write_managed(written, rel, content)
-        AtomicFile.write(@vault.join(rel), content)
+        safe_write(@vault.join(rel), content)
         written << rel
       end
 
       def write_json(written, rel, data)
-        AtomicFile.write(@vault.join(rel), "#{JSON.pretty_generate(data)}\n")
+        safe_write(@vault.join(rel), "#{JSON.pretty_generate(data)}\n")
         written << rel
       end
 

data/lib/woods/operator/pipeline_guard.rb

@@ -19,6 +19,8 @@ module Woods
     #   end
     #
     class PipelineGuard
+      SUPPORTED_OPERATIONS = %w[extraction embedding].freeze
+
       # @param state_dir [String] Directory for persisting state
       # @param cooldown [Integer] Minimum seconds between runs
       def initialize(state_dir:, cooldown: 300)
@@ -29,13 +31,44 @@ module Woods
 
       # Check if an operation is allowed (cooldown elapsed).
       #
+      # Fails closed on state this process cannot trust: :missing is the
+      # legitimate "never run" case and allows, but :corrupt and
+      # :permission_denied used to be indistinguishable from :missing —
+      # both parsed to `{}` (or crashed uncaught) and let the operation
+      # through, silently defeating the cooldown on exactly the state that
+      # means it can no longer be verified.
+      #
       # @param operation [Symbol, String] Operation name
       # @return [Boolean]
       def allow?(operation)
-        last = last_run(operation)
-        return true if last.nil?
+        case state_status
+        when :corrupt, :permission_denied
+          false
+        else
+          last = last_run(operation)
+          return true if last.nil?
 
-        (Time.now - last) >= @cooldown
+          (Time.now - last) >= @cooldown
+        end
+      end
+
+      # Diagnose the on-disk cooldown state without side effects, distinguishing
+      # the three states {#allow?} used to collapse into one silent outcome —
+      # public callers (the MCP pipeline tools) need to tell a fresh install
+      # apart from a state file that needs operator attention.
+      #
+      # @return [Symbol] `:ok`, `:missing`, `:corrupt`, or `:permission_denied`
+      def state_status
+        return :missing unless File.exist?(@state_path)
+
+        parsed = JSON.parse(File.read(@state_path))
+        parsed.is_a?(Hash) ? :ok : :corrupt
+      rescue Errno::EACCES
+        :permission_denied
+      rescue JSON::ParserError
+        :corrupt
+      rescue Errno::ENOENT
+        :missing
       end
 
       # Record that an operation has just run.
@@ -43,23 +76,31 @@ module Woods
       # @param operation [Symbol, String] Operation name
       # @return [void]
       def record!(operation)
-        FileUtils.mkdir_p(@state_dir)
-        File.open(@state_path, File::RDWR | File::CREAT) do |f|
-          f.flock(File::LOCK_EX)
-          content = f.read
-          state = if content.empty?
-                    {}
-                  else
-                    begin
-                      JSON.parse(content)
-                    rescue StandardError
-                      {}
-                    end
-                  end
+        with_locked_state do |state|
           state[operation.to_s] = Time.now.iso8601
-          f.rewind
-          f.write(JSON.generate(state))
-          f.truncate(f.pos)
+          true
+        end
+        nil
+      end
+
+      # Reset one supported operation or all supported operations atomically.
+      #
+      # @param operation [Symbol, String] `:extraction`, `:embedding`, or `:all`
+      # @return [Boolean] true when at least one cooldown was removed
+      # @raise [ArgumentError] when the operation is unsupported
+      def reset!(operation)
+        operations = reset_operations(operation)
+        return false unless requested_state_present?(operations)
+
+        with_existing_locked_state do |state|
+          changed = false
+          operations.each do |key|
+            next unless state.key?(key)
+
+            state.delete(key)
+            changed = true
+          end
+          changed
         end
       end
 
@@ -79,12 +120,68 @@ module Woods
 
       private
 
+      def with_locked_state
+        FileUtils.mkdir_p(@state_dir)
+        File.open(@state_path, File::RDWR | File::CREAT) do |file|
+          file.flock(File::LOCK_EX)
+          state = parse_state(file.read)
+          changed = yield(state)
+          if changed
+            file.rewind
+            file.write(JSON.generate(state))
+            file.truncate(file.pos)
+          end
+          changed
+        end
+      end
+
+      def parse_state(content)
+        state = content.empty? ? {} : JSON.parse(content)
+        state.is_a?(Hash) ? state : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def requested_state_present?(operations)
+        File.open(@state_path, File::RDONLY) do |file|
+          file.flock(File::LOCK_SH)
+          state = parse_state(file.read)
+          operations.any? { |key| state.key?(key) }
+        end
+      rescue Errno::ENOENT
+        false
+      end
+
+      def with_existing_locked_state
+        File.open(@state_path, File::RDWR) do |file|
+          file.flock(File::LOCK_EX)
+          state = parse_state(file.read)
+          changed = yield(state)
+          if changed
+            file.rewind
+            file.write(JSON.generate(state))
+            file.truncate(file.pos)
+          end
+          changed
+        end
+      rescue Errno::ENOENT
+        false
+      end
+
+      def reset_operations(operation)
+        key = operation.to_s
+        return SUPPORTED_OPERATIONS if key == 'all'
+        return [key] if SUPPORTED_OPERATIONS.include?(key)
+
+        raise ArgumentError, "Unsupported pipeline operation: #{operation}"
+      end
+
       # @return [Hash]
       def read_state
         return {} unless File.exist?(@state_path)
 
-        JSON.parse(File.read(@state_path))
-      rescue JSON::ParserError
+        parse_state(File.read(@state_path))
+      rescue Errno::ENOENT, Errno::EACCES
         {}
       end
     end

data/lib/woods/operator/status_reporter.rb

@@ -3,6 +3,9 @@
 require 'json'
 require 'time'
 
+require_relative '../atomic_file'
+require_relative '../generation'
+
 module Woods
   module Operator
     # Reports pipeline status by reading extraction output metadata.
@@ -43,13 +46,27 @@ module Woods
 
       private
 
+      # Read manifest.json via AtomicFile.read (a bare File.read tags the bytes
+      # with the process's default external encoding — US-ASCII under LANG=C —
+      # so a non-ASCII branch name raised EncodingError out of JSON.parse). An
+      # unparseable or unreadable manifest degrades to nil, the same as a
+      # missing one: the report becomes :not_extracted rather than an error.
+      #
+      # Resolved through {Woods::Generation#payload_dir}: a payload-born
+      # index keeps +manifest.json+ only under the directory the published
+      # generation names, never at +@output_dir+ directly, so reading the
+      # root path unconditionally reported :not_extracted against a fresh
+      # extraction. Resolves to +@output_dir+ itself for a flat (pre-payload)
+      # index, so this is a no-op for every index that predates payloads.
+      #
       # @return [Hash, nil]
       def read_manifest
-        path = File.join(@output_dir, 'manifest.json')
+        generation = Woods::Generation.new(output_dir: @output_dir)
+        path = generation.payload_dir(generation.current).join('manifest.json')
         return nil unless File.exist?(path)
 
-        JSON.parse(File.read(path))
-      rescue JSON::ParserError
+        JSON.parse(AtomicFile.read(path))
+      rescue JSON::ParserError, EncodingError, SystemCallError
         nil
       end