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

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 { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { ArrayHelper, ComponentFactory, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
-import { JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
+import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
+import { ContextIdHelper, ContextIdKeys, ContextIdStore } from "@twin.org/context";
+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,16 @@ export class AuditableItemGraphService {
      * @internal
      */
     _eventBusComponent;
+    /**
+     * The telemetry component.
+     * @internal
+     */
+    _telemetryComponent;
+    /**
+     * The timeout in milliseconds when acquiring a mutex lock.
+     * @internal
+     */
+    _mutexTimeoutMs;
     /**
      * Create a new instance of AuditableItemGraphService.
      * @param options The dependencies for the auditable item graph connector.
@@ -68,10 +80,12 @@ 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);
+        this._mutexTimeoutMs = Coerce.integer(options?.config?.mutexTimeoutMs);
         SchemaOrgDataTypes.registerRedirects();
+        AuditableItemGraphDataTypes.registerTypes();
+        JsonLdDataTypes.registerTypes();
     }
     /**
      * Returns the class name of the component.
@@ -80,6 +94,16 @@ export class AuditableItemGraphService {
     className() {
         return AuditableItemGraphService.CLASS_NAME;
     }
+    /**
+     * Register all AIG metrics with the telemetry component.
+     * @returns A promise that resolves when all metrics have been registered.
+     */
+    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.
@@ -92,20 +116,29 @@ export class AuditableItemGraphService {
     async create(vertex) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
         const contextIds = await ContextIdStore.getContextIds();
+        ContextIdHelper.guard(contextIds, ContextIdKeys.Organization);
         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 = RandomHelper.generateUuidV7("compact");
+            const ownerOrganizationId = contextIds?.[ContextIdKeys.UserOrganization] ?? contextIds?.[ContextIdKeys.Organization];
             const context = {
                 now: new Date(Date.now()).toISOString(),
-                contextIds
+                organizationIdentity: ownerOrganizationId,
+                userIdentity: contextIds?.[ContextIdKeys.User]
             };
             const vertexModel = {
                 id,
-                organizationIdentity: contextIds?.[ContextIdKeys.Organization],
+                organizationIdentity: contextIds[ContextIdKeys.Organization],
                 dateCreated: context.now
             };
             const originalEntity = ObjectHelper.clone(vertexModel);
@@ -115,11 +148,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,6 +163,116 @@ 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 A promise that resolves when the vertex has been updated.
+     */
+    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, timeoutMs: this._mutexTimeoutMs });
+        try {
+            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 contextIds = await ContextIdStore.getContextIds();
+                const ownerOrganizationId = vertexEntity.organizationIdentity ??
+                    contextIds?.[ContextIdKeys.UserOrganization] ??
+                    contextIds?.[ContextIdKeys.Organization];
+                const context = {
+                    now: new Date(Date.now()).toISOString(),
+                    organizationIdentity: ownerOrganizationId,
+                    userIdentity: contextIds?.[ContextIdKeys.User]
+                };
+                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);
+                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 A promise that resolves when the partial update has been applied.
+     */
+    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, timeoutMs: this._mutexTimeoutMs });
+        try {
+            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 contextIds = await ContextIdStore.getContextIds();
+                const ownerOrganizationId = vertexEntity.organizationIdentity ??
+                    contextIds?.[ContextIdKeys.UserOrganization] ??
+                    contextIds?.[ContextIdKeys.Organization];
+                const context = {
+                    now: new Date(Date.now()).toISOString(),
+                    organizationIdentity: ownerOrganizationId,
+                    userIdentity: contextIds?.[ContextIdKeys.User]
+                };
+                delete vertexEntity.aliasIndex;
+                const originalEntity = ObjectHelper.clone(vertexEntity);
+                const newEntity = ObjectHelper.clone(vertexEntity);
+                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.
@@ -217,6 +362,14 @@ export class AuditableItemGraphService {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
             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 changesetList = {
                 "@context": [
                     SchemaOrgContexts.Context,
@@ -270,6 +423,14 @@ export class AuditableItemGraphService {
             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;
@@ -279,70 +440,68 @@ 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 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 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 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: 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 currentVersion = vertexEntity.version ?? 0;
+            if (version > currentVersion || version < 0) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", version.toString());
             }
-            const context = {
-                now: new Date(Date.now()).toISOString(),
-                contextIds
+            // 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
             };
-            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 });
+            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, "updatingFailed", undefined, error);
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionFailed", undefined, error);
         }
     }
     /**
-     * Remove the verifiable storage for an item.
-     * @param id The id of the vertex to get.
-     * @returns Nothing.
+     * 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 removeVerifiable(id) {
+    async getVersions(id, options) {
         Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
         const urnParsed = Urn.fromValidString(id);
         if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
@@ -353,6 +512,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 A promise that resolves when the proof has been removed from all changesets.
+     * @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, timeoutMs: this._mutexTimeoutMs });
+        try {
             const vertexEntity = await this._vertexStorage.get(vertexId);
             if (Is.empty(vertexEntity)) {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
@@ -371,7 +576,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);
                     }
@@ -379,7 +584,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);
         }
     }
     /**
@@ -388,7 +596,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.
@@ -406,46 +614,62 @@ export class AuditableItemGraphService {
                 "aliases",
                 "annotationObject"
             ];
-            const combinedConditions = conditions ?? [];
+            const andGroups = [];
             const orderProperty = orderBy ?? "dateCreated";
             const orderDirection = orderByDirection ?? SortDirection.Descending;
             const idExact = options?.idExact ?? false;
+            if (!Is.empty(conditions)) {
+                andGroups.push(conditions);
+            }
             const idOrAlias = options?.id;
             if (Is.stringValue(idOrAlias)) {
                 const idMode = options?.idMode ?? "both";
+                const idComparators = [];
                 if (idMode === "id" || idMode === "both") {
-                    combinedConditions.push({
+                    idComparators.push({
                         property: "id",
                         comparison: idExact ? ComparisonOperator.Equals : ComparisonOperator.Includes,
                         value: idOrAlias
                     });
                 }
                 if (idMode === "alias" || idMode === "both") {
-                    combinedConditions.push({
+                    idComparators.push({
                         property: "aliasIndex",
                         comparison: ComparisonOperator.Includes,
                         value: idExact ? `||${idOrAlias.toLowerCase()}||` : idOrAlias.toLowerCase()
                     });
                 }
+                if (idComparators.length === 1) {
+                    andGroups.push(idComparators[0]);
+                }
+                else if (idComparators.length > 1) {
+                    andGroups.push({ logicalOperator: LogicalOperator.Or, conditions: idComparators });
+                }
             }
-            if (Is.arrayValue(options?.includesResourceTypes)) {
-                for (const resourceType of options.includesResourceTypes) {
-                    combinedConditions.push({
-                        property: "resourceTypeIndex",
-                        comparison: ComparisonOperator.Includes,
-                        value: `||${resourceType.toLowerCase()}||`
+            if (Is.arrayValue(options?.resourceTypes)) {
+                const resourceComparators = options.resourceTypes.map(rt => ({
+                    property: "resourceTypeIndex",
+                    comparison: ComparisonOperator.Includes,
+                    value: `||${rt.toLowerCase()}||`
+                }));
+                if (resourceComparators.length === 1) {
+                    andGroups.push(resourceComparators[0]);
+                }
+                else {
+                    andGroups.push({
+                        logicalOperator: LogicalOperator.Or,
+                        conditions: resourceComparators
                     });
                 }
             }
             if (!propertiesToReturn.includes("id")) {
                 propertiesToReturn.unshift("id");
             }
-            const results = await this._vertexStorage.query(combinedConditions.length > 0
-                ? {
-                    conditions: combinedConditions,
-                    logicalOperator: LogicalOperator.Or
-                }
-                : undefined, [
+            const finalConditions = {
+                logicalOperator: LogicalOperator.And,
+                conditions: andGroups
+            };
+            const results = await this._vertexStorage.query(finalConditions, [
                 {
                     property: orderProperty,
                     sortDirection: orderDirection
@@ -462,6 +686,10 @@ export class AuditableItemGraphService {
                 [SchemaOrgTypes.ItemListElement]: models
             };
             const result = await JsonLdProcessor.compact(vertexList, vertexList["@context"]);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.QueriesExecuted, {
+                resultCount: models.length,
+                hasMore: Is.stringValue(results.cursor)
+            });
             return {
                 entries: result,
                 cursor: results.cursor
@@ -471,6 +699,69 @@ export class AuditableItemGraphService {
             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.
+     * @throws {GeneralError} If the namespace does not match the expected namespace.
+     * @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.
+     * @throws {GeneralError} If the patch value is a bare array instead of a list patch object.
+     * @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.
+     * @returns A promise that resolves when the changes have been persisted and events published.
+     * @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.
@@ -587,24 +878,62 @@ 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.
+     * @returns A promise that resolves when the alias list has been replaced.
      * @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);
                 }
             }
         }
@@ -614,18 +943,44 @@ export class AuditableItemGraphService {
             }
         }
     }
+    /**
+     * Apply alias patch operations (PATCH).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @param patch The alias patch.
+     * @returns A promise that resolves when the alias patch has been applied.
+     * @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.
      * @param vertex The vertex.
      * @param alias The alias.
+     * @returns A promise that resolves when the alias has been added or updated.
      * @internal
      */
     async updateAlias(context, vertex, alias) {
         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
@@ -646,23 +1001,29 @@ 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.
+     * @returns A promise that resolves when the resource list has been replaced.
      * @internal
      */
     async updateResourceList(context, vertex, resources) {
@@ -677,11 +1038,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);
                 }
             }
         }
