woods 1.6.0 → 2.0.0.beta1

data/lib/woods/flow_precomputer.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'fileutils'
 require_relative 'filename_utils'
 require_relative 'flow_assembler'
+require_relative 'atomic_file'
 
 module Woods
   # Orchestrates pre-computation of request flow maps for all controller actions.
@@ -11,10 +12,20 @@ module Woods
   # After the dependency graph is built, FlowPrecomputer iterates controller units,
   # runs FlowAssembler for each action, and writes flow documents to disk.
   #
+  # All persisted path values — `flow_index.json` entries and each controller
+  # unit's `metadata[:flow_paths]` — are RELATIVE to the output dir
+  # (e.g. "flows/OrdersController_create.json"), matching the #166 portability
+  # contract: extraction inside a container must not bake `/app/...` prefixes
+  # into artifacts a host reads through a volume mount, and identical trees at
+  # different roots must produce identical bytes (which is also what keeps
+  # {#canonical_json}'s churn-avoidance honest). Readers join the relative
+  # value against their own index dir (see the MCP server's
+  # `load_precomputed_flow`).
+  #
   # @example
   #   precomputer = FlowPrecomputer.new(units: all_units, graph: dep_graph, output_dir: out)
   #   flow_map = precomputer.precompute
-  #   flow_map["OrdersController#create"] #=> "/tmp/woods/flows/OrdersController_create.json"
+  #   flow_map["OrdersController#create"] #=> "flows/OrdersController_create.json"
   #
   class FlowPrecomputer
     # Default maximum recursion depth for flow assembly
@@ -34,7 +45,15 @@ module Woods
 
     # Pre-compute flow documents for all controller actions.
     #
-    # @return [Hash{String => String}] Map of entry_point to flow file path
+    # Assembly is fail closed (M3 review round 3): a per-action failure
+    # raises instead of skipping the entry, so a partial index — missing
+    # entries alongside a freshly written graph — is never written and the
+    # caller aborts before publishing. The full extraction path shares this
+    # contract with the incremental delta.
+    #
+    # @return [Hash{String => String}] Map of entry_point to output_dir-relative
+    #   flow file path (e.g. "flows/OrdersController_create.json")
+    # @raise [Woods::ExtractionError] when any action fails to assemble
     def precompute
       FileUtils.mkdir_p(@flows_dir)
 
@@ -42,18 +61,8 @@ module Woods
       flow_map = {}
 
       controller_units.each do |unit|
-        actions = unit.metadata[:actions] || unit.metadata['actions'] || []
-        unit_flow_paths = {}
-
-        actions.each do |action|
-          entry_point = "#{unit.identifier}##{action}"
-          flow_path = assemble_and_write(assembler, entry_point, unit.identifier, action)
-          next unless flow_path
-
-          flow_map[entry_point] = flow_path
-          unit_flow_paths[action] = flow_path
-        end
-
+        entries, unit_flow_paths = assemble_controller_unit(assembler, unit)
+        flow_map.merge!(entries)
         unit.metadata[:flow_paths] = unit_flow_paths if unit_flow_paths.any?
       end
 
@@ -62,6 +71,53 @@ module Woods
       flow_map
     end
 
