Add factory registry and config-driven task binding

- Introduce TaskFactoryRegistry with typed descriptors for declarative factory_key resolution
- Add factory_binding module to bind config-derived child specs to runtime factories
- Add factory_schema module for schema generation from registry metadata
- Wire factory lookup into child spec building and validation
- Update runtime supervisor and control loop to use resolved factories
- Add integration test for factory-bound add_child transaction

Author: developerworks

examples/split_config_supervisor.rs

@@ -3,23 +3,33 @@
 
 use rust_supervisor::config::loader::load_config_from_yaml_file;
 
+// Define the example result type used by the split configuration demo.
 type ExampleResult = Result<(), rust_supervisor::error::types::SupervisorError>;
 
 /// Loads the split example config and prints derived child and group counts.
 fn main() -> ExampleResult {
+    // Load the split configuration through the public YAML loader.
     let state = load_config_from_yaml_file("examples/config/split/supervisor.yaml")?;
 
+    // Print the selected root supervision strategy.
     println!("strategy: {:?}", state.supervisor.strategy);
+    // Print the number of configured groups.
     println!("groups: {}", state.groups.len());
+    // Print the number of configured children.
     println!("children: {}", state.children.len());
 
+    // Print every configured group name.
     for group in &state.groups {
+        // Print the current group name.
         println!("  group: {}", group.name);
     }
 
+    // Print every configured child name.
     for child in &state.children {
+        // Print the current child name.
         println!("  child: {}", child.name);
     }
 
+    // Return success after the split configuration summary is printed.
     Ok(())
 }

src/config/factory_binding.rs

@@ -0,0 +1,119 @@
+//! Factory binding from configuration keys to runtime child specs.
+//!
+//! The functions in this module keep executable task factories out of raw YAML
+//! loading while still providing a single startup-time binding step.
+
+use crate::error::types::SupervisorError;
+use crate::spec::child::{ChildSpec, TaskKind};
+use crate::task::factory_registry::TaskFactoryRegistry;
+
+/// Binds all worker child factory keys to executable task factories.
+///
+/// # Arguments
+///
+/// - `children`: Child specifications converted from configuration.
+/// - `registry`: Registry that owns the executable factories.
+///
+/// # Returns
+///
+/// Returns `Ok(())` when every worker child has a usable factory.
+///
+/// # Errors
+///
+/// Returns [`SupervisorError`] when a worker is missing `factory_key`, a key is
+/// unknown, a key does not support the declared task kind, or a supervisor child
+/// declares a factory key.
+///
+/// # Examples
+///
+/// ```
+/// use rust_supervisor::config::factory_binding::bind_task_factories;
+/// use rust_supervisor::id::types::ChildId;
+/// use rust_supervisor::spec::child_builder::ChildSpecBuilder;
+/// use rust_supervisor::task::factory::{TaskResult, service_fn};
+/// use rust_supervisor::task::factory_registry::{
+///     TaskFactoryDescriptor, TaskFactoryRegistry,
+/// };
+/// use rust_supervisor::spec::child::TaskKind;
+/// use std::sync::Arc;
+///
+/// # fn example() -> Result<(), rust_supervisor::error::types::SupervisorError> {
+/// let mut registry = TaskFactoryRegistry::new();
+/// registry.register(TaskFactoryDescriptor::new(
+///     "worker",
+///     "Worker",
+///     "Runs one worker.",
+///     [TaskKind::AsyncWorker],
+///     Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded })),
+/// ))?;
+/// let child = ChildSpecBuilder::new(ChildId::new("worker"), "worker")
+///     .kind(TaskKind::AsyncWorker)
+///     .factory_key("worker")
+///     .factory(Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded })))
+///     .build()?;
+/// let mut children = vec![child];
+/// bind_task_factories(&mut children, &registry)?;
+/// assert!(children[0].factory.is_some());
+/// # Ok(())
+/// # }
+/// ```
+pub fn bind_task_factories(
+    children: &mut [ChildSpec],
+    registry: &TaskFactoryRegistry,
+) -> Result<(), SupervisorError> {
+    for child in children {
+        bind_child_factory(child, registry)?;
+    }
+    Ok(())
+}
+
+/// Binds one child factory key to an executable task factory.
+///
+/// # Arguments
+///
+/// - `child`: Child specification converted from configuration.
+/// - `registry`: Registry that owns executable task factories.
+///
+/// # Returns
+///
+/// Returns `Ok(())` after the child has a valid factory assignment or does not
+/// require one.
+///
+/// # Errors
+///
+/// Returns [`SupervisorError`] when the child factory declaration is invalid.
+pub fn bind_child_factory(
+    child: &mut ChildSpec,
+    registry: &TaskFactoryRegistry,
+) -> Result<(), SupervisorError> {
+    match child.kind {
+        TaskKind::AsyncWorker | TaskKind::BlockingWorker => {
+            let key = child
+                .factory_key
+                .as_deref()
+                .filter(|key| !key.trim().is_empty())
+                .ok_or_else(|| {
+                    SupervisorError::fatal_config(format!(
+                        "worker child '{}' requires factory_key",
+                        child.id
+                    ))
+                })?;
+            child.factory = Some(registry.resolve(key, child.kind)?);
+            Ok(())
+        }
+        TaskKind::Supervisor => {
+            if child
+                .factory_key
+                .as_deref()
+                .is_some_and(|key| !key.trim().is_empty())
+            {
+                return Err(SupervisorError::fatal_config(format!(
+                    "supervisor child '{}' must not declare factory_key",
+                    child.id
+                )));
+            }
+            child.factory = None;
+            Ok(())
+        }
+    }
+}

