igniter 0.5.1 → 0.5.2

data/packages/igniter-extensions/README.md

@@ -1,18 +1,378 @@
 # igniter-extensions
 
-Public extension entrypoints for Igniter.
+Contracts-native extension packs for Igniter.
 
-This package owns the `igniter/extensions/*` activation surface, including:
+This package now focuses only on packs built on top of `Igniter::Contracts`.
 
+Primary entrypoints:
+
+- `require "igniter-extensions"`
+- `require "igniter/extensions/contracts"`
+
+Contracts-facing external packs now live here too:
+
+- `Igniter::Extensions::Contracts::ExecutionReportPack`
+- `Igniter::Extensions::Contracts::LookupPack`
+- `Igniter::Extensions::Contracts::AggregatePack`
+- `Igniter::Extensions::Contracts::AuditPack`
+- `Igniter::Extensions::Contracts::BranchPack`
+- `Igniter::Extensions::Contracts::CapabilitiesPack`
+- `Igniter::Extensions::Contracts::CollectionPack`
+- `Igniter::Extensions::Contracts::CommercePack`
+- `Igniter::Extensions::Contracts::ComposePack`
+- `Igniter::Extensions::Contracts::ContentAddressingPack`
+- `Igniter::Extensions::Contracts::CreatorPack`
+- `Igniter::Extensions::Contracts::DataflowPack`
+- `Igniter::Extensions::Contracts::DebugPack`
+- `Igniter::Extensions::Contracts::DifferentialPack`
+- `Igniter::Extensions::Contracts::JournalPack`
+- `Igniter::Extensions::Contracts::InvariantsPack`
+- `Igniter::Extensions::Contracts::McpPack`
+- `Igniter::Extensions::Contracts::ProvenancePack`
+- `Igniter::Extensions::Contracts::ReactivePack`
+- `Igniter::Extensions::Contracts::SagaPack`
+
+Those packs install into `Igniter::Contracts` through the public facade only:
+
+```ruby
+require "igniter/extensions/contracts"
+
+environment = Igniter::Extensions::Contracts.with
+
+result = environment.run(inputs: { rates: { ua: 0.2 } }) do
+  input :rates
+  lookup :tax_rate, from: :rates, dig: %i[eu ua], default: 0.2
+  output :tax_rate
+end
+```
+
+Default helpers like `Igniter::Extensions::Contracts.with` currently install the
+safe default packs (`ExecutionReportPack` and `LookupPack`). Operational packs
+like `JournalPack` stay opt-in:
+
+```ruby
+environment = Igniter::Extensions::Contracts.with(
+  Igniter::Extensions::Contracts::JournalPack
+)
+```
+
+`BranchPack` adds a contracts-native decision DSL that still lowers to ordinary
+`compute` semantics:
+
+```ruby
+environment = Igniter::Contracts.with(
+  Igniter::Contracts::ProjectPack,
+  Igniter::Extensions::Contracts::BranchPack
+)
+
+result = environment.run(inputs: { country: "DE", vip: true }) do
+  input :country
+  input :vip
+
+  branch :delivery_strategy, on: :country, depends_on: [:vip] do
+    on "UA", id: :local, value: :local
+    on matches: /\A[A-Z]{2}\z/, id: :international do |vip:|
+      vip ? :priority_international : :international
+    end
+    default value: :fallback
+  end
+
+  project :delivery_mode, from: :delivery_strategy, key: :value
+  output :delivery_mode
+end
+```
+
+`ComposePack` adds explicit nested contract invocation without restoring legacy
+composition semantics into the kernel:
+
+```ruby
+environment = Igniter::Contracts.with(
+  Igniter::Extensions::Contracts::ComposePack
+)
+
+pricing_contract = environment.compile do
+  input :amount
+  input :tax_rate
+  compute :total, depends_on: %i[amount tax_rate] do |amount:, tax_rate:|
+    amount + (amount * tax_rate)
+  end
+  output :total
+end
+
+result = environment.run(inputs: { subtotal: 100, rate: 0.2 }) do
+  input :subtotal
+  input :rate
+
+  compose :pricing_total,
+          contract: pricing_contract,
+          inputs: { amount: :subtotal, tax_rate: :rate },
+          output: :total
+
+  output :pricing_total
+end
+```
+
+The important forward-compatibility rule is that `ComposePack` keeps local
+execution as the default, but also exposes `via:` for a custom invocation
+adapter. That gives `igniter-application` or `igniter-cluster` room to add
+remote compose later without rewriting the DSL contract.
+
+`CollectionPack` follows the same idea for keyed collection execution:
+
+```ruby
+environment = Igniter::Contracts.with(
+  Igniter::Extensions::Contracts::CollectionPack
+)
+
+result = environment.run(inputs: {
+  items: [{ sku: "a", amount: 10 }, { sku: "b", amount: 20 }],
+  tax_rate: 0.2
+}) do
+  input :items
+  input :tax_rate
+
+  collection :priced_items, from: :items, key: :sku, inputs: { tax_rate: :tax_rate } do
+    input :sku
+    input :amount
+    input :tax_rate
+
+    compute :total, depends_on: %i[amount tax_rate] do |amount:, tax_rate:|
+      amount + (amount * tax_rate)
+    end
+
+    output :total
+  end
+
+  output :priced_items
+end
+```
+
+It returns a `CollectionResult` keyed by item identity, and keeps `via:` open
+for a future remote/distributed collection invoker without changing the user DSL.
+
+Applied presets can sit on top of those packs too:
+
+```ruby
+environment = Igniter::Extensions::Contracts.with_preset(:commerce)
+```
+
+For explicit content-addressed reuse, the contracts-side replacement is
+`ContentAddressingPack`:
+
+```ruby
+environment = Igniter::Contracts.with(
+  Igniter::Extensions::Contracts::ContentAddressingPack
+)
+
+tax = Igniter::Extensions::Contracts.content_addressed(
+  fingerprint: "tax_v1"
+) do |country:, amount:|
+  { ua: 0.2, us: 0.1 }.fetch(country) * amount
+end
+```
+
+For developer-focused observability, `DebugPack` can bundle profile,
+compilation, execution, diagnostics, and provenance into one report:
+
+```ruby
+environment = Igniter::Extensions::Contracts.with(
+  Igniter::Extensions::Contracts::DebugPack
+)
+
+report = Igniter::Extensions::Contracts.debug_report(
+  environment,
+  inputs: { amount: 10 }
+) do
+  input :amount
+  output :amount
+end
+```
+
+It can also audit a custom pack before finalize, which is the first bridge
+toward a future `CreatorPack` workflow:
+
+```ruby
+audit = Igniter::Extensions::Contracts.audit_pack(MyDraftPack, environment)
+
+audit.ok?
+audit.missing_node_definitions
+audit.missing_registry_contracts
+audit.finalize_error
+```
+
+`CreatorPack` now adds a minimal scaffold/report workflow on top of that:
+
+```ruby
+scaffold = Igniter::Extensions::Contracts.scaffold_pack(
+  name: :slug,
+  profile: :feature_node,
+  scope: :app_local,
+  namespace: "MyCompany::IgniterPacks"
+)
+
+report = Igniter::Extensions::Contracts.creator_report(
+  name: :slug,
+  profile: :feature_node
+)
+
+workflow = Igniter::Extensions::Contracts.creator_workflow(
+  name: :slug,
+  profile: :feature_node,
+  scope: :standalone_gem
+)
+```
+
+Available authoring profiles:
+
+- `:feature_node`
+- `:operational_adapter`
+- `:diagnostic_bundle`
+- `:bundle_pack`
+
+Available target scopes:
+
+- `:app_local`
+- `:monorepo_package`
+- `:standalone_gem`
+
+The workflow helper turns those decisions into an explicit authoring ladder:
+
+- profile/scope selection
+- scaffold generation
+- implementation
+- audit validation
+- packaging readiness
+
+It also separates recommended runtime dependency packs from development-only
+tooling packs, so authoring guidance does not accidentally become runtime
+bundle surface.
+
+There is also a stateful wizard layer that can hold partial decisions before
+you are ready to generate files:
+
+```ruby
+wizard = Igniter::Extensions::Contracts.creator_wizard(
+  name: :delivery,
+  capabilities: %i[effect executor]
+)
+
+wizard.current_decision
+wizard.branching_hints
+wizard.recommended_examples
+completed = wizard.apply(scope: :standalone_gem)
+```
+
+For file generation, `CreatorPack` also exposes a multi-step writer with
+explicit planning:
+
+```ruby
+writer = Igniter::Extensions::Contracts.creator_writer(
+  name: :slug,
+  profile: :feature_node,
+  scope: :app_local,
+  root: "/tmp/my_pack"
+)
+
+plan = writer.plan
+result = writer.write
+```
+
+By default the writer uses `:skip_existing`, so existing files are preserved
+unless you explicitly opt into `mode: :overwrite`.
+
+`McpPack` is the first thin tooling adapter over those stabilized surfaces:
+
+```ruby
+environment = Igniter::Extensions::Contracts.with(
+  Igniter::Extensions::Contracts::McpPack
+)
+
+Igniter::Extensions::Contracts.mcp_tools
+result = Igniter::Extensions::Contracts.mcp_call(
+  :creator_wizard,
+  target: environment,
+  name: :delivery,
+  capabilities: %i[effect executor]
+)
+```
+
+The goal is to adapt existing debug/creator primitives for external tools, not
+to invent a second authoring stack.
+
+For stepwise external tooling, `McpPack` also exposes a serialized
+`creator_session` flow:
+
+```ruby
+session = Igniter::Extensions::Contracts.mcp_creator_session(
+  target: environment,
+  name: :delivery,
+  capabilities: %i[effect executor]
+)
+
+updated = Igniter::Extensions::Contracts.mcp_call(
+  :creator_session_apply,
+  target: environment,
+  session: session.to_h.fetch(:payload).fetch(:session),
+  updates: { scope: :standalone_gem }
+)
+```
+
+You can also drive scaffolding directly from capabilities:
+
+```ruby
+Igniter::Extensions::Contracts.scaffold_pack(
+  name: :delivery,
+  capabilities: %i[effect executor]
+)
+```
+
+Older extension activators still exist for migration scenarios:
+
+- `require "igniter/extensions/auditing"`
+- `require "igniter/extensions/capabilities"`
 - `require "igniter/extensions/dataflow"`
 - `require "igniter/extensions/saga"`
 - `require "igniter/extensions/provenance"`
 - `require "igniter/extensions/differential"`
 - `require "igniter/extensions/incremental"`
