# HyperFlow architecture decisions Date: 20 October 2026. This register records design intent and inspected implementation; passing status belongs in [status](docs/flagship/status.md). Updates append or explicitly supersede decisions. ## ADR-001 — PostgreSQL owns durable state **Context:** proposals, approvals, action attempts, receipts, jobs and events must survive process and notification loss. **Alternatives:** process memory; Redis authority; distributed Kafka services; a relational service with transactional events. **Decision:** use PostgreSQL as authority, one API and one worker. Persist record changes with domain events. Redis is an optional notification accelerator; durable event cursors recover missed notifications. SQLite/file locks support isolated demonstrations, not proof of PostgreSQL concurrency. **Consequences:** fewer moving parts and ₹0 local deployment; correctness depends on transaction/locking tests and database recovery. Current outbox notification delivery can repeat, so consumers must deduplicate event IDs. **Evidence:** `backend/flagship/store.py`, `worker.py`; separate PostgreSQL suite and restart protocol in [methodology](docs/benchmark_methodology.md). ## ADR-002 — Explicit simulation and scoped identity **Context:** provider access is intermittent and replay demonstrations must remain reproducible without pretending to be live. **Alternatives:** shared environment token; anonymous guest identity; silent simulation fallback; isolated explicit workspaces. **Decision:** database-backed opaque sessions, server-assigned roles and account-bound encrypted provider credentials. Reviewer workspaces use labelled simulations. A live authentication failure stays a failure. Saving a real token requires a configured persistent encryption key even in demonstration mode. **Consequences:** local session persistence currently uses browser storage and Authorization headers; XSS is a security boundary. No cookie/session-hardening claim is implied. Unknown token expiry stays unknown. Successful storage is not successful provider verification. **Evidence:** identity/provider/API regressions; [integration contract](INTEGRATION.md). Supersedes historical shared-token and no-refresh instructions. ## ADR-003 — Proposal approval is backend authority **Context:** prices, addresses and shared carts can change between planning and mutation. Instamart cart updates replace the cart. **Alternatives:** prompt-only approval; direct model mutation; approval of a vague intent; exact versioned proposal. **Decision:** validate exact account, provider, address, payload, cart snapshot and displayed total; serialize account/provider mutations; re-read provider state and require renewed approval after material changes. Local idempotency keys bind payloads and return durable outcomes. **Consequences:** more user interaction after changes, but no silent substitution. Lost responses can leave UNKNOWN and require receipt reconciliation. Local locks and keys do not create upstream idempotency. **Evidence:** `commerce.py`, journey/failure suites; [Swiggy execution guidance](https://mcp.swiggy.com/builders/docs/build/ship-to-production/). ## ADR-004 — Grounded optimization before model fluency **Context:** an eloquent answer cannot compensate for invalid quantities or invented catalogue values. **Alternatives:** model-built catalogue and basket; cheapest-per-unit greedy selection; deterministic constraints with optional intent extraction. **Decision:** preserve provider variants, validate units and constraints, minimize exact cost then normalized excess, compare with a feasible single-variant baseline. Use exhaustive small cases as oracle. Ambiguity produces clarification. **Consequences:** bounded solver evaluation cannot prove arbitrary-scale optimal performance; model assistance must demonstrate incremental value. No cross-unit physical quantities are summed. **Evidence:** `basket.py`, `parsing.py`; frozen solver/parser gates in [methodology](docs/benchmark_methodology.md). ## ADR-005 — Bound and measure the custom AI loop **Context:** tool outputs are untrusted and model calls can cost money or repeat work. **Alternatives:** framework adoption for branding; unrestricted tool loop; rules-only; bounded optional model extraction and read tools. **Decision:** retain the custom loop, enforce limits and mutation boundaries in code, persist useful checkpoints, compare against rules. Freeze ten tool steps, three model requests and 60 seconds per turn; twenty requests/day and 120/campaign on verified free quota. These are required limits until verified, not a statement that current code enforces all of them. **Consequences:** no paid runs in default verification. A failed model experiment may leave rules as the shipping default. Historical LangGraph naming is not proof of LangGraph orchestration. ## ADR-006 — Separate real retail forecasting from censoring research **Context:** public sales do not reveal lost demand or stockouts. **Decision:** UCI Online Retail II remains GBP retail research with chronological baselines. Test Tobit recovery separately using known latent labels and controlled censoring. The previously inspected final period is exposed; it cannot become an unseen holdout again. **Consequences:** claims are narrower and defensible. Promote the exact evaluated artifact only after meaningful configured gates, successful persistence and serving verification. Failed candidates preserve the active artifact. **Evidence:** [retail report](docs/flagship/retail-results.json), [censoring report](docs/flagship/censoring-results.json); current reproduction remains a separate release gate. ## ADR-007 — Delivery evidence precedes FDE and scale claims **Decision:** one volunteer pilot, reproducible deployment, incident drill and restore drill establish bounded delivery evidence. Doctor/trace are diagnostic aids. Local load, simulation and pilot findings retain their environment and sample limits. **Consequences:** no enterprise readiness, customer-scale adoption, business savings, fraud accuracy or high-throughput claim without matching evidence. Preserve surfaces but flag unaudited compatibility paths explicitly.