@company-semantics/contracts 99.0.0 → 99.2.0

package/src/schedules/api.ts

@@ -0,0 +1,139 @@
+/**
+ * Responses the backend's schedule routes publish.
+ *
+ * Response schemas only. Request bodies stay in the backend beside their routes
+ * (contracts CLAUDE.md "What Does NOT Belong"). Not yet bound to routes: the
+ * backend PRD that adds the routes registers them in CONTRACT_SURFACES.
+ *
+ * Claim (the `cs-schedule start` step, OIDC-authenticated):
+ * - `claimed`: this run holds the execution; it must carry `claimEpoch` into
+ *   every fenced write and into its finish call.
+ * - `legacy`: an `on.schedule` (or otherwise unregistered) run of a schedule
+ *   whose mode is not `live`. It may run, gets NO execution id and counts toward
+ *   no slot (migration admission).
+ * - `refused`: the run must skip its work (`run=false`). Reasons are closed.
+ */
+
+import { z } from "zod";
+import { SCHEDULE_CLOCK_SOURCES, SCHEDULE_EXECUTION_STATES } from "./execution";
+import { SCHEDULE_MODES } from "./definition";
+import type { ScheduleClockSource } from "./execution";
+
+/**
+ * The tick route. Both clock sources hit it: the edge Worker over HTTPS with the
+ * existing edge bearer (EDGE_AUTH_TOKEN on the edge, verified by the backend's
+ * verifyEdgeAuth), the job queue in-process. There is no separate clock token.
+ */
+export const SCHEDULE_TICK_PATH = "/api/schedules/tick";
+
+/**
+ * Tick request body, as a TYPE only: request schemas stay in the backend beside
+ * the route (contracts CLAUDE.md), which binds its zod schema to this type with
+ * `satisfies z.ZodType<ScheduleTickRequest>`. Edge and backend both read it.
+ * `scheduledFor` is the clock's own scheduled instant (ISO 8601, e.g. the
+ * Worker's ScheduledController.scheduledTime); `cron` is the trigger expression
+ * that fired (the Worker's controller.cron; the job queue sends its interval
+ * label). Neither is a schedule slot: the reconciler computes slots itself.
+ */
+export interface ScheduleTickRequest {
+  readonly source: ScheduleClockSource;
+  readonly scheduledFor: string;
+  readonly cron: string;
+}
+
+/**
+ * CloudWatch EMF metric names (backend emits; control's watchdog script alarms).
+ * `Tick` carries dimension `source` (one series per clock source); a series
+ * missing for its window is breaching. `ReconcileSuccess` is emitted once per
+ * reconcile that concluded with complete observations.
+ */
+export const SCHEDULE_METRICS_NAMESPACE = "Schedules";
+export const SCHEDULE_METRIC_TICK = "Tick";
+export const SCHEDULE_METRIC_TICK_SOURCE_DIMENSION = "source";
+/**
+ * Every Schedules metric carries this dimension (value: the backend deploy
+ * environment, e.g. "production" / "staging"), so a staging tick can never
+ * feed a production alarm series.
+ */
+export const SCHEDULE_METRIC_ENVIRONMENT_DIMENSION = "environment";
+export const SCHEDULE_METRIC_RECONCILE_SUCCESS = "ReconcileSuccess";
+
+export const SCHEDULE_CLAIM_REFUSALS = [
+  "already_completed",
+  "lease_held",
+  "legacy_run_not_admitted",
+  "not_dispatched",
+  "binding_mismatch",
+  "schedule_off",
+] as const;
+export type ScheduleClaimRefusal = (typeof SCHEDULE_CLAIM_REFUSALS)[number];
+
+export const ScheduleClaimResponseSchema = z.discriminatedUnion("outcome", [
+  z
+    .object({
+      outcome: z.literal("claimed"),
+      executionId: z.string(),
+      claimEpoch: z.number().int().min(1),
+      leaseUntil: z.iso.datetime(),
+      mode: z.enum(SCHEDULE_MODES),
+    })
+    .strict(),
+  z
+    .object({
+      outcome: z.literal("legacy"),
+      scheduleId: z.string(),
+      mode: z.enum(SCHEDULE_MODES),
+    })
+    .strict(),
+  z
+    .object({
+      outcome: z.literal("refused"),
+      reason: z.enum(SCHEDULE_CLAIM_REFUSALS),
+    })
+    .strict(),
+]);
+export type ScheduleClaimResponse = z.infer<typeof ScheduleClaimResponseSchema>;
+
+export const SCHEDULE_FINISH_REJECTIONS = [
+  "stale_epoch",
+  "binding_mismatch",
+  "unknown_execution",
+] as const;
+export type ScheduleFinishRejection =
+  (typeof SCHEDULE_FINISH_REJECTIONS)[number];
+
+export const ScheduleFinishResponseSchema = z.discriminatedUnion("recorded", [
+  z
+    .object({
+      recorded: z.literal(true),
+      executionId: z.string(),
+      state: z.enum(SCHEDULE_EXECUTION_STATES),
+    })
+    .strict(),
+  z
+    .object({
+      recorded: z.literal(false),
+      reason: z.enum(SCHEDULE_FINISH_REJECTIONS),
+    })
+    .strict(),
+]);
+export type ScheduleFinishResponse = z.infer<
+  typeof ScheduleFinishResponseSchema
+>;
+
+/** One tick's outcome, reported to the tick source that triggered it. */
+export const ScheduleTickResponseSchema = z
+  .object({
+    source: z.enum(SCHEDULE_CLOCK_SOURCES),
+    tickedAt: z.iso.datetime(),
+    reconcileOk: z.boolean(),
+    registryVersion: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/)
+      .nullable(),
+    dispatched: z.number().int().min(0),
+    incidentsOpened: z.number().int().min(0),
+    incidentsResolved: z.number().int().min(0),
+  })
+  .strict();
+export type ScheduleTickResponse = z.infer<typeof ScheduleTickResponseSchema>;

