# HyperFlow integration contract This is the wiring and boundary map, not a live-provider certification. Actual passing evidence is in [status](docs/flagship/status.md). API schemas exposed by `/docs` and current source remain authoritative for field details. ## Runtime and surfaces ```mermaid flowchart TD UI[React / Vite workspace] -->|Bearer session / api/v2| API[FastAPI] API --> DB[(PostgreSQL authoritative state)] Worker[Durable worker] --> DB Worker -. optional notification .-> Redis[Redis] API -->|account credential / explicit live mode| MCP[Swiggy MCP] API -->|explicit replay mode| Sim[Isolated simulations] API -->|authenticated SSE cursor| UI ``` Entrypoint: `backend/api/main.py` calls the flagship app factory. `frontend/src/App.jsx` currently maps public routes to the persisted, source-labelled `FlagshipPages` implementations: agent, store, BasketOps, delivery/courier, intelligence, guard, site scenarios, analytics, replay and case study. Earlier prototype page files remain in source. `/dev/*` aliases also exist; testing only aliases does not replace exercising user-facing routes. The app also mounts public geo metadata with descriptive capability boundaries. Account-owned operations require authentication. Direct compatibility checkout returns 409 and directs users through reviewed proposals; compatibility weather/forecast/health endpoints return labelled UNAVAILABLE empty states. Legacy catch-all routes generally return 410, with explicitly declared exceptions such as health/retraining. Do not infer universal provider coverage from a v2 prefix. The worker processes persisted training jobs and outbox notifications. `/health` checks the API; `/ready` checks schema/database and worker freshness. Redis loss must not erase jobs or SSE history. ## Authentication and provider credentials HyperFlow login is distinct from Swiggy authorization. Ordinary registration receives a server-assigned user role; administrator/operator/courier roles are provisioned. Public reviewer accounts are isolated simulations with no live-provider or paid-model authority. Opaque sessions are stored server-side; the frontend retains its session token in browser storage and sends `Authorization: Bearer …`. Reload validation must not confuse an offline network error with proven session expiry. Clear account-scoped UI state when switching accounts. Real credentials are encrypted with account-bound authenticated encryption and a persistent `VAULT_SECRET_KEY`. Store/refresh/disconnect operations never return token plaintext. Provider failures must not downgrade a live request to simulation. Required Phase 1 contract: | Operation | Meaning | | --- | --- | | `POST /api/v2/provider/credentials` | Store this account's supplied access token and optional refresh/expiry metadata; storage does not establish validity | | `GET /api/v2/provider/credentials` | Return `configured`, `verification_status`, `verified_at`, `expiry_known`, and nullable `expires_at`; never fabricate expiry | | `DELETE /api/v2/provider/credentials` | Disconnect this account; invalidate its verification evidence | | `POST /api/v2/provider/verify` with `{ "provider": "im" }` | Read-only authenticated discovery; return status without exposing addresses or tokens | | `POST /api/v2/provider/refresh` | Refresh current credentials safely; rotating replacements cannot overwrite a concurrent user replacement | | Swiggy authorize-url/callback | Registered client ID, exact configured redirect, expiring single-use state and PKCE; reject mismatch/replay | The verification addition and revised fields are present in current source; passing verification still requires current test evidence. Verification must bind to the current credential version; an old successful response cannot verify a replacement token. Outage/rate-limit failures do not prove credential revocation. Current [Swiggy authentication documentation](https://mcp.swiggy.com/builders/docs/start/authenticate/) describes refresh support. Read actual response expiry and rotating refresh token values; unknown manual-token expiry stays unknown. Do not fabricate a refresh token from an access token. Verify provider names, schemas, error codes and limits against current official documentation before modifying integrations. ## Commerce sequence and contracts 1. Parse/edit intent with `/api/v2/baskets/parse`; discover and plan with `/api/v2/provider/read`, `/provider/discover` and `/baskets/plan`. `/baskets/optimize` validates structured inputs. 2. Create `/api/v2/proposals`, inspect the exact version and amounts, then approve at `/api/v2/actions/{proposal_id}/approve` with its version. 3. Execute `/api/v2/actions/{action_id}/execute` using `Idempotency-Key`. Reusing a key with different content conflicts. Persist the attempt before external mutation. 4. Fetch current provider cart and compare approval binding. Changed data produces a revised proposal; no silent removal, substitution or quantity change. 5. Persist validated success/receipt, failure or uncertainty. Inspect `/api/v2/actions/{action_id}` and use `/reconcile` when appropriate. A lost order response is never a reason for blind placement retry. 6. Subscribe to `/api/v2/events`, retaining event IDs; reconnect with `Last-Event-ID` or `after`. Scope history and authorization to the account, revalidate sessions and deduplicate events in consumers. States include `PROPOSED`, `APPROVED`, `EXECUTING`, `SUCCEEDED`, `FAILED`, `UNKNOWN` and `SUPERSEDED`; only validated evidence permits success. Provider payment-pending evidence must remain pending. Purchases and bookings are outside the current ₹0 verification campaign. ## Jobs, models and operations Training submission returns 202 and a durable job. The implemented lifecycle includes `EVALUATED` before explicit administrator promotion; queued/running/insufficient/rejected/failed states remain distinct. Worker restart resumes persisted work with bounded attempts. `/api/v2/models` identifies serving state; promotion and rollback require administrator authority. Candidate manifests carry immutable dataset, schema, configuration and artifact identities. Delivery enrollment, assignment, telemetry, transitions, reviews and economic inputs use `/api/v2/operations/*`; read [operations assumptions](docs/flagship/operations.md). Provider tracking grants no authority over provider couriers. Synthetic weather, coupon, health or demand values must never appear as live observations. ## Verification matrix | Boundary | Required evidence | Current restriction | | --- | --- | --- | | API ↔ database | Isolated migration, restart, account isolation and concurrency tests | SQLite results do not establish PostgreSQL semantics | | API ↔ provider | Schema fixtures plus separately captured live read receipts | Live discovery pending supplied token; no live transaction certification | | Browser ↔ API | Actual mounted-route tests, reload/account switch, offline and SSE recovery | Historical browser reports need current reproduction | | Worker ↔ model registry | Failed write/promotion, exact artifact, rollback, concurrent serving | Historical study results do not certify current serving | | Operations ↔ user workflow | Assignment/review tests and volunteer tasks | No customer-scale fleet or merchant evidence | ## Durable model turns and serving qualification Authenticated `/api/v2/agent/turns` and `/api/v2/agent/turns/{record_id}` expose only the account's persisted turn records. A stable turn ID binds the payload: completed retries return the saved response; payload changes conflict; incomplete/failed turns require inspection and an explicit new attempt. Checkpoints do not implement automatic continuation of a partially executed model loop. Model budgets count physical outbound requests, including failed requests. Global campaign and account limits apply. Both model-enable and free-quota-confirmation flags are required. Deadlines are cooperative; provider calls already in flight can exceed the turn deadline. ML studies do not become serving candidates without both explicit quality thresholds and exact-artifact verification.