woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/mcp/traversal_evidence.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'traversal_evidence_index'
+require_relative 'traversal_evidence_page'
+
+module Woods
+  module MCP
+    # Per-query identifier-level BFS with truthful typed records and a shared
+    # predecessor forest. Ambiguous endpoints never become a claimed typed path.
+    class TraversalEvidence
+      class Budget
+        attr_reader :data
+
+        def initialize(max_nodes, max_edges)
+          @data = { max_nodes: max_nodes.to_i.clamp(1, 10_000), max_edges: max_edges.to_i.clamp(1, 100_000),
+                    visited_nodes: 1, visited_edges: 0 }
+        end
+
+        def consume_node
+          throw :traversal_budget, 'node_budget' if data[:visited_nodes] >= data[:max_nodes]
+
+          data[:visited_nodes] += 1
+        end
+
+        def consume_edge
+          throw :traversal_budget, 'edge_budget' if data[:visited_edges] >= data[:max_edges]
+
+          data[:visited_edges] += 1
+        end
+      end
+
+      def initialize(index)
+        @index = index
+      end
+
+      def call(identifier, depth: 2, direction: :forward, types: nil, via: nil, max_nodes: 1000, max_edges: 10_000)
+        return { root: identifier, found: false, nodes: {} } unless @index.include?(identifier)
+
+        prepare(identifier, depth, direction, types, via, max_nodes, max_edges)
+        cursor = 0
+        while cursor < @queue.size
+          current, level = @queue[cursor]
+          cursor += 1
+          entry = @index.node(current, level)
+          @nodes[current] = entry
+          next if @partial_reason || level >= @depth
+
+          @partial_reason = catch(:traversal_budget) do
+            @index.each_edge(current, @direction, @budget) { |edge| visit(current, level, entry, edge) }
+            nil
+          end
+        end
+        response(identifier)
+      end
+
+      private
+
+      def prepare(identifier, depth, direction, types, via, max_nodes, max_edges)
+        @depth = depth
+        @direction = direction
+        @types = types&.to_set
+        @via = via&.to_set
+        @budget = Budget.new(max_nodes, max_edges)
+        @queue = [[identifier, 0]]
+        @nodes = {}
+        @neighbors = Hash.new { |hash, key| hash[key] = Set.new }
+        @edges = {}
+        @edge_ids = {}
+        @partial_reason = nil
+        @witnesses = { identifier => { parent: nil, edge_id: nil, impact: 'root',
+                                       typed_path_complete: @index.types(identifier).size == 1 } }
+      end
+
+      def visit(current, level, entry, edge)
+        return if @via && !@via.include?(edge[:via])
+
+        neighbor = edge.fetch(@direction == :forward ? :target : :source).fetch(:identifier)
+        return if @types && @index.types(neighbor).none? { |type| @types.include?(type) }
+
+        unless @witnesses.key?(neighbor)
+          @budget.consume_node
+          @queue << [neighbor, level + 1]
+          @witnesses[neighbor] = witness(current, level, edge)
+        end
+        edge_id(edge)
+        entry[:deps] << neighbor if @neighbors[current].add?(neighbor)
+      end
+
+      def witness(current, level, edge)
+        complete = @witnesses.fetch(current)[:typed_path_complete] && !edge[:target][:type].nil? &&
+                   @index.types(edge[:source][:identifier]).size == 1
+        { parent: current, edge_id: edge_id(edge), impact: level.zero? ? 'direct' : 'transitive',
+          typed_path_complete: complete }
+      end
+
+      def edge_id(edge)
+        @edge_ids[edge] ||= begin
+          id = "e#{@edges.size}"
+          @edges[id] = edge
+          id
+        end
+      end
+
+      def response(identifier)
+        result = { root: identifier, found: true, nodes: @nodes,
+                   explanation: { direction: @direction.to_s, root: @index.identity(identifier),
+                                  edges: @edges, witnesses: @witnesses } }
+        result.merge!(partial: true, partial_reason: @partial_reason, traversal_budget: @budget.data) if @partial_reason
+        result
+      end
+    end
+  end
+end

