Drop @capability annotations

Replace with references that inherit trait `Capability`.

Author: odersky

compiler/src/dotty/tools/dotc/cc/CaptureOps.scala

@@ -203,6 +203,23 @@ extension (tp: Type)
     case _ =>
       false
 
+  /** Does type derive from caps.Capability?, which means it references of this
+   *  type are maximal capabilities?
+   */
+  def derivesFromCapability(using Context): Boolean = tp.dealias match
+    case tp: (TypeRef | AppliedType) =>
+      val sym = tp.typeSymbol
+      if sym.isClass then sym.derivesFrom(defn.Caps_Capability)
+      else tp.superType.derivesFromCapability
+    case tp: TypeProxy =>
+      tp.superType.derivesFromCapability
+    case tp: AndType =>
+      tp.tp1.derivesFromCapability || tp.tp2.derivesFromCapability
+    case tp: OrType =>
+      tp.tp1.derivesFromCapability && tp.tp2.derivesFromCapability
+    case _ =>
+      false
+
   /** Drop @retains annotations everywhere */
   def dropAllRetains(using Context): Type = // TODO we should drop retains from inferred types before unpickling
     val tm = new TypeMap:
@@ -408,7 +425,7 @@ extension (sym: Symbol)
   /** The owner of the current level. Qualifying owners are
    *   - methods other than constructors and anonymous functions
    *   - anonymous functions, provided they either define a local
-   *     root of type caps.Cap, or they are the rhs of a val definition.
+   *     root of type caps.Capability, or they are the rhs of a val definition.
    *   - classes, if they are not staticOwners
    *   - _root_
    */

compiler/src/dotty/tools/dotc/cc/CaptureSet.scala

@@ -1051,7 +1051,8 @@ object CaptureSet:
         case tp: TermParamRef =>
           tp.captureSet
         case tp: TypeRef =>
-          if tp.typeSymbol == defn.Caps_Cap then universal else empty
+          if tp.derivesFromCapability then universal // TODO: maybe return another value that indicates that the underltinf ref is maximal?
+          else empty
         case _: TypeParamRef =>
           empty
         case CapturingType(parent, refs) =>

compiler/src/dotty/tools/dotc/cc/CheckCaptures.scala

@@ -537,8 +537,8 @@ class CheckCaptures extends Recheck, SymTransformer:
          */
         def addParamArgRefinements(core: Type, initCs: CaptureSet): (Type, CaptureSet) =
           var refined: Type = core
-          var allCaptures: CaptureSet = if setup.isCapabilityClassRef(core)
-            then CaptureSet.universal else initCs
+          var allCaptures: CaptureSet =
+            if core.derivesFromCapability then CaptureSet.universal else initCs
           for (getterName, argType) <- mt.paramNames.lazyZip(argTypes) do
             val getter = cls.info.member(getterName).suchThat(_.is(ParamAccessor)).symbol
             if getter.termRef.isTracked && !getter.is(Private) then
@@ -572,8 +572,10 @@ class CheckCaptures extends Recheck, SymTransformer:
         val TypeApply(fn, args) = tree
         val polyType = atPhase(thisPhase.prev):
           fn.tpe.widen.asInstanceOf[TypeLambda]
+        def isExempt(sym: Symbol) =
+          sym.isTypeTestOrCast || sym == defn.Compiletime_erasedValue
         for case (arg: TypeTree, formal, pname) <- args.lazyZip(polyType.paramRefs).lazyZip((polyType.paramNames)) do
