htm 0.0.30 → 0.0.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5765fbc2b92d89be3f2bae2f53b4353a76343efd3d092456138bea73ac7803d9
-  data.tar.gz: e594cc16f789745267ce527dcc182fbd533b7484c36e09887f702007388803a3
+  metadata.gz: f9b4fa074840f3acee69bbdf85e5149872d40b5466ad2032793c839af025049c
+  data.tar.gz: e153891af2ce3a7649e8103733ccabb9d832d1ef28b435bd8cd5af0afd43d404
 SHA512:
-  metadata.gz: 78b4b7e226b9911b429e7e0d8735dd0d50d1e56abf7e9e5f494ab50321e33e574605d6a3991d4f0ce18a95ae6dd8ee7928004e3d455730aa388ee2515ffc53c3
-  data.tar.gz: c19a0c15d79342d08e406724724cf64afc68c75ea26f1bf332b4a9b661f3ebe9d50e3f9dbf41db780c0542d4cd7a77ac0bb0da9bf45b5ea7d171def21b4ffc4a
+  metadata.gz: 38398e6f1856e259f5c7e1b18e0b833fc9cdc08acf5f664d68b96f8bc409b9e7ce9c536f85c331e63f1e8cee28141be0e5c33775fa057bc4f5083102519b3e4b
+  data.tar.gz: 4dd7f77aa05cc5d6e4a96f0c8b389729a9e96a831082df715ca6fc9b44f41e856df56c7b9bbdd4c16cdfc614f03aa9e0de9ab9cf96494b90578bf823308c8e2f

data/.irbrc

@@ -12,8 +12,8 @@ puts "=" * 60
 
 # Database Connection
 begin
-  HTM::ActiveRecordConfig.establish_connection! unless HTM::ActiveRecordConfig.connected?
-  db_name = HTM::Database.default_config[:dbname] rescue 'unknown'
+  HTM::SequelConfig.establish_connection! unless HTM::SequelConfig.connected?
+  db_name = HTM::SequelConfig.db.opts[:database] rescue 'unknown'
   puts "✓ Database connected: #{db_name}"
 rescue => e
   puts "✗ Database connection failed: #{e.message}"
@@ -27,7 +27,6 @@ HTM.configure do |config|
   config.embedding.dimensions = 768
   config.tag.provider = :ollama
   config.tag.model = 'gemma3:latest'
-  config.reset_to_defaults
 end
 puts "✓ HTM configured (inline jobs, Ollama provider)"
 

data/.rubocop.yml

@@ -0,0 +1,184 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 4.0
+  Exclude:
+    - 'examples/**/*'
+    - 'vendor/**/*'
+    - 'db/**/*'
+    - 'scripts/**/*'
+
+# ── Style: disabled cops ───────────────────────────────────────────────────
+Style/StringLiterals:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+# Ruby 4.0 freezes string literals by default
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/TrivialAccessors:
+  Enabled: false
+
+Style/MultilineTernaryOperator:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false
+
+Style/EmptyClassDefinition:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+# ── Layout ─────────────────────────────────────────────────────────────────
+Layout/LineLength:
+  Max: 140
+  Exclude:
+    - 'lib/tasks/**/*'
+    - 'test/**/*'
+
+Layout/ExtraSpacing:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+# ── Naming ─────────────────────────────────────────────────────────────────
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/VariableNumber:
+  Exclude:
+    - 'test/**/*'
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Naming/PredicateMethod:
+  AllowedMethods:
+    - soft_delete!
+    - restore!
+    - forget
+    - restore
+    - run
+    - update_existing_chunk
+    - verify_extensions!
+    - validate_database!
+  Exclude:
+    - 'test/**/*'
+
+# ── Lint ───────────────────────────────────────────────────────────────────
+Lint/EmptyBlock:
+  AllowedMethods:
+    - arguments
+  Exclude:
+    - 'test/**/*'
+    - 'lib/htm/mcp/**/*'
+
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'Rakefile'
+    - 'test/**/*'
+
+# ── Gemspec ────────────────────────────────────────────────────────────────
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: Gemfile
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Gemspec/OrderedDependencies:
+  Enabled: false
+
+# ── Metrics ────────────────────────────────────────────────────────────────
+Metrics/MethodLength:
+  Max: 35
+  CountAsOne:
+    - heredoc
+    - array
+    - hash
+  Exclude:
+    - 'test/**/*'
+    - 'lib/tasks/**/*'
+
+Metrics/AbcSize:
+  Max: 40
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ClassLength:
+  Max: 600
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ModuleLength:
+  Max: 450
+  Exclude:
+    - 'test/**/*'
+    - 'lib/tasks/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+
+Metrics/PerceivedComplexity:
+  Max: 20
+  Exclude:
+    - 'test/**/*'
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'Rakefile'
+    - '*.gemspec'
+    - 'test/**/*'
+    - 'lib/tasks/**/*'
+    - 'lib/htm/models/**/*'
+    - 'lib/htm/long_term_memory/**/*'
+
+Style/FormatStringToken:
+  Exclude:
+    - 'lib/tasks/**/*'

