# TASK 3: Expose Replay Launch Seams For Operators And Internal Jobs

## Summary

Expose a stable replay entry seam so replay execution is callable by internal jobs and, where appropriate, by manual operational tooling. This task turns the replay coordinator into an actionable recovery interface.

## Current Codebase Findings

- Current API-service orchestration already has a pattern for manual ETL launch in `BrinkPosEtlJobs` and related endpoints.
- No KDS CDC replay command, endpoint, or job entrypoint was found during branch audit.
- Current KDS CDC replay service is lookup-only and not operator-callable for execution.

Current repo constraints this task must respect:

1. Replay entry should be explicit and auditable.
2. Replay entry must require bounded parameters, not open-ended "replay everything" behavior.
3. Manual replay should reuse the same replay planner/coordinator used by any internal job path.

## Dependencies

- [TASK 1](./TASK1.md)
- [TASK 2](./TASK2.md)

## Source References

- `../../docs/features/ETL/kds-cdc/index.md#checkpointing-and-replay`
- `../../docs/features/ETL/kds-cdc/index.md#quarantine-and-failed-packages`
- `../../docs/features/ETL/kds-cdc/branch-audit.md`

## Files to Create

1. Replay launch seam under `backend/Kds.Ai.ApiService/Jobs/KdsCdc/` or adjacent orchestration location:
   - `KdsCdcReplayJobs.cs`
   - optional request DTOs for manual/internal replay inputs

   Responsibilities:
   - validate operator/internal input shape,
   - invoke replay planner and coordinator,
   - log/audit replay trigger and outcome.

2. Optional endpoint or internal service seam if repo patterns justify it:
   - endpoint under API service for manual replay
   - internal service or command handler for non-HTTP invocation

   Guidance:
   - follow existing repo orchestration pattern rather than inventing a new control plane.

## Files to Modify

- `backend/Kds.Ai.ApiService/Program.cs` only if additive registration is required
- `backend/Kds.Ai.Integrations/DependencyInjectionExtensions.cs`
- optional endpoint registration files if manual replay is exposed over HTTP

## Required Behavior

### Replay Entry Inputs

Supported request shapes should allow bounded replay by one of:

- raw stage batch id
- load stage batch id
- curated stage batch id
- tenant id + entity + stage + bounded coordinate range
- tenant id + entity + explicit batch selection criteria

Each request must include:

- trigger/reason
- requested by
- replay mode
- bounded target definition

### Diagnostics And Auditability

- Replay launch must emit clear structured logs with:
  - replay mode,
  - requested target,
  - resolved durable plan,
  - completed rerun batch ids,
  - failure reason when rejected or failed.
- Replay failures should preserve enough details to support follow-up recovery without reading raw logs only.

### Safety Rules

- Reject unbounded replay requests.
- Reject conflicting input shapes.
- Reject replay requests that would use non-KDS source identity.
- Keep KDS CDC replay separate from synthetic KDS and Brink entrypoints.

## Testing

- API/job orchestration tests for:
  - valid replay request reaches planner/coordinator,
  - invalid or conflicting request is rejected,
  - replay trigger/reason/requested-by values flow into stage job inputs,
  - KDS CDC replay cannot accidentally dispatch as another source type.

## Acceptance Criteria

- Replay execution can be launched through a real codepath, not only through direct test-only service calls.
- Entry inputs are bounded, validated, and auditable.
- Manual/internal replay launch stays source-safe and additive.

## Notes

- If UI/API exposure is too broad for this slice, an internal job seam is sufficient as long as it is production-real and not test-only.