@fayz-ai/core 0.8.0 → 0.8.2

package/src/manifest/index.ts

@@ -1,7 +1,9 @@
 import type { EntityDef } from '../types/crud'
 import type { LocaleConfig } from '../types/i18n'
-import type { PermissionsConfig } from '../types/permissions'
+import type { PermissionsConfig, FeatureDeclaration } from '../types/permissions'
 import type { BillingConfig } from '../types/billing'
+import type { LimitDeclaration } from '../types/entitlements'
+import type { AIToolParameters, AIToolExecution, AgentRpcDeclaration } from '../types/plugins'
 import type { BlockNode } from '../blocks'
 
 // ---------------------------------------------------------------------------
@@ -18,7 +20,7 @@ import type { BlockNode } from '../blocks'
 // right is why W1 is the "point of no return".
 // ---------------------------------------------------------------------------
 
-export const CURRENT_MANIFEST_VERSION = 2
+export const CURRENT_MANIFEST_VERSION = 3
 
 export type BackendProvider = 'supabase' | 'fayz-api' | 'fayz-shop' | 'mock' | 'custom'
 
@@ -68,6 +70,97 @@ export interface SurfaceManifest {
   options?: Record<string, unknown>
 }
 
+// ---------------------------------------------------------------------------
+// Agent Contract (manifest v3) — everything a SERVER-SIDE agent runtime needs
+// to operate the app without a browser: the full entity surface, the tool
+// catalog with its authorization requirements, the pool RPCs writes go
+// through, and the structured domain knowledge the app wants in the prompt.
+// Derived from app code at publish (never hand-written) and synced to the
+// Fayz platform, where it becomes the versioned AgentContract the broker
+// validates every turn against.
+// ---------------------------------------------------------------------------
+
+/** JSON-safe projection of an EntityDef — schema only, no components/closures.
+ *  `data` mirrors EntityDef.data: everything the server-plane read executor
+ *  needs (tenant scoping, search/select column allowlists, fixed filters). */
+export interface EntityContract {
+  key: string
+  label: string
+  labelPlural?: string
+  /** Plan-limit key rows of this entity consume (EntityDef.limitKey). */
+  limitKey?: string
+  /** Permission to READ via the generic data primitives (EntityDef.permission). */
+  permission?: { feature: string; action: string }
+  data: {
+    table: string
+    schema?: string
+    tenantScoped?: boolean
+    tenantIdColumn?: string
+    searchColumns?: string[]
+    selectColumns?: string
+    columnMap?: Record<string, string>
+    archetype?: string
+    archetypeKind?: string
+    filters?: Record<string, string>
+  }
+  fields: Array<{
+    key: string
+    label: string
+    type: string
+    required?: boolean
+    searchable?: boolean
+    /** FieldDef.hint — the field's helper text. Carried into the contract
+     *  because it is what tells the agent what a non-obvious column expects:
+     *  an id to look up, a default it should not restate, a format. */
+    hint?: string
+    /** Allowed values for select-like fields. */
+    options?: string[]
+    /** Table the relation field points at (FieldRelation.table). */
+    relationTable?: string
+  }>
+}
+
+/** JSON-safe projection of a PluginAITool + its owning plugin. */
+export interface AIToolContract {
+  id: string
+  name: string
+  description: string
+  mode: 'read' | 'persist'
+  parameters?: AIToolParameters
+  permission?: { feature: string; action: string }
+  limitKey?: string
+  execution?: AIToolExecution
+  requiresConfirmation?: boolean
+  pluginId?: string
+  category?: string
+}
+
+/** A tenant-scoped pool RPC the server-plane executor may call. Canonical
+ *  definition lives with the plugin types (plugins declare these). */
+export type { AgentRpcDeclaration as RpcContract } from '../types/plugins'
+
+/** Structured domain knowledge rendered into the agent's prompt as labelled
+ *  sections — statuses with transitions, scheduling defaults, free-form rules. */
+export interface AgentDomainKnowledge {
+  statuses?: Record<string, Array<{ id: string; label: string; availableWhen?: unknown }>>
+  scheduleDefaults?: Record<string, unknown>
+  businessRules?: Array<{ id: string; description: string }>
+}
+
+export interface AgentContract {
+  persona?: { name?: string; systemPrompt?: string; icon?: string }
+  /** When 'server', surfaces stop shipping data-tool executors: the broker
+   *  executes reads/writes server-plane and the surface only handles
+   *  client-plane tools. Flipped per app — no lockstep release. */
+  executionPlane?: 'client' | 'server'
+  entities?: EntityContract[]
+  tools?: AIToolContract[]
+  registries?: Array<{ pluginId: string; id: string; entityKey?: string; readOnly?: boolean }>
+  declaredFeatures?: FeatureDeclaration[]
+  rpcs?: AgentRpcDeclaration[]
+  domainKnowledge?: AgentDomainKnowledge
+}
+
 export interface AppManifest {
   manifestVersion: number
   id: string
@@ -83,6 +176,13 @@ export interface AppManifest {
   entities?: EntityDef[]
   permissions?: PermissionsConfig
   billing?: BillingConfig
+  /** The RESOLVED limit declarations (4-layer merge: core < entity-derived <
+   *  plugin < app), so a server runtime counts exactly what the client counts. */
+  limitDeclarations?: LimitDeclaration[]
+  /** v3: the agent contract — see the section comment above. */
+  agent?: AgentContract
+  /** sha256 of the canonical serialization (excluding this field). */
+  contractHash?: string
 }
 
 // ---------------------------------------------------------------------------
@@ -108,6 +208,9 @@ const allowedManifestKeys = new Set([
   'billing',
   'entities',
   'surfaces',
+  'limitDeclarations',
+  'agent',
+  'contractHash',
 ])
 const allowedBackendKeys = new Set(['provider', 'projectRef', 'url', 'adapterId', 'options'])
 const allowedSurfaceKeys = new Set(['scaffold', 'options', 'plugins', 'pages'])
@@ -122,6 +225,12 @@ export function registerManifestMigration(fromVersion: number, fn: ManifestMigra
   migrations.set(fromVersion, fn)
 }
 
+// v2 → v3 is purely additive (limitDeclarations/agent/contractHash are optional):
+// a v2 manifest is a valid v3 manifest with those sections absent. Registered
+// here so every consumer migrates for free; `fayz manifest emit` fills the new
+// sections on the next regeneration.
+registerManifestMigration(2, (m) => m)
+
 /** Bring any manifest up to CURRENT_MANIFEST_VERSION, or throw if it was built
  *  for a newer SDK than this runtime understands. */
 export function migrateManifest(input: AnyManifest): AppManifest {
@@ -167,6 +276,21 @@ export function validateManifest(m: AppManifest): string[] {
   validateLooseObject(manifest.theme, 'manifest.theme', problems)
   validateLooseObject(manifest.permissions, 'manifest.permissions', problems)
   validateLooseObject(manifest.billing, 'manifest.billing', problems)
+  validateLooseObject(manifest.agent, 'manifest.agent', problems)
+  if (manifest.contractHash !== undefined && !isNonEmptyString(manifest.contractHash)) {
+    problems.push('manifest.contractHash must be a non-empty string')
+  }
+  if (manifest.limitDeclarations !== undefined) {
+    if (!Array.isArray(manifest.limitDeclarations)) {
+      problems.push('manifest.limitDeclarations must be an array')
+    } else {
+      manifest.limitDeclarations.forEach((decl, index) => {
+        if (!isRecord(decl) || !isNonEmptyString(decl.key) || !isNonEmptyString(decl.table)) {
+          problems.push(`manifest.limitDeclarations[${index}] must declare key and table`)
+        }
+      })
+    }
+  }
   if (manifest.entities !== undefined) {
     if (!Array.isArray(manifest.entities)) {
       problems.push('manifest.entities must be an array')
@@ -368,7 +492,7 @@ function addUnsupportedKeys(
 ): void {
   for (const key of Object.keys(value)) {
     if (!allowedKeys.has(key)) {
-      problems.push(`${path}.${key} is not part of AppManifest v2`)
+      problems.push(`${path}.${key} is not part of AppManifest v${CURRENT_MANIFEST_VERSION}`)
     }
   }
 }

package/src/manifest/serialize.ts

@@ -0,0 +1,52 @@
+import type { AppManifest } from './index'
+
+// ---------------------------------------------------------------------------
+// Deterministic serialization — the SAME manifest object must always produce
+// the SAME bytes, because the sha256 of those bytes (`contractHash`) is what
+// makes `fayz manifest sync` idempotent and lets `fayz doctor` prove the
+// committed app.manifest.json is not stale. Rules: object keys sorted, arrays
+// kept in declared order (order is meaning: nav position, migration order),
+// 2-space indent, trailing newline, `contractHash` itself excluded.
+// ---------------------------------------------------------------------------
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortValue)
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(record).sort()) {
+      const v = record[key]
+      if (v !== undefined) out[key] = sortValue(v)
+    }
+    return out
+  }
+  return value
+}
+
+/** Canonical JSON of a manifest (contractHash excluded, keys sorted). */
+export function serializeManifest(manifest: AppManifest): string {
+  const { contractHash: _omit, ...rest } = manifest
+  return `${JSON.stringify(sortValue(rest), null, 2)}\n`
+}
+
+/**
+ * sha256 (hex) of the canonical serialization. Async because it runs on
+ * WebCrypto (`globalThis.crypto.subtle`), which exists in every runtime we
+ * target (browsers, Node ≥ 18, edge) — no node:crypto import, keeping this
+ * module bundleable everywhere.
+ */
+export async function computeContractHash(manifest: AppManifest): Promise<string> {
+  const bytes = new TextEncoder().encode(serializeManifest(manifest))
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+/** Serialize WITH the freshly computed contractHash embedded — what
+ *  `fayz manifest emit` writes to app.manifest.json. */
+export async function serializeManifestWithHash(manifest: AppManifest): Promise<string> {
+  const contractHash = await computeContractHash(manifest)
+  const { contractHash: _omit, ...rest } = manifest
+  return `${JSON.stringify(sortValue({ ...rest, contractHash }), null, 2)}\n`
+}

package/src/plugin/runtime.ts

@@ -20,6 +20,7 @@ import type {
   DashboardSurface,
 } from '../types/plugins'
 import type { FeatureDeclaration } from '../types/permissions'
+import type { LimitDeclaration } from '../types/entitlements'
 import type { ConnectorDefinition } from '../integrations'
 import { getComponent } from '../registry'
 
@@ -110,6 +111,7 @@ function createEmptyRuntime(context: PluginRuntimeContext = EMPTY_CONTEXT): Plug
     registries: new Map(),
     connectorsByHost: new Map(),
     pluginFeatures: [],
+    pluginLimits: [],
     issues: [],
   }
 }