data/CHANGELOG.md

@@ -8,6 +8,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`node_relationships` table** - Weighted directed edges between related nodes
+  - Stores Jaccard-similarity scores computed from tag co-occurrence
+  - Both directions (A→B and B→A) stored explicitly for O(1) index lookups during CTE traversal
+  - Unique constraint on `(source_id, target_id, rel_type)` — re-runs refresh stale weights via upsert
+  - DB CHECK constraints enforce weight in [0.0, 1.0] and prevent self-loops
+  - FK constraints (ON DELETE CASCADE) from both `source_id` and `target_id` to nodes
+- **`HTM::Models::NodeRelationship`** - Sequel model for the new table
+  - Constants: `REL_TYPES` (`related_to`, `supports`, `contradicts`, `derived_from`) and `ORIGINS` (`tag_cooccurrence`, `tag_hierarchy`, `explicit`)
+  - Dataset scopes: `neighbors_of`, `above_weight`, `by_origin`, `by_rel_type`, `between_nodes`
+  - Full validation: presence, allowed values, weight range, self-loop rejection, uniqueness
+- **`HTM::Jobs::GenerateRelationshipsJob`** - Background job that computes and upserts Jaccard edges
+  - Chained automatically after `GenerateTagsJob` completes
+  - Single SQL query computes Jaccard similarity for all tag-sharing nodes at once
+  - Skips edges below `MIN_WEIGHT_THRESHOLD` (0.1); caps at `MAX_EDGES_PER_NODE` (50) per node
+  - Idempotent: `INSERT ... ON CONFLICT DO UPDATE` refreshes stale weights on re-run
+- **Migrations** `00008_create_node_relationships` and `00009_fix_node_relationships_column_types`
+
+
 - **`sslmode` database configuration support** - SSL mode now extracted from URL and included when building URL
   - `parse_database_url` extracts `sslmode` from URL query string (e.g., `?sslmode=require`)
   - `build_database_url` includes `sslmode` as query parameter when set
@@ -61,6 +79,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Increased specificity requirements for self-contained facts
 
 ### Fixed
