rubik 0.1.0

data/lib/rubik/kernel/dmesg.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "record"
+
+module Rubik
+  module Kernel
+    # Bounded circular ring buffer for monotonic kernel event telemetry (Plan 102).
+    # Zero memory growth: pre-allocated array overwritten in O(1) time.
+    class Dmesg
+      DEFAULT_CAPACITY = 2048
+
+      attr_reader :capacity, :seq_counter, :start_time
+
+      def initialize(capacity: DEFAULT_CAPACITY)
+        @capacity = [capacity.to_i, 1].max
+        @buffer = Array.new(@capacity)
+        @head = 0
+        @size = 0
+        @seq_counter = 0
+        @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @monitor = Monitor.new
+      end
+
+      def size
+        @monitor.synchronize { @size }
+      end
+
+      def empty?
+        @monitor.synchronize { @size.zero? }
+      end
+
+      def log(subsystem, level, message, facility_id: nil, **data)
+        @monitor.synchronize do
+          @seq_counter += 1
+          uptime = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+          norm_sub = subsystem.to_sym
+          norm_lvl = Rubik::Kernel.normalize_level(level)
+
+          record = Record.new(
+            seq: @seq_counter,
+            uptime: uptime,
+            subsystem: norm_sub,
+            level: norm_lvl,
+            facility_id: facility_id,
+            message: message.to_s,
+            data: data
+          )
+
+          @buffer[@head] = record
+          @head = (@head + 1) % @capacity
+          @size += 1 if @size < @capacity
+          record
+        end
+      end
+
+      def tail(limit = 50, level: nil, subsystem: nil, since_seq: nil)
+        @monitor.synchronize do
+          records = snapshot_unlocked
+          records = filter_since(records, since_seq) if since_seq
+          records = filter_subsystem(records, subsystem) if subsystem
+          records = filter_level(records, level) if level
+          limit ? records.last(limit.to_i) : records
+        end
+      end
+
+      def to_a
+        @monitor.synchronize { snapshot_unlocked }
+      end
+
+      def clear!
+        @monitor.synchronize do
+          @buffer.fill(nil)
+          @head = 0
+          @size = 0
+          self
+        end
+      end
+
+      def formatted(records = nil, color: false)
+        recs = records || tail
+        return "" if recs.empty?
+
+        recs.map { |r| Rubik::Kernel.format_line(r, color: color) }.join("\n")
+      end
+
+      private
+
+      def snapshot_unlocked
+        return [] if @size.zero?
+
+        start_idx = @size < @capacity ? 0 : @head
+        Array.new(@size) { |i| @buffer[(start_idx + i) % @capacity] }
+      end
+
+      def filter_since(records, since_seq)
+        seq_threshold = since_seq.to_i
+        records.select { |r| r.seq > seq_threshold }
+      end
+
+      def filter_subsystem(records, subsystem)
+        subs = Array(subsystem).flat_map { |s| s.to_s.split(",") }.map(&:strip).map(&:downcase)
+        records.select { |r| subs.include?(r.subsystem.to_s.downcase) }
+      end
+
+      def filter_level(records, level)
+        if level.is_a?(Integer)
+          records.select { |r| SEVERITY_LEVELS.fetch(r.level, 7) <= level }
+        else
+          levels = Array(level).flat_map { |l| l.to_s.split(",") }.to_set { |l| Rubik::Kernel.normalize_level(l) }
+          records.select { |r| levels.include?(r.level) }
+        end
+      end
+    end
+  end
+end