data/lib/woods/mcp/traversal_evidence_index.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Woods
+  module MCP
+    # A generation-scoped view retaining typed edge ownership. Only node/variant
+    # indexes are prepared eagerly; relationship arrays remain lazy and every
+    # examined relationship consumes the caller's work budget.
+    class TraversalEvidenceIndex
+      ATTRIBUTES = %w[via through through_db disable_joins].freeze
+
+      def initialize(graph)
+        @graph = graph
+        @nodes = graph.fetch('nodes', {})
+        @variants = Array(graph['variants']).group_by { |record| record['identifier'] }
+        @types = @nodes.transform_values { |node| [node['type']].compact }
+        @variants.each do |identifier, records|
+          @types[identifier] = ((@types[identifier] || []) + records.map { |record| record['type'] }).compact.uniq.sort
+        end
+        @types.transform_values!(&:freeze).freeze
+        @multi_database = @nodes.values.filter_map { |node| node['database'] }.uniq.size > 1
+      end
+
+      def include?(identifier)
+        @nodes.key?(identifier)
+      end
+
+      def types(identifier)
+        @types.fetch(identifier, [])
+      end
+
+      def identity(identifier)
+        candidates = types(identifier)
+        return { identifier: identifier, type: candidates.first } if candidates.size == 1
+
+        { identifier: identifier, type: nil, candidate_types: candidates,
+          resolution: candidates.empty? ? 'unresolved' : 'ambiguous' }
+      end
+
+      def node(identifier, depth)
+        metadata = @nodes[identifier]
+        result = { type: metadata&.dig('type'), depth: depth, deps: [] }
+        result[:types] = types(identifier) if types(identifier).size > 1
+        result[:database] = metadata&.dig('database') if @multi_database
+        result
+      end
+
+      def each_edge(identifier, direction, budget, &block)
+        if direction == :forward
+          each_forward(identifier, budget, &block)
+        elsif @graph.key?('reverse_via')
+          each_reverse_record(identifier, budget, &block)
+        else
+          each_legacy_reverse(identifier, budget, &block)
+        end
+      end
+
+      private
+
+      def each_forward(identifier, budget, &block)
+        primary = @nodes[identifier]
+        each_owned_edge(identifier, primary && primary['type'], @graph.fetch('edges', {})[identifier], budget, &block)
+        (@variants[identifier] || []).each do |record|
+          each_owned_edge(identifier, record['type'], record['edges'], budget, &block)
+        end
+      end
+
+      def each_owned_edge(identifier, type, edges, budget)
+        (edges || []).each do |stored|
+          budget.consume_edge
+          stored = { 'target' => stored } unless stored.is_a?(Hash)
+          yield record(identifier, type, stored.fetch('target'), stored)
+        end
+      end
+
+      def each_reverse_record(identifier, budget)
+        (@graph.fetch('reverse_via')[identifier] || []).each do |stored|
+          budget.consume_edge
+          yield record(stored.fetch('source'), stored.fetch('source_type'), identifier, stored)
+        end
+      end
+
+      def each_legacy_reverse(identifier, budget)
+        (@graph.fetch('reverse', {})[identifier] || []).each do |source|
+          budget.consume_edge
+          each_forward(source, budget) do |edge|
+            yield edge if edge[:target][:identifier] == identifier
+          end
+        end
+      end
+
+      def record(source, type, target, stored)
+        result = { source: { identifier: source, type: type }, target: identity(target) }
+        ATTRIBUTES.each { |attribute| result[attribute.to_sym] = stored[attribute] }
+        result
+      end
+    end
+  end
+end

