Annotation

Annotations are a form of metadata or additional information attached to a specific code without changint its core logic but tells the compilers or tools how to treat that code.

Compile-time

@compile-time is a built-in annotation that tells the compiler that a specific line or block of code should run at compile time.

Example

@compile-time
for(int8 i = 0; i < 10; i++){
  print("hello, world");
}

This code clearly prints hello, world 10 times, no trick. Normally, the computer does not know how to print the text 10 times, it's just us that write a logic to check and update the i so the execution jump to where the print is called ten times and at run time.

However in the code above, as it's marked with @compile-time, the compiler will execute this for loop at compile time before translate it into machine code. Which means that the actual code that will be generated into assembly is something like this:

print("hello, world"); # 1 
print("hello, world"); # 2
print("hello, world"); # 3
print("hello, world"); # 4
print("hello, world"); # 5
print("hello, world"); # 6
print("hello, world"); # 7
print("hello, world"); # 8
print("hello, world"); # 9
print("hello, world"); # 10

It just prints hello, world 10 times without additional for loop.

Executing only at the surface level means that the compiler will not try to run, at compile time, the code that isn't part of the current block of code.
As in example above, the compiler may execute for loop at compile time but it won't do the same thing with the print . It won't go to that print function and try execute the code inside at compile time.

Basically, @compile-time only executes what it can see at the surface, it doesn't care what's behind the wall.