chore(deps): Bump actions/setup-node from 4 to 7

Bumps [actions/setup-node](https://github.com/actions/setup-node) from 4 to 7. - [Release notes](https://github.com/actions/setup-node/releases) - [Commits](https://github.com/actions/setup-node/compare/v4...v7) --- updated-dependencies: - dependency-name: actions/setup-node dependency-version: '7' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com>
2026-07-16 01:34:03 +00:00
43 changed files with 862 additions and 4516 deletions
@@ -22,18 +22,3 @@ DEMO_MODE=false

 # Feed recorder (NDJSON to data/)
 RECORD_FEED=false
-
-# API docs — Scalar at GET /api-docs (OpenAPI generated from Zod; no env vars required)
-
-# Observability — https://sentry.io (project: arbpulse)
-SENTRY_DSN=
-# Tracing/spans gate — default off. Error monitoring is always on when SENTRY_DSN
-# is set; spans are only created/exported when SENTRY_TRACING is enabled. Kept off
-# by default so 24/7 operation stays within Sentry's free-tier span quota.
-SENTRY_TRACING=false
-# Structured logs (pino); correlation IDs on REST, SSE, and WS hot path
-LOG_LEVEL=info
-
-# Upstash Redis — rate limit on /api/* and short-TTL snapshot cache for GET /api/state
-UPSTASH_REDIS_REST_URL="https://natural-baboon-144595.upstash.io"
-UPSTASH_REDIS_REST_TOKEN="gQAAAAAAAjTTAAIgcDE0MDk4MGZlOWMwN2M0NTdiOWQ5MWYxMjVhOWMyNWVlZQ"
@@ -21,7 +21,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
        with:
          node-version: "20"
          cache: npm
@@ -1,30 +0,0 @@
-name: CodeQL Security Scan
-
-on:
-  push:
-    branches: [main, dev]
-  pull_request:
-    branches: [main, dev]
-  schedule:
-    - cron: "0 8 * * 1"
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: github/codeql-action/init@v3
-        with:
-          languages: javascript-typescript
-          queries: security-extended
-
-      - uses: github/codeql-action/autobuild@v3
-
-      - uses: github/codeql-action/analyze@v3
@@ -1,45 +0,0 @@
-name: E2E Smoke
-
-on:
-  push:
-    branches: [main, dev]
-  pull_request:
-    branches: [main, dev]
-
-jobs:
-  smoke:
-    name: Playwright dashboard + SSE
-    runs-on: ubuntu-latest
-    env:
-      DEMO_MODE: "true"
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm
-          cache-dependency-path: |
-            package-lock.json
-            web/package-lock.json
-
-      - run: npm ci
-      - run: npm --prefix web ci
-      - run: npm run build
-
-      - name: Start server
-        run: npm start &
-
-      - name: Wait for API
-        run: |
-          for i in $(seq 1 45); do
-            curl -sf http://localhost:8080/api/health > /dev/null && echo "Ready after ${i}s" && exit 0
-            sleep 1
-          done
-          echo "::error::Server did not become ready in 45s" && exit 1
-
-      - run: npx playwright install --with-deps chromium
-
-      - name: Run smoke tests
-        run: npm run test:e2e
@@ -1 +0,0 @@
-npx lint-staged
@@ -1,6 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": false,
-  "trailingComma": "all",
-  "tabWidth": 2
-}
@@ -301,9 +301,9 @@ Respuestas REST siguen la forma `{ success, data?, error? }`.
 | `POST` | `/api/control/record` | `{ "enabled": boolean }` — grabación NDJSON en `data/` |
 | `POST` | `/api/control/threshold` | `{ "pct": number }` (atajo de `PATCH /api/config`) |
 | `POST` | `/api/control/max-trade` | `{ "btc": number }` (atajo de `PATCH /api/config`) |
-| `GET` | `/api-docs` | **Scalar** — documentación interactiva OpenAPI 3.0 |
+| `GET` | `/api-docs` | **Swagger UI** — documentación interactiva OpenAPI 3.0 |

-Contrato generado desde Zod (`src/interfaces/http/schemas/`) con `@asteasolutions/zod-to-openapi`; registro de rutas en `src/interfaces/http/openapi.ts`.
+Contrato completo y schemas en `src/interfaces/http/openapi.ts`.

 ---

@@ -343,17 +343,6 @@ Eso no indica que el bot “no funcione”: indica que el filtro económico es e

 ---

-## Production practices
-
- **Pre-commit:** Husky runs lint-staged (`eslint --fix`, `prettier --write`) on staged `*.ts` / `*.tsx` in `src/` and `web/src/`.
- **API contracts:** Zod schemas per REST endpoint → OpenAPI via `@asteasolutions/zod-to-openapi` → Scalar UI at `/api-docs`. Request bodies validated with Zod in route handlers.
- **Observability:** `@sentry/node` captures REST, WebSocket feed, and SSE errors (always on when `SENTRY_DSN` is set); `pino` JSON logs with `correlationId` (from `x-request-id` or per book tick); OpenTelemetry spans (`ws.message` → `orderbook.process` → `arbitrage.evaluate` → `sse.broadcast`) export to Sentry via `@sentry/opentelemetry` **only when `SENTRY_TRACING` is enabled** (default off, so 24/7 operation stays within the free-tier span quota). With tracing off the tracer is a no-op — no spans are created or exported — but errors are still captured. Dev probe: `GET /api/debug/sentry`; verify with `npm run test:observability`.
- **Rate limiting & cache:** Upstash sliding-window limits per IP on read/write/SSE routes (`429` + `Retry-After`). Latest `StateSnapshot` cached in Redis (~1s TTL) for `GET /api/state` and refreshed on SSE broadcast. Set `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`. Verify with `npm run test:rate-limit`.
- **CI:** GitHub Actions quality pipeline (typecheck, unit tests, build); Playwright smoke on PRs — dashboard loads and SSE connects (`npm run test:e2e`, workflow `e2e.yml`, `DEMO_MODE=true` in CI).
- **Security scanning:** CodeQL (`.github/workflows/codeql.yml`); Dependabot for npm (root + `web/`) and GitHub Actions.
-
---
-
 ## Licencia

 MIT — ver archivo `LICENSE` cuando se añada al repositorio.
@@ -1,8 +0,0 @@
-import { test, expect } from "@playwright/test";
-
-/** Asserts the dev Sentry probe responds; does not verify ingest in sentry.io (see README). */
-test("sentry dev probe returns ok", async ({ request }) => {
-  const res = await request.get("/api/debug/sentry");
-  expect(res.ok()).toBeTruthy();
-  await expect(res.json()).resolves.toMatchObject({ ok: true });
-});
@@ -1,19 +0,0 @@
-import { test, expect } from "@playwright/test";
-
-test("dashboard loads", async ({ page }) => {
-  await page.goto("/");
-  await expect(page.getByRole("heading", { name: /ArbPulse/i })).toBeVisible();
-});
-
-test("SSE stream connects and delivers engine state", async ({ page, request }) => {
-  const health = await request.get("/api/health");
-  expect(health.ok()).toBeTruthy();
-
-  await page.goto("/");
-  await expect(page.getByText("Connecting to engine…")).toBeHidden({
-    timeout: 45_000,
-  });
-  await expect(page.getByText("LIVE", { exact: true })).toBeVisible();
-  await expect(page.getByText("RUNNING")).toBeVisible();
-  await expect(page.getByText("Realized P&L")).toBeVisible();
-});
@@ -1,31 +0,0 @@
-import eslint from "@eslint/js";
-import reactHooks from "eslint-plugin-react-hooks";
-import globals from "globals";
-import tseslint from "typescript-eslint";
-
-export default tseslint.config(
-  { ignores: ["web/dist/**", "data/**", "**/node_modules/**"] },
-  {
-    files: ["src/**/*.ts"],
-    extends: [eslint.configs.recommended, ...tseslint.configs.recommended],
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: "module",
-      globals: globals.node,
-    },
-  },
-  {
-    files: ["web/src/**/*.{ts,tsx}"],
-    extends: [eslint.configs.recommended, ...tseslint.configs.recommended],
-    plugins: { "react-hooks": reactHooks },
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: "module",
-      globals: globals.browser,
-      parserOptions: { ecmaFeatures: { jsx: true } },
-    },
-    rules: {
-      ...reactHooks.configs.recommended.rules,
-    },
-  },
-);
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-07-16
@@ -1,34 +0,0 @@
-## Context
-
-`src/instrumentation/otel.ts` builds a tracer that, when `SENTRY_DSN` is set, registers a `NodeTracerProvider` with `SentrySpanProcessor`/`SentryPropagator`, so every `withSpan(...)` call on the hot path creates and exports a span to Sentry. `src/instrumentation/sentry.ts` sets `tracesSampleRate` unconditionally. Running 24/7 on a VPS multiplies span volume against Sentry's free-tier quota (5M spans/month), while error events stay small. We want tracing to remain a debugging option but be off by default.
-
-## Goals / Non-Goals
-
-**Goals:**
- Add a single boolean env var (`SENTRY_TRACING`, default `false`) that turns span creation/export on or off.
- Default behavior emits zero spans and zero hot-path span allocation.
- Preserve error monitoring exactly as-is regardless of the flag.
- No dependency changes; no API/wire changes.
-
-**Non-Goals:**
- Removing OpenTelemetry or the `withSpan` abstraction.
- Making `tracesSampleRate` itself env-configurable (kept as current 0.1 prod / 1 dev when enabled).
- Changing which operations are wrapped.
-
-## Decisions
-
- **Boolean gate over sample-rate gate.** A boolean `SENTRY_TRACING` that makes the tracer a no-op avoids hot-path span allocation entirely when off (aligns with the "no unnecessary alloc on the hot path" convention). A `tracesSampleRate=0` approach would still register the provider and create spans that are dropped later — more overhead. Alternative considered and rejected.
- **Gate lives in `otel.ts` init.** `initOpenTelemetry()` returns the no-op `trace.getTracer("arbpulse")` unless both `SENTRY_DSN` and `SENTRY_TRACING` are truthy. This keeps `withSpan`'s signature and all call sites unchanged; its `catch` still calls `Sentry.captureException`, so errors are captured even with a no-op span.
- **Conditional `tracesSampleRate` in `sentry.ts`.** Only set `tracesSampleRate` when tracing is enabled; omit it otherwise so Sentry performance is fully off. A shared helper `isTracingEnabled()` reads the flag so both files agree.
- **Parsing.** Reuse the existing truthy convention (`"1"` or `"true"`, case-insensitive) used by `config.ts`'s `bool()` for consistency; implement locally in the instrumentation module since it initializes before `config` import.
-
-## Risks / Trade-offs
-
- [Someone enables tracing in prod and hits the quota] → Documented in `.env.example`/README that it is off by default and why; enabling is an explicit opt-in.
- [Flag read in two files could drift] → Centralize in one `isTracingEnabled()` helper exported from the instrumentation layer.
- [No-op tracer still wraps hot path in a promise] → Accepted: `withSpan` remains async as today; the change only removes span export, matching prior behavior when `SENTRY_DSN` was unset.
-
-## Migration Plan
-
- Deploy with `SENTRY_TRACING` unset → tracing off (safe default), errors still reported.
- To debug, set `SENTRY_TRACING=true` (with `SENTRY_DSN`) temporarily; unset to roll back. No data migration.
@@ -1,25 +0,0 @@
-## Why
-
-Arb Pulse is moving to a 24/7 VPS (Hetzner), where the engine runs continuously and emits OpenTelemetry spans on the hot path (`ws.message` → `orderbook.process` → `arbitrage.evaluate` → `sse.broadcast`). At that volume the app can approach or exceed Sentry's free-tier span quota (5M spans/month), while error monitoring stays well within limits. We want to keep tracing available for debugging but off by default so continuous operation is free-tier safe.
-
-## What Changes
-
- Introduce an environment variable (`SENTRY_TRACING`, boolean, default `false`) that gates OpenTelemetry span creation and export to Sentry.
- When `SENTRY_TRACING` is disabled (default), the tracer is a no-op: no spans are created or exported, and no hot-path span allocation occurs. Error capture (`Sentry.captureException`, `unhandledRejection`, `uncaughtException`) remains fully active.
- When `SENTRY_TRACING` is enabled **and** `SENTRY_DSN` is set, spans are created and exported to Sentry as today, and `tracesSampleRate` is applied.
- Document the new variable in `.env.example` and `README.md`.
-
-## Capabilities
-
-### New Capabilities
- `observability`: error monitoring and optional distributed tracing behavior — how Sentry error capture is always on, and how OpenTelemetry span emission is conditioned on an environment flag.
-
-### Modified Capabilities
-<!-- None: no existing specs under openspec/specs/. -->
-
-## Impact
-
- Code: `src/instrumentation/otel.ts` (gate span provider/export), `src/instrumentation/sentry.ts` (conditional `tracesSampleRate`), possibly `src/instrumentation/index.ts`.
- Config/docs: `.env.example`, `README.md` (observability section + env var table).
- Dependencies: none added or removed (OTel packages stay for the enabled path).
- Behavior: default runtime emits zero spans; error monitoring unchanged. No API or wire-format changes.
@@ -1,43 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Error monitoring is always active
-
-The system SHALL report runtime errors to Sentry whenever `SENTRY_DSN` is configured, independent of any tracing configuration. This includes REST, WebSocket feed, and SSE errors captured via `Sentry.captureException`, plus process-level `unhandledRejection` and `uncaughtException` handlers.
-
-#### Scenario: Error captured with DSN set
-
- **WHEN** `SENTRY_DSN` is set and a handled error occurs on the WebSocket, REST, or SSE path
- **THEN** the error is sent to Sentry as an error event
-
-#### Scenario: No DSN configured
-
- **WHEN** `SENTRY_DSN` is empty or unset
- **THEN** Sentry is not initialized and no events are sent, and the application continues running normally
-
-### Requirement: Tracing spans are gated by an environment flag
-
-The system SHALL only create and export OpenTelemetry spans when the `SENTRY_TRACING` environment variable is enabled AND `SENTRY_DSN` is set. The flag SHALL default to disabled so that continuous 24/7 operation emits zero spans by default.
-
-#### Scenario: Tracing disabled by default
-
- **WHEN** `SENTRY_TRACING` is unset or falsy (default)
- **THEN** the tracer is a no-op, no spans are created on the hot path, and no spans are exported to Sentry
-
-#### Scenario: Tracing enabled with DSN
-
- **WHEN** `SENTRY_TRACING` is truthy and `SENTRY_DSN` is set
- **THEN** hot-path spans (`ws.message`, `orderbook.process`, `arbitrage.evaluate`, `sse.broadcast`) are created and exported to Sentry, and `tracesSampleRate` is applied
-
-#### Scenario: Tracing enabled without DSN
-
- **WHEN** `SENTRY_TRACING` is truthy but `SENTRY_DSN` is empty or unset
- **THEN** the tracer is a no-op and no spans are exported, since export requires a DSN
-
-### Requirement: Error capture is preserved when tracing is disabled
-
-The system SHALL continue to report exceptions thrown inside hot-path work wrappers to Sentry even when tracing is disabled, so disabling spans never reduces error visibility.
-
-#### Scenario: Exception in hot-path wrapper with tracing off
-
- **WHEN** `SENTRY_TRACING` is disabled and code wrapped by the hot-path span helper throws
- **THEN** the exception is still captured and reported to Sentry (as an error), and re-thrown to preserve existing control flow
@@ -1,16 +0,0 @@
-## 1. Tracing gate
-
- [x] 1.1 Add `isTracingEnabled()` helper (reads `SENTRY_TRACING`, truthy = `"1"`/`"true"` case-insensitive) exported from the instrumentation layer
- [x] 1.2 In `src/instrumentation/otel.ts`, return the no-op tracer unless both `SENTRY_DSN` and `SENTRY_TRACING` are truthy (keep `withSpan` signature and its `Sentry.captureException` in catch)
- [x] 1.3 In `src/instrumentation/sentry.ts`, only set `tracesSampleRate` when tracing is enabled (omit it otherwise)
-
-## 2. Documentation
-
- [x] 2.1 Add `SENTRY_TRACING` (default `false`) to `.env.example` with a note it gates spans for free-tier safety
- [x] 2.2 Update the README observability section to describe the flag and default-off behavior
-
-## 3. Verification
-
- [x] 3.1 `npm run typecheck` passes
- [x] 3.2 `npm test` passes
- [x] 3.3 Manually confirm: with `SENTRY_TRACING` unset, no spans are emitted; error capture path unaffected
@@ -1,20 +0,0 @@
-schema: spec-driven
-
-# Project context (optional)
-# This is shown to AI when creating artifacts.
-# Add your tech stack, conventions, style guides, domain knowledge, etc.
-# Example:
-#   context: |
-#     Tech stack: TypeScript, React, Node.js
-#     We use conventional commits
-#     Domain: e-commerce platform
-
-# Per-artifact rules (optional)
-# Add custom rules for specific artifacts.
-# Example:
-#   rules:
-#     proposal:
-#       - Keep proposals under 500 words
-#       - Always include a "Non-goals" section
-#     tasks:
-#       - Break tasks into chunks of max 2 hours
@@ -12,52 +12,20 @@
    "start": "tsx src/index.ts",
    "build": "npm --prefix web install && npm --prefix web run build",
    "typecheck": "tsc --noEmit && npm --prefix web run typecheck",
