@twin.org/document-management-service 0.0.3-next.15 → 0.0.3-next.17

package/dist/es/documentManagementService.js

@@ -1,9 +1,9 @@
 import { AuditableItemGraphContexts, AuditableItemGraphTypes } from "@twin.org/auditable-item-graph-models";
 import { BlobStorageContexts } from "@twin.org/blob-storage-models";
 import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { BaseError, Coerce, ComponentFactory, Converter, GeneralError, Guards, Is, NotFoundError, ObjectHelper, Urn } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, Converter, GeneralError, Guards, Is, Mutex, NotFoundError, ObjectHelper, Urn } from "@twin.org/core";
 import { IntegrityAlgorithm, IntegrityHelper, Sha256 } from "@twin.org/crypto";
-import { JsonLdProcessor } from "@twin.org/data-json-ld";
+import { JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
 import { DocumentContexts, DocumentManagementMetricIds, DocumentManagementMetrics, DocumentTypes } from "@twin.org/document-management-models";
 import { SchemaOrgContexts, SchemaOrgDataTypes, SchemaOrgTypes } from "@twin.org/standards-schema-org";
 import { UneceDocumentCodeList } from "@twin.org/standards-unece";
@@ -62,6 +62,7 @@ export class DocumentManagementService {
     }
     /**
      * Register all document management metrics with the telemetry component.
+     * @returns A promise that resolves when metrics have been registered.
      */
     async start() {
         if (Is.undefined(this._telemetryComponent)) {
@@ -91,13 +92,6 @@ export class DocumentManagementService {
         Guards.uint8Array(DocumentManagementService.CLASS_NAME, "blob", blob);
         const contextIds = await ContextIdStore.getContextIds();
         try {
-            // Get the connected vertices first, if one fails we abort the create
-            const connectedVertices = {};
-            if (Is.arrayValue(auditableItemGraphEdges)) {
-                for (const edge of auditableItemGraphEdges) {
-                    connectedVertices[edge.targetId] = await this._auditableItemGraphComponent.get(edge.targetId);
-                }
-            }
             const documentVertex = {
                 "@context": [AuditableItemGraphContexts.Context, AuditableItemGraphContexts.ContextCommon],
                 type: AuditableItemGraphTypes.Vertex
@@ -143,12 +137,44 @@ export class DocumentManagementService {
                 type: AuditableItemGraphTypes.Resource,
                 resourceObject: currentRevision
             });
-            // Add the edges from the document to the items
-            this.updateEdges(documentVertex, auditableItemGraphEdges);
+            // Add the outgoing edges from the document vertex to each connected item
+            if (Is.arrayValue(auditableItemGraphEdges)) {
+                documentVertex.edges ??= [];
+                for (const aigEdge of auditableItemGraphEdges) {
+                    documentVertex.edges.push({
+                        "@context": AuditableItemGraphContexts.Context,
+                        type: AuditableItemGraphTypes.Edge,
+                        targetId: aigEdge.targetId,
+                        edgeRelationships: ["document"]
+                    });
+                }
+            }
             // And create the vertex
             const vertexId = await this._auditableItemGraphComponent.create(ObjectHelper.removeEmptyProperties(documentVertex));
-            // Now add the edges to the connected vertices
-            await this.updateConnectedEdges(connectedVertices, vertexId, [], auditableItemGraphEdges, documentId, documentIdFormat);
+            // Now add the edges to the connected vertices.
+            // isCreatePath = true enables fail-fast + rollback if a target vertex is missing.
+            const failingVertexId = await this.updateConnectedEdges(vertexId, auditableItemGraphEdges ?? [], [], documentId, documentIdFormat, true);
+            if (Is.stringValue(failingVertexId)) {
+                // At least one connected vertex was missing. Back-edges already written have been
+                // rolled back by updateConnectedEdges. Best-effort cleanup: remove the orphaned
+                // blob and soft-delete the document resource so the vertex is left empty.
+                try {
+                    await this._blobStorageComponent.remove(blobStorageId);
+                }
+                catch { }
+                try {
+                    await this._auditableItemGraphComponent.updatePartial({
+                        "@context": [
+                            AuditableItemGraphContexts.Context,
+                            AuditableItemGraphContexts.ContextCommon
+                        ],
+                        id: vertexId,
+                        resourcePatches: { remove: [currentRevision.id] }
+                    });
+                }
+                catch { }
+                throw new NotFoundError(DocumentManagementService.CLASS_NAME, "connectedVertexNotFound", failingVertexId);
+            }
             await MetricHelper.metricIncrement(this._telemetryComponent, DocumentManagementMetricIds.DocumentsCreated, { hasAttestation: Is.stringValue(currentRevision.attestationId) });
             return vertexId;
         }
@@ -166,11 +192,18 @@ export class DocumentManagementService {
      * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
      * @param blob The data to update the document with.
      * @param annotationObject Additional information to associate with the document.
-     * @param auditableItemGraphEdges The auditable item graph vertices to connect the document to, if undefined retains current connections.
-     * @returns Nothing.
+     * @param auditableItemGraphEdges Explicit edge delta to apply. If undefined, existing connections
+     * are retained unchanged. Use `add` to create new connections and `remove` to disconnect existing
+     * ones by their target vertex id. To update alias metadata on an already-connected vertex, include
+     * it in `add` with the updated `aliasAnnotationObject` — AIG's alias patch is an upsert, so the
+     * alias is updated in place without creating a duplicate back-edge.
+     * @param auditableItemGraphEdges.add Connections to add; each creates a back-edge on the connected vertex.
+     * @param auditableItemGraphEdges.remove Target vertex IDs to disconnect; their back-edges are removed.
+     * @returns A promise that resolves when the document has been updated.
      */
-    async update(auditableItemGraphDocumentId, blob, annotationObject, auditableItemGraphEdges) {
+    async updatePartial(auditableItemGraphDocumentId, blob, annotationObject, auditableItemGraphEdges) {
         Urn.guard(DocumentManagementService.CLASS_NAME, "auditableItemGraphDocumentId", auditableItemGraphDocumentId);
+        await Mutex.lock(auditableItemGraphDocumentId, { throwOnTimeout: true });
         try {
             const documentVertex = await this._auditableItemGraphComponent.get(auditableItemGraphDocumentId, { includeDeleted: true });
             if (Is.empty(documentVertex.resources)) {
@@ -184,23 +217,7 @@ export class DocumentManagementService {
             }
             // If auditableItemGraphEdges is undefined we are not updating the edges
             // an empty array can be passed to remove all edges
-            const connectedVertices = {};
-            if (Is.array(auditableItemGraphEdges)) {
-                // Get the updated connected vertices first, if one fails we abort the update
-                for (const edge of auditableItemGraphEdges) {
-                    connectedVertices[edge.targetId] = await this._auditableItemGraphComponent.get(edge.targetId);
-                }
-                // Also get the current edges in case some need disconnecting
-                if (Is.arrayValue(documents.entries.edges)) {
-                    for (const edgeId of documents.entries.edges) {
-                        // If we haven't retrieved the edge then it must be one that needs removing
-                        if (Is.empty(connectedVertices[edgeId])) {
-                            connectedVertices[edgeId] = await this._auditableItemGraphComponent.get(edgeId);
-                        }
-                    }
-                }
-            }
-            let updatedVertex = false;
+            const resourcePatchesAdd = [];
             let blobRevisionCreated = false;
             let newRevisionHasAttestation = false;
             // If the blob is set and its hash has changed then we create a new revision
@@ -214,40 +231,87 @@ export class DocumentManagementService {
                     newRevision.id = this.createDocumentId(newRevision.documentId, newRevision.documentRevision);
                     newRevision.integrity = newIntegrity;
                     newRevision.blobStorageId = blobStorageId;
-                    newRevision.annotationObject = annotationObject;
+                    if (!Is.empty(annotationObject)) {
+                        newRevision.annotationObject = annotationObject;
+                    }
                     if (Is.stringValue(latestRevision.attestationId)) {
                         newRevision.attestationId = await this.createAttestation(newRevision);
                     }
-                    documentVertex.resources.push({
+                    resourcePatchesAdd.push({
                         "@context": AuditableItemGraphContexts.Context,
                         type: AuditableItemGraphTypes.Resource,
-                        resourceObject: newRevision
+                        resourceObject: JsonLdHelper.toNodeObject(newRevision)
                     });
                     newRevisionHasAttestation = Is.stringValue(newRevision.attestationId);
                     blobRevisionCreated = true;
-                    updatedVertex = true;
+                }
+                else if (Is.stringValue(latestRevision.dateDeleted)) {
+                    // Same content as the most recent (soft-deleted) revision — restore it.
+                    const restoredRevision = ObjectHelper.clone(latestRevision);
+                    delete restoredRevision.dateDeleted;
+                    if (!Is.empty(annotationObject)) {
+                        restoredRevision.annotationObject = annotationObject;
+                    }
+                    resourcePatchesAdd.push({
+                        "@context": AuditableItemGraphContexts.Context,
+                        type: AuditableItemGraphTypes.Resource,
+                        resourceObject: JsonLdHelper.toNodeObject(restoredRevision)
+                    });
+                    blobRevisionCreated = true;
                 }
             }
-            // If the blob wasn't updated but the annotation object has then update the current revision
-            // instead of creating a new one
-            if (!updatedVertex &&
+            // If the blob wasn't updated but the annotation object was explicitly provided and has
+            // changed, update the current revision instead of creating a new one.
+            // Undefined means "no change" in patch semantics — it does not clear the annotation.
+            if (!blobRevisionCreated &&
+                !Is.empty(annotationObject) &&
                 !ObjectHelper.equal(latestRevision.annotationObject, annotationObject)) {
-                updatedVertex = true;
                 latestRevision.annotationObject = annotationObject;
                 latestRevision.dateModified = new Date(Date.now()).toISOString();
+                resourcePatchesAdd.push(ObjectHelper.removeEmptyProperties({
+                    "@context": AuditableItemGraphContexts.Context,
+                    type: AuditableItemGraphTypes.Resource,
+                    resourceObject: JsonLdHelper.toNodeObject(latestRevision)
+                }));
             }
-            const existingEdgeIds = documentVertex.edges?.map(e => e.targetId) ?? [];
-            // Update the edges from the document to the items
-            const edgesUpdated = this.updateEdges(documentVertex, auditableItemGraphEdges);
-            if (edgesUpdated) {
-                updatedVertex = true;
-            }
-            if (updatedVertex) {
-                await this._auditableItemGraphComponent.update(ObjectHelper.removeEmptyProperties(documentVertex));
+            // Build document-vertex edge patches directly from the explicit delta.
+            const edgesToAdd = auditableItemGraphEdges?.add ?? [];
+            const edgeTargetIdsToRemove = auditableItemGraphEdges?.remove ?? [];
+            const hasEdgeChanges = !Is.empty(auditableItemGraphEdges) &&
+                (edgesToAdd.length > 0 || edgeTargetIdsToRemove.length > 0);
+            const documentEdgePatchesAdd = edgesToAdd.map(aigEdge => ({
+                "@context": AuditableItemGraphContexts.Context,
+                type: AuditableItemGraphTypes.Edge,
+                targetId: aigEdge.targetId,
+                edgeRelationships: ["document"]
+            }));
+            // Resolve remove targetIds to stored edge IDs for the document vertex patch.
+            const documentEdgePatchesRemove = edgeTargetIdsToRemove
+                .map(targetId => documentVertex.edges?.find(e => e.targetId === targetId && Is.empty(e.dateDeleted))?.id)
+                .filter((id) => Is.stringValue(id));
+            if (resourcePatchesAdd.length > 0 || hasEdgeChanges) {
+                const partial = {
+                    "@context": [
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon
+                    ],
+                    id: auditableItemGraphDocumentId
+                };
+                if (resourcePatchesAdd.length > 0) {
+                    partial.resourcePatches = { add: resourcePatchesAdd };
+                }
+                if (hasEdgeChanges) {
+                    partial.edgePatches = {
+                        ...(documentEdgePatchesAdd.length > 0 ? { add: documentEdgePatchesAdd } : {}),
+                        ...(documentEdgePatchesRemove.length > 0 ? { remove: documentEdgePatchesRemove } : {})
+                    };
+                }
+                await this._auditableItemGraphComponent.updatePartial(partial);
             }
-            if (edgesUpdated) {
-                await this.updateConnectedEdges(connectedVertices, auditableItemGraphDocumentId, existingEdgeIds, auditableItemGraphEdges, latestRevision.documentId, latestRevision.documentIdFormat);
+            if (hasEdgeChanges) {
+                await this.updateConnectedEdges(auditableItemGraphDocumentId, edgesToAdd, edgeTargetIdsToRemove, latestRevision.documentId, latestRevision.documentIdFormat);
             }
+            const updatedVertex = resourcePatchesAdd.length > 0 || hasEdgeChanges;
             if (blobRevisionCreated) {
                 await MetricHelper.metricIncrement(this._telemetryComponent, DocumentManagementMetricIds.RevisionsCreated, { hasAttestation: newRevisionHasAttestation });
             }
@@ -261,6 +325,9 @@ export class DocumentManagementService {
             }
             throw new GeneralError(DocumentManagementService.CLASS_NAME, "updateFailed", undefined, error);
         }
+        finally {
+            Mutex.unlock(auditableItemGraphDocumentId);
+        }
     }
     /**
      * Get a document using it's auditable item graph vertex id and optional revision.
@@ -270,6 +337,7 @@ export class DocumentManagementService {
      * @param options.includeBlobStorageData Flag to include the blob storage data for the document, defaults to false.
      * @param options.includeAttestation Flag to include the attestation information for the document, defaults to false.
      * @param options.includeRemoved Flag to include deleted documents, defaults to false.
+     * @param options.includeDeletedEdges Flag to include soft-deleted edges in the response, defaults to false.
      * @param options.extractRuleGroupId If provided will extract data from the document using the specified rule group id.
      * @param options.extractMimeType By default extraction will auto detect the mime type of the document, this can be used to override the detection.
      * @param cursor The cursor to get the next chunk of revisions.
@@ -279,7 +347,14 @@ export class DocumentManagementService {
     async get(auditableItemGraphDocumentId, options, cursor, limit) {
         Urn.guard(DocumentManagementService.CLASS_NAME, "auditableItemGraphDocumentId", auditableItemGraphDocumentId);
         try {
-            const documentVertex = await this._auditableItemGraphComponent.get(auditableItemGraphDocumentId, { includeDeleted: options?.includeRemoved });
+            const documentVertex = await this._auditableItemGraphComponent.get(auditableItemGraphDocumentId, {
+                includeDeleted: (options?.includeRemoved ?? false) || (options?.includeDeletedEdges ?? false)
+            });
+            // If we fetched deleted items to expose edges but the caller did not ask for deleted
+            // documents, strip the deleted resources so they don't appear in the output.
+            if ((options?.includeDeletedEdges ?? false) && !(options?.includeRemoved ?? false)) {
+                documentVertex.resources = documentVertex.resources?.filter(r => Is.empty(r.dateDeleted));
+            }
             // Populate the document and revisions with the options set
             const documents = await this.getDocumentsFromVertex(documentVertex, options, cursor, limit);
             const result = await JsonLdProcessor.compact(documents.entries, documents.entries["@context"]);
@@ -305,7 +380,7 @@ export class DocumentManagementService {
      * @param options.includeAttestation Flag to include the attestation information for the document, defaults to false.
      * @param options.extractRuleGroupId If provided will extract data from the document using the specified rule group id.
      * @param options.extractMimeType By default extraction will auto detect the mime type of the document, this can be used to override the detection.
-     * @returns The documents and revisions if requested, ordered by revision descending, cursor is set if there are more document revisions.
+     * @returns The document for the specified revision.
      */
     async getRevision(auditableItemGraphDocumentId, revision, options) {
         Urn.guard(DocumentManagementService.CLASS_NAME, "auditableItemGraphDocumentId", auditableItemGraphDocumentId);
@@ -336,11 +411,12 @@ export class DocumentManagementService {
      * The document dateDeleted will be set, but can still be queried with the includeRemoved flag.
      * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
      * @param revision The revision of the document to remove.
-     * @returns Nothing.
+     * @returns A promise that resolves when the revision has been removed.
      */
     async removeRevision(auditableItemGraphDocumentId, revision) {
         Urn.guard(DocumentManagementService.CLASS_NAME, "auditableItemGraphDocumentId", auditableItemGraphDocumentId);
-        Guards.number(DocumentManagementService.CLASS_NAME, "revision", revision);
+        Guards.integer(DocumentManagementService.CLASS_NAME, "revision", revision);
+        await Mutex.lock(auditableItemGraphDocumentId, { throwOnTimeout: true });
         try {
             const documentVertex = await this._auditableItemGraphComponent.get(auditableItemGraphDocumentId);
             if (Is.empty(documentVertex.resources)) {
@@ -350,8 +426,19 @@ export class DocumentManagementService {
             if (docRevisionIndex === -1) {
                 throw new NotFoundError(DocumentManagementService.CLASS_NAME, "documentRevisionNotFound", revision.toString());
             }
-            documentVertex.resources.splice(docRevisionIndex, 1);
-            await this._auditableItemGraphComponent.update(documentVertex);
+            const revisionResourceId = documentVertex.resources[docRevisionIndex].resourceObject?.id ??
+                documentVertex.resources[docRevisionIndex].resourceObject?.["@id"];
+            if (!Is.stringValue(revisionResourceId)) {
+                // The revision exists but its stored resource-id is unresolvable — integrity anomaly.
+                throw new GeneralError(DocumentManagementService.CLASS_NAME, "documentRevisionMissingId", {
+                    revision
+                });
+            }
+            await this._auditableItemGraphComponent.updatePartial({
+                "@context": [AuditableItemGraphContexts.Context, AuditableItemGraphContexts.ContextCommon],
+                id: auditableItemGraphDocumentId,
+                resourcePatches: { remove: [revisionResourceId] }
+            });
             await MetricHelper.metricIncrement(this._telemetryComponent, DocumentManagementMetricIds.RevisionsRemoved);
         }
         catch (error) {
@@ -360,6 +447,9 @@ export class DocumentManagementService {
             }
             throw new GeneralError(DocumentManagementService.CLASS_NAME, "removeRevisionFailed", undefined, error);
         }
+        finally {
+            Mutex.unlock(auditableItemGraphDocumentId);
+        }
     }
     /**
      * Find all the document with a specific id.
@@ -386,141 +476,137 @@ export class DocumentManagementService {
         }
     }
     /**
-     * Update the edges of the document vertex.
-     * @param documentVertex The document vertex to update.
-     * @param auditableItemGraphEdges The list of edges to use.
-     * @returns True if the edges were updated.
-     * @internal
-     */
-    updateEdges(documentVertex, auditableItemGraphEdges) {
-        let changed = false;
-        const existingEdgeIds = documentVertex.edges?.map(e => e.targetId) ?? [];
-        if (Is.array(auditableItemGraphEdges)) {
-            for (const aigEdge of auditableItemGraphEdges) {
-                const existingIndex = existingEdgeIds.indexOf(aigEdge.targetId);
-                if (existingIndex !== -1) {
-                    // If the edge already exists then we don't need to add it again
-                    // We just need to remove it from the list of existing ids
-                    // any remaining after this loop will be need to be removed
-                    existingEdgeIds.splice(existingIndex, 1);
-                }
-                else {
-                    const vertexEdge = {
-                        "@context": AuditableItemGraphContexts.Context,
-                        type: AuditableItemGraphTypes.Edge,
-                        targetId: aigEdge.targetId,
-                        edgeRelationships: ["document"]
-                    };
-                    documentVertex.edges ??= [];
-                    documentVertex.edges?.push(vertexEdge);
-                    changed = true;
-                }
-            }
-            // Anything left in the existingEdgeIds array means they need to be removed
-            if (existingEdgeIds.length > 0 && Is.array(documentVertex.edges)) {
-                for (const existingEdgeId of existingEdgeIds) {
-                    const existingIndex = documentVertex.edges.findIndex(e => e.targetId === existingEdgeId);
-                    if (existingIndex !== -1) {
-                        documentVertex.edges.splice(existingIndex, 1);
-                        changed = true;
-                    }
-                }
-            }
-        }
-        return changed;
-    }
-    /**
-     * Update the edges.
-     * @param connectedVertices The connected vertices for the edges.
+     * Update the edges on connected vertices using non-destructive patch operations.
+     * Uses updatePartial so AIG's per-vertex Mutex serialises concurrent callers.
+     *
+     * On the **create path** (`isCreatePath = true`) the method is fail-fast:
+     * if any back-edge write fails (target vertex does not exist), all back-edges
+     * already written in this call are removed (best-effort rollback) and the
+     * failing target vertex ID is returned so the caller can surface a meaningful error.
+     *
+     * On the **update path** each missing vertex is caught individually; the remaining
+     * updates continue and `undefined` is always returned.
      * @param auditableItemGraphDocumentId The document id to use.
-     * @param documentVertex The document vertex to update.
-     * @param auditableItemGraphEdges The list of edges to use.
+     * @param edgesToAdd Connections to add — each connected vertex receives a new back-edge.
+     * @param edgeTargetIdsToRemove Target vertex IDs to disconnect — their back-edges are removed.
      * @param documentId The document identifier.
      * @param documentIdFormat The format of the document identifier.
+     * @param isCreatePath When true, enables fail-fast + rollback semantics.
+     * @returns The failing target vertex ID when `isCreatePath` is true and a write fails;
+     * `undefined` on success or when called from the update path.
      * @internal
      */
-    async updateConnectedEdges(connectedVertices, auditableItemGraphDocumentId, existingEdgeIds, auditableItemGraphEdges, documentId, documentIdFormat) {
-        if (Is.array(auditableItemGraphEdges)) {
-            for (const aigEdge of auditableItemGraphEdges) {
-                const connected = connectedVertices[aigEdge.targetId];
-                if (!Is.empty(connected)) {
-                    let updatedConnected = false;
-                    const existingIndex = existingEdgeIds.indexOf(aigEdge.targetId);
-                    if (existingIndex !== -1) {
-                        // If the edge already exists we remove it from the list of existing ids
-                        // any remaining after this loop will be need to be disconnected
-                        existingEdgeIds.splice(existingIndex, 1);
-                    }
-                    // Add the edge with the document vertex id if it doesn't already exist
-                    const hasEdge = connected.edges?.some(e => e.targetId === auditableItemGraphDocumentId);
-                    if (!hasEdge) {
-                        const vertexEdge = {
+    async updateConnectedEdges(auditableItemGraphDocumentId, edgesToAdd, edgeTargetIdsToRemove, documentId, documentIdFormat, isCreatePath = false) {
+        // Track which target IDs received a successful back-edge write so we can roll back
+        // if a later write fails (create path only).
+        const writtenTargetIds = [];
+        // Add back-edges to each newly connected vertex.
+        for (const aigEdge of edgesToAdd) {
+            const partial = {
+                "@context": [AuditableItemGraphContexts.Context, AuditableItemGraphContexts.ContextCommon],
+                id: aigEdge.targetId,
+                edgePatches: {
+                    add: [
+                        {
                             "@context": AuditableItemGraphContexts.Context,
                             type: AuditableItemGraphTypes.Edge,
                             targetId: auditableItemGraphDocumentId,
                             edgeRelationships: ["document"]
-                        };
-                        connected.edges ??= [];
-                        connected.edges?.push(vertexEdge);
-                        updatedConnected = true;
-                    }
-                    // Add alias with the document id if option flag is set and it doesn't already exist
-                    if (aigEdge.addAlias) {
-                        const alias = connected.aliases?.find(a => a.id === documentId);
-                        if (Is.empty(alias)) {
-                            // No existing alias, so create one
-                            const vertexAlias = {
-                                "@context": AuditableItemGraphContexts.Context,
-                                type: AuditableItemGraphTypes.Alias,
-                                id: documentId,
-                                aliasFormat: documentIdFormat,
-                                annotationObject: aigEdge.aliasAnnotationObject
-                            };
-                            connected.aliases ??= [];
-                            connected.aliases?.push(vertexAlias);
-                            updatedConnected = true;
                         }
-                        else if (!ObjectHelper.equal(alias.annotationObject, aigEdge.aliasAnnotationObject) ||
-                            documentIdFormat !== alias.aliasFormat) {
-                            // The alias already exists, but the format or annotation object has changed
-                            alias.annotationObject = aigEdge.aliasAnnotationObject;
-                            alias.aliasFormat = documentIdFormat;
-                            updatedConnected = true;
+                    ]
+                }
+            };
+            if (aigEdge.addAlias) {
+                partial.aliasPatches = {
+                    add: [
+                        {
+                            "@context": AuditableItemGraphContexts.Context,
+                            type: AuditableItemGraphTypes.Alias,
+                            id: documentId,
+                            aliasFormat: documentIdFormat,
+                            annotationObject: aigEdge.aliasAnnotationObject
                         }
-                    }
-                    if (updatedConnected) {
-                        await this._auditableItemGraphComponent.update(connected);
-                    }
+                    ]
+                };
+            }
+            if (isCreatePath) {
+                try {
+                    await this._auditableItemGraphComponent.updatePartial(partial);
+                    writtenTargetIds.push(aigEdge.targetId);
+                }
+                catch {
+                    // Rollback all back-edges already written before this failure.
+                    await this.rollbackConnectedEdges(auditableItemGraphDocumentId, writtenTargetIds, documentId);
+                    return aigEdge.targetId;
+                }
+            }
+            else {
+                try {
+                    await this._auditableItemGraphComponent.updatePartial(partial);
+                }
+                catch {
+                    // Best-effort on the update path — swallow to avoid interrupting remaining back-edge writes.
                 }
             }
         }
-        // Anything left in the existingEdgeIds array means they need to be removed
-        if (existingEdgeIds.length > 0) {
-            for (const existingEdgeId of existingEdgeIds) {
-                const connected = connectedVertices[existingEdgeId];
-                if (!Is.empty(connected)) {
-                    let updatedConnected = false;
-                    // Remove the edge from the connected vertex
-                    if (Is.arrayValue(connected.edges)) {
-                        const existingIndex = connected.edges.findIndex(e => e.targetId === auditableItemGraphDocumentId);
-                        if (existingIndex !== -1) {
-                            connected.edges.splice(existingIndex, 1);
-                            updatedConnected = true;
-                        }
-                    }
-                    // Remove the alias from the connected vertex
-                    if (Is.arrayValue(connected.aliases)) {
-                        const existingIndex = connected.aliases.findIndex(e => e.id === documentId);
-                        if (existingIndex !== -1) {
-                            connected.aliases.splice(existingIndex, 1);
-                            updatedConnected = true;
-                        }
-                    }
-                    if (updatedConnected) {
-                        await this._auditableItemGraphComponent.update(connected);
-                    }
+        // Remove back-edges from disconnected vertices.
+        for (const staleTargetId of edgeTargetIdsToRemove) {
+            // Fetch to resolve the stored edge ID; the write is still Mutex-protected.
+            const connected = await this._auditableItemGraphComponent.get(staleTargetId);
+            const edgeId = connected.edges?.find(e => Is.empty(e.dateDeleted) && e.targetId === auditableItemGraphDocumentId)?.id;
+            const hasAlias = Is.arrayValue(connected.aliases) &&
+                connected.aliases.some(a => Is.empty(a.dateDeleted) && a.id === documentId);
+            const partial = {
+                "@context": [AuditableItemGraphContexts.Context, AuditableItemGraphContexts.ContextCommon],
+                id: staleTargetId
+            };
+            if (hasAlias) {
+                partial.aliasPatches = { remove: [documentId] };
+            }
+            if (Is.stringValue(edgeId)) {
+                partial.edgePatches = { remove: [edgeId] };
+            }
+            if (hasAlias || Is.stringValue(edgeId)) {
+                await this._auditableItemGraphComponent.updatePartial(partial);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Best-effort removal of back-edges that were written during a failed create operation.
+     * Errors are silently swallowed to avoid masking the original failure.
+     * @param auditableItemGraphDocumentId The document vertex whose back-edges should be removed.
+     * @param targetIds The connected vertex IDs that received a back-edge.
+     * @param documentId The document identifier used for alias cleanup.
+     * @internal
+     */
+    async rollbackConnectedEdges(auditableItemGraphDocumentId, targetIds, documentId) {
+        for (const targetId of targetIds) {
+            try {
+                const connected = await this._auditableItemGraphComponent.get(targetId);
+                const edgeId = connected.edges?.find(e => Is.empty(e.dateDeleted) && e.targetId === auditableItemGraphDocumentId)?.id;
+                const hasAlias = Is.arrayValue(connected.aliases) &&
+                    connected.aliases.some(a => Is.empty(a.dateDeleted) && a.id === documentId);
+                const partial = {
+                    "@context": [
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon
+                    ],
+                    id: targetId
+                };
+                if (hasAlias) {
+                    partial.aliasPatches = { remove: [documentId] };
+                }
+                if (Is.stringValue(edgeId)) {
+                    partial.edgePatches = { remove: [edgeId] };
+                }
+                if (hasAlias || Is.stringValue(edgeId)) {
+                    await this._auditableItemGraphComponent.updatePartial(partial);
                 }
             }
+            catch {
+                // Best-effort — do not let cleanup errors mask the original failure.
+            }
         }
     }
     /**
@@ -530,6 +616,7 @@ export class DocumentManagementService {
      * @param options.includeBlobStorageMetadata Flag to include the blob storage metadata for the document, defaults to false.
      * @param options.includeBlobStorageData Flag to include the blob storage data for the document, defaults to false.
      * @param options.includeAttestation Flag to include the attestation information for the document, defaults to false.
+     * @param options.includeDeletedEdges Flag to include soft-deleted edges in the response, defaults to false.
      * @param options.extractRuleGroupId If provided will extract data from the document using the specified rule group id.
      * @param options.extractMimeType By default extraction will auto detect the mime type of the document, this can be used to override the detection.
      * @param cursor The cursor to get the next chunk of revisions.
@@ -605,7 +692,8 @@ export class DocumentManagementService {
         if (Is.arrayValue(documentVertex.edges)) {
             docList.edges ??= [];
             for (const edge of documentVertex.edges) {
-                if (Is.object(edge)) {
+                if (Is.object(edge) &&
+                    ((options?.includeDeletedEdges ?? false) || Is.empty(edge.dateDeleted))) {
                     docList.edges.push(edge.targetId);
                 }
             }
@@ -619,6 +707,7 @@ export class DocumentManagementService {
      * Create an attestation for the document.
      * @param document The document to create the attestation for.
      * @returns The attestation identifier.
+     * @internal
      */
     async createAttestation(document) {
         const documentAttestation = {