Software Design Document

Omarchy Lock Dogfood v

This document was auto-generated by ReqProof on 2026-10-03 03:25:41 UTC. Do not edit manually; regenerate from source requirements and design data.

Table of Contents

1. Introduction

1.1 Purpose

This Software Design Document (SDD) describes the architecture and detailed design of Omarchy Lock Dogfood. It provides the technical design decisions, component decomposition, interface contracts, data structures, and traceability needed to satisfy safety-critical software development standards.

External codebase audit

1.2 Scope

Incrementally model externally-owned source code, tests, and documentation before enforcing release gates.

2
Components
87
Requirements
198
Variables
1
Interfaces

1.3 Definitions and Acronyms

TermDefinition
SDDSoftware Design Document
SRSSoftware Requirements Specification
SYS-REQSystem-level requirement
FRETishFormal requirements language based on NASA FRET
LTLLinear Temporal Logic
CoCoSpecContract-based specification language for Lustre model checkers
MermaidDiagram-as-code rendering library

1.4 Standards Compliance

IEC 62304 Clause 5.3/5.4
Software Architectural Design / Software Detailed Design -- this document satisfies the requirement for documented software architecture and per-unit design.
DO-178C Section 11.10
Software Design Description -- this document describes the architecture, data flow, and control flow of the software.
ISO 26262 Part 6, Clause 7-8
Software architectural design specification and unit design -- component decomposition, interfaces, and data structures.
Default Assurance Level
C

1.5 Document Overview

Section 2 presents the software architecture with component diagrams. Section 3 provides detailed per-component design. Section 4 covers data design. Section 5 specifies all interface contracts. Section 6 documents design constraints. Section 7 provides traceability from requirements to components and code.

2. Software Architecture

2.1 Architecture Overview

The system is decomposed into 2 components connected by 1 defined interface boundaries. Each component owns a set of requirements and variables that define its behavior contract.

2.2 Component Diagram

The following diagram shows the component dependency graph derived from interface specifications:

graph LR
  n_menu["menu"]
  n_lock["lock"]

  n_menu -->|subprocess| n_lock

Specification Hierarchy

graph TD
  n_specs_software["specs/software\nL2 #124; subsystem\n70 reqs"]
  n_specs_stakeholder["specs/stakeholder\nL0 #124; stakeholder\n2 reqs"]
  n_specs_system["specs/system\nL1 #124; system\n15 reqs"]

  n_specs_stakeholder --> n_specs_system
  n_specs_system --> n_specs_software

2.3 Component Summary

#ComponentRequirementsVariablesInterfaces
1 lock 21 58 1
2 menu 66 140 1

2.4 Specification Hierarchy

LevelSpec PathTypePrefixRequirements
0 specs/stakeholder stakeholder STK-REQ 2
1 specs/system system SYS-REQ 15
2 specs/software subsystem SW-REQ 70

3. Component Design

This section provides detailed design for each component, including its interfaces, data structures, requirements, and traceability.

3.1 lock

3.1.1 Interfaces

menu → lock subprocess
omarchy-system-lock() -> exit 0
The menu Lock row invokes the lock component's CLI entry point omarchy-system-lock with no arguments. The callee engages the session lock and exits 0. This is the only menu-to-lock interaction; lock never calls menu.
Assumes: Caller provides no arguments; PATH resolves omarchy-system-lock; a Hyprland session with omarchy-shell IPC answers the lock verb.
Guarantees: Callee engages the session lock via omarchy-shell lock lock, resets keyboard layout, locks 1password when running, stops the ttfx screensaver, and exits 0.

3.1.2 Data Structures

VariableTypeDirectionDescription
user_lock_requested bool input The user invoked the session lock entry point.
session_lock_engaged bool output The shell lock plugin engaged the ext-session-lock.
keyboard_layout_default bool output The keyboard layout was reset to the first layout.
screensaver_stopped bool output The ttfx screensaver was signalled and waited out.
suspend_imminent bool input logind signalled PrepareForSleep and the delay inhibitor is held.
lock_requested_first bool output The session lock was requested before clamshell reconciliation.
session_secure bool output The compositor reports the session lock as secure.
unsecured_suspend_reported bool output An unsecured suspend was diagnosed on stderr and notified as critical.
lock_auth_config_run bool input omarchy-apply-lock was invoked to configure lock authentication.
password_pam_installed bool output The PAM password stack for the lock screen is installed.
fingerprint_pam_installed bool output The PAM fingerprint stack is installed.
fingerprint_pam_removed bool output /etc/pam.d/omarchy-lock-fingerprint is removed.
lock_state_queried bool input A caller asked for the compositor session-lock state.
lock_state_reported bool output The lock state is reported as exit 0 locked, 1 unlocked, or 2 undetermined.
stranded_lock_recovered bool output A stranded compositor lock is reclaimed by the shell.
update_run_requested bool input A caller asked omarchy-update-lock to run a command under the update lock.
update_lock_exclusive bool output Only one update holds the update lock at a time.
held_state_reported bool output The held subcommand reports whether the caller holds the update lock.
user_lock_requested bool input The user invoked the session lock entry point.
ttfx_running bool input The ttfx screensaver process is running.
ttfx_signalled bool output SIGTERM was delivered to ttfx.
ttfx_wait_bounded bool output The wait for ttfx exit is bounded at 1 s.
suspend_imminent bool input logind signalled PrepareForSleep and the delay inhibitor is held.
lock_requested_before_clamshell_sync bool output The lock IPC request precedes the clamshell helper call.
budget_bounded bool output The wait budget is derived from logind InhibitDelayMaxUSec, reserves a fifth or at least 1000 ms, and is capped at 12000 ms.
budget_fallback_on_invalid bool output A missing or invalid budget argument falls back to the derived budget.
budget_expired_without_secure bool input The wait budget expired before the session reported secure.
unsecured_reported bool output The unsecured-suspend diagnostic and critical notification were emitted.
exit_failure bool output The script exits with status 1.
running_as_root bool input The helper runs with EUID 0.
trusted_path_only bool output PATH is replaced with trusted system directories before optional commands run.
fingerprint_enrollment_queried bool input The helper tests whether the target user has an enrolled fingerprint.
fprintd_absolute_path_only bool output fprintd-list is invoked only as /usr/bin/fprintd-list.
fingerprint_not_enrolled bool input No enrolled fingerprint exists or /usr/bin/fprintd-list is not executable.
fingerprint_pam_removed bool output /etc/pam.d/omarchy-lock-fingerprint is removed.
lock_state_queried bool input A caller asked for the compositor session-lock state.
exit_zero_on_lock bool output Exit 0 when any monitor lists LOCK in solitaryBlockedBy.
exit_one_on_answerable_unlocked bool output Exit 1 when no monitor shows LOCK and a monitor is not blocked by WORKSPACE.
exit_two_on_undetermined bool output Exit 2 when hyprctl fails or no monitor answer is determined.
stranded_lock_detected bool input The stranded-lock probe found a lock this shell did not take.
stranded_lock_recovered_once bool output The service takes the stranded lock exactly once.
recovery_logged bool output A lock-stranded recovery event is written to the journal log.
password_pam_configured bool input /etc/pam.d/omarchy-lock-password loaded successfully.
lock_requested bool input The lock IPC handler received a lock request.
lock_denied_missing_pam bool output The lock request is answered missing-pam and no session lock engages.
idle_timeout_expired bool input The idle blank timer expired.
blank_displays bool output The displays are blanked behind the lock.
password_auth_in_flight bool input A password authentication is in progress.
timer_rearmed_after_suspend bool output The blank timer is re-armed because wall-clock time shows a suspend gap.
password_text_overflows bool input The entered password dot row is wider than the password field.
dots_scaled_within_field bool output The password dots are scaled so the row stays inside the field.
update_run_requested bool input A caller asked omarchy-update-lock to run a command under the update lock.
lock_unavailable bool input Another process holds the update lock.
run_refused_with_diagnostic bool output The run is refused with a diagnostic and exit 1 when the lock is taken.
held_state_queried bool input A caller asked whether it holds the update lock.
held_true_only_for_owning_fd bool output held exits 0 only for the descriptor that owns the lock.
fingerprint_sensor_configured bool input A fingerprint sensor is enrolled and its PAM stack is installed.
fingerprint_indicator_tracks_sensor bool output The lock view shows the fingerprint indicator exactly when a sensor is configured.