@@ -242,6 +244,7 @@ export function resolvePluginRuntime({
   const registries = new Map<string, PluginRegistryDef[]>()
   const connectorsByHost = new Map<string, ConnectorDefinition[]>()
   const pluginFeatures: FeatureDeclaration[] = []
+  const pluginLimits: LimitDeclaration[] = []
 
   for (const plugin of activePlugins) {
     routes.push(...plugin.routes.map((r) => ({ ...r, plugin })))
@@ -261,6 +264,7 @@ export function resolvePluginRuntime({
       connectorsByHost.set(connector.hostPluginId, list)
     }
     if (plugin.declaredFeatures) pluginFeatures.push(...plugin.declaredFeatures)
+    if (plugin.declaredLimits) pluginLimits.push(...plugin.declaredLimits)
     widgets.push(...plugin.widgets.map((w, i) => ({
       ...w,
       order: w.order ?? i,
@@ -283,7 +287,7 @@ export function resolvePluginRuntime({
   widgets.sort((a, b) => a.zone !== b.zone ? a.zone.localeCompare(b.zone) : a.order - b.order)
   dashboardWidgets.sort((a, b) => a.order - b.order)
 
-  return { context, plugins: resolvedPlugins, activePlugins, routes, navigation, settingsTabs, widgets, dashboardWidgets, capabilities, aiTools, issues, registries, connectorsByHost, pluginFeatures }
+  return { context, plugins: resolvedPlugins, activePlugins, routes, navigation, settingsTabs, widgets, dashboardWidgets, capabilities, aiTools, issues, registries, connectorsByHost, pluginFeatures, pluginLimits }
 }
 
 export function getWidgetsForZone(

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

@@ -7,7 +7,7 @@ export type FieldType =
   | 'select' | 'multiselect' | 'segmented'
   | 'relation'
   | 'date' | 'datetime' | 'time'
-  | 'boolean' | 'textarea'
+  | 'boolean' | 'textarea' | 'markdown'
   | 'color' | 'computed'
 
 /** Foreign-key source for a `relation` field: the option list is loaded from a
@@ -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/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 {
@@ -225,6 +234,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 +263,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 +369,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 +463,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"]}