@frockbot/plugin-routines 0.0.0 → 0.1.0

package/src/cron.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isRoutineTimezoneV1,
+  missedRoutineRunsV1,
+  nextRoutineRunV1,
+  normalizeRoutineScheduleV1,
+  RoutineScheduleError,
+} from "./cron.js";
+
+describe("normalizeRoutineScheduleV1", () => {
+  test("accepts a five-field cron expression in the record's zone", () => {
+    expect(
+      normalizeRoutineScheduleV1("0 9 * * 1-5", "Australia/Sydney"),
+    ).toEqual({
+      kind: "cron",
+      pattern: "0 9 * * 1-5",
+      timezone: "Australia/Sydney",
+    });
+  });
+
+  test("expands every shorthand alias to five fields", () => {
+    const cases: Array<[string, string]> = [
+      ["@hourly", "0 * * * *"],
+      ["@daily", "0 0 * * *"],
+      ["@weekly", "0 0 * * 0"],
+      ["@monthly", "0 0 1 * *"],
+    ];
+    for (const [alias, pattern] of cases) {
+      expect(normalizeRoutineScheduleV1(alias, "UTC")).toEqual({
+        kind: "cron",
+        pattern,
+        timezone: "UTC",
+      });
+    }
+  });
+
+  test("reads a CRON_TZ= prefix as the schedule's own zone", () => {
+    expect(
+      normalizeRoutineScheduleV1("CRON_TZ=Europe/Berlin 30 6 * * *", "UTC"),
+    ).toEqual({
+      kind: "cron",
+      pattern: "30 6 * * *",
+      timezone: "Europe/Berlin",
+    });
+  });
+
+  test("parses @every as a fixed interval", () => {
+    expect(normalizeRoutineScheduleV1("@every 15m", "UTC")).toEqual({
+      kind: "interval",
+      intervalMs: 900_000,
+      timezone: "UTC",
+    });
+    expect(
+      (
+        normalizeRoutineScheduleV1("@every 2h30m", "UTC") as {
+          intervalMs: number;
+        }
+      ).intervalMs,
+    ).toBe(9_000_000);
+  });
+
+  test("refuses a malformed cron expression", () => {
+    for (const bad of ["not a cron", "0 9 * *", "99 * * * *", "0 9 * * * *"]) {
+      expect(() => normalizeRoutineScheduleV1(bad, "UTC")).toThrow(
+        RoutineScheduleError,
+      );
+    }
+  });
+
+  test("refuses an unknown alias and an unusable @every", () => {
+    expect(() => normalizeRoutineScheduleV1("@fortnightly", "UTC")).toThrow(
+      /not a known schedule alias/,
+    );
+    expect(() => normalizeRoutineScheduleV1("@every", "UTC")).toThrow(
+      /needs a duration/,
+    );
+    expect(() => normalizeRoutineScheduleV1("@every 5s", "UTC")).toThrow(
+      /at least one minute/,
+    );
+    expect(() => normalizeRoutineScheduleV1("@every 400d", "UTC")).toThrow(
+      /at most one year/,
+    );
+  });
+
+  test("refuses a time zone this runtime cannot format in", () => {
+    expect(() => normalizeRoutineScheduleV1("@daily", "Mars/Olympus")).toThrow(
+      /not an IANA time zone/,
+    );
+    expect(() =>
+      normalizeRoutineScheduleV1("CRON_TZ=Mars/Olympus @daily", "UTC"),
+    ).toThrow(/CRON_TZ/);
+  });
+
+  test("refuses an empty or oversized schedule", () => {
+    expect(() => normalizeRoutineScheduleV1("   ", "UTC")).toThrow(
+      /must not be empty/,
+    );
+    expect(() => normalizeRoutineScheduleV1("0 ".repeat(200), "UTC")).toThrow(
+      /at most 256 characters/,
+    );
+  });
+});
+
+describe("isRoutineTimezoneV1", () => {
+  test("accepts IANA names and refuses anything else", () => {
+    expect(isRoutineTimezoneV1("Australia/Sydney")).toBe(true);
+    expect(isRoutineTimezoneV1("UTC")).toBe(true);
+    expect(isRoutineTimezoneV1("")).toBe(false);
+    expect(isRoutineTimezoneV1("Not/AZone")).toBe(false);
+    expect(isRoutineTimezoneV1(7)).toBe(false);
+  });
+});
+
+describe("nextRoutineRunV1", () => {
+  const anchor = new Date("2026-01-01T00:00:00.000Z");
+
+  function next(schedule: string, timezone: string, from: string): string {
+    const run = nextRoutineRunV1(
+      normalizeRoutineScheduleV1(schedule, timezone),
+      new Date(from),
+      anchor,
+    );
+    if (!run) throw new Error("expected a next run");
+    return run.toISOString();
+  }
+
+  test("keeps a wall-clock time across the end of Sydney daylight saving", () => {
+    // Sydney leaves AEDT (UTC+11) for AEST (UTC+10) at 03:00 on 5 April 2026.
+    // 09:00 local is 22:00Z the day before while AEDT holds, and 23:00Z after.
+    expect(next("0 9 * * *", "Australia/Sydney", "2026-04-02T12:00:00Z")).toBe(
+      "2026-04-02T22:00:00.000Z",
+    );
+    expect(next("0 9 * * *", "Australia/Sydney", "2026-04-04T12:00:00Z")).toBe(
+      "2026-04-04T23:00:00.000Z",
+    );
+  });
+
+  test("keeps a wall-clock time across the start of New York daylight saving", () => {
+    // New York enters EDT at 02:00 on 8 March 2026: 09:00 local moves from
+    // 14:00Z to 13:00Z, and the schedule does not drift with it.
+    expect(next("0 9 * * *", "America/New_York", "2026-03-06T20:00:00Z")).toBe(
+      "2026-03-07T14:00:00.000Z",
+    );
+    expect(next("0 9 * * *", "America/New_York", "2026-03-08T00:00:00Z")).toBe(
+      "2026-03-08T13:00:00.000Z",
+    );
+  });
+
+  test("reads CRON_TZ= as the zone the pattern is evaluated in", () => {
+    // The record says UTC; the schedule the user typed overrides it. At
+    // 00:00Z it is already 10:00 in Sydney, so the next 09:00 there is the
+    // following morning — 23:00Z, not 09:00Z.
+    expect(
+      next("CRON_TZ=Australia/Sydney 0 9 * * *", "UTC", "2026-06-01T00:00:00Z"),
+    ).toBe("2026-06-01T23:00:00.000Z");
+    expect(next("0 9 * * *", "UTC", "2026-06-01T00:00:00Z")).toBe(
+      "2026-06-01T09:00:00.000Z",
+    );
+  });
+
+  test("fires @daily at local midnight", () => {
+    expect(next("@daily", "Australia/Sydney", "2026-06-01T00:00:00Z")).toBe(
+      "2026-06-01T14:00:00.000Z",
+    );
+  });
+
+  test("counts @every 5m forward from its anchor, not from the asking time", () => {
+    const normalized = normalizeRoutineScheduleV1("@every 5m", "UTC");
+    expect(
+      nextRoutineRunV1(
+        normalized,
+        new Date("2026-01-01T00:07:30.000Z"),
+        anchor,
+      )?.toISOString(),
+    ).toBe("2026-01-01T00:10:00.000Z");
+    expect(nextRoutineRunV1(normalized, anchor, anchor)?.toISOString()).toBe(
+      "2026-01-01T00:05:00.000Z",
+    );
+  });
+});
+
+describe("missedRoutineRunsV1", () => {
+  const anchor = new Date("2026-01-01T00:00:00.000Z");
+
+  test("counts the elapsed occurrences of a cron, the one firing included", () => {
+    expect(
+      missedRoutineRunsV1(
+        normalizeRoutineScheduleV1("0 * * * *", "UTC"),
+        new Date("2026-01-01T01:00:00Z"),
+        new Date("2026-01-01T04:30:00Z"),
+        anchor,
+      ),
+    ).toBe(4);
+  });
+
+  test("counts an interval schedule arithmetically", () => {
+    expect(
+      missedRoutineRunsV1(
+        normalizeRoutineScheduleV1("@every 5m", "UTC"),
+        new Date("2026-01-01T00:05:00Z"),
+        new Date("2026-01-01T00:32:00Z"),
+        anchor,
+      ),
+    ).toBe(6);
+  });
+
+  test("counts nothing when the occurrence has not arrived", () => {
+    expect(
+      missedRoutineRunsV1(
+        normalizeRoutineScheduleV1("@daily", "UTC"),
+        new Date("2026-01-02T00:00:00Z"),
+        new Date("2026-01-01T00:00:00Z"),
+        anchor,
+      ),
+    ).toBe(0);
+  });
+});

