We actively monitor our application bundle size and API latency to prevent performance regressions. Our target is sub-1ms database persistence and sub-250ms cold starts.

📊 Enterprise Performance Matrix

The Enterprise Benchmark Matrix (Audit) has transitioned to a High-Frequency, Self-Healing Infrastructure. Each benchmark test is autonomous—managing its own server lifecycle via dynamic port assignment and exporting high-fidelity telemetry directly to structured JSON payloads. This eliminates cross-test pollution and ensures deterministic scaling across SQLite, MongoDB, PostgreSQL, and MariaDB.

It measures:

• REST API Latency: High-frequency entry retrieval (Target: 0.35ms).

• Migration & Ingestion: Bulk I/O throughput (Verified: 6,625 entries/s).

• Revision Stability: Performance impact of deep document history (Verified: 0% degradation at 100+ versions).

• Chaos Resilience: System stability during 500ms database “brownouts.”

• Index Pressure: Complex filtering and sorting on 100,000+ entry collections.

• 5-Layer Truth Model: Measures performance from Pure Logic (CPU) → Full SDK (DB/IO) → Dispatcher (Middleware) → HTTP Warm (Keep-Alive) → HTTP Cold (Handshake).

• Memory Stability: RSS and Heap growth detection across sustained decentralized loads.

• World Life Data: High-fidelity diagnostics including Success/Failure Latency Splits and Fast-Fail Efficiency (Target: >1.5x efficiency on error rejection).

• Client Journey Simulation: Cumulative latency of multi-step E2E workflows (Auth → List → View → Save).

🚀 Running the Orchestrator

The orchestrator code is modularized inside scripts/benchmark-matrix/ for ultimate maintainability, but is easily executed via the main barrel file:

# Run the full matrix across all 4 databases and 8 variants (including Redis)
bun run scripts/benchmark-matrix/index.ts

# Generate the Master Comparison Leaderboard
# This aggregates all results into docs/project/benchmarks/README.mdx
bun run scripts/benchmark-matrix/cli.ts --leaderboard
```

> [!NOTE]
> Running the full matrix requires active local instances (or Docker containers) of MongoDB (`:27017`), PostgreSQL (`:5432`), and MariaDB (`:3306`). The orchestrator will automatically provision the required isolated benchmark databases for the test.

### Retention & Trend Analysis (SRE)

The matrix maintains a specialized retention policy to balance historical context with actionable trends:

- **Time-Series History**: All runs (standalone or matrix) log to `history.jsonl`, allowing for per-module regression analysis.
- **Trend Indicators**: Every report includes a **Traffic Light Trend** (🔴/🟢/⚪) and inline terminal delta percentages (e.g., `+5.2%`).
- **Master Leaderboard**: Cross-engine comparison providing a side-by-side "Database Showdown."
- **Percentile Tracking**: Standardized on **p50 (Median)**, **p95 (User Experience)**, and **p99 (Tail Risk)**.

## 🔬 SRE Truth Audit: The Gold Standard

Our "Truth Audit" suite (`truth-latency.test.ts`) is designed to provide SRE-grade credibility by isolating where latency actually comes from:

1. **Logic Layer**: Theoretical minimum (No I/O).
2. **SDK Layer**: Real-world logic with DB/Cache.
3. **Dispatcher Layer**: Framework/Middleware overhead.
4. **HTTP Warm**: Production network performance (Keep-Alive).
5. **HTTP Cold**: Worst-case network performance (TLS/TCP Handshakes).

## 🔗 Relational Performance Testing

With the 2026 update, we've introduced specialized relational benchmarks to ensure that complex data structures remain performant:

- **GQL Nested**: Tests Depth 2-3 relationship resolution.
- **REST Relational Search**: Validates filtering by related fields via the aggregation engine.

**File**: `tests/benchmarks/relational-performance.test.ts`

> [!IMPORTANT]
> **Collection isolation:** Filesystem benchmarks write only to `.compiledCollections/test/<workspace>/`. API benchmarks seed via LocalCMS. The matrix runs `purgeBenchmarkCollectionArtifacts()` before each audit. See [Benchmark Collection Isolation](/docs/tests/benchmark-isolation).

### Unified benchmark runtime flags

GraphQL, scanners, and `compile.ts` all use `isBenchmarkRuntime()` from `preset-collections.server.ts` (checks `BENCHMARK`, `BENCHMARK_MODE`, `BENCHMARK_STABLE`, `SVELTY_BENCHMARK_SUITE`, `TEST_MODE`). Standalone `bun test tests/benchmarks/*` and the matrix server set the same flags so behavior is consistent.

## Running Analysis Locally

To check the bundle size and basic performance locally:

```
bun run build:stats
```

This generates detailed reports including:

- Size of each chunk (raw, gzipped, brotli).
- Comparison with the previous build size.
- Warnings reported if predefined performance budgets are exceeded.
- An exported `bundle-report.json` designed for automated CI consumption.

## 🧩 Widget Performance Auditing (Core & Custom)

As part of the **Enterprise Matrix**, SveltyCMS performs a specialized overhead pass for widgets. This ensures that custom widgets do not introduce "Silent Regressions" into the core API.

### The Audit Process:

1. **Definition Pillar Profiling**: Measures the latency added by a widget's `modifyRequest` and `transform` logic in the server-side pipeline.
2. **Aggregation Stress Test**: Verifies that custom `listSchemas` and search aggregations remain efficient as database sizes grow.
3. **Core Baseline**: All custom widgets are measured against the **Input (Core)** baseline (~0.01ms overhead).

> [!WARNING]
> Custom widgets exceeding a **2ms per-field overhead** are flagged in the matrix as "Performance Hazards" and should be optimized using the **Vectorized Processing** patterns.

---

## 📚 Related Documentation

- [Benchmark Collection Isolation](/docs/tests/benchmark-isolation)
- [Performance Benchmarks (Progress Reports)](/docs/project/benchmarks/index)
- [Enterprise Monitor Dashboard](/docs/guides/configuration/enterprise-monitor)
- [Contributing Documentation](/docs/contributing/contributing-docs)

---

Related

• Test Documentation
• Security Testing
• Architecture Overview