igniter 0.5.1 → 0.5.2

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

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require "igniter/contracts"
+require "igniter/extensions/contracts"
+require "igniter-ai"
+require "igniter-agents"
+
+require_relative "application/config"
+require_relative "application/config_builder"
+require_relative "application/ai_provider_definition"
+require_relative "application/ai_builder"
+require_relative "application/ai_registry"
+require_relative "application/agent_definition"
+require_relative "application/agents_builder"
+require_relative "application/agent_runtime"
+require_relative "application/agent_registry"
+require_relative "application/missing_credential_error"
+require_relative "application/credential_definition"
+require_relative "application/credential_store"
+require_relative "application/application_layout"
+require_relative "application/application_manifest"
+require_relative "application/application_structure_entry"
+require_relative "application/application_structure_plan"
+require_relative "application/capsule_export"
+require_relative "application/capsule_import"
+require_relative "application/feature_slice"
+require_relative "application/feature_slice_report"
+require_relative "application/application_blueprint"
+require_relative "application/flow_event"
+require_relative "application/pending_input"
+require_relative "application/pending_action"
+require_relative "application/artifact_reference"
+require_relative "application/flow_declaration"
+require_relative "application/application_capsule_report"
+require_relative "application/capsule_builder"
+require_relative "application/application_composition_report"
+require_relative "application/mount_intent"
+require_relative "application/application_assembly_plan"
+require_relative "application/application_handoff_manifest"
+require_relative "application/application_transfer_inventory"
+require_relative "application/application_transfer_readiness"
+require_relative "application/application_transfer_bundle_plan"
+require_relative "application/application_transfer_bundle_artifact"
+require_relative "application/application_transfer_bundle_verification"
+require_relative "application/application_transfer_intake_plan"
+require_relative "application/application_transfer_apply_plan"
+require_relative "application/application_transfer_apply_result"
+require_relative "application/application_transfer_applied_verification"
+require_relative "application/application_transfer_receipt"
+require_relative "application/installed_capsule_entry"
+require_relative "application/file_backed_installed_capsule_registry"
+require_relative "application/application_host_activation_readiness"
+require_relative "application/application_host_activation_plan"
+require_relative "application/application_host_activation_plan_verification"
+require_relative "application/application_host_activation_dry_run_result"
+require_relative "application/application_host_activation_commit_readiness"
+require_relative "application/application_host_activation_operation_digest"
+require_relative "application/file_backed_host_activation_ledger_adapter"
+require_relative "application/application_host_activation_ledger_commit"
+require_relative "application/application_host_activation_ledger_verification"
+require_relative "application/application_host_activation_receipt"
+require_relative "application/flow_session_snapshot"
+require_relative "application/application_load_path"
+require_relative "application/application_load_report"
+require_relative "application/provider"
+require_relative "application/provider_registration"
+require_relative "application/provider_lifecycle_result"
+require_relative "application/provider_lifecycle_report"
+require_relative "application/service_definition"
+require_relative "application/interface"
+require_relative "application/service_registry"
+require_relative "application/contract_registry"
+require_relative "application/mount_registration"
+require_relative "application/transport_request"
+require_relative "application/transport_response"
+require_relative "application/compose_transport_adapter"
+require_relative "application/collection_transport_adapter"
+require_relative "application/compose_invoker"
+require_relative "application/collection_invoker"
+require_relative "application/session_entry"
+require_relative "application/memory_session_store"
+require_relative "application/boot_phase"
+require_relative "application/seam_lifecycle_result"
+require_relative "application/lifecycle_plan_step"
+require_relative "application/plan_executor"
+require_relative "application/embedded_host"
+require_relative "application/manual_loader"
+require_relative "application/manual_scheduler"
+require_relative "application/kernel"
+require_relative "application/profile"
+require_relative "application/snapshot"
+require_relative "application/boot_plan"
+require_relative "application/boot_report"
+require_relative "application/shutdown_plan"
+require_relative "application/shutdown_report"
+require_relative "application/environment"
+require_relative "application/rack_host"
+
+module Igniter
+  module Application
+    class << self
+      def build_kernel(*packs)
+        kernel = Kernel.new
+        packs.flatten.compact.each { |pack| kernel.install_pack(pack) }
+        kernel
+      end
+
+      def build_profile(*packs)
+        build_kernel(*packs).finalize
+      end
+
+      def with(*packs)
+        Environment.new(profile: build_profile(*packs))
+      end
+
+      def rack_app(name, root:, env: :development, metadata: {}, &block)
+        RackHost.build(name, root: root, env: env, metadata: metadata, &block)
+      end
+
+      def blueprint(...)
+        ApplicationBlueprint.new(...)
+      end
+
+      def capsule(name, root:, env: :development, &block)
+        CapsuleBuilder.build(name, root: root, env: env, &block)
+      end
+
+      def compose_capsules(*capsules, host_exports: [], host_capabilities: [], metadata: {})
+        ApplicationCompositionReport.inspect(
+          capsules: capsules.flatten,
+          host_exports: host_exports,
+          host_capabilities: host_capabilities,
+          metadata: metadata
+        )
+      end
+
+      def assemble_capsules(*capsules, host_exports: [], host_capabilities: [], mount_intents: [],
+                            surface_metadata: [], metadata: {})
+        ApplicationAssemblyPlan.build(
+          capsules: capsules.flatten,
+          host_exports: host_exports,
+          host_capabilities: host_capabilities,
+          mount_intents: mount_intents,
+          surface_metadata: surface_metadata,
+          metadata: metadata
+        )
+      end
+
+      def handoff_manifest(subject:, capsules: [], assembly_plan: nil, host_exports: [], host_capabilities: [],
+                           mount_intents: [], surface_metadata: [], metadata: {})
+        ApplicationHandoffManifest.build(
+          subject: subject,
+          capsules: capsules,
+          assembly_plan: assembly_plan,
+          host_exports: host_exports,
+          host_capabilities: host_capabilities,
+          mount_intents: mount_intents,
+          surface_metadata: surface_metadata,
+          metadata: metadata
+        )
+      end
+
+      def transfer_inventory(*capsules, surface_metadata: [], enumerate_files: true, metadata: {})
+        ApplicationTransferInventory.build(
+          capsules: capsules.flatten,
+          surface_metadata: surface_metadata,
+          enumerate_files: enumerate_files,
+          metadata: metadata
+        )
+      end
+
+      def transfer_readiness(*capsules, handoff_manifest: nil, transfer_inventory: nil, subject: :capsule_transfer,
+                             host_exports: [], host_capabilities: [], mount_intents: [], surface_metadata: [],
+                             enumerate_files: true, policy: {}, metadata: {})
+        ApplicationTransferReadiness.build(
+          handoff_manifest: handoff_manifest,
+          transfer_inventory: transfer_inventory,
+          capsules: capsules.flatten,
+          subject: subject,
+          host_exports: host_exports,
+          host_capabilities: host_capabilities,
+          mount_intents: mount_intents,
+          surface_metadata: surface_metadata,
+          enumerate_files: enumerate_files,
+          policy: policy,
+          metadata: metadata
+        )
+      end
+
+      def transfer_bundle_plan(*capsules, transfer_readiness: nil, handoff_manifest: nil, transfer_inventory: nil,
+                               subject: :capsule_transfer, host_exports: [], host_capabilities: [],
+                               mount_intents: [], surface_metadata: [], enumerate_files: true,
+                               readiness_policy: {}, policy: {}, metadata: {})
+        ApplicationTransferBundlePlan.build(
+          transfer_readiness: transfer_readiness,
+          handoff_manifest: handoff_manifest,
+          transfer_inventory: transfer_inventory,
+          capsules: capsules.flatten,
+          subject: subject,
+          host_exports: host_exports,
+          host_capabilities: host_capabilities,
+          mount_intents: mount_intents,
+          surface_metadata: surface_metadata,
+          enumerate_files: enumerate_files,
+          readiness_policy: readiness_policy,
+          policy: policy,
+          metadata: metadata
+        )
+      end
+
+      def write_transfer_bundle(plan, output:, allow_not_ready: false, create_parent: false, metadata: {})
+        ApplicationTransferBundleArtifact.write(
+          plan,
+          output: output,
+          allow_not_ready: allow_not_ready,
+          create_parent: create_parent,
+          metadata: metadata
+        )
+      end
+
+      def verify_transfer_bundle(path, metadata: {})
+        ApplicationTransferBundleVerification.verify(path, metadata: metadata)
+      end
+
+      def transfer_intake_plan(verification_or_path, destination_root:, metadata: {})
+        ApplicationTransferIntakePlan.build(
+          verification_or_path,
+          destination_root: destination_root,
+          metadata: metadata
+        )
+      end
+
+      def transfer_apply_plan(intake_plan, metadata: {})
+        ApplicationTransferApplyPlan.build(intake_plan, metadata: metadata)
+      end
+
+      def apply_transfer_plan(apply_plan, commit: false, metadata: {})
+        ApplicationTransferApplyResult.apply(
+          apply_plan,
+          commit: commit,
+          metadata: metadata
+        )
+      end
+
+      def verify_applied_transfer(apply_result, apply_plan: nil, metadata: {})
+        ApplicationTransferAppliedVerification.verify(
+          apply_result,
+          apply_plan: apply_plan,
+          metadata: metadata
+        )
+      end
+
+      def transfer_receipt(applied_verification, apply_result: nil, apply_plan: nil, metadata: {})
+        ApplicationTransferReceipt.build(
+          applied_verification,
+          apply_result: apply_result,
+          apply_plan: apply_plan,
+          metadata: metadata
+        )
+      end
+
+      def file_backed_installed_capsule_registry(root:)
+        FileBackedInstalledCapsuleRegistry.build(root: root)
+      end
+
+      def record_installed_capsule(name, receipt:, registry:, source: nil, version: nil, metadata: {})
+        registry.record(
+          name,
+          receipt: receipt,
+          source: source,
+          version: version,
+          metadata: metadata
+        )
+      end
+
+      def host_activation_readiness(transfer_receipt, handoff_manifest: nil, host_exports: [], host_capabilities: [],
+                                    manual_actions: [], load_paths: [], providers: [], contracts: [], lifecycle: {},
+                                    mount_decisions: [], surface_metadata: [], metadata: {})
+        ApplicationHostActivationReadiness.build(
+          transfer_receipt,
+          handoff_manifest: handoff_manifest,
+          host_exports: host_exports,
+          host_capabilities: host_capabilities,
+          manual_actions: manual_actions,
+          load_paths: load_paths,
+          providers: providers,
+          contracts: contracts,
+          lifecycle: lifecycle,
+          mount_decisions: mount_decisions,
+          surface_metadata: surface_metadata,
+          metadata: metadata
+        )
+      end
+
+      def host_activation_plan(readiness, metadata: {})
+        ApplicationHostActivationPlan.build(readiness, metadata: metadata)
+      end
+
+      def verify_host_activation_plan(plan, metadata: {})
+        ApplicationHostActivationPlanVerification.verify(plan, metadata: metadata)
+      end
+
+      def dry_run_host_activation(verification, host_target: nil, metadata: {})
+        ApplicationHostActivationDryRunResult.dry_run(
+          verification,
+          host_target: host_target,
+          metadata: metadata
+        )
+      end
+
+      def host_activation_commit_readiness(dry_run, provided_adapters: [], metadata: {})
+        ApplicationHostActivationCommitReadiness.build(
+          dry_run,
+          provided_adapters: provided_adapters,
+          metadata: metadata
+        )
+      end
+
+      def host_activation_operation_digest(dry_run)
+        ApplicationHostActivationOperationDigest.compute(dry_run)
+      end
+
+      def file_backed_host_activation_ledger_adapter(root:, name: :file_backed_host_activation_ledger)
+        FileBackedHostActivationLedgerAdapter.build(root: root, name: name)
+      end
+
+      def host_activation_ledger_commit(evidence_packet, adapter:, metadata: {})
+        ApplicationHostActivationLedgerCommit.commit(
+          evidence_packet,
+          adapter: adapter,
+          metadata: metadata
+        )
+      end
+
+      def verify_host_activation_ledger(evidence_packet, commit_result:, adapter:, metadata: {})
+        ApplicationHostActivationLedgerVerification.verify(
+          evidence_packet,
+          commit_result: commit_result,
+          adapter: adapter,
+          metadata: metadata
+        )
+      end
+
+      def host_activation_receipt(verification, evidence_packet:, commit_result:, metadata: {})
+        ApplicationHostActivationReceipt.build(
+          verification,
+          evidence_packet: evidence_packet,
+          commit_result: commit_result,
+          metadata: metadata
+        )
+      end
+    end
+  end
+end

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

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

