# Install generator creates a migration
rails generate woods:install

# Generates:
# db/migrate/XXXXXX_create_woods_tables.rb
# config/initializers/woods.rb

class CreateWoodsTables < ActiveRecord::Migration[7.0]
  def change
    create_table :woods_units, id: false do |t|
      t.string :id, primary_key: true
      t.string :unit_type, null: false, limit: 50  # model, controller, service, job, mailer, component, graphql_type, graphql_mutation, graphql_resolver, graphql_query, framework_source
      t.string :namespace, limit: 255
      t.string :file_path, limit: 500
      t.text :source_code, size: :medium  # MEDIUMTEXT on MySQL, TEXT on PG
      t.json :metadata, null: false

      t.timestamps
    end

    add_index :woods_units, :unit_type
    add_index :woods_units, :namespace

    # Full-text index (adapter-specific)
    if mysql?
      execute "ALTER TABLE woods_units ADD FULLTEXT INDEX idx_fulltext (id, file_path, source_code)"
    elsif postgresql?
      execute <<~SQL
        CREATE INDEX idx_fulltext ON woods_units
        USING gin (to_tsvector('english', coalesce(id, '') || ' ' || coalesce(file_path, '') || ' ' || coalesce(source_code, '')))
      SQL
    end

    create_table :woods_edges, id: false do |t|
      t.string :source_id, null: false
      t.string :target_id, null: false
      t.string :relationship, null: false, limit: 50
    end

    add_index :woods_edges, [:source_id, :target_id, :relationship], unique: true, name: "idx_edges_pk"
    add_index :woods_edges, :target_id
    add_index :woods_edges, :relationship
  end

  private

  def mysql?
    ActiveRecord::Base.connection.adapter_name.downcase.include?("mysql")
  end

  def postgresql?
    ActiveRecord::Base.connection.adapter_name.downcase.include?("postgresql")
  end
end

rails generate woods:generated_columns

# Generates:
# db/migrate/XXXXXX_add_woods_generated_columns.rb

class AddWoodsGeneratedColumns < ActiveRecord::Migration[7.0]
  def up
    return unless mysql?

    execute <<~SQL
      ALTER TABLE woods_units
        ADD COLUMN change_frequency VARCHAR(20) GENERATED ALWAYS AS (
          JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.git.change_frequency'))
        ) STORED,
        ADD COLUMN importance VARCHAR(20) GENERATED ALWAYS AS (
          JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.importance'))
        ) STORED,
        ADD COLUMN estimated_tokens INT GENERATED ALWAYS AS (
          JSON_EXTRACT(metadata, '$.estimated_tokens')
        ) STORED,
        ADD INDEX idx_change_freq (change_frequency),
        ADD INDEX idx_importance (importance)
    SQL
  end

  def down
    return unless mysql?

    execute <<~SQL
      ALTER TABLE woods_units
        DROP INDEX idx_change_freq,
        DROP INDEX idx_importance,
        DROP COLUMN change_frequency,
        DROP COLUMN importance,
        DROP COLUMN estimated_tokens
    SQL
  end
end

# Rake task handles schema directly
rake woods:db:setup          # Create tables
rake woods:db:migrate        # Run pending migrations
rake woods:db:status         # Show migration status
rake woods:db:reset          # Drop and recreate

lib/woods/db/
├── migrations/
│   ├── 001_create_units.rb
│   ├── 002_create_edges.rb
│   ├── 003_add_generated_columns_mysql.rb
│   └── 004_add_embedding_metadata.rb
├── schema/
│   ├── mysql.sql       # Full schema for MySQL fresh installs
│   ├── postgresql.sql  # Full schema for PostgreSQL fresh installs
│   └── sqlite.sql      # Full schema for SQLite fresh installs
└── migrate.rb          # Migration runner

