@bpmsoftwaresolutions/ai-engine-client 1.1.87 → 1.1.89

package/src/domains/charters.js

@@ -0,0 +1,5 @@
+export function createChartersDomain(client) {
+  return {
+    runCharter: (body = {}) => client._request('/api/charters/run', { method: 'POST', body }),
+  };
+}

package/src/domains/claims.js

@@ -0,0 +1,58 @@
+import { cleanText } from '../utils/text.js';
+
+export function createClaimsDomain(client) {
+  return {
+    getClaim: (claimId) => {
+      if (!claimId) throw new Error('claimId is required.');
+      return client._request(`/api/governance/claims/${encodeURIComponent(claimId)}`);
+    },
+    claimIsValid: async (claimId) => {
+      const claim = await client.getClaim(claimId);
+      return cleanText(claim?.status) === 'active';
+    },
+    signoffClaim: (claimId, body = {}) => {
+      if (!claimId) throw new Error('claimId is required.');
+      return client._request(`/api/governance/claims/${encodeURIComponent(claimId)}/signoff`, {
+        method: 'POST',
+        body,
+      });
+    },
+    promoteClaimSurface: ({
+      claimId,
+      workflowId,
+      contextSessionId,
+      actorId,
+      requiredToolKeys,
+      intentId,
+      bindingScope,
+      usageMode,
+      operatorScope,
+      allowedArgumentPolicy,
+      ...rest
+    } = {}) => {
+      if (!claimId) throw new Error('claimId is required.');
+      if (!workflowId) throw new Error('workflowId is required.');
+      if (!contextSessionId) throw new Error('contextSessionId is required.');
+      if (!actorId) throw new Error('actorId is required.');
+      if (!Array.isArray(requiredToolKeys) || requiredToolKeys.length === 0) {
+        throw new Error('requiredToolKeys must be a non-empty array.');
+      }
+      return client._request('/api/governance/claims/promote-surface', {
+        method: 'POST',
+        body: {
+          ...rest,
+          claim_id: claimId,
+          workflow_id: workflowId,
+          context_session_id: contextSessionId,
+          actor_id: actorId,
+          required_tool_keys: requiredToolKeys,
+          intent_id: intentId,
+          binding_scope: bindingScope,
+          usage_mode: usageMode,
+          operator_scope: operatorScope,
+          allowed_argument_policy: allowedArgumentPolicy,
+        },
+      });
+    },
+  };
+}

package/src/domains/commit-governance.js

@@ -0,0 +1,68 @@
+export function createCommitGovernanceDomain(client) {
+  return {
+    evaluateCommitGovernance: ({
+      claimId,
+      contextSessionId,
+      agentId,
+      intentId,
+      changedFiles,
+      declaredScopeFiles,
+      diffSummary,
+      branch,
+      headSha,
+    } = {}) => client._request('/api/commit-governance/evaluate', {
+      method: 'POST',
+      body: {
+        claim_id: claimId,
+        context_session_id: contextSessionId,
+        agent_id: agentId,
+        intent_id: intentId,
+        changed_files: changedFiles,
+        declared_scope_files: declaredScopeFiles,
+        diff_summary: diffSummary,
+        branch,
+        head_sha: headSha,
+      },
+    }),
+    checkGitShipReadiness: ({
+      claimId,
+      actorId,
+      targetBranch,
+      shipCommand,
+      packageName,
+      declaredScopeFiles,
+      stagedFiles,
+      dirtyFiles,
+      branch,
+      headSha,
+      packageJsonVersion,
+      facadeMinClientVersion,
+      packageRelease,
+      packageJsonHash,
+      sdkVersionHash,
+    } = {}) => client._request('/api/commit-governance/ship-readiness', {
+      method: 'POST',
+      body: {
+        claim_id: claimId,
+        actor_id: actorId,
+        target_branch: targetBranch,
+        ship_command: shipCommand,
+        package_name: packageName,
+        declared_scope_files: declaredScopeFiles,
+        staged_files: stagedFiles,
+        dirty_files: dirtyFiles,
+        branch,
+        head_sha: headSha,
+        package_json_version: packageJsonVersion,
+        facade_min_client_version: facadeMinClientVersion,
+        package_release: packageRelease,
+        package_json_hash: packageJsonHash,
+        sdk_version_hash: sdkVersionHash,
+      },
+    }),
+    getCommitGovernanceEvaluation: (evaluationId) => client._request(`/api/commit-governance/evaluations/${encodeURIComponent(evaluationId)}`),
+    listCommitGovernanceEvaluationsByClaim: (claimId, { limit } = {}) => client._request(`/api/commit-governance/claims/${encodeURIComponent(claimId)}/evaluations`, {
+      query: { limit },
+    }),
+  };
+}

