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

Raw File

TASK 1: Add Framework-Owned Export Contracts, Shared Redshift `UNLOAD` Executor, And Curated S3 Path Usage

Summary

Add framework-owned export contracts and shared execution seam for exporting curated data from tenant Redshift to S3 with UNLOAD.

Dependencies

TASK 0 - Freeze minimal curated_to_s3 delivery contract

Files to Create

1. Shared export execution types

Create shared types equivalent to:

CuratedExportRequest
CuratedExportTargetDefinition
ICuratedExportCatalog
ICuratedExportExecutor
CuratedExportExecutor

Minimum logical fields:

tenant warehouse descriptor,
target name,
export SELECT SQL,
logical entity name,
output S3 prefix or object key seed,
batch and tenant context needed for path generation.

Files to Modify

2. Warehouse/export module wiring

3. Existing S3 path helper usage

Reuse existing curated path/key builder logic instead of adding ad-hoc string formatting in stage code.

Progress Checklist

[ ] Shared export contract types created
[ ] Shared export executor created
[ ] DI wiring added
[ ] Tenant warehouse connection reuse implemented
[ ] Central UNLOAD command generation implemented
[ ] Existing curated S3 path helper reused
[ ] Executor diagnostics shape defined
[ ] Unit tests added for command generation and failure path

Required Behavior

executor opens tenant warehouse connection through existing tenant warehouse connection factory,
executor builds safe UNLOAD command for Parquet output,
executor writes to standard curated S3 layout,
executor keeps command generation centralized,
shared contract can describe export targets for any adapter,
executor surfaces per-target diagnostics useful for stage failure packaging,
executor does not own adapter target list.

Testing

Unit tests

Add unit tests for:

UNLOAD command generation,
S3 path generation usage,
per-target execution diagnostics,
failure propagation on Redshift command error.

Acceptance Criteria

shared export executor exists,
shared export catalog contract exists,
executor uses tenant-resolved Redshift connection,
executor generates Parquet UNLOAD commands centrally,
executor writes to standard curated S3 path shape,
unit tests cover success and failure command paths.

Notes

Keep contracts and executor generic enough for later sources.
Do not add Athena or Glue behavior here.