Create new production release

.agents/skills/sentry-vortex/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: sentry-vortex
+description: Audit code against Vortex's Sentry conventions and guide correct error instrumentation. Triggers on: sentry, captureException, error reporting, error monitoring, beforeSend, ignoreErrors, adding an API service method, new error class, new XState machine error handling, ErrorBoundary, "is this reported to Sentry".
+user-invocable: true
+argument-hint: "[files or 'current changes' — defaults to the working-tree diff]"
+---
+
+Audit changed code against Vortex's established Sentry conventions and report violations with concrete fixes; also the authority for how to instrument new code correctly.
+
+## MANDATORY PREPARATION
+
+1. Read the canonical implementation so you check against real code, not memory:
+   - `apps/frontend/src/helpers/sentry.ts`
+   - `apps/frontend/src/services/api/api-client.ts`
+   - `apps/frontend/src/machines/ramp.machine.ts`
+2. Determine scope: the argument, or `git diff --name-only HEAD` if blank.
+
+---
+
+## Diagnostic Scan
+
+Check each rule. Report a finding only when violated.
+
+### Configuration (single source of truth)
+- All filtering lives in `helpers/sentry.ts`. New ignore/deny/scrub logic edits that file — **NEVER** inline new filter config into `Sentry.init` in `main.tsx`.
+- `environment: config.env` (never `config.isProd ? ... : ...`). Sampling stays prod-gated.
+- Session Replay keeps `maskAllText: true` + `blockAllMedia: true`.
+
+### Error classes
+- A custom `Error` whose failures should be filterable by business area **must** `implements DomainError` and set `domain`. API errors derive it from `getApiDomain()` (the source of truth for domain values); non-API errors set it directly (e.g. `SignRampError` → `wallet`).
+
+### API layer (`services/api/`)
+- A new top-level path segment (e.g. `/payouts/...`) **must** be added to `getApiDomain()`.
+- `ApiError` messages run through `normalizePath()` — **CRITICAL**: never interpolate raw ids/addresses into an error message or Sentry tag; it fragments grouping and can leak PII.
+
+### Capture points
+- Money-flow / machine failures are captured at the machine's terminal error state (`captureActorError` pattern), skipping `SignRampError` `UserRejected`.
+- **NEVER** call `Sentry.captureException` inside React components, render paths, or fetch/TanStack-Query interceptors — let errors propagate to the machine error state or the global handler.
+- Risky subtrees (widget/KYC/ramp) are wrapped in `Sentry.ErrorBoundary` with a fallback.
+
+### Noise & privacy
+- `ignoreErrors` covers wallet user-rejections, `ResizeObserver` loops, extension-context errors, `AbortError`. **IMPORTANT**: keep `TimeoutError` reportable — a timeout can mean a slow backend.
+- `beforeSend` drops expected client 4xx (`401/403/404/409/429`); `400/422` and all `5xx` are kept.
+- No PII in query params, tags, contexts, or messages — `beforeSend` strips query strings, but new code must not route PII somewhere it can't reach.
+- **User context**: `Sentry.setUser` is set/cleared only in `AuthService` (plus a startup seed in `main.tsx`) and carries the **pseudonymous Supabase id only** (`{ id: userId }`) — **NEVER** email, wallet, or IP. New auth code must keep this invariant.
+
+## Generate Report
+
+Group findings by file, `file:line`, each with the violated rule and a concrete fix. End with a one-line compliance verdict.
+
+```
+## apps/frontend/src/services/api/payouts.service.ts
+payouts.service.ts:14 - new "/payouts" segment not mapped in getApiDomain() → add case "payouts": return "ramp"
+
+## apps/frontend/src/components/Foo.tsx
+Foo.tsx:88 - Sentry.captureException in a component → remove; let it propagate to the machine Error state
+
+Verdict: 2 violations — not compliant.
+```
+
+**NEVER:**
+- Report a violation without the exact fix.
+- Flag `Sentry.captureException` at the sanctioned capture point (`captureActorError`) as a violation.
+- Recommend blanket-ignoring `Failed to fetch` / `NetworkError` / `Loading chunk failed` — monitor volume first.
+- Recommend adding `SENTRY_AUTH_TOKEN` or `VITE_ENVIRONMENT` in code — they are Netlify build env vars; flag as infra TODOs only.
+
+## Verify Audit
+
+- Every changed `services/api/`, error class, and XState machine error path was checked.
+- Every finding has a `file:line` and a fix.
+- No false positives against the sanctioned patterns in the canonical files.
+
+A trustworthy Sentry is one where every reported issue is real and actionable — audit to keep noise out and signal in.

.agents/skills/vortex-integration/SKILL.md