data/packages/igniter-cluster/README.md

@@ -1,9 +1,116 @@
 # igniter-cluster
 
-Local monorepo gem for Igniter's cluster, mesh, trust, and replication layer.
+Clean-slate contracts-native distributed runtime for Igniter.
 
-Docs:
+This package is intentionally separate from the archived cluster package.
 
-- [Guide](../../docs/guide/README.md)
-- [Cluster guide](../../docs/guide/cluster.md)
-- [Dev](../../docs/dev/README.md)
+- `igniter-cluster` is the new target package for distributed execution
+- `packages/archive/igniter-cluster` remains reference-only until deletion
+
+Primary entrypoints:
+
+- `require "igniter-cluster"`
+- `require "igniter/cluster"`
+
+Primary API:
+
+- `Igniter::Cluster.build_kernel`
+- `Igniter::Cluster.build_profile`
+- `Igniter::Cluster.with`
+- `Igniter::Cluster::Kernel`
+- `Igniter::Cluster::Profile`
+- `Igniter::Cluster::Environment`
+- `Igniter::Cluster::PlanExecutor`
+- `Igniter::Cluster::MeshExecutor`
+- `Igniter::Cluster::RemediationPolicy`
+- `Igniter::Cluster::MeshMembership`
+- `Igniter::Cluster::MeshMembershipSource`
+- `Igniter::Cluster::RegistryMembershipSource`
+- `Igniter::Cluster::PeerDiscovery`
+- `Igniter::Cluster::MeshRetryPolicy`
+- `Igniter::Cluster::MeshTrustPolicy`
+- `Igniter::Cluster::MeshAdmission`
+
+The first active slice is intentionally narrow:
+
+- explicit `PeerProfile` identity model over name/capabilities/roles/labels
+- explicit `PeerTopology` model for region/zone/labels locality
+- richer `CapabilityQuery` intent over capabilities, traits, labels, region,
+  and zone
+- explicit `TopologyPolicy` and `RebalancePlan` for movement/rebalancing
+  semantics
+- explicit `OwnershipPolicy` and `OwnershipPlan` for workload/entity ownership
+  planning
+- explicit `LeasePolicy` and `LeasePlan` for TTL/renewal-aware coordination
+  planning
+- explicit `HealthPolicy` and `FailoverPlan` for degraded/failure transition
+  planning
+- explicit `RemediationPolicy` and `RemediationPlan` for response workflows over
+  active incidents
+- explicit cluster plan execution reports over rebalance/ownership/lease/failover
+- explicit mesh execution requests, attempts, traces, and responses over cluster plans
+- explicit mesh membership, discovery, and retry/fallback policy over peer execution
+- explicit mesh trust/admission decisions and membership sources
+- explicit `Peer` registry
+- explicit `placement` seam
+- declarative `PlacementPolicy` default
+- declarative `RoutePolicy` and `AdmissionPolicy` defaults
+- raw `router` and `admission` seams as low-level escape hatches
+- raw `placement` seam as a low-level escape hatch
+- explicit `transport` seam
+- cluster-owned `compose_invoker`
+- cluster-owned `collection_invoker`
+
+The current implementation builds on `Igniter::Application::TransportRequest`
+and `TransportResponse`, so the distributed path can grow without redesigning
+contracts DSL or application session semantics.
+
+Cluster planning can now be executed explicitly too:
+
+- `Environment#execute_plan`
+- `Environment#execute_rebalance_plan`
+- `Environment#execute_ownership_plan`
+- `Environment#execute_lease_plan`
+- `Environment#execute_failover_plan`
+
+By default these produce explicit simulated execution reports, leaving room for
+future real handlers without changing the plan shapes.
+
+Runnable illustrations live in `examples/cluster/`:
+
+- `routing.rb` for capability-aware remote compose
+- `incidents.rb` for durable incident history and active incident state
+- `incident_workflow.rb` for acknowledge/assign/silence/resolve workflow actions
+- `mesh_diagnostics.rb` for retry traces, projection reports, and operator-facing diagnostics
+- `remediation.rb` for turning active incidents into executable response steps
+
+Mesh-oriented execution now has a first dedicated adapter layer too:
+
+- `Environment#mesh_executor`
+- `Environment#execute_plan_via_mesh`
+- `MeshExecutionRequest`
+- `MeshExecutionResponse`
+- `MeshExecutionAttempt`
+- `MeshExecutionTrace`
+
+This keeps mesh behavior above plan semantics: the same cluster plans can be
+executed locally, simulated, or routed through mesh-aware peer transports.
+
+Mesh execution is now membership-aware:
+
+- `MeshMembership` snapshots available peers
+- `PeerDiscovery` derives ordered candidate peers for a plan action
+- `MeshRetryPolicy` controls retry/fallback across candidates
+
+That gives mesh execution a real multi-attempt trace without baking discovery
+or retry semantics into the plans themselves.
+
+Mesh execution is now trust-aware too:
+
+- `MeshMembershipSource` controls where membership snapshots come from
+- `MeshTrustPolicy` expresses trust constraints over roles, labels, and metadata
+- `MeshAdmission` records which peers were denied before execution
+
+So mesh traces can now answer both:
+- who we tried
+- who we refused to try, and why

