@twin.org/auditable-item-graph-service 0.0.3-next.2 → 0.0.3-next.21

package/dist/es/auditableItemGraphService.js

@@ -1,13 +1,15 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { AuditableItemGraphContexts, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
+import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
 import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { ArrayHelper, ComponentFactory, Converter, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
-import { JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
+import { ArrayHelper, Coerce, ComponentFactory, GeneralError, Guards, Is, JsonHelper, Mutex, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
+import { DataTypeHelper } from "@twin.org/data-core";
+import { JsonLdDataTypes, JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
 import { ComparisonOperator, LogicalOperator, SortDirection } from "@twin.org/entity";
 import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
 import { ImmutableProofContexts, ImmutableProofFailure, ImmutableProofTypes } from "@twin.org/immutable-proof-models";
 import { SchemaOrgContexts, SchemaOrgDataTypes, SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import { MetricHelper } from "@twin.org/telemetry-models";
 /**
  * Class for performing auditable item graph operations.
  */
@@ -60,6 +62,11 @@ export class AuditableItemGraphService {
      * @internal
      */
     _eventBusComponent;
+    /**
+     * The telemetry component.
+     * @internal
+     */
+    _telemetryComponent;
     /**
      * Create a new instance of AuditableItemGraphService.
      * @param options The dependencies for the auditable item graph connector.
@@ -68,10 +75,11 @@ export class AuditableItemGraphService {
         this._immutableProofComponent = ComponentFactory.get(options?.immutableProofComponentType ?? "immutable-proof");
         this._vertexStorage = EntityStorageConnectorFactory.get(options?.vertexEntityStorageType ?? "auditable-item-graph-vertex");
         this._changesetStorage = EntityStorageConnectorFactory.get(options?.changesetEntityStorageType ?? "auditable-item-graph-changeset");
-        if (Is.stringValue(options?.eventBusComponentType)) {
-            this._eventBusComponent = ComponentFactory.get(options.eventBusComponentType);
-        }
+        this._eventBusComponent = ComponentFactory.getIfExists(options?.eventBusComponentType);
+        this._telemetryComponent = ComponentFactory.getIfExists(options?.telemetryComponentType);
         SchemaOrgDataTypes.registerRedirects();
+        AuditableItemGraphDataTypes.registerTypes();
+        JsonLdDataTypes.registerTypes();
     }
     /**
      * Returns the class name of the component.
@@ -80,6 +88,15 @@ export class AuditableItemGraphService {
     className() {
         return AuditableItemGraphService.CLASS_NAME;
     }
+    /**
+     * Register all AIG metrics with the telemetry component.
+     */
+    async start() {
+        if (Is.undefined(this._telemetryComponent)) {
+            return;
+        }
+        await MetricHelper.createMetrics(this._telemetryComponent, AuditableItemGraphMetrics);
+    }
     /**
      * Create a new graph vertex.
      * @param vertex The vertex to create.
@@ -93,12 +110,18 @@ export class AuditableItemGraphService {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
         const contextIds = await ContextIdStore.getContextIds();
         try {
+            const id = RandomHelper.generateUuidV7("compact");
+            const schemaValidationFailures = [];
+            await DataTypeHelper.validate("vertex", `${AuditableItemGraphContexts.Namespace}${AuditableItemGraphTypes.Vertex}`, {
+                ...vertex,
+                id
+            }, schemaValidationFailures);
+            Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "vertex", schemaValidationFailures);
             if (Is.object(vertex.annotationObject)) {
                 const validationFailures = [];
                 await JsonLdHelper.validate(vertex.annotationObject, validationFailures);
                 Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "vertex.annotationObject", validationFailures);
             }
-            const id = Converter.bytesToHex(RandomHelper.generate(32), false);
             const context = {
                 now: new Date(Date.now()).toISOString(),
                 contextIds
@@ -115,11 +138,13 @@ export class AuditableItemGraphService {
             await this.updateEdgeList(context, vertexModel, vertex.edges);
             delete originalEntity.aliasIndex;
             delete originalEntity.resourceTypeIndex;
-            await this.addChangeset(context, originalEntity, vertexModel, true);
+            await this.addChangeset(context, originalEntity, vertexModel, true, 0);
+            vertexModel.version = 0;
             await this._vertexStorage.set({
                 ...vertexModel,
                 ...this.buildIndexes(vertexModel)
             });
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerticesCreated);
             const fullId = new Urn(AuditableItemGraphService.NAMESPACE, id).toString();
             await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexCreated, { id: fullId });
             return fullId;
@@ -128,12 +153,124 @@ export class AuditableItemGraphService {
             throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "createFailed", undefined, error);
         }
     }
+    /**
+     * Update a graph vertex (PUT — full replacement of vertex state).
+     * Concurrent updates for the same vertex are serialized via `Mutex` on the vertex id.
+     * @param vertex The vertex to update.
+     * @returns Nothing.
+     */
+    async update(vertex) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "vertex.id", vertex.id);
+        const vertexId = this.parseVertexId(vertex.id);
+        await Mutex.lock(vertexId, { throwOnTimeout: true });
+        try {
+            const contextIds = await ContextIdStore.getContextIds();
+            try {
+                const schemaValidationFailures = [];
+                await DataTypeHelper.validate("vertex", `${AuditableItemGraphContexts.Namespace}${AuditableItemGraphTypes.Vertex}`, vertex, schemaValidationFailures);
+                Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "vertex", schemaValidationFailures);
+                const vertexEntity = await this._vertexStorage.get(vertexId);
+                if (Is.empty(vertexEntity)) {
+                    throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", vertex.id);
+                }
+                if (Is.object(vertex.annotationObject)) {
+                    const validationFailures = [];
+                    await JsonLdHelper.validate(vertex.annotationObject, validationFailures);
+                    Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "vertex.annotationObject", validationFailures);
+                }
+                const context = {
+                    now: new Date(Date.now()).toISOString(),
+                    contextIds
+                };
+                delete vertexEntity.aliasIndex;
+                const originalEntity = ObjectHelper.clone(vertexEntity);
+                const newEntity = ObjectHelper.clone(vertexEntity);
+                // Capture org from context if vertex doesn't have one yet.
+                // Enables ownership transition: when an authenticated user first
+                // interacts with a vertex that was received without an org, the org
+                // is set here and recorded as a patch in the changeset proof.
+                if (!Is.stringValue(newEntity.organizationIdentity)) {
+                    newEntity.organizationIdentity = context.contextIds?.[ContextIdKeys.Organization];
+                }
+                newEntity.annotationObject = vertex.annotationObject;
+                await this.updateAliasList(context, newEntity, vertex.aliases);
+                await this.updateResourceList(context, newEntity, vertex.resources);
+                await this.updateEdgeList(context, newEntity, vertex.edges);
+                await this.persistVertexChanges(context, vertexId, vertex.id, originalEntity, newEntity);
+            }
+            catch (error) {
+                throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "updatingFailed", undefined, error);
+            }
+        }
+        finally {
+            Mutex.unlock(vertexId);
+        }
+    }
+    /**
+     * Partially update a graph vertex (PATCH — explicit list patches; only defined properties applied).
+     * Serialized with `update` via `Mutex` on the same vertex id within this instance.
+     * @param partial The partial vertex update.
+     * @returns Nothing.
+     */
+    async updatePartial(partial) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "partial", partial);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "partial.id", partial.id);
+        const vertexId = this.parseVertexId(partial.id);
+        await Mutex.lock(vertexId, { throwOnTimeout: true });
+        try {
+            const contextIds = await ContextIdStore.getContextIds();
+            try {
+                const vertexEntity = await this._vertexStorage.get(vertexId);
+                if (Is.empty(vertexEntity)) {
+                    throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", partial.id);
+                }
+                if (partial.annotationObject !== undefined && Is.object(partial.annotationObject)) {
+                    const validationFailures = [];
+                    await JsonLdHelper.validate(partial.annotationObject, validationFailures);
+                    Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "partial.annotationObject", validationFailures);
+                }
+                const context = {
+                    now: new Date(Date.now()).toISOString(),
+                    contextIds
+                };
+                delete vertexEntity.aliasIndex;
+                const originalEntity = ObjectHelper.clone(vertexEntity);
+                const newEntity = ObjectHelper.clone(vertexEntity);
+                // Capture org from context if vertex doesn't have one yet.
+                if (!Is.stringValue(newEntity.organizationIdentity)) {
+                    newEntity.organizationIdentity = context.contextIds?.[ContextIdKeys.Organization];
+                }
+                if (partial.annotationObject !== undefined) {
+                    newEntity.annotationObject = partial.annotationObject;
+                }
+                if (partial.aliasPatches !== undefined) {
+                    const aliasPatch = this.validateListPatch("partial.aliasPatches", partial.aliasPatches);
+                    await this.applyAliasPatch(context, newEntity, aliasPatch);
+                }
+                if (partial.resourcePatches !== undefined) {
+                    const resourcePatch = this.validateListPatch("partial.resourcePatches", partial.resourcePatches);
+                    await this.applyResourcePatch(context, newEntity, resourcePatch);
+                }
+                if (partial.edgePatches !== undefined) {
+                    const edgePatch = this.validateListPatch("partial.edgePatches", partial.edgePatches);
+                    await this.applyEdgePatch(context, newEntity, edgePatch);
+                }
+                await this.persistVertexChanges(context, vertexId, partial.id, originalEntity, newEntity);
+            }
+            catch (error) {
+                throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "updatingFailed", undefined, error);
+            }
+        }
+        finally {
+            Mutex.unlock(vertexId);
+        }
+    }
     /**
      * Get a graph vertex.
      * @param id The id of the vertex to get.
      * @param options Additional options for the get operation.
      * @param options.includeDeleted Whether to include deleted/updated aliases, resource, edges, defaults to false.
-     * @param options.includeChangesets Whether to include the changesets of the vertex, defaults to false.
      * @param options.verifySignatureDepth How many signatures to verify, defaults to "none".
      * @returns The vertex if found.
      * @throws NotFoundError if the vertex is not found.
@@ -154,17 +291,13 @@ export class AuditableItemGraphService {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
             const vertexModel = this.vertexEntityToJsonLd(vertexEntity);
-            const includeChangesets = options?.includeChangesets ?? false;
-            const verifySignatureDepth = options?.verifySignatureDepth ?? "none";
+            const verifySignatureDepth = options?.verifySignatureDepth ?? VerifyDepth.None;
             let verified;
-            let changesets;
             if (verifySignatureDepth === VerifyDepth.Current ||
-                verifySignatureDepth === VerifyDepth.All ||
-                includeChangesets) {
+                verifySignatureDepth === VerifyDepth.All) {
                 const verifyResult = await this.verifyChangesets(vertexModel, verifySignatureDepth);
                 verified = verifyResult.verified;
-                changesets = verifyResult.changesets;
-                vertexModel["@context"].push(ImmutableProofContexts.Namespace);
+                vertexModel["@context"].push(ImmutableProofContexts.Context);
             }
             if (!(options?.includeDeleted ?? false)) {
                 if (Is.arrayValue(vertexModel.aliases)) {
@@ -186,9 +319,6 @@ export class AuditableItemGraphService {
                     }
                 }
             }
-            if (includeChangesets) {
-                vertexModel.changesets = changesets;
-            }
             if (verifySignatureDepth !== VerifyDepth.None) {
                 vertexModel.verified = verified;
             }
@@ -200,70 +330,171 @@ export class AuditableItemGraphService {
         }
     }
     /**
-     * Update a graph vertex.
-     * @param vertex The vertex to update.
-     * @param vertex.id The id of the vertex to update.
-     * @param vertex.annotationObject The annotation object for the vertex as JSON-LD.
-     * @param vertex.aliases Alternative aliases that can be used to identify the vertex.
-     * @param vertex.resources The resources attached to the vertex.
-     * @param vertex.edges The edges connected to the vertex.
-     * @returns Nothing.
+     * Get a graph vertex changeset list.
+     * @param id The id of the vertex to get.
+     * @param cursor The optional cursor to get next chunk.
+     * @param limit Limit the number of entities to return.
+     * @param options Additional options for the get operation.
+     * @param options.verifySignatureDepth How many signatures to verify, defaults to "none".
+     * @returns The vertex if found.
+     * @throws NotFoundError if the vertex is not found.
      */
