@3sixty/auditable-item-graph-service 0.0.0-stage → 0.20.0-next.0

package/dist/es/auditableItemGraphService.js

@@ -0,0 +1,1913 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { HealthCategory, HealthStatus } from "@3sixty/api-models";
+import { AuditableItemGraphAuditMode, AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@3sixty/auditable-item-graph-models";
+import { ContextIdHelper, ContextIdKeys, ContextIdStore } from "@3sixty/context";
+import { ArrayHelper, BaseError, Coerce, ComponentFactory, GeneralError, Guards, Is, JsonHelper, Mutex, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@3sixty/core";
+import { DataTypeHelper } from "@3sixty/data-core";
+import { JsonLdDataTypes, JsonLdHelper, JsonLdProcessor } from "@3sixty/data-json-ld";
+import { ComparisonOperator, LogicalOperator, SortDirection } from "@3sixty/entity";
+import { EntityStorageConnectorFactory } from "@3sixty/entity-storage-models";
+import { ImmutableProofContexts, ImmutableProofFailure, ImmutableProofTypes } from "@3sixty/immutable-proof-models";
+import { SchemaOrgContexts, SchemaOrgDataTypes, SchemaOrgTypes } from "@3sixty/standards-schema-org";
+import { MetricHelper } from "@3sixty/telemetry-models";
+import { AuditableItemGraphVertexIndexHelper } from "./utils/auditableItemGraphVertexIndexHelper.js";
+/**
+ * Class for performing auditable item graph operations.
+ */
+export class AuditableItemGraphService {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "AuditableItemGraphService";
+    /**
+     * The namespace for the service.
+     * @internal
+     */
+    static NAMESPACE = "aig";
+    /**
+     * The namespace for the service changeset.
+     */
+    static NAMESPACE_CHANGESET = "changeset";
+    /**
+     * The namespace for the service edge.
+     */
+    static NAMESPACE_EDGE = "edge";
+    /**
+     * The index type for the id of the vertex itself.
+     * @internal
+     */
+    static _INDEX_TYPE_VERTEX = "vertex";
+    /**
+     * The index type for vertex aliases.
+     * @internal
+     */
+    static _INDEX_TYPE_ALIAS = "alias";
+    /**
+     * The index type for vertex resource types.
+     * @internal
+     */
+    static _INDEX_TYPE_RESOURCE_TYPE = "resourceType";
+    /**
+     * The keys to pick when creating the proof for the stream.
+     * @internal
+     */
+    static _PROOF_KEYS_CHANGESET = [
+        "id",
+        "vertexId",
+        "userIdentity",
+        "dateCreated",
+        "patches"
+    ];
+    /**
+     * The immutable proof component.
+     * @internal
+     */
+    _immutableProofComponent;
+    /**
+     * The entity storage for vertices.
+     * @internal
+     */
+    _vertexStorage;
+    /**
+     * The entity storage for vertex indices.
+     * @internal
+     */
+    _vertexIndexStorage;
+    /**
+     * The entity storage for changesets.
+     * @internal
+     */
+    _changesetStorage;
+    /**
+     * The event bus component.
+     * @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.
+     */
+    constructor(options) {
+        this._immutableProofComponent = ComponentFactory.get(options?.immutableProofComponentType ?? "immutable-proof");
+        this._vertexStorage = EntityStorageConnectorFactory.get(options?.vertexEntityStorageType ?? "auditable-item-graph-vertex");
+        this._vertexIndexStorage = EntityStorageConnectorFactory.get(options?.vertexIndexEntityStorageType ?? "auditable-item-graph-vertex-index");
+        this._changesetStorage = EntityStorageConnectorFactory.get(options?.changesetEntityStorageType ?? "auditable-item-graph-changeset");
+        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.
+     * @returns The class name of the component.
+     */
+    className() {
+        return AuditableItemGraphService.CLASS_NAME;
+    }
+    /**
+     * Runs a set/get/remove cycle against the vertex entity storage using the organisation identity
+     * from the current context.
+     * @param callback The callback to invoke when a deferred health result is ready.
+     * @returns The health status of the service.
+     */
+    async healthApplication(callback) {
+        const contextIds = (await ContextIdStore.getContextIds()) ?? {};
+        const orgId = contextIds[ContextIdKeys.Organization];
+        if (!Is.stringValue(orgId)) {
+            return [];
+        }
+        try {
+            const healthVertex = {
+                id: RandomHelper.generateUuidV7("compact"),
+                organizationIdentity: orgId,
+                dateCreated: new Date().toISOString()
+            };
+            await this._vertexStorage.set(healthVertex);
+            await this._vertexStorage.get(healthVertex.id);
+            await this._vertexStorage.remove(healthVertex.id);
+            return [
+                {
+                    source: AuditableItemGraphService.CLASS_NAME,
+                    category: HealthCategory.Application,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription"
+                }
+            ];
+        }
+        catch (error) {
+            return [
+                {
+                    source: AuditableItemGraphService.CLASS_NAME,
+                    category: HealthCategory.Application,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "getVertexFailed",
+                    error: BaseError.fromError(error)
+                }
+            ];
+        }
+    }
+    /**
+     * 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.
+     * @param vertex.auditMode How the mutations of the vertex are recorded, defaults to audited.
+     * @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 The id of the new graph item.
+     */
+    async create(vertex) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
+        if (Is.notEmpty(vertex.auditMode)) {
+            Guards.arrayOneOf(AuditableItemGraphService.CLASS_NAME, "vertex.auditMode", vertex.auditMode, Object.values(AuditableItemGraphAuditMode));
+        }
+        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 ownerOrganizationId = contextIds?.[ContextIdKeys.UserOrganization] ?? contextIds?.[ContextIdKeys.Organization];
+            const context = {
+                now: new Date(Date.now()).toISOString(),
+                organizationIdentity: ownerOrganizationId,
+                userIdentity: contextIds?.[ContextIdKeys.User]
+            };
+            const vertexModel = {
+                id,
+                organizationIdentity: contextIds[ContextIdKeys.Organization],
+                dateCreated: context.now
+            };
+            const originalEntity = ObjectHelper.clone(vertexModel);
+            vertexModel.auditMode = vertex.auditMode;
+            vertexModel.annotationObject = vertex.annotationObject;
+            await this.updateAliasList(context, vertexModel, vertex.aliases);
+            await this.updateResourceList(context, vertexModel, vertex.resources);
+            await this.updateEdgeList(context, vertexModel, vertex.edges);
+            // Bypass vertices keep no changeset history, so there is no baseline version to record.
+            if (vertex.auditMode !== AuditableItemGraphAuditMode.Bypass) {
+                await this.addChangeset(context, originalEntity, vertexModel, true, 0);
+                vertexModel.version = 0;
+            }
+            await this._vertexStorage.set(vertexModel);
+            await this.syncVertexIndexes(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;
+        }
+        catch (error) {
+            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.
+     * @throws GeneralError If a bypass vertex is being switched back to audited.
+     */
+    async update(vertex) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "vertex.id", vertex.id);
+        if (Is.notEmpty(vertex.auditMode)) {
+            Guards.arrayOneOf(AuditableItemGraphService.CLASS_NAME, "vertex.auditMode", vertex.auditMode, Object.values(AuditableItemGraphAuditMode));
+        }
+        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]
+                };
+                const auditModeTransition = this.resolveAuditModeTransition(vertexEntity, vertex.auditMode);
+                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, auditModeTransition);
+            }
+            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.
+     * @throws GeneralError If a bypass vertex is being switched back to audited.
+     */
+    async updatePartial(partial) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "partial", partial);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "partial.id", partial.id);
+        if (Is.notEmpty(partial.auditMode)) {
+            Guards.arrayOneOf(AuditableItemGraphService.CLASS_NAME, "partial.auditMode", partial.auditMode, Object.values(AuditableItemGraphAuditMode));
+        }
+        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]
+                };
+                const auditModeTransition = this.resolveAuditModeTransition(vertexEntity, partial.auditMode);
+                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, auditModeTransition);
+            }
+            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.verifySignatureDepth How many signatures to verify, defaults to "none".
+     * @returns The vertex if found.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    async get(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 vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const vertexModel = this.vertexEntityToJsonLd(vertexEntity);
+            // Bypass vertices have no changesets to verify, so verification is never reported for them.
+            const verifySignatureDepth = this.isBypass(vertexEntity)
+                ? VerifyDepth.None
+                : (options?.verifySignatureDepth ?? VerifyDepth.None);
+            let verified;
+            if (verifySignatureDepth === VerifyDepth.Current ||
+                verifySignatureDepth === VerifyDepth.All) {
+                const verifyResult = await this.verifyChangesets(vertexModel, verifySignatureDepth);
+                verified = verifyResult.verified;
+                vertexModel["@context"].push(ImmutableProofContexts.Context);
+            }
+            if (!(options?.includeDeleted ?? false)) {
+                if (Is.arrayValue(vertexModel.aliases)) {
+                    vertexModel.aliases = vertexModel.aliases.filter(a => Is.undefined(a.dateDeleted));
+                    if (vertexModel.aliases.length === 0) {
+                        delete vertexModel.aliases;
+                    }
+                }
+                if (Is.arrayValue(vertexModel.resources)) {
+                    vertexModel.resources = vertexModel.resources.filter(r => Is.undefined(r.dateDeleted));
+                    if (vertexModel.resources.length === 0) {
+                        delete vertexModel.resources;
+                    }
+                }
+                if (Is.arrayValue(vertexModel.edges)) {
+                    vertexModel.edges = vertexModel.edges.filter(r => Is.undefined(r.dateDeleted));
+                    if (vertexModel.edges.length === 0) {
+                        delete vertexModel.edges;
+                    }
+                }
+            }
+            if (verifySignatureDepth !== VerifyDepth.None) {
+                vertexModel.verified = verified;
+            }
+            const result = await JsonLdProcessor.compact(vertexModel, vertexModel["@context"], {
+                compactArrays: false
+            });
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getFailed", undefined, error);
+        }
+    }
+    /**
+     * 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 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
+            });
+        }
+        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);
+            }
+            // Bypass vertices maintain no changeset history.
+            const chunk = this.isBypass(vertexEntity)
+                ? { changesets: [], verified: true, cursor: undefined }
+                : await this.verifyChangesetChunk(vertexId, options?.verifySignatureDepth ?? VerifyDepth.None, cursor, limit);
+            if (!this.isBypass(vertexEntity) &&
+                (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,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
+                ],
+                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.ChangesetList],
+                [SchemaOrgTypes.ItemListElement]: chunk.changesets
+            };
+            const result = await JsonLdProcessor.compact(changesetList, changesetList["@context"], {
+                compactArrays: false
+            });
+            return {
+                changesets: result,
+                cursor: chunk.cursor
+            };
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getFailed", undefined, error);
+        }
+    }
+    /**
+     * Get a graph vertex changeset.
+     * @param id The id of the vertex to get.
+     * @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 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);
+            }
+            // Bypass vertices maintain no changeset history.
+            if (this.isBypass(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "changesetNotFound", 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"], {
+                compactArrays: false
+            });
+            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, a bypass vertex never has versions.
+     */
+    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);
+            }
+            // Bypass vertices maintain no version chain.
+            if (this.isBypass(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", version.toString());
+            }
+            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"], {
+                    compactArrays: false
+                });
+            }
+            const changesets = await this.internalGetChangesets(vertexId, ["patches"], {
+                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"], {
+                compactArrays: false
+            });
+            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, a bypass vertex returns a single baseline entry for its
+     * current state when that falls within the requested range.
+     * @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) {
+            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 beforeDate = Coerce.dateTime(options?.before);
+            const afterDate = Coerce.dateTime(options?.after);
+            const versions = this.isBypass(vertexEntity)
+                ? this.bypassVersions(vertexEntity, afterDate, beforeDate)
+                : await this.auditedVersions(vertexId, afterDate, beforeDate);
+            const versionList = {
+                "@context": [
+                    SchemaOrgContexts.Context,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
+                ],
+                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexVersionList],
+                [SchemaOrgTypes.ItemListElement]: versions
+            };
+            return await JsonLdProcessor.compact(versionList, versionList["@context"], {
+                compactArrays: false
+            });
+        }
+        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);
+            }
+            let changesetsResult;
+            do {
+                changesetsResult = await this._changesetStorage.query({
+                    property: "vertexId",
+                    value: vertexId,
+                    comparison: ComparisonOperator.Equals
+                }, [
+                    {
+                        property: "dateCreated",
+                        sortDirection: SortDirection.Ascending
+                    }
+                ], undefined, changesetsResult?.cursor);
+                for (const changeset of changesetsResult.entities) {
+                    if (Is.stringValue(changeset.proofId)) {
+                        await this._immutableProofComponent.removeNotarization(changeset.proofId);
+                        delete changeset.proofId;
+                        await this._changesetStorage.set(changeset);
+                    }
+                }
+            } while (Is.stringValue(changesetsResult.cursor));
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "removeProofFailed", undefined, error);
+        }
+        finally {
+            Mutex.unlock(vertexId);
+        }
+    }
+    /**
+     * Query the graph for vertices.
+     * @param options The query options.
+     * @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.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.
+     * @param properties The properties to return, if not provided defaults to id, created, aliases and object.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit The maximum number of entities to return, a page can contain fewer so follow
+     * the cursor until it is absent to read them all.
+     * @returns The entities, which can be partial if a limited keys list was provided.
+     */
+    async query(options, conditions, orderBy, orderByDirection, properties, cursor, limit) {
+        try {
+            const propertiesToReturn = properties ?? [
+                "id",
+                "dateCreated",
+                "dateModified",
+                "aliases",
+                "annotationObject"
+            ];
+            const orderProperty = orderBy ?? "dateCreated";
+            const orderDirection = orderByDirection ?? SortDirection.Descending;
+            const idExact = options?.idExact ?? false;
+            const idOrAlias = options?.id;
+            const idMode = options?.idMode ?? "both";
+            const resourceTypes = options?.resourceTypes;
+            const hasIdFilter = Is.stringValue(idOrAlias);
+            const hasResourceTypes = Is.arrayValue(resourceTypes);
+            if (!propertiesToReturn.includes("id")) {
+                propertiesToReturn.unshift("id");
+            }
+            // Every id, alias and resource type match is held in the index storage. Each filter is
+            // one dimension, satisfied by any one of the entries of a vertex, and a vertex has to
+            // satisfy every dimension it was given.
+            const indexDimensions = [];
+            if (hasIdFilter) {
+                const comparison = idExact ? ComparisonOperator.Equals : ComparisonOperator.Includes;
+                const term = idOrAlias.toLowerCase();
+                const idPredicates = [];
+                if (idMode === "id" || idMode === "both") {
+                    idPredicates.push(this.indexTypeValueCondition(AuditableItemGraphService._INDEX_TYPE_VERTEX, comparison, term));
+                }
+                if (idMode === "alias" || idMode === "both") {
+                    idPredicates.push(this.indexTypeValueCondition(AuditableItemGraphService._INDEX_TYPE_ALIAS, comparison, term));
+                }
+                indexDimensions.push(this.anyOfConditions(idPredicates));
+            }
+            if (hasResourceTypes) {
+                indexDimensions.push(this.indexTypeValueCondition(AuditableItemGraphService._INDEX_TYPE_RESOURCE_TYPE, ComparisonOperator.In, resourceTypes.map(resourceType => resourceType.toLowerCase())));
+            }
+            if (indexDimensions.length > 0) {
+                const indexPage = await this.queryIndexVertices(indexDimensions, orderProperty, orderDirection, propertiesToReturn, conditions, cursor, limit);
+                return await this.buildVertexList(indexPage.entities, indexPage.cursor);
+            }
+            const finalConditions = Is.empty(conditions)
+                ? { logicalOperator: LogicalOperator.And, conditions: [] }
+                : conditions;
+            // With no id, alias or resource type filter there is nothing for the index to answer,
+            // so the vertex storage is queried directly and paged by its own cursor.
+            const results = await this._vertexStorage.query(finalConditions, [
+                {
+                    property: orderProperty,
+                    sortDirection: orderDirection
+                },
+                {
+                    property: "id",
+                    sortDirection: SortDirection.Ascending
+                }
+            ], propertiesToReturn, cursor, limit);
+            return await this.buildVertexList(results.entities, 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.
+     * @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;
+    }
+    /**
+     * Resolve the audit mode for an update, bypass is terminal so it can not return to audited.
+     * @param vertexEntity The stored vertex entity.
+     * @param requestedMode The audit mode requested by the caller, when absent the stored mode is kept.
+     * @returns The audit mode to apply and whether the existing history must be compacted.
+     * @throws GeneralError If a bypass vertex is being switched back to audited.
+     * @internal
+     */
+    resolveAuditModeTransition(vertexEntity, requestedMode) {
+        const currentMode = vertexEntity.auditMode ?? AuditableItemGraphAuditMode.Audited;
+        if (Is.empty(requestedMode)) {
+            return { auditMode: currentMode, compactHistory: false };
+        }
+        if (currentMode === AuditableItemGraphAuditMode.Bypass &&
+            requestedMode === AuditableItemGraphAuditMode.Audited) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "auditModeTransitionNotAllowed", {
+                currentMode,
+                requestedMode
+            });
+        }
+        return {
+            auditMode: requestedMode,
+            compactHistory: currentMode === AuditableItemGraphAuditMode.Audited &&
+                requestedMode === AuditableItemGraphAuditMode.Bypass
+        };
+    }
+    /**
+     * Discard the changeset history for a vertex along with any proofs the changesets reference.
+     * @param vertexId The compact vertex id.
+     * @returns A promise that resolves when the history and its proofs have been removed.
+     * @internal
+     */
+    async compactVertexHistory(vertexId) {
+        const changesets = await this.internalGetChangesets(vertexId, ["proofId"]);
+        for (const changeset of changesets) {
+            await this._changesetStorage.remove(changeset.id);
+            if (Is.stringValue(changeset.proofId)) {
+                await this._immutableProofComponent.remove(changeset.proofId);
+            }
+        }
+    }
+    /**
+     * 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.
+     * @param auditModeTransition The audit mode to apply and whether the history must be compacted.
+     * @param auditModeTransition.auditMode The audit mode to apply.
+     * @param auditModeTransition.compactHistory Whether the existing history must be discarded.
+     * @returns A promise that resolves when the changes have been persisted and events published.
+     * @internal
+     */
+    async persistVertexChanges(context, vertexId, vertexUrn, originalEntity, newEntity, auditModeTransition) {
+        if (auditModeTransition.auditMode === AuditableItemGraphAuditMode.Bypass) {
+            await this.persistBypassChanges(context, vertexId, vertexUrn, originalEntity, newEntity, auditModeTransition.compactHistory);
+            return;
+        }
+        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;
+            await this._vertexStorage.set(newEntity);
+            await this.syncVertexIndexes(newEntity);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerticesUpdated, {
+                patchCount: patches.length
+            });
+            await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexUpdated, { id: vertexUrn, patches });
+        }
+    }
+    /**
+     * Persist vertex changes for a bypass vertex, overwriting the stored state with no changeset.
+     * @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.
+     * @param compactHistory Whether the vertex is switching from audited and must discard its history.
+     * @returns A promise that resolves when the changes have been persisted and events published.
+     * @internal
+     */
+    async persistBypassChanges(context, vertexId, vertexUrn, originalEntity, newEntity, compactHistory) {
+        newEntity.auditMode = AuditableItemGraphAuditMode.Bypass;
+        delete newEntity.version;
+        const patches = JsonHelper.diff(originalEntity, newEntity);
+        if (patches.length === 0) {
+            return;
+        }
+        if (compactHistory) {
+            await this.compactVertexHistory(vertexId);
+        }
+        newEntity.dateModified = context.now;
+        await this._vertexStorage.set(newEntity);
+        await this.syncVertexIndexes(newEntity);
+        await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerticesUpdated, {
+            patchCount: patches.length
+        });
+        await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexUpdated, { id: vertexUrn, patches });
+    }
+    /**
+     * Whether the vertex records its mutations in place with no audit trail.
+     * @param vertexEntity The stored vertex entity.
+     * @returns True if the vertex is in bypass mode.
+     * @internal
+     */
+    isBypass(vertexEntity) {
+        return vertexEntity.auditMode === AuditableItemGraphAuditMode.Bypass;
+    }
+    /**
+     * Map the vertex entity to JSON-LD.
+     * @param vertexEntity The vertex entity.
+     * @returns The model.
+     * @internal
+     */
+    vertexEntityToJsonLd(vertexEntity) {
+        const model = {
+            "@context": [
+                AuditableItemGraphContexts.Context,
+                AuditableItemGraphContexts.ContextCommon,
+                SchemaOrgContexts.Context
+            ],
+            type: AuditableItemGraphTypes.Vertex,
+            id: new Urn(AuditableItemGraphService.NAMESPACE, vertexEntity.id).toString(),
+            dateCreated: vertexEntity.dateCreated,
+            dateModified: vertexEntity.dateModified,
+            organizationIdentity: vertexEntity.organizationIdentity,
+            auditMode: vertexEntity.auditMode,
+            annotationObject: vertexEntity.annotationObject
+        };
+        if (Is.arrayValue(vertexEntity.aliases)) {
+            model.aliases ??= [];
+            for (const aliasEntity of vertexEntity.aliases) {
+                const aliasModel = {
+                    "@context": [
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon,
+                        SchemaOrgContexts.Context
+                    ],
+                    type: AuditableItemGraphTypes.Alias,
+                    id: aliasEntity.id,
+                    aliasFormat: aliasEntity.aliasFormat,
+                    dateCreated: aliasEntity.dateCreated,
+                    dateModified: aliasEntity.dateModified,
+                    dateDeleted: aliasEntity.dateDeleted,
+                    annotationObject: aliasEntity.annotationObject
+                };
+                model.aliases.push(aliasModel);
+            }
+        }
+        if (Is.arrayValue(vertexEntity.resources)) {
+            model.resources ??= [];
+            for (const resourceEntity of vertexEntity.resources) {
+                const resourceModel = {
+                    "@context": [
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon,
+                        SchemaOrgContexts.Context
+                    ],
+                    type: AuditableItemGraphTypes.Resource,
+                    id: resourceEntity.id,
+                    dateCreated: resourceEntity.dateCreated,
+                    dateModified: resourceEntity.dateModified,
+                    dateDeleted: resourceEntity.dateDeleted,
+                    resourceObject: resourceEntity.resourceObject
+                };
+                model.resources.push(resourceModel);
+            }
+        }
+        if (Is.arrayValue(vertexEntity.edges)) {
+            model.edges ??= [];
+            for (const edgeEntity of vertexEntity.edges) {
+                const edgeModel = {
+                    "@context": [
+                        AuditableItemGraphContexts.Context,
+                        AuditableItemGraphContexts.ContextCommon,
+                        SchemaOrgContexts.Context
+                    ],
+                    type: AuditableItemGraphTypes.Edge,
+                    id: this.fullEdgeId(vertexEntity.id, edgeEntity.id),
+                    targetId: edgeEntity.targetId,
+                    dateCreated: edgeEntity.dateCreated,
+                    dateModified: edgeEntity.dateModified,
+                    dateDeleted: edgeEntity.dateDeleted,
+                    edgeRelationships: edgeEntity.edgeRelationships,
+                    annotationObject: edgeEntity.annotationObject
+                };
+                model.edges.push(edgeModel);
+            }
+        }
+        return model;
+    }
+    /**
+     * Map the changeset entity to a JSON-LD.
+     * @param vertexId The id of the vertex the changeset belongs to.
+     * @param changesetEntity The changeset entity.
+     * @returns The model.
+     * @internal
+     */
+    changesetEntityToJsonLd(vertexId, changesetEntity) {
+        const model = {
+            "@context": [
+                AuditableItemGraphContexts.Context,
+                AuditableItemGraphContexts.ContextCommon,
+                SchemaOrgContexts.Context
+            ],
+            type: AuditableItemGraphTypes.Changeset,
+            id: new Urn(AuditableItemGraphService.NAMESPACE, [
+                vertexId,
+                AuditableItemGraphService.NAMESPACE_CHANGESET,
+                changesetEntity.id
+            ]).toString(),
+            dateCreated: changesetEntity.dateCreated,
+            userIdentity: changesetEntity.userIdentity,
+            patches: changesetEntity.patches.map(p => ({
+                "@context": [
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon,
+                    SchemaOrgContexts.Context
+                ],
+                type: AuditableItemGraphTypes.PatchOperation,
+                patchOperation: p.op,
+                patchPath: p.path,
+                patchFrom: p.from,
+                patchValue: p.value
+            })),
+            proofId: changesetEntity.proofId,
+            version: changesetEntity.version
+        };
+        return model;
+    }
+    /**
+     * Fetch all changesets for a vertex in ascending date order.
+     * @param vertexId The internal vertex id.
+     * @param properties The additional changeset properties to retrieve, the id and dateCreated sort
+     * keys are always included. Only the requested properties are populated on the returned
+     * entities, so the large patches payload is only transferred when a caller reads it.
+     * @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, properties, options) {
+        const all = [];
+        let cursor;
+        const propertiesToReturn = ["id", "dateCreated"];
+        for (const property of properties) {
+            if (!propertiesToReturn.includes(property)) {
+                propertiesToReturn.push(property);
+            }
+        }
+        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 }], propertiesToReturn, cursor);
+            all.push(...result.entities);
+            cursor = result.cursor;
+        } while (Is.stringValue(cursor));
+        return all;
+    }
+    /**
+     * Build the version list for an audited vertex from its changesets.
+     * @param vertexId The compact vertex id.
+     * @param afterDate Only include versions created after this date, exclusive.
+     * @param beforeDate Only include versions created before this date, exclusive.
+     * @returns The matching versions in ascending order.
+     * @internal
+     */
+    async auditedVersions(vertexId, afterDate, beforeDate) {
+        const allChangesets = await this.internalGetChangesets(vertexId, ["version"], {
+            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
+                });
+            }
+        }
+        return versions;
+    }
+    /**
+     * Build the version list for a bypass vertex, which only exposes its current state as
+     * a single baseline entry numbered zero.
+     * @param vertexEntity The stored vertex entity.
+     * @param afterDate Only include the state when it was modified after this date, exclusive.
+     * @param beforeDate Only include the state when it was modified before this date, exclusive.
+     * @returns The baseline entry when the state falls within the range, otherwise empty.
+     * @internal
+     */
+    bypassVersions(vertexEntity, afterDate, beforeDate) {
+        const stateDate = vertexEntity.dateModified ?? vertexEntity.dateCreated;
+        const stateDateTime = Coerce.dateTime(stateDate);
+        if (!Is.empty(stateDateTime)) {
+            if (!Is.empty(beforeDate) && stateDateTime >= beforeDate) {
+                return [];
+            }
+            if (!Is.empty(afterDate) && stateDateTime <= afterDate) {
+                return [];
+            }
+        }
+        return [{ version: 0, dateCreated: stateDate }];
+    }
+    /**
+     * Replace the aliases of a vertex model (PUT).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @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)) ?? [];
+        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);
+                }
+            }
+        }
+        if (Is.arrayValue(aliases)) {
+            for (const alias of aliases) {
+                await this.updateAlias(context, vertex, alias);
+            }
+        }
+    }
+    /**
+     * 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(vertex.id, alias.id);
+            if (existingVertices) {
+                throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "aliasNotUnique", {
+                    aliasId: alias.id
+                });
+            }
+        }
+        if (Is.object(alias.annotationObject)) {
+            const validationFailures = [];
+            await JsonLdHelper.validate(alias.annotationObject, validationFailures);
+            Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "alias.annotationObject", validationFailures);
+        }
+        // Try to find an existing alias with the same id.
+        const existing = vertex.aliases?.find(a => a.id === alias.id);
+        if (Is.empty(existing) || !Is.empty(existing?.dateDeleted)) {
+            // Did not find a matching item, or found one which is deleted.
+            vertex.aliases ??= [];
+            const model = {
+                id: alias.id,
+                aliasFormat: alias.aliasFormat,
+                dateCreated: context.now,
+                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) ||
+            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);
+        }
+    }
+    /**
+     * Replace the resources of a vertex (PUT).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @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) {
+        if (Is.arrayValue(resources)) {
+            for (let i = 0; i < resources.length; i++) {
+                const id = this.getResourceId(resources[i]);
+                if (Is.empty(id)) {
+                    throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "resourceIdMissing", {
+                        index: i
+                    });
+                }
+            }
+        }
+        const active = vertex.resources?.filter(r => Is.empty(r.dateDeleted)) ?? [];
+        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);
+                }
+            }
+        }
+        if (Is.arrayValue(resources)) {
+            for (const resource of resources) {
+                await this.updateResource(context, vertex, resource);
+            }
+        }
+    }
+    /**
+     * 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) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "resource", resource);
+        if (Is.object(resource.resourceObject)) {
+            const validationFailures = [];
+            await JsonLdHelper.validate(resource.resourceObject, validationFailures);
+            Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "resource.resourceObject", validationFailures);
+        }
+        // Try to find an existing resource with the same id.
+        const existing = vertex.resources?.find(r => this.getResourceId(r) === this.getResourceId(resource));
+        if (Is.empty(existing) || !Is.empty(existing?.dateDeleted)) {
+            // Did not find a matching item, or found one which is deleted.
+            vertex.resources ??= [];
+            const model = {
+                id: resource.id,
+                dateCreated: context.now,
+                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);
+        }
+    }
+    /**
+     * Replace the edges of a vertex (PUT).
+     * @param context The context for the operation.
+     * @param vertex The vertex.
+     * @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)) ?? [];
+        if (Is.arrayValue(active)) {
+            for (const edge of active) {
+                if (!edges?.find(e => this.edgeMatchesStoredEdge(e, edge.id) ||
+                    this.edgeMatchesActiveEdgeByRelationship(e, edge))) {
+                    edge.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesDeleted);
+                }
+            }
+        }
+        if (Is.arrayValue(edges)) {
+            for (const edge of edges) {
+                await this.updateEdge(context, vertex, edge);
+            }
+        }
+    }
+    /**
+     * 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) {
+        Guards.object(AuditableItemGraphService.CLASS_NAME, "edge", edge);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "edge.targetId", edge.targetId);
+        Guards.arrayValue(AuditableItemGraphService.CLASS_NAME, "edge.edgeRelationships", edge.edgeRelationships);
+        const validationFailures = [];
+        if (edge.targetId === vertex.id) {
+            validationFailures.push({
+                property: "id",
+                reason: `validation.${StringHelper.camelCase(AuditableItemGraphService.CLASS_NAME)}.edgeIdSameAsVertexId`,
+                properties: {
+                    targetId: edge.targetId
+                }
+            });
+        }
+        if (Is.object(edge.annotationObject)) {
+            await JsonLdHelper.validate(edge.annotationObject, validationFailures);
+        }
+        Validation.asValidationError(AuditableItemGraphService.CLASS_NAME, "edge.annotationObject", validationFailures);
+        let findId = Is.stringValue(edge.id) ? this.reduceEdgeId(edge.id) : undefined;
+        if (Is.empty(findId)) {
+            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);
+        if (Is.empty(existing) || !Is.empty(existing?.dateDeleted)) {
+            // Did not find a matching item, or found one which is deleted.
+            vertex.edges ??= [];
+            const model = {
+                id: findId,
+                targetId: edge.targetId,
+                dateCreated: context.now,
+                annotationObject: edge.annotationObject,
+                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) ||
+            !ObjectHelper.equal(existing.annotationObject, edge.annotationObject, false)) {
+            // Existing edge found, update the properties.
+            existing.targetId = edge.targetId;
+            existing.dateModified = context.now;
+            existing.edgeRelationships = edge.edgeRelationships;
+            existing.annotationObject = edge.annotationObject;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesModified);
+        }
+    }
+    /**
+     * Add a changeset to the vertex and generate the associated verifications.
+     * @param context The context for the operation.
+     * @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, 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: RandomHelper.generateUuidV7("compact"),
+                vertexId: updated.id,
+                dateCreated: context.now,
+                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 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 [];
+    }
+    /**
+     * 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) {
+        const changesets = [];
+        let verified = true;
+        const vertexIdUrn = Urn.fromValidString(vertex.id);
+        const vertexId = vertexIdUrn.namespaceSpecific();
+        let cursor;
+        do {
+            const chunk = await this.verifyChangesetChunk(vertexId, verifySignatureDepth, cursor);
+            cursor = chunk.cursor;
+            if (!chunk.verified) {
+                verified = false;
+            }
+            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.
+     * @internal
+     */
+    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.
+     * @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 ??
+            ObjectHelper.extractProperty(resource.resourceObject, ["id", "@id"], false));
+    }
+    /**
+     * Synchronise the index storage with the current state of a vertex.
+     * @param vertex The vertex to synchronise the index entries for.
+     * @returns A promise that resolves when the index entries match the vertex.
+     * @internal
+     */
+    async syncVertexIndexes(vertex) {
+        const required = new Map();
+        // An entry always carries a modified date so a query ordered by it can be paged by the
+        // same key set as the creation date, falling back to the creation date for a vertex which
+        // has never been modified rather than leaving the column empty.
+        const indexDateModified = vertex.dateModified ?? vertex.dateCreated;
+        // Every vertex carries an entry for its own id, so a query matching on the vertex id can
+        // be answered from the index alone. Without it a vertex holding no aliases and no
+        // resources would have no entries at all and could never be matched here.
+        const vertexIdValue = vertex.id.toLowerCase();
+        required.set(`${AuditableItemGraphService._INDEX_TYPE_VERTEX}|${vertexIdValue}`, {
+            type: AuditableItemGraphService._INDEX_TYPE_VERTEX,
+            value: vertexIdValue
+        });
+        // Index values are case folded here, and every lookup folds its term to match, so the
+        // comparisons stay case insensitive without relying on the column collation or on the
+        // connector folding case itself. The vertex keeps the value exactly as supplied.
+        for (const alias of vertex.aliases ?? []) {
+            if (Is.empty(alias.dateDeleted) && Is.stringValue(alias.id)) {
+                const value = alias.id.toLowerCase();
+                required.set(`${AuditableItemGraphService._INDEX_TYPE_ALIAS}|${value}`, {
+                    type: AuditableItemGraphService._INDEX_TYPE_ALIAS,
+                    value
+                });
+            }
+        }
+        for (const resource of vertex.resources ?? []) {
+            const resourceType = ObjectHelper.extractProperty(resource.resourceObject, ["@type", "type"], false);
+            if (Is.stringValue(resourceType)) {
+                const value = resourceType.toLowerCase();
+                required.set(`${AuditableItemGraphService._INDEX_TYPE_RESOURCE_TYPE}|${value}`, {
+                    type: AuditableItemGraphService._INDEX_TYPE_RESOURCE_TYPE,
+                    value
+                });
+            }
+        }
+        const existing = await this.queryVertexIndexes({
+            property: "vertexId",
+            comparison: ComparisonOperator.Equals,
+            value: vertex.id
+        }, ["id", "type", "value", "valueHash", "dateCreated", "dateModified"]);
+        // Collapse by row id first. A paged read can return the same row on more than one page,
+        // and without this a retained row could be queued for removal by its own duplicate.
+        const existingById = new Map();
+        for (const entry of existing) {
+            if (Is.stringValue(entry.id)) {
+                existingById.set(entry.id, entry);
+            }
+        }
+        const retainedKeys = new Set();
+        const removeIds = [];
+        const writeEntries = [];
+        for (const [id, entry] of existingById) {
+            // Entries which are no longer required, and any duplicates of a retained entry,
+            // are removed so exactly one entry remains per index value.
+            const key = `${entry.type}|${entry.value}`;
+            const requiredEntry = required.get(key);
+            if (!Is.empty(requiredEntry) && !retainedKeys.has(key)) {
+                retainedKeys.add(key);
+                const requiredIndexEntry = AuditableItemGraphVertexIndexHelper.createIndexEntry(vertex.id, requiredEntry.type, requiredEntry.value, vertex.dateCreated, indexDateModified);
+                if (entry.dateCreated !== requiredIndexEntry.dateCreated ||
+                    entry.dateModified !== requiredIndexEntry.dateModified ||
+                    entry.valueHash !== requiredIndexEntry.valueHash) {
+                    // Keep the row id so the copied dates and hash are corrected in place rather than
+                    // duplicated.
+                    writeEntries.push({ ...requiredIndexEntry, id });
+                }
+            }
+            else {
+                removeIds.push(id);
+            }
+        }
+        for (const [key, entry] of required) {
+            if (!retainedKeys.has(key)) {
+                writeEntries.push(AuditableItemGraphVertexIndexHelper.createIndexEntry(vertex.id, entry.type, entry.value, vertex.dateCreated, indexDateModified));
+            }
+        }
+        if (removeIds.length > 0) {
+            await this._vertexIndexStorage.removeBatch(removeIds);
+        }
+        if (writeEntries.length > 0) {
+            await this._vertexIndexStorage.setBatch(writeEntries);
+        }
+    }
+    /**
+     * Build the JSON-LD vertex list returned by query, and record the query metric.
+     * @param entities The vertex entities for the page.
+     * @param cursor The already encoded cursor for the next page.
+     * @returns The compacted vertex list and the cursor.
+     * @internal
+     */
+    async buildVertexList(entities, cursor) {
+        const models = entities.map(e => this.vertexEntityToJsonLd(e));
+        const vertexList = {
+            "@context": [
+                SchemaOrgContexts.Context,
+                AuditableItemGraphContexts.Context,
+                AuditableItemGraphContexts.ContextCommon
+            ],
+            type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexList],
+            [SchemaOrgTypes.ItemListElement]: models
+        };
+        const result = await JsonLdProcessor.compact(vertexList, vertexList["@context"], {
+            compactArrays: false
+        });
+        await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.QueriesExecuted, {
+            resultCount: models.length,
+            hasMore: Is.stringValue(cursor)
+        });
+        return {
+            entries: result,
+            cursor
+        };
+    }
+    /**
+     * Build the condition matching one index type and value. Exact matches are looked up by the
+     * value hash, a partial match can only be answered by the value itself.
+     * @param type The index type to match.
+     * @param comparison The comparison to apply to the value.
+     * @param value The index value or values to match, already lower cased.
+     * @returns The condition.
+     * @internal
+     */
+    indexTypeValueCondition(type, comparison, value) {
+        const valueCondition = comparison === ComparisonOperator.Includes
+            ? { property: "value", comparison, value }
+            : {
+                property: "valueHash",
+                comparison,
+                value: Is.array(value)
+                    ? value.map(v => AuditableItemGraphVertexIndexHelper.hashValue(v))
+                    : AuditableItemGraphVertexIndexHelper.hashValue(value)
+            };
+        return {
+            logicalOperator: LogicalOperator.And,
+            conditions: [
+                { property: "type", comparison: ComparisonOperator.Equals, value: type },
+                valueCondition
+            ]
+        };
+    }
+    /**
+     * Combine conditions so that matching any one of them is enough.
+     * @param conditions The conditions to combine.
+     * @returns The single condition when only one was given, otherwise their union.
+     * @internal
+     */
+    anyOfConditions(conditions) {
+        return conditions.length === 1
+            ? conditions[0]
+            : { logicalOperator: LogicalOperator.Or, conditions };
+    }
+    /**
+     * Read one page of vertices whose index entries satisfy every dimension. The entries of a
+     * vertex are grouped so it appears once however many of them match, its vertex is joined to
+     * the page so no second read is needed, and the connector pages the groups with its own cursor.
+     * @param dimensions The index conditions, a vertex has to satisfy every one of them.
+     * @param orderProperty The index date property to order by.
+     * @param orderDirection The direction to order in.
+     * @param propertiesToReturn The vertex properties to return.
+     * @param conditions Additional conditions the vertices must match.
+     * @param cursor The cursor returned by the previous page.
+     * @param limit The maximum number of vertices to return.
+     * @returns The vertices in order and the cursor for the next page.
+     * @internal
+     */
+    async queryIndexVertices(dimensions, orderProperty, orderDirection, propertiesToReturn, conditions, cursor, limit) {
+        // An entry only ever satisfies one dimension, so the entries of every dimension have to
+        // survive into the group for the group conditions to find them there, which is why the
+        // conditions are their union and the dimensions are applied across the group.
+        const results = await this._vertexIndexStorage.queryJoin(this._vertexStorage, {
+            property: "vertexId",
+            joinProperty: "id",
+            groupProperty: "vertexId",
+            conditions: this.anyOfConditions(dimensions),
+            groupConditions: dimensions.length > 1 ? dimensions : undefined,
+            sortProperties: [
+                { property: orderProperty, sortDirection: orderDirection },
+                { property: "vertexId", sortDirection: SortDirection.Ascending }
+            ],
+            properties: ["vertexId"],
+            joinConditions: conditions,
+            joinRequired: true,
+            joinProperties: propertiesToReturn,
+            cursor,
+            limit
+        });
+        // The join is required, so every group which survived carries its vertex.
+        return {
+            entities: results.entities.map(entity => entity.joined[0]),
+            cursor: results.cursor
+        };
+    }
+    /**
+     * Query all the pages of the vertex index storage which match the conditions.
+     * @param conditions The conditions to match.
+     * @param properties The properties to return.
+     * @returns The matching index entries.
+     * @internal
+     */
+    async queryVertexIndexes(conditions, properties) {
+        const entities = [];
+        let cursor;
+        do {
+            // Paging needs a deterministic order or a row can be repeated or skipped between
+            // pages, the entity declares no default sort so the primary key is used.
+            const results = await this._vertexIndexStorage.query(conditions, [{ property: "id", sortDirection: SortDirection.Ascending }], properties, cursor);
+            entities.push(...results.entities);
+            cursor = results.cursor;
+        } while (Is.stringValue(cursor));
+        return entities;
+    }
+    /**
+     * Find vertices with matching aliases.
+     * @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(vertexId, aliasId) {
+        const entities = await this.queryVertexIndexes({
+            logicalOperator: LogicalOperator.And,
+            conditions: [
+                {
+                    property: "type",
+                    comparison: ComparisonOperator.Equals,
+                    value: AuditableItemGraphService._INDEX_TYPE_ALIAS
+                },
+                {
+                    property: "valueHash",
+                    comparison: ComparisonOperator.Equals,
+                    value: AuditableItemGraphVertexIndexHelper.hashValue(aliasId)
+                },
+                {
+                    property: "vertexId",
+                    comparison: ComparisonOperator.NotEquals,
+                    value: vertexId
+                }
+            ]
+        }, ["vertexId"]);
+        return 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.
+     * @returns The edge ID.
+     * @throws GeneralError if the URN is not valid or not an edge URN.
+     * @internal
+     */
+    reduceEdgeId(urn) {
+        const urnParsed = Urn.fromValidString(urn);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id: urn
+            });
+        }
+        if (urnParsed.namespaceSpecificParts().length !== 3) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "invalidEdgeId", {
+                edgeId: urn
+            });
+        }
+        if (urnParsed.namespaceSpecificParts()[1] !== AuditableItemGraphService.NAMESPACE_EDGE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "invalidEdgeId", {
+                edgeId: urn
+            });
+        }
+        return urnParsed.namespaceSpecificParts()[2];
+    }
+    /**
+     * Create a full edge ID URN from a vertex ID and edge ID.
+     * @param vertexId The vertex id the edge belongs to.
+     * @param edgeId The edge id.
+     * @returns The full edge ID URN.
+     * @internal
+     */
+    fullEdgeId(vertexId, edgeId) {
+        return new Urn(AuditableItemGraphService.NAMESPACE, [
+            vertexId,
+            AuditableItemGraphService.NAMESPACE_EDGE,
+            edgeId
+        ]).toString();
+    }
+}
+//# sourceMappingURL=auditableItemGraphService.js.map