Repository navigation
docs: front-load Qt early killer gates #429
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # ADR 0022: Bounded pre-G2 Qt qualification harness | ||
|
|
||
| **Status:** Accepted — clarifying amendment to [ADR-0021](0021-qt-gpui-native-desktop-strategy.md) | ||
| **Date:** 2026-08-20 | ||
| **Clarifies:** ADR-0021, Decision point 7 and the G2/Wave 5 boundary | ||
|
|
||
| ## Context | ||
|
|
||
| ADR-0021 correctly prohibits production Qt or GPUI UI before the applicable admission gates. Its | ||
| wording did not explicitly distinguish a disposable feasibility probe from production UI, while | ||
| the adopted roadmap now requires early Wave 4.5 evidence before G2. That ambiguity could either | ||
| block a necessary early risk check or let a pre-G2 spike grow into an unadmitted product shell. | ||
|
|
||
| ## Decision | ||
|
|
||
| A bounded, non-product Qt learning/qualification harness under Wave 4.5 is explicitly permitted | ||
| before G2 and is not “production UI code”. It exists only to falsify lifecycle, provisional bridge, | ||
| accessibility/input, packaging/update trust, crash/recovery, and security-boundary assumptions at | ||
| the smallest useful cost. Its non-goals and evidence limits are defined in | ||
| [`docs/native/QT-EARLY-KILLER-GATES.md`](../native/QT-EARLY-KILLER-GATES.md). | ||
|
|
||
| The harness must remain disposable and isolated: | ||
|
|
||
| - no editor, plot board, AI panel, design-system port, or product shell; | ||
| - no Qt WebEngine or embedded browser shortcut; | ||
| - no generic command executor, broad FFI, or renderer-owned product truth; | ||
| - a provisional bridge candidate may be used for the probe, while G2 retains the final bridge | ||
| scorecard confirmation informed by the Wave 4.5 evidence; | ||
| - no production packaging promise, Tauri retirement, or G2/G3/G4 checklist shortcut follows from | ||
| a passing probe. | ||
|
|
||
| This is an additive clarification, not a reversal or replacement of ADR-0021. The existing | ||
| prohibition on production Qt/GPUI UI before admission remains unchanged, and all later production | ||
| gates remain mandatory. | ||
|
|
||
| ## Consequences | ||
|
|
||
| - Agents have an explicit authorization boundary for early Qt feasibility work. | ||
| - Contract and lifecycle probes may start as soon as the Rust Core exposes a typed probe call, | ||
| parallel to storage and R-15 work; packaging, recovery, and security qualification still wait | ||
| for the relevant Core semantics. | ||
| - Wave 4.5 can falsify fatal assumptions before feature-port sunk cost without becoming a hidden | ||
| Qt implementation wave. | ||
| - Wave 5 turns accepted probes into a reusable learning harness and adds its remaining capability | ||
| checks; it does not duplicate the Wave 4.5 admission decision. | ||
| - G2 remains the formal Qt implementation-admission gate, including final license, version, bridge, | ||
| learning-harness, IME, accessibility, and packaged roundtrip decisions. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| # Qt Early Killer-Gate Qualification | ||
|
|
||
| **Status: PLANNED — sequencing approved in the Qt/GPUI roadmap; no Qt production UI is admitted.** | ||
|
|
||
| This document defines the cheap, evidence-producing feasibility checks that must happen before | ||
| substantial Qt feature porting. It applies the lesson from the retired CEF path: a native direction | ||
| must be able to falsify its most dangerous assumptions before the project has accumulated UI | ||
| sunk cost. | ||
|
|
||
| The qualification is an additive prerequisite between Wave 4 (R-15 implementation) and Wave 5 | ||
| (the Qt executable learning harness). It does not replace the later G2, G3, or G4 production gates. | ||
| Those gates remain necessary because a small feasibility spike cannot prove production completeness. | ||
| The pre-G2 authorization boundary is recorded as the clarifying amendment | ||
| [`ADR-0022`](../adr/0022-qt-pre-g2-qualification-harness.md); it does not supersede ADR-0021. | ||
|
|
||
| ## Decision rule | ||
|
|
||
| The Qt direction advances only when each gate has a reproducible evidence record, a named owner, | ||
| and a result at the appropriate maturity level: | ||
|
|
||
| ```text | ||
| planned → locally proven → CI-proven → packaged-proven → admitted | ||
| ``` | ||
|
|
||
| Documentation alone is not a pass. A gate that is not applicable must include a written rationale | ||
| and an architecture decision; it must not be silently skipped. A failed kill gate stops Qt work at | ||
| the smallest possible investment and returns the program to architecture review. | ||
|
|
||
| ## Qualification order | ||
|
|
||
| The order is deliberately front-loaded by cost and irreversibility. The formal Wave 4.5 exit is | ||
| recorded after Wave 4, but its dependency-aware lanes start earlier: | ||
|
|
||
| 1. **Contract and threat-boundary review** — static and design evidence after the typed Core probe | ||
| exists; may run in parallel with Waves 3 and 4. | ||
| 2. **Provisional bridge selection** — choose one candidate implementation for the disposable probe, | ||
| record rejected alternatives, and state that G2 retains the final scorecard decision. | ||
| 3. **Executable lifecycle/bridge spike** — prove that a minimal Qt process can safely host the | ||
| renderer-neutral Core boundary. | ||
| 4. **Accessibility and input feasibility** — falsify the most important writing-workflow risks | ||
| before custom controls are built. | ||
| 5. **Packaging, updater, and rollback trust** — test the distribution trust model with throwaway | ||
| artifacts before product packaging work grows around it. | ||
| 6. **Crash diagnostics and recovery feasibility** — prove useful failure evidence without weakening | ||
| the sandbox or recovery invariants. | ||
| 7. **Security and permission posture** — validate IPC/FFI, filesystem, network, and updater | ||
| boundaries under the intended runtime conditions. | ||
| 8. **Admission review** — use the evidence to confirm or reject the bridge scorecard, record | ||
| residual risks, and only then begin larger | ||
| Qt shell or feature work. | ||
|
|
||
| Gates 1–2 may begin once Wave 2 has a typed Core probe call and do not depend on R-15. Gate 3 may | ||
| follow the lifecycle probe. Gates 4–6 wait for the relevant Wave 4 storage/crypto/recovery and | ||
| security semantics; Gate 8 waits for every lane. The admission decision remains conjunctive: one | ||
| unresolved kill gate blocks Qt implementation. | ||
|
|
||
| ## Gate matrix | ||
|
|
||
| | Gate | Minimum proof | Kill condition | | ||
| |---|---|---| | ||
| | Contract/threat boundary | Qt-facing contract inventory identifies every IPC/FFI crossing, data owner, permission, cancellation path, and failure mode; no domain truth moves into QML/C++. | The bridge requires renderer-specific domain rules, arbitrary command execution, or a new broad unsafe/FFI architecture. | | ||
| | Lifecycle and Core bridge | A disposable Qt 6/QML probe proves the minimum viability path: process/window creation, QML load, one typed Rust call, one Rust event to QML, one bounded async/cancellation path, clean shutdown, and three repeated launch/close cycles. It records the bridge/lifetime/threading model; it does not build the reusable Wave 5 harness. | Lifetime/threading behavior is nondeterministic, cancellation cannot be bounded, or the Core cannot remain GUI-independent. | | ||
| | Accessibility and input | A real Qt Quick control sample exposes a stable accessibility tree and proves keyboard/focus, accessible errors, high contrast, scalable text, RTL/BiDi, and IME smoke behavior on a supported Linux environment. | Required semantics are not observable, custom controls require inaccessible workarounds, or IME/BiDi breaks core writing input. | | ||
| | Packaging and updater trust | A packaged hello-world/Core roundtrip starts from a clean environment; signed update metadata, artifact identity, downgrade policy, rollback, and tamper rejection are exercised with test credentials. | Artifact identity or rollback cannot be trusted, updates accept tampered input, or the packaging model requires bypassing repository signing policy. | | ||
|
coderabbitai[bot] marked this conversation as resolved.
Outdated
|
||
| | Crash and recovery | An intentional harness crash produces actionable diagnostics and symbols for project-owned code; restart/recovery behavior is deterministic and does not corrupt test data. | Diagnostics require weakening sandbox/process isolation, recovery loses acknowledged data, or failures cannot be reproduced from packaged evidence. | | ||
| | Security and permissions | Runtime review covers process boundaries, filesystem/network allowlists, secret handling, updater privileges, temporary files, and least-privilege IPC; negative tests prove denied operations stay denied. | A capability needs arbitrary native execution, broad filesystem/network access, plaintext secret exposure, or weakened encryption/identity binding. | | ||
| | Admission decision | A signed/ reviewed scorecard records evidence links, residual risks, owners, expiry/retest conditions, and explicit GO/NO-GO for Wave 5. | Any Critical/High security issue, unowned residual risk, or missing evidence remains at the decision meeting. | | ||
|
|
||
| ## Minimum evidence package | ||
|
|
||
| The qualification work should produce a small, reviewable package rather than a premature product | ||
| framework: | ||
|
|
||
| - `qt-early-killer-gates.md` scorecard with commit/run links and maturity labels; | ||
| - disposable Qt feasibility probes, with no WorldScript feature UI and no Qt WebEngine; | ||
| - deterministic probe results covering repeated start/close, cancellation, and clean shutdown; | ||
| - an accessibility/input fixture with machine-observable tree and keyboard/IME assertions; | ||
| - a clean-environment packaged artifact and a test-key update/rollback fixture; | ||
| - a crash fixture with a project-owned symbolized frame and recovery-state assertion; | ||
| - a permission-negative-test record covering denied filesystem, network, and native-command paths; | ||
|
coderabbitai[bot] marked this conversation as resolved.
Outdated
|
||
| - an architecture decision record for residual risks before Wave 5 admission. | ||
|
|
||
| The harness may use a narrow C++/Rust bridge where Qt requires it, but authoritative product | ||
| semantics remain in the renderer-neutral Rust Core. It must not become a second product shell, | ||
| generic command bridge, or hidden Qt-specific domain layer. | ||
|
|
||
| ## Required execution environments | ||
|
|
||
| The early qualification should use the cheapest environment that can falsify each risk and then | ||
| repeat the meaningful checks in CI: | ||
|
|
||
| 1. **Developer smoke:** fast lifecycle, keyboard, IME, and accessibility-tree checks on the | ||
| supported Linux desktop used for development. | ||
| 2. **Linux CI:** clean build, repeated lifecycle, headless display/compositor smoke, security | ||
| negative tests, crash artifact collection, and deterministic result assertions. | ||
| 3. **Clean packaged runtime:** install/launch/update/rollback/tamper tests against the actual | ||
| artifact layout rather than the build tree. | ||
| 4. **Later platform evidence:** Windows UI Automation, macOS VoiceOver/accessibility APIs, and | ||
| supported compositor/GPU matrices remain part of G2/G3/G4; the early Linux spike does not claim | ||
| cross-platform parity. | ||
|
|
||
| ## Explicit non-goals | ||
|
|
||
| - no editor, plot board, AI panel, or broad design-system port; | ||
| - no Qt WebEngine or embedded Chromium shortcut; | ||
| - no GPUI implementation or Qt/GPUI parity race; | ||
| - no Tauri retirement before Qt Stable plus the documented field window; | ||
| - no R-15 shortcut, renderer-local encryption, or altered identity binding; | ||
| - no broad FFI, unsafe runtime, or generic native command executor; | ||
| - no production packaging promise based only on an unpackaged developer binary. | ||
|
|
||
| ## Relationship to later gates | ||
|
|
||
| Wave 4.5 answers **“is Qt still technically and operationally plausible?”** cheaply and supplies | ||
| the evidence needed to confirm or reject the provisional bridge candidate. Wave 5 | ||
| turns the accepted disposable probes into the reusable executable learning harness and adds the | ||
| remaining file-dialog and clipboard evidence; it does not repeat Wave 4.5's kill-gate work. G2 answers | ||
| **“is Qt admitted for implementation?”** with the approved license/version/bridge strategy and | ||
| the learning harness. G3 and G4 still require project compatibility, accessibility, security, | ||
| packaging, updater, recovery, performance, signing, support, and field evidence at production | ||
| quality. Passing this qualification must never be used to check those later boxes early. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.