hames 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a98e47c0878e75c0da270c193f407260acc23f58614f81500c26095b837ebd9
+  data.tar.gz: 855c87d80768f619edd593bcfd98a176263a74fe1889aa70eb0b3b7ee021574e
+SHA512:
+  metadata.gz: 7446507cced8c24120f7b76b0a8e8c3bf2ad75e286c0deed5e392058bcefcd04887e5ecc7391fd70d97b8a7e7fab12dacf0f67338f71a57a17b965b19477faaa
+  data.tar.gz: 69a3b325769844792ee3f71bfffe9e5a364b813722c3874b35c7333f7e4846f586271b4906fbbecb30277c170e28ebb3b3b26c69fccca37f5afbc9f2c623f6a3

data/lib/hames/context.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Hames
+  # A Context is a repository of services and an event bus. Plugins mount into
+  # a context, claim service keys, register listeners, and install reversible
+  # effects. Forked contexts inherit parent services and listeners; their own
+  # registrations dispose independently (the per-agent scope primitive).
+  class Context
+    Listener = Data.define(:name, :block, :prepend, :owner)
+
+    attr_reader :parent
+
+    def initialize(parent: nil)
+      @parent    = parent
+      @services  = {}
+      @listeners = Hash.new { |h, k| h[k] = [] }
+      @effects   = [] # frames: [owner, disposer] in registration order
+      @owner     = nil # plugin id currently mounting (set by Loader)
+    end
+
+    # -- services -----------------------------------------------------------
+
+    def register_service(key, instance)
+      key = key.to_sym
+      raise ContractError, "service #{key} already registered" if @services.key?(key)
+
+      @services[key] = instance
+      effect { -> { @services.delete(key) } }
+      instance
+    end
+
+    def [](key)
+      key = key.to_sym
+      @services[key] || parent&.[](key) ||
+        raise(ServiceMissingError, "no service registered at ctx[:#{key}]")
+    end
+
+    def service?(key) = @services.key?(key.to_sym) || parent&.service?(key) || false
+
+    def method_missing(name, *args, &blk)
+      service?(name) && args.empty? && blk.nil? ? self[name] : super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      service?(name) || super
+    end
+
+    # -- effects (reversible registrations) ---------------------------------
+
+    # Runs the block now; the block must return a disposer callable (or nil).
+    # Disposal happens in reverse registration order, per owner, on unload.
+    def effect(&block)
+      disposer = block.call
+      @effects << [@owner, disposer] if disposer
+      disposer
+    end
+
+    def with_owner(owner)
+      prev, @owner = @owner, owner
+      yield
+    ensure
+      @owner = prev
+    end
+
+    # Dispose everything owned by `owner` (a plugin id), reverse order.
+    def dispose_owner!(owner)
+      kept = []
+      doomed = []
+      @effects.each { |fr| (fr[0] == owner ? doomed : kept) << fr }
+      @effects = kept
+      doomed.reverse_each { |(_o, d)| d.call }
+    end
+
+    # Dispose the whole context (child scopes call this when they end).
+    def dispose!
+      @effects.reverse_each { |(_o, d)| d.call }
+      @effects.clear
+    end
+
+    # -- events --------------------------------------------------------------
+
+    # Register a listener. Mode is validated against the event declaration.
+    # Returns a disposer and records it as an effect of the current owner.
+    def on(name, prepend: false, &block)
+      name = name.to_s
+      raise ContractError, "listener for undeclared event #{name}" unless Hames.declared?(name)
+
+      l = Listener.new(name:, block:, prepend:, owner: @owner)
+      bucket = @listeners[name]
+      prepend ? bucket.unshift(l) : bucket.push(l)
+      disposer = -> { bucket.delete(l) }
+      @effects << [@owner, disposer]
+      disposer
+    end
+
+    # Listeners visible to this context: parent chain first (registration
+    # order preserved within each context), respecting prepend within buckets.
+    def listeners_for(name)
+      own = @listeners[name.to_s]
+      parent ? parent.listeners_for(name) + own : own.dup
+    end
+
+    # emit: fire-and-forget, registration order, no return value.
+    def emit(name, *args)
+      Hames.assert_mode!(name, :emit)
+      listeners_for(name).each { |l| l.block.call(*args) }
+      nil
+    end
+
+    # waterfall: around-middleware. Each listener receives (*args, next_).
+    # Calling next_.(payload) delegates; returning without calling next_
+    # short-circuits. The innermost next_ returns its (possibly rewritten)
+    # payload — or calls the base block if one is given.
+    def waterfall(name, *args, &base)
+      Hames.assert_mode!(name, :waterfall)
+      chain = listeners_for(name)
+      invoke = lambda do |i, current_args|
+        if i >= chain.length
+          base ? base.call(*current_args) : current_args.first
+        else
+          next_ = ->(*rewritten) { invoke.call(i + 1, rewritten.empty? ? current_args : rewritten) }
+          chain[i].block.call(*current_args, next_)
+        end
+      end
+      invoke.call(0, args)
+    end
+
+    # parallel: all listeners observe the event; awaited as a group. Without
+    # a reactor this runs each in sequence but preserves the contract that
+    # dispatch completes only when every listener has. (Under terret's async
+    # runtime this maps onto an Async barrier.)
+    def parallel(name, *args)
+      Hames.assert_mode!(name, :parallel)
+      listeners_for(name).each { |l| l.block.call(*args) }
+      nil
+    end
+
+    # serial: ordered, awaited, single-decision. The first non-nil listener
+    # return value wins and stops dispatch.
+    def serial(name, *args)
+      Hames.assert_mode!(name, :serial)
+      listeners_for(name).each do |l|
+        result = l.block.call(*args)
+        return result unless result.nil?
+      end
+      nil
+    end
+
+    # -- fork ----------------------------------------------------------------
+
+    # Child scope: sees parent services and listeners; its own registrations
+    # dispose when the scope ends (or when its owner unloads).
+    def fork = Context.new(parent: self)
+  end
+end