src/config/factory_schema.rs

@@ -0,0 +1,119 @@
+//! JSON Schema completion support for declarative task factories.
+//!
+//! This module enriches the generated supervisor configuration schema with
+//! `factory_key` values from the caller-provided task factory registry.
+
+use crate::config::configurable::SupervisorConfig;
+use crate::error::types::SupervisorError;
+use crate::task::factory_registry::TaskFactoryRegistry;
+use serde_json::{Value, json};
+
+/// Builds a supervisor configuration schema with `factory_key` completion values.
+///
+/// # Arguments
+///
+/// - `registry`: Task factory registry that supplies valid completion keys.
+///
+/// # Returns
+///
+/// Returns a JSON Schema value whose `ChildDeclaration.factory_key` field
+/// contains registry-backed completion candidates.
+///
+/// # Errors
+///
+/// Returns [`SupervisorError`] when the generated schema does not expose the
+/// expected `ChildDeclaration.factory_key` property.
+///
+/// # Examples
+///
+/// ```
+/// use rust_supervisor::config::factory_schema::supervisor_schema_with_factory_registry;
+/// use rust_supervisor::spec::child::TaskKind;
+/// use rust_supervisor::task::factory::{TaskResult, service_fn};
+/// use rust_supervisor::task::factory_registry::{
+///     TaskFactoryDescriptor, TaskFactoryRegistry,
+/// };
+/// use std::sync::Arc;
+///
+/// # fn example() -> Result<(), rust_supervisor::error::types::SupervisorError> {
+/// let mut registry = TaskFactoryRegistry::new();
+/// registry.register(TaskFactoryDescriptor::new(
+///     "worker",
+///     "Worker",
+///     "Runs one worker.",
+///     [TaskKind::AsyncWorker],
+///     Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded })),
+/// ))?;
+/// let schema = supervisor_schema_with_factory_registry(&registry)?;
+/// let schema_text = serde_json::to_string(&schema).unwrap();
+/// assert!(schema_text.contains("worker"));
+/// # Ok(())
+/// # }
+/// ```
+pub fn supervisor_schema_with_factory_registry(
+    registry: &TaskFactoryRegistry,
+) -> Result<Value, SupervisorError> {
+    let schema = schemars::schema_for!(SupervisorConfig);
+    let mut value = serde_json::to_value(&schema).map_err(|error| {
+        SupervisorError::fatal_config(format!("failed to serialize supervisor schema: {error}"))
+    })?;
+    inject_factory_key_completions(&mut value, registry)?;
+    Ok(value)
+}
+
+/// Injects registry-backed completion values into an existing schema.
+///
+/// # Arguments
+///
+/// - `schema`: Schema value generated from [`SupervisorConfig`].
+/// - `registry`: Task factory registry that supplies valid completion keys.
+///
+/// # Returns
+///
+/// Returns `Ok(())` after completion candidates have been injected.
+///
+/// # Errors
+///
+/// Returns [`SupervisorError`] when the schema does not expose the expected
+/// `ChildDeclaration.factory_key` property.
+pub fn inject_factory_key_completions(
+    schema: &mut Value,
+    registry: &TaskFactoryRegistry,
+) -> Result<(), SupervisorError> {
+    let pointer = if schema
+        .pointer("/definitions/ChildDeclaration/properties/factory_key")
+        .is_some()
+    {
+        "/definitions/ChildDeclaration/properties/factory_key"
+    } else if schema
+        .pointer("/$defs/ChildDeclaration/properties/factory_key")
+        .is_some()
+    {
+        "/$defs/ChildDeclaration/properties/factory_key"
+    } else {
+        return Err(SupervisorError::fatal_config(
+            "supervisor schema is missing ChildDeclaration.factory_key",
+        ));
+    };
+    let factory_key_schema = schema.pointer_mut(pointer).ok_or_else(|| {
+        SupervisorError::fatal_config("supervisor schema is missing ChildDeclaration.factory_key")
+    })?;
+
+    let choices = registry
+        .descriptors()
+        .into_iter()
+        .map(|descriptor| {
+            json!({
+                "const": descriptor.key,
+                "title": descriptor.title,
+                "description": descriptor.description,
+            })
+        })
+        .collect::<Vec<_>>();
+
+    factory_key_schema["oneOf"] = Value::Array(choices);
+    factory_key_schema["description"] = Value::String(
+        "TaskFactory registry key used to bind worker children before startup.".to_owned(),
+    );
+    Ok(())
+}

