Module jobs 

Long jobs run apart (docs/mcp.md, “The spam filter’s tools”): the MCP’s spam_fetch and spam_train start a detached sioul spam fetch|train --job <id> and answer at once with its id. The job writes where it stands, then its result, into $XDG_STATE_HOME/sioul/spam/jobs/<id>.json, which spam_job and sioul spam job read.

• Its process holds <id>.lock while it runs: a job whose file still says it runs, but whose lock nobody holds, ended without a word (killed, the computer stopped), and is said so.
• <id>.stop, made by spam_job with stop (or sioul spam job <id> --stop), stops it at its next step; what was downloaded stays.
• What it printed goes to <id>.log (its errors; never a message).
• The folder and its files are yours alone (0700, 0600); a job’s files go a week after it ended. A training’s result names its worst errors by their senders and subjects, masked: kept no longer than that.
• One job of each kind at a time.

Structs

Job 🔒

One job, as its file keeps it.

Running 🔒

A job, from inside its own process: it holds the lock while it runs, says where it stands at most once a second (and at each new step), and stops when asked.

Step 🔒

What a job is on now: a stage of sioul_learn, how far, and a line saying it.

Enums

State 🔒

Where a job stands.

Constants

GRACE 🔒

Seconds a job may stay “starting” before its process is looked for.

KEPT_DAYS 🔒

Days a job’s files are kept after it ended.

KINDS 🔒

The jobs that run apart.

Functions

create 🔒

A new job’s file, “starting”: one of each kind at a time; those ended a week ago go.

detach 🔒

A process of its own, which the end of the one that started it does not end.

file 🔒

folder 🔒

The jobs’ folder: $XDG_STATE_HOME/sioul/spam/jobs.

held 🔒

Whether a process holds the job’s lock: it runs.

list 🔒

Every job kept, the newest first.

log_tail 🔒

The last lines its process printed, on one line each (an error’s words).

look 🔒

A job as it stands: one whose file says it runs, but whose process holds its lock no more (after the grace a starting one has), ended without a word: said “died”, with the last words it printed.

new_id 🔒

A new job’s id: when, what, and four letters: “20261007-153012-train-kxqa”.

now 🔒

private_file 🔒

A file of the folder opened to write, yours alone.

private_folder 🔒

The folder, made yours alone.

prune 🔒

The files of jobs ended more than a week ago, gone.

read 🔒

A job’s file as written.

running 🔒

The job of this kind that runs, if one does.

spawn 🔒

The job’s process, started apart; the job said failed when it cannot start.

start 🔒

Starts a job: its file made (“starting”, create), then sioul spam <kind> --job <id> <args> started apart, in a group of its own (on Windows, without a console), so that it goes on when the program that started it ends. Answers at once; the job’s own process says the rest in its file.

step_line 🔒

A step said in the person’s language: “home · INBOX: 1200 / 3000”, “Learning your mail’s words…”.

stop 🔒

Asks a running job to stop at its next step.

valid 🔒

Whether id can name a job: letters, digits and dashes, as start makes them; anything else (a path, “..”) names none.

write 🔒

A job’s file written whole: beside, then moved, so that a reader never reads half of it.