@k2b/cloud 0.6.0-rc.0

package/src/workflows/runtime/index.ts

@@ -0,0 +1,60 @@
+export type {
+  WorkflowCoordinatorClaim,
+  WorkflowCoordinatorExecution,
+  WorkflowCoordinatorFinishState,
+  WorkflowCoordinatorLeaseState,
+  WorkflowCoordinatorPort,
+  WorkflowCoordinatorReleaseState,
+  WorkflowCoordinatorResult,
+} from "./coordinator";
+export { coordinateWorkflowExecution } from "./coordinator";
+export {
+  DEFAULT_MAX_LOOP_ITEMS,
+  dryRunWorkflowPlan,
+  executeWorkflowPlan,
+  WorkflowLeaseLostError,
+  WorkflowRetryableStepError,
+} from "./executor";
+export type {
+  WorkflowActionStep,
+  WorkflowDryRunActionContext,
+  WorkflowDryRunActionHandler,
+  WorkflowDryRunActionPort,
+  WorkflowDryRunIssue,
+  WorkflowDryRunOptions,
+  WorkflowDryRunResult,
+  WorkflowExecuteActionContext,
+  WorkflowExecuteActionHandler,
+  WorkflowExecuteActionPort,
+  WorkflowExecuteOptions,
+  WorkflowExecutionClock,
+  WorkflowExecutionResult,
+  WorkflowHeartbeatOutcome,
+  WorkflowRestoredStep,
+  WorkflowRuntimeRepositoryPort,
+  WorkflowRuntimeRunIdentity,
+  WorkflowRuntimeStepIdentity,
+  WorkflowRuntimeStepResult,
+  WorkflowTraceEvent,
+  WorkflowTracePort,
+  WorkflowValueResolution,
+  WorkflowValueResolverPort,
+  WorkflowVariableScope,
+} from "./ports";
+export type {
+  WorkflowSchedule,
+  WorkflowScheduleReconciliation,
+  WorkflowScheduleReconciliationPort,
+  WorkflowScheduleRegistration,
+} from "./schedule";
+export {
+  createWorkflowScheduleRegistration,
+  normalizeWorkflowSchedule,
+  planWorkflowScheduleReconciliation,
+  reconcileWorkflowSchedules,
+  workflowScheduleRegistrationId,
+  workflowScheduleSlotKey,
+} from "./schedule";
+export { evaluateWorkflowTriggerInputs } from "./trigger";
+export type { WorkflowRunWake } from "./wake";
+export { wakeWorkflowRunBestEffort } from "./wake";

package/src/workflows/runtime/instant.ts

@@ -0,0 +1,8 @@
+export const normalizeWorkflowInstant = (name: string, value: string): string => {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/u.test(value)) {
+    throw new Error(`${name} must be an ISO date-time with a timezone`);
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) throw new Error(`${name} must be an ISO date-time with a timezone`);
+  return new Date(timestamp).toISOString();
+};

package/src/workflows/runtime/ports.ts

