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

Raw File

KDS Monitor Curated Contract Migration - Implementation Tasks

Overview

Implementation of the KDS Monitor Curated Contract Migration delivery slice.

This task plan is derived from the documentation set in:

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

This task migrates the initial KDS monitor prompt/spec content from source-shaped kdsdev.* assumptions to the Redshift curated contract.

It does not change runtime routing, data access tools, ETL ingestion, or Redshift warehouse DDL.

The slice outcome is:

eight KDS monitor specs migrated to curated.orders and curated.order_items,
source table references removed,
source-only fields replaced with curated fields,
store_guid and is_deleted requirements removed,
workflow logic migrated from kdsdev.item_bumps to curated.order_items workflow columns,
static blocked-term validation,
Redshift-backed dry-run validation or documented data-availability gaps.

Source Documents

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

Spec Name

The canonical documentation slice is named 04-kds-monitor-serving-contract-migration.

This implementation spec should be referred to as KDS Monitor Curated Contract Migration.

Fixed Decisions

Only the eight initial KDS monitors are in scope.
Migrated monitors may reference only curated.orders and curated.order_items.
kdsdev.*, staging, etl_meta, and other curated objects are not valid monitor query surfaces.
store_guid and is_deleted must be removed from monitor prompt requirements.
Raw unix epoch source fields must be replaced by curated timestamp fields.
item_bumps table logic must be replaced by workflow columns on curated.order_items.
Monitor thresholds and anomaly definitions should remain stable.
New curated contracts are not introduced in this slice.
Runtime routing changes remain in slice 03.
Full evaluation framework and non-KDS monitor migration remain follow-up work.

Scope

This task includes editing these files:

backend/Kds.Ai.Data/MonitorSpecs/prep-time.md
backend/Kds.Ai.Data/MonitorSpecs/order-surge.md
backend/Kds.Ai.Data/MonitorSpecs/large-order-wave.md
backend/Kds.Ai.Data/MonitorSpecs/priority-flood.md
backend/Kds.Ai.Data/MonitorSpecs/slow-kitchen.md
backend/Kds.Ai.Data/MonitorSpecs/station-bottleneck.md
backend/Kds.Ai.Data/MonitorSpecs/forgotten-items.md
backend/Kds.Ai.Data/MonitorSpecs/item-recall-storm.md

In short, this slice ends when those eight monitor specs no longer ask the data access agent to query source-shaped schemas and can run against tenant Redshift curated.

Out of Scope

The following items are explicitly excluded from this task:

anomaly detector runtime implementation,
tenant resolver implementation,
data access tool implementation,
ETL worker and ingestion API,
S3 raw/load/curated flow,
Redshift COPY or UNLOAD,
Athena and Glue,
new curated contracts,
POS, inventory, payments, forecasting, pricing, and customer monitor migration,
new monitor authoring UX,
full automated monitor evaluation framework,
cross-tenant monitor execution,
changing alert orchestration or monitor scheduling.

Task Checklist

Phase 1: Orders-Only Monitor Migration

[ ] TASK 1.1 - Migrate prep-time and order-surge
[ ] TASK 1.2 - Migrate large-order-wave and priority-flood

Phase 2: Orders and Items Monitor Migration

[ ] TASK 2.1 - Migrate slow-kitchen and station-bottleneck
[ ] TASK 2.2 - Migrate forgotten-items and item-recall-storm

Phase 3: Validation

[ ] TASK 3.1 - Add static blocked-term validation
[ ] TASK 3.2 - Run Redshift-backed dry-run validation

Dependency Graph

Prerequisites
    |-- Redshift Foundation complete
    |   +-- curated.orders contract
    |   +-- curated.order_items contract
    |-- Redshift Synthetic Data Feed complete
    |   +-- curated orders/order_items contain synthetic rows
    +-- Single-Store Redshift Runtime Read Path complete
        +-- data access tools query tenant Redshift curated

Phase 1 (Orders-Only Monitor Migration)
    |-- 1.1 prep-time and order-surge
    +-- 1.2 large-order-wave and priority-flood

Phase 2 (Orders and Items Monitor Migration)
    |-- 2.1 slow-kitchen and station-bottleneck
    +-- 2.2 forgotten-items and item-recall-storm

Phase 3 (Validation)
    |-- 3.1 Static blocked-term validation <-- (depends on Phase 1, Phase 2)
    +-- 3.2 Redshift-backed dry-run validation <-- (depends on 3.1)

Recommended Session Order

Session	Tasks	Description
1	1.1, 1.2	Migrate orders-only and mostly-orders monitor specs
2	2.1	Migrate station and kitchen monitors using orders plus item station fields
3	2.2	Migrate workflow-heavy item monitors
4	3.1	Run static source-reference validation and fix prompt leftovers
5	3.2	Run Redshift-backed dry-run validation and document data gaps

Key Design Decisions

Prompt Migration Only

This slice edits monitor spec content. It does not change runtime services, Redshift DDL, ETL, or tool implementation.

Curated Contract Is Fixed

The only allowed runtime tables are:

curated.orders
curated.order_items

If a monitor needs data outside those tables, it must remain out of scope or be documented for a later curated contract extension.

Preserve Monitor Semantics

Existing thresholds, sample-size rules, severity guidance, and monitor intent should remain stable unless a curated-contract semantic change requires a small wording adjustment.

Remove Source Cleanup Instructions

Curated already excludes soft-deleted rows and tenant scope comes from database routing. Monitor prompts should not ask for store_guid or is_deleted filters.

Workflow Columns Replace item_bumps

curated.order_items exposes latest workflow state. Monitors should use workflow_status_code, previous_workflow_status_code, prepared_at, and done_at instead of joining kdsdev.item_bumps.

Validation Is Two-Layered

Use static blocked-term checks to catch source-schema leftovers, then use Redshift-backed dry-runs to verify runtime prompt compatibility.