hames 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a98e47c0878e75c0da270c193f407260acc23f58614f81500c26095b837ebd9
-  data.tar.gz: 855c87d80768f619edd593bcfd98a176263a74fe1889aa70eb0b3b7ee021574e
+  metadata.gz: 9f376372b744ef6dac48af0a0577f32e8bb82d3834c13f0d2416927f2558c22a
+  data.tar.gz: a554420a27aa0850da074e9d9bb5a9069b75060d57a68b56e2fd064119548e64
 SHA512:
-  metadata.gz: 7446507cced8c24120f7b76b0a8e8c3bf2ad75e286c0deed5e392058bcefcd04887e5ecc7391fd70d97b8a7e7fab12dacf0f67338f71a57a17b965b19477faaa
-  data.tar.gz: 69a3b325769844792ee3f71bfffe9e5a364b813722c3874b35c7333f7e4846f586271b4906fbbecb30277c170e28ebb3b3b26c69fccca37f5afbc9f2c623f6a3
+  metadata.gz: 273414c4bc70159631dfb9c9d7239c97f8fab9fe0d370e1c4aec29ae89c4c550e88e06933ddb9d63c0e17bf5345051060bf9fd910b7fe81f195706a957622dfb
+  data.tar.gz: 659bd79c726c33ba9764df5b04fd76efeff316f1f157e1901ddc8980a6224e74778e08bdd418f51f1469054f93649bb03c93ff12bddb402221628ad59eeaadfb

data/lib/hames/context.rb

@@ -49,10 +49,28 @@ module Hames
 
     # Runs the block now; the block must return a disposer callable (or nil).
     # Disposal happens in reverse registration order, per owner, on unload.
+    # The disposer handed back is self-removing and idempotent: calling it
+    # runs the teardown once and drops its own entry from @effects, so a
+    # long-lived context does not pin every disposed registration (and
+    # whatever its closure captured). The done flag lives on the frame (not
+    # presence in @effects) because dispose_owner! removes frames from
+    # @effects BEFORE running them — a presence check would silently skip
+    # the real teardown there.
     def effect(&block)
       disposer = block.call
-      @effects << [@owner, disposer] if disposer
-      disposer
+      return disposer unless disposer
+
+      frame = [@owner, nil, false]
+      wrapped = lambda do
+        next if frame[2]
+
+        frame[2] = true
+        @effects.delete(frame)
+        disposer.call
+      end
+      frame[1] = wrapped
+      @effects << frame
+      wrapped
     end
 
     def with_owner(owner)
@@ -68,12 +86,16 @@ module Hames
       doomed = []
       @effects.each { |fr| (fr[0] == owner ? doomed : kept) << fr }
       @effects = kept
+      # each wrapped disposer re-scans @effects for a frame that the
+      # partition above already removed — an O(doomed·kept) miss. Negligible
+      # at current roster sizes; if owner disposal ever gets hot, carry the
+      # original disposer on the frame and call it directly here.
       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.dup.reverse_each { |(_o, d)| d.call }
       @effects.clear
     end
 
@@ -88,9 +110,7 @@ module Hames
       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
+      effect { -> { bucket.delete(l) } }
     end
 
     # Listeners visible to this context: parent chain first (registration
@@ -100,10 +120,18 @@ module Hames
       parent ? parent.listeners_for(name) + own : own.dup
     end
 
-    # emit: fire-and-forget, registration order, no return value.
+    # emit: fire-and-forget, registration order, no return value. Listener
+    # failures are isolated (warned, not raised): by the time listeners run,
+    # the producer's fact is already committed — a durable append emits after
+    # the store write — so a consumer bug must not un-happen it. The other
+    # modes raise through: their results are load-bearing.
     def emit(name, *args)
       Hames.assert_mode!(name, :emit)
-      listeners_for(name).each { |l| l.block.call(*args) }
+      listeners_for(name).each do |l|
+        l.block.call(*args)
+      rescue StandardError => e
+        warn "hames: emit(#{name}): listener isolated: #{e.class}: #{e.message}"
+      end
       nil
     end
 

data/lib/hames/events.rb

@@ -18,7 +18,11 @@ module Hames
     #   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?
