@xemahq/dsl 0.8.0 → 0.8.2

package/src/workflow/lib/compiler/review-step.ts

@@ -1,548 +0,0 @@
-/**
- * Compile-time helpers for `xema/review@*` steps.
- *
- * The review action's author surface is intentionally small:
- *
- *   uses: xema/review@<semver>
- *   needs: [<producer>]
- *   with:
- *     subject: ${{ needs.<producer>.outputs.deliverable }}   # or an array
- *     redraft: { step: <producer> }                          # optional
- *     reviewers: [...]
- *     policy: { kind: ... }
- *     iterationTimeoutSeconds: ...
- *     onIterationTimeout: ...
- *
- * The worker contract on `reviewWorkflow` is different: it expects
- * `subjects: unknown[]` (always-array) and `redraft: { uses, with }`
- * (embedded action invocation, not a step ref). This module bridges
- * the two:
- *
- *   1. `validateReviewSteps` — throws on bad author shapes BEFORE
- *      anything else compiles. Catches missing/dangling step refs,
- *      shape mismatches, and the forbidden `redraft set without
- *      subject` combination.
- *
- *   2. `computeReviewNeedsExtensions` — returns a map of
- *      `reviewJobKey → string[]` of extra needs the compiler must add
- *      so the review step's expression context (built from `needs:` at
- *      dispatch) can resolve every `${{ needs.* }}` reference embedded
- *      in the redraft step's inherited `with:` block. Authors don't
- *      have to repeat the producer's transitive needs by hand.
- *
- *   3. `rewriteReviewStepWith` — produces the IR `with:` for a review
- *      step: `subject` normalized to `subjects: unknown[]`, and
- *      `redraft.step` resolved into the named producer's
- *      `{ uses, with }`.
- *
- * The action manifest's input schema (in built-in-action-manifests.ts)
- * describes the AUTHOR shape. The IR shape produced here is the
- * worker's runtime contract — they intentionally diverge.
- */
-
-import {
-  WorkflowErrorCode,
-  type CompiledManifestSource,
-} from '@xemahq/kernel-contracts/workflow';
-
-import { WorkflowDslError } from '../errors';
-import {
-  compileExpression,
-  ExpressionNodeKind,
-  type ExpressionNode,
-} from '../expression';
-import { stripInterpolation } from '../expression/interpolation';
-import type {
-  WorkflowDocument,
-  WorkflowJobDeclaration,
-  WorkflowStrategyDeclaration,
-} from '../types';
-
-/** Matches `xema/review@<semver>` (1, 2, or 3 dotted version segments). */
-const REVIEW_ACTION_RE =
-  /^xema\/review@[0-9]+(\.[0-9]+(\.[0-9]+(-[A-Za-z0-9.-]+)?)?)?$/;
-
-/** Matches `xema/agent@<semver>` — only valid `redraft.step` producer kind. */
-const AGENT_ACTION_RE =
-  /^xema\/agent@[0-9]+(\.[0-9]+(\.[0-9]+(-[A-Za-z0-9.-]+)?)?)?$/;
-
-export function isReviewActionRef(uses: string): boolean {
-  return REVIEW_ACTION_RE.test(uses);
-}
-
-interface ReviewWithShape {
-  readonly subject: string | readonly string[] | undefined;
-  readonly redraft: { readonly step: string } | undefined;
-}
-
-/**
- * Per-job redraft-strategy descriptor carried on the IR `redraft` block
- * when the producer step has a matrix strategy. Mirrors the worker
- * consumer that runs the review workflow — kept JSON-serializable so the
- * IR survives Temporal payload encoding.
- *
- * `static` entries are already cartesian-expanded at compile time;
- * `dynamic.fromExpression` is the producer's expression body (already
- * `${{ … }}`-stripped) which the parent dispatcher evaluates against
- * the review step's expression context before spawning the child
- * workflow. `keyBy` is informational only — per-CU keyed targeting is
- * a planned future feature; today every matrix entry is always re-run.
- */
-export type ReviewRedraftStrategyIR =
-  | {
-      readonly kind: 'static';
-      readonly entries: readonly Readonly<Record<string, unknown>>[];
-      readonly maxParallel: number;
-    }
-  | {
-      readonly kind: 'dynamic';
-      readonly fromExpression: string;
-      readonly bindingName: string;
-      readonly maxEntries: number;
-      readonly maxParallel: number;
-      readonly keyBy: string | null;
-    };
-
-/**
- * Lightweight typed projection of a review step's `with:` block.
- * Throws DSL_SEMANTIC_INVALID on malformed shape; downstream consumers
- * (rewriter, validators) trust the projection.
- */
-function projectReviewWith(
-  jobKey: string,
-  rawWith: Readonly<Record<string, unknown>> | undefined,
-): ReviewWithShape {
-  const w = rawWith ?? {};
-  const subjectRaw = (w as Record<string, unknown>)['subject'];
-  let subject: ReviewWithShape['subject'];
-  if (subjectRaw === undefined) {
-    subject = undefined;
-  } else if (typeof subjectRaw === 'string') {
-    if (subjectRaw.length === 0) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' with.subject must be a non-empty string or array of strings.`,
-        { jobKey, fieldPath: 'with.subject' },
-      );
-    }
-    subject = subjectRaw;
-  } else if (Array.isArray(subjectRaw)) {
-    if (subjectRaw.length === 0) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' with.subject must be a non-empty array (got []).`,
-        { jobKey, fieldPath: 'with.subject' },
-      );
-    }
-    for (let i = 0; i < subjectRaw.length; i++) {
-      const item = subjectRaw[i];
-      if (typeof item !== 'string' || item.length === 0) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Job '${jobKey}' with.subject[${i}] must be a non-empty string.`,
-          { jobKey, fieldPath: `with.subject[${i}]` },
-        );
-      }
-    }
-    subject = subjectRaw as readonly string[];
-  } else {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Job '${jobKey}' with.subject must be a string or an array of strings (got ${typeof subjectRaw}).`,
-      { jobKey, fieldPath: 'with.subject' },
-    );
-  }
-
-  const redraftRaw = (w as Record<string, unknown>)['redraft'];
-  let redraft: ReviewWithShape['redraft'];
-  if (redraftRaw === undefined) {
-    redraft = undefined;
-  } else if (
-    typeof redraftRaw === 'object' &&
-    redraftRaw !== null &&
-    !Array.isArray(redraftRaw)
-  ) {
-    const stepRaw = (redraftRaw as Record<string, unknown>)['step'];
-    if (typeof stepRaw !== 'string' || stepRaw.length === 0) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' with.redraft.step must be a non-empty string naming a producer step.`,
-        { jobKey, fieldPath: 'with.redraft.step' },
-      );
-    }
-    redraft = { step: stepRaw };
-  } else {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Job '${jobKey}' with.redraft must be an object of shape '{ step: <stepName> }'.`,
-      { jobKey, fieldPath: 'with.redraft' },
-    );
-  }
-
-  return { subject, redraft };
-}
-
-/**
- * Validate every review step in the workflow. Run before topo sort +
- * expression validation so author errors surface with clear messages
- * before downstream passes throw less-helpful errors.
- */
-export function validateReviewSteps(workflow: WorkflowDocument): void {
-  for (const [jobKey, job] of Object.entries(workflow.jobs)) {
-    if (!isReviewActionRef(job.uses)) {
-      continue;
-    }
-    const shape = projectReviewWith(jobKey, job.with);
-
-    // `redraft` set without `subject` is forbidden — the producer
-    // must be authored as a separate step that publishes a deliverable
-    // as the iter-1 subject. This keeps the standalone draft step
-    // observable in the run UI and avoids the "ghost step that runs
-    // but is ignored" footgun.
-    if (shape.redraft !== undefined && shape.subject === undefined) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' has 'redraft' set but no 'subject'. Author the producer as a separate step and reference it via 'subject: \${{ needs.${shape.redraft.step}.outputs.deliverable }}'.`,
-        { jobKey, fieldPath: 'with' },
-      );
-    }
-
-    if (shape.redraft !== undefined) {
-      const stepName = shape.redraft.step;
-      const producer = workflow.jobs[stepName];
-      if (!producer) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Job '${jobKey}' with.redraft.step references unknown job '${stepName}'.`,
-          { jobKey, fieldPath: 'with.redraft.step', referencedJob: stepName },
-        );
-      }
-      if (stepName === jobKey) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Job '${jobKey}' with.redraft.step cannot reference itself.`,
-          { jobKey, fieldPath: 'with.redraft.step' },
-        );
-      }
-      if (!AGENT_ACTION_RE.test(producer.uses)) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Job '${jobKey}' with.redraft.step = '${stepName}' must reference a step that uses 'xema/agent@<semver>' (got '${producer.uses}').`,
-          {
-            jobKey,
-            fieldPath: 'with.redraft.step',
-            referencedJob: stepName,
-            referencedUses: producer.uses,
-          },
-        );
-      }
-      // Matrix-strategy producers ARE allowed here — on `reject`, the
-      // worker re-dispatches every matrix entry of the producer in
-      // parallel (one entry → one redraft agent dispatch). The DSL
-      // pre-resolves the matrix shape onto the IR `redraft.strategy`
-      // block so the parent dispatcher (root-run.workflow.ts) can
-      // evaluate dynamic `from:` expressions against the review step's
-      // expression context before spawning the child review workflow.
-      const declaredNeeds = job.needs ?? [];
-      if (!declaredNeeds.includes(stepName)) {
-        throw new WorkflowDslError(
-          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-          `Job '${jobKey}' with.redraft.step = '${stepName}' must also be listed in 'needs:'. Add 'needs: [${[...declaredNeeds, stepName].map((s) => `'${s}'`).join(', ')}]'.`,
-          {
-            jobKey,
-            fieldPath: 'with.redraft.step',
-            referencedJob: stepName,
-          },
-        );
-      }
-    }
-  }
-}
-
-/**
- * Compute extra `needs:` entries each review step requires beyond what
- * the author declared. Specifically: for any review step with
- * `redraft.step: <producer>`, add `<producer>`'s OWN `needs:` list so
- * the review step's expression context (built from its `needs:`) has
- * every upstream value the embedded redraft `with:` may reference at
- * dispatch time.
- *
- * Returns an empty map when no review steps have a redraft. The caller
- * folds these into the topo-sort input alongside `matrixGather`.
- */
-export function computeReviewNeedsExtensions(
-  workflow: WorkflowDocument,
-): Readonly<Record<string, readonly string[]>> {
-  const out: Record<string, readonly string[]> = {};
-  for (const [jobKey, job] of Object.entries(workflow.jobs)) {
-    if (!isReviewActionRef(job.uses)) {
-      continue;
-    }
-    const shape = projectReviewWith(jobKey, job.with);
-    if (shape.redraft === undefined) {
-      continue;
-    }
-    const producer = workflow.jobs[shape.redraft.step];
-    if (!producer) {
-      // validateReviewSteps already throws for this case; defensive only.
-      continue;
-    }
-    const declared = new Set<string>(producer.needs ?? []);
-    // For dynamic-matrix producers, the `from:` expression is evaluated
-    // by the parent dispatcher at review-dispatch time against the
-    // review step's expression context — every `needs.<X>` it
-    // references MUST therefore be in the review step's `needs:` too.
-    if (producer.strategy !== undefined && 'dynamic' in producer.strategy) {
-      const fromRefs = collectNeedsReferencesFromExpression(
-        producer.strategy.dynamic.from,
-      );
-      for (const ref of fromRefs) {
-        declared.add(ref);
-      }
-    }
-    if (declared.size === 0) {
-      continue;
-    }
-    out[jobKey] = Object.freeze([...declared]) as readonly string[];
-  }
-  return Object.freeze(out);
-}
-
-/**
- * Walk a `${{ … }}`-wrapped expression body and collect every
- * `needs.<X>` root reference. Used by the review-step needs extension
- * pass when the redraft producer is a dynamic matrix — its `from:`
- * expression resolves at the parent dispatcher's review-dispatch time
- * against the review step's expression context, so every referenced
- * upstream step must be in the review step's `needs:` too. Returns a
- * deduplicated sorted-by-insertion list of step keys.
- */
-function collectNeedsReferencesFromExpression(
-  rawExpression: string,
-): readonly string[] {
-  const body = stripInterpolation(rawExpression);
-  const ast = compileExpression(body);
-  const seen = new Set<string>();
-  walkForNeedsRefs(ast, seen);
-  return [...seen];
-}
-
-function walkForNeedsRefs(node: ExpressionNode, sink: Set<string>): void {
-  switch (node.kind) {
-    case ExpressionNodeKind.MEMBER: {
-      // Match `needs.<X>` (target is the `needs` identifier).
-      if (
-        node.target.kind === ExpressionNodeKind.IDENTIFIER &&
-        node.target.name === 'needs'
-      ) {
-        sink.add(node.property);
-      }
-      walkForNeedsRefs(node.target, sink);
-      return;
-    }
-    case ExpressionNodeKind.INDEX:
-      walkForNeedsRefs(node.target, sink);
-      walkForNeedsRefs(node.index, sink);
-      return;
-    case ExpressionNodeKind.CALL:
-      for (const arg of node.args) {
-        walkForNeedsRefs(arg, sink);
-      }
-      return;
-    case ExpressionNodeKind.UNARY_NOT:
-      walkForNeedsRefs(node.operand, sink);
-      return;
-    case ExpressionNodeKind.BINARY_EQ:
-    case ExpressionNodeKind.BINARY_NEQ:
-    case ExpressionNodeKind.BINARY_AND:
-    case ExpressionNodeKind.BINARY_OR:
-      walkForNeedsRefs(node.left, sink);
-      walkForNeedsRefs(node.right, sink);
-      return;
-    case ExpressionNodeKind.LITERAL:
-    case ExpressionNodeKind.IDENTIFIER:
-      return;
-  }
-}
-
-/**
- * Rewrite a review step's `with:` block from the author shape to the
- * worker contract:
- *
- *   - Author `subject: <string>`     → IR `subjects: [<string>]`
- *   - Author `subject: <string[]>`   → IR `subjects: <string[]>`
- *   - Author `redraft: { step: X }`  → IR `redraft: { uses, with }`
- *     looked up from the named producer step.
- *
- * Other fields pass through verbatim. Inputs that are not review steps
- * fall back to `payload.with ?? {}` unchanged — callers may always
- * route through this helper without an `isReviewActionRef` check.
- */
-export function rewriteReviewStepWith(
-  jobKey: string,
-  payload: WorkflowJobDeclaration,
-  workflow: WorkflowDocument,
-  manifestSourcesByJob: Readonly<Record<string, CompiledManifestSource | null>>,
-): Readonly<Record<string, unknown>> {
-  if (!isReviewActionRef(payload.uses)) {
-    return payload.with ?? {};
-  }
-  const shape = projectReviewWith(jobKey, payload.with);
-  const out: Record<string, unknown> = { ...(payload.with ?? {}) };
-  // Drop the author-only fields so the IR carries only worker-facing
-  // shapes.
-  delete out['subject'];
-  delete out['redraft'];
-
-  if (shape.subject !== undefined) {
-    out['subjects'] =
-      typeof shape.subject === 'string' ? [shape.subject] : [...shape.subject];
-  }
-
-  if (shape.redraft !== undefined) {
-    const producer = workflow.jobs[shape.redraft.step];
-    if (!producer) {
-      // validateReviewSteps already throws here; keep defensive.
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' with.redraft.step references unknown job '${shape.redraft.step}'.`,
-        { jobKey, fieldPath: 'with.redraft.step' },
-      );
-    }
-    // Preserve the original step name on the IR `redraft` block. The
-    // worker uses it as the `artifactScope` override when the redraft's
-    // agent activity emits its outputs, so the regenerated bytes
-    // version the SAME logical artifact as the original draft (e.g.
-    // v2 of `draft.response`) rather than landing under the review
-    // step's identity (which would create a parallel `review.response`
-    // artifact and starve the reviewer's iter-2 view of the new draft).
-    //
-    // For matrix producers, also carry the producer's matrix shape
-    // onto the IR so the parent dispatcher (root-run.workflow.ts) can
-    // expand entries at review-dispatch time and pass the resolved
-    // bindings into the review child workflow. On `reject`, the worker
-    // re-dispatches every matrix entry in parallel — one redraft agent
-    // dispatch per entry.
-    const ir: Record<string, unknown> = {
-      step: shape.redraft.step,
-      uses: producer.uses,
-      with: producer.with ?? {},
-      manifestSource: requireRedraftManifestSource(
-        jobKey,
-        shape.redraft.step,
-        manifestSourcesByJob,
-      ),
-    };
-    const strategy = compileRedraftStrategyIR(producer.strategy);
-    if (strategy !== null) {
-      ir['strategy'] = strategy;
-    }
-    if (producer.matrixGather && producer.matrixGather.length > 0) {
-      ir['matrixGather'] = [...producer.matrixGather];
-    }
-    out['redraft'] = ir;
-  }
-
-  return out;
-}
-
-function requireRedraftManifestSource(
-  reviewJobKey: string,
-  producerJobKey: string,
-  manifestSourcesByJob: Readonly<Record<string, CompiledManifestSource | null>>,
-): CompiledManifestSource {
-  const source = manifestSourcesByJob[producerJobKey];
-  if (source === undefined || source === null) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Job '${reviewJobKey}' redraft producer '${producerJobKey}' has no compiled Agent revision source.`,
-      {
-        jobKey: reviewJobKey,
-        fieldPath: 'with.redraft.step',
-        referencedJob: producerJobKey,
-      },
-    );
-  }
-  return source;
-}
-
-/**
- * Pre-resolve a producer step's authored matrix strategy into a
- * JSON-serializable IR descriptor the worker carries through the
- * review step's `with.redraft`. `null` for non-matrix producers — the
- * worker takes the legacy single-dispatch path when `strategy` is
- * absent on the IR `redraft` block. Static matrices are NOT
- * cartesian-expanded here (that's the job of `compileStrategy` which
- * runs against the producer's own job IR); we propagate the raw axes
- * because the worker reuses the same compile-time expansion behavior
- * via the parent dispatcher's per-job CompiledJob lookup. Keeping this
- * descriptor small and shape-faithful avoids drift with
- * `compileStrategy`'s output — the parent dispatcher reads the
- * producer's own `CompiledJob.strategy` (Source of truth) and uses
- * THIS descriptor only as a discriminator hint + entry-resolution
- * fallback. Mirror of the worker contract `ReviewRedraftStrategyIR`.
- */
-function compileRedraftStrategyIR(
-  strategy: WorkflowStrategyDeclaration | undefined,
-): ReviewRedraftStrategyIR | null {
-  if (strategy === undefined) {
-    return null;
-  }
-  if ('matrix' in strategy) {
-    // Carry static axes; the worker side mirrors `compileStrategy`'s
-    // cartesian expansion. `maxParallel` defaults align with
-    // `matrix.ts:resolveMaxParallel` — when absent, the worker uses 8.
-    const entries = expandStaticMatrixAxes(strategy.matrix);
-    const maxParallel =
-      strategy.maxParallel !== undefined && strategy.maxParallel > 0
-        ? Math.min(strategy.maxParallel, entries.length || 1)
-        : Math.min(8, Math.max(1, entries.length));
-    return {
-      kind: 'static',
-      entries,
-      maxParallel,
-    };
-  }
-  const dyn = strategy.dynamic;
-  const body = stripInterpolation(dyn.from);
-  const maxEntries = dyn.maxEntries ?? 64;
-  const maxParallel =
-    strategy.maxParallel !== undefined && strategy.maxParallel > 0
-      ? Math.min(strategy.maxParallel, maxEntries)
-      : Math.min(8, maxEntries);
-  return {
-    kind: 'dynamic',
-    fromExpression: body,
-    bindingName: dyn.as,
-    maxEntries,
-    maxParallel,
-    keyBy: dyn.keyBy ?? null,
-  };
-}
-
-/**
- * Cartesian expansion of a static-matrix axes block. Mirrors
- * `expandStaticMatrix` in `./matrix.ts` minus the cap-checking, which
- * has already been enforced on the producer's own CompiledJob by the
- * normal compile path. Lexicographic axis order keeps replay
- * deterministic.
- */
-function expandStaticMatrixAxes(
-  axes: Readonly<Record<string, readonly unknown[]>>,
-): readonly Readonly<Record<string, unknown>>[] {
-  const axisKeys = Object.keys(axes).sort();
-  let entries: Record<string, unknown>[] = [{}];
-  for (const axis of axisKeys) {
-    const values = axes[axis]!;
-    const next: Record<string, unknown>[] = [];
-    for (const partial of entries) {
-      for (const value of values) {
-        next.push({ ...partial, [axis]: value });
-      }
-    }
-    entries = next;
-  }
-  return entries.map(Object.freeze) as readonly Readonly<
-    Record<string, unknown>
-  >[];
-}