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

Raw File

TASK 3.2: Implement Current-State, Supersede, And Upstream-Batch Semantics

Summary

Implement the runtime behavior that decides which batch is current, how reruns supersede prior success, and how downstream stages resolve the exact upstream batch they consume.

This subtask makes tenant-day stage reruns safe and replayable without relying on newest-row inference.

Dependencies

TASK 3.1 - stage batch and checkpoint contracts

Files to Create

1. Lifecycle transition services

Create or finalize the services that:

start a stage batch
complete a stage batch successfully
fail a stage batch
supersede the prior current batch on successful rerun
resolve upstream batches by explicit id or by current-state lookup

Recommended logical services:

IngestionBatchLifecycleService
StageUpstreamBatchResolver

Required Behavior

only successful batches may become current
failed or partial batches never become current
rerun creates a new batch and links to the prior current successful batch
a successful rerun clears is_current on the previously current successful batch for the same stage key
supersede behavior is stage-local and must not mutate unrelated stage state
downstream stages must accept either an explicitly requested upstream batch id or resolve the current successful upstream batch automatically
downstream stages must reject nonexistent, failed, or non-current upstream references unless an explicit replay contract later allows them

Testing

Unit tests

Add unit tests for:

first successful batch becoming current
successful rerun superseding the previous current batch
failed rerun preserving the previous current batch
upstream batch resolution by explicit id
upstream batch resolution by current successful batch lookup
rejection of invalid upstream batch references

Acceptance Criteria

[x] Current-state transitions exist for successful stage completion
[x] Successful rerun supersedes the previous current batch
[x] Failed rerun does not clear the previous current batch
[x] Upstream-batch resolution supports explicit and implicit selection paths
[x] Unit tests cover current-state, supersede, and upstream selection behavior

Notes

Keep current-state resolution explicit and deterministic.
Do not let downstream stages infer upstream input from the newest created batch record.