3.1.3 Requirements Traceability

RequirementPriorityCategoryStatus
STK-REQ-260912-XJ5D shall functional review
SW-REQ-260912-0Y70 shall functional review
SW-REQ-260912-41VV shall functional review
SW-REQ-260912-EH0K shall functional review
SW-REQ-260912-EKJP shall functional review
SW-REQ-260912-FAWV shall functional review
SW-REQ-260912-FVHS shall functional review
SW-REQ-260912-GGGS shall functional review
SW-REQ-260912-H2YF shall functional review
SW-REQ-260912-J8SX shall functional review
SW-REQ-260912-MXQG shall functional review
SW-REQ-260912-ND55 shall functional review
SW-REQ-260912-S154 shall functional review
SW-REQ-260912-WBS3 shall functional review
SW-REQ-260912-WJYM shall functional review
SW-REQ-260912-Y0WT shall functional review
SYS-REQ-260912-FRG0 shall functional review
SYS-REQ-260912-H8A5 shall functional review
SYS-REQ-260912-HC86 shall functional review
SYS-REQ-260912-JW2J shall functional review
SYS-REQ-260912-T0XP shall functional review

3.2 menu

3.2.1 Interfaces

menu → lock subprocess
omarchy-system-lock() -> exit 0
The menu Lock row invokes the lock component's CLI entry point omarchy-system-lock with no arguments. The callee engages the session lock and exits 0. This is the only menu-to-lock interaction; lock never calls menu.
Assumes: Caller provides no arguments; PATH resolves omarchy-system-lock; a Hyprland session with omarchy-shell IPC answers the lock verb.
Guarantees: Callee engages the session lock via omarchy-shell lock lock, resets keyboard layout, locks 1password when running, stops the ttfx screensaver, and exits 0.

3.2.2 Data Structures

