@unyt/datex 0.0.13 → 0.0.15

package/esm/dif/dif-handler.js

@@ -1,3 +1,7 @@
+/**
+ * @module DIF Handler
+ * Represents the main interface for interacting with the DATEX Core via DIF from JavaScript.
+ */
 var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
@@ -10,13 +14,68 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 var _DIFHandler_runtime, _DIFHandler_handle, _DIFHandler_transceiver_id, _DIFHandler_cache, _DIFHandler_proxyMapping, _DIFHandler_referenceMetadata, _DIFHandler_observers, _DIFHandler_type_registry;
-import { Ref } from "../refs/ref.js";
 import { Endpoint } from "../lib/special-core-types/endpoint.js";
-import { DIFSharedValueMutability, DIFTypeDefinitionKind, DIFUpdateKind, } from "./definitions.js";
-import { CoreTypeAddress, CoreTypeAddressRanges } from "./core.js";
+import { Range } from "../lib/special-core-types/range.js";
+import { DIFUpdateKind, } from "./types/mod.js";
+import { CoreLibTypeId } from "./core.js";
 import { TypeRegistry } from "./type-registry.js";
-import { panic } from "../utils/exceptions.js";
+import { panic, unimplemented, unreachable } from "../utils/exceptions.js";
+import { isJsUndefined, JS_UNDEFINED } from "../lib/special-core-types/undefined.js";
+import { SharedContainerMutability } from "../shared-container/base-shared-container.js";
+import { BaseSharedContainer } from "../shared-container/mod.js";
+import { DIFSharedContainerOwnership } from "./types/type.js";
+import { splitPointerAddressWithOwnership } from "../shared-container/mod.js";
+import { combinePointerAddressWithOwnership } from "../shared-container/mod.js";
+import { appendEntry, clear, deleteEntry, DIFPropertyKind, listSplice, replace, setEntry } from "./update.js";
+import { createDIFProperty } from "./update.js";
 import { JsLibTypeAddress } from "./js-lib.js";
