woods 2.0.0.beta2 → 2.0.0.beta3

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}; " \
+          "typed path complete=#{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/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

data/lib/woods/obsidian/note_builder.rb

@@ -28,12 +28,15 @@ module Woods
       ASSOCIATION_ORDER = %w[belongs_to has_one has_many has_and_belongs_to_many].freeze
 
       # @param name_mapper [NameMapper] resolves ids to wikilinks/paths
-      # @param nodes [Hash] graph nodes ({ id => { 'type' => , ... } }) for edge-endpoint types
+      # @param nodes [Hash] note-key => graph node for edge-endpoint types
       # @param pagerank [Hash{String=>Float}] persisted pagerank scores
       # @param analysis [Hash, nil] parsed graph_analysis.json (hubs/cycles/orphans/bridges) or nil
       # @param include_source [Boolean] embed scrubbed source code
       # @param scanner [#scan, nil] credential scanner (required when include_source)
-      def initialize(name_mapper:, nodes:, pagerank: {}, analysis: nil, include_source: false, scanner: nil)
+      def initialize(name_mapper:, nodes:, pagerank: {}, analysis: nil, include_source: false, scanner: nil,
+                     identifiers: {}, ambiguous_identifiers: Set.new)
+        @identifiers = identifiers
+        @ambiguous_identifiers = ambiguous_identifiers
         @mapper = name_mapper
         @nodes = nodes || {}
         @pagerank = pagerank || {}
@@ -45,10 +48,10 @@ module Woods
         @cycle_members = cycle_member_set(analysis)
       end
 
-      # @param id [String] bare unit identifier (graph node key)
+      # @param id [String, Array<String>] note key: bare id for standalone use, or [identifier, type]
       # @param unit [Hash] parsed unit JSON (used only for body facts)
       # @param depends_on [Array<Hash>] [{ target:, via: }] filtered to the emitted set
-      # @param used_by [Array<String>] unique dependent ids filtered to the emitted set
+      # @param used_by [Array<String, Array<String>>] unique dependent note keys filtered to the emitted set
       # @return [String] the rendered note. A failed source scrub omits the source
       #   section (the note is still written); build never returns nil.
       def build(id:, unit:, depends_on:, used_by:)
@@ -74,7 +77,7 @@ module Woods
       def frontmatter(id, unit, depends_on, used_by)
         fm = {
           'woods_managed' => true,
-          'id' => id,
+          'id' => @identifiers.fetch(id, id),
           'type' => unit['type'],
           'file' => unit['file_path'],
           'source_hash' => unit['source_hash'],
@@ -82,17 +85,23 @@ module Woods
           'dependency_count' => depends_on.size,
           'dependent_count' => used_by.size,
           'tags' => tags_for(id, unit),
-          'aliases' => [id]
+          'aliases' => [@identifiers.fetch(id, id)]
         }.compact
         "#{fm.to_yaml}---"
       end
 
+      def analysis_identifier(id)
+        identifier = @identifiers.fetch(id, id)
+        identifier unless @ambiguous_identifiers.include?(identifier)
+      end
+
       def pagerank_for(id)
-        score = @pagerank[id]
+        score = @pagerank[analysis_identifier(id)]
         score&.round(6)
       end
 
       def tags_for(id, unit)
+        id = analysis_identifier(id)
         tags = ['woods/unit', "woods/#{unit['type']}"]
         tags << 'woods/hub' if @hubs.include?(id)
         tags << 'woods/orphan' if @orphans.include?(id)
@@ -124,11 +133,11 @@ module Woods
       end
 
       def callout(id, used_by)
-        if @hubs.include?(id)
+        if @hubs.include?(analysis_identifier(id))
           pr = pagerank_for(id)
           suffix = pr ? " (PageRank #{format('%.4f', pr)})" : ''
           "> [!warning] Hub — high blast radius\n> #{used_by.size} units depend on this#{suffix}."
-        elsif @cycle_members.include?(id)
+        elsif @cycle_members.include?(analysis_identifier(id))
           "> [!warning] Part of a dependency cycle\n> This unit participates in a circular dependency."
         end
       end
@@ -181,7 +190,7 @@ module Woods
         return [] unless items
 
         items.filter_map do |assoc|
-          link = @mapper.wikilink(assoc[:target])
+          link = @mapper.wikilink_for_identifier(assoc[:target])
           next unless link
 
           assoc[:dependent] ? "#{link} (dependent: #{assoc[:dependent]})" : link