VariableTypeDirectionDescription
menu_invoked bool input A keybind or CLI invocation asked for the menu.
menu_presented bool output The menu card is visible with rows for the active route.
route_given bool input The caller passed a route string (item id or alias).
routed_to_intended_item bool output The menu opens at the item the route denotes.
menu_sources_loaded bool input The default and user JSONC menu sources were (re)loaded.
item_tree_merged bool output One ordered item tree exists with user overrides applied.
provider_rows_arrive bool input A provider (apps, fonts, power-profiles) delivered a new row batch.
dynamic_rows_swapped bool output The provider's rows replaced its previous batch atomically.
guards_evaluated bool input The guard batch ran for the current item set.
system_state_reflected bool output Row visibility, checkmarks, and dimming match the guard results.
search_entered bool input The user typed a filter query.
matching_rows_ranked bool output Visible matching rows are ranked by match quality.
selection_made bool input The user activated a row or answered a prompt.
action_executed_or_submenu_opened bool output A leaf action ran or the target submenu opened.
picker_active bool input The menu is answering a script's select/input prompt.
picker_answer_returned bool output The picked value was delivered to the calling script.
action_script_invoked bool input A menu action script (share, timezone, picker, images, keybindings, file) was invoked.
intended_side_effect bool output The script performed its documented side effect or refusal.
lock_row_activated bool input The user activated the menu's Lock row.
system_lock_invoked bool output The menu invoked the lock component's omarchy-system-lock entry point.
verb_known bool input The verb is one of toggle, summon, close, refresh, ping, or help.
ipc_call_executed bool output The matching omarchy-shell IPC call was exec'd with the route payload.
verb_unknown bool input The verb matches none of the known verbs.
diagnostic_printed bool output An unknown-verb diagnostic naming the verb is written to stderr.
exit_two bool output The script exits with status 2.
route_input bool input A non-empty route string was supplied.
exact_id_match bool input The normalized route equals an existing item id.
alias_match bool input The normalized route equals an alias of a non-app item.
route_is_exact_id bool output The route resolves to the exact id, ahead of any alias.
route_is_alias_target bool output The route resolves to the id of the item declaring the alias.
route_is_literal_input bool output The route resolves to the literal input string.
resolved_kind_action bool input The resolved item is an action with a non-empty action.
action_runs_directly bool output The action executes without opening the menu.
menu_not_opened bool output No menu card opens for the invocation.
resolved_kind_link bool input The resolved item is a link with a non-empty target.
link_target_followed bool output The menu opens at the link target.
jsonc_has_comments_or_commas bool input The JSONC source carries // comments or trailing commas.
items_parsed bool output The item set parses to the declared entries.
json_invalid bool input The source is not parseable JSON after stripping.
empty_item_set bool output The parse yields an empty item set.
parse_error_raised bool output A parse exception escapes to the caller.
entry_shape_declared bool input An entry carries action, target, or neither.
kind_and_parent_inferred bool output Kind is action/target/menu by shape; parent derives from the dotted id; root's parent is empty.
user_entry_overrides bool input The user source re-declares an id from the default source.
per_key_override_applied bool output Only the re-declared keys change; the row keeps its original order slot.
root_injected bool output A root item exists even when no source declares it.
orphan_id_present bool input itemOrder lists an id with no item behind it.
orphans_dropped bool output Orphan ids and previous app rows are absent from the merged result.
id_listed_once bool output The id appears exactly once in the merged order.
inputs_not_mutated bool output The merge writes no key into the maps it was handed.
provider_reran bool input The provider for a submenu produced a new batch.
previous_batch_replaced bool output Rows from the provider's previous batch are gone; other items are untouched.
guards_declared bool input Items declare when, checked, or disabled expressions.
one_line_per_guard bool output The guard script holds exactly one tagged if-line per declared guard.
no_guards_declared bool input No item declares any guard expression.
empty_guard_script bool output The guard script is empty.
reader_value_reused bool input Several guards read the same value command.
reader_read_once bool output The value command runs once per batch, captured before any guard.
pkg_presence_asked bool input A guard asks omarchy-pkg-present or omarchy-pkg-missing.
shadow_matches_pacman bool output The prelude's answer equals pacman -Q, including provides and the no-argument case.
plain_substitution_form bool input A guard reads a value as plain $(reader).
only_plain_form_substituted bool output Only the plain $(reader) form is substituted; every other form runs the real command.
batch_killed bool input The guard batch exited nonzero or by signal.
last_complete_set_kept bool output The previous complete guard results stay in effect.
pending_reeval_runs bool output An evaluation that stood aside runs after the in-flight batch exits.
query_terms_given bool input The user typed one or more query terms.
all_terms_matched bool output Every term matches the name text or a whole description word.
row_hidden_from_results bool output Invisible and disabled rows are absent from search results.
match_quality_varies bool input Rows match by exact label, prefix, substring, name text, or description.
better_match_ranks_first bool output Exact beats prefix beats substring beats name beats description; apps demote within a tier; ties break by depth then order.
matches_span_menus bool input Matches exist both in the active menu and in deeper submenus.
sections_divided bool output Current-menu rows list before drilldown rows with a divider between.
cursor_moves bool input The user moves the cursor up or down.
disabled_rows_skipped bool output The cursor lands on the next selectable row in the direction of travel, wrapping at the ends.
all_rows_disabled bool input Every row in the list is disabled.
no_cursor_parked bool output No cursor is shown (selectedIndex reset, cursor inactive).
submenu_entered bool input The user drilled into a submenu.
back_retraces_path bool output Back pops the navigation stack, or falls back to the parent menu; the filter clears.
dmenu_option_picked bool input The user picked a dmenu option.
glyph_stripped bool output The leading glyph is shown but never returned.
subtext_returned bool output A subtext-bearing option returns label TAB subtext.
select_invoked bool input omarchy-menu-select was called with a prompt and options.
payload_shape_correct bool output The summon payload carries mode, prompt, options, selectionFile, doneFile, and integer width/maxHeight when given.
no_options_given bool input No options were passed and stdin is not a terminal with zero lines.
usage_error_exit_one bool output A usage diagnostic prints to stderr and the script exits 1.
answer_file_written bool input The menu wrote the selection and done files.
selection_printed bool output The selection content is printed to stdout.
empty_selection bool input The selection file is empty at done time.
exit_one_on_empty bool output The script exits 1 without printing.
finish_requested bool input The QML side finishes an active request with a selection or null.
selection_and_done_written bool output The selection file holds the value and the done file is created.
done_only_written bool output Only the done file is created (cancellation).
no_active_request bool input finishRequest runs with no active request or no done file.
menu_closes_silently bool output The menu closes without touching any file.
picker_verb_given bool input omarchy-menu-plugin was called with enable, disable, clone, or remove.
verb_filter_applied bool output Only plugins matching the verb's rule are offered.
same_named_plugins bool input Two offered plugins share a display name.
pick_resolves_by_id bool output The pick acts on the row's id, not its name.
nothing_actionable bool input No plugin matches the verb's rule.
notification_and_exit_zero bool output A 'No plugin to <verb>' notification is sent and the script exits 0.
share_clipboard bool input omarchy-menu-share runs in clipboard mode.
clipboard_saved_to_temp bool output The clipboard is written to a temp .txt file that outlives the script.
chooser_failed bool input The file chooser exited with status above 1.
critical_notification_exit_one bool output A critical notification is sent and the script exits 1.
send_detached bool output LocalSend runs detached via systemd-run --user.
timezone_pick_cancelled bool input The timezone picker was cancelled.
timezone_not_set bool output timedatectl set-timezone is not invoked.
timezone_picked bool input A timezone was picked.
timezone_set_and_refreshed bool output The timezone is set, the clock plugin refreshes, and a confirmation notification is sent.
dirs_unchanged bool input The image directories' fast signature (path + mtime) matches the cache.
cached_rows_reused bool output Cached rows are used without rescanning image files.
signature_mismatch bool input The fast signature differs from the cache.
rows_rebuilt_and_cached bool output Rows are rebuilt from a full scan and the cache is rewritten.
lua_binds_present bool input Hyprland reports Lua binds as dispatcher __lua.
lua_binds_dispatchable bool output Lua binds appear with resolved keys and can be dispatched.
keycode_binding bool input A binding is reported as an XKB keycode (code:N).
symbol_resolved bool output The key shows as a symbol from the compiled keymap, or the built-in fallback; GRAVE shows as ~.
paths_given bool input omarchy-menu-file was given label, colon-separated paths, and formats.
listing_shape bool output Files match the formats, dotfiles and dot-directories are pruned, and rows sort by mtime descending.
prompt_dismissed bool input The user cancelled the prompt without picking (mirrors the system-layer variable).
guard_results_applied bool input The batched guard results (when/checked/disabled per id) landed in the view state.
rows_hidden_or_marked_per_results bool output Rows hide on when:false, static submenus with no visible descendant hide, provider menus stay, checked/disabled rows earn the check mark, disabled rows dim.
menu_open_called bool input The host called open(payloadJson) after summon.
lifecycle_answered bool output Payload mode dispatched (select/input/route), close cancels, refresh reloads both JSONC sources and answers ok, ping answers ok.
rows_overflow bool input The row list is taller than the height available to it.
fold_signals_more bool output The list height ends mid-row with a peek of the next row, capped at 70 percent of panel height, never exactly on a row boundary.
delete_key_on_app bool input The user pressed Delete with the cursor on an app row.
uninstall_confirmed_flow bool output A confirmation dialog opens; confirm removes the app through the app library, cancel restores focus without removing.
action_is_bare_summon bool input The action string matches the bare-summon grammar 'omarchy-shell shell summon <id> ['<payload>']' (id [A-Za-z0-9._-]+, payload single-quoted, no embedded quote).
in_process_summon_equivalent bool output The action runs in-process via shell.summon(id, payload) with bash-equivalent argv semantics (payload defaults to '{}' exactly as bin/omarchy-shell line 51 does for the 3-arg form); non-matching actions keep the unchanged execDetached bash path.
item_requested bool input A caller asks the item model for an item by id (guard evaluation, navigation fallback, or route/state lookup).
item_by_id_resolved bool output The by-id accessor answers with the id item when present and null otherwise; the answer is never a dangling entry.
menu_interacted bool input The user interacts with the open menu: the first filter keystroke or a submenu move.
card_top_frozen bool output The card top edge and max rows height hold at their interaction-time values; closing the menu clears the freeze.
pointer_moves_over_rows bool input The pointer genuinely moves past the PointerMoveGate threshold over the row list.
gated_row_selection bool output Pointer-driven selection ends in the gate-honored outcome: it lands on the hovered row only when the gate moved and the row is selectable, otherwise selection holds.
thumbnail_missing bool input A scanned media file has no thumbnail at its content-hash cache path.
thumbnail_generated bool output The thumbnail is generated by the format-appropriate converter and lands at the file content-hash cache path.
media_rejected bool input The converter refuses a video: it exits non-zero without a timeout or kill, or a .failed marker already stands for the file content hash.
rejection_marker_recorded bool output The rejection stands recorded and honored: the .failed marker keyed by the video hash exists, the video offers no row, and the rows stay uncached.

