# GizApp architecture

GizApp (`gizapp`, `app/`) owns pages, actions and live views for the web, terminals and desktop windows. This page
describes their request path, models and owners.

The framework and client kernel form the `app` build unit. GizBrowser imports the same client contracts and kernel.
The internal `app-host` build unit owns `gizapp/host`, `gizapp/tui` and `gizapp/window` over both. It has no separate
package or import name. A web server loads only the framework; a terminal or window app adds its host and renderer.

| Topic | Owner |
| --- | --- |
| Languages: messages, catalogs, request language | [Localization](localization.md) |
| Durable data: identities, transactions, query dependencies | [GizDB](database.md) |

The current product, documentation and diagnostics use English.

## Contents

1. [Starting from what a web application needs](#1-starting-from-what-a-web-application-needs)
2. [The GizApp public API](#2-the-gizapp-public-api)
3. [One declarative routing contract](#3-one-declarative-routing-contract)
4. [GSX authoring and hydration-free HTML](#4-gsx-authoring-and-hydration-free-html)
5. [Streaming, updates and state convergence](#5-streaming-updates-and-state-convergence)
6. [Assets, caching and development updates](#6-assets-caching-and-development-updates)
7. [Actions, data, middleware and operations](#7-actions-data-middleware-and-operations)
8. [Platform placement and deployment](#8-platform-placement-and-deployment)
9. [Developer and agent experience](#9-developer-and-agent-experience)

## 1. Starting from what a web application needs

A request does these things:

1. It identifies a resource.
2. It gives authority and typed input.
3. It does a bounded operation.
4. It returns bytes that a browser or another program can use.

A page must:

- show meaningful content quickly;
- work before optional scripts load;
- keep the interaction state of the user;
- converge on the authoritative server data.

Developers and agents need the same small set of operations that they can find and reproduce. The
hosting location does not change the meaning of an application.

Thus the architecture has these independent responsibilities:

| Responsibility | Existing owner | Required invariant |
| --- | --- | --- |
| Typed program and contracts | `compiler/`, existing markup and metadata generation | One parser and checker, and one declaration meaning |
| Transport and framing | `sdk/net/http.giz`, `sdk/net/tls.giz` | Correct bounded I/O, streaming, cancellation and protocol behavior |
| URL routing and HTTP policies | `sdk/net/http.giz` | One route contract, one matcher, one encoding and decoding implementation |
| HTML output | `sdk/format/html.giz`, `app/html.giz`, `app/markdown.giz` | Escaped typed output and explicit trusted markup |
| App shell and browser behavior | `app/app.giz`, `app/kernel.giz` | Assets, navigation, updates and the interaction lifecycle each have one owner |
| Domain schema and actions | `model/model.giz`, generated domain contracts | Server validation, forms and tool descriptions come from one declaration |
| Persistent data and live changes | `model/store.giz` and `model/relay.giz` (external SQL stores: a change log and a long poll), `model/data.giz` (the database maintainers: `db.follow` over a GizDB watch), existing storage and GizDB owners. One delivery path is the target (the database maintainers, the web maintainers). | One committed truth. Derived views can be built again. |
| Tasks and resource admission | `sdk/core/task.giz`, `sdk/core/system.giz`, existing runtime | Bounded lifetime, memory, output and concurrency |
| Hosted projects and deployment | GizStack (`stack/`), a user of the public API ([§8](#giz-apps-on-gizapp)) | Tenant isolation, immutable provenance and reversible publication |

Composition does not require a monolith:

- Static rendering needs no database.
- An HTTP API needs no browser kernel.
- A database service needs no application UI.

Gizlang modules can be used independently through the existing package model. When a feature is
missing, improve its owner. Never make a parallel router, ORM, schema engine, browser state store or
deployment scheduler.

## 2. The GizApp public API

This section is the only list of what GizApp exports. A web export that is not in this section is
private. The web maintainers own this section. The database maintainers own the rows marked "database".

### Distribution

- GizApp ships in the release train as a compiled module of the installed toolchain. Its source is
  open under the Apache License 2.0 in this repository.
- Every program, local or hosted, imports GizApp from the toolchain that runs it. The project's
  toolchain pin selects the version.
- Never put framework source into a project, an app folder or a package. A copy of the sources in a
  `vendor/` folder is also a source copy.
- The `gizlang:` prefix names a module that the toolchain gives. It does not move GizApp below
  `db` in the package dependencies of `PACKAGES`.

### Modules

| Import | Contents | Owner |
| --- | --- | --- |
| `gizapp` | The web framework: every export of [Exports of `gizapp`](#exports-of-gizapp) | web |
| `gizlang/http` | HTTP: the transport (`serve`, `Request`, `Response`, headers, `Exchange`, streamed replies) and the protocol policy of [Exports of `gizlang/http`](#exports-of-gizlang-http) | language (transport), web (policy) |
| `gizlang/html` | The `Html` type that GSX markup compiles to, `escape`, `escaped`, `attribute`, `raw` (explicit trusted markup), `empty`, `each`, `when`, `Shadow`, `ShadowProps`, `plainText` (the text of markup). The `markup…` functions are the target of markup lowering, not documented API. | the language maintainers (markup lowering), the web maintainers (HTML contract) |

- An application imports `gizapp` for the framework and `gizlang/http` for the protocol. It
  does not import a file from `app/`.
- `gizlang/http` is an SDK module. Storage, the database and the tools can import it.
- `gizapp` is above `db` (`PACKAGES`). No SDK module, `fs/`,
  `db/` or `tools/` file imports it. Thus the framework can use the database without a cycle.

### Exports of `gizlang/http`

These exports are protocol policy, not framework. They have no page, session or store.

| Concern | Public exports | File |
| --- | --- | --- |
| Routing | `Route`, `Route.href`, `Router`, `Routed`, `Params`, `router`, `mount`, `MAX_ROUTES`, `MAX_ROUTE_DEPTH`, `MAX_ROUTE_NODES`, `MAX_ROUTE_PATH`, `MAX_ROUTE_SEGMENTS` | `sdk/net/http.giz` |
| URLs and forms | `pathOf`, `search`, `hostOf`, `mediaType`, `under`, `query`, `encode`, `decode`, `encodeForm`, `decodeForm`, `MAX_FORM_FIELDS`, `MAX_FORM_BYTES`, `multipart`, `Multipart`, `Part`, `PartEvent`, `PartLimits`, `partLimits`, `encodeMultipart`, `FormPart`, `Encoded`, `Exchange.multipart`, `Exchange.parts` | `sdk/net/http.giz` |
| Replies and caching | `text`, `json`, `html`, `redirect`, `toHttps`, `withHeader`, `httpDate`, `parseHttpDate`, `mimeType`, `file`, `fileReply`, `Files`, `files`, `Kept`, `MOST_KEPT_FILE`, `MOST_KEPT_BYTES`, `KEPT_VALID_MS`, `Span`, `ByteRange`, `parseByteRange`, `notModified`, `entityTagMatches`, `precondition`, `rangeValidatorMatches`, `logLine` | `sdk/net/http.giz` |
| Compression | `compressed`, `acceptsEncoding`, `gzip`, `MIN_COMPRESS` | `sdk/net/http.giz` |
| Proxy | `proxy`, `proxied`, `returned`, `balancer`, `Balancer.send` | `sdk/net/http.giz` |
| Cookies and credentials | `cookie`, `setCookie`, `bearer` | `sdk/net/http.giz` |
| Trace context (W3C `traceparent`) | `Trace`, `traceOf`, `traceparent` | `sdk/net/http.giz` |
| Content-named assets | `Asset`, `asset` | `sdk/net/http.giz` |

### Exports of `gizapp`

`app/main.giz` is the module. It re-exports each name below from the private file in the "File"
column. `tests/app/facade.test.giz` imports `gizapp` as an application does.

| Concern | Public exports | File |
| --- | --- | --- |
| Page shell | `Shell`, `Sources`, `Offline`, `Identity`, `Media`, `Enhancement`, `shell`, `sources`, `offline`, `identity`, `media` (the pictures and fonts of the asset graph: their files, the fonts preloaded and their faces linked on every page), `enhancement`, `built` (the elements app/components builds), `client`, `state`, `version`, `pageVersion`, `current`, `WORKER`, `SUBSCRIBE_MS` | `app/app.giz` |
| Pages and streaming | `page` (a buffered document), `pageIn` (one with markup for its head), `html` (a progressive document), `slot`, `fill`, `FILL` (the script that fills a slot), `Later`, `MOST_REGIONS` (its out-of-order regions) | `app/app.giz` |

`Http.progressive(render, release)` owns a streamed response. HTTP/1, multiplexed replies and `Http.play` release
the plan after use, including when an earlier pipelined write fails before `render` starts. An adapter that refuses
a plan calls `plan.dispose()`; a wrapper passes its release callback on. GizApp uses this contract to finish the
handler worker and its children without ending unrelated services of the HTTP server.
| Serving and events | `bind`, `listen`, `listenOn`, `listenOnSecure`, `Serving`, `serving`, `Event`, `Attr`, `Record`, `served` (the answer for an asset or the service worker of a `finished` shell), `finished` | `app/app.giz` |
| Routes | `Handle` (a route's handler of the app context `C`), `route`, `Path`, `path`, `typed`, `link`, `prerender` (the answers of a function for a list of GET paths, written to a folder for `Http.files`), `limiter`, `Limiter.admits`, `limited` (a client over its request limit gets 429 with Retry-After; the client is the socket peer, or the last X-Forwarded-For value when the peer is a configured proxy) (a route whose parameters are the fields of a record: the handler gets the record and `link` takes it), `before` (one policy run ahead of every handler of a route table: it answers in the handler's place or lets the route run), `RenderCache`, `renderCache`, `RenderCache.route`, `RenderCache.invalidate` (the render cache, §6), `serve`; `TOOLS`, `SUBSCRIPTIONS` | `app/app.giz`, `app/kernel.giz` |
| Sessions and origin | `Signed`, `signed`, `principal`, `sessionCookie`, `sameOrigin`, `crossSite` (the refusal the serving loop answers), `secured` (the security headers every answer gets: nosniff, no framing by another site, an origin-only referrer), `referer` (a same-site Referer path), `secret` (the session secret kept in the store) | `app/app.giz` |
| Client limits and the form cookie | `clientOf` (the client of a request: the socket peer, or the last X-Forwarded-For value when the peer is a listed proxy), `Limiter`, `limiter` (at most N requests per client in a window), `Budget` (one limit on a key: at most N events in a window, none within a gap of the last), `Counted` (what a store keeps of a client), `limited` (the routes behind a limiter, a client over its limit gets 429), `KEPT` (the cookie that brings a rejected plain form back to its page) | `app.giz` |
| Inputs and answers | `fields` (a request's text fields), `validatedInputs` and `ValidatedInputs` (typed values and checked files from one multipart parse), `inputs` (the typed row of a Shape), `uploads` (the checked files of its @File fields), `rejected`, `wantsPage` (a browser asks for a page, so an app can show a refusal in its own layout), `answer`, `act`, `respond`, `changes`; live: `live` (the element attributes), `refresh` (the page again), `channel` (the page's live channel: one WebSocket at `/_s`) | `app/app.giz` |
| Forms and patches (namespace `Forms`) | `Forms.Form`, `Forms.compile` (an action's form, posted to `Forms.ACTIONS` + NAME), `Forms.form` (a Shape's form, posted to its own page), `Forms.control` and its type `Forms.Control` (a GSX attribute value that gives a control laid out by hand its constraints from the Shape: `<input name="slug" constraints={Forms.control(shape, "slug")}/>`), `Forms.path`, `Forms.go` and `Forms.GO` (where a form goes after its action), `Forms.Patch` and `Forms.patch` | `app/html.giz` |
| Markdown (namespace `Markdown`) | `Markdown.render`, `Markdown.blocks`, `Markdown.patch`; the one parse of a content page: `Markdown.parse`, `Markdown.Document`, `Markdown.Hooks`, `Markdown.Link`, `Markdown.Fence`, `Markdown.Directive`, `Markdown.Reference`, `Markdown.Attribute` | `app/markdown.giz` |
| Content (the CMS, [§7](#content); namespace `Content`) | `Content.Site`, `Content.Collection`, `Content.Source`, `Content.Binding`, `Content.Block`, `Content.Entry`, `Content.Item`, `Content.Section`, `Content.Menu`, `Content.Tree`, `Content.View`, `Content.Loaded`, `Content.Found`, `Content.Live`, `Content.Access`, `Content.Problem`, `Content.Target`, `Content.load`, `Content.check`, `Content.routes`, `Content.handle`, `Content.markdownPath` | `app/content.giz` |
| Site and documentation components | `Labels`, `Link`, `Heading`, `Callout`, `calloutKinds`, `Tabs`, `Panel`, `steps`, `cards`, `Code` (code or a command with a Copy button; a Markdown fence renders the same ui-code markup), `Search`, `SiteHeader`, `SiteFooter`, `NavSection`, `DocsLayout`, `Pager`, `toc`, `PageActions`, `Stored`, `EditList`, `Editor`, and the props type of each component (`CalloutProps`, `TabsProps`, `SearchProps`, `SiteHeaderProps`, `SiteFooterProps`, `DocsLayoutProps`, `PagerProps`, `PageActionsProps`, `EditListProps`, `EditorProps`) | `app/components/ui.ghtml` |
| Records in GizDB or SQL (namespaces `Data`, `model/data.giz`, and `Query`, `model/query.giz`) | `Data.Db`, `Data.open` with `{ engine }` (the typed records of a GizDB engine this process serves (`Embedded.serve`), read on the thread whose System it takes; `engine.connect(name)` reads through the data actor, for a factory that may make no state of its thread), `Data.connect` (any store: the engine when this process serves it, else SQL on SQLite or PostgreSQL with a `db/feed` for live views; a parameter of a blob, vector or temporal type needs GizDB), `db.inSchema` (the same records in a PostgreSQL or GizDB schema: every table it installs, reads and writes is `schema.table`, and a write names its one table), `db.transaction` (one transaction for a piece of work, such as a page action: a refused write undoes it all; a `db.transaction` of a `Data.Db` that is already in one is a savepoint of that transaction, whose refusal undoes its own writes only), `db.install` (the tables, indexes and columns that are not there, on either store: an old row reads a new field as its default), `db.write`, `db.insert`, `db.save`, `db.update`, `db.remove`, `db.rows`, `db.one`, `db.first`, and the write specs `Data.insert`, `Data.statement`, `Data.changing`, `Data.deleting` (`Data.changing` and `Data.deleting` take a `Query.Query`); live: `db.follow`, `db.changed`, `Data.Changed`, `db.unfollow` | `model/data.giz` |
| Page helpers | `FormSet` (the action handlers a page's forms post to, by name: `FormSet.get`), `ago` (how long ago a time was, as a page says it) | `app/html.giz` |
| File uploads | `Upload`, `Received`, `receive` (the text fields and files of a multipart request), `shaped` (the text fields of a Shape), `acceptable` (a file against an accept list), `MULTIPART` | `app/uploads.giz` |
| Setup checks and the contract | `doctor` (the gaps of the setup, as problems), `doctorReport`, `weights`, `Weight`, `HEAVY_BYTES` (a heavy file); `CONTRACT` (`/_contract`), `contract`, `contractRoute` | `app/doctor.giz`, `app/contract.giz` |
| Assets (namespace `Assets`) | The asset graph: `Assets.build`, `Assets.Graph`, `Assets.Source`, `Assets.Module`, `Assets.Sheet`, `Assets.Problem`, `Assets.minifyScript`, `Assets.minifyStyle`, `Assets.picture`, `Assets.Picture`, `Assets.Variant`, `Assets.font`, `Assets.Font` and the rest of `app/assets.giz` | `app/assets.giz` |
| QR codes (namespace `Qr`) | `Qr.encode` (byte mode, level M, versions 1 to 10), `Qr.Code` and `Qr.svg`; the security page draws the authenticator's key with it | `app/qr.giz` |
| Pages (namespace `Pages`) | File-system routing of `.ghtml` pages: `Pages.Site`, `Pages.site`, `Pages.standalone`, `Pages.hosted`, `Pages.handle`, `Pages.poll`; `Pages.endpoint` (a `.giz` file of the folder: a handler of every method), `Pages.app` and its steps (`Application.theme`, `.admin`, `.signIn`, `.account`, `.actions`, `.mount`, `.handler`), and the rest of `app/pages.giz`; the CLI writes a folder's `.routes` and `.tables` (`tools/cli/sources.giz`) | `app/pages.giz` |
| Controls | `Field`, `FieldProps`, `controlId`, `describedBy`, `SignIn`, `SignInProps`, `Account`, `AccountProps`, `AccountMenu`, `AccountMenuProps` (the account corner of a header: sign in, or the person's menu), `Members`, `MembersProps`, `MemberRow`, `Tokens`, `TokensProps`, `TokenRow`, `Passkeys`, `PasskeysProps`, `PasskeyRow`, `Devices`, `DevicesProps`, `DeviceRow` (the identity components, [accounts](../guides/auth.md)), `DateField`, `DateFieldProps`, `Check`, `CheckProps`, `Chip`, `ChipProps`, `Picture`, `PictureProps` (a picture of the asset graph as an img element with its widths, size and lazy loading), `Icon`, `IconProps` (a named stroke icon in the text colour), `Combobox`, `ComboboxProps`, `Choice`, `comboboxScript` (the giz-combobox element), `Level`, `levelScript` (the giz-level element: the microphone's level, live), `Dialog`, `DialogProps`, `Terminal`, `TerminalProps`, `Desktop`, `DesktopProps` (the giz-desktop element: a Computer's screen over noVNC), `Menu`, `MenuProps`, `Palette`, `PaletteProps` (the ⌘K command list of a product), `Marked`, `MarkedProps` (text with the words a search found marked, as the search found them), `LanguagePicker`, `LanguagePickerProps` (the languages of a site, [localization](localization.md)), `Chart`, `ChartProps`, `Point` | `app/components/*.ghtml` |
| Chat | `ChatMessage`, `ChatMessageProps`, `ChatAnswer`, `ChatAnswerProps`, `ChatReasoning`, `ChatReasoningProps`, `ChatStep`, `ChatStepProps`, `ChatMedia`, `ChatMediaProps` (a picture, a clip or a sound that a model made, in the thread), `ChatEvent`, `ChatEventProps`, `ChatMeta`, `ChatMetaProps`, `ChatStop`, `ChatStopProps` (the Stop button of a running answer, a plain form post), `ChatContext`, `ChatContextProps` (the ring of the context used), `ChatOrb`, `ChatOrbProps` (the orb of an empty chat and of a voice conversation: idle, thinking, listening, speaking), `ChatHello`, `ChatHelloProps`, `ChatWorkspace`, `ChatWorkspaceProps` (the one shell of an agent app: the bar, the conversation on the left, the open surface under its tabs on the right; a phone shows one side at a time) (the empty conversation: the orb, a title and the page's starters), `ChatComposer`, `ChatComposerProps` (the box a person writes to an agent in: a form that posts, or one a script sends), `ModelList`, `ModelListProps` (one list of models for every screen: each row its maker's mark, name, line and note; search, chips and sort when long), `ModelPicker`, `ModelPickerProps` (a button and a menu of a ModelList), `ModelSort`, `ModelSortProps` (the sort menu of a ModelList, as giz.ai sorts its catalog; chatui sorts the rows), `Note`, `NoteProps` (a model's note, such as "Not installed · Free", in the page's language) | `app/components/Chat*.ghtml`, `app/components/ModelList.ghtml`, `app/components/ModelPicker.ghtml`, `app/components/ModelSort.ghtml`, `app/components/Note.ghtml` |
| Chat presentation (namespace ChatUI) | `ChatUI.ModelOption`, `ChatUI.Source`, `ChatUI.Chip`, `ChatUI.chips`, `ChatUI.keyed`, `ChatUI.groups`, the sorting of a model list (`ChatUI.Sortable`, `ChatUI.sortsOf`, `ChatUI.places`, `ChatUI.placeOf`, `ChatUI.sortable`, `ChatUI.inCategory`); who made a model (`Makers.makerOf`, `Makers.makerName`, `Makers.makerSlug`, `Makers.initials`, `Makers.hue`); `voiceScript` (the optional microphone and speech enhancement) | `app/chatui.giz`, `app/makers.giz`, `app/components/src/voice.js` |
| The app's database | `secret`. A .giz app's GizDB folder is in `gizdb/app`, not in gizapp: `Local.store` (a `Local.AppStore`: its db is a client of the folder or of DATABASE_URL; its engine is the one this process serves for the folder, none when another process serves it or for SQL; `Local.AppStore.dispose` ends both) and `Local.app`. A .ts app (`app/start.giz`) opens gizlang/sql only: SQLite at `data/app.db`, or DATABASE_URL | `app/app.giz`, `db/app.giz` |
| A .ts app | `app` (`app(options).listen(port)`: the pages beside the entry, their tables and the database), `App`, `Options`; the tables: `schema` (`schema<T>(name, columns)`: a Shape whose fields are the columns, in their order), `Column`, `key`, `text`, `flag`, `number`, `Limits`, `TextRules`, `Owner`; the TypeScript files of the folder: `Props` (what a handler gets: the request, its URL and its route parameters), `Handler` (the handler of one method), `endpoint` and `middleware` | `app/start.giz` |
| Accounts and sign-in (namespace `Auth`, [guide](../guides/auth.md)) | `Auth.install`, `Auth.signUp`, `Auth.insertPerson`, `Auth.signIn`, `Auth.startSession`, `Auth.current`, `Auth.signOut`, `Auth.signOutEverywhere`, `Auth.devicesOf`, `Auth.revokeDevice`, `Auth.linkFor`, `Auth.signInWithLink`, `Auth.verifyMailbox`, `Auth.resetPassword`, `Auth.newApiToken`, `Auth.tokensOf`, `Auth.revokeApiToken`, `Auth.addPasskey`, `Auth.signInWithPasskey`, `Auth.passkeysOf`, `Auth.removePasskey`, `Auth.signInWithIdentity`, `Auth.linksOf`, `Auth.oidcToken`, `Auth.oidcUserinfo`, `Auth.shapes`, `Auth.SIGN_IN_PAUSED`, the issuer's `Auth.OidcIssuer`, `Auth.OidcAsk`, `Auth.OidcToken`, `Auth.COOKIE`, and the sub-namespaces `Auth.Teams`, `Auth.Gate`, `Auth.OAuth`, `Auth.Passkey`, `Auth.Totp`, `Auth.Oidc`, `Auth.Password`, `Person`, `Session`, `Team`, `Member`, `Invite`, `Proof`, `ApiToken`, `ProviderLink`, `Passkey`, `TwoFactor`, `GroupRole`, `ImportedSession`, `credentialAlg` | `app/auth/main.giz` (the rules in `app/auth/*.giz`) |
| Design tokens and the shared parts | `Pair` (a choice of a form), `uiStyle`, `uiStyleOf` and `uiStyleFor` (the theme as root variables and the components; the Of forms take a base and a dark theme; the For forms take a preset name), `uiTheme`, `uiPreset` and `uiPresetNames` (the default DTCG themes of app/theme and the built-in project presets), `uiComponents` (the components alone, for the components layer of a Tailwind site), `uiTokens`, `uiTokensOf` and `uiTokensFor` (the theme as root variables alone, for an app page that styles its own chrome) | `app/components/ui.ghtml` |
| Data regions | `Load`, `Region`, `RegionProps` (the loading, empty, failed and ready states of every component; its words are `Labels`) | `app/components/ui.ghtml` |
| Charts and pivots (namespace `Visual`) | `Visual.Chart`, `Visual.figure` (the giz-chart element: SVG and its table; ECharts with the enhancement), `Visual.svg`, `Visual.layout`, `Visual.readPivot`, `Visual.pivotTable` and the rest of `app/visual.giz` | `app/visual.giz` |
| Flow diagrams | `Flow`, `FlowProps`, `FlowNode` (a labeled step with its input and detail) | `app/components/Flow.ghtml` |
| Views of relations (namespace `Views`, [§7](#views)) | `Views.Spec`, `Views.Ask`, `Views.Runner`, `Views.Column`, `Views.Edit`, `Views.Opened`, `Views.gate` (a host table through the Gate), `Views.source` (a relation of any SQL source), `Views.derived` (an unlimited read-only relation compiled from the same Spec), `Views.batches` (typed windows with an explicit row budget; oversized results fail), `Views.held`, `Views.handle`, `Views.answer`, `Views.serve`, `Views.selectSql`, `Views.editSql`, `Views.frame`, `Views.restricted`, `Views.cache`, `Views.cached`; `gridScript` (the giz-grid element) | `app/view.giz`, `app/table.giz` |
| The default app of stored Shapes (namespace `Admin`) | `Admin.admin` (with its open function, the actor of a request), `Admin.override`, `Admin.routes` (pages and actions) and the default screens `Admin.list`, `Admin.detail`, `Admin.create` | `app/admin.giz` |
| Row and field permissions of a Shape | `db.as`, `db.from`, `q.rows`, `q.count`, `db.createRow`, `db.saveRow`, `db.removeRow`, `db.install` over the gate | `model/gate.giz`, `model/data.giz` |

### Exports of the data layer

The record model, the store and the feed are the data layer. They live in `db/`, not in `app/`, because a record's meaning (its table, its checks, its JSON, its tools) does not depend on a page. `gizapp` imports them
and does not re-export them. An application imports each one it uses, by its namespace.

| Import | Public exports | File |
| --- | --- | --- |
| `gizmodel/model` | `Shape`, `Field`, `Handler`, `Outcome`, `Rejection`, `Problem`, `Reference`, `Fields`, `Row`, `noFields`, `jsonFields`, `formFields`, `read`, `tools`, `invalid`, `forbidden`, `missing`, `unauthenticated`, `rejection`, `diagnosed` (a store or GizDB failure reaches an action as `f().mapErr((e) => e.rejection())`); the annotations `Table`, `Key`, `Index`, `Unique`, `References`, `MaxLength`, `Pattern`, `Values`, `Column`, `Label`, `Min`, `Max`, `Hidden`, `Multiline`, `Trim`, `Submit`, `Action`; the row: `json`, `values`, `display`, `columns`, `wireValue`, `plainField`, `slotField`; storage: `select` (typed queries of a Shape), `schema` (the checked `Schema.Table`), `ddl` (its SQL text), `migrate`, `migrateLocked` | `model/model.giz` |
| `gizmodel/store` | `Database` (a GizDB folder, or a `gizlang/sql` database), `Engine` (what a serving thread needs to reach the GizDB folder: plain data, so a thread closure may hold it), `open` (a client: a folder must be served), `isFolder`, `placeOf`, `client`, `movedIn`, `move`, `serving`, `gizdbLocation`, `gizdbSocket`, `socketFolder`, `GIZDB_FILES`, `GIZDB_RUN`, `GIZDB_PASSWORD`, `GIZDB_MOVED` | `model/store.giz` |
| `gizlang/sql` | `Database` (SQLite, or PostgreSQL and GizDB by `postgres://`), `open`, `Rows`, `SqlError`, `sqlError`, `conflictError`, `flag`, `integer`, `poolOf`, `quota`, `POOL` | `sdk/sql/sql.giz` |
| `gizdb/local` | `serve`: a GizDB folder served by this process, its engine for typed records as a `Data.Engine` (`Local.store` of `gizdb/app` uses it). The one module of the in-process engine: `gizmodel/data` and `gizmodel/store` import no engine, so a program that never imports this one links none. | `db/local.giz` |
| `gizmodel/relay` | Live updates for external SQL stores (an app on GizDB uses `db.follow`): `Relay`, `Notice`, `Delta`, `relay`, `Relay.ingest` (ordered external CDC notices) | `model/relay.giz` |

### One name for each export

The main application API is the facade. Public subject submodules, including gizapp/pages, gizapp/table and gizapp/view,
are declared by structure/packages. Products import their package names, never implementation file paths.
Forms, Markdown, Content, Data and Visual are also namespaces of the facade. These names differ from the private ones:

| Implementation name | Public name | Reason |
| --- | --- | --- |
| `App.Asset` | (not exported) | The `Asset` of `gizlang/http`. One declaration. |
| `Ui.style` | `uiStyle` | Says what the style is |

### Private

These stay private. Do not export them, and do not document them as API:

- `kernel` (the page client, `app/client/kernel.giz`, linked for a browser and minified: `app/kernel.giz`). The shell serves it as an asset.
- A second HTML writer. GSX markup compiles to the writer of `gizlang/html`; code that writes bytes
  uses its `escape` and `attribute`.
- A session token is `Security.token` of `gizlang/security`. The framework adds no second name.
- A server reads its own arguments (`sys.arguments()`) and gives `listen` the port.
- `listen` serves on `Serving.threads` threads of one process (default `Task.cores()`, `serveThreads` of `gizlang/system`). Each thread calls
  `start(own)` with its own System and gets its own handler; the threads share one port. Every thread starts (its
  shared listener, its handler) before any serves and before `listening` runs: when one cannot (a GizDB app's thread
  that the data actor refuses a session), `listen` prints each reason and returns 1, so no server runs with fewer
  threads than it asked for. A GizDB Pages app holds one data-actor session per thread, two with a mount; the actor
  admits 32 plus two per core (`db/access.giz`). State that
  every thread sees lives in the database. An app that keeps state in its memory sets `threads` to 1. `PORT`, when it is set, wins over the port in the code, as hosts set it.
  A value that cannot go into a thread (a System, a channel) stops the build of `listen`: such an app
  gives the listener of `bind` (the LISTEN address and the announcement) to `listenOn`.
- A live host replaces functions by name and runs `main` once. What an app makes from its code (its shell, routes,
  forms, handler) is a `Live.Made`, which the newest generation makes again: `listen` makes each thread's shell (`look`)
  and handler (`start(own)`) so; `listenOn` takes the two as `Live.Made` values (`Live.made(make)`, or `Live.kept(value)`
  for one that no generation changes). Where each request starts, the serving loop renews the shell, then the handler,
  before the new generation answers. A shell's maker may migrate the stores the generation needs; the page style, the
  assets and the page version follow the shell, and an open page reloads through the version check. A deployed host
  withdraws a generation whose maker fails (`Live.reject`) and the one before it serves again; a development host
  answers 503 with the reason until an edit fixes it (tests/app/generation).
  Presence belongs to the handler value. Subscription requests own their waiting replies and remove them when they
  finish; rebuilding a handler in a request creates no background task or task-owned state that can expire beneath it.
- `listen` serves HTTPS with automatic certificates when TLS_DOMAINS names the site's DNS names
  (comma-separated). Port TLS_HTTP_PORT (80) answers the ACME HTTP-01 challenge and redirects other
  requests to https. ACME_DIRECTORY (Let's Encrypt) issues the certificate, which TLS_DIR (`.tls`)
  keeps and `gizlang/acme` renews at two thirds of its lifetime. ACME_CONTACT is an optional
  mailto: URL. Browsers get HTTP/2 by ALPN, and HTTP/3 over UDP on the same port number (announced by `alt-svc`).
  `listenOnSecure` does the same for a site that keeps its own listener
  (gizstack.com: `stack/main.giz`).
- `app/components/ui.ghtml` holds only controls that a product uses. Add a control with its first
  product use, and add it to the table above.

## 3. One declarative routing contract

Application code declares routes. It does not test request paths in order.

- The SDK compiles the declarations into one immutable indexed router at startup. Later, compiler
  precomputation can remove that startup work without a change of the contract.
- Native request handling resolves one time and dispatches the selected typed target.
- A union target or a typed callback is binding data. It is not another matcher.
- The same route declaration owns its method, pattern, parameter names and target.
- Mounting composes declarations before admission. It does not add a nested chain of pattern parsers at request time.
- Host and tenant selection use trusted host inputs and the same URL policy. Account and object permissions stay with their domain.

### Required semantics

**Validation**

- Validate patterns, duplicate bindings, capture names and limits before the server starts to serve.

**Specificity**

- Literal segments have priority over single-segment captures. Captures have priority over a final rest capture.
- Specificity does not depend on registration order.
- Refuse ambiguous bindings with equal priority. Do not hide them behind an arbitrary first match.

**Decoding**

- Keep segment boundaries, and decode exactly one time.
- Refuse malformed escapes, invalid UTF-8 and forbidden path bytes with an explicit response.
- Decoded parameters never become unrestricted filesystem paths.

**Methods**

| Case | Response |
| --- | --- |
| Known path, unsupported method | 405 with a complete `Allow` header |
| Unknown path | 404 |
| HEAD | An explicit HEAD route has priority. If not, GET handles HEAD and suppresses the body correctly. |
| OPTIONS | Explicit policy |

**Reverse URLs**

- Reverse URLs use the registered declaration. They validate missing and extra parameters, and escape each captured segment.
- Rest captures keep intentional segment boundaries.
- Query fields use the canonical query encoder.

**Limits**

- Bound the pattern size, the route count, the graph size and the matching work for each request.
- Do not use regex backtracking or route parsing for each request.
- Measure matcher allocations.

### Typed parameters

- A route's parameters are the `Params` of its match: names from the pattern, decoded string values.
- A typed link is a small function of the app around the declaration (`Web.link(path, params)`). The compiler has no generic record construction, so parameter records are not
  generated from a pattern. Do not claim compile-time parameter checks.

### One source for each route

- A route declaration owns its method, pattern and target. With `Web.route` the target is the handler
  (`Web.Handle<C>`, a function of the app context `C`, the request and the parameters), and `Web.serve`
  resolves and calls it. A union target (an app.s own `Endpoint` union) is the other binding form.
- Links, forms and redirects use the declaration: `Route.href(params)` builds a path from its pattern, and a
  route without captures uses its `pattern`. There is no second pattern string.
- A page host (`Pages`, GHTML) serves `TOOLS` too, with a tool for each operation on each table of the host (`app/tools.giz`, docs/reference/ghtml.md §5).
- `Http.mount(prefix, routes, target)` composes a part's declarations into an app's, before admission.
  Middleware is a function that takes the request and the next handler (`Http.gzip`); request context is
  the app's `C`.
- A stable domain or action identity is different from its current URL.

Measured: a resolve costs 382-412 ns and allocates 256 B from 10 to 4,096 routes, and 4,097 routes are refused
([bench/app/http](https://github.com/gizai/gizlang/blob/main/bench/app/http/README.md#route-matching-2026-10-14)).

## 4. GSX authoring and hydration-free HTML

### Markup

- Pages, components and screens are `.ghtml` templates. TSX-like markup in a `.giz` expression ("GSX") is the same
  language for a value of a few tags. Both compile to the writes of `gizlang/html`; neither is a second semantic system.
- Typed props, escaped children and ordinary Gizlang functions lower through the existing compiler into HTML writes.
- Static markup stays static output. It is not a serialized client component tree.
- The server implementation and private data never become browser props.

### Controls and Web Components

- Use native HTML controls where their behavior satisfies the need.
- Web Components give reusable interactive boundaries. Do not wrap each paragraph in one.
- Declarative open shadow DOM can render component internals on the server.
- Meaningful content and forms stay in light DOM, and can project through slots.
- Pages with JavaScript disabled keep their meaning and the available native actions.
- `Field`, `DateField`, `Combobox`, `Dialog`, `Terminal`, `Menu` and `Chart` (`app/components/*.ghtml`) are the controls: native elements first (`input`, `datalist`, `dialog`, `popover`, `svg` with a table), a Web Component only where no native element does the work: the combobox, the grid (`giz-grid`, a view of any size on canvas), the chart (`giz-chart`, ECharts over the same table) and the terminal (`Terminal`: `giz-terminal`, xterm.js built by `app/components` like the grid, chart and desktop, over WebSockets, which no native element gives). The keyboard, language, IME and right-to-left behavior are the browser's. `uiStyle()` also covers `prefers-contrast`, `forced-colors`, `prefers-reduced-motion` and print.

### Kernel

The kernel improves delivered DOM. It does not build the DOM again.

- One protocol, two clients. `app/protocol.giz` holds the words a page and its client share: the paths (`ACTIONS`,
  `SUBSCRIPTIONS`, `EVENTS`), the headers (`x-giz`, `x-giz-stale`), the dev topic and the kernel's marker
  (`data-kernel`, on its script and on the `FILL` script). Another browser runs the kernel linked into one script (`app/client/.script`). GizBrowser runs
  none of it: it is the native host (`browser/client.giz`) of the kernel in Gizlang, `app/client/kernel.giz`, which acts
  on a page only through `app/client/page.giz` (its `Page`, the document, and its `Host`, the window and the network),
  so an app's window needs no script realm.
- What only a script can do, a custom element's module and its props, is one file both clients run:
  `app/kernel/elements.js`. In GizBrowser a page that names custom elements (`data-elements`) gets a realm for them
  alone.

- It activates declarative shadow roots on inserted or navigated content, patches existing shadow content, and connects behavior one time.
- Local input values, selection, composition, focus, disclosure state and modal state have explicit owners.
- A navigation closes open popovers and menus. A menu is a `<details>` whose `<summary>` has `aria-haspopup`. Other `<details>` keep their open state.
- The kernel compares the style sheets and scripts of two pages by their written `href` and `src`. A parsed page has no base URL, so its resolved URLs are not comparable. A difference in scripts loads the page in full. New style sheets are put in beside the old ones, and the old ones go when the new ones have loaded, so the page morphs in and keeps its state.
- A form without a handler id, `target`, `data-hard`, a `multipart` enctype or `method="dialog"` (the browser closes its dialog) is sent in place in every GizApp app:
  the page that its answer ends on, after redirects, is morphed in.
- A multipart form with `data-progress` uploads in place. Starting it takes ownership of the next page, so an older
  action's late redirect cannot replace its form or discard its answer. A later navigation still takes precedence.
- A link or form with `data-frame="KEY"` is a targeted navigation. It changes only the element
  `data-k=KEY` (a frame) to that element of the answer. The URL and the rest of the page stay. An
  answer without that element opens as a page. Without JavaScript the link opens the whole page.
- A search field (`type=search`) asks as the person types, also while a Korean syllable is being composed: a bound one
  (`data-b`) through the page's state request, one of a GET form with `data-frame` for that frame. One ask is in flight
  and the newest text goes next, so there is never a request per key.
- A new app version (`bin/gizlang live` loads one into the running host) answers an old page's action
  or subscription with 409. The kernel then fetches the page again, morphs it in and takes its
  version, so typing, focus and scroll stay, also when its style sheets changed. A page whose
  scripts or client module changed loads in full.
- A form with a handler id (data-a) can show an optimistic value and restore it after a rejection. A lost response
  never triggers an implicit mutation retry. A data-cancel control stops the request. An action response from a page
  that was left cannot patch the new page. Field errors preserve existing hint relationships.
- A form with a file input is sent as `FormData`; a file dropped or pasted on it fills the input. An element with
  `data-drop="FORM"` is a drop zone for form FORM, whose file inputs may stand anywhere (`form="FORM"`); it has
  `data-over` while files are dragged over it. Files pasted outside any form go to the page's drop zone. A file form
  with `data-progress="ID"` is sent in place and shows how much went in element ID (its `progress`, and `data-pct`).
- A key named by `data-key` (several keys between spaces; `Space` for the space bar), pressed outside a field with no
  modifier, focuses that field or presses that control (`data-key="/"` on a search box, `data-key="Escape"` on a close
  link). Escape first closes an open `details` menu. `data-hotkey="k"` is pressed by Ctrl+K or Command+K.
- The items of a list (`data-item`) take the arrow keys and j, k: the focus moves between their first links. A key
  pressed in an item goes to the item's own `data-key` control first, even in its closed menu, which opens. A right
  click on an item opens its menu (its `popover` with `role=menu`) at the pointer.
- An item with `data-drag="VALUE"` drags onto an element with `data-into="VALUE"` (not empty): the form named by its
  `data-into-form` gets the dragged values (all chosen items' when the dragged one is chosen) in its `path` field and
  the target's in `to`, and is sent. The target has `data-over` while an item is over it.
- A field with `data-filter="LIST"` shows only the `data-filter-item` elements of LIST whose text holds its value;
  Enter presses the first one shown. A bound field (`data-b`, a state) narrows nothing on the device: the server lists what its
  search found, and Enter still presses the first one.
- A local-state boundary cannot freeze children that the server owns.
- Element removal ends subscriptions and listeners through the existing lifecycle owner.

### Reconciliation

- Sibling reconciliation indexes stable node identities one time for each update, and moves the
  kept native nodes. It must not scan or splice an old sibling array again and again.
- Class, ARIA and other attribute-only changes use the existing patch owner directly. They do not
  serialize and parse a full row again.
- These mechanisms need correctness and state tests for large reorders, and separate measured
  browser profiles. Linear bookkeeping alone does not prove that the total DOM work is linear or fastest.

### Shadow DOM events

- Shadow DOM retargets events, and some events do not cross its boundary.
- Do not claim that arbitrary internal shadow forms work with light-DOM delegation.
- Keep forms projected in light DOM, or register them through the existing component event owner with tested teardown.
- Semantic names, keyboard operation, logical CSS ready for RTL, and reduced-motion behavior are component acceptance requirements.

### Browser logic

- Browser logic stays in Gizlang, through the existing supported browser backend and a minimal platform host bridge. The
  exceptions are the page kernel (`app/kernel/*.js`) and the Web Components of `app/components` (the grid, the chart, the
  terminal, the desktop, the combobox and the voice), which need canvas, pointer, socket and media APIs that the Wasm host does
  not bridge yet.
- For a missing capability, extend that owner. Do not add React, a separate TypeScript application or another client compiler.
- Publish only the interaction code that the page actually needs.

## 5. Streaming, updates and state convergence

### Transport

- HTML emission and transport framing are independent.
- The HTTP Exchange owner supports responses with a known size, and streaming with an unknown size, with correct framing.
- The app shell emits the same document structure through that owner.
- Socket writes give backpressure.
- Cancellation ends child tasks, pending data reads and held resources.
- Never label a buffered complete response as streaming.

### Document start

- Start the document after the critical routing, auth and header decisions, before unrelated slow data completes.
- After the headers commit, failures use the declared stream error boundary or close the response.
  They cannot act as if they replace the HTTP status.
- Keep output, parallel work and outstanding fragments bounded.

### Regions and live updates

- Ordered HTML streams stay useful without JavaScript.
- Out-of-order regions use explicit identities and the existing keyed patch protocol. A progressive
  page writes `slot(KEY, fallback)` in its ordered HTML, then `fill(exchange, regions)` renders each
  `Later` in its own task and writes each when it is ready: a template with the region's keyed
  element and the `FILL` script (`app/kernel.giz`) that replaces the slot. Without script the
  fallback stays. A page opened in place applies the same `FILL`. They do not build the page again
  from client state.
- Frames, polling and live updates share the existing feed, cursor and cancellation owners.
- An app on GizDB follows a selection: `db.follow` opens one GizDB watch per page view (a watch
  reads the changes of its table from the WAL journal, db/access.giz; entry and exit of filtered rows are
  reported with changed keys), `live` writes `data-sub` (the app's topic) and `data-pos` (the follow id),
  and `subscribed` answers one poll of the page's live channel with the patches the app makes of
  the changed keys. `refresh` makes a `page` patch, so an app with no keyed patches renders the
  page again. A follow that is unknown or expired (60 s without a poll; 64 per database) answers
  a `page` patch, and the page follows anew.
- Only the kernel's own request (`x-giz`) opens a watch. The first HTML of a page with a live table carries
  `data-connect` instead, and the kernel asks the page again to subscribe, so a crawler or a browser without script
  holds no lease. A watch that cannot open still answers the page, marked `data-live-error`, and the server log names
  the reason.
- Each page has one live channel: a WebSocket at `/_s` (`App.channel`, opened by the kernel). It carries every
  subscribed element of the page (`data-sub`, from `data-pos`, for `data-src` or the page's address). A channel
  supports up to 64 subscriptions; a larger set closes with code 1009 before any new follow starts. No set is truncated.
  For each subscription it asks the app's answer again from the position that answer gave, and sends only answers with
  patches. A changed set goes on the same socket with a larger generation (`g`): the server cancels the follows of the
  old set, each answer names its generation, and the page drops another generation's answer. A client that names no
  generation (the Data API's live channel) gets the same answers without `g`. A position moves only
  after its patches applied. A lost socket comes back after a second from the positions reached.
  A source other than the store (a Drive folder's kernel events, `Dir.watch`) answers in the same way.
- A grid follows who else has its view open on the same channel: its presence topic (`WITH` and the view's address)
  joins the page to the view, and the page leaves it when its socket closes or its set drops the topic. One task
  (`App.Presence`) owns the set; an answer waits on its cell and sets `data-with` (the other people) on the grid.
- Refuse stale generations. Recover cursor gaps explicitly. Keep the edit that the user has in progress.

### Ownership of state

| State | Owner |
| --- | --- |
| Persistent truth | The database |
| Announcement of committed change | The feed (external SQL), the GizDB watch (`db.follow`) |
| Explicitly transient interaction state | The browser |

- Do not add a second client entity database, form validation engine or implicit write retry.
- Optimistic UI, when it is justified, identifies its pending action. It reconciles with the real
  committed result under the existing domain concurrency contract.

## 6. Assets, caching and development updates

### One graph

- Use one compiler and dependency graph for server code, public interfaces, styles and assets that the browser can reach.
- Development can serve incrementally compiled modules.
- Measured request and transfer cost selects production packaging. There is no "always bundled" or "always unbundled" rule.
- Content hashes identify immutable published bytes.
- Entry preloads come from the graph. They must not load each component in the product.

### Source files

- A script, style sheet or any other text file is a file, not a Gizlang string. A `.giz` file holds it with `import {text} from "./view.css";`, and `text` is the file's bytes as a `string`. A file that is not UTF-8 (a font, an image) exports `bytes` instead: `import {bytes as face} from "./inter.woff2";`. The CLI makes that module (`textModule`), in a program and in a library unit. A change to the file changes the cache key of every importer.
- `app/kernel/*.js` is the page kernel, the `FILL` script and the offline worker, as plain JavaScript. `kernel()` puts the few facts that the server owns (`__CONFLICT__`, `__ACTIONS__`, `__SUBSCRIPTIONS__`, `__EVENTS__`, `__VERSION__`, `__FILL__`, `__ELEMENTS__`) into it and give it to `minifyScript`.
- `app/assets.giz` is the graph of an app's scripts and style sheets. `build` takes sources named by a logical name (`app/cart.js`) and roots, and gives the files that the roots reach (a source that no root reaches is not served), each named by its content, and an import map from logical names to those files, so that a script imports another by its logical name and no file is rewritten. `Graph.preload` lists the static imports of a root; `import("name")` stays lazy. A style sheet gets its `@import`s inlined (`layer(NAME)` becomes `@layer NAME`), is minified, may have a source map. A report names a missing import, an `@import` cycle, a `var(--x)` that no source declares and that has no fallback, and an unreached source.
- Pictures and fonts are files of the app too. `Assets.picture` makes a picture's variants once, when the program starts, so no request resizes one: a lossy WebP for each width no wider than the picture (a PNG when it is transparent, as the WebP coder drops alpha), named by its content. The `Picture` component writes the `<img>` with `srcset`, `sizes`, its width and height (no layout shift) and lazy loading, or `eager` with high priority for the first one seen. `Assets.font` takes a WOFF2 face; `App.media` serves both, links the faces (`font-display: swap`) and preloads the fonts on every page. The offline worker keeps the fonts when the app installs and a picture once a page shows it.
- `minifyScript` removes comments and white space only. It needs statements that end with `;`, as `deno fmt` writes them. It reads code inside a template literal as text, so `import()` there is not an import.

### Asset admission

- Asset admission allowlists modules that the browser can reach.
- It excludes private source, environment secrets, server functions and internal source maps.
- Public interfaces are projected from declarations, not from implementation files.
- Inspection tells why an asset is reachable, its byte cost and its owning entry.

### HTTP caching

- ETag, cache controls, conditional requests, range handling, compression and HTTP variation stay in the existing HTTP and web owners.
- Personalized responses, or responses bound to permissions, cannot go into a shared cache without an explicit correct scope.
- The asset references of a deployment identify the same immutable generation as its HTML.
- An older open page can finish safely after a newer version publishes.

### Render cache

The server keeps rendered answers under one policy, which the router owns (`app/app.giz`). It is the GizApp answer to
Next.js Cache Components and Nuxt `routeRules`. It has one store, one key rule and one validity rule, and it adds no
client state.

- **Declaration.** A route declares what it may keep with the route itself: `cache.route(route, seconds, tags)` on one `Web.renderCache(version)`.
  An undeclared route keeps nothing. A page part that changes alone is a live region (§5) and is not a cached fragment.
  The static shell is the cached answer, and its regions update over the page's one channel.
- **Key.** The route instance, the admitted origin, the path and query, and the request's Cookie, Authorization,
  Accept-Language and Accept-Encoding. An answer whose `Vary` names another request header, or `*`, is not kept: the
  key could not tell its variants apart. HEAD uses the GET representation. Compression happens after the handler.
- **Scope.** An answer to a request that carries a session cookie or an `Authorization` header is private: its key
  includes the digest of that credential. No other person reads it, and a sign-out ends it with the session. Every
  other answer is public. There is no shared scope for personalized answers.
- **What is kept.** Only a 200 that is buffered, has no `Set-Cookie` and has no `Cache-Control: no-store`. A streamed
  answer is answered again each time.
- **Validity.** An answer is used while all three hold:
  - It is younger than `seconds`.
  - Its database version has not moved since it was kept (`db.version()`: the engine's durable commit count). A write
    by any thread, including the request that just wrote, moves the version. So a person reads their own write, and no
    tag is needed for data in the app's database.
  - None of its tags has been cleared since (`cache.invalidate(tag)`): this is for sources outside the database, such
    as a file or another service.
  - A store with no version (SQL over a remote store, or a held transaction, where `version` is -1) keeps nothing.
    Correctness comes first.
- **Store.** One mailbox owns the byte-budget LRU that Views.cached also uses. An invalidation generation fences
  results that were still computing when a tag was cleared.
- **Browser and CDN.** The page keeps its `Cache-Control` and ETag (§HTTP caching), so a kept answer still answers 304
  to a matching `If-None-Match`.
- **Navigation.** The kernel fetches on navigation. It keeps no separate HTML prefetch cache that could outlive
  a mutation or an authentication change. Code splitting stays with the asset graph.
- **Not built.** Partial prerendering of a static shell with streamed holes is not a separate mechanism here: the
  cached shell plus live regions covers it. Parallel and intercepting routes wait for a product that needs them.

Coarse invalidation is the cost of the database version: one write makes every kept answer of that database old.
Per-table versions (the engine's watch rooms) would make it finer. That is a GizDB change, and it stays an option until
a measurement asks for it.

### Hot updates

- Hot updates use the existing compiler meaning graph, app generations and DOM update protocol.
- Compatible updates keep user state. Incompatible changes show an explicit recovery path.
- A failed compile keeps the previous working generation active.
- Every page of a live host carries the newest generation (`data-generation`), static pages and `Local.app` applications such as Desk included. On a loopback address the page's channel (`SUBSCRIPTIONS`, one WebSocket) also follows the `giz:dev` topic. The host answers it when a generation publishes or an edit is rejected (`Live.changed`), not on a timer. A newer generation updates the page in place (`W`). A page busy with an action is not fetched under it: the morph of the answer it waits for compares its generation with the newest one heard.
- A generation that cannot start shows its reason over the page. A failed compile leaves the previous generation serving and shows its diagnostics (`Live.buildError()`). Each live host owns its diagnostic file. Tests: `tests/app/hot` and `tests/app/generation`.
- `Web.doctor` lists the gaps of the setup (the shell, the asset graph, the disclosure audit, heavy files) as the `Problem`s that the graph reports.
- Development and production differ in optimization and observability. They do not differ in routing, schema or security meaning.
- `bench/compiler/live/run.giz` measures a generated program and `bench/compiler/live/desk.giz` the save-to-DOM time of GizDesk in a browser. A body-only edit is checked again in the resident compiler; every other edit is checked whole. Each generation logs its prepare, emit, test and link times.
- The live worker removes CLI startup from warm edits. A worker build error keeps the worker and keeps the previous page with its diagnostics; only worker death causes a restart.
- A direct Desk browser measurement (`desk/main.giz`, `/ml`, headless Chromium, warm resident worker) took 6,006 ms, 5,309 ms and 5,305 ms for three GHTML edits. The initial generation took 10,298 ms. Each edit kept the document, draft, focus, selection and CSS state. This is the current complete-object link cost, not a browser polling delay.

## 7. Actions, data, middleware and operations

### Domain declarations

- A text field marked `@File(accept, maxBytes, multiple)` is a file input. The form is multipart; the field holds the file name (a JSON list with `multiple`); `Web.validatedInputs` checks values and files from one parse and returns both. A larger upload streams through `Serving.uploads`.
- A domain declaration owns input types, constraints, outcome and authority checks.
- Generate server adapters, native forms, structured API errors and agent tools from that declaration.
- Browser hints help users. They do not replace authoritative server validation.
- Route bindings select the operation. They do not copy its permission or billing rules.
- Resolve the session and request context one time. Pass explicit capability values, also cancellation and deadlines.

### Middleware

- Use composable typed request and response transformations for authentication, origin policy, compression, logging and error boundaries.
- Their order and effect boundaries are explicit.
- The serving loop admits one origin per request (`Request.origin`, `Http.originOf`): `Serving.origin`, else `ORIGIN`
  of the environment behind a proxy, else the listener's scheme and the Host. Page alternates and TypeScript
  `request.url` read it; no forwarded header sets it.
- Origin policy is the serving loop's (`listen`, `listenOn`, `edge`): it refuses every request that
  is not GET, HEAD or OPTIONS and that another site sent (`sameOrigin`: `Sec-Fetch-Site`, else
  `Origin` against `Host` or the `X-Forwarded-Host` of the proxy in front) with 403, before a
  handler runs. A handler does not check it again.
- Refuse input before expensive work when its contract is already invalid.
- Bound streamed multipart parts, field sizes, file sizes and total request work through the transport and form owner.
- Never buffer arbitrary uploads. A chooser (`Http.RequestHead`) picks from a request head the requests that
  are answered on their streamed exchange. `listen` makes one on each serving thread (`Serving.uploads`); a one-thread
  listener (`listenOn`, `listenOnSecure`) takes its own as `uploads`, which may hold that thread's state. `Exchange.parts` gives the events of each body piece as it
  arrives (`PartEvent`: start, data, end), within `PartLimits` (parts, head, field, file and total
  bytes; over a limit is 413, a malformed body is 400). It keeps less than one delimiter of part
  data. A buffered request body (up to `MOST_BODY`) goes through the same `Multipart.push`.

### Errors

- A refused request has one answer: a `Rejection` (`model/model.giz`), written only by `rejected`
  (`app/app.giz`). JSON: `{"ok":false,"status","field","message","errors":[{"field","message"}]}`.
- A plain form (sent without the kernel) is never answered with a page of its own. Its rejection goes
  back (303) to the form's page: the page itself for a page form, the page that sent it (its
  `Referer` on this host) for an action. A `__Host-` cookie of 60 s carries the values that were sent
  (never a field whose name says password) and the problems. `page` fills the form again from it, as
  the kernel does in place: the values, and each problem in its `data-err` slot. When the page has
  no such form, the message goes first in the body. Only an action whose page is unknown (no
  `Referer`) gets a short page that says what failed.
- After a plain form's action succeeds, the browser goes to the form's `_go` field (`go`), with each
  `:name` replaced by that field of the answer, as the kernel goes. Without one it goes back to the page.
- A database failure is `diagnosed(status, diagnostic)`. The response then also has `"error"`: the
  diagnostic (stage, declaration, expected, actual, kind, SQLSTATE, native code, retry, permission,
  approval, capabilities, affected rows, fixes).
- A client reads `message` for a person and `error` for a program.
- A handler call over `Serving.limitMs` is cancelled and answers 504; a fault answers 500. Both go through `refusal`: a page for a browser, the JSON error for a program.

### Data

- Queries, relations, migrations and scoped writes stay with the existing typed model, store and GizDB contracts.
- A shape's table has one schema, `Model.schema` (a checked `Schema.Table`). GizDB gets it as native commands
  (`Tree.defineCommands`, no SQL text parsed); an SQL store gets its text (`Model.ddl`).
- Relations are declared on the field: `@Model.Unique("NAME")` groups fields into the unique key
  TABLE_NAME, and `@Model.References("TABLE", "COLUMN", "restrict" | "cascade" | "set null")` is the
  foreign key TABLE_COLUMN_fkey. Both are in the schema, so GizDB, PostgreSQL and SQLite refuse a write
  that breaks them. A table made before the annotation keeps its rows and does not get the constraint.
- Typed queries: `Query.from<T>()` holds a read's conditions, order and limit as a tree. `Query.prepared` makes a
  prepared tree of it for any data source, and `rows`, `first` and `count` of a `Query` that holds a `Db` (`db.from<R>()`, `q.on(db)`) run it; `db.insertAll`,
  `db.update` and `db.remove` write. `model/sql/render.giz` prints every tree for its dialect; no caller writes SQL text.
  On GizDB a read of a tree is printed with its values bound, and its plan is cached under that text, so reads that
  differ only in values share one plan, as prepared statements do. Its text is parsed only to plan it.
- `migrate` is additive: it makes the table, adds each new column (a required one with an empty default),
  renames a column named in `@was`, and makes the indexes. It never drops or converts a column.
- Do not build a new ORM for framework parity. For application connections and live subscriptions,
  see [Data access](../guides/data-access.md); for record declarations see
  [Model your data](../guides/model.md).
- Migrations have a plan that can be reviewed, versioned execution evidence and explicit recovery.
- Destructive resets are different from ordinary startup.
- Transactions and committed feed publication agree.
- Actual data dependencies and resource admission limit query parallelism. Accidental sequential component traversal does not.

### Views

`Views.derived` compiles a reusable read-only relation from the same Spec. `Views.joined` pushes an inner or left
equality join into one admitted source, checks key types and output names, and preserves the inputs' restrictions.
The result has no inferred unique key. `Views.lineageOf` projects value and row-membership dependencies gathered
by that compiler. Hosts seed table identities; raw SQL remains incomplete unless a host supplies checked lineage.
`Views.restricted` omits hidden field identities from this metadata. `Views.quality` counts total rows and rule
violations in one statement; NULL fails a predicate, while uniqueness excludes NULL. These APIs create no new
execution engine, result store or policy path.

One protocol serves every relation to every element. A view is a Runner: a relation, its typed columns, a bounded `fetch` and an
`apply` of changes in one transaction. `Views.gate` makes it for a host table through the Gate, and `Views.source` for a table or a
SELECT of any SQL source. `/_view/TABLE` is a table of the app as the person of the request may use it; `Application.view(NAME,
viewing)` adds the views of a program at `/_view/NAME/REST`, for the owner. An element posts a JSON Ask (`describe`, `rows`,
`aggregate`, `values`, `profile`, `reduce`, `marks`, `apply`, `export`, `save`, `import`) with a ViewSpec `{fields, sort, filters, search, groups, measures,
pivot, computed, where}`. A measure is an aggregate of a column (count, distinct, sum, avg, min, max, median, p25 to p99, stddev,
variance) or a measure expression over aggregates, such as `sum(amount) / total(sum(amount), region)`: `total(x, g…)` is x over every
group, or over the groups that share g. A pivot shows a measure as it is, as a share, a running total, a rank, a difference or change from
the previous column, or a moving average, and sorts its rows by a measure, keeping the top N of each group. A chart (`giz-chart`) also draws a funnel, a gauge, a radar, a waterfall and a KPI (one
measure as a number beside its target), and over a bar or line chart reference lines (`data-ref`: avg, median, pNN, a target) and a
least-squares trend line (`data-trend`). The database does the work: it answers a window of rows, a group level, or a bounded reduction (bins, a 2D bin, time buckets,
M4, candles, quartiles, the top groups) as one binary columnar frame (GZV1), so the size of a relation never reaches the browser. The top N groups of a
category end with one row of the rest (X NULL; the head says how many groups it folds), its measure taken over its own rows. A map (`data-mark="map"`, X the longitude and Y the latitude) is a 2D bin drawn in the Web Mercator projection, over the raster tiles of the server that `data-tiles` names (none by default). While a line is brushed, each linked chart of a view draws the moves from one cube of its reduction (`cube`: each group per step of the brushed column, its measure in parts that add up; at most `CUBE_CELLS`, so a chart of more groups brushes in fewer steps), and asks the exact answer when the brush rests. A change names its row by
the key and carries each cell's old value: a cell that someone changed meanwhile is a conflict, and the whole request is undone.
A window of a keyed view starts after a row (`after`: its sort fields and keys, NULL last on every dialect) instead of at an offset, so
it never reads the rows before it; a jump starts at the nearest of the `marks` (every Nth row's order values). One `profile` ask
profiles many `columns` in one scan, with every histogram in one more statement. An export reads its windows the same way.
A calculated column (`computed: [{name, expr}]`, at most 16) is an expression over the columns: names bare or in `[brackets]`,
numbers, quoted texts, `true`, `false`, `null`, the operators `+ - * / % & = <> < <= > >= and or not`, and `IF`, `AND`, `OR`, `NOT`,
`ISBLANK`, `COALESCE`, `ROUND`, `ABS`, `FLOOR`, `CEIL`, `UPPER`, `LOWER`, `TRIM`, `LEN`, `LEFT`, `RIGHT`, `CONCAT`, `YEAR`, `QUARTER`,
`MONTH`, `DAY` and `PERIOD(date, unit)` (the text of the year, quarter, month or day that holds the date: `2026-Q4`, `2026-10`; it sorts
by time). It compiles to the SQL of the dialect, so it sorts, filters, groups, pivots, charts and exports as a stored column; `/` gives a
float and NULL for a zero divisor, and `&` joins NULL as empty text. It is never edited. `where` is a condition in the same language (`amount > 100 and region = 'EU'`), beside the
filters; it may name a calculated column. `export` streams every row (at most 1M) as `csv`, `xlsx` (typed cells; `protect`
makes a read-only workbook), `parquet` or `pdf` (a landscape table report under `title`). `save` writes the same file
into the owner's files instead (`Opened.save`; `describe` says `keeps`): Desk puts it in Drive `Exports/`, which keeps the
old file as a version. One `apply` takes at most 100000 changes (`CHANGES`), in one transaction. An import is its own
request (`Views.importing`): a POST whose body is the file, a CSV (`text/csv`; `,` `;` or tab, a BOM is dropped; a coded body, such as a `.csv.gz`
sent with `content-encoding: gzip`, is undone by `Http.decoding`) read as it arrives, or an Excel workbook (at most 64 MiB). Its ask is
URL-encoded JSON in the `giz-import` header: `columns` maps each file column to a view column (by default, the column of the
same name or label), and `dry` answers the head and the first rows. An empty cell without quotes is NULL; `""` is an empty
text. `Runner.load` takes the rows as the file's own CSV fields, not decoded, at most 10000 rows or 4 MiB at a time: a
record whose columns all map in order goes on whole. A runner without `load` applies each 10000 as inserts. Desk appends
them to a file in Drive `Imports/` (a new key last, when the table's `id` is not in the file) and loads that file in one reviewed Run (`data.import`): COPY on
PostgreSQL and GizDB, else INSERTs in one transaction (`Session.load`). `notes` and `note` read and keep one note per cell, by row key and column, where the host keeps them
(`Opened.notes`; `describe` says `notes`): Desk keeps them beside the connection (`data_notes`). The grid marks a noted cell with a
corner, reads the note as the cell's ARIA description, and edits it from the cell menu or Shift+F2. `history` reads the changes of one row, newest first,
where the host keeps them (`Noting.history`; `describe` says `history`); the record layout lists them under the row. A column's `kind`
(a no-code field kind: currency, percent, rating, select, multi_select, url, email, phone, long_text, attachment, …) picks how the grid shows
and edits it. The `form` layout is a new row: each editable column empty, sent as one insert.
`Views.restricted(runner, when, hide)` is a runner as one person reads it under rules: only the rows where one of the conditions holds
(none: no row), without the hidden columns, read-only. `Views.cached(runner, cache, scope, seconds, now)` answers a repeated read of the
same SQL from `Views.cache` (one per host, least recently read dropped first past 64 MB) for SECONDS; a change through it clears its
scope (`Cache.clear`). The SQL holds the rules, so one key serves everyone. The dialects are PostgreSQL, MySQL, SQLite, SQL Server,
Oracle, DuckDB, ClickHouse, Snowflake and BigQuery (`gizmodel/sql/types/dialect`).
`Views.selectSql` and `Views.editSql` give the same SQL to a program that runs it its own way (a reviewed batch). Tests:
`tests/app/view.test.giz`, `app/components/giz-grid.test.js`, and `tests/app/grid` (3,000 rows imported through the view, in a browser, desktop and
phone: both layers, the ARIA grid, keys, the jump to the end, the timeline). Measurements: `bench/app/view`.

The element `giz-grid` (`app/components/giz-grid.js`, served by `gridScript`) is the client of a view. It holds no view
semantics: every filter, sort, group, pivot, expression and reduction runs in the database, so there is one engine. It draws on two
canvases: the cells, drawn again only when the data, the scroll or the layout change, and the marks over them (the selection, the
active cell, the fill handle, drag guides), which a pointer move or a key draws alone. An ARIA grid mirrors the drawn window. The
grid is one plain JavaScript module embedded in the server, with no build step, and an exception to the browser logic rule below:
the Wasm host gives a page no canvas, pointer or fetch bridge yet. It moves to Gizlang when that bridge exists.

Views of one `data-link` filter one another: a grid's filters and picks, a chart's brush, and the controls of a `giz-filter` (a search,
a range as `data-op="ge"` and `"le"`, a multiple select, checkboxes; each control's `name` is the field). Each tells the others its
filters with one `giz-link` event (`linked` in `giz-grid.js`, the one owner); a view takes only the filters of its own fields. A view that
joins asks the others to tell theirs again, so the order of their start does not matter, and one that leaves takes its filters back.

### Content

`app/content.giz` is the one CMS of GizApp: documentation, marketing pages and blogs use it. There
is no second Markdown renderer, menu builder or `llms.txt` writer. A site is a value (`Site`):

| Part | Contract |
| --- | --- |
| `Collection` | Entries under a URL prefix (`route`). `shape` (a `Model.Shape`, from `Model.shape<T>()`) types the frontmatter. Each field is checked as a form submission is. The fields `description` (required by the site's shape), `nav: hidden` and `aliases` have a meaning to the CMS |
| `Source` | Where the texts of a collection come from. `files`: the `.md` files under a folder of the site root, that is Git content in the deployed tree. A folder that is the root of another collection belongs to that collection. `storage`: the `.md` objects of a bucket of a Storage store (`Volume.Client`), each at the version that its ref `published` names; `folder` is where `nav.md` sees them. Each source gives the same texts, so nothing after `load` depends on the source |
| Routes of entries | A file's route is its path under the collection's `route`, without `.md`; `index.md` is its folder. `aliases` (space-separated paths) answer `301` to the entry |
| `nav.md` | The menus: `# ` a menu, `## ` a section, a link an item. A link to a `.md` file is that entry, and empty link text means the entry's title. `[](folder/)` lists the entries under the folder that no file link and no deeper folder link lists, in file order, without hidden entries. Any other link needs its text. Each entry is in a menu or has `nav: hidden` |
| `Binding` | Data that code owns. Content shows a scalar as \{{name.path}}, and gives a value to a block as `data="name.path"`. `read` gives JSON for the request; `version` changes when the data changes |
| `Block` | A GSX function that content calls as `:::name{key="value"}` … `:::`. `props` (a `Model.Shape`) checks the attributes. The built-in blocks are the callouts (`> [!NOTE]` and `:::note` … `:::caution`), `tabs` (`@tab LABEL`), `code-group`, `steps` and `cards` |
| `layout` | A GSX function from `View` (the nav tree, the entry, its article, headings, pager, Markdown URL, canonical URL and source text) to the page. The components of `app/components/ui.ghtml` give the parts. `text` (`Labels`) gives every word of the components from the site's message catalog |

| Function | Contract |
| --- | --- |
| `load(root, site)` | Reads and parses every entry and `nav.md` once. It also makes once what requests read: the route of each entry path (`Found`), the layout markup of each entry that uses no binding, `llms.txt` and `sitemap.xml`. Gives `Loaded` with every `Problem` (file, line, message) of frontmatter, titles, blocks and their attributes, binding names, nav links, unlisted entries and repeated routes or aliases. A problem leaves out only its entry or nav item: that page answers 404 and the rest of the site serves. A test of the site keeps `problems` empty; the program reports them |
| `check(loaded, router)` | Every link of every entry and of `nav.md` that is a site path has a route in the program's one router. Each binding that an entry uses reads once, within `MOST_BINDING` bytes. Each \{{path}} gives a scalar and each `data=` path a value. The program decides if a check problem stops its start |
| `routes(loaded, wrap)` | For each entry of a `files` collection: its page, its Markdown (`markdownPath`: `/docs/quickstart.md`, `/index.md` for `/`) and each alias. For a `storage` collection: its route, the route's Markdown, every path below it, and its editor (`ROUTE/_edit`, `ROUTE/_edit/*page`, GET and POST). Then `/llms.txt`, `/llms-full.txt` and `/sitemap.xml`. `wrap` makes each `Target` a target of the program's one route graph |
| `Live` | The `Loaded` that requests read now (`current`, a `Ref`) and `reload`, which loads the site again. The program owns the root and the site, so it gives `reload` |
| `handle(live, shell, target, request, access)` | An `entry` target finds the entry of the request path, so a stored entry answers as soon as it is published. A page is `App.page` around the layout (ETag of the bytes, `304`). The text outputs carry an ETag of the content version and the versions of the bindings they use, and answer `304` before they render. An entry without a binding renders once, at load; an entry with one renders for each request |
| Failure | A binding that fails renders its block as a failed region (`Ui.Region`, `Labels.notAvailable`). The page still answers `200` |
| Editing | Only for a `storage` collection. `access(request)` gives the `Access` of the request: its actor, the grants it holds and the scope of the site (a team). `Security.decide` on `[SPACE/collection/NAME, scope]` needs `editor` to open, save and review, and `manager` to publish (else `403`). The program owns sign-in and grants; Content owns the roles of the steps. A POST must also be same-origin (`App.sameOrigin`). `ROUTE/_edit` lists the pages and their refs (`Ui.EditList`); `?name=SLUG/SLUG` opens a new page. `ROUTE/_edit/NAME` is the editor of `NAME.md` (`Ui.Editor`): the draft, its problems and its preview. A save puts a new version and moves ref `draft`; a review moves `review` to the draft and needs a draft without problems (`422`); a publish moves `published` to the review and stores `reload()` in `live`. Each move names the version that the page showed (`Volume.Client.moveRef`), so a lost race answers `409` and keeps the typed text. There is no unpublish |

- `llms.txt` lists each menu section with the entries of the section: the title, the Markdown URL
  and the description. `llms-full.txt` is the Markdown of every listed entry.
- gizstack.com is a site of this contract (`stack/site.giz`). Its developer documentation stays in
  Git, so each example is tested with the commit that changes it. Its blog is a `storage` collection
  in an embedded store under `STACK_HOME/storage`. The gizstack team edits it: a membership is its grant (`Actions.teamGrant`), so the owner (`STACK_ADMIN`) and admins publish.

### Events

Product analytics and the server's spans are the same wide events
. An app adds no line for them.

| Event | Made by | Fields and attributes |
| --- | --- | --- |
| `request` | The serving loop (`listen`, `listenOn`), for each answer except a shell asset | name (the method), route (the path without its query), status, duration. A document request also has visitor and the attributes referrer, agent and lang. |
| `page` | The kernel, for a page that it opened in place | route, name (the title), attribute from (the path before) |
| `error` | The kernel, for an error in a page's script | name (the message), route, attribute at (`FILE:LINE:COLUMN`) |

- **Page views need no script.** A page that the browser loads is a document request (`Sec-Fetch-Dest: document`).
  The kernel reports only what the server cannot see. A page without the kernel sends nothing.
- **One trace.** An answer continues the request's `traceparent`, else starts a trace. The handler sees the
  answer's span as its caller (`traceparent` header). An HTML answer names its trace in `Server-Timing`. The
  kernel gives the page's events that trace, with the answer's span as parent.
- **Visitor without a cookie.** The visitor is a hash of the host, the address (`X-Forwarded-For`) and the user
  agent, under a key of the UTC day. The key is random for each process and stays only in its memory. A browser
  with `Sec-GPC: 1` has no visitor. A signed-in person is the principal, which the record names.
- **The kernel sends no field values and no page text.** The referrer of another site is its origin only.
- **Policy is the record's job.** `Serving.record` receives each event with its request on the thread that answered.
  It names the principal, masks fields, drops what the person did not consent to, and writes the one event store.
  `serving()` has no record, so the loop does no event work.
- Pages send events in one beacon to `/_giz/e` (same origin only, 32 events and 16 KiB at most), when the page is
  hidden or at 20 events.
- Not supported: DOM replay events, Web Vitals and `exposure` events of flags.

### Operations

- Background jobs, realtime feeds and hosted development use the existing task, storage and deployment owners.
- A job has explicit authority, deadline, output and recovery semantics.
- Native resources and subprocesses are capabilities. They are not global environment access.
- Public compiler workers and browser assets contain no tenant secrets.
- Keep the existing project IDs, data, memberships and deployments through the GizStack upgrade.

## 8. Platform placement and deployment

### Rendering targets

The complete platform also includes SSR and SSG, SEO, PWA and offline, edge and distributed
execution, through the same renderer, route and capability contracts.

- Generate static output from declared inputs and the same HTML writer. Do not add an SSG framework.
- Offline shell caching never silently replays server actions.
- Browser or edge placement follows supported effects and explicit authority.
- Automatic placement requires measured transfer and resource cost, and compatibility evidence.

### Standalone web server

The target for the standalone web server includes, through the existing HTTP, TLS and task owners:

- HTTP/3 (HTTP/1.1, HTTP/2, WebSocket and automatic TLS certificates are in `gizlang/http`,
  `gizlang/tls` and `listen`);
- typed reverse proxy and load balancing (`Http.proxy`, `Http.balancer`);
- rate limits.

> **Note:** These are required coverage targets. They are not claims that the current implementation
> already replaces nginx, Caddy or the deployed Traefik.

Retire a production proxy only after its exact protocol, certificate and recovery gates pass against
a reversible migration, measured in the existing benchmarks.

### Generation transition

Development and production converge on one verified generation transition:

1. impact analysis;
2. incremental check and compile;
3. selected meaningful tests;
4. artifacts with content hashes;
5. explicit state migration;
6. atomic activation.

- Canary admission, rollback, deterministic replay and observation use that transition.
- Keep these identities different: declaration identity, meaning hash, memory layout, stored schema identity and artifact hash.
- Code rollback is not data restore, and not compensation of external effects.
- GizDB ([database](database.md)) owns the durable data contracts. The web layer uses them.

### Giz Apps on GizApp

A Giz App is an application that GizStack hosts. It is an ordinary GizApp program.

**Dependency**

- The app imports `gizapp`, `gizlang/html` and `gizlang/http` ([§2](#2-the-gizapp-public-api))
  from the toolchain that runs it. A local app does the same.
- The app folder holds only the app: its sources, its tests, its manifest, its data and its live
  generations. It holds no framework source and no copy of a GizApp file.
- Do not copy framework files, rewrite import text, or relocate a framework module.

**Version**

- The project manifest pins the toolchain identity. That identity selects the GizApp version.
- The host runs each app with the toolchain that its project pins. A new platform toolchain does not
  change the pin of a running app.
- A deployment records the app artifact and the toolchain identity together. A rollback restores
  both. A change of the pin is a new generation ([Generation transition](#generation-transition)),
  with its tests.
- The GizStack host gives each app the `gizapp` of its own toolchain. It puts no framework source into the app
  folder.

**Sandbox**

- The manifest that the platform writes grants the imports of the app. A `gizlang:` module is part
  of the toolchain. Thus the app needs no read access to a framework path.
- The app reaches the database, the platform API and secrets only through the capabilities that
  the host gives it. Its isolation stays as GizStack defines it.

**Owners that a hosted app uses**

| Concern | GizApp owner | Not allowed in the hosted runtime |
| --- | --- | --- |
| Server loop, compression, assets, request limit and events | `listen`, `listenOn`, `Serving`, `Event` | A second `serve` loop, gzip wrapper, handler timeout, request log or analytics script |
| Anonymous visitors | `Event.visitor` | A visitor cookie |
| Store selection from `DATABASE_URL` | `store` | A second store opener or SQLite-only DDL |
| Signed cookies and sessions | `Security.token`, `sessionCookie`, `signed`, `principal`, `setCookie` | A second HMAC cookie or session table format |
| Routing | `router`, `Route` | Path tests in order (`path ===`, `under`) |
| Responses and pages | `page`, `html`, `Http.json`, `Http.text`, `redirect`, `Response` | A second `Response`, `page` or `redirect`; a JSON answer whose headers are written by hand |
| Escaping | `gizlang/html`, GSX | A second escape function |
| Live updates | `follow`, `changed`, `live`, `changes`, `channel`, `SUBSCRIBE_MS` | A second subscription constant, change log or poll protocol |
| Schema of records | Action contract, `ddl`, `migrate` | Hand-written `CREATE TABLE` for framework records |
| Design tokens | `uiStyle` | A second palette |

- GizStack's own capabilities for an app (documents, jobs, feedback, the platform API) are a
  GizStack library on `gizapp`. They do not repeat a row of this table.
- A missing capability is a gap of its GizApp owner. Report it to the web maintainers with a reproduction. Do not
  add it to the hosted runtime.

**Acceptance**

- Existing apps start again on the new runtime with their data, IDs and deployments.
- The app folder contains no framework source.
- Each owner in the table above has one implementation in the repository.

## 9. Developer and agent experience

### One project and CLI

- One Gizlang project and CLI give editing, checks, runs, tests, inspection and publication, locally and in GizStack Cloud.
- Do not add a lock file only for the web, a project schema only for the cloud, or an action model only for agents.
- Diagnostics show stable codes, source spans and actionable English messages.
- Machine output separates validation failure, authority denial, resource admission, timeout and runtime failure. It never invents success.

### Agents

- Agents inspect the same route and domain contract that humans use. They get bounded tools, and receive the exact executed IDs and revisions.
- Tool descriptions are public declarations projected by the compiler.
- Requests never show a provider secret or private core source only to make an agent productive.
- `Web.contractRoute` serves `/_contract`: the version, routes, actions, subscription path and served files, made from the declarations.
- A site of pages answers `/_contract` from `site.router.declarations()`. GHTML page events are not in it: they run
  only from a rendered page of the current revision. An operation for agents is an endpoint or an action.
- Starters for new projects use real routes, forms, markup and storage contracts. They do not use disconnected mock pages.