-          if !tree.symbol.isTypeTestOrCast then
+          if !isExempt(tree.symbol) then
             def where = if fn.symbol.exists then i" in an argument of ${fn.symbol}" else ""
             disallowRootCapabilitiesIn(arg.knownType, NoSymbol,
               i"Sealed type variable $pname", "be instantiated to",
@@ -1305,7 +1307,7 @@ class CheckCaptures extends Recheck, SymTransformer:
                 case ref: TermParamRef
                 if !allowed.contains(ref) && !seen.contains(ref) =>
                   seen += ref
-                  if ref.underlying.isRef(defn.Caps_Cap) then
+                  if ref.underlying.isRef(defn.Caps_Capability) then
                     report.error(i"escaping local reference $ref", tree.srcPos)
                   else
                     val widened = ref.captureSetOfInfo

compiler/src/dotty/tools/dotc/cc/Setup.scala

@@ -77,9 +77,7 @@ class Setup extends PreRecheck, SymTransformer, SetupAPI:
   def isCapabilityClassRef(tp: Type)(using Context): Boolean = tp.dealiasKeepAnnots match
     case _: TypeRef | _: AppliedType =>
       val sym = tp.classSymbol
-      def checkSym: Boolean =
-        sym.hasAnnotation(defn.CapabilityAnnot)
-        || sym.info.parents.exists(hasUniversalCapability)
+      def checkSym: Boolean = sym.info.parents.exists(hasUniversalCapability)
       sym.isClass && capabilityClassMap.getOrElseUpdate(sym, checkSym)
     case _ => false
 
@@ -594,7 +592,7 @@ class Setup extends PreRecheck, SymTransformer, SetupAPI:
         if sym.isClass then
           !sym.isPureClass
         else
-          sym != defn.Caps_Cap && instanceCanBeImpure(tp.superType)
+          sym != defn.Caps_Capability && instanceCanBeImpure(tp.superType)
       case tp: (RefinedOrRecType | MatchType) =>
         instanceCanBeImpure(tp.underlying)
       case tp: AndType =>

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -991,7 +991,7 @@ class Definitions {
 
   @tu lazy val CapsModule: Symbol = requiredModule("scala.caps")
     @tu lazy val captureRoot: TermSymbol = CapsModule.requiredValue("cap")
-    @tu lazy val Caps_Cap: TypeSymbol = CapsModule.requiredType("Cap")
+    @tu lazy val Caps_Capability: TypeSymbol = CapsModule.requiredType("Capability")
     @tu lazy val Caps_reachCapability: TermSymbol = CapsModule.requiredMethod("reachCapability")
     @tu lazy val CapsUnsafeModule: Symbol = requiredModule("scala.caps.unsafe")
     @tu lazy val Caps_unsafeAssumePure: Symbol = CapsUnsafeModule.requiredMethod("unsafeAssumePure")
@@ -1014,7 +1014,6 @@ class Definitions {
   @tu lazy val BeanPropertyAnnot: ClassSymbol = requiredClass("scala.beans.BeanProperty")
   @tu lazy val BooleanBeanPropertyAnnot: ClassSymbol = requiredClass("scala.beans.BooleanBeanProperty")
   @tu lazy val BodyAnnot: ClassSymbol = requiredClass("scala.annotation.internal.Body")
-  @tu lazy val CapabilityAnnot: ClassSymbol = requiredClass("scala.annotation.capability")
   @tu lazy val ChildAnnot: ClassSymbol = requiredClass("scala.annotation.internal.Child")
   @tu lazy val ContextResultCountAnnot: ClassSymbol = requiredClass("scala.annotation.internal.ContextResultCount")
   @tu lazy val ProvisionalSuperClassAnnot: ClassSymbol = requiredClass("scala.annotation.internal.ProvisionalSuperClass")
@@ -2033,7 +2032,7 @@ class Definitions {
    */
   @tu lazy val ccExperimental: Set[Symbol] = Set(
     CapsModule, CapsModule.moduleClass, PureClass,
-    CapabilityAnnot, RequiresCapabilityAnnot,
+    RequiresCapabilityAnnot,
     RetainsAnnot, RetainsCapAnnot, RetainsByNameAnnot)
 
   /** Experimental language features defined in `scala.runtime.stdLibPatches.language.experimental`.

compiler/src/dotty/tools/dotc/core/Types.scala

@@ -3014,7 +3014,8 @@ object Types extends TypeUtils {
       name == nme.CAPTURE_ROOT && symbol == defn.captureRoot
 
     override def isMaxCapability(using Context): Boolean =
-      widen.derivesFrom(defn.Caps_Cap) && symbol.isStableMember
+      import cc.*
+      this.derivesFromCapability && symbol.isStableMember
 
     override def normalizedRef(using Context): CaptureRef =
       if isTrackableRef then symbol.termRef else this
@@ -4815,7 +4816,9 @@ object Types extends TypeUtils {
     def kindString: String = "Term"
     def copyBoundType(bt: BT): Type = bt.paramRefs(paramNum)
     override def isTrackableRef(using Context) = true
-    override def isMaxCapability(using Context) = widen.derivesFrom(defn.Caps_Cap)
+    override def isMaxCapability(using Context) =
+      import cc.*
+      this.derivesFromCapability
   }
 
   private final class TermParamRefImpl(binder: TermLambda, paramNum: Int) extends TermParamRef(binder, paramNum)

library/src/scala/CanThrow.scala

@@ -6,9 +6,9 @@ import annotation.{implicitNotFound, experimental, capability}
  *  experimental.saferExceptions feature, a `throw Ex()` expression will require
  *  a given of class `CanThrow[Ex]` to be available.
  */
-@experimental @capability
+@experimental
 @implicitNotFound("The capability to throw exception ${E} is missing.\nThe capability can be provided by one of the following:\n - Adding a using clause `(using CanThrow[${E}])` to the definition of the enclosing method\n - Adding `throws ${E}` clause after the result type of the enclosing method\n - Wrapping this piece of code with a `try` block that catches ${E}")
-erased class CanThrow[-E <: Exception]
+erased class CanThrow[-E <: Exception] extends caps.Capability
 
 @experimental
 object unsafeExceptions:

library/src/scala/annotation/capability.scala

@@ -11,4 +11,6 @@ import annotation.experimental
  *  THere, the capture set of any instance of `CanThrow` is assumed to be
  *  `{*}`.
  */
-@experimental final class capability extends StaticAnnotation
+@experimental
+@deprecated("To make a class a capability, let it derive from the `Capability` trait instead")
+final class capability extends StaticAnnotation

library/src/scala/caps.scala

@@ -4,14 +4,17 @@ import annotation.experimental
 
 @experimental object caps:
 
-  class Cap // should be @erased
+  trait Capability // should be @erased
+
+  /** The universal capture reference */
+  val cap: Capability = new Capability() {}
 
   /** The universal capture reference (deprecated) */
   @deprecated("Use `cap` instead")
-  val `*`: Cap = cap
+  val `*`: Capability = cap
 
-  /** The universal capture reference */
-  val cap: Cap = Cap()
+  @deprecated("Use `Capability` instead")
+  type Cap = Capability
 
   /** Reach capabilities x* which appear as terms in @retains annotations are encoded
    *  as `caps.reachCapability(x)`. When converted to CaptureRef types in capture sets

tests/disabled/pos/lazylist.scala

@@ -34,7 +34,7 @@ object LazyNil extends LazyList[Nothing]:
 def map[A, B](xs: {*} LazyList[A], f: {*} A => B): {f, xs} LazyList[B] =
   xs.map(f)
 
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 def test(cap1: Cap, cap2: Cap, cap3: Cap) =
   def f[T](x: LazyList[T]): LazyList[T] = if cap1 == cap1 then x else LazyNil

tests/neg-custom-args/captures/box-unsoundness.scala

@@ -1,4 +1,3 @@
-//@annotation.capability
 class CanIO { def use(): Unit = () }
 def use[X](x: X): (op: X -> Unit) -> Unit = op => op(x)
 def test(io: CanIO^): Unit =

tests/neg-custom-args/captures/byname.check

@@ -1,7 +1,7 @@
 -- Error: tests/neg-custom-args/captures/byname.scala:19:5 -------------------------------------------------------------
 19 |  h(g()) // error
    |    ^^^
-   |    reference (cap2 : Cap^) is not included in the allowed capture set {cap1}
+   |    reference (cap2 : Cap) is not included in the allowed capture set {cap1}
    |    of an enclosing function literal with expected type () ?->{cap1} I
 -- [E007] Type Mismatch Error: tests/neg-custom-args/captures/byname.scala:4:2 -----------------------------------------
  4 |  def f() = if cap1 == cap1 then g else g // error

tests/neg-custom-args/captures/byname.scala

@@ -1,4 +1,4 @@
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 def test(cap1: Cap, cap2: Cap) =
   def f() = if cap1 == cap1 then g else g // error

tests/neg-custom-args/captures/capt-box-env.scala

@@ -1,4 +1,4 @@
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 class Pair[+A, +B](x: A, y: B):
     def fst: A = x

tests/neg-custom-args/captures/capt-box.scala

@@ -1,4 +1,4 @@
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 def test(x: Cap) =
 

tests/neg-custom-args/captures/capt-wf2.scala

@@ -1,4 +1,4 @@
-@annotation.capability class C
+class C extends caps.Capability
 
 def test(c: C) =
   var x: Any^{c} = ???

tests/neg-custom-args/captures/caseclass/Test_2.scala

@@ -1,4 +1,4 @@
-@annotation.capability class C
+class C extends caps.Capability
 def test(c: C) =
   val pure: () -> Unit = () => ()
   val impure: () => Unit = pure

tests/neg-custom-args/captures/cc-this.scala

@@ -1,4 +1,4 @@
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 def eff(using Cap): Unit = ()
 

tests/neg-custom-args/captures/cc-this2.check

@@ -2,7 +2,7 @@
 -- Error: tests/neg-custom-args/captures/cc-this2/D_2.scala:3:8 --------------------------------------------------------
 3 |  this: D^ => // error
   |        ^^
-  |reference (caps.cap : caps.Cap) captured by this self type is not included in the allowed capture set {} of pure base class class C
+  |reference (caps.cap : caps.Capability) captured by this self type is not included in the allowed capture set {} of pure base class class C
 -- [E058] Type Mismatch Error: tests/neg-custom-args/captures/cc-this2/D_2.scala:2:6 -----------------------------------
 2 |class D extends C: // error
   |      ^

tests/neg-custom-args/captures/cc-this3.scala

@@ -1,4 +1,4 @@
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 def eff(using Cap): Unit = ()
 

tests/neg-custom-args/captures/cc-this5.check

@@ -1,7 +1,7 @@
 -- Error: tests/neg-custom-args/captures/cc-this5.scala:16:20 ----------------------------------------------------------
 16 |    def f = println(c)  // error
    |                    ^
-   |                    (c : Cap^) cannot be referenced here; it is not included in the allowed capture set {}
+   |                    (c : Cap) cannot be referenced here; it is not included in the allowed capture set {}
    |                    of the enclosing class A
 -- [E007] Type Mismatch Error: tests/neg-custom-args/captures/cc-this5.scala:21:15 -------------------------------------
 21 |    val x: A = this // error

tests/neg-custom-args/captures/cc-this5.scala

@@ -1,7 +1,7 @@
 class C:
   val x: C = this
 
-@annotation.capability class Cap
+class Cap extends caps.Capability
 
 def foo(c: Cap) =
   object D extends C:   // error
@@ -17,5 +17,5 @@ def test(c: Cap) =
 
 def test2(c: Cap) =
   class A:
-    def f = println(c) 
+    def f = println(c)
     val x: A = this // error

tests/neg-custom-args/captures/class-constr.scala

@@ -1,6 +1,6 @@
 import annotation.{capability, constructorOnly}
 
-@capability class Cap
+class Cap extends caps.Capability
 
 class C(x: Cap, @constructorOnly y: Cap)
 

tests/neg-custom-args/captures/effect-swaps-explicit.check

@@ -0,0 +1,29 @@
+-- [E007] Type Mismatch Error: tests/neg-custom-args/captures/effect-swaps-explicit.scala:64:8 -------------------------
+63 |      Result:
+64 |        Future: // error, type mismatch
+   |      ^
+   |      Found:    Result.Ok[box Future[box T^?]^{fr, contextual$1}]
+   |      Required: Result[Future[T], Nothing]
+65 |          fr.await.ok
+   |--------------------------------------------------------------------------------------------------------------------
+   |Inline stack trace
+   |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   |This location contains code that was inlined from effect-swaps-explicit.scala:41
+41 |    boundary(Ok(body))
+   |             ^^^^^^^^
+    --------------------------------------------------------------------------------------------------------------------
+   |
+   | longer explanation available when compiling with `-explain`
+-- [E007] Type Mismatch Error: tests/neg-custom-args/captures/effect-swaps-explicit.scala:74:10 ------------------------
+74 |          Future: fut ?=> // error: type mismatch
+   |          ^
+   |          Found:    Future[box T^?]^{fr, lbl}
+   |          Required: Future[box T^?]^?
+75 |            fr.await.ok
+   |
+   | longer explanation available when compiling with `-explain`
+-- Error: tests/neg-custom-args/captures/effect-swaps-explicit.scala:68:15 ---------------------------------------------
+68 |        Result.make: //lbl ?=> // error, escaping label from Result
+   |        ^^^^^^^^^^^
+   |local reference contextual$9 from (using contextual$9: boundary.Label[Result[box Future[box T^?]^{fr, contextual$9}, box E^?]]^):
+   |  box Future[box T^?]^{fr, contextual$9} leaks into outer capture set of type parameter T of method make in object Result

tests/neg-custom-args/captures/effect-swaps-explicit.scala

@@ -0,0 +1,76 @@
+import annotation.capability
+
+object boundary:
+
+  final class Label[-T] // extends caps.Capability
+
+  /** Abort current computation and instead return `value` as the value of
+   *  the enclosing `boundary` call that created `label`.
+   */
+  def break[T](value: T)(using label: Label[T]^): Nothing = ???
+
+  def apply[T](body: Label[T]^ ?=> T): T = ???
+end boundary
+
+import boundary.{Label, break}
+
+trait Async extends caps.Capability
+object Async:
+  def blocking[T](body: Async ?=> T): T = ???
+
+class Future[+T]:
+  this: Future[T]^ =>
+  def await(using Async): T = ???
+object Future:
+  def apply[T](op: Async ?=> T)(using Async): Future[T]^{op} = ???
+
+enum Result[+T, +E]:
+  case Ok[+T](value: T) extends Result[T, Nothing]
+  case Err[+E](error: E) extends Result[Nothing, E]
+
+
+object Result:
+  extension [T, E](r: Result[T, E]^)(using Label[Err[E]]^)
+
+    /** `_.ok` propagates Err to current Label */
+    def ok: T = r match
+      case Ok(value) => value
+      case Err(value) => break[Err[E]](Err(value))
+
+  transparent inline def apply[T, E](inline body: Label[Result[T, E]]^ ?=> T): Result[T, E] =
+    boundary(Ok(body))
+
+  // same as apply, but not an inline method
+  def make[T, E](body: Label[Result[T, E]]^ ?=> T): Result[T, E] =
+    boundary(Ok(body))
+
+end Result
+
+def test[T, E](using Async) =
+  import Result.*
+  Async.blocking: async ?=>
+    val good1: List[Future[Result[T, E]]] => Future[Result[List[T], E]] = frs =>
+      Future:
+        Result:
+          frs.map(_.await.ok) // OK
+
+    val good2: Result[Future[T], E] => Future[Result[T, E]] = rf =>
+      Future:
+        Result:
+          rf.ok.await  // OK, Future argument has type Result[T]
+
+    def fail3(fr: Future[Result[T, E]]^) =
+      Result:
+        Future: // error, type mismatch
+          fr.await.ok
+
+    def fail4[T, E](fr: Future[Result[T, E]]^) =
+        Result.make: //lbl ?=> // error, escaping label from Result
+          Future: fut ?=>
+            fr.await.ok
+
+    def fail5[T, E](fr: Future[Result[T, E]]^) =
+        Result.make[Future[T], E]: lbl ?=>
+          Future: fut ?=> // error: type mismatch
+            fr.await.ok
+