DEV Community: azathothx

Migrating from crontab: five everyday schedules, translated into Kairos

azathothx — Sun, 13 Sep 2026 15:57:25 +0000

If you arrived from the Kairos 1.0 announcement, this is the
hands-on one: take a crontab you already have and translate it.

First, the honest part: if your jobs are plain fixed-time repeats, stay on cron. "Every hour",
"3am daily" — there is nothing to gain from rewriting them. You reach for a schedule language when
you hit one of these: "end of month" won't fit; "business day" won't fit; the job started running at
the wrong hour after a server move; nobody can tell you what was skipped during an outage.

All examples below use one premise — the 2026 US federal holidays (observed dates) — and were run on
the reference implementation. The premise is declared once and reused:

premise US {
  calendar-system: Gregorian
  tz: "America/New_York"
  wkst: Sun
}

@US
holidays2026 = [2026-01-01, 2026-01-19, 2026-02-16, 2026-05-25, 2026-06-19,
                2026-07-03, 2026-09-07, 2026-10-12, 2026-11-11, 2026-11-26,
                2026-12-25] covering: 2026..2026
satSun = everyDay |> filter(d => weekday(d) == Sat or weekday(d) == Sun)
bizDay = everyDay \ (satSun | holidays2026)

1. `0 9 * * 1-5` — weekdays at 9

Two things this cron line does not say. Which 9 o'clock — it's whatever timezone the host
happens to have, which is exactly how "the batch moved an hour after we containerized" happens.
And holidays — cron has no such concept.

bizDay |> at(T09:00)

Labor Day week (Sep 4–10, 2026):

2026-09-04T09:00
2026-09-08T09:00
2026-09-09T09:00
2026-09-10T09:00

Monday 9/7 (Labor Day) and the weekend are skipped. "New York, 9:00" is written in the definition,
so it survives any host move.

2. `55 23 28-31 * *` + a script — month-end at 23:55

cron has no "last day", so the folk remedy is to wake up on the 28th–31st and let a script check
"is tomorrow the 1st?". The check disappears into the expression:

monthEnd |> at(T23:55)
#=> 2026-09-30T23:55  2026-10-31T23:55  2026-11-30T23:55  2026-12-31T23:55

3. Payday: the 25th, previous business day if it falls on a weekend or holiday

This is where migration starts to pay off — cron cannot express the second half at all:

everyDay |> within(month) |> nth(25) |> roll(Preceding, on: bizDay)
#=> 2026-09-25  2026-10-23  2026-11-25  2026-12-24

October 25 is a Sunday, so it rolls back to Friday the 23rd. December 25 is Christmas Day, so it
rolls back to the 24th. roll is a conditional move — it only acts when the point isn't on the
axis — which is what distinguishes it from counting (shift).

4. Last business day of the month

bizDay |> within(month) |> last
#=> 2026-09-30  2026-10-30  2026-11-30  2026-12-31

October 31 is a Saturday, so the month closes on Friday the 30th. "Build the stream of business
days, take the last point of each month" — the structure reads exactly as stated.

5. Three business days before month-end

The expression that started the whole project. Holidays are simply not on the business-day ruler,
so counting skips them:

monthEnd |> roll(Preceding, on: bizDay) |> shift(-3, unit: bizDay)
#=> 2026-08-26  2026-09-25  2026-10-27  2026-11-24

November: the 30th is a Monday; three business days back skips Thanksgiving (11/26) and lands on
Tuesday the 24th.

The three questions cron never answers

Save the definition to a file and ask the CLI.

What's next?

$ kairos next -n 3 --from 2026-09-14 payday.kairos
2026-09-25
2026-10-23
2026-11-25

What did I miss? Say the box was down Oct 20–31:

$ kairos list --from 2026-10-20 --to 2026-11-01 payday.kairos
2026-10-23

The payroll run on the 23rd was skipped — and you learn it as a list, not by re-deriving the
schedule in your head. (--from/--to is a half-open interval; the --to day is excluded.)

