Merge remote-tracking branch 'origin/feat/orm-diffs' into refactor

sdk/js/alien-deepsignals/README.md

@@ -13,7 +13,8 @@ Core idea: wrap a data tree in a `Proxy` that lazily creates per-property signal
 - Patch stream: microtask‑batched granular mutations (paths + op) for syncing external stores / framework adapters.
 - Getter => computed: property getters become derived (readonly) signals automatically.
 - `$` accessors: TypeScript exposes `$prop` for each non‑function key plus `$` / `$length` for arrays.
-- Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids (prefers `id` / `@id` fields or auto‑generated blank IDs).
+- Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids via `@id` property.
+- `@id` property system: configurable automatic ID assignment to objects with custom generators.
 - Shallow escape hatch: wrap sub-objects with `shallow(obj)` to track only reference replacement.
 
 ## Install
@@ -46,6 +47,68 @@ state.$count!.set(5); // update via signal
 console.log(state.$count!()); // read via signal function
 ```
 
+## Configuration options
+
+`deepSignal(obj, options?)` accepts an optional configuration object:
+
+```ts
+type DeepSignalOptions = {
+    idGenerator?: (pathToObject: (string | number)[]) => string | number; // Custom ID generator function
+    addIdToObjects?: boolean; // Automatically add @id to plain objects
+};
+```
+
+### Custom ID generation
+
+Provide a custom function to generate synthetic IDs instead of auto-generated blank node IDs:
+
+```ts
+let counter = 0;
+const state = deepSignal(
+    { items: new Set() },
+    { 
+        idGenerator: () => `urn:item:${++counter}`,
+        addIdToObjects: true 
+    }
+);
+
+state.items.add({ name: "Item 1" }); // Gets @id: "urn:item:1"
+state.items.add({ name: "Item 2" }); // Gets @id: "urn:item:2"
+```
+
+### The `@id` property
+
+When `addIdToObjects: true`, plain objects automatically receive a readonly, enumerable `@id` property:
+
+```ts
+const state = deepSignal(
+    { data: {} },
+    { 
+        idGenerator: (_path) => `urn:uuid:${crypto.randomUUID()}`,
+        addIdToObjects: true 
+    }
+);
+
+state.data.user = { name: "Ada" };
+console.log(state.data.user["@id"]); // e.g., "urn:uuid:550e8400-e29b-41d4-a716-446655440000"
+
+// @id is readonly
+state.data.user["@id"] = "new-id"; // TypeError in strict mode
+
+// @id assignment emits a patch
+watch(state, ({ patches }) => {
+    // patches includes: { op: "add", path: ["data", "user", "@id"], value: "..." }
+});
+```
+
+**Key behaviors:**
+
+- `@id` is assigned **before** the object is proxied, ensuring it's available immediately
+- `@id` properties are **readonly** and **enumerable**
+- Assigning `@id` emits a patch just like any other property
+- Objects with existing `@id` properties keep their values (not overwritten)
+- Options propagate to nested objects created after initialization
+
 ## Watching patches
 
 `watch(root, cb, options?)` observes a deepSignal root and invokes your callback with microtask‑batched mutation patches plus snapshots.
@@ -113,23 +176,103 @@ Notes:
 
 ## Sets & synthetic ids
 
-Object entries inside Sets need a stable key. Priority:
+Object entries inside Sets need a stable key for patch paths. The synthetic ID resolution follows this priority:
 
-1. `entry.id`
+1. Explicit custom ID via `setSetEntrySyntheticId(entry, 'myId')` (before `add`)
-2. `entry['@id']`
+2. Existing `entry['@id']` property
-3. Custom via `setSetEntrySyntheticId(entry, 'myId')` before `add`
+3. Auto-generated blank node ID (`_bN` format)
-4. Auto `_bN` blank id
 
-Helpers:
+### Working with Sets
 
 ```ts
-import { addWithId, setSetEntrySyntheticId } from "alien-deepsignals";
+import { addWithId, setSetEntrySyntheticId } from "@ng-org/alien-deepsignals";
+
+// Option 1: Use @id from configuration
+const state = deepSignal(
+    { items: new Set() },
+    { 
+        idGenerator: (_path) => `urn:uuid:${crypto.randomUUID()}`,
+        addIdToObjects: true 
+    }
+);
+const item = { name: "Item 1" };
+state.items.add(item); // Automatically gets @id before being added
+console.log(item["@id"]); // e.g., "urn:uuid:550e8400-..."
+
+// Option 2: Manually set synthetic ID
+const obj = { value: 42 };
+setSetEntrySyntheticId(obj, "urn:custom:my-id");
+state.items.add(obj);
+
+// Option 3: Use convenience helper
+addWithId(state.items as any, { value: 99 }, "urn:item:special");
+
+// Option 4: Pre-assign @id property
+const preTagged = { "@id": "urn:explicit:123", data: "..." };
+state.items.add(preTagged); // Uses "urn:explicit:123" as synthetic ID
+```
+
+### Set entry patches and paths
+
+When objects are added to Sets, their **synthetic ID becomes part of the patch path**. This allows patches to uniquely identify which Set entry is being mutated.
+
+```ts
+const state = deepSignal(
+    { s: new Set() }, 
+    { 
+        idGenerator: () => "urn:entry:set-entry-1",
+        addIdToObjects: true 
+    }
+);
+
+watch(state, ({ patches }) => {
+    console.log(JSON.stringify(patches));
+    // [
+    //   {"path":["s","urn:entry:set-entry-1"],"op":"add","type":"object"},
+    //   {"path":["s","urn:entry:set-entry-1","@id"],"op":"add","value":"urn:entry:set-entry-1"},
+    //   {"path":["s","urn:entry:set-entry-1","data"],"op":"add","value":"test"}
+    // ]
+});
 