-    "test": "node scripts/run-tests.mjs",
-    "test:rate-limit": "node --import tsx --test src/interfaces/http/rate-limit.test.ts",
-    "test:e2e": "playwright test",
-    "test:observability": "playwright test observability.spec.ts",
-    "lint": "eslint .",
-    "prepare": "husky"
-  },
-  "lint-staged": {
-    "src/**/*.ts": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "web/src/**/*.{ts,tsx}": [
-      "eslint --fix",
-      "prettier --write"
-    ]
+    "test": "node scripts/run-tests.mjs"
  },
  "dependencies": {
-    "@asteasolutions/zod-to-openapi": "^8.5.0",
-    "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/sdk-trace-node": "^2.7.1",
-    "@scalar/express-api-reference": "^0.8.48",
-    "@sentry/node": "^10.57.0",
-    "@sentry/opentelemetry": "^10.57.0",
-    "@upstash/ratelimit": "^2.0.6",
-    "@upstash/redis": "^1.35.3",
    "express": "^4.21.2",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
+    "swagger-ui-express": "^5.0.1",
    "tsx": "^4.19.2",
-    "ws": "^8.18.0",
-    "zod": "^4.4.3"
+    "ws": "^8.18.0"
  },
  "devDependencies": {
-    "@eslint/js": "^9.18.0",
-    "@playwright/test": "^1.51.1",
    "@types/express": "^4.17.21",
    "@types/node": "^22.10.5",
+    "@types/swagger-ui-express": "^4.1.8",
    "@types/ws": "^8.5.13",
-    "eslint": "^9.18.0",
-    "eslint-plugin-react-hooks": "^5.1.0",
-    "globals": "^15.14.0",
-    "husky": "^9.1.7",
-    "lint-staged": "^16.4.0",
-    "prettier": "^3.8.3",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.26.0"
+    "openapi-types": "^12.1.3",
+    "typescript": "^5.7.3"
  }
 }
@@ -1,24 +0,0 @@
-import { defineConfig, devices } from "@playwright/test";
-
-export default defineConfig({
-  testDir: "e2e",
-  fullyParallel: false,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: 1,
-  timeout: 60_000,
-  reporter: process.env.CI ? "github" : "html",
-  use: {
-    baseURL: "http://localhost:8080",
-    trace: "on-first-retry",
-  },
-  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
-  ...(!process.env.CI && {
-    webServer: {
-      command: "npm start",
-      url: "http://localhost:8080/api/health",
-      reuseExistingServer: !process.env.PW_FRESH_SERVER,
-      env: { DEMO_MODE: "true" },
-    },
-  }),
-});
@@ -1,10 +1,5 @@
 import type { OrderBook } from "../../domain/entities/index.js";
 import type { ArbitrageEngine } from "../../domain/services/arbitrage-engine.js";