So how do I actually run it? Keep one crontab line. Kairos stops at when things should
happen; firing, retrying, and logging stay with your runner (systemd, a job queue, whatever you
already trust). That division of labor is written into the spec, not left to convention — which is
no help by itself, so here are the two wiring patterns. Both work with the CLI as it ships
(--json emits the same points, machine-readable, with epoch milliseconds). One thing to know first:
labels, the [--from, --to) window and the default "today" are read in your machine's time zone
(override with --tz). The outputs in this post were taken with the machine in America/New_York;
elsewhere, add --tz America/New_York and you get the same labels. If the machine's zone and the
definition's premise zone differ, day-granular points print with a time of day — midnight in New
York shows up as T13:00 in Tokyo — and the daily window may not line up with the definition's day.

Pattern 1: cron stays the clock, Kairos makes the decision. Keep a single crontab line and move
the calendar logic out of it. Every morning at 9, ask "is there a point today?" and run the job if so:

0 9 * * *  cd /srv/batch && ./run-if-today.sh payday.kairos ./payday.sh

#!/bin/sh
# run-if-today.sh <definition.kairos> <job> — exec the job if there is a point in [today, tomorrow)
today=$(date +%F); tomorrow=$(date -d "$today + 1 day" +%F)   # GNU date; macOS: date -v+1d +%F
n=$(kairos list --from "$today" --to "$tomorrow" --json "$1" | jq '.results[0].dates | length')
[ "$n" -gt 0 ] && exec "$2"

Holidays and the time zone live in the definition, so the crontab line carries no weekday and no
day-of-month. The window is [today, tomorrow) in the machine's zone; if the definition's premise
zone is a different one, pass --tz with that zone so the window is the definition's day. Count with --json: the human-readable output also prints the coverage summary as
# lines, so a naive | grep -q . would fire every day. With the payday.kairos above this
yields 0 for 2026-09-14 and 1 for 2026-09-25.

Pattern 2: schedule the next point, one at a time. Put the time of day into the definition as
well (… |> roll(Preceding, on: bizDay) |> at(T09:00)) and ask for the next point. next --json
returns it as wall-clock text and as epoch milliseconds; hand it to a one-shot OS timer, and let the
job re-register the next point as its last step:

t=$(kairos next --json payday.kairos | jq -r '.results[0].dates[0]')   # e.g. 2026-09-25T09:00 — printed in the machine's local time zone, which is what the timer expects
systemd-run --user --on-calendar="$(echo "$t" | tr T ' '):00" ./payday.sh
# same shape with at(1) on Linux, or schtasks /sc once on Windows

"Re-materialize the point list periodically" is exactly the operating model the spec describes; the
full 20–40-line version of this gets its own post.

And the data

The examples inline eleven holidays. In production you feed calendar data through an external
binding — the expression stays static, the data arrives at runtime — and every table carries a
covering: claim ("verified through this date"). Past that date, results still come out, but with
a machine-readable annotation saying the calendar ran out. Nothing degrades silently.

Try it

Everything runs in the browser; nothing leaves the page. Install the CLI with
npm i -g kairos-lang, then kairos next -n 3 payday.kairos.

Kairos is at 1.0 — the language is frozen; the reference implementation is a prototype
(TypeScript, zero runtime dependencies). Docs are canonical in Japanese with a
full English mirror. Repo:
https://github.com/azathothx/kairos-lang. Apache-2.0.

Disclosure (AI-assisted): the English text of this post was drafted with an LLM from my Japanese originals and reviewed by me before publishing. Every code example and its output was executed by the reference implementation; the numbers are measured, not written.

Kairos 1.0 — a schedule language where "3 business days before month-end" is an expression

azathothx — Sun, 13 Sep 2026 15:57:20 +0000

Today I tagged 1.0 of Kairos, a schedule
definition language I've been building — a small DSL where schedules like "3 business days
before month-end" or "payday on the 25th, previous business day if it's a holiday" are single
expressions.

premise US { calendar-system: Gregorian; calendar: NYSE; tz: "America/New_York"; wkst: Sun }

@US
monthEnd |> roll(Preceding, on: bizDay) |> shift(-3, unit: bizDay)

The itch

cron can say "the 25th". It cannot say "the 25th, rolled back onto business days". Quartz has
L and LW, but they don't compose and don't know about holidays. RRULE was designed as an
exchange format, not an expression language.