data/lib/rubik/kernel/init.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "unit"
+
+module Rubik
+  module Kernel
+    # Root lifecycle supervisor (PID 1) governing all kernel execution units (Plan 104).
+    # Single source of truth for background execution, zombie reaping, and LIFO shutdown.
+    class Init
+      attr_reader :context, :dmesg, :dispatcher
+
+      def initialize(context: nil, dmesg: nil, dispatcher: nil)
+        @context = context
+        @dmesg = dmesg
+        @dispatcher = dispatcher
+        @units = {}
+        @order = []
+        @monitor = Monitor.new
+        @stopped = false
+
+        bind_context(@context)
+      end
+
+      def register(unit)
+        @monitor.synchronize do
+          raise ArgumentError, "Unit cannot be nil" if unit.nil?
+          raise Unit::StateError, "Init supervisor is stopped" if @stopped
+
+          unit.dmesg ||= @dmesg if unit.respond_to?(:dmesg=)
+          unit.dispatcher ||= @dispatcher if unit.respond_to?(:dispatcher=)
+
+          @units[unit.id] = unit
+          @order << unit.id unless @order.include?(unit.id)
+          @dmesg&.log(:kernel, :info, "registered unit:#{unit.id} type:#{unit.type}", facility_id: "init", unit_id: unit.id)
+          unit
+        end
+      end
+      alias spawn register
+
+      def get(id)
+        @monitor.synchronize do
+          unit = @units[id.to_s]
+          unit&.sync_state! if unit.respond_to?(:sync_state!)
+          unit
+        end
+      end
+      alias [] get
+
+      def units
+        @monitor.synchronize do
+          @units.each_value { |u| u.sync_state! if u.respond_to?(:sync_state!) }
+          @units.values.dup
+        end
+      end
+
+      def units_by_state(*states)
+        target_states = states.flatten.map(&:to_sym)
+        @monitor.synchronize do
+          @units.values.select do |u|
+            u.sync_state! if u.respond_to?(:sync_state!)
+            target_states.include?(u.state)
+          end
+        end
+      end
+
+      def size
+        @monitor.synchronize { @units.size }
+      end
+
+      def empty?
+        @monitor.synchronize { @units.empty? }
+      end
+
+      def reap_dead_units!
+        @monitor.synchronize do
+          reaped = []
+          @units.each_value do |unit|
+            unit.sync_state! if unit.respond_to?(:sync_state!)
+            next unless unit.dead? && unit.state != :reaped
+
+            safely_dispose_context(unit)
+            unit.transition_to!(:reaped, reason: "reaped")
+            reaped << unit
+          end
+          @dmesg&.log(:kernel, :info, "reaped #{reaped.size} dead units", facility_id: "init") unless reaped.empty?
+          reaped
+        end
+      end
+
+      def kill(id, reason = "killed")
+        @monitor.synchronize do
+          unit = @units[id.to_s]
+          return false unless unit
+
+          safely_kill_unit(unit, reason)
+          true
+        end
+      end
+
+      def kill_all(reason = "killed")
+        @monitor.synchronize do
+          # LIFO shutdown: reverse chronological order of registered units
+          @order.reverse_each do |id|
+            unit = @units[id]
+            next unless unit
+
+            safely_kill_unit(unit, reason)
+          end
+          true
+        end
+      end
+
+      def resume_all
+        @monitor.synchronize do
+          resumed = []
+          @units.each_value do |unit|
+            unit.sync_state! if unit.respond_to?(:sync_state!)
+            next unless unit.paused?
+
+            begin
+              unit.respond_to?(:resume) ? unit.resume : unit.transition_to!(:active, reason: "resumed")
+              resumed << unit
+            rescue StandardError => e
+              @dmesg&.log(:kernel, :warn, "failed to resume unit:#{unit.id}: #{e.message}", facility_id: "init")
+            end
+          end
+          resumed
+        end
+      end
+
+      def stop
+        @monitor.synchronize do
+          return true if @stopped
+
+          @stopped = true
+        end
+
+        kill_all("init_stopped")
+        reap_dead_units!
+        @dmesg&.log(:kernel, :info, "init stopped; all units reaped", facility_id: "init")
+        true
+      end
+      alias dispose stop
+
+      def stopped?
+        @monitor.synchronize { @stopped }
+      end
+
+      private
+
+      def safely_kill_unit(unit, reason)
+        return if unit.dead?
+
+        if unit.respond_to?(:kill)
+          unit.kill(reason)
+        elsif unit.active? || unit.paused? || unit.pending?
+          unit.transition_to!(:failed, reason: reason)
+        end
+      rescue StandardError => e
+        @dmesg&.log(:kernel, :warn, "error killing unit:#{unit.id}: #{e.message}", facility_id: "init")
+      end
+
+      def safely_dispose_context(unit)
+        unit.context&.dispose if unit.context.respond_to?(:dispose)
+      rescue StandardError => e
+        @dmesg&.log(:kernel, :warn, "error disposing context for unit:#{unit.id}: #{e.message}", facility_id: "init")
+      end
+
+      def bind_context(ctx)
+        return unless ctx.respond_to?(:on_dispose)
+
+        ctx.on_dispose { stop }
+      end
+    end
+  end
+end