src/config/mod.rs

@@ -1,5 +1,7 @@
 pub mod audit;
 pub mod configurable;
+pub mod factory_binding;
+pub mod factory_schema;
 pub mod ipc_security;
 pub mod loader;
 pub mod policy;

src/config/policy.rs

@@ -322,22 +322,26 @@ pub struct GroupsConfigSection {
 }
 
 impl Default for GroupsConfigSection {
+    /// Returns an empty group configuration section.
     fn default() -> Self {
         Self { items: Vec::new() }
     }
 }
 
 impl JsonSchema for GroupsConfigSection {
+    /// Returns the schema name used for split group sections.
     fn schema_name() -> Cow<'static, str> {
         Cow::Borrowed("GroupsConfigSection")
     }
 
+    /// Returns the transparent array schema for group declarations.
     fn json_schema(generator: &mut SchemaGenerator) -> Schema {
         Vec::<GroupConfig>::json_schema(generator)
     }
 }
 
 impl Serialize for GroupsConfigSection {
+    /// Serializes group section entries as a transparent array.
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: confique::serde::Serializer,
@@ -347,6 +351,7 @@ impl Serialize for GroupsConfigSection {
 }
 
 impl<'de> Deserialize<'de> for GroupsConfigSection {
+    /// Deserializes group section entries from a transparent array.
     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
     where
         D: confique::serde::Deserializer<'de>,
@@ -375,6 +380,7 @@ impl GroupsConfigSection {
 }
 
 impl From<GroupsConfigSection> for Vec<GroupConfig> {
+    /// Converts a group section into its transparent entry vector.
     fn from(section: GroupsConfigSection) -> Self {
         section.items
     }

src/config/state.rs

@@ -388,6 +388,46 @@ impl ConfigState {
     pub fn to_supervisor_spec(
         &self,
     ) -> Result<crate::spec::supervisor::SupervisorSpec, crate::error::types::SupervisorError> {
+        let spec = self.build_supervisor_spec();
+        spec.validate()?;
+        Ok(spec)
+    }
+
+    /// Converts validated configuration into a supervisor declaration and binds factories.
+    ///
+    /// # Arguments
+    ///
+    /// - `registry`: Task factory registry used to resolve worker `factory_key` values.
+    ///
+    /// # Returns
+    ///
+    /// Returns a [`crate::spec::supervisor::SupervisorSpec`] with executable
+    /// task factories assigned to worker children.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`crate::error::types::SupervisorError`] when factory binding or
+    /// supervisor validation fails.
+    pub fn to_supervisor_spec_with_factories(
+        &self,
+        registry: &crate::task::factory_registry::TaskFactoryRegistry,
+    ) -> Result<crate::spec::supervisor::SupervisorSpec, crate::error::types::SupervisorError> {
+        let mut spec = self.build_supervisor_spec();
+        crate::config::factory_binding::bind_task_factories(&mut spec.children, registry)?;
+        spec.validate()?;
+        Ok(spec)
+    }
+
+    /// Builds a supervisor specification before final validation.
+    ///
+    /// # Arguments
+    ///
+    /// This function has no arguments.
+    ///
+    /// # Returns
+    ///
+    /// Returns a supervisor specification assembled from validated config state.
+    fn build_supervisor_spec(&self) -> crate::spec::supervisor::SupervisorSpec {
         let mut spec = crate::spec::supervisor::SupervisorSpec::root(self.children.clone());
         spec.strategy = self.supervisor.strategy;
         spec.config_version = self.config_version();
@@ -454,8 +494,7 @@ impl ConfigState {
         ));
         spec.metrics_enabled = self.observability.metrics_enabled;
         spec.audit_enabled = self.observability.audit_enabled;
-        spec.validate()?;
-        Ok(spec)
+        spec
     }
 
     /// Builds a stable configuration version string from configured values.