-    async update(vertex) {
-        Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
-        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "vertex.id", vertex.id);
-        const contextIds = await ContextIdStore.getContextIds();
-        const urnParsed = Urn.fromValidString(vertex.id);
+    async getChangesets(id, cursor, limit, options) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        const urnParsed = Urn.fromValidString(id);
         if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
             throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
                 namespace: AuditableItemGraphService.NAMESPACE,
-                id: vertex.id
+                id
             });
         }
         try {
             const vertexId = urnParsed.namespaceSpecific(0);
             const vertexEntity = await this._vertexStorage.get(vertexId);
             if (Is.empty(vertexEntity)) {
-                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", vertex.id);
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
-            if (Is.object(vertex.annotationObject)) {
-                const validationFailures = [];
-                await JsonLdHelper.validate(vertex.annotationObject, validationFailures);
-                Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "vertex.annotationObject", validationFailures);
+            const chunk = await this.verifyChangesetChunk(vertexId, options?.verifySignatureDepth ?? VerifyDepth.None, cursor, limit);
+            if ((options?.verifySignatureDepth ?? VerifyDepth.None) !== VerifyDepth.None) {
+                if (chunk.verified) {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
+                }
+                else {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsFailed);
+                }
             }
-            const context = {
-                now: new Date(Date.now()).toISOString(),
-                contextIds
+            const changesetList = {
+                "@context": [
+                    SchemaOrgContexts.Context,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
+                ],
+                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.ChangesetList],
+                [SchemaOrgTypes.ItemListElement]: chunk.changesets
+            };
+            const result = await JsonLdProcessor.compact(changesetList, changesetList["@context"]);
+            return {
+                changesets: result,
+                cursor: chunk.cursor
             };
-            delete vertexEntity.aliasIndex;
-            const originalEntity = ObjectHelper.clone(vertexEntity);
-            const newEntity = ObjectHelper.clone(vertexEntity);
-            newEntity.annotationObject = vertex.annotationObject;
-            await this.updateAliasList(context, newEntity, vertex.aliases);
-            await this.updateResourceList(context, newEntity, vertex.resources);
-            await this.updateEdgeList(context, newEntity, vertex.edges);
-            const patches = await this.addChangeset(context, originalEntity, newEntity, false);
-            if (patches.length > 0) {
-                newEntity.dateModified = context.now;
-                const indexes = this.buildIndexes(newEntity);
-                await this._vertexStorage.set({
-                    ...newEntity,
-                    ...indexes
-                });
-                await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexUpdated, { id: vertex.id, patches });
-            }
         }
         catch (error) {
-            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "updatingFailed", undefined, error);
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getFailed", undefined, error);
         }
     }
     /**
-     * Remove the verifiable storage for an item.
+     * Get a graph vertex changeset.
      * @param id The id of the vertex to get.
-     * @returns Nothing.
+     * @param options Additional options for the get operation.
+     * @param options.verifySignatureDepth How many signatures to verify, defaults to "none".
+     * @returns The vertex if found.
      * @throws NotFoundError if the vertex is not found.
      */
