lex-coldstart 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77ee2421158cb9a62de788b3ccfb8333a133a51205a2de77cb4676717fb03f5f
-  data.tar.gz: c91dd8d5e753495d06a7bab45305a0c6bbb8708d0ac3c465aeacc67bd7ad8ed9
+  metadata.gz: 2505b31b1c5c73daeaae75d58a8c90334a1737cb6404bbdc5dfe16a2ad725487
+  data.tar.gz: 56c698c91719584872f5d5b3363304554520810853e507bf9978441d1cc4f1d6
 SHA512:
-  metadata.gz: 33885d264cb29034efa973f6a501bc55ee1ad29556c70dcf5e22b88604f618f467143b2617d66cbb4a03b5b17b790a636ab35f9b04f8578443884b9a28fb8ddf
-  data.tar.gz: 9bc2bdd0c4f97a573d637bacdb495557f3aea405a19f7830eeb381f41af4a6e6fec3e5af36b9c0b668709c09374a105d014e355972660cc18ce143f4e7e9d6e7
+  metadata.gz: 025cbbf8e9199150819ba6439f0ba80ec65d15276bc9b729574f146713d09181bb80fd9a4df3e18c0da9503fd0b6752817fda1c04a1be0d5a7c255e902a9049c
+  data.tar.gz: 54fa4158dcabdee1125bcee466020a4cd92bb5af86e554671fc285d65cdda2c90548c87fdf25b4b02d67f3af0ca579f566193b2512e5f9a0254a930b595e943f

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

@@ -10,13 +10,11 @@ module Legion
       class Client
         include Runners::Coldstart
 
-        def initialize(**)
-          @bootstrap = Helpers::Bootstrap.new
-        end
-
         private
 
-        attr_reader :bootstrap
+        def bootstrap
+          Helpers::Bootstrap.instance
+        end
       end
     end
   end

data/lib/legion/extensions/coldstart/helpers/bootstrap.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'monitor'
+
 module Legion
   module Extensions
     module Coldstart
@@ -7,6 +9,21 @@ module Legion
         class Bootstrap
           attr_reader :started_at, :observation_count, :firmware_loaded, :calibration_state
 
+          LOCK = Monitor.new
+          @instance = nil
+
+          class << self
+            def instance
+              LOCK.synchronize do
+                @instance ||= new
+              end
+            end
+
+            def reset!
+              LOCK.synchronize { @instance = nil }
+            end
+          end
+
           def initialize
             @started_at = nil
             @observation_count = 0
@@ -15,52 +32,68 @@ module Legion
             load_from_local
           end
 
-          def begin_imprint
-            @started_at = Time.now.utc
-            @calibration_state = :imprinting
-            save_to_local
+          def begin_imprint(force: false)
+            LOCK.synchronize do
+              return if @started_at && !force
+
+              @started_at = Time.now.utc
+              @observation_count = 0 if force
+              @calibration_state = :imprinting
+              save_to_local
+            end
           end
 
           def load_firmware
-            @firmware_loaded = true
-            save_to_local
+            LOCK.synchronize do
+              @firmware_loaded = true
+              save_to_local
+            end
           end
 
           def record_observation
-            @observation_count += 1
-            check_calibration_progress
-            save_to_local
+            LOCK.synchronize do
+              @observation_count += 1
+              check_calibration_progress
+              save_to_local
+            end
           end
 
           def imprint_active?
-            Imprint.imprint_active?(@started_at)
+            Imprint.imprint_active?(started_at: @started_at, observation_count: @observation_count)
+          end
+
+          def current_multiplier
+            Imprint.current_multiplier(started_at: @started_at, observation_count: @observation_count)
           end
 
           def current_layer
             return :firmware unless @firmware_loaded
 
-            Imprint.current_layer(@started_at, observations: @observation_count)
+            Imprint.current_layer(started_at: @started_at, observation_count: @observation_count)
           end
 
           def progress
             {
-              firmware_loaded:   @firmware_loaded,
-              imprint_active:    imprint_active?,
-              imprint_progress:  Imprint.imprint_progress(@started_at),
-              observation_count: @observation_count,
-              calibration_state: @calibration_state,
-              current_layer:     current_layer
+              firmware_loaded:    @firmware_loaded,
+              imprint_active:     imprint_active?,
+              imprint_progress:   Imprint.imprint_progress(started_at: @started_at, observation_count: @observation_count),
+              observation_count:  @observation_count,
+              calibration_state:  @calibration_state,
+              current_layer:      current_layer,
+              current_multiplier: current_multiplier
             }
           end
 
           private
 
           def check_calibration_progress
