@company-semantics/contracts 99.0.0 → 99.2.0

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