@xemahq/dsl 0.1.1

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

@@ -0,0 +1,517 @@
+/**
+ * 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 } 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 in `biomes/workflow-runtime/api/workflow-runtime-worker/src/workflows/review.workflow.ts`
+ * — 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 Phase-2 feature; Phase 1 always re-runs every matrix entry.
+ */
+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,
+): 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 ?? {},
+    };
+    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;
+}
+
+/**
+ * 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>>[];
+}

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

@@ -0,0 +1,170 @@
+import type {
+  ActionExecutionKind,
+  Briefcase,
+  TaskQueueName,
+  TriggerPayload,
+  WalletContents,
+  WorkflowRef,
+} from '@xemahq/kernel-contracts/workflow';
+import type { ActionManifest, WorkflowDocument } from '../types';
+
+/**
+ * Everything the compiler needs beyond the workflow document itself. The
+ * engine gathers these inputs before calling `compileWorkflow(...)`:
+ *
+ *   - `workflow` — validated WorkflowDocument (pass through
+ *     `validateWorkflowDocument` first).
+ *   - `workflowRef` — slug/version/isSystem, resolved from the DB.
+ *   - `trigger` — the payload that fired this run.
+ *   - `resolvedRefs` — map of `uses:` strings to resolved refs, populated
+ *     by looking up each job's `uses:` in the action-manifest registry
+ *     (for `xema/...`) or the reusable-workflow registry (for
+ *     `xema://workflow/...`).
+ *   - `workflowDefinitionVersionSha256` — sha256 of the source YAML the
+ *     compiler is consuming. Emitted into CompiledRun for audit.
+ */
+export interface CompileInput {
+  readonly workflow: WorkflowDocument;
+  readonly workflowRef: WorkflowRef;
+  readonly trigger: TriggerPayload;
+  readonly resolvedRefs: Readonly<Record<string, ResolvedRef>>;
+  /**
+   * Map of literal `agentSlug` values (used in `with.agentSlug` and
+   * `with.reviewers[].agentSlug`) to the agent metadata the compiler
+   * needs for validation. The engine pre-fetches this from
+   * llm-registry-api. The compiler validates that every literal slug
+   * appears here; expression-shaped slugs (e.g. `${{ inputs.agentSlug }}`)
+   * are skipped — they resolve at dispatch and the activity's
+   * `AGENT_NOT_REGISTERED` preflight catches them at runtime.
+   *
+   * Pass an empty map (or omit) to opt out of agent validation (e.g.
+   * for the `preview-raw` endpoint when the engine cannot reach the
+   * registry, or for tests that don't exercise the registry).
+   */
+  readonly resolvedAgents?: Readonly<Record<string, ResolvedAgent>>;
+  /**
+   * Map of literal deliverable-spec refs (used in `with.deliverableSpecRef`
+   * and the `produces:` array) to the spec metadata the compiler needs
+   * for validation. The engine pre-fetches this from
+   * deliverable-specs-api. Same literal-vs-expression rule as
+   * `resolvedAgents`. Same opt-out semantics: empty / omitted = skip.
+   */
+  readonly resolvedDeliverableSpecs?: Readonly<
+    Record<string, ResolvedDeliverableSpec>
+  >;
+  readonly workflowDefinitionVersionSha256: string;
+  /**
+   * Contents of every wallet referenced under `requires.wallets`, plus
+   * any additional wallets a dispatch caller asked for. The compiler
+   * unions the entries to derive `CompiledRun.requiredVariables` and to
+   * validate `${{ vars.X }}` / `${{ secrets.X }}` references. When
+   * omitted, wallet-derived validation is skipped — used by
+   * `preview-raw` during authoring where the engine can't reach the
+   * variable store.
+   */
+  readonly resolvedWallets?: Readonly<Record<string, WalletContents>>;
+  /**
+   * Installation scope of this dispatch — present when the workflow is
+   * dispatched from a biome installation (webhook trigger gated on
+   * the installation, manual dispatch from the installation's UX, a
+   * scheduled trigger tied to the installation). Absent for system /
+   * org-wide dispatches that don't belong to any installation.
+   *
+   * The compiler's installation-resource validator uses this scope to
+   * resolve `x-installation-resource: { kind: ... }` references in
+   * action input schemas against the installation's bound resources
+   * (wallets / repos / channels / …). When `installationScope` is
+   * undefined, the validator skips installation-bound fields — system
+   * workflows can still reference wallet ids, but compile-time
+   * binding-set validation only happens for biome-installed runs.
+   */
+  readonly installationScope?: InstallationCompileScope;
+  /**
+   * When true, the compiler substitutes type-appropriate sentinel values
+   * for missing required inputs instead of throwing. Intended only for
+   * the `preview-raw` endpoint (Monaco editor live feedback) where the
+   * caller deliberately omits real input values during YAML authoring.
+   * Never set this on real run compilation paths.
+   */
+  readonly previewMode?: boolean;
+  /**
+   * Run-scoped Briefcase the dispatch caller attached to this run.
+   * Synthesized server-side from the StartRun request body (uploads /
+   * references / vars / mcpTools) and threaded into the CompiledRun so
+   * the run's snapshot captures the dispatch payload alongside its
+   * inputs and trigger. Absent for runs without dispatch-attached
+   * context (compiler treats absent and `emptyBriefcase()` identically
+   * downstream).
+   */
+  readonly briefcase?: Briefcase;
+}
+
+/**
+ * Installation context the engine pre-fetches at dispatch time. Each
+ * `boundResources` entry lists the resource ids the installation is
+ * bound to for a single `InstallationResourceKind` — the compiler
+ * checks every literal value in a `x-installation-resource` field
+ * against the matching kind's set and rejects unbound values.
+ *
+ * The engine populates this from biome-host-api right before calling
+ * the compiler. Passing an empty array for a kind means "no resources
+ * bound" — every literal value for that kind fails validation.
+ */
+export interface InstallationCompileScope {
+  readonly installationId: string;
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly biomeId: string;
+  readonly boundResources: Readonly<Record<string, readonly string[]>>;
+}
+
+/**
+ * Minimal agent metadata the compiler keeps for each literal `agentSlug`.
+ * The engine fetches the full row from llm-registry-api but the compiler
+ * only needs the existence proof and the snapshot hash (so a future
+ * `CompiledRun` can carry it for cache-invalidation matching). Extend
+ * with more fields only when the compiler actually consumes them.
+ */
+export interface ResolvedAgent {
+  readonly slug: string;
+  readonly snapshotHash: string;
+}
+
+/**
+ * Minimal deliverable-spec metadata the compiler keeps for each literal
+ * `deliverableSpecRef`. Same minimality rule as `ResolvedAgent`.
+ *
+ * Optional `topLevelKeys` enables compile-time field validation for
+ * expressions of shape
+ * `${{ job.outputs.deliverable.content.value.<field> }}` — when
+ * populated, the DSL asserts `<field>` is one of these. The engine
+ * extracts the keys from the spec's `zodSchemaSource` (Zod) or
+ * `content`'s `properties` (JSON Schema) at registry-fetch time. Specs
+ * whose kind has no known shape (e.g. CUSTOM, ENDPOINT_FETCH) leave it
+ * undefined and the validator skips them.
+ */
+export interface ResolvedDeliverableSpec {
+  readonly ref: string;
+  readonly slug: string;
+  readonly snapshotHash: string;
+  readonly topLevelKeys?: readonly string[];
+}
+
+/**
+ * Resolved reference for a single `uses:` value. Emitted by the engine's
+ * ref-resolution layer before compilation; the compiler trusts it blindly.
+ *
+ * For action refs, `actionManifest` is the full manifest (the compiler
+ * needs retry/timeout/allowedMounts). For reusable-workflow refs,
+ * `actionManifest` is null — reusable workflows have their own compilation
+ * pass, so this outer compilation only records the pointer.
+ */
+export interface ResolvedRef {
+  readonly id: string;
+  readonly version: string;
+  readonly manifestSha256: string;
+  readonly executionKind: ActionExecutionKind;
+  readonly taskQueue: TaskQueueName;
+  readonly isReusableWorkflow: boolean;
+  readonly actionManifest: ActionManifest | null;
+}