-    async removeVerifiable(id) {
+    async getChangeset(id, options) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        try {
+            const namespaceSpecificParts = urnParsed.namespaceSpecificParts();
+            const vertexId = namespaceSpecificParts[0];
+            const changesetId = namespaceSpecificParts[2];
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const changesetEntity = await this._changesetStorage.get(changesetId);
+            if (Is.empty(changesetEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "changesetNotFound", id);
+            }
+            const changesetModel = this.changesetEntityToJsonLd(vertexId, changesetEntity);
+            const verifySignatureDepth = options?.verifySignatureDepth ?? VerifyDepth.None;
+            if (verifySignatureDepth !== VerifyDepth.None) {
+                changesetModel["@context"]?.push(ImmutableProofContexts.Context);
+                changesetModel.verification = await this.verifyChangesetSignature(changesetModel);
+                if (changesetModel.verification?.verified) {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
+                }
+                else {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsFailed, {
+                        failureReason: changesetModel.verification?.failure
+                    });
+                }
+            }
+            const result = await JsonLdProcessor.compact(changesetModel, changesetModel["@context"]);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getFailed", undefined, error);
+        }
+    }
+    /**
+     * Get a graph vertex at a specific version.
+     * @param id The id of the vertex.
+     * @param version The version number to retrieve.
+     * @returns The vertex reconstructed at that version.
+     * @throws NotFoundError if the vertex or version is not found.
+     */
+    async getVersion(id, version) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        Guards.integer(AuditableItemGraphService.CLASS_NAME, "version", version);
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        try {
+            const vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const currentVersion = vertexEntity.version ?? 0;
+            if (version > currentVersion || version < 0) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", version.toString());
+            }
+            // Short circuit if requesting the current version to avoid unnecessary changeset retrieval and patching
+            if (version === currentVersion) {
+                const vertexModel = this.vertexEntityToJsonLd(vertexEntity);
+                vertexModel.version = version;
+                return await JsonLdProcessor.compact(vertexModel, vertexModel["@context"]);
+            }
+            const changesets = await this.internalGetChangesets(vertexId, {
+                maxVersion: version
+            });
+            let entityState = {
+                id: vertexEntity.id,
+                dateCreated: vertexEntity.dateCreated,
+                organizationIdentity: vertexEntity.organizationIdentity
+            };
+            for (const changeset of changesets) {
+                entityState = JsonHelper.patch(entityState, changeset.patches);
+            }
+            const vertexModel = this.vertexEntityToJsonLd(entityState);
+            vertexModel.version = version;
+            const result = await JsonLdProcessor.compact(vertexModel, vertexModel["@context"]);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionFailed", undefined, error);
+        }
+    }
+    /**
+     * Get all versions of a graph vertex.
+     * @param id The id of the vertex.
+     * @param options Additional options for the operation.
+     * @param options.after Only return versions created after this ISO 8601 timestamp (exclusive).
+     * @param options.before Only return versions created before this ISO 8601 timestamp (exclusive).
+     * @returns The list of vertex versions.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    async getVersions(id, options) {
         Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
         const urnParsed = Urn.fromValidString(id);
         if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
@@ -274,6 +505,52 @@ export class AuditableItemGraphService {
         }
         try {
             const vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const beforeDate = Coerce.dateTime(options?.before);
+            const afterDate = Coerce.dateTime(options?.after);
+            const allChangesets = await this.internalGetChangesets(vertexId, {
+                before: beforeDate?.toISOString()
+            });
+            const versions = [];
+            for (const changeset of allChangesets) {
+                const changesetDate = Coerce.dateTime(changeset.dateCreated);
+                const afterExcluded = !Is.empty(afterDate) && !Is.empty(changesetDate) && changesetDate <= afterDate;
+                if (!afterExcluded) {
+                    versions.push({
+                        version: changeset.version ?? 0,
+                        dateCreated: changeset.dateCreated
+                    });
+                }
+            }
+            const versionList = {
+                "@context": [
+                    SchemaOrgContexts.Context,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
+                ],
+                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexVersionList],
+                [SchemaOrgTypes.ItemListElement]: versions
+            };
+            return await JsonLdProcessor.compact(versionList, versionList["@context"]);
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionsFailed", undefined, error);
+        }
+    }
+    /**
+     * Remove the proof for an item.
+     * @param id The id of the vertex to remove the proof from.
+     * @returns Nothing.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    async removeProof(id) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        const vertexId = this.parseVertexId(id);
+        await Mutex.lock(vertexId, { throwOnTimeout: true });
+        try {
             const vertexEntity = await this._vertexStorage.get(vertexId);
             if (Is.empty(vertexEntity)) {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
@@ -292,7 +569,7 @@ export class AuditableItemGraphService {
                 ], undefined, changesetsResult?.cursor);
                 for (const changeset of changesetsResult.entities) {
                     if (Is.stringValue(changeset.proofId)) {
-                        await this._immutableProofComponent.removeVerifiable(changeset.proofId);
+                        await this._immutableProofComponent.removeNotarization(changeset.proofId);
                         delete changeset.proofId;
                         await this._changesetStorage.set(changeset);
                     }
@@ -300,7 +577,10 @@ export class AuditableItemGraphService {
             } while (Is.stringValue(changesetsResult.cursor));
         }
         catch (error) {
-            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "removeVerifiableFailed", undefined, error);
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "removeProofFailed", undefined, error);
+        }
+        finally {
+            Mutex.unlock(vertexId);
         }
     }
     /**
@@ -309,7 +589,7 @@ export class AuditableItemGraphService {
      * @param options.id The optional id to look for.
      * @param options.idMode Look in id, alias or both, defaults to both.
      * @param options.idExact Find only exact matches, default to false meaning partial matching.
-     * @param options.includesResourceTypes Include vertices with specific resource types.
+     * @param options.resourceTypes Include vertices with specific resource types.
      * @param conditions Conditions to use in the query.
      * @param orderBy The order for the results, defaults to created.
      * @param orderByDirection The direction for the order, defaults to desc.
@@ -349,8 +629,8 @@ export class AuditableItemGraphService {
                     });
                 }
             }
-            if (Is.arrayValue(options?.includesResourceTypes)) {
-                for (const resourceType of options.includesResourceTypes) {
+            if (Is.arrayValue(options?.resourceTypes)) {
+                for (const resourceType of options.resourceTypes) {
                     combinedConditions.push({
                         property: "resourceTypeIndex",
                         comparison: ComparisonOperator.Includes,
@@ -375,21 +655,87 @@ export class AuditableItemGraphService {
             const models = results.entities.map(e => this.vertexEntityToJsonLd(e));
             const vertexList = {
                 "@context": [
-                    SchemaOrgContexts.Namespace,
-                    AuditableItemGraphContexts.Namespace,
-                    AuditableItemGraphContexts.NamespaceCommon
+                    SchemaOrgContexts.Context,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
                 ],
                 type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexList],
-                [SchemaOrgTypes.ItemListElement]: models,
-                [SchemaOrgTypes.NextItem]: results.cursor
+                [SchemaOrgTypes.ItemListElement]: models
             };
             const result = await JsonLdProcessor.compact(vertexList, vertexList["@context"]);
-            return result;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.QueriesExecuted, {
+                resultCount: models.length,
+                hasMore: Is.stringValue(results.cursor)
+            });
+            return {
+                entries: result,
+                cursor: results.cursor
+            };
         }
         catch (error) {
             throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "queryingFailed", undefined, error);
         }
     }
+    /**
+     * Parse and validate a vertex URN; return the compact storage id.
+     * @param id The vertex URN.
+     * @returns The compact vertex id.
+     * @internal
+     */
+    parseVertexId(id) {
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        return urnParsed.namespaceSpecific(0);
+    }
+    /**
+     * Validate that a PATCH sub-list value is a list patch object, not a bare array.
+     * @param propertyName The property name for error reporting.
+     * @param patch The patch value.
+     * @returns The validated list patch.
+     * @internal
+     */
+    validateListPatch(propertyName, patch) {
+        if (Is.array(patch)) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "listPatchInvalidFormat", {
+                property: propertyName
+            });
+        }
+        Guards.object(AuditableItemGraphService.CLASS_NAME, propertyName, patch);
+        return patch;
+    }
+    /**
+     * Persist vertex changes after update or partial update.
+     * @param context The context for the operation.
+     * @param vertexId The compact vertex id.
+     * @param vertexUrn The vertex URN for events.
+     * @param originalEntity The entity before changes.
+     * @param newEntity The entity after changes.
+     * @internal
+     */
+    async persistVertexChanges(context, vertexId, vertexUrn, originalEntity, newEntity) {
+        const nextVersion = Is.empty(originalEntity.version)
+            ? (await this.internalGetChangesets(vertexId)).length
+            : originalEntity.version + 1;
+        const patches = await this.addChangeset(context, originalEntity, newEntity, false, nextVersion);
+        if (patches.length > 0) {
+            newEntity.dateModified = context.now;
+            newEntity.version = nextVersion;
+            const indexes = this.buildIndexes(newEntity);
+            await this._vertexStorage.set({
+                ...newEntity,
+                ...indexes
+            });
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerticesUpdated, {
+                patchCount: patches.length
+            });
+            await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexUpdated, { id: vertexUrn, patches });
+        }
+    }
     /**
      * Map the vertex entity to JSON-LD.
      * @param vertexEntity The vertex entity.
@@ -399,9 +745,9 @@ export class AuditableItemGraphService {
     vertexEntityToJsonLd(vertexEntity) {
         const model = {
             "@context": [
-                AuditableItemGraphContexts.Namespace,
-                AuditableItemGraphContexts.NamespaceCommon,
-                SchemaOrgContexts.Namespace
+                AuditableItemGraphContexts.Context,
+                AuditableItemGraphContexts.ContextCommon,
+                SchemaOrgContexts.Context
             ],
             type: AuditableItemGraphTypes.Vertex,
             id: new Urn(AuditableItemGraphService.NAMESPACE, vertexEntity.id).toString(),
@@ -415,9 +761,9 @@ export class AuditableItemGraphService {
             for (const aliasEntity of vertexEntity.aliases) {
                 const aliasModel = {
                     "@context": [
-                        AuditableItemGraphContexts.Namespace,
-                        AuditableItemGraphContexts.NamespaceCommon,
-                        SchemaOrgContexts.Namespace
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon,
+                        SchemaOrgContexts.Context
                     ],
                     type: AuditableItemGraphTypes.Alias,
                     id: aliasEntity.id,
@@ -435,9 +781,9 @@ export class AuditableItemGraphService {
             for (const resourceEntity of vertexEntity.resources) {
                 const resourceModel = {
                     "@context": [
-                        AuditableItemGraphContexts.Namespace,
-                        AuditableItemGraphContexts.NamespaceCommon,
-                        SchemaOrgContexts.Namespace
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon,
+                        SchemaOrgContexts.Context
                     ],
                     type: AuditableItemGraphTypes.Resource,
                     id: resourceEntity.id,
@@ -454,9 +800,9 @@ export class AuditableItemGraphService {
             for (const edgeEntity of vertexEntity.edges) {
                 const edgeModel = {
                     "@context": [
-                        AuditableItemGraphContexts.Namespace,
-                        AuditableItemGraphContexts.NamespaceCommon,
-                        SchemaOrgContexts.Namespace
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon,
+                        SchemaOrgContexts.Context
                     ],
                     type: AuditableItemGraphTypes.Edge,
                     id: this.fullEdgeId(vertexEntity.id, edgeEntity.id),
@@ -482,9 +828,9 @@ export class AuditableItemGraphService {
     changesetEntityToJsonLd(vertexId, changesetEntity) {
         const model = {
             "@context": [
-                AuditableItemGraphContexts.Namespace,
-                AuditableItemGraphContexts.NamespaceCommon,
-                SchemaOrgContexts.Namespace
+                AuditableItemGraphContexts.Context,
+                AuditableItemGraphContexts.ContextCommon,
+                SchemaOrgContexts.Context
             ],
             type: AuditableItemGraphTypes.Changeset,
             id: new Urn(AuditableItemGraphService.NAMESPACE, [
@@ -496,9 +842,9 @@ export class AuditableItemGraphService {
             userIdentity: changesetEntity.userIdentity,
             patches: changesetEntity.patches.map(p => ({
                 "@context": [
-                    AuditableItemGraphContexts.Namespace,
-                    AuditableItemGraphContexts.NamespaceCommon,
-                    SchemaOrgContexts.Namespace
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon,
+                    SchemaOrgContexts.Context
                 ],
                 type: AuditableItemGraphTypes.PatchOperation,
                 patchOperation: p.op,
@@ -506,24 +852,61 @@ export class AuditableItemGraphService {
                 patchFrom: p.from,
                 patchValue: p.value
             })),
-            proofId: changesetEntity.proofId
+            proofId: changesetEntity.proofId,
+            version: changesetEntity.version
         };
         return model;
     }
     /**
-     * Update the aliases of a vertex model.
+     * Fetch all changesets for a vertex in ascending date order.
+     * @param vertexId The internal vertex id.
+     * @param options Optional filtering options.
+     * @param options.before Only fetch changesets created strictly before this ISO 8601 timestamp.
+     * @param options.maxVersion Only fetch changesets with version <= this value.
+     * @returns All changeset entities sorted ascending by dateCreated.
+     * @internal
+     */
+    async internalGetChangesets(vertexId, options) {
+        const all = [];
+        let cursor;
+        const conditions = [
+            { property: "vertexId", value: vertexId, comparison: ComparisonOperator.Equals }
+        ];
+        if (Is.stringValue(options?.before)) {
+            conditions.push({
+                property: "dateCreated",
+                value: options.before,
+                comparison: ComparisonOperator.LessThan
+            });
+        }
+        if (!Is.empty(options?.maxVersion)) {
+            conditions.push({
+                property: "version",
+                value: options.maxVersion,
+                comparison: ComparisonOperator.LessThanOrEqual
+            });
+        }
+        do {
+            const result = await this._changesetStorage.query({ conditions, logicalOperator: LogicalOperator.And }, [{ property: "dateCreated", sortDirection: SortDirection.Ascending }], undefined, cursor);
+            all.push(...result.entities);
+            cursor = result.cursor;
+        } while (Is.stringValue(cursor));
+        return all;
+    }
+    /**
+     * Replace the aliases of a vertex model (PUT).
      * @param context The context for the operation.
      * @param vertex The vertex.
-     * @param aliases The aliases to update.
+     * @param aliases The new active alias set.
      * @internal
      */
     async updateAliasList(context, vertex, aliases) {
         const active = vertex.aliases?.filter(a => Is.empty(a.dateDeleted)) ?? [];
-        // The active aliases that are not in the update list should be marked as deleted.
         if (Is.arrayValue(active)) {
             for (const alias of active) {
                 if (!aliases?.find(a => a.id === alias.id)) {
                     alias.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesDeleted);
                 }
             }
         }