+- **`token_counter` never set on config load** - `setup_defaults` on-load hook assigned to `@setup_defaults` (typo) instead of `@token_counter`, causing `HTM::ValidationError: token_counter must be callable` in any test that triggered a fresh config load via `HTM.configure`
+- **`reset_htm_configuration` lost mock services** - After `HTM.reset_configuration!` the helper only set `job.backend = :inline`, leaving the real Ollama embedding generator active; subsequent tests accumulated circuit breaker failures and left nodes without embeddings. Now calls `configure_htm_with_mocks` to fully restore test defaults
+- **Integration test circuit breaker leak** - `IntegrationTest#setup` now explicitly resets `EmbeddingService` and `TagService` circuit breakers before each test to prevent state bleed from other test classes
+- **Duplicate rescue branches** - Merged redundant `rescue HTM::CircuitBreakerOpenError` + service-specific error rescues (both just `raise`) into single `rescue A, B` in `EmbeddingService`, `TagService`, and `PropositionService`
+- **Duplicate `when "cosine"` branch in Node distance operator** - Removed branch whose body was identical to the `else` fallback (`"<=>"`), eliminating the `Lint/DuplicateBranch` offense
+- **Identical conditional branches in `Tag.format_tree_branch`** - `branch = is_last ? '+-- ' : '+-- '` both sides were identical; simplified to a direct string literal
+- **`EmptyElse` in `Observability#process_memory_mb`** - Removed redundant `else nil` branch from the platform detection conditional
+
+### Refactored
+- **Flog complexity reduced across 15+ files** - All methods now score below the 50.0 failure threshold (previously 9 methods failed):
+  - `HTM::Models::Tag::generate_tree_svg` (93.6 → passing): extracted `svg_title_element`, `svg_node_elements`, `svg_node_coords`, `svg_edge_path`, `svg_node_rect`, `svg_node_label`
+  - `HybridSearch#search_hybrid_rrf` (83.2 → passing): extracted `extract_rrf_tag_info`, `build_rrf_literals`, `build_rrf_filter_sql`, `post_process_rrf_results`
+  - `HybridSearch#merge_with_rrf` (65.7 → passing): extracted `merge_vector_rrf_entry`, `merge_fulltext_rrf_entry`, `merge_tag_rrf_entry`
+  - `RelevanceScorer#fetch_nodes_by_tags` (62.6 → passing): extracted `build_tag_base_query`, `apply_match_all_constraint`
+  - `MarkdownLoader#sync_chunks` (61.2 → passing): extracted `update_existing_chunk`, `soft_delete_removed_chunks`
+  - `HybridSearch#build_hybrid_cte_sql` (55.9 → passing): extracted per-CTE builder methods
+  - `Config::Database#build_database_url` (55.6 → passing): extracted `database_auth_segment`
+  - `MCP::GetWorkingMemoryTool#call` (56.0 → passing): extracted `format_working_memory_entry`
+  - `MarkdownLoader#load_file` (50.1 → passing): extracted `validate_file_path!`, `read_file_content`, `prepend_frontmatter_to_chunk`
+  - `Config#apply_provider_config` (77.4 → passing): replaced `case` statement with dynamic dispatch (`send(:"apply_#{provider}_provider_config", config)`)
+  - `RememberWorkflow#finalize_step` (50.7 → passing): extracted `finalize_node`, `evict_working_memory_if_needed`
+  - `HTM#remember`: extracted `validate_remember_content!`, `validate_remember_tags!`, `enqueue_background_jobs`, `handle_existing_node_tags`, `store_in_working_memory`
+- **RuboCop: 128 offenses resolved** - Zero offenses across 89 files:
+  - Replaced all `[[x, min].max, max].min` patterns with `x.clamp(min, max)` in `tag_operations.rb`, `fulltext_search.rb`, `vector_search.rb`, `hybrid_search.rb`
+  - Broke all `end.sort_by {}` / `end.map {}` multiline block chains into two statements across `database.rb`, `hybrid_search.rb`, `relevance_scorer.rb`, `mcp/cli.rb`, `working_memory.rb`
+  - Updated `.rubocop.yml`: added `AllowedMethods` for bang methods (`soft_delete!`, `restore!`) and MCP DSL (`arguments` block), excluded `lib/tasks/**/*` from `BlockLength`, `MethodLength`, `FormatStringToken`, and `LineLength` cops
+  - Removed development dependencies from `htm.gemspec` in favour of `Gemfile` group blocks (enforced by `Gemspec/DevelopmentDependencies`)
+
 - **Test database isolation** - Two-layer protection prevents tests from polluting development/production
   - `Rakefile`: `set_test_env` task now ALWAYS overrides `HTM_DATABASE__URL` to test database
   - Uses `#{service_name}_test` pattern (e.g., `htm_test`) based on `HTM_SERVICE__NAME` env var

