@fayz-ai/core 0.8.1 → 0.8.3

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(