Spensara Spensara Knowledge Base & Documentation Repository
System Overview Brink & Borg Master Index (722 Docs) Spensara Platform Project Tracker

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)

Categories

Implementation Specs (157)

Detailed engineering and feature implementation specifications.
implementation-specs/specs/KdsCdcReplayExecution/TASK1.md 5,221 bytes · Updated Oct 23, 2026 10:44 AM EDT
Raw File

TASK 1: Define Bounded Replay Contracts And Durable Resolution Rules

Summary

Define the executable replay model for KDS CDC. This task freezes supported replay levels, request contracts, replay-target resolution rules, and the durable metadata each execution path requires before any operator-visible replay launcher is built.

Current Codebase Findings

  • IKdsCdcReplayService already supports replay lookup by:
  • batch id,
  • tenant/entity/stage,
  • coordinate range,
  • artifact URI.
  • KdsCdcReplayService currently only forwards those queries to IKdsCdcReplayIndexService.
  • KdsCdcCheckpointSupport.CreateReplayIndexRequest(...) already persists enough facts to locate batches by stage, coordinate range, and primary artifact URI.
  • KdsCdcStageJobInput already gives downstream stages a clean replay-ready execution seam through UpstreamBatchId.
  • Branch audit confirmed no current service consumes replay lookup results to launch replay.

Current repo constraints this task must respect:

  1. Replay selection must be deterministic even when multiple candidate batches exist.
  2. Replay after acknowledgement must depend on durable raw/load/curated artifacts, not transport state.
  3. Current replay-index rows do not themselves execute work; this task must define the mapping from lookup result to execution target.

Dependencies

  • ../../docs/features/ETL/kds-cdc/index.md
  • ../../docs/features/ETL/kds-cdc/branch-audit.md
  • ../KdsCdcIngestion/TASK8.md

Source References

  • ../../docs/features/ETL/kds-cdc/index.md#checkpointing-and-replay
  • ../../docs/features/ETL/kds-cdc/index.md#batch-lifecycle-and-lineage
  • ../../docs/features/ETL/kds-cdc/index.md#supported-corner-cases
  • ../../docs/features/ETL/kds-cdc/branch-audit.md

Files to Create

  1. Replay contracts under backend/Kds.Ai.Integrations/KdsCdc/Replay/ or backend/Kds.Ai.Integrations/KdsCdc/Models/:
  2. KdsCdcReplayRequest
  3. KdsCdcReplayMode
  4. KdsCdcReplayTarget
  5. KdsCdcReplayExecutionPlan
  6. KdsCdcReplayResolutionFailure

Responsibilities:

  • describe supported replay levels,
  • capture explicit bounded request inputs,
  • describe resolved durable starting point and downstream stages to execute.
  1. Replay resolution seam:
  2. IKdsCdcReplayPlanner
  3. KdsCdcReplayPlanner

Responsibilities:

  • resolve user/internal replay requests into durable execution plans,
  • validate ambiguity and unsupported requests before any stage work starts.

Files to Modify

  • backend/Kds.Ai.Integrations/KdsCdc/IKdsCdcReplayService.cs
  • backend/Kds.Ai.Integrations/KdsCdc/KdsCdcReplayService.cs

Guidance:

  • keep the current lookup API if still useful,
  • add planning/execution seams instead of overloading plain lookup methods with side effects.

Required Behavior

Supported Replay Levels

The replay model must explicitly support:

  • raw batch replay
  • tenant/entity replay
  • coordinate range replay
  • load artifact retry
  • curated retry

Each mode must define:

  • required inputs,
  • durable starting artifact or upstream batch,
  • first stage to execute,
  • downstream stop point when bounded.

Deterministic Resolution Rules

  • Raw batch replay resolves from an explicit stage batch id or raw artifact pointer.
  • Load retry resolves from an explicit normalized/load batch or load artifact pointer.
  • Curated retry resolves from an explicit staging-to-curated or curated batch.
  • Tenant/entity replay resolves one bounded set of raw batches for a named tenant/entity and requested replay window or explicit bound.
  • Coordinate replay resolves all relevant raw-stage candidates whose coordinate ranges overlap the requested range.

Ambiguity Handling

  • Replay planning must fail clearly when a request resolves to:
  • zero durable candidates,
  • multiple candidates where one exact target was required,
  • a candidate whose required upstream durable artifact is missing,
  • a candidate whose stage lineage is broken or inconsistent.

Replay Execution Plan Shape

The resolved plan should state at minimum:

  • replay mode,
  • company id,
  • tenant id,
  • entity if applicable,
  • starting stage,
  • terminal stage,
  • upstream durable batch ids or artifact URIs,
  • whether execution is single-batch or multi-batch,
  • human-readable reason/context for diagnostics.

Testing

  • Unit tests for replay request validation.
  • Planner tests for:
  • raw batch exact resolution,
  • load retry exact resolution,
  • curated retry exact resolution,
  • tenant/entity resolution,
  • coordinate-range overlap resolution,
  • ambiguity failure,
  • missing durable artifact failure,
  • lineage break failure.

Acceptance Criteria

  • Supported replay modes are explicitly modeled in code.
  • Replay requests resolve to deterministic execution plans before any stage job runs.
  • Ambiguous or impossible requests fail with clear diagnostics.
  • The codebase has a first-class replay planning seam rather than only replay-index lookup helpers.

Notes

  • Prefer explicit request contracts over loosely shaped dictionaries or untyped context objects.
  • Preserve IKdsCdcReplayService lookup behavior if other tests or tooling already depend on it.