@fayz-ai/core 0.1.6

package/src/data/archetype.ts

@@ -0,0 +1,210 @@
+import type { DataProvider, CrudQuery, CrudResult } from './types'
+import { getSupabaseClientOptional } from './supabase'
+import type { EntityArchetype } from '../types/entities'
+
+// Archetypes that have a `kind` discriminator column
+const HAS_KIND = new Set<EntityArchetype>(['person', 'category', 'order', 'transaction', 'schedule', 'location'])
+
+const ARCHETYPE_CONFIG: Record<EntityArchetype, { table: string; fkColumn: string }> = {
+  person: { table: 'persons', fkColumn: 'person_id' },
+  category: { table: 'categories', fkColumn: 'category_id' },
+  product: { table: 'products', fkColumn: 'product_id' },
+  service: { table: 'services', fkColumn: 'service_id' },
+  location: { table: 'locations', fkColumn: 'location_id' },
+  order: { table: 'orders', fkColumn: 'order_id' },
+  transaction: { table: 'transactions', fkColumn: 'transaction_id' },
+
+  schedule: { table: 'schedules', fkColumn: 'schedule_id' },
+}
+
+const ARCHETYPE_COLUMNS: Record<EntityArchetype, Set<string>> = {
+  person: new Set(['name', 'email', 'phone', 'document_number', 'avatar_url', 'date_of_birth', 'address', 'city', 'state', 'country', 'postal_code', 'tags', 'is_active', 'notes', 'metadata']),
+  category: new Set(['name', 'slug', 'parent_id', 'icon', 'color', 'sort_order', 'is_active', 'metadata']),
+  product: new Set(['name', 'description', 'sku', 'price', 'cost', 'currency', 'unit', 'image_url', 'stock', 'min_stock', 'status', 'is_active', 'tags', 'metadata', 'category_id']),
+  service: new Set(['name', 'description', 'price', 'cost', 'currency', 'duration_minutes', 'image_url', 'status', 'is_active', 'tags', 'metadata', 'category_id']),
+  location: new Set(['name', 'email', 'phone', 'address', 'city', 'state', 'country', 'postal_code', 'is_headquarters', 'is_active', 'tags', 'notes', 'metadata']),
+  order: new Set(['reference_number', 'status', 'party_id', 'assignee_id', 'location_id', 'subtotal', 'discount', 'tax', 'total', 'currency', 'due_at', 'completed_at', 'notes', 'tags', 'metadata']),
+  transaction: new Set(['order_id', 'party_id', 'amount', 'currency', 'payment_method', 'reference', 'status', 'transacted_at', 'notes', 'metadata']),
+
+  schedule: new Set(['assignee_id', 'location_id', 'day_of_week', 'specific_date', 'starts_at', 'ends_at', 'is_active', 'metadata']),
+}
+
+function camelToSnake(str: string): string {
+  return str.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase())
+}
+
+function snakeToCamel(str: string): string {
+  return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+function mapRow<T>(row: Record<string, unknown>): T {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(row)) {
+    result[snakeToCamel(key)] = value
+  }
+  return result as T
+}
+
+export interface ArchetypeProviderConfig {
+  archetype: EntityArchetype
+  archetypeKind: string
+  projectTable: string
+  tenantId: () => string | undefined
+  searchColumns?: string[]
+}
+
+export function createArchetypeProvider<T extends { id: string }>(
+  config: ArchetypeProviderConfig,
+): DataProvider<T> {
+  const ac = ARCHETYPE_CONFIG[config.archetype]
+  const archetypeColumns = ARCHETYPE_COLUMNS[config.archetype]
+  const { fkColumn } = ac
+
+  function getClient() {
+    const supabase = getSupabaseClientOptional() as any
+    if (!supabase) throw new Error('Supabase client not available')
+    return supabase
+  }
+
+  function coreClient() {
+    return getClient().schema('saas_core')
+  }
+
+  function splitFields(data: Record<string, unknown>): { archetypeData: Record<string, unknown>; projectData: Record<string, unknown> } {
+    const archetypeData: Record<string, unknown> = {}
+    const projectData: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(data)) {
+      if (['id', 'createdAt', 'updatedAt', 'tenantId', fkColumn].includes(key)) continue
+      const snakeKey = camelToSnake(key)
+      if (archetypeColumns.has(snakeKey)) {
+        archetypeData[snakeKey] = value
+      } else {
+        projectData[snakeKey] = value
+      }
+    }
+    return { archetypeData, projectData }
+  }
+
+  // View name convention: v_{shortName} — maps project table to its view
+  const VIEW_MAP: Record<string, string> = {
+    clients: 'v_clients',
+    staff_members: 'v_staff',
+  }
+  const viewName = VIEW_MAP[config.projectTable] ?? `v_${config.projectTable}`
+
+  return {
+    async list(query: CrudQuery): Promise<CrudResult<T>> {
+      const tenantId = config.tenantId()
+      if (!tenantId) return { data: [], total: 0 }
+
+      // Single query via v_ view (JOINs public table with saas_core archetype)
+      let q = getClient()
+        .from(viewName)
+        .select('*', { count: 'exact' })
+        .eq('tenant_id', tenantId)
+
+      // Search
+      if (query.search && config.searchColumns && config.searchColumns.length > 0) {
+        const term = `%${query.search}%`
+        const orClauses = config.searchColumns
+          .map((col) => camelToSnake(col))
+          .map((col) => `${col}.ilike.${term}`)
+        if (orClauses.length > 0) {
+          q = q.or(orClauses.join(','))
+        }
+      }
+
+      // Sort
+      if (query.sortBy) {
+        q = q.order(camelToSnake(query.sortBy), { ascending: query.sortDir !== 'desc' })
+      } else {
+        q = q.order('created_at', { ascending: false })
+      }
+
+      // Pagination
+      const page = query.page ?? 1
+      const pageSize = query.pageSize ?? 50
+      const from = (page - 1) * pageSize
+      q = q.range(from, from + pageSize - 1)
+
+      const { data, error, count } = await q
+      if (error) throw error
+
+      const rows = (data ?? []).map((row: Record<string, unknown>) => mapRow<T>(row))
+      return { data: rows, total: count ?? 0 }
+    },
+
+    async create(data) {
+      const tenantId = config.tenantId()
+      if (!tenantId) throw new Error('No tenant selected')
+
+      const { archetypeData, projectData } = splitFields(data as Record<string, unknown>)
+
+      // 1. Insert into archetype table
+      archetypeData.tenant_id = tenantId
+      if (HAS_KIND.has(config.archetype)) {
+        archetypeData.kind = config.archetypeKind
+      }
+
+      const { data: archetypeRow, error: archetypeError } = await coreClient()
+        .from(ac.table)
+        .insert(archetypeData)
+        .select()
+        .single()
+
+      if (archetypeError) throw archetypeError
+      const archetypeId = (archetypeRow as any).id
+
+      // 2. Insert into project table with archetype FK as PK
+      projectData[fkColumn] = archetypeId
+      projectData.tenant_id = tenantId
+
+      const { error: projectError } = await getClient()
+        .from(config.projectTable)
+        .insert(projectData)
+
+      if (projectError) {
+        await coreClient().from(ac.table).delete().eq('id', archetypeId)
+        throw projectError
+      }
+
+      return { id: archetypeId, ...archetypeRow, ...projectData } as unknown as T
+    },
+
+    async update(id, data) {
+      const { archetypeData, projectData } = splitFields(data as Record<string, unknown>)
+
+      if (Object.keys(archetypeData).length > 0) {
+        const { error } = await coreClient()
+          .from(ac.table)
+          .update(archetypeData)
+          .eq('id', id)
+        if (error) throw error
+      }
+
+      if (Object.keys(projectData).length > 0) {
+        const { error } = await getClient()
+          .from(config.projectTable)
+          .update(projectData)
+          .eq(fkColumn, id)
+        if (error) throw error
+      }
+
+      // Re-fetch
+      const { data: archetypeRow } = await coreClient().from(ac.table).select('*').eq('id', id).single()
+      const { data: projectRow } = await getClient().from(config.projectTable).select('*').eq(fkColumn, id).single()
+
+      const flat = { ...archetypeRow, ...projectRow, id }
+      delete (flat as any)[fkColumn]
+      return mapRow<T>(flat as Record<string, unknown>)
+    },
+
+    async remove(id) {
+      const { error } = await coreClient()
+        .from(ac.table)
+        .delete()
+        .eq('id', id)
+      if (error) throw error
+    },
+  }
+}

