@maykonpaulo/maestro-core 0.3.0-next.3 → 0.3.0-next.4

package/dist/index.d.ts

@@ -650,6 +650,10 @@ declare class MetadataRiskClassifier implements RiskClassifier {
     classify(input: RiskClassificationInput): OperationalRisk;
 }
 
+interface EnumOptionDeclaration {
+    value: string | number;
+    label: string;
+}
 interface FieldDeclaration {
     type: FieldType;
     label?: string;
@@ -663,6 +667,10 @@ interface FieldDeclaration {
     filterable?: boolean;
     exportable?: boolean;
     description?: string;
+    /** Options for enum fields. Only valid when type is 'enum'. */
+    enumOptions?: EnumOptionDeclaration[];
+    /** Target entity identifier for relation fields. Only valid when type is 'relation'. */
+    relationEntity?: string;
 }
 interface ConfirmationDeclaration {
     required: boolean;
@@ -677,6 +685,23 @@ interface OperationDeclaration {
     confirmation?: ConfirmationDeclaration;
     permission?: string;
 }
+interface RelationDeclaration {
+    /** Explicit relation identifier. Derived as `${fromEntity}.${toEntity}` when absent. */
+    id?: string;
+    type: RelationType;
+    /** Field in the declaring entity that holds the foreign key or join key. */
+    fromField: string;
+    /** Identifier of the target entity. Cross-entity references are validated at startup. */
+    toEntity: string;
+    /** Field in the target entity that the relation points to. */
+    toField: string;
+    /** Human-readable label. Defaults to capitalizeFirst(toEntity) when absent. */
+    label?: string;
+    display?: {
+        tab?: boolean;
+        label?: string;
+    };
+}
 interface EntityDeclaration {
     entity: string;
     /** Human-readable singular label (e.g. "User"). */
@@ -685,7 +710,11 @@ interface EntityDeclaration {
     pluralLabel?: string;
     description?: string;
     fields: Record<string, FieldDeclaration>;
+    /** Capability overrides merged over DEFAULT_CAPABILITIES at startup. */
+    capabilities?: Partial<EntityCapabilities>;
     operations?: Record<string, OperationDeclaration>;
+    /** Relationships from this entity to other entities. Cross-entity refs are validated at startup. */
+    relationships?: RelationDeclaration[];
 }
 
 interface ConsumerListConfig {
@@ -1305,6 +1334,8 @@ interface DeclarativeCompilationResult {
     operations: OperationDef[];
     /** Validated consumer declarations ready for resolution after metadata is built. */
     consumers: ConsumerDeclaration[];
+    /** Relation schemas derived from RelationDeclaration[]. Cross-entity refs validated at startup. */
+    relations: RelationSchema[];
 }
 interface CompileDeclarationsOptions {
     datasourceIds: string[];
@@ -1397,4 +1428,4 @@ declare class DefaultGovernanceApi implements GovernanceApi {
     getPolicyViolations(filter?: PolicyViolationFilter): Promise<PolicyViolation[]>;
 }
 
-export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, type AuditRecordedPayload, AuditRecorder, type AuditRepository, type AuditTimeline, type AuthorizationContext, type AuthorizationDecision, type AuthorizationDeniedPayload, type AuthorizationProvider, type AuthorizationResult, type CompileDeclarationsOptions, type ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, type ConfirmationDeclaration, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, type ConsumerActionsConfig, type ConsumerDeclaration, type ConsumerDetailConfig, type ConsumerFormConfig, type ConsumerFormsConfig, type ConsumerListConfig, type ConsumerProjectionFields, type ConsumerProjectionOperations, type ContextAction, type ContextActionCondition, type ContextActionStyle, ContextualAuthorizationEngine, type CorrelationContext, type CorrelationId, type CreateMaestroFromIntrospectionOptions, CsvExportProvider, type CursorPagination, DEFAULT_CAPABILITIES, type DatasourceDeleteContext, type DatasourceFindContext, type DatasourceProvider, type DatasourceQueryContext, DatasourceRegistry, type DatasourceUpdateContext, type DatasourceWriteContext, type DeclarativeCompilationResult, type DeclarativeConfig, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, type EntityDeclaration, type EntityDiffChange, type EntityDiffChangeKind, type EntityExportConfig, type EntityIntrospectionSchema, type EntityLabelConfig, type EntityMetadata, type EntitySchema, type EntitySourceConfig, type EnumOption, ErrorCode, type EventBus, type EventHandler, type ExportConfig, type ExportFormat, type ExportOptions, type ExportProvider, type ExportResult, type FeatureFlag, type FeatureFlagProvider, type FieldDeclaration, type FieldDetailConfig, type FieldDiffChange, type FieldDiffChangeKind, type FieldFormConfig, type FieldIntrospectionSchema, type FieldListConfig, type FieldMetadata, type FieldSchema, type FieldSchemaDetailConfig, type FieldSchemaEnumOption, type FieldSchemaFormConfig, type FieldSchemaListConfig, type FieldType, type FileSystemReader, type FilterDescriptor, type FilterOperator, GOVERNANCE_EVENT_TYPES, type GeneratedConfig, type GovernanceApi, type GovernanceEventBus, type GovernanceEventType, type ImpactLevel, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryConfirmationRepository, InMemoryDatasourceProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, InMemoryGovernanceEventBus, InMemoryPolicyProvider, InMemorySnapshotRepository, type IndexIntrospectionSchema, type IntrospectionDiff, type IntrospectionProvider, type IntrospectionReport, type IntrospectionReportChange, type IntrospectionReportStats, type IntrospectionResult, IntrospectionRuntime, type IntrospectionRuntimeResult, type IntrospectionRuntimeRunOptions, type IntrospectionSnapshot, type ListResult, type LoadedConfig, type LogEntry, type LogLevel, type Logger, type MaestroActorResolver, type MaestroConfig, MaestroEngine, MaestroError, type MaestroFileLoaderOptions, type MaestroHttpHandler, type MaestroHttpHandlers, type MaestroHttpOptions, type MaestroHttpRequest, type MaestroHttpResponse, type MaestroMetadata, type MaestroRequestContext, type MergeIntrospectionOptions, type MergeStrategy, type Metadata, MetadataEngine, MetadataRiskClassifier, type MetadataValue, type OffsetPagination, type OperationContext, type OperationDeclaration, type OperationDef, type OperationExecutedPayload, type OperationLogStatus, type OperationMetadata, OperationRegistry, type OperationResult, type OperationScope, type OperationalRisk, type PagePagination, type PaginationInput, type Permission, type PolicyContext, type PolicyDecision, PolicyEngine, type PolicyEvaluationResult, type PolicyProvider, type PolicyRule, type PolicyRuleResult, type PolicyTriggeredPayload, type PolicyViolation, type PolicyViolationFilter, type QueryInput, RbacEngine, type RbacPolicy, type RecordAuditInput, type RelationDiffChange, type RelationDiffChangeKind, type RelationDisplayConfig, type RelationEndpoint, type RelationIntrospectionSchema, type RelationMetadata, type RelationSchema, type RelationType, ReportGenerator, type RequestConfirmationInput, type ResolvedConsumerProjection, type ResourceRef, type RiskClassificationInput, type RiskClassifier, type Role, type SchemaValidationError, type SchemaValidationResult, type SearchConfig, type SearchInput, type SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, resolveConsumerProjections, tableNameToEntityId, tableNameToLabel, validateConsumerDeclaration, validateEntityDeclaration, validateMaestroConfig };
+export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, type AuditRecordedPayload, AuditRecorder, type AuditRepository, type AuditTimeline, type AuthorizationContext, type AuthorizationDecision, type AuthorizationDeniedPayload, type AuthorizationProvider, type AuthorizationResult, type CompileDeclarationsOptions, type ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, type ConfirmationDeclaration, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, type ConsumerActionsConfig, type ConsumerDeclaration, type ConsumerDetailConfig, type ConsumerFormConfig, type ConsumerFormsConfig, type ConsumerListConfig, type ConsumerProjectionFields, type ConsumerProjectionOperations, type ContextAction, type ContextActionCondition, type ContextActionStyle, ContextualAuthorizationEngine, type CorrelationContext, type CorrelationId, type CreateMaestroFromIntrospectionOptions, CsvExportProvider, type CursorPagination, DEFAULT_CAPABILITIES, type DatasourceDeleteContext, type DatasourceFindContext, type DatasourceProvider, type DatasourceQueryContext, DatasourceRegistry, type DatasourceUpdateContext, type DatasourceWriteContext, type DeclarativeCompilationResult, type DeclarativeConfig, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, type EntityDeclaration, type EntityDiffChange, type EntityDiffChangeKind, type EntityExportConfig, type EntityIntrospectionSchema, type EntityLabelConfig, type EntityMetadata, type EntitySchema, type EntitySourceConfig, type EnumOption, type EnumOptionDeclaration, ErrorCode, type EventBus, type EventHandler, type ExportConfig, type ExportFormat, type ExportOptions, type ExportProvider, type ExportResult, type FeatureFlag, type FeatureFlagProvider, type FieldDeclaration, type FieldDetailConfig, type FieldDiffChange, type FieldDiffChangeKind, type FieldFormConfig, type FieldIntrospectionSchema, type FieldListConfig, type FieldMetadata, type FieldSchema, type FieldSchemaDetailConfig, type FieldSchemaEnumOption, type FieldSchemaFormConfig, type FieldSchemaListConfig, type FieldType, type FileSystemReader, type FilterDescriptor, type FilterOperator, GOVERNANCE_EVENT_TYPES, type GeneratedConfig, type GovernanceApi, type GovernanceEventBus, type GovernanceEventType, type ImpactLevel, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryConfirmationRepository, InMemoryDatasourceProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, InMemoryGovernanceEventBus, InMemoryPolicyProvider, InMemorySnapshotRepository, type IndexIntrospectionSchema, type IntrospectionDiff, type IntrospectionProvider, type IntrospectionReport, type IntrospectionReportChange, type IntrospectionReportStats, type IntrospectionResult, IntrospectionRuntime, type IntrospectionRuntimeResult, type IntrospectionRuntimeRunOptions, type IntrospectionSnapshot, type ListResult, type LoadedConfig, type LogEntry, type LogLevel, type Logger, type MaestroActorResolver, type MaestroConfig, MaestroEngine, MaestroError, type MaestroFileLoaderOptions, type MaestroHttpHandler, type MaestroHttpHandlers, type MaestroHttpOptions, type MaestroHttpRequest, type MaestroHttpResponse, type MaestroMetadata, type MaestroRequestContext, type MergeIntrospectionOptions, type MergeStrategy, type Metadata, MetadataEngine, MetadataRiskClassifier, type MetadataValue, type OffsetPagination, type OperationContext, type OperationDeclaration, type OperationDef, type OperationExecutedPayload, type OperationLogStatus, type OperationMetadata, OperationRegistry, type OperationResult, type OperationScope, type OperationalRisk, type PagePagination, type PaginationInput, type Permission, type PolicyContext, type PolicyDecision, PolicyEngine, type PolicyEvaluationResult, type PolicyProvider, type PolicyRule, type PolicyRuleResult, type PolicyTriggeredPayload, type PolicyViolation, type PolicyViolationFilter, type QueryInput, RbacEngine, type RbacPolicy, type RecordAuditInput, type RelationDeclaration, type RelationDiffChange, type RelationDiffChangeKind, type RelationDisplayConfig, type RelationEndpoint, type RelationIntrospectionSchema, type RelationMetadata, type RelationSchema, type RelationType, ReportGenerator, type RequestConfirmationInput, type ResolvedConsumerProjection, type ResourceRef, type RiskClassificationInput, type RiskClassifier, type Role, type SchemaValidationError, type SchemaValidationResult, type SearchConfig, type SearchInput, type SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, resolveConsumerProjections, tableNameToEntityId, tableNameToLabel, validateConsumerDeclaration, validateEntityDeclaration, validateMaestroConfig };

package/dist/index.js

@@ -1191,6 +1191,12 @@ var SUPPORTED_FIELD_TYPES = [
 ];
 var SUPPORTED_OPERATIONAL_RISKS = ["LOW", "MEDIUM", "HIGH", "CRITICAL"];
 var SUPPORTED_OPERATION_SCOPES = ["global", "entity", "record", "bulk"];
+var SUPPORTED_RELATION_TYPES = [
+  "one-to-one",
+  "one-to-many",
+  "many-to-one",
+  "many-to-many"
+];
 function validateEntityDeclaration(input) {
   const errors = [];
   if (!input || typeof input !== "object") {
@@ -1224,6 +1230,50 @@ function validateEntityDeclaration(input) {
       }
     }
   }
+  const relationships = decl["relationships"];
+  if (relationships !== void 0) {
+    if (!Array.isArray(relationships)) {
+      errors.push({ path: "relationships", message: "Relationships must be an array." });
+    } else {
+      const knownFields = fields && typeof fields === "object" && !Array.isArray(fields) ? new Set(Object.keys(fields)) : /* @__PURE__ */ new Set();
+      const seenRelIds = /* @__PURE__ */ new Set();
+      for (let i = 0; i < relationships.length; i++) {
+        validateRelationDeclaration(i, relationships[i], knownFields, seenRelIds, errors);
+      }
+    }
+  }
+  const capabilities = decl["capabilities"];
+  if (capabilities !== void 0) {
+    if (typeof capabilities !== "object" || Array.isArray(capabilities)) {
+      errors.push({ path: "capabilities", message: "Capabilities must be an object." });
+    } else {
+      const caps = capabilities;
+      const booleanKeys = [
+        "list",
+        "detail",
+        "create",
+        "update",
+        "clone",
+        "delete",
+        "softDelete",
+        "export",
+        "bulkActions"
+      ];
+      for (const key of Object.keys(caps)) {
+        if (!booleanKeys.includes(key)) {
+          errors.push({
+            path: `capabilities.${key}`,
+            message: `Unknown capability '${key}'. Valid capabilities: ${booleanKeys.join(", ")}.`
+          });
+        } else if (typeof caps[key] !== "boolean") {
+          errors.push({
+            path: `capabilities.${key}`,
+            message: `Capability '${key}' must be a boolean.`
+          });
+        }
+      }
+    }
+  }
   return { valid: errors.length === 0, errors };
 }
 function validateFieldDeclaration(name, rawField, errors) {
@@ -1247,6 +1297,53 @@ function validateFieldDeclaration(name, rawField, errors) {
       message: `Field '${name}' cannot be both sensitive and exportable.`
     });
   }
+  if (field.enumOptions !== void 0) {
+    if (field.type !== "enum") {
+      errors.push({
+        path: `${prefix}.enumOptions`,
+        message: `Field '${name}' has enumOptions but type is '${field.type}'. enumOptions is only valid for type 'enum'.`
+      });
+    } else {
+      validateEnumOptions(name, field.enumOptions, errors);
+    }
+  }
+  if (field.relationEntity !== void 0) {
+    if (field.type !== "relation") {
+      errors.push({
+        path: `${prefix}.relationEntity`,
+        message: `Field '${name}' has relationEntity but type is '${field.type}'. relationEntity is only valid for type 'relation'.`
+      });
+    } else if (typeof field.relationEntity !== "string" || field.relationEntity.trim() === "") {
+      errors.push({
+        path: `${prefix}.relationEntity`,
+        message: `Field '${name}' relationEntity must be a non-empty string.`
+      });
+    }
+  }
+}
+function validateEnumOptions(fieldName, rawOptions, errors) {
+  const prefix = `fields[${fieldName}].enumOptions`;
+  if (!Array.isArray(rawOptions)) {
+    errors.push({ path: prefix, message: `enumOptions for field '${fieldName}' must be an array.` });
+    return;
+  }
+  if (rawOptions.length === 0) {
+    errors.push({ path: prefix, message: `enumOptions for field '${fieldName}' must not be empty.` });
+    return;
+  }
+  for (let i = 0; i < rawOptions.length; i++) {
+    const opt = rawOptions[i];
+    if (!opt || typeof opt !== "object") {
+      errors.push({ path: `${prefix}[${i}]`, message: `Enum option at index ${i} must be an object.` });
+      continue;
+    }
+    if (opt.value === void 0 || opt.value === null) {
+      errors.push({ path: `${prefix}[${i}].value`, message: `Enum option at index ${i} is missing 'value'.` });
+    }
+    if (!opt.label || typeof opt.label !== "string" || opt.label.trim() === "") {
+      errors.push({ path: `${prefix}[${i}].label`, message: `Enum option at index ${i} is missing 'label'.` });
+    }
+  }
 }
 function validateOperationDeclaration(id, rawOp, errors) {
   const prefix = `operations[${id}]`;
@@ -1280,6 +1377,45 @@ function validateOperationDeclaration(id, rawOp, errors) {
     }
   }
 }
