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/KdsCdcDurableRelationRouting/TASK5.md 3,549 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

TASK 5: Add Verification And Guardrails

Summary

Add deterministic and live-readiness coverage that proves durable relation routing, landing-before-resolution behavior, and unresolved-child recovery all work as intended.

Current Codebase Findings

Repository/runtime analysis shows:

current integration and live tests already cover major KDS CDC Debezium behavior,
recent Aspire/runtime investigation exposed real unresolved-child FIFO churn not covered by earlier tests,
relation-index, landing/promotion, and retry behavior need direct automated coverage,
readiness evidence must prove child routing no longer depends on immediate parent arrival in SQS hot path.

Dependencies

TASK 1
TASK 2
TASK 3
TASK 4

Source References

../KdsCdcIngestion/TASK9.md
../../docs/features/ETL/kds-cdc/index.md#supported-corner-cases
../../docs/features/ETL/kds-cdc/branch-direction-and-flow.md

Scope From Breakdown

This task covers:

unit/integration/live coverage additions,
regression guards against old SQS retry-loop behavior,
readiness checks for relation-based promotion behavior,
explicit proof that skipped areas are still intentionally skipped.

Files to Modify

backend/tests/Kds.Ai.Integrations.Tests/KdsCdc/
backend/tests/Kds.Ai.Data.Tests/
optional live test harnesses or infrastructure helpers only where needed

Required Behavior

Deterministic coverage

Need tests for:

order writes relation,
item resolves via durable order relation,
item bump resolves via durable item relation,
unresolved child lands durably and leaves SQS hot path,
unresolved child later promotes after relation appears,
duplicate redelivery converges on one landing/promoted record,
stale older relation write ignored,
delete events still resolve by retained relation,
malformed payload quarantine remains distinct from unresolved child flow.

Worker/readiness coverage

Need verification that:

SQS ack happens after landing durability,
promotion retry no longer depends on receipt visibility,
unresolved child no longer blocks later progress by remaining only in SQS loop,
logs/metrics expose durable unresolved backlog.

Non-goal protection

Tests or assertions should explicitly confirm:

no Redis dependency introduced,
no historical backfill behavior assumed,
no cleanup/TTL policy required for correctness,
Debezium contract and store_guid == tenant_id assumptions remain intact.

Testing

Recommended test layers:

data tests for relation persistence and stale-write semantics,
integration tests for resolver, landing/promotion, and retry coordinator,
live tests for at least one delayed-parent or delayed-relation scenario where infrastructure exists,
regression tests that would fail if system falls back to pure SQS retry churn.

Acceptance Criteria

[ ] Automated coverage exists for durable relation writes and reads
[ ] Automated coverage exists for landing-before-resolution ack behavior
[ ] Automated coverage exists for durable unresolved retry and later promotion
[ ] Automated coverage distinguishes malformed payload from retryable unresolved child
[ ] Readiness coverage demonstrates SQS visibility no longer controls eventual child success
[ ] Tests document skipped backfill/cleanup/Redis areas explicitly rather than implying they were delivered

Notes

Prefer assertions on durable state and batch metadata over log-only checks.
Keep live coverage opt-in as already established in this repo.