data/lib/woods/mcp/traversal_evidence_page.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Woods
+  module MCP
+    # Retain the paged rows' ancestors once, together with their witness edges
+    # and other recorded relationships between visible/context endpoints.
+    module TraversalEvidencePage
+      def self.apply(result)
+        explanation = result[:explanation]
+        return result unless explanation
+
+        visible = result.fetch(:nodes).keys.to_set
+        witnesses = explanation.fetch(:witnesses)
+        needed = ancestors(visible, witnesses)
+        page_witnesses = witnesses.slice(*(witnesses.keys & needed.to_a))
+        witness_edges = page_witnesses.values.map { |witness| witness[:edge_id] }.compact.to_set
+        edges = explanation.fetch(:edges).select do |id, edge|
+          source = edge[:source][:identifier]
+          target = edge[:target][:identifier]
+          witness_edges.include?(id) ||
+            (needed.include?(source) && needed.include?(target) && (visible.include?(source) || visible.include?(target)))
+        end
+        result[:explanation] = explanation.merge(edges: edges, witnesses: page_witnesses.to_h do |identifier, witness|
+          [identifier, witness.merge(context: !visible.include?(identifier))]
+        end)
+        result
+      end
+
+      def self.ancestors(visible, witnesses)
+        needed = Set.new
+        visible.each do |identifier|
+          identifier = witnesses.fetch(identifier)[:parent] while identifier && needed.add?(identifier)
+        end
+        needed
+      end
+      private_class_method :ancestors
+    end
+  end
+end

data/lib/woods/mcp/traversal_evidence_text.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Woods
+  module MCP
+    # Equivalent evidence for all text renderers; JSON retains the same records.
+    module TraversalEvidenceText
+      def self.lines(explanation)
+        return [] unless explanation
+
+        lines = ['', "Recorded relationships (original source -> target; traversal: #{value(explanation, :direction)}):",
+                 "Root identity: #{identity(value(explanation, :root))}"]
+        value(explanation, :edges).each do |id, edge|
+          attributes = TraversalEvidenceIndex::ATTRIBUTES.map do |attribute|
+            stored = value(edge, attribute)
+            "#{attribute}=#{stored.nil? ? 'unknown' : stored}"
+          end
+          lines << "#{id}: #{identity(value(edge, :source))} -> #{identity(value(edge, :target))}; #{attributes.join('; ')}"
+        end
+        lines << 'Witnesses: direct = recorded root relationship; transitive = inferred reachability, not observed execution.'
+        value(explanation, :witnesses).each do |identifier, witness|
+          lines << witness_line(identifier, witness)
+        end
+        lines
+      end
+
+      def self.identity(endpoint)
+        type = value(endpoint, :type)
+        label = if type
+                  type
+                else
+                  candidates = value(endpoint, :candidate_types) || []
+                  "#{value(endpoint, :resolution)}; candidate types: #{candidates.empty? ? 'none' : candidates.join(', ')}"
+                end
+        "#{value(endpoint, :identifier)} (#{label})"
+      end
+
+      def self.witness_line(identifier, witness)
+        parent = value(witness, :parent) || 'none'
+        edge = value(witness, :edge_id) || 'none'
+        complete = value(witness, :typed_path_complete) ? 'yes' : 'no'
+        context = value(witness, :context) ? 'yes' : 'no'
+        "#{identifier}: #{value(witness, :impact)}; parent=#{parent}; edge=#{edge}; " \
+          "witness types unambiguous=#{complete}; context only=#{context}"
+      end
+
+      def self.value(hash, key)
+        hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key.to_s]
+      end
+      private_class_method :identity, :witness_line, :value
+    end
+  end
+end

data/lib/woods/mcp/traversal_response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Woods
+  module MCP
+    # Response scope is independent of traversal evidence and page selection.
+    module TraversalResponse
+      COVERAGE = {
+        scope: 'published_relationships',
+        source_references: 'not_exhaustive',
+        notice: 'Graph coverage: published relationships only. Arbitrary method-body constant references ' \
+                'are not exhaustively captured; missing relationships do not prove no callers or dependencies.'
+      }.freeze
+
+      def self.annotate(result)
+        return if result[:found] == false
+
+        result[:graph_coverage] = COVERAGE
+        result[:total_is_exact] = !result[:partial]
+      end
+    end
+  end
+end

