woods 1.6.1 → 2.0.0.beta2

data/lib/woods/session_tracer/session_flow_assembler.rb

@@ -24,9 +24,10 @@ module Woods
     #   doc = assembler.assemble("abc123", budget: 8000, depth: 1)
     #   puts doc.to_context
     #
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class SessionFlowAssembler
       ASYNC_TYPES = %w[job mailer].to_set.freeze
+      RENDER_BUDGET_ATTEMPTS = 3
 
       # @param store [Store] Session trace store
       # @param reader [MCP::IndexReader] Index reader for unit lookups
@@ -41,7 +42,7 @@ module Woods
       # @param budget [Integer] Maximum token budget (default: 8000)
       # @param depth [Integer] Expansion depth (0=metadata only, 1=direct deps, 2+=full flow)
       # @return [SessionFlowDocument] The assembled document
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
       def assemble(session_id, budget: 8000, depth: 1)
         requests = @store.read(session_id)
         return empty_document(session_id) if requests.empty?
@@ -77,19 +78,12 @@ module Woods
           step[:unit_refs].concat(deps)
         end
 
-        # Apply token budget
-        token_count = apply_budget(context_pool, budget)
-
-        SessionFlowDocument.new(
-          session_id: session_id,
-          steps: steps,
-          context_pool: context_pool,
-          side_effects: side_effects,
-          dependency_map: dependency_map,
-          token_count: token_count
-        )
+        # Apply token budget against the rendered output, not just the pool
+        apply_budget(context_pool, budget)
+        parts = { session_id: session_id, steps: steps, context_pool: context_pool,
+                  side_effects: side_effects, dependency_map: dependency_map }
+        budgeted_document(parts, budget)
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
 
       private
 
@@ -115,7 +109,7 @@ module Woods
       # Resolve dependencies for a unit, separating sync deps from async side effects.
       #
       # @return [Array<String>] Non-async dependency identifiers added
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
       def resolve_dependencies(unit_id, seen_units, context_pool,
                                side_effects, step, dependency_map, depth)
         graph = @reader.dependency_graph
@@ -154,7 +148,6 @@ module Woods
 
         added
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
 
       # Expand transitive dependencies (depth 2+).
       #
@@ -241,6 +234,54 @@ module Woods
         end
       end
 
+      # The budget target is the RENDERED document: the steps timeline, side
+      # effects, dependency map, and markup all cost tokens the pool estimate
+      # never counted, so a document could ship over budget while reporting a
+      # compliant token_count. Measure to_context, tighten the source pool by
+      # the observed overshoot, and re-measure; when nothing truncatable
+      # remains, ship the floor flagged budget_exceeded instead of silently
+      # over budget.
+      def budgeted_document(parts, budget)
+        rendered = rendered_tokens(parts)
+        (RENDER_BUDGET_ATTEMPTS - 1).times do
+          break if rendered <= budget
+          break unless shrink_source_pool?(parts[:context_pool], budget, rendered)
+
+          rendered = rendered_tokens(parts)
+        end
+
+        SessionFlowDocument.new(**parts, token_count: rendered, budget_exceeded: rendered > budget)
+      end
+
+      # to_context embeds the token count itself, so measure to a fixpoint:
+      # the reported number must be the measure of the document printing it.
+      def rendered_tokens(parts)
+        count = 0
+        3.times do
+          probe = SessionFlowDocument.new(**parts, token_count: count)
+          measured = TokenUtils.estimate_tokens(probe.to_context)
+          return measured if measured == count
+
+          count = measured
+        end
+        count
+      end
+
+      # Tighten the source-pool budget by the measured structural overshoot.
+      # Returns false when no truncatable source remains — the floor.
+      def shrink_source_pool?(context_pool, budget, rendered)
+        return false unless context_pool.values.any? { |unit| truncatable_source?(unit) }
+
+        overshoot = rendered - budget
+        apply_budget(context_pool, [estimate_tokens(context_pool) - overshoot, 0].max)
+        true
+      end
+
+      def truncatable_source?(unit)
+        source = unit[:source_code]
+        source && !source.start_with?('# source truncated')
+      end
+
       # Build an empty document for sessions with no requests.
       #
       # @param session_id [String]
@@ -249,6 +290,5 @@ module Woods
         SessionFlowDocument.new(session_id: session_id)
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/woods/session_tracer/session_flow_document.rb

