Module calls 

Calls screened on a phone (docs/android.md, “Calls”; docs/research/call-screening.md, section 8).

Android asks Sioul about each call, as its “Caller ID & spam app”, and waits for the answer before the phone rings: the answer must come in milliseconds, from Java alone (android/…/Calls.java), never from Sioul’s library. So Sioul writes ahead, in its state folder, a table (calls/table.json): who each number is (by phones::key), the floors that always ring, “Let every call through” as your devices last said it, and the coming days cut into frames, each with whether each row of the Calls rows of the matrix of what reaches you rings then (attention): the times, Free time’s cells, and the layers (today’s slots of time for you, do-not-disturb from its switch or a focus session). Java decides in this order: the floors (an emergency number or its callback; a day after you call an emergency number); your blocked numbers, refused; “Let every call through”; a second call within 15 minutes, which rings; then the frame for now. No table, or past its frames: it rings. Always through (everywhere::People) is no floor any more: its people’s numbers are written as rows of their own (“always-safe”, their own row read where Always through says “as their list”), never a blocked one: blocked beats Always through (docs/attention.md, Q3).

A refused call goes to your voicemail. Java writes every incoming call it screened, declined or let ring (rang), in a file of its own (calls/held.jsonl); Rust copies each into this phone’s own log, calls/log/<device>.jsonl (carry_into), which the sharing carries, sealed, a line at a time, to your other devices (the part “Calls”). Every device reads every phone’s log (read_logs): the Porch lists the declined calls calmly, at the next time those callers may reach you, never counted (lines); a person’s sheet shows their calls of the month (history). Seen is each device’s own log of lines (calls/seen/<device>.jsonl, mark_seen), every device’s read together (read_seen): seen on one, gone from all. A call is kept KEPT_DAYS: each device takes its own lines out after that (trim_own), and the sharing takes them out everywhere.

Let every call through is pressed on any device: each device’s own table in do-not-disturb’s switch file (state/do-not-disturb.toml, shared) carries its last press, [device.<id>.calls]; the latest press anywhere holds. The phone’s notification writes its press in a file of its own (calls/through-here.json) that Java reads at once and Rust carries into the switch (merge_local).

Structs

Decision

What Java answers, and why.

DevicePart

The calls’ part of one device’s table in the switch’s file.

Floors

The numbers that always ring.

Frame

A stretch of time and, for each row of the Calls matrix, whether it rings.

Held

A call screened, as Java wrote it (Calls.held) and as a phone’s log keeps it: declined (held, sent to voicemail) or let ring (rang). The log’s line leaves out what stays on the phone (the number as the network gave it, its presentation) and every empty field (logged).

Incoming

A call as Java sees it (Calls.decide), what it knows beside the table.

Layers

What holds on top of the clock’s times, ahead (docs/attention.md, §1.6): today’s slots of time for you (attention::Slots), and do-not-disturb from its switch or a focus session, from, and until when (none: until turned off; the table is written again when it changes).

Line

One line of the list: a caller, in one context, one day, on one phone.

Lister

What the list needs besides the calls.

Made

What a table is made of.

Message

A voicemail left, as the list says it (voicemail::Voicemail, linked).

Prefix

A prefix on a list, and who a number starting with it is.

RegionRules

A country’s way of writing numbers, as Java needs it (phones::Region).

Seen

The calls seen, by id.

SeenLine

One press of Seen on a device: when (ms), and the calls of its line.

Table

What Java reads (Calls.Table). Times are Unix milliseconds.

Through

A press of “Let every call through”: when (ms, the pressing device’s hybrid clock), on or off, until when (ms; 0: until turned off).

Constants

AFTER_EMERGENCY_HOURS

Every call rings this many hours after you call an emergency number (research 7.1).

DAY_MS 🔒

A day, in milliseconds.

DEVICE_PART 🔒

The key of the calls’ own part in a device’s table of the switch’s file.

EMERGENCY

When this phone last called an emergency number (Java’s).

FOLDER

The calls’ folder, in the state folder.

FRENCH_OVERSEAS 🔒

The French plan’s overseas numbers, by the three digits after the 0 (as phones reads them).

HELD