data/lib/rubik/kernel/record.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Kernel
+    SEVERITY_LEVELS = {
+      emerg: 0,
+      alert: 1,
+      crit: 2,
+      err: 3,
+      warn: 4,
+      notice: 5,
+      info: 6,
+      debug: 7
+    }.freeze
+
+    LEVEL_COLORS = {
+      emerg: "\e[1;31m",
+      alert: "\e[1;31m",
+      crit: "\e[1;31m",
+      err: "\e[31m",
+      warn: "\e[33m",
+      notice: "\e[36m",
+      info: "\e[32m",
+      debug: "\e[90m"
+    }.freeze
+
+    LEVEL_ALIASES = {
+      "error" => :err,
+      "warning" => :warn,
+      "critical" => :crit,
+      "emergency" => :emerg,
+      "informational" => :info
+    }.freeze
+
+    Record = Data.define(:seq, :uptime, :subsystem, :level, :facility_id, :message, :data) do
+      def format_line(color: false)
+        Rubik::Kernel.format_line(self, color: color)
+      end
+      alias_method :formatted, :format_line
+      alias_method :to_s, :format_line
+
+      def self.format_line(record, color: false)
+        Rubik::Kernel.format_line(record, color: color)
+      end
+    end
+
+    def self.normalize_level(lvl)
+      key = lvl.to_s.downcase.strip
+      sym = LEVEL_ALIASES.fetch(key, key.to_sym)
+      SEVERITY_LEVELS.key?(sym) ? sym : :info
+    end
+
+    def self.format_line(record, color: false)
+      uptime_str = format("[%+12.6f]", record.uptime)
+      fac = record.facility_id.to_s
+      tag = fac.empty? ? "[#{record.subsystem}]" : "[#{record.subsystem}/#{fac}]"
+      lvl_str = "#{record.level.to_s.upcase}:"
+      lvl_fmt = color ? "#{LEVEL_COLORS[record.level.to_sym] || ''}#{lvl_str}\e[0m" : lvl_str
+      "#{uptime_str} #{tag} #{lvl_fmt} #{record.message}#{payload_suffix(record)}"
+    end
+
+    # Session review B1: bus events land as message="event:<name>" with the
+    # facts (which server, why it failed) in `data` — rendered nowhere. Append
+    # a bounded key=value summary (6 keys, 160-char tails, flat newlines).
+    # safe_utf8 first: payload values carry raw error bodies (binary/UTF-16)
+    # and one poisoned record would cost the model the whole dmesg view.
+    def self.payload_suffix(record)
+      data = record.respond_to?(:data) ? record.data : nil
+      return "" unless data.is_a?(Hash) && !data.empty?
+
+      pairs = data.first(6).filter_map do |k, v|
+        flat = begin
+          Rubik::Platform.safe_utf8(v.to_s)
+        rescue StandardError
+          next
+        end.strip.tr("\r\n", " ").squeeze(" ")
+        next if flat.empty?
+
+        flat.length > 160 ? "#{k}=...#{flat[-160, 160]}" : "#{k}=#{flat}"
+      end
+      pairs << "(+#{data.size - 6} more)" if data.size > 6
+      pairs.empty? ? "" : " #{pairs.join(' ')}"
+    end
+  end
+end

