igniter-embed 0.5.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b4a43a4e170a429c5aa9b8380a47b0dd9f254109eadc7268f67e205fe74d6b2
+  data.tar.gz: 1b40c7e366edd2704bec098aa86c463272b614f134a8c0ab3ab6c80cb994109f
+SHA512:
+  metadata.gz: 598d577bbdeb6c7ddf50c73c90a6d24bbb8ab9414a8bab78556b0aa61754a2c3a820b627484d4de38749c965f316f106371cb1385ceac03436da2d3f2cbc47fe
+  data.tar.gz: 400425f586822adcc7847ad6fe0b3c4dc92ceeff28eb9250432a85eef90b882cf981e1c400e27b4f6fa342f96c95e52dee5ba63525ca28aa5c642a612218bef7

data/README.md

@@ -0,0 +1,360 @@
+# Igniter Embed
+
+`igniter-embed` is the host-local layer for applications that want to register,
+cache, and execute Igniter contracts without adopting the full application
+runtime.
+
+```ruby
+contracts = Igniter::Embed.configure(:sparkcrm) do |config|
+  config.cache = true
+  config.pack Igniter::Contracts::ProjectPack
+end
+
+contracts.register(:tax_quote) do
+  input :amount
+  compute :tax, depends_on: [:amount] do |amount:|
+    amount * 0.2
+  end
+  output :tax
+end
+
+result = contracts.call(:tax_quote, amount: 100)
+result.success?
+result.output(:tax)
+```
+
+For human-facing app initializers, `host` is sugar over the same host-local
+configuration:
+
+```ruby
+contracts = Igniter::Embed.host(:shop) do
+  owner Shop
+  path "app/contracts"
+  cache !Rails.env.development?
+
+  contracts do
+    add :price_quote, PriceContract
+  end
+end
+```
+
+For app-local contract classes, prefer host-level registration:
+
+```ruby
+class PriceContract < Igniter::Contract
+  define do
+    input :amount
+    compute :total, depends_on: [:amount] do |amount:|
+      amount * 1.2
+    end
+    output :total
+  end
+end
+
+contracts = Igniter::Embed.configure(:shop) do |config|
+  config.root "app/contracts"
+  config.contract PriceContract, as: :price_quote
+end
+
+contracts.call(:price_quote, amount: 100).output(:total)
+```
+
+Named contract classes can also be registered directly:
+
+```ruby
+contracts.register(PriceContract)
+contracts.call(:price, amount: 100)
+```
+
+`config.root` is the host-local directory where contract files live. It is
+metadata for explicit registration unless discovery is enabled.
+
+Discovery is opt-in:
+
+```ruby
+contracts = Igniter::Embed.configure(:shop) do |config|
+  config.root "app/contracts"
+  config.discover!
+end
+```
+
+By default discovery requires `**/*_contract.rb` under `config.root` and
+registers newly loaded, named `Class < Igniter::Contract` definitions by
+inferred name. Anonymous contract classes are ignored by discovery and must be
+registered explicitly with `as:` if you want to call them through the host.
+
+Prefer explicit `config.contract` for application boot paths where stable
+naming matters. If explicit registration and discovery produce the same name,
+the explicit registration wins. If two discovered classes infer the same name,
+discovery raises `Igniter::Embed::DiscoveryError` and asks you to register them
+explicitly.
+
+Rails integration is optional:
+
+```ruby
+require "igniter/embed/rails"
+
+Igniter::Embed::Rails.install(
+  contracts,
+  reloader: Rails.application.reloader,
+  cache: !Rails.env.development?
+)
+```
+
+The Rails adapter only connects host reload callbacks to `container.reload!`.
+The base package remains Rails-free.
+
+## Contractable Shadowing
+
+`igniter-contracts` owns the core `Contractable` service protocol used by
+`compute using:`. The `igniter-embed` `contractable` API below is a host
+wrapper for migration, shadowing, discovery, and production observation.
+
+`contractable` wraps host services without changing their public API. The
+primary callable runs synchronously and its raw result is returned; an optional
+candidate can run through a shadow adapter, normalize outputs, compare through
+`DifferentialPack`, and record an observation through an app-supplied store.
+When `async` is true, the default adapter uses a local Ruby thread so candidate
+work does not block the primary response. It is not a durable production job
+queue; provide an app adapter for ActiveJob, Sidekiq, or another backend when
+durability matters.
+
+When a primary or candidate is a core `Igniter::Contracts::Contractable`
+service, embed invokes it through the core protocol and adopts its declared
+`role`, `stage`, and metadata as wrapper defaults unless the wrapper explicitly
+overrides them.
+
+```ruby
+QuoteShadow = Igniter::Embed.contractable(:quote) do |config|
+  config.role :migration_candidate
+  config.stage :shadowed
+  config.primary LegacyQuote
+  config.candidate ContractQuote
+  config.normalize_primary QuoteNormalizer
+  config.normalize_candidate QuoteNormalizer
+  config.accept :shape, outputs: { total: Numeric, status: String }
+  config.store QuoteObservationStore
+end
+
+result = QuoteShadow.call(amount: 100)
+```
+
+The same shape can be declared through host sugar. This keeps registration,
+shadow migration intent, adapters, and event hooks in one inspectable
+initializer:
+
+```ruby
+contracts = Igniter::Embed.host(:billing) do
+  contracts do
+    add :price_quote, Billing::PriceContract do
+      migrate Billing::LegacyQuote, to: Billing::ContractQuote
+      shadow async: false, sample: 1.0
+
+      use :normalizer, Billing::QuoteNormalizer
+      use :redaction, only: %i[amount customer_id]
+      use :acceptance, policy: :shape, outputs: { total: Numeric }
+      use :store, Billing::ObservationStore
+
+      on :divergence do |event|
+        Billing.logger.warn(event)
+      end
+    end
+  end
+end
+
+runner = contracts.contractable(:price_quote)
+runner.call(amount: 100, customer_id: "cust_1", token: "secret")
+```
+
+Generated contractable runners are host-local:
+
+```ruby
+contracts.contractable_names
+contracts.fetch_contractable(:price_quote)
+contracts.sugar_expansion.to_h
+```
+
+`on :failure` is an alias family for typed failure events:
+`:primary_error`, `:candidate_error`, `:acceptance_failure`, and
+`:store_error`. Divergence is intentionally separate and should be subscribed
+to with `on :divergence`.
+
+Capability attachment sugar exists for host-owned targets. It does not install
+implicit built-ins:
+
+```ruby
+contracts = Igniter::Embed.host(:billing) do
+  contracts do
+    add :price_quote, Billing::PriceContract do
+      migrate Billing::LegacyQuote, to: Billing::ContractQuote
+      use :normalizer, Billing::QuoteNormalizer
+
+      use :logging, contract: Billing::LogObservationContract
+      use :reporting, ->(event) { Billing.reporter.record(event) }
+      use :metrics, target: Billing::MetricsSink
+      use :validation, callable: Billing::ObservationValidator
+    end
+  end
+end
+```
+
+Each explicit target appears in `sugar_expansion` as either `kind: :contract`
+or `kind: :callable_adapter`.
+
+Primary-only observed services use the same surface:
+
+```ruby
+ObservedQuote = Igniter::Embed.contractable(:quote) do |config|
+  config.role :observed_service
+  config.primary LegacyQuote
+  config.normalize_primary QuoteNormalizer
+  config.store QuoteObservationStore
+end
+```
+
+For an observed service, the normalizer should return a redacted aggregate
+summary. The primary callable remains authoritative and its raw result is still
+returned to the host app.
+
+```ruby
+AvailabilityObserver = Igniter::Embed.contractable(:availability) do |config|
+  config.role :observed_service
+  config.stage :captured
+  config.primary AvailabilityService
+  config.normalize_primary AvailabilitySummaryNormalizer
+  config.redact_inputs ->(**inputs) { inputs.slice(:request_ref, :window_ref) }
+  config.store AvailabilityObservationStore
+end
+
+class AvailabilitySummaryNormalizer
+  def self.call(_result)
+    {
+      status: :ok,
+      outputs: {
+        status: "success",
+        receipt_kind: "availability_slot_map_summary",
+        redaction_policy: "availability_slot_map_summary_v1",
+        availability_bucket: "available",
+        dominant_unavailable_state: "day_off",
+        available_ratio: 0.75,
+        total_slots: 4,
+        available_slots: 3,
+        scheduled_slots: 0,
+        off_schedule_slots: 0,
+        day_off_slots: 1,
+        past_slots: 0
+      },
+      metadata: { normalizer: :availability_summary_v1 }
+    }
+  end
+end
+```
+
+The aggregate payload above is a sanitized normalizer example. It becomes part
+of `receipt[:primary][:outputs]`; it is not the top-level Embed receipt
+envelope. In particular, `"availability_slot_map_summary"` is fixture/example
+vocabulary for the aggregate output shape, not an `igniter-embed` receipt kind.
+The Embed observation receipt that contains it still uses
+`receipt_kind: :contractable_observation`, and event receipts still use
+`receipt_kind: :contractable_event`.
+
+Keep this shape host-local:
+
+- choose the observed target, rollout flag, and sample rate in the app;
+- keep the redaction allow-list app-owned;
+- persist receipts through an app-owned store adapter;
+- treat Ledger sinks as optional adapters, not as the source of truth;
+- do not infer release readiness or a public schema from synthetic aggregate
+  examples.
+
+## Observation Receipts
+
+Each contractable call produces a canonical observation receipt. The receipt
+includes a stable `observation_id`, `schema_version`, `receipt_kind`, and a
+`status` that summarises the outcome:
+
+```text
+:ok               — primary and candidate matched and were accepted
+:diverged         — outputs diverged but acceptance policy passed
+:candidate_error  — candidate raised an exception
+:acceptance_failed — candidate succeeded but acceptance policy failed
+:store_error      — store adapter raised after primary returned
+:unsampled        — call was outside the configured sample rate
+```
+
+A Spark-style store adapter wires receipts into a durable sink:
+
+```ruby
+class SparkObservationStore
+  def record_observation(receipt)
+    # receipt[:observation_id]  — stable id for linking to logs/admin
+    # receipt[:status]          — :ok | :diverged | :candidate_error | …
+    # receipt[:redaction]       — policy applied to inputs
+    ObservationRecord.create!(receipt.slice(:observation_id, :status, :name, :role, :stage).merge(payload: receipt))
+  end
+
+  def record_event(receipt)
+    # receipt[:receipt_kind]  == :contractable_event
+    # receipt[:event_id]      — unique per event
+    # receipt[:observation_id] — links back to the observation
+    # receipt[:severity]      — :info | :warning | :error
+    return unless receipt[:severity] == :error || receipt[:event] == :divergence
+
+    ObservationEvent.create!(receipt.slice(:event_id, :observation_id, :event, :severity, :summary))
+  end
+end
+```
+
+Register the store in a host:
+
+```ruby
+runner = Igniter::Embed.contractable(:marketing_executor) do
+  migrate Api::Marketing::ExecutorService::Legacy,
+          to: Api::Marketing::ExecutorService::Contract
+  shadow async: true, sample: 0.1
+  use :normalizer, Api::Marketing::ExecutorNormalizer
+  use :redaction, only: %i[provider_payload technician_id customer_id]
+  use :acceptance, policy: :shape, outputs: { status: String, result: Hash }
+  use :store, SparkObservationStore.new
+
+  on :divergence do |event|
+    Rails.logger.warn("[igniter] divergence obs=#{event.dig(:receipt, :observation_id)}")
+  end
+end
+```
+
+A divergence event payload includes a compact receipt:
+
+```ruby
+{
+  event: :divergence,
+  receipt: {
+    schema_version: 1,
+    receipt_kind: :contractable_event,
+    event_id: "evt_...",
+    observation_id: "obs_...",
+    severity: :warning,
+    summary: "outputs diverged from primary",
+    observation_ref: { observation_id: "obs_...", match: false, accepted: false }
+  }
+}
+```
+
+Async adapters receive a handoff descriptor for durable job wiring:
+
+```ruby
+class SidekiqObservationAdapter
+  def enqueue(name:, inputs:, metadata:, handoff: nil, &block)
+    if handoff
+      ObservationJob.perform_later(
+        observation_id: handoff[:observation_id],
+        name: handoff[:name],
+        queued_at: handoff[:queued_at]
+      )
+    else
+      # fallback: run inline
+      block.call
+    end
+  end
+end
+```