-            if @observation_count >= Imprint::IMPRINT_ENTROPY_BASELINE && !imprint_active?
-              @calibration_state = :calibrated
-            elsif @observation_count >= Imprint::IMPRINT_ENTROPY_BASELINE
-              @calibration_state = :baseline_established
-            end
+            return unless @observation_count >= Imprint::IMPRINT_ENTROPY_BASELINE
+
+            @calibration_state = if imprint_active?
+                                   :consolidating
+                                 else
+                                   :calibrated
+                                 end
           end
 
           def save_to_local

data/lib/legion/extensions/coldstart/helpers/imprint.rb

@@ -8,11 +8,11 @@ module Legion
           # Three learning layers (spec: cold-start-spec.md)
           LAYERS = %i[firmware imprint_window continuous_learning].freeze
 
-          # Imprint window parameters
-          IMPRINT_DURATION        = 7 * 86_400 # 7 days
-          IMPRINT_MULTIPLIER      = 3.0        # consolidation rate multiplier during imprint
-          IMPRINT_CONSENT_TIER    = :consult # conservative consent during imprint
-          IMPRINT_ENTROPY_BASELINE = 50 # minimum observations before entropy is meaningful
+          # Interaction-denominated imprint parameters
+          IMPRINT_ENTROPY_BASELINE = 50   # observations before window begins narrowing
+          IMPRINT_RAMP_LENGTH      = 50   # additional observations over which multiplier ramps down
+          IMPRINT_MAX_MULTIPLIER   = 3.0  # consolidation rate multiplier at full imprint
+          IMPRINT_SAFETY_BOUND     = 30 * 86_400 # wall-clock safety: warn if window open >30 days
 
           # Self-play bootstrap parameters
           SELF_PLAY_ITERATIONS    = 100
@@ -20,27 +20,42 @@ module Legion
 
           module_function
 
-          def imprint_active?(started_at)
+          def imprint_active?(started_at:, observation_count:)
             return false unless started_at
 
-            (Time.now.utc - started_at) < IMPRINT_DURATION
+            observation_count < (IMPRINT_ENTROPY_BASELINE + IMPRINT_RAMP_LENGTH)
           end
 
-          def imprint_progress(started_at)
+          def imprint_progress(started_at:, observation_count:)
             return 1.0 unless started_at
 
-            elapsed = Time.now.utc - started_at
-            [elapsed / IMPRINT_DURATION.to_f, 1.0].min
+            total = IMPRINT_ENTROPY_BASELINE + IMPRINT_RAMP_LENGTH
+            [observation_count.to_f / total, 1.0].min
           end
 
-          def current_layer(started_at, observations:)
-            if (observations < IMPRINT_ENTROPY_BASELINE && imprint_active?(started_at)) ||
-               imprint_active?(started_at)
+          def current_multiplier(started_at:, observation_count:)
+            return 1.0 unless started_at
+            return IMPRINT_MAX_MULTIPLIER if observation_count < IMPRINT_ENTROPY_BASELINE
+
+            ramp_progress = [(observation_count - IMPRINT_ENTROPY_BASELINE).to_f / IMPRINT_RAMP_LENGTH, 1.0].min
+            IMPRINT_MAX_MULTIPLIER - ((IMPRINT_MAX_MULTIPLIER - 1.0) * ramp_progress)
+          end
+
+          def current_layer(started_at:, observation_count:)
+            return :continuous_learning unless started_at
+
+            if observation_count < (IMPRINT_ENTROPY_BASELINE + IMPRINT_RAMP_LENGTH)
               :imprint_window
             else
               :continuous_learning
             end
           end
+
+          def safety_bound_exceeded?(started_at:)
+            return false unless started_at
+
+            (Time.now.utc - started_at) > IMPRINT_SAFETY_BOUND
+          end
         end
       end
     end

data/lib/legion/extensions/coldstart/runners/coldstart.rb

@@ -8,18 +8,17 @@ module Legion
           include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
                                                       Legion::Extensions::Helpers.const_defined?(:Lex, false)
 
-          def begin_imprint(**)
+          def begin_imprint(force: false, **)
             bootstrap.load_firmware
