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

Raw File

TASK 3: Expose Replay Launch Seams For Operators And Internal Jobs

Summary

Expose a stable replay entry seam so replay execution is callable by internal jobs and, where appropriate, by manual operational tooling. This task turns the replay coordinator into an actionable recovery interface.

Current Codebase Findings

Current API-service orchestration already has a pattern for manual ETL launch in BrinkPosEtlJobs and related endpoints.
No KDS CDC replay command, endpoint, or job entrypoint was found during branch audit.
Current KDS CDC replay service is lookup-only and not operator-callable for execution.

Current repo constraints this task must respect:

Replay entry should be explicit and auditable.
Replay entry must require bounded parameters, not open-ended "replay everything" behavior.
Manual replay should reuse the same replay planner/coordinator used by any internal job path.

Dependencies

Source References

../../docs/features/ETL/kds-cdc/index.md#checkpointing-and-replay
../../docs/features/ETL/kds-cdc/index.md#quarantine-and-failed-packages
../../docs/features/ETL/kds-cdc/branch-audit.md

Files to Create

Replay launch seam under backend/Kds.Ai.ApiService/Jobs/KdsCdc/ or adjacent orchestration location:
KdsCdcReplayJobs.cs
optional request DTOs for manual/internal replay inputs

Responsibilities:

validate operator/internal input shape,
invoke replay planner and coordinator,
log/audit replay trigger and outcome.

Optional endpoint or internal service seam if repo patterns justify it:
endpoint under API service for manual replay
internal service or command handler for non-HTTP invocation

Guidance:

follow existing repo orchestration pattern rather than inventing a new control plane.

Files to Modify

backend/Kds.Ai.ApiService/Program.cs only if additive registration is required
backend/Kds.Ai.Integrations/DependencyInjectionExtensions.cs
optional endpoint registration files if manual replay is exposed over HTTP

Required Behavior

Replay Entry Inputs

Supported request shapes should allow bounded replay by one of:

raw stage batch id
load stage batch id
curated stage batch id
tenant id + entity + stage + bounded coordinate range
tenant id + entity + explicit batch selection criteria

Each request must include:

trigger/reason
requested by
replay mode
bounded target definition

Diagnostics And Auditability

Replay launch must emit clear structured logs with:
replay mode,
requested target,
resolved durable plan,
completed rerun batch ids,
failure reason when rejected or failed.
Replay failures should preserve enough details to support follow-up recovery without reading raw logs only.

Safety Rules

Reject unbounded replay requests.
Reject conflicting input shapes.
Reject replay requests that would use non-KDS source identity.
Keep KDS CDC replay separate from synthetic KDS and Brink entrypoints.

Testing

API/job orchestration tests for:
valid replay request reaches planner/coordinator,
invalid or conflicting request is rejected,
replay trigger/reason/requested-by values flow into stage job inputs,
KDS CDC replay cannot accidentally dispatch as another source type.

Acceptance Criteria

Replay execution can be launched through a real codepath, not only through direct test-only service calls.
Entry inputs are bounded, validated, and auditable.
Manual/internal replay launch stays source-safe and additive.

Notes

If UI/API exposure is too broad for this slice, an internal job seam is sufficient as long as it is production-real and not test-only.