package/src/cron.ts

@@ -0,0 +1,246 @@
+// Schedules: the one place a Routine's `schedule` string is understood — both
+// the syntax a write must pass and the next firing the scheduler arms an alarm
+// on.
+//
+// "Timezone is validated
+// with `Intl.DateTimeFormat` at *write* time so a bad TZ is a rejected command,
+// not a dead alarm" — the same rule applies to the pattern itself: a Routine
+// whose schedule cannot be parsed is never written, so the scheduler can assume
+// every stored schedule is parseable.
+//
+// `croner` owns 5-field cron and IANA timezones. It does not understand
+// GrokBot's `CRON_TZ=` prefix, its `@shorthand` aliases, or `@every <duration>`,
+// so this module owns exactly that normalization and hands the rest over.
+import { Cron } from "croner";
+
+/** Longest schedule string a command may carry. */
+export const ROUTINE_SCHEDULE_MAX_LENGTH = 256;
+
+/** The shortest `@every` interval a Routine may ask for. */
+export const ROUTINE_MIN_INTERVAL_MS = 60_000;
+/** The longest `@every` interval a Routine may ask for: one year. */
+export const ROUTINE_MAX_INTERVAL_MS = 366 * 24 * 60 * 60 * 1000;
+
+/** A schedule after normalization: either a cron pattern or a fixed interval. */
+export type NormalizedScheduleV1 =
+  | { kind: "cron"; pattern: string; timezone: string }
+  | { kind: "interval"; intervalMs: number; timezone: string };
+
+export class RoutineScheduleError extends Error {
+  override readonly name = "RoutineScheduleError";
+}
+
+const CRON_SHORTHANDS: Record<string, string> = {
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+  "@monthly": "0 0 1 * *",
+  "@weekly": "0 0 * * 0",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly": "0 * * * *",
+};
+
+const DURATION_UNITS_MS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/**
+ * True when the IANA name is one this runtime can actually format in. An
+ * unknown zone throws `RangeError` here rather than silently resolving to UTC
+ * later, which is the whole reason the check happens at write time.
+ */
+export function isRoutineTimezoneV1(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 64) {
+    return false;
+  }
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `@every 15m`, `@every 2h30m`, `@every 90s`. */
+function parseEveryDuration(rest: string): number {
+  const trimmed = rest.trim();
+  if (trimmed.length === 0) {
+    throw new RoutineScheduleError(
+      "@every needs a duration, such as @every 15m",
+    );
+  }
+  const parts = trimmed.match(/\d+[smhd]/g);
+  if (!parts || parts.join("") !== trimmed.replace(/\s+/g, "")) {
+    throw new RoutineScheduleError(
+      `"@every ${rest.trim()}" is not a duration; use units s, m, h or d, such as @every 15m`,
+    );
+  }
+  let total = 0;
+  for (const part of parts) {
+    const unit = part.slice(-1);
+    total += Number(part.slice(0, -1)) * DURATION_UNITS_MS[unit]!;
+  }
+  if (total < ROUTINE_MIN_INTERVAL_MS) {
+    throw new RoutineScheduleError("@every must be at least one minute apart");
+  }
+  if (total > ROUTINE_MAX_INTERVAL_MS) {
+    throw new RoutineScheduleError("@every must be at most one year apart");
+  }
+  return total;
+}
+
+/**
+ * Normalize and validate a schedule string against the Routine's timezone.
+ *
+ * A `CRON_TZ=` prefix wins over the record's `timezone`, matching GrokBot,
+ * because it is written into the schedule the user typed. Both are validated;
+ * neither is guessed.
+ */
+export function normalizeRoutineScheduleV1(
+  schedule: string,
+  timezone: string,
+): NormalizedScheduleV1 {
+  if (typeof schedule !== "string") {
+    throw new RoutineScheduleError("schedule must be a string");
+  }
+  const raw = schedule.trim();
+  if (raw.length === 0) {
+    throw new RoutineScheduleError("schedule must not be empty");
+  }
+  if (raw.length > ROUTINE_SCHEDULE_MAX_LENGTH) {
+    throw new RoutineScheduleError(
+      `schedule must be at most ${ROUTINE_SCHEDULE_MAX_LENGTH} characters`,
+    );
+  }
+  if (!isRoutineTimezoneV1(timezone)) {
+    throw new RoutineScheduleError(
+      `timezone "${timezone}" is not an IANA time zone`,
+    );
+  }
+  let body = raw;
+  let zone = timezone;
+  const prefix = /^CRON_TZ=(\S+)\s+(.*)$/.exec(body);
+  if (prefix) {
+    const declared = prefix[1]!;
+    if (!isRoutineTimezoneV1(declared)) {
+      throw new RoutineScheduleError(
+        `CRON_TZ="${declared}" is not an IANA time zone`,
+      );
+    }
+    zone = declared;
+    body = prefix[2]!.trim();
+  }
+  if (body.length === 0) {
+    throw new RoutineScheduleError("schedule must not be empty");
+  }
+  if (body.startsWith("@every")) {
+    const rest = body.slice("@every".length);
+    if (rest.length > 0 && !/^\s/.test(rest)) {
+      throw new RoutineScheduleError(`"${body}" is not a known schedule alias`);
+    }
+    return {
+      kind: "interval",
+      intervalMs: parseEveryDuration(rest),
+      timezone: zone,
+    };
+  }
+  if (body.startsWith("@")) {
+    const expanded = CRON_SHORTHANDS[body.toLowerCase()];
+    if (!expanded) {
+      throw new RoutineScheduleError(`"${body}" is not a known schedule alias`);
+    }
+    body = expanded;
+  }
+  const fields = body.split(/\s+/);
+  if (fields.length !== 5) {
+    throw new RoutineScheduleError(
+      `cron expression "${body}" must have five fields (minute hour day month weekday)`,
+    );
+  }
+  try {
+    // Constructing without a callback parses and validates; it schedules
+    // nothing. `stop` is called so no timer survives the check.
+    const parsed = new Cron(body, { timezone: zone, paused: true });
+    parsed.stop();
+  } catch (error) {
+    throw new RoutineScheduleError(
+      `cron expression "${body}" is invalid: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  return { kind: "cron", pattern: body, timezone: zone };
+}
+
+/** A one-line summary of a schedule for a list row. */
+export function describeRoutineScheduleV1(schedule: string): string {
+  return schedule.trim();
+}
+
+/**
+ * The first firing strictly after `from`, or `undefined` when the schedule has
+ * no further occurrence. D1 only parsed; this is the evaluation the scheduler
+ * rests on.
+ *
+ * An interval schedule (`@every 15m`) has no calendar to consult, so it counts
+ * forward from its own anchor: the moment the Routine's timing was last
+ * written. That keeps `@every 15m` fifteen minutes apart across a firing, an
+ * eviction and a redeploy, instead of drifting to whenever the object happened
+ * to wake.
+ */
+export function nextRoutineRunV1(
+  normalized: NormalizedScheduleV1,
+  from: Date,
+  anchor: Date,
+): Date | undefined {
+  if (normalized.kind === "interval") {
+    const elapsed = from.getTime() - anchor.getTime();
+    const periods =
+      elapsed < 0 ? 0 : Math.floor(elapsed / normalized.intervalMs) + 1;
+    return new Date(anchor.getTime() + periods * normalized.intervalMs);
+  }
+  const cron = new Cron(normalized.pattern, {
+    timezone: normalized.timezone,
+    paused: true,
+  });
+  try {
+    return cron.nextRun(from) ?? undefined;
+  } finally {
+    cron.stop();
+  }
+}
+
+/** Most missed occurrences one coalescing report counts before it gives up. */
+export const ROUTINE_MISSED_COUNT_CAP = 1_000;
+
+/**
+ * How many firings a Routine slept through: occurrences in `(due, now]`, the
+ * one about to fire included. Capped, because a Routine dormant for a year on
+ * `@every 5m` must not be counted one occurrence at a time.
+ */
+export function missedRoutineRunsV1(
+  normalized: NormalizedScheduleV1,
+  due: Date,
+  now: Date,
+  anchor: Date,
+): number {
+  if (now.getTime() < due.getTime()) return 0;
+  if (normalized.kind === "interval") {
+    return Math.min(
+      ROUTINE_MISSED_COUNT_CAP,
+      Math.floor((now.getTime() - due.getTime()) / normalized.intervalMs) + 1,
+    );
+  }
+  let counted = 1;
+  let cursor = due;
+  while (counted < ROUTINE_MISSED_COUNT_CAP) {
+    const next = nextRoutineRunV1(normalized, cursor, anchor);
+    if (!next || next.getTime() > now.getTime()) break;
+    cursor = next;
+    counted += 1;
+  }
+  return counted;
+}

package/src/env.d.ts

@@ -0,0 +1,6 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent;
+  export default component;
+}

package/src/firing.ts

@@ -0,0 +1,222 @@
+// The durable records the scheduler owns: when a Routine is next due, and the
+// one firing of it that has not settled yet.
+//
+// Two records, two jobs.
+//
+//   * `RoutineScheduleStateV1` is the Routine's clock. `dueAt` is the debt: the
+//     moment the Routine was owed a firing, and it moves only when a firing is
+//     minted for it. `deferredUntil` is a hold, set when the object is busy, and
+//     it never moves `dueAt` — pushing `dueAt` forward would silently skip a
+//     firing, which is the one thing a scheduler must not do. `anchor` records
+//     the record revision the clock was computed under, so editing a Routine's
+//     schedule recomputes it instead of inheriting a due time from the old one.
+//
+//   * `RoutineFireV1` is one firing, written durably *before* the Turn it
+//     admits. It doubles as the same-Routine lock: at most one exists per
+//     Routine, and a firing that arrives while one is unsettled queues behind
+//     it. "Record durable execution intent before invoking an external side
+//     effect", and "retries reuse the fire id as the run id".
+import {
+  isRoutineIdV1,
+  RoutineDecodeError,
+  routineExactKeys,
+  routineText,
+  routineTimestamp,
+  ROUTINE_TRIGGER_KINDS,
+  type RoutineTriggerKindV1,
+} from "./records.js";
+
+/** A Routine's durable clock. Absent means "compute it from the record". */
+export interface RoutineScheduleStateV1 {
+  schemaVersion: 1;
+  routineId: string;
+  /** The record revision this clock was computed under: the record's `updatedAt`. */
+  anchor: string;
+  /** Epoch milliseconds the Routine is next owed a firing. */
+  dueAt: number;
+  /** Epoch milliseconds before which the alarm must not settle this Routine. */
+  deferredUntil?: number;
+}
+
+/** One firing, durable before the Turn it admits. The same-Routine lock. */
+export interface RoutineFireV1 {
+  schemaVersion: 1;
+  routineId: string;
+  /** The run id the Turn is admitted under; a retry reuses it. */
+  fireId: string;
+  trigger: RoutineTriggerKindV1;
+  /** The cue text the Turn is admitted with. */
+  cue: string;
+  /** When the firing was minted. */
+  mintedAt: string;
+  /** The occurrence this firing settles, for a scheduled Routine. */
+  dueAt?: number;
+  /** How many occurrences this firing coalesces, when it fired late. */
+  missedCount?: number;
+  /** The run-log entry this firing writes and later rewrites. */
+  entryId: string;
+}
+
+/**
+ * Longest cue a firing may carry. A Routine prompt is capped at 8 000
+ * characters and a webhook rendering at 4 KiB; this leaves room for both and
+ * the framing between them.
+ */
+export const ROUTINE_CUE_MAX_LENGTH = 16_000;
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new RoutineDecodeError(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function epoch(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new RoutineDecodeError(`${label} must be epoch milliseconds`);
+  }
+  return value as number;
+}
+
+function count(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new RoutineDecodeError(`${label} must be a non-negative integer`);
+  }
+  return value as number;
+}
+
+export function decodeRoutineScheduleStateV1(
+  value: unknown,
+): RoutineScheduleStateV1 {
+  const candidate = record(value, "Routine schedule state");
+  routineExactKeys(
+    candidate,
+    ["schemaVersion", "routineId", "anchor", "dueAt"],
+    ["deferredUntil"],
+    "Routine schedule state",
+  );
+  if (candidate.schemaVersion !== 1) {
+    throw new RoutineDecodeError(
+      "Routine schedule state schemaVersion is unsupported",
+    );
+  }
+  if (!isRoutineIdV1(candidate.routineId)) {
+    throw new RoutineDecodeError("Routine schedule state routineId is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    routineId: candidate.routineId,
+    anchor: routineTimestamp(candidate.anchor, "Routine schedule state anchor"),
+    dueAt: epoch(candidate.dueAt, "Routine schedule state dueAt"),
+    ...(candidate.deferredUntil === undefined
+      ? {}
+      : {
+          deferredUntil: epoch(
+            candidate.deferredUntil,
+            "Routine schedule state deferredUntil",
+          ),
+        }),
+  };
+}
+
+export function decodeRoutineFireV1(value: unknown): RoutineFireV1 {
+  const candidate = record(value, "Routine firing");
+  routineExactKeys(
+    candidate,
+    [
+      "schemaVersion",
+      "routineId",
+      "fireId",
+      "trigger",
+      "cue",
+      "mintedAt",
+      "entryId",
+    ],
+    ["dueAt", "missedCount"],
+    "Routine firing",
+  );
+  if (candidate.schemaVersion !== 1) {
+    throw new RoutineDecodeError("Routine firing schemaVersion is unsupported");
+  }
+  if (!isRoutineIdV1(candidate.routineId)) {
+    throw new RoutineDecodeError("Routine firing routineId is invalid");
+  }
+  const trigger = ROUTINE_TRIGGER_KINDS.find(
+    (known) => known === candidate.trigger,
+  );
+  if (!trigger) {
+    throw new RoutineDecodeError("Routine firing trigger is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    routineId: candidate.routineId,
+    fireId: routineText(candidate.fireId, 256, "Routine firing fireId"),
+    trigger,
+    cue: routineText(
+      candidate.cue,
+      ROUTINE_CUE_MAX_LENGTH,
+      "Routine firing cue",
+    ),
+    mintedAt: routineTimestamp(candidate.mintedAt, "Routine firing mintedAt"),
+    entryId: routineText(candidate.entryId, 128, "Routine firing entryId"),
+    ...(candidate.dueAt === undefined
+      ? {}
+      : { dueAt: epoch(candidate.dueAt, "Routine firing dueAt") }),
+    ...(candidate.missedCount === undefined
+      ? {}
+      : {
+          missedCount: count(
+            candidate.missedCount,
+            "Routine firing missedCount",
+          ),
+        }),
+  };
+}
+
+/** The Session a Routine's firings run in. One per Routine, never the User's. */
+export function routineSessionIdV1(routineId: string): string {
+  return `routine:${routineId}`;
+}
+
+/**
+ * The run id one firing is admitted under. It is derived, not random: a
+ * scheduled occurrence names its own due time and a delivered one names its
+ * delivery, so a retry after eviction reuses the id and the kernel's own
+ * fingerprint idempotency refuses the second admission rather than running the
+ * Routine twice.
+ */
+export function routineFireIdV1(
+  routineId: string,
+  discriminator: string,
+): string {
+  const sanitized = discriminator.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 80);
+  return `rf-${routineId}-${sanitized}`.slice(0, 250);
+}
+
+/**
+ * What the Turn is admitted with. A firing is not a message from a person, so
+ * the cue says what fired and why, and then hands over the Routine's own
+ * instruction verbatim.
+ */
+export function routineCueV1(input: {
+  name: string;
+  prompt: string;
+  trigger: RoutineTriggerKindV1;
+  missedCount?: number;
+  delivery?: string;
+}): string {
+  const lines = [
+    `Routine "${input.name}" fired (${input.trigger}).`,
+    ...(input.missedCount && input.missedCount > 1
+      ? [
+          `It was late: ${input.missedCount} scheduled occurrences elapsed and this firing covers all of them.`,
+        ]
+      : []),
+    "",
+    input.prompt,
+  ];
+  if (input.delivery !== undefined) {
+    lines.push("", "Delivered payload:", input.delivery);
+  }
+  return lines.join("\n").slice(0, ROUTINE_CUE_MAX_LENGTH);
+}