+      if mode.nil?
+        return events.fetch(name) do
+          raise Hames::ContractError, "lookup of undeclared event #{name}"
+        end
+      end
 
       raise ArgumentError, "unknown dispatch mode #{mode.inspect}" unless MODES.include?(mode)
       if (existing = events[name]) && existing.mode != mode

data/lib/hames/loader.rb

@@ -4,16 +4,27 @@ 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
+    # config_schema (and its inheritance) comes from the DSL mixin, so a
+    # functional plugin that is not a Service can extend the same module and be
+    # schema'd identically (docs/composition.md §9).
+    extend Hames::Schema::DSL
+
     class << self
+      # Both class-level declarations are inherited: a subclass (a test
+      # double, a provider variant) mounts exactly like its parent unless it
+      # redeclares. inject accumulates down the chain; service_key overrides.
       def service_key(key = nil)
         @service_key = key.to_sym if key
-        @service_key
+        return @service_key if @service_key
+
+        superclass <= Hames::Service ? superclass.service_key : nil
       end
 
       def inject(*keys)
         @inject ||= []
         @inject.concat(keys.map(&:to_sym)) unless keys.empty?
-        @inject
+        inherited = superclass <= Hames::Service ? superclass.inject : []
+        inherited + @inject
       end
     end
 
@@ -32,6 +43,18 @@ module Hames
 
     def start(ctx); end
     def stop(ctx); end
+
+    # Hot-reload hook (plan §M6): the loader replaces config wholesale, then
+    # calls this. Override to re-derive whatever start captured. The default
+    # warns — a service running on stale knobs should say so, not hide it.
+    def reconfigure(_config)
+      warn "hames: #{self.class} does not support hot-reconfigure; remount the row to apply"
+    end
+
+    # Loader-only: swap the config object under the reader.
+    def replace_config!(config)
+      @config = config
+    end
   end
 
   Row = Data.define(:id, :plugin, :config, :disabled) do
@@ -46,7 +69,12 @@ module Hames
   # row with an existing id replaces that row's config wholesale (never a
   # deep merge); unknown ids append.
   class Loader
-    attr_reader :ctx, :rows
+    # `mounted` is insertion-ordered by boot!, which mounts in dependency
+    # order — so its reverse is exact reverse-dependency order, and that is
+    # what a teardown wants: a consumer comes down before what it injects.
+    # Row order cannot stand in for it, since an inserted row's position in
+    # the tree need not match where its dependencies put it.
+    attr_reader :ctx, :rows, :mounted
 
     def initialize(ctx = Context.new)
       @ctx = ctx
@@ -88,10 +116,44 @@ module Hames
       ctx
     end
 
+    # Hot config swap — wholesale, like layering, never a merge. Replaces the
+    # row's config, swaps the mounted service's, invokes its reconfigure hook
+    # under with_owner(id) (so hook-registered effects are owned by the row,
+    # not left ownerless), and emits config/updated when the app vocabulary
+    # declares it (hames itself declares no events and stays app-agnostic). A
+    # raising hook rolls the row and the service's config back to what they
+    # were before the call and re-raises — the swap is atomic, never split-brain.
+    def reconfigure!(id, config)
+      id = id.to_s
+      old_row = @rows.fetch(id) { raise KeyError, "no row #{id.inspect}" }
+      service = @mounted.fetch(id) { raise KeyError, "no mounted plugin #{id.inspect}" }
+      old_config = old_row.config
+      @rows[id] = Hames::Row.new(id: old_row.id, plugin: old_row.plugin, config: config, disabled: old_row.disabled)
+      service.replace_config!(config)
+      begin
+        ctx.with_owner(id) { service.reconfigure(config) }
+      rescue StandardError
+        @rows[id] = old_row
+        service.replace_config!(old_config)
+        raise
+      end
+      ctx.emit("config/updated", id, config) if Hames.declared?("config/updated")
+      config
+    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)
+      plugin = @mounted.fetch(id) { raise ArgumentError, "no mounted plugin #{id}" }
+      # Owner effects are disposed even when stop raises, so a wedged stop hook
+      # cannot strand this row's service registration and listeners; and the
+      # @mounted entry is dropped only AFTER a clean teardown, so a stop that
+      # raised keeps the row unloadable (a retry re-runs stop) rather than
+      # vanishing behind a misleading "no mounted plugin".
+      begin
+        plugin.stop(ctx) if plugin.respond_to?(:stop)
+      ensure
+        ctx.dispose_owner!(id)
+      end
+      @mounted.delete(id)
     end
 
     # Resolved tree, layer-agnostic view (for --dump-config).
