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, Expecting a call); 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.
PERSON_ROW: A person’s own row (decision 16 of 18 October 2026; the proposal’s 3.7): person.contact:<the card's UID> for a card, which covers all its numbers and addresses; else person.tel:<a number's key> or person.<address>. Nine cells, for their calls and their messages, each At once, Held or As their list (=), and under do-not-disturb In the shade for their texts. Read after a conversation’s own row and before an app’s, the blocked first; never for someone on Always through, who has no row of their own. No name is ever written: the card gives it.
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; the call screening’s rows left as they are (screened).
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). The switch and the reasons read as the window reads them: the devices gone from the sharing as As usual (everywhere::read_switch), the pause, Free time, the nights and focus (everywhere::sources_from_files), so that a pause ends Reachable here too (review of part 3, F7).
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_person: Whether an id names a person’s own row.
is_source: Whether an id names a source’s row: app.<package>, conversation.<key> or person.<who>.
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: “Your contacts: 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).
person_choices: The levels a person’s own cell takes: at once, held, as their list; under do-not-disturb, in the shade too (their texts; a call then goes to voicemail).
person_row: A person’s row id: who as the lists write it (contact:<UID>, tel:<key>, an address).
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.
screened: Whether a row is the call screening’s (screening), apart from the matrix: numbers nobody knows and hidden numbers, on calls. Kept in the matrix for the screening’s first values and for when a declined call is listed (listed), never shown in its grid nor said by its cards. No preset nor any write of the matrix sets them, and no count of changes counts them (review of part 2, 19 October 2026, F2).
screened_refusal 🔒: The refusal said when a write would set one of the call screening’s rows.
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_rows_with: The source rows a notification reads, the most precise first: its conversation’s, then the person’s own rows (persons: their ids, the card’s first), then its app’s (the proposal’s 3.7).
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. The call screening’s rows are never set (screened): left as they are; the first time, written as the older keys seeded them, so that taking those keys out moves neither them nor the screening’s first values.