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

Raw File

TASK 5.1: Implement Load-To-Staging Orchestration And Upstream Normalize-Load Batch Resolution

Summary

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

This subtask turns the replay boundary from TASK4.md and the lifecycle contract from TASK3.md into a concrete execution path that resolves the upstream normalize-load batch, reads the produced load inventory, and prepares Redshift staging execution.

Dependencies

TASK 3 - batch lifecycle, checkpoints, and failure packaging
TASK 4 - raw to load normalization

Files to Create

1. Load-to-staging orchestration services

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

Recommended logical services:

BrinkPosLoadToStagingJobs
BrinkPosNormalizeLoadBatchResolver
BrinkPosStagingLoadOrchestrator

Required Behavior

child load-to-staging accepts a BrinkPosLoadToStagingJobInput-style contract
explicit NormalizeLoadBatchId wins when provided
otherwise the resolver loads the current successful normalize_load batch for the same tenant-day key
the upstream normalize-load batch must be successful and replayable
orchestration resolves the produced load/ artifact inventory from persisted batch metadata rather than from in-memory normalization state
the orchestration layer passes only upstream batch context and contract inventory into the staging-load boundary

Testing

Unit tests

Add unit tests for:

explicit upstream normalize-load batch selection
implicit upstream normalize-load batch selection through current-state lookup
rejection of failed or invalid upstream normalize-load batches
load-inventory resolution from persisted batch metadata
orchestration handoff from child job to staging-load execution

Acceptance Criteria

[x] Child load-to-staging job entry exists
[x] Upstream normalize-load batch resolution exists for explicit and implicit selection paths
[x] Failed or invalid upstream normalize-load batches are rejected
[x] Produced load inventory is resolved from persisted batch metadata
[x] Unit tests cover upstream resolution and orchestration behavior

Notes

Keep this subtask focused on stage orchestration readiness.
Do not implement contract-to-table mapping or Redshift execution here; those belong to later subtasks in TASK 5.