@@ -533,6 +916,30 @@ export class AuditableItemGraphService {
             }
         }
     }
+    /**
+     * Apply alias patch operations (PATCH).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @param patch The alias patch.
+     * @internal
+     */
+    async applyAliasPatch(context, vertex, patch) {
+        if (Is.arrayValue(patch.remove)) {
+            for (const removeId of patch.remove) {
+                Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "removeId", removeId);
+                const alias = vertex.aliases?.find(a => a.id === removeId && Is.empty(a.dateDeleted));
+                if (!Is.empty(alias)) {
+                    alias.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesDeleted);
+                }
+            }
+        }
+        if (Is.arrayValue(patch.add)) {
+            for (const alias of patch.add) {
+                await this.updateAlias(context, vertex, alias);
+            }
+        }
+    }
     /**
      * Update an alias in the vertex.
      * @param context The context for the operation.
@@ -544,7 +951,7 @@ export class AuditableItemGraphService {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "alias", alias);
         Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "alias.id", alias.id);
         if (alias.unique ?? false) {
-            const existingVertices = await this.findMatchingVertices(context, vertex.id, alias.id);
+            const existingVertices = await this.findMatchingVertices(vertex.id, alias.id);
             if (existingVertices) {
                 throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "aliasNotUnique", {
                     aliasId: alias.id
@@ -565,23 +972,28 @@ export class AuditableItemGraphService {
                 id: alias.id,
                 aliasFormat: alias.aliasFormat,
                 dateCreated: context.now,
-                annotationObject: alias.annotationObject
+                annotationObject: alias.annotationObject,
+                unique: alias.unique
             };
             vertex.aliases.push(model);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesAdded);
         }
         else if (existing.aliasFormat !== alias.aliasFormat ||
-            !ObjectHelper.equal(existing.annotationObject, alias.annotationObject, false)) {
+            !ObjectHelper.equal(existing.annotationObject, alias.annotationObject, false) ||
+            existing.unique !== alias.unique) {
             // Existing alias found, update the annotationObject.
             existing.dateModified = context.now;
             existing.aliasFormat = alias.aliasFormat;
             existing.annotationObject = alias.annotationObject;
+            existing.unique = alias.unique;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesModified);
         }
     }
     /**
-     * Update the resources of a vertex.
+     * Replace the resources of a vertex (PUT).
      * @param context The context for the operation.
      * @param vertex The vertex.
-     * @param resources The resources to update.
+     * @param resources The new active resource set.
      * @internal
      */
     async updateResourceList(context, vertex, resources) {
@@ -596,11 +1008,11 @@ export class AuditableItemGraphService {
             }
         }
         const active = vertex.resources?.filter(r => Is.empty(r.dateDeleted)) ?? [];