+function validateRelationDeclaration(index, rawRel, knownFields, seenIds, errors) {
+  const prefix = `relationships[${index}]`;
+  if (!rawRel || typeof rawRel !== "object") {
+    errors.push({ path: prefix, message: `Relationship at index ${index} must be an object.` });
+    return;
+  }
+  const rel = rawRel;
+  if (rel.id !== void 0) {
+    if (typeof rel.id !== "string" || rel.id.trim() === "") {
+      errors.push({ path: `${prefix}.id`, message: "Relationship id must be a non-empty string." });
+    } else if (seenIds.has(rel.id)) {
+      errors.push({ path: `${prefix}.id`, message: `Duplicate relationship id '${rel.id}'.` });
+    } else {
+      seenIds.add(rel.id);
+    }
+  }
+  if (!rel.type) {
+    errors.push({ path: `${prefix}.type`, message: "Relationship type is required." });
+  } else if (!SUPPORTED_RELATION_TYPES.includes(rel.type)) {
+    errors.push({
+      path: `${prefix}.type`,
+      message: `Relationship type '${rel.type}' is not valid. Valid values: ${SUPPORTED_RELATION_TYPES.join(", ")}.`
+    });
+  }
+  if (!rel.fromField || typeof rel.fromField !== "string" || rel.fromField.trim() === "") {
+    errors.push({ path: `${prefix}.fromField`, message: "Relationship fromField is required." });
+  } else if (knownFields.size > 0 && !knownFields.has(rel.fromField)) {
+    errors.push({
+      path: `${prefix}.fromField`,
+      message: `Relationship fromField '${rel.fromField}' does not exist in the entity's fields.`
+    });
+  }
+  if (!rel.toEntity || typeof rel.toEntity !== "string" || rel.toEntity.trim() === "") {
+    errors.push({ path: `${prefix}.toEntity`, message: "Relationship toEntity is required." });
+  }
+  if (!rel.toField || typeof rel.toField !== "string" || rel.toField.trim() === "") {
+    errors.push({ path: `${prefix}.toField`, message: "Relationship toField is required." });
+  }
+}
 function validateConsumerDeclaration(input, entity) {
   const errors = [];
   if (!input || typeof input !== "object") {
@@ -1360,7 +1496,9 @@ function fieldDeclToFieldSchema(name, field) {
     sortable: field.sortable,
     filterable: field.filterable,
     exportable: field.exportable,
-    description: field.description
+    description: field.description,
+    enumOptions: field.enumOptions,
+    relationEntity: field.relationEntity
   };
 }
 function opDeclToStubOperationDef(entityId, opKey, op) {
@@ -1398,9 +1536,22 @@ function entityDeclToEntitySchema(decl, datasource) {
       table: decl.entity,
       primaryKey
     },
+    capabilities: decl.capabilities,
     fields
   };
 }