+    # Recompute the flow documents for the controllers an incremental run
+    # touched (M3), carrying every untouched controller's entries forward
+    # from the previous generation's flow_index.json — payload seeding
+    # hardlinks it into this run's payload directory — and rewriting the
+    # index with the merged result.
+    #
+    # Touched controllers replace their previous entries wholesale (a full
+    # run would emit exactly their current actions), so an action removed
+    # from a re-extracted controller leaves the index even though the file
+    # still exists. Controllers named in +removed_identifiers+ lost their
+    # unit this run (deleted or renamed) and leave the index entirely;
+    # {Woods::Extractor#sweep_orphaned_flow_files} then removes the
+    # documents nothing references anymore.
+    #
+    # @param touched_units [Array<ExtractedUnit>] the run's re-extracted
+    #   controller units, rehydrated from the payload this run seeded
+    # @param removed_identifiers [Array<String>] controller identifiers
+    #   whose unit the run pruned
+    # @return [Hash{String => Hash{String => String}}] per-controller
+    #   annotation (action => relative flow path) to write into the units'
+    #   metadata; an empty hash means "no flows", which clears any
+    #   annotation a previous run had written
+    def recompute_delta(touched_units:, removed_identifiers: [])
+      FileUtils.mkdir_p(@flows_dir)
+
+      assembler = FlowAssembler.new(graph: @graph, extracted_dir: @output_dir)
+      delta = {}
+      annotations = {}
+
+      touched_units.each do |unit|
+        # A per-action skip would publish an index missing that entry, so
+        # assembly raises. The incremental path must not advance publication
+        # over a broken assembly; the caller aborts before the generation
+        # bump.
+        entries, unit_flow_paths = assemble_controller_unit(assembler, unit)
+        annotations[unit.identifier] = unit_flow_paths
+        delta.merge!(entries)
+      end
+
+      replaced = touched_units.map(&:identifier) + Array(removed_identifiers)
+      carried = previous_flow_index.reject { |entry_point, _path| replaced.include?(controller_of(entry_point)) }
+
+      write_flow_index(carried.merge(delta))
+
+      annotations
+    end
+
     private
 
     # Filter units to only controllers.
@@ -71,33 +127,93 @@ module Woods
       @units.select { |u| u.type.to_s == 'controller' }
     end
 
+    # Assemble and write every flow for one controller unit.
+    #
+    # Both entry points fail closed: a per-action failure aborts the run
+    # rather than publishing a flow index missing that entry (EXTB-14 — the
+    # old `fail_closed:` switch documented a log-and-skip contract for the
+    # full path that no caller ever asked for).
+    #
+    # @param assembler [FlowAssembler]
+    # @param unit [ExtractedUnit]
+    # @return [Array(Hash{String => String}, Hash{String => String})] the
+    #   entry_point => relative-path entries for the flow index, and the
+    #   action => relative-path annotation for the unit's metadata
+    # @raise [Woods::ExtractionError] when an action fails to assemble
+    def assemble_controller_unit(assembler, unit)
+      entries = {}
+      unit_flow_paths = {}
+
+      actions = unit.metadata[:actions] || unit.metadata['actions'] || []
+      actions.each do |action|
+        entry_point = "#{unit.identifier}##{action}"
+        flow_path = assemble_and_write(assembler, entry_point, unit.identifier, action)
+
+        entries[entry_point] = flow_path
+        unit_flow_paths[action] = flow_path
+      end
+
+      [entries, unit_flow_paths]
+    end
+
+    # The controller part of a flow index entry point.
+    #
+    # @param entry_point [String]
+    # @return [String]
+    def controller_of(entry_point)
+      entry_point.to_s.split('#', 2).first
+    end
+
+    # The previous generation's flow index, or an empty hash when none was
+    # published. A missing index means there is nothing to carry forward
+    # (the caller established whether the family is genuinely absent); a
+    # corrupt one raises — publication must not advance over unreadable
+    # prior flow state.
+    #
+    # @return [Hash{String => String}]
+    # @raise [Woods::ExtractionError] when the index does not parse
+    def previous_flow_index
+      path = File.join(@flows_dir, 'flow_index.json')
+      return {} unless File.exist?(path)
+
+      JSON.parse(Woods::AtomicFile.read(path))
+    rescue JSON::ParserError => e
+      raise Woods::ExtractionError, "previous flow_index.json does not parse: #{e.message}"
+    end
+
     # Assemble a flow for one entry point and write the JSON file.
     #
+    # Written via {Woods::AtomicFile} (temp + fsync + rename) like every
+    # other index artifact — a plain +File.write+ interrupted mid-write left
+    # a torn partial for the MCP read side to trip over.
+    #
     # @param assembler [FlowAssembler]
     # @param entry_point [String]
     # @param controller_id [String]
     # @param action [String]