package/src/schedules/cron.ts

@@ -0,0 +1,268 @@
+/**
+ * Five-field UTC cron evaluator for the schedule registry.
+ *
+ * Pure: no clock reads, no I/O. Every function takes the instant it reasons
+ * about. Consumed by control (registry validation at generation time) and by
+ * the backend reconciler (slot computation), so both read one definition of
+ * "when is this schedule due" (contracts ADR slug schedule-execution-wire-types).
+ *
+ * Supported per field: `*`, `*\/n`, `n`, `a-b`, `a-b/n`, and comma lists of those.
+ * NOT supported (parse fails with a reason): names (JAN, MON), `L`, `W`, `#`, `?`,
+ * `@hourly`-style macros, and a step on a single value (`5/15`).
+ *
+ * Semantics:
+ * - All evaluation is in UTC. A slot is a whole-minute instant (seconds = 0).
+ * - Day-of-week 7 is Sunday, the same as 0.
+ * - Day matching follows Vixie cron: when BOTH day-of-month and day-of-week are
+ *   restricted (their field text does not start with `*`), a day matches if
+ *   EITHER matches; otherwise both must match. So `*\/2` in day-of-month counts
+ *   as unrestricted, exactly as in Vixie cron.
+ * - An expression that can never fire (e.g. `0 0 31 2 *`) fails to parse.
+ */
+
+export type CronField =
+  "minute" | "hour" | "dayOfMonth" | "month" | "dayOfWeek";
+
+export interface ParsedCron {
+  /** The expression with whitespace normalized to single spaces. */
+  readonly source: string;
+  /** Ascending, deduplicated. */
+  readonly minutes: readonly number[];
+  readonly hours: readonly number[];
+  readonly daysOfMonth: readonly number[];
+  readonly months: readonly number[];
+  /** 0..6, Sunday = 0 (7 is folded into 0). */
+  readonly daysOfWeek: readonly number[];
+  readonly dayOfMonthRestricted: boolean;
+  readonly dayOfWeekRestricted: boolean;
+}
+
+export type CronParseResult =
+  | { readonly ok: true; readonly cron: ParsedCron }
+  | {
+      readonly ok: false;
+      readonly field: CronField | "expression";
+      readonly reason: string;
+    };
+
+const FIELD_ORDER: readonly CronField[] = [
+  "minute",
+  "hour",
+  "dayOfMonth",
+  "month",
+  "dayOfWeek",
+];
+
+const FIELD_BOUNDS: Readonly<Record<CronField, readonly [number, number]>> = {
+  minute: [0, 59],
+  hour: [0, 23],
+  dayOfMonth: [1, 31],
+  month: [1, 12],
+  dayOfWeek: [0, 7],
+};
+
+const TERM = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/;
+const MINUTE_MS = 60_000;
+const DAY_MS = 86_400_000;
+/** Feb 29 schedules can skip a century year: 8 years bounds every satisfiable expression. */
+const MAX_SEARCH_DAYS = 366 * 8 + 1;
+/** Fixed reference instant for the "can this ever fire" check (keeps parse pure). */
+const SATISFIABILITY_REFERENCE = Date.UTC(2028, 0, 1);
+
+function parseField(
+  text: string,
+  field: CronField,
+): readonly number[] | string {
+  const [lo, hi] = FIELD_BOUNDS[field];
+  const values = new Set<number>();
+  for (const term of text.split(",")) {
+    const match = TERM.exec(term);
+    if (!match) return `unsupported term "${term}"`;
+    const base = match[1];
+    const stepText = match[2];
+    let start: number;
+    let end: number;
+    if (base === "*") {
+      start = lo;
+      end = hi;
+    } else if (base.includes("-")) {
+      const [a, b] = base.split("-").map(Number);
+      start = a;
+      end = b;
+    } else {
+      if (stepText !== undefined)
+        return `a step on a single value ("${term}") is unsupported`;
+      start = Number(base);
+      end = start;
+    }
+    if (start < lo || end > hi || start > end) {
+      return `"${term}" is outside ${lo}-${hi}`;
+    }
+    const step = stepText === undefined ? 1 : Number(stepText);
+    if (!Number.isInteger(step) || step < 1)
+      return `the step in "${term}" must be at least 1`;
+    for (let v = start; v <= end; v += step) {
+      values.add(field === "dayOfWeek" && v === 7 ? 0 : v);
+    }
+  }
+  return [...values].sort((a, b) => a - b);
+}
+
+function dayMatches(cron: ParsedCron, day: Date): boolean {
+  const domOk = cron.daysOfMonth.includes(day.getUTCDate());
+  const dowOk = cron.daysOfWeek.includes(day.getUTCDay());
+  if (cron.dayOfMonthRestricted && cron.dayOfWeekRestricted)
+    return domOk || dowOk;
+  return domOk && dowOk;
+}
+
+function dayEligible(cron: ParsedCron, dayStart: number): boolean {
+  const day = new Date(dayStart);
+  return cron.months.includes(day.getUTCMonth() + 1) && dayMatches(cron, day);
+}
+
+function utcDayStart(ms: number): number {
+  return Math.floor(ms / DAY_MS) * DAY_MS;
+}
+
+/** Parse a five-field UTC cron expression. Never throws. */
+export function parseCron(expression: string): CronParseResult {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return {
+      ok: false,
+      field: "expression",
+      reason: `expected 5 fields, got ${parts.length}`,
+    };
+  }
+  const fields: Partial<Record<CronField, readonly number[]>> = {};
+  for (let i = 0; i < FIELD_ORDER.length; i++) {
+    const field = FIELD_ORDER[i];
+    const parsed = parseField(parts[i], field);
+    if (typeof parsed === "string") return { ok: false, field, reason: parsed };
+    fields[field] = parsed;
+  }
+  const cron: ParsedCron = {
+    source: parts.join(" "),
+    minutes: fields.minute ?? [],
+    hours: fields.hour ?? [],
+    daysOfMonth: fields.dayOfMonth ?? [],
+    months: fields.month ?? [],
+    daysOfWeek: fields.dayOfWeek ?? [],
+    dayOfMonthRestricted: !parts[2].startsWith("*"),
+    dayOfWeekRestricted: !parts[4].startsWith("*"),
+  };
+  if (nextSlot(cron, new Date(SATISFIABILITY_REFERENCE)) === null) {
+    return {
+      ok: false,
+      field: "expression",
+      reason: "the expression can never fire",
+    };
+  }
+  return { ok: true, cron };
+}
+
+/** True when `instant` is exactly a slot of `cron` (whole minute, UTC). */
+export function cronMatches(cron: ParsedCron, instant: Date): boolean {
+  const ms = instant.getTime();
+  if (ms % MINUTE_MS !== 0) return false;
+  return (
+    dayEligible(cron, utcDayStart(ms)) &&
+    cron.hours.includes(instant.getUTCHours()) &&
+    cron.minutes.includes(instant.getUTCMinutes())
+  );
+}
+
+/** The latest slot at or before `atOrBefore`, or null when none exists in the search window. */
+export function previousSlot(cron: ParsedCron, atOrBefore: Date): Date | null {
+  const floored = Math.floor(atOrBefore.getTime() / MINUTE_MS) * MINUTE_MS;
+  let dayStart = utcDayStart(floored);
+  let limit = (floored - dayStart) / MINUTE_MS;
+  for (let i = 0; i <= MAX_SEARCH_DAYS; i++) {
+    if (dayEligible(cron, dayStart)) {
+      for (let h = cron.hours.length - 1; h >= 0; h--) {
+        const hour = cron.hours[h];
+        if (hour * 60 > limit) continue;
+        for (let m = cron.minutes.length - 1; m >= 0; m--) {
+          const minuteOfDay = hour * 60 + cron.minutes[m];
+          if (minuteOfDay <= limit)
+            return new Date(dayStart + minuteOfDay * MINUTE_MS);
+        }
+      }
+    }
+    dayStart -= DAY_MS;
+    limit = 24 * 60 - 1;
+  }
+  return null;
+}
+
+/** The earliest slot strictly after `after`, or null when none exists in the search window. */
+export function nextSlot(cron: ParsedCron, after: Date): Date | null {
+  const start = Math.floor(after.getTime() / MINUTE_MS) * MINUTE_MS + MINUTE_MS;
+  let dayStart = utcDayStart(start);
+  let floor = (start - dayStart) / MINUTE_MS;
+  for (let i = 0; i <= MAX_SEARCH_DAYS; i++) {
+    if (dayEligible(cron, dayStart)) {
+      for (const hour of cron.hours) {
+        if (hour * 60 + 59 < floor) continue;
+        for (const minute of cron.minutes) {
+          const minuteOfDay = hour * 60 + minute;
+          if (minuteOfDay >= floor)
+            return new Date(dayStart + minuteOfDay * MINUTE_MS);
+        }
+      }
+    }
+    dayStart += DAY_MS;
+    floor = 0;
+  }
+  return null;
+}
+
+export interface SlotWindow {
+  /** Ascending. At most `limit` slots: the NEWEST ones when truncated. */
+  readonly slots: readonly Date[];
+  /** True when more slots existed in the window than `limit`. */
+  readonly truncated: boolean;
+}
+
+/** Slots in (afterExclusive, atOrBefore], newest `limit` kept, returned ascending. */
+export function slotsBetween(
+  cron: ParsedCron,
+  afterExclusive: Date,
+  atOrBefore: Date,
+  limit: number,
+): SlotWindow {
+  const newestFirst: Date[] = [];
+  let cursor = previousSlot(cron, atOrBefore);
+  while (cursor !== null && cursor.getTime() > afterExclusive.getTime()) {
+    if (newestFirst.length === limit)
+      return { slots: newestFirst.reverse(), truncated: true };
+    newestFirst.push(cursor);
+    cursor = previousSlot(cron, new Date(cursor.getTime() - MINUTE_MS));
+  }
+  return { slots: newestFirst.reverse(), truncated: false };
+}
+
+/**
+ * The longest gap, in minutes, between consecutive slots among the `samples`
+ * intervals ending at or before `at`. "N cadences" thresholds use this, so an
+ * irregular schedule (`30 9 * * 1,4`) is judged by its longest normal gap.
+ */
+export function maxIntervalMinutes(
+  cron: ParsedCron,
+  at: Date,
+  samples = 8,
+): number {
+  let newer = previousSlot(cron, at);
+  let longest = 0;
+  for (let i = 0; i < samples && newer !== null; i++) {
+    const older = previousSlot(cron, new Date(newer.getTime() - MINUTE_MS));
+    if (older === null) break;
+    longest = Math.max(
+      longest,
+      (newer.getTime() - older.getTime()) / MINUTE_MS,
+    );
+    newer = older;
+  }
+  return longest;
+}