data/lib/woods/notion/exporter.rb

@@ -8,6 +8,7 @@ require_relative 'mappers/column_mapper'
 require_relative 'mappers/migration_mapper'
 require_relative 'rate_limiter'
 require_relative 'sync_manifest'
+require_relative '../export/typed_reader'
 
 module Woods
   module Notion
@@ -83,6 +84,7 @@ module Woods
         @database_ids = config.notion_database_ids || {}
         @client = client || Client.new(api_token: api_token)
         @reader = reader || build_reader(index_dir)
+        @typed_reader = Export::TypedReader.new(@reader)
         @manifest = manifest || build_manifest(index_dir)
         @force_full = force_full.nil? ? env_force? : force_full
         @page_id_cache = {}
@@ -94,7 +96,7 @@ module Woods
       # @return [Hash] { data_models: Integer, columns: Integer,
       #   skipped: Integer, errors: Array<String> }
       def sync_all
-        with_pinned_index do
+        with_prepared_index do
           model_stats = @database_ids[:data_models] ? sync_data_models : empty_stats
           warn_columns_without_data_models if @database_ids[:columns] && !@database_ids[:data_models]
           column_stats = @database_ids[:columns] ? sync_columns : empty_stats
@@ -124,12 +126,20 @@ module Woods
       #
       # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
       def sync_data_models
+        return empty_stats unless @database_ids[:data_models]
+
+        with_prepared_index(%w[model migration]) { sync_data_models_prepared }
+      end
+
+      def sync_data_models_prepared
         database_id = @database_ids[:data_models]
         return empty_stats unless database_id
 
+        prepared = false
         begin
           migration_dates = load_migration_dates
           shared_tables = shared_table_names
+          prepared = true
           stats = sync_units('model', database_id, 'Table Name', SCOPE_DATA_MODELS) do |unit_data|
             properties = Mappers::ModelMapper.new.map(unit_data)
             # Enrichment reads the bare table name from the title — run it
@@ -141,9 +151,10 @@ module Woods
           @manifest.prune(SCOPE_DATA_MODELS, stats.delete(:current_keys))
           stats
         ensure
-          save_manifest
+          save_manifest if prepared
         end
       end
+      private :sync_data_models_prepared
 
       # Sync column data to the Columns Notion database.
       #
@@ -160,14 +171,23 @@ module Woods
       #
       # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
       def sync_columns
+        return empty_stats unless @database_ids[:columns]
+
+        with_prepared_index(['model']) { sync_columns_prepared }
+      end
+
+      def sync_columns_prepared
         database_id = @database_ids[:columns]
         return empty_stats unless database_id
 
+        prepared = false
         begin
           totals = { synced: 0, skipped: 0, errors: [] }
           current_keys = []
+          groups = column_groups
+          prepared = true
 
-          column_groups.each do |group|
+          groups.each do |group|
             result = sync_table_columns(group, database_id, current_keys)
             totals[:synced] += result[:synced]
             totals[:skipped] += result[:skipped]
@@ -177,12 +197,40 @@ module Woods
           @manifest.prune(SCOPE_COLUMNS, current_keys)
           totals
         ensure
-          save_manifest
+          save_manifest if prepared
         end
       end
+      private :sync_columns_prepared
 
       private
 
+      # Reuse one validated snapshot through preprocessing and remote mapping.
+      # Standalone public sync methods have the same pin as sync_all.
+      def with_prepared_index(types = nil)
+        return yield if @published_units
+
+        with_pinned_index do
+          types ||= configured_types
+          @published_units = types.empty? ? [] : @typed_reader.all(only: types)
+          begin
+            yield
+          ensure
+            @published_units = nil
+          end
+        end
+      end
+
+      def units_for(type)
+        @published_units.select { |unit| unit['type'] == type }
+      end
+
+      def configured_types
+        types = []
+        types << 'model' if @database_ids[:data_models] || @database_ids[:columns]
+        types << 'migration' if @database_ids[:data_models]
+        types
+      end
+
       # Sync all units of a type, yielding each for property mapping.
       #
       # @param type [String] Unit type to list