-    # @return [String, nil] The written file path, or nil on failure
+    # @return [String] The output_dir-relative path of the written file
+    #   (e.g. "flows/OrdersController_create.json")
+    # @raise [Woods::ExtractionError] when assembly or the write fails
     def assemble_and_write(assembler, entry_point, controller_id, action)
       flow = assembler.assemble(entry_point, max_depth: @max_depth)
 
       filename = Woods::FilenameUtils.flow_filename(controller_id, action)
-      flow_path = File.join(@flows_dir, filename)
 
-      File.write(flow_path, canonical_json(flow.to_h))
+      Woods::AtomicFile.write(File.join(@flows_dir, filename), canonical_json(flow.to_h))
 
-      flow_path
+      # Relative — this value is persisted (flow_index.json and the unit's
+      # metadata[:flow_paths]), so it must not carry this machine's root.
+      File.join('flows', filename)
     rescue StandardError => e
-      Rails.logger.error("[Woods] Flow precompute failed for #{entry_point}: #{e.message}")
-      nil
+      raise Woods::ExtractionError, "flow precompute failed for #{entry_point}: #{e.message}"
     end
 
-    # Write the flow index mapping entry points to file paths.
+    # Write the flow index mapping entry points to output_dir-relative file paths.
     #
     # @param flow_map [Hash{String => String}]
     def write_flow_index(flow_map)
       index_path = File.join(@flows_dir, 'flow_index.json')
-      File.write(index_path, canonical_json(flow_map))
+      Woods::AtomicFile.write(index_path, canonical_json(flow_map))
     end
 
     # Emit deterministic pretty JSON — keys recursively sorted so two runs

