@company-semantics/contracts 98.0.0 → 99.1.0

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];

package/src/schedules/identity.ts

@@ -0,0 +1,99 @@
+/**
+ * Scheduled-execution identity.
+ *
+ * An execution is named by the slot it was INTENDED for, never by when a run
+ * happened to start: `execution_id = <schedule_id>/<slot ISO>`, with the slot a
+ * whole UTC minute written `YYYY-MM-DDTHH:MM:00Z`. A dispatch attempt is named
+ * `<execution_id>#<attempt>`; that string is the workflow's `run-name`, so the
+ * GitHub run's `display_title` is how a dispatched run is found again after an
+ * ambiguous dispatch.
+ *
+ * A run that carries no execution_id (a manual run, an unrelated dispatch, or a
+ * legacy `on.schedule` run) never satisfies a slot. Legacy runs are admitted
+ * only while the schedule's mode is not `live`, and still never get an id
+ * (migration admission; contracts ADR slug schedule-execution-wire-types).
+ */
+
+/** Kebab-case, no `/` or `#`, so an execution_id and a display title parse unambiguously. */
+export const SCHEDULE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const SCHEDULE_ID_MAX_LENGTH = 64;
+export const SCHEDULE_SLOT_ISO_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:00Z$/;
+
+/** The workflow_dispatch inputs every registered workflow declares once it leaves mode `off`. */
+export const SCHEDULE_DISPATCH_INPUTS = [
+  "schedule_id",
+  "scheduled_at",
+  "execution_id",
+  "attempt",
+] as const;
+export type ScheduleDispatchInput = (typeof SCHEDULE_DISPATCH_INPUTS)[number];
+
+/** The exact `run-name:` a registered workflow declares, so display_title = execution_id#attempt. */
+export const SCHEDULE_RUN_NAME =
+  "${{ inputs.execution_id && format('{0}#{1}', inputs.execution_id, inputs.attempt) || github.workflow }}";
+
+export function isScheduleId(value: string): boolean {
+  return (
+    value.length <= SCHEDULE_ID_MAX_LENGTH && SCHEDULE_ID_PATTERN.test(value)
+  );
+}
+
+/** `YYYY-MM-DDTHH:MM:00Z`. Throws RangeError when `slot` is not a whole UTC minute. */
+export function slotIso(slot: Date): string {
+  if (Number.isNaN(slot.getTime()) || slot.getTime() % 60_000 !== 0) {
+    throw new RangeError("a schedule slot must be a whole UTC minute");
+  }
+  return slot.toISOString().replace(".000Z", "Z");
+}
+
+export function executionIdFor(scheduleId: string, slot: Date): string {
+  if (!isScheduleId(scheduleId))
+    throw new RangeError(`invalid schedule id "${scheduleId}"`);
+  return `${scheduleId}/${slotIso(slot)}`;
+}
+
+export interface ParsedExecutionId {
+  readonly scheduleId: string;
+  readonly slot: Date;
+}
+
+export function parseExecutionId(
+  executionId: string,
+): ParsedExecutionId | null {
+  const slash = executionId.indexOf("/");
+  if (slash < 0) return null;
+  const scheduleId = executionId.slice(0, slash);
+  const iso = executionId.slice(slash + 1);
+  if (!isScheduleId(scheduleId) || !SCHEDULE_SLOT_ISO_PATTERN.test(iso))
+    return null;
+  const slot = new Date(iso);
+  if (Number.isNaN(slot.getTime()) || slotIso(slot) !== iso) return null;
+  return { scheduleId, slot };
+}
+
+export function displayTitleFor(executionId: string, attempt: number): string {
+  if (parseExecutionId(executionId) === null) {
+    throw new RangeError(`invalid execution id "${executionId}"`);
+  }
+  if (!Number.isInteger(attempt) || attempt < 1) {
+    throw new RangeError("a dispatch attempt is a positive integer");
+  }
+  return `${executionId}#${attempt}`;
+}
+
+export interface ParsedDisplayTitle extends ParsedExecutionId {
+  readonly executionId: string;
+  readonly attempt: number;
+}
+
+/** Inverse of displayTitleFor; null for any run title that is not a scheduled dispatch. */
+export function parseDisplayTitle(title: string): ParsedDisplayTitle | null {
+  const hash = title.lastIndexOf("#");
+  if (hash < 0) return null;
+  const executionId = title.slice(0, hash);
+  const attemptText = title.slice(hash + 1);
+  if (!/^[1-9]\d*$/.test(attemptText)) return null;
+  const parsed = parseExecutionId(executionId);
+  if (parsed === null) return null;
+  return { ...parsed, executionId, attempt: Number(attemptText) };
+}

package/src/schedules/index.ts

