@xemahq/dsl 0.1.1

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

@@ -0,0 +1,1518 @@
+import {
+  ActionExecutionKind,
+  ActionKind,
+  MatrixStrategyKind,
+  WorkflowErrorCode,
+  type ActionRef,
+  type CompiledJob,
+  type CompiledRun,
+  type PermissionResource,
+  type PermissionScope,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import {
+  compileExpression,
+  ExpressionNodeKind,
+  extractInterpolations,
+  stripInterpolation,
+  type ExpressionNode,
+} from '../expression';
+import type { WorkflowDocument } from '../types';
+import { canonicalJsonSha256 } from './canonical-json';
+import {
+  compileConcurrency,
+  validateConcurrencyGroupTemplate,
+} from './concurrency';
+import { topologicalSort } from './dag';
+import { bindTriggerInputs } from './inputs';
+import { compileStrategy } from './matrix';
+import { compileManifestSource } from './manifest-source';
+import { compileMountPlan } from './mount-plan';
+import { assertJobPermissionsFit, normalizePermissions } from './permissions';
+import {
+  computeReviewNeedsExtensions,
+  rewriteReviewStepWith,
+  validateReviewSteps,
+} from './review-step';
+import {
+  resolveJobRetry,
+  resolveJobTimeout,
+  resolveWorkflowDefaults,
+} from './retry-timeout';
+import {
+  collectPayloadReachInsForJob,
+  validatePayloadReachIns,
+} from './payload-reach-in';
+import { validateInstallationResourceBindings } from './installation-resource-validator';
+import {
+  resolveWalletRequirements,
+  validateVariableReferences,
+} from './variable-requirements';
+import type {
+  CompileInput,
+  ResolvedAgent,
+  ResolvedDeliverableSpec,
+  ResolvedRef,
+} from './types';
+
+/**
+ * Compile a validated workflow document into a CompiledRun. Deterministic:
+ * the same (workflow, trigger, resolvedRefs) always produces the same
+ * CompiledRun modulo `snapshotCreatedAt`. Pure function; no I/O.
+ *
+ * Responsibilities:
+ *   1. Bind trigger inputs against declared schemas (fail-fast).
+ *   2. Resolve concurrency group to a concrete lease key.
+ *   3. Resolve action/reusable-workflow refs using the pre-fetched map.
+ *   4. Pre-compile every authored expression (so runtime only deals with
+ *      already-validated ASTs — not done yet in this pass, we validate
+ *      without caching because ASTs aren't serializable into the CompiledRun).
+ *   5. Expand static matrices; record dynamic matrix metadata for runtime.
+ *   6. Topologically sort jobs; reject cycles + unknown needs.
+ *   7. Enforce job-level permissions are a subset of workflow permissions.
+ *   8. Emit CompiledRun with a deterministic sha256.
+ */
+export function compileWorkflow(input: CompileInput): CompiledRun {
+  const { workflow, workflowRef, trigger, resolvedRefs, workflowDefinitionVersionSha256 } = input;
+
+  const inputs = bindTriggerInputs(workflow, trigger, input.previewMode ?? false);
+  const vars: Readonly<Record<string, unknown>> = workflow.vars ?? {};
+  const requiredVariables = resolveWalletRequirements(
+    workflow,
+    input.resolvedWallets,
+  );
+  const requiredWallets = Object.freeze([
+    ...(workflow.requires?.wallets ?? []),
+  ]) as readonly string[];
+  const permissions = normalizePermissions(workflow.permissions);
+  const concurrency = compileConcurrency(workflow.concurrency, trigger, inputs, vars);
+  const defaults = resolveWorkflowDefaults(workflow.defaults);
+
+  // Validate every expression everywhere at compile time. We throw away the
+  // compiled ASTs because CompiledRun is a serializable DTO; the worker will
+  // recompile from the same source strings — determinism is preserved
+  // because the source text itself is a function of the workflow document.
+  validateAllAuthoredExpressions(workflow);
+
+  // Cross-validate every `${{ vars.X }}` / `${{ secrets.X }}` reference
+  // against the union of wallet contents the engine pre-fetched (plus the
+  // YAML-static `vars:` block for `vars.*`). Authors get a typo /
+  // stale-name error at compile time instead of a runtime
+  // DSL_EXPRESSION_INVALID against an unknown property.
+  validateVariableReferences(
+    workflow,
+    requiredVariables,
+    input.resolvedWallets,
+  );
+
+  // Validate every literal cross-document reference (agent slugs, deliverable
+  // spec refs) against the resolved maps the engine pre-fetched. Expression-
+  // shaped values are skipped — they bind at dispatch and the activity's
+  // own preflight catches unknowns at runtime. Empty maps opt out (e.g.
+  // preview-raw cannot reach the registries).
+  validateAllLiteralReferences(
+    workflow,
+    input.resolvedAgents ?? {},
+    input.resolvedDeliverableSpecs ?? {},
+  );
+
+  // `xema/review@*` semantic checks: subject/redraft shape, redraft.step
+  // exists/is-agent/is-in-needs/is-not-matrix, redraft-without-subject
+  // forbidden. Run BEFORE expression validation so author errors surface
+  // with clear messages before less-helpful generic errors (e.g.
+  // "unknown step in needs"). The rewrite + needs extension happen
+  // alongside the per-job compile loop below.
+  validateReviewSteps(workflow);
+  const reviewNeedsExtensions = computeReviewNeedsExtensions(workflow);
+
+  // `matrixGather:` implicitly depends on the gathered jobKeys, so fold
+  // them into `needs` BEFORE the topological sort. This keeps authors from
+  // having to duplicate each key; the compiler validates referenced keys
+  // below (must exist + must be matrix jobs).
+  validateMatrixGather(workflow);
+
+  // Cross-job validation: every `needs.<X>.outputs.…` access must match
+  // upstream's strategy + keyBy. Catches `needs.matrix.outputs.deliverables`
+  // (silent-passing-then-runtime-error) and `byKey[…]` against
+  // un-`keyBy`-ed upstreams at compile time.
+  validateAllNeedsAccessShapes(workflow);
+
+  // Spec-aware field validation: every
+  // `${{ ...outputs.deliverable.content.value.<field> }}` access must
+  // reference a `<field>` that exists as a top-level key on the producing
+  // job's declared deliverable spec. Skips when the engine couldn't
+  // pre-fetch spec content (preview mode or specs without introspectable
+  // shape).
+  validateDeliverableValueExpressions(workflow, input.resolvedDeliverableSpecs ?? {});
+
+  // §C.1 payload reach-in validation: `needs.<X>.outputs.<name>.<field>`
+  // chains where `<field>` is not an ArtifactRef envelope field reach
+  // INTO the artifact's parsed payload. The validator asserts the
+  // upstream job has a schema-bearing `with.deliverableSpecRef` and
+  // that `<field>` is a top-level key on that spec — fail-fast with
+  // `DSL_FIELD_NOT_TYPED` / `DSL_FIELD_NOT_IN_SCHEMA` at compile time
+  // so authors don't see a generic "Unknown property" at runtime.
+  validatePayloadReachIns(
+    workflow,
+    input.resolvedDeliverableSpecs ?? {},
+    resolvedRefs,
+  );
+
+  const orderedJobs = topologicalSort(
+    Object.entries(workflow.jobs).map(([key, decl]) => {
+      const authoredNeeds = decl.needs ?? [];
+      const gather = decl.matrixGather ?? [];
+      const reviewExt = reviewNeedsExtensions[key] ?? [];
+      const merged =
+        gather.length > 0 || reviewExt.length > 0
+          ? Array.from(new Set([...authoredNeeds, ...gather, ...reviewExt]))
+          : authoredNeeds;
+      return { key, payload: decl, needs: merged };
+    }),
+  );
+
+  const compiledJobs: CompiledJob[] = orderedJobs.map(({ key, payload, needs }) => {
+    const resolved = lookupResolvedRef(payload.uses, resolvedRefs);
+    const actionRef: ActionRef = {
+      id: resolved.id,
+      version: resolved.version,
+      manifestSha256: resolved.manifestSha256,
+      executionKind: resolveJobExecutionKind(key, payload.with, resolved),
+      taskQueue: resolved.taskQueue,
+      actionKind: resolveActionKind(resolved),
+      isReusableWorkflow: resolved.isReusableWorkflow,
+      // Pin the manifest's `inputs:` schema into the compiled ref so the
+      // worker validates `with:` against the schema that was in effect at
+      // compile time — not whatever's currently published. Reusable
+      // workflows have their own `workflow_call.inputs`, validated by
+      // their own compile pass.
+      inputsSchema: resolved.isReusableWorkflow
+        ? null
+        : resolved.actionManifest?.spec.inputs ?? null,
+    };
+
+    const jobPermissions = normalizePermissions(payload.permissions);
+    assertJobPermissionsFit(jobPermissions, permissions, key);
+
+    const strategy = compileStrategy(payload.strategy, key);
+
+    // When the job uses a reusable workflow, mount planning is governed
+    // by the reusable workflow's own jobs, not by this job. So we emit an
+    // empty plan — the child workflow's compiler run will produce its own.
+    const mountPlan = resolved.isReusableWorkflow
+      ? { readOnly: {}, readWrite: {} }
+      : compileMountPlan(key, payload.with, resolved.actionManifest);
+
+    // For agent-shaped actions, pre-resolve the manifest source so the
+    // worker sees a single discriminated shape (`ref` / `inline` /
+    // `inline-deferred`) instead of branching on input fields at
+    // dispatch. Reusable-workflow jobs return null — their nested
+    // CompiledRun owns its own agent steps.
+    const manifestSource = resolved.isReusableWorkflow
+      ? null
+      : compileManifestSource(key, payload.with, resolved.actionManifest);
+
+    const retry = resolveJobRetry(
+      defaults.retry,
+      resolved.actionManifest?.spec.retryDefaults ?? null,
+      payload.retry,
+    );
+    const timeoutMs = resolveJobTimeout(
+      defaults.timeoutMs,
+      resolved.actionManifest?.spec.timeoutDefaults ?? null,
+      payload.timeout,
+    );
+
+    // Validate `if` expression shape now — runtime evaluator only fails on
+    // unknown bindings after this point. Plan §G shorthand: rewrite a
+    // bare `needs.<X>` reference to `needs.<X>.outcome == 'ok'` so the
+    // evaluator sees the explicit success check (an envelope object is
+    // truthy even on failure — silent always-true is the trap §G
+    // explicitly avoids).
+    const ifExpression = payload.if !== undefined
+      ? (() => {
+          const body = stripInterpolation(payload.if!);
+          const rewritten = rewriteBareNeedsInIf(body);
+          compileExpression(rewritten);
+          return rewritten;
+        })()
+      : null;
+
+    // For `xema/review@*` steps, rewrite `with:` from the author shape
+    // (`subject` + `redraft.step`) to the worker contract
+    // (`subjects` + embedded `redraft: { uses, with }`). Other steps
+    // pass through verbatim.
+    const compiledWith = rewriteReviewStepWith(key, payload, workflow);
+
+    // Compile-time installation-binding gate: when the engine threaded
+    // an installationScope through CompileInput, walk every literal
+    // `x-installation-resource` field in the `with:` block and confirm
+    // its value is bound to the calling installation. Rejects unbound
+    // walletIds (etc.) BEFORE the dispatch creates a run, instead of
+    // failing 3 activities later when integration-adapters refuses to
+    // mint credentials. Skips entirely for system / org-wide dispatches.
+    validateInstallationResourceBindings({
+      jobKey: key,
+      actionId: actionRef.id,
+      inputsSchema: actionRef.inputsSchema,
+      withValue: compiledWith,
+      scope: input.installationScope,
+    });
+
+    return Object.freeze({
+      jobKey: key,
+      title: payload.title ?? null,
+      needs,
+      matrixGather: Object.freeze([...(payload.matrixGather ?? [])]) as readonly string[],
+      ifExpression,
+      strategy,
+      action: actionRef,
+      mountPlan,
+      manifestSource,
+      with: Object.freeze({ ...compiledWith }) as Readonly<Record<string, unknown>>,
+      // Strip the `${{ ... }}` wrapper at compile time so the runtime
+      // evaluator receives expression bodies directly — same convention
+      // as `ifExpression`. `validateAllAuthoredExpressions` already
+      // compiled each body to surface invalid expressions as DSL errors.
+      outputs: compileOutputsMap(payload.outputs, `jobs.${key}.outputs`),
+      retry,
+      timeoutMs,
+      permissions: jobPermissions,
+      // The DSL emits null; the engine (which owns the reusable-workflow
+      // registry) post-processes each CompiledRun and attaches the nested
+      // compiled body for jobs whose action is a reusable workflow.
+      reusableCompiledRun: null,
+      payloadReachIns: Object.freeze(
+        collectPayloadReachInsForJob(
+          workflow,
+          key,
+          payload,
+          input.resolvedDeliverableSpecs ?? {},
+          resolvedRefs,
+        ),
+      ),
+    }) as CompiledJob;
+  });
+
+  const snapshotCreatedAt = input.trigger.triggeredAt;
+  const workflowCallOutputs = compileOutputsMap(
+    workflow.on.workflow_call?.outputs,
+    'on.workflow_call.outputs',
+  );
+  const workflowOutputs = compileWorkflowOutputs(workflow);
+
+  const baseCompiled = {
+    compiledRunVersion: 1 as const,
+    workflowRef,
+    trigger,
+    inputs,
+    vars,
+    requiredWallets,
+    requiredVariables,
+    permissions,
+    concurrency,
+    defaults,
+    jobs: Object.freeze(compiledJobs) as readonly CompiledJob[],
+    snapshotCreatedAt,
+    workflowDefinitionVersionSha256,
+    workflowCallOutputs,
+    workflowOutputs,
+    // Spread only when present so a run dispatched without a briefcase
+    // produces a CompiledRun without the field — keeps snapshots from
+    // older runs hash-stable while letting new dispatches carry the
+    // briefcase into the run's permanent record.
+    ...(input.briefcase !== undefined && { briefcase: input.briefcase }),
+  };
+
+  const snapshotSha256 = canonicalJsonSha256(baseCompiled);
+
+  const compiled: CompiledRun = {
+    ...baseCompiled,
+    snapshotSha256,
+  };
+
+  // Final shape check: strategy presence vs static cardinality makes
+  // sense. Dynamic strategies cannot satisfy permission budgets at compile
+  // time — the runtime enforces against the declared maxEntries instead.
+  assertStrategyInvariants(compiled);
+
+  return compiled;
+}
+
+/**
+ * Resolve an action's semantic `ActionKind` from its manifest. Reusable
+ * workflows are always `DISPATCH` (their `uses:` resolves to another
+ * workflow). Otherwise read the manifest's `spec.actionKind`; any
+ * unknown string falls back to `GENERIC` so third-party manifests stay
+ * safe with this compiler's closed enum.
+ */
+/**
+ * Plan §G shorthand: rewrite a bare `needs.<X>` reference at the top
+ * level of an `if:` expression to `needs.<X>.outcome == 'ok'`. Authors
+ * write `if: needs.draft` to mean "run if draft succeeded"; without
+ * this rewrite the evaluator sees the upstream's envelope object
+ * (always truthy) and the gate becomes a silent no-op.
+ *
+ * Only the BARE form is rewritten — anything compound (comparison,
+ * boolean op, function call, payload reach-in) is left alone so
+ * authors who want the raw value can still get it.
+ */
+function rewriteBareNeedsInIf(body: string): string {
+  let ast: ExpressionNode;
+  try {
+    ast = compileExpression(body);
+  } catch {
+    // Defer to the caller's compileExpression — it'll re-throw with the
+    // proper DSL error envelope.
+    return body;
+  }
+  const upstreamKey = matchBareNeedsRef(ast);
+  if (upstreamKey === null) return body;
+  return `needs.${upstreamKey}.outcome == 'ok'`;
+}
+
+/**
+ * Match `needs.<X>` as a top-level expression (no descendant fields,
+ * no operators). Returns `<X>` on match, `null` otherwise.
+ */
+function matchBareNeedsRef(node: ExpressionNode): string | null {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
+  const target = node.target;
+  if (target.kind !== ExpressionNodeKind.IDENTIFIER) return null;
+  if (target.name !== 'needs') return null;
+  return node.property;
+}
+
+/**
+ * Resolve a job's Temporal dispatch primitive.
+ *
+ * For most actions the execution kind is fixed by the manifest
+ * (`spec.executionKind`). An action MAY opt into per-job selection by
+ * declaring a top-level `executionKind` property in its `inputs:`
+ * schema — today only `xema/dispatch-workflow`, which serves both the
+ * fire-and-forget (`activity`) and await-completion (`child_workflow`)
+ * forms from a single manifest. When opted in, the job's
+ * `with.executionKind` overrides the manifest default.
+ *
+ * The value MUST be a literal — the dispatch primitive is chosen at
+ * compile time, so a `${{ }}` expression (which only resolves at
+ * dispatch) cannot drive it. Anything other than the two literals
+ * fails fast with `DSL_SEMANTIC_INVALID`.
+ */
+function resolveJobExecutionKind(
+  jobKey: string,
+  withBlock: Readonly<Record<string, unknown>> | undefined,
+  resolved: ResolvedRef,
+): ActionExecutionKind {
+  const inputs = resolved.actionManifest?.spec.inputs;
+  const inputProps =
+    inputs && typeof inputs === 'object'
+      ? (inputs as { properties?: unknown }).properties
+      : undefined;
+  const declaresExecutionKindInput =
+    inputProps !== null &&
+    typeof inputProps === 'object' &&
+    'executionKind' in (inputProps as Record<string, unknown>);
+  if (!declaresExecutionKindInput) {
+    return resolved.executionKind;
+  }
+  const raw = withBlock?.executionKind;
+  if (raw === undefined) {
+    return resolved.executionKind;
+  }
+  if (
+    raw !== ActionExecutionKind.ACTIVITY &&
+    raw !== ActionExecutionKind.CHILD_WORKFLOW
+  ) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `jobs.${jobKey}.with.executionKind must be the literal '${ActionExecutionKind.ACTIVITY}' or '${ActionExecutionKind.CHILD_WORKFLOW}' — the Temporal dispatch primitive is fixed at compile time, so expressions are not allowed.`,
+      { jobKey, executionKind: raw },
+    );
+  }
+  return raw;
+}
+
+function resolveActionKind(resolved: ResolvedRef): ActionKind {
+  if (resolved.isReusableWorkflow) return ActionKind.DISPATCH;
+  const declared = resolved.actionManifest?.spec.actionKind;
+  if (declared === undefined) return ActionKind.GENERIC;
+  const known: ReadonlySet<string> = new Set<string>(Object.values(ActionKind));
+  return known.has(declared) ? (declared as ActionKind) : ActionKind.GENERIC;
+}
+
+function lookupResolvedRef(
+  uses: string,
+  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
+): ResolvedRef {
+  const ref = resolvedRefs[uses];
+  if (!ref) {
+    const isReusable = uses.startsWith('xema://workflow/');
+    throw new WorkflowDslError(
+      isReusable
+        ? WorkflowErrorCode.DSL_UNKNOWN_REUSABLE_WORKFLOW
+        : WorkflowErrorCode.DSL_UNKNOWN_ACTION,
+      `Reference '${uses}' is not present in resolvedRefs map passed to compiler.`,
+      { uses },
+    );
+  }
+  return ref;
+}
+
+function validateAllAuthoredExpressions(doc: WorkflowDocument): void {
+  // Walk every job's with/outputs/strategy.dynamic.from/if for `${{ ... }}`
+  // blocks and compile each. Uses extractInterpolations which enforces the
+  // "fully wrapped or pure literal" policy and rejects partial interpolation.
+  // The concurrency.group template is the one DSL field that opts in to
+  // partial interpolation; it has its own validator below.
+  for (const [key, job] of Object.entries(doc.jobs)) {
+    validateJobExpressions(key, job);
+  }
+
+  // Reusable workflows declare their externally-visible outputs under
+  // `on.workflow_call.outputs`. Each value is a `${{ needs.<job>.outputs.* }}`
+  // expression evaluated by the parent runtime once the child finishes.
+  const callOutputs = doc.on.workflow_call?.outputs;
+  if (callOutputs) {
+    for (const expr of Object.values(callOutputs)) {
+      const body = stripInterpolation(expr);
+      compileExpression(body);
+    }
+  }
+
+  validateConcurrencyGroupTemplate(doc.concurrency);
+}
+
+/**
+ * Walk every job's `with.agentSlug`, `with.reviewers[].agentSlug`, and
+ * `with.deliverableSpecRef` entries and assert each literal value
+ * resolves against the engine-supplied registry maps.
+ *
+ * Skips:
+ *   - Expression-shaped values (`${{ … }}`). Those resolve at dispatch
+ *     and the activity's preflight (`AGENT_NOT_REGISTERED`) catches
+ *     unknowns at runtime — the compiler has no way to know what an
+ *     unbound expression will evaluate to.
+ *   - Empty maps. The engine signals "skip validation" by passing `{}`
+ *     (e.g. for `preview-raw` where it cannot reach the registries).
+ *
+ * Errors are thrown one-at-a-time on the first miss, naming the exact
+ * job + field path + offending value so authors fix at the source.
+ */
+function validateAllLiteralReferences(
+  doc: WorkflowDocument,
+  resolvedAgents: Readonly<Record<string, ResolvedAgent>>,
+  resolvedDeliverableSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+): void {
+  const agentValidationEnabled = Object.keys(resolvedAgents).length > 0;
+  const specValidationEnabled =
+    Object.keys(resolvedDeliverableSpecs).length > 0;
+  if (!agentValidationEnabled && !specValidationEnabled) {
+    return;
+  }
+  for (const [jobKey, job] of Object.entries(doc.jobs)) {
+    validateJobLiteralReferences(
+      jobKey,
+      job,
+      agentValidationEnabled ? resolvedAgents : null,
+      specValidationEnabled ? resolvedDeliverableSpecs : null,
+    );
+  }
+}
+
+function validateJobLiteralReferences(
+  jobKey: string,
+  job: WorkflowDocument['jobs'][string],
+  resolvedAgents: Readonly<Record<string, ResolvedAgent>> | null,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>> | null,
+): void {
+  const withMap = job.with as Record<string, unknown> | undefined;
+  if (withMap) {
+    if (resolvedAgents) {
+      assertLiteralAgent(
+        jobKey,
+        'with.agentSlug',
+        withMap['agentSlug'],
+        resolvedAgents,
+      );
+      validateReviewerAgents(jobKey, withMap['reviewers'], resolvedAgents);
+    }
+    if (resolvedSpecs) {
+      assertLiteralDeliverableSpec(
+        jobKey,
+        'with.deliverableSpecRef',
+        withMap['deliverableSpecRef'],
+        resolvedSpecs,
+      );
+    }
+    assertVersioningMode(jobKey, withMap['versioning']);
+  }
+}
+
+function validateReviewerAgents(
+  jobKey: string,
+  reviewers: unknown,
+  resolvedAgents: Readonly<Record<string, ResolvedAgent>>,
+): void {
+  if (!Array.isArray(reviewers)) {
+    return;
+  }
+  for (let i = 0; i < reviewers.length; i++) {
+    const reviewer = reviewers[i];
+    if (
+      reviewer === null ||
+      typeof reviewer !== 'object' ||
+      Array.isArray(reviewer)
+    ) {
+      continue;
+    }
+    assertLiteralAgent(
+      jobKey,
+      `with.reviewers[${i}].agentSlug`,
+      (reviewer as Record<string, unknown>)['agentSlug'],
+      resolvedAgents,
+    );
+  }
+}
+
+/**
+ * Match the literal/expression policy used by `validateAllAuthoredExpressions`:
+ * a value is "literal" when it is a string that does NOT contain `${{`. The
+ * full interpolation grammar is enforced separately by the expression pass —
+ * here we only care whether the compiler can reasonably know the bound value.
+ */
+function isLiteralStringValue(value: unknown): value is string {
+  return typeof value === 'string' && !value.includes('${{');
+}
+
+function assertLiteralAgent(
+  jobKey: string,
+  fieldPath: string,
+  value: unknown,
+  resolvedAgents: Readonly<Record<string, ResolvedAgent>>,
+): void {
+  if (!isLiteralStringValue(value)) {
+    return;
+  }
+  if (resolvedAgents[value] !== undefined) {
+    return;
+  }
+  const knownPreview = formatKnownPreview(Object.keys(resolvedAgents));
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_UNKNOWN_AGENT,
+    `Job '${jobKey}' ${fieldPath} = '${value}' is not a registered agent. Known: [${knownPreview}].`,
+    { jobKey, fieldPath, value, knownCount: Object.keys(resolvedAgents).length },
+  );
+}
+
+function assertLiteralDeliverableSpec(
+  jobKey: string,
+  fieldPath: string,
+  value: unknown,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+): void {
+  if (!isLiteralStringValue(value)) {
+    return;
+  }
+  if (resolvedSpecs[value] !== undefined) {
+    return;
+  }
+  const knownPreview = formatKnownPreview(Object.keys(resolvedSpecs));
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_UNKNOWN_DELIVERABLE_SPEC,
+    `Job '${jobKey}' ${fieldPath} = '${value}' is not a registered deliverable spec. Known: [${knownPreview}].`,
+    { jobKey, fieldPath, value, knownCount: Object.keys(resolvedSpecs).length },
+  );
+}
+
+/**
+ * Closed-set validation for `with.versioning`. Mirrors
+ * `ArtifactVersioningMode` in `@xemahq/platform-common` — duplicated
+ * as a string literal here because workflow-contracts (Layer-1) must
+ * not depend on platform-common (Layer-2). Drift between the two is
+ * caught by a unit test in the artifact-store-api suite.
+ */
+const VALID_VERSIONING_MODES = ['append', 'new', 'replace'] as const;
+
+function assertVersioningMode(jobKey: string, value: unknown): void {
+  if (value === undefined || value === null) return;
+  // Interpolated expressions land here as strings starting with `${{`;
+  // semantics are checked at runtime, so we only reject literal bad
+  // values at compile time.
+  if (typeof value === 'string' && value.startsWith('${{')) return;
+  if (
+    typeof value === 'string' &&
+    (VALID_VERSIONING_MODES as readonly string[]).includes(value)
+  ) {
+    return;
+  }
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+    `Job '${jobKey}' with.versioning = ${JSON.stringify(value)} is not a valid ArtifactVersioningMode. Allowed: [${VALID_VERSIONING_MODES.join(', ')}].`,
+    {
+      jobKey,
+      fieldPath: 'with.versioning',
+      value: typeof value === 'string' ? value : JSON.stringify(value),
+      allowed: [...VALID_VERSIONING_MODES],
+    },
+  );
+}
+
+/**
+ * Lexicographic, stable, capped preview of known keys for the
+ * "Known: [...]" hint in DSL_UNKNOWN_* error messages. Capped at 12
+ * names so a registry of hundreds of agents does not produce a
+ * thousand-character error string.
+ */
+function formatKnownPreview(keys: readonly string[]): string {
+  if (keys.length === 0) {
+    return '(none)';
+  }
+  const sorted = [...keys].sort((a, b) => a.localeCompare(b));
+  if (sorted.length <= 12) {
+    return sorted.join(', ');
+  }
+  return `${sorted.slice(0, 12).join(', ')}, … (+${sorted.length - 12} more)`;
+}
+
+function validateJobExpressions(
+  key: string,
+  job: WorkflowDocument['jobs'][string],
+): void {
+  if (job.if !== undefined) {
+    const body = stripInterpolation(job.if);
+    compileExpression(body);
+  }
+  if (job.with) {
+    const extracted = extractInterpolations(job.with, [key, 'with']);
+    for (const ext of extracted) compileExpression(ext.source);
+  }
+  if (job.outputs) {
+    for (const expr of Object.values(job.outputs)) {
+      const body = stripInterpolation(expr);
+      compileExpression(body);
+    }
+  }
+  if (job.strategy && 'dynamic' in job.strategy) {
+    const body = stripInterpolation(job.strategy.dynamic.from);
+    compileExpression(body);
+  }
+}
+
+/**
+ * Strip the `${{ ... }}` wrapper from each entry of an authored
+ * outputs map and return a frozen body→body map. The compiler's
+ * validation pass already compiled each expression, so this never sees
+ * a malformed body — but we still call `stripInterpolation` to
+ * normalize the storage format the runtime evaluator expects.
+ *
+ * Empty / missing input → frozen empty object so downstream code can
+ * treat the field as a non-nullable map.
+ */
+function compileOutputsMap(
+  raw: Readonly<Record<string, string>> | undefined,
+  contextLabel: string,
+): Readonly<Record<string, string>> {
+  if (!raw || Object.keys(raw).length === 0) {
+    return Object.freeze({}) as Readonly<Record<string, string>>;
+  }
+  const stripped: Record<string, string> = {};
+  for (const [name, expr] of Object.entries(raw)) {
+    try {
+      stripped[name] = stripInterpolation(expr);
+    } catch (err) {
+      // Re-throw with the explicit field path so authors see exactly
+      // which output expression was malformed.
+      const message = err instanceof Error ? err.message : String(err);
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+        `${contextLabel}.${name}: ${message}`,
+        { contextLabel, name, expr },
+      );
+    }
+  }
+  return Object.freeze(stripped) as Readonly<Record<string, string>>;
+}
+
+/**
+ * Compile + validate the workflow-level `outputs:` block. Each entry
+ * is cross-referenced against the workflow's `jobs[fromJob].outputs`
+ * map; missing references fail fast at compile time.
+ *
+ * The frozen result is consumed by biome-host-sdk (mcpWorkflowTools
+ * cross-validation), workflow-engine-api (RunResponseDto.deliverables
+ * projection), and the future workflow_call composition surfaces.
+ */
+function compileWorkflowOutputs(
+  workflow: WorkflowDocument,
+): Readonly<Record<string, import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor>> {
+  const raw = workflow.outputs;
+  if (!raw || Object.keys(raw).length === 0) {
+    return Object.freeze({}) as Readonly<
+      Record<string, import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor>
+    >;
+  }
+  const seenSlugs = new Set<string>();
+  const compiled: Record<
+    string,
+    import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor
+  > = {};
+  for (const [name, decl] of Object.entries(raw)) {
+    const job = workflow.jobs[decl.fromJob];
+    if (!job) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `outputs.${name}: fromJob "${decl.fromJob}" is not a declared job`,
+        { outputName: name, fromJob: decl.fromJob },
+      );
+    }
+    if (!job.outputs || !(decl.fromOutput in job.outputs)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `outputs.${name}: job "${decl.fromJob}" does not declare an output named "${decl.fromOutput}"`,
+        { outputName: name, fromJob: decl.fromJob, fromOutput: decl.fromOutput },
+      );
+    }
+    if (seenSlugs.has(decl.slug)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `outputs.${name}: slug "${decl.slug}" is already used by another output`,
+        { outputName: name, slug: decl.slug },
+      );
+    }
+    seenSlugs.add(decl.slug);
+    if (decl.kind === 'deliverable') {
+      compiled[name] = {
+        kind: 'deliverable',
+        slug: decl.slug,
+        fromJob: decl.fromJob,
+        fromOutput: decl.fromOutput,
+        deliverableSpecRef: decl.deliverableSpecRef,
+        ...(decl.description ? { description: decl.description } : {}),
+      };
+    } else if (decl.kind === 'structured') {
+      compiled[name] = {
+        kind: 'structured',
+        slug: decl.slug,
+        fromJob: decl.fromJob,
+        fromOutput: decl.fromOutput,
+        ...(decl.schemaRef ? { schemaRef: decl.schemaRef } : {}),
+        ...(decl.description ? { description: decl.description } : {}),
+      };
+    } else {
+      compiled[name] = {
+        kind: 'text',
+        slug: decl.slug,
+        fromJob: decl.fromJob,
+        fromOutput: decl.fromOutput,
+        ...(decl.description ? { description: decl.description } : {}),
+      };
+    }
+  }
+  return Object.freeze(compiled) as Readonly<
+    Record<string, import('@xemahq/kernel-contracts/workflow').WorkflowOutputDescriptor>
+  >;
+}
+
+/**
+ * Enforce the `matrixGather:` invariants up-front, before the topological
+ * sort so errors carry the authored jobKey rather than a less useful
+ * cycle/unknown-need complaint. Each entry must name a declared job, the
+ * target job must itself use a matrix strategy, and self-references are
+ * rejected.
+ */
+function validateMatrixGather(doc: WorkflowDocument): void {
+  for (const [jobKey, decl] of Object.entries(doc.jobs)) {
+    const gather = decl.matrixGather;
+    if (!gather || gather.length === 0) continue;
+    for (const target of gather) {
+      if (target === jobKey) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+          `Job '${jobKey}' matrixGather cannot reference itself.`,
+          { jobKey, target },
+        );
+      }
+      const targetDecl = doc.jobs[target];
+      if (!targetDecl) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+          `Job '${jobKey}' matrixGather references unknown job '${target}'.`,
+          { jobKey, target },
+        );
+      }
+      if (!targetDecl.strategy || (!('matrix' in targetDecl.strategy) && !('dynamic' in targetDecl.strategy))) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+          `Job '${jobKey}' matrixGather references '${target}' which has no matrix/dynamic strategy; gathering only makes sense across matrix entries.`,
+          { jobKey, target },
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Cross-job shape validator for `needs.<X>.outputs.…` accesses. Catches
+ * the entire class of "YAML reads like the intent but runtime sees the
+ * wrong shape" bugs at compile time.
+ *
+ * Rules per upstream `<X>`:
+ *   • non-matrix → any access OK; skip.
+ *   • matrix WITHOUT `keyBy` →
+ *       - `outputs.byKey…` → DSL_MATRIX_KEY_NOT_DECLARED.
+ *       - `outputs.<word>` where `<word>` is not `length` / `byKey` →
+ *         DSL_INVALID_MATRIX_OUTPUT_ACCESS (with three-pronged fix-it).
+ *       - `outputs[<numeric literal>]` → OK (positional access).
+ *       - bare `outputs` (no further deref) → OK (consumer takes the
+ *         indexed map as-is).
+ *   • matrix WITH `keyBy` →
+ *       - `outputs.byKey[<string-literal>]` → OK.
+ *       - `outputs.byKey[matrix.<binding>.<keyBy-path>]` → OK iff
+ *         `<binding>` matches THIS job's matrix binding AND
+ *         `<keyBy-path>` matches upstream's declared `keyBy`.
+ *       - any other `outputs.byKey[<expr>]` → DSL_INVALID_MATRIX_OUTPUT_ACCESS.
+ *       - `outputs.<word>` other than `byKey` / `length` and not numeric
+ *         index → DSL_INVALID_MATRIX_OUTPUT_ACCESS.
+ *       - `if:` body cannot use `matrix.*` (binding doesn't exist there)
+ *         — caught generically by the existing evaluator at runtime;
+ *         this validator does not duplicate that check.
+ *
+ * `outputs` and `on.workflow_call.outputs` use `job.outputs.*` /
+ * `needs.<X>.outputs.*` against the *child* run, which is identical
+ * shape — so the same rules apply.
+ */
+function validateAllNeedsAccessShapes(doc: WorkflowDocument): void {
+  for (const [jobKey, job] of Object.entries(doc.jobs)) {
+    const consumerBinding = extractConsumerBinding(job);
+    const expressions = collectJobExpressions(jobKey, job);
+    for (const { source, fieldPath } of expressions) {
+      const ast = compileExpression(source);
+      walkNeedsAccesses(ast, (access) => {
+        validateNeedsAccess(doc, jobKey, fieldPath, consumerBinding, access);
+      });
+    }
+  }
+
+  const callOutputs = doc.on.workflow_call?.outputs;
+  if (callOutputs) {
+    for (const [outputName, expr] of Object.entries(callOutputs)) {
+      const ast = compileExpression(stripInterpolation(expr));
+      walkNeedsAccesses(ast, (access) => {
+        // workflow_call.outputs has no consumer binding (it's a
+        // workflow-level output). Pass null and let the validator
+        // reject any matrix-binding indices.
+        validateNeedsAccess(
+          doc,
+          '<workflow_call.outputs>',
+          `on.workflow_call.outputs.${outputName}`,
+          null,
+          access,
+        );
+      });
+    }
+  }
+}
+
+interface CollectedExpression {
+  readonly source: string;
+  readonly fieldPath: string;
+}
+
+function collectJobExpressions(
+  jobKey: string,
+  job: WorkflowDocument['jobs'][string],
+): readonly CollectedExpression[] {
+  const out: CollectedExpression[] = [];
+  if (job.if !== undefined) {
+    out.push({ source: stripInterpolation(job.if), fieldPath: `${jobKey}.if` });
+  }
+  if (job.with) {
+    for (const ext of extractInterpolations(job.with, [jobKey, 'with'])) {
+      out.push({ source: ext.source, fieldPath: ext.path.join('.') });
+    }
+  }
+  if (job.outputs) {
+    for (const [name, expr] of Object.entries(job.outputs)) {
+      out.push({
+        source: stripInterpolation(expr),
+        fieldPath: `${jobKey}.outputs.${name}`,
+      });
+    }
+  }
+  if (job.strategy && 'dynamic' in job.strategy) {
+    out.push({
+      source: stripInterpolation(job.strategy.dynamic.from),
+      fieldPath: `${jobKey}.strategy.dynamic.from`,
+    });
+  }
+  return out;
+}
+
+/**
+ * The dynamic-matrix `as:` binding name for the current consumer job, or
+ * null when the consumer is not a dynamic matrix. Used by the validator
+ * to allow `byKey[matrix.<thisBinding>.<keyBy-path>]` indices.
+ *
+ * Static matrices bind axis names — those don't pair with upstream
+ * matrix-output keys (different cardinality semantics) so we don't
+ * surface them here.
+ */
+function extractConsumerBinding(
+  job: WorkflowDocument['jobs'][string],
+): string | null {
+  if (job.strategy && 'dynamic' in job.strategy) {
+    return job.strategy.dynamic.as;
+  }
+  return null;
+}
+
+interface NeedsAccess {
+  readonly upstreamJobKey: string;
+  /**
+   * The chain of accesses *after* `needs.<X>.outputs`. Each step is
+   * either `{ kind: 'member', name: string }` (e.g. `.deliverables`,
+   * `.byKey`, `.length`) or `{ kind: 'index', node: ExpressionNode }`
+   * (e.g. `[0]`, `['cu-1']`, `[matrix.x.id]`). Empty chain means the
+   * expression is just `needs.<X>.outputs` (consumer takes the whole
+   * shape as-is).
+   */
+  readonly steps: readonly AccessStep[];
+}
+
+type AccessStep =
+  | { readonly kind: 'member'; readonly name: string }
+  | { readonly kind: 'index'; readonly node: ExpressionNode };
+
+function walkNeedsAccesses(
+  node: ExpressionNode,
+  visit: (access: NeedsAccess) => void,
+): void {
+  // Try to interpret this node as a `needs.<X>.outputs.*` chain. If it
+  // is, emit the access and recurse into any index expressions inside
+  // it (those can also reference `needs.*`). Otherwise recurse into
+  // children generically.
+  const access = matchNeedsAccess(node);
+  if (access !== null) {
+    visit(access);
+    for (const step of access.steps) {
+      if (step.kind === 'index') {
+        walkNeedsAccesses(step.node, visit);
+      }
+    }
+    return;
+  }
+  // Generic recursion for non-needs subtrees.
+  switch (node.kind) {
+    case ExpressionNodeKind.MEMBER:
+      walkNeedsAccesses(node.target, visit);
+      return;
+    case ExpressionNodeKind.INDEX:
+      walkNeedsAccesses(node.target, visit);
+      walkNeedsAccesses(node.index, visit);
+      return;
+    case ExpressionNodeKind.CALL:
+      for (const arg of node.args) walkNeedsAccesses(arg, visit);
+      return;
+    case ExpressionNodeKind.UNARY_NOT:
+      walkNeedsAccesses(node.operand, visit);
+      return;
+    case ExpressionNodeKind.BINARY_EQ:
+    case ExpressionNodeKind.BINARY_NEQ:
+    case ExpressionNodeKind.BINARY_AND:
+    case ExpressionNodeKind.BINARY_OR:
+      walkNeedsAccesses(node.left, visit);
+      walkNeedsAccesses(node.right, visit);
+      return;
+    case ExpressionNodeKind.LITERAL:
+    case ExpressionNodeKind.IDENTIFIER:
+      return;
+  }
+}
+
+/**
+ * Walk a node that might be an outermost `needs.<X>.outputs.<…>` chain.
+ * Returns null if the chain root is not `needs.<X>.outputs`. The
+ * returned chain is in author order (first access first), regardless
+ * of how the parser built the AST.
+ */
+function matchNeedsAccess(node: ExpressionNode): NeedsAccess | null {
+  // Collect the chain by walking down from outermost to innermost,
+  // pushing each step onto a stack we'll reverse at the end.
+  const reverseSteps: AccessStep[] = [];
+  let cursor: ExpressionNode = node;
+  while (
+    cursor.kind === ExpressionNodeKind.MEMBER ||
+    cursor.kind === ExpressionNodeKind.INDEX
+  ) {
+    if (cursor.kind === ExpressionNodeKind.MEMBER) {
+      reverseSteps.push({ kind: 'member', name: cursor.property });
+    } else {
+      reverseSteps.push({ kind: 'index', node: cursor.index });
+    }
+    cursor = cursor.target;
+  }
+  // Innermost must be `needs` IDENTIFIER, then the popped chain must
+  // start with member('<jobKey>') member('outputs').
+  if (
+    cursor.kind !== ExpressionNodeKind.IDENTIFIER ||
+    cursor.name !== 'needs'
+  ) {
+    return null;
+  }
+  const steps = reverseSteps.toReversed();
+  if (steps.length < 2) return null;
+  const first = steps[0]!;
+  const second = steps[1]!;
+  if (first.kind !== 'member') return null;
+  if (second.kind !== 'member' || second.name !== 'outputs') return null;
+  return {
+    upstreamJobKey: first.name,
+    steps: steps.slice(2),
+  };
+}
+
+function validateNeedsAccess(
+  doc: WorkflowDocument,
+  consumerJobKey: string,
+  fieldPath: string,
+  consumerBinding: string | null,
+  access: NeedsAccess,
+): void {
+  const upstream = doc.jobs[access.upstreamJobKey];
+  if (!upstream) {
+    // Unknown upstream — the topo sort already fails this with a more
+    // useful message. Don't double-report.
+    return;
+  }
+  const isDynamicMatrix = !!upstream.strategy && 'dynamic' in upstream.strategy;
+  const isStaticMatrix = !!upstream.strategy && 'matrix' in upstream.strategy;
+  const isMatrix = isDynamicMatrix || isStaticMatrix;
+  if (!isMatrix) {
+    // Single (non-matrix) jobs accept any shape, EXCEPT `byKey[…]` —
+    // single jobs don't have a keyed map. Catch the misuse at compile
+    // time so authors don't get a confusing runtime "Unknown property
+    // byKey" later.
+    if (
+      access.steps.length > 0 &&
+      access.steps[0]!.kind === 'member' &&
+      access.steps[0]!.name === 'byKey'
+    ) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+        `Job '${consumerJobKey}' ${fieldPath}: cannot read 'byKey' on '${access.upstreamJobKey}' because it is not a matrix job. 'byKey' is only available on matrix jobs that declare 'keyBy:'.`,
+        {
+          consumerJobKey,
+          upstreamJobKey: access.upstreamJobKey,
+          fieldPath,
+        },
+      );
+    }
+    return;
+  }
+
+  const consumerJob = doc.jobs[consumerJobKey];
+  if (consumerJob?.matrixGather?.includes(access.upstreamJobKey)) {
+    rejectByKeyOnGathered(access, consumerJobKey, fieldPath);
+    return;
+  }
+
+  const keyBy = isDynamicMatrix
+    ? (upstream.strategy as { dynamic: { keyBy?: string } }).dynamic.keyBy ?? null
+    : null;
+
+  // Bare `needs.X.outputs` is always OK — consumer chooses to receive
+  // the indexed map (or the keyed map; runtime exposes both).
+  if (access.steps.length === 0) return;
+
+  const head = access.steps[0]!;
+
+  if (head.kind === 'member' && head.name === 'byKey') {
+    validateByKeyChain(access, keyBy, consumerJobKey, consumerBinding, fieldPath);
+    return;
+  }
+
+  if (head.kind === 'member') {
+    // `outputs.length` is part of the indexed-map shape — allowed.
+    if (head.name === 'length') return;
+    // Anything else (`outputs.deliverables`, etc.) is the bug we want
+    // to catch at compile time.
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+      `Job '${consumerJobKey}' ${fieldPath}: cannot read 'needs.${access.upstreamJobKey}.outputs.${head.name}' because '${access.upstreamJobKey}' is a matrix job — its outputs are indexed by entry, not by field. Choose one: (1) read positionally with 'outputs[<n>].${head.name}'; (2) flatten with 'matrixGather: [${access.upstreamJobKey}]' on '${consumerJobKey}' and drop the '.${head.name}' suffix; (3) add 'keyBy: <field>' to '${access.upstreamJobKey}' and use 'outputs.byKey[<key>].${head.name}'.`,
+      {
+        consumerJobKey,
+        upstreamJobKey: access.upstreamJobKey,
+        fieldPath,
+        offendingProperty: head.name,
+      },
+    );
+  }
+
+  // `head.kind === 'index'` — positional access. Numeric literals are
+  // the canonical use; non-numeric string literals are nonsense on the
+  // indexed map (no key '0' for a string), but a runtime evaluator
+  // already errors clearly there. Don't over-validate.
+}
+
+function rejectByKeyOnGathered(
+  access: NeedsAccess,
+  consumerJobKey: string,
+  fieldPath: string,
+): void {
+  const head = access.steps[0];
+  if (head?.kind === 'member' && head.name === 'byKey') {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+      `Job '${consumerJobKey}' ${fieldPath}: cannot read 'byKey' on '${access.upstreamJobKey}' because the consumer applies 'matrixGather' which flattens the upstream into an array. Drop 'matrixGather' to enable keyed access, or read positional entries via [n].`,
+      {
+        consumerJobKey,
+        upstreamJobKey: access.upstreamJobKey,
+        fieldPath,
+      },
+    );
+  }
+}
+
+function validateByKeyChain(
+  access: NeedsAccess,
+  upstreamKeyBy: string | null,
+  consumerJobKey: string,
+  consumerBinding: string | null,
+  fieldPath: string,
+): void {
+  if (upstreamKeyBy === null) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_MATRIX_KEY_NOT_DECLARED,
+      `Job '${consumerJobKey}' ${fieldPath}: cannot read 'needs.${access.upstreamJobKey}.outputs.byKey' because '${access.upstreamJobKey}' has no 'keyBy:' declared on its matrix strategy. Add 'keyBy: <field>' to '${access.upstreamJobKey}.strategy.dynamic' to expose a keyed map.`,
+      {
+        consumerJobKey,
+        upstreamJobKey: access.upstreamJobKey,
+        fieldPath,
+      },
+    );
+  }
+  const indexStep = access.steps[1];
+  if (indexStep?.kind !== 'index') {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+      `Job '${consumerJobKey}' ${fieldPath}: 'needs.${access.upstreamJobKey}.outputs.byKey' must be followed by '[<key>]'. Use a string literal or 'matrix.<binding>.${upstreamKeyBy}'.`,
+      {
+        consumerJobKey,
+        upstreamJobKey: access.upstreamJobKey,
+        fieldPath,
+      },
+    );
+  }
+  assertByKeyIndexShape(
+    indexStep.node,
+    upstreamKeyBy,
+    consumerJobKey,
+    consumerBinding,
+    access.upstreamJobKey,
+    fieldPath,
+  );
+}
+
+function assertByKeyIndexShape(
+  indexNode: ExpressionNode,
+  upstreamKeyBy: string,
+  consumerJobKey: string,
+  consumerBinding: string | null,
+  upstreamJobKey: string,
+  fieldPath: string,
+): void {
+  // Acceptable forms:
+  //   • LITERAL string                           → OK
+  //   • IDENTIFIER('matrix') + MEMBER chain matching the consumer's
+  //     binding name and the upstream's keyBy path           → OK
+  // Anything else → DSL_INVALID_MATRIX_OUTPUT_ACCESS.
+
+  if (
+    indexNode.kind === ExpressionNodeKind.LITERAL &&
+    typeof indexNode.value === 'string'
+  ) {
+    return;
+  }
+
+  if (
+    indexNode.kind === ExpressionNodeKind.MEMBER ||
+    indexNode.kind === ExpressionNodeKind.INDEX
+  ) {
+    const path = collectMatrixMemberPath(indexNode);
+    if (path) {
+      if (consumerBinding === null) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+          `Job '${consumerJobKey}' ${fieldPath}: 'matrix.*' indices into 'needs.${upstreamJobKey}.outputs.byKey' require the consumer job to declare its own 'strategy.dynamic'. Use a string literal key instead, or convert '${consumerJobKey}' into a dynamic matrix.`,
+          { consumerJobKey, upstreamJobKey, fieldPath },
+        );
+      }
+      if (path.binding !== consumerBinding) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+          `Job '${consumerJobKey}' ${fieldPath}: 'matrix.${path.binding}' is not bound here — '${consumerJobKey}' binds 'matrix.${consumerBinding}'.`,
+          { consumerJobKey, upstreamJobKey, fieldPath },
+        );
+      }
+      if (path.path !== upstreamKeyBy) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+          `Job '${consumerJobKey}' ${fieldPath}: 'byKey' index reads 'matrix.${path.binding}.${path.path}' but '${upstreamJobKey}' is keyed by '${upstreamKeyBy}'. Match the upstream's 'keyBy:' path or change the upstream's 'keyBy:' to '${path.path}'.`,
+          { consumerJobKey, upstreamJobKey, fieldPath },
+        );
+      }
+      return;
+    }
+  }
+
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+    `Job '${consumerJobKey}' ${fieldPath}: 'needs.${upstreamJobKey}.outputs.byKey[…]' index must be a string literal or 'matrix.<binding>.${upstreamKeyBy}'.`,
+    { consumerJobKey, upstreamJobKey, fieldPath },
+  );
+}
+
+/**
+ * Collapse a chain like `matrix.changeUnit.metadata.id` into
+ * `{ binding: 'changeUnit', path: 'metadata.id' }`. Returns null if the
+ * chain root isn't `matrix.<binding>` or contains an INDEX step (we
+ * only support pure dotted paths in `keyBy`).
+ */
+function collectMatrixMemberPath(
+  node: ExpressionNode,
+): { readonly binding: string; readonly path: string } | null {
+  const reverseProperties: string[] = [];
+  let cursor: ExpressionNode = node;
+  while (cursor.kind === ExpressionNodeKind.MEMBER) {
+    reverseProperties.push(cursor.property);
+    cursor = cursor.target;
+  }
+  if (
+    cursor.kind !== ExpressionNodeKind.IDENTIFIER ||
+    cursor.name !== 'matrix'
+  ) {
+    return null;
+  }
+  const props = reverseProperties.toReversed();
+  if (props.length < 2) return null;
+  const [binding, ...rest] = props;
+  return { binding: binding!, path: rest.join('.') };
+}
+
+function assertStrategyInvariants(compiled: CompiledRun): void {
+  for (const job of compiled.jobs) {
+    if (job.strategy.kind === MatrixStrategyKind.STATIC && job.strategy.entries.length === 0) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Job '${job.jobKey}' static strategy expansion produced zero entries.`,
+        { jobKey: job.jobKey },
+      );
+    }
+  }
+
+  // Permission escalation is already checked per-job. Cycle checked in DAG.
+  // No-op placeholder kept explicit for the next author.
+  const _permissionRef: Readonly<Record<PermissionResource, PermissionScope>> = compiled.permissions;
+  void _permissionRef;
+}
+
+/**
+ * Walk every authored expression and field-check
+ * `<root>.outputs.deliverable.content.value.<field>` accesses (the JSON
+ * payload for `JSON_SCHEMA` / `ZOD_SCHEMA` / `STRUCTURED_JSON` kinds).
+ * `<field>` must be one of the producing job's spec `topLevelKeys` when
+ * the engine pre-fetched them. Other content paths (`pages`, `text`,
+ * `files`, `payload`, `manifestPath`) are kind-discriminated and the
+ * activity-side harvester enforces them at runtime.
+ */
+function validateDeliverableValueExpressions(
+  doc: WorkflowDocument,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+): void {
+  if (Object.keys(resolvedSpecs).length === 0) return;
+
+  for (const [jobKey, job] of Object.entries(doc.jobs)) {
+    const expressions = collectJobExpressions(jobKey, job);
+    for (const { source, fieldPath } of expressions) {
+      const ast = compileExpression(source);
+      walkDeliverableAccesses(ast, (access) => {
+        validateDeliverableAccess(doc, jobKey, fieldPath, access, resolvedSpecs);
+      });
+    }
+  }
+
+  const callOutputs = doc.on.workflow_call?.outputs;
+  if (callOutputs) {
+    for (const [outputName, expr] of Object.entries(callOutputs)) {
+      const ast = compileExpression(stripInterpolation(expr));
+      walkDeliverableAccesses(ast, (access) => {
+        validateDeliverableAccess(
+          doc,
+          '<workflow_call.outputs>',
+          `on.workflow_call.outputs.${outputName}`,
+          access,
+          resolvedSpecs,
+        );
+      });
+    }
+  }
+}
+
+interface ValueFieldDeliverableAccess {
+  readonly upstreamJobKey: string | null;
+  readonly field: string;
+}
+
+function walkDeliverableAccesses(
+  node: ExpressionNode,
+  visit: (access: ValueFieldDeliverableAccess) => void,
+): void {
+  const valueField = matchDeliverableValueFieldAccess(node);
+  if (valueField !== null) {
+    visit(valueField);
+    return;
+  }
+  switch (node.kind) {
+    case ExpressionNodeKind.MEMBER:
+      walkDeliverableAccesses(node.target, visit);
+      return;
+    case ExpressionNodeKind.INDEX:
+      walkDeliverableAccesses(node.target, visit);
+      walkDeliverableAccesses(node.index, visit);
+      return;
+    case ExpressionNodeKind.CALL:
+      for (const arg of node.args) walkDeliverableAccesses(arg, visit);
+      return;
+    case ExpressionNodeKind.UNARY_NOT:
+      walkDeliverableAccesses(node.operand, visit);
+      return;
+    case ExpressionNodeKind.BINARY_EQ:
+    case ExpressionNodeKind.BINARY_NEQ:
+    case ExpressionNodeKind.BINARY_AND:
+    case ExpressionNodeKind.BINARY_OR:
+      walkDeliverableAccesses(node.left, visit);
+      walkDeliverableAccesses(node.right, visit);
+      return;
+    case ExpressionNodeKind.LITERAL:
+    case ExpressionNodeKind.IDENTIFIER:
+      return;
+  }
+}
+
+/**
+ * Match `<root>.outputs.deliverable.content.value.<field>`. `<root>` is
+ * `job` (same-job projection), `needs.<jobKey>` (cross-job), or
+ * `needs.<jobKey>.outputs.byKey[<...>]` (matrix-keyed cross-job — handled
+ * structurally by walking through the byKey index).
+ */
+function matchDeliverableValueFieldAccess(
+  node: ExpressionNode,
+): ValueFieldDeliverableAccess | null {
+  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
+  const field = node.property;
+
+  const valueNode = node.target;
+  if (valueNode.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (valueNode.property !== 'value') return null;
+
+  const contentNode = valueNode.target;
+  if (contentNode.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (contentNode.property !== 'content') return null;
+
+  const deliverableNode = contentNode.target;
+  if (deliverableNode.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (deliverableNode.property !== 'deliverable') return null;
+
+  const outputsNode = deliverableNode.target;
+  if (outputsNode.kind !== ExpressionNodeKind.MEMBER) return null;
+  if (outputsNode.property !== 'outputs') return null;
+
+  const rootNode = outputsNode.target;
+  if (
+    rootNode.kind === ExpressionNodeKind.IDENTIFIER &&
+    rootNode.name === 'job'
+  ) {
+    return { upstreamJobKey: null, field };
+  }
+  if (rootNode.kind === ExpressionNodeKind.MEMBER) {
+    const needsRoot = rootNode.target;
+    if (
+      needsRoot.kind === ExpressionNodeKind.IDENTIFIER &&
+      needsRoot.name === 'needs'
+    ) {
+      return {
+        upstreamJobKey: rootNode.property,
+        field,
+      };
+    }
+    // `needs.<X>.outputs.byKey[<...>].deliverable.content.value.<f>` —
+    // walk through the index node.
+    if (needsRoot.kind === ExpressionNodeKind.MEMBER) {
+      const upstreamRoot = needsRoot.target;
+      if (
+        needsRoot.property === 'outputs' &&
+        upstreamRoot.kind === ExpressionNodeKind.MEMBER
+      ) {
+        // outputs.byKey[<...>] — outputs.target is needs.<X>
+        const needsParent = upstreamRoot.target;
+        if (
+          upstreamRoot.property === 'byKey' &&
+          needsParent.kind === ExpressionNodeKind.IDENTIFIER &&
+          needsParent.name === 'needs'
+        ) {
+          // outputsNode would actually be the index node; this branch
+          // is only reachable via the INDEX path in walkDeliverableAccesses.
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function validateDeliverableAccess(
+  doc: WorkflowDocument,
+  consumerJobKey: string,
+  fieldPath: string,
+  access: ValueFieldDeliverableAccess,
+  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
+): void {
+  // value-field access: validate against producing job's spec when
+  // introspectable.
+  const producingJobKey = access.upstreamJobKey ?? consumerJobKey;
+  const producingJob = doc.jobs[producingJobKey];
+  if (!producingJob) return;
+
+  if (access.upstreamJobKey !== null) {
+    // Explicit `outputs:` projection re-shapes the namespace; skip.
+    if (producingJob.outputs && Object.keys(producingJob.outputs).length > 0) {
+      return;
+    }
+  }
+
+  const withMap = producingJob.with as Record<string, unknown> | undefined;
+  const specRef = withMap?.['deliverableSpecRef'];
+  if (typeof specRef !== 'string' || specRef.length === 0) return;
+  // Skip expression-shaped refs — the spec is unknown until dispatch.
+  if (specRef.includes('${{')) return;
+
+  const spec = resolvedSpecs[specRef];
+  if (!spec) return;
+  if (!spec.topLevelKeys || spec.topLevelKeys.length === 0) return;
+  if (spec.topLevelKeys.includes(access.field)) return;
+
+  const knownPreview = formatKnownPreview(spec.topLevelKeys);
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_UNKNOWN_DELIVERABLE_FIELD,
+    `${fieldPath}: deliverable.content.value.${access.field} is not a top-level field on deliverable spec '${spec.ref}' (produced by job '${producingJobKey}'). Known fields: [${knownPreview}].`,
+    {
+      consumerJobKey,
+      fieldPath,
+      producingJobKey,
+      specRef: spec.ref,
+      field: access.field,
+      knownFields: [...spec.topLevelKeys],
+    },
+  );
+}