data/lib/rubik/kernel/unit.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Rubik
+  module Kernel
+    # Kernel execution unit representing an asynchronous computation (Plan 104).
+    class Unit
+      class StateError < StandardError; end
+
+      VALID_TYPES = [:subagent, :process, :task, :service].freeze
+      VALID_STATES = [:pending, :active, :paused_error, :waiting_budget, :budget_exhausted, :completed, :failed, :reaped].freeze
+      TERMINAL_STATES = [:completed, :failed, :reaped].freeze
+      PAUSED_STATES = [:paused_error, :waiting_budget, :budget_exhausted].freeze
+
+      # Dmesg severity by TARGET state (bug-llm-timeout-observability): a
+      # stalled unit must surface in `dmesg(level: "err")` — error pauses and
+      # failures are err, budget parks are warn, everything else stays info.
+      TRANSITION_SEVERITIES = { paused_error: :err, failed: :err, waiting_budget: :warn, budget_exhausted: :warn }.freeze
+
+      attr_reader :id, :type, :state, :context, :facility_id, :created_at, :started_at, :finished_at, :reason
+      attr_accessor :dmesg, :dispatcher
+
+      def initialize(id:, type:, context: nil, facility_id: nil, state: :pending, dmesg: nil, dispatcher: nil, reason: nil, started_at: nil, finished_at: nil)
+        @id = id.to_s
+        @type = type.to_sym
+        @context = context
+        @reason = reason
+        @state = state.to_sym
+        @facility_id = facility_id || id.to_s
+        @created_at = Time.now
+        @started_at = started_at || (Time.now if @state == :active)
+        @finished_at = finished_at || (Time.now if dead?)
+        @dmesg = dmesg
+        @dispatcher = dispatcher
+        @monitor = Monitor.new
+      end
+
+      def transition_to!(new_state, reason: nil)
+        @monitor.synchronize do
+          target = new_state.to_sym
+          raise ArgumentError, "Invalid state: #{target}" unless VALID_STATES.include?(target)
+          return self if @state == target
+
+          raise StateError, "Terminal :#{@state} cannot transition to :#{target}" if @state == :reaped || ([:completed, :failed].include?(@state) && target != :reaped)
+
+          old_state = @state
+          @state = target
+          @reason = reason || @reason
+          @started_at ||= Time.now if target == :active
+          @finished_at ||= Time.now if TERMINAL_STATES.include?(target)
+          notify_transition(old_state, target, reason)
+          self
+        end
+      end
+
+      def active? = @state == :active
+      def running? = active?
+      def pending? = @state == :pending
+      def paused? = PAUSED_STATES.include?(@state)
+      def dead? = TERMINAL_STATES.include?(@state)
+      def reaped? = @state == :reaped
+      def uptime = @started_at ? ((@finished_at || Time.now) - @started_at).to_f : 0.0
+
+      def kill(reason = "killed")
+        stop_underlying
+        transition_to!(:failed, reason: reason) if active? || paused? || pending?
+      end
+
+      def resume(additional_steps: 10)
+        resume_underlying(additional_steps)
+        transition_to!(:active, reason: "resumed") if paused?
+      end
+
+      def sync_state!
+        return @state if dead?
+
+        new_st = underlying_state
+        transition_to!(new_st, reason: underlying_reason) if new_st && new_st != @state
+        @state
+      end
+
+      def to_h
+        { id: @id, type: @type, state: @state, facility_id: @facility_id, uptime: uptime.round(2),
+          created_at: @created_at, started_at: @started_at, finished_at: @finished_at, reason: @reason }
+      end
+
+      private
+
+      def stop_underlying = nil
+      def resume_underlying(_steps) = nil
+      def underlying_state = nil
+      def underlying_reason = nil
+
+      def notify_transition(from_state, to_state, reason)
+        suffix = " (#{reason})" if reason
+        msg = "unit:#{@id} state transition #{from_state} -> #{to_state}#{suffix}"
+        level = TRANSITION_SEVERITIES.fetch(to_state, :info)
+        subsystem = (@type == :subagent ? :subagent : :kernel)
+        @dmesg&.log(subsystem, level, msg, facility_id: @facility_id, unit_id: @id, from_state: from_state, to_state: to_state)
+        @dispatcher&.post(:unit_state_changed, unit_id: @id, type: @type, from_state: from_state,
+                                               to_state: to_state, reason: reason, facility_id: @facility_id,
+                                               subsystem: subsystem, level: level)
+      end
+    end
+
+    # Unit wrapper for managed child background processes (TaskManager tasks).
+    class ProcessUnit < Unit
+      STATUS_MAP = { running: :active, completed: :completed, failed: :failed, killed: :failed }.freeze
+      attr_reader :task, :task_manager
+
+      def initialize(task_or_id, task_manager: nil, context: nil, dmesg: nil, dispatcher: nil, **kwargs)
+        @task = task_or_id.respond_to?(:id) ? task_or_id : kwargs[:task]
+        @task_manager = task_manager
+        super(id: @task ? @task.id : task_or_id, type: :process, context: context,
+              facility_id: "process-#{@task ? @task.id : task_or_id}",
+              state: @task ? STATUS_MAP.fetch(@task.status, :pending) : kwargs.fetch(:state, :pending),
+              dmesg: dmesg, dispatcher: dispatcher, started_at: @task&.started_at, finished_at: @task&.ended_at, **kwargs)
+      end
+
+      private
+
+      def stop_underlying = @task_manager&.kill(@id)
+      def underlying_state = (@task ? STATUS_MAP.fetch(@task.status, :pending) : nil)
+      def underlying_reason = ("process failed" if @task&.status == :failed)
+    end
+
+    # Unit wrapper for autonomous subagents (Subagent::Instance).
+    class SubagentUnit < Unit
+      # Instance -> unit symbols, strict and COMPLETE: fetch has no default, unmapped fails
+      # loud (contract: keys == Instance::TRANSITIONS.keys; the kernel plane is coarser by design).
+      STATE_MAP = {
+        pending: :pending, running: :active, waiting_input: :active, waiting_budget: :waiting_budget, budget_exhausted: :budget_exhausted,
+        paused_error: :paused_error, canceling: :failed, completed: :completed, failed: :failed, disposed: :failed
+      }.freeze
+      attr_reader :instance
+
+      # birth_state: the activation seam's override (activation.rb) — a unit
+      # registered while its instance is settled must be born LIVE, never dead.
+      def initialize(inst_or_id, context: nil, dmesg: nil, dispatcher: nil, birth_state: nil, **kwargs)
+        @instance = inst_or_id.respond_to?(:id) ? inst_or_id : kwargs[:instance]
+        super(id: @instance ? @instance.id : inst_or_id, type: :subagent,
+              context: context || (@instance.context if @instance.respond_to?(:context)),
+              facility_id: "subagent-#{@instance ? @instance.id : inst_or_id}",
+              state: birth_state || (@instance ? STATE_MAP.fetch(@instance.state) : kwargs.fetch(:state, :pending)),
+              dmesg: dmesg, dispatcher: dispatcher, started_at: @instance&.started_at,
+              finished_at: @instance&.ended_at, **kwargs)
+        @instance.unit = self if @instance.respond_to?(:unit=)
+      end
+
+      private
+
+      def stop_underlying = (@instance&.kill if @instance.respond_to?(:kill))
+      def resume_underlying(steps) = (@instance.resume!(additional_steps: steps) if @instance.respond_to?(:resume!))
+      def underlying_state = (@instance ? STATE_MAP.fetch(@instance.state) : nil)
+      # Derived pause reasons (Narration seam), never a stored placeholder.
+      def underlying_reason = (@instance.last_error || @instance.result || @instance.state_note if @instance.respond_to?(:last_error))
+    end
+  end
+end