@k2b/cloud 0.6.0-rc.0

package/src/workflows/language/expressions.ts

@@ -0,0 +1,34 @@
+const EXACT_EXPRESSION = /^\$\{\{\s*([^{}]+?)\s*\}\}$/;
+const EMBEDDED_EXPRESSION = /\$\{\{\s*([^{}]+?)\s*\}\}/g;
+const REFERENCE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[^{}]+)?$/;
+
+export type WorkflowValueExpression = { kind: "now" } | { kind: "reference"; reference: string };
+
+export type WorkflowValueString = { kind: "literal" } | { kind: "invalid" } | { kind: "expression"; expression: WorkflowValueExpression };
+
+const parseExpression = (source: string): WorkflowValueExpression | null => {
+  const expression = source.trim();
+  if (expression === "now()") return { kind: "now" };
+  return REFERENCE.test(expression) ? { kind: "reference", reference: expression } : null;
+};
+
+export const parseWorkflowValueString = (value: string): WorkflowValueString => {
+  const match = EXACT_EXPRESSION.exec(value);
+  if (!match) return value.includes("${{") ? { kind: "invalid" } : { kind: "literal" };
+  const expression = parseExpression(match[1] ?? "");
+  return expression ? { kind: "expression", expression } : { kind: "invalid" };
+};
+
+export const workflowValueExpression = (reference: string): string => `\${{ ${reference} }}`;
+
+export const workflowMessageExpressions = (
+  message: string,
+): Array<{ source: string; raw: string; index: number; expression: WorkflowValueExpression | null }> =>
+  [...message.matchAll(EMBEDDED_EXPRESSION)].map((match) => ({
+    source: match[1]?.trim() ?? "",
+    raw: match[0],
+    index: match.index ?? 0,
+    expression: parseExpression(match[1] ?? ""),
+  }));
+
+export const hasInvalidWorkflowMessageExpression = (message: string): boolean => message.replace(EMBEDDED_EXPRESSION, "").includes("${{");

package/src/workflows/language/index.ts

@@ -0,0 +1,20 @@
+export { createWorkflowManifest } from "../manifest";
+export { bindWorkflow, type WorkflowCatalogBinder, type WorkflowCatalogBinding } from "./binder";
+export { canonicalWorkflowJson, hashWorkflowJson, hashWorkflowSource, normalizeWorkflowJson } from "./canonical";
+export { type CompileWorkflowResult, compileWorkflow } from "./compiler";
+export {
+  hasInvalidWorkflowMessageExpression,
+  parseWorkflowValueString,
+  type WorkflowValueExpression,
+  type WorkflowValueString,
+  workflowMessageExpressions,
+  workflowValueExpression,
+} from "./expressions";
+export {
+  isWorkflowReservedReferenceRoot,
+  readWorkflowValuePath,
+  resolveWorkflowValuePathDescriptor,
+  WORKFLOW_RESERVED_REFERENCE_ROOTS,
+  type WorkflowValuePathDescriptor,
+} from "./references";
+export { type ParsedWorkflowYaml, type ParseWorkflowYamlResult, parseWorkflowYaml } from "./strict-yaml";

package/src/workflows/language/references.ts