@@ -691,11 +1052,37 @@ export class AuditableItemGraphService {
             }
         }
     }
+    /**
+     * Apply resource patch operations (PATCH).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @param patch The resource patch.
+     * @returns A promise that resolves when the resource patch has been applied.
+     * @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.
      * @param vertex The vertex.
      * @param resource The resource.
+     * @returns A promise that resolves when the resource has been added or updated.
      * @internal
      */
     async updateResource(context, vertex, resource) {
@@ -716,27 +1103,32 @@ 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.
+     * @returns A promise that resolves when the edge list has been replaced.
      * @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);
                 }
             }
         }
@@ -746,11 +1138,37 @@ export class AuditableItemGraphService {
             }
         }
     }
+    /**
+     * Apply edge patch operations (PATCH).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @param patch The edge patch.
+     * @returns A promise that resolves when the edge patch has been applied.
+     * @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.
      * @param vertex The vertex.
      * @param edge The edge.
+     * @returns A promise that resolves when the edge has been added or updated.
      * @internal
      */
     async updateEdge(context, vertex, edge) {
@@ -773,7 +1191,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 = RandomHelper.generateUuidV7("compact");
+            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);
@@ -788,6 +1209,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) ||
@@ -797,6 +1219,7 @@ export class AuditableItemGraphService {
             existing.dateModified = context.now;
             existing.edgeRelationships = edge.edgeRelationships;
             existing.annotationObject = edge.annotationObject;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesModified);
         }
     }
     /**
@@ -805,10 +1228,11 @@ 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) {
@@ -816,16 +1240,24 @@ export class AuditableItemGraphService {
                 id: RandomHelper.generateUuidV7("compact"),
                 vertexId: updated.id,
                 dateCreated: context.now,
-                userIdentity: context.contextIds?.[ContextIdKeys.User],
-                patches
+                userIdentity: context.userIdentity,
+                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 [];
@@ -834,6 +1266,7 @@ export class AuditableItemGraphService {
      * Verify the changesets of a vertex.
      * @param vertex The vertex to verify.
      * @param verifySignatureDepth How many signatures to verify.
+     * @returns The verified flag and list of changesets.
      * @internal
      */
     async verifyChangesets(vertex, verifySignatureDepth) {
@@ -850,6 +1283,12 @@ export class AuditableItemGraphService {
             }
             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
@@ -904,6 +1343,7 @@ export class AuditableItemGraphService {
      * 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.
+     * @internal
      */
     async verifyChangesetSignature(storedChangeset) {
         let verification;
@@ -927,6 +1367,7 @@ export class AuditableItemGraphService {
      * @param resource.id The id of the resource.
      * @param resource.resourceObject The resource object.
      * @returns The resource id if it can find one.
+     * @internal
      */
     getResourceId(resource) {
         return (resource.id ??
@@ -961,13 +1402,12 @@ export class AuditableItemGraphService {
     }
     /**
      * Find vertices with matching aliases.
-     * @param context The context for the operation.
      * @param vertexId The id of the vertex to exclude from the search.
      * @param aliasId The alias id to try and find.
      * @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: [
                 {
@@ -985,6 +1425,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.