@@ -118,6 +180,19 @@ module Hames
     def mount(row, plugin)
       ctx.with_owner(row.id) { plugin.apply(ctx) }
       @mounted[row.id] = plugin
+    rescue Exception # rubocop:disable Lint/RescueException
+      # apply raised partway through: whatever it registered before the raise is
+      # owned by this row, and this row is NOT in @mounted, so no unload! or
+      # shutdown could ever find those registrations to dispose them. Roll them
+      # back here so a failed mount leaves nothing live, then let the boot
+      # failure out unchanged. A raising disposer during rollback is warned
+      # rather than allowed to mask the failure that started it.
+      begin
+        ctx.dispose_owner!(row.id)
+      rescue StandardError => e
+        warn "hames: mount rollback for #{row.id}: a disposer raised: #{e.class}: #{e.message}"
+      end
+      raise
     end
   end
 end

data/lib/hames/schema.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Hames
+  # The kernel's own tiny config validator (docs/composition.md §9): a plain
+  # description of a service's config keys — for each one a type:, whether it is
+  # required:, an optional enum: of legal values, a default:, and a doc: string
+  # — plus the code that checks a config hash against it and reports what does
+  # not fit.
+  #
+  # Pure stdlib rather than dry-schema, because the kernel's zero-runtime-
+  # dependency rule is a design constraint rather than a coincidence (CLAUDE.md).
+  # The plan's §10 dry-schema mention is superseded by that rule.
+  class Schema
+    # Distinguishes a read of config_schema from a declaration: with no argument
+    # config_schema() reads the stored schema, config_schema({}) declares an
+    # empty one (a service that takes no config), and config_schema(key: {...})
+    # declares a populated one.
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
+    # One key's rules. `type` is a Class or an array of Classes (a union);
+    # [TrueClass, FalseClass] is how a boolean is spelled, since Ruby has no
+    # Boolean class. `default` documents what the service reads when the key is
+    # missing — it fills a missing key at read time, it does NOT merge into the
+    # config, because config layering is wholesale-replace (CLAUDE.md).
+    KeySpec = Data.define(:name, :type, :required, :enum, :default, :doc)
+
+    Result = Data.define(:errors, :warnings) do
+      def ok? = errors.empty?
+    end
+
+    # Class-level DSL. Hames::Service extends it so every service is schema-able;
+    # a functional plugin (one that only responds to apply, not a Service) can
+    # `extend Hames::Schema::DSL` to be schema'd too — that is how the OpenRouter
+    # plugin, which is not a Service, still carries a schema doctor can read.
+    module DSL
+      def config_schema(specs = UNSET)
+        return stored_config_schema if specs.equal?(UNSET)
+
+        @config_schema = Hames::Schema.build(specs)
+        Hames::Schema.register(self, @config_schema)
+        @config_schema
+      end
+
+      # Inherited like service_key and inject: a subclass that does not redeclare
+      # validates exactly like its parent.
+      def stored_config_schema
+        return @config_schema if defined?(@config_schema) && @config_schema
+
+        parent = superclass if respond_to?(:superclass)
+        parent.respond_to?(:config_schema) ? parent.config_schema : nil
+      end
+    end
+
+    # Every declared schema, class => schema, in declaration order. The catalog
+    # generator (rake config:catalog) walks this once the code is required, the
+    # way events:catalog walks Hames.catalog.
+    def self.declared = (@declared ||= {})
+    def self.register(klass, schema) = declared[klass] = schema
+    def self.reset_declared! = declared.clear # test hook
+
+    def self.build(specs)
+      keys = (specs || {}).to_h do |name, opts|
+        opts ||= {}
+        key = name.to_sym
+        [key, KeySpec.new(name: key, type: opts[:type], required: opts.fetch(:required, false),
+                          enum: opts[:enum], default: opts[:default], doc: opts[:doc])]
+      end
+      new(keys)
+    end
+
+    attr_reader :keys
+
+    def initialize(keys)
+      @keys = keys
+    end
+
+    # Validates a config hash without mutating it. `subject` names the row (or
+    # class) so an error reads as "sandbox: image is required but was not set" —
+    # a refusal that cannot say which of thirty rows it is about is one an
+    # operator cannot act on.
+    #
+    # A key that is absent OR present-but-nil counts as UNSET: a required unset
+    # key is an error, a non-required one is fine — its default applies, and an
+    # unset !env resolving to nil is an ordinary state (§5) rather than a fault.
+    # A non-nil value is checked against `type` and `enum`. Extra keys WARN
+    # rather than fail, because config rows grow.
+    #
+    # `redact:` governs whether a rejected value's CONTENT may appear in the
+    # message. It stays false for programmatic callers (which hold plain config,
+    # and a message naming the value is more useful), and doctor passes true
+    # because by the time it validates, a value is a materialized !env/!setting/
+    # !ruby result and may be a secret — so its message names the type only,
+    # never the content.
+    def validate(config, subject: nil, redact: false)
+      config ||= {}
+      prefix = subject ? "#{subject}: " : ""
+      errors = []
+
+      @keys.each_value do |spec|
+        value = config[spec.name]
+        if value.nil?
+          errors << "#{prefix}#{spec.name} is required but was not set" if spec.required
+          next
+        end
+        if spec.type && Array(spec.type).none? { |t| value.is_a?(t) }
+          got = redact ? Schema.article(value.class.name) : Schema.describe(value)
+          errors << "#{prefix}#{spec.name} must be #{Schema.type_desc(spec.type)}, got #{got}"
+        end
+        if spec.enum && !spec.enum.include?(value)
+          allowed = spec.enum.map(&:inspect).join(", ")
+          # Redacted: the allowed set is schema-defined and safe to print; the
+          # configured value is not, so it is named as out-of-set, not echoed.
+          errors << if redact
+                      "#{prefix}#{spec.name} must be one of #{allowed} (the configured value is not)"
+                    else
+                      "#{prefix}#{spec.name} must be one of #{allowed}, got #{value.inspect}"
+                    end
+        end
+      end
+
+      warnings = (config.keys - @keys.keys).map { |extra| "#{prefix}#{extra} is not a known config key" }
+      Result.new(errors: errors, warnings: warnings)
+    end
+
+    # A boolean is the TrueClass/FalseClass union, so it reads as "a boolean"
+    # rather than naming two classes nobody wrote in a config.
+    def self.type_desc(type)
+      types = Array(type)
+      return "a boolean" if types.sort_by(&:name) == [FalseClass, TrueClass]
+      return article(types.first.name) if types.length == 1
+
+      "one of #{types.map(&:name).join(', ')}"
+    end
+
+    # "an Integer", "a String" — the article chosen by the leading sound, close
+    # enough on class names, so a message never reads "a Integer".
+    def self.article(word)
+      word = word.to_s
+      /\A[aeiou]/i.match?(word) ? "an #{word}" : "a #{word}"
+    end
+
+    # A scalar renders as itself ("got 5", "got nil"); anything larger renders
+    # as its class, so a wrong Hash where a String was wanted does not paste a
+    # whole tree into a one-line status. Only reached when redact is false —
+    # doctor never lets a rejected value's content into a message.
+    def self.describe(value)
+      case value
+      when String, Numeric, Symbol, true, false then value.inspect
+      else value.class.to_s
+      end
+    end
+  end
+end

data/lib/hames.rb

@@ -4,9 +4,10 @@
 # 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"
+  VERSION = "0.1.1"
 end
 
 require_relative "hames/events"
 require_relative "hames/context"
+require_relative "hames/schema"
 require_relative "hames/loader"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hames
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Obie Fernandez
@@ -24,6 +24,7 @@ files:
 - lib/hames/context.rb
 - lib/hames/events.rb
 - lib/hames/loader.rb
+- lib/hames/schema.rb
 homepage: https://terret.org
 licenses:
 - MIT