data/packages/igniter-cluster/lib/igniter/cluster/active_incident_set.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class ActiveIncidentSet
+      attr_reader :entries, :metadata
+
+      def initialize(entries:, metadata: {})
+        @entries = Array(entries).sort_by(&:sequence).freeze
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def empty?
+        entries.empty?
+      end
+
+      def count
+        entries.length
+      end
+
+      def incident_keys
+        entries.map(&:incident_key).freeze
+      end
+
+      def incidents
+        entries.map(&:incident).freeze
+      end
+
+      def to_h
+        {
+          count: count,
+          incident_keys: incident_keys,
+          entries: entries.map(&:to_h),
+          metadata: metadata.dup
+        }
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/admission_policy.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    class AdmissionPolicy
+      attr_reader :name, :allowed_peers, :blocked_peers, :required_query_capabilities,
+                  :required_route_capabilities, :allow_empty_query, :metadata
+
+      def initialize(name:, allowed_peers: nil, blocked_peers: [], required_query_capabilities: [],
+                     required_route_capabilities: [], allow_empty_query: true, metadata: {})
+        @name = name.to_sym
+        @allowed_peers = normalize_optional_names(allowed_peers)
+        @blocked_peers = normalize_names(blocked_peers)
+        @required_query_capabilities = normalize_names(required_query_capabilities)
+        @required_route_capabilities = normalize_names(required_route_capabilities)
+        @allow_empty_query = allow_empty_query == true
+        @metadata = metadata.dup.freeze
+        freeze
+      end
+
+      def self.permissive(metadata: {})
+        new(name: :permissive, metadata: metadata)
+      end
+
+      def admit(request:, route:)
+        return denied_empty_query(request) if !allow_empty_query && request.query.empty?
+        return denied_blocked_peer(request, route) if blocked_peers.include?(route.peer.name)
+        return denied_unlisted_peer(request, route) unless allowed_peer?(route.peer.name)
+        return denied_query_capabilities(request, route) unless query_capabilities_allowed?(request.query)
+        return denied_route_capabilities(request, route) unless route_capabilities_allowed?(route.peer)
+
+        accepted_code, accepted_message = accepted_reason_for(request)
+        AdmissionResult.allowed(
+          code: :accepted,
+          metadata: result_metadata(request, route),
+          reason: DecisionExplanation.new(
+            code: accepted_code,
+            message: accepted_message,
+            metadata: result_metadata(request, route)
+          )
+        )
+      end
+
+      def to_h
+        {
+          name: name,
+          allowed_peers: allowed_peers&.dup,
+          blocked_peers: blocked_peers.dup,
+          required_query_capabilities: required_query_capabilities.dup,
+          required_route_capabilities: required_route_capabilities.dup,
+          allow_empty_query: allow_empty_query,
+          metadata: metadata.dup
+        }
+      end
+
+      private
+
+      def normalize_names(values)
+        Array(values).map(&:to_sym).uniq.sort.freeze
+      end
+
+      def normalize_optional_names(values)
+        return nil if values.nil?
+
+        normalize_names(values)
+      end
+
+      def allowed_peer?(peer_name)
+        return true if allowed_peers.nil?
+
+        allowed_peers.include?(peer_name)
+      end
+
+      def query_capabilities_allowed?(query)
+        required_query_capabilities.all? do |capability|
+          query.required_capabilities.include?(capability)
+        end
+      end
+
+      def route_capabilities_allowed?(peer)
+        peer.supports_capabilities?(required_route_capabilities)
+      end
+
+      def denied_empty_query(request)
+        denied_result(
+          request,
+          code: :empty_query_denied,
+          message: "admission policy #{name} rejected empty query"
+        )
+      end
+
+      def denied_blocked_peer(request, route)
+        denied_result(
+          request,
+          route: route,
+          code: :blocked_peer,
+          message: "admission policy #{name} blocked peer #{route.peer.name}"
+        )
+      end
+
+      def denied_unlisted_peer(request, route)
+        denied_result(
+          request,
+          route: route,
+          code: :unlisted_peer,
+          message: "admission policy #{name} rejected peer #{route.peer.name}"
+        )
+      end
+
+      def denied_query_capabilities(request, route)
+        denied_result(
+          request,
+          route: route,
+          code: :missing_query_capabilities,
+          message: "admission policy #{name} requires query capabilities #{required_query_capabilities.inspect}"
+        )
+      end
+
+      def denied_route_capabilities(request, route)
+        denied_result(
+          request,
+          route: route,
+          code: :missing_route_capabilities,
+          message: "admission policy #{name} requires route capabilities #{required_route_capabilities.inspect}"
+        )
+      end
+
+      def denied_result(request, code:, message:, route: nil)
+        details = result_metadata(request, route)
+        AdmissionResult.denied(
+          code: code,
+          metadata: details,
+          reason: DecisionExplanation.new(
+            code: code,
+            message: message,
+            metadata: details
+          )
+        )
+      end
+
+      def accepted_reason_for(request)
+        return [:permissive_accept, "permissive admission accepted #{request.session_id}"] if name == :permissive
+
+        [:policy_accept, "admission policy #{name} accepted #{request.session_id}"]
+      end
+
+      def result_metadata(request, route)
+        {
+          policy: name,
+          session_id: request.session_id,
+          peer: route&.peer&.name,
+          peer_view: route&.peer_view&.to_h,
+          peer_profile: route&.peer&.profile&.to_h
+        }.compact
+      end
+    end
+  end
+end