interface SchemaRegistry {
  generatedBy: string;
  version: string;
  features: Record<string, string[]>;
  tables: Record<string, TableMeta>;
  tablesByFeature: Record<string, string[]>;
  featureActions: Record<string, ActionMeta[]>;
  pages: Record<string, PageMeta>;
  pagesByFeature: Record<string, string[]>;
}

interface TableMeta {
  name: string;
  dbName: string;
  apiPath: string;
  feature: string;
  columns: ColumnMeta[];
  firewall: Record<string, unknown>;
  crud: Record<string, CrudConfig>;
  create?: WriteOperationConfig | false;
  update?: WriteOperationConfig | false;
  delete?: WriteOperationConfig | false;
  upsert?: WriteOperationConfig | false;
  guards: GuardsConfig;
  masking: Record<string, MaskingRule>;
  views: Record<string, ViewMeta>;
  defaultView?: string;
  requiresExplicitView?: true;
  validation: Record<string, ValidationRule>;
  actions: ActionMeta[];
  displayColumn?: string;
  defaultSort?: { field: string; order: 'asc' | 'desc' };
  inputHints?: Record<string, string>;
  layouts?: Record<string, CmsLayout>;
  internal?: boolean;
  ownsRelations?: Record<string, OwnsRelation>;
  ownedBy?: string;
  readInclude?: string[];
  emitsAfterCommit?: boolean;
  routesDisabled?: string[];
}

interface OwnsRelation {
  table: string;              // owned child table (camelCase registry name)
  fk: string;                 // FK on the child pointing at this root — compiler-stamped
  inherit?: string[];         // parent columns copied onto inserted children — compiler-stamped
  refs?: Record<string, string>; // client-supplied pointers at independent entities
  owns?: Record<string, OwnsRelation>; // nested owned relations
}

interface ColumnMeta {
  name: string;
  dbName: string;
  type: "text" | "integer" | "real" | "blob";
  mode?: "boolean";
  kind?: string;
  primaryKey: boolean;
  notNull: boolean;
  defaultValue?: string | number | boolean;
  fkTarget?: string;
}

interface CrudConfig {
  access?: AccessRule;
  mode?: string;
}

interface WriteOperationConfig extends CrudConfig {
  defaults?: Record<string, unknown>;
  computed?: Record<string, unknown>;
  fields?: string[];
  maxBatchSize?: number;
  allowFailFast?: boolean;
  batch?: false | Record<string, unknown>;
}

interface AccessRule {
  roles?: string[];
  or?: Array<{
    roles?: string[];
    record?: Record<string, unknown>;
  }>;
  record?: Record<string, unknown>;
}

interface GuardsConfig {
  createable: string[];
  updatable: string[];
  immutable: string[];
  protected: Record<string, string[]>;
}

interface ActionMeta {
  name: string;
  description: string;
  inputFields: ActionInputField[];
  access?: {
    roles: string[];
    record?: Record<string, unknown>;
  };
  transition?: ActionTransitionMeta;  // record actions with a state machine
  standalone?: boolean;
  path?: string;
  method?: string;
  responseType?: string;
  sideEffects?: string;
  cms?: CmsConfig;
}

/** The state-machine subset of the action's `transition` policy. Write-side
 *  keys (stamp, clears, onIllegal) are omitted; a `custom` guard function is
 *  replaced by `hasCustomGuard: true`. The CMS hides the action when the
 *  record's current state cannot take it — see /ui/admin/actions#transition-state. */
interface ActionTransitionMeta {
  field?: string | null;
  fromTo?: Record<string, Array<string | number | boolean>>;
  to?: string | number | boolean;
  via?: string;
  guard?: Record<string, string | number | boolean | { null: true } | { notNull: true }>;
  hasCustomGuard?: boolean;
  idempotent?: "noop" | "error";
}

interface CmsConfig {
  label?: string;
  icon?: string;
  confirm?: string | boolean;
  destructive?: boolean;
  category?: string;
  hidden?: boolean;
  placement?: 'feature' | 'tables';
  tables?: string[];
  successMessage?: string;
  onSuccess?: 'refresh' | 'redirect:list' | 'close';
  order?: number;
}

interface ActionInputField {
  name: string;
  type: string;        // "string" | "number" | "boolean" | "enum" | "object" | "array<item>" | "unknown"
  required: boolean;
  default?: unknown;
  enum?: Array<string | number | boolean>;
  integer?: true;
  nullable?: true;
  description?: string;
}

interface ViewMeta {
  fields: string[];
  access: AccessRule;
  query: {
    filterable: string[] | null;
    searchable: string[];
    sortable?: string[];
    defaultSort?: string;
  };
  aggregateOnly?: true;
}

interface CmsLayout {
  sections: CmsLayoutSection[];
}

interface CmsLayoutSection {
  label: string;
  fields: string[];
  columns?: 1 | 2;
  collapsed?: boolean;
}

interface MaskingRule {
  type: "email" | "phone" | "ssn" | "redact";
  show: {
    roles: string[];
    or?: string;
  };
}

interface ValidationRule {
  enum?: string[];
  maxLength?: number;
  minLength?: number;
  min?: number;
  max?: number;
  integer?: boolean;
  pattern?: string;
  url?: boolean;
  email?: boolean;
}

interface PageMeta {
  slug: string;
  title: string;
  description?: string;
  icon?: string;
  feature: string;
  access?: { roles: string[] };
  dataSources: Record<string, PageDataSource>;
  layout: PageLayout;
  matching?: PageMatching;
  pageActions?: Record<string, PageAction>;
}

interface PageDataSource {
  table: string;
  defaultFilters?: Record<string, unknown>;
  defaultSort?: { field: string; order: 'asc' | 'desc' };
  displayColumns?: string[];
}

interface PageLayout {
  type: 'split-panel';
  panels: PagePanel[];
}

interface PagePanel {
  id: string;
  title: string;
  dataSource: string;
  position: 'left' | 'right';
  features?: string[];
}

interface PageMatching {
  enabled: boolean;
  rules: MatchingRule[];
  confidenceThreshold?: number;
}

interface MatchingRule {
  name: string;
  weight: number;
  condition: {
    left: string;
    right: string;
    operator: 'abs-equals' | 'within-days' | 'fuzzy-match';
    value?: number;
  };
}

interface PageAction {
  table: string;
  action: string;
  inputMapping: Record<string, string>;
  label?: string;
  icon?: string;
  confirm?: string;
}