3.2.3 Requirements Traceability

RequirementPriorityCategoryStatus
STK-REQ-260922-XTNR shall functional review
SW-REQ-260922-0W96 shall functional review
SW-REQ-260922-2JZT shall functional review
SW-REQ-260922-3JG5 shall functional review
SW-REQ-260922-3T3F shall functional review
SW-REQ-260922-3VTN shall functional review
SW-REQ-260922-4079 shall functional review
SW-REQ-260922-43HQ shall functional review
SW-REQ-260922-46HY shall functional review
SW-REQ-260922-4EWA shall functional review
SW-REQ-260922-4VAV shall functional review
SW-REQ-260922-50RE shall functional review
SW-REQ-260922-74BZ shall functional review
SW-REQ-260922-7NPE shall functional review
SW-REQ-260922-8CQ4 shall functional review
SW-REQ-260922-8ERH shall functional review
SW-REQ-260922-9ABD shall functional review
SW-REQ-260922-9DMS shall functional review
SW-REQ-260922-B757 shall functional review
SW-REQ-260922-B839 shall functional review
SW-REQ-260922-C8HX shall functional review
SW-REQ-260922-CYB9 shall functional review
SW-REQ-260922-DE93 shall functional review
SW-REQ-260922-DQ9P shall functional review
SW-REQ-260922-E4J2 shall functional review
SW-REQ-260922-EFNR shall functional review
SW-REQ-260922-FGZQ shall functional review
SW-REQ-260922-HR29 shall functional review
SW-REQ-260922-JREH shall functional review
SW-REQ-260922-JRW1 shall functional review
SW-REQ-260922-KRBH shall functional review
SW-REQ-260922-MH9B shall functional review
SW-REQ-260922-MP00 shall functional review
SW-REQ-260922-MQ37 shall functional review
SW-REQ-260922-N3RM shall functional review
SW-REQ-260922-NM45 shall functional review
SW-REQ-260922-PRNV shall functional review
SW-REQ-260922-Q6ZS shall functional review
SW-REQ-260922-QMWP shall functional review
SW-REQ-260922-RGCV shall functional review
SW-REQ-260922-SJ7P shall functional review
SW-REQ-260922-SNZG shall functional review
SW-REQ-260922-SWFT shall functional review
SW-REQ-260922-T257 shall functional review
SW-REQ-260922-TKDP shall functional review
SW-REQ-260922-W17G shall functional review
SW-REQ-260922-XW52 shall functional review
SW-REQ-260922-Y58B shall functional review
SW-REQ-260922-Z48F shall functional review
SW-REQ-260922-Z680 shall functional review
SW-REQ-260928-8VJQ shall functional review
SW-REQ-260929-B8N9 shall functional review
SW-REQ-260929-DXFJ shall functional review
SW-REQ-260929-REJT shall functional review
SW-REQ-260929-T378 shall functional review
SW-REQ-260929-THMB shall functional review
SYS-REQ-260922-0M8A shall functional review
SYS-REQ-260922-47T8 shall functional review
SYS-REQ-260922-6642 shall functional review
SYS-REQ-260922-J0AN shall functional review
SYS-REQ-260922-P708 shall functional review
SYS-REQ-260922-PPDW shall functional review
SYS-REQ-260922-R8DQ shall functional review
SYS-REQ-260922-V7W6 shall functional review
SYS-REQ-260922-X6Z5 shall functional review
SYS-REQ-260927-WC89 shall interface review