+import { isJsMapTypeDefinition } from "../lib/mod.js";
+import { OwnedSharedContainer } from "../shared-container/owned.js";
+import { EMPTY_TAG, Tagged } from "../lib/special-core-types/tagged.js";
+import { ibig } from "./helpers/mod.js";
+/**
+ * Some DIF methods may return an optional ValueContainer, so does the execute_sync, when no result is returned.
+ * DIF must differentiate between null and no result, so we wrap DIFOptionalValueContainer.
+ * @param value - The DIFOptionalValueContainer to collapse.
+ * @returns The contained DIFValueContainer if present, or undefined if the value is not present.
+ */
+function collapseDIFOption(value) {
+    if (value === null) {
+        return undefined;
+    }
+    else {
+        if (Array.isArray(value) && value.length === 1) {
+            return value[0];
+        }
+        else {
+            throw new Error("Invalid DIFOptionalValueContainer format: expected an array of length 1 or null");
+        }
+    }
+}
+/**
+ * Converts special float string representations ("nan", "infinity", "-infinity") to the JS values NaN, Infinity and -Infinity respectively.
+ * @param value - The string representation of the float value.
+ * @returns The corresponding JS number value for the special float representation.
+ * @throws If the input value is not a valid special float representation.
+ */
+function specialDIFFloatToNumber(value) {
+    if (!isSpecialDIFFloatString(value)) {
+        throw new Error(`Expected a special float string ("nan", "infinity", "-infinity"), got ${value}`);
+    }
+    if (value === "nan") {
+        return NaN;
+    }
+    else if (value === "infinity") {
+        return Infinity;
+    }
+    else if (value === "-infinity") {
+        return -Infinity;
+    }
+    unreachable(`Invalid special float string: ${value}`);
+}
+function isSpecialDIFFloatString(value) {
+    return ["nan", "infinity", "-infinity"].includes(value);
+}
 export const IS_PROXY_ACCESS = Symbol("IS_PROXY_ACCESS");
 /**
  * The DIFHandler class provides methods to interact with the DATEX Core DIF runtime,
@@ -33,7 +92,7 @@ export class DIFHandler {
     }
     /**
      * Internal property
-     * @returns The RuntimeDIFHandle instance.
+     * @returns The {@link JSDIFInterface} instance.
      */
     get _handle() {
         return __classPrivateFieldGet(this, _DIFHandler_handle, "f");
@@ -51,7 +110,6 @@ export class DIFHandler {
     /**
      * Creates a new DIFHandler instance.
      * @param runtime - The JSRuntime instance for executing Datex scripts.
-     * @param pointerCache - The PointerCache instance for managing object pointers. If not provided, a new PointerCache will be created.
      */
     constructor(runtime) {
         /** The JSRuntime interface for the underlying Datex Core runtime */
@@ -76,7 +134,7 @@ export class DIFHandler {
         _DIFHandler_observers.set(this, new Map());
         _DIFHandler_type_registry.set(this, new TypeRegistry(this));
         __classPrivateFieldSet(this, _DIFHandler_runtime, runtime, "f");
-        __classPrivateFieldSet(this, _DIFHandler_handle, runtime.dif(), "f");
+        __classPrivateFieldSet(this, _DIFHandler_handle, runtime.dif_interface(), "f");
     }
     /**
      * Executes a Datex script asynchronously and returns a Promise that resolves to a DIFContainer.
@@ -85,8 +143,8 @@ export class DIFHandler {
      * @returns A Promise that resolves to the execution result as a DIFContainer.
      * @throws If an error occurs during execution.
      */
-    executeDIF(datexScript, values = []) {
-        return __classPrivateFieldGet(this, _DIFHandler_runtime, "f").execute(datexScript, this.convertToDIFValues(values));
+    async executeDIF(datexScript, values = []) {
+        return collapseDIFOption(await __classPrivateFieldGet(this, _DIFHandler_runtime, "f").execute(datexScript, this.convertToDIFValues(values)));
     }
     /**
      * Executes a Datex script synchronously and returns the result as a DIFContainer.
@@ -96,7 +154,7 @@ export class DIFHandler {
      * @throws If an error occurs during execution.
      */
     executeSyncDIF(datexScript, values = []) {
-        return __classPrivateFieldGet(this, _DIFHandler_runtime, "f").execute_sync(datexScript, this.convertToDIFValues(values));
+        return collapseDIFOption(__classPrivateFieldGet(this, _DIFHandler_runtime, "f").execute_sync(datexScript, this.convertToDIFValues(values)));
     }
     /**
      * Creates a new shared value for the specified DIF value.
@@ -105,16 +163,23 @@ export class DIFHandler {
      * @param mutability - The mutability of the pointer.
      * @returns The created pointer address.
      */
-    createSharedValueFromDIFValue(difValueContainer, allowedType = null, mutability) {
-        return __classPrivateFieldGet(this, _DIFHandler_handle, "f").create_pointer(difValueContainer, allowedType, mutability);
+    constructSharedValue(difValueContainer, mutability = SharedContainerMutability.Mutable, allowedType = null) {
+        const baseSharedValueContainer = [
+            difValueContainer,
+            mutability,
+        ];
+        if (allowedType) {
+            baseSharedValueContainer[2] = allowedType;
+        }
+        return __classPrivateFieldGet(this, _DIFHandler_handle, "f").create_pointer(baseSharedValueContainer);
     }
     /**
      * Updates the DIF value at the specified address.
      * @param address - The address of the DIF value to update.
-     * @param dif - The DIFUpdate object containing the update information.
+     * @param update_data - The DIFUpdate object containing the update information.
      */
-    updateReference(address, dif) {
-        __classPrivateFieldGet(this, _DIFHandler_handle, "f").update(__classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f"), address, dif);
+    updateSharedValue(address, update_data) {
+        return __classPrivateFieldGet(this, _DIFHandler_handle, "f").update(address, [__classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f"), ...update_data]);
     }
     /**
      * Registers an observer callback for changes to the DIF value at the specified address
@@ -127,8 +192,8 @@ export class DIFHandler {
      * @returns An observer ID that can be used to unregister the observer.
      * @throws If the pointer is final.
      */
-    observePointerBindDirect(address, callback, options = { relay_own_updates: false }) {
-        return __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif().observe_pointer(__classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f"), address, options, callback);
+    observeSharedValueBindDirect(address, callback, options = { relay_own_updates: false }) {
+        return __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif_interface().observe_pointer(__classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f"), address, options, callback);
     }
     /**
      * Updates the observe options for a registered observer.
@@ -137,7 +202,7 @@ export class DIFHandler {
      * @param options - The new observe options to apply.
      */
     updateObserverOptions(address, observerId, options) {
-        __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif().update_observer_options(address, observerId, options);
+        __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif_interface().update_observer_options(address, observerId, options);
     }
     /**
      * Enables propagation of own updates for a registered observer.
@@ -166,8 +231,8 @@ export class DIFHandler {
      * @param address - The address of the DIF value being observed.
      * @param observerId - The observer ID returned by the observePointer method.
      */
-    unobserveReferenceBindDirect(address, observerId) {
-        __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif().unobserve_pointer(address, observerId);
+    unobserveSharedValueBindDirect(address, observerId) {
+        __classPrivateFieldGet(this, _DIFHandler_runtime, "f").dif_interface().unobserve_pointer(address, observerId);
     }
     /**
      * Registers a local observer callback for changes to the DIF value at the specified address.
@@ -184,7 +249,7 @@ export class DIFHandler {
         let cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address);
         if (!cached) {
             // first resolve the pointer to make sure it's loaded in the cache
-            this.resolvePointerAddressSync(address);
+            this.resolvePointerAddress(DIFSharedContainerOwnership.Immutable, address);
             cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address);
         }
         // make sure the pointer is not final (no observer)
@@ -235,131 +300,176 @@ export class DIFHandler {
      * @param value
      */
     resolveDIFValue(value) {
-        let type = value.type;
-        let convertMapToJSObject = false;
-        // no type specified since it is inferable from the value
-        if (type === undefined) {
-            if (Array.isArray(value.value)) {
-                // [[x,y,]] -> map
-                if (Array.isArray(value.value[0])) {
-                    type = CoreTypeAddress.map;
-                } // [x,y] or [] -> list
-                else {
-                    type = CoreTypeAddress.list;
-                }
+        // direct interpretation of trivial types without type annotation
+        if (value === null) {
+            return null;
+        }
+        else if (isJsUndefined(value)) {
+            return undefined;
+        }
+        else if (typeof value === "string") {
+            return value;
+        }
+        else if (typeof value === "boolean") {
+            return value;
+        }
+        else if (typeof value === "number") {
+            return value;
+        }
+        // custom interpretation means
+        if (!Array.isArray(value) || value.length < 2 || value.length > 3) {
+            console.log("value", value);
+            throw new Error("Invalid DIFValue format: expected an array for non-primitive types");
+        }
+        const [type, core, definition] = value;
+        let val = null;
+        if (type === CoreLibTypeId.null) {
+            if (core !== null) {
+                throw new Error("Expected null value for null type");
+            }
+            val = null;
+        }
+        else if (type === CoreLibTypeId.boolean) {
+            if (typeof core !== "boolean") {
+                throw new Error("Expected boolean value for boolean type");
+            }
+            val = core;
+        }
+        else if ([
+            CoreLibTypeId.integer_i8,
+            CoreLibTypeId.integer_i16,
+            CoreLibTypeId.integer_i32,
+            CoreLibTypeId.integer_u8,
+            CoreLibTypeId.integer_u16,
+            CoreLibTypeId.integer_u32,
+            CoreLibTypeId.integer_i64,
+        ].includes(type)) {
+            if (typeof core !== "number") {
+                throw new Error("Expected number value for integer type");
+            }
+            val = core;
+        }
+        else if (type === CoreLibTypeId.integer) {
+            if (typeof core === "string") {
+                val = parseInt(core, 10);
+            }
+            else
+                throw new Error("Expected number value for integer type");
+        }
+        else if ([
+            CoreLibTypeId.integer_i128,
+            CoreLibTypeId.integer_u64,
+            CoreLibTypeId.integer_u128,
+            CoreLibTypeId.integer_ibig,
+        ].includes(type)) {
+            if (typeof core !== "string" && typeof core !== "number") {
+                throw new Error("Expected string or number value for big integer type");
+            }
+            val = BigInt(core);
+        }
+        else if ([
+            CoreLibTypeId.decimal_dbig,
+            CoreLibTypeId.decimal, // FIXME rational notation 3/4
+        ].includes(type)) {
+            if (typeof core !== "string") {
+                throw new Error("Expected string value for decimal big type" + typeof core + " " + JSON.stringify(core));
+            }
+            if (isSpecialDIFFloatString(core)) {
+                val = specialDIFFloatToNumber(core);
+            } // FIXME this is a temporary solution until we have a proper decimal implementation
+            else if (core.includes("/")) {
+                const [numerator, denominator] = core.split("/").map((part) => part.trim());
+                val = parseFloat(numerator) / parseFloat(denominator);
+            }
+            else if (core.includes(".")) {
+                val = parseFloat(core);
             }
-            else if (typeof value.value === "object" && value.value !== null) {
-                type = CoreTypeAddress.map;
-                convertMapToJSObject = true;
-            } // primitive JS value, no type specified
             else {
-                return value.value;
-            }
-        }
-        // null, boolean and text types values are just returned as is
-        if (type === CoreTypeAddress.boolean ||
-            type == CoreTypeAddress.text ||
-            type === CoreTypeAddress.null) {
-            return value.value;
-        } // small integers are interpreted as JS numbers
-        else if (typeof type === "string" && (type == CoreTypeAddress.integer ||
-            this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.small_signed_integers) ||
-            this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.small_unsigned_integers))) {
-            return Number(value.value);
-        } // big integers are interpreted as JS BigInt
-        else if (typeof type === "string" && (this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.big_signed_integers))) {
-            return BigInt(value.value);
-        } // decimal types are interpreted as JS numbers
-        else if (typeof type === "string" &&
-            this.isPointerAddressInAdresses(type, CoreTypeAddressRanges.decimals)) {
-            return Number(value.value);
-        } // endpoint types are resolved to Endpoint instances
-        else if (type === CoreTypeAddress.endpoint) {
-            return Endpoint.get(value.value);
-        }
-        else if (type === CoreTypeAddress.list) {
-            return this.promiseAllOrSync(value.value.map((v) => this.resolveDIFValueContainer(v)));
-        } // map types are resolved from a DIFObject (aka JS Map) or Array of key-value pairs to a JS object
-        else if (type === CoreTypeAddress.map) {
-            if (Array.isArray(value.value)) {
-                const resolvedMap = new Map();
-                for (const [key, val] of value.value) {
-                    resolvedMap.set(this.resolveDIFValueContainer(key), this.resolveDIFValueContainer(val));
-                }
-                // TODO: map promises
-                return resolvedMap;
+                throw new Error("Expected a valid decimal string for decimal big type");
+            }
+        }
+        else if ([
+            CoreLibTypeId.decimal_f32,
+            CoreLibTypeId.decimal_f64,
+        ].includes(type)) {
+            if (typeof core === "string") {
+                val = specialDIFFloatToNumber(core);
+            }
+            else if (typeof core === "number") {
+                val = core;
             }
             else {
-                if (convertMapToJSObject) {
-                    const resolvedObj = {};
-                    for (const [key, val] of Object.entries(value.value)) {
-                        resolvedObj[key] = this.resolveDIFValueContainer(val);
-                    }
-                    return resolvedObj;
-                }
-                else {
-                    const resolvedMap = new Map();
-                    for (const [key, val] of Object.entries(value.value)) {
-                        resolvedMap.set(key, this.resolveDIFValueContainer(val));
-                    }
-                    return resolvedMap;
-                }
+                throw new Error("Expected number value for decimal type");
             }
-        } // impl types
-        else if (typeof type == "object" &&
-            type.kind === DIFTypeDefinitionKind.ImplType) {
-            // undefined (null + js.undefined)
-            if (type.def[0] === CoreTypeAddress.null &&
-                type.def[1].length === 1 &&
-                type.def[1][0] == JsLibTypeAddress.undefined) {
-                return undefined;
+        }
+        else if (type === CoreLibTypeId.text) {
+            if (typeof core !== "string") {
+                throw new Error("Expected string value for text type");
             }
+            val = core;
         }
-        // custom types not implemented yet
-        throw new Error("Custom type resolution not implemented yet");
-    }
-    /**
-     * Converts an array of Promises or resolved values to either a Promise of an array of resolved values,
-     * or an array of resolved values if all values are already resolved.
-     */
-    promiseAllOrSync(values) {
-        if (values.some((v) => v instanceof Promise)) {
-            return Promise.all(values);
+        else if (type === CoreLibTypeId.endpoint) {
+            if (typeof core !== "string") {
+                throw new Error("Expected string value for endpoint type");
+            }
+            val = Endpoint.get(core);
         }
-        else {
-            return values;
+        else if (type === CoreLibTypeId.Range) {
+            if (!Array.isArray(core) || core.length !== 2) {
+                throw new Error("Expected array of length 2 for range type");
+            }
+            const [start, end] = core;
+            const res = [
+                this.resolveDIFValueContainer(start),
+                this.resolveDIFValueContainer(end),
+            ];
+            // FIXME fix range
+            val = new Range(res[0], res[1]);
+        }
+        else if (type === CoreLibTypeId.List) {
+            if (!Array.isArray(core)) {
+                throw new Error("Expected array value for list type");
+            }
+            val = core.map((v) => this.resolveDIFValueContainer(v));
         }
-    }
-    /**
-     * Converts an object with values that may be Promises to either a Promise of an object with resolved values,
-     * or an object with resolved values if all values are already resolved.
-     */
-    promiseFromObjectOrSync(values) {
-        const valueArray = Object.values(values);
-        if (valueArray.some((v) => v instanceof Promise)) {
-            return Promise.all(valueArray).then((resolvedValues) => {
-                const resolvedObj = {};
-                let i = 0;
-                for (const key of Object.keys(values)) {
-                    resolvedObj[key] = resolvedValues[i++];
+        else if (type === CoreLibTypeId.Map) {
+            if (Array.isArray(core)) {
+                const map = new Map();
+                for (const [key, value] of core) {
+                    map.set(this.resolveDIFValueContainer(key), this.resolveDIFValueContainer(value));
                 }
-                return resolvedObj;
-            });
-        }
-        else {
-            return values;
-        }
-    }
-    /**
-     * Maps a value or Promise of a value to another value or Promise of a value using the provided onfulfilled function.
-     */
-    mapPromise(value, onfulfilled) {
-        if (value instanceof Promise) {
-            return value.then(onfulfilled);
+                val = map;
+            }
+            else if (typeof core === "object" && core !== null) {
+                const obj = {};
+                for (const [key, value] of Object.entries(core)) {
+                    obj[key] = this.resolveDIFValueContainer(value);
+                }
+                val = obj;
+                if (definition && isJsMapTypeDefinition(definition)) {
+                    val = new Map(Object.entries(obj));
+                }
+            }
+            else {
+                throw new Error("Expected array of key-value pairs or object for map type");
+            }
         }
-        else {
-            return onfulfilled(value);
+        // for tagged type definition, wrap in Tagged
+        if (definition && typeof definition === "object" && "tagged_type" in definition) {
+            const [tag, innerType] = definition.tagged_type;
+            // special case: empty tag
+            if (val === null && innerType === CoreLibTypeId.Unit) {
+                val = new Tagged(tag, EMPTY_TAG);
+            }
+            else {
+                // TODO: handle other innerTypes if not default type
+                val = new Tagged(tag, val);
+            }
         }
+        // FIXME custom type resolution not implemented yet, just return the core value for now
+        return val;
+        // custom types not implemented yet
+        // throw new Error("Custom type resolution not implemented yet");
     }
     /**
      * Resolves a DIFValueContainer (either a DIFValue or a pointer address) to its corresponding JS value.
@@ -369,41 +479,27 @@ export class DIFHandler {
      * @returns The resolved value as type T, or a Promise that resolves to type T.
      */
     resolveDIFValueContainer(value) {
-        if (typeof value !== "string") {
-            return this.resolveDIFValue(value);
+        if (typeof value === "object" && value !== null && !Array.isArray(value) && "$" in value) {
+            return this.resolvePointerAddress(...splitPointerAddressWithOwnership(value.$));
         }
         else {
-            return this.resolvePointerAddress(value);
-        }
-    }
-    /**
-     * Synchronous version of resolveDIFValueContainer.
-     * This method can only be used if the value only contains pointer addresses that are already loaded in memory -
-     * otherwise, use the asynchronous `resolveDIFValueContainer` method instead.
-     * @param value - The DIFValueContainer to resolve.
-     * @returns The resolved value as type T.
-     * @throws If the resolution would require asynchronous operations.
-     */
-    resolveDIFValueContainerSync(value) {
-        const result = this.resolveDIFValueContainer(value);
-        if (result instanceof Promise) {
-            throw new Error("resolveDIFValueContainerSync cannot return a Promise. Use resolveDIFValueContainer() instead.");
+            return this.resolveDIFValue(value);
         }
-        return result;
     }
     /**
      * Resolves a DIFProperty to its corresponding JS value.
      */
-    resolveDIFPropertySync(property) {
-        if (property.kind === "text") {
-            return property.value;
+    resolveDIFProperty(property) {
+        if (typeof property === "number") {
+            return property;
         }
-        else if (property.kind === "index") {
-            return property.value;
+        if (typeof property === "string") {
+            return property;
         }
-        else {
-            return this.resolveDIFValueContainerSync(property.value);
+        if (typeof property === "object" && property !== null && !Array.isArray(property) && "value" in property) {
+            return this.resolveDIFValueContainer(property.value);
         }
+        throw new Error("Invalid DIFProperty format");
     }
     /**
      * Resolves a pointer address to its corresponding JS value.
@@ -412,43 +508,33 @@ export class DIFHandler {
      * @param address - The pointer address to resolve.
      * @returns The resolved value as type T, or a Promise that resolves to type T.
      */
-    resolvePointerAddress(address) {
+    resolvePointerAddress(ownership, address) {
+        const addressWithOwnership = combinePointerAddressWithOwnership(address, ownership);
         // check cache first
-        const cached = this.getCachedReference(address);
-        if (cached) {
-            return cached;
+        const cached = this.getCachedStateForSharedContainer(address, ownership);
+        if (cached === "insufficient_ownership") {
+            // try to resolve with with upgraded owership if possible
+            if (!__classPrivateFieldGet(this, _DIFHandler_handle, "f").has_address_with_ownership(addressWithOwnership)) {
+                throw new Error(`Address ${address} not found in runtime with ownership ${ownership} or higher`);
+            }
+            __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address).maxOwnership = ownership;
+            const upgraded = this.getCachedStateForSharedContainer(address, ownership);
+            if (typeof upgraded === "string") {
+                unreachable(`Ownership assertion passed but cache still returns ${upgraded}`);
+            }
+            return upgraded;
         }
-        // if not in cache, resolve from runtime
-        const reference = __classPrivateFieldGet(this, _DIFHandler_handle, "f").resolve_pointer_address(address);
-        return this.mapPromise(reference, (reference) => {
-            const value = this.resolveDIFValueContainer(reference.value);
-            return this.mapPromise(value, (v) => {
-                // init pointer
-                this.initReference(address, v, reference.mut, reference.allowed_type);
-                return v;
-            });
-        });
-    }
-    /**
-     * Resolves a pointer address to its corresponding JS value synchronously.
-     * If the pointer address is not yet loaded in memory, it returns a Promise that resolves to the value.
-     * Otherwise, it returns the resolved value directly.
-     * @param address - The pointer address to resolve.
-     * @returns The resolved value as type T, or a Promise that resolves to type T.
-     * @throws If the resolution would require asynchronous operations.
-     */
-    resolvePointerAddressSync(address) {
-        // check cache first
-        const cached = this.getCachedReference(address);
-        if (cached) {
+        else if (cached === "not_cached") {
+            // if not in cache, resolve from runtime
+            const base = __classPrivateFieldGet(this, _DIFHandler_handle, "f").resolve_pointer_address(addressWithOwnership);
+            const value = this.resolveDIFValueContainer(base[0]);
+            // init pointer
+            return this.initSharedValue(address, value, base[1], ownership, base[2]);
+        }
+        else {
+            // falltrough case, already in cache with correct ownership
             return cached;
         }
-        // if not in cache, resolve from runtime
-        const entry = __classPrivateFieldGet(this, _DIFHandler_handle, "f")
-            .resolve_pointer_address_sync(address);
-        const value = this.resolveDIFValueContainerSync(entry.value);
-        this.initReference(address, value, entry.mut, entry.allowed_type);
-        return value;
     }
     /**
      * Retrieves the original value from a proxy value if available
@@ -489,25 +575,28 @@ export class DIFHandler {
         return values?.map((value) => this.convertJSValueToDIFValueContainer(value)) ||
             null;
     }
-    /**
-     * Returns true if the given address is within the specified address range.
-     */
-    isPointerAddressInAdresses(address, range) {
-        return range.has(address);
-    }
     /**
      * Initializes a reference with the given value and mutability, by
      * adding a proxy wrapper if necessary, and setting up observation and caching on the JS side.
      */
-    initReference(pointerAddress, value, mutability, allowedType = null) {
-        let wrappedValue = this.wrapJSValue(value, pointerAddress, allowedType);
+    initSharedValue(pointerAddress, value, mutability, ownership, allowedType) {
+        let wrappedValue = this.wrapJSValue(value, pointerAddress, mutability, allowedType);
         let typeBinding = null;
         let metadata = undefined;
         // bind js value (if mutable, nominal type)
-        const bindJSValue = mutability !== DIFSharedValueMutability.Immutable &&
-            typeof allowedType == "string";
-        if (bindJSValue && !(wrappedValue instanceof Ref)) {
-            typeBinding = this.type_registry.getTypeBinding(allowedType);
+        const implType = typeof allowedType === "object" && allowedType !== null && "impl_type" in allowedType
+            ? allowedType.impl_type
+            : null;
+        if (implType && implType[0] === CoreLibTypeId.Map) {
+            // FIXME can we make this cleaner, or do we need it more generic?
+            allowedType = implType[0];
+        }
+        const bindJSValue = mutability !== SharedContainerMutability.Immutable &&
+            (typeof allowedType === "string" || typeof allowedType === "number");
+        if (bindJSValue && !(wrappedValue instanceof BaseSharedContainer)) {
+            typeBinding = typeof allowedType == "number"
+                ? this.type_registry.getTypeBindingByCoreLibTypeId(allowedType)
+                : this.type_registry.getTypeBinding(allowedType); // TS Bug
             if (typeBinding) {
                 const { value, metadata: newMetadata } = typeBinding
                     .bindValue(wrappedValue, pointerAddress);
@@ -517,12 +606,13 @@ export class DIFHandler {
         }
         // if not immutable, observe to keep the pointer 'live' and receive updates
         let observerId = null;
-        if (mutability !== DIFSharedValueMutability.Immutable) {
-            observerId = this.observePointerBindDirect(pointerAddress, (update) => {
+        if (mutability !== SharedContainerMutability.Immutable) {
+            observerId = this.observeSharedValueBindDirect(pointerAddress, (update) => {
+                const [sourceId, ...data] = update;
                 // if source_id is not own transceiver id, handle pointer update
-                if (update.source_id !== __classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f")) {
+                if (sourceId !== __classPrivateFieldGet(this, _DIFHandler_transceiver_id, "f")) {
                     try {
-                        this.handlePointerUpdate(pointerAddress, wrappedValue, update.data, typeBinding);
+                        this.handlePointerUpdate(pointerAddress, wrappedValue, data, typeBinding);
                     }
                     catch (e) {
                         console.error("Error handling pointer update", e);
@@ -534,7 +624,7 @@ export class DIFHandler {
                 if (observers) {
                     for (const cb of observers.values()) {
                         try {
-                            cb(update.data);
+                            cb(data);
                         }
                         catch (e) {
                             console.error("Error in pointer observer callback", e);
@@ -544,7 +634,7 @@ export class DIFHandler {
                 console.debug("Pointer update received", update);
             });
         }
-        this.cacheWrappedReferenceValue(pointerAddress, value, wrappedValue, observerId, metadata);
+        this.cacheWrappedReferenceValue(pointerAddress, ownership, value, wrappedValue, observerId, metadata);
         // set up observers
         return wrappedValue;
     }
@@ -555,8 +645,8 @@ export class DIFHandler {
         const deref = cached.value.deref();
         if (!deref)
             return false;
-        if (deref instanceof Ref && update.kind === DIFUpdateKind.Replace) {
-            deref.updateValueSilently(this.resolveDIFValueContainerSync(update.value));
+        if (deref instanceof BaseSharedContainer && update[0] === DIFUpdateKind.Replace) {
+            deref.updateValueSilently(this.resolveDIFValueContainer(update[1]));
         }
         // handle generic updates for values (depending on type interface definition)
         if (typeBinding) {
@@ -568,11 +658,12 @@ export class DIFHandler {
      * Caches the given reference value with the given address in the JS side cache.
      * The reference must already be wrapped if necessary.
      */
-    cacheWrappedReferenceValue(address, originalValue, proxiedValue, observerId, metadata = {}) {
+    cacheWrappedReferenceValue(address, ownership, originalValue, proxiedValue, observerId, metadata = {}) {
         const isProxifiedValue = this.isWeakKey(originalValue) &&
             originalValue !== proxiedValue;
         __classPrivateFieldGet(this, _DIFHandler_cache, "f").set(address, {
             value: new WeakRef(proxiedValue),
+            maxOwnership: ownership,
             originalValue: isProxifiedValue ? originalValue : null,
             observerId,
         });
@@ -598,20 +689,33 @@ export class DIFHandler {
             __classPrivateFieldGet(this, _DIFHandler_observers, "f").delete(address);
             // if observer is active, unregister it
             if (observerId !== null) {
-                this.unobserveReferenceBindDirect(address, observerId);
+                this.unobserveSharedValueBindDirect(address, observerId);
             }
         });
         finalizationRegistry.register(proxiedValue, address);
     }
-    getCachedReference(address) {
+    getCachedStateForSharedContainer(address, ownership) {
+        if (!__classPrivateFieldGet(this, _DIFHandler_cache, "f").has(address)) {
+            return "not_cached";
+        }
         const cached = __classPrivateFieldGet(this, _DIFHandler_cache, "f").get(address);
-        if (cached) {
-            const deref = cached.value.deref();
-            if (deref) {
-                return deref;
-            }
+        const deref = cached.value.deref();
+        if (!deref) {
+            throw new Error(`Cached reference for address ${address} is not dereferenceable`);
+        }
+        if (
+        // owership mismatch
+        (ownership === DIFSharedContainerOwnership.Owned &&
+            cached.maxOwnership !== DIFSharedContainerOwnership.Owned) || (cached.maxOwnership === DIFSharedContainerOwnership.Immutable &&
+            ownership === DIFSharedContainerOwnership.Mutable)) {
+            return "insufficient_ownership";
+        }
+        if (deref instanceof BaseSharedContainer) {
+            return deref.withOwnership(ownership);
+        }
+        else {
+            return deref;
         }
-        return undefined;
     }
     /**
      * Creates a new reference containg the given JS value.
@@ -619,19 +723,24 @@ export class DIFHandler {
      * but also propagates changes between JS and the DATEX runtime.
      * If a reference for the given value already exists, an error is thrown.
      */
-    createTransparentReference(value, allowedType = null, mutability = DIFSharedValueMutability.Mutable) {
-        // if already bound to a reference, return the existing reference proxy (or the value itself)
+    createSharedValueFromJSValue(value, allowedType = null, mutability = SharedContainerMutability.Mutable) {
         const pointerAddress = this.getPointerAddressForValue(value);
         if (pointerAddress) {
             throw new Error(`Value is already bound to a reference ($${pointerAddress}). Cannot create a new reference for the same value.`);
         }
         const difValue = this.convertJSValueToDIFValueContainer(value);
-        const ptrAddress = this.createSharedValueFromDIFValue(difValue, allowedType, mutability);
+        const ptrAddress = this.constructSharedValue(difValue, mutability, allowedType);
         // get inferred allowed type from pointer if not explicitly set
         if (!allowedType) {
-            allowedType = __classPrivateFieldGet(this, _DIFHandler_handle, "f").resolve_pointer_address_sync(ptrAddress).allowed_type;
+            allowedType = __classPrivateFieldGet(this, _DIFHandler_handle, "f").resolve_pointer_address(ptrAddress)[2];
+        }
+        const base = this.initSharedValue(ptrAddress, value, mutability, DIFSharedContainerOwnership.Owned, allowedType);
+        if (base instanceof BaseSharedContainer) {
+            return new OwnedSharedContainer(base);
+        }
+        else {
+            return base;
         }
-        return this.initReference(ptrAddress, value, mutability, allowedType);
     }
     isPrimitiveValue(value) {
         return value === null || value === undefined ||
@@ -647,17 +756,17 @@ export class DIFHandler {
     /**
      * Wraps a given JS value in a Ref proxy if necessary.
      */
-    wrapJSValue(value, pointerAddress, _type = null) {
+    wrapJSValue(value, pointerAddress, mutability, _type = null) {
         // primitive values are always wrapped in a Ref proxy
         if (this.isWeakKey(value)) {
             return value;
         }
         else {
-            return new Ref(value, pointerAddress, this);
+            return new BaseSharedContainer(value, pointerAddress, mutability, this);
         }
     }
-    isRef(value) {
-        return value instanceof Ref;
+    isBaseSharedContainer(value) {
+        return value instanceof BaseSharedContainer;
     }
     wrapJSObjectInProxy(value) {
         // deno-lint-ignore no-this-alias
@@ -665,14 +774,14 @@ export class DIFHandler {
         return new Proxy(value, {
             get(target, prop, receiver) {
                 const val = Reflect.get(target, prop, receiver);
-                if (val && typeof val === "object" && !self.isRef(val)) {
+                if (val && typeof val === "object" && !self.isBaseSharedContainer(val)) {
                     return self.wrapJSObjectInProxy(val);
                 }
                 return val;
             },
             set(target, prop, newValue, receiver) {
                 const oldValue = Reflect.get(target, prop, receiver);
-                if (!self.isRef(oldValue)) {
+                if (!self.isBaseSharedContainer(oldValue)) {
                     throw new Error(`Cannot modify non-Ref property "${String(prop)}"`);
                 }
                 oldValue.value = newValue;
@@ -712,92 +821,96 @@ export class DIFHandler {
             __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").get(__classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").get(value)?.deref()) ??
             null);
     }
-    isReference(value) {
-        return __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").has(value) ||
-            __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").has(value);
-    }
-    getReferenceProxy(value) {
-        const reference = __classPrivateFieldGet(this, _DIFHandler_referenceMetadata, "f").get(value);
-        if (reference) {
-            return value;
-        }
-        const proxyRef = __classPrivateFieldGet(this, _DIFHandler_proxyMapping, "f").get(value);
-        if (proxyRef) {
-            const deref = proxyRef.deref();
-            if (deref) {
-                return deref;
-            }
-            else {
-                panic("Reference proxy has been garbage collected");
-            }
-        }
-        else {
-            return null;
-        }
-    }
+    // FIXME do we need these two methods still?
+    // public isReference(value: object): boolean {
+    //     return this.#referenceMetadata.has(value as CachedSharedContainer) ||
+    //         this.#proxyMapping.has(value);
+    // }
+    // public getReferenceProxy<T>(value: CachedSharedContainer<T>): T | null {
+    //     const reference = this.#referenceMetadata.get(value);
+    //     if (reference) {
+    //         return value;
+    //     }
+    //     const proxyRef = this.#proxyMapping.get(value);
+    //     if (proxyRef) {
+    //         const deref = proxyRef.deref();
+    //         if (deref) {
+    //             return deref as T;
+    //         } else {
+    //             panic("Reference proxy has been garbage collected");
+    //         }
+    //     } else {
+    //         return null;
+    //     }
+    // }
     /**
      * Converts a given JS value to its DIFValueContainer representation.
      * This method can be called statically or with an instance to use the instance's DIFHandler context.
      * NOTE: When called statically, there is no cache for already registered references, meaning that new references will be created
      * for the same object each time this method is called.
      */
-    static convertJSValueToDIFValueContainer(value, difHandlerInstance) {
+    static convertJSValueToDIFValueContainer(value, difHandlerInstance, forceExplicitFormat = false) {
         // if the value is a registered reference, return its address
         const existingReference = difHandlerInstance &&
             difHandlerInstance.tryGetReferenceMetadata(value);
         if (existingReference) {
-            return existingReference.address;
+            const ownership = __classPrivateFieldGet(difHandlerInstance, _DIFHandler_cache, "f").get(existingReference.address);
+            if (!ownership) {
+                throw new Error(`Reference metadata found for address ${existingReference.address} but no ownership info in cache`);
+            }
+            // move(x) -> function (x: OwnedValue) {}
+            return { $: combinePointerAddressWithOwnership(existingReference.address, ownership.maxOwnership) };
         }
-        // assuming core values
         // TODO: handle custom types
         if (value === null) {
-            return {
-                value: null,
-            };
+            return forceExplicitFormat ? [CoreLibTypeId.null, null] : null;
         }
         else if (value === undefined) {
-            return {
-                type: {
-                    kind: DIFTypeDefinitionKind.ImplType,
-                    def: [
-                        CoreTypeAddress.null,
-                        [JsLibTypeAddress.undefined],
-                    ],
-                },
-                value: null,
-            };
+            return JS_UNDEFINED;
+        }
+        else if (typeof value === "string") {
+            return forceExplicitFormat ? [CoreLibTypeId.text, value] : value;
         }
         else if (typeof value === "boolean") {
-            return {
-                value,
-            };
+            return forceExplicitFormat ? [CoreLibTypeId.boolean, value] : value;
         }
         else if (typeof value === "number") {
-            return {
-                value,
-            };
+            return forceExplicitFormat ? [CoreLibTypeId.decimal_f64, value] : value;
         }
         else if (typeof value === "bigint") {
-            return {
-                type: CoreTypeAddress.integer_ibig,
-                value: value.toString(), // convert bigint to string for DIFValue
-            };
-        }
-        else if (typeof value === "string") {
-            return {
-                value,
-            };
+            return ibig(value);
         }
         else if (value instanceof Endpoint) {
-            return {
-                type: CoreTypeAddress.endpoint,
-                value: value.toString(),
-            };
+            return [CoreLibTypeId.endpoint, value.toString()];
+        }
+        else if (value instanceof Tagged) {
+            // special case: empty tagged value
+            if (value.value === EMPTY_TAG) {
+                return [CoreLibTypeId.null, null, {
+                        tagged_type: [value.tag, CoreLibTypeId.Unit],
+                    }];
+            }
+            const inner = this.convertJSValueToDIFValueContainer(value.value, difHandlerInstance, true);
+            if (inner instanceof Array) {
+                return [inner[0], inner[1], {
+                        tagged_type: [value.tag, inner[2] || inner[0]], // TODO: nullable type
+                    }];
+            }
+            else if (typeof inner === "object" && inner !== null) {
+                unimplemented("Support nested shared reference value in tagged value");
+            }
+            else {
+                unreachable("convertJSValueToDIFValueContainer with forceExplicitFormat should return an array or object");
+            }
+        }
+        else if (value instanceof Range) {
+            return [CoreLibTypeId.Range, [
+                    this.convertJSValueToDIFValueContainer(value.start),
+                    this.convertJSValueToDIFValueContainer(value.end),
+                ]];
         }
         else if (Array.isArray(value)) {
-            return {
-                value: value.map((v) => this.convertJSValueToDIFValueContainer(v)),
-            };
+            return [CoreLibTypeId.List, value.map((v) => this.convertJSValueToDIFValueContainer(v))];
         }
         else if (value instanceof Map) {
             const map = value
@@ -805,19 +918,16 @@ export class DIFHandler {
                 this.convertJSValueToDIFValueContainer(k),
                 this.convertJSValueToDIFValueContainer(v),
             ]).toArray();
-            return {
-                type: CoreTypeAddress.map,
-                value: map,
-            };
+            return [CoreLibTypeId.Map, map, {
+                    impl_type: [CoreLibTypeId.Map, [JsLibTypeAddress.map]],
+                }];
         }
         else if (typeof value === "object") {
             const map = {};
             for (const [key, val] of Object.entries(value)) {
                 map[key] = this.convertJSValueToDIFValueContainer(val);
             }
-            return {
-                value: map,
-            };
+            return [CoreLibTypeId.Map, map];
         }
         throw new Error("Unsupported type for conversion to DIFValue");
     }
@@ -836,13 +946,7 @@ export class DIFHandler {
     triggerSet(pointerAddress, key, value) {
         const difKey = this.convertJSValueToDIFValueContainer(key);
         const difValue = this.convertJSValueToDIFValueContainer(value);
-        const update = {
-            kind: DIFUpdateKind.Set,
-            key: { kind: "value", value: difKey },
-            value: difValue,
-        };
-        console.log("Triggering set update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, setEntry(createDIFProperty(difKey, DIFPropertyKind.ValueContainer), difValue));
     }
     /**
      * Triggers a 'set' update for the given pointer address, index and value.
@@ -852,73 +956,41 @@ export class DIFHandler {
             throw new Error("Index must be a non-negative integer");
         }
         const difValue = this.convertJSValueToDIFValueContainer(value);
-        const update = {
-            kind: DIFUpdateKind.Set,
-            key: { kind: "index", value: Number(index) },
-            value: difValue,
-        };
-        console.log("Triggering index set update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, setEntry(createDIFProperty(Number(index), DIFPropertyKind.Index), difValue));
     }
     /**
      * Triggers an 'append' update for the given pointer address and value.
      */
     triggerAppend(pointerAddress, value) {
         const difValue = this.convertJSValueToDIFValueContainer(value);
-        const update = {
-            kind: DIFUpdateKind.Append,
-            value: difValue,
-        };
-        console.log("Triggering append update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, appendEntry(difValue));
     }
     /**
      * Triggers a 'replace' update for the given pointer address and key.
      */
     triggerReplace(pointerAddress, value) {
         const difValue = this.convertJSValueToDIFValueContainer(value);
-        const update = {
-            kind: DIFUpdateKind.Replace,
-            value: difValue,
-        };
-        console.log("Triggering replace update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, replace(difValue));
     }
     /**
      * Triggers a 'delete' update for the given pointer address and key.
      */
     triggerDelete(pointerAddress, key) {
         const difKey = this.convertJSValueToDIFValueContainer(key);
-        const update = {
-            kind: DIFUpdateKind.Delete,
-            key: { kind: "value", value: difKey },
-        };
-        console.log("Triggering delete update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, deleteEntry(createDIFProperty(difKey, DIFPropertyKind.ValueContainer)));
     }
     /**
      * Triggers a 'clear' update for the given pointer address.
      */
     triggerClear(pointerAddress) {
-        const update = {
-            kind: DIFUpdateKind.Clear,
-        };
-        console.log("Triggering clear update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, clear());
     }
     /**
      * Triggers a 'list splice' update for the given pointer address.
      */
     triggerListSplice(pointerAddress, start, deleteCount, items) {
         const difItems = items.map((item) => this.convertJSValueToDIFValueContainer(item));
-        const update = {
-            kind: DIFUpdateKind.ListSplice,
-            start,
-            delete_count: deleteCount,
-            items: difItems,
-        };
-        console.log("Triggering list splice update", update);
-        this.updateReference(pointerAddress, update);
+        this.updateSharedValue(pointerAddress, listSplice(start, deleteCount, difItems));
     }
 }
 _DIFHandler_runtime = new WeakMap(), _DIFHandler_handle = new WeakMap(), _DIFHandler_transceiver_id = new WeakMap(), _DIFHandler_cache = new WeakMap(), _DIFHandler_proxyMapping = new WeakMap(), _DIFHandler_referenceMetadata = new WeakMap(), _DIFHandler_observers = new WeakMap(), _DIFHandler_type_registry = new WeakMap();