runtime

GenClass documentation

This is the index of the GenClass Runtime documentation: which document answers which question, how current each one is, and where genclass.dev shows it. It covers @genclass/runtime on main (version string 0.3.0-beta.5; npm i @genclass/runtime@beta installs 0.3.0-beta.5, npm i @genclass/runtime installs 0.2.3) and the model @genclass/runtime-model 0.2.0. Items marked 0.3.0 are in the 0.3.0 line (0.3.0-beta.0 and later) and not in 0.2.x. The glossary at the end defines the terms the other documents use.

What is GenClass Runtime?

GenClass Runtime (@genclass/runtime) is an open-source (Apache-2.0) browser library that reports race conditions in web apps while they happen: stale responses that land over newer data, duplicate requests such as double submits, inconsistent state and failure storms. A small model runs on the user's device, in a Web Worker on WebGPU or WASM, and each report comes with its evidence. By default it only reports (observe): it never holds, delays or changes a request, a response or a state write. The opt-in guard mode may act on a few of them: on held-out data it acted on 7.5% of actionable real-app cases at a 0.00% false-intervention rate (7.8% of clear simulated cases at 0.13%), but in the six demos no mode lowered the bug rate (RESULTS.md §1, §5). The heal mode is experimental.

Every measured number (recall, false-intervention rate, cost, size) is in RESULTS.md, with the false-intervention rate next to each recall figure.

Which document answers my question?

document	the question it answers	status	on genclass.dev
Package README	What does it do, and how do I install and use it?	current (0.3.0)	/docs, npm
FAQ	Short answers to the common questions, with links to the details	current
INSTALL.md	Every init and remove flag, the app token, the tested project setups	reference (0.3.0)
DASHBOARD.md	How do I see my app's reports on genclass.dev, and what do login, connect, whoami, logout and dashboard do?	reference (0.3.0)	/docs/dashboard
SINKS.md	How do I send reports to my own logging (the sink record format and the two adapters)?	reference (0.3.0)
API.md	Every export, option, event, action and type	reference	/docs/api
OPTIONS-SPEC.md	Why each configuration option exists and how the options combine	design spec, built	/docs/options
INTERCEPTION.md	Which browser APIs it wraps, what each action does, and how to undo it	reference, checked by a test	/docs/interception
TELEMETRY.md	What anonymous diagnostics are sent, and how to turn them off	reference	/docs/telemetry
PRIVACY.md	What genclass.dev collects and keeps	policy	/privacy
SECURITY.md	How do I report a vulnerability, and how do I check a published tarball?	policy	/security
THREAT-MODEL.md	What could go wrong, or be made to go wrong, and what the code does about it	reference	/docs/threat-model
RESULTS.md	How well does it work, and what does it cost? Every measured number	source of truth	/benchmarks
compat/RESULTS.md	Which frameworks and state libraries does it run in?	generated by the compat runs	/docs/compatibility
AGENT.md	How does my coding agent see a race, replay it and prove the fix? @genclass/runtime/agent and the @genclass/mcp server, its tools and its threat model	reference (0.3.0-beta.1 and @genclass/mcp 0.1.0, not on npm yet)
GenClass for Playwright	How do I put GenClass on every page my Playwright tests open, with seeded network chaos, and get one pull-request report of what it flagged?	reference (@genclass/playwright 0.1.0, the fixture and the reporter, not on npm yet)
Model card	What is the model: size, training data, gate profiles, accuracy	reference (model 0.2.0)
ARCHITECTURE.md	How do the parts fit together, and why are they built this way?	design	/docs/architecture
VISUAL.md	How the measured visual checks work: every check, threshold and exclusion	design; v1 built in 0.3.0	/visual
EXPECTATIONS.md	How flow expectations learn what each user action usually does	design; built in 0.3.0, opt-in, false-report rate not measured
ANALYTICS.md	How interaction analytics count page views, time on page, scrolls and clicks	design; built in 0.3.0-beta.1, not on npm yet
QUERY-CACHE-ADAPTERS.md	Should GenClass ship TanStack Query and SWR adapters?	proposal, not built
CONTRACT.md	The rules for people changing the runtime and its training pipeline	binding, for contributors
CHANGELOG	What changed in each release	current

The repository's README gives the overview, and AGENTS.md the repository map and the rules for coding agents working on GenClass itself.

Glossary

