lex-synapse 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1961edd72029f290abdb673e1a4b23736cdc52b963d11243e4f47e4f38c65f1
+  data.tar.gz: 83be98e416e226e960e331fa24c197f99ff236cc419ea5afd26b050ee6e09fcd
+SHA512:
+  metadata.gz: ef8000741910d6a3532cafb21a4c82924e17067359609524d41df993947677bc7fe6f505f3230cbdc94a89cca0c6a8e3db7a026a77aed2a4edb5f1a43030c227
+  data.tar.gz: 86fccd6c3ecb7f4a43c0a5030c21a82af341ea50fc7e0b4e334ef77718c637358018a5fca556361ab2a26c2870879db1d54eb91505a947b9fbf3779aa05f16a4

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,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,53 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+Metrics/ClassLength:
+  Max: 1500
+Metrics/ModuleLength:
+  Max: 1500
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+Metrics/AbcSize:
+  Max: 60
+Metrics/CyclomaticComplexity:
+  Max: 15
+Metrics/PerceivedComplexity:
+  Max: 17
+Metrics/ParameterLists:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+Style/SymbolArray:
+  Enabled: true
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false
+Naming/PredicatePrefix:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Lint/EmptyClass:
+  Exclude:
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.2.2] - 2026-03-18
+
+### Fixed
+- Remove local path references from Gemfile (lex-conditioner, lex-transformer)
+
+## [0.2.1] - 2026-03-18
+
+### Changed
+- Extract VALID_STATUSES, EVALUABLE_STATUSES, VALID_ORIGINS, VALID_OUTCOMES constants into Confidence module
+- Replace inline status array in Evaluate#evaluate with EVALUABLE_STATUSES constant reference
+
+## [0.2.0] - 2026-03-17
+
+### Added
+- `Runners::GaiaReport` with `gaia_summary` (tick-consumable stats) and `gaia_reflection` (mutation tally + summary for post-tick)
+- `Runners::Dream` with `dream_replay` (read-only mutation timeline) and `dream_simulate` (what-if without modifying state)
+- `Runners::Promote` pushes high-confidence synapse patterns to Apollo (threshold: confidence >= 0.9, no reverts in 24h)
+- `Runners::Retrieve` seeds new synapses from Apollo knowledge entries (threshold: entry confidence >= 0.7)
+- Client includes all 4 new runner modules
+- 92 new specs (303 total), 96% coverage
+
+## [0.1.0] - 2026-03-17
+
+### Added
+- Cognitive routing layer for LegionIO task chains
+- Data model: `synapses`, `synapse_mutations`, `synapse_signals` tables with Sequel migrations
+- Confidence scoring: starting scores by origin (explicit=0.7, emergent=0.3, seeded=0.5), event-based adjustments, idle decay, autonomy ranges (OBSERVE/FILTER/TRANSFORM/AUTONOMOUS)
+- Homeostasis: spike detection (>3x baseline for 60s), drought detection (0 throughput for 10x avg interval), exponential moving average baseline tracking
+- 6 core runners: evaluate (attention+transform+route+record), pain (failure handling, auto-revert), crystallize (emergent synapse creation), mutate (versioned self-modification), revert (rollback to previous version), report (aggregated stats)
+- 5 actors: evaluate (subscription), pain (subscription), crystallize (every 5min), homeostasis (every 30s), decay (every 1hr)
+- Transport layer: synapse exchange, evaluate/pain queues, signal/pain messages
+- Standalone `Client` class with injected conditioner/transformer clients
+- `RelationshipWrapper` helper for wrapping Layer 1 relationships as synapses
+- 211 specs, 94%+ coverage

data/CLAUDE.md

