# Kovo — Technical Specification
**Version:** 0.2 (Draft)
**Status:** Normative specification for v1, with staged roadmap through v3
**Audience:** Framework implementers and AI app-builder integrators
---
## 1. Vision
Kovo is a web-platform-native framework for building multi-page applications that **never show stale or inconsistent UI** and are **interactive at first paint with minimal JS and CSS** — achieved by making the whole system legible at every layer and statically verifiable end-to-end.
It composes ideas from prior systems (Qwik, htmx/LiveView, RTK Query, Replicache; full prior-art table in the README) around one organizing constraint: _every artifact the system produces (compiled output, HTML, wire traffic, dependency graphs) must be readable by a human in devtools and checkable by a machine without executing a browser._
### 1.1 Primary goals
Kovo exists to deliver three outcomes, in priority order, all produced by one technique — machine-auditable generation (§1.3). Every other property of the framework — legibility, static verifiability, the auditable wire — is a _means_ to these ends.
1. **Secure by construction.** Whole vulnerability classes — cross-site scripting, SQL injection, broken access control and IDOR, confidential-data exposure, mass assignment, SSRF, request forgery, lost-update races — are not runtime hazards to test for but build/check errors that never ship, or fail-closed runtime floors where static proof is impossible. Kovo makes the insecure pattern _inexpressible_ wherever the same static analysis that proves data freshness can prove it, and forces the residue into declared, audited, suppressible-in-source decisions visible to `kovo explain`. The distinctive claim is not "secure" — every framework says that — but **secure by the same machine-auditable construction that eliminates stale UI**: one substrate, checked without a browser.
2. **Eliminate stale-UI bugs at compile time.** Inconsistent UI states — a badge that disagrees with the cart, a list that didn't reflect its own mutation, two views of one fact drifting apart — are not runtime races to debug but build/check errors that never ship. Kovo makes the staleness it can statically model (§1.2) a `tsc`/check failure, and forces the residue it cannot prove into declared, suppressible-in-source decisions.
3. **Make loading instant.** First paint is interactive, and the bytes to get there are minimal: little-to-no JavaScript on the critical path (global delegation + `import()` on first interaction, not hydration), compiler-scoped CSS with no runtime style engine, and named incremental wire deltas in prod. Performance is a budget the compiler enforces, not a guideline.
### 1.2 Thesis statement
> An application's complete behavior — every handler wiring, navigation target, form field, mutation contract, data dependency, and optimistic prediction — should be provable by TypeScript static checking plus static graph queries, and auditable by reading the page source and the Network panel.
For v1 data freshness, that proof covers staleness caused by this client's own
statically analyzable, modeled writes. Kovo turns those stale-UI paths into build
or check errors, and turns freshness gaps it cannot statically prove — raw-SQL
seams, database-engine side effects, the wall clock — into declared, checked,
suppressible-in-source decisions. Cross-session liveness is an explicit
out-of-guarantee boundary for v1 and belongs to the opt-in live tier (§9.3), not
to the core mutation proof.
### 1.3 Design driver: machine-auditable generation
Kovo is built to be the most machine-auditable compilation target a code-generation agent can emit: generated apps fail TypeScript static checking if wiring is wrong, and intent is verifiable against printed dependency graphs without headless browsers. Where a design choice trades author convenience for machine-checkability, machine-checkability wins. The corollary holds for every reader, not just agents: debugging always proceeds _down_ into plainer code, never _up_ into compiler internals. Machine-auditable generation is the chief _technique_ by which the three primary goals (§1.1) are reached: the same static analysis that lets an agent's output be checked without a browser is what makes whole vulnerability classes inexpressible (the Prime Principle, §2), turns stale-UI paths into build errors, and lets the compiler hold the byte budget.
### 1.4 Explicit non-goals
- **Figma-class shared-workspace apps.** Long-lived client sessions over one mutable heap (collaborative canvases, video editors, DAWs) are outside the sweet spot. Kovo islands can host rich widgets, but the framework will not grow a client router or global client store to serve this segment.
- **Offline-first.** Server truth is unconditionally authoritative; Kovo does not ship a sync engine.
- **App-authored persistent navigation state** in v1. Enhanced navigation may preserve unchanged compiler-stamped layout DOM when JS is present (§8), but the canonical behavior is still real URLs and server-rendered documents.
- **Browser support parity for enhancements.** Speculation Rules and invoker commands are Chromium-led; Kovo degrades gracefully (real navigations, real forms) but does not polyfill them.
- **A sanctioned JSON/REST public API in v1.** Typed public APIs need their own token-auth and schema-reuse story. Until that exists, ad-hoc JSON APIs live only behind declared `endpoint()` entries (§9.1), where their auth and CSRF posture stay visible to audits; `respond.json()` is not a route outcome.
---
## 2. The Constitution (Design Tests)
The framework's overriding commitment is the **Prime Principle**, which precedes and is served by every test below:
> **Security is by construction.** A feature crossing a trust boundary — data coming _in_, data going _out_, _who_ may act, _how much_ — makes the unsafe state inexpressible at compile time wherever static analysis can prove it (over AST symbol-identity provenance, never a branded type or runtime taint, both unsound here; §6.6), falls back to a fail-closed runtime floor where it cannot, and routes every exception through an audited escape hatch surfaced in `kovo explain`. **Default-deny over default-allow; advanced TypeScript types make the safe path explicit wherever they naturally encode the contract, but are defense-in-depth, not the mechanism; runtime floors are labeled as floors, never sold as proofs.** This turns XSS, SQL injection, IDOR/broken access control, confidential-data exposure, mass assignment, SSRF, and lost-update races into build errors or fail-closed floors — checkable without a browser, by the same machine-auditable generation (§1.3) that eliminates stale UI. It is the first primary goal (§1.1) and the lead gate here precisely because it is the highest-stakes property _and_ is delivered by the legibility, declare-once, and static-auditability the tests below enforce.
Every feature proposal is then evaluated against five design tests. A feature failing the Prime Principle or any test is redesigned or rejected. These are normative. The objectives are the three primary goals (§1.1); the tests are how those goals — security included — are kept honest under pressure.
| # | Test | Consequence |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Legibility is load-bearing.** Names appear in HTML attributes and wire traffic, so they structurally cannot be mangled. | Minifiers cannot rename handler exports; debugging never requires decompiling the framework. |
| 2 | **No global knowledge at local sites.** Any API requiring the author to enumerate distant call sites from memory is a bug factory and is rejected. | Killed manual fragment targets, manual per-island optimism, query-side mutation registration, call-site mass-assignment allowlists, and per-handler authorization — security facts (`secret`/`owner`/`governed`/`access`) are declared once and derived everywhere. |
| 3 | **Sugar must lower to authorable IR.** Every compiler feature emits valid Kovo source. Compiling the output is a no-op (CI-enforced fixpoint). | Output is auditable in devtools and mechanically checked; app authors still write TSX. |
| 4 | **The wire is the documentation.** Named POSTs and schema-shaped JSON in every environment; full self-describing HTML fragments in dev; size-optimized but still named/schema-shaped deltas against a version-validated base in prod (§9.1.1). The wire documents what the server **chose to send**, not all it knows: a `secret`-classified field is ineligible to reach the client wire or a client module, so legibility and confidentiality coexist by construction — the dual of output-safety (§5.2 rule 10, integrity), now for confidentiality. | A dev frame is a complete document auditable from the Network panel; a prod frame shows _what changed_, reconstructable via `kovo explain`. Names are never mangled in either mode (#1). A typed `secret` boundary keeps the readable wire from becoming an over-exposure channel. |
| 5 | **Server truth always wins.** No client cache to invalidate; reconciliation is "morph the authority in." | Optimistic predictions are disposable; there is no consistency protocol. |
---
## 3. Architecture Overview
```
AUTHORING COMPILED IR RUNTIME
┌──────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────────────┐
│ cart.tsx │ │ cart.server.js │ │ Self-describing HTML │
│ (JSX, inline │──▶│ render fns, queries │──▶│ • plain elements, kovo-c stamps │
│ closures, │ │ cart.client.js │ │ • on:click="cart.js#Cart$remove"│
│ single file) │ │ named handler exports, │ │ •
```
Components render to **light DOM** as plain, never-registered elements — no shadow roots, no `customElements.define`, no upgrade step (rationale in §3.1). The load-bearing DOM identity is the derived `kovo-c` leaf; the compiler omits it when the host tag already spells the derived leaf (`` — dashed tags are inert sugar) and emits it on native hosts (`
`, so table content-model nesting works). Query-backed server-refreshable roots also carry a derived `kovo-fragment-target`; for singleton components this is the DOM leaf (`cart-badge`), while repeated instances append stable authored identity (`product-form:p2`). Registry and type identities are separately namespaced by module path (§6.1), so global uniqueness never lengthens the ordinary DOM leaf. If two distinct registry keys would put the same DOM leaf on one page, the composition pass derives a stable disambiguated `kovo-c` value from the registry key and reports it through component explain output; fragment target identities use the same disambiguated leaf before any instance suffix. StyleX-authored component styles compile to globally collision-free atomic classes and dedupe into declared stylesheet assets; raw co-located CSS remains an escape hatch scoped to the derived host leaf (`@scope`, donut-scoped out of nested islands) (§13.1). With no shadow boundary, IDREF wiring (`commandfor`, `for`, `aria-*`), native form participation, and find-in-page work document-wide — the L0 layer and no-JS form fallback depend on it. The compiler validates JSX nesting against the HTML content model (**KV225**): markup the parser would re-parent (`
` in `
`, `
` outside a table) makes served HTML and parsed DOM disagree, silently breaking morph identity and fragment targets — a compile error, not a runtime surprise.
**Declarative Shadow DOM is disabled.** A `` carrying `shadowrootmode`,
`shadowrootdelegatesfocus`, `shadowrootclonable`, or `shadowrootserializable` (ASCII casing
insensitive) is **KV236**, including direct/static/dynamic attributes, binding or derive targets,
static spreads, and opaque spreads. There is no app-authored suppression. The server renderer, live
binding paths, inline loader, and response-fragment sanitizer remove those controls and their
control-targeting stamps before output or detached-tree adoption, while preserving ordinary inert
template content. This runtime floor covers uncompiled JSX and hostile response bytes; it does not
make declarative shadow roots an alternate component API. For the same finite-output reason, Kovo
does not render or adopt unsandboxable `object`/`embed` or obsolete `frame`/`frameset` primitives;
use a reviewed sandboxed `iframe` or ordinary navigation/download link instead (§4.8, §5.2 rule 10).
Everything is inspectable in the Elements panel: dependencies (`kovo-deps`), data (the JSON), behavior (`on:*` attributes), pending mutations (`kovo-pending`, §10.3).
### 4.3 Handlers and closures
You author inline closures; the compiler lowers them (§5). The lowered form is the contract:
```tsx
// Authoring (sugar)
```
```js
// cart.client.js — GENERATED compiler IR, never an app-authoring surface
import { securityHandler } from '@kovojs/browser/generated';
/** captures: item.id → element params */
export const Cart$removeItem = securityHandler(
[{ door: 'compiler-state', kind: 'browser.state.write', target: 'state.pendingRemovalId' }],
(event, ctx) => {
ctx.state.pendingRemovalId = String(ctx.params.itemId);
},
);
```
```html
```
**Capture channels (exhaustive):** component/query state (via `ctx`), element params (`data-p-*`, typed — attribute values arrive as strings, so non-string params declare coercion once, schema-style, exactly like form fields §6.3), module scope (shared, not captured). Anything else is compile error `KV201`, whose message shows what the closure _would have_ compiled to and the three fixes.
**Finite browser effects (normative).** Every serialized handler is classified before emission into
the closed `kovo-security-operation-ir/v1` vocabulary. Authored inline handlers currently admit
static component-state reads/writes and exact timer schedule/cancel operations; compiler-generated
primitive handler references retain their separately reviewed event/DOM behavior. The generated
`securityHandler(operations, fn)` wrapper carries the exact compiler-derived list into the immutable
client module. It is a generated ABI and audit witness, not a public authoring helper and not an
opcode interpreter. App source cannot construct, widen, or suppress the list.
A native event and every object reached from it remain capability-bearing. Property or method names
such as `target`, `value`, `preventDefault`, or `focus` are not authority proofs: a synthetic event
can own-shadow them and invoke attacker-selected getters or functions. Authored raw event/DOM member
reads and calls are therefore **KV449** until lowering targets a framework-pinned operation rather
than dispatching through the raw receiver. The same rule closes raw browser globals, computed
terminal operations, and authority that escapes through an alias, destructuring, mutable container,
constructor, or unreviewed call. Exact framework import identity alone does not summarize argument
positions, callback-bearing containers, or return authority, so authored inline framework-helper
calls are also **KV449** until that export has a generated exact summary. Direct primitive handler
references remain the supported path. Named exceptional doors and the server vocabulary are defined
in §6.6, while §5.2 owns lowering and fixpoint behavior.
**Closed handler language (normative).** A browser handler is synchronous and its public function
type returns `void`. A concise body or explicit return may evaluate only closed JSON/scalar data or
an exact finite effect; the loader discards that value. Authority-bearing, executable, or thenable
outcomes are **KV449**. `async`, generators, `await`, `yield`, exception control
(`try`/`catch`/`finally`/`throw`), constructors, `instanceof`, and every tagged template are outside
the language. The loader never performs `PromiseResolve`, reads a returned `then`, or awaits a
handler return. Asynchronous work must use an explicit finite operation such as a timer whose
callback is an exact reviewed zero-parameter callable; source-text timer callbacks and callback
parameters/defaults/destructuring are forbidden. Timer cancellation accepts exactly one
compiler-proven primitive handle or the exact result of a finite timer schedule. Promise factories
and other asynchronous global work are outside the synchronous language. A handler may contain at
most 256 distinct finite operations, matching the generated runtime manifest bound. A timer callback cannot
read, write, or capture handler state, including through an immutable alias: synchronous dispatch
has already committed and retired that state snapshot before the callback runs. Delayed state work
requires a future framework-owned scheduled operation that re-enters the state-host queue and
performs a fresh snapshot/validate/commit transaction.
State may be read and written only through static member targets. Computed or destructured state
targets, binding or assignment default initializers, spreads, `for...of`, `this`, authority-bearing
computed keys or scalar coercions, opaque call/callback results, accessors, constructors/classes, and
implicit object protocols are outside the language. `Object.assign` cannot hide a state mutation
from the compiler-owned state-write IR. A state write expression is built from JSON literals and
dense literal containers, immutable aliases of those values, static state reads, ordinary scalar
operators, and the compiler's exact scalar intrinsics. The callable state-method vocabulary is
closed to `pop`, `push`, `reverse`, `shift`, `unshift`, `endsWith`, `includes`, `indexOf`,
`lastIndexOf`, `replace`, `replaceAll`, `startsWith`, `toLowerCase`, `toUpperCase`, `trim`, `trimEnd`,
and `trimStart`; replacement callbacks are not accepted. The only callback transform on local data
is `map` over an exact dense array literal or its immutable alias, with an exact reviewed callback.
Adding a method requires a SPEC change and adversarial proof of its callbacks, coercions, return
provenance, and mutation semantics; a familiar JavaScript method name is not evidence.
State is also a runtime boundary. Before module import and the first state snapshot, the loader
serializes dispatches per state host so overlapping events cannot read the same stale base. Before
the first handler and after every handler in a chain, it replaces `ctx.state` with a fresh recursive
own-data `JsonValue` snapshot. Arrays must be
dense and use the intrinsic array prototype; records must use `Object.prototype` or `null`; only
enumerable string-keyed data properties are copied; enumerable accessors, cycles, non-finite
numbers, non-JSON values, exotic prototypes, and over-budget graphs fail with **KV449**. The current
bounds are 64 levels, 10,000 values, and 1,000,000 string/key code units. Non-enumerable and symbol
data is outside JSON and is discarded. This runtime check is defense-in-depth after the compiler's
closed verdict, not a substitute for it.
A delegated dispatch is one fail-closed state transaction. After the final handler, the loader first
snapshots and serializes the candidate state. It then prepares the complete state-binding update:
every direct target and derive reference is snapshotted, every derive module is imported, every
owned export and owned `run` function is strictly validated, every derive runs, and the results are
materialized as a closed list of typed text/attribute/property sink operations. Preparation performs
no framework DOM writes. Only after preparation succeeds does the loader apply that list, commit the
serialized `kovo-state`, and drain post-commit callbacks, in that order. A missing or invalid derive
export/`run` is a closed failure, never an implicit `undefined` binding value.
If handler import/export resolution, handler invocation, the post-handler state snapshot or
serialization, or binding preparation throws, the loader aborts the remaining transaction, performs
no binding write, leaves serialized state unchanged, and discards every post-commit callback
collected by that dispatch. If an arbitrary platform DOM setter throws while applying an already
prepared list, an earlier presentation write in that list can remain applied: the web platform does
not provide a general rollback transaction for setters. Kovo still leaves `kovo-state` unchanged and
does not drain post-commit work because that commit happens only after every prepared write succeeds.
Modular and all generated-inline runtimes use the same rule. A later queued dispatch starts from the
last successfully committed state snapshot.
### 4.4 The loader
A gzip-capped inline bootstrap is the only JavaScript Kovo ever puts in a document. Its enforced
ceiling lives in `inlineKovoLoaderGzipByteBudget` (currently 10,500 gzip bytes).
The bootstrap captures first interactions, queues or falls back safely while the
runtime loads, promotes deferred styles, and imports the versioned Kovo deferred
runtime module from the framework-owned `/c/` module registry. The deferred
runtime module is not part of the first-paint byte budget and has no SPEC gzip
cap; it is versioned, cacheable, and loaded by `import()` after the bootstrap's
first-interaction or post-paint trigger.
**Emission is conditional (normative).** The bootstrap is emitted only into a document that carries
client surface — anything below the deferred runtime's responsibilities: an island or delegated
handler or execution trigger, an update-plan binding, an enhanced form, `` truth, a
deferred region, a `deferFull` stylesheet the bootstrap alone promotes (§13.1), an app-declared
module preload or bootstrap script, or a session-dependent/fingerprinted document whose bfcache
restore the runtime must force through the server (§8, §9.3). A document with none of those has
nothing for the deferred runtime to do, so it ships **zero** JavaScript: no inline bootstrap, no
`import()`, and correspondingly no inline-script hash in its `Content-Security-Policy` — a strictly
tighter policy, never a looser one. The test is a deliberate over-approximation read only in the
fail-safe direction: any framework-emitted client marker keeps the bootstrap, and only the total
absence of every marker drops it. A fully server-rendered document therefore also has no enhanced
navigation; it navigates natively, which is the same behavior it already has before the runtime
settles.
Ordering inside `` is fixed by authority class, not by hint kind. Non-executable CSS delivery
— inline critical `