@@ -23,7 +23,7 @@ module Woods
     #   doc.to_markdown   # => human-readable document
     #   doc.to_context    # => LLM XML format
     #
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class SessionFlowDocument
       attr_reader :session_id, :steps, :context_pool, :side_effects,
                   :dependency_map, :token_count, :generated_at
@@ -33,20 +33,28 @@ module Woods
       # @param context_pool [Hash<String, Hash>] Deduplicated unit data keyed by identifier
       # @param side_effects [Array<Hash>] Async side effects (jobs, mailers)
       # @param dependency_map [Hash<String, Array<String>>] Unit -> dependency identifiers
-      # @param token_count [Integer] Estimated total tokens
+      # @param token_count [Integer] Estimated tokens of the rendered context output
+      # @param budget_exceeded [Boolean] True when even the fully-truncated
+      #   rendering exceeds the requested budget, so callers see an honest
+      #   flag instead of a silently over-budget document
       # @param generated_at [String, nil] ISO8601 timestamp (defaults to now)
-      # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable-next Metrics/ParameterLists
       def initialize(session_id:, steps: [], context_pool: {}, side_effects: [],
-                     dependency_map: {}, token_count: 0, generated_at: nil)
+                     dependency_map: {}, token_count: 0, budget_exceeded: false, generated_at: nil)
         @session_id = session_id
         @steps = steps
         @context_pool = context_pool
         @side_effects = side_effects
         @dependency_map = dependency_map
         @token_count = token_count
+        @budget_exceeded = budget_exceeded
         @generated_at = generated_at || Time.now.utc.iso8601
       end
-      # rubocop:enable Metrics/ParameterLists
+
+      # @return [Boolean]
+      def budget_exceeded?
+        @budget_exceeded ? true : false
+      end
 
       # Serialize to a JSON-compatible Hash.
       #
@@ -56,6 +64,7 @@ module Woods
           session_id: @session_id,
           generated_at: @generated_at,
           token_count: @token_count,
+          budget_exceeded: budget_exceeded?,
           steps: @steps,
           context_pool: @context_pool,
           side_effects: @side_effects,
@@ -79,6 +88,7 @@ module Woods
           side_effects: data[:side_effects] || [],
           dependency_map: data[:dependency_map] || {},
           token_count: data[:token_count] || 0,
+          budget_exceeded: data.fetch(:budget_exceeded, false),
           generated_at: data[:generated_at]
         )
       end
@@ -86,7 +96,7 @@ module Woods
       # Render as human-readable Markdown.
       #
       # @return [String]
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       def to_markdown
         lines = []
         lines << "## Session: #{@session_id}"
@@ -146,17 +156,16 @@ module Woods
 
         lines.join("\n")
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
       # Render as LLM-consumable XML context.
       #
-      # Follows the format from docs/CONTEXT_AND_CHUNKING.md.
+      # Follows the format from `git log --follow -- docs/design/CONTEXT_AND_CHUNKING.md`.
       #
       # @return [String]
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       def to_context
         lines = []
-        header = "<session_context session_id=\"#{@session_id}\" requests=\"#{@steps.size}\" " \
+        header = "<session_context session_id=\"#{escape_attribute(@session_id)}\" requests=\"#{@steps.size}\" " \
                  "tokens=\"#{@token_count}\" units=\"#{@context_pool.size}\">"
         lines << header
 
@@ -175,8 +184,10 @@ module Woods
         @context_pool.each do |identifier, unit|
           type = unit[:type] || 'unknown'
           file_path = unit[:file_path] || 'unknown'
-          lines << %(<unit identifier="#{identifier}" type="#{type}" file="#{file_path}">)
-          lines << (unit[:source_code] || '# source not available')
+          tag = %(<unit identifier="#{escape_attribute(identifier)}" type="#{escape_attribute(type)}" ) \
+                "file=\"#{escape_attribute(file_path)}\">"
+          lines << tag
+          lines << escape_content(unit[:source_code] || '# source not available')
           lines << '</unit>'
         end
 
