Module porch 

The Porch: where new mail waits, checked and sorted, until you look.

Every message gets one lane and the reasons for it. The order of the checks is the order of what protects you most: forged mail first, then spam, then the short-lived codes that cannot wait, then projects, then the rest (docs/porch.md). The core returns facts; the sentences are the translator’s (i18n), in your language.

Structs

Book

Your address books, as who may reach you needs them (docs/porch.md, “Who may reach you, and when”): who is in them, by address, number, name and card, with each card’s categories. Read from every address book, on a server or on this device only, read-only ones too.

BookCard

A card of your address books, as who may reach you needs it.

Checks 🔒

What the Porch reads of a message before it gives it a lane: who sent it, how far that is believed, and what protects it.

Context

What the triage needs to know beyond the message.

Gate

The Porch’s checks for mail already kept (admission), read from its file with what the Porch reads beside it: every account’s trusted ids and words, your projects and the mail tied to them, who may reach you, your own addresses, the AI’s readings of shielded mail. A project’s page, the mail tied when a project’s routes change, the agents’ consent and their list_projects ask it before a project takes a message.

Judged

Who someone is, and why.

Sender 🔒

Who sent a message, as every rule of its triage reads it: judged once (Context::sender).

SenderList

A list of who may reach you, one entry per line, # for comments: an address, or a pattern holding * for any run of characters (*@example.org: everyone there; *@*.example.org: its subdomains; news*@example.org; @example.org and a bare example.org stand for *@example.org); a phone number, tel:+33465711234, however written, or a prefix with * (tel:+3319900*); a contact card, contact:<its UID>: all its addresses and numbers, now and later; a category of your contacts, category:Friends. Five such lists exist: the senders you let in (the screener’s), and who is safe, neutral, restricted or blocked (Senders).

Senders

The four lists of who may reach you: safe, neutral, restricted and blocked, with your address books, their cards and categories, and the senders you let in (docs/porch.md, “Who may reach you, and when”). The most precise entry decides: the person’s own address or number; then their card (contact:<UID>); then its categories; then patterns (a domain, a prefix), the more precise first; then, neutral: let in through the screener, or in your address books; else a stranger. At one level, blocked before restricted before neutral before safe. An address marked safe stays safe in a domain you blocked; a friend you put on neutral stays neutral in a category you marked safe. Lists judge the sender’s address only, after forged mail was set aside: a message whose sender is not verified never changes them (porch.rs, trust.rs), and nobody is judged by the server or the domain another sender shares.

Summary

What came, as counts: the translator turns it into a few calm sentences.

Triaged

A message with its lane and the reasons, as the Porch shows it.

Enums

Admission

Whether a project may take a message, as the Porch decides it: the one check behind every place that ties mail to a project (the Porch’s lanes, a project’s page and its line of time, the mail tied when a project’s routes change, the agents’ list_projects), so that none of them shows what the Porch would not.

By

What decided who someone is, the most precise first.

Entry

What one line of a list names.

Lane

Where a message waits.

Reason

Why a message is where it is.

Standing

The four lists (docs/porch.md, “Who may reach you, and when”): where an entry is written. Who someone is (reach::Who) adds strangers, who are on none.

Constants

CATEGORY

What starts a line naming a category of your contacts: category:Friends. Never a pattern: a pattern has no :.

CONTACT

What starts a line naming a contact card by its UID: contact:….

REVIEW_DAYS 🔒

How long a message your filter flagged waits in the review queue after you closed the Porch on it: the Porch’s two weeks.

TEL

What starts a line naming a phone number: tel:+33465711234.

VERDICTS_KEPT 🔒

Verdicts remembered at most: past them, the memory starts again.

Statics

VERDICTS 🔒

The verdicts on files remembered, under one gate’s seal; emptied when the seal changes.

Functions

admission

Whether a project may take a message (Admission), as triage decides it. Its code is looked for only where a code could change the verdict (it is what reading the whole text costs): a mailing list’s message failing DMARC (no list relays your codes), or one your provider calls spam (a code protects it). Elsewhere the verdict is the same without it.

admission_of 🔒

after 🔒

What follows head at the start of a line, case aside; none when empty.

card_of

The card a line names, by its UID (“contact:…”).

category_key

A category’s name as categories are compared: trimmed, without case or accents (“Amis”, “ amis “ and “AMIS” are one), as contacts.rs compares them.

category_of

The category a line names (“category:Friends” → “Friends”), as written; none for an address or a pattern.

checks 🔒

checks_with 🔒

checks, the results and the code already read (detected).

choose_lane 🔒

The lanes are decided in this order: set aside; for a shielded address, hostile (both admission); what your own spam filter flagged or would move, as you chose (review); codes; projects; what you sent yourself; a shielded address’s own lane; addresses ranked below; newsletters and automatic senders; the screener; people you know.

clear_standing

Takes an entry’s own line out of every list: its card, its categories, else its domain, decide (“As their categories say”).

expired 🔒

A code past its validity is no longer a code to show: its message goes to its lane.

filed 🔒

files_in 🔒

The files of a Maildir folder, new/ and cur/.

fits 🔒

Whether text fits pattern, * standing for any run of characters.

