Performance Policy
Open Grid treats performance as a versioned regression contract for its own public packages and maintained renderers. The project does not make release decisions from third-party package behavior and does not publish broad comparative claims from CI.
Principles
- Measure production builds with deterministic datasets and pinned tool versions.
- Validate correctness before accepting a performance observation.
- Prefer stable absolute limits and source-bound Open Grid baselines over noisy cross-machine timing comparisons.
- Keep raw benchmark output out of Git; CI uploads generated evidence as artifacts.
- Investigate regressions instead of raising a checked-in limit without an explicit explanation and reproducible command.
Release Gates
The release workflows enforce these Open Grid-owned contracts:
| Gate | Command | Contract |
|---|---|---|
| Bundle | pnpm benchmark:bundle:run | Required gzip ceilings for Open Grid-owned runtime files in every public package. Framework-inclusive example app bundles remain visible as diagnostics and cannot fail a release. |
| DOM structure | pnpm benchmark:structure:run | Mounted row/cell and document node ceilings for standard and wide workloads. |
| Framework heap | pnpm benchmark:framework:heap:budget:run | React/Vue/Svelte retained heap and node-count ceilings after a settled workload. |
| Core scale | pnpm benchmark:core-filter:massive:run | Deterministic 100,000- and 1,000,000-row core processing budgets. |
| Server | pnpm benchmark:server:budget:run | Controlled standard and stress server-data budgets without network variance. |
| Behavior | pnpm benchmark:framework:e2e | Cross-framework correctness for the same Open Grid workload and dataset. |
The checked-in JSON files under benchmarks/ contain the active limits. A limit change is a policy change and must be reviewed with the implementation change that requires it. Browser or measurement-tool upgrades may require a coordinated baseline update when repeated runs show a stable measurement-definition shift across all renderers; unaffected metrics and relative limits should remain unchanged.
Core scaling limits are workload-specific. Row-model construction and filtering keep the 2.0x per-row ceiling. Numeric sorting uses 2.5x, and repeated sort-direction flips use 3.0x, reflecting reproduced one-million-row allocation and garbage-collection behavior on hosted Linux and local macOS. The budget tests enforce both sides of each boundary and continue to reject quadratic scaling.
Bundle targets declare enforcement: "required" or "diagnostic". Required targets must measure artifacts owned and shipped by Open Grid. Diagnostic targets may include framework runtimes and example application code to expose integration changes, but their failures are reported separately and do not change the release result.
React 19 server resource baseline
The server application includes its framework runtime. With the same Open Grid source, Vite 6.0.3 build, and CSS, switching React/React DOM 18.3.1 to 19.2.8 changes the application JavaScript from 266,332 to 317,294 decoded bytes and from 84,710 to 99,786 gzip bytes. These are framework-inclusive application measurements, not a change to the published Open Grid package budgets.
Ten measured runs after two warmups on each standard/stress profile with Chromium 153 recorded 105,809 transferred bytes and 343,690 decoded bytes. The corresponding server resource ceilings are 115,000 and 380,000 bytes, retaining roughly 9–11% headroom. Timing, retained heap, DOM, workload, and required package bundle limits remain unchanged. Future increases still require measured attribution.
Observational Measurements
pnpm benchmark:run records React, Vue, and Svelte measurements for local diagnosis. pnpm benchmark:baseline:run records a longer six-profile Open Grid matrix and writes source-bound checkpoints under .benchmark-results/. These commands produce raw JSON and Markdown summaries; they do not by themselves establish a public performance claim or block a release.
Browser timings vary with host load, browser scheduling, and frame phase. A timing result should only inform a product decision when the source revision, environment, dataset fingerprint, warmups, run count, raw samples, median, and p95 are retained.
External Comparisons
External product comparisons are intentionally outside this repository and outside the required release workflow. If a separate benchmark project is introduced later, it must document feature equivalence, dependency versions, licensing, environment, raw results, and known limitations. Open Grid release health must remain independent of that project.