Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Implementation Specs (157)

Detailed engineering and feature implementation specifications.

implementation-specs/specs/KdsCdcDebeziumIntegration/TASK1.md 5,378 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

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.