package/src/domains/context-orientation.js

@@ -0,0 +1,48 @@
+export function createContextOrientationDomain(client) {
+  return {
+    conductOrientation: async ({
+      agentId,
+      runtimeSessionId,
+      intentId,
+      executionPurpose,
+      agentSignature,
+      understandingSummary,
+      lockClaim = true,
+    } = {}) => {
+      const { context_session, reminders } = await client.contextSessions.openContextSession({
+        agentId,
+        runtimeSessionId,
+        intentId,
+        executionPurpose,
+      });
+      const sessionId = context_session.context_session_id;
+
+      const required = (reminders || []).filter((reminder) => reminder.severity === 'required');
+      let acknowledgedCount = 0;
+      for (const reminder of required) {
+        await client.contextSessions.acknowledgeReminder(sessionId, {
+          reminderId: reminder.reminder_id,
+          agentSignature,
+          understandingSummary,
+        });
+        acknowledgedCount++;
+      }
+
+      const completion = await client.contextSessions.completeOrientation(sessionId);
+
+      let claimLockResult = null;
+      if (lockClaim) {
+        claimLockResult = await client.contextSessions.lockContextSessionClaim(sessionId);
+      }
+
+      return {
+        context_session_id: sessionId,
+        intent_id: intentId,
+        context_session: claimLockResult?.context_session || completion.context_session,
+        gate_result: claimLockResult?.gate_result || completion.gate_result,
+        acknowledged_count: acknowledgedCount,
+        claim_locked: lockClaim && !!claimLockResult,
+      };
+    },
+  };
+}

package/src/domains/context-sessions.js

@@ -0,0 +1,46 @@
+import { cleanText } from '../utils/text.js';
+
+export function contextSessionIdFromInput(input) {
+  if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+    return cleanText(input.contextSessionId)
+      || cleanText(input.context_session_id)
+      || cleanText(input.context_session?.context_session_id)
+      || cleanText(input.claim?.context_session_id);
+  }
+  return cleanText(input);
+}
+
+export function createContextSessionsDomain(client) {
+  return {
+    openContextSession: ({ agentId, runtimeSessionId, intentId, executionPurpose, notes } = {}) => client._request('/api/context-session/open', {
+      method: 'POST',
+      body: {
+        agent_id: agentId,
+        runtime_session_id: runtimeSessionId,
+        intent_id: intentId,
+        execution_purpose: executionPurpose,
+        notes,
+      },
+    }),
+    getOrientationWindow: (contextSessionId) => client._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/window`),
+    acknowledgeReminder: (contextSessionId, { reminderId, agentSignature, understandingSummary } = {}) => client._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/acknowledge`, {
+      method: 'POST',
+      body: {
+        reminder_id: reminderId,
+        agent_signature: agentSignature,
+        understanding_summary: understandingSummary,
+      },
+    }),
+    completeOrientation: (contextSessionId) => client._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/complete`, {
+      method: 'POST',
+    }),
+    lockContextSessionClaim: (input) => {
+      const contextSessionId = contextSessionIdFromInput(input);
+      if (!contextSessionId) throw new Error('contextSessionId is required.');
+      return client._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/lock-claim`, {
+        method: 'POST',
+      });
+    },
+    getContextSessionGateStatus: (contextSessionId) => client._request(`/api/context-session/${encodeURIComponent(contextSessionId)}/gate-status`),
+  };
+}

package/src/domains/execution-eligibility.js

