igniter-contracts 0.5.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3d6daf13d97a2824269d7dc2d255cf3a7844a36e83f7faec39a5e40000d924f
+  data.tar.gz: 6995a02e4283062ed8ad29cc4414f46a90ac184759db64d4bb68b7b2858fbd3d
+SHA512:
+  metadata.gz: 8e2aaf2deb50cfc7db0befaa7e4d25e18312b490034fc1052bcc03143b4b967d9c6f76c989108232ac9a31b61e32542a6fd24babc7b79703cdc8ede6102b3a4e
+  data.tar.gz: 11fddc0cfd6811517dfce9a024c468403abafd9b98c1e68ca426ba1b2bce57e735cef32038a9349049d5d8e72ec036a85b68262483e29e7d592ea740ba665add

data/README.md

@@ -0,0 +1,239 @@
+# igniter-contracts
+
+Public embedded kernel package for Igniter:
+
+- contracts and DSL
+- graph model and compiler
+- execution/runtime primitives
+- diagnostics, events, and core extension seams
+
+Primary entrypoints:
+
+- `require "igniter-contracts"`
+- `require "igniter/contracts"`
+- `require "igniter/lang"` for the additive Lang foundation
+
+Current proof path:
+
+- [Contract Class DSL](../../docs/guide/contract-class-dsl.md)
+- [Igniter Lang Foundation](../../docs/guide/igniter-lang-foundation.md)
+- [Getting Started](../../docs/guide/getting-started.md)
+
+Current implementation focus:
+
+- `Kernel`
+- `Profile`
+- `Environment`
+- `Registry` / `OrderedRegistry`
+- `Pack` / `BaselinePack`
+
+## Intended Use
+
+Use `igniter-contracts` when Igniter is embedded inside another host such as:
+
+- Rails applications
+- scripts and jobs
+- existing service runtimes
+
+This package is the lower-layer dependency that other runtime shapes should
+build on top of. It should not pull:
+
+- application hosting
+- server/runtime containers
+- cluster coordination
+- web rendering or schema-rendering packages
+
+It also should not depend on the legacy core implementation. Legacy code remains
+reference/parity material during the rewrite, not the public architecture.
+
+## Current Shape
+
+`igniter-contracts` starts from its own internal primitives:
+
+- registries
+- kernel/profile lifecycle
+- environment sugar over a finalized profile
+- packs
+- a tiny baseline pack
+
+## Ergonomics
+
+You can still work directly with `Kernel` and `Profile`, but the public facade
+now gives two equal authoring paths.
+
+For the low-level embedded kernel API, compile or run a block directly:
+
+```ruby
+environment = Igniter::Contracts.with
+
+result = environment.run(inputs: {}) do
+  const :tax_rate, 0.2
+  output :tax_rate
+end
+```
+
+For app code and human-edited contract files, use the class DSL:
+
+```ruby
+class PriceContract < Igniter::Contract
+  define do
+    input :order_total, type: :numeric
+    input :country, type: :string
+
+    compute :gross_total, depends_on: %i[order_total country] do |order_total:, country:|
+      order_total * (country == "UA" ? 1.2 : 1.0)
+    end
+
+    output :gross_total
+  end
+end
+
+contract = PriceContract.new(order_total: 100, country: "UA")
+contract.result.gross_total
+contract.update_inputs(order_total: 150)
+contract.output(:gross_total)
+```
+
+Compute nodes may also use `call:` for service objects or callable classes:
+
+```ruby
+compute :gross_total, depends_on: %i[order_total country], call: Pricing::GrossTotal
+```
+
+Contractable services expose a small service protocol to compute nodes:
+
+```ruby
+class BodyBatteryScorer
+  include Igniter::Contracts::Contractable
+
+  contractable :call do
+    role :migration_candidate
+    stage :shadowed
+    meta :domain, :wellness
+    input :sleep_hours
+    input :training_minutes
+    output :score
+  end
+
+  def call(sleep_hours:, training_minutes:)
+    sleep_score = observe(:sleep_score) { [[sleep_hours / 8.0, 1.0].min * 40, 0].max }
+    training_score = observe(:training_score) { training_minutes <= 45 ? 10 : 2 }
+
+    success(score: [[45 + sleep_score + training_score, 100].min, 0].max.round)
+  end
+end
+
+compute :body_battery,
+        depends_on: %i[sleep_hours training_minutes],
+        using: BodyBatteryScorer
+```
+
+`using:` returns a normalized payload with `outputs`, `observations`, `error`,
+and `success`. The service owns its internal implementation; Igniter owns the
+graph boundary and result protocol.
+
+Declared `input` and `output` names are validated at the protocol boundary.
+Missing inputs or missing declared outputs return a failure payload instead of
+raising through the caller. Extra outputs are allowed for now, which keeps
+contractable services useful during migration and discovery.
+
+`role`, `stage`, and `meta` travel in result metadata. Host layers such as
+`igniter-embed` can use those fields as defaults for observation and migration
+wrappers.
+
+Use `output:` when the graph should expose one named service output as the
+compute value:
+
+```ruby
+compute :score,
+        depends_on: %i[sleep_hours training_minutes],
+        using: BodyBatteryScorer,
+        output: :score
+```
+
+Additional helpers:
+
+- `Igniter::Contracts.build_kernel(*packs)`
+- `Igniter::Contracts.build_profile(*packs)`
+- `Igniter::Contracts.with(*packs)`
+
+## Verification
+
+Use focused package specs and runnable examples as the current proof path:
+
+```bash
+bundle exec rspec packages/igniter-contracts/spec spec/current
+ruby examples/run.rb smoke
+```
+
+Focused contracts/lang checks:
+
+```bash
+ruby examples/run.rb run contracts/class_pricing
+ruby examples/run.rb run contracts/class_callable
+ruby examples/run.rb run contracts/embed_class_registration
+ruby examples/run.rb run contracts/contractable_shadow
+ruby examples/run.rb run contracts/step_result
+ruby examples/run.rb run contracts/lang_foundation
+```
+
+For narrow changes, run RuboCop on the changed files. Full-project RuboCop
+currently includes pre-existing archived/research offenses, so changed-file
+lint is the practical gate for focused package slices; this is a caveat, not a
+quality target.
+
+## Igniter Lang Foundation
+
+`require "igniter/lang"` loads a small contracts-facing Lang namespace.
+Currently this is an additive reference surface over the existing contracts
+runtime:
+
+- `Igniter::Lang.ruby_backend` wraps current compile, execute, diagnose, and
+  verify APIs.
+- `History`, `BiHistory`, `OLAPPoint`, and `Forecast` are immutable
+  definition-time descriptors that can be attached as operation metadata.
+- `VerificationReport` is read-only and follows current compilation findings.
+  Its `metadata` hash can carry generic report-only sections such as
+  `diagnostics`, `receipts`, `model_validity_reports`,
+  `scenario_comparison_reports`, and `review_receipts`.
+- `MetadataManifest` reports declared `type:`, `return_type:`, `deadline:`,
+  and `wcet:` metadata.
+- `DiagnosticPayload` is a generic report-only carrier for metadata-only
+  diagnostic hashes from projection, pipeline, availability, or future
+  operation profiles. It includes a redaction policy and rejects raw refs in v0.
+- `ReceiptPayload` is a generic report-only carrier for metadata-only receipts
+  such as request, execution, idempotency, or external bridge receipt shapes.
+  It includes the same redaction defaults and does not authorize execution.
+- `SchemaCompatibilityDiagnostic` is an immutable report-only compatibility
+  value object with required evidence links and an optional single-hop
+  `migration_profile`.
+
+Metadata manifest fields are declared, not enforced. `return_type`, `deadline`,
+and `wcet` appear in reports with `enforced: false`; they do not add runtime
+checks, warnings, deadline monitoring, or `ExecutionResult` changes.
+Verification metadata carrier sections are opaque serializable hashes. When
+present, they require an explicit `redaction_policy`, force
+`raw_ref_export: false`, reject raw refs, and produce a `carrier_manifest` with
+section counts, profile names, and report-only enforcement flags. Future opaque
+sections can be carried under `metadata[:custom_sections]`; OSINT-style
+profiles and future compiler-pipeline proof profiles remain metadata-only
+custom sections rather than public package API, including separated compiler
+pass reports.
+Generic diagnostic payloads are serialized through `VerificationReport` as
+`diagnostic_payloads`; generic receipt payloads use `receipt_payloads`. Neither
+surface authorizes package adapters, real data export, provider bridges,
+operation execution, readiness checks, Ledger integration, or runtime
+enforcement.
+Schema compatibility diagnostics follow the same boundary:
+`report_only: true`, `runtime_enforced: false`, and no migration execution.
+The optional migration profile only serializes evidence, including blocked
+OOF-MR3 wrong-fingerprint cases.
+
+Try the compact proof:
+
+```bash
+ruby examples/contracts/lang_foundation.rb
+```
+
+See [Igniter Lang Foundation](../../docs/guide/igniter-lang-foundation.md) for
+the short guide.

