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

Raw File

TASK 4.1: Implement Normalize-Load Orchestration And Upstream Raw-Batch Resolution

Summary

Implement the tenant-day normalize_load entry point and the ETL/Warehouse orchestration flow that starts one raw -> load run for Brink Sales2.GetOrders.

This subtask turns the replay boundary from TASK2.md and the lifecycle contract from TASK3.md into a concrete execution path that resolves the upstream raw batch, builds normalization context, and prepares load artifact persistence.

Dependencies

TASK 2 - extract raw XML
TASK 3 - batch lifecycle, checkpoints, and failure packaging

Files to Create

1. Normalize-load orchestration services

Create or finalize the services responsible for one tenant-day normalize_load execution.

Recommended logical services:

BrinkPosNormalizeLoadJobs
BrinkPosRawBatchResolver
BrinkPosNormalizeLoadOrchestrator
BrinkPosNormalizationContextFactory

Required Behavior

child normalize-load accepts a BrinkPosNormalizeLoadJobInput-style contract
explicit ExtractBatchId wins when provided
otherwise the resolver loads the current successful extract_raw batch for the same tenant-day key
the upstream raw batch must be successful and replayable
normalization context is built from persisted raw artifact metadata rather than in-memory DTOs
the orchestration layer passes only normalization context and raw artifact references into the Brink normalization boundary

Testing

Unit tests

Add unit tests for:

explicit upstream raw-batch selection
implicit upstream raw-batch selection through current-state lookup
rejection of failed or invalid upstream raw batches
normalization-context creation from raw artifact metadata
orchestration handoff from child job to normalization execution

Acceptance Criteria

[x] Child normalize-load job entry exists
[x] Upstream raw-batch resolution exists for explicit and implicit selection paths
[x] Failed or invalid upstream raw batches are rejected
[x] Normalization context is built from persisted raw metadata
[x] Unit tests cover upstream resolution and orchestration behavior

Notes

Keep this subtask focused on stage orchestration readiness.
Do not implement relational decomposition or Parquet persistence here; those belong to later subtasks in TASK 4.