data/README.md

@@ -150,8 +150,10 @@ For MCP integration, database setup, and configuration options, see the [full do
 | **Hive Mind** | Shared memory across all robots |
 | **Vector Search** | Semantic retrieval with pgvector |
 | **Hybrid Search** | Combines vector + full-text matching |
+| **Graph Traversal** | CTE-based relationship traversal via Jaccard-weighted edges |
 | **Temporal Queries** | "last week", "yesterday", date ranges |
 | **Auto-Tagging** | LLM extracts hierarchical tags automatically |
+| **Auto-Relationships** | Tag co-occurrence edges computed after tagging |
 | **Robot Groups** | High-availability with failover |
 | **Rails Integration** | Auto-configures via Railtie, uses ActiveJob |
 | **Telemetry** | Optional OpenTelemetry metrics |

data/Rakefile

@@ -3,11 +3,14 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+RUBOCOP_ENV = { "RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache" }.freeze
+
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
   t.verbose = true
+  t.ruby_opts << "-rtest_helper"
 end
 
 # Prepend environment setup before test runs
@@ -23,7 +26,7 @@ task :set_test_env do
 
   # ALWAYS use the test database - never allow tests to run against other databases
   # This prevents accidental pollution of development/production data
-  test_db_url = "postgresql://#{ENV['USER']}@localhost:5432/#{test_db_name}"
+  test_db_url = "postgresql://#{ENV.fetch('USER', nil)}@localhost:5432/#{test_db_name}"
 
   if ENV['HTM_DATABASE__URL'] && !ENV['HTM_DATABASE__URL'].include?('_test')
     warn "WARNING: HTM_DATABASE__URL was set to '#{ENV['HTM_DATABASE__URL']}'"
@@ -52,7 +55,7 @@ task :set_examples_env do
   examples_db_name = "#{service_name}_examples"
 
   # ALWAYS use the examples database
-  examples_db_url = "postgresql://#{ENV['USER']}@localhost:5432/#{examples_db_name}"
+  examples_db_url = "postgresql://#{ENV.fetch('USER', nil)}@localhost:5432/#{examples_db_name}"
 
   if ENV['HTM_DATABASE__URL'] && !ENV['HTM_DATABASE__URL'].include?('_examples')
     warn "WARNING: HTM_DATABASE__URL was set to '#{ENV['HTM_DATABASE__URL']}'"
@@ -80,7 +83,7 @@ namespace :examples do
   end
 
   desc "Run all standalone examples"
-  task :all => :set_examples_env do
+  task all: :set_examples_env do
     examples = %w[
       examples/01_basic_usage.rb
       examples/03_custom_llm_configuration.rb
@@ -88,12 +91,11 @@ namespace :examples do
       examples/05_timeframe_demo.rb
     ]
     examples.each do |example|
-      if File.exist?(example)
-        puts "\n#{'=' * 60}"
-        puts "Running: #{example}"
-        puts "#{'=' * 60}"
-        ruby example
-      end
+      next unless File.exist?(example)
+      puts "\n#{'=' * 60}"
+      puts "Running: #{example}"
+      puts('=' * 60)
+      ruby example
     end
   end
 
@@ -102,8 +104,8 @@ namespace :examples do
     require_relative 'lib/htm'
     puts "Examples Environment Status"
     puts "=" * 40
-    puts "HTM_ENV: #{ENV['HTM_ENV']}"
-    puts "Database URL: #{ENV['HTM_DATABASE__URL']}"
+    puts "HTM_ENV: #{ENV.fetch('HTM_ENV', nil)}"
+    puts "Database URL: #{ENV.fetch('HTM_DATABASE__URL', nil)}"
     puts "Expected database: #{HTM.config.expected_database_name}"
     if HTM.config.database_configured?
       puts "Database configured: Yes"
@@ -129,13 +131,92 @@ namespace :examples do
 end
 
 desc "Run example (alias for examples:basic)"
-task :example => 'examples:basic'
+task example: 'examples:basic'
 
 desc "Run timeframe demo"
 task :timeframe_demo do
   ruby "examples/05_timeframe_demo.rb"
 end
 
+desc "Check code style with RuboCop"
+task :rubocop do
+  sh RUBOCOP_ENV, "bundle exec rubocop"
+end
+
+desc "Auto-correct RuboCop offenses"
+task :rubocop_fix do
+  sh RUBOCOP_ENV, "bundle exec rubocop -a"
+end
+
+desc "Check code complexity with Flog (warn >=20, fail >=50)"
+task :flog_check do
+  require 'flog'
+
+  method_warn = 20.0
+  method_fail = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob('lib/**/*.rb').reject { |f| f.start_with?('lib/tasks/') })
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?('#none')
+
+    if score > method_fail
+      failures << "#{format('%.1f', score)}: #{method}"
+    elsif score > method_warn
+      warnings << "#{format('%.1f', score)}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
+  else
+    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
+  end
+end
+
+desc "Run all quality checks: tests (with coverage), RuboCop, and Flog"
+task :quality do
+  results = {}
+
+  puts "\n#{'=' * 60}"
+  puts "Quality Gate: Tests + Coverage"
+  puts '=' * 60
+  results[:tests] = system("bundle exec rake test") ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts "Quality Gate: RuboCop"
+  puts '=' * 60
+  results[:rubocop] = system(RUBOCOP_ENV, "bundle exec rubocop") ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts "Quality Gate: Flog Complexity"
+  puts '=' * 60
+  results[:flog] = system("bundle exec rake flog_check") ? :pass : :fail
+
+  puts "\n#{'=' * 60}"
+  puts "Quality Summary"
+  puts '=' * 60
+  results.each do |gate, status|
+    icon = status == :pass ? 'PASS' : 'FAIL'
+    puts "  [#{icon}] #{gate}"
+  end
+  puts '=' * 60
+
+  abort "\nQuality gate failed" if results.values.any?(:fail)
+  puts "\nAll quality gates passed."
+end
+
 desc "Show gem stats"
 task :stats do
   puts "\nHTM Gem Statistics:"