package/src/data/cached.ts

@@ -0,0 +1,55 @@
+import type { DataProvider, CrudQuery, CrudResult } from './types'
+import { globalCache, stableKey } from '../lib/cache'
+
+export interface ProviderCacheOptions {
+  /** Table/entity name — used as cache key namespace */
+  table: string
+  /** Dynamic tenant ID resolver */
+  tenantId: () => string | undefined
+  /** Override default TTL for this entity (ms) */
+  ttl?: number
+}
+
+/**
+ * Wraps a DataProvider with transparent read caching + mutation invalidation.
+ *
+ * - `list()` results are cached by query params
+ * - `create()`, `update()`, `remove()` invalidate all cached entries for the table
+ */
+export function withCache<T extends { id: string }>(
+  provider: DataProvider<T>,
+  options: ProviderCacheOptions,
+): DataProvider<T> {
+  function prefix(): string {
+    return `${options.tenantId() ?? '_'}:${options.table}`
+  }
+
+  return {
+    async list(query: CrudQuery): Promise<CrudResult<T>> {
+      const key = `${prefix()}:${stableKey(query)}`
+      const cached = globalCache.get<CrudResult<T>>(key)
+      if (cached) return cached
+
+      const result = await provider.list(query)
+      globalCache.set(key, result, options.ttl)
+      return result
+    },
+
+    async create(data) {
+      const result = await provider.create(data)
+      globalCache.invalidate(prefix())
+      return result
+    },
+
+    async update(id, data) {
+      const result = await provider.update(id, data)
+      globalCache.invalidate(prefix())
+      return result
+    },
+
+    async remove(id) {
+      await provider.remove(id)
+      globalCache.invalidate(prefix())
+    },
+  }
+}