data/lib/woods/gem_mapper.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'time'
+
+require_relative 'atomic_file'
+require_relative 'coordination/pipeline_lock'
+require_relative 'dependency_graph'
+require_relative 'extracted_unit'
+require_relative 'filename_utils'
+require_relative 'generation'
+require_relative 'graph_analyzer'
+require_relative 'payload_store'
+require_relative 'ruby_analyzer'
+
+module Woods
+  # Publishes a static, source-only index of the Woods implementation.
+  class GemMapper
+    include FilenameUtils
+
+    SOURCE_GLOBS = %w[lib/woods.rb lib/woods/**/*.rb lib/tasks/**/*.rake exe/*].freeze
+    TYPE_DIRECTORIES = {
+      ruby_class: 'ruby_classes', ruby_module: 'ruby_modules',
+      ruby_method: 'ruby_methods', ruby_file: 'ruby_files'
+    }.freeze
+    PROVENANCE = {
+      mode: 'woods_static_ruby_source', runtime_fidelity: 'none', embeddings: 'absent',
+      included: SOURCE_GLOBS, excluded: %w[spec docs .git tmp vendor]
+    }.freeze
+
+    def initialize(root:, output_dir:)
+      @root = Pathname.new(root).expand_path
+      @output_dir = Pathname.new(output_dir).expand_path
+    end
+
+    # Publishes one complete source snapshot, or skips when it is unchanged.
+    def map!
+      with_lock do
+        snapshot = source_snapshot
+        return { status: :skipped, generation: current_generation.number } if current_checksum == snapshot[:checksum]
+
+        units, graph = GemMapSource.new(root: @root).build(snapshot[:sources])
+        payload = create_payload
+        GemMapPublisher.new(payload: payload, units: units, graph: graph, checksum: snapshot[:checksum]).write
+        ensure_snapshot_unchanged!(snapshot[:checksum])
+        marker = publish_generation
+        { status: :published, generation: marker.number, units: units.size }
+      end
+    end
+
+    private
+
+    def with_lock(&block)
+      Coordination::PipelineLock.new(lock_dir: @output_dir.to_s, name: 'woods_self_map').with_lock(&block)
+    end
+
+    def source_files
+      SOURCE_GLOBS.flat_map { |glob| Dir.glob(@root.join(glob).to_s) }
+                  .select { |path| File.file?(path) }.uniq.sort
+    end
+
+    def source_snapshot
+      sources = source_files.to_h { |path| [path, read_source(path)] }
+      { sources: sources, checksum: checksum_for(sources) }
+    end
+
+    def checksum_for(sources)
+      digest = Digest::SHA256.new
+      sources.sort.each { |path, source| digest << relative_path(path) << "\0" << source << "\0" }
+      digest.hexdigest
+    end
+
+    def read_source(path)
+      source = File.read(path, encoding: Encoding::UTF_8)
+      source.valid_encoding? ? source : source.scrub
+    end
+
+    def ensure_snapshot_unchanged!(checksum)
+      return if source_snapshot[:checksum] == checksum
+
+      raise Woods::ExtractionError, 'Woods source changed during self-map; refusing to publish a mixed snapshot'
+    end
+
+    def current_generation
+      Generation.new(output_dir: @output_dir).current
+    end
+
+    def next_generation
+      current_generation.number + 1
+    end
+
+    def current_checksum
+      payload = Generation.new(output_dir: @output_dir).payload_dir(current_generation)
+      manifest = payload.join('manifest.json')
+      return nil unless manifest.file?
+
+      JSON.parse(AtomicFile.read(manifest)).dig('provenance', 'source_checksum')
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def relative_path(path)
+      Pathname.new(path).expand_path.relative_path_from(@root).to_s
+    rescue ArgumentError
+      raise Woods::ExtractionError, "Source path escapes gem root: #{path}"
+    end
+
+    def create_payload
+      PayloadStore.new(@output_dir).create(next_generation)
+    end
+
+    def publish_generation
+      marker = Generation.new(output_dir: @output_dir).bump!(
+        reason: 'woods_static_source_map', payload: PayloadStore.name_for(next_generation)
+      )
+      PayloadStore.new(@output_dir).prune(keep: PayloadStore::DEFAULT_RETENTION, protect: marker.number)
+      marker
+    end
+  end
+
+  # Turns a pre-read Woods source snapshot into typed static analysis units.
+  class GemMapSource
+    def initialize(root:)
+      @root = root
+    end
+
+    def build(sources)
+      units = build_units(sources)
+      graph = DependencyGraph.new
+      units.each { |unit| graph.register(unit) }
+      [units, graph]
+    end
+
+    private
+
+    def build_units(sources)
+      analyzable = sources.select { |path, _| path.end_with?('.rb', '.rake') || executable?(path) }
+      units = RubyAnalyzer.analyze(sources: analyzable)
+      units.each { |unit| unit.file_path = relative_path(unit.file_path) }
+      units.concat(file_units(sources))
+      disambiguate!(units)
+      qualify_dependencies(units)
+      resolve_dependents(units)
+      units.sort_by { |unit| [unit.identifier, unit.type.to_s, unit.file_path] }
+    end
+
+    def executable?(path)
+      path.start_with?(@root.join('exe').to_s + File::SEPARATOR)
+    end
+
+    def file_units(sources)
+      sources.map do |path, source|
+        relative = relative_path(path)
+        unit = ExtractedUnit.new(type: :ruby_file, identifier: "file:#{relative}", file_path: relative)
+        unit.source_code = source
+        unit.metadata = { static_kind: 'ruby_file', executable: executable?(path) }
+        unit
+      end
+    end
+
+    def disambiguate!(units)
+      units.group_by(&:identifier).each do |canonical, colliding|
+        colliding.sort_by! { |unit| [unit.file_path, unit.type.to_s] }
+        colliding.each_with_index do |unit, index|
+          unit.metadata[:canonical_identifier] = canonical
+          next if index.zero?
+
+          unit.identifier = "#{canonical} [#{unit.file_path}]"
+          unit.dependencies << { type: unit.type, target: canonical, via: :definition_of }
+        end
+      end
+    end
+
+    # Resolve only known lexical definitions, retaining external/dynamic names as written.
+    def qualify_dependencies(units)
+      definitions = units.select { |unit| %i[ruby_class ruby_module].include?(unit.type) }.to_h do |unit|
+        [unit.metadata[:canonical_identifier] || unit.identifier, unit]
+      end
+      units.each do |unit|
+        unit.dependencies.each { |dependency| qualify_dependency(unit, dependency, definitions) }
+      end
+    end
+
+    def qualify_dependency(unit, dependency, definitions)
+      target = dependency[:target]
+      return unless target.is_a?(String)
+
+      scopes = Array(unit.metadata[:lexical_scopes])
+      scopes = scopes.drop(1) if dependency[:via] == :inheritance
+      candidates = if target.start_with?('::')
+                     [target.delete_prefix('::')]
+                   else
+                     scopes.map { |scope| "#{scope}::#{target}" } + [target]
+                   end
+      resolved = candidates.find { |candidate| definitions.key?(candidate) }
+      return unless resolved
+
+      dependency[:target] = resolved
+      dependency[:type] = definitions[resolved].type
+    end
+
+    def resolve_dependents(units)
+      by_identifier = units.group_by(&:identifier)
+      units.each do |unit|
+        unit.dependencies.each do |dependency|
+          Array(by_identifier[dependency[:target]]).each do |target|
+            target.dependents << { type: unit.type, identifier: unit.identifier }
+          end
+        end
+      end
+    end
+
+    def relative_path(path)
+      Pathname.new(path).expand_path.relative_path_from(@root).to_s
+    rescue ArgumentError
+      raise Woods::ExtractionError, "Source path escapes gem root: #{path}"
+    end
+  end
+
+  # Writes a complete source-map payload before GemMapper atomically publishes it.
+  class GemMapPublisher
+    include FilenameUtils
+
+    def initialize(payload:, units:, graph:, checksum:)
+      @payload = payload
+      @units = units
+      @graph = graph
+      @checksum = checksum
+    end
+
+    def write
+      GemMapper::TYPE_DIRECTORIES.each do |type, directory|
+        write_type(@payload.join(directory), @units.select { |unit| unit.type == type })
+      end
+      write_graph
+      write_manifest
+      write_summary
+    end
+
+    private
+
+    def write_type(directory, units)
+      FileUtils.mkdir_p(directory)
+      units.each do |unit|
+        AtomicFile.write(directory.join(collision_safe_filename(unit.identifier)), JSON.pretty_generate(unit.to_h))
+      end
+      index = units.map do |unit|
+        { identifier: unit.identifier, file_path: unit.file_path, namespace: unit.namespace,
+          estimated_tokens: unit.estimated_tokens, chunk_count: unit.chunks.size }
+      end
+      AtomicFile.write(directory.join('_index.json'), JSON.pretty_generate(index))
+    end
+
+    def write_graph
+      data = @graph.to_h
+      data[:pagerank] = @graph.pagerank
+      AtomicFile.write(@payload.join('dependency_graph.json'), JSON.pretty_generate(data))
+      AtomicFile.write(@payload.join('graph_analysis.json'), JSON.pretty_generate(GraphAnalyzer.new(@graph).analyze))
+    end
+
+    def write_manifest
+      counts = GemMapper::TYPE_DIRECTORIES.keys.to_h do |type|
+        [GemMapper::TYPE_DIRECTORIES[type], @units.count { |unit| unit.type == type }]
+      end
+      manifest = {
+        extracted_at: Time.now.utc.iso8601, rails_version: nil, ruby_version: RUBY_VERSION,
+        counts: counts, total_units: @units.size, total_chunks: 0, git_sha: nil, git_branch: nil,
+        provenance: GemMapper::PROVENANCE.merge(source_checksum: @checksum),
+        graph_nodes: @graph.to_h.dig(:stats, :node_count), graph_edges: @graph.to_h.dig(:stats, :edge_count)
+      }
+      AtomicFile.write(@payload.join('manifest.json'), JSON.pretty_generate(manifest))
+    end
+
+    def write_summary
+      stats = @graph.to_h.fetch(:stats)
+      AtomicFile.write(@payload.join('SUMMARY.md'), [
+        '# Woods static Ruby source map', '', "Units: #{@units.size}", "Graph nodes: #{stats[:node_count]}",
+        "Graph edges: #{stats[:edge_count]}", 'Static source analysis only; not a Rails runtime extraction.'
+      ].join("\n"))
+    end
+  end
+end

data/lib/woods/generation.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'pathname'
+require 'digest'
+require 'securerandom'
+
+require_relative 'atomic_file'
+
+module Woods
+  # A monotonic marker for "which version of the index is on disk".
+  #
+  # The index is a directory of files, so a reader has no cheap way to ask
+  # "has this changed since I cached it?" — it would have to stat everything.
+  # This is that cheap way: one small file, bumped as the *last* step of any
+  # write, holding a counter that only ever increases plus a token that
+  # changes whenever the counter does.
+  #
+  # Two properties matter, and both come from #164's central rule — never
+  # advance a cursor over work that didn't land:
+  #
+  # * **Bumped last.** Callers write the index, then bump. A reader that sees
+  #   generation N therefore knows the files for N are already there.
+  # * **Not bumped on failure.** A run that raised, or that changed nothing,
+  #   leaves the generation alone. Staleness is then honest: the reader keeps
+  #   serving N and knows it.
+  #
+  # The write itself is atomic ({AtomicFile}), so a reader never sees a torn
+  # generation file. It can also carry a **payload pointer** — the name of an
+  # immutable per-generation directory the payload was published into. When
+  # present, the single atomic write of this file is the one commit point for
+  # the whole payload: a reader resolves every artifact of a read through the
+  # directory this generation names, so it sees one generation whole rather
+  # than a mix of a manifest from N+1 next to a unit from N. The pointer is
+  # optional — an index written flat (payload files directly under the output
+  # directory) carries none, and readers fall back to the output directory.
+  #
+  # @example Publishing after a successful write
+  #   Woods::Generation.new(output_dir: "tmp/woods").bump!(reason: "incremental")
+  #   # => #<Generation::Marker number=42 token="9f2c…" reason="incremental">
+  #
+  class Generation
+    FILENAME = 'generation.json'
+
+    # An immutable snapshot of the generation file.
+    #
+    # @!attribute number
+    #   @return [Integer] monotonically increasing, starting at 1
+    # @!attribute token
+    #   @return [String] opaque; changes on every bump
+    # @!attribute updated_at
+    #   @return [String, nil] ISO8601 stamp of the bump
+    # @!attribute reason
+    #   @return [String, nil] what produced this generation
+    # @!attribute payload
+    #   @return [String, nil] name of the immutable directory this generation's
+    #     payload lives in, relative to the output directory. nil for an index
+    #     written flat (payload files directly under the output directory).
+    Marker = Struct.new(:number, :token, :updated_at, :reason, :payload, keyword_init: true) do
+      # @return [Hash] string-keyed, ready to serialize. The +payload+ key is
+      #   emitted only when set, so a flat index's generation file is byte-for-
+      #   byte what it always was.
+      def to_h
+        base = { 'number' => number, 'token' => token, 'updated_at' => updated_at, 'reason' => reason }
+        base['payload'] = payload if payload
+        base
+      end
+    end
+
+    # Marker returned when no generation file exists yet — an index written
+    # before generations existed, or a directory nothing has published to.
+    UNPUBLISHED = Marker.new(number: 0, token: nil, updated_at: nil, reason: nil).freeze
+
+    # @param output_dir [String, Pathname] index directory
+    # @param clock [#call] returns the ISO8601 stamp for a bump; injectable
+    #   so specs don't depend on wall-clock time
+    def initialize(output_dir:, clock: -> { Time.now.utc.iso8601 })
+      @path = File.join(output_dir.to_s, FILENAME)
+      @clock = clock
+    end
+
+    # @return [String] absolute path to the generation file
+    attr_reader :path
+
+    # The generation currently published.
+    #
+    # A missing or unreadable file reads as {UNPUBLISHED} rather than raising:
+    # a reader asking "what generation is this?" of a directory that has none
+    # wants an answer, not an exception.
+    #
+    # @return [Marker]
+    def current
+      return UNPUBLISHED unless File.exist?(@path)
+
+      data = JSON.parse(AtomicFile.read(@path))
+      Marker.new(
+        number: data['number'].to_i,
+        token: data['token'],
+        updated_at: data['updated_at'],
+        reason: data['reason'],
+        payload: data['payload']
+      )
+    rescue JSON::ParserError, SystemCallError
+      UNPUBLISHED
+    end
+
+    # Advance to the next generation.
+    #
+    # Call this *after* the index files are written, never before, and never
+    # after a run that failed or wrote nothing.
+    #
+    # @param reason [String, nil] what produced this generation, for humans
+    #   reading `woods_status`
+    # @param payload [String, nil] name of the immutable directory this
+    #   generation's payload was published into, relative to the output
+    #   directory. Omit for a flat index; when given, this bump becomes the
+    #   single commit point for that whole payload (see the class docs).
+    # @return [Marker] the newly published generation
+    def bump!(reason: nil, payload: nil)
+      marker = Marker.new(
+        number: current.number + 1,
+        token: SecureRandom.hex(8),
+        updated_at: @clock.call,
+        reason: reason,
+        payload: payload
+      )
+      AtomicFile.write(@path, JSON.generate(marker.to_h))
+      marker
+    end
+
+    # The directory a generation's payload artifacts live in.
+    #
+    # Returns the index root when there is no pointer (an index written flat,
+    # which is every index written before payloads existed), when the named
+    # directory is gone (a stale pointer — a payload retention pruned), or
+    # when the name would escape the index root. A torn or tampered pointer
+    # must degrade to the flat layout, never read outside the index; the name
+    # is written by Woods and is relative by contract.
+    #
+    # Every reader of a payload artifact resolves through this, so the pointer
+    # is followed identically wherever it is read.
+    #
+    # @param marker [Marker] the generation to resolve; defaults to the
+    #   published one. Pass an already-loaded marker to avoid re-reading, and
+    #   to resolve a generation a caller has pinned rather than the current one.
+    # @return [Pathname]
+    def payload_dir(marker = current)
+      name = marker.payload
+      return root if name.nil? || name.empty?
+
+      candidate = root.join(name)
+      return root unless candidate.directory?
+      return root unless within_root?(candidate)
+
+      candidate
+    end
+
+    # @return [Pathname] the index directory this generation lives in
+    def root
+      @root ||= Pathname.new(File.dirname(@path))
+    end
+
+    private
+
+    # Does +candidate+ resolve inside the index root?
+    #
+    # Compared through +realpath+, mirroring
+    # {Woods::IndexArtifact#validate_dump_dir!} (B-134). +expand_path+ is
+    # textual, so a symlink planted *inside* +payloads/+ and pointing outside
+    # the index passed the check while +Pathname#directory?+ happily followed
+    # it — aiming every payload reader at an arbitrary directory (CORE-6). An
+    # index reached through a symlinked root still resolves, because both
+    # sides go through realpath.
+    #
+    # @param candidate [Pathname] an existing directory
+    # @return [Boolean] false when it cannot be resolved at all
+    def within_root?(candidate)
+      candidate_real = candidate.realpath.to_s
+      root_real = root.realpath.to_s
+      candidate_real.start_with?("#{root_real}#{File::SEPARATOR}")
+    rescue SystemCallError
+      false
+    end
+  end
+end