GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

TopicOwner
Languages: messages, catalogs, request languageLocalization
Durable data: identities, transactions, query dependenciesGizDB

The current product, documentation and diagnostics use English.

Contents

  1. Starting from what a web application needs
  2. The GizApp public API
  3. One declarative routing contract
  4. GSX authoring and hydration-free HTML
  5. Streaming, updates and state convergence
  6. Assets, caching and development updates
  7. Actions, data, middleware and operations
  8. Platform placement and deployment
  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:

ResponsibilityExisting ownerRequired invariant
Typed program and contractscompiler/, existing markup and metadata generationOne parser and checker, and one declaration meaning
Transport and framingsdk/net/http.giz, sdk/net/tls.gizCorrect bounded I/O, streaming, cancellation and protocol behavior
URL routing and HTTP policiessdk/net/http.gizOne route contract, one matcher, one encoding and decoding implementation
HTML outputsdk/format/html.giz, app/html.giz, app/markdown.gizEscaped typed output and explicit trusted markup
App shell and browser behaviorapp/app.giz, app/kernel.gizAssets, navigation, updates and the interaction lifecycle each have one owner
Domain schema and actionsmodel/model.giz, generated domain contractsServer validation, forms and tool descriptions come from one declaration
Persistent data and live changesmodel/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 admissionsdk/core/task.giz, sdk/core/system.giz, existing runtimeBounded lifetime, memory, output and concurrency
Hosted projects and deploymentGizStack (stack/), a user of the public API (§8)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

ImportContentsOwner
gizappThe web framework: every export of Exports of gizappweb
gizlang/httpHTTP: the transport (serve, Request, Response, headers, Exchange, streamed replies) and the protocol policy of Exports of gizlang/httplanguage (transport), web (policy)
gizlang/htmlThe 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.

ConcernPublic exportsFile
RoutingRoute, Route.href, Router, Routed, Params, router, mount, MAX_ROUTES, MAX_ROUTE_DEPTH, MAX_ROUTE_NODES, MAX_ROUTE_PATH, MAX_ROUTE_SEGMENTSsdk/net/http.giz
URLs and formspathOf, 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.partssdk/net/http.giz
Replies and cachingtext, 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, logLinesdk/net/http.giz
Compressioncompressed, acceptsEncoding, gzip, MIN_COMPRESSsdk/net/http.giz
Proxyproxy, proxied, returned, balancer, Balancer.sendsdk/net/http.giz
Cookies and credentialscookie, setCookie, bearersdk/net/http.giz
Trace context (W3C traceparent)Trace, traceOf, traceparentsdk/net/http.giz
Content-named assetsAsset, assetsdk/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.

ConcernPublic exportsFile
Page shellShell, 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_MSapp/app.giz
Pages and streamingpage (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; 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), 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), 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) | 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.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.

ImportPublic exportsFile
gizmodel/modelShape, 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, migrateLockedmodel/model.giz
gizmodel/storeDatabase (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_MOVEDmodel/store.giz
gizlang/sqlDatabase (SQLite, or PostgreSQL and GizDB by postgres://), open, Rows, SqlError, sqlError, conflictError, flag, integer, poolOf, quota, POOLsdk/sql/sql.giz
gizdb/localserve: 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/relayLive 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 namePublic nameReason
App.Asset(not exported)The Asset of gizlang/http. One declaration.
Ui.styleuiStyleSays 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

CaseResponse
Known path, unsupported method405 with a complete Allow header
Unknown path404
HEADAn explicit HEAD route has priority. If not, GET handles HEAD and suppresses the body correctly.
OPTIONSExplicit 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).

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

StateOwner
Persistent truthThe database
Announcement of committed changeThe feed (external SQL), the GizDB watch (db.follow)
Explicitly transient interaction stateThe 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 @imports 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 Problems 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; for record declarations see Model your data.
  • 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):

PartContract
CollectionEntries 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
SourceWhere 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 entriesA 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.mdThe 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
BindingData 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
BlockA 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
layoutA 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
FunctionContract
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
LiveThe 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
FailureA binding that fails renders its block as a failed region (Ui.Region, Labels.notAvailable). The page still answers 200
EditingOnly 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.

EventMade byFields and attributes
requestThe serving loop (listen, listenOn), for each answer except a shell assetname (the method), route (the path without its query), status, duration. A document request also has visitor and the attributes referrer, agent and lang.
pageThe kernel, for a page that it opened in placeroute, name (the title), attribute from (the path before)
errorThe kernel, for an error in a page's scriptname (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) 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) 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), 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

ConcernGizApp ownerNot allowed in the hosted runtime
Server loop, compression, assets, request limit and eventslisten, listenOn, Serving, EventA second serve loop, gzip wrapper, handler timeout, request log or analytics script
Anonymous visitorsEvent.visitorA visitor cookie
Store selection from DATABASE_URLstoreA second store opener or SQLite-only DDL
Signed cookies and sessionsSecurity.token, sessionCookie, signed, principal, setCookieA second HMAC cookie or session table format
Routingrouter, RoutePath tests in order (path ===, under)
Responses and pagespage, html, Http.json, Http.text, redirect, ResponseA second Response, page or redirect; a JSON answer whose headers are written by hand
Escapinggizlang/html, GSXA second escape function
Live updatesfollow, changed, live, changes, channel, SUBSCRIBE_MSA second subscription constant, change log or poll protocol
Schema of recordsAction contract, ddl, migrateHand-written CREATE TABLE for framework records
Design tokensuiStyleA 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.