AvengeMedia / AvengeMedia/DankMaterialShell
Feature: Agency-preserving action receipts for system-changing shell actions
- Dominant language
- QML
- Stars
- 8.1k
- Forks
- 515
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 102
Description
### Feature Description
Add an action receipt and verification lifecycle for DMS actions that change system state. The main goal is to distinguish "the command or IPC request completed" from "the requested state was observed and verified."
For important shell/system actions, DMS would create a reusable action receipt with states such as:
`proposed -> executed -> observed -> verified | uncertain | failed`
Each receipt could record:
- action ID
- action type and parameters
- command or IPC execution result
- post-action state observation
- verification status
- observation time and source
- optional retry/revert affordance
- reason verification was not possible, when applicable
This does not need to wrap every small UI interaction at once. A first version could progressively add the lifecycle only to important system-changing actions where DMS currently has enough information to verify the result.
### Use Case
Some system operations can report command success while reality has not changed. For example, a helper command may exit with status 0 even though a kernel/sysfs setting, compositor state, hardware state, or daemon state did not actually become what the user requested.
In those cases, showing unconditional success gives the user a false model of the desktop state. DMS should preserve the user's ability to notice, contest, retry, revise, or revert when the observed state does not match the requested state.
Acceptance criterion: if a test or mocked action creates the case "command exits 0, but post-action observation shows the requested state did not change", DMS must not present it as unconditional success. It should show `uncertain` or `failed`, with enough context for the user to act.
### Compositor(s)
All compositors
### Proposed Solution
Introduce a small action receipt model used by selected system-changing operations:
- `proposed`: DMS has a requested action and expected post-state.
- `executed`: DMS has sent the command/IPC request and recorded its result.
- `observed`: DMS has re-read the relevant reality source after execution.
- `verified`: observed state matches the requested state.
- `uncertain`: DMS cannot prove whether the requested state took effect.
- `failed`: observed state conflicts with the requested state, or execution failed.
The receipt should keep history even when the current judgment changes. For example, an earlier "verified" judgment can later become stale if reality changes, but the old record should remain available as history rather than continuing to authorize current UI state.
This can start with a narrow set of actions that already have clear read-back paths, then become a shared helper for future actions.
### Alternatives/Existing Solutions
Today, many shell actions rely on the command/IPC result and immediate UI assumptions. That is useful, but it cannot reliably represent systems where the action transport accepted the request while the target state did not change.
An alternative is to add one-off verification to individual features. That helps locally, but a shared receipt lifecycle would make success/uncertainty/failure semantics more consistent across DMS.
Contributor guide
Research direction
No files, tests, or concrete action entry points are identified in the issue. Start by locating existing system-changing actions and their read-back paths, then define a narrow first action whose command-success/state-mismatch case can be tested and displayed as uncertain or failed.
Written by the indexing model from the issue text.
Assessment
- Domain
- desktop, operating-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100