lex-subliminal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 942de14ddf12c8a592ed87370978cd88ed2e6e239c67cdcce276b80d59aaa76f
+  data.tar.gz: fead526f92b11f15af80d1d21ce18c6065c2f8c319389e3a684f9e13a2a79363
+SHA512:
+  metadata.gz: ed24c0d2f0e071cfa8e5f27d00f9a4bc0de45fc652309b319c3b9c0dcc11022e30e2689e097a9ccd1129773ed9affceba65a1d3b398962217d13c27a957cbd6c
+  data.tar.gz: 948dbd1b4733e98618010563ca944670348dbb300d86a5a24aa60fa5d26c031aad2ed05520795fb6a7694e047b024186ec92eebf0f60780b3c328bdbc5bc76a7

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,10 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+pkg
+spec/reports
+tmp
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--order random

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*
+
+Style/OneClassPerFile:
+  Exclude:
+    - spec/spec_helper.rb

data/CLAUDE.md

@@ -0,0 +1,120 @@
+# lex-subliminal
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-subliminal`
+- **Version**: `0.1.0`
+- **Namespace**: `Legion::Extensions::Subliminal`
+
+## Purpose
+
+Models subliminal (below-threshold) influences on cognition. Subliminal traces carry an activation level that is structurally prevented from reaching the conscious threshold — they cannot be consciously attended to, but they exert a measurable influence on named cognitive targets (attention, memory, decision, emotion, etc.). Traces decay over time; those that fall to near-zero are extinct. Useful for modeling background priming, emotional contagion, implicit learning, and attentional drift.
+
+## Gem Info
+
+- **Gem name**: `lex-subliminal`
+- **License**: MIT
+- **Ruby**: >= 3.4
+- **No runtime dependencies** beyond the Legion framework
+
+## File Structure
+
+```
+lib/legion/extensions/subliminal/
+  version.rb                        # VERSION = '0.1.0'
+  helpers/
+    constants.rb                    # thresholds, decay rates, influence strength, max caps, type/target lists, labels
+    subliminal_trace.rb             # SubliminalTrace class — single below-threshold activation trace
+    subliminal_engine.rb            # SubliminalEngine class — collection with bulk influence processing
+  runners/
+    subliminal.rb                   # Runners::Subliminal module — all public runner methods
+  client.rb                         # Client class including Runners::Subliminal
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `CONSCIOUS_THRESHOLD` | 0.4 | The threshold subliminal traces are prevented from reaching |
+| `SUBLIMINAL_CEILING` | 0.39 | Hard cap on trace activation (just below CONSCIOUS_THRESHOLD) |
+| `SUBLIMINAL_FLOOR` | 0.02 | Minimum activation before approaching extinction |
+| `EXTINCTION_THRESHOLD` | 0.01 | At or below this, trace is considered extinct |
+| `DEFAULT_ACTIVATION` | 0.2 | Starting activation for new traces |
+| `ACTIVATION_BOOST` | 0.08 | Activation increase per `boost!` call |
+| `ACTIVATION_DECAY` | 0.015 | Per-tick activation decrease |
+| `INFLUENCE_STRENGTH` | 0.05 | Magnitude multiplier: `activation * INFLUENCE_STRENGTH` |
+| `MAX_INFLUENCE_PER_DOMAIN` | 0.3 | Maximum total influence on any single domain |
+| `MAX_TOTAL_INFLUENCE` | 0.5 | Maximum combined influence across all targets |
+| `TRACE_TYPES` | 8 symbols | `:priming`, `:emotional`, `:procedural`, `:semantic`, `:inhibitory`, `:motivational`, `:contextual`, `:evaluative` |
+| `INFLUENCE_TARGETS` | 8 symbols | `:attention`, `:memory`, `:decision`, `:emotion`, `:action`, `:perception`, `:language`, `:reasoning` |
+
+## Helpers
+
+### `Helpers::SubliminalTrace`
+
+Single below-threshold activation trace.
+
+- `initialize(id:, content:, trace_type:, domain: :general, target: :attention, activation: DEFAULT_ACTIVATION)` — clamps activation to SUBLIMINAL_CEILING on init
+- `boost!(amount = ACTIVATION_BOOST)` — increments activation; hard-clamps to SUBLIMINAL_CEILING (never reaches CONSCIOUS_THRESHOLD)
+- `decay!` — decrements activation by ACTIVATION_DECAY; floors at 0.0
+- `exert_influence!` — decrements activation slightly, returns `influence_magnitude`
+- `influence_magnitude` — `activation * INFLUENCE_STRENGTH`
+- `near_threshold?` — activation between 0.3 and 0.39
+- `active?` — activation > EXTINCTION_THRESHOLD
+- `extinct?` — activation <= EXTINCTION_THRESHOLD
+- `potent?` — activation >= 0.2
+- `breached_threshold?` — activation >= 0.4 (anomaly: should never occur due to ceiling, logged if detected)
+- `activation_label` — `:extinct`, `:faint`, `:weak`, `:moderate`, `:strong` based on activation
+
+### `Helpers::SubliminalEngine`
+
+Collection of SubliminalTrace objects with bulk influence processing.
+
+- `initialize` — traces hash, keyed by trace id
+- `create_trace(content:, trace_type:, domain: :general, target: :attention, activation: DEFAULT_ACTIVATION)` — rejects invalid types/targets; appends trace
+- `boost_trace(trace_id, amount: ACTIVATION_BOOST)` — calls `trace.boost!`
+- `process_influences!` — all active traces call `exert_influence!`; generates InfluenceEvent objects per trace; returns events array
+- `decay_all!` — decays all traces; removes extinct ones
+- `active_traces` — all with `active? == true`
+- `near_threshold_traces` — all with `near_threshold? == true`
+- `potent_traces` — all with `potent? == true`
+- `traces_by_domain(domain)` — filter by domain
+- `traces_by_type(trace_type)` — filter by trace_type
+- `traces_by_target(target)` — filter by influence target
+- `influence_on(target:)` — sum of influence_magnitude across all active traces targeting `target`; capped at MAX_INFLUENCE_PER_DOMAIN
+- `domain_saturation(domain)` — total influence magnitude across all traces in domain
+- `overall_subliminal_load` — sum of all active trace activations; capped at MAX_TOTAL_INFLUENCE
+- `strongest_traces(limit: 5)` — sorted by activation descending
+- `breached_traces` — any traces with `breached_threshold? == true` (anomaly detection)
+- `subliminal_report` — summary: trace counts, overall load, influence per target, near-threshold count
+
+## Runners
+
+All runners are in `Runners::Subliminal`. The `Client` includes this module. Note: the runner uses `@default_engine` internally (not `@engine`).
+
+| Runner | Parameters | Returns |
+|---|---|---|
+| `create_subliminal_trace` | `content:, trace_type:, domain: :general, target: :attention, activation: DEFAULT_ACTIVATION` | `{ success:, trace_id:, activation:, trace_type: }` |
+| `boost_trace` | `trace_id:, amount: ACTIVATION_BOOST` | `{ success:, trace_id:, activation: }` |
+| `process_influences` | (none) | `{ success:, events:, count: }` — runs `process_influences!` |
+| `decay_all` | (none) | `{ success:, active_count:, removed_count: }` |
+| `active_traces` | (none) | `{ success:, traces:, count: }` |
+| `near_threshold` | (none) | `{ success:, traces:, count: }` — traces approaching conscious threshold |
+| `influence_on` | `target:` | `{ success:, target:, influence: }` |
+| `subliminal_status` | (none) | Full `SubliminalEngine#subliminal_report` hash |
+
+## Integration Points
+
+- **lex-tick / lex-cortex**: `process_influences` wired as a tick phase handler to apply subliminal influence each cycle; influence events can be forwarded to target extensions (e.g., influence on `:attention` biases the sensory gating thresholds)
+- **lex-sensory-gating**: subliminal influence on `:perception` can modulate gate thresholds without the agent's explicit awareness
+- **lex-emotion**: `:emotional` trace type targeting `:emotion` models emotional contagion and implicit mood induction
+- **lex-dream**: dream consolidation may create subliminal traces from unresolved material; `:contextual` traces targeting `:decision` model incubation effects
+- **lex-semantic-priming**: near-threshold traces can trigger priming events when their target aligns with active concept nodes
+
+## Development Notes
+
+- `SUBLIMINAL_CEILING = 0.39` is a hard cap enforced in both `initialize` and `boost!` — traces structurally cannot reach CONSCIOUS_THRESHOLD, making the subliminal/conscious boundary a guaranteed architectural constraint
+- `breached_threshold?` >= 0.4 should never trigger in normal operation; it is an anomaly detection flag
+- `process_influences!` slightly decrements activation on each call — sustained influence gradually weakens the trace
+- `@default_engine` naming (vs `@engine`) is specific to this runner module; specs and injection must reference `@default_engine`
+- InfluenceEvent objects from `process_influences!` are plain structs (trace_id, target, magnitude, domain) — callers can route them to downstream handlers by target

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75'
+gem 'rubocop-rspec'
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,66 @@
+# lex-subliminal
+
+Subliminal influence modeling for LegionIO cognitive agents. Traces operate below the conscious threshold but exert measurable influence on attention, memory, decision-making, and emotion.
+
+## What It Does
+
+`lex-subliminal` maintains a set of activation traces that are structurally capped below the conscious threshold (0.39 max, threshold at 0.4). These traces cannot be consciously attended to but exert influence on named cognitive targets each tick. Traces decay over time; those that reach near-zero are extinct.
+
+- **Trace types**: `:priming`, `:emotional`, `:procedural`, `:semantic`, `:inhibitory`, `:motivational`, `:contextual`, `:evaluative`
+- **Influence targets**: `:attention`, `:memory`, `:decision`, `:emotion`, `:action`, `:perception`, `:language`, `:reasoning`
+- **Activation ceiling**: 0.39 — structurally enforced; traces can never breach conscious threshold
+- **Influence magnitude**: `activation * 0.05` per trace per tick
+- **Potent traces**: activation >= 0.2; near-threshold traces: activation 0.3–0.39
+
+## Usage
+
+```ruby
+require 'legion/extensions/subliminal'
+
+client = Legion::Extensions::Subliminal::Client.new
+
+# Create a subliminal trace
+result = client.create_subliminal_trace(
+  content: 'unresolved conflict',
+  trace_type: :emotional,
+  domain: :relationships,
+  target: :decision,
+  activation: 0.25
+)
+trace_id = result[:trace_id]
+
+# Boost a trace (activation can never exceed 0.39)
+client.boost_trace(trace_id: trace_id, amount: 0.08)
+
+# Process influences (called each tick)
+client.process_influences
+# => { events: [{ target: :decision, magnitude: 0.017, ... }], count: 1 }
+
+# Check influence on a specific target
+client.influence_on(target: :decision)
+# => { target: :decision, influence: 0.017 }
+
+# Near-threshold traces (approaching conscious awareness)
+client.near_threshold
+# => { traces: [...], count: 0 }
+
+# Decay all traces
+client.decay_all
+# => { active_count: 1, removed_count: 0 }
+
+# Full status report
+client.subliminal_status
+# => { trace_count:, active_count:, overall_load:, influence_per_target: { ... }, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-subliminal.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/subliminal/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-subliminal'
+  spec.version       = Legion::Extensions::Subliminal::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'Subliminal activation and below-threshold influence for LegionIO agents'
+  spec.description   = 'Models below-threshold cognitive traces that influence behavior ' \
+                       'without reaching conscious awareness in the LegionIO architecture'
+  spec.homepage      = 'https://github.com/LegionIO/lex-subliminal'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata = {
+    'homepage_uri'          => spec.homepage,
+    'source_code_uri'       => spec.homepage,
+    'documentation_uri'     => "#{spec.homepage}/blob/origin/README.md",
+    'changelog_uri'         => "#{spec.homepage}/blob/origin/CHANGELOG.md",
+    'bug_tracker_uri'       => "#{spec.homepage}/issues",
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/subliminal/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Subliminal
+      class Client
+        include Runners::Subliminal
+
+        def initialize
+          @default_engine = Helpers::SubliminalEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/subliminal/helpers/constants.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Subliminal
+      module Helpers
+        module Constants
+          MAX_TRACES = 500
+          MAX_INFLUENCES = 1000
+
+          # Threshold boundaries
+          CONSCIOUS_THRESHOLD = 0.4
+          SUBLIMINAL_CEILING = 0.39
+          SUBLIMINAL_FLOOR = 0.02
+          EXTINCTION_THRESHOLD = 0.01
+
+          # Dynamics
+          DEFAULT_ACTIVATION = 0.2
+          ACTIVATION_BOOST = 0.08
+          ACTIVATION_DECAY = 0.015
+          INFLUENCE_STRENGTH = 0.05
+          ACCUMULATION_RATE = 0.03
+
+          # Influence caps
+          MAX_INFLUENCE_PER_DOMAIN = 0.3
+          MAX_TOTAL_INFLUENCE = 0.5
+
+          TRACE_TYPES = %i[
+            perceptual emotional associative procedural
+            semantic motivational aversive appetitive
+          ].freeze
+
+          INFLUENCE_TARGETS = %i[
+            attention emotion decision memory
+            preference avoidance approach valence
+          ].freeze
+
+          ACTIVATION_LABELS = {
+            (0.3...0.4)  => :near_threshold,
+            (0.2...0.3)  => :moderate,
+            (0.1...0.2)  => :faint,
+            (0.02...0.1) => :trace,
+            (..0.02)     => :extinct
+          }.freeze
+
+          INFLUENCE_LABELS = {
+            (0.2..)       => :strong,
+            (0.1...0.2)   => :moderate,
+            (0.05...0.1)  => :subtle,
+            (0.01...0.05) => :minimal,
+            (..0.01)      => :none
+          }.freeze
+
+          SATURATION_LABELS = {
+            (0.8..)     => :saturated,
+            (0.6...0.8) => :heavy,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :light,
+            (..0.2)     => :clear
+          }.freeze
+
+          def self.label_for(labels, value)
+            labels.each { |range, label| return label if range.cover?(value) }
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/subliminal/helpers/influence_event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Subliminal
+      module Helpers
+        class InfluenceEvent
+          include Constants
+
+          attr_reader :id, :trace_id, :target, :magnitude, :domain, :created_at
+
+          def initialize(trace_id:, target:, magnitude:, domain: :general)
+            @id = SecureRandom.uuid
+            @trace_id = trace_id
+            @target = target.to_sym
+            @magnitude = magnitude.to_f.clamp(0.0, MAX_INFLUENCE_PER_DOMAIN).round(10)
+            @domain = domain.to_sym
+            @created_at = Time.now
+          end
+
+          def significant? = @magnitude >= 0.05
+          def subtle? = @magnitude < 0.05 && @magnitude > 0.0
+
+          def to_h
+            {
+              id:         @id,
+              trace_id:   @trace_id,
+              target:     @target,
+              magnitude:  @magnitude,
+              domain:     @domain,
+              created_at: @created_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/subliminal/helpers/subliminal_engine.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Subliminal
+      module Helpers
+        class SubliminalEngine
+          include Constants
+
+          def initialize
+            @traces = {}
+            @influences = []
+          end
+
+          def create_trace(content:, trace_type: :associative, domain: :general, activation: DEFAULT_ACTIVATION,
+                           influence_target: :attention)
+            prune_extinct
+            trace = SubliminalTrace.new(content: content, trace_type: trace_type, domain: domain,
+                                        activation: activation, influence_target: influence_target)
+            @traces[trace.id] = trace
+            trace
+          end
+
+          def boost_trace(trace_id:, amount: ACTIVATION_BOOST)
+            trace = @traces[trace_id]
+            return nil unless trace
+
+            trace.boost!(amount: amount)
+            trace
+          end
+
+          def process_influences!
+            active = active_traces
+            events = []
+            active.each do |trace|
+              mag = trace.exert_influence!
+              next if mag <= 0.0
+
+              event = InfluenceEvent.new(trace_id: trace.id, target: trace.influence_target,
+                                         magnitude: mag, domain: trace.domain)
+              events << event
+              @influences << event
+            end
+            prune_influences
+            { influences_generated: events.size, events: events.map(&:to_h) }
+          end
+
+          def decay_all!
+            @traces.each_value(&:decay!)
+            prune_extinct
+            { traces_remaining: @traces.size }
+          end
+
+          def active_traces = @traces.values.select(&:active?)
+          def near_threshold_traces = @traces.values.select(&:near_threshold?)
+          def potent_traces = @traces.values.select(&:potent?)
+          def extinct_traces = @traces.values.select(&:extinct?)
+
+          def traces_by_domain(domain:)
+            @traces.values.select { |t| t.domain == domain.to_sym }
+          end
+
+          def traces_by_type(trace_type:)
+            @traces.values.select { |t| t.trace_type == trace_type.to_sym }
+          end
+
+          def traces_by_target(target:)
+            @traces.values.select { |t| t.influence_target == target.to_sym }
+          end
+
+          def influence_on(target:)
+            recent = @influences.last(100).select { |e| e.target == target.to_sym }
+            return 0.0 if recent.empty?
+
+            recent.sum(&:magnitude).clamp(0.0, MAX_TOTAL_INFLUENCE).round(10)
+          end
+
+          def domain_saturation(domain:)
+            domain_traces = traces_by_domain(domain: domain)
+            return 0.0 if domain_traces.empty?
+
+            total_activation = domain_traces.sum(&:activation)
+            (total_activation / (domain_traces.size * SUBLIMINAL_CEILING)).clamp(0.0, 1.0).round(10)
+          end
+
+          def overall_subliminal_load
+            return 0.0 if @traces.empty?
+
+            active = active_traces
+            return 0.0 if active.empty?
+
+            (active.sum(&:activation) / (active.size * SUBLIMINAL_CEILING)).clamp(0.0, 1.0).round(10)
+          end
+
+          def saturation_label = Constants.label_for(SATURATION_LABELS, overall_subliminal_load)
+
+          def strongest_traces(limit: 5) = @traces.values.sort_by { |t| -t.activation }.first(limit)
+
+          def breached_traces
+            @traces.values.select(&:breached_threshold?)
+          end
+
+          def subliminal_report
+            {
+              total_traces:     @traces.size,
+              active_count:     active_traces.size,
+              near_threshold:   near_threshold_traces.size,
+              potent_count:     potent_traces.size,
+              total_influences: @influences.size,
+              subliminal_load:  overall_subliminal_load,
+              saturation_label: saturation_label,
+              breached_count:   breached_traces.size,
+              strongest:        strongest_traces(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_traces:     @traces.size,
+              active:           active_traces.size,
+              subliminal_load:  overall_subliminal_load,
+              total_influences: @influences.size
+            }
+          end
+
+          private
+
+          def prune_extinct
+            return if @traces.size < MAX_TRACES
+
+            @traces.reject! { |_, t| t.extinct? }
+            return unless @traces.size >= MAX_TRACES
+
+            weakest = @traces.values.min_by(&:activation)
+            @traces.delete(weakest.id) if weakest
+          end
+
+          def prune_influences
+            @influences.shift while @influences.size > MAX_INFLUENCES
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/subliminal/helpers/subliminal_trace.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Subliminal
+      module Helpers
+        class SubliminalTrace
+          include Constants
+
+          attr_reader :id, :content, :trace_type, :domain, :original_activation,
+                      :influence_target, :created_at, :influence_count
+          attr_accessor :activation
+
+          def initialize(content:, trace_type: :associative, domain: :general, activation: DEFAULT_ACTIVATION,
+                         influence_target: :attention)
+            @id = SecureRandom.uuid
+            @content = content.to_s
+            @trace_type = valid_trace_type(trace_type)
+            @domain = domain.to_sym
+            @activation = activation.to_f.clamp(SUBLIMINAL_FLOOR, SUBLIMINAL_CEILING).round(10)
+            @original_activation = @activation
+            @influence_target = valid_influence_target(influence_target)
+            @influence_count = 0
+            @created_at = Time.now
+          end
+
+          def boost!(amount: ACTIVATION_BOOST)
+            @activation = (@activation + amount).clamp(0.0, SUBLIMINAL_CEILING).round(10)
+            self
+          end
+
+          def decay!
+            @activation = (@activation - ACTIVATION_DECAY).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def exert_influence!
+            @influence_count += 1
+            @activation = (@activation - (INFLUENCE_STRENGTH * 0.5)).clamp(0.0, 1.0).round(10)
+            influence_magnitude
+          end
+
+          def influence_magnitude
+            (@activation * INFLUENCE_STRENGTH).clamp(0.0, MAX_INFLUENCE_PER_DOMAIN).round(10)
+          end
+
+          def near_threshold? = @activation >= 0.3 && @activation < CONSCIOUS_THRESHOLD
+          def active? = @activation >= SUBLIMINAL_FLOOR
+          def extinct? = @activation < EXTINCTION_THRESHOLD
+          def potent? = @activation >= 0.2
+
+          def breached_threshold?
+            @activation >= CONSCIOUS_THRESHOLD
+          end
+
+          def persistence = (@activation / @original_activation).clamp(0.0, 1.0).round(10)
+          def activation_label = Constants.label_for(ACTIVATION_LABELS, @activation)
+          def influence_label = Constants.label_for(INFLUENCE_LABELS, influence_magnitude)
+
+          def to_h
+            {
+              id:                  @id,
+              content:             @content,
+              trace_type:          @trace_type,
+              domain:              @domain,
+              activation:          @activation,
+              original_activation: @original_activation,
+              influence_target:    @influence_target,
+              influence_count:     @influence_count,
+              influence_magnitude: influence_magnitude,
+              near_threshold:      near_threshold?,
+              active:              active?,
+              extinct:             extinct?,
+              activation_label:    activation_label,
+              persistence:         persistence,
+              created_at:          @created_at.iso8601
+            }
+          end
+
+          private
+
+          def valid_trace_type(type)
+            sym = type.to_sym
+            TRACE_TYPES.include?(sym) ? sym : :associative
+          end
+
+          def valid_influence_target(target)
+            sym = target.to_sym
+            INFLUENCE_TARGETS.include?(sym) ? sym : :attention
+          end
+        end
+      end
+    end
+  end
+end