@@ -196,9 +244,8 @@ module Woods
       def sync_units(type, database_id, title_property, scope)
         stats = { synced: 0, skipped: 0, errors: [], current_keys: [] }
 
-        @reader.list_units(type: type).each do |entry|
-          unit_data = @reader.find_unit(entry['identifier'])
-          next unless unit_data
+        units_for(type).each do |unit_data|
+          entry = unit_data
 
           begin
             properties, legacy_title = yield(unit_data)
@@ -227,12 +274,7 @@ module Woods
       #
       # @yield [Hash, Hash] Index entry and full unit data
       def each_model_unit
-        @reader.list_units(type: 'model').each do |entry|
-          unit_data = @reader.find_unit(entry['identifier'])
-          next unless unit_data
-
-          yield(entry, unit_data)
-        end
+        units_for('model').each { |unit_data| yield(unit_data, unit_data) }
       end
 
       # Run a multi-read export body against one index generation.
@@ -436,10 +478,7 @@ module Woods
       # @return [Hash<String, String>] { table_name => latest_date }
       def load_migration_dates
         mapper = Mappers::MigrationMapper.new
-        units = @reader.list_units(type: 'migration').filter_map { |e| @reader.find_unit(e['identifier']) }
-        mapper.latest_changes(units)
-      rescue StandardError
-        {}
+        mapper.latest_changes(units_for('migration'))
       end
 
       # Upsert a Notion page: find by title, update if exists, create if not.

data/lib/woods/obsidian/destination_plan.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require_relative 'errors'
+
+module Woods
+  module Obsidian
+    # Preflight every output before changing the vault. The receipt deliberately
+    # covers only the fixed machine assets; Markdown retains its public marker.
+    # This is not a transaction against concurrent external editors.
+    class DestinationPlan
+      RECEIPT = '_woods/ownership.json'
+      ASSETS = %w[_woods/manifest.json _woods/dependency_graph.json _woods/graph_analysis.json
+                  .obsidian/app.json .obsidian/types.json .obsidian/graph.json Units.base].freeze
+      MAX_RECEIPT_BYTES = 4096
+
+      def initialize(vault, files, managed_note:)
+        @vault = vault
+        @files = files
+        @managed_note = managed_note
+      end
+
+      def commit
+        previous = read_receipt
+        files = @files.dup
+        digests = files.filter_map do |path, content|
+          rel = relative(path)
+          [rel, Digest::SHA256.hexdigest(content)] if ASSETS.include?(rel)
+        end.to_h
+        digests = previous.merge(digests)
+        files[@vault.join(RECEIPT)] = "#{JSON.pretty_generate('schema_version' => 1, 'files' => digests.sort.to_h)}\n"
+        snapshots = files.to_h do |path, content|
+          current = existing_bytes(path)
+          rel = relative(path)
+          permitted = current.nil? || current == content.b ||
+                      (path.extname == '.md' && @managed_note.call(path)) ||
+                      (ASSETS.include?(rel) && previous[rel] == Digest::SHA256.hexdigest(current)) ||
+                      rel == RECEIPT
+          refuse(rel) unless permitted
+          [path, current]
+        end
+        files.each do |path, content|
+          refuse(relative(path), 'changed after preflight') unless existing_bytes(path) == snapshots[path]
+          AtomicFile.write(path, content)
+        end
+      end
+
+      private
+
+      def read_receipt
+        bytes = existing_bytes(@vault.join(RECEIPT))
+        return {} unless bytes
+
+        refuse(RECEIPT, 'invalid ownership receipt') if bytes.bytesize > MAX_RECEIPT_BYTES
+        data = JSON.parse(bytes)
+        valid = data.is_a?(Hash) && data.keys.sort == %w[files schema_version] &&
+                data['schema_version'] == 1 && data['files'].is_a?(Hash) &&
+                data['files'].all? do |path, digest|
+                  ASSETS.include?(path) && digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+                end
+        refuse(RECEIPT, 'invalid ownership receipt') unless valid
+        data['files']
+      rescue JSON::ParserError
+        refuse(RECEIPT, 'invalid ownership receipt')
+      end
+
+      # Reject child symlinks, directories and special files before any read,
+      # including a FIFO at the receipt path. The vault root itself can be a
+      # symlink, as can ancestors such as macOS /tmp.
+      def existing_bytes(path)
+        rel = relative(path)
+        cursor = @vault
+        parts = Pathname.new(rel).each_filename.to_a
+        parts.each_with_index do |part, index|
+          cursor = cursor.join(part)
+          next unless cursor.exist? || cursor.symlink?
+
+          refuse(rel, 'symlink destination') if cursor.symlink?
+          expected = index == parts.size - 1 ? cursor.file? : cursor.directory?
+          refuse(rel, 'not a regular destination') unless expected
+        end
+        path.exist? ? File.binread(path) : nil
+      end
+
+      def relative(path)
+        rel = path.relative_path_from(@vault).to_s
+        refuse(rel, 'outside the vault') if Pathname.new(rel).each_filename.include?('..')
+        rel
+      end
+
+      def refuse(path, reason = 'unmanaged or modified destination')
+        raise ExportError, "refusing #{path}: #{reason}; no sweep performed. " \
+                           'Inspect and back up the conflicting file, then move it aside or export to a new directory.'
+      end
+    end
+  end
+end

