@xemahq/dsl 0.8.1 → 0.8.3

package/src/workflow/lib/compiler/mount-plan.ts

@@ -1,190 +0,0 @@
-import {
-  AWP_V1_SPEC,
-  findSlot,
-  isKnownSlotKey,
-  SlotMode,
-  type WorkspaceSpec,
-} from '@xemahq/kernel-contracts/agent-workspace';
-import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
-import type { MountPlan } from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-import type { ActionManifest } from '../types';
-import { isAgentShapedAction } from './action-shape';
-
-/**
- * Compile a job's `with:` block into a compile-time {@link MountPlan} —
- * a declarative list of mount keys grouped by access, validated against
- * (a) the workspace spec's closed slot set and (b) the action manifest's
- * `allowedMounts`.
- *
- * Read/write classification is per-mount with a slot-default fallback:
- *   - `with.mounts.<key>: true` uses the slot's `defaultMode` from the
- *     {@link WorkspaceSpec}.
- *   - `with.mounts.<key>: { mode: 'read-only' | 'read-write' }`
- *     overrides the slot default. The value is the closed `SlotMode`
- *     enum; any other string is rejected fail-fast.
- *
- * The legacy `with.mountKeys: []` / `with.writableMountKeys: []` array
- * form is gone — the action manifest's input schema rejects it before
- * this compiler runs, but we also explicitly reject those keys here so
- * a misconfigured manifest can't sneak the legacy shape through.
- *
- * Concrete {@link MountSource} resolution is NOT the compiler's job: it
- * requires access to the engine's org-scoped resource registry, which is
- * only available at dispatch time.
- *
- * Rules:
- *   - `with.mounts` absent → empty plan (no implicit mounts).
- *   - Unknown slot keys (per the spec) fail fast.
- *   - If the action manifest declares `allowedMounts`, keys outside it
- *     also fail fast.
- *   - Legacy `mountKeys` / `writableMountKeys` keys on `with:` → fail fast
- *     with a migration hint.
- */
-
-const SPEC: WorkspaceSpec = AWP_V1_SPEC;
-
-const LEGACY_MOUNT_KEYS = ['mountKeys', 'writableMountKeys'] as const;
-
-export function compileMountPlan(
-  jobKey: string,
-  withBlock: Readonly<Record<string, unknown>> | undefined,
-  actionManifest: ActionManifest | null,
-): MountPlan {
-  rejectLegacyShape(jobKey, withBlock);
-
-  enforceManifestSourceDiscriminator(jobKey, withBlock, actionManifest);
-
-  const mounts = extractMountsBlock(withBlock);
-  if (!mounts) {
-    return { readOnly: [], readWrite: [] };
-  }
-
-  const allowed =
-    actionManifest?.spec.allowedMounts !== undefined
-      ? new Set(actionManifest.spec.allowedMounts)
-      : null;
-
-  const readOnly: { key: string }[] = [];
-  const readWrite: { key: string }[] = [];
-
-  const sortedKeys = Object.keys(mounts).sort();
-  for (const key of sortedKeys) {
-    const mode = parseMountValue(jobKey, key, mounts[key]);
-    if (!isKnownSlotKey(SPEC, key)) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' requests mount '${key}' which is not a known slot in WorkspaceSpec '${SPEC.id}'.`,
-        { jobKey, mountKey: key, knownSlots: SPEC.slots.map((s) => s.key) },
-      );
-    }
-    if (allowed !== null && !allowed.has(key)) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' requests mount '${key}' but action manifest does not list it in allowedMounts.`,
-        { jobKey, mountKey: key, allowedMounts: [...allowed] },
-      );
-    }
-    const slot = findSlot(SPEC, key);
-    const slotDefault = slot?.defaultMode ?? SlotMode.ReadOnly;
-    const effective = mode ?? slotDefault;
-    if (slot && !slot.allowedModes.includes(effective)) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' requests mount '${key}' with mode '${effective}', which is not in slot allowedModes [${slot.allowedModes.join(', ')}].`,
-        { jobKey, mountKey: key, requestedMode: effective, allowedModes: [...slot.allowedModes] },
-      );
-    }
-    if (effective === SlotMode.ReadWrite) {
-      readWrite.push({ key });
-    } else {
-      readOnly.push({ key });
-    }
-  }
-
-  return { readOnly, readWrite };
-}
-
-function parseMountValue(
-  jobKey: string,
-  mountKey: string,
-  value: unknown,
-): SlotMode | null {
-  if (value === true) return null;
-  if (value && typeof value === 'object' && !Array.isArray(value)) {
-    const obj = value as Record<string, unknown>;
-    const mode = obj['mode'];
-    if (mode === SlotMode.ReadOnly || mode === SlotMode.ReadWrite) {
-      return mode;
-    }
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Job '${jobKey}' mount '${mountKey}' has invalid 'mode': must be '${SlotMode.ReadOnly}' or '${SlotMode.ReadWrite}'.`,
-      { jobKey, mountKey, mode: typeof mode === 'string' ? mode : typeof mode },
-    );
-  }
-  throw new WorkflowDslError(
-    WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-    `Job '${jobKey}' mount '${mountKey}' value must be \`true\` or \`{ mode: 'read-only' | 'read-write' }\`.`,
-    { jobKey, mountKey, valueKind: Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value },
-  );
-}
-
-function extractMountsBlock(
-  withBlock: Readonly<Record<string, unknown>> | undefined,
-): Readonly<Record<string, unknown>> | null {
-  if (!withBlock) return null;
-  const raw = withBlock['mounts'];
-  if (raw === undefined) return null;
-  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `\`with.mounts\` must be an object mapping slot keys to \`true\` or \`{ mode }\`.`,
-      { mountsKind: Array.isArray(raw) ? 'array' : raw === null ? 'null' : typeof raw },
-    );
-  }
-  return raw as Readonly<Record<string, unknown>>;
-}
-
-function rejectLegacyShape(
-  jobKey: string,
-  withBlock: Readonly<Record<string, unknown>> | undefined,
-): void {
-  if (!withBlock) return;
-  for (const legacyKey of LEGACY_MOUNT_KEYS) {
-    if (legacyKey in withBlock) {
-      throw new WorkflowDslError(
-        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-        `Job '${jobKey}' uses legacy '${legacyKey}' on \`with:\`. Migrate to \`with.mounts\` (object form): \`mounts: { references: true, deliverables: { mode: 'read-write' } }\`.`,
-        { jobKey, legacyKey },
-      );
-    }
-  }
-}
-
-/**
- * Manifest-source requirement: every agent-shaped action must name its
- * agent via `with.agentRef`. `agentRef` is the SOLE source — there is no
- * inline `mounts` short-form anymore. Detected generically so
- * biome-shipped agent actions inherit the same compile-time check
- * without a hardcoded action-id allowlist.
- */
-function enforceManifestSourceDiscriminator(
-  jobKey: string,
-  withBlock: Readonly<Record<string, unknown>> | undefined,
-  actionManifest: ActionManifest | null,
-): void {
-  if (!isAgentShapedAction(actionManifest)) return;
-  const hasRef =
-    withBlock !== undefined &&
-    'agentRef' in withBlock &&
-    typeof withBlock['agentRef'] === 'string' &&
-    (withBlock['agentRef'] as string).length > 0;
-  if (!hasRef) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
-      `Job '${jobKey}' is an agent-shaped action but does not set \`with.agentRef\`. \`agentRef\` (a \`<slug>\` or \`<slug>@<version>\` reference) is the only way a workflow names its agent.`,
-      { jobKey, actionId: actionManifest.metadata.id },
-    );
-  }
-}