-        // The active resources that are not in the update list should be marked as deleted.
         if (Is.arrayValue(active)) {
             for (const resource of active) {
                 if (!resources?.find(a => this.getResourceId(a) === this.getResourceId(resource))) {
                     resource.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesDeleted);
                 }
             }
         }
@@ -610,6 +1022,30 @@ export class AuditableItemGraphService {
             }
         }
     }
+    /**
+     * Apply resource patch operations (PATCH).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @param patch The resource patch.
+     * @internal
+     */
+    async applyResourcePatch(context, vertex, patch) {
+        if (Is.arrayValue(patch.remove)) {
+            for (const removeId of patch.remove) {
+                Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "removeId", removeId);
+                const resource = vertex.resources?.find(r => this.getResourceId(r) === removeId && Is.empty(r.dateDeleted));
+                if (!Is.empty(resource)) {
+                    resource.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesDeleted);
+                }
+            }
+        }
+        if (Is.arrayValue(patch.add)) {
+            for (const resource of patch.add) {
+                await this.updateResource(context, vertex, resource);
+            }
+        }
+    }
     /**
      * Add a resource to the vertex.
      * @param context The context for the operation.
@@ -635,27 +1071,31 @@ export class AuditableItemGraphService {
                 resourceObject: resource.resourceObject
             };
             vertex.resources.push(model);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesAdded);
         }
         else if (!ObjectHelper.equal(existing.resourceObject, resource.resourceObject, false)) {
             // Existing resource found, update the resourceObject.
             existing.dateModified = context.now;
             existing.resourceObject = resource.resourceObject;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesModified);
         }
     }
     /**
-     * Update the edges of a vertex.
+     * Replace the edges of a vertex (PUT).
      * @param context The context for the operation.
      * @param vertex The vertex.
-     * @param edges The edges to update.
+     * @param edges The new active edge set.
      * @internal
      */
     async updateEdgeList(context, vertex, edges) {
+        // `active` shares element refs with `vertex.edges` (the cloned newEntity); mutating `edge` below is intended.
         const active = vertex.edges?.filter(e => Is.empty(e.dateDeleted)) ?? [];
-        // The active edges that are not in the update list should be marked as deleted.
         if (Is.arrayValue(active)) {
             for (const edge of active) {
-                if (!edges?.find(e => Is.stringValue(e.id) && this.reduceEdgeId(e.id) === edge.id)) {
+                if (!edges?.find(e => this.edgeMatchesStoredEdge(e, edge.id) ||
+                    this.edgeMatchesActiveEdgeByRelationship(e, edge))) {
                     edge.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesDeleted);
                 }
             }
         }
@@ -665,6 +1105,30 @@ export class AuditableItemGraphService {
             }
         }
     }