data/lib/igniter/embed/config.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    class Config
+      ContractRegistration = Struct.new(:definition, :name, keyword_init: true)
+
+      attr_reader :name, :packs, :contract_registrations,
+                  :contractable_configs, :discovery_pattern
+      attr_accessor :cache, :capture_exceptions, :executor_name
+
+      UNSET = Object.new.freeze
+
+      def initialize(name:)
+        @name = name.to_sym
+        @cache = true
+        @root = nil
+        @owner = nil
+        @packs = []
+        @contract_registrations = []
+        @contractable_configs = []
+        @discovery_enabled = false
+        @discovery_pattern = "**/*_contract.rb"
+        @capture_exceptions = false
+        @executor_name = :inline
+      end
+
+      def pack(pack)
+        packs << pack
+        self
+      end
+
+      def owner(value = UNSET)
+        return @owner if value.equal?(UNSET)
+
+        @owner = value
+        self
+      end
+
+      def owner=(value)
+        owner(value)
+      end
+
+      def contract(definition, as: nil)
+        contract_registrations << ContractRegistration.new(definition: definition, name: as)
+        self
+      end
+
+      def contractable(config)
+        raise DuplicateContractError, "contractable #{config.name} is already configured" if contractable_registered?(config.name)
+
+        contractable_configs << config
+        self
+      end
+
+      def contractable_config(name)
+        key = name.to_sym
+        contractable_configs.find { |contractable_config| contractable_config.name == key }
+      end
+
+      def contracts(&block)
+        builder = ContractsBuilder.new(config: self)
+        evaluate_builder_block(builder, &block) if block
+        self
+      end
+
+      def root(path = nil)
+        return @root if path.nil?
+
+        @root = File.expand_path(path.to_s)
+        self
+      end
+
+      def root=(path)
+        root(path)
+      end
+
+      def path(value = nil)
+        return root if value.nil?
+
+        root(resolve_path(value))
+      end
+
+      def path=(value)
+        path(value)
+      end
+
+      def sugar_expansion
+        SugarExpansion.new(config: self)
+      end
+
+      def discover!(pattern: "**/*_contract.rb")
+        @discovery_enabled = true
+        @discovery_pattern = pattern
+        self
+      end
+
+      def cache?
+        !!cache
+      end
+
+      def discovery_enabled?
+        !!@discovery_enabled
+      end
+
+      def capture_exceptions?
+        !!capture_exceptions
+      end
+
+      private
+
+      def contractable_registered?(name)
+        contractable_configs.any? { |contractable_config| contractable_config.name == name }
+      end
+
+      def resolve_path(value)
+        if value.is_a?(Array)
+          raise SugarError, "path requires exactly one path in this implementation slice" unless value.length == 1
+
+          value = value.first
+        end
+
+        raise SugarError, "path entries must be strings or path-like objects" unless path_like?(value)
+
+        path_value = value.respond_to?(:to_path) ? value.to_path : value.to_s
+        return path_value if absolute_path?(path_value)
+
+        owner_root = resolved_owner_root
+        owner_root ? File.join(owner_root, path_value) : path_value
+      end
+
+      def absolute_path?(path)
+        File.absolute_path(path) == path
+      end
+
+      def resolved_owner_root
+        return nil unless @owner.respond_to?(:root)
+
+        @owner.root.to_s
+      end
+
+      def path_like?(value)
+        value.is_a?(String) || value.respond_to?(:to_path)
+      end
+
+      def evaluate_builder_block(builder, &block)
+        if block.arity.zero?
+          builder.instance_eval(&block)
+        else
+          block.call(builder)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/embed/container.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    class Container
+      attr_reader :config, :registry
+
+      def initialize(config:)
+        @config = config
+        @registry = Registry.new
+        @compiled_contracts = {}
+        @contractable_runners = {}
+        register_configured_contracts
+        discover_configured_contracts
+      end
+
+      def profile
+        @profile ||= Igniter::Contracts.build_profile(config.packs)
+      end
+
+      def register(name_or_definition, definition = nil, as: nil, &block)
+        name, contract_definition = normalize_registration(name_or_definition, definition, as: as, block: block)
+        raise ArgumentError, "contract definition is required" unless contract_definition
+
+        registry.register(name, contract_definition)
+        compiled_contracts.delete(name)
+        ContractHandle.new(name: name, container: self)
+      end
+
+      def fetch(name)
+        registry.fetch(name)
+        ContractHandle.new(name: name, container: self)
+      end
+
+      def compile(name = nil, &block)
+        return compile_block(&block) if block
+
+        compile_registered(name)
+      end
+
+      def call(name, inputs = {}, **keyword_inputs)
+        normalized_inputs = inputs.merge(keyword_inputs)
+        compiled_graph = compile_registered(name)
+        result = Igniter::Contracts.execute_with(
+          config.executor_name,
+          compiled_graph,
+          inputs: normalized_inputs,
+          profile: profile
+        )
+        ExecutionEnvelope.new(name: name, inputs: normalized_inputs, result: result)
+      rescue StandardError => e
+        raise unless config.capture_exceptions?
+
+        ExecutionEnvelope.new(
+          name: name,
+          inputs: normalized_inputs || {},
+          errors: [e],
+          metadata: { captured_exception: true }
+        )
+      end
+
+      def contractable(name)
+        key = name.to_sym
+        return contractable_runners.fetch(key) if contractable_runners.key?(key)
+
+        contractable_config = config.contractable_config(key)
+        raise UnknownContractableError, "unknown contractable #{key}" unless contractable_config
+
+        contractable_runners[key] = Contractable::Runner.new(config: contractable_config)
+      end
+      alias fetch_contractable contractable
+
+      def contractable_names
+        config.contractable_configs.map(&:name)
+      end
+
+      def clear_cache
+        compiled_contracts.clear
+        contractable_runners.clear
+        @profile = nil
+        self
+      end
+
+      def reload!
+        clear_cache
+      end
+
+      def sugar_expansion
+        config.sugar_expansion
+      end
+
+      private
+
+      attr_reader :compiled_contracts, :contractable_runners
+
+      def discover_configured_contracts
+        return unless config.discovery_enabled?
+
+        root = config.root
+        raise DiscoveryError, "config.root is required when discovery is enabled" unless root
+        raise DiscoveryError, "contract discovery root does not exist: #{root}" unless Dir.exist?(root)
+
+        before = contract_classes
+        Dir[File.join(root, config.discovery_pattern)].sort.each { |path| require path }
+        discovered_contract_classes = (contract_classes - before).select { |klass| discoverable_contract_class?(klass) }
+        discovered_by_name = discovered_contract_classes.group_by { |klass| ContractNaming.infer_contract_name(klass) }
+        duplicates = discovered_by_name.select { |_name, classes| classes.length > 1 }
+        unless duplicates.empty?
+          duplicate_names = duplicates.keys.sort.map { |name| ":#{name}" }.join(", ")
+          raise DiscoveryError,
+                "discovered duplicate contract names #{duplicate_names}; use explicit config.contract registrations"
+        end
+
+        discovered_by_name.keys.sort.each do |name|
+          next if registry.key?(name)
+
+          register(discovered_by_name.fetch(name).first, as: name)
+        end
+      end
+
+      def contract_classes
+        ObjectSpace.each_object(Class).select { |klass| ContractNaming.contract_class?(klass) }
+      end
+
+      def discoverable_contract_class?(contract_class)
+        !contract_class.name.nil?
+      end
+
+      def register_configured_contracts
+        config.contract_registrations.each do |registration|
+          register(registration.definition, as: registration.name)
+        end
+      end
+
+      def normalize_registration(name_or_definition, definition, as:, block:)
+        if ContractNaming.contract_class?(name_or_definition)
+          name = ContractNaming.normalize_contract_name(as || ContractNaming.infer_contract_name(name_or_definition))
+          return [name, name_or_definition]
+        end
+
+        name = ContractNaming.normalize_contract_name(as || name_or_definition)
+        [name, definition || block]
+      end
+
+      def compile_block(&block)
+        Igniter::Contracts.compile(profile: profile, &block)
+      end
+
+      def compile_registered(name)
+        key = name.to_sym
+        return compiled_contracts.fetch(key) if config.cache? && compiled_contracts.key?(key)
+
+        compiled = compile_registration(registry.fetch(key))
+        compiled_contracts[key] = compiled if config.cache?
+        compiled
+      end
+
+      def compile_registration(registration)
+        return compile_block(&registration.definition) if registration.block?
+
+        registration.definition.compile(profile: profile)
+      end
+    end
+  end
+end

data/lib/igniter/embed/contract_handle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Embed
+    class ContractHandle
+      attr_reader :name, :container
+
+      def initialize(name:, container:)
+        @name = name.to_sym
+        @container = container
+        freeze
+      end
+
+      def compile
+        container.compile(name)
+      end
+
+      def call(inputs = {}, **keyword_inputs)
+        container.call(name, inputs.merge(keyword_inputs))
+      end
+    end
+  end
+end