@@ -0,0 +1,44 @@
+import { cleanText } from '../utils/text.js';
+import { GOVERNED_MUTATION_REQUIRED_CAPABILITIES } from '../constants/governance.js';
+
+export function buildEligibilityError(message, details = {}) {
+  const error = new Error(message);
+  error.code = 'EXECUTION_ELIGIBILITY_FAILED';
+  error.details = details;
+  return error;
+}
+
+export function createExecutionEligibilityDomain(client) {
+  return {
+    getExecutionEligibility: (body = {}) => client._request('/api/governance/execution-eligibility', {
+      method: 'POST',
+      body: {
+        required_capabilities: GOVERNED_MUTATION_REQUIRED_CAPABILITIES,
+        verification_required: true,
+        ...body,
+      },
+    }),
+    _assertExecutionEligibility: async (body = {}) => {
+      const eligibility = await client.getExecutionEligibility(body);
+      if (eligibility?.execution_eligible && eligibility?.mutation_allowed) {
+        return eligibility;
+      }
+      const remediation = cleanText(eligibility?.remediation_command);
+      const verification = cleanText(eligibility?.verification_command);
+      throw buildEligibilityError(
+        [
+          `Execution eligibility gate blocked mutation${cleanText(body?.requested_mutation_surface) ? ` on ${cleanText(body.requested_mutation_surface)}` : ''}.`,
+          remediation ? `Fix: ${remediation}` : null,
+          verification ? `Then verify: ${verification}` : null,
+        ].filter(Boolean).join(' '),
+        {
+          required_gate: eligibility?.required_gate || 'execution_eligibility.required_gate',
+          execution_eligibility: eligibility ?? null,
+          requested_mutation_surface: cleanText(body?.requested_mutation_surface) || null,
+          remediation_command: remediation || null,
+          verification_command: verification || null,
+        },
+      );
+    },
+  };
+}

package/src/domains/governed-implementation.js

@@ -0,0 +1,7 @@
+export function createGovernedImplementationDomain(client) {
+  return {
+    getExecutionEligibility: (body = {}) => client.executionEligibility.getExecutionEligibility(body),
+    _assertExecutionEligibility: (body = {}) => client.executionEligibility._assertExecutionEligibility(body),
+    executeVerifiedMutation: (request = {}) => client.verifiedMutations.executeVerifiedMutation(request),
+  };
+}

package/src/domains/implementation-artifacts.js

@@ -1,6 +1,67 @@
+import { isPlainObject } from '../utils/text.js';
+import { buildVerificationError } from '../utils/verified-mutations.js';
+
 export function createImplementationArtifactsDomain(client) {
   return {
     getArtifactManifest: (implementationItemId) => client._request(`/api/governed-implementation/items/${implementationItemId}/artifact-manifest`),
     getDecisionPacket: (implementationItemId) => client._request(`/api/governed-implementation/items/${implementationItemId}/decision-packet`),
+    verifyImplementationItemArtifacts: async (implementationItemId, { requiredArtifacts = [] } = {}) => {
+      const requiredKinds = Array.isArray(requiredArtifacts) ? requiredArtifacts : [];
+      const verifications = [];
+      const artifactReaders = {
+        artifact_manifest: async () => client.getArtifactManifest(implementationItemId),
+        decision_packet: async () => client.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,
+      };
+    },
   };
 }

package/src/domains/implementation-checks.js

@@ -0,0 +1,41 @@
+import { executeVerifiedMutation } from '../utils/verified-mutations.js';
+
+export function createImplementationChecksDomain(client) {
+  return {
+    getImplementationItemAcceptanceChecks: (implementationItemId) => client._request(`/api/governed-implementation/items/${implementationItemId}/acceptance-checks`),
+    updateAcceptanceCheckStatus: (implementationItemId, acceptanceCheckId, body) => {
+      client._assertExecutionEligibility({
+        ...(body || {}),
+        claimed_item_id: body?.claimed_item_id || implementationItemId,
+        requested_mutation_surface: body?.requested_mutation_surface || 'implementation_acceptance_check',
+        verification_required: true,
+      });
+      return client._request(
+        `/api/governed-implementation/items/${implementationItemId}/acceptance-checks/${acceptanceCheckId}/status`,
+        { method: 'PATCH', body }
+      );
+    },
+    updateAcceptanceCheckStatusVerified: (implementationItemId, acceptanceCheckId, status, body = {}) => executeVerifiedMutation({
+      mutationName: 'updateAcceptanceCheckStatus',
+      evidenceLabel: `acceptance-check-status:${implementationItemId}:${acceptanceCheckId}`,
+      mutationFn: () => client.updateAcceptanceCheckStatus(implementationItemId, acceptanceCheckId, { ...body, status }),
+      verificationFn: async () => client.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,
+        };
+      },
+    }),
+  };
+}

package/src/domains/implementation-items.js