-            bootstrap.begin_imprint
-            dur = Helpers::Imprint::IMPRINT_DURATION
-            mul = Helpers::Imprint::IMPRINT_MULTIPLIER
-            tier = Helpers::Imprint::IMPRINT_CONSENT_TIER
-            log.info "[coldstart] imprint begun: duration=#{dur}s multiplier=#{mul}x consent=#{tier}"
+            bootstrap.begin_imprint(force: force)
+            mul = bootstrap.current_multiplier
+            log.info "[coldstart] imprint begun: force=#{force} multiplier=#{mul}x"
             {
-              started:          true,
-              imprint_duration: Helpers::Imprint::IMPRINT_DURATION,
-              multiplier:       Helpers::Imprint::IMPRINT_MULTIPLIER,
-              consent_tier:     Helpers::Imprint::IMPRINT_CONSENT_TIER
+              started:           true,
+              imprint_active:    bootstrap.imprint_active?,
+              multiplier:        mul,
+              observation_count: bootstrap.observation_count,
+              calibration_state: bootstrap.calibration_state
             }
           end
 
@@ -28,9 +27,10 @@ module Legion
             log.debug "[coldstart] observation: count=#{bootstrap.observation_count} " \
                       "calibration=#{bootstrap.calibration_state} layer=#{bootstrap.current_layer}"
             {
-              observation_count: bootstrap.observation_count,
-              calibration_state: bootstrap.calibration_state,
-              current_layer:     bootstrap.current_layer
+              observation_count:  bootstrap.observation_count,
+              calibration_state:  bootstrap.calibration_state,
+              current_layer:      bootstrap.current_layer,
+              current_multiplier: bootstrap.current_multiplier
             }
           end
 
@@ -47,8 +47,8 @@ module Legion
           end
 
           def current_multiplier(**)
+            multiplier = bootstrap.current_multiplier
             active = bootstrap.imprint_active?
-            multiplier = active ? Helpers::Imprint::IMPRINT_MULTIPLIER : 1.0
             log.debug "[coldstart] multiplier=#{multiplier} imprint_active=#{active}"
             { multiplier: multiplier, imprint_active: active }
           end
@@ -56,7 +56,7 @@ module Legion
           private
 
           def bootstrap
-            @bootstrap ||= Helpers::Bootstrap.new
+            Helpers::Bootstrap.instance
           end
         end
       end

data/lib/legion/extensions/coldstart/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Coldstart
-      VERSION = '0.1.3'
+      VERSION = '0.1.5'
     end
   end
 end

data/spec/legion/extensions/coldstart/runners/coldstart_spec.rb

@@ -5,12 +5,22 @@ require 'legion/extensions/coldstart/client'
 RSpec.describe Legion::Extensions::Coldstart::Runners::Coldstart do
   let(:client) { Legion::Extensions::Coldstart::Client.new }
 
+  before { Legion::Extensions::Coldstart::Helpers::Bootstrap.reset! }
+
   describe '#begin_imprint' do
     it 'starts the imprint window' do
       result = client.begin_imprint
       expect(result[:started]).to be true
       expect(result[:multiplier]).to eq(3.0)
     end
+
+    it 'supports force restart' do
+      client.begin_imprint
+      5.times { client.record_observation }
+      result = client.begin_imprint(force: true)
+      expect(result[:started]).to be true
+      expect(result[:observation_count]).to eq(0)
+    end
   end
 
   describe '#record_observation' do
@@ -20,11 +30,19 @@ RSpec.describe Legion::Extensions::Coldstart::Runners::Coldstart do
       expect(result[:observation_count]).to eq(1)
     end
 
-    it 'transitions calibration state at baseline threshold' do
+    it 'transitions calibration state to consolidating at baseline threshold' do
       client.begin_imprint
       50.times { client.record_observation }
       result = client.record_observation
-      expect(result[:calibration_state]).to eq(:baseline_established)
+      expect(result[:calibration_state]).to eq(:consolidating)
+    end
+
+    it 'returns current multiplier that ramps down after baseline' do
+      client.begin_imprint
+      51.times { client.record_observation }
+      result = client.current_multiplier
+      expect(result[:multiplier]).to be < 3.0
+      expect(result[:multiplier]).to be > 1.0
     end
   end
 