4. Data Design

4.1 Variable Definitions

The system defines 198 variables across 2 components.

ComponentVariableTypeDirectionDescription
lock user_lock_requested bool input The user invoked the session lock entry point.
lock session_lock_engaged bool output The shell lock plugin engaged the ext-session-lock.
lock keyboard_layout_default bool output The keyboard layout was reset to the first layout.
lock screensaver_stopped bool output The ttfx screensaver was signalled and waited out.
lock suspend_imminent bool input logind signalled PrepareForSleep and the delay inhibitor is held.
lock lock_requested_first bool output The session lock was requested before clamshell reconciliation.
lock session_secure bool output The compositor reports the session lock as secure.
lock unsecured_suspend_reported bool output An unsecured suspend was diagnosed on stderr and notified as critical.
lock lock_auth_config_run bool input omarchy-apply-lock was invoked to configure lock authentication.
lock password_pam_installed bool output The PAM password stack for the lock screen is installed.
lock fingerprint_pam_installed bool output The PAM fingerprint stack is installed.
lock fingerprint_pam_removed bool output /etc/pam.d/omarchy-lock-fingerprint is removed.
lock lock_state_queried bool input A caller asked for the compositor session-lock state.
lock lock_state_reported bool output The lock state is reported as exit 0 locked, 1 unlocked, or 2 undetermined.
lock stranded_lock_recovered bool output A stranded compositor lock is reclaimed by the shell.
lock update_run_requested bool input A caller asked omarchy-update-lock to run a command under the update lock.
lock update_lock_exclusive bool output Only one update holds the update lock at a time.
lock held_state_reported bool output The held subcommand reports whether the caller holds the update lock.
lock user_lock_requested bool input The user invoked the session lock entry point.
lock ttfx_running bool input The ttfx screensaver process is running.
lock ttfx_signalled bool output SIGTERM was delivered to ttfx.
lock ttfx_wait_bounded bool output The wait for ttfx exit is bounded at 1 s.
lock suspend_imminent bool input logind signalled PrepareForSleep and the delay inhibitor is held.
lock lock_requested_before_clamshell_sync bool output The lock IPC request precedes the clamshell helper call.
lock budget_bounded bool output The wait budget is derived from logind InhibitDelayMaxUSec, reserves a fifth or at least 1000 ms, and is capped at 12000 ms.
lock budget_fallback_on_invalid bool output A missing or invalid budget argument falls back to the derived budget.
lock budget_expired_without_secure bool input The wait budget expired before the session reported secure.
lock unsecured_reported bool output The unsecured-suspend diagnostic and critical notification were emitted.
lock exit_failure bool output The script exits with status 1.
lock running_as_root bool input The helper runs with EUID 0.
lock trusted_path_only bool output PATH is replaced with trusted system directories before optional commands run.
lock fingerprint_enrollment_queried bool input The helper tests whether the target user has an enrolled fingerprint.
lock fprintd_absolute_path_only bool output fprintd-list is invoked only as /usr/bin/fprintd-list.
lock fingerprint_not_enrolled bool input No enrolled fingerprint exists or /usr/bin/fprintd-list is not executable.
lock fingerprint_pam_removed bool output /etc/pam.d/omarchy-lock-fingerprint is removed.
lock lock_state_queried bool input A caller asked for the compositor session-lock state.
lock exit_zero_on_lock bool output Exit 0 when any monitor lists LOCK in solitaryBlockedBy.
lock exit_one_on_answerable_unlocked bool output Exit 1 when no monitor shows LOCK and a monitor is not blocked by WORKSPACE.
lock exit_two_on_undetermined bool output Exit 2 when hyprctl fails or no monitor answer is determined.
lock stranded_lock_detected bool input The stranded-lock probe found a lock this shell did not take.
lock stranded_lock_recovered_once bool output The service takes the stranded lock exactly once.
lock recovery_logged bool output A lock-stranded recovery event is written to the journal log.
lock password_pam_configured bool input /etc/pam.d/omarchy-lock-password loaded successfully.
lock lock_requested bool input The lock IPC handler received a lock request.
lock lock_denied_missing_pam bool output The lock request is answered missing-pam and no session lock engages.
lock idle_timeout_expired bool input The idle blank timer expired.
lock blank_displays bool output The displays are blanked behind the lock.
lock password_auth_in_flight bool input A password authentication is in progress.
lock timer_rearmed_after_suspend bool output The blank timer is re-armed because wall-clock time shows a suspend gap.
lock password_text_overflows bool input The entered password dot row is wider than the password field.
lock dots_scaled_within_field bool output The password dots are scaled so the row stays inside the field.
lock update_run_requested bool input A caller asked omarchy-update-lock to run a command under the update lock.
lock lock_unavailable bool input Another process holds the update lock.
lock run_refused_with_diagnostic bool output The run is refused with a diagnostic and exit 1 when the lock is taken.
lock held_state_queried bool input A caller asked whether it holds the update lock.
lock held_true_only_for_owning_fd bool output held exits 0 only for the descriptor that owns the lock.
lock fingerprint_sensor_configured bool input A fingerprint sensor is enrolled and its PAM stack is installed.
lock fingerprint_indicator_tracks_sensor bool output The lock view shows the fingerprint indicator exactly when a sensor is configured.
menu menu_invoked bool input A keybind or CLI invocation asked for the menu.
menu menu_presented bool output The menu card is visible with rows for the active route.
menu route_given bool input The caller passed a route string (item id or alias).
menu routed_to_intended_item bool output The menu opens at the item the route denotes.
menu menu_sources_loaded bool input The default and user JSONC menu sources were (re)loaded.
menu item_tree_merged bool output One ordered item tree exists with user overrides applied.
menu provider_rows_arrive bool input A provider (apps, fonts, power-profiles) delivered a new row batch.
menu dynamic_rows_swapped bool output The provider's rows replaced its previous batch atomically.
menu guards_evaluated bool input The guard batch ran for the current item set.
menu system_state_reflected bool output Row visibility, checkmarks, and dimming match the guard results.
menu search_entered bool input The user typed a filter query.
menu matching_rows_ranked bool output Visible matching rows are ranked by match quality.
menu selection_made bool input The user activated a row or answered a prompt.
menu action_executed_or_submenu_opened bool output A leaf action ran or the target submenu opened.
menu picker_active bool input The menu is answering a script's select/input prompt.
menu picker_answer_returned bool output The picked value was delivered to the calling script.
menu action_script_invoked bool input A menu action script (share, timezone, picker, images, keybindings, file) was invoked.
menu intended_side_effect bool output The script performed its documented side effect or refusal.
menu lock_row_activated bool input The user activated the menu's Lock row.
menu system_lock_invoked bool output The menu invoked the lock component's omarchy-system-lock entry point.
menu verb_known bool input The verb is one of toggle, summon, close, refresh, ping, or help.
menu ipc_call_executed bool output The matching omarchy-shell IPC call was exec'd with the route payload.
menu verb_unknown bool input The verb matches none of the known verbs.
menu diagnostic_printed bool output An unknown-verb diagnostic naming the verb is written to stderr.
menu exit_two bool output The script exits with status 2.
menu route_input bool input A non-empty route string was supplied.
menu exact_id_match bool input The normalized route equals an existing item id.
menu alias_match bool input The normalized route equals an alias of a non-app item.
menu route_is_exact_id bool output The route resolves to the exact id, ahead of any alias.
menu route_is_alias_target bool output The route resolves to the id of the item declaring the alias.
menu route_is_literal_input bool output The route resolves to the literal input string.
menu resolved_kind_action bool input The resolved item is an action with a non-empty action.
menu action_runs_directly bool output The action executes without opening the menu.
menu menu_not_opened bool output No menu card opens for the invocation.
menu resolved_kind_link bool input The resolved item is a link with a non-empty target.
menu link_target_followed bool output The menu opens at the link target.
menu jsonc_has_comments_or_commas bool input The JSONC source carries // comments or trailing commas.
menu items_parsed bool output The item set parses to the declared entries.
menu json_invalid bool input The source is not parseable JSON after stripping.
menu empty_item_set bool output The parse yields an empty item set.
menu parse_error_raised bool output A parse exception escapes to the caller.
menu entry_shape_declared bool input An entry carries action, target, or neither.
menu kind_and_parent_inferred bool output Kind is action/target/menu by shape; parent derives from the dotted id; root's parent is empty.
menu user_entry_overrides bool input The user source re-declares an id from the default source.
menu per_key_override_applied bool output Only the re-declared keys change; the row keeps its original order slot.
menu root_injected bool output A root item exists even when no source declares it.
menu orphan_id_present bool input itemOrder lists an id with no item behind it.
menu orphans_dropped bool output Orphan ids and previous app rows are absent from the merged result.
menu id_listed_once bool output The id appears exactly once in the merged order.
menu inputs_not_mutated bool output The merge writes no key into the maps it was handed.
menu provider_reran bool input The provider for a submenu produced a new batch.
menu previous_batch_replaced bool output Rows from the provider's previous batch are gone; other items are untouched.
menu guards_declared bool input Items declare when, checked, or disabled expressions.
menu one_line_per_guard bool output The guard script holds exactly one tagged if-line per declared guard.
menu no_guards_declared bool input No item declares any guard expression.
menu empty_guard_script bool output The guard script is empty.
menu reader_value_reused bool input Several guards read the same value command.
menu reader_read_once bool output The value command runs once per batch, captured before any guard.
menu pkg_presence_asked bool input A guard asks omarchy-pkg-present or omarchy-pkg-missing.
menu shadow_matches_pacman bool output The prelude's answer equals pacman -Q, including provides and the no-argument case.
menu plain_substitution_form bool input A guard reads a value as plain $(reader).
menu only_plain_form_substituted bool output Only the plain $(reader) form is substituted; every other form runs the real command.
menu batch_killed bool input The guard batch exited nonzero or by signal.
menu last_complete_set_kept bool output The previous complete guard results stay in effect.
menu pending_reeval_runs bool output An evaluation that stood aside runs after the in-flight batch exits.
menu query_terms_given bool input The user typed one or more query terms.
menu all_terms_matched bool output Every term matches the name text or a whole description word.
menu row_hidden_from_results bool output Invisible and disabled rows are absent from search results.
menu match_quality_varies bool input Rows match by exact label, prefix, substring, name text, or description.
menu better_match_ranks_first bool output Exact beats prefix beats substring beats name beats description; apps demote within a tier; ties break by depth then order.
menu matches_span_menus bool input Matches exist both in the active menu and in deeper submenus.
menu sections_divided bool output Current-menu rows list before drilldown rows with a divider between.
menu cursor_moves bool input The user moves the cursor up or down.
menu disabled_rows_skipped bool output The cursor lands on the next selectable row in the direction of travel, wrapping at the ends.
menu all_rows_disabled bool input Every row in the list is disabled.
menu no_cursor_parked bool output No cursor is shown (selectedIndex reset, cursor inactive).
menu submenu_entered bool input The user drilled into a submenu.
menu back_retraces_path bool output Back pops the navigation stack, or falls back to the parent menu; the filter clears.
menu dmenu_option_picked bool input The user picked a dmenu option.
menu glyph_stripped bool output The leading glyph is shown but never returned.
menu subtext_returned bool output A subtext-bearing option returns label TAB subtext.
menu select_invoked bool input omarchy-menu-select was called with a prompt and options.
menu payload_shape_correct bool output The summon payload carries mode, prompt, options, selectionFile, doneFile, and integer width/maxHeight when given.
menu no_options_given bool input No options were passed and stdin is not a terminal with zero lines.
menu usage_error_exit_one bool output A usage diagnostic prints to stderr and the script exits 1.
menu answer_file_written bool input The menu wrote the selection and done files.
menu selection_printed bool output The selection content is printed to stdout.
menu empty_selection bool input The selection file is empty at done time.
menu exit_one_on_empty bool output The script exits 1 without printing.
menu finish_requested bool input The QML side finishes an active request with a selection or null.
menu selection_and_done_written bool output The selection file holds the value and the done file is created.
menu done_only_written bool output Only the done file is created (cancellation).
menu no_active_request bool input finishRequest runs with no active request or no done file.
menu menu_closes_silently bool output The menu closes without touching any file.
menu picker_verb_given bool input omarchy-menu-plugin was called with enable, disable, clone, or remove.
menu verb_filter_applied bool output Only plugins matching the verb's rule are offered.
menu same_named_plugins bool input Two offered plugins share a display name.
menu pick_resolves_by_id bool output The pick acts on the row's id, not its name.
menu nothing_actionable bool input No plugin matches the verb's rule.
menu notification_and_exit_zero bool output A 'No plugin to <verb>' notification is sent and the script exits 0.
menu share_clipboard bool input omarchy-menu-share runs in clipboard mode.
menu clipboard_saved_to_temp bool output The clipboard is written to a temp .txt file that outlives the script.
menu chooser_failed bool input The file chooser exited with status above 1.
menu critical_notification_exit_one bool output A critical notification is sent and the script exits 1.
menu send_detached bool output LocalSend runs detached via systemd-run --user.
menu timezone_pick_cancelled bool input The timezone picker was cancelled.
menu timezone_not_set bool output timedatectl set-timezone is not invoked.
menu timezone_picked bool input A timezone was picked.
menu timezone_set_and_refreshed bool output The timezone is set, the clock plugin refreshes, and a confirmation notification is sent.
menu dirs_unchanged bool input The image directories' fast signature (path + mtime) matches the cache.
menu cached_rows_reused bool output Cached rows are used without rescanning image files.
menu signature_mismatch bool input The fast signature differs from the cache.
menu rows_rebuilt_and_cached bool output Rows are rebuilt from a full scan and the cache is rewritten.
menu lua_binds_present bool input Hyprland reports Lua binds as dispatcher __lua.
menu lua_binds_dispatchable bool output Lua binds appear with resolved keys and can be dispatched.
menu keycode_binding bool input A binding is reported as an XKB keycode (code:N).
menu symbol_resolved bool output The key shows as a symbol from the compiled keymap, or the built-in fallback; GRAVE shows as ~.
menu paths_given bool input omarchy-menu-file was given label, colon-separated paths, and formats.
menu listing_shape bool output Files match the formats, dotfiles and dot-directories are pruned, and rows sort by mtime descending.
menu prompt_dismissed bool input The user cancelled the prompt without picking (mirrors the system-layer variable).
menu guard_results_applied bool input The batched guard results (when/checked/disabled per id) landed in the view state.
menu rows_hidden_or_marked_per_results bool output Rows hide on when:false, static submenus with no visible descendant hide, provider menus stay, checked/disabled rows earn the check mark, disabled rows dim.
menu menu_open_called bool input The host called open(payloadJson) after summon.
menu lifecycle_answered bool output Payload mode dispatched (select/input/route), close cancels, refresh reloads both JSONC sources and answers ok, ping answers ok.
menu rows_overflow bool input The row list is taller than the height available to it.
menu fold_signals_more bool output The list height ends mid-row with a peek of the next row, capped at 70 percent of panel height, never exactly on a row boundary.
menu delete_key_on_app bool input The user pressed Delete with the cursor on an app row.
menu uninstall_confirmed_flow bool output A confirmation dialog opens; confirm removes the app through the app library, cancel restores focus without removing.
menu action_is_bare_summon bool input The action string matches the bare-summon grammar 'omarchy-shell shell summon <id> ['<payload>']' (id [A-Za-z0-9._-]+, payload single-quoted, no embedded quote).
menu in_process_summon_equivalent bool output The action runs in-process via shell.summon(id, payload) with bash-equivalent argv semantics (payload defaults to '{}' exactly as bin/omarchy-shell line 51 does for the 3-arg form); non-matching actions keep the unchanged execDetached bash path.
menu item_requested bool input A caller asks the item model for an item by id (guard evaluation, navigation fallback, or route/state lookup).
menu item_by_id_resolved bool output The by-id accessor answers with the id item when present and null otherwise; the answer is never a dangling entry.
menu menu_interacted bool input The user interacts with the open menu: the first filter keystroke or a submenu move.
menu card_top_frozen bool output The card top edge and max rows height hold at their interaction-time values; closing the menu clears the freeze.
menu pointer_moves_over_rows bool input The pointer genuinely moves past the PointerMoveGate threshold over the row list.
menu gated_row_selection bool output Pointer-driven selection ends in the gate-honored outcome: it lands on the hovered row only when the gate moved and the row is selectable, otherwise selection holds.
menu thumbnail_missing bool input A scanned media file has no thumbnail at its content-hash cache path.
menu thumbnail_generated bool output The thumbnail is generated by the format-appropriate converter and lands at the file content-hash cache path.
menu media_rejected bool input The converter refuses a video: it exits non-zero without a timeout or kill, or a .failed marker already stands for the file content hash.
menu rejection_marker_recorded bool output The rejection stands recorded and honored: the .failed marker keyed by the video hash exists, the video offers no row, and the rows stay uncached.