-setSetEntrySyntheticId(obj, "custom");
+state.s.add({ data: "test" });
-state.settings.add(obj);
-addWithId(state.settings as any, { x: 1 }, "x1");
 ```
 
+**Path structure explained:**
+
+- `["s", "urn:entry:set-entry-1"]` - The structural Set patch; the IRI identifies the entry
+- `["s", "urn:entry:set-entry-1", "@id"]` - Patch for the @id property assignment
+- `["s", "urn:entry:set-entry-1", "data"]` - Nested property patch; the IRI identifies which Set entry
+- The synthetic ID (the IRI) is stable across mutations, allowing tracking of the same object
+
+**Mutating nested properties:**
+
+```ts
+const state = deepSignal(
+    { users: new Set() }, 
+    { 
+        idGenerator: (path) => `urn:user:${path.join("-")}:${crypto.randomUUID()}`,
+        addIdToObjects: true 
+    }
+);
+const user = { name: "Ada", age: 30 };
+state.users.add(user); // Gets @id, e.g., "urn:user:550e8400-..."
+
+watch(state, ({ patches }) => {
+    console.log(JSON.stringify(patches));
+    // [{"path":["users","urn:user:550e8400-...","age"],"op":"add","value":31}]
+});
+
+// Later mutation: synthetic ID identifies which Set entry changed
+user.age = 31;
+```
+
+The path `["users", "urn:user:550e8400-...", "age"]` shows:
+1. `users` - the Set container
+2. `urn:user:550e8400-...` - the IRI identifying which object in the Set
+3. `age` - the property being mutated
+
+This structure enables precise tracking of nested changes within Set entries, critical for syncing state changes or implementing undo/redo.
+
 ## Shallow
 
 Skip deep proxying of a subtree (only reference replacement tracked):
@@ -153,16 +296,16 @@ const n: number = state.$count!(); // typed number
 ## API surface
 
 | Function                           | Description                                       |
-| ---------------------------------- | --------------------------------------- |
+| ---------------------------------- | ------------------------------------------------- |
-| `deepSignal(obj)`                  | Create (or reuse) reactive deep proxy.  |
+| `deepSignal(obj, options?)`        | Create (or reuse) reactive deep proxy with optional configuration. |
 | `watch(root, cb, opts?)`           | Observe batched deep mutations.                   |
 | `observe(root, cb, opts?)`         | Alias of `watch`.                                 |
 | `peek(obj,key)`                    | Untracked property read.                          |
 | `shallow(obj)`                     | Mark object to skip deep proxying.                |
 | `isDeepSignal(val)`                | Runtime predicate.                                |
 | `isShallow(val)`                   | Was value marked shallow.                         |
-| `setSetEntrySyntheticId(obj,id)`   | Assign custom Set entry id.             |
+| `setSetEntrySyntheticId(obj,id)`   | Assign custom Set entry id (highest priority).    |
-| `addWithId(set, entry, id)`        | Insert with desired synthetic id.       |
+| `addWithId(set, entry, id)`        | Insert with desired synthetic id (convenience).   |
 | `subscribeDeepMutations(root, cb)` | Low-level patch stream (used by watch).           |
 
 ## Credits

sdk/js/alien-deepsignals/src/deepSignal.ts

@@ -56,6 +56,14 @@ export interface DeepLiteralAddPatch {
 /** Callback signature for subscribeDeepMutations. */
 export type DeepPatchSubscriber = (patches: DeepPatch[]) => void;
 
+/** Options for configuring deepSignal behavior. */
+export interface DeepSignalOptions {
+    /** Custom function to generate synthetic IDs for objects without @id. */
+    idGenerator?: (pathToObject: (string | number)[]) => string | number;
+    /** If true, add @id property to all objects in the tree. */
+    addIdToObjects?: boolean;
+}
+
 /** Minimal per-proxy metadata for path reconstruction. */
 interface ProxyMeta {
     /** Parent proxy in the object graph (undefined for root). */
@@ -64,10 +72,14 @@ interface ProxyMeta {
     key?: string | number;
     /** Stable root id symbol shared by the entire deepSignal tree. */
     root: symbol;
+    /** Options inherited from root. */
+    options?: DeepSignalOptions;
 }
 
 // Proxy -> metadata
 const proxyMeta = new WeakMap<object, ProxyMeta>();
+// Root symbol -> options
+const rootOptions = new Map<symbol, DeepSignalOptions>();
 // Root symbol -> subscribers
 const mutationSubscribers = new Map<symbol, Set<DeepPatchSubscriber>>();
 // Pending patches grouped per root (flushed once per microtask)
@@ -118,6 +130,86 @@ function queuePatch(patch: DeepPatch) {
     }
 }
 
+/** Recursively emit patches for all nested properties of a newly attached object. */
+function queueDeepPatches(
+    val: any,
+    rootId: symbol,
+    basePath: (string | number)[],
+    options?: DeepSignalOptions
+) {
+    if (!val || typeof val !== "object") {
+        // Emit patch for primitive leaf
+        queuePatch({
+            root: rootId,
+            path: basePath,
+            op: "add",
+            value: val,
+        });
+        return;
+    }
+
+    // Add @id to object if options specify it
+    if (
+        options?.addIdToObjects &&
+        val.constructor === Object &&
+        !("@id" in val)
+    ) {
+        let syntheticId: string | number;
+        if (options.idGenerator) {
+            syntheticId = options.idGenerator(basePath);
+        } else {
+            syntheticId = assignBlankNodeId(val);
+        }
+
+        // Define @id on the raw object before proxying
+        Object.defineProperty(val, "@id", {
+            value: syntheticId,
+            writable: false,
+            enumerable: true,
+            configurable: false,
+        });
+    }
+
+    // Emit patch for the object/array/Set itself
+    queuePatch({
+        root: rootId,
+        path: basePath,
+        op: "add",
+        type: "object",
+    });
+
+    // Emit patch for @id if it exists
+    if ("@id" in val) {
+        queuePatch({
+            root: rootId,
+            path: [...basePath, "@id"],
+            op: "add",
+            value: (val as any)["@id"],
+        });
+    }
+
+    // Recursively process nested properties
+    if (Array.isArray(val)) {
+        for (let i = 0; i < val.length; i++) {
+            queueDeepPatches(val[i], rootId, [...basePath, i], options);
+        }
+    } else if (val instanceof Set) {
+        for (const entry of val) {
+            const key = getSetEntryKey(entry);
+            queueDeepPatches(entry, rootId, [...basePath, key], options);
+        }
+    } else if (val.constructor === Object) {
+        for (const key in val) {
+            if (
+                Object.prototype.hasOwnProperty.call(val, key) &&
+                key !== "@id"
+            ) {
+                queueDeepPatches(val[key], rootId, [...basePath, key], options);
+            }
+        }
+    }
+}
+
 /** Subscribe to microtask-batched deep patches for a root (returns unsubscribe). */
 export function subscribeDeepMutations(
     root: object | symbol,
@@ -275,17 +367,21 @@ export function setSetEntrySyntheticId(obj: object, id: string | number) {
 }
 const getSetEntryKey = (val: any): string | number => {
     if (val && typeof val === "object") {
+        // First check for explicitly assigned synthetic ID
         if (setObjectIds.has(val)) return setObjectIds.get(val)!;
-    if (
+        // Then check for @id property (primary identifier)
-      typeof (val as any).id === "string" ||
-      typeof (val as any).id === "number"
-    )
-      return (val as any).id;
         if (
             typeof (val as any)["@id"] === "string" ||
             typeof (val as any)["@id"] === "number"
         )
             return (val as any)["@id"];
+        // Then check for id property (backward compatibility)
+        if (
+            typeof (val as any).id === "string" ||
+            typeof (val as any).id === "number"
+        )
+            return (val as any).id;
+        // Fall back to generating a blank node ID
         return assignBlankNodeId(val);
     }
     return val as any;
@@ -316,16 +412,28 @@ export const isShallow = (source: any) => {
 };
 
 /** Create (or reuse) a deep reactive proxy for an object / array / Set. */
-export const deepSignal = <T extends object>(obj: T): DeepSignal<T> => {
+export const deepSignal = <T extends object>(
+    obj: T,
+    options?: DeepSignalOptions
+): DeepSignal<T> => {
     if (!shouldProxy(obj)) throw new Error("This object can't be observed.");
     if (!objToProxy.has(obj)) {
         // Create a unique root id symbol to identify this deep signal tree in patches.
         const rootId = Symbol("deepSignalRoot");
-    const proxy = createProxy(obj, objectHandlers, rootId) as DeepSignal<T>;
+        if (options) {
+            rootOptions.set(rootId, options);
+        }
+        const proxy = createProxy(
+            obj,
+            objectHandlers,
+            rootId,
+            options
+        ) as DeepSignal<T>;
         const meta = proxyMeta.get(proxy)!;
         meta.parent = undefined; // root has no parent
         meta.key = undefined; // root not addressed by a key
         meta.root = rootId; // ensure root id stored (explicit)
+        meta.options = options; // store options in metadata
         // Pre-register an empty signals map so isDeepSignal() is true before any property access.
         if (!proxyToSignals.has(proxy)) proxyToSignals.set(proxy, new Map());
         objToProxy.set(obj, proxy);
@@ -336,7 +444,7 @@ export const deepSignal = <T extends object>(obj: T): DeepSignal<T> => {
 /** Read property without tracking (untracked read). */
 export const peek = <
     T extends DeepSignalObject<object>,
-  K extends keyof RevertDeepSignalObject<T>
+    K extends keyof RevertDeepSignalObject<T>,
 >(
     obj: T,
     key: K
@@ -359,14 +467,19 @@ export function shallow<T extends object>(obj: T): Shallow<T> {
 const createProxy = (
     target: object,
     handlers: ProxyHandler<object>,
-  rootId?: symbol
+    rootId?: symbol,
+    options?: DeepSignalOptions
 ) => {
     const proxy = new Proxy(target, handlers);
     ignore.add(proxy);
     // Initialize proxy metadata if not present. Root proxies provide a stable root id.
     if (!proxyMeta.has(proxy)) {
-    proxyMeta.set(proxy, { root: rootId || Symbol("deepSignalDetachedRoot") });
+        proxyMeta.set(proxy, {
+            root: rootId || Symbol("deepSignalDetachedRoot"),
+            options: options || rootOptions.get(rootId!),
+        });
     }
+
     return proxy;
 };
 
@@ -386,7 +499,12 @@ function getFromSet(
             !objToProxy.has(entry)
         ) {
             const synthetic = getSetEntryKey(entry);
-      const childProxy = createProxy(entry, objectHandlers, meta!.root);
+            const childProxy = createProxy(
+                entry,
+                objectHandlers,
+                meta!.root,
+                meta!.options
+            );
             const childMeta = proxyMeta.get(childProxy)!;
             childMeta.parent = receiver;
             childMeta.key = synthetic;
@@ -398,6 +516,7 @@ function getFromSet(
     };
     // Pre-pass to ensure any existing non-proxied object entries are proxied (enables deep patches after iteration)
     if (meta) raw.forEach(ensureEntryProxy);
+
     if (key === "add" || key === "delete" || key === "clear") {
         const fn: Function = (raw as any)[key];
         return function (this: any, ...args: any[]) {
@@ -410,9 +529,37 @@ function getFromSet(
                     metaNow.parent !== undefined &&
                     metaNow.key !== undefined
                 ) {
-          const containerPath = buildPath(metaNow.parent, metaNow.key);
+                    const containerPath = buildPath(
+                        metaNow.parent,
+                        metaNow.key
+                    );
                     if (key === "add") {
                         const entry = args[0];
+
+                        // Add @id to object entries if options specify it
+                        if (
+                            entry &&
+                            typeof entry === "object" &&
+                            metaNow.options?.addIdToObjects &&
+                            entry.constructor === Object &&
+                            !("@id" in entry)
+                        ) {
+                            let syntheticId: string | number;
+                            if (metaNow.options.idGenerator) {
+                                syntheticId =
+                                    metaNow.options.idGenerator(containerPath);
+                            } else {
+                                syntheticId = assignBlankNodeId(entry);
+                            }
+
+                            Object.defineProperty(entry, "@id", {
+                                value: syntheticId,
+                                writable: false,
+                                enumerable: true,
+                                configurable: false,
+                            });
+                        }
+
                         let synthetic = getSetEntryKey(entry);
                         if (entry && typeof entry === "object") {
                             for (const existing of raw.values()) {
@@ -433,7 +580,8 @@ function getFromSet(
                             const childProxy = createProxy(
                                 entryVal,
                                 objectHandlers,
-                metaNow.root
+                                metaNow.root,
+                                metaNow.options
                             );
                             const childMeta = proxyMeta.get(childProxy)!;
                             childMeta.parent = receiver;
@@ -441,30 +589,46 @@ function getFromSet(
                             objToProxy.set(entryVal, childProxy);
                             entryVal = childProxy;
                         }
-            // Set entry add: emit object vs literal variant.
+                        // Set entry add: emit object vs primitive variant.
                         if (entryVal && typeof entryVal === "object") {
-              queuePatch({
+                            // Object entry: path includes synthetic id, and emit deep patches for nested properties
-                root: metaNow.root,
+                            queueDeepPatches(
-                path: [...containerPath, synthetic],
+                                entry,
-                op: "add",
+                                metaNow.root,
-                type: "object",
+                                [...containerPath, synthetic],
-              });
+                                metaNow.options
+                            );
                         } else {
+                            // Primitive entry: path is just the Set, value contains the primitive
                             queuePatch({
                                 root: metaNow.root,
-                path: [...containerPath, synthetic],
+                                path: containerPath,
                                 op: "add",
-                value: entryVal,
+                                type: "set",
+                                value: [entryVal],
                             });
                         }
                     } else if (key === "delete") {
                         const entry = args[0];
                         const synthetic = getSetEntryKey(entry);
+                        // Check if entry is primitive or object
+                        if (entry && typeof entry === "object") {
+                            // Object entry: path includes synthetic id
                             queuePatch({
                                 root: metaNow.root,
                                 path: [...containerPath, synthetic],
                                 op: "remove",
                             });
+                        } else {
+                            // Primitive entry: path is just the Set, value contains the primitive
+                            queuePatch({
+                                root: metaNow.root,
+                                path: containerPath,
+                                op: "remove",
+                                type: "set",
+                                value: entry,
+                            });
+                        }
                     } else if (key === "clear") {
                         // Structural clear: remove prior entry-level patches for this Set this tick.
                         if (pendingPatches) {
@@ -473,8 +637,11 @@ function getFromSet(
                                 for (let i = group.length - 1; i >= 0; i--) {
                                     const p = group[i];
                                     if (
-                    p.path.length === containerPath.length + 1 &&
+                                        p.path.length ===
-                    containerPath.every((seg, idx) => p.path[idx] === seg)
+                                            containerPath.length + 1 &&
+                                        containerPath.every(
+                                            (seg, idx) => p.path[idx] === seg
+                                        )
                                     ) {
                                         group.splice(i, 1);
                                     }
@@ -504,7 +671,10 @@ function getFromSet(
                             const n = iterable.next();
                             if (n.done) return n;
                             const entry = ensureEntryProxy(n.value);
-              return { value: pair ? [entry, entry] : entry, done: false };
+                            return {
+                                value: pair ? [entry, entry] : entry,
+                                done: false,
+                            };
                         },
                     };
                 },
@@ -516,7 +686,12 @@ function getFromSet(
     if (key === "forEach") {
         return function thisForEach(this: any, cb: any, thisArg?: any) {
             raw.forEach((entry: any) => {
-        cb.call(thisArg, ensureEntryProxy(entry), ensureEntryProxy(entry), raw);
+                cb.call(
+                    thisArg,
+                    ensureEntryProxy(entry),
+                    ensureEntryProxy(entry),
+                    raw
+                );
             });
         };
     }
@@ -569,7 +744,12 @@ function ensureChildProxy(value: any, parent: object, key: string | number) {
     if (!shouldProxy(value)) return value;
     if (!objToProxy.has(value)) {
         const parentMeta = proxyMeta.get(parent)!;
-    const childProxy = createProxy(value, objectHandlers, parentMeta.root);
+        const childProxy = createProxy(
+            value,
+            objectHandlers,
+            parentMeta.root,
+            parentMeta.options
+        );
         const childMeta = proxyMeta.get(childProxy)!;
         childMeta.parent = parent;
         childMeta.key = key as string;
@@ -590,9 +770,15 @@ function normalizeKey(
         if (fullKey === "$") {
             // Provide $ meta proxy for array index signals
             if (!arrayToArrayOfSignals.has(target)) {
+                const receiverMeta = proxyMeta.get(receiver);
                 arrayToArrayOfSignals.set(
                     target,
-          createProxy(target, arrayHandlers, proxyMeta.get(receiver)?.root)
+                    createProxy(
+                        target,
+                        arrayHandlers,
+                        receiverMeta?.root,
+                        receiverMeta?.options
+                    )
                 );
             }
             return { shortCircuit: arrayToArrayOfSignals.get(target) };
@@ -652,10 +838,15 @@ const get =
 const objectHandlers = {
     get: get(false),
     set(target: object, fullKey: string, val: any, receiver: object): boolean {
+        // Prevent modification of @id property
+        if (fullKey === "@id") {
+            throw new Error("Cannot modify readonly property '@id'");
+        }
         // Respect original getter/setter semantics
         if (typeof descriptor(target, fullKey)?.set === "function")
             return Reflect.set(target, fullKey, val, receiver);
-    if (!proxyToSignals.has(receiver)) proxyToSignals.set(receiver, new Map());
+        if (!proxyToSignals.has(receiver))
+            proxyToSignals.set(receiver, new Map());
         const signals = proxyToSignals.get(receiver);
         if (fullKey[0] === "$") {
             if (!isSignal(val)) throwOnMutation();
@@ -679,7 +870,12 @@ const objectHandlers = {
                         proxyMeta.set(receiver, created);
                         parentMeta = created;
                     }
-          const childProxy = createProxy(val, objectHandlers, parentMeta!.root);
+                    const childProxy = createProxy(
+                        val,
+                        objectHandlers,
+                        parentMeta!.root,
+                        parentMeta!.options
+                    );
                     const childMeta = proxyMeta.get(childProxy)!;
                     childMeta.parent = receiver;
                     childMeta.key = fullKey;
@@ -697,28 +893,20 @@ const objectHandlers = {
                 // Subsequent writes -> update underlying signal.
                 signals.get(fullKey).set(internal);
             }
-      if (isNew && objToIterable.has(target)) objToIterable.get(target).value++;
+            if (isNew && objToIterable.has(target))
+                objToIterable.get(target).value++;
             if (Array.isArray(target) && signals.has("length"))
                 signals.get("length").set(target.length);
             // Emit patch (after mutation) so subscribers get final value snapshot.
             const meta = proxyMeta.get(receiver);
             if (meta) {
-        // Object/Array/Set assignment at property path.
+                // Recursively emit patches for all nested properties of newly attached objects
-        if (val && typeof val === "object") {
+                queueDeepPatches(
-          queuePatch({
+                    val,
-            root: meta.root,
+                    meta.root,
-            path: buildPath(receiver, fullKey),
+                    buildPath(receiver, fullKey),
-            op: "add",
+                    meta.options
-            type: "object",
+                );
-          });
-        } else {
-          queuePatch({
-            root: meta.root,
-            path: buildPath(receiver, fullKey),
-            op: "add",
-            value: val,
-          });
-        }
             }
             return result;
         }
@@ -810,7 +998,8 @@ type RevertDeepSignalObject<T> = Pick<T, FilterSignals<keyof T>>;
 type RevertDeepSignalArray<T> = Omit<T, "$" | "$length">;
 
 /** Inverse mapped type removing deepSignal wrapper affordances. */
-export type RevertDeepSignal<T> = T extends Array<unknown>
+export type RevertDeepSignal<T> =
+    T extends Array<unknown>
         ? RevertDeepSignalArray<T>
         : T extends object
           ? RevertDeepSignalObject<T>

sdk/js/alien-deepsignals/src/test/deepSignalOptions.test.ts

@@ -0,0 +1,340 @@
+import { describe, it, expect } from "vitest";
+import { deepSignal, DeepPatch, DeepSignalOptions } from "../deepSignal";
+import { watch } from "../watch";
+
+describe("deepSignal options", () => {
+    describe("custom ID generator", () => {
+        it("uses custom ID generator for objects without @id", async () => {
+            let counter = 1000;
+            const options: DeepSignalOptions = {
+                idGenerator: () => `custom-${counter++}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ data: {} as any }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.data.user = { name: "Alice" };
+            await Promise.resolve();
+
+            // Check that @id was assigned
+            expect((state.data.user as any)["@id"]).toBe("custom-1000");
+
+            // Check that patch was emitted for @id
+            const flat = patches.flat().map((p) => p.path.join("."));
+            expect(flat).toContain("data.user.@id");
+
+            stop();
+        });
+
+        it("respects existing @id on objects", async () => {
+            const options: DeepSignalOptions = {
+                idGenerator: () => "should-not-be-used",
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ items: [] as any[] }, options);
+
+            state.items.push({ "@id": "existing-123", value: 42 });
+
+            // Should use the existing @id
+            expect((state.items[0] as any)["@id"]).toBe("existing-123");
+        });
+
+        it("uses @id property from objects added to Sets", async () => {
+            const options: DeepSignalOptions = {
+                idGenerator: () => "fallback-id",
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ s: new Set<any>() }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            const obj = { "@id": "set-entry-1", data: "test" };
+            state.s.add(obj);
+
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Path should use the @id as synthetic key
+            expect(flat.some((p) => p.startsWith("s.set-entry-1"))).toBe(true);
+
+            stop();
+        });
+    });
+
+    describe("addIdToObjects option", () => {
+        it("adds @id to all nested objects when enabled", async () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ root: {} as any }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.root.level1 = {
+                level2: {
+                    level3: { value: "deep" },
+                },
+            };
+
+            await Promise.resolve();
+
+            // Check all levels have @id
+            expect((state.root.level1 as any)["@id"]).toBeDefined();
+            expect((state.root.level1.level2 as any)["@id"]).toBeDefined();
+            expect(
+                (state.root.level1.level2.level3 as any)["@id"]
+            ).toBeDefined();
+
+            // Check patches were emitted for all @id fields
+            const flat = patches.flat().map((p) => p.path.join("."));
+            expect(flat).toContain("root.level1.@id");
+            expect(flat).toContain("root.level1.level2.@id");
+            expect(flat).toContain("root.level1.level2.level3.@id");
+
+            stop();
+        });
+
+        it("does not add @id when option is false", () => {
+            const state = deepSignal({ data: { nested: {} } });
+
+            // Should not have @id
+            expect("@id" in (state.data as any)).toBe(false);
+            expect("@id" in (state.data.nested as any)).toBe(false);
+        });
+
+        it("adds @id to objects in arrays", async () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ items: [] as any[] }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.items.push({ name: "Item 1" }, { name: "Item 2" });
+
+            await Promise.resolve();
+
+            // Both items should have @id
+            expect((state.items[0] as any)["@id"]).toBeDefined();
+            expect((state.items[1] as any)["@id"]).toBeDefined();
+
+            // Check patches
+            const flat = patches.flat().map((p) => p.path.join("."));
+            expect(flat).toContain("items.0.@id");
+            expect(flat).toContain("items.1.@id");
+
+            stop();
+        });
+
+        it("adds @id to objects in Sets", async () => {
+            const options: DeepSignalOptions = {
+                idGenerator: () =>
+                    `gen-${Math.random().toString(36).substr(2, 9)}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ s: new Set<any>() }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            const obj1 = { value: 1 };
+            const obj2 = { value: 2 };
+            state.s.add(obj1);
+            state.s.add(obj2);
+
+            await Promise.resolve();
+
+            // Get proxied objects from Set
+            const proxiedObjs = Array.from(state.s);
+            expect((proxiedObjs[0] as any)["@id"]).toBeDefined();
+            expect((proxiedObjs[1] as any)["@id"]).toBeDefined();
+
+            // @id should be used as synthetic key in paths
+            const flat = patches.flat().map((p) => p.path.join("."));
+            const obj1Id = (proxiedObjs[0] as any)["@id"];
+            const obj2Id = (proxiedObjs[1] as any)["@id"];
+            expect(flat.some((p) => p.startsWith(`s.${obj1Id}`))).toBe(true);
+            expect(flat.some((p) => p.startsWith(`s.${obj2Id}`))).toBe(true);
+
+            stop();
+        });
+    });
+
+    describe("@id property behavior", () => {
+        it("makes @id readonly", () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ obj: {} as any }, options);
+            state.obj.data = { value: 1 };
+
+            // Attempting to modify @id should throw
+            expect(() => {
+                (state.obj.data as any)["@id"] = "new-id";
+            }).toThrow("Cannot modify readonly property '@id'");
+        });
+
+        it("makes @id enumerable", () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ obj: {} as any }, options);
+            state.obj.data = { value: 1 };
+
+            // @id should show up in Object.keys()
+            const keys = Object.keys(state.obj.data);
+            expect(keys).toContain("@id");
+        });
+
+        it("emits patches for @id even on objects with existing @id", async () => {
+            const options: DeepSignalOptions = {
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ container: {} as any }, options);
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            // Object already has @id before being added
+            const objWithId = { "@id": "pre-existing", data: "test" };
+            state.container.item = objWithId;
+
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Patch should still be emitted for @id
+            expect(flat).toContain("container.item.@id");
+
+            // Verify the value in the patch
+            const idPatch = patches
+                .flat()
+                .find((p) => p.path.join(".") === "container.item.@id");
+            expect((idPatch as any).value).toBe("pre-existing");
+
+            stop();
+        });
+    });
+
+    describe("options inheritance", () => {
+        it("child objects inherit options from root", async () => {
+            let idCounter = 5000;
+            const options: DeepSignalOptions = {
+                idGenerator: () => `inherited-${idCounter++}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ root: {} as any }, options);
+
+            // Add nested structure
+            state.root.child = {
+                grandchild: {
+                    value: "nested",
+                },
+            };
+
+            // All should have IDs generated by the custom generator
+            expect((state.root.child as any)["@id"]).toMatch(/^inherited-/);
+            expect((state.root.child.grandchild as any)["@id"]).toMatch(
+                /^inherited-/
+            );
+        });
+
+        it("objects added to Sets inherit options", async () => {
+            let counter = 9000;
+            const options: DeepSignalOptions = {
+                idGenerator: () => `set-child-${counter++}`,
+                addIdToObjects: true,
+            };
+
+            const state = deepSignal({ s: new Set<any>() }, options);
+
+            const obj = { nested: { value: 1 } };
+            state.s.add(obj);
+
+            // Iterate to get proxied object
+            const proxied = Array.from(state.s)[0];
+
+            // Object and nested object should have custom IDs
+            expect((proxied as any)["@id"]).toMatch(/^set-child-/);
+            expect((proxied.nested as any)["@id"]).toMatch(/^set-child-/);
+        });
+    });
+
+    describe("backward compatibility", () => {
+        it("still works without options", async () => {
+            const state = deepSignal({ data: { value: 1 } });
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.data.value = 2;
+            await Promise.resolve();
+
+            expect(patches.flat().length).toBeGreaterThan(0);
+            stop();
+        });
+
+        // TODO: Delete duplicate logic for `id`. Only accept @id.
+        it("objects with id property still work for Sets", async () => {
+            const state = deepSignal({ s: new Set<any>() });
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.s.add({ id: "legacy-id", value: 1 });
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Should use id as synthetic key
+            expect(flat.some((p) => p.startsWith("s.legacy-id"))).toBe(true);
+
+            stop();
+        });
+
+        it("@id takes precedence over id property", async () => {
+            const state = deepSignal({ s: new Set<any>() });
+            const patches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+                patches.push(batch)
+            );
+
+            state.s.add({
+                id: "should-not-use",
+                "@id": "should-use",
+                value: 1,
+            });
+            await Promise.resolve();
+
+            const flat = patches.flat().map((p) => p.path.join("."));
+            // Should use @id, not id
+            expect(flat.some((p) => p.startsWith("s.should-use"))).toBe(true);
+            expect(flat.some((p) => p.startsWith("s.should-not-use"))).toBe(
+                false
+            );
+
+            stop();
+        });
+    });
+});