@@ -0,0 +1,55 @@
+import type { WorkflowJsonValue } from "../contracts";
+
+export const WORKFLOW_RESERVED_REFERENCE_ROOTS = ["inputs", "trigger", "bindings", "context"] as const;
+
+const reservedReferenceRoots = new Set<string>(WORKFLOW_RESERVED_REFERENCE_ROOTS);
+const canonicalArrayIndex = /^(?:0|[1-9][0-9]*)$/;
+const hasOwn = (value: object, key: string): boolean => Object.prototype.hasOwnProperty.call(value, key);
+
+export const isWorkflowReservedReferenceRoot = (value: string): boolean => reservedReferenceRoots.has(value);
+
+export type WorkflowValuePathDescriptor =
+  | { kind: "scalar"; type: string }
+  | { kind: "object"; type: string; properties: Readonly<Record<string, WorkflowValuePathDescriptor>> }
+  | { kind: "array"; type: string; items: WorkflowValuePathDescriptor; elements?: readonly WorkflowValuePathDescriptor[] };
+
+const arrayIndex = (segment: string): number | null => {
+  if (!canonicalArrayIndex.test(segment)) return null;
+  const index = Number(segment);
+  return Number.isSafeInteger(index) ? index : null;
+};
+
+export const resolveWorkflowValuePathDescriptor = (
+  descriptor: WorkflowValuePathDescriptor,
+  path: readonly string[],
+): WorkflowValuePathDescriptor | null => {
+  let current = descriptor;
+  for (const segment of path) {
+    if (current.kind === "array") {
+      const index = arrayIndex(segment);
+      if (index === null) return null;
+      const item = current.elements ? current.elements[index] : current.items;
+      if (!item) return null;
+      current = item;
+      continue;
+    }
+    if (current.kind !== "object" || !hasOwn(current.properties, segment)) return null;
+    current = current.properties[segment]!;
+  }
+  return current;
+};
+
+export const readWorkflowValuePath = (value: WorkflowJsonValue, path: readonly string[]): WorkflowJsonValue | undefined => {
+  let current: WorkflowJsonValue | undefined = value;
+  for (const segment of path) {
+    if (Array.isArray(current)) {
+      const index = arrayIndex(segment);
+      if (index === null || index >= current.length) return undefined;
+      current = current[index];
+      continue;
+    }
+    if (current === null || typeof current !== "object" || !hasOwn(current, segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+};

package/src/workflows/language/schema.ts

@@ -0,0 +1,134 @@
+import type { WorkflowDiagnostic, WorkflowFieldSchema, WorkflowJsonValue, WorkflowSourceLocation } from "../contracts";
+import { workflowPathKey } from "../contracts";
+
+const isRecord = (value: unknown): value is Record<string, WorkflowJsonValue> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const locationForPath = (
+  path: Array<string | number>,
+  locations: Record<string, WorkflowSourceLocation>,
+): WorkflowSourceLocation | undefined => {
+  for (let length = path.length; length >= 0; length -= 1) {
+    const location = locations[workflowPathKey(path.slice(0, length))];
+    if (location) return location;
+  }
+  return undefined;
+};
+
+const addDiagnostic = (
+  diagnostics: WorkflowDiagnostic[],
+  code: string,
+  message: string,
+  path: Array<string | number>,
+  locations: Record<string, WorkflowSourceLocation>,
+): void => {
+  const location = locationForPath(path, locations);
+  diagnostics.push({ code, message, severity: "error", path, ...(location ? { location } : {}) });
+};
+
+const describeType = (schema: WorkflowFieldSchema): string => {
+  if (schema.kind === "value") return "JSON value";
+  if (schema.kind === "record") return "object";
+  return schema.kind;
+};
+
+export const validateWorkflowField = (
+  value: WorkflowJsonValue,
+  schema: WorkflowFieldSchema,
+  path: Array<string | number>,
+  locations: Record<string, WorkflowSourceLocation>,
+  diagnostics: WorkflowDiagnostic[],
+): void => {
+  const typeError = (): void => addDiagnostic(diagnostics, "schema.type", `Expected ${describeType(schema)}`, path, locations);
+
+  if (schema.kind === "value") return;
+  if (schema.kind === "string") {
+    if (typeof value !== "string") return typeError();
+    if (schema.enum && !schema.enum.includes(value))
+      addDiagnostic(diagnostics, "schema.enum", `Expected one of: ${schema.enum.join(", ")}`, path, locations);
+    if (schema.minLength !== undefined && value.length < schema.minLength)
+      addDiagnostic(diagnostics, "schema.minimum", `Expected at least ${schema.minLength} characters`, path, locations);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength)
+      addDiagnostic(diagnostics, "schema.maximum", `Expected at most ${schema.maxLength} characters`, path, locations);
+    if (schema.format === "identifier" && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value))
+      addDiagnostic(diagnostics, "schema.format", "Expected an identifier", path, locations);
+    if (schema.format === "uri") {
+      try {
+        new URL(value);
+      } catch {
+        addDiagnostic(diagnostics, "schema.format", "Expected an absolute URI", path, locations);
+      }
+    }
+    return;
+  }
+  if (schema.kind === "number") {
+    if (typeof value !== "number") return typeError();
+    if (schema.integer && !Number.isInteger(value)) addDiagnostic(diagnostics, "schema.integer", "Expected an integer", path, locations);
+    if (schema.minimum !== undefined && value < schema.minimum)
+      addDiagnostic(diagnostics, "schema.minimum", `Expected a value of at least ${schema.minimum}`, path, locations);
+    if (schema.maximum !== undefined && value > schema.maximum)
+      addDiagnostic(diagnostics, "schema.maximum", `Expected a value of at most ${schema.maximum}`, path, locations);
+    return;
+  }
+  if (schema.kind === "boolean") {
+    if (typeof value !== "boolean") typeError();
+    return;
+  }
+  if (schema.kind === "array") {
+    if (!Array.isArray(value)) return typeError();
+    if (schema.minItems !== undefined && value.length < schema.minItems)
+      addDiagnostic(diagnostics, "schema.minimum", `Expected at least ${schema.minItems} items`, path, locations);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems)
+      addDiagnostic(diagnostics, "schema.maximum", `Expected at most ${schema.maxItems} items`, path, locations);
+    value.forEach((item, index) => validateWorkflowField(item, schema.items, [...path, index], locations, diagnostics));
+    return;
+  }
+  if (schema.kind === "record") {
+    if (!isRecord(value)) return typeError();
+    const keys = Object.keys(value);
+    if (schema.minProperties !== undefined && keys.length < schema.minProperties)
+      addDiagnostic(diagnostics, "schema.minimum", `Expected at least ${schema.minProperties} properties`, path, locations);
+    if (schema.maxProperties !== undefined && keys.length > schema.maxProperties)
+      addDiagnostic(diagnostics, "schema.maximum", `Expected at most ${schema.maxProperties} properties`, path, locations);
+    keys.forEach((key) => validateWorkflowField(value[key]!, schema.values, [...path, key], locations, diagnostics));
+    return;
+  }
+  if (schema.kind === "object") {
+    if (!isRecord(value)) return typeError();
+    for (const key of Object.keys(value)) {
+      if (!schema.properties[key]) addDiagnostic(diagnostics, "schema.unknown", `Unknown property "${key}"`, [...path, key], locations);
+    }
+    for (const [key, propertySchema] of Object.entries(schema.properties)) {
+      const property = value[key];
+      if (property === undefined) {
+        if (!propertySchema.optional)
+          addDiagnostic(diagnostics, "schema.required", `Missing required property "${key}"`, [...path, key], locations);
+      } else {
+        validateWorkflowField(property, propertySchema, [...path, key], locations, diagnostics);
+      }
+    }
+    return;
+  }
+
+  const variants = schema.variants.map((variant) => {
+    const variantDiagnostics: WorkflowDiagnostic[] = [];
+    validateWorkflowField(value, variant, path, locations, variantDiagnostics);
+    return variantDiagnostics;
+  });
+  if (variants.some((variant) => variant.length === 0)) return;
+  const best = variants.reduce((left, right) => (right.length < left.length ? right : left));
+  diagnostics.push(...best);
+};
+
+export const workflowDiagnostic = (
+  code: string,
+  message: string,
+  path: Array<string | number>,
+  locations: Record<string, WorkflowSourceLocation>,
+): WorkflowDiagnostic => {
+  const diagnostics: WorkflowDiagnostic[] = [];
+  addDiagnostic(diagnostics, code, message, path, locations);
+  return diagnostics[0]!;
+};
+
+export const workflowRecord = isRecord;

