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. 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.

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. 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.

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.

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, censoring report; 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.