Module attention

Expand description

What reaches you, and when: one model for everything Sioul shows, tells, holds or silences (docs/attention.md). Sioul spends one thing four ways, your attention: what it shows (the Porch, the pages), what it tells (its own notifications), what it holds of the system’s (other apps’ notifications, calls), and what it silences (the system’s do-not-disturb).

One matrix: a row per who on each channel (mail, calls, messages from other apps: Always through, safe, neutral, restricted, strangers, hidden numbers for calls, groups for messages, the blocked fixed at never), and a row per kind of Sioul’s own and of the automated sources (codes, doses, reminders, sites, other apps’ automatons…). Nine columns: the seven times (work, admin, leisure, meals, sleep, the pause, Free time) and two layers on top of them (time for you, do-not-disturb from its switch or a focus session). A cell holds a level, from the least strict to the strictest: ● at once, ◑ shown, not told, ◐ when its event falls then, ◎ at the gathered times, ○ later, – not at all; and on the Always through row alone, = as their own row says, ☆ through this layer at their own row’s times. Two times open together (work and admin) give the less strict of their cells; a layer that holds gives the stricter of it and the time.

The pipeline (Attention::decide): what an event is; the emergency numbers (calls); who wrote, proven or not; the blocked, never, whatever else says (blocked beats Always through); the content (a code, a lane never told); the floors (a second call, Let every call through); the exceptions (Always through, a conversation, a site); the matrix; what the source is for (its area); the named holds (the Porch resting after a pause, a meeting, the chat limit). Each caller asks it, and stays where it is.

Kept in the configuration: [attention], one key per row in the words [notify] used: a bare column is ●, column:level another level (“now”, “quiet”, “event”, “gathered”, “later”, “never”, “as”, “through”); a row not written keeps its usual cells, a fixed cell keeps its value. While no [attention] is written, the older [reach], [notify] and the switches they replaced seed it, once: what you changed there is kept, the rest is the usual; the first row written writes them all and takes the older keys out (apply).

Time for you everywhere: today’s slots are written to state/slots.toml by the window that lays out the day (Slots); every process reads them (the window, the listener of other apps, a phone’s background step, sioul remind --watch, the calls’ table).

Structs§

Attention: The matrix: a level in each cell, as set; and the sources’ own rows, an app’s or a conversation’s on a phone, by id (app.<package>, conversation.<key>), each with its name when written with one.
Event: What happened, as its caller knows it (docs/attention.md, §2, step 1).
Grid: The matrix in words, as Settings draws it: the columns (a layer flagged), the levels with their marks (the legend), the rows, the presets, and the moment now in a sentence when one is given.
GridCell: A cell: its column, its value, those it may take; why it is fixed, when it is; its value differs from the preset’s; and the cell in a sentence.
GridRow: A row as Settings draws it: its words, its group’s, a sentence on it, the values its cells may take in its own words, its cells, and whether it differs from the preset it is compared with.
Holds: What holds now, beside the time and its layers: the named holds kept outside the matrix (docs/attention.md, §1.7), as the caller knows them.
Mark: A value, its mark, and its words.
Named: An id and its words.
NotifySettings: [notify] as an older Sioul wrote it (what each kind of notification did at each time, before [attention]): each row’s words, read once to seed the matrix (seeded), never written again.
Now: The moment as the matrix reads it.
Output: What comes of an event now.
Phone: What this phone does itself.
PresetView: A preset, and how far the matrix is from it.
Settings: [attention] as written: each row’s words, read leniently (a row that is no list of words is left aside, never the whole configuration).
Silence: What one of Sioul’s modes lets through (Android’s ZenPolicy), from the matrix at its column: the phone’s mode follows the matrix as far as Android lets it (docs/attention.md, §3.3).
Slots: Today’s slots of time for you (docs/capacity.md, G18b), as the window that laid out the day wrote them: every process reads them, so that Time for you holds everywhere.
SourceLine: A source’s row to draw (source_grid): its id (app.<package>, conversation.<key>), its words (an app’s name; a conversation’s title and its app’s), and the group it shows in, in words and by id.

Enums§

Base 🔒: What a source’s row is read over: a row of the matrix, or a person on a channel, on the Always through list or not.
Column: A column: one of the seven times, or a layer above them.
Kind: Sioul’s own and the automated sources: a row each, with no who.
Lane: What the Porch’s lanes decide of mail (docs/attention.md, §2, step 6).
Level: What a cell says, from the least strict to the strictest (the first six); the last two belong to the Always through row alone.
Person: Who, as a row of a people channel (mail, calls, messages).
Preset: Where you start from (docs/attention.md, Q19): as Sioul does now, quieter, more reachable. A preset never touches a fixed cell.
Row: A row of the matrix: a who on a channel, or a kind.
Senders: Whom one of Sioul’s modes lets through the system’s do-not-disturb, on a phone (Android names nobody, starred contacts, contacts, or anyone).
Source: Where an event comes from, with what decides it.
Step: Which step answered (docs/attention.md, §2).