The root problem isn't a missing feature — their expressions don't compose. You can't take
the dates one rule derives and feed them into the next rule. Kairos is built around closure:
every expression maps a time stream to a time stream, so derived streams (substitute holidays,
fiscal periods, lunisolar months) feed further definitions.

Try it in your browser

The reference implementation runs client-side; nothing leaves the page.

Payday: the 25th → previous business day (US federal holidays)
3 business days before month-end
Deriving the observed federal holidays from the statutory dates alone — July 4, 2026 lands on a Saturday; the expression yields July 3. No lookup table of observed dates anywhere.

What's different from a date library

Temporal, date-fns, dateutil are arithmetic over points and durations. Kairos is one layer
up: it defines and governs sets of instants (streams).

Calendars are user-defined. The Gregorian calendar itself is a transparent stdlib written in Kairos. Fiscal calendars (4-4-5 included), trading calendars, and the Japanese lunisolar calendar are ordinary definitions, not built-ins. Derivation rules — like the observed-holiday expression above, or Japan's substitute-holiday law — live in the definition, not in a pre-expanded table.
A definition denotes a set of instants. Evaluation is a pure function — missed fires during downtime are enumerable, audits are reproducible. This has now survived a summer of production use by an independent implementation (schedule predictions stable across 10 hostnames and a local→VPS migration).
When calendar data runs out, the results say so — machine-readable annotations (covering / freshness) instead of silent degradation.
Mistakes are static errors with fix-it guidance: mixing civil-day and elapsed-hour widths, undeclared timezones or week starts, misaligned streams, unknown named arguments.

What 1.0 means

The language is frozen: semantics, the operator family, the grammar (EBNF), and the lexis.
Definitions that parse today keep their meaning. The reference implementation stays honest
about what it is — a prototype (TypeScript, zero runtime deps; 638 tests including doctests:
every example in the docs is executed in CI).

The documentation is canonical in Japanese — I develop documentation-first in my native
language — with a full English mirror of the spec, operator reference, and stdlib guides.
Evaluator error messages are currently Japanese (the CLI's --json output is language-neutral).
Apache-2.0.

"One day later" and "24 hours later" are different quantities — the batch job that drifts an hour every spring

azathothx — Tue, 18 Aug 2026 12:03:09 +0000

The code didn't change. The schedule did.

There's a batch job on a US East Coast server that runs every morning at 9:00. It has been
running fine for months — until the second Sunday of March, when it quietly starts running
at 10:00 every morning. Nobody deployed anything.

The cause usually looks like this:

next = prev + 24 * 60 * 60 * 1000;   // "one day later"

The US East Coast switches to daylight saving time at 02:00 on the second Sunday of March.
The clock jumps forward one hour, so that civil day is only 23 hours long. "Previous
time + 86,400 seconds" is physically exactly 24 hours later — but read on a wall clock,
it's an hour off. And it stays off until the clocks fall back in November.

The interesting part is not how to fix the bug. It's the fact that the phrase "one day"
names two different quantities:

A civil day — one square on the calendar. It sticks to the wall clock, and on a transition day it is 23 or 25 hours long.
24 elapsed hours — 86,400 physical seconds, regardless of what the wall clock does.

Both are legitimate readings of "one day"; which one you want depends on the requirement.
A daily 9:00 report wants the former. "Inspect the equipment every 24 hours of runtime"
wants the latter. The accident starts the moment your code holds both in the same type.

In Kairos, they are different literals

Kairos is a schedule definition language I've
been writing about (in Japanese) for a while. It separates the two quantities at the level
of width literals: 1d is a civil day, 24h is elapsed time. Here is "every day from
9:00" written both ways, evaluated across the 2026 spring-forward date (March 8) in
America/New_York:

premise NY {
  calendar-system: Gregorian
  tz: "America/New_York"
  wkst: Mon
}

@NY
everyInstant |> strideBy(1d, from: 2026-03-06T09:00)
everyInstant |> strideBy(24h, from: 2026-03-06T09:00)

# expression 1 (4 points)
2026-03-06T09:00
2026-03-07T09:00
2026-03-08T09:00
2026-03-09T09:00
# expression 2 (4 points)
2026-03-06T09:00
2026-03-07T09:00
2026-03-08T10:00
2026-03-09T10:00

▶ Open in Playground

Expression 1 (1d) sticks to 09:00 every day. Expression 2 (24h) drifts to 10:00 on
the transition day — and stays there. That's the batch job from the opening,
reproduced. Neither expression is wrong: they are different questions, and the
language returns different answers.

And if you try to write a width that mixes the two:

字句エラー(8:26): 市民時と経過時間の幅は混合できない: 1d12h（ADR-28）

— a lexical error: "civil-time and elapsed-time widths cannot be mixed: 1d12h".
It is rejected at parse time. "One day and twelve hours" is a quantity whose length
is undefined until you know how the civil day stretches; if you could write it, its
behavior on transition days would be implementation-defined. So you can't write it.

Writing a time that doesn't exist

A transition day also has a wall-clock hole: 02:00–03:00 never happens that morning.
Write 02:30 of that day as data — a named, literal time — and:

x = [2026-03-08T02:30] covering: 2026..2026
x

存在しない時刻: 2026-03-08T02:30（tz "America/New_York" の DST の隙間に落ちる——実在の壁時計で書く。ADR-33）

— "nonexistent time: 2026-03-08T02:30 (falls into the DST gap of tz "America/New_York" —
write a wall-clock time that exists)".

