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/SingleStoreRedshiftRuntimeReadPath/TASK.md 8,326 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

Single-Store Redshift Runtime Read Path - Implementation Tasks

Overview

Implementation of the Single-Store Redshift Runtime Read Path delivery slice.

This task plan is derived from the documentation set in:

../../docs/features/ETL/slices/03-single-store-redshift-runtime-read-path/index.md
../../docs/features/ETL/slices/03-single-store-redshift-runtime-read-path/runtime-read-path-spec.md
../../docs/features/ETL/slices/03-single-store-redshift-runtime-read-path/follow-ups.md
../../docs/features/ETL/slices/01-redshift-foundation/serving-mapping.md
../../docs/ETL.md

This task switches current single-store runtime reads from the shared PostgreSQL warehouse to tenant-resolved Redshift curated tables.

It does not migrate monitor specs from kdsdev. to curated.. That belongs to slice 04.

The slice outcome is:

a runtime tenant resolver with explicit/default single-tenant support,
anomaly detector data access tools that open tenant-resolved Redshift connections,
curated-only schema/table discovery,
curated-only read query guardrails,
data access prompt/tool descriptions updated for Redshift curated,
runtime AI reads aligned to source-mirror curated.<system>_<table> objects,
/warehouse/orders endpoint migration remains unresolved in the current branch,
smoke validation against Redshift curated data loaded by slice 02.

Source Documents

../../docs/features/ETL/slices/03-single-store-redshift-runtime-read-path/index.md
../../docs/features/ETL/slices/03-single-store-redshift-runtime-read-path/runtime-read-path-spec.md
../../docs/features/ETL/slices/03-single-store-redshift-runtime-read-path/follow-ups.md
../../docs/features/ETL/slices/01-redshift-foundation/index.md
../../docs/features/ETL/slices/01-redshift-foundation/serving-mapping.md
../../docs/features/ETL/slices/02-redshift-synthetic-data-feed/index.md
../../docs/ETL.md

Spec Name

The canonical documentation slice is named 03-single-store-redshift-runtime-read-path.

This implementation spec should be referred to as Single-Store Redshift Runtime Read Path.

Fixed Decisions

This slice is single-store only.
A configured default tenant_id is acceptable until authenticated tenant resolution exists.
CLI/dev flows may accept an explicit tenant_id override.
Runtime database routing is platform-owned and resolved outside agent SQL.
Runtime reads use tenant Redshift, not the shared PostgreSQL warehousedb.
Runtime tools expose approved source-mirror curated objects only.
staging, etl_meta, kdsdev, and source schemas are not runtime query surfaces.
Data access prompt/tool language moves to Redshift curated.
Individual monitor specs are not migrated in this slice.
API order endpoints are not yet aligned to the branch's source-mirror curated model.
Cross-tenant Athena, full RBAC, ETL/S3/COPY/UNLOAD, simulator writes, and new serving domains remain out of scope.

Scope

This task includes:

adding runtime tenant configuration and resolver abstractions,
integrating runtime consumers with the tenant warehouse foundation from slice 01,
replacing shared PostgreSQL warehouse reads in the anomaly detector data access tool path,
restricting AI schema/table discovery to approved source-mirror curated objects,
adding pragmatic curated-only SQL guardrails,
updating data access prompt and tool descriptions,
deferring the canonical order-read service and /warehouse/orders migration until a branch-aligned runtime contract exists,
adding smoke validation for tenant Redshift curated reads.

In short, the slice ends when current single-store runtime reads can use tenant Redshift curated without depending on the shared PostgreSQL warehouse.

Out of Scope

The following items are explicitly excluded from this task:

simulator write migration,
synthetic data feed implementation,
monitor spec migration from kdsdev. to curated.,
authenticated user-to-tenant RBAC,
store groups,
cross-tenant Athena path,
Glue,
S3 curated exports,
Redshift COPY and UNLOAD,
ETL worker and ingestion API,
POS, inventory, payments, forecasting, pricing, and customer serving domains,
production-grade SQL parser or policy engine,
anomaly detector orchestration redesign.