Constants§

APP_ROW: A source’s own row, on a phone (docs/attention.md, §1.3): an app’s (app.<package>) or a conversation’s in one (conversation.<key>, the key appnotes::talk_key makes). A row of the matrix like the others, a cell per column, but each cell says “as usual” (=) until set, read then as the row the notification takes otherwise (a person’s on Messages, a group’s, the automatons’, the apps set to come at once), as Always through’s = reads their own row. A conversation’s cell set wins over its app’s; a source’s cell set for a time is your word for it, so no area holds it then. Blocked senders, codes and what is never held stay as they are.
CONVERSATION_ROW
NAME: A source row’s word for its name, written for your other devices (“name=Discord”); never a column, so an older Sioul leaves it aside.
OLDER: The older keys [attention] replaced, taken out when it is first written.
SLOTS_FILE: The slots file, in the state folder: this device’s own.
SOURCE_CHOICES: The levels a source’s cell takes: at once, at the gathered times, held (later), as usual.

Functions§

apply: A row changed from Settings (attention.<row>, its words; the older grids’ notify.<kind> and the senders’ ticks come here too, reach.<row>): each word read, a fixed cell or a value not offered there refused, a word not understood refused; the row then written whole, or taken out when it says the usual. The first time, every row the older keys seeded is written, and they are taken out.
apply_change: A row changed from the window: only the cells the window changed, from what its row showed (shown, its words then) to value, set over the row as the configuration holds it now; a cell another device changed meanwhile stays. Without shown, every word of value.
apply_locked 🔒
apply_preset: A preset chosen: every row written as it says (the usual taken out), under the configuration’s lock, from the file as it is then.
channel_rows: The rows of a channel, the blocked last.
choices: The values a cell may take, the usual first among them where it can.
column_label: A column’s words.
dnd_from_files: Whether do-not-disturb holds now from its switch or a focus session, as the shared files say (everywhere): its layer, for what runs without the window (sioul remind --watch, sioul watch, a phone’s alarms and listener).
grid: The grid, in tr‘s words, of rows (all of them, or a part: a channel’s, the kinds’), compared with preset. The moment now is said by the window, which knows the devices and the hours (reaches::now_sentences).
is_source: Whether an id names a source’s row: app.<package> or conversation.<key>.
kind_rows: The kinds’ rows: Sioul’s own and the automated sources.
level_label: A value in a row’s own words: a code not told stays on the Porch; Always through’s at once is whatever their list; mail not at all stays in its lane.
list_choice: A state with the times its mail comes or shows, for a list’s choice: “Neutral: work, admin”, “Safe: any time”, “Blocked: never”; one: as said of one person (French says “Sûr” of a person, “Sûrs” of the list).
lock: Why a cell is fixed, as the id of its sentence; none when it can change. A dose comes at its time but in sleep and a pause, your choice; a code you just asked for at once, but in sleep, where “On the Porch only” stays a choice; an event’s alarms in a pause and under do-not-disturb, as both promise; the alarm at waking always; the blocked never.
older 🔒: What the older keys made Sioul do, written as cells (docs/attention.md, §5).
older_notify 🔒: [notify]’s usual values, as it had them (notify.rs at 2e9bbf1).
persons: The rows of a channel, in the order they are shown.
row_label: A row’s words: its person’s or its kind’s.
seeded: The matrix while no [attention] is written: the usual, but where the older keys said something else than their own usual ([reach], [notify], the doses’ switches, the people on the list getting through): what you changed is kept, the decided changes hold elsewhere.
source_grid: The sources’ own rows as Settings draws them (AttentionGrid.qml): each a row of the nine columns, its cells as set or as usual, each in a sentence; a cell set carries the grid’s dot. The values a source’s cell takes, in their own words: at once, at the gathered times, held, as usual.
source_rows: The source rows a notification reads, the most precise first: its conversation’s when it has one, then its app’s.
source_sentence: A source’s row in one sentence: where it comes at once, where at the gathered times, where it is held, and as usual the rest of the time; “As usual at every time.” when nothing is set. “At once: Work and Do not disturb; held: Leisure and Sleep; as usual the rest of the time.”
usual: The usual cell of a row: what Sioul does unless you change it. Today’s behaviour, with the owner’s decisions of 7 October 2026 (docs/attention.md, §9): Always through at once everywhere (mail shown, not told, in sleep and a pause); messages from people held in sleep and a pause; codes at once in every time; calls carry the layers; groups a row of their own.
word: One word of a row: “sleep” (at once) or “sleep:later”; none when either half is not understood.
write 🔒: rows written as attention has them, each whole or taken out when usual; the first time, every row that is not usual too, and the older keys out.
write_with 🔒: write, with sources’ own rows (sources, by id) written too, each as set or taken out when as usual everywhere; the other sources’ rows stay.