package/src/workflows/language/strict-yaml.ts

@@ -0,0 +1,131 @@
+import { isAlias, isMap, isNode, isScalar, isSeq, LineCounter, parseDocument } from "yaml";
+import type { WorkflowDiagnostic, WorkflowJsonValue, WorkflowSourceLocation } from "../contracts";
+import { workflowPathKey } from "../contracts";
+
+export type ParsedWorkflowYaml = {
+  value: WorkflowJsonValue;
+  sourceLocations: Record<string, WorkflowSourceLocation>;
+};
+
+export type ParseWorkflowYamlResult = { ok: true; parsed: ParsedWorkflowYaml } | { ok: false; diagnostics: WorkflowDiagnostic[] };
+
+const locationAt = (lineCounter: LineCounter, offset: number): WorkflowSourceLocation => {
+  const { line, col } = lineCounter.linePos(offset);
+  return { offset, line, column: col };
+};
+
+const errorLocation = (lineCounter: LineCounter, error: unknown): WorkflowSourceLocation | undefined => {
+  const offset = (error as { pos?: number[] }).pos?.[0];
+  return typeof offset === "number" ? locationAt(lineCounter, offset) : undefined;
+};
+
+const diagnostic = (
+  code: string,
+  message: string,
+  path: Array<string | number>,
+  location?: WorkflowSourceLocation,
+): WorkflowDiagnostic => ({ code, message, severity: "error", path, ...(location ? { location } : {}) });
+
+type DecodeContext = {
+  lineCounter: LineCounter;
+  locations: Record<string, WorkflowSourceLocation>;
+  diagnostics: WorkflowDiagnostic[];
+};
+
+const nodeLocation = (node: unknown, context: DecodeContext): WorkflowSourceLocation | undefined => {
+  const offset = isNode(node) ? node.range?.[0] : undefined;
+  return typeof offset === "number" ? locationAt(context.lineCounter, offset) : undefined;
+};
+
+const recordLocation = (node: unknown, path: Array<string | number>, context: DecodeContext): void => {
+  const location = nodeLocation(node, context);
+  const key = workflowPathKey(path);
+  if (location && context.locations[key] === undefined) context.locations[key] = location;
+};
+
+const decodeNode = (node: unknown, path: Array<string | number>, context: DecodeContext): WorkflowJsonValue | undefined => {
+  recordLocation(node, path, context);
+  const location = nodeLocation(node, context);
+
+  if (node === null) return null;
+  if (!isNode(node)) {
+    context.diagnostics.push(diagnostic("yaml.node", "Unsupported YAML node", path, location));
+    return undefined;
+  }
+  if (isAlias(node)) {
+    context.diagnostics.push(diagnostic("yaml.alias", "YAML aliases are not allowed", path, location));
+    return undefined;
+  }
+  if (node.anchor) {
+    context.diagnostics.push(diagnostic("yaml.anchor", "YAML anchors are not allowed", path, location));
+    return undefined;
+  }
+  if (node.tag) {
+    context.diagnostics.push(diagnostic("yaml.tag", "Explicit YAML tags are not allowed", path, location));
+    return undefined;
+  }
+
+  if (isScalar(node)) {
+    const value = node.value;
+    if (value === null) return null;
+    if (typeof value === "string" || typeof value === "boolean") return value;
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+    context.diagnostics.push(diagnostic("yaml.value", "YAML value must be valid JSON", path, location));
+    return undefined;
+  }
+
+  if (isSeq(node)) {
+    const result: WorkflowJsonValue[] = [];
+    node.items.forEach((item, index) => {
+      const value = decodeNode(item, [...path, index], context);
+      if (value !== undefined) result.push(value);
+    });
+    return result;
+  }
+
+  if (isMap(node)) {
+    const entries: Array<[string, WorkflowJsonValue]> = [];
+    for (const pair of node.items) {
+      if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
+        context.diagnostics.push(diagnostic("yaml.key", "YAML object keys must be strings", path, nodeLocation(pair.key, context)));
+        continue;
+      }
+      const key = pair.key.value;
+      const childPath = [...path, key];
+      recordLocation(pair.key, childPath, context);
+      const value = decodeNode(pair.value, childPath, context);
+      if (value !== undefined) entries.push([key, value]);
+    }
+    return Object.fromEntries(entries) as Record<string, WorkflowJsonValue>;
+  }
+
+  context.diagnostics.push(diagnostic("yaml.node", "Unsupported YAML node", path, location));
+  return undefined;
+};
+
+export const parseWorkflowYaml = (source: string): ParseWorkflowYamlResult => {
+  const lineCounter = new LineCounter();
+  const document = parseDocument(source, {
+    lineCounter,
+    prettyErrors: false,
+    schema: "core",
+    strict: true,
+    uniqueKeys: true,
+  });
+
+  const parseDiagnostics = [...document.errors, ...document.warnings].map((error) =>
+    diagnostic("yaml.parse", error.message, [], errorLocation(lineCounter, error)),
+  );
+  if (parseDiagnostics.length > 0) return { ok: false, diagnostics: parseDiagnostics };
+
+  const context: DecodeContext = { lineCounter, locations: {}, diagnostics: [] };
+  const value = decodeNode(document.contents, [], context);
+  if (context.diagnostics.length > 0) return { ok: false, diagnostics: context.diagnostics };
+  if (value === undefined || value === null || typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      diagnostics: [diagnostic("workflow.root", "Workflow source must be a YAML object", [], context.locations[""])],
+    };
+  }
+  return { ok: true, parsed: { value, sourceLocations: context.locations } };
+};

