@cloudhal/schedules

Scheduled publishing and automations for Cloudhal sites (RFC-0008, ADR-0023): the time model, the RRULE subset, releases pinned to exact node versions, automation and run state, taint and budget accounting, and the scheduler's runDue with its D1/SQLite store.

Everything here is Worker-safe: no Node-only import at any entry. The only Temporal entry point is temporal-polyfill/implementation (never a native or global Temporal, never Temporal.Now; Biome refuses the other entries and a test scans the repository). now is always injected.

Time (§9)

• resolveLocalTime("2026-11-02T09:00", "Europe/Istanbul") → { at: "2026-11-02T06:00:00.000Z", offset: "+03:00" }. A time inside a DST gap moves to the next valid time (adjusted: "dst-gap"); a repeated time resolves to its first instant (D2).
• recomputeExecuteAt(when) — never early: a stored wall-clock time is re-resolved with today's tzdata and the instant only ever moves later (adjusted: "tzdata").
• isTimeZone, toLocalDateTime, zoneOffset, latenessSeconds, canonicalInstant (the stored form is Date#toISOString()).

Recurrence (§9.3, D3)

parseRule, formatRule, validateRecurrence (minimum interval 1 hour, at most 24 a day), occurrences, nextOccurrence, occurrencesBetween, presetRule/presetOf, presetMinuteOffset. Gap occurrences move forward instead of being dropped (the documented deviation from RFC 5545 §3.3.10); property tests compare the expander with rrule-temporal on seeded random rules with that difference excluded.

Sentences are data: describeRecurrence(rec) returns { key, times, days?, weekdays?, monthDays?, n?, count?, until? }; renderRecurrence(sentence, "en" | "tr") renders it with RECURRENCE_MESSAGES ("On the second Tuesday of every month at 09:07" / "Her ayın ikinci salısı 09:07").

Releases (§6)

• pinItems, dependencyClosure (with referencedNodeIds as the default extractor), composeRelease (S1: nodes(S) = nodes(L) − ids + targets), releaseConflicts (S4), missingDependency, planRelease.
• RELEASE_TRANSITIONS, HOLDING_STATES, TERMINAL_RELEASE_STATES, releaseWhen (lead time, horizon), baseApprovalVerdict (D5, D9), isPastLateLimit and nextRetryAt (the one-hour rule and back-off), orderReleases and releaseOverlaps (D15).

Identifiers (stable)

rl1   = "rl1:" + hex(SHA-256(utf8(lines.join("\n"))))
lines = ["site <siteId>"] + per item, sorted by node id (code-unit order):
        "<set|remove> <nodeId> <nodeKind> <targetRev>:<targetHash>|- <baseRev>:<baseHash>|-"

runId = "run_" + Crockford-base32(first 100 bits of SHA-256(utf8(subjectId + "\n" + occurrenceAt.toISOString())))

The time is not in rl1: (D4); an approval request's args_hash covers approvalArgs(releaseId, when). Release and automation ids are random (rel_/aut_ + 20 Crockford characters); lease tokens are random per claim.

Automations (§5.3, §11)

AUTOMATION_TRANSITIONS, RUN_TRANSITIONS, accountRunResult (three failures pause, a budget breach pauses at once), dueOccurrences (only the latest missed occurrence runs), runWindow, runEndsAt, killSwitchPauses/killSwitchResumes; taint (checkRunCall, afterRunCall, forbiddenUntrustedScopes, untrustedEffectiveScopes); budgets (checkRunBudget, budgetLeft, withinDailyWriteCap).

Scheduler (§8)

import { createScheduler, TICK_BUDGETS, TickMeter } from "@cloudhal/schedules";
import { SqlScheduleStore } from "@cloudhal/schedules/sql";

const scheduler = createScheduler({
  openStore: (meter) => new SqlScheduleStore(meter.wrap(d1Driver)),
  newMeter: (budget) => new TickMeter(budget),
  releases: releaseExecutor({ graph, schedules }), // `@cloudhal/core-ts/releases`
  builtins, systemJobs, checkApproval, wake: "minute",
});
await scheduler.runDue(new Date(controller.scheduledTime), TICK_BUDGETS.free, "cron");

In practice every ticker calls runScheduledTick from @cloudhal/core-ts/releases, which builds the graph, this store, the executor and the system jobs over one TickMeter. runClaimedRelease ends a run a caller claimed itself (a person's "Publish now", SqlScheduleStore.claimManualRun).

runDue claims each occurrence with a compare-and-swap and a fresh lease token and guards every later write on that token, so concurrent ticks produce one effect (S3). Releases run one at a time per site in time order (D15), at most an hour late (S8), with back-off retries and lease recovery. SqlScheduleStore.releaseFinishStatements(…, guard) gives publishRelease the statements that end a release to append to its own guarded batch.

For the API and MCP (rollout steps 7–8) the store also has automationByKey, openAgentRun, readyAgentRun, openManualWindow, recordRunCall, endAgentRunAs, updateAutomation, deleteAutomation, retitleRelease and releaseLateness. The scheduler's checkApproval is createReleaseApprovalCheck from @cloudhal/mcp-server/schedules (re-exported by @cloudhal/api with releaseRights).

Built-in automations (§11.1, rollout step 9)

createBuiltinRunner(sources) is the BuiltinRunner for the five jobs; @cloudhal/core-ts/automations implements BuiltinSources over the site graph (graphBuiltinRunner), and runScheduledTick uses it by default. Every job runs in bounded steps — one per tick, at most BUILTIN_STEP_COST[job] statements — and keeps its position in automations.cursor, so a large site spans several ticks and a crash between them continues the same run. Findings (Studio-only JSON on the run, at most 200; counts exact) carry stable codes:

Every built-in run also records counts.steps and counts.statements (its budget use). A step that reads visitor text or a fetched document returns taint; the running run is marked at once. RunDueDeps.notify (ScheduleNotifier) receives automation-findings, automation-digest, automation-failed and automation-paused after the run's end is committed; Studio's notifications are derived from the run rows by @cloudhal/api. A person's "Run now" is SqlScheduleStore.startBuiltinNow: a manual run for this minute that the next tick steps, after which the automation returns to its schedule. Nothing seeds automations: people create them in Studio (D7).

Statements per path (counted by TickMeter, Workers Free budget 40):