@@ -503,7 +503,7 @@ try {
 ## Current corridor reality (May 2026)
 - **BRL via PIX**: onramp and offramp both live.
 - **EUR via SEPA**: SDK types exist (`EurOnrampQuote`, `EurOfframpQuote`) but handlers throw `"Euro onramp/offramp handler not implemented yet"` at runtime. Treat as `planned`.
-- **ARS via CBU**: offramp only.
+- **ARS via CBU**: supported via the AlfredPay corridor; route resolver determines availability per-combination.
 - **USD / MXN / COP via ACH / SPEI / WIRE**: supported via the AlfredPay corridor; route resolver determines availability per-combination.
 
 ## Common failures

.github/workflows/ci.yml

@@ -39,3 +39,56 @@ jobs:
 
       - name: ✏️ Typecheck
         run: bun run typecheck
+
+  test:
+    name: Running tests
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: vortex_test
+        ports:
+          - 54329:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - name: 🛒 Checkout code
+        uses: actions/checkout@v3
+
+      - name: 🧩 Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.1
+
+      - name: 🧩 Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: 🔨 Build shared package
+        run: bun run build:shared
+
+      - name: 🧪 Shared tests (coverage-gated)
+        run: cd packages/shared && bun run test:coverage
+
+      - name: 🧪 SDK tests
+        run: bun run test:sdk
+
+      - name: 🧪 SDK coverage gate
+        run: cd packages/sdk && bun run test:coverage
+
+      - name: 🧪 Rebalancer tests (coverage-gated)
+        run: cd apps/rebalancer && bun run test:coverage
+
+      - name: 🧪 API tests (unit + integration, coverage-gated)
+        run: cd apps/api && bun run test:coverage
+
+      - name: 🧪 Frontend tests (coverage-gated)
+        run: cd apps/frontend && bun run test:coverage

.github/workflows/e2e.yml

@@ -0,0 +1,62 @@
+# Non-PR-blocking Playwright E2E journeys (see docs/testing-strategy.md).
+# Runs nightly and on demand; failures alert but never gate merges.
+name: e2e
+
+on:
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+jobs:
+  e2e:
+    name: Playwright E2E journeys
+    runs-on: ubuntu-latest
+    env:
+      CI: true
+
+    steps:
+      - name: 🛒 Checkout code
+        uses: actions/checkout@v3
+
+      - name: 🧩 Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.1
+
+      - name: 🧩 Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: 🔨 Build shared package
+        run: bun run build:shared
+
+      - name: 🌐 Install Playwright browsers
+        working-directory: apps/frontend
+        run: bunx playwright install --with-deps chromium
+
+      - name: 🧪 E2E journeys
+        working-directory: apps/frontend
+        run: bun run test:e2e
+
+      - name: 📤 Upload report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: apps/frontend/playwright-report/
+          retention-days: 7
+
+      # Non-blocking runs are only useful if somebody hears about failures.
+      # Uses the same webhook token the backend's Slack notifier uses
+      # (repo secret SLACK_WEB_HOOK_TOKEN); skips silently when unset.
+      - name: 📣 Notify Slack on failure
+        if: failure()
+        env:
+          SLACK_WEB_HOOK_TOKEN: ${{ secrets.SLACK_WEB_HOOK_TOKEN }}
+        run: |
+          if [ -z "$SLACK_WEB_HOOK_TOKEN" ]; then
+            echo "SLACK_WEB_HOOK_TOKEN secret not configured; skipping notification."
+            exit 0
+          fi
+          curl -sf -X POST -H 'Content-Type: application/json' \
+            -d "{\"text\":\"Nightly Playwright e2e run failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\"}" \
+            "https://hooks.slack.com/services/${SLACK_WEB_HOOK_TOKEN}"

.gitignore

@@ -12,8 +12,11 @@ dist
 dist-ssr
 *.local
 
+# Coverage reports (any workspace; bun/vitest lcov output)
+coverage
+
 # Environment files (any package, any name)
-**/.env
+packages/sdk/.env
 **/.env.local
 **/.env.*.local
 **/.env.development
@@ -57,5 +60,74 @@ CLAUDE.local.md
 # hardhat generated files in workspace contract projects
 contracts/*/artifacts
 contracts/*/cache
+contracts/*/.env
+
+.mcp.json
+
+# Playwright E2E artifacts
+apps/frontend/test-results/
+apps/frontend/playwright-report/
 
-.mcp.json
+# Local credentials and agent-tool artifacts
+.api-key.json
+.playwright-mcp/
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/IERC20Errors.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/IERC721Errors.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/IERC1155Errors.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/interfaces/IERC1363.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/interfaces/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/extensions/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/utils/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/utils/SafeERC20.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/ERC20.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/IERC20.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/ERC20/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/token/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/utils/introspection/IERC165.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/utils/introspection/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/utils/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/utils/ReentrancyGuard.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/contracts/index.ts
+/contracts/cctp-settlement/typechain-types/@openzeppelin/index.ts
+/contracts/cctp-settlement/typechain-types/contracts/interfaces/index.ts
+/contracts/cctp-settlement/typechain-types/contracts/interfaces/ITokenMessengerV2.ts
+/contracts/cctp-settlement/typechain-types/contracts/mocks/index.ts
+/contracts/cctp-settlement/typechain-types/contracts/mocks/MockERC20.ts
+/contracts/cctp-settlement/typechain-types/contracts/mocks/MockTokenMessengerV2.ts
+/contracts/cctp-settlement/typechain-types/contracts/index.ts
+/contracts/cctp-settlement/typechain-types/contracts/PerUserCctpSettlement.ts
+/contracts/cctp-settlement/typechain-types/contracts/PerUserCctpSettlementFactory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/IERC20Errors__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/IERC721Errors__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/IERC1155Errors__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/interfaces/draft-IERC6093.sol/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/interfaces/IERC1363__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/interfaces/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/extensions/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/utils/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/utils/SafeERC20__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/ERC20__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/IERC20__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/ERC20/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/token/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/utils/introspection/IERC165__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/utils/introspection/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/utils/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/utils/ReentrancyGuard__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/contracts/index.ts
+/contracts/cctp-settlement/typechain-types/factories/@openzeppelin/index.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/interfaces/index.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/interfaces/ITokenMessengerV2__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/mocks/index.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/mocks/MockERC20__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/mocks/MockTokenMessengerV2__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/index.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/PerUserCctpSettlement__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/contracts/PerUserCctpSettlementFactory__factory.ts
+/contracts/cctp-settlement/typechain-types/factories/index.ts
+/contracts/cctp-settlement/typechain-types/common.ts
+/contracts/cctp-settlement/typechain-types/hardhat.d.ts
+/contracts/cctp-settlement/typechain-types/index.ts

apps/api/bunfig.toml

@@ -0,0 +1,18 @@
+[test]
+# Only discover tests under src/ — the swc build in dist/ contains compiled
+# copies of test files that would otherwise run (stale) a second time.
+root = "src"
+preload = ["./src/test-utils/preload.ts"]
+
+# Coverage report config; the gate itself lives in scripts/check-coverage.ts.
+# Excluded from the denominator: built/foreign packages (sdk has its own suite),
+# migrations (run-once DDL), and generated contract ABIs (const data, always "covered").
+coverageSkipTestFiles = true
+coveragePathIgnorePatterns = [
+  "**/packages/shared/dist/**",
+  "**/packages/sdk/**",
+  "**/test-utils/**",
+  "**/database/migrations/**",
+  "**/src/contracts/**"
+]
+

apps/api/package.json

@@ -95,7 +95,10 @@
     "seed:phase-metadata": "bun -r @swc-node/register src/database/seeders/phase-metadata.ts",
     "serve": "bun dist/index.js",
     "start": "bun run build && bun run serve",
-    "test": "bun test"
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov && bun ../../scripts/check-coverage.ts coverage/lcov.info 0.55 0.64",
+    "test:db:start": "./scripts/test-db.sh start",
+    "test:db:stop": "./scripts/test-db.sh stop"
   },
   "version": "1.0.0"
 }

apps/api/scripts/test-db.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Manages the dedicated Postgres container for integration tests.
+set -euo pipefail
+
+CONTAINER=vortex-test-db
+PORT="${TEST_DB_PORT:-54329}"
+
+case "${1:-start}" in
+  start)
+    if docker ps -a --format '{{.Names}}' | grep -q "^${CONTAINER}$"; then
+      docker start "$CONTAINER" >/dev/null
+    else
+      docker run -d --name "$CONTAINER" \
+        -e POSTGRES_PASSWORD=postgres \
+        -e POSTGRES_DB=vortex_test \
+        -p "${PORT}:5432" \
+        postgres:16-alpine >/dev/null
+    fi
+    for _ in $(seq 1 30); do
+      if docker exec "$CONTAINER" pg_isready -U postgres >/dev/null 2>&1; then
+        echo "test db ready on port ${PORT}"
+        exit 0
+      fi
+      sleep 1
+    done
+    echo "test db failed to become ready" >&2
+    exit 1
+    ;;
+  stop)
+    docker rm -f "$CONTAINER" >/dev/null
+    echo "test db removed"
+    ;;
+  *)
+    echo "usage: $0 [start|stop]" >&2
+    exit 1
+    ;;
+esac