package/src/schedules/definition.ts

@@ -0,0 +1,148 @@
+/**
+ * Schedule definitions and the registry snapshot.
+ *
+ * A ScheduleDefinition is the whole delivery contract for one scheduled job:
+ * when (cron, UTC), what (repo + workflow), how late is still on time (grace),
+ * how long it may run (timeout), what to do about missed slots (catchUp), how
+ * duplicates are prevented (idempotency, effects), how its output is checked
+ * (verify), whether the clock drives it yet (mode) and how loudly it escalates
+ * (severity). `id` is permanent: changing the cron never changes the id.
+ *
+ * control's `scripts/schedules/registry.ts` is the single authored source; control
+ * publishes a ScheduleRegistrySnapshot to the backend, which swaps it in
+ * atomically. `contentHash` is the sha256 hex of canonicalScheduleRegistryJson,
+ * computed by the publisher and re-checked by the receiver.
+ */
+
+import { z } from "zod";
+import { parseCron } from "./cron";
+import { SCHEDULE_EFFECTS } from "./execution";
+import { SCHEDULE_ID_MAX_LENGTH, SCHEDULE_ID_PATTERN } from "./identity";
+
+export const SCHEDULE_CATCH_UP_POLICIES = ["latest", "all", "skip"] as const;
+export type ScheduleCatchUpPolicy = (typeof SCHEDULE_CATCH_UP_POLICIES)[number];
+
+export const SCHEDULE_IDEMPOTENCY_LEVELS = ["required", "best_effort"] as const;
+export type ScheduleIdempotency = (typeof SCHEDULE_IDEMPOTENCY_LEVELS)[number];
+
+/** Closed catalog. v0 has one verifier. */
+export const SCHEDULE_OUTPUT_VERIFIERS = ["production_signal_fresh"] as const;
+export type ScheduleOutputVerifier = (typeof SCHEDULE_OUTPUT_VERIFIERS)[number];
+
+/** off: GitHub cron only, clock ignores it. shadow: clock plans, never dispatches. live: clock dispatches; legacy cron runs refused. */
+export const SCHEDULE_MODES = ["off", "shadow", "live"] as const;
+export type ScheduleMode = (typeof SCHEDULE_MODES)[number];
+
+export const SCHEDULE_SEVERITIES = ["red-main", "schedule"] as const;
+export type ScheduleSeverity = (typeof SCHEDULE_SEVERITIES)[number];
+
+export const SCHEDULE_TIMEZONE = "UTC" as const;
+export const SCHEDULE_MAX_CATCH_UP_SLOTS = 48;
+/** GitHub-hosted job ceiling. */
+export const SCHEDULE_MAX_TIMEOUT_MINUTES = 360;
+
+export const ScheduleDefinitionSchema = z
+  .object({
+    id: z.string().max(SCHEDULE_ID_MAX_LENGTH).regex(SCHEDULE_ID_PATTERN),
+    repo: z.string().regex(/^company-semantics-[a-z]+(?:-[a-z]+)*$/),
+    workflow: z.string().regex(/^[A-Za-z0-9._-]+\.ya?ml$/),
+    cron: z.string().refine((value) => parseCron(value).ok, {
+      message:
+        "cron must be a supported five-field UTC expression that can fire",
+    }),
+    timezone: z.literal(SCHEDULE_TIMEZONE),
+    graceMinutes: z.number().int().min(0).max(1440),
+    timeoutMinutes: z.number().int().min(1).max(SCHEDULE_MAX_TIMEOUT_MINUTES),
+    admissionTimeoutMinutes: z.number().int().min(1).max(60),
+    catchUp: z.enum(SCHEDULE_CATCH_UP_POLICIES),
+    maxCatchUpSlots: z.number().int().min(1).max(SCHEDULE_MAX_CATCH_UP_SLOTS),
+    idempotency: z.enum(SCHEDULE_IDEMPOTENCY_LEVELS),
+    effects: z.enum(SCHEDULE_EFFECTS),
+    verify: z.enum(SCHEDULE_OUTPUT_VERIFIERS).nullable(),
+    mode: z.enum(SCHEDULE_MODES),
+    severity: z.enum(SCHEDULE_SEVERITIES),
+  })
+  .strict()
+  .superRefine((definition, ctx) => {
+    if (
+      (definition.effects === "fenced" || definition.effects === "unsafe") &&
+      definition.idempotency !== "required"
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["idempotency"],
+        message: "fenced or unsafe effects require idempotency 'required'",
+      });
+    }
+    if (definition.catchUp === "all" && definition.effects === "unsafe") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["catchUp"],
+        message: "catchUp 'all' never replays unsafe effects",
+      });
+    }
+  });
+export type ScheduleDefinition = z.infer<typeof ScheduleDefinitionSchema>;
+
+/** Key order used by canonicalScheduleRegistryJson. Every field, in declaration order. */
+export const SCHEDULE_DEFINITION_KEYS = [
+  "id",
+  "repo",
+  "workflow",
+  "cron",
+  "timezone",
+  "graceMinutes",
+  "timeoutMinutes",
+  "admissionTimeoutMinutes",
+  "catchUp",
+  "maxCatchUpSlots",
+  "idempotency",
+  "effects",
+  "verify",
+  "mode",
+  "severity",
+] as const satisfies readonly (keyof ScheduleDefinition)[];
+
+/**
+ * Deterministic serialization: definitions sorted by id, keys in
+ * SCHEDULE_DEFINITION_KEYS order, no whitespace. The snapshot's contentHash is
+ * sha256(hex) of this string; publisher and receiver both compute it from here.
+ */
+export function canonicalScheduleRegistryJson(
+  schedules: readonly ScheduleDefinition[],
+): string {
+  const ordered = [...schedules]
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((definition) =>
+      Object.fromEntries(
+        SCHEDULE_DEFINITION_KEYS.map((key) => [key, definition[key]]),
+      ),
+    );
+  return JSON.stringify(ordered);
+}
+
+export const SCHEDULE_REGISTRY_SCHEMA_VERSION = 1 as const;
+
+export const ScheduleRegistrySnapshotSchema = z
+  .object({
+    schemaVersion: z.literal(SCHEDULE_REGISTRY_SCHEMA_VERSION),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    schedules: z.array(ScheduleDefinitionSchema),
+  })
+  .strict()
+  .superRefine((snapshot, ctx) => {
+    const seen = new Set<string>();
+    snapshot.schedules.forEach((definition, index) => {
+      if (seen.has(definition.id)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["schedules", index, "id"],
+          message: `duplicate schedule id "${definition.id}"`,
+        });
+      }
+      seen.add(definition.id);
+    });
+  });
+export type ScheduleRegistrySnapshot = z.infer<
+  typeof ScheduleRegistrySnapshotSchema
+>;