data/db/migrate/00008_create_node_relationships.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/htm/migration'
+
+class CreateNodeRelationships < HTM::Migration
+  def up
+    create_table(:node_relationships) do
+      primary_key :id
+      Bignum :source_id, null: false
+      Bignum :target_id, null: false
+      String :rel_type,  null: false, default: 'related_to'
+      String :origin,    null: false, default: 'tag_cooccurrence'
+      Float  :weight,    null: false, default: 1.0
+      DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :updated_at, default: Sequel::CURRENT_TIMESTAMP
+    end
+
+    add_index :node_relationships, [:source_id, :target_id, :rel_type],
+              unique: true, name: :idx_node_relationships_unique
+    add_index :node_relationships, :source_id, name: :idx_node_relationships_source_id
+    add_index :node_relationships, :target_id, name: :idx_node_relationships_target_id
+    add_index :node_relationships, :weight,    name: :idx_node_relationships_weight
+    add_index :node_relationships, :origin,    name: :idx_node_relationships_origin
+
+    alter_table(:node_relationships) do
+      add_foreign_key [:source_id], :nodes, name: :fk_node_relationships_source, on_delete: :cascade
+      add_foreign_key [:target_id], :nodes, name: :fk_node_relationships_target, on_delete: :cascade
+    end
+
+    run <<~SQL
+      ALTER TABLE node_relationships
+        ADD CONSTRAINT chk_node_relationships_weight
+        CHECK (weight >= 0.0 AND weight <= 1.0)
+    SQL
+
+    run <<~SQL
+      ALTER TABLE node_relationships
+        ADD CONSTRAINT chk_node_relationships_no_self_loop
+        CHECK (source_id <> target_id)
+    SQL
+
+    run "COMMENT ON TABLE node_relationships IS 'Weighted directed edges between nodes for graph traversal'"
+    run "COMMENT ON COLUMN node_relationships.source_id IS 'Starting node of the relationship'"
+    run "COMMENT ON COLUMN node_relationships.target_id IS 'Ending node of the relationship'"
+    run "COMMENT ON COLUMN node_relationships.rel_type IS 'Semantic label: related_to, supports, contradicts, derived_from'"
+    run "COMMENT ON COLUMN node_relationships.origin IS 'How created: tag_cooccurrence, tag_hierarchy, explicit'"
+    run "COMMENT ON COLUMN node_relationships.weight IS 'Relationship strength 0.0-1.0 (Jaccard similarity for tag_cooccurrence)'"
+    run "COMMENT ON COLUMN node_relationships.updated_at IS 'When weight was last recalculated'"
+  end
+
+  def down
+    drop_table(:node_relationships)
+  end
+end