4.2 Data Properties

Variables with special merge, deduplication, or comparison properties:

ComponentVariableProperties

4.3 Data Flow

Data flows between components via the interface boundaries defined in Section 5. Input variables are consumed from upstream callers; output variables are produced for downstream callees. The direction field in the variable definitions indicates whether a variable is an input (consumed), output (produced), or mode (operating state).

5. Interface Design

5.1 Interface Specification Table

The system defines 1 interface boundaries.

#CallerCalleeTypeSignatureDescriptionAssumptionsGuarantees
1 menu lock subprocess omarchy-system-lock() -> exit 0 The menu Lock row invokes the lock component's CLI entry point omarchy-system-lock with no arguments... Caller provides no arguments; PATH resolves omarchy-system-lock; a Hyprland session with omarchy-she... Callee engages the session lock via omarchy-shell lock lock, resets keyboard layout, locks 1password...

5.2 Protocol Details

1. menu → lock subprocess
omarchy-system-lock() -> exit 0

The menu Lock row invokes the lock component's CLI entry point omarchy-system-lock with no arguments. The callee engages the session lock and exits 0. This is the only menu-to-lock interaction; lock never calls menu.

Preconditions (Assumptions): Caller provides no arguments; PATH resolves omarchy-system-lock; a Hyprland session with omarchy-shell IPC answers the lock verb.

