singulus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac98626fb3bc3db2c925dc5a31d25655501aa36544907ee9ba95d87b3e7e3917
+  data.tar.gz: 371565dd472005e3a4038a0fd7ad1d9fa2679fe237b610072101c5a541b7f821
+SHA512:
+  metadata.gz: 5a6826300e20a88e8ae1e811cd1525c7f3cd38dcb6628d22608c92e2fc9ebc7029774288b2b990742783222f98f9054d188e5d892852a3bc7da8cf74181f71cc
+  data.tar.gz: 8d7b79fbcaac93d423b22c82856539e57c6ed3f718cbed8a22a1ca2f6760c45d2e47c42c1db3a11bfb1bda1033cf6800cfcf3029474693add6f54e8fb876855f

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
+
+## [Unreleased]
+
+### Fixed
+
+- Completed the final RuboCop cleanup across Multiton and specs.
+- Removed `refuse_coverage_drop`; coverage is enforced by absolute minimums of 95% line and 90% branch.
+
+- Normalized RuboCop policy so local Rubcraft checks and GitHub CI enforce the same repository-local configuration.
+- Fixed production-code indentation/alignment issues introduced during the `Singulus::Internal` refactor.
+- Removed the redundant `thread` require.
+- Added RubyGems MFA metadata.
+- Moved development tooling declarations to Gemfile.
+- Kept intentional reflection interception, internal ivar naming, Multiton complexity, and contract-style specs explicitly documented in RuboCop configuration.
+
+- Added a small coverage buffer for safe mutation/reflection fallthrough paths and repeated runtime-hardening activation.
+
+- Made RuboCop configuration explicit and repository-local for identical local/CI behavior.
+- CI and release workflows now pass `.rubocop.yml` explicitly.
+- Standardized the project on double-quoted Ruby strings.
+
+- Added `bundler-audit` as a development dependency so Rubcraft's mandatory audit gate runs through the repository bundle.
+
+- Fixed `InstanceGuard#clone` so it does not forward an implicit `freeze:` keyword to Ruby Singleton implementations that accept no arguments.
+- Corrected standard-mode reflection coverage: reflective constructor access is intentionally available when local hardening is disabled.
+- Corrected runtime-hardening coverage to distinguish blocked reflection gateways from safe non-gateway UnboundMethod binding.
+
+- Added branch-focused behavior coverage for standard-mode fallthroughs, reflection guards, runtime-hardening negative paths, and valid Multiton retention branches.
+
+- Corrected runtime Method composition specs to distinguish `Method#<<`/`Method#>>` from `Proc#<<` composition semantics.
+
+- Expanded behavioral coverage for configuration normalization, public reflection guards, Multiton registry edge cases, forwarding semantics, standard-mode inheritance, and runtime Method composition.
+
+- Corrected RSpec expectations for sealed constructor access.
+- Corrected Multiton key-stabilization coverage to use genuinely mutable input under `frozen_string_literal`.
+- Corrected Hash identifiers to be passed positionally under Ruby 3 keyword argument semantics.
+
+## [0.1.0] - 2026-08-21
+
+### Changed
+
+- Reduced the public root API to `Singulus::Singleton`, `Singulus::Multiton`, `Singulus::Error`, `Singulus::VERSION`, and the configuration facade.
+- Moved implementation classes, guards, configuration objects, and specialized exceptions behind a private `Singulus::Internal` namespace.
+- Marked Multiton implementation constants (`RETENTIONS`, `Entry`, and `ClassMethods`) private.
+- Added a public API contract spec to prevent accidental constant leakage.
+
+### Added
+
+- `Singulus::Singleton` for one managed instance per class.
+- `Singulus::Multiton` for one managed instance per normalized identifier.
+- `:standard`, `:strict`, and `:runtime` hardening modes.
+- Include-time configuration with `Singulus::Singleton.with(...)` and `Singulus::Multiton.with(...)`.
+- Two-step `singulus` DSL in addition to include-time `.with(...)` configuration.
+- Multiton key normalization and defensive stabilization of common mutable keys.
+- `:forever`, `:lru`, `:ttl`, `:bounded`, and `:weak` Multiton retention strategies.
+- Explicit Multiton lifecycle operations: `instance?`, `instance_count`, `instance_keys`, `delete_instance`, and `clear_instances`.
+- Thread-safe Singleton and Multiton initialization.
+- Recursive Multiton initialization detection.
+- Constructor, duplication, inheritance, mutation, and reflection guards in hardened modes.
+- Runtime protection for common captured `Method` and `UnboundMethod` constructor/reflection paths.
+- RSpec, RuboCop, SimpleCov, GitHub Actions CI, and RubyGems Trusted Publishing workflow.
+
+### Security
+
+- Guard `new` and `allocate` from the moment hardened Singulus modules are included.
+- Prevent constructor bypass by changing constructor visibility.
+- Reject constructor redefinition attempts in hardened modes.
+- Protect common reflective constructor access paths.
+- Protect captured `Method` and `UnboundMethod` paths in `:runtime` mode.
+
+[Unreleased]: https://github.com/Rubcraft/singulus/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Rubcraft/singulus/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,248 @@
+# Singulus
+
+[![CI](https://github.com/Rubcraft/singulus/actions/workflows/ci.yml/badge.svg)](https://github.com/Rubcraft/singulus/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/singulus.svg)](https://rubygems.org/gems/singulus)
+
+
+`Singulus` adds configurable Ruby-level hardening around two instance-uniqueness patterns:
+
+- `Singulus::Singleton` — one instance per class and Ruby process.
+- `Singulus::Multiton` — one registered instance per class and normalized key.
+
+It builds on Ruby's standard `Singleton` for the classic Singleton implementation and provides its own thread-safe keyed registry for Multiton.
+
+Singulus exposes one supported entry point:
+
+```ruby
+require "singulus"
+```
+
+The supported root API is intentionally small:
+
+- `Singulus::Singleton`
+- `Singulus::Multiton`
+- `Singulus::Error` as the public base exception
+- `Singulus.configure`, `Singulus.configuration`, and `Singulus.reset_configuration!`
+- `Singulus::VERSION`
+
+All implementation classes, guards, configuration types, and specialized errors live behind a private `Singulus::Internal` namespace and are not public constants. No pre-release compatibility entry points are shipped.
+
+## Security boundary
+
+This gem is aggressive Ruby-level hardening, **not a sandbox**. Code executing in the same Ruby process can reopen core classes, use native extensions, replace guards, or otherwise modify the runtime. `:runtime` closes many common `Method`/`UnboundMethod` bypasses, but it cannot create a cryptographic or process-isolation boundary.
+
+## Modes
+
+```ruby
+Singulus.configure do |config|
+  config.default_mode = :strict
+end
+```
+
+Available modes:
+
+- `:standard` — minimal policy. Classic Singleton delegates to Ruby `Singleton`; Multiton keeps constructors private but does not install local hardening policy.
+- `:strict` — constructor reflection guards, mutation protection, duplication protection, inheritance restrictions, and constructor sealing for classic Singleton.
+- `:runtime` — everything in `:strict`, plus process-wide `Method` and `UnboundMethod` guards that activate only for classes marked as runtime-hardened.
+
+The default is `:strict`.
+
+### Configure directly from `include`
+
+`Singleton` and `Multiton` also expose `.with(...)`, which creates an independent configured inclusion module. It does not mutate the shared `Singulus::Singleton` or `Singulus::Multiton` module.
+
+```ruby
+class Configuration
+  include Singulus::Singleton.with(:strict)
+end
+
+class RuntimeConfiguration
+  include Singulus::Singleton.with(mode: :runtime)
+end
+
+class TenantConfiguration
+  include Singulus::Multiton.with(
+    :runtime,
+    retention: :lru,
+    max_size: 5_000
+  )
+end
+```
+
+The existing two-step DSL remains supported and equivalent:
+
+```ruby
+include Singulus::Singleton
+singulus mode: :strict
+```
+
+## Classic Singleton
+
+```ruby
+require "singulus"
+
+class Configuration
+  include Singulus::Singleton.with(:runtime)
+end
+
+Configuration.instance.equal?(Configuration.instance)
+# => true
+```
+
+In hardened modes, direct constructor access is guarded from the moment the module is included, including attempts to change constructor visibility. Common reflection routes, duplication, constructor redefinition, and inheritance are rejected. After the first `instance`, classic Singleton also seals its constructor lookup path.
+
+## Multiton: one instance per identifier
+
+```ruby
+class TenantConfiguration
+  include Singulus::Multiton.with(:strict)
+
+  def initialize(tenant_id)
+    @tenant_id = tenant_id
+  end
+end
+
+one = TenantConfiguration.instance_for(10)
+two = TenantConfiguration.instance_for(10)
+other = TenantConfiguration.instance_for(20)
+
+one.equal?(two)   # => true
+one.equal?(other) # => false
+```
+
+`instance_for(identifier, *args, **kwargs)` passes the original identifier as the first initializer argument. Additional initializer arguments are used only when an instance for that normalized key does not already exist.
+
+### Stable tenant keys
+
+Prefer immutable identifiers such as integers, symbols, UUID strings, or normalized composite keys. Strings, arrays, and hashes returned as keys are defensively duplicated/frozen recursively where practical.
+
+For domain objects, define a key normalizer:
+
+```ruby
+class TenantConfiguration
+  include Singulus::Multiton
+
+  multiton_key { |tenant| tenant.id }
+
+  def initialize(tenant)
+    @tenant = tenant
+  end
+end
+```
+
+This avoids retaining an ActiveRecord object itself as the registry key.
+
+## Multiton lifecycle
+
+```ruby
+TenantConfiguration.instance?(10)
+TenantConfiguration.instance_count
+TenantConfiguration.instance_keys
+TenantConfiguration.delete_instance(10)
+TenantConfiguration.clear_instances
+```
+
+`delete_instance` and `clear_instances` explicitly release registry ownership. If another part of the application still holds the old object, a later `instance_for` can create a new object for the same key. Therefore uniqueness is **registry/lifecycle scoped**, not a claim that no second live Ruby object can ever exist after explicit release or eviction.
+
+## Retention strategies
+
+The default is strict registry retention:
+
+```ruby
+class TenantConfiguration
+  include Singulus::Multiton
+  multiton_retention :forever
+end
+```
+
+Supported strategies:
+
+### `:forever`
+
+Keeps each registered instance until `delete_instance`/`clear_instances` or process exit. This is the strongest per-key identity guarantee supplied by Multiton.
+
+### `:lru`
+
+```ruby
+multiton_retention :lru, max_size: 5_000
+```
+
+Bounds memory by evicting the least recently used registry entry. Once evicted, the same key can create a new instance later.
+
+### `:ttl`
+
+```ruby
+multiton_retention :ttl, ttl: 300
+```
+
+Keeps an instance for a fixed TTL measured with `Process::CLOCK_MONOTONIC`. Expiration is based on creation time, not sliding access time. After expiration, the same key can create a new instance.
+
+### `:bounded`
+
+```ruby
+multiton_retention :bounded, ttl: 300, max_size: 5_000
+```
+
+Combines TTL expiration with an LRU capacity bound. Entries are evicted when they expire or when the registry exceeds `max_size`. Use this instead of passing `max_size` to `:ttl` or `ttl` to `:lru`; those ambiguous configurations are rejected.
+
+### `:weak`
+
+```ruby
+multiton_retention :weak
+```
+
+Stores weak references. Singulus reuses the same object while it remains alive elsewhere, but the garbage collector may reclaim it when no strong references remain. A later `instance_for` can therefore create a new instance. `:weak` accepts neither `ttl` nor `max_size`.
+
+| Strategy | `ttl` | `max_size` | Identity scope |
+| --- | --- | --- | --- |
+| `:forever` | no | no | until explicit release/process exit |
+| `:lru` | no | required | while retained by capacity |
+| `:ttl` | required | no | until expiration |
+| `:bounded` | required | required | until expiration or capacity eviction |
+| `:weak` | no | no | while the object remains strongly referenced |
+
+`multiton_key` and retention configuration are locked while the registry contains instances. Call `clear_instances` before changing them deliberately.
+
+## Runtime hardening
+
+Runtime mode additionally guards common bypasses involving:
+
+- `Method#call`
+- `Method#[]`
+- `Method#to_proc`
+- `Method#>>` / `Method#<<`
+- `UnboundMethod#bind`
+- `UnboundMethod#bind_call`
+- captured reflection gateways such as `Object#method` and `BasicObject#__send__`
+
+The patches are installed process-wide once required, but their rejection logic only activates for classes marked `:runtime`.
+
+Enable runtime mode as early as possible during boot:
+
+```ruby
+Singulus.configure do |config|
+  config.default_mode = :runtime
+end
+```
+
+For Rails, place this in an early initializer before code that might capture constructor references.
+
+A `Proc` created from a constructor `Method` *before* Singulus runtime hardening is enabled cannot be retroactively identified as constructor-derived. Enable `:runtime` during boot, before untrusted or extension code can capture such references.
+
+## Development
+
+```bash
+bundle install
+bundle exec rubocop --parallel
+bundle exec rspec
+bundle exec bundler-audit check --update
+bundle exec rake build
+```
+
+SimpleCov enforces line and branch coverage, while CI tests supported Ruby versions independently from RuboCop.
+
+## Releasing
+
+Repository initialization, version-control operations, and release-tag creation are managed by the Rubcraft Toolkit. Singulus itself does not prescribe or duplicate those commands.
+
+The repository keeps only the CI/publish boundary: `.github/workflows/release.yml` reacts to a version tag produced by the Toolkit, verifies that it matches `Singulus::VERSION`, runs quality checks, builds the gem, and publishes through RubyGems Trusted Publishing (OIDC). Configure a GitHub environment named `release` and the matching RubyGems Trusted Publisher before the first release.

data/lib/singulus/internal/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    class Configuration
+      MODES = %i[standard strict runtime].freeze
+
+      attr_reader :default_mode
+
+      def initialize
+        self.default_mode = :strict
+      end
+
+      def default_mode=(mode)
+        mode = normalize_mode(mode)
+
+        unless MODES.include?(mode)
+          raise InvalidModeError,
+                "invalid Singulus mode #{mode.inspect}; expected one of: #{MODES.join(', ')}"
+        end
+
+        @default_mode = mode
+      end
+
+      private
+
+      def normalize_mode(mode)
+        mode.to_sym
+      rescue NoMethodError
+        mode
+      end
+    end
+  end
+end

data/lib/singulus/internal/constructor_guard.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    module ConstructorGuard
+      private
+
+      def new(...)
+        singulus_reject_unauthorized_constructor!(:new)
+        super
+      end
+
+      def allocate
+        singulus_reject_unauthorized_constructor!(:allocate)
+        super
+      end
+
+      def singulus_reject_unauthorized_constructor!(method_name)
+        return unless Internal.locally_hardened?(self)
+        return if Internal.constructor_access_allowed?(self)
+
+        raise ConstructorAccessError,
+              "constructor #{method_name.inspect} is inaccessible for #{Internal.kind_for(self)} #{self}"
+      end
+    end
+  end
+end

data/lib/singulus/internal/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Singulus
+  class Error < StandardError; end
+
+  module Internal
+    class ConstructorAccessError < Singulus::Error; end
+    class DuplicationError < Singulus::Error; end
+    class InheritanceError < Singulus::Error; end
+    class InvalidModeError < Singulus::Error; end
+    class InvalidRetentionError < Singulus::Error; end
+    class ConfigurationLockedError < Singulus::Error; end
+    class RecursiveInitializationError < Singulus::Error; end
+  end
+end

data/lib/singulus/internal/instance_guard.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    module InstanceGuard
+      def dup
+        singulus_reject_duplication!(:duplicated)
+        super
+      end
+
+      def clone(**options)
+        singulus_reject_duplication!(:cloned)
+        return super() if options.empty?
+
+        super
+      end
+
+      def initialize_dup(other)
+        singulus_reject_duplication!(:duplicated)
+        super
+      end
+
+      def initialize_clone(other, **kwargs)
+        singulus_reject_duplication!(:cloned)
+        super
+      end
+
+      private
+
+      def singulus_reject_duplication!(operation)
+        return unless Internal.locally_hardened?(self.class)
+
+        raise DuplicationError, "#{self.class} instance cannot be #{operation} in hardened mode"
+      end
+    end
+  end
+end

data/lib/singulus/internal/mutation_guard.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    module MutationGuard
+      def singleton_method_added(method_name)
+        return super if @__singulus_restoring_constructor__
+        return super unless Internal.locally_hardened?(self)
+        return super unless Internal.constructor_name?(method_name)
+
+        singulus_restore_constructor!(method_name)
+
+        raise ConstructorAccessError,
+              "constructor #{method_name.inspect} cannot be redefined on #{Internal.kind_for(self)} #{self}"
+      end
+
+      private
+
+      def singulus_restore_constructor!(method_name)
+        @__singulus_restoring_constructor__ = true
+        singleton_class.__send__(:remove_method, method_name)
+
+        if Internal.sealed_singleton?(self)
+          singleton_class.__send__(:undef_method, method_name)
+        else
+          private_class_method method_name
+        end
+      ensure
+        @__singulus_restoring_constructor__ = false
+      end
+    end
+  end
+end

data/lib/singulus/internal/reflection_guard.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    module ReflectionGuard
+      def method(method_name)
+        singulus_reject_constructor_access!(method_name)
+        super
+      end
+
+      def public_method(method_name)
+        singulus_reject_constructor_access!(method_name)
+        super
+      end
+
+      def singleton_method(method_name)
+        singulus_reject_constructor_access!(method_name)
+        super
+      end
+
+      def send(method_name, ...)
+        singulus_reject_constructor_access!(method_name)
+        super
+      end
+
+      def __send__(method_name, ...)
+        singulus_reject_constructor_access!(method_name)
+        super
+      end
+
+      def public_send(method_name, ...)
+        singulus_reject_constructor_access!(method_name)
+        super
+      end
+
+      private
+
+      def singulus_reject_constructor_access!(method_name)
+        return unless Internal.locally_hardened?(self)
+        return unless Internal.constructor_name?(method_name)
+
+        raise ConstructorAccessError,
+              "constructor #{method_name.inspect} is inaccessible for #{Internal.kind_for(self)} #{self}"
+      end
+    end
+  end
+end

data/lib/singulus/internal/runtime_hardening.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    module RuntimeHardening
+      REFLECTION_GATEWAYS = %i[
+        method
+        public_method
+        singleton_method
+        send
+        __send__
+        public_send
+      ].freeze
+
+      module UnboundMethodGuard
+        def bind(object)
+          singulus_reject_binding!(object)
+          super
+        end
+
+        def bind_call(object, *args, &)
+          singulus_reject_bind_call!(object, args)
+          super
+        end
+
+        private
+
+        def singulus_reject_binding!(object)
+          return unless Internal.runtime_hardened?(object)
+          return unless Internal.constructor_name?(name) || RuntimeHardening.reflection_gateway?(name)
+
+          raise ConstructorAccessError,
+                "cannot bind #{owner}##{name} to runtime-hardened Singulus #{object}"
+        end
+
+        def singulus_reject_bind_call!(object, args)
+          return unless Internal.runtime_hardened?(object)
+
+          if Internal.constructor_name?(name)
+            raise ConstructorAccessError,
+                  "cannot invoke constructor #{owner}##{name} on runtime-hardened Singulus #{object}"
+          end
+
+          return unless RuntimeHardening.reflection_gateway?(name)
+          return unless Internal.constructor_name?(args.first)
+
+          raise ConstructorAccessError,
+                "cannot use #{owner}##{name} to access constructor #{args.first.inspect} " \
+                "on runtime-hardened Singulus #{object}"
+        end
+      end
+
+      module MethodGuard
+        def call(*args, &)
+          singulus_reject_invocation!(args)
+          super
+        end
+
+        def [](*args, &)
+          singulus_reject_invocation!(args)
+          super
+        end
+
+        def to_proc
+          singulus_reject_transformation!
+          super
+        end
+
+        def >>(other)
+          singulus_reject_transformation!
+          super
+        end
+
+        def <<(other)
+          singulus_reject_transformation!
+          super
+        end
+
+        private
+
+        def singulus_reject_invocation!(args)
+          return unless Internal.runtime_hardened?(receiver)
+
+          if Internal.constructor_name?(name)
+            raise ConstructorAccessError,
+                  "constructor #{name.inspect} cannot be invoked for runtime-hardened Singulus #{receiver}"
+          end
+
+          return unless RuntimeHardening.reflection_gateway?(name)
+          return unless Internal.constructor_name?(args.first)
+
+          raise ConstructorAccessError,
+                "#{name} cannot be used to access constructor #{args.first.inspect} " \
+                "for runtime-hardened Singulus #{receiver}"
+        end
+
+        def singulus_reject_transformation!
+          return unless Internal.runtime_hardened?(receiver)
+          return unless Internal.constructor_name?(name) || RuntimeHardening.reflection_gateway?(name)
+
+          raise ConstructorAccessError,
+                "Method #{name.inspect} for runtime-hardened Singulus #{receiver} " \
+                "cannot be converted or composed"
+        end
+      end
+
+      class << self
+        def enable!
+          mutex.synchronize do
+            return if enabled?
+
+            UnboundMethod.prepend(UnboundMethodGuard)
+            Method.prepend(MethodGuard)
+
+            @enabled = true
+          end
+        end
+
+        def enabled?
+          @enabled == true
+        end
+
+        def reflection_gateway?(method_name)
+          REFLECTION_GATEWAYS.include?(Internal.normalize_method_name(method_name))
+        end
+
+        private
+
+        def mutex
+          @mutex ||= Thread::Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/singulus/internal/singleton_class_methods.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Internal
+    module SingletonClassMethods
+      def instance
+        return super unless Internal.locally_hardened?(self)
+
+        instance = Internal.with_constructor_access(self) { super }
+        singulus_seal_constructors!
+        instance
+      end
+
+      def singulus(mode:)
+        Internal.set_mode!(self, mode)
+        self
+      end
+
+      def singulus_mode
+        Internal.mode_for(self)
+      end
+
+      private
+
+      def inherited(subclass)
+        if Internal.locally_hardened?(self)
+          raise InheritanceError,
+                "#{self} is a Singulus in #{singulus_mode.inspect} mode and cannot be subclassed"
+        end
+
+        super
+      end
+
+      def singulus_seal_constructors!
+        return if singulus_sealed?
+
+        singulus_seal_mutex.synchronize do
+          return if singulus_sealed?
+
+          singulus_seal_constructor!(:new)
+          singulus_seal_constructor!(:allocate)
+
+          @__singulus_sealed__ = true
+        end
+      end
+
+      def singulus_seal_constructor!(method_name)
+        singleton_class.__send__(:undef_method, method_name)
+      rescue NameError
+        return unless respond_to?(method_name, true)
+
+        raise
+      end
+
+      def singulus_sealed?
+        @__singulus_sealed__ == true
+      end
+
+      def singulus_seal_mutex
+        @__singulus_seal_mutex__ ||= Thread::Mutex.new
+      end
+    end
+  end
+end

data/lib/singulus/multiton.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Singulus
+  module Multiton
+    RETENTIONS = %i[forever lru ttl bounded weak].freeze
+    private_constant :RETENTIONS
+
+    Entry = Struct.new(:value, :expires_at, keyword_init: true) do
+      def instance
+        value.is_a?(WeakRef) ? value.__getobj__ : value
+      rescue WeakRef::RefError
+        nil
+      end
+
+      def alive?
+        !instance.nil?
+      end
+    end
+    private_constant :Entry
+
+    class << self
+      def included(base)
+        install(base)
+      end
+
+      def with(mode = nil, **options)
+        resolved_mode = options.delete(:mode)
+
+        raise ArgumentError, "mode must be provided either positionally or as mode:, not both" if mode && resolved_mode
+
+        resolved_mode ||= mode || Singulus.configuration.default_mode
+        retention = options.delete(:retention)
+        ttl = options.delete(:ttl)
+        max_size = options.delete(:max_size)
+
+        raise ArgumentError, "unknown Multiton options: #{options.keys.map(&:inspect).join(', ')}" unless options.empty?
+
+        Module.new do
+          define_singleton_method(:included) do |base|
+            Multiton.install(base, mode: resolved_mode)
+            base.singulus(retention: retention, ttl: ttl, max_size: max_size) if retention
+          end
+        end
+      end
+
+      def install(base, mode: Singulus.configuration.default_mode)
+        Internal.initialize_managed_class!(base, kind: :multiton, mode: mode)
+
+        base.include Internal::InstanceGuard
+        base.private_class_method :new, :allocate
+        base.singleton_class.prepend Internal::ReflectionGuard
+        base.singleton_class.prepend Internal::MutationGuard
+        base.singleton_class.prepend Internal::ConstructorGuard
+        base.extend ClassMethods
+
+        initialize_registry_state(base)
+        Internal::RuntimeHardening.enable! if Internal.runtime_hardened?(base)
+        base
+      end
+
+      private
+
+      def initialize_registry_state(base)
+        base.instance_variable_set(:@__singulus_multiton_mutex__, Monitor.new)
+        base.instance_variable_set(:@__singulus_multiton_instances__, {})
+        base.instance_variable_set(:@__singulus_multiton_key_normalizer__, nil)
+        base.instance_variable_set(:@__singulus_multiton_retention__, :forever)
+        base.instance_variable_set(:@__singulus_multiton_ttl__, nil)
+        base.instance_variable_set(:@__singulus_multiton_max_size__, nil)
+        base.instance_variable_set(:@__singulus_multiton_initializing_keys__, {})
+      end
+    end
+
+    module ClassMethods
+      def instance_for(identifier, ...)
+        key = singulus_multiton_key_for(identifier)
+
+        singulus_multiton_mutex.synchronize do
+          singulus_multiton_purge_expired!
+
+          if (entry = singulus_multiton_instances[key])
+            if (instance = entry.instance)
+              singulus_multiton_touch_lru!(key, entry)
+              return instance
+            end
+
+            singulus_multiton_instances.delete(key)
+          end
+
+          singulus_multiton_reject_recursive_initialization!(key)
+          singulus_multiton_initializing_keys[key] = true
+
+          begin
+            instance = Internal.with_constructor_access(self) do
+              new(identifier, ...)
+            end
+            singulus_multiton_store!(key, instance)
+            instance
+          ensure
+            singulus_multiton_initializing_keys.delete(key)
+          end
+        end
+      end
+
+      def instance?(identifier)
+        key = singulus_multiton_key_for(identifier)
+
+        singulus_multiton_mutex.synchronize do
+          singulus_multiton_purge_expired!
+          singulus_multiton_instances.key?(key)
+        end
+      end
+
+      def delete_instance(identifier)
+        key = singulus_multiton_key_for(identifier)
+
+        singulus_multiton_mutex.synchronize do
+          singulus_multiton_purge_expired!
+          singulus_multiton_instances.delete(key)&.instance
+        end
+      end
+
+      def clear_instances
+        singulus_multiton_mutex.synchronize do
+          singulus_multiton_purge_expired!
+          count = singulus_multiton_instances.length
+          singulus_multiton_instances.clear
+          count
+        end
+      end
+
+      def instance_count
+        singulus_multiton_mutex.synchronize do
+          singulus_multiton_purge_expired!
+          singulus_multiton_instances.length
+        end
+      end
+
+      def instance_keys
+        singulus_multiton_mutex.synchronize do
+          singulus_multiton_purge_expired!
+          singulus_multiton_instances.keys.dup.freeze
+        end
+      end
+
+      def singulus(mode: nil, retention: nil, ttl: nil, max_size: nil)
+        Internal.set_mode!(self, mode) if mode
+        multiton_retention(retention, ttl: ttl, max_size: max_size) if retention
+        self
+      end
+
+      def singulus_mode
+        Internal.mode_for(self)
+      end
+
+      def multiton_key(&block)
+        return @__singulus_multiton_key_normalizer__ unless block
+
+        singulus_multiton_assert_registry_empty!("key normalizer")
+        @__singulus_multiton_key_normalizer__ = block
+        self
+      end
+
+      def multiton_retention(strategy = nil, ttl: nil, max_size: nil)
+        return @__singulus_multiton_retention__ unless strategy
+
+        strategy = Internal.normalize_method_name(strategy)
+        unless RETENTIONS.include?(strategy)
+          raise Internal::InvalidRetentionError,
+                "invalid Multiton retention #{strategy.inspect}; expected one of: #{RETENTIONS.join(', ')}"
+        end
+
+        singulus_multiton_validate_retention_options!(strategy, ttl: ttl, max_size: max_size)
+        singulus_multiton_assert_registry_empty!("retention")
+
+        @__singulus_multiton_retention__ = strategy
+        @__singulus_multiton_ttl__ = ttl&.to_f
+        @__singulus_multiton_max_size__ = max_size&.to_i
+        self
+      end
+
+      private
+
+      def inherited(subclass)
+        if Internal.locally_hardened?(self)
+          raise Internal::InheritanceError,
+                "#{self} is a Multiton in #{singulus_mode.inspect} mode and cannot be subclassed"
+        end
+
+        super
+        Multiton.install(subclass, mode: singulus_mode)
+      end
+
+      def singulus_multiton_instances
+        @__singulus_multiton_instances__ ||= {}
+      end
+
+      def singulus_multiton_mutex
+        @__singulus_multiton_mutex__ ||= Monitor.new
+      end
+
+      def singulus_multiton_initializing_keys
+        @__singulus_multiton_initializing_keys__ ||= {}
+      end
+
+      def singulus_multiton_key_for(identifier)
+        normalizer = @__singulus_multiton_key_normalizer__
+        key = normalizer ? normalizer.call(identifier) : identifier
+        singulus_multiton_stabilize_key(key)
+      end
+
+      def singulus_multiton_stabilize_key(key)
+        case key
+        when String
+          key.dup.freeze
+        when Array
+          key.map { |item| singulus_multiton_stabilize_key(item) }.freeze
+        when Hash
+          key.each_with_object({}) do |(hash_key, value), stabilized|
+            stabilized[singulus_multiton_stabilize_key(hash_key)] = singulus_multiton_stabilize_key(value)
+          end.freeze
+        else
+          key
+        end
+      end
+
+      def singulus_multiton_store!(key, instance)
+        retention = @__singulus_multiton_retention__
+        ttl_retention = %i[ttl bounded].include?(retention)
+        expires_at = singulus_multiton_monotonic_time + @__singulus_multiton_ttl__ if ttl_retention
+        value = retention == :weak ? WeakRef.new(instance) : instance
+
+        singulus_multiton_instances[key] = Entry.new(value: value, expires_at: expires_at)
+        singulus_multiton_evict_lru! if %i[lru bounded].include?(retention)
+      end
+
+      def singulus_multiton_touch_lru!(key, entry)
+        return unless %i[lru bounded].include?(@__singulus_multiton_retention__)
+
+        singulus_multiton_instances.delete(key)
+        singulus_multiton_instances[key] = entry
+      end
+
+      def singulus_multiton_evict_lru!
+        max_size = @__singulus_multiton_max_size__
+        singulus_multiton_instances.shift while singulus_multiton_instances.length > max_size
+      end
+
+      def singulus_multiton_purge_expired!
+        retention = @__singulus_multiton_retention__
+
+        if %i[ttl bounded].include?(retention)
+          now = singulus_multiton_monotonic_time
+          singulus_multiton_instances.delete_if { |_key, entry| entry.expires_at <= now }
+        elsif retention == :weak
+          singulus_multiton_instances.delete_if { |_key, entry| !entry.alive? }
+        end
+      end
+
+      def singulus_multiton_monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def singulus_multiton_validate_retention_options!(strategy, ttl:, max_size:)
+        case strategy
+        when :forever, :weak
+          return unless ttl || max_size
+
+          raise Internal::InvalidRetentionError,
+                "#{strategy.inspect} retention does not accept ttl: or max_size:"
+        when :ttl
+          if !ttl || ttl.to_f <= 0
+            raise Internal::InvalidRetentionError,
+                  ":ttl retention requires ttl: greater than zero"
+          end
+          return unless max_size
+
+          raise Internal::InvalidRetentionError,
+                "max_size: is not valid for :ttl retention; use retention: :bounded to combine ttl and max_size"
+        when :lru
+          if !max_size || max_size.to_i <= 0
+            raise Internal::InvalidRetentionError, ":lru retention requires max_size: greater than zero"
+          end
+          return unless ttl
+
+          raise Internal::InvalidRetentionError,
+                "ttl: is not valid for :lru retention; use retention: :bounded to combine ttl and max_size"
+        when :bounded
+          if !ttl || ttl.to_f <= 0
+            raise Internal::InvalidRetentionError,
+                  ":bounded retention requires ttl: greater than zero"
+          end
+          return if max_size&.to_i&.positive?
+
+          raise Internal::InvalidRetentionError, ":bounded retention requires max_size: greater than zero"
+        end
+      end
+
+      def singulus_multiton_reject_recursive_initialization!(key)
+        return unless singulus_multiton_initializing_keys.key?(key)
+
+        raise Internal::RecursiveInitializationError,
+              "recursive Multiton initialization detected for key #{key.inspect} on #{self}"
+      end
+
+      def singulus_multiton_assert_registry_empty!(setting)
+        return if instance_count.zero?
+
+        raise Internal::ConfigurationLockedError,
+              "cannot change Multiton #{setting} after instances have been created; clear_instances first"
+      end
+    end
+
+    private_constant :ClassMethods
+  end
+end

data/lib/singulus/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Singulus
+  VERSION = "0.1.0"
+end

data/lib/singulus.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "monitor"
+require "weakref"
+
+require_relative "singulus/version"
+require_relative "singulus/internal/errors"
+require_relative "singulus/internal/configuration"
+require_relative "singulus/internal/instance_guard"
+require_relative "singulus/internal/constructor_guard"
+require_relative "singulus/internal/reflection_guard"
+require_relative "singulus/internal/mutation_guard"
+require_relative "singulus/internal/singleton_class_methods"
+require_relative "singulus/internal/runtime_hardening"
+require_relative "singulus/multiton"
+
+module Singulus
+  module Internal
+    CONSTRUCTORS = %i[new allocate].freeze
+
+    MARKER_IVAR = :@__singulus_managed_class__
+    KIND_IVAR = :@__singulus_kind__
+    MODE_IVAR = :@__singulus_mode__
+
+    class << self
+      def install_singleton!(base, mode: Singulus.configuration.default_mode)
+        base.include ::Singleton
+        base.include InstanceGuard
+
+        initialize_managed_class!(base, kind: :singleton, mode: mode)
+        base.instance_variable_set(:@__singulus_seal_mutex__, Thread::Mutex.new)
+        base.instance_variable_set(:@__singulus_sealed__, false)
+
+        base.singleton_class.prepend ReflectionGuard
+        base.singleton_class.prepend MutationGuard
+        base.singleton_class.prepend ConstructorGuard
+        base.extend SingletonClassMethods
+
+        RuntimeHardening.enable! if runtime_hardened?(base)
+        base
+      end
+
+      def initialize_managed_class!(base, kind:, mode:)
+        base.instance_variable_set(MARKER_IVAR, true)
+        base.instance_variable_set(KIND_IVAR, kind)
+        base.instance_variable_set(MODE_IVAR, normalize_mode!(mode))
+        base
+      end
+
+      def managed_class?(object)
+        object.is_a?(Class) && object.instance_variable_get(MARKER_IVAR) == true
+      end
+
+      alias singulus_class? managed_class?
+
+      def kind_for(klass)
+        return unless managed_class?(klass)
+
+        klass.instance_variable_get(KIND_IVAR)
+      end
+
+      def mode_for(klass)
+        return unless managed_class?(klass)
+
+        klass.instance_variable_get(MODE_IVAR)
+      end
+
+      def set_mode!(klass, mode)
+        raise ArgumentError, "#{klass} is not managed by Singulus" unless managed_class?(klass)
+
+        normalized_mode = normalize_mode!(mode)
+        current_mode = mode_for(klass)
+
+        if kind_for(klass) == :singleton && current_mode != :standard && normalized_mode == :standard &&
+           klass.instance_variable_get(:@__singulus_sealed__)
+          raise InvalidModeError,
+                "cannot downgrade #{klass} to :standard after its constructors have been sealed"
+        end
+
+        klass.instance_variable_set(MODE_IVAR, normalized_mode)
+        RuntimeHardening.enable! if normalized_mode == :runtime
+        normalized_mode
+      end
+
+      def locally_hardened?(klass)
+        %i[strict runtime].include?(mode_for(klass))
+      end
+
+      def runtime_hardened?(klass)
+        mode_for(klass) == :runtime
+      end
+
+      def sealed_singleton?(klass)
+        kind_for(klass) == :singleton && klass.instance_variable_get(:@__singulus_sealed__) == true
+      end
+
+      def constructor_name?(method_name)
+        CONSTRUCTORS.include?(normalize_method_name(method_name))
+      end
+
+      def normalize_method_name(method_name)
+        method_name.to_sym
+      rescue NoMethodError
+        method_name
+      end
+
+      def constructor_access_allowed?(klass)
+        permissions = Thread.current[:__singulus_constructor_permissions__]
+        permissions && permissions[klass].to_i.positive?
+      end
+
+      def with_constructor_access(klass)
+        permissions = (Thread.current[:__singulus_constructor_permissions__] ||= {})
+        permissions[klass] = permissions[klass].to_i + 1
+        yield
+      ensure
+        if permissions
+          permissions[klass] = permissions[klass].to_i - 1
+          permissions.delete(klass) unless permissions[klass].to_i.positive?
+          Thread.current[:__singulus_constructor_permissions__] = nil if permissions.empty?
+        end
+      end
+
+      private
+
+      def normalize_mode!(mode)
+        normalized_mode = normalize_method_name(mode)
+        return normalized_mode if Configuration::MODES.include?(normalized_mode)
+
+        raise InvalidModeError,
+              "invalid Singulus mode #{mode.inspect}; expected one of: #{Configuration::MODES.join(', ')}"
+      end
+    end
+  end
+
+  private_constant :Internal
+
+  class << self
+    def configuration
+      @configuration ||= Internal::Configuration.new
+    end
+
+    def configure
+      raise ArgumentError, "a block is required" unless block_given?
+
+      yield configuration
+      Internal::RuntimeHardening.enable! if configuration.default_mode == :runtime
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Internal::Configuration.new
+    end
+  end
+
+  module Singleton
+    class << self
+      def included(base)
+        Internal.install_singleton!(base)
+      end
+
+      def with(mode = nil, **options)
+        resolved_mode = options.delete(:mode)
+
+        raise ArgumentError, "mode must be provided either positionally or as mode:, not both" if mode && resolved_mode
+
+        unless options.empty?
+          raise ArgumentError, "unknown Singleton options: #{options.keys.map(&:inspect).join(', ')}"
+        end
+
+        resolved_mode ||= mode || Singulus.configuration.default_mode
+
+        Module.new do
+          define_singleton_method(:included) do |base|
+            Internal.install_singleton!(base, mode: resolved_mode)
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: singulus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Juan Furattini
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Singulus provides configurable local and runtime hardening for classic
+  Singleton and keyed Multiton patterns, including reflection guards, constructor
+  protection, mutation protection, inheritance restrictions, bounded retention
+  strategies, and optional guards around Method and UnboundMethod.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/singulus.rb
+- lib/singulus/internal/configuration.rb
+- lib/singulus/internal/constructor_guard.rb
+- lib/singulus/internal/errors.rb
+- lib/singulus/internal/instance_guard.rb
+- lib/singulus/internal/mutation_guard.rb
+- lib/singulus/internal/reflection_guard.rb
+- lib/singulus/internal/runtime_hardening.rb
+- lib/singulus/internal/singleton_class_methods.rb
+- lib/singulus/multiton.rb
+- lib/singulus/version.rb
+homepage: https://github.com/Rubcraft/singulus
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/Rubcraft/singulus
+  changelog_uri: https://github.com/Rubcraft/singulus/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Hardened Singleton and keyed Multiton patterns for Ruby
+test_files: []