module Woods
  module DB
    class Migration001CreateUnits < Migration
      def up(conn, adapter)
        case adapter
        when :mysql
          conn.execute <<~SQL
            CREATE TABLE IF NOT EXISTS woods_units (
              id VARCHAR(255) PRIMARY KEY,
              -- ... MySQL-specific schema
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
          SQL
        when :postgresql
          conn.execute <<~SQL
            CREATE TABLE IF NOT EXISTS woods_units (
              id TEXT PRIMARY KEY,
              -- ... PostgreSQL-specific schema
            )
          SQL
        when :sqlite
          conn.execute <<~SQL
            CREATE TABLE IF NOT EXISTS woods_units (
              id TEXT PRIMARY KEY,
              -- ... SQLite-specific schema
            )
          SQL
        end
      end

      def down(conn, adapter)
        conn.execute "DROP TABLE IF EXISTS woods_units"
      end
    end
  end
end

CREATE TABLE woods_schema_migrations (
  version VARCHAR(20) PRIMARY KEY,
  applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

# Qdrant adapter auto-creates collection
class QdrantAdapter
  def ensure_collection!
    return if collection_exists?

    client.create_collection(
      collection_name: @collection,
      vectors: { size: @dimensions, distance: "Cosine" }
    )
  end
end

rails generate woods:pgvector

# Generates:
# db/migrate/XXXXXX_create_woods_embeddings.rb

class CreateCodebaseEmbeddings < ActiveRecord::Migration[7.0]
  def up
    enable_extension "vector" unless extension_enabled?("vector")

    create_table :woods_embeddings, id: false do |t|
      t.string :id, primary_key: true
      t.column :embedding, "vector(1536)"  # Dimension matches embedding provider
      t.jsonb :metadata, null: false, default: {}
      t.timestamps
    end

    execute <<~SQL
      CREATE INDEX ON woods_embeddings
      USING hnsw (embedding vector_cosine_ops)
      WITH (m = 16, ef_construction = 64)
    SQL

    execute <<~SQL
      CREATE INDEX ON woods_embeddings
      USING gin (metadata jsonb_path_ops)
    SQL
  end
end

rake woods:reindex[new_provider]
# 1. Creates new vector storage alongside old
# 2. Re-embeds everything with new provider
# 3. Swaps atomically
# 4. Drops old storage

Tier 1: Full retrieval (vector + keyword + graph + ranking)
  │
  │ Vector store fails
  ▼
Tier 2: Keyword + graph (no semantic search, exact matches only)
  │
  │ Metadata store fails
  ▼
Tier 3: Graph-only (dependency traversal from known identifiers)
  │
  │ Graph store fails
  ▼
Tier 4: Direct file lookup (read from extracted JSON on disk)
  │
  │ Extraction output missing
  ▼
Tier 5: Empty result with diagnostic message

module Woods
  class CircuitBreaker
    STATES = %i[closed open half_open].freeze

    def initialize(name:, failure_threshold: 5, reset_timeout: 60)
      @name = name
      @failure_threshold = failure_threshold
      @reset_timeout = reset_timeout
      @failure_count = 0
      @state = :closed
      @last_failure_at = nil
    end

    def call(&block)
      case @state
      when :closed
        execute_with_tracking(&block)
      when :open
        if Time.now - @last_failure_at > @reset_timeout
          @state = :half_open
          execute_with_tracking(&block)
        else
          raise CircuitOpenError, "Circuit #{@name} is open (#{@failure_count} failures, resets in #{remaining_reset_time}s)"
        end
      when :half_open
        execute_with_tracking(&block)
      end
    end

    private

    def execute_with_tracking
      result = yield
      reset! if @state == :half_open
      result
    rescue StandardError => e
      record_failure!
      raise
    end

    def record_failure!
      @failure_count += 1
      @last_failure_at = Time.now
      @state = :open if @failure_count >= @failure_threshold
    end

    def reset!
      @failure_count = 0
      @state = :closed
    end
  end
end

module Woods
  class Retriever
    def retrieve(query, budget: 8000)
      classification = classify(query)
      trace = RetrievalTrace.new(query: query, classification: classification)

      # Attempt full retrieval
      candidates = search_with_fallback(query, classification, trace)
      ranked = rank(candidates, classification, trace)
      context = assemble(ranked, budget, trace)

      RetrievalResult.new(
        context: context.text,
        tokens_used: context.tokens,
        sources: context.sources,
        classification: classification,
        trace: trace,
        degraded: trace.degraded?,
        degradation_reason: trace.degradation_reason
      )
    end

    private

    def search_with_fallback(query, classification, trace)
      candidates = []

      # Vector search (Tier 1)
      begin
        vector_results = @vector_circuit.call { vector_search(query, classification) }
        candidates.concat(vector_results)
        trace.record(:vector_search, :success, count: vector_results.size)
      rescue CircuitOpenError, VectorStoreError => e
        trace.record(:vector_search, :failed, error: e.message)
        trace.mark_degraded!("Vector search unavailable: #{e.message}")
      end

      # Keyword search (always attempted)
      begin
        keyword_results = keyword_search(query, classification)
        candidates.concat(keyword_results)
        trace.record(:keyword_search, :success, count: keyword_results.size)
      rescue MetadataStoreError => e
        trace.record(:keyword_search, :failed, error: e.message)
        trace.mark_degraded!("Keyword search unavailable: #{e.message}")
      end

      # Graph expansion (if we have any candidates to expand from)
      if candidates.any?
        begin
          graph_results = graph_expand(candidates, classification)
          candidates.concat(graph_results)
          trace.record(:graph_expansion, :success, count: graph_results.size)
        rescue GraphStoreError => e
          trace.record(:graph_expansion, :failed, error: e.message)
          # Graph failure is non-critical — we still have direct results
        end
      end

      # Tier 4 fallback: direct file lookup if nothing worked
      if candidates.empty?
        trace.mark_degraded!("All search backends failed, falling back to file lookup")
        candidates = direct_file_lookup(query)
        trace.record(:file_lookup, :fallback, count: candidates.size)
      end

      candidates
    end
  end
end

module Woods
  module Embedding
    class RetryableProvider
      MAX_RETRIES = 3
      BACKOFF_BASE = 2  # seconds

      def initialize(provider)
        @provider = provider
        @retry_queue = []
      end

      def embed_batch(texts)
        results = []
        failed = []

        texts.each_slice(batch_size) do |batch|
          retries = 0
          begin
            results.concat(@provider.embed_batch(batch))
          rescue RateLimitError => e
            retries += 1
            if retries <= MAX_RETRIES
              sleep_time = BACKOFF_BASE ** retries + rand(0.0..1.0)
              log_retry(e, retries, sleep_time)
              sleep(sleep_time)
              retry
            else
              log_failure(e, batch)
              failed.concat(batch)
            end
          rescue EmbeddingError => e
            log_failure(e, batch)
            failed.concat(batch)
          end
        end

        # Queue failed items for later retry
        @retry_queue.concat(failed) if failed.any?

        EmbeddingResult.new(
          embeddings: results,
          failed_count: failed.size,
          retry_queued: failed.size
        )
      end

      def process_retry_queue!
        return if @retry_queue.empty?

        to_retry = @retry_queue.dup
        @retry_queue.clear
        embed_batch(to_retry)
      end
    end
  end
end

module Woods
  class IndexValidator
    def validate!
      issues = []

      # Check schema version
      current = SchemaVersion.current
      expected = Woods::SCHEMA_VERSION
      if current != expected
        issues << SchemaVersionMismatch.new(current: current, expected: expected)
      end

      # Check embedding dimensions match
      if @vector_store.respond_to?(:dimensions)
        stored_dims = @vector_store.dimensions
        provider_dims = @embedding_provider.dimensions
        if stored_dims != provider_dims
          issues << DimensionMismatch.new(
            stored: stored_dims,
            provider: provider_dims,
            message: "Vector index has #{stored_dims}-dim vectors but embedding provider produces #{provider_dims}-dim. Full re-index required."
          )
        end
      end

      # Check manifest freshness
      manifest = Manifest.load(@output_dir)
      if manifest.nil?
        issues << MissingManifest.new
      elsif manifest.extracted_at < 7.days.ago
        issues << StaleIndex.new(extracted_at: manifest.extracted_at)
      end

      # Check unit counts match between extraction and index
      extracted_count = Dir.glob("#{@output_dir}/**/*.json").count { |f| !f.include?("_index") }
      indexed_count = @metadata_store.count
      if (extracted_count - indexed_count).abs > extracted_count * 0.1
        issues << CountMismatch.new(extracted: extracted_count, indexed: indexed_count)
      end

      ValidationResult.new(valid: issues.empty?, issues: issues)
    end
  end
end

result = Woods.retrieve("how does checkout work?")

result.degraded?           # => true
result.degradation_reason  # => "Vector search unavailable: Qdrant connection refused"
result.tier                # => 2 (keyword + graph only)
result.trace.to_h          # => full diagnostic trace

# For agents, the suggestions field includes degradation info:
result.suggestions
# => ["Results may be incomplete — vector search was unavailable",
#     "Consider retrying after Qdrant is restored",
#     "Keyword-only results may miss semantically related units"]

module Woods
  module Instrumentation
    def self.instrument(event_name, payload = {}, &block)
      if defined?(ActiveSupport::Notifications)
        ActiveSupport::Notifications.instrument("woods.#{event_name}", payload, &block)
      else
        InternalNotifier.instrument(event_name, payload, &block)
      end
    end
  end
end

module Woods
  class RetrievalTrace
    attr_reader :query, :classification, :steps, :started_at, :completed_at

    def initialize(query:, classification:)
      @query = query
      @classification = classification
      @steps = []
      @started_at = Time.now
      @degraded = false
      @degradation_reasons = []
    end

    def record(stage, status, **details)
      @steps << {
        stage: stage,
        status: status,
        timestamp: Time.now,
        duration_ms: details.delete(:duration_ms),
        **details
      }
    end

    def mark_degraded!(reason)
      @degraded = true
      @degradation_reasons << reason
    end

    def complete!
      @completed_at = Time.now
    end

    def total_duration_ms
      ((@completed_at || Time.now) - @started_at) * 1000
    end

    def degraded?
      @degraded
    end

    def to_h
      {
        query: @query,
        classification: @classification,
        started_at: @started_at.iso8601,
        completed_at: @completed_at&.iso8601,
        total_duration_ms: total_duration_ms.round(1),
        degraded: @degraded,
        degradation_reasons: @degradation_reasons,
        steps: @steps.map { |s|
          s.merge(
            elapsed_ms: ((s[:timestamp] - @started_at) * 1000).round(1)
          )
        }
      }
    end

    # Compact summary for logging
    def to_summary
      stages = @steps.map { |s| "#{s[:stage]}:#{s[:status]}" }.join(" → ")
      "query=#{@query.truncate(60)} #{stages} tokens=#{@tokens_used} duration=#{total_duration_ms.round}ms#{' DEGRADED' if @degraded}"
    end
  end
end

{
  "query": "how does checkout work?",
  "classification": {
    "intent": "understand",
    "scope": "focused",
    "target_type": "service",
    "framework_context": false
  },
  "started_at": "2025-02-08T14:30:00.000Z",
  "completed_at": "2025-02-08T14:30:00.247Z",
  "total_duration_ms": 247.3,
  "degraded": false,
  "degradation_reasons": [],
  "steps": [
    {
      "stage": "classification",
      "status": "success",
      "elapsed_ms": 2.1,
      "duration_ms": 2.1
    },
    {
      "stage": "vector_search",
      "status": "success",
      "elapsed_ms": 87.4,
      "duration_ms": 85.3,
      "count": 12,
      "similarity_range": [0.92, 0.61]
    },
    {
      "stage": "keyword_search",
      "status": "success",
      "elapsed_ms": 102.1,
      "duration_ms": 14.7,
      "count": 4,
      "matched_fields": ["id", "method_names"]
    },
    {
      "stage": "graph_expansion",
      "status": "success",
      "elapsed_ms": 118.6,
      "duration_ms": 16.5,
      "count": 8,
      "expanded_from": ["CheckoutService", "Order"],
      "depth": 1
    },
    {
      "stage": "ranking",
      "status": "success",
      "elapsed_ms": 125.2,
      "duration_ms": 6.6,
      "candidates_in": 24,
      "candidates_out": 10,
      "top_score": 0.94,
      "scores": {
        "CheckoutService": 0.94,
        "Order": 0.89,
        "CartService": 0.83,
        "PaymentGateway": 0.78,
        "OrdersController": 0.74
      }
    },
    {
      "stage": "assembly",
      "status": "success",
      "elapsed_ms": 247.0,
      "duration_ms": 121.8,
      "tokens_used": 6841,
      "budget": 8000,
      "sections": {
        "structural": 782,
        "primary": 3420,
        "supporting": 1890,
        "framework": 749
      },
      "sources_included": 7,
      "sources_truncated": 1,
      "sources_dropped": 2
    }
  ]
}

module Woods
  class StructuredLogger
    def initialize(output: $stdout, level: :info)
      @output = output
      @level = level
    end

    def log(level, event, **data)
      return if level_value(level) < level_value(@level)

      entry = {
        timestamp: Time.now.iso8601(3),
        level: level,
        event: "woods.#{event}",
        **data
      }

      @output.puts(entry.to_json)
    end
  end
end

{"timestamp":"2025-02-08T14:30:00.087Z","level":"info","event":"woods.retrieval.vector_search","query":"checkout","candidates":12,"duration_ms":85.3,"store":"qdrant"}
{"timestamp":"2025-02-08T14:30:00.247Z","level":"info","event":"woods.retrieval.completed","query":"checkout","tokens":6841,"sources":7,"duration_ms":247.3,"degraded":false}

{"timestamp":"2025-02-08T14:31:15.003Z","level":"warn","event":"woods.storage.circuit_opened","name":"qdrant","failure_count":5,"last_error":"Connection refused - connect(2) for \"localhost\" port 6333"}
{"timestamp":"2025-02-08T14:31:15.050Z","level":"warn","event":"woods.retrieval.completed","query":"order validation","tokens":2100,"sources":3,"duration_ms":52.1,"degraded":true,"tier":2}

# config/initializers/woods.rb
Woods.configure do |config|
  config.logger = Rails.logger
end

# Subscribe to all Woods events
ActiveSupport::Notifications.subscribe(/^woods\./) do |name, start, finish, id, payload|
  Rails.logger.info("#{name}: #{payload.to_json}")
end

# Or specific events
ActiveSupport::Notifications.subscribe("woods.retrieval.completed") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  StatsD.timing("woods.retrieval", event.duration)
  StatsD.increment("woods.retrieval.degraded") if event.payload[:degraded]
end

ActiveSupport::Notifications.subscribe("woods.retrieval.completed") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  StatsD.distribution("woods.retrieval.duration_ms", event.duration * 1000)
  StatsD.distribution("woods.retrieval.tokens", event.payload[:tokens])
  StatsD.gauge("woods.retrieval.tier", event.payload[:tier])
end

ActiveSupport::Notifications.subscribe("woods.embedding.batch_completed") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  StatsD.increment("woods.embedding.batches")
  StatsD.distribution("woods.embedding.cost", event.payload[:cost_estimate])
end

module Woods
  class HealthCheck
    def check
      results = {}

      results[:vector_store] = check_component("vector_store") { @vector_store.ping }
      results[:metadata_store] = check_component("metadata_store") { @metadata_store.ping }
      results[:graph_store] = check_component("graph_store") { @graph_store.ping }
      results[:embedding_provider] = check_component("embedding_provider") { @embedding_provider.ping }
      results[:index] = check_index_health

      overall = results.values.all? { |r| r[:status] == :ok } ? :healthy : :degraded
      { status: overall, components: results, checked_at: Time.now.iso8601 }
    end

    private

    def check_component(name)
      start = Time.now
      yield
      { status: :ok, latency_ms: ((Time.now - start) * 1000).round(1) }
    rescue StandardError => e
      { status: :error, error: e.message }
    end

    def check_index_health
      validator = IndexValidator.new(@config)
      result = validator.validate!
      {
        status: result.valid? ? :ok : :warn,
        issues: result.issues.map(&:to_s)
      }
    end
  end
end

# Rake task
# rake woods:health

Woods.configure do |config|
  config.vector_store_collection = "codebase_#{ENV['USER']}"
end

# .buildkite/pipeline.yml
steps:
  - label: "Update Index"
    command:
      - bundle exec rake woods:extract
      - bundle exec rake woods:index
    concurrency: 1
    concurrency_group: "woods-update"

module Woods
  module IO
    def self.atomic_write(path, content)
      temp_path = "#{path}.#{Process.pid}.tmp"
      File.write(temp_path, content)
      File.rename(temp_path, path)  # Atomic on POSIX
    rescue StandardError => e
      File.delete(temp_path) if File.exist?(temp_path)
      raise
    end
  end
end

module Woods
  module Storage
    class SqliteAdapter
      def initialize(db_path:)
        @db = SQLite3::Database.new(db_path)
        @db.execute("PRAGMA journal_mode=WAL")
        @db.execute("PRAGMA busy_timeout=5000")  # 5 second wait on lock contention
      end
    end
  end
end

Source code → [Extraction] → JSON units → [Embedding] → Vector store

module Woods
  class ChangeManifest
    MANIFEST_FILE = "_change_manifest.json"

    def initialize(output_dir:)
      @output_dir = Pathname.new(output_dir)
      @changes = { added: [], modified: [], deleted: [], unchanged: [] }
    end

    def record_added(identifier, type:, content_hash:)
      @changes[:added] << { identifier: identifier, type: type, content_hash: content_hash }
    end

    def record_modified(identifier, type:, content_hash:, previous_hash:)
      @changes[:modified] << {
        identifier: identifier,
        type: type,
        content_hash: content_hash,
        previous_hash: previous_hash
      }
    end

    def record_deleted(identifier, type:)
      @changes[:deleted] << { identifier: identifier, type: type }
    end

    def record_unchanged(identifier, type:, content_hash:)
      @changes[:unchanged] << { identifier: identifier, type: type, content_hash: content_hash }
    end

    def write!
      Woods::IO.atomic_write(
        @output_dir.join(MANIFEST_FILE).to_s,
        {
          generated_at: Time.now.iso8601,
          git_sha: current_git_sha,
          previous_git_sha: previous_manifest&.dig(:git_sha),
          summary: {
            added: @changes[:added].size,
            modified: @changes[:modified].size,
            deleted: @changes[:deleted].size,
            unchanged: @changes[:unchanged].size,
            total: @changes.values.sum(&:size)
          },
          changes: @changes
        }.to_json
      )
    end

    def units_needing_embedding
      @changes[:added] + @changes[:modified]
    end

    def units_needing_deletion
      @changes[:deleted]
    end

    private

    def current_git_sha
      stdout, _status = Open3.capture2("git", "rev-parse", "HEAD", chdir: Rails.root.to_s)
      stdout.strip
    rescue StandardError
      "unknown"
    end

    def previous_manifest
      path = @output_dir.join(MANIFEST_FILE)
      return nil unless path.exist?

      JSON.parse(File.read(path), symbolize_names: true)
    rescue JSON::ParserError
      nil
    end
  end
end

module Woods
  class ContentHasher
    def hash_unit(unit)
      # Hash the fields that affect embedding: source code, metadata, dependencies
      content = [
        unit.identifier,
        unit.source_code,
        unit.metadata.to_json,
        unit.dependencies.sort.to_json
      ].join("\n")

      Digest::SHA256.hexdigest(content)
    end
  end
end

module Woods
  module Embedding
    class IncrementalIndexer
      def initialize(pipeline:, output_dir:)
        @pipeline = pipeline
        @manifest = ChangeManifest.load(output_dir)
      end

      def index_changes!
        return full_reindex! if @manifest.nil?

        # Embed new and modified units
        to_embed = @manifest.units_needing_embedding
        if to_embed.any?
          identifiers = to_embed.map { |u| u[:identifier] }
          @pipeline.index_incremental(identifiers)
          Woods.logger.info(
            "Embedded #{identifiers.size} units (#{@manifest.changes[:added].size} added, #{@manifest.changes[:modified].size} modified)"
          )
        end

        # Delete removed units from vector store
        to_delete = @manifest.units_needing_deletion
        if to_delete.any?
          identifiers = to_delete.map { |u| u[:identifier] }
          @pipeline.delete_embeddings(identifiers)
          Woods.logger.info("Deleted embeddings for #{identifiers.size} removed units")
        end

        # Also delete chunk embeddings for modified units (they'll be re-created)
        modified_ids = @manifest.changes[:modified].map { |u| u[:identifier] }
        if modified_ids.any?
          @pipeline.delete_chunk_embeddings(modified_ids)
        end

        EmbeddingResult.new(
          embedded: to_embed.size,
          deleted: to_delete.size,
          skipped: @manifest.changes[:unchanged].size
        )
      end

      private

      def full_reindex!
        Woods.logger.warn("No change manifest found — performing full re-index")
        @pipeline.index_all
      end
    end
  end
end

module Woods
  class TransitiveInvalidator
    def initialize(dependency_graph:, concern_map:)
      @graph = dependency_graph
      @concern_map = concern_map  # { concern_name => [including_model_1, ...] }
    end

    def expand_invalidation(changed_files)
      invalidated = Set.new

      changed_files.each do |file|
        unit = identify_unit(file)
        next unless unit

        invalidated << unit[:identifier]

        # Concern change → invalidate all including models
        if unit[:type] == :concern
          includers = @concern_map[unit[:identifier]] || []
          invalidated.merge(includers)
        end

        # Schema change → invalidate all models on affected tables
        if file.match?(%r{db/migrate/})
          affected_tables = detect_affected_tables(file)
          affected_tables.each do |table|
            models = models_for_table(table)
            invalidated.merge(models)
          end
        end
      end

      invalidated.to_a
    end
  end
end

# In the embedding pipeline
def delete_embeddings(identifiers)
  # Delete unit-level embeddings
  @vector_store.delete(identifiers)

  # Delete chunk-level embeddings
  identifiers.each do |id|
    @vector_store.delete_by_filter({ parent: id, type: "chunk" })
  end

  # Delete from metadata store
  @metadata_store.delete(identifiers)
end

module Woods
  class FileWatcher
    WATCH_PATTERNS = %w[
      app/models/**/*.rb
      app/controllers/**/*.rb
      app/services/**/*.rb
      app/jobs/**/*.rb
      app/mailers/**/*.rb
      app/components/**/*.rb
      app/graphql/**/*.rb
    ].freeze

    def start!
      listener = Listen.to(Rails.root.to_s, only: /\.rb$/) do |modified, added, removed|
        changed = modified + added
        relevant = changed.select { |f| WATCH_PATTERNS.any? { |p| File.fnmatch?(p, f, File::FNM_PATHNAME) } }
        next if relevant.empty?

        Woods.extract_incremental(relevant)
        # Embedding follows automatically via change manifest
        Woods.embed_incremental
      end

      listener.start
    end
  end
end

Requested → Validating → Running → Completed
                ↓                       ↓
             Rejected              Failed

module Woods
  module Operator
    class TaskRunner
      def run_extraction(mode:, extractors: nil, dry_run: false)
        # 1. Validate
        validate_extraction_request!(mode, extractors)

        # 2. Acquire lock
        lock = Coordination::PipelineLock.new
        lock.acquire!(operation: "extraction_#{mode}")

        begin
          # 3. Run
          result = if mode == "full"
            run_full_extraction(extractors: extractors, dry_run: dry_run)
          else
            run_incremental_extraction(dry_run: dry_run)
          end

          # 4. Write change manifest
          result.change_manifest.write! unless dry_run

          # 5. Return structured result
          {
            status: "completed",
            mode: mode,
            units_extracted: result.units.size,
            units_changed: result.changed_count,
            duration_seconds: result.duration,
            git_sha: result.git_sha,
            dry_run: dry_run,
            change_summary: result.change_manifest&.summary
          }
        rescue StandardError => e
          {
            status: "failed",
            mode: mode,
            error: e.message,
            error_class: e.class.name,
            duration_seconds: elapsed_time
          }
        ensure
          lock.release!
        end
      end

      def run_embedding(mode:, identifiers: nil)
        validate_embedding_request!(mode, identifiers)

        lock = Coordination::PipelineLock.new
        lock.acquire!(operation: "embedding_#{mode}")

        begin
          result = if mode == "full"
            @embedding_pipeline.index_all
          else
            indexer = Embedding::IncrementalIndexer.new(
              pipeline: @embedding_pipeline,
              output_dir: @config.output_dir
            )
            indexer.index_changes!
          end

          {
            status: "completed",
            mode: mode,
            units_embedded: result.embedded,
            units_deleted: result.deleted,
            units_skipped: result.skipped,
            duration_seconds: result.duration,
            retry_queue_size: @embedding_pipeline.retry_queue_size
          }
        rescue StandardError => e
          {
            status: "failed",
            mode: mode,
            error: e.message,
            error_class: e.class.name
          }
        ensure
          lock.release!
        end
      end

      private

      def validate_extraction_request!(mode, extractors)
        PipelineGuard.new.allow_extraction?(mode)

        if extractors
          unknown = extractors - Woods.configuration.available_extractors.map(&:to_s)
          raise ArgumentError, "Unknown extractors: #{unknown.join(', ')}" if unknown.any?
        end
      end

      def validate_embedding_request!(mode, identifiers)
        if mode == "incremental" && identifiers.nil?
          # Incremental without identifiers uses change manifest — valid
        end

        if mode == "full"
          PipelineGuard.new.allow_extraction?("full")  # Same cooldown applies
        end
      end
    end
  end
end

module Woods
  module Operator
    class StatusReporter
      def report
        manifest = load_manifest
        health = HealthCheck.new(@config).check

        {
          extraction: extraction_status(manifest),
          embedding: embedding_status,
          index: index_status(manifest),
          health: health[:components].transform_values { |c| c[:status] }
        }
      end

      private

      def extraction_status(manifest)
        return { status: "never_run" } unless manifest

        {
          last_run: manifest[:generated_at],
          mode: manifest[:mode] || "unknown",
          git_sha: manifest[:git_sha],
          units_total: manifest.dig(:summary, :total) || 0,
          units_changed: (manifest.dig(:summary, :added) || 0) +
                         (manifest.dig(:summary, :modified) || 0),
          status: "completed"
        }
      end

      def embedding_status
        {
          units_embedded: @config.build_vector_store.count,
          retry_queue_size: retry_queue_size,
          status: retry_queue_size > 0 ? "has_pending_retries" : "completed"
        }
      rescue StandardError => e
        { status: "error", error: e.message }
      end

      def index_status(manifest)
        current_sha = current_git_sha
        manifest_sha = manifest&.dig(:git_sha)

        staleness = if manifest_sha.nil?
          "never_indexed"
        elsif manifest_sha == current_sha
          "current"
        else
          commits_behind = count_commits_between(manifest_sha, current_sha)
          "#{commits_behind}_commits_behind"
        end

        {
          total_units: count_extracted_units,
          manifest_git_sha: manifest_sha,
          current_git_sha: current_sha,
          staleness: staleness,
          schema_version: SchemaVersion.current
        }
      end

      def count_commits_between(from_sha, to_sha)
        stdout, _status = Open3.capture2(
          "git", "rev-list", "--count", "#{from_sha}..#{to_sha}",
          chdir: Rails.root.to_s
        )
        stdout.strip.to_i
      rescue StandardError
        -1  # Unknown
      end
    end
  end
end

module Woods
  module Operator
    class ErrorEscalator
      RETRYABLE_ERRORS = [
        LockContention,
        RateLimitError,
        Timeout::Error
      ].freeze

      HUMAN_ESCALATION_ERRORS = [
        DimensionMismatch,
        SchemaVersionMismatch,
        CircuitOpenError
      ].freeze

      def classify(error)
        case error
        when *RETRYABLE_ERRORS
          {
            action: :retry,
            message: "Temporary error (#{error.class.name}): #{error.message}",
            max_retries: 3,
            backoff: :exponential
          }
        when *HUMAN_ESCALATION_ERRORS
          {
            action: :escalate,
            message: "Requires human intervention: #{error.message}",
            severity: :high,
            suggested_action: suggest_human_action(error)
          }
        when ExtractionError
          {
            action: :skip_and_continue,
            message: "Extraction error for single unit: #{error.message}",
            severity: :low
          }
        else
          {
            action: :escalate,
            message: "Unexpected error: #{error.class.name}: #{error.message}",
            severity: :medium,
            suggested_action: "Check logs and retry manually"
          }
        end
      end

      private

      def suggest_human_action(error)
        case error
        when DimensionMismatch
          "Embedding dimensions changed. Run: bundle exec rake woods:reindex"
        when SchemaVersionMismatch
          "Schema needs migration. Run: bundle exec rake woods:db:migrate"
        when CircuitOpenError
          "Backend service (#{error.service_name}) is down. Check infrastructure and retry."
        end
      end
    end
  end
end

1. Agent starts a coding task
2. codebase_pipeline_status()
   → staleness: "5_commits_behind"
3. Agent decides to update the index first:
   codebase_extract(mode: "incremental")
   → Result: 12 units changed, 3 added, 1 deleted
4. codebase_embed(mode: "incremental")
   → Result: 15 units embedded, 1 deleted, 1232 skipped
5. Now proceed with retrieval:
   codebase_retrieve("checkout flow")
   → Returns current, accurate context
6. After making code changes:
   codebase_extract(mode: "incremental")
   → Updates index to reflect the agent's own changes
7. Verify:
   codebase_diagnose()
   → All checks pass