@@ -0,0 +1,98 @@
+# lex-synapse: Cognitive Routing Layer for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-core/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Cognitive routing layer that wraps task chain relationships with observation, learning, confidence scoring, pain signals, homeostasis, and self-governance. Sits between Layer 1 (explicit user-defined relationships in lex-tasker) and Layer 3 (GAIA cognitive coordination + Apollo shared knowledge).
+
+**GitHub**: https://github.com/LegionIO/lex-synapse
+**License**: MIT
+**Version**: 0.2.2
+
+## Architecture
+
+```
+Legion::Extensions::Synapse
+├── Actors/
+│   ├── Evaluate        # Subscription — main signal evaluation
+│   ├── Pain            # Subscription — task.failed handler
+│   ├── Crystallize     # Every 300s — emergent synapse detection
+│   ├── Homeostasis     # Every 30s — spike/drought monitoring
+│   └── Decay           # Every 3600s — idle confidence decay
+├── Runners/
+│   ├── Evaluate        # attention -> transform -> route -> record
+│   ├── Pain            # failure recording, confidence hit, auto-revert
+│   ├── Crystallize     # unrouted traffic analysis, emergent creation
+│   ├── Mutate          # versioned self-modification with snapshots
+│   ├── Revert          # rollback to previous mutation version
+│   └── Report          # aggregate stats for GAIA consumption
+├── Helpers/
+│   ├── Confidence      # scoring, adjustments, autonomy ranges, decay
+│   ├── Homeostasis     # spike/drought detection, baseline tracking
+│   └── RelationshipWrapper  # Layer 1 -> Layer 2 wrapping
+├── Data/
+│   ├── Migrations/     # 001 synapses, 002 mutations, 003 signals
+│   └── Models/         # Synapse, SynapseMutation, SynapseSignal
+├── Transport/
+│   ├── Exchanges/Synapse
+│   ├── Queues/Evaluate, Pain
+│   └── Messages/Signal, Pain
+└── Client              # Standalone client including all runners
+```
+
+## Key Thresholds
+
+| Parameter | Value |
+|-----------|-------|
+| Explicit starting confidence | 0.7 |
+| Emergent starting confidence | 0.3 |
+| Seeded starting confidence | 0.5 |
+| Success adjustment | +0.02 |
+| Failure adjustment | -0.05 |
+| Validation failure adjustment | -0.03 |
+| Consecutive success bonus (>50) | +0.05 |
+| Idle decay rate | *0.998/hour |
+| Auto-revert threshold | 3 consecutive failures |
+| Spike multiplier | 3x baseline for 60s |
+| Drought threshold | 0 throughput for 10x avg interval |
+| Crystallize threshold | 20 unrouted signals |
+
+## Autonomy Ranges
+
+| Confidence | Mode | Capabilities |
+|------------|------|-------------|
+| 0.0-0.3 | OBSERVE | Log, pass through unchanged |
+| 0.3-0.6 | FILTER | Suppress signals |
+| 0.6-0.8 | TRANSFORM | Filter + transform within schemas |
+| 0.8-1.0 | AUTONOMOUS | Self-modify rules, infer transforms |
+
+## Data Model
+
+- **synapses**: Core routing definition with confidence, status, version, baseline_throughput
+- **synapse_mutations**: Versioned change history with before/after JSON snapshots
+- **synapse_signals**: Per-signal outcome records (attention pass, transform success, latency, downstream outcome)
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `lex-conditioner` >= 0.3.0 | Attention evaluation (condition rules) |
+| `lex-transformer` >= 0.2.0 | Payload transformation (template engines) |
+| `legion-data` | Required — database persistence via Sequel |
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+308 specs, 96%+ coverage. Uses in-memory SQLite for model/runner tests.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+  gem 'sequel'
+  gem 'simplecov'
+  gem 'sqlite3'
+end

data/README.md

