feat(yes-core): add command_group DSL to aggregate

[ncri]

Summary

Adds a command_group :name do … end macro to Yes::Core::Aggregate, mirroring how command works. The macro produces a single callable on the aggregate that runs several existing aggregate commands as one atomic, transactionally-published unit — with its own, leaner guard set and the sub-command guards fully bypassed.

command_group :create_apprenticeship do
  command :assign_company
  command :assign_user
  command :change_name
  command :change_description
  command :publish

  guard(:company_assigned) { payload.company_id.present? }
end

aggregate.create_apprenticeship(company_id:, user_id:, name:, description:)
# => Yes::Core::Commands::CommandGroupResponse(cmd:, events: [...], error: nil)

How it runs

• All sub-events publish inside a single PgEventstore.client.multiple block at SERIALIZABLE isolation — atomic by transaction, with pg_eventstore retrying SSI conflicts transparently.
• First sub-event publishes via EventPublisher, getting both:
  • own-stream expected_revision = read_model.revision optimistic locking, and
  • external-aggregate revision verification via the AggregateTracker populated by the group's GuardEvaluator (covers attribute :foo, :aggregate access inside guards and payload-resolved aggregates via PayloadProxy).
    Drift on either surfaces as WrongExpectedRevisionError → the executor's outer rescue retries → guards re-evaluate against fresh state.
• Subsequent sub-events use expected_revision: :any; revision sequencing comes for free inside the same multiple transaction.
• Read-model updates run after the eventstore commit, in declaration order, so each sub-command's state-updater sees the cumulative state produced by the previous ones.
• set_pending_update_state provides the read-model-side mutex (same mechanism as per-command commands).

Scope

• Single-aggregate groups only. Cross-aggregate groups continue to use the legacy stateless Yes::Core::Commands::Group / GroupHandler, which are untouched. The shared infrastructure (CommandGroup, CommandGroupResponse, executor patterns) was designed to keep the cross-aggregate top-level form (planned future addition in app/command_groups/) an incremental layer.
• Sub-command guards (including the auto-injected :no_change and the :not_removed aggregate auto-block) are fully bypassed when running the group.
• No envelope event is emitted for the group itself — only the sub-commands' existing events.

Generated artifacts (per command_group :foo)

Class / Method	Namespace
Command	Context::Aggregate::CommandGroups::Foo::Command (subclass of Yes::Core::Commands::CommandGroup)
GuardEvaluator	Context::Aggregate::CommandGroups::Foo::GuardEvaluator (subclass of Yes::Core::CommandHandling::GuardEvaluator)
Aggregate#foo(payload, guards:, metadata:)	invocation method
Aggregate#can_foo?(payload)	guards-only predicate
Aggregate#foo_error	error accessor mirroring per-command pattern

Sub-command symbols are resolved lazily, so the group can be declared before or after the individual commands. A TracePoint(:end) hook on the subclass validates all referenced sub-commands exist at end of class body.

Test DSL

command_group 'name' do … end block with success_group, invalid_group, no_change_group helpers, plus three new shared examples mirroring the per-command DSL. Draft mode supported via draft: true.

Commits

1. refactor — Extract GroupPayloadNormalizer so the legacy stateless Group and the new CommandGroup share the three-form payload normalization (flat / subject-nested / context-nested).
2. feat — command_group DSL: data + definer, class resolvers, method definers, configuration + command_utils helpers, Aggregate.command_group macro, CommandGroupHandler + CommandGroupExecutor, test DSL extension, integration + unit specs.
3. docs — Add Command Groups section and Command Group Test DSL section to the main README, with ToC updates.

Test plan

• bundle exec rspec from yes-core/ — full suite green: 1159 examples, 0 failures (44 new examples across 6 new spec files).
• bundle exec rubocop from the umbrella repo on all touched files — 0 offenses.
• Concurrency hardening tests in command_group_executor_spec.rb cover:
  • first sub-event routed through EventPublisher with accessed_external_aggregates,
  • subsequent events sequence as stream revisions 0, 1, 2,
  • simulated stale snapshot triggers retry and eventually succeeds,
  • persistent failure exhausts MAX_RETRIES and re-raises,
  • GuardEvaluator is reconstructed on each retry (proves guards re-evaluate).
• Integration spec (command_group_handler_spec.rb) hits real PG eventstore + AR read model: happy path, group-guard failure, sub-command guard bypass, read-model cumulative state, can_<group_name>? predicate.

Known follow-ups (not part of this PR)

• Outer ActiveRecord::Base.transaction around the read-model update loop, to rollback partial application on a per-sub failure.
• Top-level app/command_groups/ form for cross-aggregate groups.
• Group-level authorize do … end block.
• Dispatcher-side entry point so groups can be enqueued.
• AggregateTracker coverage gaps for direct AR queries and manually-constructed aggregates inside guard blocks — these exist for the per-command flow too and warrant a separate workstream.