@@ -201,7 +212,39 @@ module Woods
         lines << '</session_context>'
         lines.join("\n")
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      private
+
+      # Escape a value for use inside a double-quoted attribute in
+      # {#to_context}'s markup.
+      #
+      # This is prompt-injection hardening, not XML conformance: `session_id`
+      # comes from the client-controlled X-Trace-Session header, and unit
+      # identifiers/paths flow through from extracted code. Unescaped, a
+      # crafted value (e.g. `"><injected_tag>`) breaks out of the attribute
+      # and inserts sibling markup into context an LLM later reads as trusted
+      # structure.
+      #
+      # @param value [Object]
+      # @return [String]
+      def escape_attribute(value)
+        value.to_s
+             .gsub('&', '&amp;')
+             .gsub('"', '&quot;')
+             .gsub('<', '&lt;')
+             .gsub('>', '&gt;')
+      end
+
+      # Escape a value for use as element content (between tags) in
+      # {#to_context}'s markup. Same prompt-injection motivation as
+      # {#escape_attribute}; content only needs `&` and `<` escaped since
+      # there's no attribute quote to break out of.
+      #
+      # @param value [Object]
+      # @return [String]
+      def escape_content(value)
+        value.to_s.gsub('&', '&amp;').gsub('<', '&lt;')
+      end
 
       # @api private
       def self.deep_symbolize_keys(obj)