@@ -1,94 +1,9 @@
+import { cleanText, isPlainObject } from '../utils/text.js';
+import { buildVerificationError, executeVerifiedMutation } from '../utils/verified-mutations.js';
+
 export function createImplementationItemsDomain(client) {
   return {
-    createImplementationTask: async (implementationItemId, {
-      title,
-      implementationPacketId,
-      description,
-      priority,
-      assignedTo,
-      assignedBy,
-      dueAt,
-      sortOrder,
-      notes,
-      createdBy,
-      parentTaskId,
-      claimId,
-      claimProjectId,
-      projectId,
-      claimedItemId,
-      workflowRunId,
-      agentSessionId,
-      allowedMutationSurfaces,
-      acknowledgedReminders,
-      executionIntent,
-      executionType,
-      executionPurpose,
-    } = {}) => {
-      const normalizedClaimId = String(claimId || '').trim() || null;
-      const normalizedClaimProjectId = String(claimProjectId || projectId || '').trim() || null;
-      const normalizedClaimedItemId = String(claimedItemId || implementationItemId || '').trim() || null;
-      const normalizedWorkflowRunId = String(workflowRunId || '').trim() || null;
-      const normalizedAgentSessionId = String(agentSessionId || '').trim() || null;
-      const normalizedAllowedMutationSurfaces = Array.isArray(allowedMutationSurfaces) && allowedMutationSurfaces.length > 0
-        ? allowedMutationSurfaces
-        : ['project_roadmap_task'];
-      const normalizedAcknowledgedReminders = Array.isArray(acknowledgedReminders)
-        ? acknowledgedReminders
-        : undefined;
-      const normalizedExecutionIntent = (() => {
-        if (executionIntent && typeof executionIntent === 'object') {
-          const execution_type = String(executionIntent.execution_type || executionIntent.executionType || '').trim();
-          const execution_purpose = String(executionIntent.execution_purpose || executionIntent.executionPurpose || '').trim();
-          if (execution_type || execution_purpose) {
-            return {
-              ...(execution_type ? { execution_type } : {}),
-              ...(execution_purpose ? { execution_purpose } : {}),
-            };
-          }
-        }
-        const normalizedExecutionType = String(executionType || '').trim() || 'implementation_task';
-        const normalizedExecutionPurpose = String(executionPurpose || title || '').trim() || 'implementation task';
-        return {
-          execution_type: normalizedExecutionType,
-          execution_purpose: normalizedExecutionPurpose,
-        };
-      })();
-      await client._assertExecutionEligibility({
-        claim_id: normalizedClaimId,
-        claim_project_id: normalizedClaimProjectId,
-        claimed_item_id: normalizedClaimedItemId,
-        workflow_run_id: normalizedWorkflowRunId,
-        agent_session_id: normalizedAgentSessionId,
-        allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
-        acknowledged_reminders: normalizedAcknowledgedReminders || [],
-        requested_mutation_surface: 'project_roadmap_task',
-        verification_required: true,
-      });
-      return client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`, {
-        method: 'POST',
-        body: {
-          title,
-          implementation_packet_id: implementationPacketId,
-          description,
-          priority,
-          assigned_to: assignedTo,
-          assigned_by: assignedBy,
-          due_at: dueAt,
-          sort_order: sortOrder,
-          notes,
-          created_by: createdBy,
-          parent_task_id: parentTaskId,
-          claim_id: normalizedClaimId,
-          claim_project_id: normalizedClaimProjectId,
-          claimed_item_id: normalizedClaimedItemId,
-          workflow_run_id: normalizedWorkflowRunId,
-          agent_session_id: normalizedAgentSessionId,
-          allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
-          acknowledged_reminders: normalizedAcknowledgedReminders,
-          execution_intent: normalizedExecutionIntent,
-        },
-      });
-    },
+    createImplementationTask: (implementationItemId, request) => client.implementationTasks.createImplementationTask(implementationItemId, request),
     listImplementationTasks: (implementationItemId) => client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`),
     listImplementationSubtasks: (taskId) => client._request(`/api/operator/implementation-item-tasks/${taskId}/subtasks`),
     updateImplementationTask: (taskId, updates) => client._request(`/api/operator/implementation-item-tasks/${taskId}`, {
@@ -103,5 +18,83 @@ export function createImplementationItemsDomain(client) {
       method: 'POST',
       body: { completed_by: request.completedBy },
     }),
+    updateImplementationItemStatus: async (implementationItemId, body) => {
+      await client._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 client._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;
+    },
+    updateImplementationItemStatusVerified: (implementationItemId, status, body = {}) => executeVerifiedMutation({
+      mutationName: 'updateImplementationItemStatus',
+      evidenceLabel: `implementation-item-status:${implementationItemId}`,
+      mutationFn: () => client.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 client.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,
+        };
+      },
+    }),
   };
 }