▶ Open in Playground

No silent forward-shift to 03:30, no silent drop. You named a specific wall-clock time;
that time doesn't exist; therefore your data is wrong — and the language says so.
Contrast this with points that are derived by evaluation (say, a "daily at 02:30" rule
hitting the transition day): those resolve deterministically to "the first instant after
the gap", by convention. Named times are strict; derived times follow conventions.
Nothing you didn't write ever runs; nothing you did write is silently rewritten.

"We don't have DST here"

Half true. Japan (where I live) hasn't had DST since 1951; our civil days are always
24 hours. But "the server is on UTC, the business runs on Tokyo mornings" is an everyday
setup, and inside it someone is doing the civil-day ↔ elapsed-time conversion — every
single day. A cron line 0 9 * * * means "9:00 wherever the server is", and its meaning
changes the day you migrate the box. Same species of bug: not "which quantity", but
"whose wall clock" left unstated.

That's why a Kairos premise requires the timezone declaration (tz: "America/New_York"
above): no schedule definition can be written without saying whose wall clock it reads.
Move the server; the definition means what it always meant.

cron's minefield — I've written before about what 0 9 13 * 5 actually does — is rarely
a lack of power. It's polysemy: "one day" that names two quantities, "9:00" that
doesn't say whose. What a language can do is split the ambiguous words into distinct
spellings, and make the confusion unwritable.

Kairos is a schedule definition language in RC, developed documentation-first: the spec,
operator reference, and stdlib guides are canonical in Japanese with a full
English mirror, and every
example in the docs is executed and verified against the reference implementation in CI.
The Playground runs that same reference
implementation in your browser (nothing leaves the page); evaluator error messages are the
implementation's canonical Japanese, as you saw above — the English spec defines their exact
semantics. If you came for the "schedules cron and RRULE can't express" angle, the
recipes walk the greatest hits — last business day
of the month, Easter as pure arithmetic, the 4-4-5 fiscal calendar — one page per
requirement, each with a runnable Playground link.

DEV Community: azathothx

Migrating from crontab: five everyday schedules, translated into Kairos

1. 0 9 * * 1-5 — weekdays at 9

2. 55 23 28-31 * * + a script — month-end at 23:55

3. Payday: the 25th, previous business day if it falls on a weekend or holiday

4. Last business day of the month

5. Three business days before month-end

The three questions cron never answers

And the data

Try it

Kairos 1.0 — a schedule language where "3 business days before month-end" is an expression

The itch

Try it in your browser

What's different from a date library

What 1.0 means

Links

"One day later" and "24 hours later" are different quantities — the batch job that drifts an hour every spring

The code didn't change. The schedule did.

In Kairos, they are different literals

Writing a time that doesn't exist

"We don't have DST here"

1. `0 9 * * 1-5` — weekdays at 9

2. `55 23 28-31 * *` + a script — month-end at 23:55