# 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](./TASK1.1.md) - Add runtime tenant resolver and configuration
- [x] [TASK 1.2](./TASK1.2.md) - Wire runtime services to tenant warehouse foundation

### Phase 2: AI Data Access Runtime

- [x] [TASK 2.1](./TASK2.1.md) - Update warehouse query tools to use tenant-resolved Redshift
- [x] [TASK 2.2](./TASK2.2.md) - Restrict schema discovery and SQL execution to approved source-mirror `curated` objects
- [x] [TASK 2.3](./TASK2.3.md) - Update data access prompt and tool descriptions

### Phase 3: Backend Order Read Endpoints

- [ ] [TASK 3.1](./TASK3.1.md) - Create a branch-aligned Redshift runtime read service
- [ ] [TASK 3.2](./TASK3.2.md) - Migrate `/warehouse/orders` endpoints to a branch-aligned Redshift runtime contract

### Phase 4: Smoke Validation

- [ ] [TASK 4.1](./TASK4.1.md) - 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.