+    /**
+     * Apply edge patch operations (PATCH).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @param patch The edge patch.
+     * @internal
+     */
+    async applyEdgePatch(context, vertex, patch) {
+        if (Is.arrayValue(patch.remove)) {
+            for (const removeId of patch.remove) {
+                Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "removeId", removeId);
+                const edge = vertex.edges?.find(e => Is.empty(e.dateDeleted) && this.edgeRemoveIdMatches(e.id, removeId));
+                if (!Is.empty(edge)) {
+                    edge.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesDeleted);
+                }
+            }
+        }
+        if (Is.arrayValue(patch.add)) {
+            for (const edge of patch.add) {
+                await this.updateEdge(context, vertex, edge);
+            }
+        }
+    }
     /**
      * Add an edge to the vertex.
      * @param context The context for the operation.
@@ -692,7 +1156,10 @@ export class AuditableItemGraphService {
         Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "edge.annotationObject", validationFailures);
         let findId = Is.stringValue(edge.id) ? this.reduceEdgeId(edge.id) : undefined;
         if (Is.empty(findId)) {
-            findId = Converter.bytesToHex(RandomHelper.generate(32), false);
+            const existingActive = vertex.edges?.find(e => Is.empty(e.dateDeleted) &&
+                e.targetId === edge.targetId &&
+                ArrayHelper.matches(e.edgeRelationships, edge.edgeRelationships));
+            findId = existingActive?.id ?? RandomHelper.generateUuidV7("compact");
         }
         // Try to find an existing edge with the same id.
         const existing = vertex.edges?.find(r => r.id === findId);
@@ -707,6 +1174,7 @@ export class AuditableItemGraphService {
                 edgeRelationships: edge.edgeRelationships
             };
             vertex.edges.push(model);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesAdded);
         }
         else if (existing.targetId !== edge.targetId ||
             !ArrayHelper.matches(existing.edgeRelationships, edge.edgeRelationships) ||
@@ -716,6 +1184,7 @@ export class AuditableItemGraphService {
             existing.dateModified = context.now;
             existing.edgeRelationships = edge.edgeRelationships;
             existing.annotationObject = edge.annotationObject;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesModified);
         }
     }
     /**
@@ -724,27 +1193,36 @@ export class AuditableItemGraphService {
      * @param original The original vertex.
      * @param updated The updated vertex.
      * @param isNew Whether this is a new item.
+     * @param version The version number of the vertex after this changeset.
      * @returns True if there were changes.
      * @internal
      */