+- `require "igniter/extensions/reactive"`
+- `require "igniter/extensions/invariants"`
 
-It also provides the package facade:
+Those activators are migration context, not the long-term extension model.
 
-- `require "igniter-extensions"`
+The first canonical activator-to-pack migration target is now explicit:
+
+- `require "igniter/extensions/execution_report"`
+  -> `Igniter::Extensions::Contracts::ExecutionReportPack`
+- `require "igniter/extensions/auditing"`
+  -> `Igniter::Extensions::Contracts::AuditPack`
+- `require "igniter/extensions/capabilities"`
+  -> `Igniter::Extensions::Contracts::CapabilitiesPack`
+- `require "igniter/extensions/dataflow"`
+  -> `Igniter::Extensions::Contracts::DataflowPack`
+- `require "igniter/extensions/provenance"`
+  -> `Igniter::Extensions::Contracts::ProvenancePack`
+- `require "igniter/extensions/saga"`
+  -> `Igniter::Extensions::Contracts::SagaPack`
+- `require "igniter/extensions/incremental"`
+  -> `Igniter::Extensions::Contracts::IncrementalPack`
+- `require "igniter/extensions/differential"`
+  -> `Igniter::Extensions::Contracts::DifferentialPack`
+- `require "igniter/extensions/reactive"`
+  -> `Igniter::Extensions::Contracts::ReactivePack`
+- `require "igniter/extensions/invariants"`
+  -> `Igniter::Extensions::Contracts::InvariantsPack`
+
+See [examples/contracts/auditing.rb](../../examples/contracts/auditing.rb)
+and [examples/contracts/capabilities.rb](../../examples/contracts/capabilities.rb)
+and [examples/contracts/dataflow.rb](../../examples/contracts/dataflow.rb)
+and [examples/contracts/differential.rb](../../examples/contracts/differential.rb)
+and [examples/contracts/invariants.rb](../../examples/contracts/invariants.rb)
+and [examples/contracts/provenance.rb](../../examples/contracts/provenance.rb)
+and [examples/contracts/reactive.rb](../../examples/contracts/reactive.rb)
+and [examples/contracts/saga.rb](../../examples/contracts/saga.rb)
+and [examples/contracts/incremental.rb](../../examples/contracts/incremental.rb)
+for runnable migration walkthroughs.
 
 Docs:
 

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module AggregatePack
+        AGGREGATE_KEYWORDS = %i[count sum avg].freeze
+
+        class << self
+          def manifest
+            Igniter::Contracts::PackManifest.new(
+              name: :extensions_aggregate,
+              registry_contracts: AGGREGATE_KEYWORDS.map { |kind| Igniter::Contracts::PackManifest.dsl_keyword(kind) }
+            )
+          end
+
+          def install_into(kernel)
+            install_dsl_keywords(kernel)
+            kernel
+          end
+
+          def install_dsl_keywords(kernel)
+            kernel.dsl_keywords.register(:count, count_keyword)
+            kernel.dsl_keywords.register(:sum, sum_keyword)
+            kernel.dsl_keywords.register(:avg, avg_keyword)
+          end
+
+          def count_keyword
+            Igniter::Contracts::DslKeyword.new(:count) do |name, from:, builder:, matching: nil|
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: [from.to_sym],
+                callable: lambda do |**values|
+                  items = AggregatePack.enumerable_source(values.fetch(from.to_sym), source_name: from.to_sym,
+                                                                                     operation_name: :count)
+
+                  if matching
+                    items.count { |item| matching.call(item) }
+                  else
+                    items.count
+                  end
+                end
+              )
+            end
+          end
+
+          def sum_keyword
+            Igniter::Contracts::DslKeyword.new(:sum) do |name, from:, builder:, using: nil|
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: [from.to_sym],
+                callable: lambda do |**values|
+                  items = AggregatePack.enumerable_source(values.fetch(from.to_sym), source_name: from.to_sym,
+                                                                                     operation_name: :sum)
+                  items.reduce(0) do |total, item|
+                    total + AggregatePack.extract_value(item, using)
+                  end
+                end
+              )
+            end
+          end
+
+          def avg_keyword
+            Igniter::Contracts::DslKeyword.new(:avg) do |name, from:, builder:, using: nil|
+              builder.add_operation(
+                kind: :compute,
+                name: name,
+                depends_on: [from.to_sym],
+                callable: lambda do |**values|
+                  items = AggregatePack.enumerable_source(values.fetch(from.to_sym), source_name: from.to_sym,
+                                                                                     operation_name: :avg)
+                  projected = items.map { |item| AggregatePack.extract_value(item, using) }
+                  next nil if projected.empty?
+
+                  projected.sum.to_f / projected.length
+                end
+              )
+            end
+          end
+
+          def enumerable_source(source, source_name:, operation_name:)
+            return source.to_a if source.respond_to?(:to_a)
+
+            raise TypeError, "#{operation_name} source #{source_name} is not enumerable"
+          end
+
+          def extract_value(item, projection)
+            return item if projection.nil?
+            return projection.call(item) if projection.respond_to?(:call)
+
+            key = projection.to_sym
+            return item.fetch(key) if item.respond_to?(:key?) && item.key?(key)
+            return item.fetch(key.to_s) if item.respond_to?(:key?) && item.key?(key.to_s)
+
+            item.public_send(key)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit/builder.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Audit
+        module Builder
+          module_function
+
+          def build(target)
+            result = unwrap_result(target)
+            compiled_graph = result.compiled_graph
+            outputs = result.outputs.to_h
+            state_values = result.state.to_h
+
+            Snapshot.new(
+              graph: graph_name(compiled_graph),
+              profile_fingerprint: result.profile_fingerprint,
+              events: build_events(compiled_graph, state_values: state_values, outputs: outputs),
+              states: build_states(compiled_graph, state_values: state_values, outputs: outputs),
+              children: build_children(state_values),
+              output_names: compiled_graph.operations.select(&:output?).map(&:name)
+            )
+          end
+
+          def unwrap_result(target)
+            return target.execution_result if target.respond_to?(:execution_result)
+
+            target
+          end
+
+          def graph_name(compiled_graph)
+            operation_names = compiled_graph.operations.reject(&:output?).map(&:name)
+            return "contracts_graph" if operation_names.empty?
+
+            "contracts_graph(#{operation_names.join(",")})"
+          end
+
+          def build_events(compiled_graph, state_values:, outputs:)
+            compiled_graph.operations.each_with_index.map do |operation, index|
+              Event.new(
+                event_id: "#{operation.kind}:#{operation.name}:#{index}",
+                type: event_type_for(operation),
+                node_name: operation.name,
+                path: [operation.name],
+                status: status_for(operation, state_values: state_values, outputs: outputs),
+                payload: payload_for(operation, state_values: state_values, outputs: outputs)
+              )
+            end
+          end
+
+          def build_states(compiled_graph, state_values:, outputs:)
+            compiled_graph.operations.each_with_object({}) do |operation, memo|
+              next if operation.output?
+
+              value = operation.output? ? outputs[operation.name] : state_values[operation.name]
+              memo[operation.name] = {
+                path: [operation.name],
+                kind: operation.kind,
+                status: status_for(operation, state_values: state_values, outputs: outputs),
+                value: serialize_value(value),
+                dependencies: dependency_names_for(operation)
+              }
+            end
+          end
+
+          def build_children(state_values)
+            state_values.each_with_object([]) do |(name, value), memo|
+              next unless nested_execution_result?(value)
+
+              memo << {
+                node_name: name,
+                snapshot: build(value).to_h
+              }
+            end
+          end
+
+          def event_type_for(operation)
+            return :output_observed if operation.output?
+
+            :"#{operation.kind}_observed"
+          end
+
+          def status_for(operation, state_values:, outputs:)
+            collection = operation.output? ? outputs : state_values
+            collection.key?(operation.name) ? :succeeded : :missing
+          end
+
+          def payload_for(operation, state_values:, outputs:)
+            value = operation.output? ? outputs[operation.name] : state_values[operation.name]
+            payload = {
+              kind: operation.kind,
+              value: serialize_value(value)
+            }
+
+            dependencies = dependency_names_for(operation)
+            payload[:dependencies] = dependencies if dependencies.any?
+            payload
+          end
+
+          def dependency_names_for(operation)
+            names = []
+            names.concat(Array(operation.attributes[:depends_on])) if operation.attribute?(:depends_on)
+            names << operation.attributes[:from] if operation.attribute?(:from)
+            names.map(&:to_sym).uniq
+          end
+
+          def serialize_value(value)
+            case value
+            when Igniter::Contracts::ExecutionResult
+              {
+                type: :execution_result,
+                profile_fingerprint: value.profile_fingerprint,
+                outputs: value.outputs.to_h
+              }
+            when Array
+              value.map { |item| serialize_value(item) }
+            when Hash
+              value.transform_keys(&:to_sym).transform_values { |item| serialize_value(item) }
+            else
+              value
+            end
+          end
+
+          def nested_execution_result?(value)
+            value.is_a?(Igniter::Contracts::ExecutionResult)
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit/event.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Audit
+        class Event
+          attr_reader :event_id, :type, :node_name, :path, :status, :payload
+
+          def initialize(event_id:, type:, node_name:, path:, status:, payload: {})
+            @event_id = event_id.to_s
+            @type = type.to_sym
+            @node_name = node_name.to_sym
+            @path = Array(path).map(&:to_sym).freeze
+            @status = status.to_sym
+            @payload = payload.freeze
+            freeze
+          end
+
+          def to_h
+            {
+              event_id: event_id,
+              type: type,
+              node_name: node_name,
+              path: path,
+              status: status,
+              payload: payload
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-extensions/lib/igniter/extensions/contracts/audit/snapshot.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Extensions
+    module Contracts
+      module Audit
+        class Snapshot
+          attr_reader :graph, :profile_fingerprint, :event_count, :events, :states, :children, :output_names
+
+          def initialize(graph:, profile_fingerprint:, events:, states:, children:, output_names:)
+            @graph = graph.to_s
+            @profile_fingerprint = profile_fingerprint
+            @events = events.freeze
+            @states = states.transform_keys(&:to_sym).freeze
+            @children = children.freeze
+            @output_names = output_names.map(&:to_sym).freeze
+            @event_count = @events.length
+            freeze
+          end
+
+          def event_types
+            events.map(&:type).uniq
+          end
+
+          def state(name)
+            states.fetch(name.to_sym)
+          end
+
+          def to_h
+            {
+              graph: graph,
+              profile_fingerprint: profile_fingerprint,
+              event_count: event_count,
+              output_names: output_names,
+              events: events.map(&:to_h),
+              states: states,
+              children: children
+            }
+          end
+        end
+      end
+    end
+  end
+end