storm/cthulhu
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Wine/Proton stage contract and phase ledger

Browse Source 
Settled decisions, scope and done checklist in wine-proton.md; execution ledger with batch amendments, the satisfied Phase 0 gate and the accepted Phase 1 handoff in wine-proton-phases.md.
This commit is contained in:
hjozwiak committed 2026-11-01 23:28:24 -05:00
1 parent 71093286c7
commit a60a251472
2 files changed
+661
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/testing/wine-proton.md
+249
View File
@@ -0,0 +1,249 @@
# Steam/Proton and controller-only verification
Status: Draft. Settled decisions from the 2026-11-01 grilling session are
recorded here as they land; unresolved questions stay visibly marked.
Per decision 15, contract acceptance settles the decisions but keeps
this document Draft; it becomes Final only when the done checklist
passes and the per-application results are written in.
Execution is split into separately reviewed phases: Phase 0, the
already-committed native-exclusion foundation; Phase 1, ready
record, spawn evidence, and mixed-prefix semantics; Phase 2, live
Wine settings; Phase 3, the Wine preferences tab; and Phase 4, live
verification and final results. Branch assignments, activation
rules, fresh-session startup text, and handoff reporting live in
[wine-proton-phases.md](wine-proton-phases.md). That ledger is
operational only; this contract remains normative if they differ.
## Established facts (verified live, 2026-11-01)
- Cthulhu sends one `--exclude-hook-program <name>` argument per entry in
the profile's `wine.excluded-hook-programs` setting, plus
`--no-dialog-reader` when a listed program (or the global
`wine.controller-only` setting) makes the prefix controller-only.
- The wine-access helper enforces exclusions itself: a listed program's
thread never receives the native menu/input hooks, and its windows get
no dialog reading, from the helper's first foreground poll. Controller
speech and review remain available.
- Diablo IV under Proton Hotfix (Steam app 2344520), with
`excluded-hook-programs = ['Diablo IV.exe']`: the running helper showed
`--exclude-hook-program diablo iv.exe --no-dialog-reader`, staged under
`~/.local/state/cthulhu/wine-access/helper/<content hash>/` for the
pressure-vessel session, and the game stayed up past the roughly
100-second window in which full-mode sessions had crashed on
2026-10-31.
- Two failure modes were proven the same evening: a missing TOML section
silently means full mode, and a stale helper that owns the Wine
session singleton defeats any newly launched helper regardless of
settings.
## Settled decisions
1. Scope of the next stage (2026-11-01): the manager trio (diagnostics
classification, spawn decision logging, live settings reload), a Wine
section in preferences, and this document. Nothing outside that set
is approved by this decision. (Widened once, by decision 5, to
include the ready-record field in the wine-access helper.)
2. Spawn logging mirrors Orca's text format: the helper-start record
carries `programs=[...] extra=[...]` with sorted program names and
the exact extra helper arguments, so both readers' logs read
identically and can be compared line for line.
3. Wine settings take effect as soon as preferences are finished (Apply),
with no reader restart. The manager reads the same live settings the
rest of the reader uses, at each poll and helper spawn, instead of
the one-time snapshot it takes at startup today.
4. A running helper keeps its current mode until its game exits. The
only mid-session change is the existing safety upgrade: if an edit
newly protects a running game, its helper restarts into the
protected mode. Removing a program or clearing the global switch
never downgrades a running helper. Rationale: helper restarts tear
down and recreate the NVDA controller endpoint, and some programs
(Mistworld is the known example) crash when that endpoint is pulled
out from under them. Restarts therefore happen only when protection
is being added, never as a side effect of unrelated edits. (For
the listed-program path, this restart is superseded by decision
16; the no-downgrade rule stands.)
5. The helper's ready record gains a `hook_exclusions` count beside
`controls_enabled` and friends, and Cthulhu parses and logs it as a
field of the initialized record. The plain startup line stays (it is
emitted even when a helper exits early, for example against the
singleton), and Cthulhu recognizes it as info; the
invalid-exclusion line stays a warning. Older helpers without the
field report zero, which is accurate for them. This extends the
stage into the wine-access helper by explicit choice.
6. Preferences gain a Wine tab modeled on the Pronunciation page: a
"Controller-only mode for all Wine applications" checkbox and an
editable program list (tree view with New and Delete), with text
explaining that listed programs keep controller speech but lose
standard control reading. Entries are validated by the existing
settings rules at Apply.
7. Done includes physical Braille acceptance. The display is usable
again (paired over Bluetooth, so the missing charger no longer
blocks it), and the stage is not done until Wine output is checked
on the physical display alongside the speech checks.
8. The stage lands in reviewable steps, evidence first: diagnostics
and spawn logging, then live settings exercised through the TOML,
then the Wine preferences tab, then this document and the live
acceptance pass. The reader stays usable at every step, and no
intermediate step counts the stage as done.
9. The Wine tab validates entries as they are edited: a path, a blank,
or an overlong name is flagged by name in the tab and blocks Apply
until fixed or deleted. Case-insensitive duplicates collapse to a
single entry. Config validation remains the backstop; invalid
entries are never silently dropped, since a user who believes a
game is protected when nothing was saved for it is tonight's
failure repeated.
10. The Braille bar is a full Wine regression on the physical display:
review cursor, window titles, menus, and edits across several
applications, not a spot check of focus output alone. This widens
decision 7's "done" by explicit choice.
11. Every failure that regression finds blocks done, whenever the
defect was born. There is no baseline carve-out for pre-existing
failures: the stage ends with the full Wine Braille regression
passing clean, at whatever size that makes the stage.
12. No escape hatch. If a blocking Braille failure needs a redesign,
or its root cause sits in shared infrastructure rather than
Wine-specific code, it is still built inside this stage. The
stage's true size is accepted as unknown until the regression
passes clean.
13. Program names enter the Wine tab by typing only, as under Orca.
There is no running-program picker and no file browser in this
stage; a well-formed but wrong name remains possible, with the
mirrored spawn log as the after-the-fact evidence.
14. The live regression corpus is fixed by name: Diablo IV (excluded,
anti-tamper), Mistworld (controller-endpoint sensitivity), Wine
Notepad (menus and plain edits), Notepad++ (Scintilla edits), and
the Battle.net bootstrapper (UIA path). Results are recorded per
application in this document. If an application becomes unusable
for reasons unrelated to the reader, its replacement is decided
and recorded here, never silently dropped.
15. This document stays Draft through implementation and acceptance
testing. Contract acceptance settles the decisions above; the
document becomes Final only when the done checklist passes and
the per-application results are written in.
16. Exclusion is per program, enforced by the helper natively. A
listed program's presence in a prefix no longer flips the whole
helper to `--no-dialog-reader`: other programs in the same prefix
keep full hook and dialog reading while the listed one gets the
controller only. For avoidance of doubt, `--no-dialog-reader`
itself remains helper-wide for the whole prefix; a listed name
by itself must never cause Cthulhu to pass it. The global
controller-only switch still runs the whole helper with
`--no-dialog-reader`, and that wholesale mode is also the
fallback when a helper's ready record does not confirm it applied
the exclusions it was sent (for example an old helper that
ignores the flags). This supersedes the
upgrade-on-listed-appearance restart in decision 4 for the listed
path, and both readers change together; the wine-access side of
this stage therefore includes the Orca manager's spawn semantics,
not only the ready-record field.
17. A list addition reaches a running helper at the moment it
matters: if the newly listed program is discovered in a prefix
whose running helper lacks its flag, that helper restarts once in
the same mode, now carrying the flag. Additions for programs that
are not running wait for the next natural spawn. Restarts thus
happen only to add presently-needed protection, never for
prospective edits or housekeeping.
18. Both managers consume the helper's ready record at startup. If
its `hook_exclusions` count does not match the flags sent, that
helper restarts once in wholesale `--no-dialog-reader` mode, and
the manager remembers that binary as unconfirmed so later spawns
go wholesale directly. Go wires its existing diagnostics parser
into the manager; Orca reads the spawn's stderr through a bounded
forwarding path instead of only filing it. No new D-Bus protocol
surface is added for this.
19. The Wine exclusion list is global-only. The manager always reads
the active/global profile's Wine values and ignores
per-application profile switching for Wine. The Wine tab appears
only in global preferences. One list therefore governs every
prefix regardless of which application currently has focus.
20. Cthulhu and Orca keep independent Wine exclusion lists. There is
no one-time import and no live shared canonical list in this
stage. Each reader's list is maintained in its own settings
system. The maintainer plans to transition to Cthulhu full-time
relatively soon, so Cthulhu is the primary path going forward.
21. Orca is frozen as-is for this stage. The maintainer does not
intend to use Orca anymore after today, and Cthulhu is the sole
normative reader for the remaining Wine work. This supersedes
the parts of decisions 5, 16, and 18 that required both readers
to move together: no Orca manager per-program spawn semantics,
bounded Orca stderr reader, Orca test gate, or Orca relaunch
acceptance is required here. Existing Orca support stays as it
is; anyone who wants to carry it forward can do so later. The
wine-access helper ready-record field remains in scope because
Cthulhu consumes it.
22. Decision 21 is a stage-and-maintainer scope decision, not a
project-wide deprecation of Orca. This maintainer is not the
repository's sole maintainer, and the decision records only that
he will not use or carry the Orca path in this stage. It does not
preclude other maintainers from using, maintaining, or improving
Orca support.
23. No wine-access maintenance-status notice will be added for this
stage. The work is overwhelmingly Cthulhu-based; apart from any
root-cause Braille fix the regression may prove necessary, the
only planned wine-access code change is the helper ready-record
field that Cthulhu consumes. Decisions 21 and 22 do not change
Orca's project status, functionality, or availability to other
maintainers, so there is no work-relevant maintenance-status
change for wine-access documentation to announce.
24. Mixed-prefix operation remains mandatory. It is not merely a
Diablo hypothetical: the maintainer has real mixed-prefix uses,
and ordinary programs in a prefix must retain hooks and dialog
reading while a listed program in that same prefix receives only
controller support. The current silence from Wine Notepad while
Diablo IV is alive is therefore a defect against decision 16,
caused by Cthulhu adding the prefix-wide `--no-dialog-reader`
once the listed program is discovered. Removing that listed-
presence trigger is required; wholesale mode remains available
only for the global switch/environment override and the
unconfirmed-helper fallback in decision 18.
25. The scope contract below is accepted for now as the settled
stage boundary. On 2026-11-01, in this Muse Code session, the
maintainer said: "For now, I am satisfied." Per decision 15,
that acceptance does not finalize this document or authorize
implementation; it remains Draft until the done checklist passes
and the per-application results are written in.
## Unresolved questions
(none)
## Scope contract (accepted; document remains Draft)
Boundary. In Cthulhu: `internal/wine`, the Wine settings wiring in
`internal/app` and `internal/config`, a Wine page in
`internal/preferences` including `preferences.ui`, and this document.
In wine-access: the ready-record field in the helper only. For
this stage and this maintainer's work, the Orca integration is
frozen as-is under decisions 21 and 22; that is not a project-wide
Orca deprecation. No Orca manager changes, Orca test gate, or Orca
relaunch acceptance belongs to this stage. Fixes for blocking
Braille regression failures (decisions 11 and 12) may land wherever
their root cause lies, including shared Braille infrastructure. Out
of scope: staged-helper hardening parity for the Orca manager,
stale-helper retirement redesign, the `explorer.exe` classification
divergence, Nix helper candidates on the Go side, and landing either
repo's branches anywhere (commits and merges stay the maintainer's
separate acts).
Done means, all of:
- Cthulhu test suites pass for the touched packages, and the
wine-access helper CTest suite passes. Orca tests are not a gate.
- Diablo IV under Cthulhu: controller speech confirmed by ear, game
survives a normal session, and the start log shows the mirrored
`programs=[...] extra=[...]` record plus the exclusion count.
- An ordinary Wine application still reads standard controls in the
same setup, including inside an excluded game's own prefix while
the game is present and unaffected.
- Full Wine Braille regression on the physical display: review
cursor, window titles, menus, and edits across several
applications, passing clean with no unresolved failures regardless
of when a defect was introduced.
- Preferences round trip by keyboard: Tab and Shift+Tab through the
Wine tab, edit the list, Apply, and confirm a newly started helper
picks the change up with no reader restart.
Nothing outside this checklist is a completion dependency. Accepting
this contract does not authorize implementation; that takes a separate
explicit request.