Task Checklist

Phase 1: Runtime Tenant Context

[x] TASK 1.1 - Add runtime tenant resolver and configuration
[x] TASK 1.2 - Wire runtime services to tenant warehouse foundation

Phase 2: AI Data Access Runtime

[x] TASK 2.1 - Update warehouse query tools to use tenant-resolved Redshift
[x] TASK 2.2 - Restrict schema discovery and SQL execution to approved source-mirror curated objects
[x] TASK 2.3 - Update data access prompt and tool descriptions

Phase 3: Backend Order Read Endpoints

[ ] TASK 3.1 - Create a branch-aligned Redshift runtime read service
[ ] TASK 3.2 - Migrate /warehouse/orders endpoints to a branch-aligned Redshift runtime contract

Phase 4: Smoke Validation

[ ] TASK 4.1 - Add smoke validation for the runtime read path

Dependency Graph

Prerequisites
    |-- Redshift Foundation complete
    |   +-- tenant routing metadata
    |   +-- tenant warehouse connection factory
    |   +-- bootstrapped tenant database
    |   +-- source-mirror curated tables for supported systems
    +-- Redshift Synthetic Data Feed complete
        +-- source-mirror KDS curated tables contain synthetic rows

Phase 1 (Runtime Tenant Context)
    |-- 1.1 Runtime tenant resolver and configuration
    +-- 1.2 Runtime services wired to tenant warehouse foundation <-- (depends on 1.1)

Phase 2 (AI Data Access Runtime)
    |-- 2.1 Tenant-resolved Redshift query tools <-- (depends on 1.2)
    |-- 2.2 Source-mirror curated discovery and SQL guardrails <-- (depends on 2.1)
    +-- 2.3 Prompt/tool description update <-- (depends on 2.2)

Phase 3 (Backend Order Read Endpoints)
    |-- 3.1 Branch-aligned runtime read service <-- (depends on 1.2)
    +-- 3.2 Migrate order endpoints <-- (depends on 3.1)

Phase 4 (Smoke Validation)
    +-- 4.1 Runtime read path smoke validation <-- (depends on 2.3, 3.2)

Recommended Session Order

Session	Tasks	Description
1	1.1, 1.2	Runtime tenant context and foundation wiring
2	2.1, 2.2	Tenant-resolved AI data access and source-mirror curated guardrails
3	2.3	Prompt/tool language update
4	3.1, 3.2	Branch-aligned runtime read service and API endpoint migration
5	4.1	Smoke validation against synthetic Redshift curated data

Key Design Decisions

Single Tenant Only

The runtime resolver returns one tenant for this slice. Multi-tenant user access, store groups, and Athena routing are future work.

Default Tenant Is Temporary

The configured default tenant is a deliberate shortcut for the current single-store backend context. It must be explicit and easy to replace with authenticated tenant resolution later.

Runtime Uses Tenant Redshift

Migrated runtime reads must use the tenant warehouse foundation to resolve and open Redshift. They should not use the shared PostgreSQL warehousedb read connection.

Curated Is the Runtime Surface

AI tools should read only approved source-mirror curated.<system>_<table> objects in this phase. Internal schemas and source schemas are not runtime query surfaces.

The branch does not currently define a canonical curated.orders / curated.order_items runtime surface for migrated API endpoints.

Guardrails Are Layered

Use Redshift permissions where available, and also add lightweight application guardrails around schema discovery and generated SQL. Prompt instructions alone are not enough.

Preserve Orchestration

Monitor run lifecycle, dry-run behavior, alert suppression, alert emission, and monitor spec storage should remain unchanged.

Monitor Prompts Stay Deferred

Existing monitor specs may still reference kdsdev.* until slice 04. This slice prepares the runtime surface and may expose "table not available" failures for unmigrated prompts.