@@ -0,0 +1,213 @@
+import type {
+  WorkflowBoundPlan,
+  WorkflowDependency,
+  WorkflowInvocation,
+  WorkflowInvocationMode,
+  WorkflowIrStep,
+  WorkflowJsonValue,
+  WorkflowPlanningIssue,
+  WorkflowPlanningOutcome,
+  WorkflowRunState,
+  WorkflowStepOutcome,
+} from "../contracts";
+
+export type WorkflowActionStep = Extract<WorkflowIrStep, { kind: "action" }>;
+
+export type WorkflowRuntimeRunIdentity = {
+  runId: string;
+  executionGeneration: number;
+  mode: WorkflowInvocationMode;
+  workflowId: string;
+  sourceHash: string;
+  idempotencyKey: string;
+};
+
+export type WorkflowRuntimeStepIdentity = WorkflowRuntimeRunIdentity & {
+  key: string;
+  sourcePath: Array<string | number>;
+  iterationPath: number[];
+  path: Array<string | number>;
+  kind: WorkflowIrStep["kind"];
+  action?: string;
+};
+
+export type WorkflowHeartbeatOutcome = { state: "active" } | { state: "stale" } | { state: "canceled"; message?: string };
+
+export type WorkflowRestoredStep =
+  | { mode: "execute"; outcome: Exclude<WorkflowStepOutcome, { state: "waiting" }> }
+  | { mode: "dryRun"; outcome: WorkflowPlanningOutcome };
+
+export type WorkflowRuntimeStepResult =
+  | { mode: "execute"; outcome: WorkflowStepOutcome }
+  | { mode: "dryRun"; outcome: WorkflowPlanningOutcome };
+
+export interface WorkflowRuntimeRepositoryPort {
+  heartbeat(run: WorkflowRuntimeRunIdentity): Promise<WorkflowHeartbeatOutcome>;
+  restoreStepOutcome(step: WorkflowRuntimeStepIdentity): Promise<WorkflowRestoredStep | null>;
+  startStep(step: WorkflowRuntimeStepIdentity): Promise<void>;
+  finishStep(step: WorkflowRuntimeStepIdentity, result: WorkflowRuntimeStepResult): Promise<void>;
+  parkStep(step: WorkflowRuntimeStepIdentity, dependency: WorkflowDependency): Promise<void>;
+}
+
+export interface WorkflowVariableScope {
+  get(name: string): WorkflowJsonValue | undefined;
+  has(name: string): boolean;
+  set(name: string, value: WorkflowJsonValue): void;
+  snapshot?(): Record<string, WorkflowJsonValue>;
+}
+
+export type WorkflowValueResolution =
+  | { state: "resolved"; value: WorkflowJsonValue }
+  | { state: "missing" }
+  | { state: "waiting"; dependency: WorkflowDependency };
+
+export interface WorkflowExecutionClock {
+  now(): string;
+}
+
+type WorkflowActionContextBase<Mode extends WorkflowInvocationMode> = {
+  mode: Mode;
+  run: WorkflowRuntimeRunIdentity & { mode: Mode };
+  step: WorkflowRuntimeStepIdentity & { mode: Mode };
+  plan: WorkflowBoundPlan;
+  invocation: WorkflowInvocation & { mode: Mode };
+  variables: WorkflowVariableScope;
+  evaluate(value: WorkflowJsonValue, path?: Array<string | number>): Promise<WorkflowJsonValue>;
+  resolveReference(reference: string, path?: Array<string | number>): Promise<WorkflowJsonValue | undefined>;
+  heartbeat(): Promise<void>;
+};
+
+export type WorkflowExecuteActionContext = WorkflowActionContextBase<"execute">;
+export type WorkflowDryRunActionContext = WorkflowActionContextBase<"dryRun">;
+
+export type WorkflowExecuteActionHandler = {
+  execute(context: WorkflowExecuteActionContext, step: WorkflowActionStep): Promise<WorkflowStepOutcome>;
+  restoreCompleted?(
+    context: WorkflowExecuteActionContext,
+    step: WorkflowActionStep,
+    outcome: Extract<WorkflowStepOutcome, { state: "completed" }>,
+  ): Promise<void> | void;
+};
+
+export type WorkflowDryRunActionHandler = {
+  plan(context: WorkflowDryRunActionContext, step: WorkflowActionStep): Promise<WorkflowPlanningOutcome>;
+  restoreCompleted?(
+    context: WorkflowDryRunActionContext,
+    step: WorkflowActionStep,
+    outcome: Extract<WorkflowPlanningOutcome, { state: "planned" }>,
+  ): Promise<void> | void;
+};
+
+export interface WorkflowExecuteActionPort {
+  get(action: string): WorkflowExecuteActionHandler | undefined;
+}
+
+export interface WorkflowDryRunActionPort {
+  get(action: string): WorkflowDryRunActionHandler | undefined;
+}
+
+/**
+ * What an observer is told about a run's progress.
+ *
+ * The run-level events bracket the step-level ones: a worker claimed this run,
+ * and it settled this way. An app that streams progress to a browser needs both
+ * ends — without `run.started` a queued run appears to sit still until its first
+ * step reports, and without `run.finished` a run that failed before any step
+ * never announces that it stopped.
+ *
+ * Deliberately thin: the transition and which run it happened to. Whoever
+ * publishes re-reads the run, because the row is the truth and an event that
+ * carried a copy of it would be one more thing to keep in step.
+ */
+export type WorkflowTraceEvent =
+  | { type: "run.started"; run: WorkflowRuntimeRunIdentity }
+  | { type: "step.started"; step: WorkflowRuntimeStepIdentity }
+  | { type: "step.restored"; step: WorkflowRuntimeStepIdentity; restored: WorkflowRestoredStep }
+  | { type: "step.waiting"; step: WorkflowRuntimeStepIdentity; dependency: WorkflowDependency }
+  | { type: "step.finished"; step: WorkflowRuntimeStepIdentity; result: WorkflowRuntimeStepResult }
+  | { type: "run.canceled"; run: WorkflowRuntimeRunIdentity; message?: string }
+  | { type: "run.finished"; run: WorkflowRuntimeRunIdentity; state: WorkflowRunState | "released" };
+
+export interface WorkflowTracePort {
+  emit(event: WorkflowTraceEvent): Promise<void> | void;
+}
+
+export interface WorkflowValueResolverPort {
+  resolve(input: {
+    reference: string;
+    path: Array<string | number>;
+    plan: WorkflowBoundPlan;
+    invocation: WorkflowInvocation;
+    variables: WorkflowVariableScope;
+    fallback: () => WorkflowJsonValue | undefined;
+  }): Promise<WorkflowValueResolution>;
+}
+
+type WorkflowRuntimeOptionsBase = {
+  runId: string;
+  executionGeneration: number;
+  plan: WorkflowBoundPlan;
+  invocation: WorkflowInvocation;
+  repository: WorkflowRuntimeRepositoryPort;
+  clock: WorkflowExecutionClock;
+  trace?: WorkflowTracePort;
+  values?: WorkflowValueResolverPort;
+  maxLoopItems?: number;
+  initialVariables?: Record<string, WorkflowJsonValue>;
+};
+
+export type WorkflowExecuteOptions = Omit<WorkflowRuntimeOptionsBase, "invocation"> & {
+  invocation: WorkflowInvocation & { mode: "execute" };
+  actions: WorkflowExecuteActionPort;
+};
+
+export type WorkflowDryRunOptions = Omit<WorkflowRuntimeOptionsBase, "invocation"> & {
+  invocation: WorkflowInvocation & { mode: "dryRun" };
+  actions: WorkflowDryRunActionPort;
+};
+
+export type WorkflowExecutionResult =
+  | { state: "succeeded"; output?: WorkflowJsonValue; message?: string }
+  | { state: "waiting"; dependency: Extract<WorkflowStepOutcome, { state: "waiting" }>["dependency"]; step: WorkflowRuntimeStepIdentity }
+  | { state: "failed"; error: Extract<WorkflowStepOutcome, { state: "failed" }>["error"]; step: WorkflowRuntimeStepIdentity }
+  | {
+      state: "needs_attention";
+      error: Extract<WorkflowStepOutcome, { state: "needs_attention" }>["error"];
+      step: WorkflowRuntimeStepIdentity;
+    }
+  | { state: "canceled"; message?: string; step?: WorkflowRuntimeStepIdentity };
+
+export type WorkflowDryRunIssue = Omit<WorkflowPlanningIssue, "step"> & {
+  step: WorkflowRuntimeStepIdentity;
+};
+
+export type WorkflowDryRunResult =
+  | { state: "planned"; output?: WorkflowJsonValue; effects: WorkflowJsonValue[] }
+  | {
+      state: "terminal";
+      status: "succeeded" | "failed";
+      message?: string;
+      effects: WorkflowJsonValue[];
+      issues?: WorkflowDryRunIssue[];
+    }
+  | {
+      state: "unsupported";
+      reason: string;
+      effects: WorkflowJsonValue[];
+      step: WorkflowRuntimeStepIdentity;
+      issues: WorkflowDryRunIssue[];
+    }
+  | {
+      state: "indeterminate";
+      reason: string;
+      effects: WorkflowJsonValue[];
+      step: WorkflowRuntimeStepIdentity;
+      issues: WorkflowDryRunIssue[];
+    }
+  | {
+      state: "canceled";
+      message?: string;
+      effects: WorkflowJsonValue[];
+      step?: WorkflowRuntimeStepIdentity;
+      issues?: WorkflowDryRunIssue[];
+    };

