Lesson 9.39.3 Scheduled and event-triggered work

In everyday life. An alarm clock wakes you at a set time. A doorbell wakes you when someone comes, and it can ring twice for one visitor.

What you will learn. The two ways work can start without you, at a set time or when something happens, and five facts that every job nobody watches must be designed for. You practice it in Tasks 3, 6 and 8 of the lab.

Why it matters. A run that nobody watches cannot ask you what you meant. Everything it needs has to be written down before it starts, and every way it can fail has to reach a person.

Work that runs without you starts in one of two ways. A scheduled run starts at a set time on the clock: every Thursday at 7 a.m. An event-triggered run starts when something happens: an email arrives, a file changes, a message is posted. Choose by what the work waits for. A weekly note before a payment run waits for a day of the week. A check for an invoice received twice waits for an invoice.

At Brightline, the book's example company, the AP Worker is the AI Worker that handles the bills Brightline owes. When Maria, the office manager, moved the Thursday review from her own chat to a schedule, four things changed.¹ The brief she used to type each week, the written instructions for the task, became a standing spec: written instructions the run reads every time. Like a brief, it says when a run is done, in one sentence that starts "Done when" (5.1). Her habit of checking each note by reading it became examples with known answers. These are past weeks whose right answers she knows, so she can test the spec. Before, she was there to answer questions. That became designed exits: points where the run stops and calls a named person. And the chat became a run in a runtime: the replaceable harness that reasons and acts for the worker. A harness is the software that runs a model in a loop with its tools. Here, the runtime also starts the job on its schedule.

Here are five facts about runs. Design for them on either AI vendor.

Assume each run starts fresh. Many runs begin with no memory of the last one. Some products can return a scheduled task to an earlier chat, but a chat is not a governed record. So anything a run must know about earlier runs has to be written in a place it reads. Concept 9.4 is about where.

A run sees only what it is given. An event-triggered run starts from the event: one email, one file. If the check needs other records, such as earlier invoices, the spec must tell the run to read them.

A trigger can fire twice. A trigger is what starts a run, such as an email arriving. One piece of work can start two runs. A sender sends the same thing again. A system that sent a request tries again. Two events arrive close together. Design every run so that running it twice does no harm. Before it creates anything, it checks whether its output already exists. That check works only if two runs never happen at the same time, because both can read "not done yet" before either one writes. So run such jobs one at a time, or use a shared record that accepts each intended action only once. Chapter 30 covers two more things: recovering a half-finished run after a crash, and limiting how many runs happen at once.

A run acts under someone's identity. The name on the work decides what it can reach and who is responsible for it. A run under one person's account can do anything that person can, and it may stop when that person leaves. Put team work under an identity the team controls, with only the access the job needs.²

A failure must never be silent.² Every run should end with a result in a named place, and a failure should reach a named person. But a run that never starts says nothing. So something outside the run must check that the result arrived: a separate check, or a named person who looks at a set time.

A duplicate run does not have to mean a duplicate payment. DSoR, the Data System of Record, as specified, treats two requests with the same idempotency key, a fixed name for one intended action, as one request. The second gets the first result back.³ It protects the action, not the run, so a second run, note or log line can still happen.

Figure 9.3. Clock or event: the two ways a run starts.