-import { withSpan } from "../../instrumentation/otel.js";
-import {
-  newCorrelationId,
-  runWithCorrelation,
-} from "../../infrastructure/logging/correlation.js";

 export interface FeedRecorderPort {
  record(book: OrderBook): void;
@@ -15,30 +10,12 @@ export class ProcessOrderBookUpdate {
  constructor(
    private readonly engine: ArbitrageEngine,
    private readonly recorder: FeedRecorderPort,
-    private readonly isExchangeActive: (
-      exchange: OrderBook["exchange"],
-    ) => boolean,
+    private readonly isExchangeActive: (exchange: OrderBook["exchange"]) => boolean,
  ) {}

  run(book: OrderBook): void {
    if (!this.isExchangeActive(book.exchange)) return;
-
-    const correlationId = newCorrelationId("book");
-    runWithCorrelation({ correlationId, exchange: book.exchange }, () => {
-      void withSpan(
-        "orderbook.process",
-        { exchange: book.exchange, correlationId },
-        async () => {
-          this.recorder.record(book);
-          await withSpan(
-            "arbitrage.evaluate",
-            { exchange: book.exchange, correlationId },
-            async () => {
-              this.engine.onBook(book);
-            },
-          );
-        },
-      );
-    });
+    this.recorder.record(book);
+    this.engine.onBook(book);
  }
 }
@@ -1,11 +1,5 @@
-import "./load-env.js";
-import { initInstrumentation } from "./instrumentation/index.js";
-
-initInstrumentation();
-
 import express from "express";
-import * as Sentry from "@sentry/node";
-import { apiReference } from "@scalar/express-api-reference";
+import swaggerUi from "swagger-ui-express";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -14,7 +8,7 @@ import { bootstrap, config } from "./composition/bootstrap.js";
 import { runtime } from "./infrastructure/config/runtime.js";
 import { SseHub } from "./interfaces/sse/sse.js";
 import { createRouter } from "./interfaces/http/routes.js";
-import { openapiDocument } from "./interfaces/http/openapi.js";
+import { openapiSpec } from "./interfaces/http/openapi.js";

 const log = createLogger("server");

@@ -31,15 +25,11 @@ function main(): void {
  const server = express();
  server.use(express.json());
  server.use("/api", createRouter(ctx.application, sse));
-  Sentry.setupExpressErrorHandler(server);

-  server.use(
-    "/api-docs",
-    apiReference({
-      content: openapiDocument,
-      pageTitle: "Arb Pulse — API Docs",
-    }),
-  );
+  server.use("/api-docs", swaggerUi.serve, swaggerUi.setup(openapiSpec, {
+    customSiteTitle: "Arb Pulse — API Docs",
+    swaggerOptions: { defaultModelsExpandDepth: 2, defaultModelExpandDepth: 2 },
+  }));

  if (existsSync(webDist)) {
    server.use(express.static(webDist));
@@ -50,9 +40,7 @@ function main(): void {
    server.get("/", (_req, res) => {
      res
        .status(200)
-        .send(
-          "Backend running. Frontend not built yet — run `npm run build` (or `npm run dev:web`).",
-        );
+        .send("Backend running. Frontend not built yet — run `npm run build` (or `npm run dev:web`).");
    });
  }

@@ -1,48 +0,0 @@
-import { Redis } from "@upstash/redis";
-
-const SNAPSHOT_KEY = "arbpulse:snapshot";
-const SNAPSHOT_TTL_SEC = 1;
-
-let redis: Redis | null | undefined;
-
-export function isUpstashConfigured(): boolean {
-  return Boolean(
-    process.env.UPSTASH_REDIS_REST_URL?.trim() &&
-    process.env.UPSTASH_REDIS_REST_TOKEN?.trim(),
-  );
-}
-
-function getRedis(): Redis | null {
-  if (redis !== undefined) {
-    return redis;
-  }
-  const url = process.env.UPSTASH_REDIS_REST_URL?.trim();
-  const token = process.env.UPSTASH_REDIS_REST_TOKEN?.trim();
-  if (!url || !token) {
-    redis = null;
-    return null;
-  }
-  redis = new Redis({ url, token });
-  return redis;
-}
-
-export async function getCachedSnapshot<T>(): Promise<T | null> {
-  const client = getRedis();
-  if (!client) return null;
-  try {
-    return (await client.get<T>(SNAPSHOT_KEY)) ?? null;
-  } catch (err) {
-    console.warn("[upstash] get snapshot failed", err);
-    return null;
-  }
-}
-
-export async function setCachedSnapshot<T>(snapshot: T): Promise<void> {
-  const client = getRedis();
-  if (!client) return;
-  try {
-    await client.set(SNAPSHOT_KEY, snapshot, { ex: SNAPSHOT_TTL_SEC });
-  } catch (err) {
-    console.warn("[upstash] set snapshot failed", err);
-  }
-}
@@ -1,7 +1,5 @@
 import WebSocket from "ws";
-import * as Sentry from "@sentry/node";
 import type { ExchangeId, OrderBook } from "../../domain/entities/index.js";
-import { withSpan } from "../../instrumentation/otel.js";
 import { createLogger, type Logger } from "../logging/logger.js";
 import type { MarketDataFeed } from "../../domain/ports/ports.js";
 import { LocalBook } from "./local-book.js";
@@ -58,16 +56,12 @@ export abstract class ExchangeConnector implements MarketDataFeed {
    ws.on("open", () => {
      this.reconnectAttempts = 0;
      this.book.reset();
-      this.log.info(
-        this.skipSubscribe() ? "connected" : "connected, subscribing",
-      );
+      this.log.info(this.skipSubscribe() ? "connected" : "connected, subscribing");
      if (!this.skipSubscribe()) {
        try {
          ws.send(JSON.stringify(this.subscribeMessage()));
        } catch (err) {
-          this.log.error("subscribe send failed", {
-            error: err instanceof Error ? err.message : String(err),
-          });
+          this.log.error("subscribe send failed", err);
        }
      }
      this.startPing();
@@ -78,27 +72,15 @@ export abstract class ExchangeConnector implements MarketDataFeed {
      const text = data.toString();
      // Some exchanges (OKX) reply to app-level pings with a plain "pong" frame.
      if (text === "pong" || text === "ping") return;
-      void withSpan(
-        "ws.message",
-        { exchange: this.id, bytes: text.length },
-        async () => {
-          try {
-            this.handleMessage(JSON.parse(text));
-          } catch (err) {
-            this.log.warn("failed to parse message", {
-              error: err instanceof Error ? err.message : String(err),
-            });
-          }
-        },
-      );
+      try {
+        this.handleMessage(JSON.parse(text));
+      } catch (err) {
+        this.log.warn("failed to parse message", err);
+      }
    });

    ws.on("error", (err) => {
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.log.error("socket error", { error: error.message });
-      Sentry.captureException(error, {
-        tags: { exchange: this.id, component: "ws" },
-      });
+      this.log.error("socket error", err instanceof Error ? err.message : err);
    });

    ws.on("close", () => {
@@ -115,13 +97,8 @@ export abstract class ExchangeConnector implements MarketDataFeed {

  private scheduleReconnect(): void {
    this.reconnectAttempts += 1;
-    const delay = Math.min(
-      30_000,
-      500 * 2 ** Math.min(this.reconnectAttempts, 6),
-    );
-    this.log.warn(
-      `disconnected, reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`,
-    );
+    const delay = Math.min(30_000, 500 * 2 ** Math.min(this.reconnectAttempts, 6));
+    this.log.warn(`disconnected, reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
    setTimeout(() => {
      if (!this.closed) this.connect();
    }, delay);
@@ -1,39 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID } from "node:crypto";
-
-export interface CorrelationContext {
-  correlationId: string;
-  exchange?: string;
-}
-
-const storage = new AsyncLocalStorage<CorrelationContext>();
-
-export function getCorrelationContext(): CorrelationContext | undefined {
-  return storage.getStore();
-}
-
-export function getCorrelationId(): string | undefined {
-  return storage.getStore()?.correlationId;
-}
-
-export function runWithCorrelation<T>(
-  context: CorrelationContext,
-  fn: () => T,
-): T {
-  return storage.run(context, fn);
-}
-
-export function newCorrelationId(prefix = "tick"): string {
-  return `${prefix}_${randomUUID().slice(0, 8)}`;
-}
-
-export function bindRequestCorrelation(
-  headerValue: string | string[] | undefined,
-): CorrelationContext {
-  const raw = Array.isArray(headerValue) ? headerValue[0] : headerValue;
-  const correlationId =
-    typeof raw === "string" && raw.trim()
-      ? raw.trim()
-      : newCorrelationId("req");
-  return { correlationId };
-}
@@ -1,38 +1,22 @@
-import pino from "pino";
-import { getCorrelationContext } from "./correlation.js";
+type Level = "info" | "warn" | "error";

-const root = pino({
-  level: process.env.LOG_LEVEL ?? "info",
-  base: { service: "arbpulse" },
-  timestamp: pino.stdTimeFunctions.isoTime,
-  ...(process.env.NODE_ENV !== "production"
-    ? {
-        transport: {
-          target: "pino-pretty",
-          options: { colorize: true, singleLine: true },
-        },
-      }
-    : {}),
-});
-
-export function createLogger(scope: string) {
-  const child = root.child({ scope });
-  return {
-    info: (msg: string, extra?: Record<string, unknown>) =>
-      child.info({ ...bindings(), ...extra }, msg),
-    warn: (msg: string, extra?: Record<string, unknown>) =>
-      child.warn({ ...bindings(), ...extra }, msg),
-    error: (msg: string, extra?: Record<string, unknown>) =>
-      child.error({ ...bindings(), ...extra }, msg),
-  };
+function emit(level: Level, scope: string, msg: string, extra?: unknown): void {
+  const ts = new Date().toISOString();
+  const line = `${ts} [${level.toUpperCase()}] (${scope}) ${msg}`;
+  if (level === "error") {
+    console.error(line, extra ?? "");
+  } else if (level === "warn") {
+    console.warn(line, extra ?? "");
+  } else {
+    console.log(line, extra ?? "");
+  }
 }

-function bindings(): Record<string, unknown> {
-  const ctx = getCorrelationContext();
-  if (!ctx) return {};
+export function createLogger(scope: string) {
  return {
-    correlationId: ctx.correlationId,
-    ...(ctx.exchange ? { exchange: ctx.exchange } : {}),
+    info: (msg: string, extra?: unknown) => emit("info", scope, msg, extra),
+    warn: (msg: string, extra?: unknown) => emit("warn", scope, msg, extra),
+    error: (msg: string, extra?: unknown) => emit("error", scope, msg, extra),
  };
 }

@@ -1,7 +0,0 @@
-import { initOpenTelemetry } from "./otel.js";
-import { initSentry } from "./sentry.js";
-
-export function initInstrumentation(): void {
-  initSentry();
-  initOpenTelemetry();
-}
@@ -1,55 +0,0 @@
-import * as Sentry from "@sentry/node";
-import { trace, type Span, type Tracer } from "@opentelemetry/api";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { SentrySpanProcessor, SentryPropagator } from "@sentry/opentelemetry";
-import { isTracingEnabled } from "./tracing.js";
-
-let tracer: Tracer | null = null;
-
-/**
- * OpenTelemetry spans export to Sentry via @sentry/opentelemetry only when
- * SENTRY_DSN is set AND SENTRY_TRACING is enabled. Otherwise spans are no-ops
- * (default; safe for 24/7 operation, local dev, and tests). Error capture in
- * `withSpan` is preserved regardless.
- */
-export function initOpenTelemetry(): Tracer {
-  if (tracer) return tracer;
-
-  if (!process.env.SENTRY_DSN?.trim() || !isTracingEnabled()) {
-    tracer = trace.getTracer("arbpulse");
-    return tracer;
-  }
-
-  const provider = new NodeTracerProvider({
-    spanProcessors: [new SentrySpanProcessor()],
-  });
-  provider.register({
-    propagator: new SentryPropagator(),
-  });
-
-  tracer = provider.getTracer("arbpulse");
-  return tracer;
-}
-
-export function getTracer(): Tracer {
-  return tracer ?? initOpenTelemetry();
-}
-
-export async function withSpan<T>(
-  name: string,
-  attributes: Record<string, string | number | boolean>,
-  fn: (span: Span) => T | Promise<T>,
-): Promise<T> {
-  const activeTracer = getTracer();
-  return activeTracer.startActiveSpan(name, { attributes }, async (span) => {
-    try {
-      return await fn(span);
-    } catch (err) {
-      span.setStatus({ code: 2, message: String(err) });
-      Sentry.captureException(err);
-      throw err;
-    } finally {
-      span.end();
-    }
-  });
-}
@@ -1,32 +0,0 @@
-import * as Sentry from "@sentry/node";
-import { isTracingEnabled } from "./tracing.js";
-
-const dsn = process.env.SENTRY_DSN?.trim();
-
-export function initSentry(): void {
-  if (!dsn) return;
-
-  Sentry.init({
-    dsn,
-    environment: process.env.NODE_ENV ?? "development",
-    integrations: [Sentry.httpIntegration(), Sentry.expressIntegration()],
-    // Tracing/spans are gated by SENTRY_TRACING (default off) to stay within
-    // the Sentry free-tier span quota during 24/7 operation. Error monitoring
-    // is always on.
-    ...(isTracingEnabled()
-      ? { tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1 }
-      : {}),
-  });
-
-  process.on("unhandledRejection", (reason) => {
-    Sentry.captureException(
-      reason instanceof Error ? reason : new Error(String(reason)),
-    );
-  });
-
-  process.on("uncaughtException", (error) => {
-    Sentry.captureException(error);
-  });
-}
-
-export { Sentry };
@@ -1,11 +0,0 @@
-/**
- * Single source of truth for the tracing gate. OpenTelemetry spans are only
- * created and exported to Sentry when `SENTRY_TRACING` is truthy (and a
- * `SENTRY_DSN` is set). Defaults to disabled so 24/7 operation stays off the
- * Sentry free-tier span quota. Error monitoring is unaffected by this flag.
- */
-export function isTracingEnabled(): boolean {
-  const raw = process.env.SENTRY_TRACING;
-  if (raw === undefined) return false;
-  return raw === "1" || raw.toLowerCase() === "true";
-}
@@ -1,296 +1,745 @@
 /**
- * OpenAPI 3.0 document generated from Zod schemas via @asteasolutions/zod-to-openapi.
- * Served interactively at /api-docs through Scalar.
+ * OpenAPI 3.0 specification for the Arb Pulse REST API.
+ *
+ * Arb Pulse is a **simulated** cross-exchange BTC/USDT arbitrage system.
+ * No real funds are at risk — all trades are paper-executed against live order
+ * book data from Kraken, Bybit, OKX and Binance (or a synthetic feed in demo mode).
 */

-import {
-  OpenAPIRegistry,
-  OpenApiGeneratorV3,
-} from "@asteasolutions/zod-to-openapi";
-import {
-  ErrorEnvelopeSchema,
-  SuccessEnvelopeNoDataSchema,
-} from "./schemas/common.js";
-import {
-  ConfigPatchSchema,
-  DemoControlBodySchema,
-  MaxTradeControlBodySchema,
-  RecordControlBodySchema,
-  ThresholdControlBodySchema,
-} from "./schemas/requests.js";
-import {
-  ConfigResponseSchema,
-  DemoModeResponseSchema,
-  HealthResponseSchema,
-  MaxTradeResponseSchema,
-  RecordFeedResponseSchema,
-  StateResponseSchema,
-  ThresholdResponseSchema,
-} from "./schemas/responses.js";
-import { StateSnapshotSchema } from "./schemas/domain.js";
+import type { OpenAPIV3 } from "openapi-types";

-const registry = new OpenAPIRegistry();
+// ---------------------------------------------------------------------------
+// Reusable schema components
+// ---------------------------------------------------------------------------

-registry.register("ErrorEnvelope", ErrorEnvelopeSchema);
-registry.register("SuccessEnvelopeNoData", SuccessEnvelopeNoDataSchema);
-registry.register("StateSnapshot", StateSnapshotSchema);
-
-const jsonError = {
-  description: "Invalid request body or out-of-range value.",
-  content: { "application/json": { schema: ErrorEnvelopeSchema } },
-};
-
-const jsonServerError = {
-  description: "Unexpected server error.",
-  content: { "application/json": { schema: ErrorEnvelopeSchema } },
-};
-
-registry.registerPath({
-  method: "get",
-  path: "/api/health",
-  tags: ["Monitoring"],
-  summary: "Health check",
-  description:
-    "Lightweight endpoint used by Fly.io (and any uptime monitor) to verify the server is alive.",
-  operationId: "getHealth",
-  responses: {
-    200: {
-      description: "Server is healthy.",
-      content: { "application/json": { schema: HealthResponseSchema } },
-    },
-    500: jsonServerError,
+const schemas: Record<string, OpenAPIV3.SchemaObject> = {
+  ExchangeId: {
+    type: "string",
+    enum: ["kraken", "bybit", "okx", "binance"],
+    description: "One of the supported exchanges.",
  },
-});

-registry.registerPath({
-  method: "get",
-  path: "/api/state",
-  tags: ["Monitoring"],
-  summary: "Full state snapshot",
-  description:
-    "Returns the complete in-memory engine state as a single JSON document.",
-  operationId: "getState",
-  responses: {
-    200: {
-      description: "Current engine state.",
-      content: { "application/json": { schema: StateResponseSchema } },
-    },
-    500: jsonServerError,
+  FeedStatus: {
+    type: "string",
+    enum: ["connecting", "live", "stale", "down"],
+    description: "Connectivity state of the exchange WebSocket feed.",
  },
-});

-registry.registerPath({
-  method: "get",
-  path: "/api/stream",
-  tags: ["Streaming"],
-  summary: "SSE real-time feed",
-  description:
-    "Opens a persistent Server-Sent Events connection. Each event carries a JSON-encoded StateSnapshot.",
-  operationId: "getStream",
-  responses: {
-    200: {
-      description: "SSE stream opened.",
-      content: {
-        "text/event-stream": {
-          schema: {
-            type: "string",
-            description: "Newline-delimited SSE events.",
-          },
-        },
+  CircuitState: {
+    type: "string",
+    enum: ["running", "paused", "tripped"],
+    description:
+      "State of the circuit-breaker: `running` = normal, `paused` = manually paused, `tripped` = auto-paused after N consecutive losses.",
+  },
+
+  OpportunityStatus: {
+    type: "string",
+    enum: [
+      "executed",
+      "executed_partial",
+      "rejected_fees",
+      "rejected_liquidity",
+      "rejected_risk",
+      "rejected_flicker",
+      "rejected_stale",
+      "pending_confirm",
+    ],
+    description: "Disposition of a detected arbitrage opportunity.",
+  },
+
+  BestQuote: {
+    type: "object",
+    description: "Best bid/ask snapshot for one exchange, as seen by the engine.",
+    required: ["exchange", "bid", "bidQty", "ask", "askQty", "recvTs", "status", "ageMs"],
+    properties: {
+      exchange: { $ref: "#/components/schemas/ExchangeId" },
+      bid: { type: "number", nullable: true, description: "Best bid price in USDT (null when feed is down)." },
+      bidQty: { type: "number", nullable: true, description: "Quantity available at the best bid (BTC)." },
+      ask: { type: "number", nullable: true, description: "Best ask price in USDT (null when feed is down)." },
+      askQty: { type: "number", nullable: true, description: "Quantity available at the best ask (BTC)." },
+      recvTs: { type: "integer", nullable: true, description: "Local receive timestamp (ms since epoch)." },
+      status: { $ref: "#/components/schemas/FeedStatus" },
+      ageMs: { type: "integer", nullable: true, description: "Milliseconds since the last update was received." },
+    },
+  },
+
+  Wallet: {
+    type: "object",
+    description:
+      "Simulated per-exchange wallet. Each exchange starts with pre-positioned USDT **and** BTC so buy/sell legs execute in parallel without on-chain transfers.",
+    required: ["exchange", "usdt", "btc"],
+    properties: {
+      exchange: { $ref: "#/components/schemas/ExchangeId" },
+      usdt: { type: "number", description: "USDT balance at this exchange." },
+      btc: { type: "number", description: "BTC balance at this exchange." },
+    },
+  },
+
+  Opportunity: {
+    type: "object",
+    description:
+      "An arbitrage opportunity detected by the engine. May have been executed or rejected for various reasons (fees, liquidity, flicker, stale quotes, risk).",
+    required: [
+      "id", "ts", "buyExchange", "sellExchange",
+      "topBuyAsk", "topSellBid", "volumeBtc",
+      "buyVwap", "sellVwap",
+      "grossSpread", "grossSpreadPct",
+      "feeBuy", "feeSell",
+      "netProfit", "netProfitPct",
+      "status", "reason", "demo",
+    ],
+    properties: {
+      id: { type: "string" },
+      ts: { type: "integer", description: "Detection timestamp (ms epoch)." },
+      buyExchange: { $ref: "#/components/schemas/ExchangeId" },
+      sellExchange: { $ref: "#/components/schemas/ExchangeId" },
+      topBuyAsk: { type: "number", description: "Top-of-book ask price on the buy exchange (USDT)." },
+      topSellBid: { type: "number", description: "Top-of-book bid price on the sell exchange (USDT)." },
+      volumeBtc: {
+        type: "number",
+        description: "Volume evaluated (BTC) after applying liquidity depth and wallet inventory caps.",
+      },
+      buyVwap: {
+        type: "number",
+        description: "Volume-weighted average buy price after walking the order book depth (USDT). Slippage is embedded here.",
+      },
+      sellVwap: {
+        type: "number",
+        description: "Volume-weighted average sell price after walking the order book depth (USDT). Slippage is embedded here.",
+      },
+      grossSpread: { type: "number", description: "Raw spread (sellVwap − buyVwap) in USDT." },
+      grossSpreadPct: { type: "number", description: "Gross spread as a percentage of buyVwap." },
+      feeBuy: { type: "number", description: "Taker fee rate for the buy exchange (e.g. 0.0026 for Kraken)." },
+      feeSell: { type: "number", description: "Taker fee rate for the sell exchange." },
+      netProfit: {
+        type: "number",
+        description: "Net P&L in USDT: sellVwap·vol·(1−feeSell) − buyVwap·vol·(1+feeBuy). Negative = loss.",
+      },
+      netProfitPct: { type: "number", description: "Net profit as a percentage of cost basis." },
+      status: { $ref: "#/components/schemas/OpportunityStatus" },
+      reason: { type: "string", description: "Human-readable explanation of the disposition." },
+      demo: {
+        type: "boolean",
+        description: "True when this opportunity was synthetically injected by the demo feed — never real market data.",
      },
    },
  },
-});

-registry.registerPath({
-  method: "get",
-  path: "/api/config",
-  tags: ["Configuration"],
-  summary: "Get engine configuration",
-  operationId: "getConfig",
-  responses: {
-    200: {
-      description: "Current configuration.",
-      content: { "application/json": { schema: ConfigResponseSchema } },
-    },
-    500: jsonServerError,
-  },
-});
-
-registry.registerPath({
-  method: "patch",
-  path: "/api/config",
-  tags: ["Configuration"],
-  summary: "Update engine configuration",
-  operationId: "patchConfig",
-  request: {
-    body: {
-      content: { "application/json": { schema: ConfigPatchSchema } },
-      required: true,
+  Trade: {
+    type: "object",
+    description:
+      "A simulated trade that was executed (or partially executed). Includes latency-drift adjustment on both VWAP prices to model realistic fill slippage between detection and execution.",
+    required: [
+      "id", "ts", "buyExchange", "sellExchange",
+      "volumeBtc", "requestedBtc",
+      "buyVwap", "sellVwap", "execBuyVwap", "execSellVwap",
+      "feeBuy", "feeSell",
+      "netProfit", "netProfitPct",
+      "partial", "demo",
+    ],
+    properties: {
+      id: { type: "string" },
+      ts: { type: "integer", description: "Execution timestamp (ms epoch)." },
+      buyExchange: { $ref: "#/components/schemas/ExchangeId" },
+      sellExchange: { $ref: "#/components/schemas/ExchangeId" },
+      volumeBtc: { type: "number", description: "Actual filled volume (BTC)." },
+      requestedBtc: { type: "number", description: "Originally requested volume before partial fill." },
+      buyVwap: { type: "number", description: "VWAP at detection time (pre-latency, USDT)." },
+      sellVwap: { type: "number", description: "VWAP at detection time (pre-latency, USDT)." },
+      execBuyVwap: {
+        type: "number",
+        description: "Simulated fill price after latency drift on the buy side (USDT). Reflects real-world price movement during order routing.",
+      },
+      execSellVwap: {
+        type: "number",
+        description: "Simulated fill price after latency drift on the sell side (USDT).",
+      },
+      feeBuy: { type: "number" },
+      feeSell: { type: "number" },
+      netProfit: { type: "number", description: "Realized net P&L in USDT (negative = loss)." },
+      netProfitPct: { type: "number" },
+      partial: { type: "boolean", description: "True when the fill was limited by order book depth or wallet balance." },
+      demo: { type: "boolean" },
    },
  },
-  responses: {
-    200: {
-      description: "Updated configuration.",
-      content: { "application/json": { schema: ConfigResponseSchema } },
-    },
-    400: jsonError,
-    500: jsonServerError,
-  },
-});

-function registerControlPost(
-  path: string,
-  operationId: string,
-  summary: string,
-  description: string,
-): void {
-  registry.registerPath({
-    method: "post",
-    path,
-    tags: ["Control"],
-    summary,
+  RebalanceEvent: {
+    type: "object",
+    description:
+      "An inter-exchange rebalance triggered to correct inventory drift. Withdrawal fees apply here — not per-trade.",
+    required: ["id", "ts", "fromExchange", "toExchange", "asset", "amount", "withdrawalFee", "reason"],
+    properties: {
+      id: { type: "string" },
+      ts: { type: "integer" },
+      fromExchange: { $ref: "#/components/schemas/ExchangeId" },
+      toExchange: { $ref: "#/components/schemas/ExchangeId" },
+      asset: { type: "string", enum: ["BTC", "USDT"] },
+      amount: { type: "number" },
+      withdrawalFee: { type: "number", description: "Withdrawal fee in the transferred asset." },
+      reason: { type: "string" },
+    },
+  },
+
+  PnlPoint: {
+    type: "object",
+    description: "A cumulative P&L data point for the time-series chart.",
+    required: ["ts", "pnl"],
+    properties: {
+      ts: { type: "integer", description: "Timestamp (ms epoch)." },
+      pnl: { type: "number", description: "Cumulative realized P&L in USDT at this timestamp." },
+    },
+  },
+
+  EngineStats: {
+    type: "object",
+    description: "Runtime statistics for the arbitrage engine.",
+    required: [
+      "uptimeMs", "ticksProcessed", "opportunitiesDetected",
+      "tradesExecuted", "tradesRejected",
+      "realizedPnl", "consecutiveLosses",
+      "circuit", "demoMode", "avgTickMs",
+    ],
+    properties: {
+      uptimeMs: { type: "integer", description: "Engine uptime in milliseconds." },
+      ticksProcessed: { type: "integer", description: "Total order-book ticks processed." },
+      opportunitiesDetected: { type: "integer" },
+      tradesExecuted: { type: "integer" },
+      tradesRejected: { type: "integer" },
+      realizedPnl: { type: "number", description: "Cumulative realized P&L in USDT." },
+      consecutiveLosses: {
+        type: "integer",
+        description: "Consecutive losing trades since the last reset — triggers the circuit-breaker when it reaches the configured threshold.",
+      },
+      circuit: { $ref: "#/components/schemas/CircuitState" },
+      demoMode: {
+        type: "boolean",
+        description: "When true the engine consumes a synthetic (clearly-labelled) feed instead of live exchange data.",
+      },
+      avgTickMs: { type: "number", description: "EWMA of tick processing time in milliseconds." },
+    },
+  },
+
+  PublicConfig: {
+    type: "object",
+    description: "Live engine configuration. All fields are read/write unless noted.",
+    required: [
+      "minNetProfitPct", "maxTradeBtc", "staleMs",
+      "flickerConfirmMs", "latencyMs",
+      "activeExchanges", "defaults", "takerFees", "withdrawalFeesBtc",
+    ],
+    properties: {
+      minNetProfitPct: {
+        type: "number",
+        description: "Minimum net profit percentage required to execute a trade. Opportunities below this threshold are rejected as `rejected_fees`.",
+      },
+      maxTradeBtc: {
+        type: "number",
+        description: "Maximum BTC volume per simulated trade. Caps partial fills.",
+      },
+      staleMs: {
+        type: "integer",
+        description: "Quote age (ms) beyond which a price is considered stale and the opportunity is rejected. Read-only (set via env).",
+      },
+      flickerConfirmMs: {
+        type: "integer",
+        description: "Minimum time (ms) a spread must persist before execution. Prevents acting on transient latency artefacts.",
+      },
+      latencyMs: {
+        type: "integer",
+        description: "Simulated order-routing latency applied when computing exec VWAP drift. Read-only (set via env).",
+      },
+      activeExchanges: {
+        type: "object",
+        additionalProperties: { type: "boolean" },
+        description: "Map of exchangeId → enabled. Disabled exchanges are excluded from opportunity detection.",
+      },
+      defaults: {
+        type: "object",
+        description: "Factory defaults for the mutable fields.",
+        properties: {
+          minNetProfitPct: { type: "number" },
+          maxTradeBtc: { type: "number" },
+          flickerConfirmMs: { type: "integer" },
+          activeExchanges: { type: "object", additionalProperties: { type: "boolean" } },
+        },
+      },
+      takerFees: {
+        type: "object",
+        additionalProperties: { type: "number" },
+        description: "Taker fee rates per exchange (e.g. kraken: 0.0026, bybit: 0.001, okx: 0.001, binance: 0.001).",
+      },
+      withdrawalFeesBtc: {
+        type: "object",
+        additionalProperties: { type: "number" },
+        description: "BTC withdrawal fees per exchange — only relevant for the rebalancer, never charged per trade.",
+      },
+    },
+  },
+
+  StateSnapshot: {
+    type: "object",
+    description: "Full engine snapshot — same payload pushed over SSE on every tick.",
+    required: ["ts", "quotes", "wallets", "stats", "recentOpportunities", "recentTrades", "rebalances", "pnlSeries", "config"],
+    properties: {
+      ts: { type: "integer", description: "Snapshot timestamp (ms epoch)." },
+      quotes: { type: "array", items: { $ref: "#/components/schemas/BestQuote" } },
+      wallets: { type: "array", items: { $ref: "#/components/schemas/Wallet" } },
+      stats: { $ref: "#/components/schemas/EngineStats" },
+      recentOpportunities: { type: "array", items: { $ref: "#/components/schemas/Opportunity" } },
+      recentTrades: { type: "array", items: { $ref: "#/components/schemas/Trade" } },
+      rebalances: { type: "array", items: { $ref: "#/components/schemas/RebalanceEvent" } },
+      pnlSeries: { type: "array", items: { $ref: "#/components/schemas/PnlPoint" } },
+      config: { $ref: "#/components/schemas/PublicConfig" },
+    },
+  },
+
+  SuccessEnvelope: {
+    type: "object",
+    required: ["success"],
+    properties: {
+      success: { type: "boolean", enum: [true] },
+      data: { description: "Response payload (shape depends on the endpoint)." },
+    },
+    additionalProperties: false,
+  },
+
+  SuccessEnvelopeNoData: {
+    type: "object",
+    required: ["success"],
+    properties: {
+      success: { type: "boolean", enum: [true] },
+    },
+    additionalProperties: false,
+    example: { success: true },
+  },
+
+  ErrorEnvelope: {
+    type: "object",
+    required: ["success", "error"],
+    properties: {
+      success: { type: "boolean", enum: [false] },
+      error: { type: "string", description: "Human-readable error message." },
+    },
+    additionalProperties: false,
+    example: { success: false, error: "enabled must be a boolean" },
+  },
+
+  DemoControlBody: {
+    type: "object",
+    required: ["enabled"],
+    properties: {
+      enabled: {
+        type: "boolean",
+        description: "`true` to activate the synthetic feed, `false` to return to live data.",
+        example: true,
+      },
+    },
+    additionalProperties: false,
+  },
+
+  RecordControlBody: {
+    type: "object",
+    required: ["enabled"],
+    properties: {
+      enabled: { type: "boolean", description: "Start or stop NDJSON feed recording.", example: false },
+    },
+    additionalProperties: false,
+  },
+
+  ThresholdControlBody: {
+    type: "object",
+    required: ["pct"],
+    properties: {
+      pct: {
+        type: "number",
+        description: "Net profit threshold as a decimal percentage (0.0001–0.01, e.g. `0.0005` = 0.05 %).",
+        minimum: 0.0001,
+        maximum: 0.01,
+        example: 0.0005,
+      },
+    },
+    additionalProperties: false,
+  },
+
+  MaxTradeControlBody: {
+    type: "object",
+    required: ["btc"],
+    properties: {
+      btc: {
+        type: "number",
+        description: "Maximum BTC volume per trade (0.01–1.0).",
+        minimum: 0.01,
+        maximum: 1.0,
+        example: 0.05,
+      },
+    },
+    additionalProperties: false,
+  },
+
+  ConfigPatch: {
+    type: "object",
+    description: "Partial update for engine configuration. Only provided fields are changed.",
+    properties: {
+      minNetProfitPct: { type: "number" },
+      maxTradeBtc: { type: "number" },
+      flickerConfirmMs: { type: "integer" },
+      activeExchanges: {
+        type: "object",
+        additionalProperties: { type: "boolean" },
+        description: "Partial map — only provided exchange entries are updated.",
+      },
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Reusable response helpers
+// ---------------------------------------------------------------------------
+
+function successResponseNoData(description: string): OpenAPIV3.ResponseObject {
+  return {
    description,
-    operationId,
-    responses: {
-      200: {
-        description: summary,
-        content: {
-          "application/json": { schema: SuccessEnvelopeNoDataSchema },
-        },
+    content: {
+      "application/json": {
+        schema: { $ref: "#/components/schemas/SuccessEnvelopeNoData" },
      },
-      500: jsonServerError,
    },
-  });
+  };
 }

-registerControlPost(
-  "/api/control/pause",
-  "controlPause",
-  "Pause the arbitrage engine",
-  "Manually pauses the engine until resume is called.",
-);
-registerControlPost(
-  "/api/control/resume",
-  "controlResume",
-  "Resume the arbitrage engine",
-  "Resumes opportunity evaluation after pause or circuit-breaker trip.",
-);
-registerControlPost(
-  "/api/control/reset",
-  "controlReset",
-  "Reset simulated state",
-  "Resets wallets, trade history, and cumulative P&L.",
-);
+function successResponse(description: string, dataSchema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, example?: unknown): OpenAPIV3.ResponseObject {
+  return {
+    description,
+    content: {
+      "application/json": {
+        schema: {
+          type: "object",
+          required: ["success", "data"],
+          properties: {
+            success: { type: "boolean", enum: [true] },
+            data: dataSchema,
+          },
+          additionalProperties: false,
+        },
+        ...(example !== undefined ? { example } : {}),
+      },
+    },
+  };
+}

-registry.registerPath({
-  method: "post",
-  path: "/api/control/demo",
-  tags: ["Control"],
-  summary: "Enable / disable demo feed",
-  operationId: "controlDemo",
-  request: {
-    body: {
-      content: { "application/json": { schema: DemoControlBodySchema } },
-      required: true,
+const badRequestResponse: OpenAPIV3.ResponseObject = {
+  description: "Invalid request body or out-of-range value.",
+  content: {
+    "application/json": {
+      schema: { $ref: "#/components/schemas/ErrorEnvelope" },
    },
  },
-  responses: {
-    200: {
-      description: "Demo mode updated.",
-      content: { "application/json": { schema: DemoModeResponseSchema } },
-    },
-    400: jsonError,
-    500: jsonServerError,
-  },
-});
+};

-registry.registerPath({
-  method: "post",
-  path: "/api/control/record",
-  tags: ["Control"],
-  summary: "Enable / disable feed recording",
-  operationId: "controlRecord",
-  request: {
-    body: {
-      content: { "application/json": { schema: RecordControlBodySchema } },
-      required: true,
+const serverErrorResponse: OpenAPIV3.ResponseObject = {
+  description: "Unexpected server error.",
+  content: {
+    "application/json": {
+      schema: { $ref: "#/components/schemas/ErrorEnvelope" },
+      example: { success: false, error: "Internal server error" },
    },
  },
-  responses: {
-    200: {
-      description: "Recording state updated.",
-      content: { "application/json": { schema: RecordFeedResponseSchema } },
-    },
-    400: jsonError,
-    500: jsonServerError,
-  },
-});
+};

-registry.registerPath({
-  method: "post",
-  path: "/api/control/threshold",
-  tags: ["Control"],
-  summary: "Set minimum net profit threshold",
-  operationId: "controlThreshold",
-  request: {
-    body: {
-      content: { "application/json": { schema: ThresholdControlBodySchema } },
-      required: true,
-    },
-  },
-  responses: {
-    200: {
-      description: "Threshold updated.",
-      content: { "application/json": { schema: ThresholdResponseSchema } },
-    },
-    400: jsonError,
-    500: jsonServerError,
-  },
-});
+function controlBodyResponses(
+  okDescription: string,
+  dataSchema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+  example: unknown,
+): OpenAPIV3.ResponsesObject {
+  return {
+    "200": successResponse(okDescription, dataSchema, example),
+    "400": badRequestResponse,
+    "500": serverErrorResponse,
+  };
+}

-registry.registerPath({
-  method: "post",
-  path: "/api/control/max-trade",
-  tags: ["Control"],
-  summary: "Set maximum trade volume",
-  operationId: "controlMaxTrade",
-  request: {
-    body: {
-      content: { "application/json": { schema: MaxTradeControlBodySchema } },
-      required: true,
-    },
-  },
-  responses: {
-    200: {
-      description: "Max trade volume updated.",
-      content: { "application/json": { schema: MaxTradeResponseSchema } },
-    },
-    400: jsonError,
-    500: jsonServerError,
-  },
-});
+// ---------------------------------------------------------------------------
+// Full OpenAPI document
+// ---------------------------------------------------------------------------

-const generator = new OpenApiGeneratorV3(registry.definitions);
-
-export const openapiDocument = generator.generateDocument({
+export const openapiSpec: OpenAPIV3.Document = {
  openapi: "3.0.3",
  info: {
    title: "Arb Pulse API",
    version: "1.0.0",
-    description:
-      "Real-time BTC/USDT arbitrage detection and simulation engine. Simulated only — no real funds are committed.",
+    description: `
+**Arb Pulse** is a real-time BTC/USDT arbitrage detection and simulation engine
+that monitors live order books from **Kraken**, **Bybit**, **OKX** and **Binance** simultaneously.
+
+> ⚠️ **Simulated only** — no real funds are ever committed. All trades are paper-executed
+> against live (or synthetic demo) market data. The system uses a *pre-positioned inventory
+> model*: each exchange holds both USDT and BTC so buy and sell legs run in parallel without
+> on-chain transfers.
+
+### Key concepts
+| Concept | Detail |
+|---|---|
+| Profit formula | \`sellVwap·vol·(1−feeSell) − buyVwap·vol·(1+feeBuy)\` |
+| Slippage | Embedded in VWAP by walking the order book depth level by level |
+| Anti-flicker | Spread must persist \`flickerConfirmMs\` before execution |
+| Circuit breaker | Auto-pauses after N consecutive losses |
+| Demo mode | Injects synthetic divergences — clearly labelled, never presented as real |
+    `.trim(),
    contact: { name: "Arb Pulse" },
    license: { name: "MIT" },
  },
-  servers: [{ url: "/", description: "Current host (Fly.io / local)" }],
+  servers: [
+    { url: "/", description: "Current host (Fly.io / local)" },
+  ],
  tags: [
    { name: "Monitoring", description: "Health and state inspection." },
    { name: "Streaming", description: "Server-Sent Events real-time feed." },
-    {
-      name: "Configuration",
-      description: "Read and update engine parameters.",
-    },
+    { name: "Configuration", description: "Read and update engine parameters." },
    { name: "Control", description: "Pause, resume, reset and mode switches." },
  ],
-});
+  paths: {
+    "/api/health": {
+      get: {
+        tags: ["Monitoring"],
+        summary: "Health check",
+        description:
+          "Lightweight endpoint used by Fly.io (and any uptime monitor) to verify the server is alive. Always returns HTTP 200 while the process is running.",
+        operationId: "getHealth",
+        responses: {
+          "200": successResponse("Server is healthy.", {
+            type: "object",
+            required: ["status", "ts"],
+            properties: {
+              status: { type: "string", enum: ["ok"] },
+              ts: { type: "integer", description: "Server timestamp (ms epoch)." },
+            },
+          }, { success: true, data: { status: "ok", ts: 1_700_000_000_000 } }),
+          "500": serverErrorResponse,
+        },
+      },
+    },
+
+    "/api/state": {
+      get: {
+        tags: ["Monitoring"],
+        summary: "Full state snapshot",
+        description:
+          "Returns the complete in-memory engine state as a single JSON document: live quotes from all active exchanges, simulated wallet balances, engine statistics, the last N detected opportunities and executed trades, rebalance history, the cumulative P&L time-series, and the current engine configuration.",
+        operationId: "getState",
+        responses: {
+          "200": successResponse("Current engine state.", { $ref: "#/components/schemas/StateSnapshot" }),
+          "500": serverErrorResponse,
+        },
+      },
+    },
+
+    "/api/stream": {
+      get: {
+        tags: ["Streaming"],
+        summary: "SSE real-time feed",
+        description:
+          "Opens a persistent [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) connection. The server pushes a `StateSnapshot` JSON payload on every engine tick (typically every few hundred milliseconds). The dashboard React app subscribes here — no WebSocket or polling needed.\n\nConnect with `EventSource` or any SSE client. The stream never closes unless the server restarts or the client disconnects.",
+        operationId: "getStream",
+        responses: {
+          "200": {
+            description: "SSE stream opened. Each `data:` event carries a JSON-encoded `StateSnapshot`.",
+            content: {
+              "text/event-stream": {
+                schema: {
+                  type: "string",
+                  description: "Newline-delimited SSE events. Each `data:` line contains a serialized `StateSnapshot`.",
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+
+    "/api/config": {
+      get: {
+        tags: ["Configuration"],
+        summary: "Get engine configuration",
+        description:
+          "Returns the current mutable and immutable engine parameters: profit threshold, max trade size, flicker window, active exchanges, fee tables and factory defaults.",
+        operationId: "getConfig",
+        responses: {
+          "200": successResponse("Current configuration.", { $ref: "#/components/schemas/PublicConfig" }),
+          "500": serverErrorResponse,
+        },
+      },
+      patch: {
+        tags: ["Configuration"],
+        summary: "Update engine configuration",
+        description:
+          "Applies a partial update to mutable engine parameters. Only the fields present in the request body are changed; omitted fields retain their current values.\n\nReturns the full updated configuration on success.",
+        operationId: "patchConfig",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ConfigPatch" } },
+          },
+        },
+        responses: {
+          "200": successResponse("Updated configuration.", { $ref: "#/components/schemas/PublicConfig" }),
+          "400": badRequestResponse,
+          "500": serverErrorResponse,
+        },
+      },
+    },
+
+    "/api/control/pause": {
+      post: {
+        tags: ["Control"],
+        summary: "Pause the arbitrage engine",
+        description:
+          "Manually pauses the engine. Opportunities are no longer evaluated and no new trades are executed until `resume` is called. Order book feeds remain connected. This is equivalent to setting the circuit state to `paused`.",
+        operationId: "controlPause",
+        responses: {
+          "200": successResponseNoData("Engine paused."),
+          "500": serverErrorResponse,
+        },
+      },
+    },
+
+    "/api/control/resume": {
+      post: {
+        tags: ["Control"],
+        summary: "Resume the arbitrage engine",
+        description:
+          "Resumes opportunity evaluation after a `pause` or a circuit-breaker trip. The engine immediately re-enters the `running` circuit state.",
+        operationId: "controlResume",
+        responses: {
+          "200": successResponseNoData("Engine resumed."),
+          "500": serverErrorResponse,
+        },
+      },
+    },
+
+    "/api/control/reset": {
+      post: {
+        tags: ["Control"],
+        summary: "Reset simulated state",
+        description:
+          "Resets the simulated wallets back to their initial pre-positioned balances, clears the trade history, resets the cumulative P&L to zero, and restores the consecutive-loss counter. Engine configuration (thresholds, fee tables) is not affected. Useful for starting a clean simulation session.",
+        operationId: "controlReset",
+        responses: {
+          "200": successResponseNoData("State reset."),
+          "500": serverErrorResponse,
+        },
+      },
+    },
+
+    "/api/control/demo": {
+      post: {
+        tags: ["Control"],
+        summary: "Enable / disable demo feed",
+        description:
+          "Switches between the live exchange feeds and the **synthetic demo injector**. When `enabled: true` the engine receives artificially inflated spreads that guarantee visible arbitrage opportunities — clearly labelled with `demo: true` in every event so they are never mistaken for real market signals.\n\n**Note:** Real feeds are paused while demo mode is active.",
+        operationId: "controlDemo",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/DemoControlBody" } },
+          },
+        },
+        responses: controlBodyResponses(
+          "Demo mode updated.",
+          {
+            type: "object",
+            required: ["demoMode"],
+            properties: { demoMode: { type: "boolean" } },
+            additionalProperties: false,
+          },
+          { success: true, data: { demoMode: true } },
+        ),
+      },
+    },
+
+    "/api/control/record": {
+      post: {
+        tags: ["Control"],
+        summary: "Enable / disable feed recording",
+        description:
+          "Starts or stops recording live order-book events to an NDJSON file on disk for later replay. Useful for capturing real market sessions to run deterministic back-tests without re-connecting to exchanges.",
+        operationId: "controlRecord",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/RecordControlBody" } },
+          },
+        },
+        responses: controlBodyResponses(
+          "Recording state updated.",
+          {
+            type: "object",
+            required: ["recordFeed"],
+            properties: { recordFeed: { type: "boolean" } },
+            additionalProperties: false,
+          },
+          { success: true, data: { recordFeed: false } },
+        ),
+      },
+    },
+
+    "/api/control/threshold": {
+      post: {
+        tags: ["Control"],
+        summary: "Set minimum net profit threshold",
+        description:
+          "Adjusts the minimum net profit percentage an opportunity must exceed to be executed. Lower values detect more opportunities but increase the chance of tiny losses due to fee rounding. Opportunities below this threshold are logged as `rejected_fees`.\n\nEquivalent to `PATCH /api/config` with `{ minNetProfitPct }` but provided as a convenience endpoint.",
+        operationId: "controlThreshold",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/ThresholdControlBody" } },
+          },
+        },
+        responses: controlBodyResponses(
+          "Threshold updated.",
+          {
+            type: "object",
+            required: ["minNetProfitPct"],
+            properties: { minNetProfitPct: { type: "number" } },
+            additionalProperties: false,
+          },
+          { success: true, data: { minNetProfitPct: 0.0005 } },
+        ),
+      },
+    },
+
+    "/api/control/max-trade": {
+      post: {
+        tags: ["Control"],
+        summary: "Set maximum trade volume",
+        description:
+          "Sets the upper bound on BTC volume per simulated trade. The engine also caps volume by available order-book liquidity and wallet inventory — this parameter acts as an additional hard cap.\n\nEquivalent to `PATCH /api/config` with `{ maxTradeBtc }` but provided as a convenience endpoint.",
+        operationId: "controlMaxTrade",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/MaxTradeControlBody" } },
+          },
+        },
+        responses: controlBodyResponses(
+          "Max trade volume updated.",
+          {
+            type: "object",
+            required: ["maxTradeBtc"],
+            properties: { maxTradeBtc: { type: "number" } },
+            additionalProperties: false,
+          },
+          { success: true, data: { maxTradeBtc: 0.05 } },
+        ),
+      },
+    },
+  },
+
+  components: {
+    schemas,
+    responses: {
+      BadRequest: badRequestResponse,
+      ServerError: serverErrorResponse,
+    },
+  },
+};
@@ -1,60 +0,0 @@
-import assert from "node:assert/strict";
-import { randomUUID } from "node:crypto";
-import type { AddressInfo } from "node:net";
-import { test } from "node:test";
-import express, { Router } from "express";
-import { isUpstashConfigured } from "../../infrastructure/cache/upstash.js";
-import { loadEnvLocal } from "../../test-support/load-env-local.js";
-import { createRateLimitMiddleware } from "./rate-limit.js";
-
-loadEnvLocal();
-
-const READ_LIMIT_PER_MIN = 60;
-
-test(
-  "read tier returns 429 with Retry-After after limit",
-  { skip: !isUpstashConfigured() },
-  async () => {
-    const app = express();
-    const router = Router();
-    router.use(createRateLimitMiddleware());
-    router.get("/state", (_req, res) => {
-      res.json({ success: true, data: { ok: true } });
-    });
-    app.use("/api", router);
-
-    const server = await new Promise<ReturnType<typeof app.listen>>(
-      (resolve) => {
-        const s = app.listen(0, "127.0.0.1", () => resolve(s));
-      },
-    );
-    const port = (server.address() as AddressInfo).port;
-    const url = `http://127.0.0.1:${port}/api/state`;
-    const clientIp = `rate-limit-qa-${randomUUID()}`;
-
-    try {
-      for (let i = 0; i < READ_LIMIT_PER_MIN; i++) {
-        const res = await fetch(url, {
-          headers: { "x-forwarded-for": clientIp },
-        });
-        assert.equal(res.status, 200, `request ${i + 1} should pass`);
-      }
-
-      const blocked = await fetch(url, {
-        headers: { "x-forwarded-for": clientIp },
-      });
-      assert.equal(blocked.status, 429);
-      assert.ok(blocked.headers.get("retry-after"));
-      const body = (await blocked.json()) as { error?: string };
-      assert.equal(body.error, "Too many requests");
-    } finally {
-      await new Promise<void>((resolve, reject) => {
-        server.close((err) => (err ? reject(err) : resolve()));
-      });
-    }
-  },
-);
-
-test("reports whether Upstash REST credentials are set", () => {
-  assert.equal(typeof isUpstashConfigured(), "boolean");
-});
@@ -1,86 +0,0 @@
-import { Ratelimit } from "@upstash/ratelimit";
-import { Redis } from "@upstash/redis";
-import type { NextFunction, Request, Response } from "express";
-import { isUpstashConfigured } from "../../infrastructure/cache/upstash.js";
-
-type RouteTier = "read" | "stream" | "write" | "health";
-
-const LIMITS: Record<
-  Exclude<RouteTier, "health">,
-  { requests: number; window: `${number} s` | `${number} m` }
-> = {
-  read: { requests: 60, window: "1 m" },
-  stream: { requests: 10, window: "1 m" },
-  write: { requests: 30, window: "1 m" },
-};
-
-const limiters = new Map<Exclude<RouteTier, "health">, Ratelimit>();
-
-function getLimiter(tier: Exclude<RouteTier, "health">): Ratelimit | null {
-  if (!isUpstashConfigured()) {
-    return null;
-  }
-  let limiter = limiters.get(tier);
-  if (limiter) {
-    return limiter;
-  }
-  const url = process.env.UPSTASH_REDIS_REST_URL!.trim();
-  const token = process.env.UPSTASH_REDIS_REST_TOKEN!.trim();
-  const redis = new Redis({ url, token });
-  const cfg = LIMITS[tier];
-  limiter = new Ratelimit({
-    redis,
-    limiter: Ratelimit.slidingWindow(cfg.requests, cfg.window),
-    prefix: `arbpulse:${tier}`,
-  });
-  limiters.set(tier, limiter);
-  return limiter;
-}
-
-function clientKey(req: Request): string {
-  const forwarded = req.header("x-forwarded-for");
-  if (forwarded) {
-    return forwarded.split(",")[0]?.trim() || "unknown";
-  }
-  return req.ip || req.socket.remoteAddress || "unknown";
-}
-
-function tierForPath(path: string, method: string): RouteTier {
-  if (path === "/health") return "health";
-  if (path === "/stream") return "stream";
-  if (method === "GET" || method === "HEAD") return "read";
-  return "write";
-}
-
-export function createRateLimitMiddleware() {
-  return async (
-    req: Request,
-    res: Response,
-    next: NextFunction,
-  ): Promise<void> => {
-    const tier = tierForPath(req.path, req.method);
-    if (tier === "health") {
-      next();
-      return;
-    }
-
-    const limiter = getLimiter(tier);
-    if (!limiter) {
-      next();
-      return;
-    }
-
-    const { success, reset } = await limiter.limit(`${tier}:${clientKey(req)}`);
-    if (success) {
-      next();
-      return;
-    }
-
-    const retryAfterSec = Math.max(1, Math.ceil((reset - Date.now()) / 1000));
-    res.setHeader("Retry-After", String(retryAfterSec));
-    res.status(429).json({
-      success: false,
-      error: "Too many requests",
-    });
-  };
-}
@@ -1,64 +1,16 @@
-import {
-  Router,
-  type NextFunction,
-  type Request,
-  type Response,
-} from "express";
-import { Sentry } from "../../instrumentation/sentry.js";
+import { Router, type Request, type Response } from "express";
 import type { ApplicationService } from "../../composition/application-service.js";
-import {
-  bindRequestCorrelation,
-  runWithCorrelation,
-} from "../../infrastructure/logging/correlation.js";
-import {
-  getCachedSnapshot,
-  setCachedSnapshot,
-} from "../../infrastructure/cache/upstash.js";
 import type { SseHub } from "../sse/sse.js";
-import { createRateLimitMiddleware } from "./rate-limit.js";
-import {
-  ConfigPatchSchema,
-  DemoControlBodySchema,
-  MaxTradeControlBodySchema,
-  RecordControlBodySchema,
-  ThresholdControlBodySchema,
-} from "./schemas/requests.js";
-import { parseBody } from "./validate.js";

 export function createRouter(app: ApplicationService, sse: SseHub): Router {
  const router = Router();

-  router.use((req: Request, res: Response, next: NextFunction) => {
-    const ctx = bindRequestCorrelation(req.header("x-request-id"));
-    res.setHeader("x-request-id", ctx.correlationId);
-    runWithCorrelation(ctx, () => next());
-  });
-
-  router.use(createRateLimitMiddleware());
-
  router.get("/health", (_req: Request, res: Response) => {
    res.json({ success: true, data: { status: "ok", ts: Date.now() } });
  });

-  router.get("/debug/sentry", (_req: Request, res: Response) => {
-    if (process.env.NODE_ENV === "production") {
-      res.status(404).json({ error: "Not found" });
-      return;
-    }
-    Sentry.captureException(new Error("Arb Pulse Sentry test error"));
-    res.json({ ok: true, message: "Test error sent to Sentry" });
-  });
-
-  router.get("/state", async (_req: Request, res: Response) => {
-    const cached =
-      await getCachedSnapshot<ReturnType<ApplicationService["getSnapshot"]>>();
-    if (cached) {
-      res.json({ success: true, data: cached });
-      return;
-    }
-    const snapshot = app.getSnapshot();
-    void setCachedSnapshot(snapshot);
-    res.json({ success: true, data: snapshot });
+  router.get("/state", (_req: Request, res: Response) => {
+    res.json({ success: true, data: app.getSnapshot() });
  });

  router.get("/stream", (req: Request, res: Response) => {
@@ -70,10 +22,7 @@ export function createRouter(app: ApplicationService, sse: SseHub): Router {
  });

  router.patch("/config", (req: Request, res: Response) => {
-    const patch = parseBody(ConfigPatchSchema, req, res);
-    if (patch === null) return;
-
-    const error = app.patchConfig(patch);
+    const error = app.patchConfig(req.body ?? {});
    if (error) {
      res.status(400).json({ success: false, error });
      return;
@@ -97,43 +46,51 @@ export function createRouter(app: ApplicationService, sse: SseHub): Router {
  });

  router.post("/control/demo", (req: Request, res: Response) => {
-    const body = parseBody(DemoControlBodySchema, req, res);
-    if (body === null) return;
-
-    app.setDemoMode(body.enabled);
-    res.json({ success: true, data: { demoMode: body.enabled } });
+    const enabled = req.body?.enabled;
+    if (typeof enabled !== "boolean") {
+      res.status(400).json({ success: false, error: "enabled must be a boolean" });
+      return;
+    }
+    app.setDemoMode(enabled);
+    res.json({ success: true, data: { demoMode: enabled } });
  });

  router.post("/control/record", (req: Request, res: Response) => {
-    const body = parseBody(RecordControlBodySchema, req, res);
-    if (body === null) return;
-
-    app.setRecordFeed(body.enabled);
-    res.json({ success: true, data: { recordFeed: body.enabled } });
+    const enabled = req.body?.enabled;
+    if (typeof enabled !== "boolean") {
+      res.status(400).json({ success: false, error: "enabled must be a boolean" });
+      return;
+    }
+    app.setRecordFeed(enabled);
+    res.json({ success: true, data: { recordFeed: enabled } });
  });

  router.post("/control/threshold", (req: Request, res: Response) => {
-    const body = parseBody(ThresholdControlBodySchema, req, res);
-    if (body === null) return;
-
-    const error = app.setThreshold(body.pct);
+    const pct = req.body?.pct;
+    if (typeof pct !== "number" || !Number.isFinite(pct)) {
+      res.status(400).json({ success: false, error: "pct must be a finite number" });
+      return;
+    }
+    const error = app.setThreshold(pct);
    if (error) {
      res.status(400).json({ success: false, error });
      return;
    }
-    res.json({ success: true, data: { minNetProfitPct: body.pct } });
+    res.json({ success: true, data: { minNetProfitPct: pct } });
  });

  router.post("/control/max-trade", (req: Request, res: Response) => {
-    const body = parseBody(MaxTradeControlBodySchema, req, res);
-    if (body === null) return;
-
-    const error = app.setMaxTradeBtc(body.btc);
+    const btc = req.body?.btc;
+    if (typeof btc !== "number" || !Number.isFinite(btc)) {
+      res.status(400).json({ success: false, error: "btc must be a finite number" });
+      return;
+    }
+    const error = app.setMaxTradeBtc(btc);
    if (error) {
      res.status(400).json({ success: false, error });
      return;
    }
-    res.json({ success: true, data: { maxTradeBtc: body.btc } });
+    res.json({ success: true, data: { maxTradeBtc: btc } });
  });

  return router;
@@ -1,59 +0,0 @@
-import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
-import { z } from "zod";
-
-extendZodWithOpenApi(z);
-
-export { z };
-
-export const ExchangeIdSchema = z
-  .enum(["kraken", "bybit", "okx", "binance"])
-  .openapi("ExchangeId");
-
-export const FeedStatusSchema = z
-  .enum(["connecting", "live", "stale", "down"])
-  .openapi("FeedStatus");
-
-export const CircuitStateSchema = z
-  .enum(["running", "paused", "tripped"])
-  .openapi("CircuitState");
-
-export const OpportunityStatusSchema = z
-  .enum([
-    "executed",
-    "executed_partial",
-    "rejected_fees",
-    "rejected_liquidity",
-    "rejected_risk",
-    "rejected_flicker",
-    "rejected_stale",
-    "pending_confirm",
-  ])
-  .openapi("OpportunityStatus");
-
-export const ErrorEnvelopeSchema = z
-  .object({
-    success: z.literal(false),
-    error: z.string(),
-  })
-  .strict()
-  .openapi("ErrorEnvelope");
-
-export const SuccessEnvelopeNoDataSchema = z
-  .object({
-    success: z.literal(true),
-  })
-  .strict()
-  .openapi("SuccessEnvelopeNoData");
-
-export function successEnvelope<T extends z.ZodType>(
-  dataSchema: T,
-  name: string,
-) {
-  return z
-    .object({
-      success: z.literal(true),
-      data: dataSchema,
-    })
-    .strict()
-    .openapi(name);
-}
@@ -1,161 +0,0 @@
-import {
-  CircuitStateSchema,
-  ExchangeIdSchema,
-  FeedStatusSchema,
-  OpportunityStatusSchema,
-  z,
-} from "./common.js";
-
-export const BestQuoteSchema = z
-  .object({
-    exchange: ExchangeIdSchema,
-    bid: z.number().nullable(),
-    bidQty: z.number().nullable(),
-    ask: z.number().nullable(),
-    askQty: z.number().nullable(),
-    recvTs: z.number().int().nullable(),
-    status: FeedStatusSchema,
-    ageMs: z.number().int().nullable(),
-  })
-  .strict()
-  .openapi("BestQuote");
-
-export const WalletSchema = z
-  .object({
-    exchange: ExchangeIdSchema,
-    usdt: z.number(),
-    btc: z.number(),
-  })
-  .strict()
-  .openapi("Wallet");
-
-export const OpportunitySchema = z
-  .object({
-    id: z.string(),
-    ts: z.number().int(),
-    buyExchange: ExchangeIdSchema,
-    sellExchange: ExchangeIdSchema,
-    topBuyAsk: z.number(),
-    topSellBid: z.number(),
-    volumeBtc: z.number(),
-    buyVwap: z.number(),
-    sellVwap: z.number(),
-    grossSpread: z.number(),
-    grossSpreadPct: z.number(),
-    feeBuy: z.number(),
-    feeSell: z.number(),
-    netProfit: z.number(),
-    netProfitPct: z.number(),
-    status: OpportunityStatusSchema,
-    reason: z.string(),
-    demo: z.boolean(),
-  })
-  .strict()
-  .openapi("Opportunity");
-
-export const TradeSchema = z
-  .object({
-    id: z.string(),
-    ts: z.number().int(),
-    buyExchange: ExchangeIdSchema,
-    sellExchange: ExchangeIdSchema,
-    volumeBtc: z.number(),
-    requestedBtc: z.number(),
-    buyVwap: z.number(),
-    sellVwap: z.number(),
-    execBuyVwap: z.number(),
-    execSellVwap: z.number(),
-    feeBuy: z.number(),
-    feeSell: z.number(),
-    netProfit: z.number(),
-    netProfitPct: z.number(),
-    partial: z.boolean(),
-    demo: z.boolean(),
-  })
-  .strict()
-  .openapi("Trade");
-
-export const RebalanceEventSchema = z
-  .object({
-    id: z.string(),
-    ts: z.number().int(),
-    fromExchange: ExchangeIdSchema,
-    toExchange: ExchangeIdSchema,
-    asset: z.enum(["BTC", "USDT"]),
-    amount: z.number(),
-    withdrawalFee: z.number(),
-    reason: z.string(),
-  })
-  .strict()
-  .openapi("RebalanceEvent");
-
-export const PnlPointSchema = z
-  .object({
-    ts: z.number().int(),
-    pnl: z.number(),
-  })
-  .strict()
-  .openapi("PnlPoint");
-
-export const EngineStatsSchema = z
-  .object({
-    uptimeMs: z.number().int(),
-    ticksProcessed: z.number().int(),
-    opportunitiesDetected: z.number().int(),
-    tradesExecuted: z.number().int(),
-    tradesRejected: z.number().int(),
-    realizedPnl: z.number(),
-    consecutiveLosses: z.number().int(),
-    circuit: CircuitStateSchema,
-    demoMode: z.boolean(),
-    avgTickMs: z.number(),
-  })
-  .strict()
-  .openapi("EngineStats");
-
-const ActiveExchangesSchema = z.record(ExchangeIdSchema, z.boolean());
-
-export const PublicConfigSchema = z
-  .object({
-    minNetProfitPct: z.number(),
-    maxTradeBtc: z.number(),
-    staleMs: z.number().int(),
-    flickerConfirmMs: z.number().int(),
-    latencyMs: z.number().int(),
-    activeExchanges: ActiveExchangesSchema,
-    defaults: z
-      .object({
-        minNetProfitPct: z.number(),
-        maxTradeBtc: z.number(),
-        flickerConfirmMs: z.number().int(),
-        activeExchanges: ActiveExchangesSchema,
-      })
-      .strict(),
-    takerFees: z.record(ExchangeIdSchema, z.number()),
-    withdrawalFeesBtc: z.record(ExchangeIdSchema, z.number()),
-  })
-  .strict()
-  .openapi("PublicConfig");
-
-export const StateSnapshotSchema = z
-  .object({
-    ts: z.number().int(),
-    quotes: z.array(BestQuoteSchema),
-    wallets: z.array(WalletSchema),
-    stats: EngineStatsSchema,
-    recentOpportunities: z.array(OpportunitySchema),
-    recentTrades: z.array(TradeSchema),
-    rebalances: z.array(RebalanceEventSchema),
-    pnlSeries: z.array(PnlPointSchema),
-    config: PublicConfigSchema,
-  })
-  .strict()
-  .openapi("StateSnapshot");
-
-export const HealthDataSchema = z
-  .object({
-    status: z.literal("ok"),
-    ts: z.number().int(),
-  })
-  .strict()
-  .openapi("HealthData");
@@ -1,53 +0,0 @@
-import { ExchangeIdSchema, z } from "./common.js";
-
-const MIN_PROFIT_PCT = 0.0001;
-const MAX_PROFIT_PCT = 0.01;
-const MIN_TRADE_BTC = 0.01;
-const MAX_TRADE_BTC = 1.0;
-const MAX_FLICKER_MS = 500;
-
-export const BooleanControlBodySchema = z
-  .object({
-    enabled: z.boolean(),
-  })
-  .strict()
-  .openapi("BooleanControlBody");
-
-export const DemoControlBodySchema =
-  BooleanControlBodySchema.openapi("DemoControlBody");
-export const RecordControlBodySchema =
-  BooleanControlBodySchema.openapi("RecordControlBody");
-
-export const ThresholdControlBodySchema = z
-  .object({
-    pct: z.number().finite().min(MIN_PROFIT_PCT).max(MAX_PROFIT_PCT),
-  })
-  .strict()
-  .openapi("ThresholdControlBody");
-
-export const MaxTradeControlBodySchema = z
-  .object({
-    btc: z.number().finite().min(MIN_TRADE_BTC).max(MAX_TRADE_BTC),
-  })
-  .strict()
-  .openapi("MaxTradeControlBody");
-
-export const ConfigPatchSchema = z
-  .object({
-    minNetProfitPct: z
-      .number()
-      .finite()
-      .min(MIN_PROFIT_PCT)
-      .max(MAX_PROFIT_PCT)
-      .optional(),
-    maxTradeBtc: z
-      .number()
-      .finite()
-      .min(MIN_TRADE_BTC)
-      .max(MAX_TRADE_BTC)
-      .optional(),
-    flickerConfirmMs: z.number().int().min(0).max(MAX_FLICKER_MS).optional(),
-    activeExchanges: z.record(ExchangeIdSchema, z.boolean()).optional(),
-  })
-  .strict()
-  .openapi("ConfigPatch");
@@ -1,42 +0,0 @@
-import { successEnvelope, SuccessEnvelopeNoDataSchema } from "./common.js";
-import {
-  HealthDataSchema,
-  PublicConfigSchema,
-  StateSnapshotSchema,
-} from "./domain.js";
-import { z } from "./common.js";
-
-export const HealthResponseSchema = successEnvelope(
-  HealthDataSchema,
-  "HealthResponse",
-);
-export const StateResponseSchema = successEnvelope(
-  StateSnapshotSchema,
-  "StateResponse",
-);
-export const ConfigResponseSchema = successEnvelope(
-  PublicConfigSchema,
-  "ConfigResponse",
-);
-
-export const DemoModeResponseSchema = successEnvelope(
-  z.object({ demoMode: z.boolean() }).strict(),
-  "DemoModeResponse",
-);
-
-export const RecordFeedResponseSchema = successEnvelope(
-  z.object({ recordFeed: z.boolean() }).strict(),
-  "RecordFeedResponse",
-);
-
-export const ThresholdResponseSchema = successEnvelope(
-  z.object({ minNetProfitPct: z.number() }).strict(),
-  "ThresholdResponse",
-);
-
-export const MaxTradeResponseSchema = successEnvelope(
-  z.object({ maxTradeBtc: z.number() }).strict(),
-  "MaxTradeResponse",
-);
-
-export { SuccessEnvelopeNoDataSchema };
@@ -1,18 +0,0 @@
-import type { Request, Response } from "express";
-import type { ZodType } from "zod";
-
-export function parseBody<T>(
-  schema: ZodType<T>,
-  req: Request,
-  res: Response,
-): T | null {
-  const result = schema.safeParse(req.body ?? {});
-  if (!result.success) {
-    const message = result.error.issues
-      .map((issue) => issue.message)
-      .join("; ");
-    res.status(400).json({ success: false, error: message });
-    return null;
-  }
-  return result.data;
-}
@@ -1,9 +1,6 @@
 import type { Request, Response } from "express";
-import * as Sentry from "@sentry/node";
 import { config } from "../../infrastructure/config/config.js";
-import { setCachedSnapshot } from "../../infrastructure/cache/upstash.js";
 import { createLogger } from "../../infrastructure/logging/logger.js";
-import { withSpan } from "../../instrumentation/otel.js";
 import type { ApplicationService } from "../../composition/application-service.js";

 const log = createLogger("sse");
@@ -25,58 +22,26 @@ export class SseHub {
  }

  handle(req: Request, res: Response): void {
-    try {
-      res.writeHead(200, {
-        "Content-Type": "text/event-stream",
-        "Cache-Control": "no-cache, no-transform",
-        Connection: "keep-alive",
-        "X-Accel-Buffering": "no",
-      });
-      res.write(`retry: 2000\n\n`);
-      this.send(res, this.app.getSnapshot());
-      this.clients.add(res);
-      log.info(`client connected`, { clientCount: this.clients.size });
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no",
+    });
+    res.write(`retry: 2000\n\n`);
+    this.send(res, this.app.getSnapshot());
+    this.clients.add(res);
+    log.info(`client connected (${this.clients.size} total)`);

-      req.on("close", () => {
-        this.clients.delete(res);
-      });
-
-      res.on("error", (err) => {
-        const error = err instanceof Error ? err : new Error(String(err));
-        log.error("sse client error", { error: error.message });
-        Sentry.captureException(error, { tags: { component: "sse" } });
-        this.clients.delete(res);
-      });
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      log.error("sse handle failed", { error: error.message });
-      Sentry.captureException(error, { tags: { component: "sse" } });
-      if (!res.headersSent) {
-        res.status(500).json({ success: false, error: "SSE setup failed" });
-      }
-    }
+    req.on("close", () => {
+      this.clients.delete(res);
+    });
  }

  private broadcast(): void {
    if (this.clients.size === 0) return;
-    void withSpan(
-      "sse.broadcast",
-      { clientCount: this.clients.size },
-      async () => {
-        const snapshot = this.app.getSnapshot();
-        void setCachedSnapshot(snapshot);
-        for (const res of this.clients) {
-          try {
-            this.send(res, snapshot);
-          } catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
-            log.warn("sse send failed", { error: error.message });
-            Sentry.captureException(error, { tags: { component: "sse" } });
-            this.clients.delete(res);
-          }
-        }
-      },
-    );
+    const snapshot = this.app.getSnapshot();
+    for (const res of this.clients) this.send(res, snapshot);
  }

  private send(res: Response, data: unknown): void {
@@ -1,9 +0,0 @@
-import { existsSync } from "node:fs";
-import { loadEnvFile } from "node:process";
-
-for (const file of [".env.local", ".env"]) {
-  if (existsSync(file)) {
-    loadEnvFile(file);
-    break;
-  }
-}
@@ -1,35 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/** Loads `.env.local` without overriding variables already set in the shell. */
-export function loadEnvLocal(): void {
-  const file = join(process.cwd(), ".env.local");
-  if (!existsSync(file)) {
-    return;
-  }
-
-  for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) {
-      continue;
-    }
-
-    const eq = trimmed.indexOf("=");
-    if (eq <= 0) {
-      continue;
-    }
-
-    const key = trimmed.slice(0, eq).trim();
-    let value = trimmed.slice(eq + 1).trim();
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-
-    if (process.env[key] === undefined) {
-      process.env[key] = value;
-    }
-  }
-}
@@ -9,11 +9,11 @@
      "version": "1.0.0",
      "dependencies": {
        "arb-pulse": "file:..",
-        "react": "^19.2.7",
+        "react": "^18.3.1",
        "react-dom": "^18.3.1"
      },
      "devDependencies": {
-        "@types/react": "^19.2.17",
+        "@types/react": "^18.3.18",
        "@types/react-dom": "^18.3.5",
        "@vitejs/plugin-react": "^4.3.4",
        "autoprefixer": "^10.4.20",
@@ -27,35 +27,18 @@
      "name": "arb-pulse",
      "version": "1.0.0",
      "dependencies": {
-        "@asteasolutions/zod-to-openapi": "^8.5.0",
-        "@opentelemetry/api": "^1.9.1",
-        "@opentelemetry/sdk-trace-node": "^2.7.1",
-        "@scalar/express-api-reference": "^0.8.48",
-        "@sentry/node": "^10.57.0",
-        "@sentry/opentelemetry": "^10.57.0",
-        "@upstash/ratelimit": "^2.0.6",
-        "@upstash/redis": "^1.35.3",
        "express": "^4.21.2",
-        "pino": "^10.3.1",
-        "pino-pretty": "^13.1.3",
+        "swagger-ui-express": "^5.0.1",
        "tsx": "^4.19.2",
-        "ws": "^8.18.0",
-        "zod": "^4.4.3"
+        "ws": "^8.18.0"
      },
      "devDependencies": {
-        "@eslint/js": "^9.18.0",
-        "@playwright/test": "^1.51.1",
        "@types/express": "^4.17.21",
        "@types/node": "^22.10.5",
+        "@types/swagger-ui-express": "^4.1.8",
        "@types/ws": "^8.5.13",
-        "eslint": "^9.18.0",
-        "eslint-plugin-react-hooks": "^5.1.0",
-        "globals": "^15.14.0",
-        "husky": "^9.1.7",
-        "lint-staged": "^16.4.0",
-        "prettier": "^3.8.3",
-        "typescript": "^5.7.3",
-        "typescript-eslint": "^8.26.0"
+        "openapi-types": "^12.1.3",
+        "typescript": "^5.7.3"
      },
      "engines": {
        "node": ">=20"
@@ -1295,13 +1278,21 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@types/prop-types": {
+      "version": "15.7.15",
+      "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
+      "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@types/react": {
-      "version": "19.2.17",
-      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.17.tgz",
-      "integrity": "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==",
+      "version": "18.3.31",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz",
+      "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
+        "@types/prop-types": "*",
        "csstype": "^3.2.2"
      }
    },
@@ -2293,10 +2284,13 @@
      "license": "MIT"
    },
    "node_modules/react": {
-      "version": "19.2.7",
-      "resolved": "https://registry.npmjs.org/react/-/react-19.2.7.tgz",
-      "integrity": "sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==",
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      },
      "engines": {
        "node": ">=0.10.0"
      }
@@ -11,11 +11,11 @@
  },
  "dependencies": {
    "arb-pulse": "file:..",
-    "react": "^19.2.7",
+    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
-    "@types/react": "^19.2.17",
+    "@types/react": "^18.3.18",
    "@types/react-dom": "^18.3.5",
    "@vitejs/plugin-react": "^4.3.4",
    "autoprefixer": "^10.4.20",