-    async addChangeset(context, original, updated, isNew) {
+    async addChangeset(context, original, updated, isNew, version) {
         const patches = JsonHelper.diff(original, updated);
         // If there is a diff set or this is the first time the item is created.
         if (patches.length > 0 || isNew) {
             const changesetEntity = {
-                id: Converter.bytesToHex(RandomHelper.generate(32), false),
+                id: RandomHelper.generateUuidV7("compact"),
                 vertexId: updated.id,
                 dateCreated: context.now,
                 userIdentity: context.contextIds?.[ContextIdKeys.User],
-                patches
+                patches,
+                version
             };
             // Create the JSON-LD object we want to use for the proof
             // this is a subset of fixed properties from the changeset object.
             const reducedChangesetJsonLd = this.changesetEntityToJsonLd(original.id, ObjectHelper.pick(changesetEntity, AuditableItemGraphService._PROOF_KEYS_CHANGESET));
-            // Create the proof for the changeset object
-            changesetEntity.proofId = await this._immutableProofComponent.create(reducedChangesetJsonLd);
-            // Link the verifiable storage id to the changeset
+            // Create the proof for the changeset object only when the vertex has
+            // an owning organisation. Vertices created by inbound unauthenticated
+            // activities (e.g. DSP push via skipAuth inbox) have no org context at
+            // creation time and must not require a proof until a local org claims
+            // ownership through an authenticated interaction.
+            if (Is.stringValue(updated.organizationIdentity)) {
+                changesetEntity.proofId = await this._immutableProofComponent.create(JsonLdHelper.toNodeObject(reducedChangesetJsonLd));
+            }
+            // Link the storage id to the changeset
             await this._changesetStorage.set(changesetEntity);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ChangesetsCreated);
             return patches;
         }
         return [];
@@ -753,63 +1231,99 @@ export class AuditableItemGraphService {
      * Verify the changesets of a vertex.
      * @param vertex The vertex to verify.
      * @param verifySignatureDepth How many signatures to verify.
-     * @param contextIds The context ids to perform the operation with.
      * @internal
      */
-    async verifyChangesets(vertex, verifySignatureDepth, partitionKey) {
+    async verifyChangesets(vertex, verifySignatureDepth) {
         const changesets = [];
-        let changesetsResult;
         let verified = true;
-        const vertexId = Urn.fromValidString(vertex.id);
+        const vertexIdUrn = Urn.fromValidString(vertex.id);
+        const vertexId = vertexIdUrn.namespaceSpecific();
+        let cursor;
         do {
-            changesetsResult = await this._changesetStorage.query({
-                property: "vertexId",
-                value: vertexId.namespaceSpecific(),
-                comparison: ComparisonOperator.Equals
-            }, [
-                {
-                    property: "dateCreated",
-                    sortDirection: SortDirection.Ascending
-                }
-            ], undefined, changesetsResult?.cursor);
-            const storedChangesets = changesetsResult.entities;
-            if (Is.arrayValue(storedChangesets)) {
-                for (let i = 0; i < storedChangesets.length; i++) {
-                    const storedChangeset = storedChangesets[i];
-                    const storedChangesetJsonLd = this.changesetEntityToJsonLd(vertexId.namespaceSpecific(), storedChangeset);
-                    changesets.push(storedChangesetJsonLd);
-                    // If we are verifying all signatures
-                    // or this is the last changeset (cursor is empty)
-                    // and the changeset has a proofId, then verify the proof.
-                    if (verifySignatureDepth === VerifyDepth.All ||
-                        (verifySignatureDepth === VerifyDepth.Current &&
-                            !Is.stringValue(changesetsResult.cursor) &&
-                            i === storedChangesets.length - 1)) {
-                        if (!Is.stringValue(storedChangeset.proofId)) {
-                            verified = false;
-                            storedChangesetJsonLd.verification = {
-                                "@context": ImmutableProofContexts.Namespace,
-                                type: ImmutableProofTypes.ImmutableProofVerification,
-                                verified: false,
-                                failure: ImmutableProofFailure.ProofMissing
-                            };
-                        }
-                        else {
-                            // Verify the proof for the changeset object
-                            storedChangesetJsonLd.verification = await this._immutableProofComponent.verify(storedChangeset.proofId);
-                            if (!storedChangesetJsonLd.verification.verified) {
-                                verified = false;
-                            }
-                        }
-                    }
-                }
+            const chunk = await this.verifyChangesetChunk(vertexId, verifySignatureDepth, cursor);
+            cursor = chunk.cursor;
+            if (!chunk.verified) {
+                verified = false;
             }
-        } while (Is.stringValue(changesetsResult.cursor));
+            changesets.push(...chunk.changesets);
+        } while (Is.stringValue(cursor));
+        if (verified) {
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
+        }
+        else {
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsFailed);
+        }
         return {
             verified,
             changesets
         };
     }
+    /**
+     * Verify a chunk of changesets for a vertex.
+     * @param vertexId The id of the vertex to verify the changesets for.
+     * @param verifySignatureDepth How many signatures to verify.
+     * @param cursor The cursor to request the next chunk of changesets.
+     * @param limit The maximum number of changesets to verify in this chunk.
+     * @returns The changesets and whether they were verified.
+     * @internal
+     */
+    async verifyChangesetChunk(vertexId, verifySignatureDepth, cursor, limit) {
+        const changesets = [];
+        let verified = true;
+        const changesetsResult = await this._changesetStorage.query({
+            property: "vertexId",
+            value: vertexId,
+            comparison: ComparisonOperator.Equals
+        }, [
+            {
+                property: "dateCreated",
+                sortDirection: SortDirection.Ascending
+            }
+        ], undefined, cursor, limit);
+        const storedChangesets = changesetsResult.entities;
+        if (Is.arrayValue(storedChangesets)) {
+            for (let i = 0; i < storedChangesets.length; i++) {
+                const storedChangeset = storedChangesets[i];
+                const storedChangesetJsonLd = this.changesetEntityToJsonLd(vertexId, storedChangeset);
+                changesets.push(storedChangesetJsonLd);
+                // If we are verifying all signatures
+                // or this is the last changeset (cursor is empty)
+                // and the changeset has a proofId, then verify the proof.
+                if (verifySignatureDepth === VerifyDepth.All ||
+                    (verifySignatureDepth === VerifyDepth.Current &&
+                        !Is.stringValue(changesetsResult.cursor) &&
+                        i === storedChangesets.length - 1)) {
+                    storedChangesetJsonLd.verification =
+                        await this.verifyChangesetSignature(storedChangesetJsonLd);
+                    if (storedChangesetJsonLd.verification?.verified !== true) {
+                        verified = false;
+                    }
+                }
+            }
+        }
+        return { changesets, verified, cursor: changesetsResult.cursor };
+    }
+    /**
+     * Verify the signature of a changeset and add the verification result to the changeset JSON-LD.
+     * @param storedChangeset The changeset to verify.
+     * @returns Whether the changeset is verified.
+     */
+    async verifyChangesetSignature(storedChangeset) {
+        let verification;
+        if (!Is.stringValue(storedChangeset.proofId)) {
+            verification = {
+                "@context": ImmutableProofContexts.Context,
+                type: ImmutableProofTypes.ImmutableProofVerification,
+                verified: false,
+                failure: ImmutableProofFailure.ProofMissing
+            };
+        }
+        else {
+            // Verify the proof for the changeset object
+            verification = await this._immutableProofComponent.verify(storedChangeset.proofId);
+        }
+        return verification;
+    }
     /**
      * Get the resource id from a resource object.
      * @param resource The resource.
@@ -856,7 +1370,7 @@ export class AuditableItemGraphService {
      * @returns True if any other vertices have matching aliases.
      * @internal
      */
-    async findMatchingVertices(context, vertexId, aliasId) {
+    async findMatchingVertices(vertexId, aliasId) {
         const results = await this._vertexStorage.query({
             conditions: [
                 {
@@ -874,6 +1388,47 @@ export class AuditableItemGraphService {
         });
         return results.entities.length > 0;
     }
+    /**
+     * Whether an incoming edge matches a stored edge id.
+     * @param incoming The incoming edge.
+     * @param storedEdgeId The compact stored edge id.
+     * @returns True if the incoming edge matches the stored edge id.
+     * @internal
+     */
+    edgeMatchesStoredEdge(incoming, storedEdgeId) {
+        return Is.stringValue(incoming.id) && this.reduceEdgeId(incoming.id) === storedEdgeId;
+    }
+    /**
+     * Whether a PATCH remove id matches a stored compact edge id (full URN or compact).
+     * @param storedEdgeId The compact stored edge id.
+     * @param removeId The id from the patch remove list.
+     * @returns True if the remove id identifies the stored edge.
+     * @internal
+     */
+    edgeRemoveIdMatches(storedEdgeId, removeId) {
+        if (storedEdgeId === removeId) {
+            return true;
+        }
+        try {
+            return this.reduceEdgeId(removeId) === storedEdgeId;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Whether an incoming id-less edge matches an active stored edge by target and relationships.
+     * @param incoming The incoming edge.
+     * @param stored The stored edge.
+     * @returns True if they match.
+     * @internal
+     */
+    edgeMatchesActiveEdgeByRelationship(incoming, stored) {
+        return (Is.empty(incoming.id) &&
+            Is.empty(stored.dateDeleted) &&
+            incoming.targetId === stored.targetId &&
+            ArrayHelper.matches(incoming.edgeRelationships, stored.edgeRelationships));
+    }
     /**
      * Reduce the edge ID from a URN.
      * @param urn The URN to reduce.