The calls screened, declined or let ring, one JSON line each (Java’s, this phone’s alone: Rust copies them into its log, LOG).

KEPT_DAYS

A call is kept this long (days), on every device: its phone takes it out of its log after that, and the sharing takes it out everywhere.

LATE_DAYS

Another device’s line kept this long past KEPT_DAYS (days) is taken out by any device: its phone, gone for good, never will (trim_others).

LISTED_DAYS

A call refused stays on the list this long at most (days), seen or not.

LOG

The folder of the phones’ logs of the calls they screened, one file per phone (<device>.jsonl), written by that phone alone; shared.

REPEAT_MINUTES

A second call within this many minutes rings (research 7.3).

ROWS

The rows a frame says, as Java looks a caller up: the states, hidden numbers, and Always through read against each state (“always-neutral”: someone on the list whose own row is neutral).

SEEN

The calls seen on the list, as this phone kept them before Seen was shared: read once into its own seen log, then gone (adopt_older_seen).

SEEN_LOG

The folder of the calls marked seen, one file per device, written by that device alone; shared.

TABLE

The table Java decides from.

TABLE_DAYS

How many days the table’s frames cover, from today’s midnight: it is written again long before, at each change and each step.

THROUGH_HERE

This phone’s press of “Let every call through” on the notification (Java’s).

VERSION

The table’s shape: Java reads this one only (another one: every call rings).

Functions

adopt_older_seen

This phone’s calls seen before Seen was shared (SEEN): one line of its own seen log, then the older file goes. Nothing to do once it is gone.

always_numbers

The numbers of the people Always through, each as a row of its own read against who the number is (judge: “always-safe”), whole numbers only; never a blocked number: blocked beats Always through.

append_private 🔒

Adds lines at the end of a file of this device’s own, made yours alone (0600, in a 0700 folder, on Unix). The caller holds its lock.

capitalized

The first letter in capital: a sentence that starts with a context’s words.

carry_into

Java’s new calls copied into this phone’s own log (own), under its lock, read again there: those whose line is not in it yet (by its id), never a blocked caller’s, nor one past KEPT_DAYS (taken out already, it would come back). Two processes copying at once never write a line twice. Returns how many lines were written.

column_of 🔒

The column a moment is said by: a layer that holds, else the time’s (the pause, sleep, Free time, the hours; work when work and admin are both open, or no hours are set).

content

The table as written, without its time: two tables that say the same are the same.

context 🔒

“while you slept”, “during work”: what the time was, in a few words.

day_words 🔒

“Monday 5 October”, “yesterday”, “today”: a day, as the lines say it before a capital is put to the sentence.

decide

Java’s decision (Calls.decide), step for step: the order’s reference, tested here. Outgoing: rings (to an emergency number, Java marks the moment). Incoming: what always rings (an emergency number, a day after you called one, the do-not-disturb list); blocked; “Let every call through”; a second call within 15 minutes; the frame for now. Nothing to decide from: it rings.

device_files 🔒

Every device’s file of a shared folder (*.jsonl), each with its device’s name, by name.

emergency_keys

Emergency numbers, crisis lines and callback numbers of every country Sioul knows (data/crisis-lines.toml), keyed as each country writes them, and as the person’s country would.

file_safe 🔒

A device’s name as a file’s: letters, digits, - and _.

folder

The calls’ folder.

frames

The frames from from to until, each with whether each row rings then (ROWS): the clock’s own frames (reach::Clock::frames), cut where a layer begins or ends; two in a row that say the same are one.

history

A person’s calls of the last month (keys, their numbers as Sioul keys them), newest first, from every phone, rang or declined: one sentence each, for their sheet, never a count. Each says the phone only when several phones share their calls. A blocked caller’s never come: their calls never leave their phone.

history_line 🔒

“Tuesday 6 October at 23:10, while you slept: declined, sent to voicemail.”, “Today at 06:48, while you slept: it rang. A second call within 15 minutes rings.”

incoming_key

A caller ID as Java keys it (Calls.key, the same steps): phones::key for what a caller ID holds (no extension, no “(0)”). The tests check that the two agree.

is_false 🔒

is_zero 🔒

length

“0:42”: a voicemail’s length.

line 🔒

lines

