# TASK 1: Define Bounded Replay Contracts And Durable Resolution Rules

## Summary

Define the executable replay model for KDS CDC. This task freezes supported replay levels, request contracts, replay-target resolution rules, and the durable metadata each execution path requires before any operator-visible replay launcher is built.

## Current Codebase Findings

- `IKdsCdcReplayService` already supports replay lookup by:
  - batch id,
  - tenant/entity/stage,
  - coordinate range,
  - artifact URI.
- `KdsCdcReplayService` currently only forwards those queries to `IKdsCdcReplayIndexService`.
- `KdsCdcCheckpointSupport.CreateReplayIndexRequest(...)` already persists enough facts to locate batches by stage, coordinate range, and primary artifact URI.
- `KdsCdcStageJobInput` already gives downstream stages a clean replay-ready execution seam through `UpstreamBatchId`.
- Branch audit confirmed no current service consumes replay lookup results to launch replay.

Current repo constraints this task must respect:

1. Replay selection must be deterministic even when multiple candidate batches exist.
2. Replay after acknowledgement must depend on durable raw/load/curated artifacts, not transport state.
3. Current replay-index rows do not themselves execute work; this task must define the mapping from lookup result to execution target.

## Dependencies

- `../../docs/features/ETL/kds-cdc/index.md`
- `../../docs/features/ETL/kds-cdc/branch-audit.md`
- `../KdsCdcIngestion/TASK8.md`

## Source References

- `../../docs/features/ETL/kds-cdc/index.md#checkpointing-and-replay`
- `../../docs/features/ETL/kds-cdc/index.md#batch-lifecycle-and-lineage`
- `../../docs/features/ETL/kds-cdc/index.md#supported-corner-cases`
- `../../docs/features/ETL/kds-cdc/branch-audit.md`

## Files to Create

1. Replay contracts under `backend/Kds.Ai.Integrations/KdsCdc/Replay/` or `backend/Kds.Ai.Integrations/KdsCdc/Models/`:
   - `KdsCdcReplayRequest`
   - `KdsCdcReplayMode`
   - `KdsCdcReplayTarget`
   - `KdsCdcReplayExecutionPlan`
   - `KdsCdcReplayResolutionFailure`

   Responsibilities:
   - describe supported replay levels,
   - capture explicit bounded request inputs,
   - describe resolved durable starting point and downstream stages to execute.

2. Replay resolution seam:
   - `IKdsCdcReplayPlanner`
   - `KdsCdcReplayPlanner`

   Responsibilities:
   - resolve user/internal replay requests into durable execution plans,
   - validate ambiguity and unsupported requests before any stage work starts.

## Files to Modify

- `backend/Kds.Ai.Integrations/KdsCdc/IKdsCdcReplayService.cs`
- `backend/Kds.Ai.Integrations/KdsCdc/KdsCdcReplayService.cs`

Guidance:

- keep the current lookup API if still useful,
- add planning/execution seams instead of overloading plain lookup methods with side effects.

## Required Behavior

### Supported Replay Levels

The replay model must explicitly support:

- raw batch replay
- tenant/entity replay
- coordinate range replay
- load artifact retry
- curated retry

Each mode must define:

- required inputs,
- durable starting artifact or upstream batch,
- first stage to execute,
- downstream stop point when bounded.

### Deterministic Resolution Rules

- Raw batch replay resolves from an explicit stage batch id or raw artifact pointer.
- Load retry resolves from an explicit normalized/load batch or load artifact pointer.
- Curated retry resolves from an explicit staging-to-curated or curated batch.
- Tenant/entity replay resolves one bounded set of raw batches for a named tenant/entity and requested replay window or explicit bound.
- Coordinate replay resolves all relevant raw-stage candidates whose coordinate ranges overlap the requested range.

### Ambiguity Handling

- Replay planning must fail clearly when a request resolves to:
  - zero durable candidates,
  - multiple candidates where one exact target was required,
  - a candidate whose required upstream durable artifact is missing,
  - a candidate whose stage lineage is broken or inconsistent.

### Replay Execution Plan Shape

The resolved plan should state at minimum:

- replay mode,
- company id,
- tenant id,
- entity if applicable,
- starting stage,
- terminal stage,
- upstream durable batch ids or artifact URIs,
- whether execution is single-batch or multi-batch,
- human-readable reason/context for diagnostics.

## Testing

- Unit tests for replay request validation.
- Planner tests for:
  - raw batch exact resolution,
  - load retry exact resolution,
  - curated retry exact resolution,
  - tenant/entity resolution,
  - coordinate-range overlap resolution,
  - ambiguity failure,
  - missing durable artifact failure,
  - lineage break failure.

## Acceptance Criteria

- Supported replay modes are explicitly modeled in code.
- Replay requests resolve to deterministic execution plans before any stage job runs.
- Ambiguous or impossible requests fail with clear diagnostics.
- The codebase has a first-class replay planning seam rather than only replay-index lookup helpers.

## Notes

- Prefer explicit request contracts over loosely shaped dictionaries or untyped context objects.
- Preserve `IKdsCdcReplayService` lookup behavior if other tests or tooling already depend on it.