@fayz-ai/core 0.8.1 → 0.8.3

package/src/search/text.ts

@@ -0,0 +1,206 @@
+// Text folding + ranking for global search. The same folding must exist in SQL
+// as public.fayz_norm() (@fayz-ai/db 018_global_search.sql), or server and
+// client disagree on what matched.
+
+const COMBINING_MARKS = /[\u0300-\u036f]/g
+
+/** Strip diacritics, lowercase, collapse non-alphanumerics to single spaces. */
+export function foldText(value: unknown): string {
+  if (typeof value !== 'string' || value === '') return ''
+  return value
+    .normalize('NFD')
+    .replace(COMBINING_MARKS, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+}
+
+/** Fold, keeping each folded char's index in the source — used for highlighting. */
+export function foldWithMap(value: string): { folded: string; map: number[] } {
+  const out: string[] = []
+  const map: number[] = []
+  let pendingSpace = false
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i]!
+    const folded = ch.normalize('NFD').replace(COMBINING_MARKS, '').toLowerCase()
+    for (const f of folded) {
+      const alnum = (f >= 'a' && f <= 'z') || (f >= '0' && f <= '9')
+      if (!alnum) { pendingSpace = out.length > 0; continue }
+      if (pendingSpace) { out.push(' '); map.push(i); pendingSpace = false }
+      out.push(f)
+      map.push(i)
+    }
+  }
+  return { folded: out.join(''), map }
+}
+
+/** Digits only — phone numbers, CPF/CNPJ, SKUs typed with separators. */
+export function digitsOf(value: unknown): string {
+  return typeof value === 'string' ? value.replace(/\D+/g, '') : ''
+}
+
+export interface NormalizedQuery {
+  /** What the user typed, untouched. */
+  raw: string
+  /** Folded form of the whole query — the "phrase". */
+  folded: string
+  /** Folded query split on whitespace. */
+  tokens: string[]
+  /** Digits the user typed, when they typed enough of them to mean a number. */
+  digits: string
+  /** The longest token — the most selective thing to send to a `%LIKE%` backend. */
+  anchor: string
+}
+
+/** Below this a phone/document lookup is indistinguishable from noise. */
+const MIN_DIGIT_QUERY = 4
+
+export function normalizeQuery(raw: string): NormalizedQuery {
+  const folded = foldText(raw)
+  const tokens = folded ? folded.split(' ').filter(Boolean) : []
+  const digits = raw.replace(/\D+/g, '')
+  let anchor = ''
+  for (const token of tokens) if (token.length > anchor.length) anchor = token
+  return {
+    raw,
+    folded,
+    tokens,
+    digits: digits.length >= MIN_DIGIT_QUERY ? digits : '',
+    anchor,
+  }
+}
+
+// Fuzzy similarity — Sørensen–Dice over bigrams. Same family as pg_trgm's
+// similarity(), so both sides rank near-misses the same way.
+
+function bigrams(value: string): string[] {
+  if (value.length < 2) return value ? [value] : []
+  const out: string[] = []
+  for (let i = 0; i < value.length - 1; i++) out.push(value.slice(i, i + 2))
+  return out
+}
+
+/** 0 (nothing in common) … 1 (identical). Both inputs must already be folded. */
+export function similarity(a: string, b: string): number {
+  if (!a || !b) return 0
+  if (a === b) return 1
+  const left = bigrams(a)
+  const right = bigrams(b)
+  if (left.length === 0 || right.length === 0) return 0
+  const pool = new Map<string, number>()
+  for (const g of left) pool.set(g, (pool.get(g) ?? 0) + 1)
+  let shared = 0
+  for (const g of right) {
+    const count = pool.get(g)
+    if (count) { shared++; pool.set(g, count - 1) }
+  }
+  return (2 * shared) / (left.length + right.length)
+}
+
+/** Best similarity between the query token and any single word of the text. */
+function wordSimilarity(text: string, token: string): number {
+  let best = similarity(text, token)
+  for (const word of text.split(' ')) {
+    if (!word) continue
+    const s = similarity(word, token)
+    if (s > best) best = s
+  }
+  return best
+}
+
+// ---------------------------------------------------------------------------
+// Ranking
+// ---------------------------------------------------------------------------
+
+export interface RankCandidate {
+  /** Folded display name — what the user is most likely aiming at. */
+  title: string
+  /** Folded concatenation of every searchable value on the record. */
+  haystack: string
+  /** Digits of every phone/document-ish value on the record. */
+  digits?: string
+}
+
+/** A fuzzy word has to be at least this close before it counts as a match. */
+const FUZZY_FLOOR = 0.62
+
+/** Score a candidate 0…1. Zero means "not a match" — the score is also the filter. */
+export function scoreCandidate(query: NormalizedQuery, candidate: RankCandidate): number {
+  const { folded, tokens } = query
+  if (!folded || tokens.length === 0) return 0
+  const title = candidate.title
+  const haystack = candidate.haystack || title
+
+  // Phrase: the query as one string.
+  let phrase = 0
+  if (title === folded) phrase = 1
+  else if (title.startsWith(folded)) phrase = 0.94
+  else if (title.includes(' ' + folded)) phrase = 0.88
+  else if (title.includes(folded)) phrase = 0.76
+  else if (haystack.startsWith(folded) || haystack.includes(' ' + folded)) phrase = 0.7
+  else if (haystack.includes(folded)) phrase = 0.62
+
+  // Tokens: every word must land somewhere ("maria silva" → "Maria da Silva").
+  let tokenTotal = 0
+  let fuzzyUsed = false
+  for (const token of tokens) {
+    let best = 0
+    if (title.startsWith(token)) best = 0.95
+    else if (title.includes(' ' + token)) best = 0.85
+    else if (title.includes(token)) best = 0.7
+    else if (haystack.startsWith(token) || haystack.includes(' ' + token)) best = 0.6
+    else if (haystack.includes(token)) best = 0.5
+    else {
+      const sim = wordSimilarity(title, token)
+      if (sim >= FUZZY_FLOOR) { best = 0.45 * sim; fuzzyUsed = true }
+    }
+    if (best === 0) return phrase > 0 ? phrase : 0
+    tokenTotal += best
+  }
+  let tokenScore = tokenTotal / tokens.length
+  // A typo-only match must never outrank a literal one.
+  if (fuzzyUsed) tokenScore *= 0.8
+
+  let score = Math.max(phrase, tokenScore)
+
+  // Digits: a phone number has no words to match.
+  if (query.digits && candidate.digits && candidate.digits.includes(query.digits)) {
+    score = Math.max(score, 0.72 + Math.min(0.2, query.digits.length / 50))
+  }
+
+  if (score === 0) return 0
+
+  // Tie-break: shorter title wins ("Ana" over "Ana Beatriz" for "ana").
+  const brevity = 1 / (1 + Math.max(0, title.length - folded.length) / 40)
+  return score * 0.97 + brevity * 0.03
+}
+
+/** Ranges in the ORIGINAL text covered by the query, merged and sorted. */
+export function highlightRanges(text: string, query: NormalizedQuery): Array<[number, number]> {
+  if (!text || query.tokens.length === 0) return []
+  const { folded, map } = foldWithMap(text)
+  if (!folded) return []
+  const spans: Array<[number, number]> = []
+  const needles = query.tokens.length > 1 ? [query.folded, ...query.tokens] : [query.folded]
+  for (const needle of needles) {
+    if (!needle) continue
+    let from = 0
+    for (;;) {
+      const at = folded.indexOf(needle, from)
+      if (at === -1) break
+      const start = map[at]
+      const endChar = map[at + needle.length - 1]
+      if (start !== undefined && endChar !== undefined) spans.push([start, endChar + 1])
+      from = at + needle.length
+    }
+  }
+  if (spans.length === 0) return []
+  spans.sort((a, b) => a[0] - b[0])
+  const merged: Array<[number, number]> = [spans[0]!]
+  for (const span of spans.slice(1)) {
+    const last = merged[merged.length - 1]!
+    if (span[0] <= last[1]) last[1] = Math.max(last[1], span[1])
+    else merged.push(span)
+  }
+  return merged
+}