@@ -0,0 +1,156 @@
+# lex-synapse
+
+Cognitive routing layer for [LegionIO](https://github.com/LegionIO/LegionIO) task chains. Wraps task relationships with observation, learning, confidence scoring, pain signals, and self-governance.
+
+## Installation
+
+```bash
+gem install lex-synapse
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'lex-synapse'
+```
+
+## Standalone Client
+
+Use the synapse engine without the full LegionIO framework:
+
+```ruby
+require 'legion/extensions/synapse/client'
+
+# Optionally inject conditioner and transformer clients
+conditioner = Legion::Extensions::Conditioner::Client.new
+transformer = Legion::Extensions::Transformer::Client.new
+
+client = Legion::Extensions::Synapse::Client.new(
+  conditioner_client: conditioner,
+  transformer_client: transformer
+)
+
+# Create a synapse
+synapse = client.create(
+  source_function_id: 1,
+  target_function_id: 2,
+  attention: '{"all":[{"fact":"status","operator":"equal","value":"open"}]}',
+  transform: '{"template":"{\"message\":\"<%= title %>\"}","engine":"erb"}'
+)
+
+# Evaluate a signal through the synapse
+result = client.evaluate(synapse_id: synapse.id, payload: { status: 'open', title: 'Bug fix' })
+result[:success]     # => true
+result[:mode]        # => :transform (based on confidence level)
+result[:result]      # => { message: "Bug fix" }
+
+# Get synapse stats
+report = client.report(synapse_id: synapse.id)
+report[:confidence]  # => 0.72
+report[:signals_24h] # => 1
+report[:success_rate] # => 1.0
+```
+
+## Architecture
+
+### Three-Layer Model
+
+```
+Layer 1 (Bones)  — Explicit relationships defined by users (lex-tasker)
+Layer 2 (Nerves) — Synapses wrapping relationships with learning (lex-synapse)
+Layer 3 (Mind)   — GAIA cognitive coordination + Apollo shared knowledge (future)
+```
+
+### Confidence Scoring
+
+Each synapse has a confidence score (0.0-1.0) that governs what it's allowed to do:
+
+| Range | Mode | Permitted Actions |
+|-------|------|-------------------|
+| 0.0-0.3 | OBSERVE | Log what it would do, pass through unchanged |
+| 0.3-0.6 | FILTER | Can suppress signals, cannot modify |
+| 0.6-0.8 | TRANSFORM | Can filter + transform within defined schemas |
+| 0.8-1.0 | AUTONOMOUS | Can self-modify rules, infer transforms, adjust routing |
+
+**Starting scores**: explicit=0.7, emergent=0.3, seeded=0.5
+
+**Adjustments**: success +0.02, failure -0.05, validation failure -0.03, 50+ consecutive successes +0.05 bonus
+
+**Decay**: Unused synapses fade at 0.998x per hour (~15% per day of inactivity)
+
+### Pain Signals
+
+Downstream task failures propagate backward through the chain:
+- Each failure reduces confidence by 0.05
+- 3+ consecutive failures trigger auto-revert to last known-good state
+- Extreme failure rates trigger dampening (homeostasis)
+
+### Homeostasis
+
+- **Spike detection**: Throughput >3x baseline for 60+ seconds triggers dampening
+- **Drought detection**: Zero throughput for 10x average interval flags for review
+- **Baseline tracking**: Exponential moving average of signals/minute
+
+## Runners
+
+### Evaluate
+`evaluate(synapse_id:, payload:, conditioner_client:, transformer_client:)`
+
+Main signal flow: load synapse, check autonomy, run attention (conditioner), run transform (transformer), record signal, adjust confidence.
+
+### Pain
+`handle_pain(synapse_id:, task_id:)`
+
+Downstream failure handler. Records failed signal, adjusts confidence, checks for auto-revert threshold, may dampen synapse.
+
+### Crystallize
+`crystallize(signal_pairs:, threshold: 20)`
+
+Bottom-up emergence. Given pairs of `{source_function_id, target_function_id, count}`, creates new synapses for pairs exceeding the threshold.
+
+### Mutate
+`mutate(synapse_id:, mutation_type:, changes:, trigger:)`
+
+Versioned self-modification. Records before/after state snapshots. Types: `attention_adjusted`, `transform_adjusted`, `route_changed`, `confidence_changed`. Triggers: `hebbian`, `pain`, `dream`, `gaia`, `manual`.
+
+### Revert
+`revert(synapse_id:, to_version:, trigger:)`
+
+Rolls back to a previous mutation version, restoring the before_state.
+
+### Report
+`report(synapse_id:)`
+
+Aggregates stats: confidence, status, 24h signal count, success rate, last mutation.
+
+## Relationship Wrapper
+
+Wrap existing Layer 1 relationships as synapses (opt-in, zero breaking changes):
+
+```ruby
+relationship = { id: 42, trigger_function_id: 1, function_id: 2,
+                 conditions: '{"all":[...]}', transformation: '{"template":"..."}' }
+synapse = Legion::Extensions::Synapse::Helpers::RelationshipWrapper.wrap(relationship)
+```
+
+## Transport
+
+- **Exchange**: `synapse` (inherits from `Legion::Transport::Exchanges::Task`)
+- **Queues**: `synapse.evaluate`, `synapse.pain`
+- **Routing keys**: `synapse.evaluate`, `task.failed`
+
+## Data Model
+
+Three tables: `synapses` (core routing definition + confidence + status), `synapse_mutations` (versioned change history), `synapse_signals` (per-signal outcome records).
+
+## Dependencies
+
+- `lex-conditioner` >= 0.3.0
+- `lex-transformer` >= 0.2.0
+- Ruby >= 3.4
+- [LegionIO](https://github.com/LegionIO/LegionIO) framework (for AMQP actor mode)
+- Standalone Client works without the framework (requires Sequel + database)
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lex-synapse.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/synapse/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-synapse'
+  spec.version       = Legion::Extensions::Synapse::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Cognitive routing layer for LegionIO task chains'
+  spec.description   = 'Attention, transformation, and routing with confidence scoring, pain signals, homeostasis, and self-governance'
+  spec.homepage      = 'https://github.com/LegionIO/lex-synapse'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-synapse'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-synapse'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-synapse/blob/main/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-synapse/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'lex-conditioner', '>= 0.3.0'
+  spec.add_dependency 'lex-transformer', '>= 0.2.0'
+end

data/lib/legion/extensions/synapse/actors/crystallize.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Synapse
+      module Actor
+        class Crystallize < Legion::Extensions::Actors::Every
+          def runner_function
+            'crystallize'
+          end
+
+          def time
+            300
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/synapse/actors/decay.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Synapse
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_function
+            'apply_decay'
+          end
+
+          def time
+            3600
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/synapse/actors/evaluate.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Synapse
+      module Actor
+        class Evaluate < Legion::Extensions::Actors::Subscription
+          def runner_function
+            'evaluate'
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/synapse/actors/homeostasis.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Synapse
+      module Actor
+        class Homeostasis < Legion::Extensions::Actors::Every
+          def runner_function
+            'check_homeostasis'
+          end
+
+          def time
+            30
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/synapse/actors/pain.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Synapse
+      module Actor
+        class Pain < Legion::Extensions::Actors::Subscription
+          def runner_function
+            'handle_pain'
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'runners/evaluate'
+require_relative 'runners/pain'
+require_relative 'runners/crystallize'
+require_relative 'runners/mutate'
+require_relative 'runners/revert'
+require_relative 'runners/report'
+require_relative 'runners/gaia_report'
+require_relative 'runners/dream'
+require_relative 'runners/promote'
+require_relative 'runners/retrieve'
+
+module Legion
+  module Extensions
+    module Synapse
+      class Client
+        include Runners::Evaluate
+        include Runners::Pain
+        include Runners::Crystallize
+        include Runners::Mutate
+        include Runners::Revert
+        include Runners::Report
+        include Runners::GaiaReport
+        include Runners::Dream
+        include Runners::Promote
+        include Runners::Retrieve
+
+        attr_reader :conditioner_client, :transformer_client
+
+        def initialize(conditioner_client: nil, transformer_client: nil)
+          @conditioner_client = conditioner_client
+          @transformer_client = transformer_client
+        end
+
+        def evaluate(synapse_id:, payload: {})
+          super(
+            synapse_id:         synapse_id,
+            payload:            payload,
+            conditioner_client: @conditioner_client,
+            transformer_client: @transformer_client
+          )
+        end
+
+        def create(source_function_id:, target_function_id:, attention: nil, transform: nil,
+                   routing_strategy: 'direct', origin: 'explicit', relationship_id: nil)
+          Data::Model::Synapse.create(
+            source_function_id: source_function_id,
+            target_function_id: target_function_id,
+            attention:          attention,
+            transform:          transform,
+            routing_strategy:   routing_strategy,
+            origin:             origin,
+            relationship_id:    relationship_id,
+            confidence:         Helpers::Confidence.starting_score(origin),
+            status:             origin == 'emergent' ? 'observing' : 'active'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/synapse/data/migrations/001_create_synapses.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    create_table(:synapses) do
+      primary_key :id
+      Integer  :source_function_id, null: true, index: true
+      Integer  :target_function_id, null: true, index: true
+      Integer  :relationship_id,    null: true, index: true
+      String   :attention,          text: true
+      String   :transform,          text: true
+      String   :routing_strategy,   null: false, default: 'direct', size: 50
+      Float    :confidence,         null: false, default: 0.5
+      Float    :baseline_throughput, null: false, default: 0.0
+      String   :origin,             null: false, default: 'explicit', size: 50
+      String   :status,             null: false, default: 'active', size: 50
+      Integer  :version,            null: false, default: 1
+      DateTime :created_at,         null: false, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :updated_at
+    end
+  end
+
+  down do
+    drop_table :synapses
+  end
+end