data/db/migrate/00009_fix_node_relationships_column_types.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/htm/migration'
+
+class FixNodeRelationshipsColumnTypes < HTM::Migration
+  def up
+    run "ALTER TABLE node_relationships ALTER COLUMN id TYPE bigint"
+    run "ALTER TABLE node_relationships ALTER COLUMN created_at TYPE timestamp with time zone"
+    run "ALTER TABLE node_relationships ALTER COLUMN updated_at TYPE timestamp with time zone"
+  end
+
+  def down
+    run "ALTER TABLE node_relationships ALTER COLUMN id TYPE integer"
+    run "ALTER TABLE node_relationships ALTER COLUMN created_at TYPE timestamp without time zone"
+    run "ALTER TABLE node_relationships ALTER COLUMN updated_at TYPE timestamp without time zone"
+  end
+end

data/db/schema.sql

@@ -115,6 +115,78 @@ CREATE SEQUENCE public.file_sources_id_seq
 
 ALTER SEQUENCE public.file_sources_id_seq OWNED BY public.file_sources.id;
 
+--
+-- Name: node_relationships; Type: TABLE; Schema: public; Owner: -
+--
+
+CREATE TABLE public.node_relationships (
+    id bigint NOT NULL,
+    source_id bigint NOT NULL,
+    target_id bigint NOT NULL,
+    rel_type text DEFAULT 'related_to'::text NOT NULL,
+    origin text DEFAULT 'tag_cooccurrence'::text NOT NULL,
+    weight double precision DEFAULT 1.0 NOT NULL,
+    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT chk_node_relationships_no_self_loop CHECK ((source_id <> target_id)),
+    CONSTRAINT chk_node_relationships_weight CHECK (((weight >= (0.0)::double precision) AND (weight <= (1.0)::double precision)))
+);
+
+--
+-- Name: TABLE node_relationships; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON TABLE public.node_relationships IS 'Weighted directed edges between nodes for graph traversal';
+
+--
+-- Name: COLUMN node_relationships.source_id; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.node_relationships.source_id IS 'Starting node of the relationship';
+
+--
+-- Name: COLUMN node_relationships.target_id; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.node_relationships.target_id IS 'Ending node of the relationship';
+
+--
+-- Name: COLUMN node_relationships.rel_type; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.node_relationships.rel_type IS 'Semantic label: related_to, supports, contradicts, derived_from';
+
+--
+-- Name: COLUMN node_relationships.origin; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.node_relationships.origin IS 'How created: tag_cooccurrence, tag_hierarchy, explicit';
+
+--
+-- Name: COLUMN node_relationships.weight; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.node_relationships.weight IS 'Relationship strength 0.0-1.0 (Jaccard similarity for tag_cooccurrence)';
+
+--
+-- Name: COLUMN node_relationships.updated_at; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.node_relationships.updated_at IS 'When weight was last recalculated';
+
+--
+-- Name: node_relationships_id_seq; Type: SEQUENCE; Schema: public; Owner: -
+--
+
+ALTER TABLE public.node_relationships ALTER COLUMN id ADD GENERATED BY DEFAULT AS IDENTITY (
+    SEQUENCE NAME public.node_relationships_id_seq
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1
+);
+
 --
 -- Name: node_tags; Type: TABLE; Schema: public; Owner: -
 --