package/src/search/types.ts

@@ -0,0 +1,75 @@
+import type { EntityDef } from '../types/crud'
+
+/** One searchable thing — declaring an entity is all it takes to be findable. */
+export interface SearchTarget {
+  /** Stable entity key (`deriveEntityKey`): 'person:client', 'product', … */
+  key: string
+  /** Plural human label; becomes the result group heading. */
+  label: string
+  icon?: string
+  entity: EntityDef
+  mockData?: Array<{ id: string }>
+  /** Multiplies the final score. Default 1. */
+  boost?: number
+}
+
+export interface SearchHit {
+  /** `${target.key}:${record id}` — stable across both search paths. */
+  uid: string
+  id: string
+  /** Target key this record came from. */
+  key: string
+  /** Group heading (the target's plural label). */
+  group: string
+  icon?: string
+  title: string
+  subtitle?: string
+  /** 0 … 1 (times the target boost). Higher is better. */
+  score: number
+  archetype?: string
+  archetypeKind?: string
+  table?: string
+  /** The row, when the path that found it had one. The index path returns
+   *  titles only. */
+  record?: Record<string, unknown>
+}
+
+export interface SearchGroup {
+  key: string
+  label: string
+  icon?: string
+  hits: SearchHit[]
+  /** True when this group hit its per-target cap — more matches exist. */
+  hasMore: boolean
+}
+
+export type SearchPath = 'index' | 'scan' | 'cache'
+
+export interface GlobalSearchResult {
+  query: string
+  hits: SearchHit[]
+  groups: SearchGroup[]
+  /** Which path produced this result — surfaced for diagnostics, not for UI. */
+  via: SearchPath
+  /** Targets whose query failed. Never fatal: a broken table cannot blind the box. */
+  failed: string[]
+  /** Wall-clock milliseconds. */
+  elapsedMs: number
+  /** True while a better (network) answer is still on its way. */
+  partial: boolean
+}
+
+export interface SearchOptions {
+  /** Permission filtering is the caller's job — the engine searches what it's handed. */
+  targets: SearchTarget[]
+  /** Max hits returned overall. Default 30. */
+  limit?: number
+  /** Max hits per target. Default 5. */
+  perTarget?: number
+  /** Fired with early/partial answers before the authoritative one resolves. */
+  onPartial?: (result: GlobalSearchResult) => void
+  /** Discard the result if this aborts. */
+  signal?: AbortSignal
+  /** Skip the server index and force the per-entity scan (tests, diagnostics). */
+  forceScan?: boolean
+}