data/lib/woods/obsidian/name_mapper.rb

@@ -42,7 +42,13 @@ module Woods
 
       # @param id_to_dir [Hash{String=>String}] map of unit identifier -> type
       #   folder name (e.g. "User" => "models")
-      def initialize(id_to_dir)
+      # @param options [Hash] optional internal-key display identifiers and the
+      #   complete graph's ambiguous identifier set. Positional hash support is
+      #   retained for existing NameMapper.new('User' => 'models') callers.
+      def initialize(id_to_dir, options = {})
+        @identifiers = options.fetch(:identifiers, {})
+        @ambiguous_identifiers = options.fetch(:ambiguous_identifiers, Set.new)
+        @reference_keys = id_to_dir.keys.to_h { |key| [@identifiers.fetch(key, key), key] }
         @map = {}
         @paths = {}
         build(id_to_dir)
@@ -63,6 +69,14 @@ module Woods
         "[[#{entry[:target]}|#{entry[:alias]}]]"
       end
 
+      # Resolve a human metadata reference only when its identifier is unambiguous
+      # in the complete graph, including units excluded from this export.
+      def wikilink_for_identifier(identifier)
+        return nil if @ambiguous_identifiers.include?(identifier)
+
+        wikilink(@reference_keys[identifier])
+      end
+
       # @return [Hash{String=>String}] inverse path -> id map (sorted)
       def paths_to_ids
         @paths
@@ -74,9 +88,11 @@ module Woods
         taken = Hash.new { |h, dir| h[dir] = Set.new(RESERVED_BASENAMES) }
         id_to_dir.keys.sort.each do |id|
           dir = id_to_dir[id]
-          basename = assign_basename(id, taken[dir])
+          identifier = @identifiers.fetch(id, id)
+          basename = assign_basename(identifier, taken[dir])
           path = "#{dir}/#{basename}#{EXTENSION}"
-          @map[id] = { dir: dir, basename: basename, path: path, target: "#{dir}/#{basename}", alias: alias_for(id) }
+          @map[id] =
+            { dir: dir, basename: basename, path: path, target: "#{dir}/#{basename}", alias: alias_for(identifier) }
           @paths[path] = id
         end
       end