package/src/data/fayz-api.ts

@@ -0,0 +1,200 @@
+import type { CrudQuery, CrudResult, DataProvider } from './types'
+
+type FayzApiFilterOperator = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'like' | 'ilike' | 'is_null' | 'is_not_null'
+
+interface FayzApiTableFilter {
+  column: string
+  operator: FayzApiFilterOperator
+  value?: unknown
+}
+
+export interface FayzApiProviderConfig {
+  baseUrl?: string
+  projectId?: string
+  tenantId?: string | (() => string | undefined)
+  tenantIdColumn?: string | false
+  entityKey?: string
+  table?: string
+  schema?: string
+  idColumn?: string
+  searchColumns?: string[]
+  runtimeToken?: string | (() => string | undefined | Promise<string | undefined>)
+  headers?: () => HeadersInit | Promise<HeadersInit>
+  fetcher?: typeof fetch
+}
+
+function resolveTenantId(config?: FayzApiProviderConfig): string | undefined {
+  const tenantId = config?.tenantId
+  return typeof tenantId === 'function' ? tenantId() : tenantId
+}
+
+async function resolveRuntimeToken(config?: FayzApiProviderConfig): Promise<string | undefined> {
+  const runtimeToken = config?.runtimeToken
+  return typeof runtimeToken === 'function' ? runtimeToken() : runtimeToken
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, '')
+}
+
+function appendQuery(
+  url: URL,
+  query: CrudQuery,
+  tenantId?: string,
+  tenantIdColumn = 'tenant_id',
+  searchColumns: string[] = [],
+): void {
+  const filters = normalizeFilters(query.filters)
+  if (query.search && searchColumns[0]) {
+    filters.push({ column: searchColumns[0], operator: 'ilike', value: `%${query.search}%` })
+  }
+  if (query.sortBy) url.searchParams.set('sortColumn', query.sortBy)
+  if (query.sortDir) url.searchParams.set('sortDirection', query.sortDir)
+  if (query.page != null) url.searchParams.set('page', String(query.page))
+  if (query.pageSize != null) url.searchParams.set('limit', String(query.pageSize))
+  if (tenantId) filters.push({ column: tenantIdColumn, operator: 'eq', value: tenantId })
+  if (filters.length > 0) url.searchParams.set('filters', JSON.stringify(filters))
+}
+
+async function parseResponse<T>(response: Response): Promise<T> {
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    throw new Error(`[@fayz-ai/core] Fayz API request failed (${response.status}): ${text || response.statusText}`)
+  }
+  return response.json() as Promise<T>
+}
+
+function isFilterOperator(value: unknown): value is FayzApiFilterOperator {
+  return typeof value === 'string' && [
+    'eq',
+    'neq',
+    'gt',
+    'lt',
+    'gte',
+    'lte',
+    'like',
+    'ilike',
+    'is_null',
+    'is_not_null',
+  ].includes(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function normalizeFilters(filters?: Record<string, unknown>): FayzApiTableFilter[] {
+  if (!filters) return []
+  return Object.entries(filters).map(([column, raw]) => {
+    if (isRecord(raw) && isFilterOperator(raw.operator)) {
+      return { column, operator: raw.operator, value: raw.value }
+    }
+    return { column, operator: 'eq', value: raw }
+  })
+}
+
+export function createFayzApiProvider<T extends { id: string }>(
+  entityOrTable: string,
+  config: FayzApiProviderConfig = {},
+): DataProvider<T> {
+  const fetcher = config.fetcher ?? fetch
+  const baseUrl = trimTrailingSlash(config.baseUrl ?? '')
+  const projectId = config.projectId
+  const table = config.table ?? entityOrTable
+  const idColumn = config.idColumn ?? 'id'
+
+  async function headers(runtimeToken?: string): Promise<HeadersInit> {
+    return {
+      'Content-Type': 'application/json',
+      ...(config.headers ? await config.headers() : {}),
+      ...(runtimeToken ? { Authorization: `Bearer ${runtimeToken}` } : {}),
+    }
+  }
+
+  function tableRowsUrl(runtime = false): URL {
+    const prefix = baseUrl || (typeof window !== 'undefined' ? window.location.origin : 'http://localhost')
+    const encodedProjectId = encodeURIComponent(projectId ?? 'current')
+    const encodedTable = encodeURIComponent(table)
+    const route = runtime
+      ? `/api/v1/runtime/projects/${encodedProjectId}/database/tables/${encodedTable}/rows`
+      : `/api/projects/${encodedProjectId}/database/tables/${encodedTable}/rows`
+    const url = new URL(route, prefix)
+    if (config.schema) url.searchParams.set('schema', config.schema)
+    return url
+  }
+
+  function withTenant(data: Record<string, unknown>, runtime = false): Record<string, unknown> {
+    if (runtime) return data
+    const tenantId = resolveTenantId(config)
+    if (!tenantId || config.tenantIdColumn === false) return data
+    return { ...data, [config.tenantIdColumn ?? 'tenant_id']: tenantId }
+  }
+
+  function primaryKeys(id: string): Record<string, unknown> {
+    return { [idColumn]: id }
+  }
+
+  async function listRows(query: CrudQuery): Promise<CrudResult<T>> {
+    const runtimeToken = await resolveRuntimeToken(config)
+    const runtime = Boolean(runtimeToken)
+    const url = tableRowsUrl(runtime)
+    appendQuery(
+      url,
+      query,
+      runtime || config.tenantIdColumn === false ? undefined : resolveTenantId(config),
+      config.tenantIdColumn || undefined,
+      config.searchColumns,
+    )
+    const result = await parseResponse<{ rows: T[]; total: number }>(await fetcher(url, { headers: await headers(runtimeToken) }))
+    return { data: result.rows, total: result.total }
+  }
+
+  async function assertTenantScopedRowExists(id: string, runtime = false): Promise<void> {
+    if (runtime) return
+    const tenantId = config.tenantIdColumn === false ? undefined : resolveTenantId(config)
+    if (!tenantId) return
+
+    const result = await listRows({ filters: { [idColumn]: id }, page: 1, pageSize: 1 })
+    if (result.data.length === 0) {
+      throw new Error(`[@fayz-ai/core] Row "${id}" was not found for the active tenant.`)
+    }
+  }
+
+  return {
+    async list(query: CrudQuery): Promise<CrudResult<T>> {
+      return listRows(query)
+    },
+
+    async create(data) {
+      const runtimeToken = await resolveRuntimeToken(config)
+      const runtime = Boolean(runtimeToken)
+      return parseResponse<T>(await fetcher(tableRowsUrl(runtime), {
+        method: 'POST',
+        headers: await headers(runtimeToken),
+        body: JSON.stringify(withTenant(data as Record<string, unknown>, runtime)),
+      }))
+    },
+
+    async update(id, data) {
+      const runtimeToken = await resolveRuntimeToken(config)
+      const runtime = Boolean(runtimeToken)
+      await assertTenantScopedRowExists(id, runtime)
+      return parseResponse<T>(await fetcher(tableRowsUrl(runtime), {
+        method: 'PATCH',
+        headers: await headers(runtimeToken),
+        body: JSON.stringify({ primaryKeys: primaryKeys(id), data }),
+      }))
+    },
+
+    async remove(id) {
+      const runtimeToken = await resolveRuntimeToken(config)
+      const runtime = Boolean(runtimeToken)
+      await assertTenantScopedRowExists(id, runtime)
+      await parseResponse<{ deletedCount: number }>(await fetcher(tableRowsUrl(runtime), {
+        method: 'DELETE',
+        headers: await headers(runtimeToken),
+        body: JSON.stringify({ rows: [primaryKeys(id)] }),
+      }))
+    },
+  }
+}

package/src/data/index.ts

@@ -0,0 +1,8 @@
+export { createSupabaseProvider, setGlobalSupabaseClient, getSupabaseClientOptional } from './supabase'
+export { createFayzApiProvider } from './fayz-api'
+export { createMockProvider } from './mock'
+export { resolveDataProvider } from './resolve'
+export type { DataProvider, CrudQuery, CrudResult } from './types'
+export type { SupabaseProviderConfig } from './supabase'
+export type { FayzApiProviderConfig } from './fayz-api'
+export type { ResolveDataProviderOptions } from './resolve'

package/src/data/mock.ts

@@ -0,0 +1,84 @@
+import type { DataProvider, CrudQuery, CrudResult } from './types'
+import type { EntityDef } from '../types/crud'
+
+export function createMockProvider<T extends { id: string; [key: string]: unknown }>(
+  entityDefOrSearchKeys: EntityDef<T> | string[],
+  initialData: T[] = [],
+): DataProvider<T> {
+  let items = [...initialData]
+
+  const searchableKeys = Array.isArray(entityDefOrSearchKeys)
+    ? entityDefOrSearchKeys
+    : entityDefOrSearchKeys.fields.filter((f) => f.searchable).map((f) => f.key)
+
+  const defaultSort = Array.isArray(entityDefOrSearchKeys) ? undefined : entityDefOrSearchKeys.defaultSort
+  const defaultSortDir = Array.isArray(entityDefOrSearchKeys) ? 'asc' : (entityDefOrSearchKeys.defaultSortDir ?? 'asc')
+
+  return {
+    async list(query: CrudQuery): Promise<CrudResult<T>> {
+      let filtered = [...items]
+
+      if (query.search && searchableKeys.length > 0) {
+        const term = query.search.toLowerCase()
+        filtered = filtered.filter((item) =>
+          searchableKeys.some((key) => {
+            const val = item[key]
+            return typeof val === 'string' && val.toLowerCase().includes(term)
+          }),
+        )
+      }
+
+      // Faceted / dynamic filters (equality match per key).
+      if (query.filters) {
+        for (const [key, val] of Object.entries(query.filters)) {
+          if (val == null || val === '') continue
+          filtered = filtered.filter((item) => item[key] === val)
+        }
+      }
+
+      const sortBy = query.sortBy ?? defaultSort
+      const sortDir = query.sortDir ?? defaultSortDir
+      if (sortBy) {
+        filtered.sort((a, b) => {
+          const av = a[sortBy] ?? ''
+          const bv = b[sortBy] ?? ''
+          const cmp = typeof av === 'number' && typeof bv === 'number'
+            ? av - bv
+            : String(av).localeCompare(String(bv))
+          return sortDir === 'desc' ? -cmp : cmp
+        })
+      }
+
+      const total = filtered.length
+      const page = query.page ?? 1
+      const pageSize = query.pageSize ?? 50
+      const start = (page - 1) * pageSize
+      const data = filtered.slice(start, start + pageSize)
+      return { data, total }
+    },
+
+    async create(data) {
+      const now = new Date().toISOString()
+      const item = {
+        ...data,
+        id: crypto.randomUUID(),
+        tenantId: 'mock-tenant',
+        createdAt: now,
+        updatedAt: now,
+      } as unknown as T
+      items.unshift(item)
+      return item
+    },
+
+    async update(id, data) {
+      const idx = items.findIndex((i) => i.id === id)
+      if (idx === -1) throw new Error(`[@fayz-ai/core] Mock provider: item not found: ${id}`)
+      items[idx] = { ...items[idx], ...data, updatedAt: new Date().toISOString() }
+      return items[idx]!
+    },
+
+    async remove(id) {
+      items = items.filter((i) => i.id !== id)
+    },
+  }
+}

package/src/data/resolve.ts

@@ -0,0 +1,108 @@
+import type { EntityDef } from '../types/crud'
+import type { BackendRef } from '../manifest'
+import type { DataProvider } from './types'
+import { getSupabaseClientOptional } from './supabase'
+import { createSupabaseProvider } from './supabase'
+import { createArchetypeProvider } from './archetype'
+import { createMockProvider } from './mock'
+import { createFayzApiProvider, type FayzApiProviderConfig } from './fayz-api'
+import { withCache } from './cached'
+import { getActiveTenantId } from '../tenant'
+
+/**
+ * Resolve the best data provider for an EntityDef.
+ * Supabase → Archetype → Mock (in order of preference).
+ *
+ * Reusable by createCrudPage, PluginRegistryManager, or any component
+ * that needs a DataProvider from an EntityDef.
+ */
+export interface ResolveDataProviderOptions {
+  backend?: BackendRef
+  fayzApi?: Omit<FayzApiProviderConfig, 'entityKey' | 'table'>
+  customProviders?: Record<string, <T extends { id: string }>(entityDef: EntityDef<T>, mockData?: T[]) => DataProvider<T>>
+}
+
+export function resolveDataProvider<T extends { id: string }>(
+  entityDef: EntityDef<T>,
+  mockData?: T[],
+  options: ResolveDataProviderOptions = {},
+): DataProvider<T> {
+  const backend = options.backend
+
+  if (backend?.provider === 'mock') {
+    return createMockProvider(entityDef, mockData)
+  }
+
+  if (backend?.provider === 'fayz-api') {
+    const table = entityDef.data?.table ?? entityDef.name
+    return createFayzApiProvider<T>(table, {
+      ...options.fayzApi,
+      baseUrl: options.fayzApi?.baseUrl ?? backend.url,
+      projectId: options.fayzApi?.projectId ?? backend.projectRef,
+      entityKey: entityDef.name ?? table,
+      table,
+      schema: options.fayzApi?.schema ?? entityDef.data?.schema,
+      idColumn: options.fayzApi?.idColumn ?? entityDef.data?.columnMap?.id,
+      searchColumns: options.fayzApi?.searchColumns ?? entityDef.data?.searchColumns ?? entityDef.fields
+        .filter((field) => field.searchable)
+        .map((field) => field.key),
+      tenantIdColumn: entityDef.data?.tenantScoped === false
+        ? false
+        : options.fayzApi?.tenantIdColumn ?? entityDef.data?.tenantIdColumn,
+      tenantId: options.fayzApi?.tenantId ?? (() => getActiveTenantId()),
+    })
+  }
+
+  if (backend?.provider === 'custom') {
+    const adapterId = backend.adapterId
+    const factory = adapterId ? options.customProviders?.[adapterId] : undefined
+    if (!adapterId || !factory) {
+      throw new Error(`[@fayz-ai/core] Custom data provider "${adapterId ?? 'unknown'}" is not registered.`)
+    }
+    return factory<T>(entityDef, mockData)
+  }
+
+  const client = getSupabaseClientOptional()
+
+  if (client && entityDef.data?.table) {
+    const tenantId = () => getActiveTenantId()
+    const cacheOptions = {
+      table: entityDef.data.table,
+      tenantId,
+      ttl: entityDef.data.cacheTTL,
+    }
+
+    if (entityDef.data.archetype && entityDef.data.archetypeKind && !entityDef.data.schema) {
+      return withCache(createArchetypeProvider<T>({
+        archetype: entityDef.data.archetype,
+        archetypeKind: entityDef.data.archetypeKind,
+        projectTable: entityDef.data.table,
+        tenantId,
+        searchColumns: entityDef.data.searchColumns ?? entityDef.fields
+          .filter((field) => field.searchable)
+          .map((field) => field.key),
+      }), cacheOptions)
+    }
+
+    return withCache(createSupabaseProvider<T>(entityDef.data.table, {
+      schema: entityDef.data.schema,
+      tenantId: entityDef.data.tenantScoped === false ? undefined : tenantId,
+      tenantIdColumn: entityDef.data.tenantIdColumn,
+      searchColumns: entityDef.data.searchColumns ?? entityDef.fields
+        .filter((field) => field.searchable)
+        .map((field) => field.key),
+      selectColumns: entityDef.data.selectColumns,
+      columnMap: entityDef.data.columnMap,
+      filters: entityDef.data.filters,
+      defaults: entityDef.data.defaults,
+    }), cacheOptions)
+  }
+
+  if (entityDef.data?.table) {
+    console.warn(
+      `[fayz/core] resolveDataProvider: falling back to mock for "${entityDef.name}" (table: ${entityDef.data.table}). ` +
+      `Supabase client ${client ? 'available' : 'NOT initialized'}.`,
+    )
+  }
+  return createMockProvider(entityDef, mockData)
+}