@@ -0,0 +1,124 @@
+/**
+ * Schedules Domain Barrel
+ *
+ * Re-exports the scheduled-execution vocabulary: schedule definitions and the
+ * registry snapshot, execution identity, the execution lifecycle with its
+ * recovery and incident vocabulary, the pure UTC cron evaluator, and the
+ * responses the backend's schedule routes publish.
+ * Import from the package root, '@company-semantics/contracts'. This barrel is
+ * reached only through that root re-export: there is no './schedules' subpath
+ * in package.json, by design (same as product-intake).
+ *
+ * Participating repos: control authors the registry and validates it with
+ * parseCron; the backend stores the ledger and runs the reconciler on the same
+ * evaluator; edge reads SCHEDULE_TICK_PATH and the ScheduleTickRequest type. The
+ * ci action speaks HTTP only and imports nothing here.
+ *
+ * @see ./README.md
+ */
+
+export {
+  parseCron,
+  cronMatches,
+  previousSlot,
+  nextSlot,
+  slotsBetween,
+  maxIntervalMinutes,
+} from "./cron";
+export type {
+  CronField,
+  ParsedCron,
+  CronParseResult,
+  SlotWindow,
+} from "./cron";
+
+export {
+  SCHEDULE_ID_PATTERN,
+  SCHEDULE_ID_MAX_LENGTH,
+  SCHEDULE_SLOT_ISO_PATTERN,
+  SCHEDULE_DISPATCH_INPUTS,
+  SCHEDULE_RUN_NAME,
+  isScheduleId,
+  slotIso,
+  executionIdFor,
+  parseExecutionId,
+  displayTitleFor,
+  parseDisplayTitle,
+} from "./identity";
+export type {
+  ScheduleDispatchInput,
+  ParsedExecutionId,
+  ParsedDisplayTitle,
+} from "./identity";
+
+export {
+  SCHEDULE_EXECUTION_STATES,
+  SCHEDULE_RUN_CONCLUSIONS,
+  SCHEDULE_DISPATCH_OUTCOMES,
+  SCHEDULE_EXECUTION_TRANSITIONS,
+  canTransitionScheduleExecution,
+  isScheduleExecutionSettled,
+  SCHEDULE_EFFECTS,
+  mayReexecuteAutomatically,
+  SCHEDULE_INCIDENT_CLASSES,
+  scheduleIncidentKey,
+  SCHEDULE_INFRA_LABEL,
+  SCHEDULE_LOSS_ACK_LABEL,
+  SCHEDULE_CLOCK_SOURCES,
+} from "./execution";
+export type {
+  ScheduleExecutionState,
+  ScheduleRunConclusion,
+  ScheduleDispatchOutcome,
+  ScheduleExecutionSettlementInput,
+  ScheduleEffects,
+  ScheduleIncidentClass,
+  ScheduleClockSource,
+} from "./execution";
+
+export {
+  SCHEDULE_CATCH_UP_POLICIES,
+  SCHEDULE_IDEMPOTENCY_LEVELS,
+  SCHEDULE_OUTPUT_VERIFIERS,
+  SCHEDULE_MODES,
+  SCHEDULE_SEVERITIES,
+  SCHEDULE_TIMEZONE,
+  SCHEDULE_MAX_CATCH_UP_SLOTS,
+  SCHEDULE_MAX_TIMEOUT_MINUTES,
+  ScheduleDefinitionSchema,
+  SCHEDULE_DEFINITION_KEYS,
+  canonicalScheduleRegistryJson,
+  SCHEDULE_REGISTRY_SCHEMA_VERSION,
+  ScheduleRegistrySnapshotSchema,
+} from "./definition";
+export type {
+  ScheduleCatchUpPolicy,
+  ScheduleIdempotency,
+  ScheduleOutputVerifier,
+  ScheduleMode,
+  ScheduleSeverity,
+  ScheduleDefinition,
+  ScheduleRegistrySnapshot,
+} from "./definition";
+
+export {
+  SCHEDULE_CLAIM_REFUSALS,
+  ScheduleClaimResponseSchema,
+  SCHEDULE_FINISH_REJECTIONS,
+  ScheduleFinishResponseSchema,
+  ScheduleTickResponseSchema,
+  SCHEDULE_TICK_PATH,
+  SCHEDULE_METRICS_NAMESPACE,
+  SCHEDULE_METRIC_TICK,
+  SCHEDULE_METRIC_TICK_SOURCE_DIMENSION,
+  SCHEDULE_METRIC_RECONCILE_SUCCESS,
+  SCHEDULE_METRIC_ENVIRONMENT_DIMENSION,
+} from "./api";
+export type {
+  ScheduleClaimRefusal,
+  ScheduleClaimResponse,
+  ScheduleFinishRejection,
+  ScheduleFinishResponse,
+  ScheduleTickResponse,
+  ScheduleTickRequest,
+} from "./api";