@maykonpaulo/maestro-core 0.2.1 → 0.3.0-next.1

package/dist/index.d.ts

@@ -66,6 +66,40 @@ declare class ConsoleLogger implements Logger {
     private serializeError;
 }
 
+type OperationLogStatus = 'success' | 'failure' | 'partial';
+
+interface StructuredLogEntry {
+    correlationId?: string;
+    operation?: string;
+    entity?: string;
+    entityId?: string;
+    actor?: string;
+    durationMs?: number;
+    status?: OperationLogStatus;
+    severity?: string;
+    message?: string;
+    metadata?: Metadata;
+    error?: unknown;
+}
+
+interface StructuredLogger {
+    debug(entry: StructuredLogEntry): void;
+    info(entry: StructuredLogEntry): void;
+    warn(entry: StructuredLogEntry): void;
+    error(entry: StructuredLogEntry): void;
+}
+
+declare class ConsoleStructuredLogger implements StructuredLogger {
+    private readonly minLevel;
+    constructor(minLevel?: LogLevel);
+    debug(entry: StructuredLogEntry): void;
+    info(entry: StructuredLogEntry): void;
+    warn(entry: StructuredLogEntry): void;
+    error(entry: StructuredLogEntry): void;
+    private log;
+    private serializeError;
+}
+
 type AuditLevel = 'debug' | 'info' | 'warn' | 'error' | 'critical';
 
 interface AuditEvent {
@@ -74,6 +108,8 @@ interface AuditEvent {
     action: string;
     actor: Actor;
     resource?: ResourceRef;
+    entity?: string;
+    entityId?: string;
     level: AuditLevel;
     before?: Metadata;
     after?: Metadata;
@@ -87,6 +123,8 @@ interface AuditEvent {
 interface AuditFilter {
     actorId?: string;
     action?: string;
+    entity?: string;
+    entityId?: string;
     resourceType?: string;
     resourceId?: string;
     level?: AuditLevel;
@@ -99,11 +137,17 @@ interface AuditRepository {
     list(filter?: AuditFilter): Promise<AuditEvent[]>;
 }
 
+interface AuditTimeline {
+    query(filter?: AuditFilter): Promise<AuditEvent[]>;
+}
+
 interface RecordAuditInput {
     action: string;
     actor: Actor;
     level?: AuditLevel;
     resource?: ResourceRef;
+    entity?: string;
+    entityId?: string;
     before?: Metadata;
     after?: Metadata;
     metadata?: Metadata;
@@ -118,10 +162,11 @@ declare class AuditRecorder {
     record(input: RecordAuditInput): Promise<AuditEvent>;
 }
 
-declare class InMemoryAuditRepository implements AuditRepository {
+declare class InMemoryAuditRepository implements AuditRepository, AuditTimeline {
     private readonly store;
     record(event: AuditEvent): Promise<void>;
     list(filter?: AuditFilter): Promise<AuditEvent[]>;
+    query(filter?: AuditFilter): Promise<AuditEvent[]>;
 }
 
 type Permission = string;
@@ -206,4 +251,999 @@ declare class InMemoryEventBus implements EventBus {
     unsubscribe<TPayload>(eventType: string, handler: EventHandler<TPayload>): void;
 }
 
-export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, AuditRecorder, type AuditRepository, type ConfigProvider, ConsoleLogger, type DomainEvent, ErrorCode, type EventBus, type EventHandler, type FeatureFlag, type FeatureFlagProvider, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, type LogEntry, type LogLevel, type Logger, MaestroError, type Metadata, type MetadataValue, type Permission, RbacEngine, type RbacPolicy, type RecordAuditInput, type ResourceRef, type Role };
+type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'isNull' | 'isNotNull' | 'isTrue' | 'isFalse';
+
+interface FilterDescriptor {
+    field: string;
+    operator: FilterOperator;
+    value?: unknown;
+}
+
+type SortDirection = 'asc' | 'desc';
+interface SortDescriptor {
+    field: string;
+    direction: SortDirection;
+}
+
+interface PagePagination {
+    strategy: 'page';
+    page: number;
+    pageSize: number;
+}
+interface OffsetPagination {
+    strategy: 'offset';
+    offset: number;
+    limit: number;
+}
+interface CursorPagination {
+    strategy: 'cursor';
+    cursor?: string;
+    limit: number;
+}
+type PaginationInput = PagePagination | OffsetPagination | CursorPagination;
+
+interface SearchInput {
+    term: string;
+    fields: string[];
+}
+
+interface QueryInput {
+    filters?: FilterDescriptor[];
+    sort?: SortDescriptor[];
+    pagination?: PaginationInput;
+    search?: SearchInput;
+}
+
+interface ListResult<T = Record<string, unknown>> {
+    records: T[];
+    total: number;
+    page?: number;
+    pageSize?: number;
+    totalPages?: number;
+    nextCursor?: string;
+}
+
+type FieldType = 'string' | 'text' | 'number' | 'integer' | 'decimal' | 'currency' | 'boolean' | 'date' | 'datetime' | 'time' | 'email' | 'phone' | 'url' | 'document' | 'uuid' | 'enum' | 'json' | 'relation' | 'array';
+
+interface EnumOption {
+    value: string | number;
+    label: string;
+}
+interface FieldListConfig {
+    visible: boolean;
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+    order?: number;
+}
+interface FieldDetailConfig {
+    visible: boolean;
+    group?: string;
+    order?: number;
+}
+interface FieldFormConfig {
+    creatable: boolean;
+    editable: boolean;
+    cloneable: boolean;
+    placeholder?: string;
+    helpText?: string;
+    section?: string;
+    order?: number;
+}
+interface FieldMetadata {
+    name: string;
+    label: string;
+    type: FieldType;
+    required: boolean;
+    readonly: boolean;
+    hidden: boolean;
+    sensitive: boolean;
+    searchable: boolean;
+    sortable: boolean;
+    filterable: boolean;
+    exportable: boolean;
+    filterOperators: FilterOperator[];
+    description?: string;
+    enumOptions?: EnumOption[];
+    relationEntity?: string;
+    mask?: string;
+    list: FieldListConfig;
+    detail: FieldDetailConfig;
+    form: FieldFormConfig;
+}
+
+interface EntityCapabilities {
+    list: boolean;
+    detail: boolean;
+    create: boolean;
+    update: boolean;
+    clone: boolean;
+    delete: boolean;
+    softDelete: boolean;
+    export: boolean;
+    bulkActions: boolean;
+}
+declare const DEFAULT_CAPABILITIES: EntityCapabilities;
+
+interface SoftDeleteConfig {
+    field: string;
+    activeValue: unknown;
+    inactiveValue: unknown;
+}
+
+interface SearchConfig {
+    fields: string[];
+}
+
+type ContextActionCondition = 'always' | 'when-active' | 'when-inactive';
+type ContextActionStyle = 'default' | 'warning' | 'danger';
+interface ContextAction {
+    id: string;
+    label: string;
+    permission: string;
+    condition?: ContextActionCondition;
+    style?: ContextActionStyle;
+    operationId?: string;
+}
+
+interface ExportConfig {
+    filename?: string;
+}
+
+interface EntityMetadata {
+    id: string;
+    label: {
+        singular: string;
+        plural: string;
+    };
+    description?: string;
+    datasource: string;
+    table: string;
+    primaryKey: string;
+    displayField: string;
+    fields: FieldMetadata[];
+    capabilities: EntityCapabilities;
+    softDelete?: SoftDeleteConfig;
+    defaultSort?: SortDescriptor;
+    search?: SearchConfig;
+    relations: string[];
+    contextActions: ContextAction[];
+    bulkOperations: string[];
+    exportConfig?: ExportConfig;
+}
+
+type RelationType = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+interface RelationEndpoint {
+    entity: string;
+    field: string;
+}
+interface RelationDisplayConfig {
+    tab: boolean;
+    label?: string;
+}
+interface RelationMetadata {
+    id: string;
+    type: RelationType;
+    from: RelationEndpoint;
+    to: RelationEndpoint;
+    label: string;
+    display?: RelationDisplayConfig;
+}
+
+type OperationScope = 'global' | 'entity' | 'record' | 'bulk';
+interface OperationMetadata {
+    id: string;
+    label: string;
+    description?: string;
+    entity?: string;
+    scope: OperationScope;
+    requiresConfirmation: boolean;
+    confirmationMessage?: string;
+    requiresTypedConfirmation: boolean;
+    requiredPermission?: string;
+}
+
+interface MaestroMetadata {
+    entities: EntityMetadata[];
+    relations: RelationMetadata[];
+    operations: OperationMetadata[];
+    policies: RbacPolicy;
+}
+
+interface DatasourceQueryContext {
+    table: string;
+    primaryKey: string;
+    filters?: FilterDescriptor[];
+    sort?: SortDescriptor[];
+    pagination?: PaginationInput;
+    search?: SearchInput;
+}
+interface DatasourceFindContext {
+    table: string;
+    primaryKey: string;
+    id: string;
+}
+interface DatasourceWriteContext {
+    table: string;
+    primaryKey: string;
+    data: Record<string, unknown>;
+}
+interface DatasourceUpdateContext {
+    table: string;
+    primaryKey: string;
+    id: string;
+    data: Record<string, unknown>;
+}
+interface DatasourceDeleteContext {
+    table: string;
+    primaryKey: string;
+    id: string;
+}
+
+interface DatasourceProvider {
+    list(context: DatasourceQueryContext): Promise<ListResult<Record<string, unknown>>>;
+    findById(context: DatasourceFindContext): Promise<Record<string, unknown> | null>;
+    create(context: DatasourceWriteContext): Promise<Record<string, unknown>>;
+    update(context: DatasourceUpdateContext): Promise<Record<string, unknown>>;
+    delete(context: DatasourceDeleteContext): Promise<void>;
+    count(context: DatasourceQueryContext): Promise<number>;
+}
+
+declare class DatasourceRegistry {
+    private readonly registry;
+    register(id: string, provider: DatasourceProvider): void;
+    get(id: string): DatasourceProvider;
+    has(id: string): boolean;
+    ids(): string[];
+}
+
+declare class InMemoryDatasourceProvider implements DatasourceProvider {
+    private readonly tables;
+    seed(table: string, records: Record<string, unknown>[], primaryKey?: string): void;
+    list(context: DatasourceQueryContext): Promise<ListResult<Record<string, unknown>>>;
+    findById(context: DatasourceFindContext): Promise<Record<string, unknown> | null>;
+    create(context: DatasourceWriteContext): Promise<Record<string, unknown>>;
+    update(context: DatasourceUpdateContext): Promise<Record<string, unknown>>;
+    delete(context: DatasourceDeleteContext): Promise<void>;
+    count(context: DatasourceQueryContext): Promise<number>;
+    private getStore;
+    private applyFilters;
+    private matchFilter;
+    private applySort;
+}
+
+interface OperationContext<TInput = unknown> {
+    actor: Actor;
+    entityId?: string;
+    record?: Record<string, unknown>;
+    records?: Record<string, unknown>[];
+    input?: TInput;
+    correlationId?: string;
+    metadata?: Metadata;
+}
+
+interface OperationResult<TOutput = unknown> {
+    success: boolean;
+    output?: TOutput;
+    message?: string;
+    error?: string;
+    metadata?: Metadata;
+}
+
+interface OperationDef<TInput = unknown, TOutput = unknown> {
+    id: string;
+    label: string;
+    description?: string;
+    entity?: string;
+    scope: OperationScope;
+    requiresConfirmation?: boolean;
+    confirmationMessage?: string;
+    requiresTypedConfirmation?: boolean;
+    requiredPermission?: string;
+    execute: (context: OperationContext<TInput>) => Promise<OperationResult<TOutput>>;
+}
+
+declare class OperationRegistry {
+    private readonly operations;
+    register(operation: OperationDef): void;
+    get(id: string): OperationDef;
+    find(id: string): OperationDef | undefined;
+    forEntity(entityId: string, scope?: OperationScope): OperationDef[];
+    all(): OperationDef[];
+}
+
+interface FieldSchemaListConfig {
+    visible?: boolean;
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+    order?: number;
+}
+interface FieldSchemaDetailConfig {
+    visible?: boolean;
+    group?: string;
+    order?: number;
+}
+interface FieldSchemaFormConfig {
+    creatable?: boolean;
+    editable?: boolean;
+    cloneable?: boolean;
+    placeholder?: string;
+    helpText?: string;
+    section?: string;
+    order?: number;
+}
+interface FieldSchemaEnumOption {
+    value: string | number;
+    label: string;
+}
+interface FieldSchema {
+    name: string;
+    label: string;
+    type: FieldType;
+    required?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    sensitive?: boolean;
+    searchable?: boolean;
+    sortable?: boolean;
+    filterable?: boolean;
+    exportable?: boolean;
+    filterOperators?: FilterOperator[];
+    description?: string;
+    enumOptions?: FieldSchemaEnumOption[];
+    relationEntity?: string;
+    mask?: string;
+    list?: FieldSchemaListConfig;
+    detail?: FieldSchemaDetailConfig;
+    form?: FieldSchemaFormConfig;
+}
+
+interface EntitySourceConfig {
+    datasource: string;
+    table: string;
+    primaryKey?: string;
+}
+interface EntityLabelConfig {
+    singular: string;
+    plural: string;
+}
+interface EntityExportConfig {
+    filename?: string;
+}
+interface EntitySchema {
+    id: string;
+    label: EntityLabelConfig;
+    description?: string;
+    source: EntitySourceConfig;
+    displayField?: string;
+    capabilities?: Partial<EntityCapabilities>;
+    softDelete?: SoftDeleteConfig;
+    defaultSort?: SortDescriptor;
+    search?: SearchConfig;
+    exportConfig?: EntityExportConfig;
+    fields: FieldSchema[];
+}
+
+interface RelationSchema {
+    id: string;
+    type: RelationType;
+    from: RelationEndpoint;
+    to: RelationEndpoint;
+    label: string;
+    display?: RelationDisplayConfig;
+}
+
+interface MaestroConfig {
+    datasources: Record<string, DatasourceProvider>;
+    entities: EntitySchema[];
+    relations?: RelationSchema[];
+    operations?: OperationDef[];
+    policies?: RbacPolicy;
+    audit?: AuditRepository;
+    logger?: Logger;
+}
+
+interface SchemaValidationError {
+    path: string;
+    message: string;
+}
+interface SchemaValidationResult {
+    valid: boolean;
+    errors: SchemaValidationError[];
+}
+declare function validateMaestroConfig(config: MaestroConfig): SchemaValidationResult;
+
+declare class MetadataEngine {
+    normalize(config: MaestroConfig): MaestroMetadata;
+    private normalizeEntity;
+    private normalizeField;
+}
+
+type ExportFormat = 'csv' | 'json';
+
+interface ExportResult {
+    format: ExportFormat;
+    data: string;
+    filename: string;
+    recordCount: number;
+    mimeType: string;
+}
+
+declare class MaestroEngine {
+    private readonly metadata;
+    private readonly datasources;
+    private readonly operations;
+    private readonly audit?;
+    private readonly rbac;
+    constructor(metadata: MaestroMetadata, datasources: DatasourceRegistry, operations: OperationRegistry, audit?: AuditRecorder | undefined);
+    getMetadata(): MaestroMetadata;
+    list(entityId: string, query: QueryInput, actor: Actor): Promise<ListResult<Record<string, unknown>>>;
+    findById(entityId: string, id: string, actor: Actor): Promise<Record<string, unknown> | null>;
+    create(entityId: string, data: Record<string, unknown>, actor: Actor): Promise<Record<string, unknown>>;
+    update(entityId: string, id: string, data: Record<string, unknown>, actor: Actor): Promise<Record<string, unknown>>;
+    clone(entityId: string, id: string, actor: Actor): Promise<Record<string, unknown>>;
+    softDelete(entityId: string, id: string, actor: Actor): Promise<void>;
+    restore(entityId: string, id: string, actor: Actor): Promise<void>;
+    hardDelete(entityId: string, id: string, actor: Actor): Promise<void>;
+    export(entityId: string, query: QueryInput, actor: Actor, format?: ExportFormat): Promise<ExportResult>;
+    executeOperation(operationId: string, context: OperationContext, actor: Actor): Promise<OperationResult>;
+    private requireEntity;
+    private requireCapability;
+    private recordAudit;
+}
+
+declare function createMaestro(config: MaestroConfig): MaestroEngine;
+
+interface FieldIntrospectionSchema {
+    name: string;
+    nativeType: string;
+    type: FieldType;
+    nullable: boolean;
+    isPrimaryKey: boolean;
+    isUnique?: boolean;
+    isForeignKey?: boolean;
+    referencesTable?: string;
+    referencesField?: string;
+    defaultValue?: unknown;
+    maxLength?: number;
+    isIndexed?: boolean;
+    candidateForSearch?: boolean;
+    candidateForSoftDelete?: boolean;
+    isTimestamp?: boolean;
+}
+interface IndexIntrospectionSchema {
+    name?: string;
+    fields: string[];
+    isUnique: boolean;
+}
+interface EntityIntrospectionSchema {
+    table: string;
+    fields: FieldIntrospectionSchema[];
+    indices?: IndexIntrospectionSchema[];
+}
+interface RelationIntrospectionSchema {
+    id: string;
+    type: RelationType;
+    from: {
+        table: string;
+        field: string;
+    };
+    to: {
+        table: string;
+        field: string;
+    };
+    confidence: 'definite' | 'inferred';
+}
+interface IntrospectionResult {
+    entities: EntityIntrospectionSchema[];
+    relations: RelationIntrospectionSchema[];
+}
+
+interface IntrospectionProvider {
+    introspect(): Promise<IntrospectionResult>;
+}
+
+interface YamlParser {
+    parse(content: string): unknown;
+}
+
+interface FileSystemReader {
+    readFile(path: string): Promise<string>;
+    readDir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}
+interface MaestroFileLoaderOptions {
+    rootDir: string;
+    yamlParser?: YamlParser;
+    fileReader?: FileSystemReader;
+}
+interface LoadedConfig {
+    entities: EntitySchema[];
+    relations: RelationSchema[];
+    policies?: RbacPolicy;
+}
+declare function loadMaestroConfig(options: MaestroFileLoaderOptions): Promise<LoadedConfig>;
+
+type MergeStrategy = 'extend' | 'override';
+interface MergeIntrospectionOptions {
+    introspection: IntrospectionResult;
+    overrides: LoadedConfig;
+    datasources: Record<string, DatasourceProvider>;
+    defaultDatasource: string;
+    strategy?: MergeStrategy;
+    operations?: OperationDef[];
+    audit?: AuditRepository;
+    logger?: Logger;
+}
+declare function mergeIntrospectionWithOverrides(options: MergeIntrospectionOptions): MaestroConfig;
+
+interface CreateMaestroFromIntrospectionOptions {
+    provider: IntrospectionProvider;
+    overrides?: LoadedConfig;
+    mergeStrategy?: MergeStrategy;
+    datasources?: Record<string, DatasourceProvider>;
+    defaultDatasource?: string;
+    policies?: RbacPolicy;
+    operations?: OperationDef[];
+    audit?: AuditRepository;
+    logger?: Logger;
+}
+declare function createMaestroFromIntrospection(options: CreateMaestroFromIntrospectionOptions): Promise<MaestroEngine>;
+
+interface ExportOptions {
+    format: ExportFormat;
+    includeFields?: string[];
+    excludeFields?: string[];
+    dateFormat?: string;
+    bom?: boolean;
+}
+
+interface ExportProvider {
+    export(entity: EntityMetadata, records: Record<string, unknown>[], options: ExportOptions): ExportResult;
+}
+
+declare class CsvExportProvider implements ExportProvider {
+    export(entity: EntityMetadata, records: Record<string, unknown>[], options: ExportOptions): ExportResult;
+    private resolveFields;
+    private formatValue;
+    private formatDate;
+    private escapeCsvCell;
+}
+
+interface MaestroHttpRequest {
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    path: string;
+}
+interface MaestroHttpResponse {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+}
+type MaestroHttpHandler = (request: MaestroHttpRequest) => Promise<MaestroHttpResponse>;
+
+interface MaestroRequestContext {
+    actor: Actor;
+    correlationId?: string;
+}
+type MaestroActorResolver = (request: MaestroHttpRequest) => Promise<MaestroRequestContext>;
+interface MaestroHttpOptions {
+    actorResolver: MaestroActorResolver;
+}
+
+interface MaestroHttpHandlers {
+    list: MaestroHttpHandler;
+    findById: MaestroHttpHandler;
+    create: MaestroHttpHandler;
+    update: MaestroHttpHandler;
+    clone: MaestroHttpHandler;
+    softDelete: MaestroHttpHandler;
+    restore: MaestroHttpHandler;
+    hardDelete: MaestroHttpHandler;
+    export: MaestroHttpHandler;
+    executeOperation: MaestroHttpHandler;
+    getMetadata: MaestroHttpHandler;
+    getEntityMetadata: MaestroHttpHandler;
+    health: MaestroHttpHandler;
+}
+
+declare function parseQueryInput(query: Record<string, string | string[]>): QueryInput;
+
+declare function createMaestroHttpHandlers(engine: MaestroEngine, options: MaestroHttpOptions): MaestroHttpHandlers;
+
+declare function inferFieldType(nativeType: string, fieldName: string): FieldType;
+declare function isTimestampField(fieldName: string, fieldType: FieldType): boolean;
+declare function isSoftDeleteCandidate(fieldName: string, fieldType: FieldType, nullable: boolean): boolean;
+declare function isSearchCandidate(fieldName: string, fieldType: FieldType, isPrimaryKey: boolean): boolean;
+declare function tableNameToEntityId(table: string): string;
+declare function tableNameToLabel(table: string): {
+    singular: string;
+    plural: string;
+};
+declare function humanizeFieldName(name: string): string;
+declare function detectDisplayField(fields: Array<{
+    name: string;
+    type: FieldType;
+    isPrimaryKey: boolean;
+}>): string | undefined;
+
+interface GeneratedConfig {
+    entities: Record<string, EntitySchema>;
+    relations: Record<string, RelationSchema>;
+}
+declare function generateEntityConfig(entity: EntityIntrospectionSchema, datasource: string): EntitySchema;
+declare function generateRelationConfig(relation: RelationIntrospectionSchema, entityIdByTable: Map<string, string>): RelationSchema | null;
+declare function generateAllConfigs(result: IntrospectionResult, datasource: string): GeneratedConfig;
+
+type ImpactLevel = 'SAFE' | 'WARNING' | 'BREAKING';
+type EntityDiffChangeKind = 'entity_added' | 'entity_removed' | 'entity_label_changed' | 'entity_primary_key_changed';
+type FieldDiffChangeKind = 'field_added' | 'field_removed' | 'field_type_changed' | 'field_nullable_changed' | 'field_index_added' | 'field_index_removed' | 'field_metadata_changed';
+type RelationDiffChangeKind = 'relation_added' | 'relation_removed' | 'relation_cardinality_changed' | 'relation_fields_changed';
+type DiffChangeKind = EntityDiffChangeKind | FieldDiffChangeKind | RelationDiffChangeKind;
+interface EntityDiffChange {
+    category: 'entity';
+    kind: EntityDiffChangeKind;
+    impact: ImpactLevel;
+    entityTable: string;
+    previous?: unknown;
+    current?: unknown;
+}
+interface FieldDiffChange {
+    category: 'field';
+    kind: FieldDiffChangeKind;
+    impact: ImpactLevel;
+    entityTable: string;
+    fieldName: string;
+    previous?: unknown;
+    current?: unknown;
+}
+interface RelationDiffChange {
+    category: 'relation';
+    kind: RelationDiffChangeKind;
+    impact: ImpactLevel;
+    relationId: string;
+    previous?: unknown;
+    current?: unknown;
+}
+type DiffChange = EntityDiffChange | FieldDiffChange | RelationDiffChange;
+interface DiffSummary {
+    total: number;
+    safe: number;
+    warnings: number;
+    breaking: number;
+}
+interface IntrospectionDiff {
+    changes: DiffChange[];
+    summary: DiffSummary;
+    hasBreaking: boolean;
+    hasWarnings: boolean;
+}
+
+interface DiffEngineOptions {
+    /**
+     * Optional explicit label maps (table → label) for detecting label changes
+     * across two introspection snapshots. When omitted, labels are derived
+     * from table names via tableNameToLabel — making entity_label_changed
+     * only fire when the table name itself changes its derived label.
+     */
+    previousEntityLabels?: Map<string, string>;
+    currentEntityLabels?: Map<string, string>;
+}
+declare class DiffEngine {
+    compare(previous: IntrospectionResult, current: IntrospectionResult, options?: DiffEngineOptions): IntrospectionDiff;
+    private compareFields;
+}
+
+interface IntrospectionReportStats {
+    entitiesDiscovered: number;
+    relationsDiscovered: number;
+    totalChanges: number;
+    safeChanges: number;
+    warnings: number;
+    breakingChanges: number;
+}
+interface IntrospectionReportChange {
+    impact: ImpactLevel;
+    description: string;
+    recommendation?: string;
+}
+interface IntrospectionReport {
+    completedAt: string;
+    stats: IntrospectionReportStats;
+    changes: IntrospectionReportChange[];
+    hasDiff: boolean;
+    text: string;
+}
+
+declare class ReportGenerator {
+    generate(result: IntrospectionResult, diff?: IntrospectionDiff): IntrospectionReport;
+    private describeChange;
+    private generateText;
+}
+
+interface IntrospectionSnapshot {
+    id: string;
+    timestamp: string;
+    result: IntrospectionResult;
+    label?: string;
+}
+
+interface SnapshotRepository {
+    save(snapshot: IntrospectionSnapshot): Promise<void>;
+    load(id: string): Promise<IntrospectionSnapshot | null>;
+}
+
+declare class InMemorySnapshotRepository implements SnapshotRepository {
+    private readonly store;
+    save(snapshot: IntrospectionSnapshot): Promise<void>;
+    load(id: string): Promise<IntrospectionSnapshot | null>;
+}
+
+interface IntrospectionRuntimeRunOptions {
+    provider: IntrospectionProvider;
+    overrides?: LoadedConfig;
+    mergeStrategy?: MergeStrategy;
+    datasources?: Record<string, DatasourceProvider>;
+    defaultDatasource?: string;
+    /** ID of a previously saved snapshot to diff against */
+    snapshotId?: string;
+    /** Whether to automatically save the new snapshot after running. Defaults to true when a repository is configured. */
+    saveSnapshot?: boolean;
+    operations?: OperationDef[];
+    audit?: AuditRepository;
+    logger?: Logger;
+    policies?: RbacPolicy;
+}
+interface IntrospectionRuntimeResult {
+    metadata: MaestroMetadata;
+    diff?: IntrospectionDiff;
+    report: IntrospectionReport;
+    snapshot: IntrospectionSnapshot;
+}
+declare class IntrospectionRuntime {
+    private readonly snapshotRepository?;
+    private lastProvider?;
+    constructor(snapshotRepository?: SnapshotRepository | undefined);
+    run(options: IntrospectionRuntimeRunOptions): Promise<IntrospectionRuntimeResult>;
+    saveSnapshot(snapshot: IntrospectionSnapshot): Promise<void>;
+    loadSnapshot(id: string): Promise<IntrospectionSnapshot | null>;
+    compareWithSnapshot(snapshotId: string, provider?: IntrospectionProvider): Promise<IntrospectionDiff | null>;
+}
+
+type CorrelationId = string;
+declare function generateCorrelationId(): CorrelationId;
+
+interface CorrelationContext {
+    correlationId: CorrelationId;
+}
+
+type OperationalRisk = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+
+interface RiskClassificationInput {
+    operation: string;
+    resource?: ResourceRef;
+    metadata?: Metadata;
+}
+interface RiskClassifier {
+    classify(input: RiskClassificationInput): OperationalRisk;
+}
+
+declare class MetadataRiskClassifier implements RiskClassifier {
+    private readonly operationRiskMap;
+    private readonly defaultRisk;
+    constructor(operationRiskMap?: Record<string, OperationalRisk>, defaultRisk?: OperationalRisk);
+    classify(input: RiskClassificationInput): OperationalRisk;
+}
+
+type AuthorizationDecision = 'ALLOW' | 'DENY' | 'REQUIRES_CONFIRMATION';
+
+interface AuthorizationContext {
+    actor: Actor;
+    operation: string;
+    resource?: ResourceRef;
+    metadata?: Metadata;
+    riskLevel?: OperationalRisk;
+    correlationId?: string;
+}
+
+interface AuthorizationResult {
+    decision: AuthorizationDecision;
+    reason?: string;
+    metadata?: Metadata;
+}
+
+interface AuthorizationProvider {
+    evaluate(context: AuthorizationContext): Promise<AuthorizationResult>;
+}
+
+declare class ContextualAuthorizationEngine implements AuthorizationProvider {
+    private readonly criticalOperations;
+    private readonly rbac;
+    constructor(policy: RbacPolicy, criticalOperations?: ReadonlySet<string>);
+    evaluate(context: AuthorizationContext): Promise<AuthorizationResult>;
+}
+
+type PolicyDecision = 'ALLOW' | 'DENY' | 'REQUIRES_CONFIRMATION';
+
+interface PolicyContext {
+    actor: Actor;
+    operation: string;
+    resource?: ResourceRef;
+    metadata?: Metadata;
+    riskLevel?: OperationalRisk;
+    correlationId?: string;
+}
+
+interface PolicyRuleResult {
+    decision: PolicyDecision;
+    reason?: string;
+}
+interface PolicyRule {
+    id: string;
+    description?: string;
+    evaluate(context: PolicyContext): PolicyRuleResult | null;
+}
+
+interface PolicyViolation {
+    ruleId: string;
+    reason?: string;
+    context: PolicyContext;
+    occurredAt: Date;
+}
+
+interface PolicyEvaluationResult {
+    decision: PolicyDecision;
+    violations: PolicyViolation[];
+    reason?: string;
+}
+
+interface PolicyProvider {
+    rules(): PolicyRule[];
+}
+
+declare class PolicyEngine {
+    private readonly provider;
+    constructor(provider: PolicyProvider);
+    evaluate(context: PolicyContext): PolicyEvaluationResult;
+}
+
+declare class InMemoryPolicyProvider implements PolicyProvider {
+    private readonly _rules;
+    constructor(rules?: PolicyRule[]);
+    rules(): PolicyRule[];
+}
+
+type ConfirmationStatus = 'REQUESTED' | 'AWAITING_CONFIRMATION' | 'APPROVED' | 'REJECTED' | 'EXECUTED' | 'EXPIRED';
+
+interface ConfirmationApproval {
+    approver: Actor;
+    approvedAt: Date;
+    comment?: string;
+}
+
+interface ConfirmationRequest {
+    id: string;
+    operation: string;
+    actor: Actor;
+    resource?: ResourceRef;
+    status: ConfirmationStatus;
+    requiredApprovals: number;
+    approvals: ConfirmationApproval[];
+    rejections: ConfirmationApproval[];
+    requestedAt: Date;
+    executedAt?: Date;
+    expiresAt?: Date;
+    metadata?: Metadata;
+    correlationId?: string;
+}
+
+interface ConfirmationRepository {
+    save(request: ConfirmationRequest): Promise<void>;
+    findById(id: string): Promise<ConfirmationRequest | undefined>;
+    listPending(): Promise<ConfirmationRequest[]>;
+}
+
+interface RequestConfirmationInput {
+    operation: string;
+    actor: Actor;
+    resource?: ResourceRef;
+    requiredApprovals?: number;
+    metadata?: Metadata;
+    correlationId?: string;
+    expiresAt?: Date;
+}
+declare class ConfirmationEngine {
+    private readonly repository;
+    constructor(repository: ConfirmationRepository);
+    request(input: RequestConfirmationInput): Promise<ConfirmationRequest>;
+    approve(requestId: string, approver: Actor, comment?: string): Promise<ConfirmationRequest>;
+    reject(requestId: string, approver: Actor, comment?: string): Promise<ConfirmationRequest>;
+    execute(requestId: string): Promise<ConfirmationRequest>;
+    getPending(): Promise<ConfirmationRequest[]>;
+    private findOrThrow;
+    private assertActive;
+}
+
+declare class InMemoryConfirmationRepository implements ConfirmationRepository {
+    private readonly store;
+    save(request: ConfirmationRequest): Promise<void>;
+    findById(id: string): Promise<ConfirmationRequest | undefined>;
+    listPending(): Promise<ConfirmationRequest[]>;
+}
+
+declare const GOVERNANCE_EVENT_TYPES: {
+    readonly OPERATION_EXECUTED: "governance.operation.executed";
+    readonly AUTHORIZATION_DENIED: "governance.authorization.denied";
+    readonly POLICY_TRIGGERED: "governance.policy.triggered";
+    readonly CONFIRMATION_REQUESTED: "governance.confirmation.requested";
+    readonly CONFIRMATION_APPROVED: "governance.confirmation.approved";
+    readonly CONFIRMATION_REJECTED: "governance.confirmation.rejected";
+    readonly AUDIT_RECORDED: "governance.audit.recorded";
+};
+type GovernanceEventType = (typeof GOVERNANCE_EVENT_TYPES)[keyof typeof GOVERNANCE_EVENT_TYPES];
+
+interface OperationExecutedPayload {
+    operation: string;
+    actor: Actor;
+    resource?: ResourceRef;
+    correlationId?: string;
+    durationMs?: number;
+}
+interface AuthorizationDeniedPayload {
+    context: AuthorizationContext;
+    reason?: string;
+}
+interface PolicyTriggeredPayload {
+    violations: PolicyViolation[];
+    correlationId?: string;
+}
+interface ConfirmationRequestedPayload {
+    request: ConfirmationRequest;
+}
+interface ConfirmationApprovedPayload {
+    request: ConfirmationRequest;
+    approver: Actor;
+}
+interface ConfirmationRejectedPayload {
+    request: ConfirmationRequest;
+    approver: Actor;
+}
+interface AuditRecordedPayload {
+    event: AuditEvent;
+}
+
+interface GovernanceEventBus extends EventBus {
+    publishGovernance<TPayload>(type: GovernanceEventType, payload: TPayload, correlationId?: string): Promise<DomainEvent<TPayload>>;
+}
+
+declare class InMemoryGovernanceEventBus extends InMemoryEventBus implements GovernanceEventBus {
+    publishGovernance<TPayload>(type: GovernanceEventType, payload: TPayload, correlationId?: string): Promise<DomainEvent<TPayload>>;
+}
+
+interface PolicyViolationFilter {
+    ruleId?: string;
+    correlationId?: string;
+    from?: Date;
+    to?: Date;
+}
+interface GovernanceApi {
+    getAuditTimeline(filter?: AuditFilter): Promise<AuditEvent[]>;
+    getCorrelationTrace(correlationId: string): Promise<AuditEvent[]>;
+    getPendingConfirmations(): Promise<ConfirmationRequest[]>;
+    getPolicyViolations(filter?: PolicyViolationFilter): Promise<PolicyViolation[]>;
+}
+
+declare class DefaultGovernanceApi implements GovernanceApi {
+    private readonly auditRepository;
+    private readonly confirmationRepository;
+    private readonly violationLog;
+    constructor(auditRepository: AuditRepository, confirmationRepository: ConfirmationRepository, violationLog?: PolicyViolation[]);
+    getAuditTimeline(filter?: AuditFilter): Promise<AuditEvent[]>;
+    getCorrelationTrace(correlationId: string): Promise<AuditEvent[]>;
+    getPendingConfirmations(): Promise<ConfirmationRequest[]>;
+    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 ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, 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, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, 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 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 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 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, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, tableNameToEntityId, tableNameToLabel, validateMaestroConfig };