• observe: the default mode. GenClass watches and reports what the model finds; it never holds, delays or changes a request, a response or a state write, and no action runs.
• guard: an opt-in mode. GenClass may also run guard-tier actions when the gate clears: discard, defer, coalesce and delay. They withhold, deduplicate or slow something down; they never invent data or fail a request.
• heal: the experimental mode. It adds the heal-tier actions block, serve_cached, retry, hedge, rollback, resync and plugin actions.
• trigger: the kind of moment at which the runtime may ask the model: delivery (a response or pushed message is about to reach the app), mutation (a state write), request (a request is about to be sent), failure, stall, inconsistency (a learned relation between fields broke), transition (an operation changed state unlike it usually does), error, and ask (a question the app asks itself with rt.ask() or rt.decide(), which offers no actions). Each of the other eight has its own passive action and its own set of actions (API.md, Triggers and actions).
• situation: the short text the model reads at a trigger (sections app, trigger, facts, in_flight, timeline, state, stats), with two standing questions: the diagnosis and the action. Its format is frozen under the tag situation-v2.3. By default (triage: "salient") only salient situations (at least one non-neutral fact) reach the model; the app's own rt.ask() and rt.decide() questions, and plugin questions marked always, are asked regardless.
• diagnosis: the model's label for a situation: expected, stale, conflict, duplicate, inconsistent, failing, transient, slow, overload or unusual.
• detection (likely, possible): a report that something is wrong. Likely: the top diagnosis is not expected and its probability reaches the report gate of the active profile. Possible (0.3.0, observe by default): it reaches the eager profile's lower report value but not the report gate. It prints with console.debug, shows dimmed in the devtools, is counted in summary().possibleDetections and is sent in telemetry as a detect event with tier: "possible"; detect and report listeners and a report function get it only when the app sets detect: "possible", and sinks only with possible: true.
• gate: the policy check before any non-passive action. It applies protected and cross-origin requests, the route rule an operation started under (off or observe rules block it), the mode, allow and deny, the diagnosis (never expected), the model's gate for the active profile, the action limits and the app's onBeforeAction veto (API.md, Policy). Model 0.2.0 ships a gain gate: the estimated gain of the best permitted action over doing nothing must clear a margin per tier and trigger. A model without a gate of its own uses a summed probability of 0.9 (guard) or 0.8 (heal) at balanced; cautious adds 0.05 to both and eager subtracts 0.05.
• profile, aggressiveness: cautious, balanced (default) or eager, or a number from 0 to 1 between them. It selects the model's gate profile: its margins for actions and its report value for detections. The values are in the model card.
• FIR (false-intervention rate): the share of cases where doing nothing was best but the gate fired anyway. RESULTS.md reports it next to every recall figure.
• false-detection rate: the share of decisions on correct traffic that were reported as a problem.
• recall: for detections, the share of real problems reported with the right diagnosis. For actions, on simulated apps, the share of clear cases (the gold label puts at least 0.9 on one permitted action other than doing nothing) on which the gate acted, and on real apps the share of actionable cases on which it acted (RESULTS.md §1).
• hold budget: the longest GenClass may hold a response, message or request in guard and heal while the model decides (policy.holdBudgetMs, by default 1.5 times the model's recent median latency, between 150 and 800 ms). Observe holds nothing.
• late revert: in guard and heal, a state write that already applied and that the model then answers discard for is reverted, but only within 800 ms of applying (LATE_REVERT_MS), if nothing has overwritten it and its operation has written nothing else since. It is reported as such and can be undone.
• local or private host: a page host where the default telemetry stays off: localhost and *.localhost, *.local, *.test, *.internal, *.home.arpa, single-label intranet names, loopback, private, link-local, CGNAT and 0/8 addresses, and an empty host name such as a file: page's (isLocalHost in src/telemetry/config.ts). An intranet or VPN-only production app is on one. Not the same as a development host (src/devhost.ts: http(s) on localhost, 127.0.0.1, [::1] or *.localhost with an explicit port, or *.test), the narrower set where ?genclass= or localStorage.genclass may raise the mode and where the measured visual checks are on by default (THREAT-MODEL.md T8).
• protected request: a request matched by requests.protect (for example protectPreset("payments", "auth")). It is observed and reported but never acted on, nor is anything its response causes.
• measured visual check: a deterministic measurement of a visual or CSS bug (unreadable text, a broken image, a stuck scroll lock, and others) with a documented threshold, reported as kind "check". It is never a model finding and never feeds a situation, the gate or the model (VISUAL.md). One indirect path remains: a check's read that makes the browser lay out a very heavy page can cause a long task, which the runtime's perf observer records as an event the model can read (VISUAL.md section 1).
• flow expectation: an opt-in, deterministic report that a step a user action usually causes (a request, a write, a navigation) did not happen this time (EXPECTATIONS.md). The model is not consulted.
• Jev: the name of TypeSafe AI's typed-decision API, which GenClass is not affiliated with. The GenClass model reads questions in the same request shape (noul, choice and score questions over a state), from the project's earlier research in research/.