HyperFlow / DECISIONS.md
Gaurav711's picture
Deploy 891f179
2b86c60 verified
|
Raw History Blame Contribute Delete
6.26 kB
# 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.