@connextar/house 0.10.0 → 0.12.0

package/README.md

@@ -60,6 +60,18 @@ is one right answer to that — which is exactly the shape of thing that belongs
 here and nowhere else. The module is the union of the five, not a copy of the
 best one.
 
+`jobs`, in 0.11.0, is the same case with two copies. AltEd and Quickie grew
+their scheduled jobs from one seed and each proved something the other lacked —
+AltEd a switch with a name and a date against it, Quickie a Run now fenced to the
+caller's own organisation — and both printed a job's result as its variable
+names, so production read "0 chargesRaised · 0 totalOutstanding", with an amount
+of money shown as a number of things. The module is their union, with that
+made impossible rather than fixed: a count reaches the screen only through a
+declaration that says its words and its kind. 0.12.0 lets a job offer Run now
+to owners and operators both — Quickie's operators could not re-run a failed
+overnight sweep of a per-organisation job — and prunes the ledger without ever
+deleting a row health is read from.
+
 ## Modules
 
 ### `@connextar/house/errors`
@@ -730,6 +742,584 @@ app that imports `/ai` needs them; `/ai/config` needs none. The SDKs refuse to r
 environment, so a Vitest suite that calls the harness needs
 `// @vitest-environment node` on the file.
 
+### `@connextar/house/jobs`, `/jobs/react`
+
+Scheduled jobs: declared once, run once per window, switched off and on by
+name, and honest about their health. `/jobs` is server code — the registry, the
+dispatcher, Run now, the switch, health, the words for counts and the tick
+route's secret check. `/jobs/react` is the health screen's list, and re-exports
+the wording and types a client component needs, so nothing in the browser ever
+imports `/jobs` (which reaches `node:crypto`; `src/jobs/entry-points.test.ts`
+holds both sides of that line against the built output).
+
+AltEd and Quickie each had this, from one seed. What each proved, and what each
+got wrong:
+
+| Concern                 | AltEd                                                                                        | Quickie                                                                                             | Here                                                                                                    |
+| ----------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Registry                | `JobSpec`: name, label, `when` in words, scope, `maxAgeMs`, `attempt` + `windowKey`, `run`   | The same, without `when`                                                                            | `defineJob`: id, label, cadence, one `window`, threshold, timeout, switchable, Run now rule, counts     |
+| Window and idempotency  | Unique `(job, windowKey)` claim; tracker keyed on the UK date after a twice-sent day         | The same claim; hour, day, six-hour and month keys                                                  | The same claim, one function instead of two; calendar helpers take a time zone and keep both apps' keys |
+| Missed window           | Weekly digest only on Monday — a failed Monday loses the week                                | Monthly report only on the 1st — a failed 1st loses the month                                       | `weekly` and `monthly` stay open (after `from` each day) until the period ends                          |
+| One job failing         | Isolated — but a failed claim or ledger write threw out of the loop                          | The same                                                                                            | Isolated, store failures included; each job's result says what happened                                 |
+| Ledger                  | `CronRun`: job, window, start, finish, ok, counts, error                                     | Identical table                                                                                     | The same eight columns plus `tenant_id` and `triggered_by`; the app owns it behind `JobStore`           |
+| Health states           | Paused · Never run · Errored · Stale · Healthy                                               | Never run · Errored · Stale · Healthy                                                               | Paused · Never run · **Running** · Failed · Stale · Healthy — derived, never stored                     |
+| A run in progress       | Shown as **Errored** (`ok` is false until it finishes); one cut off stays so, with no reason | The same                                                                                            | Running inside its timeout; past it, Failed — "never finished, probably cut off"                        |
+| Staleness               | Last OK older than `maxAgeMs` (strictly)                                                     | The same — and a tenant's Run now reset it for everyone                                             | Last successful _whole_ run older than the threshold; healthy exactly at it                             |
+| Pause / resume          | Per job, who and when, audited; harvest's switch shared with its own screen                  | None                                                                                                | Per job, who and when; platform authority; audit in the adapter's transaction; tick says it skipped     |
+| Run now                 | `runJobNow` exists but has no caller, and every job is `global`, so it would refuse them all | Owner-only, scoped to the caller's organisation; no cool-down, and `force` skips reminder throttles | `tenant`, `platform` or both; refused outside it, while paused, while running, in its cool-down         |
+| Jobs on their own clock | Harvest (10 min) and imports (1 min): switchable, but record no runs, so no health           | —                                                                                                   | `schedule: "own"` + `runOwn`: the switch and the ledger, with or without a window                       |
+| Errors                  | Message stored; shown to administrators                                                      | Message stored; shown to **every** organisation's owner, whoever's data it came from                | Message stored; a tenant viewer sees whether a sweep failed, not its words or its numbers               |
+| `CRON_SECRET`           | Bearer or `?secret=`; `timingSafeEqual` after a length check                                 | Bearer (prefix optional) or `?secret=`; SHA-256 digests; dev secret refused in production           | Bearer required; digests; dev secret refused; `?secret=` only when a route asks                         |
+| Counts                  | `Record<string, number>` printed as keys; `totalOutstanding` is pounds shown as a count      | The same, in the card and the Run now toast ("3 remindersSent")                                     | Declared: words (singular and plural) and a kind — count, money (currency and unit) or duration         |
+| Legacy routes           | —                                                                                            | Three per-job routes still live, bypassing the ledger; `?force=1` sweeps every tenant               | One tick route; nothing else runs a tick job                                                            |
+
+**Declaring the jobs** — once, beside the store adapter, server-only:
+
+```ts
+// lib/jobs/index.ts
+import "server-only";
+import { createScheduler, daily, defineJob, defineJobs, hourly } from "@connextar/house/jobs";
+
+import { jobStore } from "./store";
+
+const HOUR = 60 * 60 * 1000;
+
+export const jobs = defineJobs([
+  defineJob({
+    id: "billing-housekeeping", // stored: never rename one
+    label: "Billing & payment reminders",
+    cadence: "Daily",
+    window: daily(),
+    staleAfterMs: 26 * HOUR,
+    counts: {
+      chargesRaised: { label: { one: "charge raised", other: "charges raised" } },
+      sent: { label: { one: "family reminded", other: "families reminded" } },
+      skipped: { label: "already reminded this week" },
+      totalOutstanding: { label: "outstanding", kind: "money", currency: "GBP", unit: "major" },
+    },
+    run: async ({ now }) => {
+      const { charged } = await rollUpCharges(now);
+      return { chargesRaised: charged, ...(await sendPaymentReminders(now)) };
+    },
+  }),
+  defineJob({
+    id: "payment-reminders",
+    label: "Payment reminders",
+    cadence: "Daily, from 09:00",
+    window: daily({ from: 9 }),
+    staleAfterMs: 26 * HOUR,
+    // An owner sweeps their own organisation, and nobody else's; an operator re-runs the sweep over all of them.
+    // One scope — `{ scope: "tenant" }` — is declared as before.
+    runNow: { scope: ["tenant", "platform"] },
+    counts: { remindersSent: { label: { one: "reminder sent", other: "reminders sent" } } },
+    // `tenantId` is null for the schedule's sweep and a platform Run now, and always set for an owner's.
+    run: async ({ now, tenantId }) => {
+      const { remindersSent } = await sendPaymentReminders(now, { organizationId: tenantId ?? undefined });
+      return { remindersSent };
+    },
+  }),
+  defineJob({
+    id: "harvest",
+    label: "Harvest",
+    cadence: "Every 10 minutes",
+    schedule: "own", // its own route and clock; the tick never runs it
+    staleAfterMs: HOUR,
+    counts: { sites: { label: { one: "site read", other: "sites read" } } },
+    run: async () => ({ sites: (await runHarvest({ budgetMs: 150_000, maxSites: 4 })).sites.length }),
+  }),
+]);
+
+export const scheduler = createScheduler({ jobs, store: jobStore });
+```
+
+`defineJobs` checks the list when the module loads and throws every problem at
+once (`jobDefinitionProblems` returns them as sentences, for a test). `defineJob`
+holds `run` to its counts at compile time: every declared count must be
+reported, and nothing undeclared may be. At run time an undeclared key is dropped
+before it is stored, and one in an old row is not shown — there is no fallback
+that could print a variable name.
+
+**The routes** — each app answers in its own envelope; the module returns
+decisions, not `Response`s:
+
+```ts
+// app/api/cron/tick/route.ts — the one entry in vercel.json's crons
+export async function GET(request: Request) {
+  const auth = checkCronRequest(request, { publicSecrets: ["dev-cron-secret"] });
+  if (!auth.ok) return apiError(auth.message, auth.status);
+  const results = await scheduler.tick();
+  return apiSuccess({ results }, summariseTick(results)); // "2 ran, 1 failed, 1 paused, 5 not due"
+}
+
+// app/api/cron/harvest/route.ts — a job on its own clock
+const result = await scheduler.runOwn("harvest");
+
+// app/api/cron/run/route.ts — Run now, behind the session
+const outcome = await scheduler.runNow(body.job, {
+  actor: { id: user.id, name: user.name },
+  platform: user.platformAdmin,
+  tenantId: user.organizationId,
+  scope: body.scope, // the button pressed, on a job that offers both; optional
+});
+if (outcome.status === "refused") return apiError(outcome.message, refusalStatus(outcome.reason));
+if (outcome.status === "failed") return apiError(outcome.message, 500);
+return apiSuccess(outcome, outcome.message); // "Ran Payment reminders — 3 reminders sent."
+
+// app/api/admin/cron/route.ts — the switch
+const outcome = await scheduler.setPaused(body.job, body.action === "pause", {
+  actor: { id: admin.id, name: admin.name },
+  platform: true,
+});
+if (outcome.status === "refused") return apiError(outcome.message, refusalStatus(outcome.reason));
+return apiSuccess(outcome, outcome.message);
+```
+
+**The screen** — the server works out the view for whoever is looking; the list
+draws it inside the app's own card:
+
+```tsx
+// app/dashboard/settings/page.tsx (server)
+const jobs = await scheduler.views({ platform: isAdmin, tenantId: user.organizationId });
+
+// components/settings/automation-card.tsx
+("use client");
+import { JobHealthList } from "@connextar/house/jobs/react";
+
+<JobHealthList
+  jobs={jobs}
+  onSwitch={async (job, on) => {
+    await commitApi("/api/admin/cron", { job, action: on ? "resume" : "pause" });
+  }}
+  onRunNow={(job, scope) => commitApi("/api/cron/run", { job, scope })}
+  runNowWords={{ tenant: "your organisation", platform: "every organisation" }}
+  onSettled={router.refresh}
+  extra={(job) => (job.id === "harvest" ? <Link href={routes.harvest}>What it searches next</Link> : null)}
+/>;
+```
+
+`onSwitch` and `onRunNow` throw to refuse — the ux layer's one failure
+contract. The switch is `useOptimisticValue`: it moves on the click, the badge
+moves with it (to the job's health as if on, which the view carries), and a
+refusal puts both back and reports the reason through the
+`ActionFeedbackProvider`. No other row is disabled while one saves. Run now is
+`useKeyedAction`: that row's button is busy (`data-busy`), the route's message is
+said, and the screen refreshes whether the run worked or not, since a failure is
+on the ledger too. A row draws one button per scope the view offers
+(`runNowScopes`) and hands `onRunNow` the one pressed; nearly every viewer holds
+one — an operator the platform run, an owner their own — and sees "Run now". A
+viewer who holds both sees two, "Run for every account" and "Run for your
+account", in the app's words through `runNowWords`. Dates are drawn in
+`timeZone` (default `Europe/London`), never the runtime's own — the server
+draws the list in UTC and the browser again in BST, and two times in one
+element is a hydration error. `classNames` replaces any part's look.
+
+The rules it keeps:
+
+- **One run per job per window.** The window is `(now) => key | null`; the
+  store's unique index on `(job, windowKey)` is the idempotency. A second tick
+  in the window finds the key taken and says `already-ran`. `hourly`,
+  `everyHours`, `daily`, `weekly` and `monthly` produce the keys both apps
+  already store, so moving onto them runs nothing twice.
+- **One failure stops nothing else.** A job that throws, a store that cannot
+  claim, a window function with a bug — each is that job's `failed` result and
+  its error on the ledger, and the next job runs. A run whose result could not
+  be written says so rather than calling the work failed.
+- **A paused job's tick skips it and says so** ("switched off by AltEd Admin on
+  29 Sept 2026; not started"). Its window is not claimed, so switched back on
+  inside the same window it still runs. If the switches cannot be read at all, no
+  switchable job starts: a switch nobody can read must not send a job out
+  spending. `pausedFromStored` reads a stored value AltEd's way — a row that
+  exists but does not parse is _paused_.
+- **Switching takes platform authority** — it stops a job for every tenant — and
+  records who and when. `JobStore.writeSwitch` is where the audit entry goes,
+  in the same transaction as the switch. A switch to where it already is writes
+  nothing.
+- **Health is derived, in this order:** paused · never run · running · failed ·
+  stale · healthy. A run past its timeout (default 15 minutes) and still
+  unfinished is failed, and says it never finished. Stale means no successful
+  run over every tenant for longer than the threshold — exactly at the threshold
+  is still healthy — and a job with `staleAfterMs: null` (one that runs only
+  when there is work) is never stale.
+- **Run now is scoped and fenced.** `tenant` sweeps the caller's own tenant and
+  needs one; `platform` sweeps everything and needs platform authority. It is
+  refused while the job is off, while a run it would overlap is in flight (the
+  schedule's sweep covers the caller's tenant too), and within its cool-down
+  (default ten minutes, per job and scope, and per tenant for tenant runs) — a
+  manual run sets `force`, so a second press would otherwise send the whole
+  batch again. `force` is for a job's hour gates; a per-recipient throttle
+  should stay on.
+- **A job may offer both** — `runNow: { scope: ["tenant", "platform"] }` —
+  and a single scope is declared as it always was. The caller's `scope` says
+  which was pressed; left out, it is the caller's tenant when they have one and
+  every tenant when they do not, and it never grants anything `platform` and
+  `tenantId` do not. The scopes are fenced from each other: separate
+  cool-downs, and neither starts while the other is in flight — a tenant run
+  waits for a platform run, and a platform run waits for any tenant's
+  (`JobStore.latestUnfinishedRun`, which `createScheduler` requires the moment
+  one job offers both). A platform Run now is a run over every tenant, so it
+  resets the job's health for everyone, as the schedule's does; a tenant's never
+  does. `outcome.scope` says which ran, for the app's audit entry.
+- **A tenant sees their own.** To a tenant viewer, a sweep over every tenant
+  shows whether it ran and when, but not its numbers (which are everyone's) or
+  its error (which may name another organisation's data). Their own Run now
+  shows in full. Other tenants' runs never appear, and none of them resets the
+  job's staleness.
+- **Every count is declared.** A label (the words after the number; singular and
+  plural where they differ) and a kind: `count`, `money` (a currency _and_ a
+  unit — `major` for AltEd's pounds, `minor` for pence — because a default would
+  be out by a hundred for one of them), or `duration`. Money is formatted by
+  `Intl` in its currency, which also rounds away a summed decimal's float noise.
+- **The tick's door** (`checkCronRequest`): an unset `CRON_SECRET` refuses with
+  503; the secret is compared as SHA-256 digests with `timingSafeEqual`; the
+  Bearer scheme is required; `publicSecrets` (the committed development value)
+  are refused in production; `?secret=` is accepted only with
+  `allowQuery: true`, because an address lands in request logs.
+
+**Storage.** The package owns no schema. The app implements `JobStore` — claim,
+finish, latest run, read switches, write a switch, and, since 0.12.0, the latest
+unfinished run over any tenant (for a job with both Run now scopes) and pruning
+— over its own tables. The two new methods are optional in the type, so an
+0.11.0 adapter still compiles; `createScheduler` and `pruneJobRuns` say by name
+what is missing when a feature needs one. This is
+the reference model; both apps' existing `cron_run` tables are it minus two
+nullable columns, so every row they hold maps across as it is:
+
+```prisma
+/// One row per job per window: the claim that makes a second tick skip, and the result.
+model CronRun {
+  id          String    @id @default(cuid())
+  job         String    @db.VarChar(60)
+  /// The window, e.g. "2026-09-30", or "manual:tenant:<id>:<time>" for a Run now.
+  windowKey   String    @map("window_key") @db.VarChar(120)
+  /// Null: a run over every tenant. Otherwise the one tenant a Run now swept.
+  tenantId    String?   @map("tenant_id") @db.VarChar(64)
+  /// Who pressed Run now, by name. Null for the schedule.
+  triggeredBy String?   @map("triggered_by") @db.VarChar(120)
+  startedAt   DateTime  @default(now()) @map("started_at")
+  finishedAt  DateTime? @map("finished_at")
+  ok          Boolean   @default(false)
+  /// The declared counts, e.g. { "remindersSent": 3 }.
+  counts      Json?
+  error       String?   @db.Text
+
+  @@unique([job, windowKey])
+  @@index([job, startedAt])
+  @@index([job, tenantId, startedAt])
+  @@map("cron_run")
+}
+
+/// A job switched off or on — the latest change. No row means on.
+model CronSwitch {
+  job            String   @id @db.VarChar(60)
+  paused         Boolean
+  switchedAt     DateTime @map("switched_at")
+  switchedById   String?  @map("switched_by_id")
+  switchedByName String   @map("switched_by_name") @db.VarChar(120)
+
+  @@map("cron_switch")
+}
+```
+
+For an app that already has `cron_run`:
+
+```sql
+ALTER TABLE "cron_run" ADD COLUMN "tenant_id" VARCHAR(64), ADD COLUMN "triggered_by" VARCHAR(120);
+CREATE INDEX "cron_run_job_tenant_id_started_at_idx" ON "cron_run"("job", "tenant_id", "started_at");
+```
+
+```ts
+// lib/jobs/store.ts
+import "server-only";
+import type { JobStore } from "@connextar/house/jobs";
+
+import { Prisma } from "@/lib/db/generated/client";
+import { prisma } from "@lib/db/prisma";
+
+export const jobStore: JobStore = {
+  async claimRun({ job, windowKey, tenantId, by, startedAt }) {
+    try {
+      const row = await prisma.cronRun.create({ data: { job, windowKey, tenantId, triggeredBy: by, startedAt } });
+      return row.id;
+    } catch (error) {
+      // The unique index refusing a second claim is the answer "already ran", not a failure.
+      if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002") return null;
+      throw error;
+    }
+  },
+  async finishRun(id, { finishedAt, ok, counts, error }) {
+    await prisma.cronRun.update({ where: { id }, data: { finishedAt, ok, error, ...(counts ? { counts } : {}) } });
+  },
+  async latestRun({ job, tenants, ok, manualOnly }) {
+    const row = await prisma.cronRun.findFirst({
+      where: {
+        job,
+        OR: tenants.map((tenantId) => ({ tenantId })), // `{ tenantId: null }` matches the whole-tenant runs
+        ...(ok ? { ok: true } : {}),
+        ...(manualOnly ? { windowKey: { startsWith: "manual:" } } : {}),
+      },
+      // `id` breaks a tie the way `pruneRuns` does, so the row read as latest is the row kept as latest.
+      orderBy: [{ startedAt: "desc" }, { id: "desc" }],
+    });
+    return row && { ...row, by: row.triggeredBy };
+  },
+  // Since 0.12.0 — needed once a job's Run now offers both scopes.
+  async latestUnfinishedRun(job) {
+    const row = await prisma.cronRun.findFirst({
+      where: { job, finishedAt: null }, // any tenant: a platform run must wait for every tenant's
+      orderBy: [{ startedAt: "desc" }, { id: "desc" }],
+    });
+    return row && { ...row, by: row.triggeredBy };
+  },
+  // Since 0.12.0 — `pruneJobRuns` calls it from the housekeeping job. One statement, at most `limit` rows, oldest
+  // first. `PARTITION BY` groups every NULL tenant together, which is exactly "the runs over every tenant".
+  async pruneRuns({ startedBefore, limit }) {
+    return prisma.$executeRaw`
+      DELETE FROM "cron_run" WHERE "id" IN (
+        SELECT "id" FROM (
+          SELECT "id", "ok", "started_at", "finished_at",
+            ROW_NUMBER() OVER (PARTITION BY "job", "tenant_id" ORDER BY "started_at" DESC, "id" DESC) AS "nth",
+            ROW_NUMBER() OVER (PARTITION BY "job", "tenant_id", "ok" ORDER BY "started_at" DESC, "id" DESC) AS "nth_of_kind"
+          FROM "cron_run"
+        ) AS "ranked"
+        WHERE "started_at" < ${startedBefore}
+          AND "finished_at" IS NOT NULL -- never a run still under way
+          AND "nth" > 1 -- never the latest run of a job for its tenant
+          AND NOT ("ok" AND "nth_of_kind" = 1) -- nor its latest success
+        ORDER BY "started_at", "id"
+        LIMIT ${limit}
+      )`;
+  },
+  async readSwitches() {
+    const rows = await prisma.cronSwitch.findMany();
+    return new Map(rows.map((r) => [r.job, { paused: r.paused, at: r.switchedAt, by: r.switchedByName }]));
+  },
+  async writeSwitch({ job, label, paused, at, by }) {
+    await prisma.$transaction([
+      prisma.cronSwitch.upsert({
+        where: { job },
+        create: { job, paused, switchedAt: at, switchedById: by.id, switchedByName: by.name },
+        update: { paused, switchedAt: at, switchedById: by.id, switchedByName: by.name },
+      }),
+      prisma.auditLog.create({
+        data: {
+          actorId: by.id,
+          actorName: by.name,
+          action: paused ? "cron.paused" : "cron.resumed",
+          entityType: "cron_job",
+          entityId: job,
+          summary: `${paused ? "Paused" : "Resumed"} ${label}`,
+        },
+      }),
+    ]);
+  },
+};
+```
+
+`createMemoryJobStore()` is the same contract in memory, unique index and
+pruning rules included, for the app's own tests of its binding.
+
+**Pruning the ledger.** Every tick and every own-clock call writes a row —
+AltEd about 150 a day — and a Run now row keeps the name of whoever pressed it.
+`pruneJobRuns(store, { now, retentionDays, batchLimit })` deletes the old ones
+through `JobStore.pruneRuns`, from the app's **own housekeeping job**, and
+reports what it removed as a declared count:
+
+```ts
+import { JOB_RUN_PRUNE_COUNTS, pruneJobRuns } from "@connextar/house/jobs";
+
+defineJob({
+  id: "rate-limit-prune",
+  label: "Housekeeping",
+  // …
+  counts: { windowsPruned: { label: "…" }, ...JOB_RUN_PRUNE_COUNTS }, // "12 old job runs removed"
+  run: async ({ now }) => ({ windowsPruned: await pruneRateLimits(), ...(await pruneJobRuns(jobStore, { now })) }),
+});
+```
+
+- **Retention** is 90 days by default, in days (at least 1), so a number cannot
+  be read as milliseconds and empty the ledger. A run exactly at the boundary is
+  kept.
+- **Always kept, however old:** per job, the latest run and the latest
+  successful run — once for the runs over every tenant (the schedule's and
+  platform Run nows), and once for each tenant's own. Health, the Last run and
+  Last success lines and an owner's own view are read from exactly these, so a
+  monthly job that last ran 120 days ago still says so rather than "Never run",
+  and a job whose last run failed still shows when it last worked.
+- **Never a run still under way** — an unfinished row is never deleted. (A run
+  cut off by the platform stays as the evidence; there are few.)
+- **Bounded:** at most `batchLimit` rows a call (default 1,000), oldest first, in
+  one statement, so a housekeeping run never holds the table. What is left goes
+  the next day; calling it again straight away deletes only that. A long
+  history is caught up a batch a day — or raise `batchLimit` for the first run.
+
+Choosing the retention: keep it longer than the longest window (a monthly job's
+33 days), so the ledger holds a whole period of every job to investigate; and
+where the privacy policy names a period for operator activity, use that — the
+`triggered_by` names are why it matters. The rows always kept outlive it, name
+included; a quiet job's single last run is the price of its health staying
+true.
+
+**What should not be a scheduled job.**
+
+- **Anything a person is waiting for.** A report they asked for, a model call,
+  an import step with its page open — do it in the request or straight after it.
+  A tick is up to an hour away, and a spinner cannot wait that long.
+- **A reaction to an event.** A payment landing, a sign-up, a status change:
+  handle it where it happens. A sweep that looks for "anything that changed" is
+  a webhook written late and paid for on every tick.
+- **A job per record, or per tenant.** A reminder due seven days after an
+  invoice is one daily sweep over "due today", not a job per invoice. The
+  registry is a short list a person reads on one screen.
+- **Anything that must happen at a moment.** Windows are as coarse as the tick —
+  AltEd's runs hourly, Quickie's every fifteen minutes. "At 09:00 sharp" is a
+  queue with a due time, not a window.
+- **Work longer than one request.** A job that can outlive the platform's time
+  limit is cut off and reads as never finished. Give it a budget and let the
+  next window continue — AltEd's harvest stops starting new sites after two and
+  a half minutes — or give it its own runner with `schedule: "own"`.
+- **Housekeeping a query already does.** An expired row the reads already ignore
+  does not need deleting on a schedule unless something promises it will be
+  gone — a retention period in a privacy policy does, and is then a job.
+
+**Adopting it — AltEd.** Nothing changes in what runs or when:
+
+1. **Jobs.** Each `JobSpec` becomes a `defineJob`: `name` → `id` (unchanged, so
+   the ledger and the `cron:<name>` switches still match), `when` → `cadence`,
+   `maxAgeMs` → `staleAfterMs`, `attempt` + `windowKey` → one `window` with the
+   same key: `daily()` for billing and housekeeping (the UTC date),
+   `daily({ timeZone: "Europe/London" })` for the tracker and class sessions
+   (`todayKey`), `daily({ from: 7, timeZone: "Europe/London" })` for the admin
+   summary (its London date equals the UTC date from 07:00). The hourly
+   moderation sweep's key is `2026-09-30-14` where `hourly()` gives
+   `2026-09-30T14` — keep a one-line custom window, or accept one extra sweep in
+   the cutover hour (it re-reads flagged messages, which is harmless). The weekly
+   digest keeps ``(now) => (isMondayMorning(now) ? `digest-${todayKey(now)}` : null)``,
+   or moves to `weekly({ from: 7, timeZone: "Europe/London" })` — which also
+   catches up a missed Monday — cut over on any day but a Monday.
+2. **Counts.** Declare every key each job already returns, under the same name,
+   so every stored row reads: `totalOutstanding` as
+   `{ kind: "money", currency: "GBP", unit: "major" }` (it is pounds, summed from
+   the decimal column), the rest as counts with their words.
+3. **Run now.** `scope: "global"` becomes `runNow: false` — what it effectively
+   was, since `runJobNow` never had a caller. Where an administrator should be
+   able to run one (the admin summary, class sessions, the tracker), give it
+   `runNow: { scope: "platform" }` and add the run route; leave billing
+   scheduled-only.
+4. **Own schedules.** The harvest and the import runner become
+   `schedule: "own"` and their routes call `scheduler.runOwn(...)` after the
+   secret check — so both write runs and get health for the first time. The
+   harvest takes `staleAfterMs: HOUR`; imports take `null` (idle is not stale),
+   keep their cached nothing-to-do answer ahead of `runOwn`, and drop their own
+   `isJobPaused("imports")`.
+5. **Switches.** Keep `PlatformSetting`: `readSwitches` merges
+   `readJobSettings()` with `readHarvestSetting()` under `harvest`, exactly as
+   `jobSwitches()` does now, and `writeSwitch` calls
+   `writeHarvestSetting`/`writeJobSetting` and `recordJobSwitched`. The
+   round-23 rule is `pausedFromStored`.
+6. **Ledger.** Run the two-column SQL above. No backfill: there are no Run now
+   rows, because nothing ever called it
+   (`SELECT count(*) FROM cron_run WHERE window_key LIKE 'manual:%'` should say
+   0 before and after).
+7. **Routes and screen.** The tick, harvest and imports routes use
+   `checkCronRequest` — `?secret=` now needs `allowQuery: true`, and Vercel's
+   cron never sends it. `/api/admin/cron` calls `setPaused`. `AutomationCard`
+   keeps its card and description and renders `JobHealthList` with
+   `scheduler.views({ platform: true })`, the harvest link as `extra`.
+   `lib/repos/cron.repo.ts`, `lib/server/cron-auth.ts` and the dispatcher half of
+   `lib/services/cron.service.ts` go; `cron-switch.db.test.ts` stays as the test
+   of the binding.
+
+**Adopting it — Quickie.**
+
+1. **Jobs.** Every key it stores is one a helper makes, so the cutover runs
+   nothing twice: `hourly()` for the follow-up digest and review requests;
+   `daily({ from: 9 })`, `daily({ from: 17 })` and `daily({ from: 18 })` for
+   payment reminders, booking reminders and budget alerts; `daily()` for bank
+   consents and housekeeping; `everyHours(6)` for the bank feed;
+   `(now) => (now.getUTCDay() === 1 ? hourly()(now) : null)` for the finance
+   digest; `monthly()` for the monthly report, which now catches up a failed 1st
+   on the 2nd. `scope: "tenant"` → `runNow: { scope: "tenant" }`; housekeeping
+   → `runNow: false`.
+2. **Counts.** Declare each key (`orgsEmailed`, `emailsSent`,
+   `invoicesConsidered`, `remindersSent`, …) with its words; the Run now toast
+   and the guide stop saying "3 remindersSent".
+3. **Ledger.** Run the two-column SQL, then give the old Run now rows a tenant:
+   `UPDATE "cron_run" SET "tenant_id" = 'unrecorded' WHERE "window_key" LIKE 'manual:%';`
+   Every one was a single organisation's run, but which was never recorded.
+   Marked so, none of them counts as a whole run for staleness and none appears
+   on any owner's screen; nothing is deleted.
+4. **Switches.** Add `CronSwitch`, and write the audit entry in `writeSwitch`
+   with `organizationId: null` — a switch is a platform-level action, which
+   `AuditLog` already allows. The switch belongs to platform operators
+   (`User.platformAdmin`): an Automation page in the admin panel renders
+   `scheduler.views({ platform: true })` with `onSwitch`.
+5. **Owners.** Settings › Automation health renders
+   `scheduler.views({ platform: false, tenantId: user.organizationId })` with
+   `onRunNow` and no switch. `/api/cron/run` keeps its owner check and the bank
+   feed's rate limit, then calls `runNow` with `platform: false` and the
+   organisation. Owners now see their own runs in full and the platform's sweeps
+   without other organisations' numbers or errors.
+6. **Remove the three per-job routes** (`payment-reminders`, `finance-digest`,
+   `follow-up-digest`). Nothing schedules them, and anyone holding the secret
+   could run a sweep outside the ledger and its window — `?force=1` over every
+   organisation, ignoring the hour and the throttle.
+7. **The tick** calls `checkCronRequest(request, { publicSecrets: ["dev-cron-secret"] })`
+   and `scheduler.tick()`. Payment reminders' Run now should stop passing
+   `ignoreThrottle` — the cool-down stops a double press, but a throttle per
+   invoice is what stops a customer being chased twice in a day.
+8. **The guide** (`docs/guides/automation.md`): Errored is now Failed, a run in
+   progress says Running, and the counts read as words.
+
+**Upgrading to 0.12.0 — both Run now scopes, and pruning.** A job declared
+with one scope behaves exactly as in 0.11.0, and an 0.11.0 adapter compiles
+unchanged. Each app then adds pruning to its housekeeping, and Quickie makes
+its per-organisation jobs that are safe to re-sweep dual.
+
+- **AltEd** — no dual jobs: it is single-tenant, and every job that offers Run
+  now already sweeps everything (`platform`). In `lib/jobs/store.ts` add
+  `pruneRuns` from the adapter above (`latestUnfinishedRun` is not needed
+  until a job offers both), and add `{ id: "desc" }` to `latestRun`'s
+  `orderBy`. In `lib/jobs/index.ts`, Housekeeping (`rate-limit-prune`) takes
+  `...JOB_RUN_PRUNE_COUNTS` in its counts and
+  `...(await pruneJobRuns(jobStore, { now }))` in its result. The harvest's
+  144 rows a day are most of the ledger; whatever history has built up beyond
+  90 days is caught up at a thousand rows a day. Test the SQL in
+  `store.db.test.ts` with runs dated before 2000 under the test's own job ids
+  and `startedBefore` in 2000, so no real row is old enough to go.
+- **Quickie** — make these dual, `runNow: { scope: ["tenant", "platform"] }`,
+  because a second sweep sends nobody anything twice: **payment reminders**
+  (the per-invoice throttle, which Run now does not lift), **booking
+  reminders** (a booking's `REMINDER` message), **review requests** (`PENDING`
+  becomes `SENT`), **bank consent check** (`expiryNoticeAt`) and **budget
+  alerts** (`BudgetAlert`, one per budget, category and month). Keep these
+  tenant-only: the **follow-up** and **weekly finance digests** —
+  `ignoreHour: force` would email every opted-in organisation at once, and
+  nothing stops a second digest the same day; the **monthly report** — nothing
+  records that an organisation's report went, so re-running a sweep that failed
+  half-way emails the first half again (make it dual once it does); and the
+  **bank feed sync** — `force` lifts each connection's six-hour hold, so a
+  platform run would call every bank for every organisation, and the next
+  window recovers anyway (if it is ever made dual, pass
+  `force && tenantId !== null`). In `lib/repos/cron.repo.ts` add
+  `latestUnfinishedRun` — `createScheduler` refuses a dual job without it — and
+  `pruneRuns`. No route changes: `/api/admin/cron` already calls `runNow` with
+  `platform: true, tenantId: null`, which on a dual job is the platform run,
+  and `/api/cron/run` with `platform: false` and the organisation, which is the
+  tenant run; the admin panel now shows Run now on the dual jobs, and owners see
+  what they saw. Reword the admin route's and panel's "only for the jobs that
+  sweep shared tables", and the automation guide, to say an operator can re-run
+  a failed sweep. Housekeeping (`rate-limit-prune`, `lib/services/cron.service.ts`)
+  prunes through `cronJobStore`. The old `unrecorded` Run now rows age out like
+  any tenant's, the latest per job kept; no screen reads them.
+- **senco** — no dual jobs: retention and housekeeping are sweeps over every
+  school, and a school's Run now is refused on purpose (`lib/jobs/index.ts`).
+  In `lib/jobs/store.ts` add `pruneRuns` and `{ id: "desc" }` in `latestRun`'s
+  `orderBy`; Housekeeping (`rate-limit-prune`, `lib/jobs/index.ts`) takes the
+  counts and `pruneJobRuns(jobStore, { now })`. `CronSwitchChange` is the
+  switches' audit record, not ledger, and is not pruned. Retention enforcement
+  is a promise to schools about how long evidence is kept; say the ledger's 90
+  days in the same place.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's