Stability
What Quantum promises, tag by tag. From 1.0, Core and AI follow semantic versioning: a 1.x release does not break a program that uses only them — their meaning is fixed by the rules in the SPEC, and a break waits for 2.0. Experimental and Laboratory carry no such promise.
This page is the promise. What really runs today is measured on the Status page, and every change is in the Changelog.
The sentence
Quantum — declarative web applications in XML, with AI and RAG built into the language. No build chain, no JavaScript, no front-end framework.
If something does not fit that sentence, it does not belong in the README or the pitch. It can keep existing — in another tier, or in another repository.
Who it is for
Solo developers and small teams building internal tools, dashboards, admin panels and AI applications, who do not want a front-end build chain.
The tiers
Core — what the framework is
Documented, tested end to end, stable. A break here is a critical bug. No tag enters without: a rule in SPEC.md with a test that cites it, an example that runs, a guide page, and a line in FEATURE_STATUS.md.
| Tag | Role |
|---|---|
q:component | Unit of composition, with q:param / q:return |
q:set | Variables and scopes (session. / application. / request.) |
q:if | Conditional (q:elseif / q:else) |
q:loop | Iteration (array, list, range, query) |
q:function | Reusable function, with q:param / q:return |
q:query | Parameterised SQL — q:param required, injection impossible by construction; pagination, schema check (quantum check), history (DB-11) |
q:transaction | Queries that commit or roll back together (DB-4) |
q:action | Form handler, with q:redirect and q:flash; rules from q:param checked on the server and shown next to each field |
q:invoke | Call a function, a component or an HTTP service |
q:data | Import and transform CSV/JSON/XML |
q:import / q:slot | Component composition |
q:file | Uploads under paths.uploads, and downloads a page decides who may have (FILE-1, FILE-2) |
q:mail | Mail through the mail: config, with a log mode for development (MAIL-1, MAIL-2) |
ui:* — the Core set | Screens in a page, listed in SPEC UI-7. Drawn with the same meaning by the browser (quantum start), the console (quantum console) and the window (quantum desktop, the page in a local window); one parity script runs in a real browser and in the console |
require_auth / require_role | Authentication and authorisation per component, over the session scope (decision D4); hashPassword / verifyPassword in expressions |
AI — the reason the project exists
The same contract as Core, plus a live test against a real model before every release. It is what Quantum has that no other declarative framework has.
| Tag | Role | Proven by |
|---|---|---|
q:llm | Completion and chat; knowledge= answers from a base and cites its sources; stream="true" sends the answer as it is written | IA-1…IA-8, projects/docs-assistant |
q:knowledge | A vector knowledge base (RAG) over text, files and queries | IA-2, IA-6, IA-8, projects/docs-assistant |
q:agent | An agent whose tools are declared in .q, with a failure contract and a time budget | IA-4, IA-5, projects/shop-agent |
Experimental — exists, without a promise
Kept and working, but outside the README and the pitch, with no API stability guarantee. It moves to Core with the same rigour: a SPEC rule and its test, an example, a guide page and a line in the status.
| Area | Tags |
|---|---|
| Multi-agent | q:team — no SPEC rule and no proving app yet |
| Jobs | q:job, q:schedule, q:thread |
| Messaging | q:message, q:queue, q:subscribe, q:messageAck, q:messageNack, q:websocket, q:websocket-send, q:websocket-close |
| Services | q:log, q:dump |
| Scripting | q:python, q:pyclass, q:pyimport — off by default, turned on with security.python_scripting (see SECURITY.md) |
| Events | q:dispatchEvent |
| Decorators | q:decorator / q:pydecorator — a parser and an AST node with no consumer in the runtime; either decorators get designed for q:function or the tags leave. Not documented until then |
| UI / other targets | ui:* elements outside the Core set (browser only; the console says it does not draw them); the standalone q:application type="ui" build (--target html/textual, layout only, UI-8); the terminal target (qt:), htmx, islands |
Laboratory — stays in the repository, outside the promise
Decision D1/D2 (2026-09-10): these projects stay in the repository because they press on the language — playing is how features and bugs the core needs show up. They are not in the pitch and carry no stability promise, and the runtime warns once when one runs (quantum/core/tiers.py). Their tests run in CI in a job of their own (pytest -m laboratory), required like the main one, so a core change that breaks a game shows up — and a red CI says at once which side broke.
| Area | Note |
|---|---|
2D game engine (qg:), Godot codegen | The games in projects/ and examples/ are built by the codegen; never edit the generated output. Language changes that break a game migrate its .q sources in the same change |
quantum-as4 (MXML/AS4 → JS compiler) | Has an open regression in test_transpiler_comprehensive.py |
quantum run --target mobile (React Native) | Translates q:set/q:function to JavaScript on its own — the opposite of "one runtime". Phones are out of 1.0. Warns once (tiers.warn_ui_target) |
How this does not rot
ROADMAP.md rotted because it was kept by hand and nobody checked it. The defences:
FEATURE_STATUS.mdis generated, by really running the examples (scripts/generate-feature-status.py).manifest.yamlhas no authority over "works or not" — 29 files kept in sync by hand is exactly why they drifted.- The engine enforces the tiers (
quantum/core/tiers.py, tested intests/unit/test_tiers.py); this page and that file change together. - This document only changes by an explicit decision, and the change is small: moving a tag between tiers.
Changes for 1.0
| Change | Why |
|---|---|
| The tier names are English: Core, AI, Experimental, Laboratory (were Core, Diferencial, Experimental, Laboratório) | The repository is in English |
q:file, q:mail and q:transaction → Core | Each has SPEC rules with tests (FILE-1/2, MAIL-1/2, DB-4) and an app in CI that uses it (projects/helpdesk, projects/blog) |
q:team → Experimental | No SPEC rule and no proving app; the AI tier promises only what is proven |
ui:* Core set → Core (0.16) | UI-1…UI-14, the parity script, three renderers |
q:decorator / q:transaction left "no tier" | q:transaction got its rule (DB-4); the decorators are Experimental with the note above |