data/lib/hames/events.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hames
+  # Runtime event contracts. Every event is declared once with its dispatch
+  # mode (and optionally a durability flag and payload class). The bus refuses
+  # to dispatch undeclared events or to dispatch a declared event through the
+  # wrong mode. This is the Ruby replacement for Cordis's TypeScript
+  # declaration-merged event typing.
+  MODES = %i[emit waterfall parallel serial].freeze
+
+  EventDecl = Data.define(:name, :mode, :durable, :payload, :doc)
+
+  class << self
+    def events = (@events ||= {})
+
+    # Declare (or look up) an event contract.
+    #
+    #   Hames.event "tools/pre_execute", mode: :waterfall, payload: Tools::Call
+    def event(name, mode: nil, durable: false, payload: nil, doc: nil)
+      name = name.to_s
+      return events.fetch(name) if mode.nil?
+
+      raise ArgumentError, "unknown dispatch mode #{mode.inspect}" unless MODES.include?(mode)
+      if (existing = events[name]) && existing.mode != mode
+        raise Hames::ContractError,
+              "event #{name} already declared with mode #{existing.mode}, got #{mode}"
+      end
+
+      events[name] = EventDecl.new(name:, mode:, durable:, payload:, doc:)
+    end
+
+    def declared?(name) = events.key?(name.to_s)
+
+    def assert_mode!(name, mode)
+      decl = events[name.to_s]
+      raise Hames::ContractError, "dispatch of undeclared event #{name}" unless decl
+      return if decl.mode == mode
+
+      raise Hames::ContractError,
+            "event #{name} is #{decl.mode}, dispatched as #{mode}"
+    end
+
+    # Generated documentation source: [ [name, mode, durable, doc], ... ]
+    def catalog
+      events.values.sort_by(&:name).map { |d| [d.name, d.mode, d.durable, d.doc] }
+    end
+
+    def reset_events! = events.clear # test hook
+  end
+
+  class ContractError < StandardError; end
+  class CycleError < StandardError; end
+  class ServiceMissingError < StandardError; end
+end

