SPICE-0020: Deferred, type-safe references (#1354)

docs/modules/ROOT/partials/component-attributes.adoc

@@ -69,6 +69,7 @@ endif::[]
 
 :uri-stdlib-baseModule: {uri-pkl-stdlib-docs}/base
 :uri-stdlib-CommandModule: {uri-pkl-stdlib-docs}/Command
+:uri-stdlib-refModule: {uri-pkl-stdlib-docs}/ref
 :uri-stdlib-analyzeModule: {uri-pkl-stdlib-docs}/analyze
 :uri-stdlib-jsonnetModule: {uri-pkl-stdlib-docs}/jsonnet
 :uri-stdlib-reflectModule: {uri-pkl-stdlib-docs}/reflect
@@ -160,6 +161,8 @@ endif::[]
 :uri-stdlib-Command-CountedFlag: {uri-stdlib-CommandModule}/CountedFlag
 :uri-stdlib-Command-Argument: {uri-stdlib-CommandModule}/Argument
 :uri-stdlib-Command-Import: {uri-stdlib-CommandModule}/Import
+:uri-stdlib-ref-Reference: {uri-stdlib-baseModule}/Reference
+:uri-stdlib-ref-Access: {uri-stdlib-baseModule}/Access
 
 :uri-messagepack: https://msgpack.org/index.html
 :uri-messagepack-spec: https://github.com/msgpack/msgpack/blob/master/spec.md

docs/modules/bindings-specification/pages/binary-encoding.adoc

@@ -187,7 +187,15 @@ The array's length is the number of slots that are filled. For example, xref:{ur
 |
 |
 |
-|===
+
+|link:{uri-stdlib-ref-Reference}[Reference]
+|`0x20`
+|`<value>` (Typed)
+|Domain
+|`<value>`
+|Data
+|link:{uri-messagepack-array}[array]
+|Array of link:{uri-stdlib-ref-Access}[`pkl.ref#Access`] values
 
 [[type-name-encoding]]
 [NOTE]

pkl-core/src/main/java/org/pkl/core/PClass.java

@@ -27,6 +27,7 @@ public final class PClass extends Member implements Value {
   private final List<TypeParameter> typeParameters;
   private final Map<String, Property> properties;
   private final Map<String, Method> methods;
+  private final @Nullable PClass moduleClass;
 
   private @Nullable PType supertype;
   private @Nullable PClass superclass;
@@ -42,12 +43,14 @@ public final class PClass extends Member implements Value {
       PClassInfo<?> classInfo,
       List<TypeParameter> typeParameters,
       Map<String, Property> properties,
-      Map<String, Method> methods) {
+      Map<String, Method> methods,
+      @Nullable PClass moduleClass) {
     super(docComment, sourceLocation, modifiers, annotations, classInfo.getSimpleName());
     this.classInfo = classInfo;
     this.typeParameters = typeParameters;
     this.properties = properties;
     this.methods = methods;
+    this.moduleClass = moduleClass;
   }
 
   public void initSupertype(PType supertype, PClass superclass) {
@@ -57,7 +60,7 @@ public final class PClass extends Member implements Value {
 
   /**
    * Returns the name of the module that this class is declared in. Note that a module name is not
-   * guaranteed to be unique, especially if it not declared but inferred from the module URI.
+   * guaranteed to be unique, especially if it is not declared but inferred from the module URI.
    */
   public String getModuleName() {
     return classInfo.getModuleName();
@@ -119,6 +122,11 @@ public final class PClass extends Member implements Value {
     return allMethods;
   }
 
+  /** Returns the class's containing module's class, or this class if it is a module class. */
+  public PClass getModuleClass() {
+    return moduleClass != null ? moduleClass : this;
+  }
+
   @Override
   public void accept(ValueVisitor visitor) {
     visitor.visitClass(this);
@@ -138,6 +146,10 @@ public final class PClass extends Member implements Value {
     return getDisplayName();
   }
 
+  public boolean isSubclassOf(PClass other) {
+    return this == other || getSuperclass() != null && getSuperclass().isSubclassOf(other);
+  }
+
   public abstract static class ClassMember extends Member {
     @Serial private static final long serialVersionUID = 0L;
 

pkl-core/src/main/java/org/pkl/core/PClassInfo.java

@@ -39,6 +39,7 @@ public final class PClassInfo<T> implements Serializable {
   public static final URI pklSemverUri = URI.create("pkl:semver");
   public static final URI pklSettingsUri = URI.create("pkl:settings");
   public static final URI pklProjectUri = URI.create("pkl:Project");
+  public static final URI pklRefUri = URI.create("pkl:ref");
 
   public static final PClassInfo<Void> Any = pklBaseClassInfo("Any", Void.class);
   public static final PClassInfo<PNull> Null = pklBaseClassInfo("Null", PNull.class);
@@ -82,9 +83,11 @@ public final class PClassInfo<T> implements Serializable {
   public static final PClassInfo<PObject> Version =
       new PClassInfo<>("pkl.semver", "Version", PObject.class, pklSemverUri);
   public static final PClassInfo<PObject> Project =
-      new PClassInfo<>("pkl.Project", "ModuleClass", PObject.class, pklProjectUri);
+      new PClassInfo<>("pkl.Project", MODULE_CLASS_NAME, PObject.class, pklProjectUri);
   public static final PClassInfo<PObject> Settings =
-      new PClassInfo<>("pkl.settings", "ModuleClass", PObject.class, pklSettingsUri);
+      new PClassInfo<>("pkl.settings", MODULE_CLASS_NAME, PObject.class, pklSettingsUri);
+  public static final PClassInfo<Reference> Reference =
+      new PClassInfo<>("pkl.ref", "Reference", Reference.class, pklRefUri);
 
   public static final PClassInfo<Object> Unavailable =
       new PClassInfo<>("unavailable", "unavailable", Object.class, URI.create("pkl:unavailable"));

pkl-core/src/main/java/org/pkl/core/PType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ package org.pkl.core;
 import java.io.Serial;
 import java.io.Serializable;
 import java.util.*;
+import java.util.stream.Collectors;
 
 /** A Pkl type as used in type annotations. */
 public abstract class PType implements Serializable {
@@ -27,18 +28,33 @@ public abstract class PType implements Serializable {
   public static final PType UNKNOWN =
       new PType() {
         @Serial private static final long serialVersionUID = 0L;
+
+        @Override
+        public String toString() {
+          return "unknown";
+        }
       };
 
   /** The bottom type. */
   public static final PType NOTHING =
       new PType() {
         @Serial private static final long serialVersionUID = 0L;
+
+        @Override
+        public String toString() {
+          return "nothing";
+        }
       };
 
   /** The type of the enclosing module. */
   public static final PType MODULE =
       new PType() {
         @Serial private static final long serialVersionUID = 0L;
+
+        @Override
+        public String toString() {
+          return "module";
+        }
       };
 
   private PType() {}
@@ -59,6 +75,11 @@ public abstract class PType implements Serializable {
     public String getLiteral() {
       return literal;
     }
+
+    @Override
+    public String toString() {
+      return ValueFormatter.basic().formatStringValue(literal, "");
+    }
   }
 
   public static final class Class extends PType {
@@ -92,6 +113,18 @@ public abstract class PType implements Serializable {
     public List<PType> getTypeArguments() {
       return typeArguments;
     }
+
+    @Override
+    public String toString() {
+      var result = pClass.getDisplayName();
+      if (!typeArguments.isEmpty()) {
+        result +=
+            "<"
+                + typeArguments.stream().map(Object::toString).collect(Collectors.joining(", "))
+                + ">";
+      }
+      return result;
+    }
   }
 
   public static final class Nullable extends PType {
@@ -106,6 +139,13 @@ public abstract class PType implements Serializable {
     public PType getBaseType() {
       return baseType;
     }
+
+    @Override
+    public String toString() {
+      return baseType instanceof Function || baseType instanceof Union
+          ? "(" + baseType + ")?"
+          : baseType + "?";
+    }
   }
 
   public static final class Constrained extends PType {
@@ -126,6 +166,16 @@ public abstract class PType implements Serializable {
     public List<String> getConstraints() {
       return constraints;
     }
+
+    @Override
+    public String toString() {
+      return (baseType instanceof Function || baseType instanceof Union
+              ? "(" + baseType + ")"
+              : baseType)
+          + "("
+          + String.join(", ", constraints)
+          + ")";
+    }
   }
 
   public static final class Alias extends PType {
@@ -161,6 +211,18 @@ public abstract class PType implements Serializable {
     public PType getAliasedType() {
       return aliasedType;
     }
+
+    @Override
+    public String toString() {
+      var result = typeAlias.getDisplayName();
+      if (!typeArguments.isEmpty()) {
+        result +=
+            "<"
+                + typeArguments.stream().map(Object::toString).collect(Collectors.joining(", "))
+                + ">";
+      }
+      return result;
+    }
   }
 
   public static final class Function extends PType {
@@ -181,6 +243,14 @@ public abstract class PType implements Serializable {
     public PType getReturnType() {
       return returnType;
     }
+
+    @Override
+    public String toString() {
+      return "("
+          + parameterTypes.stream().map(Object::toString).collect(Collectors.joining(", "))
+          + ") -> "
+          + returnType;
+    }
   }
 
   public static final class Union extends PType {
@@ -195,6 +265,11 @@ public abstract class PType implements Serializable {
     public List<PType> getElementTypes() {
       return elementTypes;
     }
+
+    @Override
+    public String toString() {
+      return elementTypes.stream().map(Object::toString).collect(Collectors.joining(" | "));
+    }
   }
 
   public static final class TypeVariable extends PType {
@@ -213,5 +288,10 @@ public abstract class PType implements Serializable {
     public TypeParameter getTypeParameter() {
       return typeParameter;
     }
+
+    @Override
+    public String toString() {
+      return typeParameter.getName();
+    }
   }
 }

pkl-core/src/main/java/org/pkl/core/PropertiesRenderer.java

@@ -177,6 +177,13 @@ final class PropertiesRenderer implements ValueRenderer {
               "Values of type `Regex` cannot be rendered as Properties. Value: %s", value));
     }
 
+    @Override
+    public String convertReference(Reference value) {
+      throw new RendererException(
+          String.format(
+              "Values of type `Reference` cannot be rendered as Properties. Value: %s", value));
+    }
+
     private void doVisitMap(@Nullable String keyPrefix, Map<?, ?> map) {
       for (Map.Entry<?, ?> entry : map.entrySet()) {
         doVisitKeyAndValue(keyPrefix, entry.getKey(), entry.getValue());

pkl-core/src/main/java/org/pkl/core/Reference.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core;
+
+import java.io.Serial;
+import java.util.List;
+
+public class Reference implements Value {
+  @Serial private static final long serialVersionUID = 0L;
+
+  private final Composite domain;
+  private final Object data;
+  private final List<Composite> path;
+  private final PType referentType;
+
+  /** Constructs a reference. */
+  public Reference(Composite domain, Object data, List<Composite> path, PType referentType) {
+    this.domain = domain;
+    this.data = data;
+    this.path = path;
+    this.referentType = referentType;
+  }
+
+  /** Returns the domain object of this reference. */
+  public Composite getDomain() {
+    return domain;
+  }
+
+  /** Returns the data object of this reference. */
+  public Object getData() {
+    return data;
+  }
+
+  /**
+   * Returns the access path of this reference.
+   *
+   * <p>All elements are exported {@code pkl.ref#Access} instances.
+   */
+  public List<Composite> getPath() {
+    return path;
+  }
+
+  /** Returns the referent type of this reference. */
+  public PType getReferentType() {
+    return referentType;
+  }
+
+  @Override
+  public void accept(ValueVisitor visitor) {
+    visitor.visitReference(this);
+  }
+
+  @Override
+  public <T> T accept(ValueConverter<T> converter) {
+    return converter.convertReference(this);
+  }
+
+  @Override
+  public final boolean equals(Object o) {
+    if (!(o instanceof Reference reference)) {
+      return false;
+    }
+
+    return domain.equals(reference.domain)
+        && data.equals(reference.data)
+        && path.equals(reference.path)
+        && referentType.equals(reference.referentType);
+  }
+
+  @Override
+  public PClassInfo<?> getClassInfo() {
+    return PClassInfo.Reference;
+  }
+
+  @Override
+  public int hashCode() {
+    int result = domain.hashCode();
+    result = 31 * result + data.hashCode();
+    result = 31 * result + path.hashCode();
+    result = 31 * result + referentType.hashCode();
+    return result;
+  }
+
+  @Override
+  public String toString() {
+    return super.toString();
+  }
+}

pkl-core/src/main/java/org/pkl/core/TypeAlias.java

@@ -28,6 +28,7 @@ public final class TypeAlias extends Member implements Value {
   private final String moduleName;
   private final String qualifiedName;
   private final List<TypeParameter> typeParameters;
+  private final PClass moduleClass;
 
   @LateInit private PType aliasedType;
 
@@ -39,11 +40,13 @@ public final class TypeAlias extends Member implements Value {
       String simpleName,
       String moduleName,
       String qualifiedName,
-      List<TypeParameter> typeParameters) {
+      List<TypeParameter> typeParameters,
+      PClass moduleClass) {
     super(docComment, sourceLocation, modifiers, annotations, simpleName);
     this.moduleName = moduleName;
     this.qualifiedName = qualifiedName;
     this.typeParameters = typeParameters;
+    this.moduleClass = moduleClass;
   }
 
   public void initAliasedType(PType type) {
@@ -79,6 +82,10 @@ public final class TypeAlias extends Member implements Value {
     return typeParameters;
   }
 
+  public PClass getModuleClass() {
+    return moduleClass;
+  }
+
   /** Returns the type that this type alias stands for. */
   public PType getAliasedType() {
     //noinspection ConstantValue

pkl-core/src/main/java/org/pkl/core/ValueConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -57,6 +57,8 @@ public interface ValueConverter<T> {
 
   T convertRegex(Pattern value);
 
+  T convertReference(Reference value);
+
   default T convert(Object value) {
     if (value instanceof Value v) {
       return (v.accept(this));

pkl-core/src/main/java/org/pkl/core/ValueVisitor.java

@@ -93,6 +93,10 @@ public interface ValueVisitor {
     visitDefault(value);
   }
 
+  default void visitReference(Reference value) {
+    visitDefault(value);
+  }
+
   default void visit(Object value) {
     if (value instanceof Value v) {
       v.accept(this);

pkl-core/src/main/java/org/pkl/core/ast/expression/binary/SubscriptNode.java

@@ -100,6 +100,20 @@ public abstract class SubscriptNode extends BinaryExpressionNode {
     return readMember(dynamic, key, callNode);
   }
 
+  @Specialization
+  protected VmReference eval(VmReference reference, Object key) {
+    var result = reference.withSubscriptAccess(key);
+    if (result != null) return result;
+
+    CompilerDirectives.transferToInterpreter();
+    throw exceptionBuilder()
+        .evalError(
+            "operatorNotDefined2", getShortName(), reference.exportType(), VmUtils.getClass(key))
+        .withProgramValue("Left operand", reference)
+        .withProgramValue("Right operand", key)
+        .build();
+  }
+
   @Specialization
   protected long eval(VmBytes receiver, long index) {
     if (index < 0 || index >= receiver.getLength()) {

pkl-core/src/main/java/org/pkl/core/ast/expression/member/ReadPropertyNode.java

@@ -61,6 +61,18 @@ public abstract class ReadPropertyNode extends ExpressionNode {
     this(sourceSection, propertyName, MemberLookupMode.EXPLICIT_RECEIVER, false);
   }
 
+  @Specialization
+  protected VmReference evalReference(VmReference receiver) {
+    assert lookupMode == MemberLookupMode.EXPLICIT_RECEIVER;
+    var result = receiver.withPropertyAccess(propertyName);
+    if (result != null) return result;
+
+    CompilerDirectives.transferToInterpreter();
+    throw exceptionBuilder()
+        .evalError("cannotFindPropertyInReference", propertyName, receiver.exportType())
+        .build();
+  }
+
   // This method effectively covers `VmObject receiver` but is implemented in a more
   // efficient way. See:
   // https://www.graalvm.org/22.0/graalvm-as-a-platform/language-implementation-framework/TruffleLibraries/#strategy-2-java-interfaces

pkl-core/src/main/java/org/pkl/core/ast/internal/ToStringNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,6 +20,7 @@ import com.oracle.truffle.api.dsl.Cached;
 import com.oracle.truffle.api.dsl.Fallback;
 import com.oracle.truffle.api.dsl.Specialization;
 import com.oracle.truffle.api.frame.VirtualFrame;
+import com.oracle.truffle.api.nodes.DirectCallNode;
 import com.oracle.truffle.api.source.SourceSection;
 import org.pkl.core.ast.ExpressionNode;
 import org.pkl.core.ast.MemberLookupMode;
@@ -62,10 +63,18 @@ public abstract class ToStringNode extends UnaryExpressionNode {
       VmTyped value,
       @Cached(value = "createInvokeNode()", neverDefault = true)
           InvokeMethodVirtualNode invokeNode) {
-
     return (String) invokeNode.executeWith(frame, value, value.getVmClass());
   }
 
+  @Specialization
+  protected String evalReference(
+      VirtualFrame frame,
+      VmReference value,
+      @Cached(value = "createReferenceCallNode(value)", neverDefault = true)
+          DirectCallNode callNode) {
+    return (String) callNode.call(value, value.getVmClass().getPrototype());
+  }
+
   @Fallback
   @Override
   @TruffleBoundary
@@ -74,7 +83,6 @@ public abstract class ToStringNode extends UnaryExpressionNode {
   }
 
   protected InvokeMethodVirtualNode createInvokeNode() {
-    //noinspection ConstantConditions
     return InvokeMethodVirtualNodeGen.create(
         sourceSection,
         Identifier.TO_STRING,
@@ -83,4 +91,10 @@ public abstract class ToStringNode extends UnaryExpressionNode {
         null,
         null);
   }
+
+  protected DirectCallNode createReferenceCallNode(VmReference reference) {
+    var toStringMethod = reference.getVmClass().getDeclaredMethod(Identifier.TO_STRING);
+    assert toStringMethod != null;
+    return DirectCallNode.create(toStringMethod.getCallTarget());
+  }
 }

pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java

@@ -2127,6 +2127,125 @@ public abstract class TypeNode extends PklNode {
     }
   }
 
+  public abstract static class ReferenceTypeNode extends ObjectSlotTypeNode {
+    @Child private TypeNode domainTypeNode;
+    @Child private TypeNode referentTypeNode;
+    @Child private ExpressionNode getModuleNode;
+
+    public ReferenceTypeNode(
+        SourceSection sourceSection, TypeNode domainTypeNode, TypeNode referentTypeNode) {
+      super(sourceSection);
+      this.domainTypeNode = domainTypeNode;
+      this.referentTypeNode = referentTypeNode;
+      this.getModuleNode = new GetModuleNode(sourceSection);
+      validateTypeArguments(sourceSection);
+    }
+
+    @Specialization
+    protected Object eval(VirtualFrame frame, VmReference value) {
+      if (domainTypeNode.isNoopTypeCheck() && referentTypeNode.isNoopTypeCheck()) {
+        return value;
+      }
+
+      try {
+        domainTypeNode.execute(frame, value.getDomain());
+      } catch (VmTypeMismatchException e) {
+        CompilerDirectives.transferToInterpreter();
+        throw new VmTypeMismatchException.Reference(
+            sourceSection,
+            value,
+            TypeNode.export(domainTypeNode),
+            TypeNode.export(referentTypeNode));
+      }
+
+      var module = (VmTyped) getModuleNode.executeGeneric(frame);
+      return doEval(value, module);
+    }
+
+    @TruffleBoundary
+    private Object doEval(VmReference value, VmTyped module) {
+      var referentType = TypeNode.export(referentTypeNode);
+      if (value.referentTypeIsSubtypeOf(referentType, module.getVmClass().export())) {
+        return value;
+      }
+
+      throw new VmTypeMismatchException.Reference(
+          sourceSection, value, TypeNode.export(domainTypeNode), referentType);
+    }
+
+    public void validateTypeArguments(@Nullable SourceSection aliasSourceSection) {
+      // constraints may not be used in Reference type annotation referents
+      // walk the type and throw if any part of the referent is constrained
+
+      // TODO improve error message when this type node and/or referent constraint are behind type
+      // aliases
+      referentTypeNode.acceptTypeNode(
+          true,
+          (typeNode) -> {
+            if (typeNode instanceof ConstrainedTypeNode) {
+              CompilerDirectives.transferToInterpreter();
+              var err =
+                  exceptionBuilder().evalError("invalidReferenceTypeAnnotationWithConstraint");
+              if (aliasSourceSection != null) {
+                err.withSourceSection(aliasSourceSection);
+              }
+              throw err.build();
+            }
+            return true;
+          });
+    }
+
+    @Fallback
+    protected Object fallback(Object value) {
+      throw typeMismatch(value, RefModule.getReferenceClass());
+    }
+
+    @Override
+    protected boolean acceptTypeNode(boolean visitTypeArguments, TypeNodeConsumer consumer) {
+      if (visitTypeArguments)
+        return consumer.accept(this)
+            && consumer.accept(domainTypeNode)
+            && consumer.accept(referentTypeNode);
+      return consumer.accept(this);
+    }
+
+    @Override
+    public VmClass getVmClass() {
+      return RefModule.getReferenceClass();
+    }
+
+    @Override
+    public VmList getTypeArgumentMirrors() {
+      return VmList.of(domainTypeNode.getMirror(), referentTypeNode.getMirror());
+    }
+
+    @Override
+    protected boolean doIsEquivalentTo(TypeNode other) {
+      if (!(other instanceof ReferenceTypeNode referenceTypeNode)) {
+        return false;
+      }
+      return referentTypeNode.isEquivalentTo(referenceTypeNode.referentTypeNode);
+    }
+
+    @Override
+    public boolean isNoopTypeCheck() {
+      return domainTypeNode.isNoopTypeCheck() && referentTypeNode.isNoopTypeCheck();
+    }
+
+    @Override
+    protected PType doExport() {
+      return new PType.Class(
+          RefModule.getReferenceClass().export(),
+          domainTypeNode.doExport(),
+          referentTypeNode.doExport());
+    }
+
+    @Override
+    protected boolean isParametric() {
+      return true;
+    }
+  }
+
   public static final class PairTypeNode extends ObjectSlotTypeNode {
     @Child private TypeNode firstTypeNode;
     @Child private TypeNode secondTypeNode;
@@ -2584,7 +2703,7 @@ public abstract class TypeNode extends PklNode {
 
       this.typeAlias = typeAlias;
       this.typeArgumentNodes = typeArgumentNodes;
-      aliasedTypeNode = typeAlias.instantiate(typeArgumentNodes);
+      aliasedTypeNode = typeAlias.instantiate(typeArgumentNodes, sourceSection);
     }
 
     public TypeNode getAliasedTypeNode() {

pkl-core/src/main/java/org/pkl/core/ast/type/UnresolvedTypeNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -287,6 +287,13 @@ public abstract class UnresolvedTypeNode extends PklNode {
           return new VarArgsTypeNode(sourceSection, typeArgumentNodes[0].execute(frame));
         }
 
+        if (clazz.isReferenceClass()) {
+          return ReferenceTypeNodeGen.create(
+              sourceSection,
+              typeArgumentNodes[0].execute(frame),
+              typeArgumentNodes[1].execute(frame));
+        }
+
         throw exceptionBuilder()
             .evalError("notAParameterizableClass", clazz.getDisplayName())
             .withSourceSection(typeArgumentNodes[0].sourceSection)

pkl-core/src/main/java/org/pkl/core/ast/type/VmTypeMismatchException.java

@@ -23,6 +23,7 @@ import com.oracle.truffle.api.source.SourceSection;
 import java.util.*;
 import java.util.stream.Collectors;
 import org.jspecify.annotations.Nullable;
+import org.pkl.core.PType;
 import org.pkl.core.StackFrame;
 import org.pkl.core.ValueFormatter;
 import org.pkl.core.ast.type.TypeNode.UnionTypeNode;
@@ -333,4 +334,44 @@ public abstract class VmTypeMismatchException extends ControlFlowException {
       return false;
     }
   }
+
+  public static final class Reference extends VmTypeMismatchException {
+
+    private final PType expectedDomainType;
+    private final PType expectedReferentType;
+
+    public Reference(
+        SourceSection sourceSection,
+        VmReference actualValue,
+        PType expectedDomainType,
+        PType expectedReferentType) {
+      super(sourceSection, actualValue);
+      this.expectedDomainType = expectedDomainType;
+      this.expectedReferentType = expectedReferentType;
+    }
+
+    @Override
+    public void buildMessage(
+        AnsiStringBuilder builder, String indent, boolean withPowerAssertions) {
+      builder
+          .append(
+              ErrorMessages.createIndented(
+                  "typeMismatch",
+                  indent,
+                  new PType.Class(
+                      RefModule.getReferenceClass().export(),
+                      expectedDomainType,
+                      expectedReferentType),
+                  ((VmReference) actualValue).exportType()))
+          .append("\n")
+          .append(indent)
+          .append("Value: ")
+          .append(VmValueRenderer.singleLine(80 - indent.length()).render(actualValue));
+    }
+
+    @Override
+    protected Boolean hasHint() {
+      return false;
+    }
+  }
 }

pkl-core/src/main/java/org/pkl/core/runtime/Identifier.java

@@ -165,6 +165,10 @@ public final class Identifier implements Comparable<Identifier> {
 
   public static final Identifier ILLEGAL = get("`");
 
+  // members of pkl.ref
+  public static final Identifier PROPERTY = get("property");
+  public static final Identifier KEY = get("key");
+
   // common in lambdas etc
   public static final Identifier IT = get("it");
 

pkl-core/src/main/java/org/pkl/core/runtime/ModuleCache.java

@@ -104,6 +104,8 @@ public final class ModuleCache {
           return PlatformModule.getModule();
         case "project":
           return ProjectModule.getModule();
+        case "ref":
+          return RefModule.getModule();
         case "reflect":
           return ReflectModule.getModule();
         case "release":

pkl-core/src/main/java/org/pkl/core/runtime/RefModule.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.runtime;
+
+import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
+import java.net.URI;
+
+public class RefModule extends StdLibModule {
+  private static final VmTyped instance = VmUtils.createEmptyModule();
+
+  static {
+    loadModule(URI.create("pkl:ref"), instance);
+  }
+
+  public static VmClass getReferenceClass() {
+    return ReferenceClass.instance;
+  }
+
+  public static VmClass getAccessClass() {
+    return AccessClass.instance;
+  }
+
+  private static final class ReferenceClass {
+    static final VmClass instance = loadClass("Reference");
+  }
+
+  private static final class AccessClass {
+    static final VmClass instance = loadClass("Access");
+  }
+
+  @TruffleBoundary
+  private static VmClass loadClass(String className) {
+    var theModule = getModule();
+    return (VmClass) VmUtils.readMember(theModule, Identifier.get(className));
+  }
+
+  public static VmTyped getModule() {
+    return instance;
+  }
+}

pkl-core/src/main/java/org/pkl/core/runtime/VmClass.java

@@ -445,6 +445,11 @@ public final class VmClass extends VmValue {
     return isClass(BaseModule.getVarArgsClass(), "pkl.base#VarArgs");
   }
 
+  @Idempotent
+  public boolean isReferenceClass() {
+    return isClass(RefModule.getReferenceClass(), "pkl.ref#Reference");
+  }
+
   private boolean isClass(@Nullable VmClass clazz, String qualifiedClassName) {
     // may be null during evaluation of base module
     return clazz != null ? this == clazz : getQualifiedName().equals(qualifiedClassName);
@@ -621,49 +626,62 @@ public final class VmClass extends VmValue {
   public PClass export() {
     synchronized (pClassLock) {
       //noinspection ConstantValue
-      if (__pClass == null) {
-        var exportedAnnotations = new ArrayList<PObject>();
-        var properties =
-            CollectionUtils.<String, PClass.Property>newLinkedHashMap(
-                EconomicMaps.size(declaredProperties));
-        var methods =
-            CollectionUtils.<String, PClass.Method>newLinkedHashMap(
-                EconomicMaps.size(declaredMethods));
+      if (__pClass != null) {
+        return __pClass;
+      }
 
-        // set pClass before exporting class members to prevent
-        // infinite recursion in case of cyclic references
-        __pClass =
-            new PClass(
-                VmUtils.exportDocComment(docComment),
-                new SourceLocation(headerSection.getStartLine(), sourceSection.getEndLine()),
-                VmModifier.export(modifiers, true),
-                exportedAnnotations,
-                classInfo,
-                typeParameters,
-                properties,
-                methods);
+      // if this is not a module class, export this class's module's class first to break the cycle
+      PClass moduleClass = null;
+      if (!classInfo.isModuleClass()) {
+        moduleClass = getModule().getVmClass().export();
+      }
+      // then if the cached value is still null, initialize it
+      if (__pClass != null) {
+        return __pClass;
+      }
 
-        for (var parameter : typeParameters) {
-          parameter.initOwner(__pClass);
+      var exportedAnnotations = new ArrayList<PObject>();
+      var properties =
+          CollectionUtils.<String, PClass.Property>newLinkedHashMap(
+              EconomicMaps.size(declaredProperties));
+      var methods =
+          CollectionUtils.<String, PClass.Method>newLinkedHashMap(
+              EconomicMaps.size(declaredMethods));
+
+      // set pClass before exporting class members to prevent
+      // infinite recursion in case of cyclic references
+      __pClass =
+          new PClass(
+              VmUtils.exportDocComment(docComment),
+              new SourceLocation(headerSection.getStartLine(), sourceSection.getEndLine()),
+              VmModifier.export(modifiers, true),
+              exportedAnnotations,
+              classInfo,
+              typeParameters,
+              properties,
+              methods,
+              moduleClass);
+
+      for (var parameter : typeParameters) {
+        parameter.initOwner(__pClass);
+      }
+
+      if (supertypeNode != null) {
+        assert superclass != null;
+        __pClass.initSupertype(TypeNode.export(supertypeNode), superclass.export());
+      }
+
+      VmUtils.exportAnnotations(annotations, exportedAnnotations);
+
+      for (var property : EconomicMaps.getValues(declaredProperties)) {
+        if (isClassPropertyDefinition(property)) {
+          properties.put(property.getName().toString(), property.export(__pClass));
         }
+      }
 
-        if (supertypeNode != null) {
-          assert superclass != null;
-          __pClass.initSupertype(TypeNode.export(supertypeNode), superclass.export());
-        }
-
-        VmUtils.exportAnnotations(annotations, exportedAnnotations);
-
-        for (var property : EconomicMaps.getValues(declaredProperties)) {
-          if (isClassPropertyDefinition(property)) {
-            properties.put(property.getName().toString(), property.export(__pClass));
-          }
-        }
-
-        for (var method : EconomicMaps.getValues(declaredMethods)) {
-          if (method.isLocal()) continue;
-          methods.put(method.getName().toString(), method.export(__pClass));
-        }
+      for (var method : EconomicMaps.getValues(declaredMethods)) {
+        if (method.isLocal()) continue;
+        methods.put(method.getName().toString(), method.export(__pClass));
       }
 
       return __pClass;

pkl-core/src/main/java/org/pkl/core/runtime/VmObjectBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -87,4 +87,9 @@ public final class VmObjectBuilder {
         members,
         elementCount);
   }
+
+  public VmTyped toTyped(VmClass clazz) {
+    return new VmTyped(
+        VmUtils.createEmptyMaterializedFrame(), clazz.getPrototype(), clazz, members);
+  }
 }

pkl-core/src/main/java/org/pkl/core/runtime/VmPklBinaryEncoder.java

@@ -324,6 +324,22 @@ public class VmPklBinaryEncoder extends AbstractRenderer {
     }
   }
 
+  @Override
+  public void visitReference(VmReference value) {
+    try {
+      packer.packArrayHeader(4);
+      packCode(PklBinaryCode.REFERENCE);
+      visit(value.getDomain());
+      visit(value.getData());
+      packer.packArrayHeader(value.getPath().size());
+      for (var access : value.getPath()) {
+        visit(access);
+      }
+    } catch (IOException e) {
+      throw PklBugException.unreachableCode();
+    }
+  }
+
   @Override
   protected void visitEntryKey(Object key, boolean isFirst) {
     visit(key);

pkl-core/src/main/java/org/pkl/core/runtime/VmReference.java

@@ -0,0 +1,473 @@
+/*
+ * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.runtime;
+
+import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.function.BiConsumer;
+import java.util.function.Supplier;
+import org.jspecify.annotations.Nullable;
+import org.pkl.core.Composite;
+import org.pkl.core.PClass;
+import org.pkl.core.PClassInfo;
+import org.pkl.core.PType;
+import org.pkl.core.Reference;
+import org.pkl.core.TypeAlias;
+import org.pkl.core.util.paguro.RrbTree;
+import org.pkl.core.util.paguro.RrbTree.ImRrbt;
+
+public final class VmReference extends VmValue {
+
+  private final VmTyped domain;
+  private final Object data;
+  private final ImRrbt<VmTyped> path;
+  // candidate types can only be: PType.Class, PType.Alias (only preservedAliasTypes),
+  // PType.StringLiteral, PType.UNKNOWN, or PType.Union (containing only the previous; flattened)
+  private final PType referentType;
+
+  private boolean forced = false;
+
+  private static VmTyped newAccess(@Nullable String property, @Nullable Object key) {
+    return new VmObjectBuilder()
+        .addProperty(Identifier.PROPERTY, property == null ? VmNull.withoutDefault() : property)
+        .addProperty(Identifier.KEY, key == null ? VmNull.withoutDefault() : key)
+        .toTyped(RefModule.getAccessClass());
+  }
+
+  @TruffleBoundary
+  public VmReference(VmTyped domain, VmClass clazz, Object data) {
+    this(
+        domain,
+        data,
+        RrbTree.empty(),
+        normalizeTypes(new PType.Class(clazz.export()), clazz.getModule().getVmClass().export()));
+  }
+
+  public VmReference(VmTyped domain, Object data, ImRrbt<VmTyped> path, PType referentType) {
+    this.domain = domain;
+    this.data = data;
+    this.referentType = referentType;
+    this.path = path;
+  }
+
+  public VmTyped getDomain() {
+    return domain;
+  }
+
+  public Object getData() {
+    return data;
+  }
+
+  public List<VmTyped> getPath() {
+    return path;
+  }
+
+  public PType getReferentType() {
+    return referentType;
+  }
+
+  // simplifies a type by:
+  // * erasing constraints
+  // * transforming T? into T|Null
+  // * dereferencing aliases (except for well-known stdlib alias types)
+  // * flattening unions
+  // * when moduleClass is supplied, replace PType.MODULE with appropriate PType.Class
+  // * drop PType.Function and PType.TypeVariable
+  private static PType normalizeTypes(PType type, PClass moduleClass) {
+    var types = new HashSet<PType>();
+    normalizeTypes(type, moduleClass, types);
+    return minimizeTypes(types);
+  }
+
+  private static PType minimizeTypes(Set<PType> types) {
+    if (types.size() == 1) return types.iterator().next();
+    // optimization: unknown allows all references, erase all candidates to only unknown
+    if (types.contains(PType.UNKNOWN)) return PType.UNKNOWN;
+    // optimization: All allows all references, erase all candidates to only All
+    if (containsClass(types, BaseModule.getAnyClass().export()))
+      return new PType.Class(BaseModule.getAnyClass().export());
+    var typesList = new ArrayList<>(types);
+    typesList.sort(Comparator.comparing(Object::toString));
+    return new PType.Union(typesList);
+  }
+
+  private static void normalizeTypes(PType type, PClass moduleClass, Set<PType> result) {
+    if (type == PType.UNKNOWN || type == PType.NOTHING || type instanceof PType.StringLiteral) {
+      result.add(type);
+    } else if (type instanceof PType.Class clazz) {
+      if (clazz.getTypeArguments().isEmpty()) {
+        // if a generic type is used without type arguments, it needs to be normalized so all args
+        // are unknown; i.e. with bare List/Map/etc. type annotations (via FinalClassTypeNode).
+        var typeParameterCount = clazz.getPClass().getTypeParameters().size();
+        result.add(
+            typeParameterCount == 0
+                ? clazz
+                : new PType.Class(
+                    clazz.getPClass(), Collections.nCopies(typeParameterCount, PType.UNKNOWN)));
+      } else {
+        var typeArgs = new ArrayList<PType>(clazz.getTypeArguments().size());
+        for (var arg : clazz.getTypeArguments()) {
+          typeArgs.add(normalizeTypes(arg, moduleClass));
+        }
+        result.add(new PType.Class(clazz.getPClass(), typeArgs));
+      }
+    } else if (type instanceof PType.Nullable nullable) {
+      normalizeTypes(nullable.getBaseType(), moduleClass, result);
+      result.add(new PType.Class(BaseModule.getNullClass().export()));
+    } else if (type instanceof PType.Constrained constrained) {
+      normalizeTypes(constrained.getBaseType(), moduleClass, result);
+    } else if (type instanceof PType.Alias alias) {
+      if (isPreservedTypeAlias(alias.getTypeAlias())) {
+        result.add(alias);
+      } else {
+        normalizeTypes(alias.getAliasedType(), alias.getTypeAlias().getModuleClass(), result);
+      }
+    } else if (type instanceof PType.Union union) {
+      for (var t : union.getElementTypes()) {
+        normalizeTypes(t, moduleClass, result);
+      }
+    } else if (type == PType.MODULE) {
+      result.add(new PType.Class(moduleClass));
+    }
+  }
+
+  private static Iterable<PType> iterateTypes(PType t) {
+    if (t instanceof PType.Union union) return union.getElementTypes();
+    return Collections.singleton(t);
+  }
+
+  public @Nullable VmReference withPropertyAccess(Identifier property) {
+    var propString = property.toString();
+    return withAccess(
+        (t, candidates) -> getCandidatePropertyType(t, propString, candidates),
+        () -> newAccess(property.toString(), null));
+  }
+
+  public @Nullable VmReference withSubscriptAccess(Object key) {
+    return withAccess(
+        (t, candidates) -> getCandidateSubscriptType(t, key, candidates),
+        () -> newAccess(null, key));
+  }
+
+  @TruffleBoundary
+  private @Nullable VmReference withAccess(
+      BiConsumer<PType, Set<PType>> checkCandidate, Supplier<VmTyped> makeAccess) {
+    Set<PType> candidates = new HashSet<>();
+    for (var t : iterateTypes(referentType)) {
+      checkCandidate.accept(t, candidates);
+    }
+    if (candidates.isEmpty()) {
+      return null; // no valid access found
+    }
+    return new VmReference(domain, data, path.append(makeAccess.get()), minimizeTypes(candidates));
+  }
+
+  @SuppressWarnings("DuplicatedCode")
+  private static void getCandidatePropertyType(PType type, String property, Set<PType> result) {
+    if (type == PType.UNKNOWN) {
+      result.add(type);
+      return;
+    }
+    // restriction: only class types can have their properties referenced
+    if (!(type instanceof PType.Class clazz)) return;
+    // restriction: cannot reference properties of external classes
+    if (clazz.getPClass().isExternal()) return;
+    if (clazz.getPClass().getInfo() == PClassInfo.Dynamic) {
+      // restriction: cannot reference Dynamic.default
+      if (!property.equals("default")) result.add(PType.UNKNOWN);
+      return;
+    }
+    // restriction: cannot reference Listing/Mapping.default
+    if (clazz.getPClass().getInfo() == PClassInfo.Listing
+        || clazz.getPClass().getInfo() == PClassInfo.Mapping) {
+      return;
+    }
+    // restriction: cannot reference Module.output.
+    //   generalized: properties originally defined in external classes; the only extant example.
+    // This is implemented specifically because this is the only case where an external class
+    //   containing a property can be subclassed.
+    // And this can't check prop.getOwner().isExternal() because fully overriding the property with
+    //   a new type annotation means the owner isn't Module.
+    if (clazz.getPClass().isSubclassOf(BaseModule.getModuleClass().export())
+        && property.equals("output")) return;
+
+    var prop = clazz.getPClass().getAllProperties().get(property);
+    // restriction: cannot reference external properties
+    if (prop == null || prop.isExternal()) {
+      return;
+    }
+    normalizeTypes(prop.getType(), clazz.getPClass().getModuleClass(), result);
+  }
+
+  @SuppressWarnings("DuplicatedCode")
+  private static void getCandidateSubscriptType(PType type, Object key, Set<PType> result) {
+    if (type == PType.UNKNOWN) {
+      result.add(type);
+      return;
+    }
+    if (!(type instanceof PType.Class clazz)) {
+      return;
+    }
+    if (clazz.getPClass().getInfo() == PClassInfo.Dynamic) {
+      result.add(PType.UNKNOWN);
+      return;
+    }
+    if (clazz.getPClass().getInfo() == PClassInfo.Listing
+        || clazz.getPClass().getInfo() == PClassInfo.List) {
+      if (key instanceof Long) {
+        normalizeTypes(clazz.getTypeArguments().get(0), clazz.getPClass().getModuleClass(), result);
+      }
+      return;
+    }
+    if (clazz.getPClass().getInfo() == PClassInfo.Mapping
+        || clazz.getPClass().getInfo() == PClassInfo.Map) {
+      var typeArgs = clazz.getTypeArguments();
+      var keyTypes = normalizeTypes(typeArgs.get(0), clazz.getPClass().getModuleClass());
+      for (var kt : iterateTypes(keyTypes)) {
+        if (kt == PType.UNKNOWN
+            || (kt instanceof PType.Class klazz
+                && klazz.getPClass().getInfo() == PClassInfo.forValue(VmValue.export(key)))
+            || (kt instanceof PType.StringLiteral stringLiteral
+                && stringLiteral.getLiteral().equals(key))) {
+          normalizeTypes(typeArgs.get(1), clazz.getPClass().getModuleClass(), result);
+          return;
+        }
+      }
+    }
+  }
+
+  /**
+   * Tells if this reference's referent type is a subtype of {@code type}. Does not check domain.
+   */
+  public boolean referentTypeIsSubtypeOf(PType type, PClass moduleClass) {
+    // fast path: if referent is unknown it can match any type check
+    if (referentType == PType.UNKNOWN) {
+      return true;
+    }
+
+    var checkType = normalizeTypes(type, moduleClass);
+    // fast path: short circuit if any referent is accepted
+    if (checkType == PType.UNKNOWN || isClass(checkType, BaseModule.getAnyClass().export())) {
+      return true;
+    }
+    // fast path: short circuit if nothing is accepted
+    if (checkType == PType.NOTHING) {
+      return false;
+    }
+
+    return isSubtype(referentType, checkType);
+  }
+
+  private static boolean containsClass(Set<PType> types, PClass pClass) {
+    for (var t : types) {
+      if (isClass(t, pClass)) return true;
+    }
+    return false;
+  }
+
+  private static boolean isClass(PType t, PClass pClass) {
+    return t instanceof PType.Class clazz && clazz.getPClass() == pClass;
+  }
+
+  private static boolean isSubtype(PType a, PType b) {
+    // checks if A is a subtype of B
+    // cases (A -> B)
+    // * A == B
+    // * StringLiteral -> StringLiteral: if literals are the same
+    // * StringLiteral -> Class: B is String
+    // * Char Alias -> Char Alias, StringLiteral (known single character)
+    // * Int Alias -> Class: B is a subtype of Number (Int|Float|Number)
+    // * Int Alias -> Alias
+    //   * same alias
+    //   * Int8 is Int16|Int32
+    //   * Int16 is Int32
+    //   * UInt8 is Int16|Int32|Uint16|UInt32|UInt
+    //   * UInt16 is Int32|UInt32|UInt
+    //   * UInt32 is UInt
+    // * Class -> Class: if same class or A is a subclass of B
+    //   * if type args are present, must have equal number of them
+    //   * for each pair of type args, check variance
+    //     * invariant: A_i must be identical to B_i
+    //     * covariant: A_i must be a subtype of B_i
+    //     * contravariant: B_i must be a subtype of A_i
+    // * Union -> Union: Each elem of A must be a subtype of at least one elem of B
+    // * Non-union -> Union: A must be a subtype of at least one elem of B
+    if (a == b) return true;
+
+    if (a instanceof PType.StringLiteral aStr) {
+      if (b instanceof PType.StringLiteral bStr) {
+        return aStr.getLiteral().equals(bStr.getLiteral());
+      } else if (b instanceof PType.Class bClass) {
+        return bClass.getPClass() == BaseModule.getStringClass().export();
+      }
+    } else if (a instanceof PType.Alias aAlias) {
+      var aa = aAlias.getTypeAlias();
+      if (isIntTypeAlias(aa)) {
+        // special casing for stdlib Int typealiases
+        if (b instanceof PType.Class bClass) {
+          // A is an int alias, B is a Number (sub)class
+          return bClass.getPClass().isSubclassOf(BaseModule.getNumberClass().export());
+        } else if (b instanceof PType.Alias bAlias) {
+          var bb = bAlias.getTypeAlias();
+          if (aa == bb) {
+            return true;
+          }
+          if (aa == BaseModule.getInt8TypeAlias().export()) {
+            return bb == BaseModule.getInt16TypeAlias().export()
+                || bb == BaseModule.getInt32TypeAlias().export();
+          } else if (aa == BaseModule.getInt16TypeAlias().export()) {
+            return bb == BaseModule.getInt32TypeAlias().export();
+          } else if (aa == BaseModule.getUInt8TypeAlias().export()) {
+            return bb == BaseModule.getInt16TypeAlias().export()
+                || bb == BaseModule.getInt32TypeAlias().export()
+                || bb == BaseModule.getUInt16TypeAlias().export()
+                || bb == BaseModule.getUInt32TypeAlias().export()
+                || bb == BaseModule.getUIntTypeAlias().export();
+          } else if (aa == BaseModule.getUInt16TypeAlias().export()) {
+            return bb == BaseModule.getInt32TypeAlias().export()
+                || bb == BaseModule.getUInt32TypeAlias().export()
+                || bb == BaseModule.getUIntTypeAlias().export();
+          } else if (aa == BaseModule.getUInt32TypeAlias().export()) {
+            return bb == BaseModule.getUIntTypeAlias().export();
+          }
+        }
+      }
+    } else if (a instanceof PType.Class aClass && b instanceof PType.Class bClass) {
+      if (!aClass.getPClass().isSubclassOf(bClass.getPClass())) {
+        return false;
+      }
+      var aArgs = aClass.getTypeArguments();
+      var bArgs = bClass.getTypeArguments();
+      var bParams = bClass.getPClass().getTypeParameters();
+      if (aArgs.size() != bArgs.size()) {
+        return false;
+      }
+      // check variance of type args pairwise
+      for (var i = 0; i < aArgs.size(); i++) {
+        if (!switch (bParams.get(i).getVariance()) {
+          case INVARIANT -> aArgs.get(i) == bArgs.get(i);
+          case COVARIANT -> isSubtype(aArgs.get(i), bArgs.get(i));
+          case CONTRAVARIANT -> isSubtype(bArgs.get(i), aArgs.get(i));
+        }) {
+          return false;
+        }
+      }
+      return true;
+    } else if (b instanceof PType.Union bUnion) {
+      if (a instanceof PType.Union aUnion) {
+        a:
+        for (var aElem : aUnion.getElementTypes()) {
+          for (var bElem : bUnion.getElementTypes()) {
+            if (isSubtype(aElem, bElem)) continue a;
+          }
+          return false;
+        }
+        return true;
+      } else {
+        for (var bElem : bUnion.getElementTypes()) {
+          if (isSubtype(a, bElem)) return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  private static boolean isIntTypeAlias(TypeAlias t) {
+    return t == BaseModule.getInt8TypeAlias().export()
+        || t == BaseModule.getInt16TypeAlias().export()
+        || t == BaseModule.getInt32TypeAlias().export()
+        || t == BaseModule.getUInt8TypeAlias().export()
+        || t == BaseModule.getUInt16TypeAlias().export()
+        || t == BaseModule.getUInt32TypeAlias().export()
+        || t == BaseModule.getUIntTypeAlias().export();
+  }
+
+  private static boolean isPreservedTypeAlias(TypeAlias t) {
+    return isIntTypeAlias(t);
+  }
+
+  @Override
+  public VmClass getVmClass() {
+    return RefModule.getReferenceClass();
+  }
+
+  @Override
+  public void force(boolean allowUndefinedValues) {
+    if (forced) return;
+
+    forced = true;
+
+    domain.force(allowUndefinedValues);
+    VmValue.force(data, allowUndefinedValues);
+    for (var elem : path) {
+      elem.force(allowUndefinedValues);
+    }
+  }
+
+  @Override
+  public Reference export() {
+    var pathList = new ArrayList<Composite>(path.size());
+    for (var elem : path) {
+      pathList.add(elem.export());
+    }
+
+    return new Reference(domain.export(), VmValue.export(data), pathList, getReferentType());
+  }
+
+  public PType exportType() {
+    return new PType.Class(
+        RefModule.getReferenceClass().export(),
+        new PType.Class(domain.getVmClass().export()),
+        getReferentType());
+  }
+
+  @Override
+  public void accept(VmValueVisitor visitor) {
+    visitor.visitReference(this);
+  }
+
+  @Override
+  public <T> T accept(VmValueConverter<T> converter, Iterable<Object> path) {
+    return converter.convertReference(this, path);
+  }
+
+  @Override
+  public boolean equals(@Nullable Object o) {
+    if (o == this) return true;
+    if (!(o instanceof VmReference that)) {
+      return false;
+    }
+
+    return domain.equals(that.domain)
+        && data.equals(that.data)
+        && path.equals(that.path)
+        && referentType.equals(that.referentType);
+  }
+
+  @Override
+  public int hashCode() {
+    int result = domain.hashCode();
+    result = 31 * result + data.hashCode();
+    result = 31 * result + path.hashCode();
+    result = 31 * result + referentType.hashCode();
+    return result;
+  }
+}

pkl-core/src/main/java/org/pkl/core/runtime/VmTypeAlias.java

@@ -32,6 +32,7 @@ import org.pkl.core.TypeParameter;
 import org.pkl.core.ast.VmModifier;
 import org.pkl.core.ast.type.TypeNode;
 import org.pkl.core.ast.type.TypeNode.ConstrainedTypeNode;
+import org.pkl.core.ast.type.TypeNode.ReferenceTypeNode;
 import org.pkl.core.ast.type.TypeNode.TypeVariableNode;
 import org.pkl.core.ast.type.TypeNode.UnknownTypeNode;
 import org.pkl.core.util.LateInit;
@@ -177,7 +178,8 @@ public final class VmTypeAlias extends VmValue {
   }
 
   @TruffleBoundary
-  public TypeNode instantiate(TypeNode[] typeArgumentNodes) {
+  public TypeNode instantiate(
+      TypeNode[] typeArgumentNodes, SourceSection typeAliasTypeNodeSourceSection) {
     // Cloning the type node means that the entire type check remains within a single root node,
     // which should be good for interpreted and compiled performance alike:
     // * Fewer root nodes to call
@@ -199,6 +201,13 @@ public final class VmTypeAlias extends VmValue {
           }
           return true;
         });
+    clone.accept(
+        node -> {
+          if (node instanceof ReferenceTypeNode referenceTypeNode) {
+            referenceTypeNode.validateTypeArguments(typeAliasTypeNodeSourceSection);
+          }
+          return true;
+        });
 
     return clone;
   }
@@ -228,7 +237,8 @@ public final class VmTypeAlias extends VmValue {
                 simpleName,
                 getModuleName(),
                 qualifiedName,
-                typeParameters);
+                typeParameters,
+                module.getVmClass().export());
 
         for (var parameter : typeParameters) {
           parameter.initOwner(__pTypeAlias);

pkl-core/src/main/java/org/pkl/core/runtime/VmTypes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,6 +40,7 @@ import com.oracle.truffle.api.dsl.TypeSystem;
   VmRegex.class,
   VmTypeAlias.class,
   VmObjectLike.class,
-  VmValue.class
+  VmReference.class,
+  VmValue.class,
 })
 public class VmTypes {}

pkl-core/src/main/java/org/pkl/core/runtime/VmValueConverter.java

@@ -85,6 +85,8 @@ public interface VmValueConverter<T> {
 
   T convertFunction(VmFunction value, Iterable<Object> path);
 
+  T convertReference(VmReference value, Iterable<Object> path);
+
   /** Returns with an empty identifier if the second value is a RenderDirective */
   Pair<Identifier, T> convertProperty(ClassProperty property, Object value, Iterable<Object> path);
 

pkl-core/src/main/java/org/pkl/core/runtime/VmValueRenderer.java

@@ -271,6 +271,30 @@ public final class VmValueRenderer {
       append("null");
     }
 
+    @Override
+    public void visitReference(VmReference value) {
+      contexts.push(Context.EXPLICIT);
+      append("Reference(");
+      visit(value.getDomain());
+      append(", ");
+      append(value.getReferentType());
+      append(", ");
+      visit(value.getData());
+      append(")");
+      for (var elem : value.getPath()) {
+        var property = VmUtils.readMember(elem, Identifier.PROPERTY);
+        if (property instanceof String propName) {
+          append(".");
+          writeIdentifier(propName);
+        } else {
+          append("[");
+          visit(VmUtils.readMember(elem, Identifier.KEY));
+          append("]");
+        }
+      }
+      contexts.pop();
+    }
+
     private void append(Object value) {
       builder.append(value);
       checkLengthLimit();

pkl-core/src/main/java/org/pkl/core/runtime/VmValueVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -60,6 +60,8 @@ public interface VmValueVisitor {
 
   void visitFunction(VmFunction value);
 
+  void visitReference(VmReference value);
+
   default void visit(Object value) {
     Objects.requireNonNull(value, "Value to be visited must be non-null.");
 

pkl-core/src/main/java/org/pkl/core/stdlib/AbstractRenderer.java

@@ -34,6 +34,7 @@ import org.pkl.core.runtime.VmListing;
 import org.pkl.core.runtime.VmMap;
 import org.pkl.core.runtime.VmMapping;
 import org.pkl.core.runtime.VmNull;
+import org.pkl.core.runtime.VmReference;
 import org.pkl.core.runtime.VmSet;
 import org.pkl.core.runtime.VmTypeAlias;
 import org.pkl.core.runtime.VmTyped;
@@ -397,6 +398,11 @@ public abstract class AbstractRenderer implements VmValueVisitor {
     currSourceSection = prevSourceSection;
   }
 
+  @Override
+  public void visitReference(VmReference value) {
+    cannotRenderTypeAddConverter(value);
+  }
+
   protected void cannotRenderTypeAddConverter(VmValue value) {
     var builder =
         new VmExceptionBuilder()

pkl-core/src/main/java/org/pkl/core/stdlib/PklConverter.java

@@ -46,6 +46,7 @@ public final class PklConverter implements VmValueConverter<Object> {
   private final @Nullable VmFunction nullConverter;
   private final @Nullable VmFunction classConverter;
   private final @Nullable VmFunction typeAliasConverter;
+  private final @Nullable VmFunction referenceConverter;
 
   private PklConverter(
       VmMapping converters, VmMapping convertPropertyTransformers, Object rendererOrParser) {
@@ -76,6 +77,7 @@ public final class PklConverter implements VmValueConverter<Object> {
     nullConverter = typeConverters.get(BaseModule.getNullClass());
     classConverter = typeConverters.get(BaseModule.getClassClass());
     typeAliasConverter = typeConverters.get(BaseModule.getTypeAliasClass());
+    referenceConverter = typeConverters.get(RefModule.getReferenceClass());
   }
 
   public static final PklConverter NOOP =
@@ -199,6 +201,11 @@ public final class PklConverter implements VmValueConverter<Object> {
     return doConvert(value, path, nullConverter);
   }
 
+  @Override
+  public Object convertReference(VmReference value, Iterable<Object> path) {
+    return doConvert(value, path, referenceConverter);
+  }
+
   @Override
   public Pair<Identifier, Object> convertProperty(
       ClassProperty property, Object value, Iterable<Object> path) {

pkl-core/src/main/java/org/pkl/core/stdlib/protobuf/RendererNodes.java

@@ -59,6 +59,7 @@ import org.pkl.core.runtime.VmMap;
 import org.pkl.core.runtime.VmMapping;
 import org.pkl.core.runtime.VmNull;
 import org.pkl.core.runtime.VmPair;
+import org.pkl.core.runtime.VmReference;
 import org.pkl.core.runtime.VmRegex;
 import org.pkl.core.runtime.VmSet;
 import org.pkl.core.runtime.VmTyped;
@@ -554,6 +555,12 @@ public final class RendererNodes {
       builder.append(value);
     }
 
+    @Override
+    public void visitReference(VmReference value) {
+      writePropertyName();
+      builder.append(value);
+    }
+
     /**
      * Resolves types for the purpose of protobuf rendering. "Sees through" nullable types and type
      * aliases, simplifies variations of {@code Int} and {@code String} types (literate string

pkl-core/src/main/java/org/pkl/core/stdlib/ref/RefNodes.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.stdlib.ref;
+
+import com.oracle.truffle.api.dsl.Specialization;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import org.pkl.core.runtime.VmClass;
+import org.pkl.core.runtime.VmReference;
+import org.pkl.core.runtime.VmTyped;
+import org.pkl.core.stdlib.ExternalMethod3Node;
+
+public class RefNodes {
+  public abstract static class Reference extends ExternalMethod3Node {
+    @Specialization
+    protected VmReference eval(
+        VirtualFrame frame, VmTyped self, VmTyped domain, VmClass clazz, Object data) {
+      return new VmReference(domain, clazz, data);
+    }
+  }
+}

pkl-core/src/main/java/org/pkl/core/stdlib/ref/ReferenceNodes.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.core.stdlib.ref;
+
+import com.oracle.truffle.api.dsl.Specialization;
+import org.pkl.core.runtime.VmList;
+import org.pkl.core.runtime.VmReference;
+import org.pkl.core.stdlib.ExternalMethod0Node;
+
+public class ReferenceNodes {
+  private ReferenceNodes() {}
+
+  public abstract static class getDomain extends ExternalMethod0Node {
+    @Specialization
+    protected Object eval(VmReference self) {
+      return self.getDomain();
+    }
+  }
+
+  public abstract static class getData extends ExternalMethod0Node {
+    @Specialization
+    protected Object eval(VmReference self) {
+      return self.getData();
+    }
+  }
+
+  public abstract static class getPath extends ExternalMethod0Node {
+    @Specialization
+    protected VmList eval(VmReference self) {
+      return VmList.create(self.getPath());
+    }
+  }
+}

pkl-core/src/main/java/org/pkl/core/stdlib/ref/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package org.pkl.core.stdlib.ref;
+
+import org.jspecify.annotations.NullMarked;

pkl-core/src/main/java/org/pkl/core/util/pklbinary/PklBinaryCode.java

@@ -33,6 +33,7 @@ public enum PklBinaryCode {
   TYPEALIAS((byte) 0x0D),
   FUNCTION((byte) 0x0E),
   BYTES((byte) 0x0F),
+  REFERENCE((byte) 0x20),
 
   PROPERTY((byte) 0x10),
   ENTRY((byte) 0x11),
@@ -65,6 +66,7 @@ public enum PklBinaryCode {
       case 0x0D -> PklBinaryCode.TYPEALIAS;
       case 0x0E -> PklBinaryCode.FUNCTION;
       case 0x0F -> PklBinaryCode.BYTES;
+      case 0x20 -> PklBinaryCode.REFERENCE;
 
       case 0x10 -> PklBinaryCode.PROPERTY;
       case 0x11 -> PklBinaryCode.ENTRY;

pkl-core/src/main/resources/org/pkl/core/errorMessages.properties

@@ -390,6 +390,9 @@ Cannot find property `{0}` in object of type `{1}`.\n\
 Did you mean any of the following?\n\
 {2}
 
+cannotFindPropertyInReference=\
+Cannot find property `{0}` in object of type `{1}`.
+
 cannotFindMethodInScope=\
 Cannot find method `{0}`.
 
@@ -1179,3 +1182,6 @@ Cannot follow redirect from ''https:'' URL to ''http:'' URL.\
 \n\
 HTTP Request: `GET {0}`\n\
 Redirected to: `{1}`
+
+invalidReferenceTypeAnnotationWithConstraint=\
+`Reference` referent type argument may not include type constraints.

pkl-core/src/test/files/LanguageSnippetTests/input-helper/errors/ReferencedModule.pkl

@@ -0,0 +1 @@
+foo: String

pkl-core/src/test/files/LanguageSnippetTests/input-helper/errors/ReferencedModuleWithOutputOverride.pkl

@@ -0,0 +1,7 @@
+open module ReferencedModuleWithOutputOverride
+
+foo: String
+
+hidden output: ModuleOutput = new {
+  text = foo
+}

pkl-core/src/test/files/LanguageSnippetTests/input/api/reference.pkl

@@ -0,0 +1,134 @@
+import "pkl:math"
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String =
+    let (data = reference.getData())
+    let (root = if (data is Resource) data.name else data.toString())
+    let (
+      path =
+        reference
+          .getPath()
+          .map((elem) -> if (elem.isProperty) ".\(elem.property)" else "[\(elem.key)]")
+    )
+      "${\(root)\(path.join(""))}"
+}
+
+local const d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+abstract class Resource {
+  name: String
+  hidden fixed $: Ref<Resource>
+}
+
+class A extends Resource {
+  id: String
+  hidden outputs: AProperties
+  hidden fixed $: Ref<A> = ref.Reference(d, A, this)
+}
+
+/// Test doc comment
+class AProperties {
+  foo: Int
+  someMapping: Mapping<String, Int?>
+  someMap: Map<MapKey, Int>
+  someListing: Listing<Int>
+  someList: List<Int>
+  nonInt: String
+}
+
+class B extends Resource {
+  id: String
+  hidden outputs: BProperties
+  hidden fixed $: Ref<B> = ref.Reference(d, B, this)
+}
+
+class BProperties {
+  foo: String
+  someMapping: Mapping<String, String?>
+  someMap: Map<MapKey, String>
+  someListing: Listing<String>
+  someList: List<String>
+  nonString: Int
+}
+
+class MapKey {
+  k: Int
+
+  function toString(): String = "key:\(k)"
+}
+
+class K {
+  aId: String | *Ref<String>?
+  bId: String | *Ref<String>?
+  aProperties: AProperties | *Ref<AProperties>?
+  bProperties: BProperties | *Ref<BProperties>?
+  aValues: Listing<Int | Ref<Int?>>?
+  bValues: Listing<String | Ref<String?>>?
+  splitUnion: Ref<Listing<String> | Listing<Int>>?
+}
+
+a: A = new {
+  name = "a"
+  id = "some-a-value"
+}
+
+b: B = new {
+  name = "b"
+  id = "some-b-value"
+}
+
+aOrB: A | B = a
+aRef: Ref<A> = a.$
+bRef: Ref<B> = b.$
+unknownRef: Ref<A | B> = aRef
+unknownRef2: Ref<A> | Ref<B> = aRef
+unknownRef3: Ref<B | A> = aOrB.$
+
+k: K = new {
+  aId = aRef.id
+  bId = bRef.id
+  aProperties = aRef.outputs
+  bProperties = bRef.outputs
+  aValues {
+    aRef.outputs.foo
+    aRef.outputs.someMapping["key"]
+    aRef.outputs.someMap[new MapKey { k = 123 }]
+    aRef.outputs.someListing[0]
+    aRef.outputs.someList[math.maxInt]
+    bRef.outputs.nonString
+  }
+  bValues {
+    bRef.outputs.foo
+    bRef.outputs.someMapping["key"]
+    bRef.outputs.someMap[new MapKey { k = 123 }]
+    bRef.outputs.someListing[0]
+    bRef.outputs.someList[math.maxInt]
+    aRef.outputs.nonInt
+  }
+}
+
+j: K = new {
+  local aRef2 = unknownRef as Ref<A>
+  aProperties = aRef2.outputs
+  splitUnion = unknownRef.outputs.someListing
+}
+
+refInterpolation = "\(aRef.outputs.someListing[1])"
+kInterpolation = "\(k)"
+aValuesJoined = k.aValues.join("\n").replaceAll(Regex("@[a-z0-9]+"), "@<addr>")
+
+// ensure that type arguments that are unions are handled correctly
+typeArgs = ref.Reference(d, TypeHolder, null).prop as Ref<Listing<Number | Boolean | String>>
+class TypeHolder {
+  prop: Listing<String | Boolean | Number>
+}
+
+output {
+  renderer {
+    converters {
+      [ref.Reference] = (it) -> it.toString()
+    }
+  }
+}

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference1.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+test = ref.Reference(d, String, "") as Ref<Int>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference10.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+typealias Ref<T> = ref.Reference<D, T>
+local d: D = new {}
+
+test = ref.Reference(d, String, "") as Ref<Listing<String(true)>>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference11.pkl

@@ -0,0 +1,12 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+typealias Ref<T> = ref.Reference<D, T>
+local d: D = new {}
+
+test = ref.Reference(d, String, "") as Ref<Alias1?>
+
+typealias Alias1 = Int | Alias2?
+typealias Alias2 = String(length < 5)

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference12.pkl

@@ -0,0 +1,12 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+typealias RefAlias1 = ref.Reference<D, Alias1?>
+local d: D = new {}
+
+test = ref.Reference(d, String, "") as RefAlias1
+
+typealias Alias1 = Int | Alias2?
+typealias Alias2 = String(length < 5)

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference13.pkl

@@ -0,0 +1,8 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, Mapping, "").default

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference14.pkl

@@ -0,0 +1,8 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, Listing, "").default

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference15.pkl

@@ -0,0 +1,8 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, Dynamic, "").default

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference16.pkl

@@ -0,0 +1,10 @@
+import "pkl:ref"
+
+import ".../input-helper/errors/ReferencedModule.pkl"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, ReferencedModule.getClass(), "").output

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference17.pkl

@@ -0,0 +1,10 @@
+import "pkl:ref"
+
+import ".../input-helper/errors/ReferencedModuleWithOutputOverride.pkl"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, ReferencedModuleWithOutputOverride.getClass(), "").output

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference18.pkl

@@ -0,0 +1,12 @@
+import "pkl:ref"
+
+import ".../input-helper/errors/ReferencedModuleWithOutputOverride.pkl"
+
+class ModuleSubclass extends ReferencedModuleWithOutputOverride
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, ModuleSubclass, "").output

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference19.pkl

@@ -0,0 +1,12 @@
+import "pkl:ref"
+
+class A {
+  foo: String | Int | Boolean
+}
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+test = ref.Reference(d, A, "").foo as ref.Reference<D, Int | Boolean>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference2.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+test = ref.Reference(d, String, "") as Ref<Boolean | Int>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference20.pkl

@@ -0,0 +1,15 @@
+import "pkl:ref"
+
+class A {
+  foo: String | Int | Boolean
+}
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+
+local test = ref.Reference(d, A, "").foo
+testInterpolation = "test:\(test)"
+
+// this tests that the interpolation appears in the output when referenceToString throws

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference3.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+test = ref.Reference(d, String, "") as Ref<Listing<String>>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference4.pkl

@@ -0,0 +1,12 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+test = ref.Reference(d, String, "") as Ref<Alias1?>
+
+typealias Alias1 = Int | Alias2?
+typealias Alias2 = Boolean

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference5.pkl

@@ -0,0 +1,14 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+class D2 extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d2: D2 = new {}
+
+test = ref.Reference(d2, String, "") as Ref<String>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference6.pkl

@@ -0,0 +1,13 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+class A {
+  b: String
+}
+
+test = ref.Reference(d, String, new A {}).c

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference7.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+local d: D = new {}
+typealias Ref<T> = ref.Reference<D, T>
+
+test = ref.Reference(d, List, List())["hi"]

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference8.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+typealias Ref<T> = ref.Reference<D, T>
+local d: D = new {}
+
+test = ref.Reference(d, String, "") as Ref<String(true)>

pkl-core/src/test/files/LanguageSnippetTests/input/errors/reference9.pkl

@@ -0,0 +1,9 @@
+import "pkl:ref"
+
+class D extends ref.Domain {
+  function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+}
+typealias Ref<T> = ref.Reference<D, T>
+local d: D = new {}
+
+test = ref.Reference(d, String, "") as Ref<String(true) | Int>

pkl-core/src/test/files/LanguageSnippetTests/output/api/reference.pcf

@@ -0,0 +1,60 @@
+a {
+  name = "a"
+  id = "some-a-value"
+}
+b {
+  name = "b"
+  id = "some-b-value"
+}
+aOrB {
+  name = "a"
+  id = "some-a-value"
+}
+aRef = "${a}"
+bRef = "${b}"
+unknownRef = "${a}"
+unknownRef2 = "${a}"
+unknownRef3 = "${a}"
+k {
+  aId = "${a.id}"
+  bId = "${b.id}"
+  aProperties = "${a.outputs}"
+  bProperties = "${b.outputs}"
+  aValues {
+    "${a.outputs.foo}"
+    "${a.outputs.someMapping[key]}"
+    "${a.outputs.someMap[key:123]}"
+    "${a.outputs.someListing[0]}"
+    "${a.outputs.someList[9223372036854775807]}"
+    "${b.outputs.nonString}"
+  }
+  bValues {
+    "${b.outputs.foo}"
+    "${b.outputs.someMapping[key]}"
+    "${b.outputs.someMap[key:123]}"
+    "${b.outputs.someListing[0]}"
+    "${b.outputs.someList[9223372036854775807]}"
+    "${a.outputs.nonInt}"
+  }
+  splitUnion = null
+}
+j {
+  aId = null
+  bId = null
+  aProperties = "${a.outputs}"
+  bProperties = null
+  aValues = null
+  bValues = null
+  splitUnion = "${a.outputs.someListing}"
+}
+refInterpolation = "${a.outputs.someListing[1]}"
+kInterpolation = "new K { aId = Reference(new D {}, String, new A { name = \"a\"; id = \"some-a-value\" }).id; bId = Reference(new D {}, String, new B { name = \"b\"; id = \"some-b-value\" }).id; aProperties = Reference(new D {}, reference#AProperties, new A { name = \"a\"; id = \"some-a-value\" }).outputs; bProperties = Reference(new D {}, reference#BProperties, new B { name = \"b\"; id = \"some-b-value\" }).outputs; aValues { Reference(new D {}, Int, new A { name = \"a\"; id = \"some-a-value\" }).outputs.foo; Reference(new D {}, Int | Null, new A { name = \"a\"; id = \"some-a-value\" }).outputs.someMapping[\"key\"]; Reference(new D {}, Int, new A { name = \"a\"; id = \"some-a-value\" }).outputs.someMap[new MapKey { k = 123 }]; Reference(new D {}, Int, new A { name = \"a\"; id = \"some-a-value\" }).outputs.someListing[0]; Reference(new D {}, Int, new A { name = \"a\"; id = \"some-a-value\" }).outputs.someList[9223372036854775807]; Reference(new D {}, Int, new B { name = \"b\"; id = \"some-b-value\" }).outputs.nonString }; bValues { Reference(new D {}, String, new B { name = \"b\"; id = \"some-b-value\" }).outputs.foo; Reference(new D {}, Null | String, new B { name = \"b\"; id = \"some-b-value\" }).outputs.someMapping[\"key\"]; Reference(new D {}, String, new B { name = \"b\"; id = \"some-b-value\" }).outputs.someMap[new MapKey { k = 123 }]; Reference(new D {}, String, new B { name = \"b\"; id = \"some-b-value\" }).outputs.someListing[0]; Reference(new D {}, String, new B { name = \"b\"; id = \"some-b-value\" }).outputs.someList[9223372036854775807]; Reference(new D {}, String, new A { name = \"a\"; id = \"some-a-value\" }).outputs.nonInt }; splitUnion = null }"
+aValuesJoined = """
+  org.pkl.core.runtime.VmReference@<addr>
+  org.pkl.core.runtime.VmReference@<addr>
+  org.pkl.core.runtime.VmReference@<addr>
+  org.pkl.core.runtime.VmReference@<addr>
+  org.pkl.core.runtime.VmReference@<addr>
+  org.pkl.core.runtime.VmReference@<addr>
+  """
+typeArgs = "${null.prop}"

pkl-core/src/test/files/LanguageSnippetTests/output/errors/cannotFindStdLibModule.err

@@ -20,6 +20,7 @@ pkl:pklbinary
 pkl:platform
 pkl:Project
 pkl:protobuf
+pkl:ref
 pkl:reflect
 pkl:release
 pkl:semver

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference1.err

@@ -0,0 +1,15 @@
+–– Pkl Error ––
+Expected value of type `pkl.ref#Reference<reference1#D, Int>`, but got type `pkl.ref#Reference<reference1#D, String>`.
+Value: Reference(new D {}, String, "")
+
+x | typealias Ref<T> = ref.Reference<D, T>
+                       ^^^^^^^^^^^^^^^^^^^
+at reference1#test (file:///$snippetsDir/input/errors/reference1.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference10.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+`Reference` referent type argument may not include type constraints.
+
+x | test = ref.Reference(d, String, "") as Ref<Listing<String(true)>>
+                                           ^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference10#test (file:///$snippetsDir/input/errors/reference10.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference11.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+`Reference` referent type argument may not include type constraints.
+
+x | test = ref.Reference(d, String, "") as Ref<Alias1?>
+                                           ^^^^^^^^^^^^
+at reference11#test (file:///$snippetsDir/input/errors/reference11.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference12.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+`Reference` referent type argument may not include type constraints.
+
+x | typealias RefAlias1 = ref.Reference<D, Alias1?>
+                          ^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference12#RefAlias1 (file:///$snippetsDir/input/errors/reference12.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference13.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `default` in object of type `pkl.ref#Reference<reference13#D, Mapping<unknown, unknown>>`.
+
+x | test = ref.Reference(d, Mapping, "").default
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference13#test (file:///$snippetsDir/input/errors/reference13.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference14.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `default` in object of type `pkl.ref#Reference<reference14#D, Listing<unknown>>`.
+
+x | test = ref.Reference(d, Listing, "").default
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference14#test (file:///$snippetsDir/input/errors/reference14.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference15.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `default` in object of type `pkl.ref#Reference<reference15#D, Dynamic>`.
+
+x | test = ref.Reference(d, Dynamic, "").default
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference15#test (file:///$snippetsDir/input/errors/reference15.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference16.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `output` in object of type `pkl.ref#Reference<reference16#D, ReferencedModule>`.
+
+xx | test = ref.Reference(d, ReferencedModule.getClass(), "").output
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference16#test (file:///$snippetsDir/input/errors/reference16.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference17.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `output` in object of type `pkl.ref#Reference<reference17#D, ReferencedModuleWithOutputOverride>`.
+
+xx | test = ref.Reference(d, ReferencedModuleWithOutputOverride.getClass(), "").output
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference17#test (file:///$snippetsDir/input/errors/reference17.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference18.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `output` in object of type `pkl.ref#Reference<reference18#D, reference18#ModuleSubclass>`.
+
+xx | test = ref.Reference(d, ModuleSubclass, "").output
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference18#test (file:///$snippetsDir/input/errors/reference18.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference19.err

@@ -0,0 +1,15 @@
+–– Pkl Error ––
+Expected value of type `pkl.ref#Reference<reference19#D, Int | Boolean>`, but got type `pkl.ref#Reference<reference19#D, Boolean | Int | String>`.
+Value: Reference(new D {}, Boolean | Int | String, "").foo
+
+xx | test = ref.Reference(d, A, "").foo as ref.Reference<D, Int | Boolean>
+                                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference19#test (file:///$snippetsDir/input/errors/reference19.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference2.err

@@ -0,0 +1,15 @@
+–– Pkl Error ––
+Expected value of type `pkl.ref#Reference<reference2#D, Boolean | Int>`, but got type `pkl.ref#Reference<reference2#D, String>`.
+Value: Reference(new D {}, String, "")
+
+x | typealias Ref<T> = ref.Reference<D, T>
+                       ^^^^^^^^^^^^^^^^^^^
+at reference2#test (file:///$snippetsDir/input/errors/reference2.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference20.err

@@ -0,0 +1,22 @@
+–– Pkl Error ––
+not supported
+
+x | function renderReference(reference: ref.Reference<D, Any>): String = throw("not supported")
+                                                                         ^^^^^^^^^^^^^^^^^^^^^^
+at reference20#D.renderReference (file:///$snippetsDir/input/errors/reference20.pkl)
+
+xxx | function toString(): String = getDomain().renderReference(this)
+                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.ref#Reference.toString (pkl:ref)
+
+xx | testInterpolation = "test:\(test)"
+                               ^^^^^^^
+at reference20#testInterpolation (file:///$snippetsDir/input/errors/reference20.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference3.err

@@ -0,0 +1,15 @@
+–– Pkl Error ––
+Expected value of type `pkl.ref#Reference<reference3#D, Listing<String>>`, but got type `pkl.ref#Reference<reference3#D, String>`.
+Value: Reference(new D {}, String, "")
+
+x | typealias Ref<T> = ref.Reference<D, T>
+                       ^^^^^^^^^^^^^^^^^^^
+at reference3#test (file:///$snippetsDir/input/errors/reference3.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference4.err

@@ -0,0 +1,15 @@
+–– Pkl Error ––
+Expected value of type `pkl.ref#Reference<reference4#D, reference4#Alias1?>`, but got type `pkl.ref#Reference<reference4#D, String>`.
+Value: Reference(new D {}, String, "")
+
+x | typealias Ref<T> = ref.Reference<D, T>
+                       ^^^^^^^^^^^^^^^^^^^
+at reference4#test (file:///$snippetsDir/input/errors/reference4.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference5.err

@@ -0,0 +1,15 @@
+–– Pkl Error ––
+Expected value of type `pkl.ref#Reference<reference5#D, String>`, but got type `pkl.ref#Reference<reference5#D2, String>`.
+Value: Reference(new D2 {}, String, "")
+
+x | typealias Ref<T> = ref.Reference<D, T>
+                       ^^^^^^^^^^^^^^^^^^^
+at reference5#test (file:///$snippetsDir/input/errors/reference5.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference6.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+Cannot find property `c` in object of type `pkl.ref#Reference<reference6#D, String>`.
+
+xx | test = ref.Reference(d, String, new A {}).c
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference6#test (file:///$snippetsDir/input/errors/reference6.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference7.err

@@ -0,0 +1,16 @@
+–– Pkl Error ––
+Operator `[]` is not defined for operand types `pkl.ref#Reference<reference7#D, List<unknown>>` and `String`.
+Left operand : Reference(new D {}, List<unknown>, List())
+Right operand: "hi"
+
+x | test = ref.Reference(d, List, List())["hi"]
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at reference7#test (file:///$snippetsDir/input/errors/reference7.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference8.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+`Reference` referent type argument may not include type constraints.
+
+x | test = ref.Reference(d, String, "") as Ref<String(true)>
+                                           ^^^^^^^^^^^^^^^^^
+at reference8#test (file:///$snippetsDir/input/errors/reference8.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

pkl-core/src/test/files/LanguageSnippetTests/output/errors/reference9.err

@@ -0,0 +1,14 @@
+–– Pkl Error ––
+`Reference` referent type argument may not include type constraints.
+
+x | test = ref.Reference(d, String, "") as Ref<String(true) | Int>
+                                           ^^^^^^^^^^^^^^^^^^^^^^^
+at reference9#test (file:///$snippetsDir/input/errors/reference9.pkl)
+
+xxx | renderer.renderDocument(value)
+      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at pkl.base#Module.output.text (pkl:base)
+
+xxx | if (renderer is BytesRenderer) renderer.renderDocument(value) else text.encodeToBytes("UTF-8")
+                                                                         ^^^^
+at pkl.base#Module.output.bytes (pkl:base)

stdlib/ref.pkl

@@ -0,0 +1,207 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+/// Type-safe deferred references to values not known at evaluation time.
+///
+/// References are an advanced API design tool that enables library authors to express
+/// domain-specific references to values that may not be known during evaluation.
+/// They are particularly suited for configuring execution systems where tasks have well-typed
+/// inputs and output.
+///
+/// WARNING: The API and semantics of references are subject to change in a future release.
+/// The Pkl team is soliciting feedback from authors of libraries considering adopting references.
+/// For questions and feedback, please reach out via
+/// [GitHub Discussions](https://github.com/apple/pkl/discussions) or
+/// [create an issue](https://github.com/apple/pkl/issues/new).
+@ModuleInfo { minPklVersion = "0.32.0" }
+module pkl.ref
+
+/// Creates a deferred [Reference] to a value of type [class] in the given [domain].
+///
+/// References may only be constructed for single, non-generic class types.
+/// To create a reference to other types (generic classes, union, nullable, constrained,
+/// typealiases, etc.), it may be necessary to create a wrapper class with a property of the desired
+/// type.
+/// Example:
+/// ```
+/// referenceListingString: Reference<Domain, Listing<String>> = Reference(domain, Holder, data).$
+///
+/// class Holder {
+///   $: Listing<String>
+/// }
+/// ```
+external const function Reference<D, T>(
+  domain: D(this is Domain),
+  `class`: Class<T>,
+  data: Any,
+): Reference<D, T>
+
+/// A reference to a value that may not exist at evaluation time.
+///
+/// References are an advanced API design tool that enables library authors to express
+/// domain-specific references to values that may not be known during evaluation.
+///
+/// Instances are created with the [Reference()] constructor method.
+/// References consist of four parts:
+/// * [Domain]: determines which references are compatible and how references are rendered
+///   as strings.
+/// * Data: an arbitrary value that may contain domain-specific information about the
+///   referenced value.
+/// * Path: a [List] of [Access] values indicating how the reference was accessed (by property or
+///   subscript).
+/// * Referent type: the type of the value that the reference refers to.
+///
+/// Every time a reference is accessed, either via qualified property access
+/// (`<reference>.<property>`) or subscript (`<reference>[<key>]`), a new reference is returned.
+/// The new reference shares the same domain and data as the original reference.
+/// The new reference's path extends the original reference's with an [Access] instance describing
+/// the accessed property name or subscript key.
+/// The new reference's referent type is the type of the accessed property or subscript value of the
+/// original referent type.
+/// Properties with the `external` modifier may not be referenced.
+/// Any type constraints within the referent type are erased and type constraints are not allowed
+/// in the referent (second) type argument of any Reference type annotations.
+///
+/// Example:
+/// ```
+/// import "pkl:ref"
+///
+/// /// Define a domain class for this configuration system:
+/// class Domain extends ref.Domain {
+///   /// Define how this domain renders references to strings:
+///   function renderReference(reference: ref.Reference<Domain, Any>): String =
+///     (
+///       List(reference.getData().toString())
+///       + reference.getPath().map((it) -> it.property ?? it.key.toString())
+///     ).join("/")
+/// }
+///
+/// class Resource {
+///   name: String
+///   /// Types that provide references will often vend a "root" Reference via a `fixed` property.
+///   /// Here, this references [Outputs] and the `data` identifies the enclosing [Resource]. 
+///   fixed outputs: ref.Reference<Domain, Outputs> = ref.Reference(new Domain {}, Outputs, name)
+/// }
+///
+/// class Outputs {
+///   a: String
+///   b: String(length < 5)
+///   c: Listing<String>
+///   d: Mapping<Foo, Int(isOdd)?>
+///   e: Foo | Bar
+/// }
+///
+/// class Foo {
+///   x: Int
+///
+///   function toString(): String = "foo:\(x)"
+/// }
+///
+/// class Bar {
+///   x: Float
+///
+///   function toString(): String = "bar:\(x)"
+/// }
+///
+/// local outputs: ref.Reference<Domain, Outputs> = new Resource { name = "root" }.outputs
+///
+/// /// Simple property access.
+/// /// getPath() == List(new ref.Access { property = "a" })
+/// aRef: ref.Reference<Domain, String> = outputs.a
+///
+/// /// Type constraint erasure.
+/// /// getPath() == List(new ref.Access { property = "b" })
+/// bRef: ref.Reference<Domain, String> = outputs.b
+///
+/// /// Simple subscript access.
+/// /// getPath() == List(new ref.Access { property = "c" }, new ref.Access { key = 10 })
+/// cRef: ref.Reference<Domain, String> = outputs.c[10]
+///
+/// /// Simple property access:
+/// /// getPath() == List(new ref.Access { property = "d" }, new ref.Access { key = new Foo { x = 1 } })
+/// /// The type constraint on the Mapping value type argument is also erased.
+/// dRef: ref.Reference<Domain, Int?> = outputs.d[new Foo { x = 1 }]
+///
+/// /// Simple property access:
+/// /// getPath() == List(new ref.Access { property = "e" }, new ref.Access { property = "x" })
+/// eRef: ref.Reference<Domain, Int | Float> = outputs.e.x
+///
+/// // Render references as strings:
+/// output {
+///   renderer {
+///     converters {
+///       [ref.Reference] = (it) -> it.toString()
+///     }
+///   }
+/// }
+/// ```
+///
+/// Output:
+/// ```
+/// aRef = "root/a"
+/// bRef = "root/b"
+/// cRef = "root/c/10"
+/// dRef = "root/d/foo:1"
+/// eRef = "root/e/x"
+/// ```
+external class Reference<out D, out T> {
+  /// The domain the reference belongs to.
+  external function getDomain(): D
+
+  /// Arbitrary data attached to the reference during creation.
+  ///
+  /// Used for domain-specific purposes such as controlling how the reference is rendered. 
+  external function getData(): Any
+
+  /// The path of property and subscript access applied to the reference.
+  external function getPath(): List<Access>
+
+  /// Render the reference to a string using its domain's ([getDomain()])
+  /// [Domain.referencetoString()] method.
+  function toString(): String = getDomain().renderReference(this)
+}
+
+/// Represents a configuration domain that a [Reference] may exist within.
+///
+/// Library authors supporting references should declare a subclass of [Domain] to be shared by all
+/// inter-compatible [Reference] instances.
+///
+/// A domain also determines how [Reference] values are transformed into strings; see
+/// [renderReference()].
+abstract class Domain {
+  /// Must be overridden by domain classes to determine how [Reference] instances are transformed to
+  /// strings by [Reference.toString()] and string interpolation.
+  abstract function renderReference(reference: Reference<Domain, Any>): String
+}
+
+/// Represents a property or subscript access as part of a [Reference]'s path.
+class Access {
+  /// Indicates if this represents a property access.
+  fixed isProperty: Boolean = property != null
+
+  /// Indicates if this represents a subscript access.
+  fixed isSubscript: Boolean = property == null
+
+  /// The property that was accessed.
+  ///
+  /// If non-null, this is a property access. If `null` this is a subscript access.
+  property: String(key == null)?
+
+  /// The subscript key that was accessed.
+  ///
+  /// May be null even when [property] is null, which represents a subscript access with key `null`.
+  key: Any
+}