# Eturns Complete Reference & Integration Blueprint
---
This is a flattened, single-file reference document detailing the complete technical architecture, data model schemas, row-level security parameters, and speculative AI racing algorithms running Eturns.

## 1. Architectural Vision
Eturns acts as an autonomous after-sales automation pipeline for high-scale Shopify merchants. It runs speculative racing models to bypass single-threaded LLM timeouts and uses Postgres row-level security (RLS) policies to keep tenant databases separate.

## 2. Row-Level Security (RLS) Specifications
All transactional data mirrors and active return tables enforce row-level security policies based on active merchant tenancies.
```sql
-- Example RLS Policy for Return Requests
CREATE POLICY shop_isolation ON return_requests
  FOR ALL
  USING (shop_id = current_setting('app.current_shop_id', true));
```
Before executing queries, the runtime adapter must invoke:
```sql
SET LOCAL app.current_shop_id = 'target-shop-id';
```

## 3. Speculative AI Racing Pipeline
To avoid Vercel serverless function timeouts and provide instant customer resolution speeds (<2.5s), Eturns utilizes a speculative racing paradigm:
1. Upon returns submission, the storefront immediately decodes and pre-authorizes credit holds via Stripe/Razorpay (BYOG).
2. Concurrently, `Promise.race()` is initiated comparing: 
   - a high-accuracy, speculative Claude 3.5 Sonnet agent pipeline.
   - a fast, deterministic local heuristics rule-engine.
3. If the local heuristics engine fires first with high confidence, or if Claude returns early, the alternate thread is aborted using an `AbortSignal`.
4. Transactions are fully decoupled from AI network scopes. LLM calls execute outside `withRequestScope` transactional closures, preventing Postgres advisory lock hangs.

## 4. Ingest, Admin & Restocking Endpoints
- **Ticket Ingestion** (`POST /api/v1/ingest/tickets`): Receives customer messages, performs sentiment indexing, and registers triage slots.
- **Returns Resolution** (`POST /api/v1/admin/returns/:id/decide`): Merchant-decide endpoint that approves, declines, or triggers gift card bonus credits (BCRE).
- **Merchant Inspection** (`POST /api/v1/admin/returns/:id/inspect`): Commits items restocking fee and warehouse location parameters, then enqueues synchronized `returnProcess` outbox queue mutations to update Shopify in real-time.
- **Policy Auto-Calibration** (`POST /api/admin/policy-retrieve`): Automates scraping brand return policies from Shopify Admin APIs and parsing guidelines using Sonnet 3.5, saving parameters in 1-click.