@elevasis/core 0.20.0 → 0.22.0

package/src/platform/registry/validation.ts

@@ -1,513 +1,743 @@
-/**
- * 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}`
-        )
-      }
-    })
-  })
-}
+/**
+ * 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 { ResourceEntry } from '../../organization-model/domains/resources'
+import type { SystemEntry } from '../../organization-model/domains/systems'
+import type {
+  TriggerDefinition,
+  ResourceRelationships,
+  ExternalResourceDefinition,
+  HumanCheckpointDefinition,
+  ResourceType
+} 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'
+  }
+}
+
+export type ResourceValidatorMode = 'strict' | 'warn-only'
+
+export type ResourceGovernanceValidationIssueType =
+  | 'missing-code-resource'
+  | 'missing-om-resource'
+  | 'type-mismatch'
+  | 'system-mismatch'
+  | 'missing-om-system'
+  | 'raw-resource-id'
+
+export interface ResourceGovernanceModel {
+  systems?: {
+    systems: SystemEntry[]
+  }
+  resources?: {
+    entries: ResourceEntry[]
+  }
+}
+
+export interface ResourceGovernanceValidationIssue {
+  type: ResourceGovernanceValidationIssueType
+  orgName: string
+  resourceId: string
+  message: string
+}
+
+export interface ResourceGovernanceValidationResult {
+  valid: boolean
+  mode: ResourceValidatorMode
+  issues: ResourceGovernanceValidationIssue[]
+}
+
+export interface ResourceGovernanceValidationOptions {
+  mode?: ResourceValidatorMode
+  onWarning?: (issue: ResourceGovernanceValidationIssue) => void
+}
+
+function getResourceValidatorMode(explicitMode?: ResourceValidatorMode): ResourceValidatorMode {
+  if (explicitMode) return explicitMode
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+  return env?.ELEVASIS_RESOURCE_VALIDATOR === 'warn-only' ? 'warn-only' : 'strict'
+}
+
+function addGovernanceIssue(
+  issues: ResourceGovernanceValidationIssue[],
+  type: ResourceGovernanceValidationIssueType,
+  orgName: string,
+  resourceId: string,
+  message: string
+): void {
+  issues.push({
+    type,
+    orgName,
+    resourceId,
+    message
+  })
+}
+
+function emitGovernanceIssues(
+  issues: ResourceGovernanceValidationIssue[],
+  mode: ResourceValidatorMode,
+  onWarning?: (issue: ResourceGovernanceValidationIssue) => void
+): void {
+  if (issues.length === 0) return
+
+  if (mode === 'strict') {
+    const first = issues[0]
+    throw new RegistryValidationError(first.orgName, first.resourceId, 'organizationModel.resources', first.message)
+  }
+
+  const warn = onWarning ?? ((issue: ResourceGovernanceValidationIssue) => console.warn(issue.message))
+  for (const issue of issues) {
+    warn(issue)
+  }
+}
+
+function getRuntimeResources(resources: DeploymentSpec): Array<{
+  resourceId: string
+  type: ResourceType
+  descriptor?: ResourceEntry
+}> {
+  return [
+    ...(resources.workflows ?? []).map((workflow) => ({
+      resourceId: workflow.config.resourceId,
+      type: workflow.config.type,
+      descriptor: workflow.config.resource
+    })),
+    ...(resources.agents ?? []).map((agent) => ({
+      resourceId: agent.config.resourceId,
+      type: agent.config.type,
+      descriptor: agent.config.resource
+    })),
+    ...(resources.integrations ?? []).map((integration) => ({
+      resourceId: integration.resourceId,
+      type: integration.type,
+      descriptor: (integration as { resource?: ResourceEntry }).resource
+    }))
+  ]
+}
+
+/**
+ * Validates runtime resource definitions against OM Resources and Systems.
+ *
+ * This is the shared core entry point for SDK, CI, deploy, and ResourceRegistry.
+ * Default mode is strict. ELEVASIS_RESOURCE_VALIDATOR=warn-only remains a
+ * permanent emergency escape hatch unless an explicit mode is passed.
+ */
+export function validateResourceGovernance(
+  orgName: string,
+  deployment: DeploymentSpec,
+  organizationModel: ResourceGovernanceModel | undefined = deployment.organizationModel,
+  options: ResourceGovernanceValidationOptions = {}
+): ResourceGovernanceValidationResult {
+  const mode = getResourceValidatorMode(options.mode)
+  const omResources = organizationModel?.resources?.entries
+  const omSystems = organizationModel?.systems?.systems
+  const issues: ResourceGovernanceValidationIssue[] = []
+
+  if (!omResources || !omSystems) {
+    return { valid: true, mode, issues }
+  }
+
+  const systemsById = new Map(omSystems.map((system) => [system.id, system]))
+  const activeOmResources = omResources.filter((resource) => resource.status === 'active')
+  const omResourcesById = new Map(activeOmResources.map((resource) => [resource.id, resource]))
+  const runtimeResources = getRuntimeResources(deployment)
+  const runtimeResourcesById = new Map(runtimeResources.map((resource) => [resource.resourceId, resource]))
+
+  for (const resource of activeOmResources) {
+    if (!systemsById.has(resource.systemId)) {
+      addGovernanceIssue(
+        issues,
+        'missing-om-system',
+        orgName,
+        resource.id,
+        `[${orgName}] OM resource '${resource.id}' references missing System '${resource.systemId}'.`
+      )
+    }
+
+    const runtimeResource = runtimeResourcesById.get(resource.id)
+    if (!runtimeResource) {
+      addGovernanceIssue(
+        issues,
+        'missing-code-resource',
+        orgName,
+        resource.id,
+        `[${orgName}] OM resource '${resource.id}' has no matching code-side resource.`
+      )
+      continue
+    }
+
+    if (runtimeResource.type !== resource.kind) {
+      addGovernanceIssue(
+        issues,
+        'type-mismatch',
+        orgName,
+        resource.id,
+        `[${orgName}] Resource '${resource.id}' type mismatch: code has '${runtimeResource.type}', OM has '${resource.kind}'.`
+      )
+    }
+
+    if (runtimeResource.descriptor && runtimeResource.descriptor.systemId !== resource.systemId) {
+      addGovernanceIssue(
+        issues,
+        'system-mismatch',
+        orgName,
+        resource.id,
+        `[${orgName}] Resource '${resource.id}' system mismatch: code descriptor has '${runtimeResource.descriptor.systemId}', OM has '${resource.systemId}'.`
+      )
+    }
+  }
+
+  for (const runtimeResource of runtimeResources) {
+    const omResource = omResourcesById.get(runtimeResource.resourceId)
+    if (!omResource) {
+      addGovernanceIssue(
+        issues,
+        'missing-om-resource',
+        orgName,
+        runtimeResource.resourceId,
+        `[${orgName}] Code-side resource '${runtimeResource.resourceId}' has no active OM Resource descriptor.`
+      )
+    }
+
+    if (!runtimeResource.descriptor) {
+      addGovernanceIssue(
+        issues,
+        'raw-resource-id',
+        orgName,
+        runtimeResource.resourceId,
+        `[${orgName}] Code-side resource '${runtimeResource.resourceId}' authors raw resourceId/type values. Use an OM Resource descriptor and bindResourceDescriptor().`
+      )
+      continue
+    }
+
+    if (runtimeResource.descriptor.id !== runtimeResource.resourceId) {
+      addGovernanceIssue(
+        issues,
+        'raw-resource-id',
+        orgName,
+        runtimeResource.resourceId,
+        `[${orgName}] Code-side resource '${runtimeResource.resourceId}' does not derive identity from its OM descriptor '${runtimeResource.descriptor.id}'.`
+      )
+    }
+
+    if (runtimeResource.descriptor.kind !== runtimeResource.type) {
+      addGovernanceIssue(
+        issues,
+        'type-mismatch',
+        orgName,
+        runtimeResource.resourceId,
+        `[${orgName}] Code-side resource '${runtimeResource.resourceId}' descriptor kind '${runtimeResource.descriptor.kind}' does not match runtime type '${runtimeResource.type}'.`
+      )
+    }
+  }
+
+  emitGovernanceIssues(issues, mode, options.onWarning)
+
+  return {
+    valid: issues.length === 0,
+    mode,
+    issues
+  }
+}
+
+// ============================================================================
+// 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)
+    }
+  })
+
+  validateResourceGovernance(orgName, resources)
+}
+
+/**
+ * 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}`
+        )
+      }
+    })
+  })
+}