package/src/workflows/manifest.ts

@@ -0,0 +1,24 @@
+import { workflowBuiltinActionDescriptors } from "./builtins";
+import type { WorkflowActionDescriptor, WorkflowLanguageManifest } from "./contracts";
+import { LANGUAGE_EFFECT, type WorkflowActionMap } from "./definition";
+
+type WorkflowActionMetadata = Record<string, Pick<WorkflowActionMap[string], "label" | "description" | "config" | "effect" | "outputType">>;
+
+const workflowActionDescriptors = (actions: WorkflowActionMetadata): WorkflowActionDescriptor[] =>
+  Object.entries(actions).map(([key, action]) => ({
+    kind: key,
+    label: action.label,
+    description: action.description,
+    config: action.config,
+    effect: LANGUAGE_EFFECT[action.effect],
+    ...(action.outputType ? { outputType: action.outputType } : {}),
+    dryRun: action.effect === "pure" ? "full" : "validate",
+  }));
+
+/** Build authoring metadata without importing action implementations. */
+export const createWorkflowManifest = (
+  definition: Omit<WorkflowLanguageManifest, "actions"> & { actions: WorkflowActionMetadata },
+): WorkflowLanguageManifest => {
+  const { actions, ...language } = definition;
+  return { ...language, actions: [...workflowActionDescriptors(actions), ...workflowBuiltinActionDescriptors] };
+};