flagged_since 🔒

What your filter flagged in src’s inbox, closed on since: the review queue waits for your word whatever you close, two weeks at most. Only the files stored here in that time are read.

follow_conversations 🔒

A message in the conversation of one of a project’s goes to that project, unless it was set aside, is a code or is hostile: those lanes come first.

gather

Everything waiting in the Porch, from every source, minus what you closed it on. Messages already done are skipped by their file name, without being read. Mail from senders you blocked is left out: never shown, never counted.

in_project 🔒

A project’s mail, as its routes say. Mail nothing authenticates is read as from nobody: a route that names a sender’s address or domain takes it no more; one by its subject, its text or an attachment still does.

judge

Judges files just fetched as the Porch would, each with its account’s trusted ids.

list_paths 🔒

Each list’s file, in the order ties are decided: blocked, restricted, neutral, safe.

moved_item 🔒

A message your filter moved, as the review queue shows it: who sent it, as for any message, and that your filter moved it.

moved_items 🔒

Mail your own filter moved into a Junk folder of src’s account (among folders, as its server last listed them), here or on another device (moved, every device’s log), still there and waiting for your word (said: no label about it since, and neither $Junk nor $NotJunk set on it in another mail client): in the review queue, as moved. Only the files fetched into the Junk folder after the move are read.

name_key

A name as chat senders are matched to cards: its words, one space between them, without case. Accents count: “Hélène” is not “Helene”.

normalize

An entry as a pattern: lower case; @domain and domain as *@domain. None for what cannot be an address or a pattern.

number_key

A number’s key, as phones::key reads it; a prefix keeps its *, its digits in the international form when they say their country (“+33 1 99 00*”, “003319900*”, or “019900*” read in France: “+3319900*”). None when empty.

number_of

The number a line names: after tel:, or a line that is only a number (“+33 4 65 71 12 34”, “04.65.71.12.34”, a prefix “+3319900*”); none for anything else.

own_addresses

The sources’ own addresses.

own_domains 🔒

The domains of the sources’ own addresses (see lookalike::own_domains), with the sources’ words (the same for every source of a configuration).

precision 🔒

How precise a pattern is: an address beats any pattern; between patterns, the one with more written characters.

protected 🔒

What no spam verdict touches, your provider’s or Sioul’s own filter’s (the owner’s decision; docs/porch.md, “Set aside”): mail from anyone but a stranger (safe, neutral or restricted: in your address books, on a list, let in), a code or a password, mail a project’s routes take, your own; and a message you said is not spam, here, on another device or in another mail client (spam::labels::said_ham). Blocked and forged mail, and a stranger borrowing a name, are set aside before this is asked.

public 🔒

A shielded address’s mail from someone you have not let in: its own lane.

push_once 🔒

review 🔒

A stranger’s message your own filter judged (learned: only of mail no protection covers), whose class you chose to flag or to move into the Junk folder: the review queue, where it waits for your word, never notified. A message to move stays there until it is moved, once fetched (sioul-app’s spam::after_fetch). “Do nothing”: its lane, as if unjudged.

right_now 🔒

What you just asked a site for, from its automatic address too: at once. A forged one was set aside before; one not verified says so (triage).

screener 🔒

sealers 🔒

Whose ARC seal vouches for mail that failed SPF and DKIM on its way (trust::authenticated): your provider’s (the hosts of the ids it writes its results under; Sioul’s own stamp seals nothing) and your own domains.

sent

When a message was sent, for its code’s validity: its Date, never later than it reached your provider (its file’s time, maildir::store), so that a message dated in the future, or not dated, cannot keep a code on top for good. The phone’s home screen card hides a code at the same time (sioul-app’s homecard).

set_aside 🔒

Blocked, forged, borrowing a brand’s name, or spam: set aside, never deleted. A sender you let in keeps the name they use. Spam here is your provider’s word; it never reaches what is protected. Sioul’s own filter’s verdicts go to the review queue instead (review).

set_category

Puts a category of your contacts on one list and out of the three others; none: on no list, each person as their own entry or their domain says.

set_person

A person’s state, for all their addresses and numbers (a contact card’s chooser): their card on one list (contact:<UID>), or on none (standing none: their categories decide), and the own entries of their addresses and numbers taken out, so that the card decides for all of them. A card without a UID gets its addresses and numbers written one by one instead.

set_standing

Puts an entry in one list and out of the three others: an address or a pattern, a number (tel:…, or digits alone), a card (contact:<UID>), or a category; your own choice for it, whatever its card, its categories or its domain say.

stored_at 🔒

When a stored message was stored here: the start of its file’s name.

summarise

Counts what came, lane by lane.

triage

Gives one message its lane and its reasons.

unblock

Unblocks an entry: out of the blocked list; still blocked by its card, a category or a broader pattern, it is written neutral, so that it is not.

unblock_person

Someone put on Always through comes off the blocked list (docs/attention.md, Q3: one list takes them off the other): their addresses’, numbers’ and card’s own lines there taken out. Whether any was.

Type Aliases

FileKey 🔒

A file’s verdict, by its path, size and modification time (nanoseconds).

KnownSenders

The senders you let in: they skip the screener.