Recipes — practical forms of the schedules long said to be unwritable
Translated from the canonical Japanese page recipes/README.md. The
source_shaabove records the source revision; a consistency check flags this page when the Japanese original changes.
Schedule requirements that cron, Quartz, and iCalendar RRULE have long been said to be unable to express, presented as one page per requirement. Each page runs “what happens today (with sources) → the Kairos expression (execution-verified) → try it in your browser” — the answer first, the background after.
| Page | Requirement |
|---|---|
| Last day of the month | cron’s most common stumbling block, up to the last business day |
| Easter | The canonical movable feast RRULE cannot express — pure arithmetic, zero data |
| What is a 4-4-5 calendar? | Definition, the 4-5-4/5-4-4 variants, the 53rd week, a 2026 period table; the carry rule falls out of the definition |
| Nearest weekday to the 15th | The general form of Quartz 15W, extendable to holidays |
| US Election Day, Black Friday and the Sunday after Thanksgiving | Dates relative to a computed date; RRULE’s BYMONTHDAY=2..8 encoding written in the order the law states it |
| Patch Tuesday | The second Tuesday at 10:00 Pacific, shown in any time zone from one definition; why “second Wednesday, 3 am” in Tokyo is wrong in 8 of 12 months |
| Kairos for Windows administrators | PowerShell and Task Scheduler, nothing else: definition → list → --json → a daily check → .ics for Outlook. For people who run commands but do not write software |
| Schedules that are hard to write with Excel’s WORKDAY and EOMONTH | Last business day of the month, payment on the 25th, the 10th business day, three business days before quarter-end — side by side with the Excel formulas. An expired holiday table is not allowed to stay silent. Results go to Excel as TSV |
| Non-delivery days and arrival dates — a logistics business-day calendar | Business days from Sundays, holidays, year-end and Obon closures; arrival date (ship date + N business days), the 15:00 order cutoff, scheduled pickups and the year-end band, all from one definition. Business-day and non-delivery masters as TSV; the yearly update is regenerate-and-compare |
| Calendar (fill in → month view → print / .ics) | Five everyday schedules (recycling, trash, payday, alarm clock, weekly class) decided by filling in blanks. The expression is assembled behind the page (visible in a fold). Month view (the week starts on the premise’s wkst), A4 printing with one month per page, .ics, round trip with the Playground |
- Every code example is execution-verified by the reference implementation’s doctests
(
impl/test/doctest.test.ts).# eval:gives the evaluation range and#=>the expected output (conventions: reference). Blocks using@JPget the standard doctest premise (Gregorian, Asia/Tokyo, wkst: Mon, with a calendar entity carrying Japan’s confirmed 2026 holidays). - Each page’s Playground link is a self-contained form (premise included) — run and edit it directly in the browser (the Playground executes the reference implementation as is; nothing is sent to any server).
- The full catalogue of collected “unwritable” cases (32 items with sources) and their three-way classification: study 11. These recipes are the practical re-arrangement of that study’s measured section.
- The language itself: specification · vocabulary: descriptor reference.
The shape of a shared URL
“Pin to URL” in the Playground and the shared URL of the Calendar have the same shape. The expression and the evaluation range ride in the URL hash — no server, nothing stored. These four items and their encoding are a published commitment (2026-10-30) and will not change.
https://kairos-lang.org/en/playground/#s=<source>&f=<from>&t=<to>&z=<tz>
| Item | Meaning | Form |
|---|---|---|
s |
The whole source (self-contained, premise included) | UTF-8 bytes in base64url (RFC 4648 §5: +→-, /→_, no trailing =) |
f |
Start of the evaluation range (included) | YYYY-MM-DD |
t |
End of the evaluation range (excluded — half-open [f, t)) |
YYYY-MM-DD |
z |
tz for display and for the range edges | IANA name (e.g. Asia/Tokyo); Asia/Tokyo when omitted |
- The Calendar adds
e=<example id>&v=<blank values, comma-separated>to the same hash; the Playground reads onlys,f,tandz. - In the browser:
b64e/b64dinplayground/core.js. In Node,Buffer.from(src, 'utf8').toString('base64url')gives the same value. - Subscriptions (webcal) and per-user storage belong to the receiving side that takes this shape.