@bpmsoftwaresolutions/ai-engine-client 1.1.14 → 1.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -93,6 +93,37 @@ function isJsonBody(value) {
   return typeof value === 'object';
 }
 
+function cleanText(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function matchesExpectedState(actual, expected) {
+  if (typeof expected === 'function') {
+    throw new Error('matchesExpectedState does not support function expectations.');
+  }
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual) || actual.length < expected.length) return false;
+    return expected.every((item, index) => matchesExpectedState(actual[index], item));
+  }
+  if (isPlainObject(expected)) {
+    if (!isPlainObject(actual)) return false;
+    return Object.entries(expected).every(([key, value]) => matchesExpectedState(actual[key], value));
+  }
+  return Object.is(actual, expected);
+}
+
+function buildVerificationError(message, details = {}) {
+  const error = new Error(message);
+  error.code = 'POST_CONDITION_VERIFICATION_FAILED';
+  error.details = details;
+  return error;
+}
+
 export class AIEngineClient {
   constructor({ baseUrl, accessToken, tokenProvider, apiKey, clientId, actorId, fetchImpl, timeoutMs } = {}) {
     if (!baseUrl) throw new Error('baseUrl is required.');
@@ -1133,9 +1164,40 @@ export class AIEngineClient {
   }
 
   async updateImplementationItemStatus(implementationItemId, body) {
-    return this._request(`/api/governed-implementation/items/${implementationItemId}/status`, {
+    const result = await this._request(`/api/governed-implementation/items/${implementationItemId}/status`, {
       method: 'PATCH', body,
     });
+    const expectedStatus = cleanText(body?.status);
+    const authoritativeItem = isPlainObject(result?.implementation_item) ? result.implementation_item : null;
+    const actualStatus = cleanText(authoritativeItem?.status);
+    if (expectedStatus && !authoritativeItem) {
+      throw buildVerificationError(
+        `updateImplementationItemStatus did not return authoritative item state for ${implementationItemId}.`,
+        {
+          mutation_name: 'updateImplementationItemStatus',
+          mutation_attempted: true,
+          authoritative_read_performed: false,
+          post_condition_verified: false,
+          expected_state: { status: expectedStatus },
+          mutation_result: result ?? null,
+        },
+      );
+    }
+    if (expectedStatus && actualStatus !== expectedStatus) {
+      throw buildVerificationError(
+        `updateImplementationItemStatus returned ${actualStatus ?? 'unknown'} instead of ${expectedStatus}.`,
+        {
+          mutation_name: 'updateImplementationItemStatus',
+          mutation_attempted: true,
+          authoritative_read_performed: true,
+          post_condition_verified: false,
+          expected_state: { status: expectedStatus },
+          verified_current_state: authoritativeItem ?? result ?? null,
+          mutation_result: result ?? null,
+        },
+      );
+    }
+    return result;
   }
 
   async addImplementationItemEvidence(implementationItemId, body) {
@@ -1181,6 +1243,232 @@ export class AIEngineClient {
     return this._request(`/api/governed-implementation/workflows/${workflowId}/resume-context`);
   }
 
+  async executeVerifiedMutation({
+    mutationName,
+    mutationFn,
+    verificationFn,
+    expectedState,
+    evidenceLabel,
+  } = {}) {
+    if (typeof mutationFn !== 'function') throw new Error('mutationFn is required.');
+    if (typeof verificationFn !== 'function') throw new Error('verificationFn is required.');
+    const normalizedMutationName = cleanText(mutationName) || 'verifiedMutation';
+    const normalizedEvidenceLabel = cleanText(evidenceLabel) || normalizedMutationName;
+
+    let mutationResult;
+    try {
+      mutationResult = await mutationFn();
+    } catch (error) {
+      throw buildVerificationError(
+        `${normalizedMutationName} mutation failed before post-condition verification.`,
+        {
+          mutation_name: normalizedMutationName,
+          evidence_label: normalizedEvidenceLabel,
+          mutation_attempted: true,
+          authoritative_read_performed: false,
+          post_condition_verified: false,
+          expected_state: expectedState ?? null,
+          mutation_error: {
+            message: error?.message || String(error),
+            status: error?.status || null,
+            payload: error?.payload || null,
+          },
+        },
+      );
+    }
+
+    let verificationResult;
+    try {
+      verificationResult = await verificationFn(mutationResult);
+    } catch (error) {
+      throw buildVerificationError(
+        `${normalizedMutationName} authoritative read failed after mutation attempt.`,
+        {
+          mutation_name: normalizedMutationName,
+          evidence_label: normalizedEvidenceLabel,
+          mutation_attempted: true,
+          authoritative_read_performed: false,
+          post_condition_verified: false,
+          expected_state: expectedState ?? null,
+          mutation_result: mutationResult ?? null,
+          verification_error: {
+            message: error?.message || String(error),
+            status: error?.status || null,
+            payload: error?.payload || null,
+          },
+        },
+      );
+    }
+
+    let evaluation;
+    if (typeof expectedState === 'function') {
+      evaluation = expectedState(verificationResult, mutationResult);
+    } else {
+      evaluation = {
+        ok: matchesExpectedState(verificationResult, expectedState),
+        verifiedCurrentState: verificationResult,
+      };
+    }
+    if (typeof evaluation === 'boolean') {
+      evaluation = { ok: evaluation, verifiedCurrentState: verificationResult };
+    }
+    if (!isPlainObject(evaluation) || typeof evaluation.ok !== 'boolean') {
+      throw new Error('expectedState must resolve to a boolean or an object with an ok field.');
+    }
+
+    const evidence = {
+      mutation_name: normalizedMutationName,
+      evidence_label: normalizedEvidenceLabel,
+      mutation_attempted: true,
+      authoritative_read_performed: true,
+      post_condition_verified: evaluation.ok,
+      expected_state: expectedState ?? null,
+      verified_current_state: evaluation.verifiedCurrentState ?? verificationResult ?? null,
+      mutation_result: mutationResult ?? null,
+      verification_result: verificationResult ?? null,
+      verification_message: cleanText(evaluation.message) || null,
+    };
+
+    if (!evaluation.ok) {
+      throw buildVerificationError(
+        cleanText(evaluation.message) || `${normalizedMutationName} post-condition verification failed.`,
+        evidence,
+      );
+    }
+
+    return {
+      mutationName: normalizedMutationName,
+      evidenceLabel: normalizedEvidenceLabel,
+      mutationResult,
+      verificationResult,
+      verifiedCurrentState: evidence.verified_current_state,
+      mutationVerificationEvidence: evidence,
+    };
+  }
+
+  async updateImplementationItemStatusVerified(implementationItemId, status, body = {}) {
+    return this.executeVerifiedMutation({
+      mutationName: 'updateImplementationItemStatus',
+      evidenceLabel: `implementation-item-status:${implementationItemId}`,
+      mutationFn: () => this.updateImplementationItemStatus(implementationItemId, { ...body, status }),
+      verificationFn: async (mutationResult) => {
+        const workflowId = cleanText(body.workflowId)
+          || cleanText(body.workflow_id)
+          || cleanText(mutationResult?.workflow_id);
+        if (!workflowId) {
+          throw new Error('workflowId is required to verify implementation item status.');
+        }
+        const roadmap = await this.getWorkflowImplementationRoadmap(workflowId);
+        const items = Array.isArray(roadmap?.items) ? roadmap.items : [];
+        const matchedItem = items.find((item) => item?.implementation_item_id === implementationItemId) || null;
+        return {
+          workflow_id: workflowId,
+          item: matchedItem,
+          roadmap,
+        };
+      },
+      expectedState: (verificationResult) => {
+        const item = verificationResult?.item || null;
+        if (!item) {
+          return {
+            ok: false,
+            message: `Implementation item ${implementationItemId} was not present in the authoritative roadmap read.`,
+            verifiedCurrentState: verificationResult,
+          };
+        }
+        return {
+          ok: item.status === status,
+          message: `Implementation item ${implementationItemId} status remained ${item.status ?? 'unknown'} after mutation attempt.`,
+          verifiedCurrentState: item,
+        };
+      },
+    });
+  }
+
+  async updateAcceptanceCheckStatusVerified(implementationItemId, acceptanceCheckId, status, body = {}) {
+    return this.executeVerifiedMutation({
+      mutationName: 'updateAcceptanceCheckStatus',
+      evidenceLabel: `acceptance-check-status:${implementationItemId}:${acceptanceCheckId}`,
+      mutationFn: () => this.updateAcceptanceCheckStatus(implementationItemId, acceptanceCheckId, { ...body, status }),
+      verificationFn: async () => this.getImplementationItemAcceptanceChecks(implementationItemId),
+      expectedState: (verificationResult) => {
+        const checks = Array.isArray(verificationResult?.acceptance_checks) ? verificationResult.acceptance_checks : [];
+        const targetCheck = checks.find((check) => check?.acceptance_check_id === acceptanceCheckId) || null;
+        if (!targetCheck) {
+          return {
+            ok: false,
+            message: `Acceptance check ${acceptanceCheckId} was not returned by the authoritative read.`,
+            verifiedCurrentState: verificationResult,
+          };
+        }
+        return {
+          ok: targetCheck.status === status,
+          message: `Acceptance check ${acceptanceCheckId} status remained ${targetCheck.status ?? 'unknown'} after mutation attempt.`,
+          verifiedCurrentState: targetCheck,
+        };
+      },
+    });
+  }
+
+  async verifyImplementationItemArtifacts(implementationItemId, { requiredArtifacts = [] } = {}) {
+    const requiredKinds = Array.isArray(requiredArtifacts) ? requiredArtifacts : [];
+    const verifications = [];
+    const artifactReaders = {
+      artifact_manifest: async () => this.getArtifactManifest(implementationItemId),
+      decision_packet: async () => this.getDecisionPacket(implementationItemId),
+    };
+
+    for (const kind of requiredKinds) {
+      const reader = artifactReaders[kind];
+      if (typeof reader !== 'function') {
+        throw new Error(`Unsupported required artifact: ${kind}`);
+      }
+      const payload = await reader();
+      if (payload?.source_truth !== 'sql') {
+        throw buildVerificationError(`Artifact ${kind} did not declare SQL as source_truth.`, {
+          artifact_kind: kind,
+          verified_current_state: payload ?? null,
+        });
+      }
+      if (payload?.item_id !== implementationItemId) {
+        throw buildVerificationError(`Artifact ${kind} returned item_id ${payload?.item_id ?? 'unknown'} instead of ${implementationItemId}.`, {
+          artifact_kind: kind,
+          verified_current_state: payload ?? null,
+        });
+      }
+      const dataKey = kind === 'artifact_manifest' ? 'artifact_manifest' : 'decision_packet';
+      if (!isPlainObject(payload?.[dataKey])) {
+        throw buildVerificationError(`Artifact ${kind} did not include required ${dataKey} data.`, {
+          artifact_kind: kind,
+          verified_current_state: payload ?? null,
+        });
+      }
+      verifications.push({
+        artifact_kind: kind,
+        http_status: 200,
+        source_truth: payload.source_truth,
+        item_id: payload.item_id,
+        verified_current_state: payload[dataKey],
+      });
+    }
+
+    return {
+      itemId: implementationItemId,
+      requiredArtifacts: requiredKinds,
+      verified: true,
+      mutationVerificationEvidence: {
+        mutation_name: 'verifyImplementationItemArtifacts',
+        evidence_label: `implementation-item-artifacts:${implementationItemId}`,
+        mutation_attempted: false,
+        authoritative_read_performed: true,
+        post_condition_verified: true,
+        expected_state: { required_artifacts: requiredKinds },
+        verified_current_state: verifications,
+      },
+      artifacts: verifications,
+    };
+  }
+
   // ─── Skills ────────────────────────────────────────────────────────────────
 
   async currentSkillRegistryStatus() {