@@ -218,6 +261,5 @@ module Woods
       end
       private_class_method :deep_symbolize_keys
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/woods/session_tracer/solid_cache_coordination.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'active_support/cache'
+require 'securerandom'
+
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module SessionTracer
+    # Uncached, per-key routed coordination operations for Solid Cache 1.0.
+    class SolidCacheCoordination # rubocop:disable Metrics/ClassLength
+      FAILURE = Object.new.freeze
+
+      class BackendError < Woods::Error; end
+
+      def initialize(cache)
+        @cache = cache
+      end
+
+      def read(name, options = nil)
+        with_operation(:read, name, options) do |key, merged_options, event|
+          raw = routed_read(key, :read_entry)
+          entry = @cache.send(:deserialize_entry, raw, **merged_options)
+          if entry&.expired?
+            delete_expired_entry(key, raw)
+            entry = nil
+          end
+          event[:hit] = !entry.nil? if event
+          entry&.value
+        end
+      rescue ActiveSupport::Cache::DeserializationError
+        nil
+      end
+
+      def write(name, value, **options)
+        with_operation(:write, name, options) do |key, merged_options, _event|
+          entry = cache_entry(name, value, merged_options)
+          payload = @cache.send(:serialize_entry, entry, **merged_options)
+          result = @cache.send(:entry_write, key, payload)
+          backend_result!(result, :write, name, nil_is_failure: true)
+        end
+      end
+
+      def delete(name, options = nil)
+        with_operation(:delete, name, options) do |key, _merged_options, _event|
+          routed_delete(key, :delete_entry).positive?
+        end
+      end
+
+      def increment(name, amount = 1, options = nil)
+        with_operation(:increment, name, options, amount: amount) do |key, merged_options, _event|
+          payload = @cache.send(:entry_lock_and_write, key) do |raw|
+            entry = @cache.send(:adjusted_entry, raw, amount, merged_options)
+            @cache.send(:serialize_entry, entry, **merged_options)
+          end
+          backend_result!(payload, :increment, name, nil_is_failure: true)
+          @cache.send(:deserialize_entry, payload, **merged_options).value
+        end
+      end
+
+      def write_if_absent(name, value, **options)
+        with_operation(:write, name, options) do |key, merged_options, _event|
+          entry = cache_entry(name, value, merged_options, version: "woods-cas:#{SecureRandom.hex(16)}")
+          payload = @cache.send(:serialize_entry, entry, **merged_options)
+          result = routed_write(key, :write_entry) do
+            entry_class = ::SolidCache::Entry
+            inserted = attempt_insert?(entry_class, key, payload)
+            if !inserted && clear_expired_entry?(entry_class, key, merged_options)
+              inserted = attempt_insert?(entry_class, key, payload)
+            end
+            @cache.send(:track_writes, 1) if inserted
+            inserted
+          end
+          backend_result!(result, :write_if_absent, name)
+        end
+      end
+
+      def delete_if_equal(name, expected)
+        with_operation(:delete, name, nil) do |key, merged_options, _event|
+          result = routed_write(key, :delete_entry) do
+            locked_compare_and_delete(key) do |raw_value|
+              entry = @cache.send(:deserialize_entry, raw_value, **merged_options)
+              entry && !entry.expired? && entry.value == expected
+            end
+          end
+          backend_result!(result, :delete_if_equal, name)
+        end
+      end
+
+      private
+
+      def with_operation(operation, name, options, event_options = nil)
+        merged_options = @cache.send(:merged_options, options)
+        key = @cache.send(:normalize_key, name, merged_options)
+        instrument_options = event_options || merged_options
+
+        @cache.send(:bypass_local_cache) do
+          @cache.send(:instrument, operation, key, instrument_options) do |event|
+            yield key, merged_options, event
+          end
+        end
+      rescue NoMethodError => e
+        raise BackendError,
+              "Solid Cache private API unavailable for #{operation} #{name.inspect} (#{e.message}); " \
+              'this Solid Cache version is not supported by Woods session tracing'
+      end
+
+      # Row-locked compare-and-delete on the raw stored payload. The block
+      # decides against the exact bytes read under lock, so a concurrent
+      # replacement can never be deleted by mistake.
+      def locked_compare_and_delete(key)
+        entry_class = ::SolidCache::Entry
+        key_hash = entry_class.send(:key_hash_for, key)
+        entry_class.transaction do
+          raw_key, raw_value = entry_class.lock.where(key_hash: key_hash).pick(:key, :value)
+          next false unless raw_key == key
+          next false unless yield(raw_value)
+
+          entry_class.delete_by_key(key)
+          true
+        end
+      end
+
+      # Conditionally remove an expired entry observed by a read: only the
+      # exact expired payload is deleted, never a fresh replacement.
+      def delete_expired_entry(key, observed_raw)
+        routed_write(key, :delete_entry) do
+          locked_compare_and_delete(key) { |raw_value| raw_value == observed_raw }
+        end
+      end
+
+      def attempt_insert?(entry_class, key, payload)
+        inserted?(entry_class, insert_entry(entry_class, key, payload), key, payload)
+      end
+
+      # Treat a physically-present but logically-expired row as absent for
+      # conditional writes by conditionally removing the exact expired payload.
+      def clear_expired_entry?(entry_class, key, merged_options)
+        raw = entry_class.read(key)
+        return false unless raw
+
+        entry = @cache.send(:deserialize_entry, raw, **merged_options)
+        return false unless entry&.expired?
+
+        locked_compare_and_delete(key) { |raw_value| raw_value == raw }
+      rescue ActiveSupport::Cache::DeserializationError
+        false
+      end
+
+      def cache_entry(name, value, options, version: @cache.send(:normalize_version, name, options))
+        ActiveSupport::Cache::Entry.new(value, **options, version: version)
+      end
+
+      def insert_entry(entry_class, key, payload)
+        attributes = entry_class.send(:add_key_hash_and_byte_size, [{ key: key, value: payload }])
+        entry_class.insert_all(attributes, unique_by: entry_class.send(:upsert_unique_by))
+      end
+
+      def inserted?(entry_class, result, key, payload)
+        affected_rows = result.affected_rows if result.respond_to?(:affected_rows)
+        return affected_rows.positive? unless affected_rows.nil?
+        return result.rows.any? if entry_class.connection.supports_insert_returning?
+
+        entry_class.read(key) == payload
+      end
+
+      def routed_read(key, failsafe)
+        result = @cache.send(:reading_key, key, failsafe: failsafe, failsafe_returning: FAILURE) do
+          ::SolidCache::Entry.read(key)
+        end
+        backend_result!(result, :read, key)
+      end
+
+      def routed_write(key, failsafe, &block)
+        @cache.send(:writing_key, key, failsafe: failsafe, failsafe_returning: FAILURE, &block)
+      end
+
+      def routed_delete(key, failsafe)
+        result = routed_write(key, failsafe) { ::SolidCache::Entry.delete_by_key(key) }
+        backend_result!(result, :delete, key)
+      end
+
+      def backend_result!(result, operation, key, nil_is_failure: false)
+        failed = result.equal?(FAILURE) || (nil_is_failure && result.nil?)
+        return result unless failed
+
+        raise BackendError,
+              "Solid Cache routed #{operation} failed for #{key.inspect}; inspect the cache backend error handler"
+      end
+    end
+  end
+end