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

Raw File

TASK 1.2: Create Tenant Warehouse Foundation Abstractions

Summary

Create the reusable tenant-aware Redshift foundation abstractions that the platform will use later for warehouse routing and bootstrap.

This task should decouple the new Redshift foundation from the legacy shared PostgreSQL KDSContext model.

The new abstractions should live in a new backend module named Kds.Ai.Warehouse.

Dependencies

TASK 1.1 (tenant routing metadata)

Files to Create

1. Foundation abstractions in `backend/Kds.Ai.Warehouse`

Create a new project/module for warehouse foundation logic.

Create abstractions equivalent to:

ITenantWarehouseResolver
ITenantWarehouseConnectionFactory
ITenantWarehouseBootstrapper

The foundation abstractions should be capable of supporting the complete phase-1 tenant template, including the minimal warehouse access boundary required for future curated-first runtime reads.

The bootstrapper abstraction must be designed as the primary reusable service that later callers can invoke from:

CLI commands in phase 1,
admin API onboarding in a later phase.

Tenant registration metadata operations may use a separate metadata-facing service or repository path, but must remain consistent with the same warehouse foundation model.

Optional supporting abstractions/models may also be added, for example:

options or settings objects,
tenant warehouse descriptors,
bootstrap request/result models.

Exact type names may differ, but these responsibilities must exist.

Files to Modify

2. Existing DI modules as needed

Prepare dependency injection registration for the foundation layer, without integrating it into the agent/runtime query path.

Required Behavior

Tenant warehouse resolver

Must be able to resolve:

tenant_id
target tenant database name
active/inactive state

from metadata stored in kdsaidb.

Tenant warehouse connection factory

Must define the abstraction for opening a connection to a resolved tenant warehouse database.

Tenant warehouse bootstrapper

Must define the abstraction for creating or validating the standard tenant warehouse template.

That template includes:

staging, curated, serving, and etl_meta,
internal source-mirror backing structures in curated,
source-mirror staging.<system>_<table> tables,
source-mirror curated.<system>_<table> tables,
the minimal warehouse access boundary required by phase 1.

Acceptance Criteria

[x] A new backend project/module named Kds.Ai.Warehouse is introduced
[x] Tenant-aware foundation interfaces are created
[x] Abstractions are independent from KDSContext
[x] Resolver contract is based on metadata from kdsaidb
[x] Connection factory contract supports tenant-scoped database access
[x] Bootstrapper contract supports tenant database creation/validation scenarios
[x] Foundation abstractions can support bootstrap of the minimal warehouse access boundary required by phase 1
[x] DI registration path exists for the new abstractions
[x] Solution builds without errors

Notes

Do not integrate these abstractions with the anomaly detector yet.
Do not migrate simulator usage yet.
This task is about creating the reusable platform contract, not consuming it.
Bootstrap must be service-first, not CLI-only.
Keep project and namespace naming warehouse-centric rather than Redshift-centric.
The dedicated tenant warehouse validator abstraction was removed from the branch when the hardcoded canonical curated contract was dropped.