Implement ephemeral integration branches for atomic promotion-group application

[ScottArbeit]

Implement the “ephemeral integration branch” behavior for promotion groups so that applying a promotion group to its parent branch is atomic, testable, and safe.

Right now, promotion groups and BranchPromotionMode are defined, but the actual orchestration logic that uses an ephemeral integration branch to apply promotions is not implemented. This issue is to design and implement that integration-branch workflow at the foundation level, without yet wiring in scheduling or advanced conflict-resolution policies.

Goals

• When a promotion group is executed:
  • Create an ephemeral integration branch off the target (parent) branch.
  • Apply the promotion group’s source branches (or commits) into that integration branch, following the rules of BranchPromotionMode and any existing policy hooks.
  • Detect success/failure at the integration-branch level:
    • If the integration branch applies cleanly and passes validation, fast-forward or merge the target branch from the integration branch atomically.
    • If there are failures (merge conflicts, validation failures, etc.), do not modify the target branch and persist an appropriate result/status.
  • Clean up the ephemeral integration branch (or flag it for debugging, depending on configuration).

The work here is branch orchestration and atomic application; detailed conflict-resolution policies and scheduling are covered in separate issues.

Requirements

1. Integration branch creation and naming

   • Define a deterministic and collision-resistant naming scheme for ephemeral integration branches (e.g. integration/{groupId}/{timestamp} or similar).
   • Integration branch must:
     • Be created from the current tip of the target branch.
     • Be clearly marked or tagged as ephemeral if your model supports such metadata.

2. Application of promotion groups

   • Given a promotion group definition (from the foundation PR), implement the workflow that:
     • Resolves which commits/branches are to be promoted.
     • Applies them onto the integration branch in the correct order, respecting BranchPromotionMode:
       • E.g. fast-forward-only vs. merge-commit vs. rebase, depending on what is already modeled in the PR branch.
     • Records any intermediate failures in a structured way (so the scheduler and conflict detection layers can consume it later).

3. Atomic apply to target branch

   • Only if integration succeeds:
     • Update the target branch from the integration branch atomically according to the promotion mode semantics (e.g., fast-forward if possible; merge otherwise).
   • Ensure there is a single, clearly-defined commit or set of commits that transition the target branch from pre-promotion → post-promotion state.
   • Ensure the operation is robust against concurrent updates (e.g., re-check the target branch tip before final apply; fail safely if it has moved and require a re-run).

4. Cleanup and observability

   • Implement a configurable policy for ephemeral branch cleanup:
     • Default: delete ephemeral integration branches after a successful promotion.
     • On failure: either preserve the branch (with clear naming) or record enough diagnostic data to make the failure debuggable.
   • Produce structured logging and/or events containing:
     • IDs of promotion group and target branch.
     • Integration branch name.
     • Result status (success, conflict, validation failure, etc.).
     • Timing information.

5. Domain model & contracts

   • If the current domain model for promotion groups does not fully express:
     • Target branch
     • Source branches/commits
     • Promotion mode
     • Execution status
       extend or refine it as needed, but keep changes minimal and aligned with the existing PR foundations.
   • Provide clear entry point(s) in the service/application layer that the scheduler and conflict-detection logic can call:
     • Example: IPromotionExecutor.RunPromotionGroup(groupId: PromotionGroupId, runId: PromotionRunId option) (signature is up to you, but should be explicit and testable).

6. Testing

   • Add unit and/or integration tests that cover at least:
     • Simple clean fast-forward promotion.
     • Non-fast-forward promotion that succeeds via merge (if supported by BranchPromotionMode).
     • Failure paths where:
       • A conflict arises during integration onto the ephemeral branch.
       • The target branch tip moves between integration and final apply (concurrency scenario).
   • Tests should assert that:
     • The target branch is updated only on successful integration.
     • The integration branch is created and cleaned up according to policy.
     • Statuses and logs are correctly produced.

Deliverables

• Implementation of the ephemeral integration branch orchestration logic for promotion groups, integrated with the existing promotion-group/BranchPromotionMode model introduced in PR Add promotion groups, BranchPromotionMode, and conflict-resolution policy (foundation) #28.
• Public service/API entry point(s) that the scheduler and conflict-detection components can call.
• Tests demonstrating:
  • Successful atomic promotions.
  • Correct handling of failures without corrupting the target branch.
  • Correct integration-branch lifecycle behavior.