+function relationDeclToRelationSchema(fromEntity, rel) {
+  const id = rel.id ?? `${fromEntity}.${rel.toEntity}`;
+  const label = rel.label ?? capitalizeFirst(rel.toEntity);
+  return {
+    id,
+    type: rel.type,
+    from: { entity: fromEntity, field: rel.fromField },
+    to: { entity: rel.toEntity, field: rel.toField },
+    label,
+    display: rel.display ? { tab: rel.display.tab ?? false, label: rel.display.label } : void 0
+  };
+}
 function compileDeclarations(config, options) {
   const errors = [];
   const datasource = options.defaultDatasource ?? (options.datasourceIds.length === 1 ? options.datasourceIds[0] : void 0);
@@ -1413,6 +1564,7 @@ function compileDeclarations(config, options) {
   const entityDeclarationMap = /* @__PURE__ */ new Map();
   const compiledEntities = [];
   const compiledOperations = [];
+  const compiledRelations = [];
   for (const decl of config.entities) {
     const entityId = typeof decl?.entity === "string" ? decl.entity : "?";
     const prefix = `declarations.entities[${entityId}]`;
@@ -1436,6 +1588,20 @@ function compileDeclarations(config, options) {
       for (const [opKey, opDecl] of Object.entries(decl.operations ?? {})) {
         compiledOperations.push(opDeclToStubOperationDef(decl.entity, opKey, opDecl));
       }
+      const seenRelIds = /* @__PURE__ */ new Set();
+      for (let i = 0; i < (decl.relationships ?? []).length; i++) {
+        const rel = decl.relationships[i];
+        const relSchema = relationDeclToRelationSchema(decl.entity, rel);
+        if (seenRelIds.has(relSchema.id)) {
+          errors.push({
+            path: `${prefix}.relationships[${i}].id`,
+            message: `Duplicate relation id '${relSchema.id}' in entity '${decl.entity}'.`
+          });
+        } else {
+          seenRelIds.add(relSchema.id);
+          compiledRelations.push(relSchema);
+        }
+      }
     }
   }
   const consumerNames = /* @__PURE__ */ new Set();
@@ -1444,13 +1610,6 @@ function compileDeclarations(config, options) {
     const consumerId = typeof consumer?.consumer === "string" ? consumer.consumer : "?";
     const prefix = `declarations.consumers[${consumerId}]`;
     const entityDecl = entityDeclarationMap.get(consumer?.entity ?? "");
-    if (consumer?.entity && !entityDecl) {
-      errors.push({
-        path: `${prefix}.entity`,
-        message: `Entity '${consumer.entity}' referenced by consumer '${consumerId}' is not declared in declarations.entities.`
-      });
-      continue;
-    }
     const validation = validateConsumerDeclaration(consumer, entityDecl);
     if (!validation.valid) {
       for (const err of validation.errors) {
@@ -1473,7 +1632,8 @@ function compileDeclarations(config, options) {
     errors,
     entities: compiledEntities,
     operations: compiledOperations,
-    consumers: validConsumers
+    consumers: validConsumers,
+    relations: compiledRelations
   };
 }
 function resolveConsumerProjections(consumers, metadata) {
@@ -1557,10 +1717,97 @@ function bindAndValidateOperations(stubs, configOps) {
   }
   return { operations: bound, errors };
 }
+function validateRelationRefs(relations, metadata) {
+  const errors = [];
+  const entityMap = new Map(metadata.entities.map((e) => [e.id, e]));
+  for (const rel of relations) {
+    const fromEntity = entityMap.get(rel.from.entity);
+    if (!fromEntity) {
+      errors.push({
+        path: `declarations.entities[${rel.from.entity}].relationships`,
+        message: `Relation '${rel.id}': source entity '${rel.from.entity}' not found in metadata.`
+      });
+      continue;
+    }
+    const fromField = fromEntity.fields.find((f) => f.name === rel.from.field);
+    if (!fromField) {
+      errors.push({
+        path: `declarations.entities[${rel.from.entity}].relationships`,
+        message: `Relation '${rel.id}': fromField '${rel.from.field}' does not exist in entity '${rel.from.entity}'.`
+      });
+    }
+    const toEntity = entityMap.get(rel.to.entity);
+    if (!toEntity) {
+      errors.push({
+        path: `declarations.entities[${rel.from.entity}].relationships`,
+        message: `Relation '${rel.id}': target entity '${rel.to.entity}' not found in metadata. Ensure the target entity is declared, introspected, or manually configured.`
+      });
+      continue;
+    }
+    const toField = toEntity.fields.find((f) => f.name === rel.to.field);
+    if (!toField) {
+      errors.push({
+        path: `declarations.entities[${rel.from.entity}].relationships`,
+        message: `Relation '${rel.id}': toField '${rel.to.field}' does not exist in entity '${rel.to.entity}'.`
+      });
+    }
+  }
+  return errors;
+}
+function validateConsumerRefs(consumers, metadata) {
+  const errors = [];
+  for (const consumer of consumers) {
+    const entityMeta = metadata.entities.find((e) => e.id === consumer.entity);
+    if (!entityMeta) {
+      errors.push({
+        path: `declarations.consumers[${consumer.consumer}].entity`,
+        message: `Consumer '${consumer.consumer}' references entity '${consumer.entity}' which does not exist in the final metadata. Ensure the entity is declared, introspected, or manually configured.`
+      });
+      continue;
+    }
+    const knownFields = new Set(entityMeta.fields.map((f) => f.name));
+    const entityOps = metadata.operations.filter((o) => o.entity === consumer.entity);
+    const knownOpKeys = new Set(
+      entityOps.map((o) => o.id.startsWith(`${consumer.entity}.`) ? o.id.slice(consumer.entity.length + 1) : o.id)
+    );
+    const checkFields = (sectionPath, fieldNames) => {
+      if (!fieldNames) return;
+      for (let i = 0; i < fieldNames.length; i++) {
+        if (!knownFields.has(fieldNames[i])) {
+          errors.push({
+            path: `declarations.consumers[${consumer.consumer}].${sectionPath}[${i}]`,
+            message: `Consumer '${consumer.consumer}': field '${fieldNames[i]}' does not exist in entity '${consumer.entity}'.`
+          });
+        }
+      }
+    };
+    const checkOps = (sectionPath, opKeys) => {
+      if (!opKeys) return;
+      for (let i = 0; i < opKeys.length; i++) {
+        if (!knownOpKeys.has(opKeys[i])) {
+          errors.push({
+            path: `declarations.consumers[${consumer.consumer}].${sectionPath}[${i}]`,
+            message: `Consumer '${consumer.consumer}': operation '${opKeys[i]}' does not exist in entity '${consumer.entity}'.`
+          });
+        }
+      }
+    };
+    checkFields("list.fields", consumer.list?.fields);
+    checkFields("detail.fields", consumer.detail?.fields);
+    checkFields("forms.create.fields", consumer.forms?.create?.fields);
+    checkFields("forms.update.fields", consumer.forms?.update?.fields);
+    checkFields("forms.clone.fields", consumer.forms?.clone?.fields);
+    checkOps("actions.row", consumer.actions?.row);
+    checkOps("actions.bulk", consumer.actions?.bulk);
+    checkOps("actions.global", consumer.actions?.global);
+  }
+  return errors;
+}
 function createMaestro(config) {
   let extraEntities = [];
   let declaredOperations = [];
   let compiledConsumers = [];
+  let compiledRelations = [];
   if (config.declarations) {
     const datasourceIds = Object.keys(config.datasources ?? {});
     const defaultDatasource = config.declarations.defaultDatasource ?? (datasourceIds.length === 1 ? datasourceIds[0] : void 0);
@@ -1578,6 +1825,7 @@ function createMaestro(config) {
     extraEntities = compilation.entities;
     declaredOperations = compilation.operations;
     compiledConsumers = compilation.consumers;
+    compiledRelations = compilation.relations;
   }
   const mergedEntities = [
     ...config.entities ?? [],
@@ -1589,10 +1837,15 @@ function createMaestro(config) {
     throw new MaestroError("CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */, `Invalid operation bindings: ${messages}`);
   }
   const mergedOperations = binding.operations;
+  const mergedRelations = [
+    ...config.relations ?? [],
+    ...compiledRelations
+  ];
   const mergedConfig = {
     ...config,
     entities: mergedEntities,
-    operations: mergedOperations
+    operations: mergedOperations,
+    relations: mergedRelations
   };
   const validation = validateMaestroConfig(mergedConfig);
   if (!validation.valid) {
@@ -1601,6 +1854,26 @@ function createMaestro(config) {
   }
   const metadataEngine = new MetadataEngine();
   const metadata = metadataEngine.normalize(mergedConfig);
+  if (compiledRelations.length > 0) {
+    const relErrors = validateRelationRefs(compiledRelations, metadata);
+    if (relErrors.length > 0) {
+      const messages = relErrors.map((e) => `${e.path}: ${e.message}`).join("; ");
+      throw new MaestroError(
+        "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+        `Invalid relation references: ${messages}`
+      );
+    }
+  }
+  if (compiledConsumers.length > 0) {
+    const consumerErrors = validateConsumerRefs(compiledConsumers, metadata);
+    if (consumerErrors.length > 0) {
+      const messages = consumerErrors.map((e) => `${e.path}: ${e.message}`).join("; ");
+      throw new MaestroError(
+        "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+        `Invalid consumer references: ${messages}`
+      );
+    }
+  }
   const consumers = resolveConsumerProjections(compiledConsumers, metadata);
   const datasources = new DatasourceRegistry();
   for (const [id, provider] of Object.entries(config.datasources)) {