Hiperspace.Heap 2.5.18

• net10.0

  • Hiperspace (>= 2.5.18)
  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • protobuf-net.Core (>= 3.2.56)
  • System.Numerics.Tensors (>= 10.0.0)

• net8.0

  • Hiperspace (>= 2.5.18)
  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • protobuf-net.Core (>= 3.2.56)
  • System.Numerics.Tensors (>= 10.0.0)

• net9.0

  • Hiperspace (>= 2.5.18)
  • Microsoft.Bcl.HashCode (>= 6.0.0)
  • protobuf-net.Core (>= 3.2.56)
  • System.Numerics.Tensors (>= 10.0.0)

https://www.cepheis.com/hiperspace/20251303
## Overview
This release adds `NotFoundException` to distinguish *not found* from *cannot be found* conditions. and extends the functionality of `@AlternateIndex` to support multiple alternate indexes on *segments* and *aspects* that are referenced by multiple *entities*.

-----

### Not Found

Prior to this release `Get(...)` calls did not distinguish between *Not Found* and *not found because of IO error*.  To improve the handling of missing values several changes have been made:
* Additional Exception class `NotFoundException`
* `KeyRef<>` (*reference to another element*) changed to return `null` when a value cannot be found
* `RefSingle<>` (*reference to an aspect*) changed to return `null` when a value cannot be found

-----

### AlternateIndex
Alternate indexes are created automatically whenever there is a path from an *element* from another *element*, but can be added to support access from a view.  The prime example is `Edge` which is defined (*in the Hilang prelude*) as
```
"edge between nodes"
view Edge
( /* keys */
   From        : Node,
   To          : Node,
   TypeName    : String
)
{ /* values */
   Name        : String
};
```
`@AlternateIndex` enables an *element* to index the *key/value* that corresponds to the `From` key member for indexed access from a `Node.Froms` extension property

For the model
```
entity CostCentre (Id : Int32) [Costs : Cost (CostCentre = this)];
aspect Cost {CostCentre : CostCentre, Amount : Decimal};
```
with
```
entity Asset (...) {...} [Cost : Cost];
entity Project (...) {...} [Cost : Cost];
```
Concreate elements `AssetCost` and `ProjectCost` will be created indexes
`AssetCostCostCentre.Index` and `ProjectCostCostCentre.Index`

Source edit will  change the source to  
```
entity CostCentre (Id : Int32) [Costs : Cost (CostCentre = this)];
aspect Cost
{
 @AlternateIndex("AssetCost", 42)
 ,AlternateIndex("ProjectCost", 43)
 CostCentre : CostCentre, Amount : Decimal};
```
To ensure the index Id is not used for something else resultuing in an incompatible model and store.

***how does CostCentre know what (Asset/Project/ etc) the Cost is for?***
The `aspect Cost` is transformed to a `view` that is equvilent to
```
view Cost (owner : Any) {CostCentre : CostCentre, Amount : Decimal};
```
the (*C#*) hiperspace query
```
from centre in space.CostCentres
select centre.Id, (from line in centre.Costs
                   let asset = line.owner.Is<Asset>() ? Amount : 0
                   let project = line.owner.Is<Project>() ? Amount : 0
                   group line by line.CostCentre into totals
                   select new { Projects = totals.Sum(v => v.asset),
                                Assets = totals.Sum(v => v.project)})
```
Will return the total costs by type for each CostCentre

#### Inherited Index
This model defines an overall *trade* type with three different implementations for {*FI, EQ, FX*}  that have different properties for the different asset-classes.   *Trade* is referenced by *Book*,  the extension property *`Book.Trades`* returns a collection of *Trade* has a *`Book`* equal to the current *Book*.  For efficient access, and index is created for the *`Trade.Book`* that is inherited by each implementation.

The syntax `Banking.FI.Trade : Banking.Trade = Banking.Trade()` means `Banking.FI.Trade`:
* Inherits *keys / values / extensions / properties* from `Banking.Trade` (via **`:`**)
* Can be viewed as a `Banking.Trade` (via **`=`**)

```
view Banking.Trade (Id : String)
{Book : Banking.Book};
entity Banking.FI.Trade : Banking.Trade = Banking.Trade();
entity Banking.FX.Trade : Banking.Trade = Banking.Trade();
entity Banking.EQ.Trade : Banking.Trade = Banking.Trade();
entity Banking.Book (Id : String) [Trades : Banking.Trade (Book = this)];
```

Adding `%ids` to the model, with result in a source edit to a `#` id to each *element*, *key/value* and extension property, and `@AlternateIndex` property for each generated concrete index.
```
view Banking.Trade #45 (Id : String)
{@AlternateIndex("Banking.EQ.Trade", 52)
,AlternateIndex("Banking.FI.Trade", 48)
,AlternateIndex("Banking.FX.Trade", 50)
Book : Banking.Book};
entity Banking.FI.Trade : Banking.Trade = Banking.Trade() #49;
entity Banking.FX.Trade : Banking.Trade = Banking.Trade() #51;
entity Banking.EQ.Trade : Banking.Trade = Banking.Trade() #53;
entity Banking.Book #47 (Id : String #1) [Trades : Banking.Trade (Book = this) #54];
```
subsequent compilation of the model will result in the indexes using the same *Id* value when stored.  
**NB** the `#id` can be of any value, but can never to reused for a different purpose once used with a *Hiperspace*.

-----

### Source Editing
When the directive `%ids` is added to a hilang model, the source code is edited to add `#id` values to ensure that the schema can be evolved without the risk of introducing incompatible changes.

***know issue***: Source editing lacks the context of other edits to a line of `hilang` source `@AlternateIndex("Banking.EQ.Trade", 52) @AlternateIndex("Banking.FI.Trade", 48) Book : Banking.Book` will create a syntax error the next time the *schema* is compiled because `@` is the prefix for a comma-separated list of one-or-more attributes.  The code needs to be edited to change subsequent `@` to `,`