@@ -49,6 +67,13 @@ RSpec.describe Legion::Extensions::Coldstart::Runners::Coldstart do
       result = client.imprint_active?
       expect(result[:active]).to be true
     end
+
+    it 'returns false after full observation ramp completes' do
+      client.begin_imprint
+      100.times { client.record_observation }
+      result = client.imprint_active?
+      expect(result[:active]).to be false
+    end
   end
 
   describe '#current_multiplier' do
@@ -57,10 +82,22 @@ RSpec.describe Legion::Extensions::Coldstart::Runners::Coldstart do
       expect(result[:multiplier]).to eq(1.0)
     end
 
-    it 'returns 3.0 during imprint' do
+    it 'returns 3.0 at start of imprint' do
       client.begin_imprint
       result = client.current_multiplier
       expect(result[:multiplier]).to eq(3.0)
     end
+
+    it 'ramps from 3.0 to 1.0 over the tail' do
+      client.begin_imprint
+      75.times { client.record_observation }
+      mid_result = client.current_multiplier
+      expect(mid_result[:multiplier]).to be < 3.0
+      expect(mid_result[:multiplier]).to be > 1.0
+
+      25.times { client.record_observation }
+      end_result = client.current_multiplier
+      expect(end_result[:multiplier]).to eq(1.0)
+    end
   end
 end

data/spec/local_persistence_spec.rb

@@ -13,6 +13,7 @@ RSpec.describe 'lex-coldstart local persistence' do
   before do
     Sequel::TimestampMigrator.new(db, migration_path).run
     stub_const('Legion::Data::Local', local_mod)
+    Legion::Extensions::Coldstart::Helpers::Bootstrap.reset!
   end
 
   let(:local_mod) do
@@ -24,6 +25,7 @@ RSpec.describe 'lex-coldstart local persistence' do
   end
 
   def fresh_bootstrap
+    Legion::Extensions::Coldstart::Helpers::Bootstrap.reset!
     Legion::Extensions::Coldstart::Helpers::Bootstrap.new
   end
 
@@ -52,7 +54,7 @@ RSpec.describe 'lex-coldstart local persistence' do
   end
 
   describe 'started_at preservation (imprint window survives restarts)' do
-    it 'restores started_at so the 7-day window continues from the original time' do
+    it 'restores started_at so the window continues from the original time' do
       b = fresh_bootstrap
       b.begin_imprint
       original_started_at = b.started_at
@@ -62,7 +64,7 @@ RSpec.describe 'lex-coldstart local persistence' do
       expect(b2.started_at.to_i).to be_within(1).of(original_started_at.to_i)
     end
 
-    it 'reports imprint still active after reload within the 7-day window' do
+    it 'reports imprint still active after reload when under baseline' do
       b = fresh_bootstrap
       b.begin_imprint
       b2 = fresh_bootstrap
@@ -75,13 +77,40 @@ RSpec.describe 'lex-coldstart local persistence' do
       b2 = fresh_bootstrap
       expect(b2.started_at).not_to be_nil
     end
+
+    it 'does not reset started_at when begin_imprint is called again without force' do
+      first_time = Time.utc(2026, 4, 2, 12, 0, 0)
+      second_time = first_time + 60
+      allow(Time).to receive(:now).and_return(first_time, second_time)
+
+      b = fresh_bootstrap
+      b.begin_imprint
+      original_started_at = b.started_at
+
+      b.begin_imprint
+
+      expect(b.started_at.to_i).to eq(original_started_at.to_i)
+    end
+
+    it 'resets started_at when begin_imprint is called with force: true' do
+      first_time = Time.utc(2026, 4, 2, 12, 0, 0)
+      second_time = first_time + 60
+      allow(Time).to receive(:now).and_return(first_time, second_time)
+
+      b = fresh_bootstrap
+      b.begin_imprint
+      original_started_at = b.started_at
+
+      b.begin_imprint(force: true)
+
+      expect(b.started_at.to_i).to be > original_started_at.to_i
+    end
   end
 
   describe 'calibration_state symbol round-trip' do
-    %i[not_started imprinting baseline_established calibrated].each do |state|
+    %i[not_started imprinting consolidating calibrated].each do |state|
       it "persists and restores :#{state}" do
         fresh_bootstrap
-        # Force the state directly through the DB to test all symbol variants
         db[:bootstrap_state].where(id: 1).delete
         db[:bootstrap_state].insert(
           id:                1,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-coldstart
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Esity