@fayz-ai/core 0.8.1 → 0.8.3

package/src/address/index.ts

@@ -0,0 +1,188 @@
+// ---------------------------------------------------------------------------
+// Postal code → address lookup (SDK-level — shared by any surface that collects
+// an address: storefront checkout, the SaaS address book, CRM, booking).
+//
+// Sits beside ./phone for the same reason: knowing that a Brazilian CEP is
+// eight digits, and that '01310100' means Avenida Paulista, is not a
+// storefront concern. It belongs wherever an address is typed.
+//
+// The lookup itself is behind an interface. ViaCEP is the default because it is
+// free, keyless and CORS-enabled, but it is a third party the merchant does not
+// control — so swapping it for an edge-function proxy (shared cache, no
+// third-party call from the shopper's browser) must be one line, not a rewrite.
+// ---------------------------------------------------------------------------
+
+/**
+ * An address as a postal service knows it: everything except the parts only the
+ * resident can supply (number, complement).
+ *
+ * Field names mirror ShippingAddressInput in @fayz-ai/shop so the value crosses
+ * from lookup to checkout to the order with no translation step in between.
+ */
+export interface PostalAddress {
+  postalCode: string
+  street: string
+  district: string
+  city: string
+  state: string
+  country: string
+  /** IBGE municipality code when the source provides one — useful for tax later. */
+  cityCode?: string
+}
+
+/** Where a postal code is resolved. Implementations must not throw for a
+ *  well-formed code that simply does not exist — that is `null`, not an error. */
+export interface PostalLookupProvider {
+  lookup(postalCode: string): Promise<PostalAddress | null>
+}
+
+/** Keep only digits. */
+export function normalizePostalCode(value: string): string {
+  return (value || '').replace(/\D/g, '')
+}
+
+/** '01310100' | '01310-100' -> '01310-100'. Partial input formats progressively. */
+export function formatPostalCode(value: string): string {
+  const digits = normalizePostalCode(value).slice(0, 8)
+  return digits.length > 5 ? `${digits.slice(0, 5)}-${digits.slice(5)}` : digits
+}
+
+/** A Brazilian CEP is exactly eight digits. */
+export function isValidPostalCode(value: string): boolean {
+  return normalizePostalCode(value).length === 8
+}
+
+// ---------------------------------------------------------------------------
+// Cache
+//
+// A CEP maps to the same street for years, so the second lookup of one should
+// never leave the browser. This also keeps a busy storefront well clear of
+// ViaCEP's per-IP rate limit. localStorage when there is a window, an in-memory
+// Map otherwise (SSR, tests, node) — never a hard failure over a cache miss.
+// ---------------------------------------------------------------------------
+
+const CACHE_KEY = 'fayz.postal.cache.v1'
+const memoryCache = new Map<string, PostalAddress>()
+
+function readCache(code: string): PostalAddress | undefined {
+  const hit = memoryCache.get(code)
+  if (hit) return hit
+  try {
+    const raw = globalThis.localStorage?.getItem(CACHE_KEY)
+    if (!raw) return undefined
+    const all = JSON.parse(raw) as Record<string, PostalAddress>
+    const stored = all[code]
+    if (stored) memoryCache.set(code, stored)
+    return stored
+  } catch {
+    return undefined
+  }
+}
+
+function writeCache(code: string, address: PostalAddress): void {
+  memoryCache.set(code, address)
+  try {
+    const store = globalThis.localStorage
+    if (!store) return
+    const raw = store.getItem(CACHE_KEY)
+    const all = raw ? (JSON.parse(raw) as Record<string, PostalAddress>) : {}
+    all[code] = address
+    store.setItem(CACHE_KEY, JSON.stringify(all))
+  } catch {
+    /* quota or private mode — the in-memory copy still stands for this session */
+  }
+}
+
+/** Drop the cache. Exposed for tests and for a "wrong address?" escape hatch. */
+export function clearPostalCache(): void {
+  memoryCache.clear()
+  try {
+    globalThis.localStorage?.removeItem(CACHE_KEY)
+  } catch {
+    /* ignore */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ViaCEP
+// ---------------------------------------------------------------------------
+
+interface ViaCepResponse {
+  cep?: string
+  logradouro?: string
+  bairro?: string
+  localidade?: string
+  uf?: string
+  ibge?: string
+  erro?: boolean | string
+}
+
+/**
+ * ViaCEP (https://viacep.com.br). Free, no key, CORS-enabled.
+ *
+ * The trap: an unknown CEP does NOT come back as 404. ViaCEP answers HTTP 200
+ * with `{"erro": true}` (and, on some deploys, the string "true"), so checking
+ * response.ok alone yields an address of empty strings that silently overwrites
+ * whatever the shopper had typed. Both shapes are treated as "not found".
+ */
+export function createViaCepProvider(options?: { fetcher?: typeof fetch }): PostalLookupProvider {
+  const fetcher = options?.fetcher ?? globalThis.fetch
+  return {
+    async lookup(postalCode: string): Promise<PostalAddress | null> {
+      const code = normalizePostalCode(postalCode)
+      if (code.length !== 8) return null
+
+      const response = await fetcher(`https://viacep.com.br/ws/${code}/json/`)
+      if (!response.ok) throw new Error(`Consulta de CEP falhou (${response.status})`)
+
+      const data = (await response.json()) as ViaCepResponse
+      if (data.erro === true || data.erro === 'true' || !data.localidade) return null
+
+      return {
+        postalCode: code,
+        street: data.logradouro ?? '',
+        district: data.bairro ?? '',
+        city: data.localidade,
+        state: (data.uf ?? '').toUpperCase(),
+        country: 'BR',
+        cityCode: data.ibge || undefined,
+      }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Module-level resolver — same shape as setShopTenantResolver /
+// setShopAccessTokenResolver, so an app overrides the source once at boot
+// instead of threading a provider through every component that needs a CEP.
+// ---------------------------------------------------------------------------
+
+let _provider: PostalLookupProvider | null = null
+
+export function setPostalLookupProvider(provider: PostalLookupProvider | null): void {
+  _provider = provider
+}
+
+export function getPostalLookupProvider(): PostalLookupProvider {
+  if (!_provider) _provider = createViaCepProvider()
+  return _provider
+}
+
+/**
+ * Resolve a postal code to an address, through the cache.
+ *
+ * Returns null for a code that is malformed or does not exist; throws only when
+ * the lookup itself failed (offline, provider down), so a caller can tell
+ * "no such CEP" from "we could not check right now" and say the right thing.
+ */
+export async function lookupPostalCode(postalCode: string): Promise<PostalAddress | null> {
+  const code = normalizePostalCode(postalCode)
+  if (code.length !== 8) return null
+
+  const cached = readCache(code)
+  if (cached) return cached
+
+  const address = await getPostalLookupProvider().lookup(code)
+  if (address) writeCache(code, address)
+  return address
+}

package/src/data/archetype.ts

@@ -109,9 +109,11 @@ export function createArchetypeProvider<T extends { id: string }>(
 
       // Pure archetype → read public.<base> directly (filtered by kind);
       // otherwise the v_ view (JOINs public extension with the public archetype).
+      // 'none' skips PostgREST's count aggregate entirely — see CrudQuery.countMode.
+      const countOpts = query.countMode === 'none' ? undefined : { count: 'exact' as const }
       let q = isPure
-        ? coreClient().from(ac.table).select('*', { count: 'exact' }).eq('tenant_id', tenantId)
-        : getClient().from(viewName).select('*', { count: 'exact' }).eq('tenant_id', tenantId)
+        ? coreClient().from(ac.table).select('*', countOpts).eq('tenant_id', tenantId)
+        : getClient().from(viewName).select('*', countOpts).eq('tenant_id', tenantId)
 
       if (isPure && HAS_KIND.has(config.archetype)) {
         q = q.eq('kind', config.archetypeKind)

package/src/data/count.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { countByTenant, invalidateCount } from './count'
+import { setGlobalSupabaseClient } from './supabase'
+import { setActiveTenantId } from '../tenant'
+
+// ---------------------------------------------------------------------------
+// Mock Supabase client — a thenable query builder that records .eq/.gte calls.
+// ---------------------------------------------------------------------------
+
+interface MockClient {
+  client: unknown
+  selectCalls: number
+  lastEq: Array<[string, unknown]>
+  lastGte: Array<[string, unknown]>
+  setCount: (n: number, error?: unknown) => void
+}
+
+function makeClient(initialCount = 0): MockClient {
+  const state = { count: initialCount as number, error: null as unknown }
+  const record: MockClient = {
+    client: null,
+    selectCalls: 0,
+    lastEq: [],
+    lastGte: [],
+    setCount: (n, error = null) => {
+      state.count = n
+      state.error = error
+    },
+  }
+
+  const query: Record<string, unknown> = {
+    eq: (col: string, val: unknown) => {
+      record.lastEq.push([col, val])
+      return query
+    },
+    gte: (col: string, val: unknown) => {
+      record.lastGte.push([col, val])
+      return query
+    },
+    then: (resolve: (r: { count: number; error: unknown }) => void) =>
+      resolve({ count: state.count, error: state.error }),
+  }
+
+  record.client = {
+    from: () => ({
+      select: (_cols: string, _opts: unknown) => {
+        record.selectCalls++
+        return query
+      },
+    }),
+  }
+  return record
+}
+
+describe('countByTenant', () => {
+  beforeEach(() => {
+    invalidateCount() // clear all cached counts
+    setGlobalSupabaseClient(null as unknown as object)
+    setActiveTenantId('tenant-1')
+  })
+
+  it('returns 0 in mock mode (no supabase client) — never blocks', async () => {
+    setGlobalSupabaseClient(null as unknown as object)
+    expect(await countByTenant('clients')).toBe(0)
+  })
+
+  it('returns 0 when no tenant is resolvable', async () => {
+    setActiveTenantId(undefined)
+    const m = makeClient(5)
+    setGlobalSupabaseClient(m.client as object)
+    expect(await countByTenant('clients')).toBe(0)
+  })
+
+  it('counts tenant-scoped rows via head:true', async () => {
+    const m = makeClient(42)
+    setGlobalSupabaseClient(m.client as object)
+    expect(await countByTenant('clients')).toBe(42)
+    expect(m.lastEq).toContainEqual(['tenant_id', 'tenant-1'])
+  })
+
+  it('caches within the TTL (second read does not hit the DB)', async () => {
+    const m = makeClient(10)
+    setGlobalSupabaseClient(m.client as object)
+    await countByTenant('clients')
+    await countByTenant('clients')
+    expect(m.selectCalls).toBe(1)
+  })
+
+  it('fresh:true bypasses the cache', async () => {
+    const m = makeClient(10)
+    setGlobalSupabaseClient(m.client as object)
+    await countByTenant('clients')
+    await countByTenant('clients', { fresh: true })
+    expect(m.selectCalls).toBe(2)
+  })
+
+  it('invalidateCount(table) drops the cached value', async () => {
+    const m = makeClient(10)
+    setGlobalSupabaseClient(m.client as object)
+    await countByTenant('clients')
+    invalidateCount('clients')
+    await countByTenant('clients')
+    expect(m.selectCalls).toBe(2)
+  })
+
+  it('separate keys (kind/period) are cached independently', async () => {
+    const m = makeClient(3)
+    setGlobalSupabaseClient(m.client as object)
+    await countByTenant('bookings', { period: 'month' })
+    await countByTenant('bookings', { period: 'total' })
+    expect(m.selectCalls).toBe(2)
+  })
+
+  it('applies kind filter and month window', async () => {
+    const m = makeClient(7)
+    setGlobalSupabaseClient(m.client as object)
+    await countByTenant('items', { kind: 'product', period: 'month' })
+    expect(m.lastEq).toContainEqual(['kind', 'product'])
+    expect(m.lastGte.some(([col]) => col === 'created_at')).toBe(true)
+  })
+
+  it('fails open (returns 0) when the query errors', async () => {
+    const m = makeClient(0)
+    m.setCount(0, new Error('boom'))
+    setGlobalSupabaseClient(m.client as object)
+    expect(await countByTenant('clients')).toBe(0)
+  })
+
+  it('fails open (returns 0) instead of hanging when the query never settles', async () => {
+    // A cold-boot query can be issued before the auth session is ready and then
+    // never resolve. The guard awaiting this must not hang the UI forever.
+    const client = {
+      from: () => ({
+        select: () => ({
+          eq: () => ({
+            eq: () => neverSettles,
+            gte: () => neverSettles,
+            then: neverSettles.then.bind(neverSettles),
+          }),
+        }),
+      }),
+    }
+    const neverSettles = { then: () => {} } as unknown as Promise<never>
+    setGlobalSupabaseClient(client as object)
+
+    vi.useFakeTimers()
+    const pending = countByTenant('clients', { fresh: true })
+    await vi.advanceTimersByTimeAsync(6_000)
+    await expect(pending).resolves.toBe(0)
+    vi.useRealTimers()
+  })
+})

package/src/data/count.ts

@@ -0,0 +1,131 @@
+import { getSupabaseClientOptional } from './supabase'
+import { getActiveTenantId } from '../tenant'
+
+/**
+ * Tenant-scoped row counter — the single cheap `count(*)` helper the access
+ * engine uses to resolve quantity limits. Uses Supabase's `head:true` count so
+ * no rows are transferred. Results are cached briefly per tenant+table+filter to
+ * survive the burst of reads a page does (nav badge + gate + list), and can be
+ * force-invalidated by creates via {@link invalidateCount}.
+ *
+ * MOCK MODE NEVER BLOCKS: with no global Supabase client the count is `0`, so
+ * limits always read as "well under cap" — offline/demo apps stay fully usable.
+ */
+
+export interface CountByTenantOptions {
+  /** Optional `kind` column filter for multi-kind tables. */
+  kind?: string
+  /** `'month'` counts rows created since the 1st of the current month; `'total'` (default) counts all. */
+  period?: 'month' | 'total'
+  /** Tenant override; defaults to the active tenant (getActiveTenantId). */
+  tenantId?: string
+  /** Skip the short-lived cache and hit the DB (used by fresh guard checks). */
+  fresh?: boolean
+}
+
+const TTL_MS = 15_000
+
+interface CacheEntry {
+  value: number
+  expires: number
+}
+
+const cache = new Map<string, CacheEntry>()
+
+function cacheKey(table: string, tenantId: string, kind: string | undefined, period: string): string {
+  return `${tenantId}::${table}::${kind ?? ''}::${period}`
+}
+
+function startOfMonthISO(): string {
+  const now = new Date()
+  return new Date(now.getFullYear(), now.getMonth(), 1).toISOString()
+}
+
+/**
+ * How long a usage count may take before we give up on it. Failing OPEN on an
+ * error was always the policy (see below); a request that never settles is the
+ * same failure with worse symptoms — a caller awaiting this (the create guards)
+ * hangs forever, which reads to the user as a dead button. Observed on a cold
+ * boot, where the query can be issued before the auth session is ready.
+ */
+const COUNT_TIMEOUT_MS = 5_000
+
+/**
+ * Count rows in `table` for the given (or active) tenant.
+ * Returns 0 when no Supabase client is registered (mock mode).
+ */
+export async function countByTenant(table: string, options: CountByTenantOptions = {}): Promise<number> {
+  const tenantId = options.tenantId ?? getActiveTenantId()
+  if (!tenantId) return 0
+
+  const period = options.period ?? 'total'
+  const key = cacheKey(table, tenantId, options.kind, period)
+
+  if (!options.fresh) {
+    const hit = cache.get(key)
+    if (hit && hit.expires > Date.now()) return hit.value
+  }
+
+  const client = getSupabaseClientOptional() as {
+    from: (t: string) => {
+      select: (columns: string, opts: { count: 'exact'; head: true }) => {
+        eq: (col: string, val: unknown) => unknown
+      }
+    }
+  } | null
+
+  // No client → mock/offline mode: never block.
+  if (!client) return 0
+
+  let query = client.from(table).select('*', { count: 'exact', head: true }).eq('tenant_id', tenantId) as {
+    eq: (col: string, val: unknown) => unknown
+    gte: (col: string, val: unknown) => unknown
+  }
+
+  if (options.kind) {
+    query = query.eq('kind', options.kind) as typeof query
+  }
+  if (period === 'month') {
+    query = query.gte('created_at', startOfMonthISO()) as typeof query
+  }
+
+  // On error OR timeout, fail OPEN (return 0) — a counting failure must never
+  // wall a tenant out of their own product, and must never hang the UI awaiting
+  // it. Enforcement's source of truth is the DB anyway.
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<{ count: null; error: unknown; timedOut: true }>((resolve) => {
+    timer = setTimeout(() => resolve({ count: null, error: 'timeout', timedOut: true }), COUNT_TIMEOUT_MS)
+  })
+  const settled = await Promise.race([
+    query as unknown as Promise<{ count: number | null; error: unknown }>,
+    timeout,
+  ])
+  if (timer) clearTimeout(timer)
+
+  const { count, error } = settled
+  const value = error ? 0 : count ?? 0
+
+  // A timed-out count is not a fact about the tenant — caching it would make one
+  // slow request suppress the guard for the whole TTL.
+  if (!(settled as { timedOut?: true }).timedOut) {
+    cache.set(key, { value, expires: Date.now() + TTL_MS })
+  }
+  return value
+}
+
+/**
+ * Drop cached counts. Called by create handlers (via invalidateLimit) so the
+ * next read reflects the row they just added.
+ *
+ * @param tenantOrKey Substring matched against cache keys (a tenant id, a table
+ *   name, or any fragment). Omit to clear the entire cache.
+ */
+export function invalidateCount(tenantOrKey?: string): void {
+  if (!tenantOrKey) {
+    cache.clear()
+    return
+  }
+  for (const key of cache.keys()) {
+    if (key.includes(tenantOrKey)) cache.delete(key)
+  }
+}

package/src/data/index.ts

@@ -1,4 +1,6 @@
 export { createSupabaseProvider, setGlobalSupabaseClient, getSupabaseClientOptional } from './supabase'
+export { countByTenant, invalidateCount } from './count'
+export type { CountByTenantOptions } from './count'
 export { getFayzCloudClient, FAYZ_CLOUD_URL, FAYZ_CLOUD_PUBLISHABLE_KEY } from './cloud'
 export { createFayzApiProvider } from './platform-api'
 export { createMockProvider } from './mock'

package/src/data/refresh.ts

@@ -0,0 +1,105 @@
+import * as React from 'react'
+import { eventBus } from '../events'
+import { globalCache } from '../lib/cache'
+import { getActiveTenantId } from '../tenant'
+
+// ---------------------------------------------------------------------------
+// Data refresh bus — "something wrote; whoever is showing it should reload".
+//
+// A write that happens OUTSIDE the list showing it (the assistant creating an
+// appointment, a webhook, another tab) used to leave the screen stale until the
+// user reloaded by hand. Providers already invalidate their own read cache on
+// create/update/remove, but a mounted list holds its rows in a store — nothing
+// told it to fetch again.
+//
+// This is the missing half: one broadcast, every surface that renders the
+// affected data listens. Deliberately coarse — a table name, not a row diff.
+// Refetching a page of rows is cheap; a stale screen after "criei o
+// agendamento" is not.
+// ---------------------------------------------------------------------------
+
+export const DATA_CHANGED_EVENT = 'data:changed'
+
+export interface DataChangedPayload {
+  /** Physical table the write touched, when the writer knows it. */
+  table?: string
+  /** Registered entity key (deriveEntityKey), when the writer knows it. */
+  entityKey?: string
+  /** Archetype the record belongs to (`person:client`), when known. */
+  archetype?: string
+  op?: 'create' | 'update' | 'delete' | 'unknown'
+  /** Affected record id, when known. */
+  id?: string
+  /** What caused the write — lets a surface ignore its own UI writes. */
+  source?: 'agent' | 'ui' | 'remote'
+}
+
+/** What a subscriber renders. Any field left out matches everything. */
+export interface DataChangedMatch {
+  table?: string
+  entityKey?: string
+  archetype?: string
+}
+
+/**
+ * A write with NO table/entityKey is a write we could not attribute (a plugin
+ * tool, an RPC). Subscribers still refresh for it: a redundant refetch costs a
+ * request, a missed one costs the user's trust in what the screen shows.
+ */
+export function matchesDataChange(match: DataChangedMatch, payload: DataChangedPayload): boolean {
+  const attributed = payload.table ?? payload.entityKey ?? payload.archetype
+  if (!attributed) return true
+  if (match.table && payload.table && match.table === payload.table) return true
+  if (match.entityKey && payload.entityKey && match.entityKey === payload.entityKey) return true
+  if (match.archetype && payload.archetype && match.archetype === payload.archetype) return true
+  // A subscriber that declared nothing listens to everything.
+  return !match.table && !match.entityKey && !match.archetype
+}
+
+// One agent turn can write twice (create + link). Coalesce so the lists behind
+// it fetch once, after the turn settles, instead of once per call.
+let pending: DataChangedPayload[] = []
+let flushTimer: ReturnType<typeof setTimeout> | null = null
+
+function flush(): void {
+  const batch = pending
+  pending = []
+  flushTimer = null
+  for (const payload of batch) eventBus.emit(DATA_CHANGED_EVENT, payload)
+}
+
+/**
+ * Announce a write. Invalidates the provider read cache for the affected table
+ * (an unattributed write clears it wholesale — a stale hit would defeat the
+ * refetch it just triggered) and broadcasts to mounted surfaces.
+ */
+export function emitDataChanged(payload: DataChangedPayload = {}): void {
+  if (payload.table) {
+    globalCache.invalidate(`${getActiveTenantId() ?? '_'}:${payload.table}`)
+  } else {
+    globalCache.clear()
+  }
+  pending.push({ op: 'unknown', source: 'agent', ...payload })
+  if (flushTimer) return
+  flushTimer = setTimeout(flush, 120)
+}
+
+/** Subscribe for the lifetime of the component. The latest handler always runs. */
+export function useDataChanged(
+  match: DataChangedMatch,
+  handler: (payload: DataChangedPayload) => void,
+  deps: React.DependencyList = [],
+): void {
+  const handlerRef = React.useRef(handler)
+  handlerRef.current = handler
+  const { table, entityKey, archetype } = match
+
+  React.useEffect(
+    () =>
+      eventBus.on<DataChangedPayload>(DATA_CHANGED_EVENT, (payload) => {
+        if (matchesDataChange({ table, entityKey, archetype }, payload)) handlerRef.current(payload)
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [table, entityKey, archetype, ...deps],
+  )
+}

package/src/data/resolve.ts

@@ -66,8 +66,14 @@ export function resolveDataProvider<T extends { id: string }>(
 
   if (client && entityDef.data?.table) {
     const tenantId = () => getActiveTenantId()
+    // Archetype entities share a physical table (e.g. people) across kinds
+    // (student/teacher/staff…). The cache key must carry the kind or the first
+    // kind's resultset is served to every sibling entity (teachers page
+    // listing students).
     const cacheOptions = {
-      table: entityDef.data.table,
+      table: entityDef.data.archetypeKind
+        ? `${entityDef.data.table}#${entityDef.data.archetypeKind}`
+        : entityDef.data.table,
       tenantId,
       ttl: entityDef.data.cacheTTL,
     }

package/src/data/supabase.ts

@@ -82,8 +82,10 @@ export function createSupabaseProvider<T extends { id: string }>(
 
   return {
     async list(query: CrudQuery): Promise<CrudResult<T>> {
+      // 'none' skips PostgREST's count aggregate entirely — see CrudQuery.countMode.
+      const wantCount = query.countMode !== 'none'
       let q = (getClient().from(table) as { select: (...args: unknown[]) => unknown })
-        .select(selectCols, { count: 'exact' }) as Record<string, unknown>
+        .select(selectCols, wantCount ? { count: 'exact' } : undefined) as Record<string, unknown>
 
       const tenantId = resolveTenantId()
       if (tenantId) q = (q as { eq: (col: string, val: string) => unknown }).eq(tenantIdCol, tenantId) as Record<string, unknown>

package/src/data/types.ts

@@ -5,6 +5,12 @@ export interface CrudQuery {
   page?: number
   pageSize?: number
   filters?: Record<string, unknown>
+  /**
+   * Default 'exact' — a CRUD pager needs the total. It is a second aggregate
+   * over the filtered set, and on the live pool cost ~1070ms against ~270ms for
+   * the rows themselves. Callers that only want rows pass 'none' (total: 0).
+   */
+  countMode?: 'exact' | 'none'
 }
 
 export interface CrudResult<T> {

package/src/entity/registry.ts

@@ -8,6 +8,13 @@ export interface RegisteredEntity {
   icon?: string
   fields: EntityDef['fields']
   source: 'app' | 'plugin'
+  /**
+   * The definition itself, so consumers that need to *read* the entity — the AI
+   * tool executor resolving a data provider — are not limited to the display
+   * metadata. Optional: registrations made before this existed omit it.
+   */
+  entityDef?: EntityDef
+  mockData?: Array<{ id: string }>
   archetype?: EntityArchetype
   pluginId?: string
   pluginName?: string