package/src/types/billing.ts

@@ -1,3 +1,5 @@
+import type { PlanEntitlements } from './entitlements'
+
 export interface Plan {
   id: string
   name: string
@@ -5,13 +7,33 @@ export interface Plan {
   price: number
   currency: string
   interval: 'month' | 'year'
+  /** Marketing bullets shown on the pricing page (display only). */
   features: string[]
   highlighted?: boolean
   stripePriceId?: string
+  /**
+   * Structured access grants for this plan (feature gates + quantity caps). This
+   * is the enforcement source of truth — distinct from `features` (display
+   * bullets). See {@link PlanEntitlements}.
+   */
+  entitlements?: PlanEntitlements
 }
 
+/**
+ * Signature of the checkout seam. When `BillingConfig.onCheckout` is defined the
+ * shell's Subscription page calls it (passing the target plan id) INSTEAD of
+ * writing `plan` straight onto the org via `adapter.updateOrg`. This is where a
+ * real payment gateway (Stripe Checkout, Pix, Mercado Pago, …) plugs in: return
+ * once the user is redirected / the intent is created, and let the webhook be the
+ * source of truth for the persisted plan. Left undefined, the shell mutates the
+ * plan optimistically (dev / self-serve / free-tier flows).
+ */
+export type BillingCheckoutFn = (planId: string) => Promise<void> | void
+
 export interface BillingConfig {
   plans: Plan[]
   stripePublishableKey?: string
   portalUrl?: string
+  /** Payment-gateway seam — see {@link BillingCheckoutFn}. */
+  onCheckout?: BillingCheckoutFn
 }

package/src/types/crud.ts

@@ -79,7 +79,8 @@ export interface FieldGroup {
   label: string
   description?: string
   columns?: 1 | 2 | 3
-  /** Renders a decorative image slot to the left of the group's fields. */
+  /** Renders an image slot to the left of the group's fields. Functional when
+   *  the EntityDef supplies `image`; a plain placeholder otherwise. */
   imageSlot?: boolean
 }
 
@@ -104,6 +105,28 @@ export interface DetailTab {
 
 export type FormLayout = 'person' | 'product' | 'service' | 'location' | 'order' | 'subject' | 'generic'
 
+/**
+ * Makes a field group's `imageSlot` functional. Without this the slot renders as
+ * a decorative placeholder — it always did, which is why product forms showed an
+ * empty thumbnail even for products that have images.
+ *
+ * Upload needs the record to exist (the file is attached to its id), so the slot
+ * stays read-only in create mode and becomes editable after the first save.
+ */
+export interface EntityImageConfig {
+  // Rows are loosely typed here on purpose: EntityDef<T> is consumed as
+  // EntityDef<Record<string, unknown>> by the generic CRUD machinery, and a
+  // T-parameterised callback makes the whole EntityDef invariant in T.
+  /** Current image URL for this record, if any. */
+  get: (row: Record<string, any>) => string | undefined
+  /** Persist a new image and return its URL. Omit to keep the slot read-only. */
+  upload?: (file: File, row: Record<string, any>) => Promise<string>
+  /** Remove the current image. Omit to hide the remove affordance. */
+  remove?: (row: Record<string, any>) => Promise<void>
+  /** Accepted mime types. Defaults to image/*. */
+  accept?: string
+}
+
 export interface EntityDef<T = Record<string, unknown>> {
   name: string
   namePlural?: string
@@ -111,6 +134,8 @@ export interface EntityDef<T = Record<string, unknown>> {
   layout?: FormLayout
   fields: FieldDef[]
   fieldGroups?: FieldGroup[]
+  /** Wiring for the `imageSlot` of whichever field group declares one. */
+  image?: EntityImageConfig
   detailTabs?: DetailTab[]
   data?: {
     table: string
@@ -134,4 +159,26 @@ export interface EntityDef<T = Record<string, unknown>> {
   /** Faceted filters shown as pills below the list search box. Each references a
    *  field whose `options` supply the pills; an "All" pill clears the filter. */
   facets?: { field: string; allLabel?: string }[]
+  /**
+   * Plan quantity-limit key gating creation of this entity (matches a
+   * `PlanEntitlements.limits` key + a `LimitDeclaration`). When set, the CRUD
+   * engine gates the "+ New" button (LimitGate), guards the create-form submit
+   * and the CSV import (useLimitGuard) against the plan cap, and invalidates the
+   * live count after a successful create. Absent ⇒ no plan gating (RBAC only).
+   */
+  limitKey?: string
+  /**
+   * Permission required to READ this entity through the agent's generic data
+   * primitives (searchRecords/queryData) — checked per TARGET at execution
+   * time, so one generic tool still honors per-user access. Absent ⇒ readable
+   * by any signed-in member (same as the CRUD list today).
+   */
+  permission?: { feature: string; action: string }
+  /**
+   * Exclude this entity from the agent's data primitives. For entities whose
+   * table is an extension/join shape the generic provider can't read usefully
+   * (e.g. staff_members without a name column) — expose a queryEntities
+   * read-model instead and hide the raw one here.
+   */
+  agentHidden?: boolean
 }

package/src/types/entitlements.ts

@@ -0,0 +1,45 @@
+/**
+ * Entitlements — the plan side of the access decision (the role side lives in
+ * permissions.ts). A plan grants FEATURES (gate a page/module) and caps LIMITS
+ * (quantity ceilings). Feature ids are the SAME id space as RBAC/nav
+ * (`permission.feature`), so a single id threads role → nav → plan.
+ */
+export interface PlanEntitlements {
+  /**
+   * feature id (same id as RBAC/nav) → whether the plan grants it. Absent = the
+   * plan does not gate the feature (allowed). Only an explicit `false` denies —
+   * this keeps plans additive: features unknown to a plan stay open.
+   */
+  features?: Record<string, boolean>
+  /**
+   * limitKey → cap. `-1` = unlimited. Keys are app/plugin-defined (e.g.
+   * `clients`, `users`, `locations`, `bookings_month`). A key absent here means
+   * "no cap on this plan" (unlimited). See {@link LimitDeclaration} for how a
+   * key is bound to a countable table.
+   */
+  limits?: Record<string, number>
+}
+
+/**
+ * Declares HOW a limit key is counted. Contributed by plugins via
+ * `PluginManifest.declaredLimits` (aggregated by the plugin runtime) and/or
+ * overridden per-app via `billing.limitDeclarations`. The access engine reads a
+ * declaration to resolve a `limitKey` → a live `count(*)` against `table` for
+ * the active tenant, with no per-entity code.
+ */
+export interface LimitDeclaration {
+  /** Limit key — matches a key in {@link PlanEntitlements.limits}. */
+  key: string
+  /** Human label for paywalls / usage banners (e.g. "Patients"). */
+  label: string
+  /** Table the count runs against (tenant-scoped via `tenant_id`). */
+  table: string
+  /** Optional `kind` column filter for tables that hold several entity kinds. */
+  kindFilter?: string
+  /**
+   * Counting window. `'month'` counts rows created since the start of the
+   * current month (recurring quotas like bookings/month); `'total'` (default)
+   * counts every row (stock quantities like clients/users).
+   */
+  period?: 'month' | 'total'
+}

package/src/types/index.ts

@@ -1,10 +1,11 @@
 // Re-export all core types
 export type { EntityArchetype, BaseEntity, PersonEntity, ProductEntity, ServiceEntity, OrderEntity, TransactionEntity, LocationEntity, ScheduleEntity, CategoryEntity } from './entities'
 export type { EntityDef, FieldDef, FieldType, FieldRelation, FieldGroup, DetailTab, FormLayout, ComputedFieldValue } from './crud'
-export type { PluginManifest, PluginScope, PluginStatus, ResolvedPluginManifest, PluginRuntime, PluginRuntimeContext, PluginWidgetZone, PluginWidgetDefinition, PluginNavigationEntry, PluginSettingsTab, PluginRouteDefinition, PluginAITool, PluginRegistryDef, PluginMigration, PluginDiagnostic, VerticalId, ScaffoldType } from './plugins'
+export type { PluginManifest, PluginScope, PluginStatus, ResolvedPluginManifest, PluginRuntime, PluginRuntimeContext, PluginWidgetZone, PluginWidgetDefinition, PluginNavigationEntry, PluginSettingsTab, PluginRouteDefinition, PluginAITool, AIToolMode, AIToolExecution, AgentRpcDeclaration, AIToolParameterProperty, AIToolParameters, AIToolSuggestion, PluginRegistryDef, PluginMigration, PluginDiagnostic, VerticalId, ScaffoldType } from './plugins'
 export type { AuthAdapter, AuthUser, AuthSession } from './auth'
 export type { OrgAdapter, Organization, OrgMember } from './org'
-export type { PermissionsConfig, FeatureDeclaration, PermissionAction } from './permissions'
-export type { Plan, BillingConfig } from './billing'
+export type { PermissionsConfig, FeatureDeclaration, PermissionAction, PermissionProfile, SystemPermission } from './permissions'
+export type { Plan, BillingConfig, BillingCheckoutFn } from './billing'
+export type { PlanEntitlements, LimitDeclaration } from './entitlements'
 export type { ThemeBrand, ThemeRadius, ThemeMode } from './theme'
 export type { LocaleConfig } from './i18n'

package/src/types/org.ts

@@ -36,6 +36,28 @@ export interface OrgMembership {
   profileName: string
 }
 
+/**
+ * A team member in the Person-first model: a person (of a configured team kind)
+ * with an OPTIONAL access overlay. `membership` is present only when the person
+ * has login + RBAC role (a `tenant_members` row linked by `person_id`).
+ */
+export interface TeamPerson {
+  personId: string
+  name: string
+  kind: string
+  email?: string
+  avatarUrl?: string
+  isActive: boolean
+  membership?: {
+    memberId: string
+    userId: string
+    /** RBAC role key (tenant_members.role). */
+    profileId: string
+    profileName?: string
+    joinedAt?: string
+  }
+}
+
 export interface Location {
   id: string
   tenantId: string
@@ -78,6 +100,13 @@ export interface OrgAdapter {
   createOrg(name: string, userId: string, options?: CreateOrgOptions): Promise<Organization>
   updateOrg(orgId: string, data: Partial<Organization>): Promise<Organization>
   listMembers(orgId: string): Promise<OrgMember[]>
+  /**
+   * Person-first team list: people whose `kind` is in `personKinds`, each with an
+   * optional membership overlay (login + role) linked by `tenant_members.person_id`.
+   * Optional so adapters can adopt it incrementally; the Team screen falls back to
+   * `listMembers` when absent or when no `personKinds` are configured.
+   */
+  listTeam?(orgId: string, personKinds: string[]): Promise<TeamPerson[]>
   updateMemberProfile(orgId: string, memberId: string, profileId: string): Promise<void>
   removeMember(orgId: string, memberId: string): Promise<void>
   listProfiles(orgId: string): Promise<PermissionProfile[]>

package/src/types/plugins.ts

@@ -1,6 +1,7 @@
 import type React from 'react'
 import type { EntityDef } from './crud'
 import type { FeatureDeclaration, PermissionAction } from './permissions'
+import type { LimitDeclaration } from './entitlements'
 import type { ConnectorDefinition } from '../integrations'
 
 export type VerticalId = 'beauty' | 'food' | 'health' | 'services' | 'retail' | 'education' | (string & {})
@@ -28,6 +29,14 @@ export interface PluginNavigationEntry {
   icon?: string
   badge?: string | number
   permission?: PluginPermissionRequirement
+  /**
+   * When this entry gains sub-path children, the shell also synthesizes a child
+   * pointing back at the parent's own route (so /courses stays reachable under
+   * the "Courses" group). Set false when the parent route is a duplicate of its
+   * first child — e.g. /shop and /shop/products render the same catalog, and
+   * listing both reads as a bug. Defaults to true.
+   */
+  indexChild?: boolean
 }
 
 export interface PluginSettingsTab {
@@ -54,6 +63,10 @@ export interface PluginRouteDefinition {
   permission?: PluginPermissionRequirement
   /** Render edge-to-edge with no page padding/animation wrapper (chat, kanban, canvas). */
   fullBleed?: boolean
+  /** Archetypes this page displays (`archetype` or `archetype:kind`, e.g.
+   *  `'schedule:appointment'`). A CRUD page claims its own; a hand-built page
+   *  must declare it or records it owns resolve to no route. */
+  entityRoutes?: string[]
 }
 
 export type PluginWidgetZone =
@@ -225,6 +238,27 @@ export interface AIToolSuggestion {
   verticalId?: VerticalId
 }
 
+export type AIToolExecution =
+  | { plane: 'server'; kind: 'rpc'; rpc: string }
+  | { plane: 'server'; kind: 'entity_read'; entity: string }
+  | { plane: 'client' }
+
+/**
+ * A tenant-scoped pool RPC (`agent_<domain>_<verb>`) this plugin ships for the
+ * server-plane agent executor. Surfaces in the manifest as
+ * `agent.rpcs` (RpcContract) — the broker only ever calls declared functions.
+ */
+export interface AgentRpcDeclaration {
+  /** Function name in the pool, e.g. 'agent_agenda_create_appointment'. */
+  name: string
+  kind: 'read' | 'write'
+  description: string
+  /** JSON Schema of the p_payload argument. */
+  payloadSchema?: AIToolParameters
+  /** Whether the function writes audit_logs itself. */
+  audits?: boolean
+}
+
 export interface PluginAITool {
   id: string
   name: string
@@ -233,6 +267,31 @@ export interface PluginAITool {
   mode: AIToolMode
   parameters?: AIToolParameters
   permission?: PluginPermissionRequirement
+  /**
+   * Quantity-limit key this tool's writes consume (e.g. 'bookings_month' for a
+   * booking-creating tool). Persist-mode tools that create countable rows MUST
+   * declare it so the agent executor can run the SAME plan-limit guard the UI
+   * runs (guard before execute, invalidate after) — an AI agent never clicks a
+   * gated button, so the declarative contract is its only gate.
+   */
+  limitKey?: string
+  /**
+   * Where the tool runs. Server-plane is what makes browserless channels
+   * (WhatsApp, MCP) able to run the tool at all:
+   * - `{ plane:'server', kind:'rpc', rpc }` — the Fayz broker calls the named
+   *   `agent_*` RPC in the tenant pool (writes / guarded reads).
+   * - `{ plane:'server', kind:'entity_read', entity }` — the broker runs the
+   *   generic tenant-scoped read against the entity's table (derived tools).
+   * - `{ plane:'client' }` (or absent) — a locally registered executor runs it
+   *   in the surface (navigation, modals).
+   */
+  execution?: AIToolExecution
+  /**
+   * Require an explicit human confirmation before executing. Defaults to true
+   * for `mode: 'persist'` tools — the channel renders it natively (FAB modal,
+   * WhatsApp yes/no reply).
+   */
+  requiresConfirmation?: boolean
   suggestions?: AIToolSuggestion[]
   category?: string
   tags?: string[]
@@ -314,6 +373,28 @@ export interface PluginManifest {
   entities?: string[]
   permissions?: string[]
   declaredFeatures?: FeatureDeclaration[]
+  /**
+   * Quantity limits this plugin knows how to count. Aggregated by the plugin
+   * runtime into `PluginRuntime.pluginLimits` and consumed by the access engine
+   * (useLimit / useLimitGuard) so a plugin "is born compatible" with freemium
+   * caps without any per-app wiring. See {@link LimitDeclaration}.
+   */
+  declaredLimits?: LimitDeclaration[]
+  /** Pool RPCs this plugin ships for the server-plane agent executor. */
+  declaredRpcs?: AgentRpcDeclaration[]
+  /**
+   * Read-models this plugin exposes to the agent's generic data primitives
+   * (searchRecords/queryData) BEYOND its CRUD registries — typically its
+   * views/ledgers (v_appointments, plg_financial_movements). `key` is a stable
+   * ASCII id (never derived from a translated label); the entity's own
+   * `permission` gates each call.
+   */
+  queryEntities?: Array<{
+    key: string
+    entity: EntityDef
+    /** Base tables may opt into createRecord; views/ledgers stay read-only. */
+    writable?: boolean
+  }>
   registries?: PluginRegistryDef[]
   /**
    * Connectors this plugin contributes. An ADDON plugin declares its connector(s)
@@ -386,4 +467,6 @@ export interface PluginRuntime {
   /** Connectors contributed by active plugins, grouped by the host plugin they extend. */
   connectorsByHost: Map<string, ConnectorDefinition[]>
   pluginFeatures: FeatureDeclaration[]
+  /** Limit declarations aggregated from every active plugin's `declaredLimits`. */
+  pluginLimits: LimitDeclaration[]
 }

package/dist/chunk-2NTHNWEH.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/entity/registry.ts"],"names":[],"mappings":";;;AAgBA,IAAM,cAAA,uBAAqB,GAAA,EAA8B;AAElD,SAAS,eAAe,KAAA,EAA+B;AAC5D,EAAA,cAAA,CAAe,GAAA,CAAI,KAAA,CAAM,SAAA,EAAW,KAAK,CAAA;AAC3C;AAEO,SAAS,eAAe,GAAA,EAA2C;AACxE,EAAA,OAAO,cAAA,CAAe,IAAI,GAAG,CAAA;AAC/B;AAEO,SAAS,cAAA,GAAqC;AACnD,EAAA,OAAO,KAAA,CAAM,IAAA,CAAK,cAAA,CAAe,MAAA,EAAQ,CAAA;AAC3C;AAEO,SAAS,mBAAA,GAA4B;AAC1C,EAAA,cAAA,CAAe,KAAA,EAAM;AACvB;AAEO,SAAS,gBAAgB,SAAA,EAA8B;AAC5D,EAAA,MAAM,OAAO,SAAA,CAAU,IAAA,CAAK,aAAY,CAAE,OAAA,CAAQ,QAAQ,GAAG,CAAA;AAC7D,EAAA,IAAI,SAAA,CAAU,IAAA,EAAM,SAAA,IAAa,SAAA,CAAU,MAAM,aAAA,EAAe;AAC9D,IAAA,OAAO,GAAG,SAAA,CAAU,IAAA,CAAK,SAAS,CAAA,CAAA,EAAI,SAAA,CAAU,KAAK,aAAa,CAAA,CAAA;AAAA,EACpE;AACA,EAAA,IAAI,SAAA,CAAU,IAAA,EAAM,SAAA,EAAW,OAAO,UAAU,IAAA,CAAK,SAAA;AACrD,EAAA,OAAO,IAAA;AACT","file":"chunk-2NTHNWEH.cjs","sourcesContent":["import type { EntityDef } from '../types/crud'\nimport type { EntityArchetype } from '../types/entities'\n\nexport interface RegisteredEntity {\n  entityKey: string\n  label: string\n  labelPlural: string\n  icon?: string\n  fields: EntityDef['fields']\n  source: 'app' | 'plugin'\n  archetype?: EntityArchetype\n  pluginId?: string\n  pluginName?: string\n  pluginIcon?: string\n}\n\nconst entityRegistry = new Map<string, RegisteredEntity>()\n\nexport function registerEntity(entry: RegisteredEntity): void {\n  entityRegistry.set(entry.entityKey, entry)\n}\n\nexport function getEntityByKey(key: string): RegisteredEntity | undefined {\n  return entityRegistry.get(key)\n}\n\nexport function getAllEntities(): RegisteredEntity[] {\n  return Array.from(entityRegistry.values())\n}\n\nexport function clearEntityRegistry(): void {\n  entityRegistry.clear()\n}\n\nexport function deriveEntityKey(entityDef: EntityDef): string {\n  const name = entityDef.name.toLowerCase().replace(/\\s+/g, '-')\n  if (entityDef.data?.archetype && entityDef.data?.archetypeKind) {\n    return `${entityDef.data.archetype}:${entityDef.data.archetypeKind}`\n  }\n  if (entityDef.data?.archetype) return entityDef.data.archetype\n  return name\n}\n"]}