Adonia’s performance contract is evidence-driven. The generated performance report records the benchmark command, environment, samples, medians/percentiles, bundle sizes, and pass/fail targets. This guide explains how application and plugin code stays on those measured paths; it does not publish guessed numbers.
Descriptor compilation
Descriptors and validators are compiled from resource classes and cached per process. Cache identity includes resource, mode, panel, protocol, abilities, locale, tenant scope, lens, plugin identity, and generation. Plugin version/cacheKey must change when its descriptor output changes. Do not attach request records, tenant objects, or actors to process-global caches.
Prefer declarative reactive rules. Server closures that cannot serialize require schema refetch and record-dependent compilation. Keep them for genuinely request-dependent behavior.
Index queries and tables
The query pipeline scopes and shapes a query before pagination/serialization. Avoid per-row database calls in serializers, fields, cells, policies, and plugin hooks. Declare relation columns and eager-load hints so query count remains independent of returned row count. Keep search, sort, and filters on allowlisted indexed columns appropriate to the workload.
Wide tables must remain horizontally operable and virtualize/limit work where the current DataTable contract permits. Do not eagerly import rich editors into the base panel graph; editor components are lazy chunks.
Actions, imports, and exports
Use query/selection target snapshots rather than loading every selected row into web memory. Large exports go through a real queue and stream scoped rows to private storage. Imports stream uploads, cap row/cell/error sizes, validate explicit mapped columns, and write bounded batches. Progress updates should be coarse enough not to turn one row into one database write.
Plugins
Hook handlers run on request-critical paths. Do not perform remote I/O in descriptor, navigation, search-result, or per-record hooks without an explicit cache/budget. Pipeline hooks must mutate the existing builder, not issue a second query per row. Client plugins should preserve lazy boundaries and avoid package-wide side effects.
Application profiling
Re-run the repository harness after changing descriptor compilation, registry resolution, DataTable rendering, query shaping, widgets, imports/exports, or bundling. Profile with representative authorization, tenant, parent, locale, and plugin configuration; a global-resource happy path cannot establish tenant-panel capacity.
Use query-count assertions for N+1 invariants and real browser/Node measurements for render, compile, and bundle work. TypeScript snippets, mocked timers, and hardcoded reports are not performance evidence. Record production-specific database plans and capacity separately from the framework report.