can't be bothered writing a commit message

graphify-out/2026-08-16/GRAPH_REPORT.md

@@ -0,0 +1,397 @@
+# Graph Report - bread  (2026-08-15)
+
+## Corpus Check
+- 62 files · ~88,250 words
+- Verdict: corpus is large enough that graph structure adds value.
+
+## Summary
+- 1467 nodes · 3347 edges · 88 communities (64 shown, 24 thin omitted)
+- Extraction: 99% EXTRACTED · 1% INFERRED · 0% AMBIGUOUS · INFERRED: 48 edges (avg confidence: 0.78)
+- Token cost: 0 input · 0 output
+
+## Graph Freshness
+- Built from commit: `a6973360`
+- Run `git rev-parse HEAD` and compare to check if the graph is stale.
+- Run `graphify update .` after code changes (no API cost).
+
+## Community Hubs (Navigation)
+- lua/mod.rs
+- RawEvent
+- config.rs
+- Server
+- widget.rs
+- Bread Daemon (breadd)
+- filesystem.rs
+- git.rs
+- Result
+- state_engine.rs
+- modules_mgmt.rs
+- systemd.rs
+- hooks_git.rs
+- bread-cli/src/main.rs
+- types.rs
+- podman.rs
+- StateHandle
+- run_udev_monitor
+- hooks_shell.rs
+- bluetooth.rs
+- SubscriptionId
+- glob.rs
+- run_state_engine
+- RtnetlinkAdapter
+- network.rs
+- power.rs
+- hyprland.rs
+- Adapter
+- dl.breadway.dev Distribution
+- git-branch-widget.lua
+- TestHarness
+- Sync
+- active-window-widget.lua
+- cpu-temp-widget.lua
+- focus-mode-widget.lua
+- workflow-status-widget.lua
+- bread.widget API
+- bluetooth-toggle-widget.lua
+- pause-media-on-headphone-unplug.lua
+- Autostart Example Module
+- install.sh
+- Filesystem Adapter
+- Git Adapter
+- Podman Adapter
+- Systemd Adapter
+- bread.after(delay_ms, fn)
+- bread.bluetooth namespace
+- bread.every(interval_ms, fn)
+- bread.exec(cmd)
+- bread.hyprland namespace
+- bread.notify(message, opts)
+- bread.state.watch(path, fn)
+- bread.system.startup
+- Monitors Configuration Example
+- Binds Module (Built-in)
+- Bakery Package Manager
+- Phase 3: GUI Control Center
+- Phase 5: Cross-Device Mesh
+- Dev Version Computation
+- ModuleHostLua
+- ModuleHostRegistry
+- xtask/src/main.rs
+- Bread
+- rules.rs
+- Normalized events
+- Bread Documentation
+- udev.rs
+- Dictionary: Lua API
+- Out-of-process module sandboxing *(Since: v1.6)*
+- Dictionary: Built-in modules
+- Events
+- Machine and filesystem
+- Contributing
+- Bluetooth
+- Widgets *(Since: v1.3)*
+- Getting started
+- Capability-scoped modules *(Since: v1.5)*
+- Workflows *(Since: v1.2)*
+- Timers
+- State
+- init.lua
+- Execution
+- packaging/README.md
+
+## God Nodes (most connected - your core abstractions)
+1. `LuaEngine` - 59 edges
+2. `RawEvent` - 49 edges
+3. `BreadEvent` - 38 edges
+4. `raw()` - 37 edges
+5. `RuntimeState` - 34 edges
+6. `StateHandle` - 28 edges
+7. `now_unix_ms()` - 26 edges
+8. `Adapter` - 25 edges
+9. `SubscriptionId` - 25 edges
+10. `ModuleHostLua` - 24 edges
+
+## Surprising Connections (you probably didn't know these)
+- `parse_bluetooth_message()` --calls--> `now_unix_ms()`  [INFERRED]
+  breadd/src/adapters/bluetooth.rs → bread-shared/src/lib.rs
+- `try_enumerate()` --calls--> `now_unix_ms()`  [INFERRED]
+  breadd/src/adapters/bluetooth.rs → bread-shared/src/lib.rs
+- `classify()` --calls--> `now_unix_ms()`  [INFERRED]
+  breadd/src/adapters/filesystem.rs → bread-shared/src/lib.rs
+- `network_raw_event()` --calls--> `now_unix_ms()`  [INFERRED]
+  breadd/src/adapters/network.rs → bread-shared/src/lib.rs
+- `power_raw_event()` --calls--> `now_unix_ms()`  [INFERRED]
+  breadd/src/adapters/power.rs → bread-shared/src/lib.rs
+
+## Import Cycles
+- 2-file cycle: `breadd/src/core/state_engine.rs -> breadd/src/lua/mod.rs -> breadd/src/core/state_engine.rs`
+- 2-file cycle: `bread-shared/src/lib.rs -> bread-shared/src/module_host_ipc.rs -> bread-shared/src/lib.rs`
+
+## Hyperedges (group relationships)
+- **** — ci_dev_release, workflow_version_compute, release_track_dev, distribution_dl_breadway_dev, package_bakery [INFERRED]
+- **** — adapter_udev, adapter_hyprland, adapter_power, sys_bread_daemon, api_bread_on, sys_lua_runtime [INFERRED]
+- **** — config_init_lua, config_modules_dir, pattern_module_skeleton, api_bread_on, sys_lua_runtime [INFERRED]
+- **** — api_bread_workflow, api_bread_spawn, api_bread_wait, example_dock_workflow, api_bread_notify [INFERRED]
+- **** — api_bread_widget, api_bread_every, example_widget_cpu_temp, api_bread_state_watch [INFERRED]
+- **** — branch_main, ci_dev_release, ci_rc_release, ci_stable_release, release_track_dev, release_track_beta, release_track_stable [INFERRED]
+
+## Communities (88 total, 24 thin omitted)
+
+### Community 0 - "lua/mod.rs"
+Cohesion: 0.06
+Nodes (86): now_unix_ms(), ModulePermission, Option, String, WidgetSpec, RuntimeState, bluetooth_connect(), bluetooth_disconnect() (+78 more)
+
+### Community 1 - "RawEvent"
+Cohesion: 0.05
+Nodes (67): adapter_source_is_hashable_and_eq(), AdapterSource, bread_event_new_accepts_owned_and_borrowed_names(), bread_event_new_assigns_unique_id_and_no_cause(), bread_event_new_sets_current_timestamp(), bread_event_with_timestamp_preserves_timestamp_and_assigns_id(), BreadEvent, DaemonSection (+59 more)
+
+### Community 2 - "config.rs"
+Cohesion: 0.07
+Nodes (50): AdaptersConfig, AdapterToggle, compat_section_defaults_legacy_hyprland_names_to_true(), CompatConfig, Config, config_path(), config_path_falls_back_to_home_when_no_xdg(), config_path_respects_xdg_config_home() (+42 more)
+
+### Community 3 - "Server"
+Cohesion: 0.05
+Nodes (41): A, command_target(), event_domain(), is_known_app(), is_reserved_domain(), Option, validate_app_namespace(), validate_command_event() (+33 more)
+
+### Community 4 - "widget.rs"
+Cohesion: 0.07
+Nodes (32): accepts_node_count_at_max(), accepts_tree_at_max_depth(), Align, Background, box_of(), default_orientation(), FontWeight, is_valid_class() (+24 more)
+
+### Community 5 - "Bread Daemon (breadd)"
+Cohesion: 0.06
+Nodes (39): Bluetooth Adapter, Hyprland Adapter, Network Adapter, Power Adapter, udev Adapter, bread.on(pattern, fn), bread.spawn(fn), bread.wait(pattern, opts) (+31 more)
+
+### Community 6 - "filesystem.rs"
+Cohesion: 0.12
+Nodes (28): classify(), classify_build_artifact_created_in_target(), classify_debounces_rapid_repeat_events_for_same_path(), classify_file_changed_for_ordinary_source_file(), classify_silent_for_modify_in_target_not_create(), classify_silent_under_git(), classify_silent_under_node_modules(), detect_markers() (+20 more)
+
+### Community 7 - "git.rs"
+Cohesion: 0.12
+Nodes (22): check_ahead_behind(), check_dirty(), discover_repos(), expand_roots(), expand_roots_globs_single_trailing_star(), expand_roots_skips_unreadable_glob_parent_without_panicking(), expand_roots_uses_literal_path_without_trailing_star(), GitAdapter (+14 more)
+
+### Community 8 - "Result"
+Cohesion: 0.15
+Nodes (50): daemon_survives_repeated_reloads_and_pipeline_resumes(), emit_with_app_source_allows_command_to_another_app(), emit_with_app_source_rejects_wrong_namespace(), emit_with_app_source_still_rejects_foreign_app_namespace(), emit_with_internal_source_is_rejected(), emit_with_known_app_source_routes_through_normalizer(), emit_with_unregistered_app_source_is_rejected(), emit_without_event_errors() (+42 more)
+
+### Community 9 - "state_engine.rs"
+Cohesion: 0.12
+Nodes (19): apply_device_change(), apply_event_to_state(), device_connect_adds_device_with_all_fields(), device_connect_is_idempotent_for_same_id(), device_disconnect_of_unknown_id_is_noop(), device_disconnect_removes_matching_id(), ev(), monitor_connect_adds_new_monitor() (+11 more)
+
+### Community 10 - "modules_mgmt.rs"
+Cohesion: 0.11
+Nodes (36): audit_detects_fs_read_and_widget_from_cpu_temp_widget_style_module(), audit_extracts_exec_bin_hint_and_ignores_baseline_calls(), audit_module(), audit_scans_required_sibling_files_in_module_directory(), classify_call_site(), collect_lua_files(), copy_dir(), extract_first_string_arg() (+28 more)
+
+### Community 11 - "systemd.rs"
+Cohesion: 0.12
+Nodes (17): active_state_to_kind(), failure_result(), get_unit_path(), handle_message(), is_failed_transition(), query_active_state(), Connection, HashMap (+9 more)
+
+### Community 12 - "hooks_git.rs"
+Cohesion: 0.15
+Nodes (24): all_hook_scripts_exit_0_unconditionally(), all_hook_scripts_start_with_shebang_and_marker(), branch_changed_emit_line(), commit_created_emit_line(), emit_line_for(), git_dir(), hook_script(), hook_script_rejects_unknown_name() (+16 more)
+
+### Community 13 - "bread-cli/src/main.rs"
+Cohesion: 0.19
+Nodes (29): CausalityTracker, Cli, Commands, config_directory(), daemon_socket_path(), format_timestamp(), handle_modules_cmd(), HooksCommand (+21 more)
+
+### Community 14 - "types.rs"
+Cohesion: 0.17
+Nodes (21): Device, DeviceRule, DeviceTopology, InterfaceState, MatchCondition, ModuleStatus, Monitor, NetworkState (+13 more)
+
+### Community 15 - "podman.rs"
+Cohesion: 0.15
+Nodes (17): container_event(), ignores_remove_event(), ignores_stop_event_to_avoid_double_emit_with_died(), ignores_unknown_action(), map_podman_event(), maps_died_event(), maps_health_status_event(), maps_start_event() (+9 more)
+
+### Community 16 - "StateHandle"
+Cohesion: 0.14
+Nodes (10): condition_matches(), resolve_device(), Option, Result, String, Value, Vec, StateHandle (+2 more)
+
+### Community 17 - "run_udev_monitor"
+Cohesion: 0.35
+Nodes (9): enumerate_with_udev(), Result, Self, Sender, String, Vec, run_udev_monitor(), ScannedDevice (+1 more)
+
+### Community 18 - "hooks_shell.rs"
+Cohesion: 0.18
+Nodes (11): hook_scripts_background_every_emit_call(), hooks_dir(), install_shell(), join_line_continuations(), Option, PathBuf, Result, String (+3 more)
+
+### Community 19 - "bluetooth.rs"
+Cohesion: 0.15
+Nodes (10): address_from_path(), BluetoothAdapter, parse_bluetooth_message(), Message, Option, Result, Self, Sender (+2 more)
+
+### Community 20 - "SubscriptionId"
+Cohesion: 0.29
+Nodes (13): HashMap, String, Vec, Subscription, SubscriptionId, SubscriptionTable, table_add_assigns_provided_id_and_finds_match(), table_clear_removes_all() (+5 more)
+
+### Community 22 - "run_state_engine"
+Cohesion: 0.27
+Nodes (12): dispatch_event(), handle_command(), Arc, AtomicU64, Receiver, RwLock, Self, Sender (+4 more)
+
+### Community 23 - "RtnetlinkAdapter"
+Cohesion: 0.22
+Nodes (7): ip_from_bytes(), Option, Result, Self, Sender, String, RtnetlinkAdapter
+
+### Community 24 - "network.rs"
+Cohesion: 0.27
+Nodes (9): has_default_route(), network_raw_event(), NetworkAdapter, NetworkSnapshot, read_network_state(), BTreeMap, Result, Sender (+1 more)
+
+### Community 25 - "power.rs"
+Cohesion: 0.26
+Nodes (8): power_raw_event(), PowerAdapter, PowerSnapshot, read_power_state(), Option, Result, Self, Sender
+
+### Community 26 - "hyprland.rs"
+Cohesion: 0.29
+Nodes (7): hyprland_event_socket(), HyprlandAdapter, parse_hyprland_line(), PathBuf, Result, Sender, String
+
+### Community 27 - "Adapter"
+Cohesion: 0.23
+Nodes (8): Adapter, parse_upower_message(), Message, Result, Self, Sender, UPowerAdapter, Send
+
+### Community 28 - "dl.breadway.dev Distribution"
+Cohesion: 0.25
+Nodes (8): main Branch, dev-release.yml Workflow, rc-release.yml Workflow, release.yml Workflow, dl.breadway.dev Distribution, beta Release Track, dev Release Track, stable Release Track
+
+### Community 29 - "git-branch-widget.lua"
+Cohesion: 0.62
+Nodes (6): focused_tab_cwd(), git_info(), M.on_load(), shell_quote(), update(), widget_root()
+
+### Community 30 - "TestHarness"
+Cohesion: 0.16
+Nodes (16): main(), parse_args(), Option, String, killing_a_module_host_child_does_not_take_down_breadd_or_other_modules(), os_execute_and_io_open_are_denied_at_the_kernel_level_outside_granted_scope(), Child, Drop (+8 more)
+
+### Community 31 - "Sync"
+Cohesion: 0.50
+Nodes (3): main(), Result, Sync
+
+### Community 32 - "active-window-widget.lua"
+Cohesion: 0.83
+Nodes (3): label_for(), M.on_load(), widget_root()
+
+### Community 33 - "cpu-temp-widget.lua"
+Cohesion: 0.83
+Nodes (3): M.on_load(), read_temp_c(), widget_root()
+
+### Community 34 - "focus-mode-widget.lua"
+Cohesion: 1.00
+Nodes (3): is_focused(), M.on_load(), widget_root()
+
+### Community 35 - "workflow-status-widget.lua"
+Cohesion: 0.83
+Nodes (3): M.on_load(), most_relevant(), widget_update()
+
+### Community 36 - "bread.widget API"
+Cohesion: 0.67
+Nodes (3): bread.widget API, CPU Temperature Widget Example, Live Widget Update Pattern
+
+### Community 64 - "ModuleHostLua"
+Cohesion: 0.10
+Nodes (38): call(), HostMessage, IoCommand, RpcResponse, Duration, Option, PathBuf, Receiver (+30 more)
+
+### Community 65 - "ModuleHostRegistry"
+Cohesion: 0.07
+Nodes (43): bin_allowed(), path_allowed(), HashMap, Option, OwnedWriteHalf, Result, Sender, String (+35 more)
+
+### Community 66 - "xtask/src/main.rs"
+Cohesion: 0.11
+Nodes (36): BTreeSet, ExitCode, check(), CheckReport, clean_state_passes(), extract_cli_commands(), extract_enum_variants(), extract_ipc_methods() (+28 more)
+
+### Community 67 - "Bread"
+Cohesion: 0.06
+Nodes (28): Deprecations, Hyprland legacy flat event names (since v1.5), Bread Examples, Example 1: Porting keyboard_and_display_watcher.sh (system script), Example 2: Porting autostart.lua, Example 3: Porting display/monitors.lua, Example 4: Multi-step automation workflows, Example 5: A live widget in breadbar (+20 more)
+
+### Community 68 - "rules.rs"
+Cohesion: 0.14
+Nodes (27): empty_file_loads_with_no_rules(), empty_on_is_treated_as_missing(), invalid_toml_is_fatal(), load_rules(), missing_on_is_reported_with_index_and_no_on(), multiple_action_keys_is_reported(), one_bad_rule_does_not_block_other_valid_rules(), ParsedRule (+19 more)
+
+### Community 69 - "Normalized events"
+Cohesion: 0.12
+Nodes (16): Bluetooth (BlueZ), Compatibility: `[compat]` config, Devices (udev / Bluetooth), Filesystem / project detection, Git (hooks + dirty-state poller), Hyprland, Network, Normalized events (+8 more)
+
+### Community 70 - "Bread Documentation"
+Cohesion: 0.14
+Nodes (14): API Stability & Versioning, Bread Documentation, Contents, Debugging tips, Dictionary: Event reference, Dictionary: IPC protocol, Dictionary: Runtime state schema, Integrating a bread\* app (+6 more)
+
+### Community 71 - "udev.rs"
+Cohesion: 0.32
+Nodes (10): build_device_event(), build_event(), enumerate_payload_includes_classification_fields(), prop_bool(), prop_str(), Option, Value, udev_event_payload() (+2 more)
+
+### Community 72 - "Dictionary: Lua API"
+Cohesion: 0.17
+Nodes (12): `bread.debounce(delay_ms, fn) -> wrapped_fn`, `bread.log(msg)` / `bread.warn(msg)` / `bread.error(msg)`, `bread.notify(message, opts)`, `bread.profile.activate(name)`, Dictionary: Lua API, Hyprland, Module declaration, Module lifecycle hooks (+4 more)
+
+### Community 73 - "Out-of-process module sandboxing *(Since: v1.6)*"
+Cohesion: 0.20
+Nodes (10): Architecture, Crash isolation, New IPC methods, Out-of-process module sandboxing *(Since: v1.6)*, RPC bridge coverage, The gap this closes, The Landlock sandbox, The token/identity handshake (+2 more)
+
+### Community 74 - "Dictionary: Built-in modules"
+Cohesion: 0.20
+Nodes (10): `bread.binds`, `bread.devices`, `bread.monitors`, `bread.rules` *(Since: v1.5)*, `bread.workspaces`, Device rule options, Dictionary: Built-in modules, Example: Dock-specific setup (+2 more)
+
+### Community 75 - "Events"
+Cohesion: 0.20
+Nodes (10): `bread.emit(event, data)`, `bread.filter(pattern, fn, opts) -> id`, `bread.off(id)`, `bread.on(pattern, fn) -> id`, `bread.once(pattern, fn) -> id`, `bread.spawn(fn)`, `bread.wait_all(patterns, opts) -> table` *(Since: v1.2)*, `bread.wait_any(patterns, opts) -> event | nil` *(Since: v1.2)* (+2 more)
+
+### Community 76 - "Machine and filesystem"
+Cohesion: 0.20
+Nodes (10): `bread.fs.exists(path) -> bool`, `bread.fs.expand(path) -> string`, `bread.fs.read(path) -> string | nil`, `bread.fs.readlink(path) -> string | nil`, `bread.fs.write(path, content)`, `bread.json.decode(str) -> table | nil`, `bread.machine.has_tag(tag) -> bool`, `bread.machine.name() -> string` (+2 more)
+
+### Community 77 - "Contributing"
+Cohesion: 0.22
+Nodes (8): Branches, CI, Contributing, Keeping the API docs honest, Local development, Questions, The release cycle, Tracks, from a user's perspective
+
+### Community 78 - "Bluetooth"
+Cohesion: 0.22
+Nodes (9): Bluetooth, `bread.bluetooth.connect(address)`, `bread.bluetooth.devices() -> table | nil`, `bread.bluetooth.disconnect(address)`, `bread.bluetooth.power(enabled)`, `bread.bluetooth.powered() -> bool | nil`, `bread.bluetooth.scan(enabled)`, Example: auto-connect headphones on AC power (+1 more)
+
+### Community 79 - "Widgets *(Since: v1.3)*"
+Cohesion: 0.22
+Nodes (9): `bread.widget.list() -> table`, `bread.widget.register(spec) -> ok, err`, `bread.widget.remove(id) -> bool`, `bread.widget.update(id, patch) -> ok, err`, Click events, Node types, `style` *(Since: v1.4)*, Style vs. `class` (+1 more)
+
+### Community 80 - "Getting started"
+Cohesion: 0.33
+Nodes (6): 1) Create a minimal config, 2) The fast path: `rules.toml` *(Since: v1.5)*, 3) Minimal `init.lua`, 4) Start the daemon, 5) Check that it's running, Getting started
+
+### Community 81 - "Capability-scoped modules *(Since: v1.5)*"
+Cohesion: 0.33
+Nodes (6): Baseline (always available, no manifest entry needed), `bread modules audit <name>`, Capability-scoped modules *(Since: v1.5)*, Gated — requires a matching `[[permissions]]` entry, `path`/`bin` enforcement depends on where the module runs, `require("bread.devices")` still works from a scoped module
+
+### Community 82 - "Workflows *(Since: v1.2)*"
+Cohesion: 0.33
+Nodes (6): `bread.workflow.define(name, fn)`, `bread.workflow.list() -> table`, `bread.workflow.start(name, opts)`, `bread.workflow.status(name) -> table | nil`, `bread.workflow.step(label)`, Workflows *(Since: v1.2)*
+
+### Community 83 - "Timers"
+Cohesion: 0.50
+Nodes (4): `bread.after(delay_ms, fn) -> id`, `bread.cancel(id)`, `bread.every(interval_ms, fn) -> id`, Timers
+
+### Community 84 - "State"
+Cohesion: 0.50
+Nodes (4): `bread.state.get(path)`, `bread.state.watch(path, fn) -> id`, State, Typed shorthands
+
+### Community 85 - "init.lua"
+Cohesion: 0.83
+Nodes (3): M.on_load(), read_temp_c(), widget_root()
+
+### Community 86 - "Execution"
+Cohesion: 0.67
+Nodes (3): `bread.exec_capture(cmd, opts) -> ok, stdout`, `bread.exec(cmd)`, Execution
+
+## Knowledge Gaps
+- **179 isolated node(s):** `install.sh script`, `Branches`, `The release cycle`, `Tracks, from a user's perspective`, `Keeping the API docs honest` (+174 more)
+  These have ≤1 connection - possible missing edges or undocumented components.
+- **24 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
+
+## Suggested Questions
+_Questions this graph is uniquely positioned to answer:_
+
+- **Why does `RawEvent` connect `RawEvent` to `Server`, `filesystem.rs`, `git.rs`, `udev.rs`, `systemd.rs`, `podman.rs`, `run_udev_monitor`, `bluetooth.rs`, `RtnetlinkAdapter`, `network.rs`, `power.rs`, `hyprland.rs`, `Adapter`?**
+  _High betweenness centrality (0.094) - this node is a cross-community bridge._
+- **Why does `Adapter` connect `Adapter` to `Server`, `filesystem.rs`, `git.rs`, `udev.rs`, `systemd.rs`, `podman.rs`, `run_udev_monitor`, `bluetooth.rs`, `RtnetlinkAdapter`, `network.rs`, `power.rs`, `hyprland.rs`, `Sync`?**
+  _High betweenness centrality (0.077) - this node is a cross-community bridge._
+- **Why does `BreadEvent` connect `RawEvent` to `ModuleHostLua`, `lua/mod.rs`, `ModuleHostRegistry`, `Server`, `state_engine.rs`, `run_state_engine`?**
+  _High betweenness centrality (0.063) - this node is a cross-community bridge._
+- **What connects `install.sh script`, `Branches`, `The release cycle` to the rest of the system?**
+  _179 weakly-connected nodes found - possible documentation gaps or missing edges._
+- **Should `lua/mod.rs` be split into smaller, more focused modules?**
+  _Cohesion score 0.056 - nodes in this community are weakly interconnected._
+- **Should `RawEvent` be split into smaller, more focused modules?**
+  _Cohesion score 0.051842708517016396 - nodes in this community are weakly interconnected._
+- **Should `config.rs` be split into smaller, more focused modules?**
+  _Cohesion score 0.07191780821917808 - nodes in this community are weakly interconnected._