sdk/js/alien-deepsignals/src/test/watchPatches.test.ts

@@ -95,7 +95,16 @@ describe("watch (patch mode)", () => {
         await Promise.resolve();
         expect(batches.length >= 1).toBe(true);
         const allPaths = batches.flatMap((b) => b.map((p) => p.path.join(".")));
-    expect(allPaths.some((p) => p.startsWith("s."))).toBe(true);
+        // For primitives, the path should be just "s" (the Set itself)
+        expect(allPaths.every((p) => p === "s")).toBe(true);
+        // Check the values
+        const patches = batches.flat();
+        const addPatches = patches.filter((p) => p.op === "add");
+        const deletePatches = patches.filter((p) => p.op === "remove");
+        expect(addPatches.length).toBe(1);
+        expect(deletePatches.length).toBe(1);
+        expect((addPatches[0] as any).value[0]).toBe(3);
+        expect((deletePatches[0] as any).value).toBe(1);
         stop();
     });
 
@@ -105,8 +114,7 @@ describe("watch (patch mode)", () => {
         const { stopListening: stop } = watch(state, ({ patches: batch }) =>
             patches.push(batch)
         );
-    state.root.child = { level: { value: 1 } };
+        state.root.child = { level: { value: 1 }, l1: "val" };
-    state.root.child.level.value = 2;
         await Promise.resolve();
         const flat = patches.flat().map((p) => p.path.join("."));
         expect(flat).toContain("root.child");
@@ -114,6 +122,68 @@ describe("watch (patch mode)", () => {
         stop();
     });
 
+    it("emits patches for deeply nested arrays and objects", async () => {
+        const state = deepSignal<{ data: any }>({ data: null });
+        const patches: DeepPatch[][] = [];
+        const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+            patches.push(batch)
+        );
+        state.data = {
+            users: [
+                {
+                    id: 1,
+                    profile: { name: "Alice", settings: { theme: "dark" } },
+                },
+                {
+                    id: 2,
+                    profile: { name: "Bob", settings: { theme: "light" } },
+                },
+            ],
+            meta: { count: 2, active: true },
+        };
+        await Promise.resolve();
+
+        const flat = patches.flat().map((p) => p.path.join("."));
+        // Check for root object
+        expect(flat).toContain("data");
+        // Check for nested array
+        expect(flat).toContain("data.users");
+        // Check for array elements
+        expect(flat).toContain("data.users.0");
+        expect(flat).toContain("data.users.1");
+        // Check for deeply nested properties
+        expect(flat).toContain("data.users.0.profile.settings.theme");
+        expect(flat).toContain("data.users.1.profile.settings.theme");
+        expect(flat).toContain("data.meta.count");
+        expect(flat).toContain("data.meta.active");
+        stop();
+    });
+
+    it("emits patches for Set with nested objects added as one operation", async () => {
+        const state = deepSignal<{ container: any }>({ container: {} });
+        const patches: DeepPatch[][] = [];
+        const { stopListening: stop } = watch(state, ({ patches: batch }) =>
+            patches.push(batch)
+        );
+        state.container.items = new Set([
+            { id: "a", data: { nested: { value: 1 } } },
+            { id: "b", data: { nested: { value: 2 } } },
+        ]);
+        await Promise.resolve();
+
+        const flat = patches.flat().map((p) => p.path.join("."));
+
+        // Check for the Set itself
+        expect(flat).toContain("container.items");
+        // Check for Set entries (using their id as synthetic key)
+        expect(flat.some((p) => p.startsWith("container.items.a"))).toBe(true);
+        expect(flat.some((p) => p.startsWith("container.items.b"))).toBe(true);
+        // Check for deeply nested properties within Set entries
+        expect(flat).toContain("container.items.a.data.nested.value");
+        expect(flat).toContain("container.items.b.data.nested.value");
+        stop();
+    });
+
     it("emits structural patches for sets of sets", async () => {
         const innerA = new Set<any>([{ id: "node1", x: 1 }]);
         const s = new Set<any>([innerA]);
@@ -165,6 +235,89 @@ describe("watch (patch mode)", () => {
     });
 
     describe("Set", () => {
+        it("emits patches for primitive adds", async () => {
+            const st = deepSignal({ s: new Set<any>() });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.add(true);
+            st.s.add(2);
+            st.s.add("3");
+            await Promise.resolve();
+
+            expect(batches.length).toBe(1);
+            const patches = batches[0];
+            expect(patches.length).toBe(3);
+
+            // All patches should have the same path (the Set itself)
+            patches.forEach((p) => {
+                expect(p.path.join(".")).toBe("s");
+                expect(p.op).toBe("add");
+                expect((p as any).type).toBe("set");
+            });
+
+            // Check that values are in the value field, not in path
+            const values = patches.map((p: any) => p.value[0]);
+            expect(values).toContain(true);
+            expect(values).toContain(2);
+            expect(values).toContain("3");
+            stop();
+        });
+        it("emits patches for primitive deletes", async () => {
+            const st = deepSignal({ s: new Set<any>([true, 2, "3"]) });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.delete(true);
+            st.s.delete(2);
+            await Promise.resolve();
+
+            expect(batches.length).toBe(1);
+            const patches = batches[0];
+            expect(patches.length).toBe(2);
+
+            // All patches should have the same path (the Set itself)
+            patches.forEach((p) => {
+                expect(p.path.join(".")).toBe("s");
+                expect(p.op).toBe("remove");
+                expect((p as any).type).toBe("set");
+            });
+
+            // Check that values are in the value field
+            const values = patches.map((p: any) => p.value);
+            expect(values).toContain(true);
+            expect(values).toContain(2);
+            stop();
+        });
+        it("does not emit patches for non-existent primitives", async () => {
+            const st = deepSignal({ s: new Set<any>([1, 2]) });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.delete("nonexistent");
+            st.s.delete(999);
+            await Promise.resolve();
+
+            expect(batches.length).toBe(0);
+            stop();
+        });
+        it("does not emit patches for already added primitive", async () => {
+            const st = deepSignal({ s: new Set<any>([1, "test", true]) });
+            const batches: DeepPatch[][] = [];
+            const { stopListening: stop } = watch(st, ({ patches }) =>
+                batches.push(patches)
+            );
+            st.s.add(1);
+            st.s.add("test");
+            st.s.add(true);
+            await Promise.resolve();
+
+            expect(batches.length).toBe(0);
+            stop();
+        });
         it("emits single structural patch on Set.clear()", async () => {
             const st = deepSignal({ s: new Set<any>() });
             addWithId(st.s as any, { id: "a", x: 1 }, "a");
@@ -175,8 +328,13 @@ describe("watch (patch mode)", () => {
             );
             st.s.clear();
             await Promise.resolve();
-      const all = batches.flat().map((p) => p.path.join("."));
+            // clear() emits a single structural patch for the Set itself (op: "add", value: [])
-      expect(all).toEqual(["s"]);
+            const structuralPatches = batches
+                .flat()
+                .filter((p) => p.path.length === 1 && p.path[0] === "s");
+            expect(structuralPatches.length).toBe(1);
+            expect(structuralPatches[0].op).toBe("add");
+            expect((structuralPatches[0] as any).value).toEqual([]);
             stop();
         });
         it("emits delete patch for object entry", async () => {
@@ -227,8 +385,11 @@ describe("watch (patch mode)", () => {
             const ret = addWithId(st.s as any, 5, "ignored");
             expect(ret).toBe(5);
             await Promise.resolve();
+            // For primitives, path should be just "s" and value should be in the value field
             const paths = patches.flat().map((p) => p.path.join("."));
-      expect(paths).toContain("s.5");
+            expect(paths).toContain("s");
+            const values = patches.flat().map((p: any) => p.value?.[0]);
+            expect(values).toContain(5);
             stop();
         });
         it("setSetEntrySyntheticId applies custom id without helper", async () => {
@@ -247,7 +408,11 @@ describe("watch (patch mode)", () => {
         });
         it("values/entries/forEach proxy nested mutation", async () => {
             const st = deepSignal({ s: new Set<any>() });
-      const entry = addWithId(st.s as any, { id: "e1", inner: { v: 1 } }, "e1");
+            const entry = addWithId(
+                st.s as any,
+                { id: "e1", inner: { v: 1 } },
+                "e1"
+            );
             const batches: DeepPatch[][] = [];
             const { stopListening: stop } = watch(st, ({ patches }) =>
                 batches.push(patches)
@@ -277,7 +442,9 @@ describe("watch (patch mode)", () => {
             proxied.data.x = 3;
             await Promise.resolve();
             const afterProxied = batches.flat().map((p) => p.path.join("."));
-      expect(afterProxied.some((p) => p.endsWith("id1.data.x"))).toBe(true);
+            expect(afterProxied.some((p) => p.endsWith("id1.data.x"))).toBe(
+                true
+            );
             stop();
         });
         it("synthetic id collision assigns unique blank node id", async () => {
@@ -291,10 +458,17 @@ describe("watch (patch mode)", () => {
             st.s.add(a1);
             st.s.add(a2);
             await Promise.resolve();
-      const keys = patches
+            // Filter for Set structural patches only (path length 2: ['s', syntheticId])
+            const setAddPatches = patches
                 .flat()
-        .filter((p) => p.op === "add")
+                .filter(
-        .map((p) => p.path.slice(-1)[0]);
+                    (p) =>
+                        p.op === "add" &&
+                        p.path.length === 2 &&
+                        p.path[0] === "s"
+                );
+            const keys = setAddPatches.map((p) => p.path.slice(-1)[0]);
+            // Both objects should have unique synthetic IDs despite id collision
             expect(new Set(keys).size).toBe(2);
             stop();
         });

sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.schema.ts

@@ -19,7 +19,7 @@ export const catShapeSchema: Schema = {
         maxCardinality: 1,
         minCardinality: 1,
         iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-        readablePredicate: "type",
+        readablePredicate: "@type",
       },
       {
         dataTypes: [

sdk/js/examples/multi-framework-signals/src/shapes/orm/catShape.typings.ts

@@ -10,11 +10,11 @@ export type IRI = string;
  * Cat Type
  */
 export interface Cat {
-  id: IRI;
+  readonly "@id": IRI;
   /**
    * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    */
-  type: string;
+  "@type": string;
   /**
    * Original IRI: http://example.org/name
    */
@@ -31,7 +31,7 @@ export interface Cat {
    * Original IRI: http://example.org/address
    */
   address: {
-    id: IRI;
+    readonly "@id": IRI;
     /**
      * Original IRI: http://example.org/street
      */

sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.schema.ts

@@ -19,7 +19,7 @@ export const personShapeSchema: Schema = {
         maxCardinality: 1,
         minCardinality: 1,
         iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-        readablePredicate: "type",
+        readablePredicate: "@type",
       },
       {
         dataTypes: [

sdk/js/examples/multi-framework-signals/src/shapes/orm/personShape.typings.ts

@@ -10,11 +10,11 @@ export type IRI = string;
  * Person Type
  */
 export interface Person {
-  id: IRI;
+  readonly "@id": IRI;
   /**
    * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    */
-  type: string;
+  "@type": string;
   /**
    * Original IRI: http://example.org/name
    */
@@ -23,7 +23,7 @@ export interface Person {
    * Original IRI: http://example.org/address
    */
   address: {
-    id: IRI;
+    readonly "@id": IRI;
     /**
      * Original IRI: http://example.org/street
      */

sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.schema.ts

@@ -19,7 +19,7 @@ export const testShapeSchema: Schema = {
         maxCardinality: 1,
         minCardinality: 1,
         iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-        readablePredicate: "type",
+        readablePredicate: "@type",
         extra: true,
       },
       {

sdk/js/examples/multi-framework-signals/src/shapes/orm/testShape.typings.ts

@@ -10,11 +10,11 @@ export type IRI = string;
  * TestObject Type
  */
 export interface TestObject {
-  id: IRI;
+  readonly "@id": IRI;
   /**
    * Original IRI: http://www.w3.org/1999/02/22-rdf-syntax-ns#type
    */
-  type: string;
+  "@type": string;
   /**
    * Original IRI: http://example.org/stringValue
    */
@@ -35,7 +35,7 @@ export interface TestObject {
    * Original IRI: http://example.org/objectValue
    */
   objectValue: {
-    id: IRI;
+    readonly "@id": IRI;
     /**
      * Original IRI: http://example.org/nestedString
      */
@@ -55,7 +55,7 @@ export interface TestObject {
   anotherObject?: Record<
     IRI,
     {
-      id: IRI;
+      readonly "@id": IRI;
       /**
        * Original IRI: http://example.org/prop1
        */

sdk/js/shex-orm/src/schema-converter/transformers/ShexJTypingTransformer.ts

@@ -225,7 +225,7 @@ function dedupeCompactProperties(
     return merged;
 }
 
-// Helpers to add id: IRI to anonymous object(-union) types
+// Helpers to add @id: IRI to anonymous object(-union) types
 function ensureIdOnMembers(members?: any[]): void {
     if (!members) return;
     const props = (members.filter?.((m: any) => m?.kind === "property") ||
@@ -233,9 +233,9 @@ function ensureIdOnMembers(members?: any[]): void {
     if (!props.some((m) => m.name === "id")) {
         members.unshift(
             dom.create.property(
-                "id",
+                "@id",
                 dom.create.namedTypeReference("IRI"),
-                dom.DeclarationFlags.None
+                dom.DeclarationFlags.ReadOnly
             )
         );
     }
@@ -322,15 +322,15 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer<
                 shapeInterface.shapeId = shapeDecl.id;
                 if (
                     !shapeInterface.members.find(
-                        (m) => m.kind === "property" && m.name === "id"
+                        (m) => m.kind === "property" && m.name === "@id"
                     )
                 ) {
                     shapeInterface.members.unshift(
                         dom.create.property(
-                            "id",
+                            "@id",
                             dom.create.namedTypeReference("IRI"),
-                            // Root interfaces should have mandatory id
+                            // Root interfaces should have mandatory @id
-                            dom.DeclarationFlags.None
+                            dom.DeclarationFlags.ReadOnly
                         )
                     );
                 }
@@ -380,7 +380,7 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer<
                         const merged = [
                             ...extInt.members.filter(
                                 (m) =>
-                                    !(m.kind === "property" && m.name === "id")
+                                    !(m.kind === "property" && m.name === "@id")
                             ),
                             ...newInterface.members,
                         ].filter(
@@ -394,7 +394,7 @@ export const ShexJTypingTransformerCompact = ShexJTraverser.createTransformer<
             // Final pass: ensure only a single id property
             const idSeen = new Set<number>();
             newInterface.members = newInterface.members.filter((m, idx) => {
-                if (m.kind !== "property" || m.name !== "id") return true;
+                if (m.kind !== "property" || m.name !== "@id") return true;
                 if (idSeen.size === 0) {
                     idSeen.add(idx);
                     // normalize id type to IRI

sdk/js/shex-orm/src/types.ts

@@ -4,7 +4,7 @@ export interface ShapeType<T extends BaseType> {
 }
 
 export interface BaseType extends Record<string, any> {
-    id: string;
+    "@id": string;
 }
 
 export type Schema = {

sdk/js/signals/src/connector/applyDiff.test.ts

@@ -52,74 +52,169 @@ describe("applyDiff - set operations (primitives)", () => {
     });
 });
 
-describe("applyDiff - set operations (object sets)", () => {
+describe("applyDiff - multi-valued objects (Set-based)", () => {
-    test("add object entries to new object-set", () => {
+    test("create multi-object container (Set) without @id", () => {
-        const state: any = {};
+        const state: any = { "urn:person1": {} };
         const diff: Patch[] = [
             {
                 op: "add",
-                valType: "set",
+                valType: "object",
-                path: p("users"),
+                path: p("urn:person1", "children"),
-                value: { u1: { id: "u1", n: 1 }, u2: { id: "u2", n: 2 } },
             },
         ];
         applyDiff(state, diff);
-        expect(state.users.u1).toEqual({ id: "u1", n: 1 });
+        expect(state["urn:person1"].children).toBeInstanceOf(Set);
-        expect(state.users.u2).toEqual({ id: "u2", n: 2 });
     });
-    test("merge object entries into existing object-set", () => {
+
-        const state: any = { users: { u1: { id: "u1", n: 1 } } };
+    test("add object to Set with @id", () => {
+        const state: any = { "urn:person1": { children: new Set() } };
         const diff: Patch[] = [
+            // First patch creates the object in the Set
             {
                 op: "add",
-                valType: "set",
+                valType: "object",
-                path: p("users"),
+                path: p("urn:person1", "children", "urn:child1"),
-                value: { u2: { id: "u2", n: 2 } },
+            },
+            // Second patch adds the @id property
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "@id"),
+                value: "urn:child1",
             },
         ];
         applyDiff(state, diff);
-        expect(Object.keys(state.users).sort()).toEqual(["u1", "u2"]);
+        const children = state["urn:person1"].children;
+        expect(children).toBeInstanceOf(Set);
+        expect(children.size).toBe(1);
+        const child = [...children][0];
+        expect(child["@id"]).toBe("urn:child1");
     });
-    test("remove object entries from object-set", () => {
+
-        const state: any = { users: { u1: {}, u2: {}, u3: {} } };
+    test("add properties to object in Set", () => {
+        const obj = { "@id": "urn:child1" };
+        const state: any = { "urn:person1": { children: new Set([obj]) } };
         const diff: Patch[] = [
             {
-                op: "remove",
+                op: "add",
-                valType: "set",
+                path: p("urn:person1", "children", "urn:child1", "name"),
-                path: p("users"),
+                value: "Alice",
-                value: ["u1", "u3"],
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "age"),
+                value: 10,
             },
         ];
         applyDiff(state, diff);
-        expect(Object.keys(state.users)).toEqual(["u2"]);
+        const child = [...state["urn:person1"].children][0];
+        expect(child.name).toBe("Alice");
+        expect(child.age).toBe(10);
     });
-    test("adding primitives to existing object-set replaces with Set", () => {
+
-        const state: any = { mixed: { a: {}, b: {} } };
+    test("remove object from Set by @id", () => {
+        const obj1 = { "@id": "urn:child1", name: "Alice" };
+        const obj2 = { "@id": "urn:child2", name: "Bob" };
+        const state: any = {
+            "urn:person1": { children: new Set([obj1, obj2]) },
+        };
         const diff: Patch[] = [
-            { op: "add", valType: "set", path: p("mixed"), value: [1, 2] },
+            { op: "remove", path: p("urn:person1", "children", "urn:child1") },
         ];
         applyDiff(state, diff);
-        expect(state.mixed).toBeInstanceOf(Set);
+        const children = state["urn:person1"].children;
-        expect([...state.mixed]).toEqual([1, 2]);
+        expect(children.size).toBe(1);
+        const remaining = [...children][0];
+        expect(remaining["@id"]).toBe("urn:child2");
+    });
+
+    test("create nested Set (multi-valued property within object in Set)", () => {
+        const parent: any = { "@id": "urn:parent1" };
+        const state: any = { root: { parents: new Set([parent]) } };
+        const diff: Patch[] = [
+            {
+                op: "add",
+                valType: "object",
+                path: p("root", "parents", "urn:parent1", "children"),
+            },
+            {
+                op: "add",
+                valType: "object",
+                path: p(
+                    "root",
+                    "parents",
+                    "urn:parent1",
+                    "children",
+                    "urn:child1"
+                ),
+            },
+            {
+                op: "add",
+                path: p(
+                    "root",
+                    "parents",
+                    "urn:parent1",
+                    "children",
+                    "urn:child1",
+                    "@id"
+                ),
+                value: "urn:child1",
+            },
+        ];
+        applyDiff(state, diff);
+        const nestedChildren = parent.children;
+        expect(nestedChildren).toBeInstanceOf(Set);
+        expect(nestedChildren.size).toBe(1);
     });
 });
 
 describe("applyDiff - object & literal operations", () => {
-    test("add object (create empty object)", () => {
+    test("create single object (with @id)", () => {
+        const state: any = { "urn:person1": {} };
+        const diff: Patch[] = [
+            { op: "add", path: p("urn:person1", "address"), valType: "object" },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "@id"),
+                value: "urn:addr1",
+            },
+        ];
+        applyDiff(state, diff);
+        expect(state["urn:person1"].address).toEqual({ "@id": "urn:addr1" });
+        expect(state["urn:person1"].address).not.toBeInstanceOf(Set);
+    });
+
+    test("create multi-object container (without @id) -> Set", () => {
+        const state: any = { "urn:person1": {} };
+        const diff: Patch[] = [
+            {
+                op: "add",
+                path: p("urn:person1", "addresses"),
+                valType: "object",
+            },
+        ];
+        applyDiff(state, diff);
+        expect(state["urn:person1"].addresses).toBeInstanceOf(Set);
+    });
+
+    test("add object (create empty object with @id)", () => {
         const state: any = {};
         const diff: Patch[] = [
             { op: "add", path: p("address"), valType: "object" },
+            { op: "add", path: p("address", "@id"), value: "urn:addr1" },
         ];
         applyDiff(state, diff);
-        expect(state.address).toEqual({});
+        expect(state.address).toEqual({ "@id": "urn:addr1" });
+        expect(state.address).not.toBeInstanceOf(Set);
     });
-    test("add nested object path with ensurePathExists", () => {
+    test("add nested object path with ensurePathExists and @id", () => {
         const state: any = {};
         const diff: Patch[] = [
             { op: "add", path: p("a", "b", "c"), valType: "object" },
+            { op: "add", path: p("a", "b", "c", "@id"), value: "urn:c1" },
         ];
         applyDiff(state, diff, true);
-        expect(state.a.b.c).toEqual({});
+        expect(state.a.b.c).toEqual({ "@id": "urn:c1" });
+        expect(state.a.b.c).not.toBeInstanceOf(Set);
     });
     test("add primitive value", () => {
         const state: any = { address: {} };
@@ -156,23 +251,46 @@ describe("applyDiff - object & literal operations", () => {
 describe("applyDiff - multiple mixed patches in a single diff", () => {
     test("sequence of mixed set/object/literal add & remove", () => {
         const state: any = {
-            users: { u1: { id: "u1" } },
+            "urn:person1": {},
             tags: new Set(["old"]),
         };
         const diff: Patch[] = [
+            // Create multi-object Set
             {
                 op: "add",
-                valType: "set",
+                valType: "object",
-                path: p("users"),
+                path: p("urn:person1", "addresses"),
-                value: { u2: { id: "u2" } },
+            },
+            {
+                op: "add",
+                valType: "object",
+                path: p("urn:person1", "addresses", "urn:addr1"),
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "addresses", "urn:addr1", "@id"),
+                value: "urn:addr1",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "addresses", "urn:addr1", "street"),
+                value: "Main St",
             },
+            // Create single object
             { op: "add", path: p("profile"), valType: "object" },
+            { op: "add", path: p("profile", "@id"), value: "urn:profile1" },
             { op: "add", path: p("profile", "name"), value: "Alice" },
+            // Primitive set operations
             { op: "add", valType: "set", path: p("tags"), value: ["new"] },
             { op: "remove", valType: "set", path: p("tags"), value: "old" },
         ];
-        applyDiff(state, diff);
+        applyDiff(state, diff); // Enable ensurePathExists for nested object creation
-        expect(Object.keys(state.users).sort()).toEqual(["u1", "u2"]);
+        expect(state["urn:person1"].addresses).toBeInstanceOf(Set);
+        expect(state["urn:person1"].addresses.size).toBe(1);
+        const addr = [...state["urn:person1"].addresses][0];
+        expect(addr["@id"]).toBe("urn:addr1");
+        expect(addr.street).toBe("Main St");
+        expect(state.profile["@id"]).toBe("urn:profile1");
         expect(state.profile.name).toBe("Alice");
         expect([...state.tags]).toEqual(["new"]);
     });
@@ -180,8 +298,11 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
     test("complex nested path creation and mutations with ensurePathExists", () => {
         const state: any = {};
         const diff: Patch[] = [
+            // Create b as a single object (with @id)
             { op: "add", path: p("a", "b"), valType: "object" },
+            { op: "add", path: p("a", "b", "@id"), value: "urn:b1" },
             { op: "add", path: p("a", "b", "c"), value: 1 },
+            // Create a primitive set
             {
                 op: "add",
                 valType: "set",
@@ -193,6 +314,7 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
             { op: "remove", path: p("a", "b", "c") },
         ];
         applyDiff(state, diff, true);
+        expect(state.a.b["@id"]).toBe("urn:b1");
         expect(state.a.b.c).toBeUndefined();
         expect(state.a.b.d).toBe(2);
         expect(state.a.nums).toBeInstanceOf(Set);
@@ -200,20 +322,166 @@ describe("applyDiff - multiple mixed patches in a single diff", () => {
     });
 });
 
-describe("applyDiff - ignored / invalid scenarios", () => {
+describe("applyDiff - complete workflow example", () => {
-    test("skip patch with non-leading slash path", () => {
+    test("full example: create person with single address and multiple children", () => {
         const state: any = {};
         const diff: Patch[] = [
-            { op: "add", path: "address/street", value: "x" },
+            // Create root person object
+            { op: "add", path: p("urn:person1"), valType: "object" },
+            { op: "add", path: p("urn:person1", "@id"), value: "urn:person1" },
+            { op: "add", path: p("urn:person1", "name"), value: "John" },
+
+            // Add single address object
+            { op: "add", path: p("urn:person1", "address"), valType: "object" },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "@id"),
+                value: "urn:addr1",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "street"),
+                value: "1st Street",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "address", "country"),
+                value: "Greece",
+            },
+
+            // Create multi-valued children Set
+            {
+                op: "add",
+                path: p("urn:person1", "children"),
+                valType: "object",
+            },
+
+            // Add first child
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1"),
+                valType: "object",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "@id"),
+                value: "urn:child1",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child1", "name"),
+                value: "Alice",
+            },
+
+            // Add second child
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2"),
+                valType: "object",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2", "@id"),
+                value: "urn:child2",
+            },
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2", "name"),
+                value: "Bob",
+            },
+
+            // Add primitive set (tags)
+            {
+                op: "add",
+                valType: "set",
+                path: p("urn:person1", "tags"),
+                value: ["developer", "parent"],
+            },
         ];
-        applyDiff(state, diff);
+
-        expect(state).toEqual({});
+        applyDiff(state, diff); // Enable ensurePathExists to create nested objects
+
+        // Verify person
+        expect(state["urn:person1"]["@id"]).toBe("urn:person1");
+        expect(state["urn:person1"].name).toBe("John");
+
+        // Verify single address (plain object)
+        expect(state["urn:person1"].address).not.toBeInstanceOf(Set);
+        expect(state["urn:person1"].address["@id"]).toBe("urn:addr1");
+        expect(state["urn:person1"].address.street).toBe("1st Street");
+        expect(state["urn:person1"].address.country).toBe("Greece");
+
+        // Verify children Set
+        const children = state["urn:person1"].children;
+        expect(children).toBeInstanceOf(Set);
+        expect(children.size).toBe(2);
+
+        const childrenArray = [...children];
+        const alice = childrenArray.find((c: any) => c["@id"] === "urn:child1");
+        const bob = childrenArray.find((c: any) => c["@id"] === "urn:child2");
+        expect(alice.name).toBe("Alice");
+        expect(bob.name).toBe("Bob");
+
+        // Verify primitive set
+        expect(state["urn:person1"].tags).toBeInstanceOf(Set);
+        expect([...state["urn:person1"].tags].sort()).toEqual([
+            "developer",
+            "parent",
+        ]);
     });
-    test("missing parent without ensurePathExists -> patch skipped and no mutation", () => {
+
-        const state: any = {};
+    test("update and remove operations on complex structure", () => {
-        const diff: Patch[] = [{ op: "add", path: p("a", "b", "c"), value: 1 }];
+        // Start with pre-existing structure
-        applyDiff(state, diff, false);
+        const child1 = { "@id": "urn:child1", name: "Alice" };
-        expect(state).toEqual({});
+        const child2 = { "@id": "urn:child2", name: "Bob" };
+        const state: any = {
+            "urn:person1": {
+                "@id": "urn:person1",
+                name: "John",
+                address: {
+                    "@id": "urn:addr1",
+                    street: "1st Street",
+                    country: "Greece",
+                },
+                children: new Set([child1, child2]),
+                tags: new Set(["developer", "parent"]),
+            },
+        };
+
+        const diff: Patch[] = [
+            // Update address property
+            {
+                op: "add",
+                path: p("urn:person1", "address", "street"),
+                value: "2nd Street",
+            },
+
+            // Remove one child
+            { op: "remove", path: p("urn:person1", "children", "urn:child1") },
+
+            // Update child property
+            {
+                op: "add",
+                path: p("urn:person1", "children", "urn:child2", "age"),
+                value: 12,
+            },
+
+            // Remove tag
+            {
+                op: "remove",
+                valType: "set",
+                path: p("urn:person1", "tags"),
+                value: "developer",
+            },
+        ];
+
+        applyDiff(state, diff);
+
+        expect(state["urn:person1"].address.street).toBe("2nd Street");
+        expect(state["urn:person1"].children.size).toBe(1);
+        expect([...state["urn:person1"].children][0]["@id"]).toBe("urn:child2");
+        expect([...state["urn:person1"].children][0].age).toBe(12);
+        expect([...state["urn:person1"].tags]).toEqual(["parent"]);
     });
 });
 

sdk/js/signals/src/connector/applyDiff.ts

@@ -21,14 +21,8 @@ export interface SetAddPatch {
      * New value for set mutations:
      *  - A single primitive
      *  - An array of primitives
-     *  - An object (id -> object) for object "set" additions
      */
-    value:
+    value: number | string | boolean | (number | string | boolean)[];
-        | number
-        | string
-        | boolean
-        | (number | string | boolean)[]
-        | { [id: string]: object };
 }
 
 export interface SetRemovePatch {
@@ -37,8 +31,8 @@ export interface SetRemovePatch {
     valType: "set";
     /**
      * The value(s) to be removed from the set. Either:
-     *  - A single primitive / id
+     *  - A single primitive
-     *  - An array of primitives / ids
+     *  - An array of primitives
      */
     value: number | string | boolean | (number | string | boolean)[];
 }
@@ -67,57 +61,113 @@ function isPrimitive(v: unknown): v is string | number | boolean {
     );
 }
 
-// TODO: Escape slashes and tildes (~1, ~0)
+/**
+ * Find an object in a Set by its @id property.
+ * Returns the object if found, otherwise undefined.
+ */
+function findInSetById(set: Set<any>, id: string): any | undefined {
+    // TODO: We could optimize that by leveraging the key @id to object mapping in sets of deepSignals.
+
+    for (const item of set) {
+        if (typeof item === "object" && item !== null && item["@id"] === id) {
+            return item;
+        }
+    }
+    return undefined;
+}
+
 /**
  * Apply a diff to an object.
  *
- *  * The syntax is inspired by RFC 6902 but it is not compatible.
+ * The syntax is inspired by RFC 6902 but it is not compatible.
+ *
+ * It supports Sets for multi-valued properties:
+ *   - Primitive values are added as Sets (Set<string | number | boolean>)
+ *   - Multi-valued objects are stored in Sets, accessed by their @id property
+ *   - Single objects are plain objects with an @id property
+ *
+ * Path traversal:
+ *   - When traversing through a Set, the path segment is treated as an @id to find the object
+ *   - When traversing through a plain object, the path segment is a property name
  *
- * It supports sets:
- *   - Primitive values are added as sets,
- *   - Sets of objects are represented as objects with their id being the key.
  * @example operations
  *   ```jsonc
- *     // Add one or more objects to a set.
+ *     // === SINGLE OBJECT ===
- *     { "op": "add", "type": "set", "path": "/address", "value": { "ID1": {...}, "ID2": {...} } },
+ *     // Creating a single object (has @id at same level)
- *     // Remove one or more objects from a set.
+ *     { "op": "add", "path": "/urn:example:person1/address", "valType": "object" }
- *     { "op": "remove", "type": "set", "path": "/address", "value": ["ID1","ID2"] }
+ *     { "op": "add", "path": "/urn:example:person1/address/@id", "value": "urn:test:address1" }
- *     // Add primitive types to a sets (URIs are treated just like strings)
+ *     // Adding primitives to single object
- *     { "op": "add", "type": "set", "path": "/address", "value": [1,2,3] }
+ *     { "op": "add", "path": "/urn:example:person1/address/street", "value": "1st street" }
- *     // Remove primitive types from a set.
+ *     { "op": "add", "path": "/urn:example:person1/address/country", "value": "Greece" }
- *     { "op": "remove", "type": "set", "path": "/address", "value": [1,2] }
+ *     // Remove a primitive from object
+ *     { "op": "remove", "path": "/urn:example:person1/address/street" }
+ *     // Remove the entire object
+ *     { "op": "remove", "path": "/urn:example:person1/address" }
  *
- *     // Creating an object.
+ *     // === MULTI-VALUED OBJECTS (Set) ===
- *     { "op": "add", "path": "/address", "type": "object" }
+ *     // Creating a multi-object container (NO @id at this level -> creates Set)
- *     // Adding primitives.
+ *     { "op": "add", "path": "/urn:example:person1/children", "valType": "object" }
- *     { "op": "add", "path": "/address/street", value: "1st street" }
+ *     // Adding an object to the Set (path includes object's @id)
- *     { "op": "add", "path": "/address/country", value: "Greece" }
+ *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1", "valType": "object" }
- *     // Remove a primitive.
+ *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1/@id", "value": "urn:example:child1" }
- *     { "op": "remove", "path": "/address/street" }
+ *     // Adding properties to object in Set
- *     // Remove an object
+ *     { "op": "add", "path": "/urn:example:person1/children/urn:example:child1/name", "value": "Alice" }
- *     { "op": "remove", "path": "/address" }
+ *     // Remove an object from Set
+ *     { "op": "remove", "path": "/urn:example:person1/children/urn:example:child1" }
+ *     // Remove all objects (the Set itself)
+ *     { "op": "remove", "path": "/urn:example:person1/children" }
+ *
+ *     // === PRIMITIVE SETS ===
+ *     // Add primitive types to Sets
+ *     { "op": "add", "valType": "set", "path": "/urn:example:person1/tags", "value": [1,2,3] }
+ *     // Remove primitive types from a Set
+ *     { "op": "remove", "valType": "set", "path": "/urn:example:person1/tags", "value": [1,2] }
  * ```
  *
  * @param currentState The object before the patch
- * @param diff An array of patches to apply to the object.
+ * @param patches An array of patches to apply to the object.
  * @param ensurePathExists If true, create nested objects along the path if the path does not exist.
  */
 export function applyDiff(
     currentState: Record<string, any>,
-    diff: Patch[],
+    patches: Patch[],
     ensurePathExists: boolean = false
 ) {
-    for (const patch of diff) {
+    for (let patchIndex = 0; patchIndex < patches.length; patchIndex++) {
+        const patch = patches[patchIndex];
         if (!patch.path.startsWith("/")) continue;
-        const pathParts = patch.path.slice(1).split("/").filter(Boolean);
+        const pathParts = patch.path
+            .slice(1)
+            .split("/")
+            .filter(Boolean)
+            .map(decodePathSegment);
 
         if (pathParts.length === 0) continue; // root not supported
         const lastKey = pathParts[pathParts.length - 1];
         let parentVal: any = currentState;
         let parentMissing = false;
-        // Traverse only intermediate segments
+        // Traverse only intermediate segments (to leaf object at path)
         for (let i = 0; i < pathParts.length - 1; i++) {
             const seg = pathParts[i];
+
+            // Handle Sets: if parentVal is a Set, find object by @id
+            if (parentVal instanceof Set) {
+                const foundObj = findInSetById(parentVal, seg);
+                if (foundObj) {
+                    parentVal = foundObj;
+                } else if (ensurePathExists) {
+                    // Create new object in the set with this @id
+                    const newObj = { "@id": seg };
+                    parentVal.add(newObj);
+                    parentVal = newObj;
+                } else {
+                    parentMissing = true;
+                    break;
+                }
+                continue;
+            }
+
+            // Handle regular objects
             if (
                 parentVal != null &&
                 typeof parentVal === "object" &&
@@ -147,46 +197,71 @@ export function applyDiff(
             continue;
         }
 
-        // parentVal now should be an object into which we apply lastKey
+        // parentVal now should be an object or Set into which we apply lastKey
-        if (parentVal == null || typeof parentVal !== "object") {
+        if (
+            parentVal == null ||
+            (typeof parentVal !== "object" && !(parentVal instanceof Set))
+        ) {
             console.warn(
-                `[applyDiff] Skipping patch because parent is not an object: ${patch.path}`
+                `[applyDiff] Skipping patch because parent is not an object or Set: ${patch.path}`
             );
             continue;
         }
         const key = lastKey;
-        // If parent does not exist and we cannot create it, skip this patch
-        if (parentVal == null || typeof parentVal !== "object") continue;
 
-        // Handle set additions
+        // Special handling when parent is a Set
-        if (patch.op === "add" && patch.valType === "set") {
+        if (parentVal instanceof Set) {
-            const existing = parentVal[key];
+            // The key represents the @id of an object within the Set
+            const targetObj = findInSetById(parentVal, key);
 
-            // Normalize value
+            // Handle object creation in a Set
-            const raw = (patch as SetAddPatch).value;
+            if (patch.op === "add" && patch.valType === "object") {
-            if (raw == null) continue;
+                if (!targetObj) {
+                    // Determine if this will be a single object or nested Set
+                    const hasId = patches
+                        .at(patchIndex + 1)
+                        ?.path.endsWith("@id");
+                    const newObj: any = hasId ? {} : new Set();
+                    // Pre-assign the @id so subsequent patches can find this object
+                    if (hasId) {
+                        newObj["@id"] = key;
+                    }
+                    parentVal.add(newObj);
+                }
+                continue;
+            }
 
-            // Object-set (id -> object)
+            // Handle remove from Set
-            if (
+            if (patch.op === "remove" && !patch.valType) {
-                typeof raw === "object" &&
+                if (targetObj) {
-                !Array.isArray(raw) &&
+                    parentVal.delete(targetObj);
-                !isPrimitive(raw)
-            ) {
-                if (
-                    existing &&
-                    (existing instanceof Set || Array.isArray(existing))
-                ) {
-                    // Replace incompatible representation
-                    parentVal[key] = {};
                 }
-                if (!parentVal[key] || typeof parentVal[key] !== "object") {
+                continue;
-                    parentVal[key] = {};
             }
-                Object.assign(parentVal[key], raw);
+
+            // All other operations require the target object to exist
+            if (!targetObj) {
+                console.warn(
+                    `[applyDiff] Target object with @id=${key} not found in Set for path: ${patch.path}`
+                );
+                continue;
+            }
+
+            // This shouldn't happen - we handle all intermediate segments in the traversal loop
+            console.warn(
+                `[applyDiff] Unexpected: reached end of path with Set as parent: ${patch.path}`
+            );
             continue;
         }
 
-            // Set primitive(s)
+        // Regular object handling (parentVal is a plain object, not a Set)
+        // Handle primitive set additions
+        if (patch.op === "add" && patch.valType === "set") {
+            const existing = parentVal[key];
+            const raw = (patch as SetAddPatch).value;
+            if (raw == null) continue;
+
+            // Normalize to array of primitives
             const toAdd: (string | number | boolean)[] = Array.isArray(raw)
                 ? raw.filter(isPrimitive)
                 : isPrimitive(raw)
@@ -195,51 +270,48 @@ export function applyDiff(
 
             if (!toAdd.length) continue;
 
+            // Ensure we have a Set, create or add to existing
             if (existing instanceof Set) {
                 for (const v of toAdd) existing.add(v);
-            } else if (
-                existing &&
-                typeof existing === "object" &&
-                !Array.isArray(existing) &&
-                !(existing instanceof Set)
-            ) {
-                // Existing is object-set (objects); adding primitives -> replace with Set
-                parentVal[key] = new Set(toAdd);
             } else {
-                // No existing or incompatible -> create a Set
+                // Create new Set (replaces any incompatible existing value)
                 parentVal[key] = new Set(toAdd);
             }
             continue;
         }
 
-        // Handle set removals
+        // Handle primitive set removals
         if (patch.op === "remove" && patch.valType === "set") {
             const existing = parentVal[key];
             const raw = (patch as SetRemovePatch).value;
             if (raw == null) continue;
+
             const toRemove: (string | number | boolean)[] = Array.isArray(raw)
                 ? raw
                 : [raw];
 
             if (existing instanceof Set) {
                 for (const v of toRemove) existing.delete(v);
-            } else if (existing && typeof existing === "object") {
-                for (const v of toRemove) delete existing[v as any];
             }
             continue;
         }
 
-        // Add object (ensure object exists)
+        // Add object (if it does not exist yet).
+        // Distinguish between single objects and multi-object containers:
+        // - If an @id patch follows for this path, it's a single object -> create {}
+        // - If no @id patch follows, it's a container for multi-valued objects -> create set.
         if (patch.op === "add" && patch.valType === "object") {
-            const cur = parentVal[key];
+            const leafVal = parentVal[key];
-            if (
+            const hasId = patches.at(patchIndex + 1)?.path.endsWith("@id");
-                cur === undefined ||
+
-                cur === null ||
+            // If the leafVal does not exist and it should be a set, create.
-                typeof cur !== "object" ||
+            if (!hasId && !leafVal) {
-                cur instanceof Set
+                parentVal[key] = new Set();
-            ) {
+            } else if (!(typeof leafVal === "object")) {
+                // If the leave does not exist yet (as object), create it.
                 parentVal[key] = {};
             }
+
             continue;
         }
 
@@ -267,3 +339,7 @@ export function applyDiffToDeepSignal(currentState: object, diff: Patch[]) {
         applyDiff(currentState as Record<string, any>, diff);
     });
 }
+
+function decodePathSegment(segment: string): string {
+    return segment.replace("~1", "/").replace("~0", "~");
+}

sdk/js/signals/src/connector/createSignalObjectForShape.ts

@@ -1,7 +1,7 @@
 import type { Diff, Scope } from "../types.js";
 import { applyDiff } from "./applyDiff.js";
 
-import type * as NG from "@ng-org/lib-wasm";
+import * as NG from "@ng-org/lib-wasm";
 
 import { deepSignal, watch, batch } from "@ng-org/alien-deepsignals";
 import type { DeepPatch, DeepSignalObject } from "@ng-org/alien-deepsignals";
@@ -42,9 +42,19 @@ function canonicalScope(scope: Scope | undefined): string {
         : String(scope);
 }
 
+function decodePathSegment(segment: string): string {
+    return segment.replace("~1", "/").replace("~0", "~");
+}
+
+function escapePathSegment(segment: string): string {
+    return segment.replace("~", "~0").replace("/", "~1");
+}
+
 export function deepPatchesToDiff(patches: DeepPatch[]): Diff {
     return patches.map((patch) => {
-        const path = "/" + patch.path.join("/");
+        const path =
+            "/" +
+            patch.path.map((el) => escapePathSegment(el.toString())).join("/");
         return { ...patch, path };
     }) as Diff;
 }
@@ -62,7 +72,10 @@ const recurseArrayToSet = (obj: any): any => {
     }
 };
 
-const setUpConnection = (entry: PoolEntry<any>, wasmMessage: WasmMessage) => {
+const handleInitialResponse = (
+    entry: PoolEntry<any>,
+    wasmMessage: WasmMessage
+) => {
     const { connectionId, initialData } = wasmMessage;
 
     const { signalObject } = entry;
@@ -125,7 +138,7 @@ const onMessage = (event: MessageEvent<WasmMessage>) => {
     if (type === "Stop") return;
 
     if (type === "InitialResponse") {
-        setUpConnection(entry, event.data);
+        handleInitialResponse(entry, event.data);
     } else if (type === "BackendUpdate" && diff) {
         applyDiff(entry.signalObject, diff);
     } else {
@@ -133,6 +146,7 @@ const onMessage = (event: MessageEvent<WasmMessage>) => {
     }
 };
 
+// TODO: Should those be WeekMaps?
 const keyToEntry = new Map<string, PoolEntry<any>>();
 const connectionIdToEntry = new Map<string, PoolEntry<any>>();
 
@@ -150,8 +164,15 @@ const cleanupSignalRegistry =
           })
         : null;
 
+/**
+ *
+ * @param shapeType
+ * @param scope
+ * @returns
+ */
 export function createSignalObjectForShape<T extends BaseType>(
     shapeType: ShapeType<T>,
+    ng: typeof NG,
     scope?: Scope
 ) {
     const scopeKey = canonicalScope(scope);
@@ -168,11 +189,13 @@ export function createSignalObjectForShape<T extends BaseType>(
     }
 
     // Otherwise, create a new signal object and an entry for it.
-    const signalObject = deepSignal<T | {}>({});
+    const signalObject = deepSignal<T | {}>(new Set());
 
+    // Create entry to keep track of the connection with the backend.
     const entry: PoolEntry<T> = {
         key,
         // The id for future communication between wasm and js land.
+        // TODO
         connectionId: `${key}_${new Date().toISOString()}`,
         shapeType,
         scopeKey,
@@ -184,7 +207,7 @@ export function createSignalObjectForShape<T extends BaseType>(
         readyPromise: Promise.resolve(),
         resolveReady: () => {},
         // Function to manually release the connection.
-        // Only releases if no more references exist.
+        // Only releases if refCount is 0.
         release: () => {
             if (entry.refCount > 0) entry.refCount--;
             if (entry.refCount === 0) {

sdk/js/signals/src/connector/ormConnectionHandler.ts

@@ -0,0 +1,217 @@
+import type { Diff as Patches, Scope } from "../types.ts";
+import { applyDiff } from "./applyDiff.ts";
+
+import * as NG from "@ng-org/lib-wasm";
+
+import {
+    deepSignal,
+    watch as watchDeepSignal,
+    batch,
+} from "@ng-org/alien-deepsignals";
+import type {
+    DeepPatch,
+    DeepSignalObject,
+    WatchPatchCallback,
+    WatchPatchEvent,
+} from "@ng-org/alien-deepsignals";
+import type { ShapeType, BaseType } from "@ng-org/shex-orm";
+
+export class OrmConnection<T extends BaseType> {
+    // TODO: WeakMaps?
+    private static idToEntry = new Map<string, OrmConnection<any>>();
+
+    private ng: typeof NG;
+    readonly shapeType: ShapeType<T>;
+    readonly scope: Scope;
+    readonly signalObject: DeepSignalObject<T | {}>;
+    private refCount: number;
+    /*** Identifier as a combination of shape type and scope. Prevents duplications. */
+    private identifier: string;
+    ready: boolean;
+    sessionId: number;
+    suspendDeepWatcher: boolean;
+    readyPromise: Promise<void>;
+    // Promise that resolves once initial data has been applied.
+    resolveReady!: () => void;
+
+    // FinalizationRegistry to clean up connections when signal objects are GC'd.
+    private static cleanupSignalRegistry =
+        typeof FinalizationRegistry === "function"
+            ? new FinalizationRegistry<string>((connectionId) => {
+                  // Best-effort fallback; look up by id and clean
+                  const entry = this.idToEntry.get(connectionId);
+                  if (!entry) return;
+                  entry.release();
+              })
+            : null;
+
+    private constructor(shapeType: ShapeType<T>, scope: Scope, ng: typeof NG) {
+        this.shapeType = shapeType;
+        this.scope = scope;
+        this.ng = ng;
+        this.refCount = 0;
+        this.ready = false;
+        this.suspendDeepWatcher = false;
+        this.identifier = `${shapeType.shape}::${canonicalScope(scope)}`;
+        this.signalObject = deepSignal<T | {}>(new Set(), {
+            addIdToObjects: true,
+            idGenerator: this.generateSubjectIri,
+        });
+
+        // TODO:
+        this.sessionId = 1;
+
+        // Schedule cleanup of the connection when the signal object is GC'd.
+        OrmConnection.cleanupSignalRegistry?.register(
+            this.signalObject,
+            this.identifier,
+            this.signalObject
+        );
+
+        // Add listener to deep signal object to report changes back to wasm land.
+        watchDeepSignal(this.signalObject as T, this.onSignalObjectUpdate);
+
+        // Initialize per-entry readiness promise that resolves in setUpConnection
+        this.readyPromise = new Promise<void>((resolve) => {
+            this.resolveReady = resolve;
+        });
+
+        // Establish connection to wasm land.
+        ng.orm_start(scope, shapeType, this.sessionId, this.onBackendMessage);
+    }
+
+    /**
+     * Get a connection which contains the ORM and lifecycle methods.
+     * @param shapeType
+     * @param scope
+     * @param ng
+     * @returns
+     */
+    public static getConnection<T extends BaseType>(
+        shapeType: ShapeType<T>,
+        scope: Scope,
+        ng: typeof NG
+    ): OrmConnection<T> {
+        const scopeKey = canonicalScope(scope);
+
+        // Unique identifier for a given shape type and scope.
+        const identifier = `${shapeType.shape}::${scopeKey}`;
+
+        // If we already have an object for this shape+scope,
+        // return it and just increase the reference count.
+        // Otherwise, create new one.
+        const connection =
+            OrmConnection.idToEntry.get(identifier) ??
+            new OrmConnection(shapeType, scope, ng);
+
+        connection.refCount += 1;
+
+        return connection;
+    }
+
+    public release() {
+        if (this.refCount > 0) this.refCount--;
+        if (this.refCount === 0) {
+            OrmConnection.idToEntry.delete(this.identifier);
+
+            OrmConnection.cleanupSignalRegistry?.unregister(this.signalObject);
+        }
+    }
+
+    private onSignalObjectUpdate({ patches }: WatchPatchEvent<T>) {
+        if (this.suspendDeepWatcher || !this.ready || !patches.length) return;
+
+        const ormPatches = deepPatchesToDiff(patches);
+
+        this.ng.orm_update(
+            this.scope,
+            this.shapeType.shape,
+            ormPatches,
+            this.sessionId
+        );
+    }
+
+    private onBackendMessage(...message: any) {
+        this.handleInitialResponse(message);
+    }
+
+    private handleInitialResponse(...param: any) {
+        console.log("RESPONSE FROM BACKEND", param);
+
+        // TODO: This will break, just provisionary.
+        const wasmMessage: WasmMessage = param;
+        const { initialData } = wasmMessage;
+
+        // Assign initial data to empty signal object without triggering watcher at first.
+        this.suspendDeepWatcher = true;
+        batch(() => {
+            // Convert arrays to sets and apply to signalObject (we only have sets but can only transport arrays).
+            Object.assign(this.signalObject, recurseArrayToSet(initialData)!);
+        });
+
+        queueMicrotask(() => {
+            this.suspendDeepWatcher = false;
+            // Resolve readiness after initial data is committed and watcher armed.
+            this.resolveReady?.();
+        });
+
+        this.ready = true;
+    }
+    private onBackendUpdate(...params: any) {
+        // Apply diff
+    }
+
+    /** Function to create random subject IRIs for newly created nested objects. */
+    private generateSubjectIri(path: (string | number)[]): string {
+        // Generate random string.
+        let b = Buffer.alloc(33);
+        crypto.getRandomValues(b);
+        const randomString = b.toString("base64url");
+
+        if (path.length > 0 && path[0].toString().startsWith("did:ng:o:")) {
+            // If the root is a nuri, use that as a base IRI.
+            let rootNuri = path[0] as string;
+
+            return rootNuri.substring(0, 9 + 44) + ":q:" + randomString;
+        } else {
+            // Else, just generate a random IRI.
+            return "did:ng:q:" + randomString;
+        }
+    }
+}
+
+//
+//
+
+function escapePathSegment(segment: string): string {
+    return segment.replace("~", "~0").replace("/", "~1");
+}
+
+export function deepPatchesToDiff(patches: DeepPatch[]): Patches {
+    return patches.map((patch) => {
+        const path =
+            "/" +
+            patch.path.map((el) => escapePathSegment(el.toString())).join("/");
+        return { ...patch, path };
+    }) as Patches;
+}
+
+const recurseArrayToSet = (obj: any): any => {
+    if (Array.isArray(obj)) {
+        return new Set(obj.map(recurseArrayToSet));
+    } else if (obj && typeof obj === "object") {
+        for (const key of Object.keys(obj)) {
+            obj[key] = recurseArrayToSet(obj[key]);
+        }
+        return obj;
+    } else {
+        return obj;
+    }
+};
+
+function canonicalScope(scope: Scope | undefined): string {
+    if (scope == null) return "";
+    return Array.isArray(scope)
+        ? scope.slice().sort().join(",")
+        : String(scope);
+}