@maykonpaulo/maestro-core 0.3.0-rc.0 → 0.3.0

package/dist/index.js

@@ -521,7 +521,10 @@ function validateMaestroConfig(config) {
     errors.push({ path: "datasources", message: "At least one datasource is required." });
   }
   if (!config.entities || config.entities.length === 0) {
-    errors.push({ path: "entities", message: "At least one entity is required." });
+    errors.push({
+      path: "entities",
+      message: "At least one entity is required. Provide entities directly or via declarations.entities."
+    });
   }
   const entityIds = /* @__PURE__ */ new Set();
   for (const entity of config.entities ?? []) {
@@ -718,7 +721,7 @@ function buildBulkOperations(entity, operations) {
 var MetadataEngine = class {
   normalize(config) {
     const operations = config.operations ?? [];
-    const entities = config.entities.map((e) => this.normalizeEntity(e, operations));
+    const entities = (config.entities ?? []).map((e) => this.normalizeEntity(e, operations));
     const relations = config.relations ?? [];
     const entityRelationMap = /* @__PURE__ */ new Map();
     for (const rel of relations) {
@@ -890,21 +893,54 @@ var CsvExportProvider = class {
 
 // src/engine/MaestroEngine.ts
 var MaestroEngine = class {
-  constructor(metadata, datasources, operations, audit) {
+  constructor(metadata, datasources, operations, audit, consumers = []) {
     this.metadata = metadata;
     this.datasources = datasources;
     this.operations = operations;
     this.audit = audit;
     this.rbac = new RbacEngine(metadata.policies);
+    this.consumerMap = new Map(consumers.map((c) => [c.consumer, c]));
   }
   metadata;
   datasources;
   operations;
   audit;
   rbac;
+  consumerMap;
   getMetadata() {
     return this.metadata;
   }
+  /**
+   * Returns the resolved consumer projection for the given consumer ID, or undefined if not found.
+   * Each call returns an independent copy — mutations to the returned object do not affect internal state.
+   * Consumer projections are only available when declarations.consumers were provided to createMaestro().
+   */
+  getConsumer(consumerId) {
+    const p = this.consumerMap.get(consumerId);
+    if (!p) return void 0;
+    return {
+      consumer: p.consumer,
+      entity: p.entity,
+      fields: {
+        list: [...p.fields.list],
+        detail: [...p.fields.detail],
+        create: [...p.fields.create],
+        update: [...p.fields.update],
+        clone: [...p.fields.clone]
+      },
+      operations: {
+        row: [...p.operations.row],
+        bulk: [...p.operations.bulk],
+        global: [...p.operations.global]
+      }
+    };
+  }
+  /**
+   * Returns the IDs of all registered consumer projections.
+   */
+  listConsumers() {
+    return [...this.consumerMap.keys()];
+  }
   async list(entityId, query, actor) {
     const entity = this.requireEntity(entityId);
     this.requireCapability(entity, "list", actor, `entity.${entityId}.list`);
@@ -1131,25 +1167,724 @@ var MaestroEngine = class {
   }
 };
 
+// src/declarative/DeclarativeValidator.ts
+var SUPPORTED_FIELD_TYPES = [
+  "string",
+  "text",
+  "number",
+  "integer",
+  "decimal",
+  "currency",
+  "boolean",
+  "date",
+  "datetime",
+  "time",
+  "email",
+  "phone",
+  "url",
+  "document",
+  "uuid",
+  "enum",
+  "json",
+  "relation",
+  "array"
+];
+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") {
+    return { valid: false, errors: [{ path: "", message: "Entity declaration must be an object." }] };
+  }
+  const decl = input;
+  if (!decl["entity"] || typeof decl["entity"] !== "string" || decl["entity"].trim() === "") {
+    errors.push({ path: "entity", message: "Entity name is required." });
+  }
+  const fields = decl["fields"];
+  if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
+    errors.push({ path: "fields", message: "Entity must declare at least one field." });
+  } else {
+    const fieldMap = fields;
+    if (Object.keys(fieldMap).length === 0) {
+      errors.push({ path: "fields", message: "Entity must declare at least one field." });
+    } else {
+      for (const [name, rawField] of Object.entries(fieldMap)) {
+        validateFieldDeclaration(name, rawField, errors);
+      }
+    }
+  }
+  const operations = decl["operations"];
+  if (operations !== void 0) {
+    if (typeof operations !== "object" || Array.isArray(operations)) {
+      errors.push({ path: "operations", message: "Operations must be an object." });
+    } else {
+      const opMap = operations;
+      for (const [id, rawOp] of Object.entries(opMap)) {
+        validateOperationDeclaration(id, rawOp, errors);
+      }
+    }
+  }
+  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) {
+  const prefix = `fields[${name}]`;
+  if (!rawField || typeof rawField !== "object") {
+    errors.push({ path: prefix, message: `Field '${name}' must be an object.` });
+    return;
+  }
+  const field = rawField;
+  if (!field.type) {
+    errors.push({ path: `${prefix}.type`, message: "Field type is required." });
+  } else if (!SUPPORTED_FIELD_TYPES.includes(field.type)) {
+    errors.push({
+      path: `${prefix}.type`,
+      message: `Field type '${field.type}' is not supported. Supported types: ${SUPPORTED_FIELD_TYPES.join(", ")}.`
+    });
+  }
+  if (field.sensitive === true && field.exportable === true) {
+    errors.push({
+      path: prefix,
+      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}]`;
+  if (!rawOp || typeof rawOp !== "object") {
+    errors.push({ path: prefix, message: `Operation '${id}' must be an object.` });
+    return;
+  }
+  const op = rawOp;
+  if (!op.label || typeof op.label !== "string" || op.label.trim() === "") {
+    errors.push({ path: `${prefix}.label`, message: "Operation label is required." });
+  }
+  if (op.risk !== void 0 && !SUPPORTED_OPERATIONAL_RISKS.includes(op.risk)) {
+    errors.push({
+      path: `${prefix}.risk`,
+      message: `Operation risk '${op.risk}' is not valid. Valid values: ${SUPPORTED_OPERATIONAL_RISKS.join(", ")}.`
+    });
+  }
+  if (op.scope !== void 0 && !SUPPORTED_OPERATION_SCOPES.includes(op.scope)) {
+    errors.push({
+      path: `${prefix}.scope`,
+      message: `Operation scope '${op.scope}' is not valid. Valid values: ${SUPPORTED_OPERATION_SCOPES.join(", ")}.`
+    });
+  }
+  if (op.confirmation !== void 0) {
+    const conf = op.confirmation;
+    if (conf.approvers !== void 0 && (typeof conf.approvers !== "number" || conf.approvers < 1)) {
+      errors.push({
+        path: `${prefix}.confirmation.approvers`,
+        message: "Confirmation approvers must be at least 1."
+      });
+    }
+  }
+}
+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") {
+    return { valid: false, errors: [{ path: "", message: "Consumer declaration must be an object." }] };
+  }
+  const decl = input;
+  if (!decl["consumer"] || typeof decl["consumer"] !== "string" || decl["consumer"].trim() === "") {
+    errors.push({ path: "consumer", message: "Consumer name is required." });
+  }
+  if (!decl["entity"] || typeof decl["entity"] !== "string" || decl["entity"].trim() === "") {
+    errors.push({ path: "entity", message: "Entity name is required." });
+  }
+  if (entity) {
+    const knownFields = new Set(Object.keys(entity.fields));
+    const knownOps = new Set(Object.keys(entity.operations ?? {}));
+    const entityName = entity.entity;
+    validateFieldRefs("list.fields", decl["list"], knownFields, entityName, errors);
+    validateFieldRefs("detail.fields", decl["detail"], knownFields, entityName, errors);
+    const forms = decl["forms"];
+    if (forms && typeof forms === "object") {
+      validateFieldRefs("forms.create.fields", forms["create"], knownFields, entityName, errors);
+      validateFieldRefs("forms.update.fields", forms["update"], knownFields, entityName, errors);
+      validateFieldRefs("forms.clone.fields", forms["clone"], knownFields, entityName, errors);
+    }
+    const actions = decl["actions"];
+    if (actions && typeof actions === "object") {
+      validateOperationRefs("actions.row", actions["row"], knownOps, entityName, errors);
+      validateOperationRefs("actions.bulk", actions["bulk"], knownOps, entityName, errors);
+      validateOperationRefs("actions.global", actions["global"], knownOps, entityName, errors);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+function validateFieldRefs(path, container, knownFields, entityName, errors) {
+  if (!container || typeof container !== "object") return;
+  const obj = container;
+  const fields = obj["fields"];
+  if (!Array.isArray(fields)) return;
+  for (let i = 0; i < fields.length; i++) {
+    const name = fields[i];
+    if (!knownFields.has(name)) {
+      errors.push({
+        path: `${path}[${i}]`,
+        message: `Field '${name}' does not exist in entity '${entityName}'.`
+      });
+    }
+  }
+}
+function validateOperationRefs(path, refs, knownOps, entityName, errors) {
+  if (!Array.isArray(refs)) return;
+  for (let i = 0; i < refs.length; i++) {
+    const id = refs[i];
+    if (!knownOps.has(id)) {
+      errors.push({
+        path: `${path}[${i}]`,
+        message: `Operation '${id}' does not exist in entity '${entityName}'.`
+      });
+    }
+  }
+}
+
+// src/declarative/DeclarativeMetadataCompiler.ts
+function capitalizeFirst(name) {
+  if (!name) return name;
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function fieldDeclToFieldSchema(name, field) {
+  return {
+    name,
+    label: field.label ?? capitalizeFirst(name),
+    type: field.type,
+    required: field.required,
+    readonly: field.readonly,
+    // FieldDeclaration uses visible (default true); FieldSchema uses hidden (default false)
+    hidden: field.visible === false ? true : void 0,
+    sensitive: field.sensitive,
+    searchable: field.searchable,
+    sortable: field.sortable,
+    filterable: field.filterable,
+    exportable: field.exportable,
+    description: field.description,
+    enumOptions: field.enumOptions,
+    relationEntity: field.relationEntity
+  };
+}
+function opDeclToStubOperationDef(entityId, opKey, op) {
+  const id = `${entityId}.${opKey}`;
+  return {
+    id,
+    label: op.label,
+    description: op.description,
+    entity: entityId,
+    scope: op.scope ?? "record",
+    requiredPermission: op.permission,
+    requiresConfirmation: op.confirmation?.required,
+    execute: async () => {
+      throw new MaestroError(
+        "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+        `Operation '${id}' declared but has no registered implementation. Provide an OperationDef with id '${id}' in config.operations.`
+      );
+    }
+  };
+}
+function entityDeclToEntitySchema(decl, datasource) {
+  const primaryKeyEntry = Object.entries(decl.fields).find(([, f]) => f.primary);
+  const primaryKey = primaryKeyEntry ? primaryKeyEntry[0] : "id";
+  const singularLabel = decl.label ?? capitalizeFirst(decl.entity);
+  const pluralLabel = decl.pluralLabel ?? decl.label ?? capitalizeFirst(decl.entity);
+  const fields = Object.entries(decl.fields).map(
+    ([name, field]) => fieldDeclToFieldSchema(name, field)
+  );
+  return {
+    id: decl.entity,
+    label: { singular: singularLabel, plural: pluralLabel },
+    description: decl.description,
+    source: {
+      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);
+  if (options.datasourceIds.length > 1 && !datasource) {
+    errors.push({
+      path: "declarations.defaultDatasource",
+      message: "Multiple datasources are configured. Set declarations.defaultDatasource to specify which one to use for declared entities."
+    });
+  }
+  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}]`;
+    const validation = validateEntityDeclaration(decl);
+    if (!validation.valid) {
+      for (const err of validation.errors) {
+        errors.push({ path: `${prefix}.${err.path}`.replace(/\.$/, ""), message: err.message });
+      }
+      continue;
+    }
+    if (entityDeclarationMap.has(decl.entity)) {
+      errors.push({
+        path: prefix,
+        message: `Duplicate entity '${decl.entity}' in declarations.entities.`
+      });
+      continue;
+    }
+    entityDeclarationMap.set(decl.entity, decl);
+    if (datasource) {
+      compiledEntities.push(entityDeclToEntitySchema(decl, datasource));
+      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();
+  const validConsumers = [];
+  for (const consumer of config.consumers ?? []) {
+    const consumerId = typeof consumer?.consumer === "string" ? consumer.consumer : "?";
+    const prefix = `declarations.consumers[${consumerId}]`;
+    const entityDecl = entityDeclarationMap.get(consumer?.entity ?? "");
+    const validation = validateConsumerDeclaration(consumer, entityDecl);
+    if (!validation.valid) {
+      for (const err of validation.errors) {
+        errors.push({ path: `${prefix}.${err.path}`.replace(/\.$/, ""), message: err.message });
+      }
+      continue;
+    }
+    if (consumerNames.has(consumer.consumer)) {
+      errors.push({
+        path: prefix,
+        message: `Duplicate consumer '${consumer.consumer}' in declarations.consumers.`
+      });
+      continue;
+    }
+    consumerNames.add(consumer.consumer);
+    validConsumers.push(consumer);
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    entities: compiledEntities,
+    operations: compiledOperations,
+    consumers: validConsumers,
+    relations: compiledRelations
+  };
+}
+function resolveConsumerProjections(consumers, metadata) {
+  const results = [];
+  for (const consumer of consumers) {
+    const entityMeta = metadata.entities.find((e) => e.id === consumer.entity);
+    if (!entityMeta) continue;
+    const allFields = entityMeta.fields;
+    const entityOps = metadata.operations.filter((o) => o.entity === consumer.entity);
+    const resolveFields = (names) => {
+      if (!names || names.length === 0) return [...allFields];
+      return names.map((name) => allFields.find((f) => f.name === name)).filter((f) => f !== void 0);
+    };
+    const resolveOps = (keys, defaultScope) => {
+      if (!keys || keys.length === 0) {
+        return defaultScope ? entityOps.filter((o) => o.scope === defaultScope) : [...entityOps];
+      }
+      return keys.map((key) => {
+        const fullId = `${consumer.entity}.${key}`;
+        return entityOps.find((o) => o.id === fullId);
+      }).filter((o) => o !== void 0);
+    };
+    results.push({
+      consumer: consumer.consumer,
+      entity: consumer.entity,
+      fields: {
+        list: resolveFields(consumer.list?.fields),
+        detail: resolveFields(consumer.detail?.fields),
+        create: resolveFields(consumer.forms?.create?.fields),
+        update: resolveFields(consumer.forms?.update?.fields),
+        clone: resolveFields(consumer.forms?.clone?.fields)
+      },
+      operations: {
+        row: resolveOps(consumer.actions?.row, "record"),
+        bulk: resolveOps(consumer.actions?.bulk, "bulk"),
+        global: resolveOps(consumer.actions?.global, "global")
+      }
+    });
+  }
+  return results;
+}
+
 // src/engine/createMaestro.ts
+function bindAndValidateOperations(stubs, configOps) {
+  const errors = [];
+  const configOpMap = /* @__PURE__ */ new Map();
+  for (const op of configOps) {
+    if (configOpMap.has(op.id)) {
+      errors.push({
+        path: `operations[${op.id}]`,
+        message: `Duplicate operation id '${op.id}' in config.operations. Each operation must have a unique id.`
+      });
+    } else {
+      configOpMap.set(op.id, op);
+    }
+  }
+  const stubIds = new Set(stubs.map((s) => s.id));
+  const bound = [];
+  for (const stub of stubs) {
+    const impl = configOpMap.get(stub.id);
+    if (!impl) {
+      errors.push({
+        path: `declarations.entities[${stub.entity}].operations`,
+        message: `Declared operation '${stub.id}' has no implementation. Provide an OperationDef with id '${stub.id}' in config.operations.`
+      });
+      continue;
+    }
+    if (impl.entity !== void 0 && impl.entity !== stub.entity) {
+      errors.push({
+        path: `operations[${impl.id}].entity`,
+        message: `Operation '${impl.id}' is declared for entity '${stub.entity}' but config.operations specifies entity '${impl.entity}'.`
+      });
+      continue;
+    }
+    bound.push(impl);
+  }
+  for (const op of configOpMap.values()) {
+    if (!stubIds.has(op.id)) {
+      bound.push(op);
+    }
+  }
+  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) {
-  const validation = validateMaestroConfig(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);
+    const compilation = compileDeclarations(config.declarations, {
+      datasourceIds,
+      defaultDatasource
+    });
+    if (!compilation.valid) {
+      const messages = compilation.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+      throw new MaestroError(
+        "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+        `Invalid declarative configuration: ${messages}`
+      );
+    }
+    extraEntities = compilation.entities;
+    declaredOperations = compilation.operations;
+    compiledConsumers = compilation.consumers;
+    compiledRelations = compilation.relations;
+  }
+  const mergedEntities = [
+    ...config.entities ?? [],
+    ...extraEntities
+  ];
+  const binding = bindAndValidateOperations(declaredOperations, config.operations ?? []);
+  if (binding.errors.length > 0) {
+    const messages = binding.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
+    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,
+    relations: mergedRelations
+  };
+  const validation = validateMaestroConfig(mergedConfig);
   if (!validation.valid) {
     const messages = validation.errors.map((e) => `${e.path}: ${e.message}`).join("; ");
     throw new MaestroError("CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */, `Invalid Maestro configuration: ${messages}`);
   }
   const metadataEngine = new MetadataEngine();
-  const metadata = metadataEngine.normalize(config);
+  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)) {
     datasources.register(id, provider);
   }
   const operations = new OperationRegistry();
-  for (const operation of config.operations ?? []) {
+  for (const operation of mergedOperations) {
     operations.register(operation);
   }
   const audit = config.audit ? new AuditRecorder(config.audit) : void 0;
-  return new MaestroEngine(metadata, datasources, operations, audit);
+  return new MaestroEngine(metadata, datasources, operations, audit, consumers);
 }
 
 // src/introspection/utils.ts
@@ -2653,6 +3388,7 @@ export {
   PolicyEngine,
   RbacEngine,
   ReportGenerator,
+  compileDeclarations,
   createMaestro,
   createMaestroFromIntrospection,
   createMaestroHttpHandlers,
@@ -2669,8 +3405,11 @@ export {
   loadMaestroConfig,
   mergeIntrospectionWithOverrides,
   parseQueryInput,
+  resolveConsumerProjections,
   tableNameToEntityId,
   tableNameToLabel,
+  validateConsumerDeclaration,
+  validateEntityDeclaration,
   validateMaestroConfig
 };
 //# sourceMappingURL=index.js.map