Postconditions (Guarantees): Callee engages the session lock via omarchy-shell lock lock, resets keyboard layout, locks 1password when running, stops the ttfx screensaver, and exits 0.

5.3 Error Handling Contracts

Each interface boundary follows a contract-based error handling pattern:

6. Design Constraints

Constraint CategoryDescription
Assurance LevelDefault assurance level: C. Components may override with higher levels as needed.
LanguageCore implementation in Go. Web UI in SvelteKit/TypeScript. Formal verification via external Kind2/JKind solvers.
PlatformCross-platform (Linux, macOS, Windows). External solver dependencies are optional.
SecurityInput validation on all external boundaries (HTTP, JSON-RPC, subprocess). HTML output uses auto-escaping to prevent XSS.
PerformanceDocument generation must complete in under 10 seconds for projects with up to 1000 requirements.

7. Traceability

7.1 Requirement-to-Component Mapping

Each requirement is assigned to exactly one component. The following table shows the distribution of requirements across components.

ComponentRequirement IDsTotal ReqsRequirement TypesCategories
lock STK-REQ-260912-XJ5D SW-REQ-260912-0Y70 SW-REQ-260912-41VV SW-REQ-260912-EH0K SW-REQ-260912-EKJP SW-REQ-260912-FAWV SW-REQ-260912-FVHS SW-REQ-260912-GGGS SW-REQ-260912-H2YF SW-REQ-260912-J8SX SW-REQ-260912-MXQG SW-REQ-260912-ND55 SW-REQ-260912-S154 SW-REQ-260912-WBS3 SW-REQ-260912-WJYM SW-REQ-260912-Y0WT SYS-REQ-260912-FRG0 SYS-REQ-260912-H8A5 SYS-REQ-260912-HC86 SYS-REQ-260912-JW2J SYS-REQ-260912-T0XP 21 21 guarantee, 0 assumption, 0 constraint, 0 derived Functional Requirements (21)
menu STK-REQ-260922-XTNR SW-REQ-260922-0W96 SW-REQ-260922-2JZT SW-REQ-260922-3JG5 SW-REQ-260922-3T3F SW-REQ-260922-3VTN SW-REQ-260922-4079 SW-REQ-260922-43HQ SW-REQ-260922-46HY SW-REQ-260922-4EWA SW-REQ-260922-4VAV SW-REQ-260922-50RE SW-REQ-260922-74BZ SW-REQ-260922-7NPE SW-REQ-260922-8CQ4 SW-REQ-260922-8ERH SW-REQ-260922-9ABD SW-REQ-260922-9DMS SW-REQ-260922-B757 SW-REQ-260922-B839 SW-REQ-260922-C8HX SW-REQ-260922-CYB9 SW-REQ-260922-DE93 SW-REQ-260922-DQ9P SW-REQ-260922-E4J2 SW-REQ-260922-EFNR SW-REQ-260922-FGZQ SW-REQ-260922-HR29 SW-REQ-260922-JREH SW-REQ-260922-JRW1 SW-REQ-260922-KRBH SW-REQ-260922-MH9B SW-REQ-260922-MP00 SW-REQ-260922-MQ37 SW-REQ-260922-N3RM SW-REQ-260922-NM45 SW-REQ-260922-PRNV SW-REQ-260922-Q6ZS SW-REQ-260922-QMWP SW-REQ-260922-RGCV SW-REQ-260922-SJ7P SW-REQ-260922-SNZG SW-REQ-260922-SWFT SW-REQ-260922-T257 SW-REQ-260922-TKDP SW-REQ-260922-W17G SW-REQ-260922-XW52 SW-REQ-260922-Y58B SW-REQ-260922-Z48F SW-REQ-260922-Z680 SW-REQ-260928-8VJQ SW-REQ-260929-B8N9 SW-REQ-260929-DXFJ SW-REQ-260929-REJT SW-REQ-260929-T378 SW-REQ-260929-THMB SYS-REQ-260922-0M8A SYS-REQ-260922-47T8 SYS-REQ-260922-6642 SYS-REQ-260922-J0AN SYS-REQ-260922-P708 SYS-REQ-260922-PPDW SYS-REQ-260922-R8DQ SYS-REQ-260922-V7W6 SYS-REQ-260922-X6Z5 SYS-REQ-260927-WC89 66 66 guarantee, 0 assumption, 0 constraint, 0 derived Functional Requirements (65) Interface Requirements (1)

7.2 Component-to-Code Mapping

Code files implementing each component, derived from implemented_by trace links.

ComponentImplementation Files
lock No code links
menu No code links