@xemahq/dsl 0.8.0 → 0.8.2

package/src/workflow/lib/compiler/concurrency.ts

@@ -1,223 +0,0 @@
-import {
-  WorkflowErrorCode,
-  WorkflowTriggerKind,
-  type ConcurrencyGroup,
-  type TriggerPayload,
-} from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-import type { WorkflowConcurrencyDeclaration } from '../types';
-import {
-  EMPTY_CONTEXT_SEEDS,
-  XemaActorKind,
-  compileExpression,
-  evaluateExpression,
-  parseTemplate,
-  TemplateSegmentKind,
-  type ExpressionContext,
-  type ExpressionNode,
-  type TemplateSegment,
-} from '../expression';
-
-/**
- * Deterministically expand the authored concurrency `group` template into a
- * concrete lease key. Two passes:
- *
- *   1. **Compile time** (`compileConcurrencyGroupTemplate`): tokenize and
- *      pre-compile every embedded expression. Authoring errors fire here so
- *      they block snapshot creation, not dispatch.
- *   2. **Dispatch time** (`expandCompiledConcurrencyTemplate`): evaluate each
- *      pre-compiled expression against the trigger / inputs / vars context
- *      and stitch the literal + evaluated segments back together.
- *
- * Concurrency `group` is the one DSL field that opts in to partial
- * interpolation (`product-development:${{ inputs.projectId }}`). Every
- * other authored expression site enforces the "fully wrapped or pure
- * literal" policy through `extractInterpolations` — see `compile.ts`.
- */
-
-interface CompiledTemplateExpressionSegment {
-  readonly kind: TemplateSegmentKind.Expression;
-  readonly source: string;
-  readonly node: ExpressionNode;
-}
-
-interface CompiledTemplateLiteralSegment {
-  readonly kind: TemplateSegmentKind.Literal;
-  readonly value: string;
-}
-
-type CompiledTemplateSegment =
-  | CompiledTemplateExpressionSegment
-  | CompiledTemplateLiteralSegment;
-
-/**
- * Tokenize and pre-compile every interpolation in the authored template.
- * Pure function: same input always yields the same compiled segments.
- */
-function compileConcurrencyGroupTemplate(
-  authored: string,
-): readonly CompiledTemplateSegment[] {
-  const segments = parseTemplate(authored, ['concurrency', 'group']);
-  return segments.map((segment) => compileSegment(segment));
-}
-
-function compileSegment(segment: TemplateSegment): CompiledTemplateSegment {
-  if (segment.kind === TemplateSegmentKind.Literal) {
-    return { kind: TemplateSegmentKind.Literal, value: segment.value };
-  }
-  return {
-    kind: TemplateSegmentKind.Expression,
-    source: segment.source,
-    node: compileExpression(segment.source),
-  };
-}
-
-function expandCompiledConcurrencyTemplate(
-  authored: string,
-  segments: readonly CompiledTemplateSegment[],
-  ctx: ExpressionContext,
-): string {
-  const out: string[] = [];
-  for (const segment of segments) {
-    if (segment.kind === TemplateSegmentKind.Literal) {
-      out.push(segment.value);
-      continue;
-    }
-    const value = evaluateExpression(segment.node, ctx);
-    out.push(stringifyConcurrencyValue(authored, segment.source, value));
-  }
-  return out.join('');
-}
-
-function stringifyConcurrencyValue(
-  authored: string,
-  expressionSource: string,
-  value: unknown,
-): string {
-  if (value === null || value === undefined) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Concurrency group expression '${expressionSource}' resolved to ${value === null ? 'null' : 'undefined'} — refuse to build an ambiguous lease key.`,
-      { authored, expression: expressionSource },
-    );
-  }
-  if (
-    typeof value !== 'string' &&
-    typeof value !== 'number' &&
-    typeof value !== 'boolean'
-  ) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Concurrency group expression '${expressionSource}' must resolve to string/number/boolean; got ${typeof value}.`,
-      { authored, expression: expressionSource, resultKind: typeof value },
-    );
-  }
-  return String(value);
-}
-
-function buildConcurrencyContext(
-  trigger: TriggerPayload,
-  inputs: Readonly<Record<string, unknown>>,
-  vars: Readonly<Record<string, unknown>>,
-): ExpressionContext {
-  // Concurrency runs before any job: no `needs`, no matrix, no `job`.
-  // `xema.*` is seeded with the run-level identity available at this
-  // point (org/project/correlation/actor) so authors may key concurrency
-  // groups off `xema.org.id` or `xema.project.id` without reaching into
-  // trigger metadata.
-  return {
-    needs: EMPTY_CONTEXT_SEEDS.needs,
-    matrix: EMPTY_CONTEXT_SEEDS.matrix,
-    inputs,
-    vars,
-    secrets: EMPTY_CONTEXT_SEEDS.secrets,
-    trigger,
-    job: EMPTY_CONTEXT_SEEDS.job,
-    payloadCache: EMPTY_CONTEXT_SEEDS.payloadCache,
-    xema: {
-      org: { id: trigger.orgId },
-      project: { id: trigger.projectId },
-      run: {
-        id: '',
-        attempt: 0,
-        startedAtIso: trigger.triggeredAt,
-        correlationId: trigger.correlationId,
-        actor: {
-          subject: trigger.actorSubject,
-          kind: actorKindFromTrigger(trigger),
-        },
-      },
-      workflow: { key: '', revisionNumber: 0 },
-      job: { key: '', attempt: 0 },
-    },
-  };
-}
-
-function actorKindFromTrigger(trigger: TriggerPayload): XemaActorKind {
-  if (trigger.actorSubject) return XemaActorKind.User;
-  switch (trigger.kind) {
-    case WorkflowTriggerKind.WEBHOOK:
-      return XemaActorKind.Webhook;
-    case WorkflowTriggerKind.SCHEDULE:
-      return XemaActorKind.Schedule;
-    default:
-      return XemaActorKind.System;
-  }
-}
-
-/**
- * Compile + expand the authored concurrency declaration into the runtime
- * `ConcurrencyGroup`. Returns `null` when the workflow declares no
- * concurrency at all.
- *
- * Compile-time errors (malformed template, malformed expression body) and
- * dispatch-time errors (expression evaluates to null/undefined or a
- * non-stringifiable type, expanded key is empty) all surface as typed
- * `WorkflowDslError`s — never silently degraded to a default group.
- */
-export function compileConcurrency(
-  declaration: WorkflowConcurrencyDeclaration | undefined,
-  trigger: TriggerPayload,
-  inputs: Readonly<Record<string, unknown>>,
-  vars: Readonly<Record<string, unknown>>,
-): ConcurrencyGroup | null {
-  if (!declaration) return null;
-
-  const compiledSegments = compileConcurrencyGroupTemplate(declaration.group);
-  const ctx = buildConcurrencyContext(trigger, inputs, vars);
-  const leaseKey = expandCompiledConcurrencyTemplate(
-    declaration.group,
-    compiledSegments,
-    ctx,
-  );
-
-  if (leaseKey.length === 0) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Concurrency group expression '${declaration.group}' expanded to an empty string.`,
-      { authored: declaration.group },
-    );
-  }
-
-  return {
-    leaseKey,
-    mode: declaration.mode,
-  };
-}
-
-/**
- * Compile-time-only validation hook: parse and pre-compile the concurrency
- * template so authoring errors block snapshot creation. Used by
- * `validateAllAuthoredExpressions` in the main compiler pass; the result is
- * discarded because the dispatch path recompiles from the same source
- * (determinism is preserved by the canonical workflow document hash).
- */
-export function validateConcurrencyGroupTemplate(
-  declaration: WorkflowConcurrencyDeclaration | undefined,
-): void {
-  if (!declaration) return;
-  // Parse + compile every embedded expression; throw on any syntax error.
-  // The returned segments are intentionally discarded — the dispatch path
-  // recompiles from the same source string (deterministic).
-  compileConcurrencyGroupTemplate(declaration.group);
-}

package/src/workflow/lib/compiler/dag.ts

@@ -1,108 +0,0 @@
-import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-
-/**
- * Topological sort for the job DAG. Returns jobs in a stable order where
- * every job appears after all its `needs` predecessors.
- *
- * Cycle detection: Kahn's algorithm. If any node remains after the queue
- * drains, there's a cycle. Stable order: within each ready set, jobs are
- * visited in input order (so authoring order drives UI layout).
- *
- * Missing-need detection: if any `needs` entry references a jobKey that
- * isn't in the graph, fail fast (can't be silently dropped — would hide
- * a copy-paste bug).
- */
-export function topologicalSort<T>(
-  nodes: readonly { key: string; payload: T; needs: readonly string[] }[],
-): readonly { key: string; payload: T; needs: readonly string[] }[] {
-  const byKey = new Map<string, { key: string; payload: T; needs: readonly string[] }>();
-  const inputOrder = new Map<string, number>();
-  nodes.forEach((node, i) => {
-    if (byKey.has(node.key)) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Duplicate job key: ${node.key}`,
-        { key: node.key },
-      );
-    }
-    byKey.set(node.key, node);
-    inputOrder.set(node.key, i);
-  });
-
-  // Validate needs references before building indegree — unknown refs are
-  // a structural error, not a cycle error.
-  for (const node of nodes) {
-    for (const needKey of node.needs) {
-      if (!byKey.has(needKey)) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Job '${node.key}' declares needs: [${needKey}] but no such job exists.`,
-          { jobKey: node.key, missingNeed: needKey },
-        );
-      }
-      if (needKey === node.key) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_CYCLE_DETECTED,
-          `Job '${node.key}' cannot depend on itself.`,
-          { jobKey: node.key },
-        );
-      }
-    }
-  }
-
-  const indegree = new Map<string, number>();
-  const dependents = new Map<string, string[]>();
-  for (const node of nodes) {
-    indegree.set(node.key, node.needs.length);
-    dependents.set(node.key, []);
-  }
-  for (const node of nodes) {
-    for (const needKey of node.needs) {
-      dependents.get(needKey)!.push(node.key);
-    }
-  }
-
-  const ready: string[] = [];
-  for (const [key, d] of indegree) {
-    if (d === 0) ready.push(key);
-  }
-  stableSortByInputOrder(ready, inputOrder);
-
-  const sorted: { key: string; payload: T; needs: readonly string[] }[] = [];
-  while (ready.length > 0) {
-    const key = ready.shift()!;
-    sorted.push(byKey.get(key)!);
-    const children = dependents.get(key)!;
-    const newlyReady: string[] = [];
-    for (const child of children) {
-      const next = indegree.get(child)! - 1;
-      indegree.set(child, next);
-      if (next === 0) newlyReady.push(child);
-    }
-    stableSortByInputOrder(newlyReady, inputOrder);
-    ready.push(...newlyReady);
-    stableSortByInputOrder(ready, inputOrder);
-  }
-
-  if (sorted.length !== nodes.length) {
-    const stuck = [...indegree.entries()]
-      .filter(([, d]) => d > 0)
-      .map(([k]) => k);
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_CYCLE_DETECTED,
-      `Workflow DAG contains a cycle. Jobs in cycle or downstream of one: ${stuck.join(', ')}`,
-      { stuck },
-    );
-  }
-
-  return sorted;
-}
-
-function stableSortByInputOrder(keys: string[], inputOrder: Map<string, number>): void {
-  keys.sort((a, b) => {
-    const ai = inputOrder.get(a)!;
-    const bi = inputOrder.get(b)!;
-    return ai - bi;
-  });
-}

package/src/workflow/lib/compiler/gate-defaults.ts

@@ -1,153 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Workflow-level decision-gate defaults (`defaults.gate`) ──
-//
-// Gate-heavy workflows (e.g. the software-dev product-development pipeline)
-// repeat the same decision-gate configuration on every gate job:
-// timeoutSeconds, onTimeout, autonomyMode, recipients, policy. `defaults.gate`
-// lets the author declare that configuration ONCE at the workflow level; the
-// compiler folds it into each gate job's `with:` before any other compile
-// pass runs, so downstream validation, expression compilation, and the
-// CompiledRun snapshot all observe the merged document — expressions inside
-// defaults compile per-job exactly as if written inline.
-//
-// Merge contract (deterministic, no silent deep-merging):
-//   • Applies ONLY to jobs whose `uses:` resolves to the `xema/decision-gate`
-//     action id — matched on the resolved ref's id, regardless of version.
-//   • Fills ABSENT `with:` keys only. Explicit per-gate values always win.
-//   • Fill is per top-level key: a gate that declares its own `policy` or
-//     `recipients` keeps that value verbatim — there is no partial merge
-//     inside a key's object/array value.
-//   • Fail-fast validation: every `defaults.gate` key must be declared in
-//     the resolved gate manifest's `inputs.properties` (guards drift between
-//     the DSL schema's closed key set and the pinned gate action version).
-// ═══════════════════════════════════════════════════════════════════════════
-
-import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-import { compileExpression, extractInterpolations } from '../expression';
-import type { WorkflowDocument, WorkflowGateDefaults } from '../types';
-import type { ResolvedRef } from './types';
-
-/**
- * Canonical action id of the decision-gate primitive. `defaults.gate`
- * targets jobs by this id — never by the raw `uses:` string — so any
- * pinned version (`xema/decision-gate@1.2.0`, `@2.x`, …) participates.
- */
-export const DECISION_GATE_ACTION_ID = 'xema/decision-gate';
-
-/**
- * Fold `defaults.gate` into every decision-gate job's `with:` block and
- * return the (possibly rewritten) document. Pure: never mutates the input.
- *
- * Runs BEFORE all other compile passes so the merged `with:` flows through
- * expression validation, needs-shape validation, review rewriting, the
- * action input-schema pin, and the snapshot hash exactly like authored
- * values.
- *
- * Jobs whose `uses:` is missing from `resolvedRefs` are skipped here — the
- * per-job compile loop already fails them with `DSL_UNKNOWN_ACTION`, and
- * pre-empting that error would reorder author-facing diagnostics.
- */
-export function applyGateDefaults(
-  workflow: WorkflowDocument,
-  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
-): WorkflowDocument {
-  const gate = workflow.defaults?.gate;
-  if (gate === undefined) return workflow;
-  const gateEntries = Object.entries(gate).filter(
-    ([, value]) => value !== undefined,
-  );
-  if (gateEntries.length === 0) return workflow;
-
-  // Validate every `${{ … }}` expression inside the defaults block up
-  // front — even when no gate job consumes it. A malformed expression in
-  // `defaults.gate` is an authoring error regardless of merge fan-out;
-  // deferring it until a gate job appears would be a silent latency.
-  for (const ext of extractInterpolations(
-    gate as Readonly<Record<string, unknown>>,
-    ['defaults', 'gate'],
-  )) {
-    compileExpression(ext.source);
-  }
-
-  let anyChanged = false;
-  const rewrittenJobs: Record<string, WorkflowDocument['jobs'][string]> = {};
-  for (const [jobKey, job] of Object.entries(workflow.jobs)) {
-    const resolved = resolvedRefs[job.uses];
-    if (
-      resolved === undefined ||
-      resolved.isReusableWorkflow ||
-      resolved.id !== DECISION_GATE_ACTION_ID
-    ) {
-      rewrittenJobs[jobKey] = job;
-      continue;
-    }
-
-    assertGateDefaultKeysDeclared(jobKey, gate, resolved);
-
-    const authored = job.with ?? {};
-    let jobChanged = false;
-    const merged: Record<string, unknown> = { ...authored };
-    for (const [key, value] of gateEntries) {
-      if (Object.hasOwn(authored, key)) continue;
-      merged[key] = value;
-      jobChanged = true;
-    }
-    if (!jobChanged) {
-      rewrittenJobs[jobKey] = job;
-      continue;
-    }
-    anyChanged = true;
-    rewrittenJobs[jobKey] = { ...job, with: merged };
-  }
-
-  if (!anyChanged) return workflow;
-  return { ...workflow, jobs: rewrittenJobs };
-}
-
-/**
- * Fail-fast subset check: every `defaults.gate` key must be a declared
- * input of the resolved gate action version. The JSON schema already
- * closes the key set to the canonical decision-gate input names; this
- * check guards manifest drift (e.g. a future gate version renaming or
- * dropping an input while a workflow still defaults it).
- *
- * Skipped only when the manifest declares no introspectable
- * `inputs.properties` map — nothing to prove against; the worker's
- * pinned input-schema validation still rejects unknown keys at dispatch.
- */
-function assertGateDefaultKeysDeclared(
-  jobKey: string,
-  gate: WorkflowGateDefaults,
-  resolved: ResolvedRef,
-): void {
-  const inputs = resolved.actionManifest?.spec.inputs;
-  const properties =
-    inputs && typeof inputs === 'object'
-      ? (inputs as { properties?: unknown }).properties
-      : undefined;
-  if (
-    properties === null ||
-    properties === undefined ||
-    typeof properties !== 'object' ||
-    Array.isArray(properties)
-  ) {
-    return;
-  }
-  const declared = properties as Readonly<Record<string, unknown>>;
-  for (const [key, value] of Object.entries(gate)) {
-    if (value === undefined) continue;
-    if (Object.hasOwn(declared, key)) continue;
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `defaults.gate.${key} is not a declared input of ${resolved.id}@${resolved.version} (consumed by job '${jobKey}'). Declared inputs: [${Object.keys(declared).sort((a, b) => a.localeCompare(b)).join(', ')}].`,
-      {
-        jobKey,
-        key,
-        actionId: resolved.id,
-        actionVersion: resolved.version,
-        declaredInputs: Object.keys(declared),
-      },
-    );
-  }
-}

package/src/workflow/lib/compiler/index.ts

@@ -1,11 +0,0 @@
-export { compileWorkflow } from './compile';
-export { DECISION_GATE_ACTION_ID, applyGateDefaults } from './gate-defaults';
-export { canonicalJsonSha256, canonicalJsonStringify } from './canonical-json';
-export { compileManifestSource } from './manifest-source';
-export { getWorkspaceManifestContract, isAgentShapedAction } from './action-shape';
-export type {
-  CompileInput,
-  ResolvedAgentMeta,
-  ResolvedDeliverableSpec,
-  ResolvedRef,
-} from './types';