package/src/workflows/runtime/schedule.ts

@@ -0,0 +1,203 @@
+import type { WorkflowRevision } from "../contracts";
+import { normalizeWorkflowInstant } from "./instant";
+
+const opaqueKey = (prefix: string, parts: readonly string[]): string =>
+  `${prefix}:${parts.map((part) => `${part.length}:${part}`).join("")}`;
+
+const CRON_FIELDS = [
+  { name: "minute", min: 0, max: 59 },
+  { name: "hour", min: 0, max: 23 },
+  { name: "day-of-month", min: 1, max: 31 },
+  { name: "month", min: 1, max: 12 },
+  { name: "day-of-week", min: 0, max: 7 },
+] as const;
+
+const cronError = (field: (typeof CRON_FIELDS)[number], value: string): Error => new Error(`cron ${field.name} field is invalid: ${value}`);
+
+const cronNumber = (value: string, field: (typeof CRON_FIELDS)[number]): number => {
+  if (!/^\d+$/u.test(value)) throw cronError(field, value);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < field.min || number > field.max) throw cronError(field, value);
+  return number;
+};
+
+type CronFieldValues = { any: boolean; values: Set<number> };
+
+const normalizeCronValue = (value: number, field: (typeof CRON_FIELDS)[number]): number =>
+  field.name === "day-of-week" && value === 7 ? 0 : value;
+
+const validateCronItem = (item: string, field: (typeof CRON_FIELDS)[number]): number[] => {
+  const stepParts = item.split("/");
+  if (stepParts.length > 2) throw cronError(field, item);
+  const [base = "", step] = stepParts;
+  const rangeParts = base.split("-");
+  if (rangeParts.length > 2) throw cronError(field, item);
+
+  const stepNumber = step === undefined ? 1 : Number(step);
+  if (step !== undefined && (!/^\d+$/u.test(step) || !Number.isSafeInteger(stepNumber) || stepNumber < 1)) {
+    throw cronError(field, item);
+  }
+
+  let start: number = field.min;
+  let end: number = field.max;
+  if (base !== "*") {
+    const [startText = "", endText] = rangeParts;
+    start = cronNumber(startText, field);
+    end = endText === undefined ? start : cronNumber(endText, field);
+  }
+
+  const normalizedStart = normalizeCronValue(start, field);
+  const normalizedEnd = normalizeCronValue(end, field);
+  const values: number[] = [];
+  if (field.name === "day-of-week" && start !== end && normalizedStart > normalizedEnd) {
+    for (let value = normalizedStart; value <= field.max; value += stepNumber) values.push(normalizeCronValue(value, field));
+    for (let value = field.min; value <= normalizedEnd; value += stepNumber) values.push(normalizeCronValue(value, field));
+    return values;
+  }
+  if (normalizedStart > normalizedEnd) throw cronError(field, item);
+  for (let value = normalizedStart; value <= normalizedEnd; value += stepNumber) values.push(normalizeCronValue(value, field));
+  return values;
+};
+
+const validateCronField = (value: string, field: (typeof CRON_FIELDS)[number]): CronFieldValues => {
+  const items = value.split(",");
+  if (items.some((item) => item.length === 0)) throw cronError(field, value);
+  const values = new Set(items.flatMap((item) => validateCronItem(item, field)));
+  if (values.size === 0) throw cronError(field, value);
+  return { any: value === "*", values };
+};
+
+const assertReachableCalendarDate = (fields: readonly CronFieldValues[]): void => {
+  const dayOfMonth = fields[2]!;
+  const month = fields[3]!;
+  const dayOfWeek = fields[4]!;
+  if (dayOfMonth.any || !dayOfWeek.any) return;
+  const maxDays = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  const reachable = [...month.values].some((value) => [...dayOfMonth.values].some((day) => day <= maxDays[value - 1]!));
+  if (!reachable) throw new Error("cron has no reachable calendar date");
+};
+
+export type WorkflowSchedule = {
+  cron: string;
+  timezone: string;
+};
+
+export type WorkflowScheduleRegistration = {
+  id: string;
+  namespace: string;
+  workflowId: string;
+  triggerId: string;
+  revision: WorkflowRevision;
+  schedule: WorkflowSchedule;
+};
+
+export const normalizeWorkflowSchedule = (schedule: WorkflowSchedule): WorkflowSchedule => {
+  const fields = schedule.cron.trim().split(/\s+/u);
+  if (fields.length !== 5 || fields.some((field) => field.length === 0)) {
+    throw new Error("cron must contain exactly five fields");
+  }
+  const parsedFields = fields.map((value, index) => validateCronField(value, CRON_FIELDS[index]!));
+  assertReachableCalendarDate(parsedFields);
+
+  const timezone = schedule.timezone.trim();
+  if (!timezone) throw new Error("timezone must be an IANA timezone");
+  let normalizedTimezone: string;
+  try {
+    normalizedTimezone = new Intl.DateTimeFormat("en-US", { timeZone: timezone }).resolvedOptions().timeZone;
+  } catch {
+    throw new Error(`timezone must be an IANA timezone: ${timezone}`);
+  }
+  return { cron: fields.join(" "), timezone: normalizedTimezone };
+};
+
+export const workflowScheduleRegistrationId = (input: {
+  namespace: string;
+  workflowId: string;
+  triggerId: string;
+  revision: WorkflowRevision;
+}): string => opaqueKey("workflow-schedule", [input.namespace, input.workflowId, input.triggerId]);
+
+export const createWorkflowScheduleRegistration = (
+  input: Omit<WorkflowScheduleRegistration, "id" | "schedule"> & WorkflowSchedule,
+): WorkflowScheduleRegistration => ({
+  id: workflowScheduleRegistrationId(input),
+  namespace: input.namespace,
+  workflowId: input.workflowId,
+  triggerId: input.triggerId,
+  revision: input.revision,
+  schedule: normalizeWorkflowSchedule(input),
+});
+
+export const workflowScheduleSlotKey = (registrationId: string, slot: string): string => {
+  return opaqueKey("workflow-schedule-slot", [registrationId, normalizeWorkflowInstant("slot", slot)]);
+};
+
+export type WorkflowScheduleReconciliation = {
+  create: WorkflowScheduleRegistration[];
+  update: Array<{ current: WorkflowScheduleRegistration; desired: WorkflowScheduleRegistration }>;
+  remove: WorkflowScheduleRegistration[];
+};
+
+const registrationMap = (
+  name: "current" | "desired",
+  registrations: readonly WorkflowScheduleRegistration[],
+): Map<string, WorkflowScheduleRegistration> => {
+  const result = new Map<string, WorkflowScheduleRegistration>();
+  for (const registration of registrations) {
+    if (result.has(registration.id)) throw new Error(`${name} schedules contain duplicate id ${registration.id}`);
+    result.set(registration.id, registration);
+  }
+  return result;
+};
+
+const schedulesMatch = (left: WorkflowSchedule, right: WorkflowSchedule): boolean => {
+  try {
+    const normalizedLeft = normalizeWorkflowSchedule(left);
+    const normalizedRight = normalizeWorkflowSchedule(right);
+    return normalizedLeft.cron === normalizedRight.cron && normalizedLeft.timezone === normalizedRight.timezone;
+  } catch {
+    return false;
+  }
+};
+
+export const planWorkflowScheduleReconciliation = (
+  desired: readonly WorkflowScheduleRegistration[],
+  current: readonly WorkflowScheduleRegistration[],
+): WorkflowScheduleReconciliation => {
+  const desiredById = registrationMap("desired", desired);
+  const currentById = registrationMap("current", current);
+  const create = desired.filter((registration) => !currentById.has(registration.id)).sort((a, b) => a.id.localeCompare(b.id));
+  const update = desired
+    .flatMap((registration) => {
+      const existing = currentById.get(registration.id);
+      return existing && (existing.revision !== registration.revision || !schedulesMatch(existing.schedule, registration.schedule))
+        ? [{ current: existing, desired: registration }]
+        : [];
+    })
+    .sort((a, b) => a.desired.id.localeCompare(b.desired.id));
+  const remove = current.filter((registration) => !desiredById.has(registration.id)).sort((a, b) => a.id.localeCompare(b.id));
+  return { create, update, remove };
+};
+
+export interface WorkflowScheduleReconciliationPort {
+  create(registration: WorkflowScheduleRegistration): Promise<void>;
+  update(current: WorkflowScheduleRegistration, desired: WorkflowScheduleRegistration): Promise<void>;
+  register(registration: WorkflowScheduleRegistration): Promise<void>;
+  remove(registration: WorkflowScheduleRegistration): Promise<void>;
+}
+
+export const reconcileWorkflowSchedules = async (input: {
+  desired: readonly WorkflowScheduleRegistration[];
+  current: readonly WorkflowScheduleRegistration[];
+  port: WorkflowScheduleReconciliationPort;
+}): Promise<WorkflowScheduleReconciliation> => {
+  const plan = planWorkflowScheduleReconciliation(input.desired, input.current);
+  const changed = new Set([...plan.create.map((registration) => registration.id), ...plan.update.map((item) => item.desired.id)]);
+  for (const registration of plan.create) await input.port.create(registration);
+  for (const item of plan.update) await input.port.update(item.current, item.desired);
+  for (const registration of input.desired.filter((item) => !changed.has(item.id)).sort((a, b) => a.id.localeCompare(b.id))) {
+    await input.port.register(registration);
+  }
+  for (const registration of plan.remove) await input.port.remove(registration);
+  return plan;
+};

