lex-cognitive-quicksilver 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 571d9e7b2d96df5d5efaa0bc37a1fe7427d7059a128f5b1b6326074447179de2
+  data.tar.gz: eb78fdceccf7682d16a9466280b47fd2868a49c0c481f1c318551d9e46df02ac
+SHA512:
+  metadata.gz: d95e318ddc47a7402d10108c37b246538cdf5eeba22ae591e006186921089a457f2499dcbfe9bd484bea6633cc7d2d70a242243e5c7f2215383a018eb8f59d01
+  data.tar.gz: 6601e6ddc468ef7ae7241411d0d54a55dbb09b9e74244fa092a59f8d23d7e4e1869ad821b67defbf52697dfa57dbdc060bcb53d858a7438f252ea51c32e5969d

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
+.rspec_status
+Gemfile.lock

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+Layout/LineLength:
+  Max: 160
+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/FrozenStringLiteralComment:
+  Enabled: true
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,123 @@
+# lex-cognitive-quicksilver
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-quicksilver`
+- **Version**: 0.1.0
+- **Namespace**: `Legion::Extensions::CognitiveQuicksilver`
+
+## Purpose
+
+Models cognitive fluidity as a mercury-like substance. Thoughts, impulses, and mental contents are represented as **droplets** that can merge, split, evaporate, be captured, or pool together. The metaphor reflects how cognitive content flows, coalesces, and transforms in states of high versus low mental fluidity.
+
+## Gem Info
+
+- **Gemspec**: `lex-cognitive-quicksilver.gemspec`
+- **Require**: `lex-cognitive-quicksilver`
+- **Ruby**: >= 3.4
+- **License**: MIT
+- **Homepage**: https://github.com/LegionIO/lex-cognitive-quicksilver
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_quicksilver/
+  version.rb                          # VERSION = '0.1.0'
+  helpers/
+    constants.rb                      # FORM_TYPES, SURFACE_TYPES, label tables, fluidity constants
+    droplet.rb                        # Droplet class — individual unit of cognitive content
+    pool.rb                           # Pool class — collection of droplets on a surface
+    quicksilver_engine.rb             # QuicksilverEngine — manages droplets and pools
+  runners/
+    cognitive_quicksilver.rb          # Runner module — public API methods
+  client.rb                           # Client class — instantiates engine, includes runner
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `FORM_TYPES` | `[:liquid, :droplet, :bead, :stream, :pool]` | Valid droplet forms |
+| `SURFACE_TYPES` | `[:glass, :metal, :wood, :stone, :fabric]` | Valid pool/droplet surfaces |
+| `MAX_DROPLETS` | 500 | Hard cap on tracked droplets |
+| `MAX_POOLS` | 50 | Hard cap on tracked pools |
+| `FLUIDITY_BASE` | 0.8 | Default fluidity for new droplets |
+| `SURFACE_TENSION` | 0.3 | Default pool surface tension |
+| `EVAPORATION_RATE` | 0.02 | Mass reduction per `evaporate!` call |
+| `COALESCENCE_BONUS` | 0.1 | Extra mass added when two droplets merge |
+
+## Key Classes
+
+### `Helpers::Droplet`
+
+An individual unit of cognitive content with form, mass, fluidity, and surface properties.
+
+- `shift_form!(new_form)` — changes form and adjusts fluidity to `FORM_FLUIDITY[form]`
+- `merge!(other_droplet)` — absorbs another droplet; mass sums + coalescence bonus; fluidity averages
+- `split!` — halves mass and spawns twin; returns nil if mass <= 0.2
+- `capture!` / `release!` — halves/doubles fluidity; toggles `@captured` flag
+- `evaporate!` — reduces mass by `EVAPORATION_RATE`
+- `elusive?` — fluidity >= 0.7 and not captured
+- `stable?` — fluidity < 0.4 or captured
+- `vanishing?` — mass < 0.1
+
+### `Helpers::Pool`
+
+A surface that holds droplets.
+
+- `add_droplet(id)` / `remove_droplet(id)` — adjusts depth by `DEPTH_CHANGE`
+- `agitate!` — lowers surface tension, probabilistically releases droplets
+- `settle!` — raises surface tension
+- `reflective?` — depth >= 0.7 and surface_tension >= 0.5
+- `shallow?` — depth < 0.2
+
+### `Helpers::QuicksilverEngine`
+
+Registry and coordinator for droplets and pools.
+
+- `create_droplet(form:, content:, **)` — enforces MAX_DROPLETS
+- `create_pool(surface_type:, **)` — enforces MAX_POOLS
+- `shift_form / merge_droplets / split_droplet / capture_droplet / release_droplet`
+- `add_to_pool(droplet_id:, pool_id:)`
+- `agitate_pool(pool_id:)`
+- `evaporate_all!` — evaporates all droplets, removes vanishing ones, returns removed IDs
+- `quicksilver_report` — aggregate counts and averages
+
+## Runners
+
+Module: `Legion::Extensions::CognitiveQuicksilver::Runners::CognitiveQuicksilver`
+
+| Runner | Key Args | Returns |
+|---|---|---|
+| `create_droplet` | `form:`, `content:` | `{ success:, droplet: }` |
+| `create_pool` | `surface_type:` | `{ success:, pool: }` |
+| `shift_form` | `droplet_id:`, `new_form:` | `{ success:, droplet: }` |
+| `merge` | `droplet_a_id:`, `droplet_b_id:` | `{ success:, droplet: }` |
+| `split` | `droplet_id:` | `{ success:, original:, twin: }` or `{ success: false, error: }` |
+| `capture` | `droplet_id:` | `{ success:, droplet: }` |
+| `release` | `droplet_id:` | `{ success:, droplet: }` |
+| `add_to_pool` | `droplet_id:`, `pool_id:` | `{ success:, pool: }` |
+| `list_droplets` | — | `{ success:, droplets:, count: }` |
+| `quicksilver_status` | — | aggregate report hash |
+
+All runners accept optional `engine:` keyword to inject a test engine instance.
+
+## Helpers
+
+- `Constants#label_for(table, value)` — range-table lookup for `COHESION_LABELS` and `FLUIDITY_LABELS`
+- `Droplet#cohesion_label` / `#fluidity_label` — delegates to `Constants.label_for`
+
+## Integration Points
+
+- No direct dependencies on other LegionIO extensions
+- Designed as a standalone cognitive metaphor subsystem
+- Can be wired into `lex-tick` phase handlers via `lex-cortex` if a fluidity signal is needed
+- All state is in-memory per `QuicksilverEngine` instance; no persistence
+
+## Development Notes
+
+- The `engine:` keyword in each runner method allows test injection without mocking global state
+- `split!` returns `nil` (not an error) when mass <= 0.2; runner handles this as `{ success: false, error: }`
+- `merge!` deletes the absorbed droplet from the engine registry; only one object remains
+- `evaporate_all!` is a batch operation; individual evaporation is only through direct Droplet calls
+- No actors defined; this extension is driven entirely by external calls or task triggers

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,67 @@
+# lex-cognitive-quicksilver
+
+A LegionIO cognitive architecture extension that models mental fluidity using a mercury metaphor. Cognitive content flows, coalesces, splits, and evaporates as droplets of varying form and mass.
+
+## What It Does
+
+Represents thought-units as **droplets** moving across cognitive surfaces. Droplets have:
+
+- **Form**: liquid, droplet, bead, stream, or pool — each with different fluidity characteristics
+- **Mass**: accumulates through merging, depletes through evaporation
+- **Fluidity**: determines how easily the droplet moves; capture reduces fluidity, release restores it
+
+Droplets can collect into **pools** on surfaces (glass, metal, wood, stone, fabric). Pools track depth and surface tension; agitating a pool releases some droplets.
+
+This extension provides a low-level building block for modeling states of mental flow, dissociation, and cognitive cohesion.
+
+## Usage
+
+```ruby
+require 'lex-cognitive-quicksilver'
+
+client = Legion::Extensions::CognitiveQuicksilver::Client.new
+
+# Create a droplet
+result = client.create_droplet(form: :droplet, content: 'working memory fragment')
+droplet_id = result[:droplet][:id]
+
+# Create a pool and add the droplet
+pool_result = client.create_pool(surface_type: :glass)
+client.add_to_pool(droplet_id: droplet_id, pool_id: pool_result[:pool][:id])
+
+# Shift form and check state
+client.shift_form(droplet_id: droplet_id, new_form: :stream)
+client.quicksilver_status
+# => { total_droplets: 1, total_pools: 1, elusive_count: 0, ... }
+```
+
+### Key Operations
+
+```ruby
+# Merge two droplets
+client.merge(droplet_a_id: id1, droplet_b_id: id2)
+
+# Split a droplet in half (requires mass > 0.2)
+client.split(droplet_id: id)
+
+# Capture a droplet (reduces fluidity)
+client.capture(droplet_id: id)
+
+# Release it again
+client.release(droplet_id: id)
+
+# List all droplets
+client.list_droplets
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-quicksilver.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_quicksilver/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-quicksilver'
+  spec.version       = Legion::Extensions::CognitiveQuicksilver::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Quicksilver'
+  spec.description   = 'Cognitive quicksilver fluidity for LegionIO agentic architecture'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-quicksilver'
+  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-cognitive-quicksilver'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-quicksilver'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-quicksilver'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-quicksilver/issues'
+  spec.metadata['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/cognitive_quicksilver/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_quicksilver/helpers/constants'
+require 'legion/extensions/cognitive_quicksilver/helpers/droplet'
+require 'legion/extensions/cognitive_quicksilver/helpers/pool'
+require 'legion/extensions/cognitive_quicksilver/helpers/quicksilver_engine'
+require 'legion/extensions/cognitive_quicksilver/runners/cognitive_quicksilver'
+
+module Legion
+  module Extensions
+    module CognitiveQuicksilver
+      class Client
+        include Runners::CognitiveQuicksilver
+
+        def initialize
+          @quicksilver_engine = Helpers::QuicksilverEngine.new
+        end
+
+        private
+
+        attr_reader :quicksilver_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveQuicksilver
+      module Helpers
+        module Constants
+          FORM_TYPES    = %i[liquid droplet bead stream pool].freeze
+          SURFACE_TYPES = %i[glass metal wood stone fabric].freeze
+
+          MAX_DROPLETS = 500
+          MAX_POOLS    = 50
+
+          FLUIDITY_BASE    = 0.8
+          SURFACE_TENSION  = 0.3
+          EVAPORATION_RATE = 0.02
+          COALESCENCE_BONUS = 0.1
+
+          COHESION_LABELS = [
+            { range: (0.8..1.0), label: :unified },
+            { range: (0.6...0.8), label: :cohesive },
+            { range: (0.4...0.6), label: :scattered },
+            { range: (0.2...0.4), label: :dispersed },
+            { range: (0.0...0.2), label: :atomized }
+          ].freeze
+
+          FLUIDITY_LABELS = [
+            { range: (0.8..1.0), label: :liquid },
+            { range: (0.6...0.8), label: :flowing },
+            { range: (0.4...0.6), label: :viscous },
+            { range: (0.2...0.4), label: :sluggish },
+            { range: (0.0...0.2), label: :solid }
+          ].freeze
+
+          module_function
+
+          def label_for(table, value)
+            clamped = value.clamp(0.0, 1.0)
+            entry = table.find { |row| row[:range].include?(clamped) }
+            entry ? entry[:label] : table.last[:label]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_quicksilver/helpers/droplet.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveQuicksilver
+      module Helpers
+        class Droplet
+          attr_reader :id, :form, :content, :mass, :fluidity, :surface, :captured, :created_at
+
+          FORM_FLUIDITY = {
+            liquid:  0.9,
+            droplet: 0.8,
+            bead:    0.7,
+            stream:  0.6,
+            pool:    0.3
+          }.freeze
+
+          def initialize(form:, content:, mass: 0.3, fluidity: Constants::FLUIDITY_BASE, surface: :glass)
+            raise ArgumentError, "invalid form: #{form}" unless Constants::FORM_TYPES.include?(form)
+            raise ArgumentError, "invalid surface: #{surface}" unless Constants::SURFACE_TYPES.include?(surface)
+
+            @id         = SecureRandom.uuid
+            @form       = form
+            @content    = content
+            @mass       = mass.clamp(0.0, 1.0)
+            @fluidity   = fluidity.clamp(0.0, 1.0)
+            @surface    = surface
+            @captured   = false
+            @created_at = Time.now.utc
+          end
+
+          def shift_form!(new_form)
+            raise ArgumentError, "invalid form: #{new_form}" unless Constants::FORM_TYPES.include?(new_form)
+
+            @form     = new_form
+            @fluidity = FORM_FLUIDITY.fetch(new_form, Constants::FLUIDITY_BASE).clamp(0.0, 1.0)
+            self
+          end
+
+          def merge!(other_droplet)
+            @mass     = (@mass + other_droplet.mass + Constants::COALESCENCE_BONUS).clamp(0.0, 1.0)
+            @form     = @mass >= other_droplet.mass ? @form : other_droplet.form
+            @fluidity = ((@fluidity + other_droplet.fluidity) / 2.0).round(10)
+            self
+          end
+
+          def split!
+            return nil if @mass <= 0.2
+
+            half_mass = (@mass / 2.0).round(10)
+            @mass     = half_mass
+
+            self.class.new(
+              form:     @form,
+              content:  @content,
+              mass:     half_mass,
+              fluidity: @fluidity,
+              surface:  @surface
+            )
+          end
+
+          def capture!
+            @captured  = true
+            @fluidity  = (@fluidity / 2.0).round(10)
+            self
+          end
+
+          def release!
+            @captured  = false
+            @fluidity  = (@fluidity * 2.0).clamp(0.0, 1.0)
+            self
+          end
+
+          def evaporate!
+            @mass = (@mass - Constants::EVAPORATION_RATE).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def elusive?
+            @fluidity >= 0.7 && !@captured
+          end
+
+          def stable?
+            @fluidity < 0.4 || @captured
+          end
+
+          def vanishing?
+            @mass < 0.1
+          end
+
+          def cohesion_label
+            Constants.label_for(Constants::COHESION_LABELS, @mass)
+          end
+
+          def fluidity_label
+            Constants.label_for(Constants::FLUIDITY_LABELS, @fluidity)
+          end
+
+          def to_h
+            {
+              id:           @id,
+              form:         @form,
+              content:      @content,
+              mass:         @mass.round(10),
+              fluidity:     @fluidity.round(10),
+              surface:      @surface,
+              captured:     @captured,
+              elusive:      elusive?,
+              stable:       stable?,
+              vanishing:    vanishing?,
+              cohesion:     cohesion_label,
+              fluidity_lbl: fluidity_label,
+              created_at:   @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_quicksilver/helpers/pool.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveQuicksilver
+      module Helpers
+        class Pool
+          attr_reader :id, :surface_type, :depth, :droplet_ids, :surface_tension, :created_at
+
+          DEPTH_CHANGE     = 0.05
+          TENSION_DECREASE = 0.1
+          TENSION_INCREASE = 0.05
+
+          def initialize(surface_type:, depth: 0.5, surface_tension: Constants::SURFACE_TENSION)
+            raise ArgumentError, "invalid surface_type: #{surface_type}" unless Constants::SURFACE_TYPES.include?(surface_type)
+
+            @id              = SecureRandom.uuid
+            @surface_type    = surface_type
+            @depth           = depth.clamp(0.0, 1.0)
+            @droplet_ids     = []
+            @surface_tension = surface_tension.clamp(0.0, 1.0)
+            @created_at      = Time.now.utc
+          end
+
+          def add_droplet(droplet_id)
+            @droplet_ids << droplet_id unless @droplet_ids.include?(droplet_id)
+            @depth = (@depth + DEPTH_CHANGE).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def remove_droplet(droplet_id)
+            @droplet_ids.delete(droplet_id)
+            @depth = (@depth - DEPTH_CHANGE).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def agitate!
+            @surface_tension = (@surface_tension - TENSION_DECREASE).clamp(0.0, 1.0).round(10)
+            released = []
+            @droplet_ids.each do |did|
+              released << did if rand > @surface_tension
+            end
+            released.each { |did| remove_droplet(did) }
+            released
+          end
+
+          def settle!
+            @surface_tension = (@surface_tension + TENSION_INCREASE).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def reflective?
+            @depth >= 0.7 && @surface_tension >= 0.5
+          end
+
+          def shallow?
+            @depth < 0.2
+          end
+
+          def to_h
+            {
+              id:              @id,
+              surface_type:    @surface_type,
+              depth:           @depth.round(10),
+              droplet_ids:     @droplet_ids.dup,
+              droplet_count:   @droplet_ids.size,
+              surface_tension: @surface_tension.round(10),
+              reflective:      reflective?,
+              shallow:         shallow?,
+              created_at:      @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end