data/lib/hames/loader.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Hames
+  # Base class for service plugins. A plugin may instead be any object that
+  # responds to apply(ctx) (the functional form), with optional #inject.
+  class Service
+    class << self
+      def service_key(key = nil)
+        @service_key = key.to_sym if key
+        @service_key
+      end
+
+      def inject(*keys)
+        @inject ||= []
+        @inject.concat(keys.map(&:to_sym)) unless keys.empty?
+        @inject
+      end
+    end
+
+    attr_reader :config
+
+    def initialize(config = {})
+      @config = config
+    end
+
+    def inject = self.class.inject
+
+    def apply(ctx)
+      ctx.register_service(self.class.service_key, self) if self.class.service_key
+      start(ctx)
+    end
+
+    def start(ctx); end
+    def stop(ctx); end
+  end
+
+  Row = Data.define(:id, :plugin, :config, :disabled) do
+    def self.build(h)
+      new(id: h.fetch(:id).to_s, plugin: h.fetch(:plugin),
+          config: h[:config] || {}, disabled: h[:disabled] || false)
+    end
+  end
+
+  # Mounts config rows into a context in dependency order derived from each
+  # plugin's inject list. Layers apply as ordered row lists; a later layer's
+  # row with an existing id replaces that row's config wholesale (never a
+  # deep merge); unknown ids append.
+  class Loader
+    attr_reader :ctx, :rows
+
+    def initialize(ctx = Context.new)
+      @ctx = ctx
+      @rows = {} # id => Row
+      @mounted = {} # id => plugin instance
+    end
+
+    def layer(row_hashes)
+      row_hashes.each do |h|
+        id = h.fetch(:id).to_s
+        if (existing = @rows[id])
+          # patch: wholesale config replacement; plugin class may also swap
+          @rows[id] = Hames::Row.new(
+            id: id,
+            plugin: h[:plugin] || existing.plugin,
+            config: h.key?(:config) ? (h[:config] || {}) : existing.config,
+            disabled: h.key?(:disabled) ? h[:disabled] : existing.disabled
+          )
+        else
+          @rows[id] = Row.build(h)
+        end
+      end
+      self
+    end
+
+    # Mount all enabled rows. Plugins whose injected services are not yet
+    # present wait; repeated passes mount whatever has become satisfiable.
+    # No progress with plugins still pending => cycle / missing provider.
+    def boot!
+      pending = @rows.values.reject(&:disabled).map { |r| [r, instantiate(r)] }
+      until pending.empty?
+        ready, pending = pending.partition { |(_r, pl)| satisfied?(pl) }
+        if ready.empty?
+          missing = pending.map { |(r, pl)| "#{r.id} (needs #{unmet(pl).join(', ')})" }
+          raise CycleError, "cannot mount: #{missing.join('; ')}"
+        end
+        ready.each { |(r, pl)| mount(r, pl) }
+      end
+      ctx
+    end
+
+    def unload!(id)
+      plugin = @mounted.delete(id) or raise ArgumentError, "no mounted plugin #{id}"
+      plugin.stop(ctx) if plugin.respond_to?(:stop)
+      ctx.dispose_owner!(id)
+    end
+
+    # Resolved tree, layer-agnostic view (for --dump-config).
+    def dump_config
+      @rows.values.map { |r| { id: r.id, plugin: r.plugin.to_s, config: r.config, disabled: r.disabled } }
+    end
+
+    private
+
+    def instantiate(row)
+      k = row.plugin
+      k.is_a?(Class) ? k.new(row.config) : k
+    end
+
+    def satisfied?(plugin)
+      unmet(plugin).empty?
+    end
+
+    def unmet(plugin)
+      needs = plugin.respond_to?(:inject) ? Array(plugin.inject) : []
+      needs.reject { |key| ctx.service?(key) }
+    end
+
+    def mount(row, plugin)
+      ctx.with_owner(row.id) { plugin.apply(ctx) }
+      @mounted[row.id] = plugin
+    end
+  end
+end

data/lib/hames.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Hames is Terret's plugin kernel: services in a context, typed events with
+# four dispatch modes, reversible effects, and dependency-driven boot. It has
+# no knowledge of LLMs and is reusable for any plugin-composed application.
+module Hames
+  VERSION = "0.1.0"
+end
+
+require_relative "hames/events"
+require_relative "hames/context"
+require_relative "hames/loader"

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: hames
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Hames is a small plugin kernel for Ruby: services resolved by key in
+  a context, typed events with four dispatch modes enforced at runtime, reversible
+  registrations, and dependency-driven boot. It has no knowledge of LLMs and is reusable
+  for any plugin-composed application. It is the kernel underneath the Terret agent
+  harness.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/hames.rb
+- lib/hames/context.rb
+- lib/hames/events.rb
+- lib/hames/loader.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret
+  bug_tracker_uri: https://github.com/terret-org/terret/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Plugin kernel: services, typed events, reversible effects'
+test_files: []