data/lib/igniter/contracts/api.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    class << self
+      def build_kernel(*packs)
+        install_packs(Assembly::Kernel.new.install(BaselinePack), packs)
+      end
+
+      def build_profile(*packs)
+        build_kernel(*packs).finalize
+      end
+
+      def with(*packs)
+        Environment.new(profile: build_profile(*packs))
+      end
+
+      def default_kernel
+        @default_kernel ||= build_kernel
+      end
+
+      def default_profile
+        @default_profile ||= default_kernel.finalize
+      end
+
+      def compile(profile: default_profile, &block)
+        Execution::Compiler.compile(profile: profile, &block)
+      end
+
+      def validation_report(profile: default_profile, &block)
+        Execution::Compiler.validation_report(profile: profile, &block)
+      end
+
+      def compilation_report(profile: default_profile, &block)
+        Execution::Compiler.compilation_report(profile: profile, &block)
+      end
+
+      def execute(compiled_graph, inputs:, profile: default_profile)
+        execute_with(:inline, compiled_graph, inputs: inputs, profile: profile)
+      end
+
+      def execute_with(executor_name, compiled_graph, inputs:, profile: default_profile, runtime: Execution::Runtime)
+        executor = profile.executor(executor_name)
+        hook_spec = Assembly::HookSpecs.fetch(:executors)
+        invocation = Execution::ExecutionRequest.new(
+          compiled_graph: compiled_graph,
+          inputs: inputs,
+          profile: profile,
+          runtime: runtime
+        )
+        result = executor.call(invocation: invocation)
+        hook_spec.validate_result!(executor_name, result)
+      rescue KeyError
+        raise UnknownExecutorError, "unknown executor #{executor_name}"
+      end
+
+      def diagnose(result, profile: default_profile)
+        Execution::Diagnostics.build_report(result: result, profile: profile)
+      end
+
+      def apply_effect(effect_name, payload:, context: {}, profile: default_profile)
+        effect = profile.effect(effect_name)
+        invocation = Execution::EffectInvocation.new(
+          payload: payload,
+          context: context,
+          profile: profile
+        )
+        effect.call(invocation: invocation)
+      rescue KeyError
+        raise UnknownEffectError, "unknown effect #{effect_name}"
+      end
+
+      def reset_defaults!
+        @default_kernel = nil
+        @default_profile = nil
+      end
+
+      private
+
+      def install_packs(kernel, packs)
+        normalize_packs(packs).each do |pack|
+          kernel.install(pack)
+        end
+        kernel
+      end
+
+      def normalize_packs(packs)
+        packs.flatten.compact.uniq
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/baseline_pack.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      module BaselinePack
+        module_function
+
+        def manifest
+          PackManifest.new(
+            name: :baseline,
+            node_contracts: BASELINE_NODE_KINDS.keys.map { |kind| PackManifest.node(kind) },
+            registry_contracts: [
+              PackManifest.normalizer(:normalize_operation_attributes),
+              PackManifest.validator(:uniqueness),
+              PackManifest.validator(:outputs),
+              PackManifest.validator(:dependencies),
+              PackManifest.validator(:callables),
+              PackManifest.validator(:effect_dependencies),
+              PackManifest.validator(:effect_payload_builders),
+              PackManifest.validator(:effect_adapters),
+              PackManifest.validator(:types),
+              PackManifest.executor(:inline),
+              PackManifest.diagnostic(:baseline_summary)
+            ]
+          )
+        end
+
+        BASELINE_NODE_KINDS = {
+          input: NodeType.new(kind: :input, metadata: { category: :data }),
+          const: NodeType.new(kind: :const, metadata: { category: :value }),
+          compute: NodeType.new(kind: :compute, metadata: { category: :data }),
+          effect: NodeType.new(kind: :effect, metadata: { category: :effect }),
+          output: NodeType.new(kind: :output, metadata: { category: :terminal })
+        }.freeze
+
+        BASELINE_DSL_KEYWORDS = {
+          input: DslKeyword.new(:input, lambda { |name, builder:, **attributes|
+            builder.add_operation(kind: :input, name: name, **attributes)
+          }),
+          const: DslKeyword.new(:const, lambda { |name, value, builder:|
+            builder.add_operation(kind: :const, name: name, value: value)
+          }),
+          compute: DslKeyword.new(:compute, lambda { |name, builder:, **attributes, &block|
+            normalized_attributes = attributes.dup
+            normalized_attributes[:callable] = normalized_attributes.delete(:call) if normalized_attributes.key?(:call)
+            if normalized_attributes.key?(:using)
+              target = normalized_attributes.delete(:using)
+              output_name = normalized_attributes.delete(:output)&.to_sym
+              normalized_attributes[:callable] = lambda do |**values|
+                payload = Contractable.invoke(target, **values).to_h
+                output_name && payload.fetch(:success) ? payload.fetch(:outputs).fetch(output_name) : payload
+              end
+            end
+            normalized_attributes[:callable] = block if block
+            builder.add_operation(kind: :compute, name: name, **normalized_attributes)
+          }),
+          effect: DslKeyword.new(:effect, lambda { |name, using:, builder:, callable: nil, **attributes, &block|
+            normalized_attributes = attributes.dup
+            normalized_attributes[:using] = using.to_sym
+            normalized_attributes[:callable] = block if block
+            normalized_attributes[:callable] = callable if callable && !block
+            builder.add_operation(kind: :effect, name: name, **normalized_attributes)
+          }),
+          output: DslKeyword.new(:output, lambda { |name, builder:, **attributes|
+            builder.add_operation(kind: :output, name: name, **attributes)
+          })
+        }.freeze
+
+        BASELINE_DIAGNOSTICS = {
+          baseline_summary: Module.new do
+            module_function
+
+            def augment(report:, result:, profile:) # rubocop:disable Lint/UnusedMethodArgument
+              report.add_section(:baseline_summary, {
+                                   outputs: result.outputs.keys.sort,
+                                   state: result.state.keys.sort
+                                 })
+            end
+          end
+        }.freeze
+
+        def install_into(kernel)
+          install_nodes(kernel)
+          install_dsl_keywords(kernel)
+          install_normalizers(kernel)
+          install_validators(kernel)
+          install_runtime_handlers(kernel)
+          install_executors(kernel)
+          install_diagnostics(kernel)
+          kernel
+        end
+
+        def install_nodes(kernel)
+          BASELINE_NODE_KINDS.each do |key, value|
+            kernel.nodes.register(key, value)
+          end
+        end
+
+        def install_dsl_keywords(kernel)
+          BASELINE_DSL_KEYWORDS.each do |key, value|
+            kernel.dsl_keywords.register(key, value)
+          end
+        end
+
+        def install_normalizers(kernel)
+          kernel.normalizers.register(:normalize_operation_attributes, Execution::BaselineNormalizers.method(:normalize_operation_attributes))
+        end
+
+        def install_validators(kernel)
+          kernel.validators.register(:uniqueness, Execution::BaselineValidators.method(:validate_uniqueness))
+          kernel.validators.register(:outputs, Execution::BaselineValidators.method(:validate_outputs))
+          kernel.validators.register(:dependencies, Execution::BaselineValidators.method(:validate_dependencies))
+          kernel.validators.register(:callables, Execution::BaselineValidators.method(:validate_callables))
+          kernel.validators.register(:effect_dependencies, Execution::BaselineValidators.method(:validate_effect_dependencies))
+          kernel.validators.register(:effect_payload_builders, Execution::BaselineValidators.method(:validate_effect_payload_builders))
+          kernel.validators.register(:effect_adapters, Execution::BaselineValidators.method(:validate_effect_adapters))
+          kernel.validators.register(:types, Execution::BaselineValidators.method(:validate_types))
+        end
+
+        def install_runtime_handlers(kernel)
+          kernel.runtime_handlers.register(:input, Execution::BaselineRuntime.method(:handle_input))
+          kernel.runtime_handlers.register(:const, Execution::ConstRuntime.method(:handle_const))
+          kernel.runtime_handlers.register(:compute, Execution::BaselineRuntime.method(:handle_compute))
+          kernel.runtime_handlers.register(:effect, Execution::BaselineRuntime.method(:handle_effect))
+          kernel.runtime_handlers.register(:output, Execution::BaselineRuntime.method(:handle_output))
+        end
+
+        def install_executors(kernel)
+          kernel.executors.register(:inline, Execution::InlineExecutor.method(:call))
+        end
+
+        def install_diagnostics(kernel)
+          BASELINE_DIAGNOSTICS.each do |key, value|
+            kernel.diagnostics_contributors.register(key, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/const_pack.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      module ConstPack
+        module_function
+
+        def manifest
+          PackManifest.new(
+            name: :const,
+            node_contracts: [PackManifest.node(:const)]
+          )
+        end
+
+        def install_into(kernel)
+          return kernel if kernel.nodes.registered?(:const)
+
+          kernel.nodes.register(:const, NodeType.new(kind: :const, metadata: { category: :value }))
+          kernel.dsl_keywords.register(:const, DslKeyword.new(:const) do |name, value, builder:|
+            builder.add_operation(kind: :const, name: name, value: value)
+          end)
+          kernel.runtime_handlers.register(:const, Execution::ConstRuntime.method(:handle_const))
+          kernel
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/dsl_keyword.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      class DslKeyword
+        attr_reader :name
+
+        def initialize(name, callable = nil, &block)
+          @name = name.to_sym
+          @callable = callable || block
+          raise ArgumentError, "keyword #{@name} requires a callable" unless @callable
+        end
+
+        def call(*args, builder:, **kwargs, &block)
+          @callable.call(*args, builder:, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/hook_result_policies.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      module HookResultPolicies
+        module_function
+
+        def operations_array(result)
+          return "must return an Array of operations" unless result.is_a?(Array)
+
+          result.each_with_index do |operation, index|
+            message = validate_operation(operation)
+            return "must return an Array of operations; element #{index} #{message}" if message
+          end
+
+          nil
+        end
+
+        def execution_result(result)
+          return "must return an ExecutionResult" unless result.is_a?(Execution::ExecutionResult)
+
+          nil
+        end
+
+        def validation_findings(result)
+          return nil if result.nil?
+          return "must return an Array of ValidationFinding entries" unless result.is_a?(Array)
+
+          invalid_index = result.find_index { |entry| !entry.is_a?(Execution::ValidationFinding) }
+          return nil if invalid_index.nil?
+
+          "must return an Array of ValidationFinding entries; element #{invalid_index} is invalid"
+        end
+
+        def validate_operation(operation)
+          return "must be an Execution::Operation" unless operation.is_a?(Execution::Operation)
+          return "must use Symbol kind" unless operation.kind.is_a?(Symbol)
+          return "must use Symbol name" unless operation.name.is_a?(Symbol)
+          return "must use Hash attributes" unless operation.attributes.is_a?(Hash)
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/igniter/contracts/assembly/hook_spec.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Contracts
+    module Assembly
+      class HookSpec
+        attr_reader :registry, :method_name, :required_keywords, :role, :return_policy
+
+        def initialize(registry:, method_name:, required_keywords:, role:, return_policy: :opaque,
+                       result_validator: nil)
+          @registry = registry.to_sym
+          @method_name = method_name.to_sym
+          @required_keywords = required_keywords.map(&:to_sym).freeze
+          @role = role.to_sym
+          @return_policy = return_policy.to_sym
+          @result_validator = result_validator
+          freeze
+        end
+
+        def validate!(key, implementation)
+          unless implementation.respond_to?(method_name)
+            raise InvalidHookImplementationError,
+                  "#{registry} entry #{key} must respond to ##{method_name}"
+          end
+
+          parameters = parameters_for(implementation)
+          return if accepts_required_keywords?(parameters)
+
+          missing = missing_keywords(parameters)
+          expected_keywords = required_keywords.map { |name| "#{name}:" }.join(", ")
+          missing_labels = missing.map { |name| "#{name}:" }.join(", ")
+
+          raise InvalidHookImplementationError,
+                "#{registry} entry #{key} must accept keywords #{expected_keywords}; missing #{missing_labels}"
+        end
+
+        def validate_result!(key, result)
+          return result unless @result_validator
+
+          message = @result_validator.call(result)
+          return result unless message
+
+          raise InvalidHookResultError,
+                "#{registry} entry #{key} (#{role}) #{message}"
+        end
+
+        private
+
+        def accepts_required_keywords?(parameters)
+          missing_keywords(parameters).empty?
+        end
+
+        def parameters_for(implementation)
+          if method_name == :call && implementation.respond_to?(:parameters)
+            implementation.parameters
+          else
+            implementation.method(method_name).parameters
+          end
+        end
+
+        def missing_keywords(parameters)
+          return [] if parameters.any? { |type, _name| type == :keyrest }
+
+          accepted = parameters.filter_map do |type, name|
+            name.to_sym if %i[key keyreq].include?(type) && name
+          end
+
+          required_keywords.reject { |keyword| accepted.include?(keyword) }
+        end
+      end
+    end
+  end
+end