igniter 0.5.1 → 0.5.2

data/packages/igniter-contracts/lib/igniter/lang/verification_report.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Lang
+    class VerificationReport
+      METADATA_CARRIER_SECTIONS = %i[
+        diagnostics
+        receipts
+        model_validity_reports
+        scenario_comparison_reports
+        review_receipts
+      ].freeze
+      CUSTOM_METADATA_CARRIER_SECTIONS_KEY = :custom_sections
+
+      METADATA_CARRIER_SEMANTICS = {
+        report_only: true,
+        runtime_enforced: false,
+        execution_authorized: false,
+        provider_call_authorized: false,
+        real_data_export_authorized: false,
+        readiness_enforced: false,
+        ledger_core: false
+      }.freeze
+
+      DEFAULT_METADATA_REDACTION_POLICY = {
+        raw_ref_export: false,
+        hash_source_refs: true,
+        redacted_ref_kinds: []
+      }.freeze
+
+      RAW_REF_KEYS = %i[raw_ref raw_refs raw_source_ref raw_source_refs].freeze
+      RAW_REF_PREFIX = "raw:"
+
+      attr_reader :profile_fingerprint,
+                  :operations,
+                  :findings,
+                  :descriptors,
+                  :metadata,
+                  :metadata_manifest,
+                  :carrier_manifest,
+                  :diagnostic_payloads,
+                  :receipt_payloads,
+                  :schema_compatibility_diagnostics
+
+      def self.from_compilation_report(report)
+        new(
+          profile_fingerprint: report.profile_fingerprint,
+          operations: report.operations,
+          findings: report.findings.map(&:to_h),
+          metadata: { source: :compilation_report }
+        )
+      end
+
+      def self.from_artifact(artifact, profile_fingerprint:)
+        operations = artifact ? artifact.operations : []
+        new(
+          profile_fingerprint: profile_fingerprint,
+          operations: operations,
+          findings: [],
+          metadata: { source: :compiled_artifact }
+        )
+      end
+
+      def initialize(
+        profile_fingerprint:,
+        operations:,
+        findings: [],
+        metadata: {},
+        diagnostic_payloads: [],
+        receipt_payloads: [],
+        schema_compatibility_diagnostics: []
+      )
+        @profile_fingerprint = profile_fingerprint
+        @operations = operations.freeze
+        @findings = findings.freeze
+        @metadata = normalize_metadata(metadata)
+        @metadata_manifest = MetadataManifest.from_operations(operations)
+        @carrier_manifest = MetadataCarrierManifest.from_metadata(@metadata)
+        @descriptors = metadata_manifest.descriptors
+        @diagnostic_payloads = normalize_diagnostic_payloads(diagnostic_payloads)
+        @receipt_payloads = normalize_receipt_payloads(receipt_payloads)
+        @schema_compatibility_diagnostics = normalize_schema_compatibility_diagnostics(
+          schema_compatibility_diagnostics
+        )
+        freeze
+      end
+
+      def ok?
+        findings.empty?
+      end
+
+      def invalid?
+        !ok?
+      end
+
+      def to_h
+        {
+          ok: ok?,
+          profile_fingerprint: profile_fingerprint,
+          descriptors: descriptors,
+          metadata_manifest: metadata_manifest.to_h,
+          carrier_manifest: carrier_manifest.to_h,
+          diagnostic_payloads: diagnostic_payloads.map(&:to_h),
+          receipt_payloads: receipt_payloads.map(&:to_h),
+          schema_compatibility_diagnostics: schema_compatibility_diagnostics.map(&:to_h),
+          findings: findings,
+          metadata: metadata
+        }
+      end
+
+      private
+
+      def normalize_metadata(value)
+        metadata_hash = normalize_hash(value, :metadata)
+        return deep_freeze(metadata_hash) unless metadata_carrier?(metadata_hash)
+
+        raise ArgumentError, "metadata.redaction_policy is required for carrier sections" unless metadata_hash.key?(:redaction_policy)
+
+        metadata_hash[:redaction_policy] = normalize_metadata_redaction_policy(metadata_hash[:redaction_policy])
+        metadata_hash[:semantics] = normalize_metadata_semantics(metadata_hash[:semantics] || {})
+        reject_metadata_raw_refs!(metadata_hash)
+        deep_freeze(metadata_hash)
+      end
+
+      def metadata_carrier?(metadata_hash)
+        METADATA_CARRIER_SECTIONS.any? { |section| metadata_hash.key?(section) } ||
+          metadata_hash.key?(CUSTOM_METADATA_CARRIER_SECTIONS_KEY)
+      end
+
+      def normalize_metadata_redaction_policy(value)
+        policy = DEFAULT_METADATA_REDACTION_POLICY.merge(normalize_hash(value, :redaction_policy))
+        raise ArgumentError, "metadata.redaction_policy.raw_ref_export must be true or false" unless [true, false].include?(policy[:raw_ref_export])
+        raise ArgumentError, "metadata.redaction_policy.raw_ref_export true is not supported in v0" if policy[:raw_ref_export]
+
+        policy[:redacted_ref_kinds] = Array(policy[:redacted_ref_kinds]).map(&:to_s)
+        policy
+      end
+
+      def normalize_metadata_semantics(value)
+        normalize_hash(value, :semantics).merge(METADATA_CARRIER_SEMANTICS)
+      end
+
+      def reject_metadata_raw_refs!(metadata_hash)
+        raw_path = find_raw_ref(metadata_hash)
+        raise ArgumentError, "raw refs are not allowed in verification metadata at metadata.#{raw_path}" if raw_path
+      end
+
+      def normalize_diagnostic_payloads(entries)
+        entries.map do |entry|
+          next entry if entry.is_a?(DiagnosticPayload)
+
+          DiagnosticPayload.new(**entry.to_h.transform_keys(&:to_sym))
+        end.freeze
+      end
+
+      def normalize_receipt_payloads(entries)
+        entries.map do |entry|
+          next entry if entry.is_a?(ReceiptPayload)
+
+          ReceiptPayload.new(**entry.to_h.transform_keys(&:to_sym))
+        end.freeze
+      end
+
+      def normalize_schema_compatibility_diagnostics(entries)
+        entries.map do |entry|
+          next entry if entry.is_a?(SchemaCompatibilityDiagnostic)
+
+          SchemaCompatibilityDiagnostic.new(**entry.to_h.transform_keys(&:to_sym))
+        end.freeze
+      end
+
+      def find_raw_ref(value, path = [])
+        case value
+        when Hash
+          value.each do |key, entry|
+            normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+            return (path + [normalized_key]).join(".") if RAW_REF_KEYS.include?(normalized_key)
+
+            nested = find_raw_ref(entry, path + [normalized_key])
+            return nested if nested
+          end
+        when Array
+          value.each_with_index do |entry, index|
+            nested = find_raw_ref(entry, path + [index])
+            return nested if nested
+          end
+        when String
+          return path.join(".") if value.start_with?(RAW_REF_PREFIX)
+        end
+
+        nil
+      end
+
+      def normalize_hash(value, name)
+        raise ArgumentError, "#{name} must be a hash" unless value.respond_to?(:to_h)
+
+        value.to_h.each_with_object({}) do |(key, entry), hash|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          hash[normalized_key] = normalize_value(entry)
+        end
+      end
+
+      def normalize_value(value)
+        case value
+        when Hash
+          normalize_hash(value, :value)
+        when Array
+          value.map { |entry| normalize_value(entry) }
+        else
+          value
+        end
+      end
+
+      def deep_freeze(value)
+        case value
+        when Array
+          value.map { |entry| deep_freeze(entry) }.freeze
+        when Hash
+          value.transform_values { |entry| deep_freeze(entry) }.freeze
+        else
+          value.freeze
+        end
+      end
+    end
+  end
+end

data/packages/igniter-contracts/lib/igniter/lang.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "contracts"
+require_relative "lang/types"
+require_relative "lang/metadata_manifest"
+require_relative "lang/metadata_carrier_manifest"
+require_relative "lang/diagnostic_payload"
+require_relative "lang/receipt_payload"
+require_relative "lang/schema_compatibility_diagnostic"
+require_relative "lang/verification_report"
+require_relative "lang/backend"
+require_relative "lang/backends/ruby"
+
+module Igniter
+  module Lang
+    History = Types::History
+    BiHistory = Types::BiHistory
+    OLAPPoint = Types::OLAPPoint
+    Forecast = Types::Forecast
+
+    class << self
+      def ruby_backend(profile: Igniter::Contracts.default_profile)
+        Backends::Ruby.new(profile: profile)
+      end
+    end
+  end
+end

data/packages/igniter-contracts/lib/igniter-contracts.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/contracts"

data/packages/igniter-embed/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
+```