@bpmsoftwaresolutions/ai-engine-client 1.1.15 → 1.1.17

package/package.json

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

package/src/index.js

@@ -1,4 +1,18 @@
 const DEFAULT_TIMEOUT_MS = 30000;
+export const AI_ENGINE_CLIENT_VERSION = '1.1.17';
+export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
+  'executeVerifiedMutation',
+  'post_mutation_verification',
+  'acceptance_check_read',
+  'artifact_manifest_read',
+  'decision_packet_read',
+  'claim_signoff',
+];
+export const AI_ENGINE_CLIENT_CAPABILITIES = [
+  ...GOVERNED_MUTATION_REQUIRED_CAPABILITIES,
+  'execution_eligibility_read',
+  'workflow_resume_context_read',
+];
 
 export const LOGA_CONTRACT = 'ai-engine-ui/v1';
 export const LOGA_INTERACTION_CONTRACT = 'loga-choreography/v1';
@@ -124,6 +138,13 @@ function buildVerificationError(message, details = {}) {
   return error;
 }
 
+function buildEligibilityError(message, details = {}) {
+  const error = new Error(message);
+  error.code = 'EXECUTION_ELIGIBILITY_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.');
@@ -135,6 +156,8 @@ export class AIEngineClient {
     this.actorId = actorId || 'sdk:npm-ai-engine-client';
     this.fetchImpl = fetchImpl || globalThis.fetch;
     this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
+    this.clientVersion = AI_ENGINE_CLIENT_VERSION;
+    this.clientCapabilities = [...AI_ENGINE_CLIENT_CAPABILITIES];
     if (typeof this.fetchImpl !== 'function') {
       throw new Error('A fetch implementation is required. Use Node 18+ or supply fetchImpl.');
     }
@@ -399,6 +422,17 @@ export class AIEngineClient {
     return this._request('/api/governance/claims/claim-work-item', { method: 'POST', body });
   }
 
+  async getExecutionEligibility(body = {}) {
+    return this._request('/api/governance/execution-eligibility', {
+      method: 'POST',
+      body: {
+        required_capabilities: GOVERNED_MUTATION_REQUIRED_CAPABILITIES,
+        verification_required: true,
+        ...body,
+      },
+    });
+  }
+
   async signoffClaim(claimId, body = {}) {
     if (!claimId) throw new Error('claimId is required.');
     return this._request(`/api/governance/claims/${encodeURIComponent(claimId)}/signoff`, {
@@ -1164,9 +1198,46 @@ export class AIEngineClient {
   }
 
   async updateImplementationItemStatus(implementationItemId, body) {
-    return this._request(`/api/governed-implementation/items/${implementationItemId}/status`, {
+    await this._assertExecutionEligibility({
+      ...(body || {}),
+      claimed_item_id: body?.claimed_item_id || implementationItemId,
+      requested_mutation_surface: body?.requested_mutation_surface || 'implementation_packet_item',
+      verification_required: true,
+    });
+    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) {
@@ -1186,6 +1257,12 @@ export class AIEngineClient {
   }
 
   async updateAcceptanceCheckStatus(implementationItemId, acceptanceCheckId, body) {
+    await this._assertExecutionEligibility({
+      ...(body || {}),
+      claimed_item_id: body?.claimed_item_id || implementationItemId,
+      requested_mutation_surface: body?.requested_mutation_surface || 'implementation_acceptance_check',
+      verification_required: true,
+    });
     return this._request(
       `/api/governed-implementation/items/${implementationItemId}/acceptance-checks/${acceptanceCheckId}/status`,
       { method: 'PATCH', body }
@@ -1316,15 +1393,17 @@ export class AIEngineClient {
   }
 
   async updateImplementationItemStatusVerified(implementationItemId, status, body = {}) {
-    const workflowId = cleanText(body.workflowId) || cleanText(body.workflow_id);
-    if (!workflowId) {
-      throw new Error('workflowId is required to verify implementation item status.');
-    }
     return this.executeVerifiedMutation({
       mutationName: 'updateImplementationItemStatus',
       evidenceLabel: `implementation-item-status:${implementationItemId}`,
       mutationFn: () => this.updateImplementationItemStatus(implementationItemId, { ...body, status }),
-      verificationFn: async () => {
+      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;
@@ -2002,6 +2081,8 @@ export class AIEngineClient {
     const resolvedHeaders = {
       accept: accept || 'application/json',
       'x-actor-id': this.actorId,
+      'x-ai-engine-client-version': this.clientVersion,
+      'x-ai-engine-client-capabilities': this.clientCapabilities.join(','),
       ...(isJsonBody(body) ? { 'content-type': 'application/json' } : {}),
       ...(token ? { authorization: `Bearer ${token}` } : {}),
       ...(!token && this.clientId ? { 'x-client-id': this.clientId } : {}),
@@ -2014,6 +2095,20 @@ export class AIEngineClient {
     return resolvedHeaders;
   }
 
+  async _assertExecutionEligibility(body = {}) {
+    const eligibility = await this.getExecutionEligibility(body);
+    if (eligibility?.execution_eligible && eligibility?.mutation_allowed) {
+      return eligibility;
+    }
+    throw buildEligibilityError(
+      `Execution eligibility gate blocked mutation${cleanText(body?.requested_mutation_surface) ? ` on ${cleanText(body.requested_mutation_surface)}` : ''}.`,
+      {
+        required_gate: eligibility?.required_gate || 'execution_eligibility.required_gate',
+        execution_eligibility: eligibility ?? null,
+      },
+    );
+  }
+
   async _request(path, { method = 'GET', query, headers, body } = {}) {
     const url = appendQuery(`${this.baseUrl}${path}`, query);
     const controller = new AbortController();