AvengeMedia / AvengeMedia/DankMaterialShell

Feature: Agency-preserving action receipts for system-changing shell actions

Open
#3,373 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.