@bpmsoftwaresolutions/ai-engine-client 1.1.87 → 1.1.89

package/src/domains/workflow-turns.js

@@ -0,0 +1,6 @@
+export function createWorkflowTurnsDomain(client) {
+  return {
+    completeTurn: (body = {}) => client._request('/api/turns/complete', { method: 'POST', body }),
+    persistAssistantTurn: (body) => client._request('/api/v1/assistant-turns', { method: 'POST', body }),
+  };
+}

package/src/index.js

@@ -1,5 +1,5 @@
 export { AIEngineClient, createAIEngineClient } from './client.js';
-export const AI_ENGINE_CLIENT_VERSION = '1.1.87';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.89';
 export { GOVERNED_MUTATION_REQUIRED_CAPABILITIES, AI_ENGINE_CLIENT_CAPABILITIES, TASK_BOUND_SUBSTRATE_EXECUTION_POLICY } from './constants/governance.js';
 export { LOGA_CONTRACT, LOGA_INTERACTION_CONTRACT, LOGA_NAVIGATION_CONTRACT, LOGA_PROJECTION_WORKFLOW } from './constants/loga.js';
 export {

package/src/utils/task-binding.js

@@ -0,0 +1,31 @@
+import { TASK_BOUND_SUBSTRATE_EXECUTION_POLICY } from '../constants/governance.js';
+import { cleanList, cleanText, isPlainObject } from './text.js';
+
+export function normalizeTaskBindingPolicy(taskBinding, { expectedAction = null } = {}) {
+  if (!isPlainObject(taskBinding)) return taskBinding;
+  const taskId = cleanText(taskBinding.task_id || taskBinding.implementation_item_task_id);
+  const roadmapItemId = cleanText(taskBinding.roadmap_item_id || taskBinding.implementation_item_id);
+  const taskStatus = cleanText(taskBinding.task_status || taskBinding.status);
+  const allowedActions = cleanList(taskBinding.allowed_actions);
+  const substrateAction = cleanText(taskBinding.substrate_action) || cleanText(expectedAction);
+  return {
+    ...taskBinding,
+    ...(taskId ? { task_id: taskId } : {}),
+    ...(roadmapItemId ? { roadmap_item_id: roadmapItemId, implementation_item_id: roadmapItemId } : {}),
+    ...(taskStatus ? { task_status: taskStatus } : {}),
+    ...(allowedActions.length > 0 ? { allowed_actions: allowedActions } : {}),
+    ...(substrateAction ? { substrate_action: substrateAction } : {}),
+    policy_key: cleanText(taskBinding.policy_key) || 'task_bound_substrate_execution',
+    policy_version: cleanText(taskBinding.policy_version) || 'v1',
+    policy_identifier: cleanText(taskBinding.policy_identifier) || TASK_BOUND_SUBSTRATE_EXECUTION_POLICY,
+  };
+}
+
+export function normalizeMetadataTaskBinding(metadata, { expectedAction = null } = {}) {
+  if (!isPlainObject(metadata)) return metadata;
+  if (!isPlainObject(metadata.task_binding)) return metadata;
+  return {
+    ...metadata,
+    task_binding: normalizeTaskBindingPolicy(metadata.task_binding, { expectedAction }),
+  };
+}

package/src/utils/verified-mutations.js

@@ -0,0 +1,128 @@
+import { cleanText, isPlainObject } from './text.js';
+
+export function buildVerificationError(message, details = {}) {
+  const error = new Error(message);
+  error.code = 'POST_CONDITION_VERIFICATION_FAILED';
+  error.details = details;
+  return error;
+}
+
+export 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);
+}
+
+export function 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;
+
+  return (async () => {
+    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,
+    };
+  })();
+}