@@ -536,6 +608,13 @@ ALTER TABLE ONLY public.tags ALTER COLUMN id SET DEFAULT nextval('public.tags_id
 ALTER TABLE ONLY public.file_sources
     ADD CONSTRAINT file_sources_pkey PRIMARY KEY (id);
 
+--
+-- Name: node_relationships node_relationships_pkey; Type: CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.node_relationships
+    ADD CONSTRAINT node_relationships_pkey PRIMARY KEY (id);
+
 --
 -- Name: node_tags node_tags_pkey; Type: CONSTRAINT; Schema: public; Owner: -
 --
@@ -596,6 +675,36 @@ CREATE INDEX idx_file_sources_last_synced ON public.file_sources USING btree (la
 
 CREATE UNIQUE INDEX idx_file_sources_path_unique ON public.file_sources USING btree (file_path);
 
+--
+-- Name: idx_node_relationships_origin; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_node_relationships_origin ON public.node_relationships USING btree (origin);
+
+--
+-- Name: idx_node_relationships_source_id; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_node_relationships_source_id ON public.node_relationships USING btree (source_id);
+
+--
+-- Name: idx_node_relationships_target_id; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_node_relationships_target_id ON public.node_relationships USING btree (target_id);
+
+--
+-- Name: idx_node_relationships_unique; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE UNIQUE INDEX idx_node_relationships_unique ON public.node_relationships USING btree (source_id, target_id, rel_type);
+
+--
+-- Name: idx_node_relationships_weight; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_node_relationships_weight ON public.node_relationships USING btree (weight);
+
 --
 -- Name: idx_node_tags_deleted_at; Type: INDEX; Schema: public; Owner: -
 --
@@ -770,6 +879,20 @@ CREATE INDEX idx_tags_name_trgm ON public.tags USING gin (name public.gin_trgm_o
 
 CREATE UNIQUE INDEX idx_tags_name_unique ON public.tags USING btree (name);
 
+--
+-- Name: node_relationships fk_node_relationships_source; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.node_relationships
+    ADD CONSTRAINT fk_node_relationships_source FOREIGN KEY (source_id) REFERENCES public.nodes(id) ON DELETE CASCADE;
+
+--
+-- Name: node_relationships fk_node_relationships_target; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.node_relationships
+    ADD CONSTRAINT fk_node_relationships_target FOREIGN KEY (target_id) REFERENCES public.nodes(id) ON DELETE CASCADE;
+
 --
 -- Name: nodes fk_rails_920ad16d08; Type: FK CONSTRAINT; Schema: public; Owner: -
 --
@@ -809,4 +932,4 @@ ALTER TABLE ONLY public.robot_nodes
 -- PostgreSQL database dump complete
 --
 
-\unrestrict 1ItB7RQU4jC5IvOL40FU9j9sS6bzk9jcKeDUYSOd78ym0sA7pq0FXYSOEoWsPh7
+\unrestrict w7upGmgsSOptbQDRWSmlGQx3H1ForwMj2X115QW1LhH1csS9lg06winM4mrfbpS