package/src/workflows/runtime/trigger.ts

@@ -0,0 +1,37 @@
+import type { WorkflowJsonValue } from "../contracts";
+import { parseWorkflowValueString } from "../language";
+import { readWorkflowValuePath } from "../language/references";
+
+const readTriggerPath = (values: Record<string, WorkflowJsonValue>, reference: string): WorkflowJsonValue | undefined => {
+  const segments = reference.split(".");
+  if (segments.shift() !== "trigger") return undefined;
+  return readWorkflowValuePath(values, segments);
+};
+
+const evaluateTriggerValue = (
+  value: WorkflowJsonValue,
+  values: Record<string, WorkflowJsonValue>,
+  occurredAt: string,
+): WorkflowJsonValue => {
+  if (typeof value === "string") {
+    const parsed = parseWorkflowValueString(value);
+    if (parsed.kind === "literal") return value;
+    if (parsed.kind === "invalid") throw new Error(`invalid workflow trigger expression "${value}"`);
+    if (parsed.expression.kind === "now") return occurredAt;
+    const resolved = readTriggerPath(values, parsed.expression.reference);
+    if (resolved === undefined) throw new Error(`workflow trigger value "${parsed.expression.reference}" is unavailable`);
+    return resolved;
+  }
+  if (Array.isArray(value)) return value.map((item) => evaluateTriggerValue(item, values, occurredAt));
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, evaluateTriggerValue(item, values, occurredAt)]));
+  }
+  return value;
+};
+
+export const evaluateWorkflowTriggerInputs = (
+  values: Record<string, WorkflowJsonValue>,
+  bindings: Record<string, WorkflowJsonValue>,
+  occurredAt: string,
+): Record<string, WorkflowJsonValue> =>
+  Object.fromEntries(Object.entries(bindings).map(([name, value]) => [name, evaluateTriggerValue(value, values, occurredAt)]));

package/src/workflows/runtime/wake.ts

@@ -0,0 +1,13 @@
+export type WorkflowRunWake = (runId: string) => Promise<void>;
+
+export const wakeWorkflowRunBestEffort = async (input: {
+  runId: string;
+  wake: WorkflowRunWake;
+  onError(error: unknown): void;
+}): Promise<void> => {
+  try {
+    await input.wake(input.runId);
+  } catch (error) {
+    input.onError(error);
+  }
+};