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

Raw File

TASK 4: Add Replay Execution Coverage And Regression Guardrails

Summary

Add deterministic coverage and guardrails proving that replay execution works from durable state and does not introduce forbidden behavior. This task completes the slice by turning replay execution into a verified operational capability.

Current Codebase Findings

KDS CDC already has broad deterministic stage coverage and replay-index query coverage.
Branch audit found no replay execution tests because no replay execution path existed yet.
Task 9 already defines required replay verification themes:
raw replay
load retry
curated retry
coordinate-bounded recovery
no SQS dependency after acknowledgement

Current repo constraints this task must respect:

Coverage should reuse existing KDS CDC integration test patterns where possible.
Tests must prove replay from durable boundaries, not just planner behavior.
Existing Brink and synthetic KDS coverage must remain unchanged.

Dependencies

TASK 1
TASK 2
TASK 3
../KdsCdcIngestion/TASK9.md

Source References

../../docs/features/ETL/kds-cdc/index.md#checkpointing-and-replay
../../docs/features/ETL/kds-cdc/index.md#supported-corner-cases
../../docs/features/ETL/kds-cdc/index.md#non-goals
../KdsCdcIngestion/TASK9.md

Files to Create

Replay-focused tests under backend/tests/Kds.Ai.Integrations.Tests/KdsCdc/ and, if needed, backend/tests/Kds.Ai.ApiService.Tests/:
suggested files:
KdsCdcReplayPlannerTests.cs
KdsCdcReplayCoordinatorTests.cs
KdsCdcReplayJobsTests.cs

Files to Modify

existing KDS CDC test infrastructure only where additive helpers are needed for replay plan fixtures or stage-call recording.

Required Behavior

Minimum Verified Replay Matrix

Coverage must verify:

raw batch replay re-runs downstream stages from durable raw state
load retry reuses durable load artifact and does not reopen SQS
curated retry reuses downstream durable state and does not reopen SQS
coordinate replay resolves correct ordered candidates
tenant/entity replay stays bounded to requested tenant/entity
failed replay stops later stages
successful replay preserves UpstreamBatchId, IsCurrent, and ResetOfBatchId semantics

Non-Goal Regression Guards

Coverage must also verify replay did not introduce:

dependency on queue retention after acknowledgement
source identity confusion with SyntheticKds
direct table mutation bypassing stage jobs
replay of unbounded tenant history from loose request inputs

Testing

Planner unit tests.
Coordinator integration-style tests with fakes for stage jobs and replay-index lookup.
API/job orchestration tests for request validation and dispatch.
Regression tests proving queue client is not used during replay.
If feasible with existing infra, one durable-state integration test that exercises persisted raw/load batch state end to end.

Acceptance Criteria

Replay execution is covered at planner, coordinator, and launch layers.
Tests prove replay runs from durable artifacts rather than queue retention.
Tests prove existing lifecycle semantics remain intact during replay reruns.
Replay-specific coverage is additive and does not weaken existing ETL behavior.

Notes

Keep this task deterministic-first. Live replay readiness can be added later if external infrastructure is available.