The list, oldest first: the declined calls not seen yet on any device, of the last two weeks, whose callers may reach you now; never the blocked; one line per phone, caller, context and day. A call that rang is never a line: it is said under the line of the declined calls it followed. calls are every phone’s (read_logs), oldest first; messages maps a call’s id to its voicemail.

local 🔒

mark_seen

Calls marked seen on this device: one line in its own seen log under root, which the sharing carries to the others. Returns the line’s time, to undo it (unmark_seen).

merge_local

The phone’s own press, from its notification (through-here.json), carried into its table once: with Java’s stamp, which came after every press the phone knew then. Whether anything changed.

message_words

What the list says of a voicemail linked to a call.

older_than 🔒

A line older than days before now_ms, by its at; a line that does not read is kept.

own_file

A device’s own file in one of the calls’ shared folders (LOG, SEEN_LOG) under root, the calls’ folder: <folder>/<device>.jsonl, its name in the sharing (a UUID made once).

part_of

A device’s calls part; nothing there: none pressed.

people_keys

The numbers of the people on the do-not-disturb list, whole numbers only (People::admits_number).

person_of 🔒

A frame’s row: its person, on the Always through list or not.

phone_words

The phone a call came to, said on another device: “your phone” when one phone shares its calls with this device, “your other phone” on a phone when one other does, else “your phone (GS290)” by its name among your devices (phones: each phone’s id with its name; “” for this device’s own).

press

A press here (ms): stamped after every press known, so that the latest wins everywhere whatever the clocks. Returns its stamp.

rang_after 🔒

The first call that rang from the same number after the last of group, the same day, on any phone: none for a hidden number (two hidden calls cannot be told apart).

rang_reason 🔒

Why a call rang when its row alone would not say it: a second call, Let every call through, an emergency, nothing to decide from.

read_held

The calls of one file, oldest first; a line that does not read (half written) is passed over.

read_json

A small JSON file of Java’s; none when it is not there or does not read.

read_lines 🔒

Every line of a file of JSON lines that reads; a line cut by a crash, or written by a later Sioul in a shape this one does not know, is passed over.

read_logs

Every phone’s log under root (the calls’ folder), each call with its phone (device), oldest first: never a blocked caller’s (their calls never leave their phone), never one kept past KEPT_DAYS before now_ms (a phone that stopped sharing never takes its own out).

read_seen

The calls seen on any device: every device’s seen log under root (the calls’ folder), read together. Seen on one device, gone from the Porch of every device.

rewrite_lines 🔒

A file of the calls’ kept but for the lines drop names: written beside under a hidden name (yours alone), then put in place, under its lock. Returns how many lines went.

screens_anywhere

Whether some device screens calls: the switch’s tables say.

set_part

A device’s calls part written; a part with nothing to say is taken out.

set_screens

This device screens calls, or no longer: written when it changed.

shown_number

A key as shown: “01 99 00 12 34” for a number of your own country’s ten-digit plan, else its international form.

spacing 🔒

The characters that only space a number out (as phones reads them).

table

The table, as Java reads it.

through_line

“Let every call through” in words: “Every call rings until 15:30.”, “… until you turn it off.”, or after an emergency call, “Every call rings until tomorrow at 09:31: you called an emergency number.”; “” otherwise. through and emergency_at in ms; when words an instant (ms).

through_of

“Let every call through” as your devices say it: the latest press of any (an “on” wins a tie); none when none pressed.

trim_others

Another device’s lines kept LATE_DAYS past their month taken out here (here: this device): a phone gone for good never takes its own out, and its calls must not stay on your other devices for ever. While it shares, it took them out long before (trim_own), and nothing differs. Returns how many went.

trim_own

This device’s own lines kept past KEPT_DAYS taken out of its log and of its seen log under root (the calls’ folder): the sharing then takes them out on every device. A line that does not read stays. Returns how many went.

trunk_zero

The country codes whose numbers drop a trunk “0” (phones’ table).

unmark_seen

A press of Seen undone: this device’s own line written at at taken out of its seen log, and so out of every device’s once the sharing carries it. Another device’s Seen of the same calls stays. Whether a line went.

write

Written beside, then put in place: Java never reads half a table.

write_whole 🔒