|
Download DECISIONS.md from Gaurav711/HyperFlow: direct link, hf CLI and curl.
- Browser
- Download file 6.26 kB
-
https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/DECISIONS.md
- Command line
-
hf download hf://spaces/Gaurav711/HyperFlow/DECISIONS.md
-
curl -L -o DECISIONS.md https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/DECISIONS.md
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. | |