package/src/workflows/module.ts

@@ -0,0 +1,12 @@
+import type { WorkflowLanguageManifest } from "./contracts";
+import type { WorkflowActionMap } from "./definition";
+import { createWorkflowManifest } from "./manifest";
+
+export type DefinedWorkflowModule<Actions extends WorkflowActionMap = WorkflowActionMap> = {
+  actions: Actions;
+  manifest: WorkflowLanguageManifest;
+};
+
+export const defineWorkflowModule = <const Actions extends WorkflowActionMap>(
+  definition: Omit<WorkflowLanguageManifest, "actions"> & { actions: Actions },
+): DefinedWorkflowModule<Actions> => ({ actions: definition.actions, manifest: createWorkflowManifest(definition) });

package/src/workflows/runtime/coordinator.ts

@@ -0,0 +1,115 @@
+export type WorkflowCoordinatorClaim = {
+  runId: string;
+  executionGeneration: number;
+};
+
+export type WorkflowCoordinatorLeaseState = { state: "active" } | { state: "stale" } | { state: "canceled"; message?: string };
+
+export type WorkflowCoordinatorFinishState = { state: "finished" } | { state: "stale" } | { state: "canceled"; message?: string };
+
+export type WorkflowCoordinatorReleaseState =
+  | { state: "released" }
+  | { state: "retry"; retryAt?: string }
+  | { state: "stale" }
+  | { state: "canceled"; message?: string };
+
+export interface WorkflowCoordinatorPort<TInput, TClaim extends WorkflowCoordinatorClaim, TResult> {
+  claim(input: TInput): Promise<TClaim | null>;
+  renew(claim: TClaim): Promise<WorkflowCoordinatorLeaseState>;
+  finish(claim: TClaim, result: TResult): Promise<WorkflowCoordinatorFinishState>;
+  release(claim: TClaim, error: unknown): Promise<WorkflowCoordinatorReleaseState>;
+}
+
+export type WorkflowCoordinatorExecution<TClaim extends WorkflowCoordinatorClaim> = {
+  claim: TClaim;
+  signal: AbortSignal;
+  heartbeat(): Promise<WorkflowCoordinatorLeaseState>;
+};
+
+export type WorkflowCoordinatorResult<TClaim extends WorkflowCoordinatorClaim, TResult> =
+  | { state: "idle" }
+  | { state: "finished"; claim: TClaim; result: TResult }
+  | { state: "released"; claim: TClaim; error: unknown }
+  | { state: "retry"; claim: TClaim; error: unknown; retryAt?: string }
+  | { state: "stale"; claim: TClaim }
+  | { state: "canceled"; claim: TClaim; message?: string };
+
+const stoppedResult = <TClaim extends WorkflowCoordinatorClaim>(
+  claim: TClaim,
+  state: Exclude<WorkflowCoordinatorLeaseState, { state: "active" }>,
+): WorkflowCoordinatorResult<TClaim, never> =>
+  state.state === "stale" ? { state: "stale", claim } : { state: "canceled", claim, message: state.message };
+
+export const coordinateWorkflowExecution = async <TInput, TClaim extends WorkflowCoordinatorClaim, TResult>(options: {
+  input: TInput;
+  heartbeatMs: number;
+  port: WorkflowCoordinatorPort<TInput, TClaim, TResult>;
+  execute(execution: WorkflowCoordinatorExecution<TClaim>): Promise<TResult>;
+}): Promise<WorkflowCoordinatorResult<TClaim, TResult>> => {
+  if (!Number.isSafeInteger(options.heartbeatMs) || options.heartbeatMs <= 0) {
+    throw new Error("heartbeatMs must be a positive integer");
+  }
+
+  const claim = await options.port.claim(options.input);
+  if (!claim) return { state: "idle" };
+
+  const controller = new AbortController();
+  let stopped = false;
+  let leaseState: WorkflowCoordinatorLeaseState = { state: "active" };
+  let renewal: Promise<WorkflowCoordinatorLeaseState> | null = null;
+  let renewalError: unknown;
+
+  const heartbeat = (): Promise<WorkflowCoordinatorLeaseState> => {
+    if (stopped) return Promise.resolve(leaseState);
+    if (leaseState.state !== "active") return Promise.resolve(leaseState);
+    if (renewal) return renewal;
+    renewal = Promise.resolve()
+      .then(() => options.port.renew(claim))
+      .then((next) => {
+        leaseState = next;
+        if (next.state !== "active") controller.abort(next);
+        return next;
+      })
+      .catch((error) => {
+        renewalError ??= error;
+        controller.abort(error);
+        throw error;
+      })
+      .finally(() => {
+        renewal = null;
+      });
+    return renewal;
+  };
+
+  const timer = setInterval(() => {
+    if (!stopped) void heartbeat().catch(() => undefined);
+  }, options.heartbeatMs);
+
+  let result!: TResult;
+  let executionError: unknown;
+  let executionFailed = false;
+  try {
+    result = await options.execute({ claim, signal: controller.signal, heartbeat });
+  } catch (error) {
+    executionFailed = true;
+    executionError = error;
+  } finally {
+    stopped = true;
+    clearInterval(timer);
+    await (renewal as Promise<WorkflowCoordinatorLeaseState> | null)?.catch(() => undefined);
+  }
+
+  if (leaseState.state !== "active") return stoppedResult(claim, leaseState);
+
+  if (executionFailed || renewalError !== undefined) {
+    const error = renewalError ?? executionError;
+    const released = await options.port.release(claim, error);
+    if (released.state === "stale" || released.state === "canceled") return stoppedResult(claim, released);
+    if (released.state === "released") return { state: "released", claim, error };
+    return { state: "retry", claim, error, ...(released.retryAt ? { retryAt: released.retryAt } : {}) };
+  }
+
+  const finished = await options.port.finish(claim, result);
+  if (finished.state !== "finished") return stoppedResult(claim, finished);
+  return { state: "finished", claim, result };
+};