Feature/diff path support (#821)

* feat: add path field to diff response using PathSummary

- Add path field to JsonDiffSerializer.java using PathSummary (enabled by default)
- Add resolveArrayPositions method to convert path like /arr/[] to /arr/[3]
- Add include-data query param to DiffHandler.kt (default false for compact mode)
- Add generateDiff overload to BasicJsonDiff.java that accepts includeData param

This enables the frontend to display diffs with full paths without requiring DeweyIDs.

* fix: update tests for new path field in diff serialization

- Update expected JSON files in basicJsonDiffTest to include path field
- Fix JsonResourceCopy to handle delete as object instead of primitive
  (delete now returns {nodeKey, path, ...} instead of just nodeKey)

* feat: implement delete() in JsonDBItem for sdb:select-item support

Implements the delete() method from UpdatableJsonItem interface,
enabling JSONiq delete expressions to work with sdb:select-item().

Changes:
- Add default delete() implementation in JsonDBItem interface
- Add test testRemoveFromObjectViaSdbSelectItem() to verify functionality

This allows queries like:
  delete json sdb:select-item(jn:doc('db','res'), nodeKey)

Requires Brackit feature/sdb-select-item-delete-support branch.

* feat: implement delete() in JsonDBItem for sdb:select-item support

Implements the delete() method from UpdatableJsonItem interface,
enabling JSONiq delete expressions to work with sdb:select-item().

Changes:
- Add default delete() implementation in JsonDBItem interface
- Add test testRemoveFromObjectViaSdbSelectItem() to verify functionality

This allows queries like:
  delete json sdb:select-item(jn:doc('db','res'), nodeKey)

Requires Brackit feature/sdb-select-item-delete-support branch.

* Update expected diff output to include path fields

The JsonDiffSerializer now includes path information in the diff output
for insert, delete, replace, and update operations. Updated the expected
test output file to match the new format with path fields.

* Fix test

* feat: enable branching from historical revisions

When editing a document opened at a historical revision (e.g., revision 1),
the write transaction is now automatically reverted to that revision before
applying changes. This enables true branching from any point in history.

Changes:
- JsonDBItem.getOrCreateWriteTrx(): New method that gets or creates a write
  transaction and calls revertTo(sourceRevision) if the source document is
  from an older revision than the most recent
- JsonDBItem.delete() and replaceValue(): Now use getOrCreateWriteTrx()
- AbstractJsonDBArray.getReadWriteTrx(): Added revertTo logic
- JsonDBObject.getReadWriteTrx(): Added revertTo logic

This allows users to:
1. View any historical revision in the Explorer
2. Make edits (insert, update, delete)
3. Commit - creates a new revision branching from that historical point
4. All intermediate revisions remain preserved (SirixDB's append-only model)

* Add reference counting to MMStorage to prevent premature arena closure

When MMStorage remaps memory-mapped segments due to file growth, it was
previously closing the old arena immediately, which invalidated any
existing readers still using those segments.

This change:
- Adds ArenaGeneration class to track arena/segments with reference count
- Readers increment ref count when created, decrement when closed
- Old arenas are only closed when their ref count reaches zero
- Fixes 'Already closed' errors in JsonDiffSerializer path resolution

Also reverts the exception-catching workaround in JsonDiffSerializer
since the root cause is now properly addressed.

* fix: use int for revision references length instead of byte

- Changed from writeByte/readByte to writeInt/readInt for the length
  field in REVISION_REFERENCES_NODE serialization
- This supports nodes with more than 255 revision references
- Previously, a byte could only hold 0-255, and due to signed byte
  interpretation, values > 127 caused IndexOutOfBoundsException

* Fix test

* Fix JSONiq bug, replacing two values...

---------

Co-authored-by: Johannes Lichtenberger <johannes.lichtenberger@sirix.io>

Author: JohannesLichtenberger

bundles/sirix-core/src/main/java/io/sirix/diff/JsonDiffSerializer.java

@@ -3,14 +3,18 @@
 import com.google.api.client.util.Objects;
 import com.google.gson.JsonArray;
 import com.google.gson.JsonObject;
+import io.brackit.query.atomic.QNm;
+import io.brackit.query.util.path.Path;
 import io.sirix.api.json.JsonNodeReadOnlyTrx;
 import io.sirix.api.json.JsonResourceSession;
+import io.sirix.index.path.summary.PathSummaryReader;
 import io.sirix.node.NodeKind;
 import io.sirix.service.json.serialize.JsonSerializer;
 
 import java.io.IOException;
 import java.io.StringWriter;
 import java.io.UncheckedIOException;
+import java.util.ArrayDeque;
 import java.util.Collection;
 
 public final class JsonDiffSerializer {
@@ -78,6 +82,9 @@ public String serialize(boolean emitFromDiffAlgorithm) {
 
             insertBasedOnNewRtx(newRtx, jsonInsertDiff);
 
+            // Add path using PathSummary (always available by default)
+            addPathIfAvailable(jsonInsertDiff, newRtx, newRevisionNumber);
+
             if (resourceManager.getResourceConfig().areDeweyIDsStored) {
               final var deweyId = newRtx.getDeweyID();
               jsonInsertDiff.addProperty("deweyID", deweyId.toString());
@@ -92,21 +99,20 @@ public String serialize(boolean emitFromDiffAlgorithm) {
             break;
           case DELETED:
             final var deletedJson = new JsonObject();
+            final var jsonDeletedDiff = new JsonObject();
 
-            if (resourceManager.getResourceConfig().areDeweyIDsStored) {
-              final var jsonDeletedDiff = new JsonObject();
+            jsonDeletedDiff.addProperty("nodeKey", diffTuple.getOldNodeKey());
 
-              jsonDeletedDiff.addProperty("nodeKey", diffTuple.getOldNodeKey());
+            // Add path using PathSummary (always available by default)
+            addPathIfAvailable(jsonDeletedDiff, oldRtx, oldRevisionNumber);
 
+            if (resourceManager.getResourceConfig().areDeweyIDsStored) {
               final var deweyId = oldRtx.getDeweyID();
               jsonDeletedDiff.addProperty("deweyID", deweyId.toString());
               jsonDeletedDiff.addProperty("depth", deweyId.getLevel());
-
-              deletedJson.add("delete", jsonDeletedDiff);
-            } else {
-              deletedJson.addProperty("delete", diffTuple.getOldNodeKey());
             }
 
+            deletedJson.add("delete", jsonDeletedDiff);
             jsonDiffs.add(deletedJson);
             break;
           case REPLACEDNEW:
@@ -118,6 +124,9 @@ public String serialize(boolean emitFromDiffAlgorithm) {
             jsonReplaceDiff.addProperty("oldNodeKey", diffTuple.getOldNodeKey());
             jsonReplaceDiff.addProperty("newNodeKey", diffTuple.getNewNodeKey());
 
+            // Add path using PathSummary (always available by default)
+            addPathIfAvailable(jsonReplaceDiff, newRtx, newRevisionNumber);
+
             if (resourceManager.getResourceConfig().areDeweyIDsStored) {
               final var deweyId = newRtx.getDeweyID();
               jsonReplaceDiff.addProperty("deweyID", deweyId.toString());
@@ -134,6 +143,9 @@ public String serialize(boolean emitFromDiffAlgorithm) {
 
             jsonUpdateDiff.addProperty("nodeKey", diffTuple.getOldNodeKey());
 
+            // Add path using PathSummary (always available by default)
+            addPathIfAvailable(jsonUpdateDiff, newRtx, newRevisionNumber);
+
             if (resourceManager.getResourceConfig().areDeweyIDsStored) {
               final var deweyId = newRtx.getDeweyID();
               jsonUpdateDiff.addProperty("deweyID", deweyId.toString());
@@ -227,4 +239,127 @@ public static void serialize(int newRevision, JsonResourceSession resourceManage
       throw new UncheckedIOException(e);
     }
   }
+
+  /**
+   * Get the path for a node using PathSummary.
+   * Returns null if PathSummary is not enabled or if the path cannot be retrieved.
+   *
+   * @param rtx the read-only transaction positioned at the node
+   * @param revisionNumber the revision number
+   * @return the path string, or null if unavailable
+   */
+  private String getNodePath(JsonNodeReadOnlyTrx rtx, int revisionNumber) {
+    if (!resourceManager.getResourceConfig().withPathSummary) {
+      return null;
+    }
+
+    try (final PathSummaryReader pathReader = resourceManager.openPathSummary(revisionNumber)) {
+      if (!pathReader.moveTo(rtx.getPathNodeKey())) {
+        return null;
+      }
+
+      final var pathNode = pathReader.getPathNode();
+      if (pathNode == null) {
+        return null;
+      }
+
+      final Path<QNm> path = pathReader.getPath();
+      if (path == null) {
+        return null;
+      }
+
+      // Resolve array positions like sdb:path() does
+      return resolveArrayPositions(rtx, path);
+    } catch (final IllegalStateException e) {
+      // Resource may have been closed (e.g., memory-mapped file reader)
+      // This can happen during concurrent operations or cleanup
+      return null;
+    }
+  }
+
+  /**
+   * Resolve array indices in the path to concrete positions.
+   * Converts "/arr/[]" to "/arr/[3]" based on actual sibling position.
+   *
+   * @param rtx the transaction positioned at the node
+   * @param path the path with unresolved array indices
+   * @return the path with resolved array indices
+   */
+  private String resolveArrayPositions(JsonNodeReadOnlyTrx rtx, Path<QNm> path) {
+    final String pathString = path.toString();
+
+    if (!pathString.contains("[]")) {
+      return pathString;
+    }
+
+    // We need to walk up the tree to resolve array positions
+    final var steps = path.steps();
+    final var positions = new ArrayDeque<Integer>();
+
+    // Save current position
+    final long originalNodeKey = rtx.getNodeKey();
+
+    try {
+      for (int i = steps.size() - 1; i >= 0; i--) {
+        final var step = steps.get(i);
+
+        if (step.getAxis() == Path.Axis.CHILD_ARRAY) {
+          positions.addFirst(getArrayPosition(rtx));
+          rtx.moveToParent();
+        } else {
+          rtx.moveToParent();
+        }
+      }
+
+      var result = pathString;
+      for (Integer pos : positions) {
+        if (pos == -1) {
+          // Keep as [] for arrays that are direct children of object keys
+          continue;
+        }
+        result = result.replaceFirst("/\\[]", "/[" + pos + "]");
+      }
+
+      // Replace remaining unresolved positions with []
+      result = result.replaceAll("/\\[-1]", "/[]");
+
+      return result;
+    } finally {
+      // Restore original position
+      rtx.moveTo(originalNodeKey);
+    }
+  }
+
+  /**
+   * Get the array position (index) of the current node among its siblings.
+   *
+   * @param rtx the transaction positioned at the node
+   * @return the 0-based index, or -1 if this is an array directly under an object key
+   */
+  private int getArrayPosition(JsonNodeReadOnlyTrx rtx) {
+    if (rtx.getParentKind() == NodeKind.OBJECT_KEY && rtx.isArray()) {
+      return -1;
+    }
+
+    int index = 0;
+    while (rtx.hasLeftSibling()) {
+      rtx.moveToLeftSibling();
+      index++;
+    }
+    return index;
+  }
+
+  /**
+   * Add path to a diff JSON object if PathSummary is available.
+   *
+   * @param json the JSON object to add the path to
+   * @param rtx the transaction positioned at the node
+   * @param revisionNumber the revision number
+   */
+  private void addPathIfAvailable(JsonObject json, JsonNodeReadOnlyTrx rtx, int revisionNumber) {
+    final String path = getNodePath(rtx, revisionNumber);
+    if (path != null) {
+      json.addProperty("path", path);
+    }
+  }
 }

bundles/sirix-core/src/main/java/io/sirix/io/memorymapped/MMFileReader.java

@@ -69,7 +69,18 @@ public final class MMFileReader extends AbstractReader {
   private final Arena arena;
 
   /**
-   * Constructor.
+   * Arena generation for reference counting. Used when managed by MMStorage.
+   */
+  private final MMStorage.@Nullable ArenaGeneration generation;
+
+  /**
+   * Reference to the storage for releasing the generation. Used when managed by MMStorage.
+   */
+  @Nullable
+  private final MMStorage storage;
+
+  /**
+   * Constructor for standalone reader with its own arena.
    *
    * @param dataFileSegment     memory-mapped segment for the data file
    * @param revisionFileSegment memory-mapped segment for the revisions file
@@ -82,11 +93,32 @@ public final class MMFileReader extends AbstractReader {
   public MMFileReader(final MemorySegment dataFileSegment, final MemorySegment revisionFileSegment,
       final ByteHandler byteHandler, final SerializationType type, final PagePersister pagePersister,
       final Cache<Integer, RevisionFileData> cache, @Nullable final Arena arena) {
+    this(dataFileSegment, revisionFileSegment, byteHandler, type, pagePersister, cache, null, null);
+  }
+
+  /**
+   * Constructor for reader managed by MMStorage with reference counting.
+   *
+   * @param dataFileSegment     memory-mapped segment for the data file
+   * @param revisionFileSegment memory-mapped segment for the revisions file
+   * @param byteHandler         {@link ByteHandler} instance
+   * @param type                serialization type
+   * @param pagePersister       page persister
+   * @param cache               revision file data cache
+   * @param generation          arena generation for reference counting
+   * @param storage             storage for releasing the generation
+   */
+  public MMFileReader(final MemorySegment dataFileSegment, final MemorySegment revisionFileSegment,
+      final ByteHandler byteHandler, final SerializationType type, final PagePersister pagePersister,
+      final Cache<Integer, RevisionFileData> cache, final MMStorage.@Nullable ArenaGeneration generation,
+      @Nullable final MMStorage storage) {
     super(byteHandler, pagePersister, type);
     this.dataFileSegment = requireNonNull(dataFileSegment);
     this.revisionsOffsetFileSegment = requireNonNull(revisionFileSegment);
     this.cache = requireNonNull(cache);
-    this.arena = arena;  // May be null if managed externally (by MMStorage)
+    this.arena = null;  // Not used when managed by MMStorage
+    this.generation = generation;
+    this.storage = storage;
   }
 
   @Override
@@ -161,9 +193,13 @@ public RevisionFileData getRevisionFileData(int revision) {
 
   @Override
   public void close() {
+    // If managed by MMStorage with reference counting, release the generation
+    if (generation != null && storage != null) {
+      storage.releaseGeneration(generation);
+    }
     // Only close the arena if we own it (not null).
     // When arena is null, the storage (MMStorage) owns and manages the shared arena.
-    if (arena != null) {
+    else if (arena != null) {
       arena.close();
     }
   }