feat(gnovm): interrealm spec; cross/crossing; readonly; defer/recover/panic fixes; blank identifier fixes.... (#4060)

Implements complete interrealm spec.
This uses heapitemvalues more such that a closure or pointer doesn't
need to refer to a block.
It resolves #3693. 
Also includes various defer/panic/recover fixes from #4188.

Excerpt from the new document 'Gno Memory Model' in this PR:

--------

```go
func Example(arg int) (res *int) {
	var x int = arg + 1
	return &x
}
```

The above code when executed will first produce the following block:

```
BlockValue{
    ...
    Source: <*FuncDecl node>,
    Values: [
        {T: nil, V: nil},                      // 'arg' parameter
        {T: nil, V: nil},                      // 'res' result
        {T: HeapItemType{},
	 V: &HeapItemValue{{T: nil, V: nil}},  // 'x' variable
    ],
    ...
}
```

In the above example the third slot for `x` is not initialized to the
zero
value of a typed value slot, but rather it is prefilled with a heap
item.

Variables declared in a closure or passed by reference are first
discovered and
marked as such from the preprocessor, and NewBlock() will prepopulate
these
slots with `*HeapItemValues`. When a `*HeapItemValue` is present in a
block
slot it is not written over but instead the value is written into the
heap
item's slot. 

When the example code executes `return &x` instead of returning a
`PointerValue` with `.Base` set to the `BlockValue` and `.Index` of 2,
it sets
`.Base` to the `*HeapItemValue` with `.Index` of 0 since a heap item
only
contains one slot. The pointer's `.TV` is set to the single slot of of
the heap
item. This way the when the pointer is used later in another transaction
there
is no need to load the whole original block value, but rather a single
heap
item object. If `Example()` returned only `x` rather than a pointer `&x`
it
would not be initialized with a heap item for the slot.

```go
func Example2(arg int) (res func()) {
	var x int = arg + 1
	return func() {
		println(x)
	}
}
```

The above example illustrates another use for heap items. Here we don't
reference `x`, but it is captured by the anonymous function literal
(closure).
At runtime the closure `*FuncValue` captures the heap item object such
that the
closure does not depend on the block at all.

Variables declared at the package (global) level may also be referred to
by
pointer in anonymous functions. In the future we will allow limited
upgrading
features for mutable realm packages (e.g. the ability to add new
functions or
replace or "swizzle" existing ones), so all package level declared
variables
are wrapped in heap item objects.

Since all global package values referenced closures can be captured as
heap
objects, the execution and persistence of a closure function value does
not
depend on any parent blocks. (Omitted here is how references to package
level declared functions and methods are replaced by a selector
expression
on the package itself; otherwise closures would still in general depend
on their parent blocks).

## Loopvars

Go1.22 introduced loopvars to reduce programmer errors. Gno uses 
heap items to implement loopvars.

```go
for _, v := range values {
    saveClosure(func() {
        fmt.Println(v)
    })
}
```

The Gno VM does something special for loopvars. Instead of assigning the
new
value `v` to the same slot, or even the same heap item object's slot, it
replaces the existing heap item object with a new one. This allows the
closure
to capture a new heap item object with every iteration. This is called 
a heap definition.

The behavior is applied for implicit loops with `goto` statements. The
preprocessor first identifies all such variable definitions whether
explicit in
range statements or implicit via `goto` statements that are captured by
closures or passed by pointer reference, and directs the VM to execute
the
define statement by replacing the existing heap item object with a new
one.

---------

Signed-off-by: moul <[email protected]>
Co-authored-by: piux2 <[email protected]>
Co-authored-by: moul <[email protected]>
Co-authored-by: ltzMaxwell <[email protected]>

Author: 4 people

docs/resources/gno-interrealm.md

@@ -0,0 +1,108 @@
+# Interrealm Specification
+
+Gno extends Go's type system with a interrealm rules.  These rules can be
+checked during the static type-checking phase (but at the moment they are
+partially dependent on runtime checks).
+
+All functions in Gno execute under a realm context as determined by the call
+stack. Objects that reside in a realm can only be modified if the realm context
+matches.
+
+A function declared in p packages when called: 
+
+ * inherits the last realm for package declared functions and closures.
+ * inherits the last realm when a method is called on unreal receiver.
+ * implicitly crosses to the receiver's resident realm when a method of the
+   receiver is called. The receiver's realm is also called the "borrow realm".
+
+A function declared in a realm package when called:
+
+ * explicitly crosses to the realm in which the function is declared if the
+   function begins with a `crossing()` statement. The new realm is called the
+   "current realm".
+ * otherwise follows the same rules as for p packages.
+
+The `crossing()` statement must be the first statement of a function's body.
+It is illegal to use anywhere else, and cannot be used in p packages. Functions
+that begin with the `crossing()` statement are called "crossing" functions".
+
+A crossing function declared in a realm different than the last explicitly
+crossed realm *must* be called like `cross(fn)(...)`. That is, functions of
+calls that result in explicit realm crossings must be wrapped with `cross()`.
+
+`std.CurrentRealm()` returns the current realm last explicitly crossed to.
+
+`std.PreviousRealm()` returns the realm explicitly crossed to before that.
+
+A crossing function declared in the same realm package as the callee may be
+called normally OR like `cross(fn)(...)`. When called normally there will be no
+realm crossing, but when called like `cross(fn)(...)` there is technically a
+realm crossing and the current realm and previous realm returned are the same.
+
+The current realm and previous realm do not depend on any implicit crossing to
+the receiver's borrowed/storage realm even if the borrowed realm is the last
+realm of the call stack equal to `m.Realm`. In other words `std.CurrentRealm()`
+may be different than `m.Realm` (the borrow realm) when a receiver is called on
+a foreign object.
+
+Calls of methods on receivers residing in realms different than the current
+realm must not be called like `cross(fn)(...)` if the method is not a
+crossing function itself, and vice versa. Or it could be said that implicit
+crossing is not real realm crossing. (When you sign a document with someone
+else's pen it is still your signature; signature:pen :: current:borrowed.
+
+A crossing method declared in a realm cannot modify the receiver if the object
+resides in a different realm. However not all methods are required to be
+crossing methods, and crossing methods may still read the state of the
+receiver (and in general anything reacheable is readible).
+
+New unreal objects reachable from the borrowed realm (or current realm if there
+was no method call that borrowed) become persisted in the borrowed realm (or
+current realm) upon finalization of the foreign object's method (or function).
+(When you put an unlabeled photo in someone else's scrap book the photo now
+belongs to the other person). In the future we will introduce an `attach()`
+function to prevent a new unreal object from being taken.
+
+MsgCall can only call (realm) crossing functions.
+
+MsgRun will run a file's `main()` function in the user's realm and may call 
+both crossing functions and non-crossing functions.
+
+A realm package's initialization (including init() calls) execute with current
+realm of itself, and it `std.PreviousRealm()` will panic unless the call stack
+includes a crossing function called like `cross(fn)(...)`.
+
+### Justifications
+
+P package code should behave the same even when copied verbatim in a realm
+package.
+
+Realm crossing with respect to `std.CurrentRealm()` and `std.PreviousRealm()`
+is important enough to be explicit and warrants type-checking.
+
+A crossing function of a realm should be able to call another crossing function
+of the same realm without necessarily explicitly crossing realms.
+
+Sometimes the previous realm and current realm must be the same realm, such as
+when a realm consumes a service that it offers to external realms and users.
+
+A method should be able to modify the receiver and associated objects of the
+same borrowed realm.
+
+A method should be able to create new objects that reside in the same realm by
+default in order to maintain storage realm consistency and encapsulation and
+reduce fragmentation.
+
+In the future an object may be migrated from one realm to another when it loses
+all references in one realm and gains references in another. The behavior of
+the object should not change after migration because this type of migration is
+implicit and generally not obvious without more language features.
+
+Code declared in p packages (or declared in "immutable" realm packages) can
+help different realms enforce contracts trustlessly, even those that involve
+the caller's current realm. Otherwise two mutable (upgreadeable) realms cannot
+export trust unto the chain because functions declared in those two realms can
+be upgraded.
+
+Both `crossing()` and `cross(fn)(...)` statements may become special syntax in
+future Gno versions.

docs/resources/gno-memory-model.md

@@ -0,0 +1,218 @@
+# Gno Memory Model
+
+## The Typed Value
+
+```go
+type TypedValue struct {
+        T Type    
+        V Value   
+        N [8]byte 
+}
+```
+
+Both `Type` and `Value` are Go interface values.  Go does not support union
+types, so primitive values like bools and ints are stored in the N field for
+performance.
+
+All values in Gno are stored represented as (type, value) tuples.  Vars in
+scope blocks, fields in structs, elements in arrays, keys and values of maps
+are all respresented by the same `TypedValue` struct.
+
+This tuple representation lets the Gno VM implementation logic be simpler with
+less code.  Reading and writing values are the same whether the static type of
+the value is an interface or something concrete with no special logic for
+memory optimizations which is less relevant in a massive multi-user
+transactional operating system where most of the data resides in disk anyways.
+
+Another benefit is that it promotes the development of new types of client
+interfaces that can make use of the type information for object display and
+interaction. The original vision of Tim Burners Lee's HTML DOM based World Wide
+Web with restful HTTP requests like GET and POST has been steamrolled over by
+continuous developments in HTML, CSS, Javascript, and the browser. The internet
+is alive but the World Wide Web is dead. Gno is a reboot of the original vision
+of the Web but better because everything is integrated based on a singular
+well designed object-oriented language. Instead of POST requests Gno has 
+typed method calls. All values are annotated with their types making the
+environment REST-ful to the core.
+
+> REST (Representational State Transfer) is a software architectural style that
+> was created to describe the design and guide the development of the
+> architecture for the World Wide Web. REST defines a set of constraints for
+> how the architecture of a distributed, Internet-scale hypermedia system, such
+> as the Web, should behave. - wikipedia
+
+While the Gno VM implements the memory model described here in the most
+straightforward way, future alternative implementations may represent values
+differently in machine memory even while conforming to the spec as implemented
+by the Gno VM.
+
+
+## Objects and Values
+
+There are many types of Values, and some of these value types are also Objects.
+The types below are all values and those that are bolded are also objects.
+
+ * Primitive            // bool, uint, int, uint8, ... int64
+ * StringValue
+ * BigintValue          // only used for constant expressions
+ * BigdecValue          // only used for constant expressions
+ * DataByteValue        // invisible type for byte array optimization
+ * PointerValue         // base is always an object
+ * **ArrayValue**
+ * SliceValue
+ * **StructValue**
+ * **FuncValue**
+ * **MapValue**
+ * **BoundMethodValue** // func & receiver
+ * TypeValue
+ * PackageValue
+ * **BlockValue**       // for package, file, if, range, switch, func
+ * RefValue             // reference to an object stored in disk
+ * **HeapItemValue**    // invisible type for loopvars and closure captures
+
+
+## Pointers
+
+```go
+type PointerValue struct {
+        TV    *TypedValue // escape val if pointer to var.
+        Base  Value       // array/struct/block, or heapitem.
+        Index int         // list/fields/values index, or -1 or -2 (see below).
+}
+```
+
+The pointer is a reference to a typed value slot in an array, struct, block,
+or heap item. It is also used internally in the VM for assigning to slots.
+Even internally the Base is used to tell the realm finalizer when the base
+has been updated.
+
+## Blocks and Heap Items
+
+All statements enclosed in {} parentheses will allocate a new block
+and push it onto the block stack of the VM. The size of the block
+is determined by the number of variables declared in the block statement.
+
+```
+type BlockValue struct {
+	ObjectInfo            
+	Source   BlockNode
+	Values   []TypedValue
+	Parent   Value         // Parent block if any, or RefValue{} to one.
+	Blank    TypedValue    // Captures "_" underscore names.
+	bodyStmt bodyStmt      // Holds a pointer to the current statement.
+}
+```
+
+The following Gno AST nodes when executed will create a new block:
+
+ * FuncLitStmt
+ * BlockStmt    // a list of statements wrapped in {} 
+ * ForStmt
+ * IfCaseStmt
+ * RangeStmt
+ * SwitchCaseStmt
+ * FuncDecl
+ * FileNode
+ * PackageNode
+
+`IfStmt`s and `SwitchStmt`s also produce faux blocks that get merged onto the
+following `IfCaseStmt` and `SwitchCaseStmt` respectively, but this is an
+invisible implementation detail and the behavior may change.
+
+Heap items are only used in blocks. Conceptually they are an object container
+around a singleton typed value slot. It is not visible to the gno developer
+but it is important to understand how they work when inspecting the block
+space. 
+
+```go
+func Example(arg int) (res *int) {
+	var x int = arg + 1
+	return &x
+}
+```
+
+The above code when executed will first produce the following block:
+
+```
+BlockValue{
+    ...
+    Source: <*FuncDecl node>,
+    Values: [
+        {T: nil, V: nil},                      // 'arg' parameter
+        {T: nil, V: nil},                      // 'res' result
+        {T: HeapItemType{},
+	 V: &HeapItemValue{{T: nil, V: nil}},  // 'x' variable
+    ],
+    ...
+}
+```
+
+In the above example the third slot for `x` is not initialized to the zero
+value of a typed value slot, but rather it is prefilled with a heap item. 
+
+Variables declared in a closure or passed by reference are first discovered and
+marked as such from the preprocessor, and NewBlock() will prepopulate these
+slots with `*HeapItemValues`.  When a `*HeapItemValue` is present in a block
+slot it is not written over but instead the value is written into the heap
+item's slot. 
+
+When the example code executes `return &x` instead of returning a
+`PointerValue` with `.Base` set to the `BlockValue` and `.Index` of 2, it sets
+`.Base` to the `*HeapItemValue` with `.Index` of 0 since a heap item only
+contains one slot. The pointer's `.TV` is set to the single slot of of the heap
+item. This way the when the pointer is used later in another transaction there
+is no need to load the whole original block value, but rather a single heap
+item object. If `Example()` returned only `x` rather than a pointer `&x` it
+would not be initialized with a heap item for the slot.
+
+```go
+func Example2(arg int) (res func()) {
+	var x int = arg + 1
+	return func() {
+		println(x)
+	}
+}
+```
+
+The above example illustrates another use for heap items. Here we don't
+reference `x`, but it is captured by the anonymous function literal (closure).
+At runtime the closure `*FuncValue` captures the heap item object such that the
+closure does not depend on the block at all.
+
+Variables declared at the package (global) level may also be referred to by
+pointer in anonymous functions. In the future we will allow limited upgrading
+features for mutable realm packages (e.g. the ability to add new functions or
+replace or "swizzle" existing ones), so all package level declared variables
+are wrapped in heap item objects.
+
+Since all global package values referenced closures can be captured as heap
+objects, the execution and persistence of a closure function value does not
+depend on any parent blocks. (Omitted here is how references to package
+level declared functions and methods are replaced by a selector expression
+on the package itself; otherwise closures would still in general depend
+on their parent blocks).
+
+## Loopvars
+
+Go1.22 introduced loopvars to reduce programmer errors. Gno uses 
+heap items to implement loopvars.
+
+```go
+for _, v := range values {
+    saveClosure(func() {
+        fmt.Println(v)
+    })
+}
+```
+
+The Gno VM does something special for loopvars. Instead of assigning the new
+value `v` to the same slot, or even the same heap item object's slot, it
+replaces the existing heap item object with a new one. This allows the closure
+to capture a new heap item object with every iteration. This is called 
+a heap definition.
+
+The behavior is applied for implicit loops with `goto` statements. The
+preprocessor first identifies all such variable definitions whether explicit in
+range statements or implicit via `goto` statements that are captured by
+closures or passed by pointer reference, and directs the VM to execute the
+define statement by replacing the existing heap item object with a new one.