package/src/schedules/execution.ts

@@ -0,0 +1,146 @@
+/**
+ * Scheduled-execution lifecycle, recovery and incident vocabulary.
+ *
+ * The backend ledger stores these states; the reconciler moves rows only along
+ * SCHEDULE_EXECUTION_TRANSITIONS. Wire values are lowercase snake_case.
+ *
+ * Lifecycle: due → dispatch_requested → started → completed → output_verified.
+ * - `dispatch_requested` is entered by a compare-and-swap on the attempt number
+ *   BEFORE the dispatch call (claim-before-call), so two clocks ticking at once
+ *   dispatch an attempt at most once. A crash before the call, or an ambiguous
+ *   acceptance, leaves `dispatch_outcome` null/`ambiguous`: after the admission
+ *   timeout the run is looked up by display_title; if none appeared, a NEW
+ *   attempt is dispatched (`dispatch_requested` → `dispatch_requested`). Creating
+ *   a run has no effect of its own; the workflow's claim is the gate.
+ * - `started` is entered by the workflow's OIDC-bound claim, which carries a
+ *   monotonically increasing `claim_epoch` (the fencing token). A lease is not
+ *   exactly-once: a stale holder's writes are rejected by epoch.
+ * - `completed` carries a conclusion. GitHub's run conclusion is authoritative;
+ *   the workflow's own finish call is an optimization.
+ * - `timed_out`: the backend canceled a run past the schedule's timeoutMinutes.
+ * - Re-execution (`completed`/`timed_out` → `started` with a new epoch) happens
+ *   automatically ONLY when the schedule's effects allow it
+ *   (mayReexecuteAutomatically); `unsafe` effects wait for a human.
+ * - `superseded`: under catchUp `latest`, an older missed slot whose successor ran.
+ * - `missed`: under catchUp `skip`, a slot recorded as not run.
+ * - `acknowledged_loss`: a person applied SCHEDULE_LOSS_ACK_LABEL to its incident.
+ */
+
+export const SCHEDULE_EXECUTION_STATES = [
+  "due",
+  "dispatch_requested",
+  "started",
+  "completed",
+  "output_verified",
+  "timed_out",
+  "superseded",
+  "missed",
+  "acknowledged_loss",
+] as const;
+export type ScheduleExecutionState = (typeof SCHEDULE_EXECUTION_STATES)[number];
+
+export const SCHEDULE_RUN_CONCLUSIONS = ["success", "failure"] as const;
+export type ScheduleRunConclusion = (typeof SCHEDULE_RUN_CONCLUSIONS)[number];
+
+export const SCHEDULE_DISPATCH_OUTCOMES = [
+  "accepted",
+  "rejected",
+  "ambiguous",
+] as const;
+export type ScheduleDispatchOutcome =
+  (typeof SCHEDULE_DISPATCH_OUTCOMES)[number];
+
+/** Allowed moves. A move not listed here is a reconciler bug, never a data repair. */
+export const SCHEDULE_EXECUTION_TRANSITIONS: Readonly<
+  Record<ScheduleExecutionState, readonly ScheduleExecutionState[]>
+> = {
+  due: ["dispatch_requested", "superseded", "missed", "acknowledged_loss"],
+  dispatch_requested: ["dispatch_requested", "started", "acknowledged_loss"],
+  started: ["started", "completed", "timed_out"],
+  completed: ["output_verified", "started", "acknowledged_loss"],
+  timed_out: ["started", "acknowledged_loss"],
+  output_verified: [],
+  superseded: [],
+  missed: [],
+  acknowledged_loss: [],
+};
+
+export function canTransitionScheduleExecution(
+  from: ScheduleExecutionState,
+  to: ScheduleExecutionState,
+): boolean {
+  return SCHEDULE_EXECUTION_TRANSITIONS[from].includes(to);
+}
+
+export interface ScheduleExecutionSettlementInput {
+  readonly state: ScheduleExecutionState;
+  readonly conclusion: ScheduleRunConclusion | null;
+  /** True when the schedule declares an output verifier. */
+  readonly requiresVerification: boolean;
+}
+
+/**
+ * Settled = nothing further will happen to this slot without a human.
+ * A successful completion settles only when no verifier is declared.
+ */
+export function isScheduleExecutionSettled(
+  row: ScheduleExecutionSettlementInput,
+): boolean {
+  switch (row.state) {
+    case "output_verified":
+    case "superseded":
+    case "missed":
+    case "acknowledged_loss":
+      return true;
+    case "completed":
+      return row.conclusion === "success" && !row.requiresVerification;
+    default:
+      return false;
+  }
+}
+
+/** What the workflow's side effects tolerate. Declared per schedule; required. */
+export const SCHEDULE_EFFECTS = [
+  "none",
+  "idempotent",
+  "fenced",
+  "unsafe",
+] as const;
+export type ScheduleEffects = (typeof SCHEDULE_EFFECTS)[number];
+
+/**
+ * none: read-only. idempotent: downstream writes keyed by execution_id.
+ * fenced: downstream writes carry claim_epoch and stale epochs are rejected.
+ * unsafe: none of the above: never re-executed without a human.
+ */
+export function mayReexecuteAutomatically(effects: ScheduleEffects): boolean {
+  return effects !== "unsafe";
+}
+
+export const SCHEDULE_INCIDENT_CLASSES = [
+  "clock",
+  "admission",
+  "delivery",
+  "execution",
+  "output",
+] as const;
+export type ScheduleIncidentClass = (typeof SCHEDULE_INCIDENT_CLASSES)[number];
+
+/**
+ * Dedupe key for an incident. Subject: the clock source (clock), the
+ * schedule_id (delivery), or the execution_id (admission, execution, output).
+ * Each class resolves on its own subject, never on an unrelated newer run.
+ */
+export function scheduleIncidentKey(
+  incidentClass: ScheduleIncidentClass,
+  subject: string,
+): string {
+  return `schedule:${incidentClass}:${subject}`;
+}
+
+export const SCHEDULE_INFRA_LABEL = "schedule-infra";
+export const SCHEDULE_LOSS_ACK_LABEL = "schedule-loss-acknowledged";
+
+/** Independent tick sources. Each one's health is tracked and alarmed separately. */
+export const SCHEDULE_CLOCK_SOURCES = ["edge", "jobqueue"] as const;
+export type ScheduleClockSource = (typeof SCHEDULE_CLOCK_SOURCES)[number];