# TASK 1: Replace Simulator Contract Assumptions With Debezium-Native Intake Models

## Summary

Replace the current simulator-shaped intake contract with Debezium-native models and parser behavior, while making intake independent from `MessageGroupId` as processing contract.

This task establishes the new source-of-truth message model for KDS CDC so later work does not keep translating Debezium into simulator-era abstractions.

## Current Codebase Findings

Repository analysis shows the current intake seam is tightly coupled to simulator/custom payload assumptions:

- `KdsCdcEnvelopeParser` rejects messages if `MessageGroupId` or `SequenceNumber` are missing.
- `KdsCdcEnvelope` expects top-level `source_type`, `source_account_id`, `store_guid`, `entity`, `operation`, and `primary_key`.
- Parser branches on `KdsCdcContractProfile.Mock` vs `Production` and still treats mock contract as first-class.
- Real payload samples under `docs/features/ETL/kds-cdc/payloads/` use top-level `schema` plus nested `payload.before`, `payload.after`, `payload.source`, and `payload.op`.

These findings mean current parser and message models are incorrect for the real input contract.

## Dependencies

- `docs/features/ETL/kds-cdc/debezium-payload-compatibility-notes.md`
- payload samples under `docs/features/ETL/kds-cdc/payloads/`

## Source References

- `../../docs/features/ETL/kds-cdc/debezium-payload-compatibility-notes.md`
- `../../docs/features/ETL/kds-cdc/payloads/customer_update.json`
- `../../docs/features/ETL/kds-cdc/payloads/item_create.json`
- `../../docs/features/ETL/kds-cdc/payloads/item_update.json`
- `../../docs/features/ETL/kds-cdc/payloads/item_bump_create.json`
- `../../docs/features/ETL/kds-cdc/payloads/order_create.json`
- `../../docs/features/ETL/kds-cdc/payloads/order_update.json`
- `../../docs/features/ETL/kds-cdc/payloads/order_delete.json`

## Scope From Breakdown

This task covers only the contract/model replacement seam:

- Debezium envelope models,
- parser shape,
- op mapping,
- effective row-image selection,
- transport metadata compatibility model.

## Files to Create

Recommended new logical types under `backend/Kds.Ai.Integrations/KdsCdc/Messages/`:

- `KdsDebeziumEnvelope.cs`
- `KdsDebeziumPayload.cs`
- `KdsDebeziumSourceMetadata.cs`
- `KdsDebeziumTransactionMetadata.cs` if needed
- optional small helper type for resolved effective row image or parsed metadata snapshot

## Files to Modify

- `backend/Kds.Ai.Integrations/KdsCdc/KdsCdcEnvelopeParser.cs`
- `backend/Kds.Ai.Integrations/KdsCdc/Messages/KdsCdcEnvelope.cs` or replace usage entirely
- `backend/Kds.Ai.Integrations/KdsCdc/Messages/KdsCdcReceivedMessage.cs`
- `backend/Kds.Ai.Integrations/KdsCdc/Messages/KdsCdcTransportMessage.cs`
- `backend/Kds.Ai.Integrations/KdsCdc/Messages/KdsCdcContractProfile.cs`
- any parser-facing diagnostics or quarantine models that assume mock/custom reason codes

## Required Behavior

### Debezium envelope parsing

Parser must:

- deserialize Debezium top-level `schema` + `payload`,
- read `payload.source.table` as source entity,
- map `payload.op` values (`c`, `u`, `d`, `r`),
- choose effective business row image:
  - `after` for `c`, `u`, `r`
  - `before` for `d`
- derive primary key from effective row image,
- preserve the full original Debezium payload for raw storage and replay.

### Transport compatibility without `MessageGroupId` dependency

Transport model must allow:

- nullable `MessageGroupId`,
- nullable `SequenceNumber`.

Parser must preserve transport metadata when present, but it must not define a new correctness contract around derived pseudo-`MessageGroupId` values.

This task must establish:

- landing-capture compatibility without `MessageGroupId`,
- nullable `SequenceNumber` support,
- no parser-time requirement that transport metadata define routing or batching.

### Contract simplification

Target direction is one Debezium-native production contract.

Preferred end state:

- no simulator/mock parser branch,
- no dependence on custom top-level `source_type`, `source_account_id`, or `primary_key` fields.

## Testing

Add parser-focused tests for:

- customer update payload,
- order create payload,
- order update payload,
- order delete payload,
- item update payload,
- missing transport metadata accepted into landing-capture path,
- malformed Debezium JSON rejected clearly,
- unsupported table/entity rejected clearly if outside supported set.

Tests should load or mirror the real sample payloads rather than inventing simulator-era bodies.

## Acceptance Criteria

- [ ] Parser no longer depends on simulator-style top-level envelope fields
- [ ] Debezium `schema` + `payload` shape is modeled explicitly
- [ ] Debezium op codes are mapped intentionally
- [ ] Effective row image is selected from `before` / `after`
- [ ] Primary key is derived from row image, not `primary_key` envelope field
- [ ] Transport model allows missing `MessageGroupId` and `SequenceNumber`
- [ ] Parser preserves transport metadata without making it a correctness prerequisite
- [ ] Full Debezium payload remains available for raw persistence/replay
- [ ] Tests cover all provided sample payload shapes

## Notes

- Keep this task focused on intake contract and parser shape.
- Do not mix tenant-resolution or normalization business logic into the parser unless required for basic field extraction.