package/src/workflow/lib/compiler/payload-reach-in.ts

@@ -1,497 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Payload reach-in validation ──
-//
-// Workflow YAML supports two flavours of `needs.<X>.outputs.<name>.<field>`:
-//
-//   1. Envelope-field access — `<field>` is one of
-//      {artifactId, versionId, version, hash, type, title}. Free; the
-//      runtime reads it off the ArtifactRef without fetching bytes.
-//      Already works structurally via `readProperty` on the ref object.
-//
-//   2. Payload reach-in — `<field>` is a property on the bound
-//      deliverable spec's JSON Schema. Requires the runtime to
-//      pre-fetch the artifact's parsed payload into the per-step
-//      `payloadCache`. The compiler validates the path against the
-//      bound spec at compile time so authors get a clean DSL error
-//      instead of a runtime "Unknown property" surfacing as
-//      `DSL_EXPRESSION_INVALID`.
-//
-// This module owns family #2's compile-time checks. The actual runtime
-// pre-fetch is the worker's responsibility — see the plan section on
-// "Compile-time resolution (chosen approach)" — and is gated by the
-// engine wiring spec metadata into `ResolvedDeliverableSpec`. Until
-// that wiring lands for every spec, this validator gracefully skips
-// when it cannot prove typing (the runtime then fails fast via
-// `DSL_PAYLOAD_PARSE_ERROR` if the author insisted on a payload field
-// without a typed binding).
-// ═══════════════════════════════════════════════════════════════════════════
-
-import {
-  isArtifactRefEnvelopeField,
-  WorkflowErrorCode,
-  type PayloadReachInPin,
-} from '@xemahq/kernel-contracts/workflow';
-import { WorkflowDslError } from '../errors';
-import {
-  compileExpression,
-  ExpressionNodeKind,
-  stripInterpolation,
-  type ExpressionNode,
-  extractInterpolations,
-} from '../expression';
-import type { WorkflowDocument } from '../types';
-import type { ResolvedDeliverableSpec, ResolvedRef } from './types';
-
-/**
- * Lookup helper: given an upstream job (by key) and an output name,
- * return the deliverable-spec ref the upstream activity manifest pins
- * for that output, or `null` when the manifest declares no per-output
- * binding for it. The compiler prefers this over `with.deliverableSpecRef`
- * — per-output bindings are activity-declared contracts; the job-level
- * `with.deliverableSpecRef` is the workflow-author chosen runtime spec
- * (dynamic, e.g. for the agent activity). They can coexist on the same
- * job; the per-output binding wins for outputs it covers.
- */
-function lookupOutputBindingSpecRef(
-  upstream: WorkflowDocument['jobs'][string],
-  outputName: string,
-  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
-): string | null {
-  const ref = resolvedRefs[upstream.uses];
-  const bindings = ref?.actionManifest?.spec.outputBindings;
-  if (!bindings) return null;
-  const binding = bindings[outputName];
-  if (!binding) return null;
-  const specRef = binding.deliverableSpecRef;
-  if (typeof specRef !== 'string' || specRef.length === 0) return null;
-  return specRef;
-}
-
-/**
- * Walk every authored expression and field-check
- * `needs.<X>.outputs.<name>.<field>` reach-ins.
- *
- * Decision table for each `<name>.<field>`:
- *   • `<field>` is an ArtifactRef envelope field → OK (no payload fetch).
- *   • Upstream activity manifest declares `outputBindings.<name>.deliverableSpecRef`
- *     (per-output binding) → use that spec; otherwise fall back
- *     to the upstream job's `with.deliverableSpecRef`. Then:
- *       - resolved spec has `topLevelKeys` and `<field>` is one → OK.
- *       - resolved spec has `topLevelKeys` and `<field>` is NOT one →
- *         `DSL_FIELD_NOT_IN_SCHEMA`.
- *   • Neither per-output binding NOR `with.deliverableSpecRef` is set,
- *     upstream has no `outputs:` projection, and no expression-shaped
- *     ref → `DSL_FIELD_NOT_TYPED`.
- *   • Otherwise (custom `outputs:` projection, expression-shaped ref,
- *     unknown spec, non-introspectable kind) → skip; the runtime
- *     evaluator + `payloadCache` will fail fast via
- *     `DSL_PAYLOAD_PARSE_ERROR` if the path is ultimately invalid.
- *
- * The validator runs only when `resolvedSpecs` is non-empty — same
- * opt-out convention as the rest of the compiler (preview-raw passes
- * an empty map).
- */
-export function validatePayloadReachIns(
-  doc: WorkflowDocument,
-  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
-  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
-): 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);
-      walkPayloadReachIns(ast, (access) => {
-        validateReachIn(
-          doc,
-          jobKey,
-          fieldPath,
-          access,
-          resolvedSpecs,
-          resolvedRefs,
-        );
-      });
-    }
-  }
-
-  const callOutputs = doc.on.workflow_call?.outputs;
-  if (callOutputs) {
-    for (const [outputName, expr] of Object.entries(callOutputs)) {
-      const ast = compileExpression(stripInterpolation(expr));
-      walkPayloadReachIns(ast, (access) => {
-        validateReachIn(
-          doc,
-          '<workflow_call.outputs>',
-          `on.workflow_call.outputs.${outputName}`,
-          access,
-          resolvedSpecs,
-          resolvedRefs,
-        );
-      });
-    }
-  }
-}
-
-/**
- * Walk every reach-in for a single job and emit one pin per
- * `(upstreamJobKey, specRef)` pair. Pins drive the runtime spec-version
- * assertion — the worker pre-fetches
- * the artifact and refuses to proceed when its `schemaVersion` doesn't
- * match the pin's `specVersion`.
- *
- * Returns `[]` when the job has no resolvable reach-ins (no upstream
- * spec, expression-shaped ref, or projected upstream `outputs:`).
- */
-export function collectPayloadReachInsForJob(
-  doc: WorkflowDocument,
-  jobKey: string,
-  job: WorkflowDocument['jobs'][string],
-  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
-  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
-): readonly PayloadReachInPin[] {
-  if (Object.keys(resolvedSpecs).length === 0) return [];
-
-  const pins: PayloadReachInPin[] = [];
-  const seen = new Set<string>();
-
-  const expressions = collectJobExpressions(jobKey, job);
-  for (const { source, fieldPath } of expressions) {
-    let ast;
-    try {
-      ast = compileExpression(source);
-    } catch {
-      continue;
-    }
-    walkPayloadReachIns(ast, (access) => {
-      const pin = resolveReachInPin(
-        doc,
-        fieldPath,
-        access,
-        resolvedSpecs,
-        resolvedRefs,
-      );
-      if (pin === null) return;
-      const dedupeKey = `${pin.upstreamJobKey}|${pin.outputName}|${pin.specRef}`;
-      if (seen.has(dedupeKey)) return;
-      seen.add(dedupeKey);
-      pins.push(pin);
-    });
-  }
-
-  return pins;
-}
-
-/**
- * Resolve one reach-in to a pin entry, returning `null` when the pin
- * cannot be statically materialized (e.g. expression-shaped specRef,
- * upstream has a custom `outputs:` projection, spec not in the resolved
- * map). The validator emits the user-facing error path; this collector
- * is silent on un-resolvable reach-ins because the validator already
- * surfaced them.
- */
-function resolveReachInPin(
-  doc: WorkflowDocument,
-  fieldPath: string,
-  access: PayloadReachIn,
-  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
-  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
-): PayloadReachInPin | null {
-  const upstream = doc.jobs[access.upstreamJobKey];
-  if (!upstream) return null;
-  if (upstream.outputs && Object.keys(upstream.outputs).length > 0) {
-    return null;
-  }
-
-  // Prefer per-output binding from the upstream activity manifest.
-  // Falls back to the job-level `with.deliverableSpecRef`
-  // when no per-output binding is declared OR when the reach-in's
-  // outputName is one of the indexed sentinels.
-  let specRef: string | null = null;
-  let outputName: string | null = null;
-  if (
-    access.outputName !== '<indexed>' &&
-    access.outputName !== '<byKey>'
-  ) {
-    const perOutputRef = lookupOutputBindingSpecRef(
-      upstream,
-      access.outputName,
-      resolvedRefs,
-    );
-    if (perOutputRef !== null) {
-      specRef = perOutputRef;
-      outputName = access.outputName;
-    }
-  }
-  if (specRef === null) {
-    const withMap = upstream.with as Record<string, unknown> | undefined;
-    const fromWith = withMap?.['deliverableSpecRef'];
-    if (typeof fromWith !== 'string' || fromWith.length === 0) return null;
-    if (fromWith.includes('${{')) return null;
-    specRef = fromWith;
-  }
-
-  const spec = resolvedSpecs[specRef];
-  if (!spec) return null;
-  const at = specRef.lastIndexOf('@');
-  const specVersion = at >= 0 ? specRef.slice(at + 1) : '';
-  if (specVersion.length === 0) return null;
-  return {
-    fieldPath,
-    upstreamJobKey: access.upstreamJobKey,
-    outputName,
-    specRef,
-    specVersion,
-  };
-}
-
-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;
-}
-
-interface PayloadReachIn {
-  readonly upstreamJobKey: string;
-  readonly outputName: string;
-  readonly field: string;
-}
-
-export function walkPayloadReachIns(
-  node: ExpressionNode,
-  visit: (access: PayloadReachIn) => void,
-): void {
-  const match = matchPayloadReachIn(node);
-  if (match !== null) {
-    visit(match);
-    // Continue recursion so nested expressions inside index nodes are
-    // also walked — e.g. byKey[needs.Y.outputs.foo.bar] would carry
-    // its own reach-in.
-  }
-  switch (node.kind) {
-    case ExpressionNodeKind.MEMBER:
-      walkPayloadReachIns(node.target, visit);
-      return;
-    case ExpressionNodeKind.INDEX:
-      walkPayloadReachIns(node.target, visit);
-      walkPayloadReachIns(node.index, visit);
-      return;
-    case ExpressionNodeKind.CALL:
-      // Skip `fromJSON(...)` and `toJSON(...)` arguments — those are
-      // the documented escape hatch; the author opted out of typed
-      // reach-in validation by wrapping the ref.
-      for (const arg of node.args) walkPayloadReachIns(arg, visit);
-      return;
-    case ExpressionNodeKind.UNARY_NOT:
-      walkPayloadReachIns(node.operand, visit);
-      return;
-    case ExpressionNodeKind.BINARY_EQ:
-    case ExpressionNodeKind.BINARY_NEQ:
-    case ExpressionNodeKind.BINARY_AND:
-    case ExpressionNodeKind.BINARY_OR:
-      walkPayloadReachIns(node.left, visit);
-      walkPayloadReachIns(node.right, visit);
-      return;
-    case ExpressionNodeKind.LITERAL:
-    case ExpressionNodeKind.IDENTIFIER:
-      return;
-  }
-}
-
-/**
- * Match the outermost `needs.<X>.outputs.<name>.<field>` shape. Returns
- * null if the chain doesn't match, OR if `<field>` is an envelope
- * field (the runtime reads those off the ArtifactRef without a fetch).
- *
- * Also matches:
- *   needs.<X>.outputs[N].<field>
- *   needs.<X>.outputs.byKey['k'].<field>
- *
- * For these, `<name>` is set to a sentinel so the validator still
- * resolves the upstream job's spec but doesn't attempt per-output
- * name resolution (today's data model declares the spec at the
- * job level, not per-output — see the plan's "B." section).
- */
-function matchPayloadReachIn(node: ExpressionNode): PayloadReachIn | null {
-  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
-  const field = node.property;
-  if (isArtifactRefEnvelopeField(field)) return null;
-
-  // Walk one level up: `<base>.<field>` where `<base>` must resolve to
-  // `needs.<X>.outputs.<name>` (or an indexed/keyed variant).
-  const base = node.target;
-
-  // Form A: needs.<X>.outputs.<name>.<field>
-  if (base.kind === ExpressionNodeKind.MEMBER) {
-    const outputName = base.property;
-    if (outputName === 'byKey') return null; // handled below
-    const outputsNode = base.target;
-    const upstreamKey = matchNeedsOutputsRoot(outputsNode);
-    if (upstreamKey !== null) {
-      return { upstreamJobKey: upstreamKey, outputName, field };
-    }
-  }
-
-  // Form B: needs.<X>.outputs[N].<field>  OR  needs.<X>.outputs.byKey['k'].<field>
-  if (base.kind === ExpressionNodeKind.INDEX) {
-    const indexed = base.target;
-    // outputs[N]
-    const upstreamFromOutputs = matchNeedsOutputsRoot(indexed);
-    if (upstreamFromOutputs !== null) {
-      return {
-        upstreamJobKey: upstreamFromOutputs,
-        outputName: '<indexed>',
-        field,
-      };
-    }
-    // outputs.byKey['k']
-    if (
-      indexed.kind === ExpressionNodeKind.MEMBER &&
-      indexed.property === 'byKey'
-    ) {
-      const upstreamFromByKey = matchNeedsOutputsRoot(indexed.target);
-      if (upstreamFromByKey !== null) {
-        return {
-          upstreamJobKey: upstreamFromByKey,
-          outputName: '<byKey>',
-          field,
-        };
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Match the chain `needs.<X>.outputs`. Returns the upstream job key, or
- * null if the node isn't that shape.
- */
-function matchNeedsOutputsRoot(node: ExpressionNode): string | null {
-  if (node.kind !== ExpressionNodeKind.MEMBER) return null;
-  if (node.property !== 'outputs') return null;
-  const needsRoot = node.target;
-  if (needsRoot.kind !== ExpressionNodeKind.MEMBER) return null;
-  const upstreamKey = needsRoot.property;
-  const ident = needsRoot.target;
-  if (ident.kind !== ExpressionNodeKind.IDENTIFIER) return null;
-  if (ident.name !== 'needs') return null;
-  return upstreamKey;
-}
-
-function validateReachIn(
-  doc: WorkflowDocument,
-  consumerJobKey: string,
-  fieldPath: string,
-  access: PayloadReachIn,
-  resolvedSpecs: Readonly<Record<string, ResolvedDeliverableSpec>>,
-  resolvedRefs: Readonly<Record<string, ResolvedRef>>,
-): void {
-  const upstream = doc.jobs[access.upstreamJobKey];
-  if (!upstream) {
-    // Topological-sort step already raises a clearer error for unknown
-    // upstreams; don't double-report here.
-    return;
-  }
-
-  // If the upstream declares an `outputs:` projection, it re-shapes the
-  // exposed namespace. We can't statically introspect arbitrary author
-  // projections, so skip — the projection itself is expression-validated
-  // upstream.
-  if (upstream.outputs && Object.keys(upstream.outputs).length > 0) {
-    return;
-  }
-
-  // Per-output binding from the upstream activity manifest
-  // wins over the job-level `with.deliverableSpecRef` when present.
-  const perOutputBinding =
-    access.outputName === '<indexed>' || access.outputName === '<byKey>'
-      ? null
-      : lookupOutputBindingSpecRef(upstream, access.outputName, resolvedRefs);
-
-  const withMap = upstream.with as Record<string, unknown> | undefined;
-  const specRef = perOutputBinding ?? withMap?.['deliverableSpecRef'];
-
-  // Expression-shaped spec → unknowable at compile time. Runtime
-  // surfaces `DSL_PAYLOAD_PARSE_ERROR` if reach-in is ultimately wrong.
-  if (typeof specRef === 'string' && specRef.includes('${{')) {
-    return;
-  }
-
-  if (typeof specRef !== 'string' || specRef.length === 0) {
-    throw new WorkflowDslError(
-      WorkflowErrorCode.DSL_FIELD_NOT_TYPED,
-      `${fieldPath}: 'needs.${access.upstreamJobKey}.outputs.${access.outputName}.${access.field}' reaches into the payload of an output that has no schema-bearing deliverable spec. Either bind a typed 'with.deliverableSpecRef' on '${access.upstreamJobKey}' or use the 'fromJSON(...)' escape hatch.`,
-      {
-        consumerJobKey,
-        upstreamJobKey: access.upstreamJobKey,
-        outputName: access.outputName,
-        field: access.field,
-        fieldPath,
-      },
-    );
-  }
-
-  const spec = resolvedSpecs[specRef];
-  if (!spec) {
-    // Engine couldn't resolve the spec (e.g. registry unreachable) —
-    // the existing literal-reference validator already emits
-    // `DSL_UNKNOWN_DELIVERABLE_SPEC` for this case; don't double-report.
-    return;
-  }
-  if (!spec.topLevelKeys || spec.topLevelKeys.length === 0) {
-    // Spec kind doesn't support static field introspection
-    // (DOCUMENT_TEMPLATE, STRUCTURED_JSON, CUSTOM, …). Defer to runtime.
-    return;
-  }
-  if (spec.topLevelKeys.includes(access.field)) {
-    // Valid reach-in. The runtime is responsible for pre-fetching this
-    // artifact's payload into the per-step `payloadCache` before the
-    // expression evaluates — see the plan's runtime-resolver scaffold.
-    return;
-  }
-
-  const knownPreview = spec.topLevelKeys.slice(0, 12).join(', ');
-  throw new WorkflowDslError(
-    WorkflowErrorCode.DSL_FIELD_NOT_IN_SCHEMA,
-    `${fieldPath}: 'needs.${access.upstreamJobKey}.outputs.${access.outputName}.${access.field}' is not a top-level field on deliverable spec '${spec.ref}' (bound by '${access.upstreamJobKey}.with.deliverableSpecRef'). Known fields: [${knownPreview}].`,
-    {
-      consumerJobKey,
-      upstreamJobKey: access.upstreamJobKey,
-      outputName: access.outputName,
-      field: access.field,
-      fieldPath,
-      specRef: spec.ref,
-      knownFields: [...spec.topLevelKeys],
-    },
-  );
-}