@twin.org/auditable-item-graph-service 0.0.3-next.22 → 0.0.3-next.24

package/dist/es/auditableItemGraphService.js

@@ -1,7 +1,7 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
-import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
+import { ContextIdHelper, ContextIdKeys, ContextIdStore } from "@twin.org/context";
 import { ArrayHelper, Coerce, ComponentFactory, GeneralError, Guards, Is, JsonHelper, Mutex, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
 import { DataTypeHelper } from "@twin.org/data-core";
 import { JsonLdDataTypes, JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
@@ -90,6 +90,7 @@ export class AuditableItemGraphService {
     }
     /**
      * 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)) {
@@ -109,6 +110,7 @@ export class AuditableItemGraphService {
     async create(vertex) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
         const contextIds = await ContextIdStore.getContextIds();
+        ContextIdHelper.guard(contextIds, ContextIdKeys.Organization);
         try {
             const id = RandomHelper.generateUuidV7("compact");
             const schemaValidationFailures = [];
@@ -122,13 +124,15 @@ export class AuditableItemGraphService {
                 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(),
-                contextIds
+                organizationIdentity: ownerOrganizationId,
+                userIdentity: contextIds?.[ContextIdKeys.User]
             };
             const vertexModel = {
                 id,
-                organizationIdentity: contextIds?.[ContextIdKeys.Organization],
+                organizationIdentity: contextIds[ContextIdKeys.Organization],
                 dateCreated: context.now
             };
             const originalEntity = ObjectHelper.clone(vertexModel);
@@ -157,7 +161,7 @@ export class AuditableItemGraphService {
      * Update a graph vertex (PUT — full replacement of vertex state).
      * Concurrent updates for the same vertex are serialized via `Mutex` on the vertex id.
      * @param vertex The vertex to update.
-     * @returns Nothing.
+     * @returns A promise that resolves when the vertex has been updated.
      */
     async update(vertex) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
@@ -165,7 +169,6 @@ export class AuditableItemGraphService {
         const vertexId = this.parseVertexId(vertex.id);
         await Mutex.lock(vertexId, { throwOnTimeout: true });
         try {
-            const contextIds = await ContextIdStore.getContextIds();
             try {
                 const schemaValidationFailures = [];
                 await DataTypeHelper.validate("vertex", `${AuditableItemGraphContexts.Namespace}${AuditableItemGraphTypes.Vertex}`, vertex, schemaValidationFailures);
@@ -179,20 +182,18 @@ export class AuditableItemGraphService {
                     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(),
-                    contextIds
+                    organizationIdentity: ownerOrganizationId,
+                    userIdentity: contextIds?.[ContextIdKeys.User]
                 };
                 delete vertexEntity.aliasIndex;
                 const originalEntity = ObjectHelper.clone(vertexEntity);
                 const newEntity = ObjectHelper.clone(vertexEntity);
-                // Capture org from context if vertex doesn't have one yet.
-                // Enables ownership transition: when an authenticated user first
-                // interacts with a vertex that was received without an org, the org
-                // is set here and recorded as a patch in the changeset proof.
-                if (!Is.stringValue(newEntity.organizationIdentity)) {
-                    newEntity.organizationIdentity = context.contextIds?.[ContextIdKeys.Organization];
-                }
                 newEntity.annotationObject = vertex.annotationObject;
                 await this.updateAliasList(context, newEntity, vertex.aliases);
                 await this.updateResourceList(context, newEntity, vertex.resources);
@@ -211,7 +212,7 @@ export class AuditableItemGraphService {
      * Partially update a graph vertex (PATCH — explicit list patches; only defined properties applied).
      * Serialized with `update` via `Mutex` on the same vertex id within this instance.
      * @param partial The partial vertex update.
-     * @returns Nothing.
+     * @returns A promise that resolves when the partial update has been applied.
      */
     async updatePartial(partial) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "partial", partial);
@@ -219,7 +220,6 @@ export class AuditableItemGraphService {
         const vertexId = this.parseVertexId(partial.id);
         await Mutex.lock(vertexId, { throwOnTimeout: true });
         try {
-            const contextIds = await ContextIdStore.getContextIds();
             try {
                 const vertexEntity = await this._vertexStorage.get(vertexId);
                 if (Is.empty(vertexEntity)) {
@@ -230,17 +230,18 @@ export class AuditableItemGraphService {
                     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(),
-                    contextIds
+                    organizationIdentity: ownerOrganizationId,
+                    userIdentity: contextIds?.[ContextIdKeys.User]
                 };
                 delete vertexEntity.aliasIndex;
                 const originalEntity = ObjectHelper.clone(vertexEntity);
                 const newEntity = ObjectHelper.clone(vertexEntity);
-                // Capture org from context if vertex doesn't have one yet.
-                if (!Is.stringValue(newEntity.organizationIdentity)) {
-                    newEntity.organizationIdentity = context.contextIds?.[ContextIdKeys.Organization];
-                }
                 if (partial.annotationObject !== undefined) {
                     newEntity.annotationObject = partial.annotationObject;
                 }
@@ -543,7 +544,7 @@ export class AuditableItemGraphService {
     /**
      * Remove the proof for an item.
      * @param id The id of the vertex to remove the proof from.
-     * @returns Nothing.
+     * @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) {
@@ -717,6 +718,7 @@ export class AuditableItemGraphService {
      * @param vertexUrn The vertex URN for events.
      * @param originalEntity The entity before changes.
      * @param newEntity The entity after changes.
+     * @returns A promise that resolves when the changes have been persisted and events published.
      * @internal
      */
     async persistVertexChanges(context, vertexId, vertexUrn, originalEntity, newEntity) {
@@ -900,6 +902,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -923,6 +926,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -947,6 +951,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -996,6 +1001,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -1029,6 +1035,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -1053,6 +1060,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -1087,6 +1095,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -1112,6 +1121,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -1136,6 +1146,7 @@ export class AuditableItemGraphService {
      * @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) {
@@ -1207,7 +1218,7 @@ export class AuditableItemGraphService {
                 id: RandomHelper.generateUuidV7("compact"),
                 vertexId: updated.id,
                 dateCreated: context.now,
-                userIdentity: context.contextIds?.[ContextIdKeys.User],
+                userIdentity: context.userIdentity,
                 patches,
                 version
             };