Implement nesting in system groups

[waynemwashuma]

Objective

Introduce hierarchical system groups with inherited ordering constraints in the scheduler.

This adds support for nested system groups, allowing child groups to inherit ordering relationships from parent groups while preserving schedule isolation and cycle safety.

Solution

The scheduler previously treated system groups as flat structures. Ordering constraints applied only to the systems directly registered inside a group, making it difficult to model layered execution phases or reusable scheduling hierarchies.

This introduces explicit parent-child relationships between system groups and expands ordering resolution across descendants.

What changed

• Added parent support to SystemGroupConfig
• Added parentId tracking during scheduler build
• Introduced group hierarchy resolution before graph construction
• Expanded group ordering edges to include descendant systems recursively
• Added validation for:
  • missing parent groups
  • cyclic group nesting

Why this approach

Instead of flattening groups eagerly during registration, hierarchy resolution is deferred until schedule construction. This keeps registration lightweight while enabling:

• recursive inheritance of ordering constraints
• validation of complete hierarchy graphs
• efficient expansion through caching
• future extensibility for deeper scheduling features

Recursive expansion also ensures that ordering rules defined on high-level phases automatically propagate to deeply nested descendants.

Showcase

Before

builder.addGroup({
  label: RootPhase,
  schedule: 'update',
  before: [tail]
})

builder.addGroup({
  label: NestedPhase,
  schedule: 'update'
})

builder.add({
  systemGroup: NestedPhase,
  system: nested
})

nested was not affected by RootPhase ordering constraints.

After

builder.addGroup({
  label: RootPhase,
  schedule: 'update',
  before: [tail]
})

builder.addGroup({
  label: NestedPhase,
  parent: RootPhase,
  schedule: 'update'
})

builder.add({
  systemGroup: NestedPhase,
  system: nested
})

nested now inherits the ordering constraints from RootPhase.

Migration guide

No migration required.

Notes

• Parent groups must be explicitly registered before scheduler build
• Cyclic group nesting throws during scheduler construction
• Existing flat group configurations continue to work unchanged

Checklist

• I have updated the documentation accordingly.
• I have added tests to cover my changes.