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.4.md 2,594 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

TASK 3.4: Add Unit Tests And Live Verification For Lifecycle Semantics

Summary

Add the verification layer for stage lifecycle behavior so reruns, checkpoints, current-state selection, and failure packaging are proven against both local tests and real ETL infrastructure where available.

Dependencies

TASK 2 - extract raw XML
TASK 3.1 - stage batch and checkpoint contracts
TASK 3.2 - current-state, supersede, and upstream-batch semantics
TASK 3.3 - failed-package handling and stage traceability

Files to Create

1. Lifecycle test suites

Create or finalize the test coverage needed for:

batch lifecycle transitions
checkpoint advancement rules
current-batch selection
upstream-batch resolution
failed-package creation and sanitization
live verification of rerun and failure behavior

Required Behavior

unit tests must cover the assembled lifecycle contract used by stage orchestration
live verification must prove the real environment honors rerun/current-state and failed-package rules whenever Aspire-managed services from TASK2.md are available
if controlled live failure is not safe or feasible in one environment, the blocker must be documented explicitly rather than silently skipping verification

Testing

Unit tests

Ensure the final unit suite covers:

stage batch state transitions
supersede lineage
checkpoint advancement and non-advancement cases
explicit and implicit upstream-batch selection
failed-package payload creation and sanitization

Live verification

Add live verification that proves at least:

one successful tenant-day rerun supersedes the previous successful batch
current-batch resolution returns the expected successful batch
checkpoint state does not advance on a failed attempt
a failed attempt produces a safe failed/ package correlated to the batch and persisted artifact references

Acceptance Criteria

[x] Unit-test coverage exists for the assembled lifecycle contract
[x] Live verification exists for rerun/current-state behavior when real integrations are available
[x] Live verification exists for failed-package behavior when a controlled failure can be induced safely
[x] Any live-verification blocker is documented explicitly
[x] TASK 3 is verifiable as a completed operational contract

Notes

Keep this subtask focused on verification, not on redesigning the lifecycle contract.
Reuse the real extract_raw path from TASK2 as the first live stage for lifecycle verification.