@elevasis/core 0.1.0

package/src/platform/registry/validation.ts

@@ -0,0 +1,513 @@
+/**
+ * Registry Validation Utilities
+ *
+ * Centralized validation logic for ResourceRegistry.
+ * All validation runs at API startup - fails fast in development.
+ */
+
+import type { z } from 'zod'
+import type { ModelConfig } from '../../execution/engine/llm/model-info'
+import { validateModelConfig, ModelConfigError } from '../../execution/engine/llm/errors'
+import type { DeploymentSpec } from './resource-registry'
+import type {
+  TriggerDefinition,
+  ResourceRelationships,
+  ExternalResourceDefinition,
+  HumanCheckpointDefinition
+} from './types'
+
+// ============================================================================
+// Validation Error Types
+// ============================================================================
+
+export class RegistryValidationError extends Error {
+  constructor(
+    public readonly orgName: string,
+    public readonly resourceId: string | null,
+    public readonly field: string | null,
+    message: string
+  ) {
+    super(message)
+    this.name = 'RegistryValidationError'
+  }
+}
+
+// ============================================================================
+// Resource Validation
+// ============================================================================
+
+/**
+ * Validates resources for a single organization
+ * - Duplicate resourceId check
+ * - Model configuration validation
+ * - ExecutionInterface-to-inputSchema validation
+ * @throws RegistryValidationError if validation fails
+ */
+export function validateDeploymentSpec(orgName: string, resources: DeploymentSpec): void {
+  const seenIds = new Set<string>()
+
+  // Validate workflows
+  resources.workflows?.forEach((workflow) => {
+    const id = workflow.config.resourceId
+
+    // Check for duplicate IDs
+    if (seenIds.has(id)) {
+      throw new RegistryValidationError(
+        orgName,
+        id,
+        null,
+        `Duplicate resourceId "${id}" in organization "${orgName}". ` +
+          `Workflows and agents must have unique IDs within an organization.`
+      )
+    }
+    seenIds.add(id)
+    // Validate model config if present (workflows may optionally have modelConfig)
+    if ('modelConfig' in workflow && workflow.modelConfig) {
+      validateResourceModelConfig(orgName, id, workflow.modelConfig as ModelConfig)
+    }
+
+    // Validate ExecutionInterface matches inputSchema
+    if (workflow.interface) {
+      validateExecutionInterface(orgName, id, workflow.interface, workflow.contract.inputSchema)
+    }
+  })
+
+  // Validate agents
+  resources.agents?.forEach((agent) => {
+    const id = agent.config.resourceId
+
+    // Check for duplicate IDs
+    if (seenIds.has(id)) {
+      throw new RegistryValidationError(
+        orgName,
+        id,
+        null,
+        `Duplicate resourceId "${id}" in organization "${orgName}". ` +
+          `Workflows and agents must have unique IDs within an organization.`
+      )
+    }
+    seenIds.add(id)
+
+    // Validate model config
+    validateResourceModelConfig(orgName, id, agent.modelConfig)
+
+    // Validate ExecutionInterface matches inputSchema
+    if (agent.interface) {
+      validateExecutionInterface(orgName, id, agent.interface, agent.contract.inputSchema)
+    }
+  })
+}
+
+/**
+ * Validates model configuration for a resource
+ */
+function validateResourceModelConfig(orgName: string, resourceId: string, modelConfig: ModelConfig): void {
+  try {
+    validateModelConfig(modelConfig)
+  } catch (error) {
+    if (error instanceof ModelConfigError) {
+      throw new RegistryValidationError(
+        orgName,
+        resourceId,
+        error.field,
+        `Invalid model config in ${orgName}/${resourceId}: ${error.message} (field: ${error.field})`
+      )
+    }
+    throw error
+  }
+}
+
+// ============================================================================
+// ExecutionInterface Validation
+// ============================================================================
+
+/**
+ * Validates that ExecutionInterface form fields match the inputSchema
+ *
+ * Checks:
+ * 1. All required fields in inputSchema have corresponding form fields
+ * 2. Form field names match schema field names (or have valid fieldMappings)
+ * 3. Required/optional alignment between form and schema
+ *
+ * @throws RegistryValidationError if interface doesn't match schema
+ */
+export function validateExecutionInterface(
+  orgName: string,
+  resourceId: string,
+  executionInterface: {
+    form: { fields: Array<{ name: string; required?: boolean }>; fieldMappings?: Record<string, string> }
+  },
+  inputSchema: z.ZodType
+): void {
+  const form = executionInterface.form
+  const fieldMappings = form.fieldMappings ?? {}
+
+  // Extract schema shape (only works for ZodObject)
+  const schemaShape = extractZodShape(inputSchema)
+  if (!schemaShape) {
+    // Can't validate non-object schemas - skip validation
+    return
+  }
+
+  const schemaFieldNames = Object.keys(schemaShape)
+
+  // Build effective mapping: form field name -> schema field name
+  const formToSchemaMap = new Map<string, string>()
+  for (const field of form.fields) {
+    const schemaKey = fieldMappings[field.name] ?? field.name
+    formToSchemaMap.set(field.name, schemaKey)
+  }
+
+  // Check 1: All required schema fields have form fields
+  for (const schemaFieldName of schemaFieldNames) {
+    const schemaField = schemaShape[schemaFieldName]
+    const isRequired = !isZodOptional(schemaField)
+
+    // Find form field that maps to this schema field
+    let hasFormField = false
+    for (const [formFieldName, mappedSchemaName] of Array.from(formToSchemaMap.entries())) {
+      if (mappedSchemaName === schemaFieldName) {
+        hasFormField = true
+
+        // Check required alignment
+        const formField = form.fields.find((f) => f.name === formFieldName)
+        if (isRequired && !formField?.required) {
+          throw new RegistryValidationError(
+            orgName,
+            resourceId,
+            `interface.form.fields.${formFieldName}`,
+            `ExecutionInterface field "${formFieldName}" should be required to match inputSchema field "${schemaFieldName}" in ${orgName}/${resourceId}`
+          )
+        }
+        break
+      }
+    }
+
+    if (isRequired && !hasFormField) {
+      throw new RegistryValidationError(
+        orgName,
+        resourceId,
+        'interface.form.fields',
+        `ExecutionInterface missing required field "${schemaFieldName}" from inputSchema in ${orgName}/${resourceId}`
+      )
+    }
+  }
+
+  // Check 2: All form fields map to valid schema fields
+  for (const [formFieldName, schemaFieldName] of Array.from(formToSchemaMap.entries())) {
+    // Detect nested field notation (e.g., "criteria.targetTitles") and suggest flattening
+    if (schemaFieldName.includes('.')) {
+      const topLevelField = schemaFieldName.split('.')[0]
+      throw new RegistryValidationError(
+        orgName,
+        resourceId,
+        `interface.form.fields.${formFieldName}`,
+        `ExecutionInterface field "${formFieldName}" uses nested notation. ` +
+          `Flatten the inputSchema by moving nested fields to top-level ` +
+          `(e.g., "${topLevelField}.x" → "x") in ${orgName}/${resourceId}`
+      )
+    }
+
+    if (!schemaFieldNames.includes(schemaFieldName)) {
+      throw new RegistryValidationError(
+        orgName,
+        resourceId,
+        `interface.form.fields.${formFieldName}`,
+        `ExecutionInterface field "${formFieldName}" maps to non-existent schema field "${schemaFieldName}" in ${orgName}/${resourceId}`
+      )
+    }
+  }
+}
+
+/**
+ * Extract shape from a Zod schema (handles ZodObject and wrapped types)
+ */
+function extractZodShape(schema: z.ZodType): Record<string, z.ZodType> | null {
+  // Handle ZodObject directly
+  if ('shape' in schema && typeof schema.shape === 'object') {
+    return schema.shape as Record<string, z.ZodType>
+  }
+
+  // Handle wrapped types (ZodEffects, ZodDefault, etc.)
+  if ('_def' in schema) {
+    const def = schema._def as { innerType?: z.ZodType; schema?: z.ZodType }
+    if (def.innerType) {
+      return extractZodShape(def.innerType)
+    }
+    if (def.schema) {
+      return extractZodShape(def.schema)
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if a Zod type is optional (or has a default)
+ * Uses isOptional() method which handles ZodOptional, ZodDefault, ZodNullable
+ */
+function isZodOptional(schema: z.ZodType): boolean {
+  // Zod provides isOptional() which returns true for optional, default, and nullable types
+  return schema.isOptional()
+}
+
+// ============================================================================
+// Relationship Validation
+// ============================================================================
+
+/**
+ * Validates relationship declarations reference valid resources
+ * @throws RegistryValidationError if validation fails
+ */
+export function validateRelationships(orgName: string, resources: DeploymentSpec): void {
+  // Skip if no manifest data
+  if (!resources.relationships && !resources.triggers && !resources.externalResources && !resources.humanCheckpoints)
+    return
+
+  // Build resource ID sets for validation
+  const validAgentIds = new Set(resources.agents?.map((a) => a.config.resourceId) ?? [])
+  const validWorkflowIds = new Set(resources.workflows?.map((w) => w.config.resourceId) ?? [])
+  const validIntegrationIds = new Set(resources.integrations?.map((i) => i.resourceId) ?? [])
+  const validTriggerIds = new Set(resources.triggers?.map((t) => t.resourceId) ?? [])
+
+  // Collect all internal resource IDs for uniqueness check
+  const allInternalIds = new Set([
+    ...Array.from(validAgentIds),
+    ...Array.from(validWorkflowIds),
+    ...Array.from(validTriggerIds),
+    ...Array.from(validIntegrationIds)
+  ])
+
+  // Validate triggers
+  validateTriggers(orgName, resources.triggers ?? [], validAgentIds, validWorkflowIds)
+
+  // Validate resource relationships
+  validateResourceRelationships(
+    orgName,
+    resources.relationships ?? {},
+    validAgentIds,
+    validWorkflowIds,
+    validIntegrationIds,
+    validTriggerIds
+  )
+
+  // Validate external resources
+  validateExternalResources(
+    orgName,
+    resources.externalResources ?? [],
+    allInternalIds,
+    validAgentIds,
+    validWorkflowIds,
+    validIntegrationIds
+  )
+
+  // Validate human checkpoints
+  validateHumanCheckpoints(orgName, resources.humanCheckpoints ?? [], allInternalIds, validAgentIds, validWorkflowIds)
+}
+
+/**
+ * Validates trigger invocations
+ * NOTE: Trigger relationships are declared in ResourceRelationships, not on TriggerDefinition
+ * This validation is now handled by validateResourceRelationships()
+ */
+function validateTriggers(
+  _orgName: string,
+  _triggers: TriggerDefinition[],
+  _validAgentIds: Set<string>,
+  _validWorkflowIds: Set<string>
+): void {
+  // No validation needed here - triggers declare their relationships in ResourceRelationships
+  // This prevents duplication and keeps all relationship declarations in one place
+}
+
+/**
+ * Validates resource relationship declarations
+ */
+function validateResourceRelationships(
+  orgName: string,
+  relationships: ResourceRelationships,
+  validAgentIds: Set<string>,
+  validWorkflowIds: Set<string>,
+  validIntegrationIds: Set<string>,
+  validTriggerIds: Set<string>
+): void {
+  for (const [resourceId, declaration] of Object.entries(relationships)) {
+    // Validate declaring resource exists (agents, workflows, or triggers can declare relationships)
+    const resourceExists =
+      validAgentIds.has(resourceId) || validWorkflowIds.has(resourceId) || validTriggerIds.has(resourceId)
+    if (!resourceExists) {
+      throw new RegistryValidationError(
+        orgName,
+        resourceId,
+        null,
+        `[${orgName}] Relationship declared for non-existent resource: ${resourceId}`
+      )
+    }
+
+    // Validate triggers.agents
+    declaration.triggers?.agents?.forEach((agentId) => {
+      if (!validAgentIds.has(agentId)) {
+        throw new RegistryValidationError(
+          orgName,
+          resourceId,
+          'triggers.agents',
+          `[${orgName}] Resource '${resourceId}' triggers non-existent agent: ${agentId}`
+        )
+      }
+    })
+
+    // Validate triggers.workflows
+    declaration.triggers?.workflows?.forEach((workflowId) => {
+      if (!validWorkflowIds.has(workflowId)) {
+        throw new RegistryValidationError(
+          orgName,
+          resourceId,
+          'triggers.workflows',
+          `[${orgName}] Resource '${resourceId}' triggers non-existent workflow: ${workflowId}`
+        )
+      }
+    })
+
+    // Validate uses.integrations
+    declaration.uses?.integrations?.forEach((integrationId) => {
+      if (!validIntegrationIds.has(integrationId)) {
+        throw new RegistryValidationError(
+          orgName,
+          resourceId,
+          'uses.integrations',
+          `[${orgName}] Resource '${resourceId}' uses non-existent integration: ${integrationId}`
+        )
+      }
+    })
+  }
+}
+
+/**
+ * Validates external resource definitions
+ */
+function validateExternalResources(
+  orgName: string,
+  externalResources: ExternalResourceDefinition[],
+  allInternalIds: Set<string>,
+  validAgentIds: Set<string>,
+  validWorkflowIds: Set<string>,
+  validIntegrationIds: Set<string>
+): void {
+  externalResources.forEach((external) => {
+    // Validate unique ID (no conflict with internal resources)
+    if (allInternalIds.has(external.resourceId)) {
+      throw new RegistryValidationError(
+        orgName,
+        external.resourceId,
+        null,
+        `[${orgName}] External resource ID '${external.resourceId}' conflicts with internal resource ID`
+      )
+    }
+
+    // Validate triggers (external -> internal)
+    external.triggers?.agents?.forEach((agentId) => {
+      if (!validAgentIds.has(agentId)) {
+        throw new RegistryValidationError(
+          orgName,
+          external.resourceId,
+          'triggers.agents',
+          `[${orgName}] External resource '${external.resourceId}' triggers non-existent agent: ${agentId}`
+        )
+      }
+    })
+
+    external.triggers?.workflows?.forEach((workflowId) => {
+      if (!validWorkflowIds.has(workflowId)) {
+        throw new RegistryValidationError(
+          orgName,
+          external.resourceId,
+          'triggers.workflows',
+          `[${orgName}] External resource '${external.resourceId}' triggers non-existent workflow: ${workflowId}`
+        )
+      }
+    })
+
+    // Validate uses integrations
+    external.uses?.integrations?.forEach((integrationId) => {
+      if (!validIntegrationIds.has(integrationId)) {
+        throw new RegistryValidationError(
+          orgName,
+          external.resourceId,
+          'uses.integrations',
+          `[${orgName}] External resource '${external.resourceId}' uses non-existent integration: ${integrationId}`
+        )
+      }
+    })
+  })
+}
+
+/**
+ * Validates human checkpoint definitions
+ */
+function validateHumanCheckpoints(
+  orgName: string,
+  humanCheckpoints: HumanCheckpointDefinition[],
+  allInternalIds: Set<string>,
+  validAgentIds: Set<string>,
+  validWorkflowIds: Set<string>
+): void {
+  humanCheckpoints.forEach((humanCheckpoint) => {
+    // Check for ID conflicts with internal resources
+    if (allInternalIds.has(humanCheckpoint.resourceId)) {
+      throw new RegistryValidationError(
+        orgName,
+        humanCheckpoint.resourceId,
+        null,
+        `[${orgName}] Human checkpoint ID '${humanCheckpoint.resourceId}' conflicts with internal resource ID`
+      )
+    }
+
+    // Validate requestedBy.agents exist
+    humanCheckpoint.requestedBy?.agents?.forEach((agentId) => {
+      if (!validAgentIds.has(agentId)) {
+        throw new RegistryValidationError(
+          orgName,
+          humanCheckpoint.resourceId,
+          'requestedBy.agents',
+          `[${orgName}] Human checkpoint '${humanCheckpoint.resourceId}' requestedBy non-existent agent: ${agentId}`
+        )
+      }
+    })
+
+    // Validate requestedBy.workflows exist
+    humanCheckpoint.requestedBy?.workflows?.forEach((workflowId) => {
+      if (!validWorkflowIds.has(workflowId)) {
+        throw new RegistryValidationError(
+          orgName,
+          humanCheckpoint.resourceId,
+          'requestedBy.workflows',
+          `[${orgName}] Human checkpoint '${humanCheckpoint.resourceId}' requestedBy non-existent workflow: ${workflowId}`
+        )
+      }
+    })
+
+    // Validate routesTo.agents exist
+    humanCheckpoint.routesTo?.agents?.forEach((agentId) => {
+      if (!validAgentIds.has(agentId)) {
+        throw new RegistryValidationError(
+          orgName,
+          humanCheckpoint.resourceId,
+          'routesTo.agents',
+          `[${orgName}] Human checkpoint '${humanCheckpoint.resourceId}' routesTo non-existent agent: ${agentId}`
+        )
+      }
+    })
+
+    // Validate routesTo.workflows exist
+    humanCheckpoint.routesTo?.workflows?.forEach((workflowId) => {
+      if (!validWorkflowIds.has(workflowId)) {
+        throw new RegistryValidationError(
+          orgName,
+          humanCheckpoint.resourceId,
+          'routesTo.workflows',
+          `[${orgName}] Human checkpoint '${humanCheckpoint.resourceId}' routesTo non-existent workflow: ${workflowId}`
+        )
+      }
+    })
+  })
+}