@rizom/brain 0.2.0-alpha.124 → 0.2.0-alpha.125

package/dist/index.js

@@ -1,5 +1,5 @@
 // @bun
-function t(i){return i}var e={name:"@rizom/brain",version:"0.2.0-alpha.124",description:"Brain runtime + CLI \u2014 scaffold, run, and manage AI brain instances",type:"module",bin:{brain:"./dist/brain.js"},exports:{".":{types:"./dist/index.d.ts",import:"./dist/index.js"},"./cli":"./dist/brain.js","./plugins":{types:"./dist/plugins.d.ts",import:"./dist/plugins.js"},"./entities":{types:"./dist/entities.d.ts",import:"./dist/entities.js"},"./services":{types:"./dist/services.d.ts",import:"./dist/services.js"},"./interfaces":{types:"./dist/interfaces.d.ts",import:"./dist/interfaces.js"},"./templates":{types:"./dist/templates.d.ts",import:"./dist/templates.js"},"./site":{types:"./dist/site.d.ts",import:"./dist/site.js"},"./themes":{types:"./dist/themes.d.ts",import:"./dist/themes.js"},"./deploy":{types:"./dist/deploy.d.ts",import:"./dist/deploy.js"},"./tsconfig.instance.json":"./tsconfig.instance.json"},files:["dist","templates","tsconfig.instance.json"],scripts:{build:"bun scripts/build.ts",prepublishOnly:"bun scripts/build.ts","dev:start":"bun scripts/build.ts && bun dist/brain.js start",typecheck:"tsc --noEmit",test:"bun test",lint:"eslint . --ext .ts"},dependencies:{"@clack/prompts":"^0.11.0","@modelcontextprotocol/sdk":"^1.24.0","@tailwindcss/postcss":"^4.1.13","@tailwindcss/typography":"^0.5.19",postcss:"^8.5.6",preact:"^10.27.2","preact-render-to-string":"^6.3.1",tailwindcss:"^4.1.11"},optionalDependencies:{"@bitwarden/sdk-napi":"^1.0.0","@libsql/client":"^0.15.7","@tailwindcss/oxide":"^4.1.4","better-sqlite3":"^11.8.1",lightningcss:"^1.29.2","playwright-core":"^1.56.0","react-devtools-core":"^6.1.1",sharp:"^0.34.5"},devDependencies:{"@brains/app":"workspace:*","@brains/content-formatters":"workspace:*","@brains/deploy-support":"workspace:*","@brains/eslint-config":"workspace:*","@brains/mcp-service":"workspace:*","@brains/plugins":"workspace:*","@brains/ranger":"workspace:*","@brains/relay":"workspace:*","@brains/rover":"workspace:*","@brains/site-composition":"workspace:*","@brains/site-default":"workspace:*","@brains/site-personal":"workspace:*","@brains/site-professional":"workspace:*","@brains/theme-default":"workspace:*","@brains/theme-rizom":"workspace:*","@brains/typescript-config":"workspace:*","@brains/utils":"workspace:*","@types/bun":"latest",rollup:"^4.60.2","rollup-plugin-dts":"^6.4.1",typescript:"^5.3.3"},publishConfig:{access:"public"},repository:{type:"git",url:"https://github.com/rizom-ai/brains.git",directory:"packages/brain-cli"},license:"Apache-2.0",author:"Yeehaa <yeehaa@rizom.ai> (https://rizom.ai)",homepage:"https://github.com/rizom-ai/brains/tree/main/packages/brain-cli#readme",bugs:"https://github.com/rizom-ai/brains/issues",engines:{bun:">=1.3.3"},keywords:["brain","ai","cli","mcp","agent","personal-ai","knowledge-management"]};var n=e.version;export{t as defineBrain,n as PLUGIN_API_VERSION};
+function t(i){return i}var e={name:"@rizom/brain",version:"0.2.0-alpha.125",description:"Brain runtime + CLI \u2014 scaffold, run, and manage AI brain instances",type:"module",bin:{brain:"./dist/brain.js"},exports:{".":{types:"./dist/index.d.ts",import:"./dist/index.js"},"./cli":"./dist/brain.js","./plugins":{types:"./dist/plugins.d.ts",import:"./dist/plugins.js"},"./entities":{types:"./dist/entities.d.ts",import:"./dist/entities.js"},"./services":{types:"./dist/services.d.ts",import:"./dist/services.js"},"./interfaces":{types:"./dist/interfaces.d.ts",import:"./dist/interfaces.js"},"./templates":{types:"./dist/templates.d.ts",import:"./dist/templates.js"},"./site":{types:"./dist/site.d.ts",import:"./dist/site.js"},"./themes":{types:"./dist/themes.d.ts",import:"./dist/themes.js"},"./deploy":{types:"./dist/deploy.d.ts",import:"./dist/deploy.js"},"./tsconfig.instance.json":"./tsconfig.instance.json"},files:["dist","templates","tsconfig.instance.json"],scripts:{build:"bun scripts/build.ts",prepublishOnly:"bun scripts/build.ts","dev:start":"bun scripts/build.ts && bun dist/brain.js start",typecheck:"tsc --noEmit",test:"bun test",lint:"eslint . --ext .ts"},dependencies:{"@clack/prompts":"^0.11.0","@modelcontextprotocol/sdk":"^1.24.0","@tailwindcss/postcss":"^4.1.13","@tailwindcss/typography":"^0.5.19",postcss:"^8.5.6",preact:"^10.27.2","preact-render-to-string":"^6.3.1",tailwindcss:"^4.1.11"},optionalDependencies:{"@bitwarden/sdk-napi":"^1.0.0","@libsql/client":"^0.15.7","@tailwindcss/oxide":"^4.1.4","better-sqlite3":"^11.8.1",lightningcss:"^1.29.2","playwright-core":"^1.56.0","react-devtools-core":"^6.1.1",sharp:"^0.34.5"},devDependencies:{"@brains/app":"workspace:*","@brains/content-formatters":"workspace:*","@brains/deploy-support":"workspace:*","@brains/eslint-config":"workspace:*","@brains/mcp-service":"workspace:*","@brains/plugins":"workspace:*","@brains/ranger":"workspace:*","@brains/relay":"workspace:*","@brains/rover":"workspace:*","@brains/site-composition":"workspace:*","@brains/site-default":"workspace:*","@brains/site-personal":"workspace:*","@brains/site-professional":"workspace:*","@brains/theme-default":"workspace:*","@brains/theme-rizom":"workspace:*","@brains/typescript-config":"workspace:*","@brains/utils":"workspace:*","@types/bun":"latest",rollup:"^4.60.2","rollup-plugin-dts":"^6.4.1",typescript:"^5.3.3"},publishConfig:{access:"public"},repository:{type:"git",url:"https://github.com/rizom-ai/brains.git",directory:"packages/brain-cli"},license:"Apache-2.0",author:"Yeehaa <yeehaa@rizom.ai> (https://rizom.ai)",homepage:"https://github.com/rizom-ai/brains/tree/main/packages/brain-cli#readme",bugs:"https://github.com/rizom-ai/brains/issues",engines:{bun:">=1.3.3"},keywords:["brain","ai","cli","mcp","agent","personal-ai","knowledge-management"]};var n=e.version;export{t as defineBrain,n as PLUGIN_API_VERSION};
 
-//# debugId=26F426DFAE97DB0264756E2164756E21
+//# debugId=FF29D032C828F0A264756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -6,6 +6,6 @@
     "import packageJson from \"../package.json\" with { type: \"json\" };\n\n/**\n * Pre-v1 external plugin API marker.\n *\n * During alpha, the external plugin API compatibility marker tracks the\n * published @rizom/brain package version. Once the plugin API is declared\n * stable, this can move to an independent semver contract such as 1.0.0.\n */\nexport const PLUGIN_API_VERSION = packageJson.version;\n"
   ],
   "mappings": ";AAkEO,SAAS,CAAW,CAAC,EAA8C,CACxE,OAAO,iuFC1DF,IAAM,EAAqB,EAAY",
-  "debugId": "26F426DFAE97DB0264756E2164756E21",
+  "debugId": "FF29D032C828F0A264756E2164756E21",
   "names": []
 }

package/dist/migrations/entity-service/0002_rename_base_notes.sql

@@ -0,0 +1,3 @@
+UPDATE `entities` SET `entityType` = 'note' WHERE `entityType` = 'base';
+--> statement-breakpoint
+UPDATE `embeddings` SET `entity_type` = 'note' WHERE `entity_type` = 'base';

package/dist/migrations/entity-service/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1779171174140,
       "tag": "0001_sleepy_mandroid",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1781822400000,
+      "tag": "0002_rename_base_notes",
+      "breakpoints": true
     }
   ]
 }

package/dist/migrations/job-queue/0001_rename_base_note_jobs.sql

@@ -0,0 +1,15 @@
+UPDATE `job_queue`
+SET `type` = 'note:generation'
+WHERE `type` = 'base:generation';
+--> statement-breakpoint
+UPDATE `job_queue`
+SET `data` = replace(`data`, '"entityType":"base"', '"entityType":"note"')
+WHERE `data` LIKE '%"entityType":"base"%';
+--> statement-breakpoint
+UPDATE `job_queue`
+SET `data` = replace(`data`, '"sourceEntityType":"base"', '"sourceEntityType":"note"')
+WHERE `data` LIKE '%"sourceEntityType":"base"%';
+--> statement-breakpoint
+UPDATE `job_queue`
+SET `data` = replace(`data`, '"targetEntityType":"base"', '"targetEntityType":"note"')
+WHERE `data` LIKE '%"targetEntityType":"base"%';

package/dist/migrations/job-queue/meta/_journal.json

@@ -8,6 +8,13 @@
       "when": 1754491884445,
       "tag": "0000_famous_micromacro",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1781822400000,
+      "tag": "0001_rename_base_note_jobs",
+      "breakpoints": true
     }
   ]
-}
+}

package/dist/plugins.js.map

@@ -259,13 +259,13 @@
     "import type {\n  AnchorProfile as RuntimeAnchorProfile,\n  BrainCharacter as RuntimeBrainCharacter,\n} from \"@brains/identity-service\";\nimport {\n  AnchorProfileSchema,\n  BrainCharacterSchema,\n  type AnchorProfile,\n  type BrainCharacter,\n} from \"../contracts/identity\";\n\nexport function toPublicBrainCharacter(\n  character: RuntimeBrainCharacter,\n): BrainCharacter {\n  return BrainCharacterSchema.parse(character);\n}\n\nexport function toPublicAnchorProfile(\n  profile: RuntimeAnchorProfile,\n): AnchorProfile {\n  return AnchorProfileSchema.parse(profile);\n}\n",
     "import type { GetMessagesOptions } from \"@brains/conversation-service\";\nimport type { JobsNamespace } from \"@brains/job-queue\";\nimport {\n  createEnqueueBatchFn,\n  createEnqueueJobFn,\n  createRegisterHandlerFn,\n} from \"@brains/job-queue\";\nimport type { MessageHandler, MessageSender } from \"@brains/messaging-service\";\nimport type { Logger } from \"@brains/utils\";\nimport type { AppInfo } from \"../contracts/app-info\";\nimport type { Conversation, Message } from \"../contracts/conversations\";\nimport type { EvalHandler, InsightHandler, IShell } from \"../interfaces\";\nimport type { Channel } from \"../utils/channels\";\nimport { isChannel } from \"../utils/channels\";\nimport { toPublicAppInfo } from \"./public-app-info\";\nimport { toPublicConversation, toPublicMessage } from \"./public-conversations\";\nimport {\n  toPublicAnchorProfile,\n  toPublicBrainCharacter,\n} from \"./public-identity\";\nimport type {\n  IConversationsNamespace,\n  IEndpointsNamespace,\n  IEvalNamespace,\n  IIdentityNamespace,\n  IInsightsNamespace,\n  IInteractionsNamespace,\n  IMessagingNamespace,\n  IPermissionsNamespace,\n  TypedMessageHandler,\n} from \"./context\";\n\nexport function createAppInfoGetter(shell: IShell): () => Promise<AppInfo> {\n  return async (): Promise<AppInfo> => {\n    return toPublicAppInfo(await shell.getAppInfo());\n  };\n}\n\nexport function createIdentityNamespace(\n  shell: IShell,\n  getAppInfo: () => Promise<AppInfo>,\n): IIdentityNamespace {\n  return {\n    get: () => toPublicBrainCharacter(shell.getIdentity()),\n    getProfile: () => toPublicAnchorProfile(shell.getProfile()),\n    getAppInfo,\n  };\n}\n\nexport function createMessagingNamespace(\n  shell: IShell,\n  pluginId: string,\n  logger: Logger,\n): IMessagingNamespace {\n  const messageBus = shell.getMessageBus();\n  const sendMessage: MessageSender = async (request) => {\n    return messageBus.send({\n      ...request,\n      sender: pluginId,\n    });\n  };\n\n  return {\n    send: sendMessage,\n    subscribe: <T = unknown, R = unknown>(\n      channelOrName: string | Channel<T, R>,\n      handler: MessageHandler<T, R> | TypedMessageHandler<T, R>,\n    ): (() => void) => {\n      if (isChannel(channelOrName)) {\n        const channel = channelOrName;\n        const typedHandler = handler as TypedMessageHandler<T, R>;\n\n        const wrappedHandler: MessageHandler<unknown, R> = async (message) => {\n          const parseResult = channel.schema.safeParse(message.payload);\n          if (!parseResult.success) {\n            logger.warn(`Invalid payload for channel ${channel.name}`, {\n              error: parseResult.error.message,\n            });\n            return { noop: true };\n          }\n\n          const { payload: _payload, ...baseMessage } = message;\n          return typedHandler(parseResult.data as T, baseMessage);\n        };\n\n        return messageBus.subscribe(channel.name, wrappedHandler);\n      }\n\n      return messageBus.subscribe(\n        channelOrName,\n        handler as MessageHandler<T, R>,\n      );\n    },\n  };\n}\n\nexport function createJobsNamespace(\n  shell: IShell,\n  pluginId: string,\n): JobsNamespace {\n  const jobQueueService = shell.getJobQueueService();\n  return {\n    ...shell.jobs,\n    enqueue: createEnqueueJobFn(jobQueueService, pluginId, true),\n    enqueueBatch: createEnqueueBatchFn(shell.jobs, pluginId),\n    registerHandler: createRegisterHandlerFn(jobQueueService, pluginId),\n  };\n}\n\nexport function createPermissionsNamespace(\n  shell: IShell,\n): IPermissionsNamespace {\n  const permissionService = shell.getPermissionService();\n  return {\n    assertEntityActionAllowed: (entityType, action, context): void => {\n      permissionService.assertEntityActionAllowed(\n        entityType,\n        action,\n        context.userPermissionLevel,\n      );\n    },\n  };\n}\n\nexport function createConversationsNamespace(\n  shell: IShell,\n): IConversationsNamespace {\n  return {\n    get: async (conversationId: string): Promise<Conversation | null> => {\n      const conversationService = shell.getConversationService();\n      const conversation =\n        await conversationService.getConversation(conversationId);\n      return conversation ? toPublicConversation(conversation) : null;\n    },\n    search: async (query: string): Promise<Conversation[]> => {\n      const conversationService = shell.getConversationService();\n      const conversations =\n        await conversationService.searchConversations(query);\n      return conversations.map(toPublicConversation);\n    },\n    list: async (options): Promise<Conversation[]> => {\n      const conversationService = shell.getConversationService();\n      const conversations =\n        await conversationService.listConversations(options);\n      return conversations.map(toPublicConversation);\n    },\n    getMessages: async (\n      conversationId: string,\n      options?: GetMessagesOptions,\n    ): Promise<Message[]> => {\n      const conversationService = shell.getConversationService();\n      const messages = await conversationService.getMessages(\n        conversationId,\n        options,\n      );\n      return messages.map(toPublicMessage);\n    },\n    countMessages: async (conversationId: string): Promise<number> => {\n      return shell.getConversationService().countMessages(conversationId);\n    },\n  };\n}\n\nexport function createEvalNamespace(\n  shell: IShell,\n  pluginId: string,\n): IEvalNamespace {\n  return {\n    registerHandler: (handlerId: string, handler: EvalHandler): void => {\n      shell.registerEvalHandler(pluginId, handlerId, handler);\n    },\n  };\n}\n\nexport function createInsightsNamespace(shell: IShell): IInsightsNamespace {\n  return {\n    register: (type: string, handler: InsightHandler): void => {\n      shell.getInsightsRegistry().register(type, handler);\n    },\n  };\n}\n\nexport function createEndpointsNamespace(\n  shell: IShell,\n  pluginId: string,\n): IEndpointsNamespace {\n  return {\n    register: (endpoint): void => {\n      shell.registerEndpoint({ ...endpoint, pluginId });\n    },\n  };\n}\n\nexport function createInteractionsNamespace(\n  shell: IShell,\n  pluginId: string,\n): IInteractionsNamespace {\n  return {\n    register: (interaction): void => {\n      shell.registerInteraction({ ...interaction, pluginId });\n    },\n  };\n}\n",
     "import type { IShell } from \"../interfaces\";\nimport { type Logger } from \"@brains/utils\";\nimport { derivePreviewDomain } from \"@brains/site-composition\";\nimport type {\n  MessageHandler,\n  MessageSender,\n  MessageResponse,\n  BaseMessage,\n} from \"@brains/messaging-service\";\nimport type { Channel } from \"../utils/channels\";\nimport type { ICoreEntityService } from \"@brains/entity-service\";\nimport type { InsightHandler } from \"../interfaces\";\nimport type {\n  GetMessagesOptions,\n  ListConversationsOptions,\n} from \"@brains/conversation-service\";\nimport type { Conversation, Message } from \"../contracts/conversations\";\nimport type { AnchorProfile, BrainCharacter } from \"../contracts/identity\";\nimport type { EvalHandler, PluginRegistrationContext } from \"../interfaces\";\nimport type { AppInfo } from \"../contracts/app-info\";\nimport type { EntityAction, UserPermissionLevel } from \"@brains/templates\";\nimport type { EntityDisplayEntry } from \"@brains/site-composition\";\nimport type { JobsNamespace } from \"@brains/job-queue\";\nimport type { IRuntimeStateNamespace } from \"@brains/runtime-state\";\nimport type { IAttachmentsNamespace } from \"../service/attachment-registry\";\nimport type { IRuntimeUploadsNamespace } from \"../service/upload-registry\";\nimport {\n  createAppInfoGetter,\n  createConversationsNamespace,\n  createEndpointsNamespace,\n  createEvalNamespace,\n  createIdentityNamespace,\n  createInsightsNamespace,\n  createInteractionsNamespace,\n  createJobsNamespace,\n  createMessagingNamespace,\n  createPermissionsNamespace,\n} from \"./namespaces\";\n\n/**\n * Handler for typed channel subscriptions\n * Receives validated payload and base message metadata\n */\nexport type TypedMessageHandler<TPayload, TResponse = unknown> = (\n  payload: TPayload,\n  message: BaseMessage,\n) => Promise<MessageResponse<TResponse>> | MessageResponse<TResponse>;\n\n/**\n * Messaging namespace — inter-plugin communication\n */\nexport interface IMessagingNamespace {\n  /** Send a message to other plugins */\n  send: MessageSender;\n\n  /**\n   * Subscribe to messages on a channel\n   *\n   * @example String-based (untyped)\n   * ```typescript\n   * context.messaging.subscribe(\"my-channel\", async (message) => {\n   *   const payload = mySchema.parse(message.payload);\n   *   return { success: true };\n   * });\n   * ```\n   *\n   * @example Channel-based (typed)\n   * ```typescript\n   * const MyChannel = defineChannel(\"my-channel\", mySchema);\n   * context.messaging.subscribe(MyChannel, async (payload) => {\n   *   // payload is already validated and typed\n   *   return { success: true };\n   * });\n   * ```\n   */\n  subscribe: {\n    // String-based (existing behavior)\n    <T = unknown, R = unknown>(\n      channel: string,\n      handler: MessageHandler<T, R>,\n    ): () => void;\n\n    // Channel-based (typed, with auto-validation)\n    <TPayload, TResponse = unknown>(\n      channel: Channel<TPayload, TResponse>,\n      handler: TypedMessageHandler<TPayload, TResponse>,\n    ): () => void;\n  };\n}\n\n/**\n * Identity namespace — brain identity and profile\n */\nexport interface IIdentityNamespace {\n  /** Get the brain's character configuration */\n  get: () => BrainCharacter;\n\n  /** Get the anchor's profile */\n  getProfile: () => AnchorProfile;\n\n  /** Get app metadata (version, model, plugins) */\n  getAppInfo: () => Promise<AppInfo>;\n}\n\n/**\n * Conversations namespace — read-only access\n */\nexport interface IConversationsNamespace {\n  /** Get a conversation by ID */\n  get: (conversationId: string) => Promise<Conversation | null>;\n\n  /** Search conversations by query */\n  search: (query: string) => Promise<Conversation[]>;\n\n  /** List conversations, newest active first */\n  list: (options?: ListConversationsOptions) => Promise<Conversation[]>;\n\n  /** Get messages from a conversation */\n  getMessages: (\n    conversationId: string,\n    options?: GetMessagesOptions,\n  ) => Promise<Message[]>;\n\n  /** Count messages in a conversation without loading them */\n  countMessages: (conversationId: string) => Promise<number>;\n}\n\n/**\n * Eval namespace — cross-cutting testing concern for all plugin types\n */\nexport interface IEvalNamespace {\n  registerHandler: (handlerId: string, handler: EvalHandler) => void;\n}\n\n/**\n * Insights namespace — register domain-specific insight handlers\n */\nexport interface IInsightsNamespace {\n  /** Register a named insight handler */\n  register: (type: string, handler: InsightHandler) => void;\n}\n\nexport interface IPermissionsNamespace {\n  /** Assert that the caller can perform an entity action. */\n  assertEntityActionAllowed(\n    entityType: string,\n    action: EntityAction,\n    context: { userPermissionLevel?: UserPermissionLevel | undefined },\n  ): void;\n}\n\n/**\n * Base plugin context — shared by all plugin types (Entity, Service, Interface).\n *\n * Contains only capabilities that every plugin needs.\n * AI, templates, views, and transport are on sibling contexts.\n */\nexport interface BasePluginContext {\n  // ============================================================================\n  // Plugin Identity\n  // ============================================================================\n\n  /** Unique plugin identifier */\n  readonly pluginId: string;\n\n  /** Logger instance for this plugin */\n  readonly logger: Logger;\n\n  /** Data directory for storing entity files */\n  readonly dataDir: string;\n\n  /** Bare domain string (e.g. \"yeehaa.io\"), undefined for local dev */\n  readonly domain: string | undefined;\n\n  /** Production site URL derived from domain (e.g. \"https://yeehaa.io\"), undefined if no domain */\n  readonly siteUrl: string | undefined;\n\n  /** Local runtime site URL (e.g. \"http://localhost:8080\"), undefined when unavailable */\n  readonly localSiteUrl: string | undefined;\n\n  /** Preview site URL derived from domain (e.g. \"https://preview.yeehaa.io\" or \"https://preview.recall.rizom.ai\"), undefined if no domain */\n  readonly previewUrl: string | undefined;\n\n  /** Prefer local runtime URLs over public domain URLs when both exist. */\n  readonly preferLocalUrls: boolean;\n\n  /** Active resolved theme CSS for site, dashboard, and media rendering. */\n  readonly themeCSS: string;\n\n  /** Entity display metadata from the active site package, if any */\n  readonly entityDisplay: Record<string, EntityDisplayEntry> | undefined;\n\n  /** Shared conversation spaces for this brain/team */\n  readonly spaces: string[];\n\n  /** Entity action policy assertions for plugin-owned tools and handlers. */\n  readonly permissions: IPermissionsNamespace;\n\n  /** App metadata (version, model, plugins) */\n  readonly appInfo: () => Promise<AppInfo>;\n\n  // ============================================================================\n  // Entity Service (Read-Only)\n  // ============================================================================\n\n  /** Core entity service with read-only operations */\n  readonly entityService: ICoreEntityService;\n\n  // ============================================================================\n  // Brain Identity & Profile\n  // ============================================================================\n\n  /**\n   * Identity namespace\n   * - `identity.get()` - Get the brain's identity configuration\n   * - `identity.getProfile()` - Get the owner's profile\n   * - `identity.getAppInfo()` - Get app metadata\n   */\n  readonly identity: IIdentityNamespace;\n\n  // ============================================================================\n  // Inter-Plugin Messaging\n  // ============================================================================\n\n  /**\n   * Messaging namespace\n   * - `messaging.send()` - Send a message to other plugins\n   * - `messaging.subscribe()` - Subscribe to messages on a channel\n   */\n  readonly messaging: IMessagingNamespace;\n\n  // ============================================================================\n  // Job Queue (monitoring + scoped write)\n  // ============================================================================\n\n  /** Job operations — monitoring + plugin-scoped enqueue/registerHandler */\n  readonly jobs: JobsNamespace;\n\n  // ============================================================================\n  // Source-derived Attachments\n  // ============================================================================\n\n  /** Source-derived publish attachment resolution namespace */\n  readonly attachments: IAttachmentsNamespace;\n\n  // ============================================================================\n  // Runtime Uploads\n  // ============================================================================\n\n  /** Ephemeral runtime upload storage namespace. */\n  readonly uploads: IRuntimeUploadsNamespace;\n\n  // ============================================================================\n  // Runtime State\n  // ============================================================================\n\n  /** Disposable, secret-free operational state namespace. */\n  readonly runtimeState: IRuntimeStateNamespace;\n\n  // ============================================================================\n  // Conversations (Read-Only)\n  // ============================================================================\n\n  /**\n   * Conversations namespace\n   * - `conversations.get()` - Get a conversation by ID\n   * - `conversations.search()` - Search conversations by query\n   * - `conversations.getMessages()` - Get messages from a conversation\n   */\n  readonly conversations: IConversationsNamespace;\n\n  // ============================================================================\n  // Evaluation\n  // ============================================================================\n\n  /**\n   * Eval namespace for plugin testing\n   * - `eval.registerHandler()` - Register an eval handler\n   */\n  readonly eval: IEvalNamespace;\n\n  // ============================================================================\n  // Insights\n  // ============================================================================\n\n  /**\n   * Insights namespace\n   * - `insights.register()` - Register a domain-specific insight handler\n   */\n  readonly insights: IInsightsNamespace;\n\n  // ============================================================================\n  // Endpoint Advertisement\n  // ============================================================================\n\n  /**\n   * Endpoints namespace — advertise this plugin's user-facing URLs\n   * so they surface in `appInfo.endpoints` for the dashboard and\n   * other operator-facing consumers.\n   */\n  readonly endpoints: IEndpointsNamespace;\n\n  /**\n   * Interactions namespace — advertise user/agent entry points for this brain.\n   */\n  readonly interactions: IInteractionsNamespace;\n}\n\nexport interface IEndpointsNamespace {\n  /** Register a user-facing URL for this plugin */\n  register(endpoint: {\n    label: string;\n    url: string;\n    priority?: number;\n    visibility?: UserPermissionLevel;\n  }): void;\n}\n\nexport interface IInteractionsNamespace {\n  /** Register a user or agent-facing way to interact with this brain */\n  register(interaction: {\n    id: string;\n    label: string;\n    description?: string;\n    href: string;\n    kind: \"human\" | \"agent\" | \"admin\" | \"protocol\";\n    priority?: number;\n    visibility?: UserPermissionLevel;\n    status?: \"available\" | \"coming-soon\" | \"disabled\";\n  }): void;\n}\n\n/**\n * Create a BasePluginContext from the shell.\n *\n * Used by all three sibling context factories (entity, service, interface).\n */\nexport function createBasePluginContext(\n  shell: IShell,\n  pluginId: string,\n  registrationContext?: PluginRegistrationContext,\n): BasePluginContext {\n  const entityService = shell.getEntityService();\n  const logger = shell.getLogger().child(pluginId);\n  const domain = shell.getDomain();\n  const localSiteUrl = shell.getLocalSiteUrl();\n  const preferLocalUrls = shell.shouldPreferLocalUrls();\n  const themeCSS = shell.getThemeCSS();\n  const getAppInfo = createAppInfoGetter(shell);\n  const attachments = shell.getAttachmentRegistry();\n  const uploads = shell.getRuntimeUploadRegistry();\n  const runtimeState = shell.getRuntimeState();\n\n  return {\n    pluginId,\n    logger,\n    entityService,\n\n    identity: createIdentityNamespace(shell, getAppInfo),\n\n    appInfo: getAppInfo,\n\n    domain,\n    siteUrl: domain ? `https://${domain}` : undefined,\n    localSiteUrl,\n    previewUrl: domain ? `https://${derivePreviewDomain(domain)}` : undefined,\n    preferLocalUrls,\n    themeCSS,\n    entityDisplay: registrationContext?.entityDisplay,\n    spaces: shell.getSpaces(),\n\n    permissions: createPermissionsNamespace(shell),\n\n    messaging: createMessagingNamespace(shell, pluginId, logger),\n\n    jobs: createJobsNamespace(shell, pluginId),\n\n    attachments,\n\n    uploads,\n\n    runtimeState,\n\n    conversations: createConversationsNamespace(shell),\n\n    dataDir: shell.getDataDir(),\n\n    eval: createEvalNamespace(shell, pluginId),\n\n    insights: createInsightsNamespace(shell),\n\n    endpoints: createEndpointsNamespace(shell, pluginId),\n    interactions: createInteractionsNamespace(shell, pluginId),\n  };\n}\n",
-    "import { createClient, type Client } from \"@libsql/client\";\nimport { drizzle } from \"drizzle-orm/libsql\";\nimport type { LibSQLDatabase } from \"drizzle-orm/libsql\";\nimport { entities } from \"../schema/entities\";\nimport type { EntityDbConfig } from \"../types\";\n\nexport type EntityDB = LibSQLDatabase<Record<string, unknown>>;\n\n/**\n * Create an entity database connection\n * Config is now required - use createShellServiceConfig() for standard paths\n */\nexport function createEntityDatabase(config: EntityDbConfig): {\n  db: EntityDB;\n  client: Client;\n  url: string;\n} {\n  const url = config.url;\n  const authToken = config.authToken ?? process.env[\"DATABASE_AUTH_TOKEN\"];\n\n  const client = authToken\n    ? createClient({ url, authToken })\n    : createClient({ url });\n\n  const db = drizzle(client, { schema: { entities } });\n\n  return { db, client, url };\n}\n\n/**\n * Enable WAL mode and set busy timeout for better concurrent access\n * This should be called during initialization\n */\nexport async function enableWALModeForEntities(\n  client: Client,\n  url: string,\n): Promise<void> {\n  // Only enable WAL mode and busy timeout for local SQLite files\n  if (url.startsWith(\"file:\")) {\n    await client.execute(\"PRAGMA journal_mode = WAL\");\n    // Set busy timeout to 5 seconds - SQLite will wait instead of returning SQLITE_BUSY\n    await client.execute(\"PRAGMA busy_timeout = 5000\");\n  }\n}\n\n/**\n * Create FTS5 virtual table for full-text keyword search on entity content.\n * Called during entity DB initialization alongside WAL mode setup.\n */\nexport async function ensureFtsTable(client: Client): Promise<void> {\n  await client.execute(`\n    CREATE VIRTUAL TABLE IF NOT EXISTS entity_fts USING fts5(\n      entity_id UNINDEXED,\n      entity_type UNINDEXED,\n      content\n    )\n  `);\n}\n\n/**\n * Type for the entity database\n */\nexport type EntityDatabase = ReturnType<typeof createEntityDatabase>;\n",
+    "import { createClient, type Client } from \"@libsql/client\";\nimport { drizzle } from \"drizzle-orm/libsql\";\nimport type { LibSQLDatabase } from \"drizzle-orm/libsql\";\nimport { entities } from \"../schema/entities\";\nimport type { EntityDbConfig } from \"../types\";\n\nexport type EntityDB = LibSQLDatabase<Record<string, unknown>>;\n\n/**\n * Create an entity database connection\n * Config is now required - use createShellServiceConfig() for standard paths\n */\nexport function createEntityDatabase(config: EntityDbConfig): {\n  db: EntityDB;\n  client: Client;\n  url: string;\n} {\n  const url = config.url;\n  const authToken = config.authToken ?? process.env[\"DATABASE_AUTH_TOKEN\"];\n\n  const client = authToken\n    ? createClient({ url, authToken })\n    : createClient({ url });\n\n  const db = drizzle(client, { schema: { entities } });\n\n  return { db, client, url };\n}\n\n/**\n * Enable WAL mode and set busy timeout for better concurrent access\n * This should be called during initialization\n */\nexport async function enableWALModeForEntities(\n  client: Client,\n  url: string,\n): Promise<void> {\n  // Only enable WAL mode and busy timeout for local SQLite files\n  if (url.startsWith(\"file:\")) {\n    await client.execute(\"PRAGMA journal_mode = WAL\");\n    // Set busy timeout to 5 seconds - SQLite will wait instead of returning SQLITE_BUSY\n    await client.execute(\"PRAGMA busy_timeout = 5000\");\n  }\n}\n\n/**\n * Create FTS5 virtual table for full-text keyword search on entity content.\n * Called during entity DB initialization alongside WAL mode setup.\n */\nexport async function ensureFtsTable(client: Client): Promise<void> {\n  await client.execute(`\n    CREATE VIRTUAL TABLE IF NOT EXISTS entity_fts USING fts5(\n      entity_id UNINDEXED,\n      entity_type UNINDEXED,\n      content\n    )\n  `);\n  await client.execute(\n    \"UPDATE entity_fts SET entity_type = 'note' WHERE entity_type = 'base'\",\n  );\n}\n\n/**\n * Type for the entity database\n */\nexport type EntityDatabase = ReturnType<typeof createEntityDatabase>;\n",
     "import { sql } from \"drizzle-orm\";\nimport {\n  sqliteTable,\n  text,\n  integer,\n  primaryKey,\n  check,\n} from \"drizzle-orm/sqlite-core\";\n\n/**\n * Main entities table for entity data\n * Embeddings are stored separately in the embeddings table\n * to allow immediate entity persistence while embeddings are generated async\n */\nexport const entities = sqliteTable(\n  \"entities\",\n  {\n    // Core fields\n    id: text(\"id\").notNull(),\n    entityType: text(\"entityType\").notNull(),\n\n    // Content with frontmatter\n    content: text(\"content\").notNull(),\n\n    // Content hash for change detection (SHA256 hex)\n    // Used by plugins to detect if content has changed without comparing full text\n    contentHash: text(\"contentHash\").notNull(),\n\n    // Visibility boundary for read/search/derivation policies\n    visibility: text(\"visibility\", {\n      enum: [\"public\", \"shared\", \"restricted\"],\n    })\n      .notNull()\n      .default(\"public\"),\n\n    // Metadata from frontmatter (includes title, tags, and entity-specific fields)\n    metadata: text(\"metadata\", { mode: \"json\" })\n      .$type<Record<string, unknown>>()\n      .notNull()\n      .default(sql`'{}'`),\n\n    // Timestamps (stored as Unix milliseconds for consistency)\n    created: integer(\"created\")\n      .notNull()\n      .$defaultFn(() => Date.now()),\n    updated: integer(\"updated\")\n      .notNull()\n      .$defaultFn(() => Date.now()),\n\n    // NOTE: embedding column has been moved to separate 'embeddings' table\n    // This allows entities to be persisted immediately while embeddings\n    // are generated asynchronously in background jobs\n  },\n  (table) => {\n    return {\n      // Composite primary key on id + entityType\n      pk: primaryKey({ columns: [table.id, table.entityType] }),\n      visibilityCheck: check(\n        \"entities_visibility_check\",\n        sql`${table.visibility} IN ('public', 'shared', 'restricted')`,\n      ),\n    };\n  },\n);\n\n/**\n * Type exports\n * Using drizzle's built-in type inference instead of z.infer due to compatibility issues\n */\nexport type InsertEntity = typeof entities.$inferInsert;\nexport type Entity = typeof entities.$inferSelect;\n",
-    "import { createClient, type Client } from \"@libsql/client\";\nimport { drizzle } from \"drizzle-orm/libsql\";\nimport type { LibSQLDatabase } from \"drizzle-orm/libsql\";\nimport { embeddings } from \"../schema/embeddings\";\nimport type { EntityDbConfig } from \"../types\";\n\nexport type EmbeddingDB = LibSQLDatabase<Record<string, unknown>>;\n\n/**\n * Create an embedding database connection.\n * This is a separate database from the entity database,\n * containing only the embeddings table.\n */\nexport function createEmbeddingDatabase(config: EntityDbConfig): {\n  db: EmbeddingDB;\n  client: Client;\n  url: string;\n} {\n  const url = config.url;\n  const authToken = config.authToken ?? process.env[\"DATABASE_AUTH_TOKEN\"];\n\n  const client = authToken\n    ? createClient({ url, authToken })\n    : createClient({ url });\n\n  const db = drizzle(client, { schema: { embeddings } });\n\n  return { db, client, url };\n}\n\n/**\n * Enable WAL mode for the embedding database\n */\nexport async function enableWALModeForEmbeddings(\n  client: Client,\n  url: string,\n): Promise<void> {\n  if (url.startsWith(\"file:\")) {\n    await client.execute(\"PRAGMA journal_mode = WAL\");\n    await client.execute(\"PRAGMA busy_timeout = 5000\");\n  }\n}\n\n/**\n * Create the embeddings table in the embedding database.\n * Dimensions come from the embedding provider (e.g. 1536 for OpenAI text-embedding-3-small).\n */\nexport async function migrateEmbeddingDatabase(\n  client: Client,\n  dimensions: number,\n): Promise<void> {\n  await client.execute(`\n    CREATE TABLE IF NOT EXISTS embeddings (\n      entity_id TEXT NOT NULL,\n      entity_type TEXT NOT NULL,\n      embedding F32_BLOB(${dimensions}) NOT NULL,\n      content_hash TEXT NOT NULL,\n      PRIMARY KEY(entity_id, entity_type)\n    )\n  `);\n}\n\n/**\n * Ensure vector index exists on the embedding database\n */\nexport async function ensureEmbeddingIndexes(client: Client): Promise<void> {\n  await client.execute(`\n    CREATE INDEX IF NOT EXISTS embeddings_embedding_idx\n    ON embeddings(libsql_vector_idx(embedding))\n  `);\n}\n\n/**\n * Attach the embedding database to an entity database client.\n * This enables cross-database joins for search queries.\n *\n * @param entityClient - The libsql client connected to the entity database\n * @param embeddingDbPath - File path (without file: prefix) to the embedding database\n */\nexport async function attachEmbeddingDatabase(\n  entityClient: Client,\n  embeddingDbPath: string,\n): Promise<void> {\n  await entityClient.execute(`ATTACH DATABASE '${embeddingDbPath}' AS emb`);\n}\n\n/**\n * Extract the file path from a database URL.\n * Strips the \"file:\" prefix.\n */\nexport function dbUrlToPath(url: string): string {\n  return url.startsWith(\"file:\") ? url.slice(5) : url;\n}\n",
+    "import { createClient, type Client } from \"@libsql/client\";\nimport { drizzle } from \"drizzle-orm/libsql\";\nimport type { LibSQLDatabase } from \"drizzle-orm/libsql\";\nimport { embeddings } from \"../schema/embeddings\";\nimport type { EntityDbConfig } from \"../types\";\n\nexport type EmbeddingDB = LibSQLDatabase<Record<string, unknown>>;\n\n/**\n * Create an embedding database connection.\n * This is a separate database from the entity database,\n * containing only the embeddings table.\n */\nexport function createEmbeddingDatabase(config: EntityDbConfig): {\n  db: EmbeddingDB;\n  client: Client;\n  url: string;\n} {\n  const url = config.url;\n  const authToken = config.authToken ?? process.env[\"DATABASE_AUTH_TOKEN\"];\n\n  const client = authToken\n    ? createClient({ url, authToken })\n    : createClient({ url });\n\n  const db = drizzle(client, { schema: { embeddings } });\n\n  return { db, client, url };\n}\n\n/**\n * Enable WAL mode for the embedding database\n */\nexport async function enableWALModeForEmbeddings(\n  client: Client,\n  url: string,\n): Promise<void> {\n  if (url.startsWith(\"file:\")) {\n    await client.execute(\"PRAGMA journal_mode = WAL\");\n    await client.execute(\"PRAGMA busy_timeout = 5000\");\n  }\n}\n\n/**\n * Create the embeddings table in the embedding database.\n * Dimensions come from the embedding provider (e.g. 1536 for OpenAI text-embedding-3-small).\n */\nexport async function migrateEmbeddingDatabase(\n  client: Client,\n  dimensions: number,\n): Promise<void> {\n  await client.execute(`\n    CREATE TABLE IF NOT EXISTS embeddings (\n      entity_id TEXT NOT NULL,\n      entity_type TEXT NOT NULL,\n      embedding F32_BLOB(${dimensions}) NOT NULL,\n      content_hash TEXT NOT NULL,\n      PRIMARY KEY(entity_id, entity_type)\n    )\n  `);\n  await client.execute(\n    \"UPDATE embeddings SET entity_type = 'note' WHERE entity_type = 'base'\",\n  );\n}\n\n/**\n * Ensure vector index exists on the embedding database\n */\nexport async function ensureEmbeddingIndexes(client: Client): Promise<void> {\n  await client.execute(`\n    CREATE INDEX IF NOT EXISTS embeddings_embedding_idx\n    ON embeddings(libsql_vector_idx(embedding))\n  `);\n}\n\n/**\n * Attach the embedding database to an entity database client.\n * This enables cross-database joins for search queries.\n *\n * @param entityClient - The libsql client connected to the entity database\n * @param embeddingDbPath - File path (without file: prefix) to the embedding database\n */\nexport async function attachEmbeddingDatabase(\n  entityClient: Client,\n  embeddingDbPath: string,\n): Promise<void> {\n  await entityClient.execute(`ATTACH DATABASE '${embeddingDbPath}' AS emb`);\n}\n\n/**\n * Extract the file path from a database URL.\n * Strips the \"file:\" prefix.\n */\nexport function dbUrlToPath(url: string): string {\n  return url.startsWith(\"file:\") ? url.slice(5) : url;\n}\n",
     "import { customType } from \"drizzle-orm/sqlite-core\";\n\n/**\n * Custom type for libSQL vector columns.\n * This allows us to use F32_BLOB in libSQL while maintaining Drizzle compatibility.\n *\n * Note: This schema is only used for the entity DB's Drizzle migration (legacy).\n * The actual embedding DB uses raw SQL with provider-supplied dimensions.\n * The dimension here must match the Drizzle migration SQL but does not\n * constrain the embedding DB.\n */\nexport const vector = customType<{\n  data: Float32Array;\n  driverData: Buffer;\n}>({\n  dataType() {\n    return \"F32_BLOB(1536)\";\n  },\n  toDriver(value: Float32Array): Buffer {\n    return Buffer.from(value.buffer);\n  },\n  fromDriver(value: Buffer): Float32Array {\n    return new Float32Array(\n      value.buffer,\n      value.byteOffset,\n      value.byteLength / 4,\n    );\n  },\n});\n",
     "import { text, primaryKey, sqliteTable } from \"drizzle-orm/sqlite-core\";\nimport { vector } from \"./vector\";\n\n/**\n * Embeddings table for vector search\n * Separated from entities to allow immediate entity persistence\n * while embeddings are generated asynchronously\n */\nexport const embeddings = sqliteTable(\n  \"embeddings\",\n  {\n    // Foreign key to entities (composite: id + entityType)\n    entityId: text(\"entity_id\").notNull(),\n    entityType: text(\"entity_type\").notNull(),\n\n    // Vector embedding for semantic search\n    // NOTE: This column has a vector index created via ensureEmbeddingIndexes():\n    // CREATE INDEX embeddings_idx ON embeddings(libsql_vector_idx(embedding))\n    embedding: vector(\"embedding\").notNull(),\n\n    // Content hash to detect stale embeddings\n    // If entity.contentHash != embedding.contentHash, embedding is stale\n    contentHash: text(\"content_hash\").notNull(),\n  },\n  (table) => {\n    return {\n      // Composite primary key on entityId + entityType\n      pk: primaryKey({ columns: [table.entityId, table.entityType] }),\n    };\n  },\n);\n\n/**\n * Type exports\n */\nexport type InsertEmbedding = typeof embeddings.$inferInsert;\nexport type Embedding = typeof embeddings.$inferSelect;\n",
     "import { z } from \"@brains/utils\";\n\nconst canonicalContentVisibilitySchema = z.enum([\n  \"public\",\n  \"shared\",\n  \"restricted\",\n]);\n\nexport type ContentVisibility = z.infer<\n  typeof canonicalContentVisibilitySchema\n>;\nexport type RawContentVisibility = ContentVisibility | \"private\";\n\nexport const contentVisibilitySchema = z\n  .union([canonicalContentVisibilitySchema, z.literal(\"private\")])\n  .optional()\n  .transform((value): ContentVisibility => {\n    if (value === undefined) return \"public\";\n    if (value === \"private\") return \"restricted\";\n    return value;\n  });\n\nexport function normalizeContentVisibility(\n  visibility: RawContentVisibility | undefined,\n): ContentVisibility {\n  return contentVisibilitySchema.parse(visibility);\n}\n\nconst visibleContentVisibilitiesByScope: Record<\n  ContentVisibility,\n  ContentVisibility[]\n> = {\n  public: [\"public\"],\n  shared: [\"public\", \"shared\"],\n  restricted: [\"public\", \"shared\", \"restricted\"],\n};\n\nexport function getVisibleContentVisibilities(\n  scope: ContentVisibility,\n): ContentVisibility[] {\n  return visibleContentVisibilitiesByScope[scope];\n}\n\nexport function isVisibleWithinScope(\n  visibility: ContentVisibility | undefined,\n  scope: ContentVisibility,\n): boolean {\n  return getVisibleContentVisibilities(scope).includes(visibility ?? \"public\");\n}\n\n/**\n * Map a caller's permission level to the content-visibility scope they may see.\n * public  → public         (only public content)\n * trusted → shared         (public + shared)\n * anchor  → restricted     (public + shared + restricted)\n *\n * Defaults to \"public\" when no permission level is provided, so missing\n * context fails closed.\n */\nexport function permissionToVisibilityScope(\n  level: \"anchor\" | \"trusted\" | \"public\" | undefined,\n): ContentVisibility {\n  if (level === \"anchor\") return \"restricted\";\n  if (level === \"trusted\") return \"shared\";\n  return \"public\";\n}\n\n/**\n * Whether a caller at `level` is allowed to author or update an entity at\n * `visibility`. A user may only write content at a visibility they themselves\n * can read — otherwise they could ghost-write content into a higher trust\n * level than their permission, which is a write-side escalation vector.\n *\n *  public  → may write \"public\"\n *  trusted → may write \"public\" | \"shared\"\n *  anchor  → may write \"public\" | \"shared\" | \"restricted\"\n */\nexport function canWriteVisibility(\n  level: \"anchor\" | \"trusted\" | \"public\" | undefined,\n  visibility: ContentVisibility,\n): boolean {\n  return isVisibleWithinScope(visibility, permissionToVisibilityScope(level));\n}\n",
-    "import { z } from \"@brains/utils\";\nimport type { DataSource } from \"./datasource-types\";\nimport {\n  contentVisibilitySchema,\n  type ContentVisibility,\n  type RawContentVisibility,\n} from \"./visibility\";\n\n/**\n * Entity type for unstructured notes (the \"base\" entity type).\n * Used as a sentinel for the default catch-all markdown file shape —\n * no typed frontmatter schema required, content is the entire file body.\n */\nexport const BASE_ENTITY_TYPE = \"base\";\n\n/**\n * Embedding job data - minimal data for job queue\n * Content is NOT stored to avoid large base64 data in job queue\n * (which would end up in dashboard hydration props JSON)\n * Handler fetches fresh content from entity when processing\n */\nexport interface EmbeddingJobData {\n  id: string;\n  entityType: string;\n  /** Hash of content at job creation time - for staleness detection */\n  contentHash: string;\n  operation: \"create\" | \"update\";\n}\n\n/**\n * Options for entity mutation operations (create, update, upsert)\n */\nexport interface EntityJobOptions {\n  priority?: number;\n  maxRetries?: number;\n}\n\nexport {\n  contentVisibilitySchema,\n  normalizeContentVisibility,\n  getVisibleContentVisibilities,\n  isVisibleWithinScope,\n  permissionToVisibilityScope,\n  canWriteVisibility,\n} from \"./visibility\";\nexport type { ContentVisibility, RawContentVisibility } from \"./visibility\";\n\n/**\n * Options for entity creation (extends EntityJobOptions with deduplication)\n */\nexport interface CreateEntityOptions extends EntityJobOptions {\n  deduplicateId?: boolean;\n}\n\n/**\n * Result of an entity mutation that triggers an embedding job.\n * When skipped is true, content was unchanged — no DB write, no event, no embedding job.\n */\nexport interface EntityMutationResult {\n  entityId: string;\n  jobId: string;\n  skipped: boolean;\n}\n\n/**\n * Input for adapter-validated direct creation from finalized markdown.\n */\nexport interface CreateEntityFromMarkdownInput {\n  entityType: string;\n  id: string;\n  markdown: string;\n}\n\n/**\n * Data for storing an embedding for an entity\n */\nexport interface StoreEmbeddingData {\n  entityId: string;\n  entityType: string;\n  embedding: Float32Array;\n  contentHash: string;\n}\n\n/**\n * Base entity schema that all entities must extend\n */\nexport const baseEntitySchema = z.object({\n  id: z.string(),\n  entityType: z.string(),\n  content: z.string(),\n  created: z.string().datetime(),\n  updated: z.string().datetime(),\n  visibility: contentVisibilitySchema,\n  metadata: z.record(z.string(), z.unknown()),\n  contentHash: z.string(),\n});\n\n/**\n * Base entity type - generic to support typed metadata\n * TMetadata defaults to Record<string, unknown> for backward compatibility\n */\nexport interface BaseEntity<TMetadata = Record<string, unknown>> {\n  id: string;\n  entityType: string;\n  content: string;\n  created: string;\n  updated: string;\n  visibility: ContentVisibility;\n  metadata: TMetadata;\n  /** SHA256 hash of content for change detection */\n  contentHash: string;\n}\n\n/**\n * Entity input type for creation - allows partial entities with optional system fields\n * contentHash is excluded because it's computed automatically by the entity service\n */\nexport type EntityInput<T extends BaseEntity> = Omit<\n  T,\n  \"id\" | \"created\" | \"updated\" | \"contentHash\" | \"visibility\"\n> & {\n  id?: string;\n  created?: string;\n  updated?: string;\n  visibility?: RawContentVisibility;\n};\n\n/**\n * Search result type\n */\nexport interface SearchResult<T extends BaseEntity = BaseEntity> {\n  entity: T;\n  score: number;\n  excerpt: string;\n}\n\n/**\n * Normalized system_create input shape used by plugin create interceptors.\n */\nexport interface CreateCoverImageInput {\n  generate?: boolean | undefined;\n  prompt?: string | undefined;\n}\n\nexport interface CreateFromAttachmentInput {\n  kind: \"entity-attachment\";\n  sourceEntityType: string;\n  sourceEntityId: string;\n  attachmentType: string;\n}\n\nexport interface CreateFromUploadInput {\n  kind: \"upload\";\n  id: string;\n}\n\nexport type CreateFromInput = CreateFromAttachmentInput | CreateFromUploadInput;\n\nexport type CreateTransform = \"extract-markdown\";\n\nexport interface CreateInput {\n  entityType: string;\n  prompt?: string;\n  title?: string;\n  content?: string;\n  url?: string;\n  from?: CreateFromInput;\n  transform?: CreateTransform;\n  replace?: boolean;\n  targetEntityType?: string;\n  targetEntityId?: string;\n  coverImage?: boolean | CreateCoverImageInput;\n}\n\n/**\n * Minimal caller context forwarded to plugin create interceptors.\n */\nexport interface CreateExecutionContext {\n  interfaceType: string;\n  userId: string;\n  channelId?: string;\n  channelName?: string;\n}\n\n/**\n * Result returned to system_create when a plugin fully handles creation.\n */\nexport const createResultAttachmentSchema = z.object({\n  mediaType: z.string(),\n  url: z.string(),\n  downloadUrl: z.string().optional(),\n  previewUrl: z.string().optional(),\n  filename: z.string().optional(),\n  sizeBytes: z.number().optional(),\n  source: z\n    .object({\n      entityType: z.string().optional(),\n      entityId: z.string().optional(),\n      attachmentType: z.string().optional(),\n    })\n    .optional(),\n});\n\nexport type CreateResultAttachment = z.infer<\n  typeof createResultAttachmentSchema\n>;\n\nexport type CreateResult =\n  | {\n      success: true;\n      data: {\n        entityId?: string;\n        jobId?: string;\n        status: string;\n        attachment?: CreateResultAttachment;\n      };\n    }\n  | { success: false; error: string };\n\n/**\n * Plugin create interceptors can either fully handle creation,\n * or continue with a rewritten normalized input.\n */\nexport type CreateInterceptionResult =\n  | { kind: \"handled\"; result: CreateResult }\n  | { kind: \"continue\"; input: CreateInput };\n\nexport type CreateInterceptor = (\n  input: CreateInput,\n  executionContext: CreateExecutionContext,\n) => Promise<CreateInterceptionResult>;\n\nexport interface UploadSaveInput {\n  upload: CreateFromUploadInput;\n  title?: string;\n}\n\nexport type UploadSaveHandler = (\n  input: UploadSaveInput,\n  executionContext: CreateExecutionContext,\n) => Promise<CreateResult>;\n\nexport interface UploadSaveHandlerRegistration {\n  entityType: string;\n  mediaTypes: string[];\n  handler: UploadSaveHandler;\n}\n\n/**\n * Called before an entity is persisted (on create or update). Throws to reject\n * the write with an operator-facing error. Use this for cross-entity invariants\n * the per-entity Zod schema cannot express.\n */\nexport type PersistValidator<T extends BaseEntity = BaseEntity> = (\n  entity: T,\n  context: { operation: \"create\" | \"update\" },\n) => Promise<void>;\n\n/**\n * Minimal event bus contract used by entity-service for lifecycle events.\n * Kept structural to avoid coupling this package to a concrete messaging service.\n */\nexport interface EntityEventBus {\n  send(request: {\n    type: string;\n    payload: Record<string, unknown>;\n    sender: string;\n    target?: string;\n    metadata?: Record<string, unknown>;\n    broadcast?: boolean;\n  }): Promise<unknown>;\n}\n\n/**\n * Interface for entity adapter - handles conversion between entities and markdown\n * following the hybrid storage model\n *\n * @template TEntity - The full entity type\n * @template TMetadata - The metadata type (defaults to Record<string, unknown>)\n */\nexport interface EntityAdapter<\n  TEntity extends BaseEntity<TMetadata>,\n  TMetadata = Record<string, unknown>,\n> {\n  entityType: string;\n  schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>;\n\n  // Convert entity to markdown content (may include frontmatter for entity-specific fields)\n  toMarkdown(entity: TEntity): string;\n\n  // Extract entity-specific fields from markdown\n  // Returns Partial<TEntity> as core fields come from database\n  fromMarkdown(markdown: string): Partial<TEntity>;\n\n  // Extract metadata from entity for search/filtering - now strongly typed\n  extractMetadata(entity: TEntity): TMetadata;\n\n  // Parse frontmatter metadata from markdown\n  parseFrontMatter<TFrontmatter>(\n    markdown: string,\n    schema: z.ZodSchema<TFrontmatter>,\n  ): TFrontmatter;\n\n  // Generate frontmatter for markdown\n  generateFrontMatter(entity: TEntity): string;\n\n  /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */\n  frontmatterSchema?: z.ZodObject<z.ZodRawShape>;\n\n  /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */\n  isSingleton?: boolean;\n\n  /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */\n  hasBody?: boolean;\n\n  /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */\n  getBodyTemplate(): string;\n\n  /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */\n  supportsCoverImage?: boolean;\n\n  /** Optional: Extract coverImageId from entity content/frontmatter */\n  getCoverImageId?(entity: TEntity): string | undefined;\n\n  /**\n   * Optional: build the markdown content and metadata for a queued-generation stub.\n   * When undefined, this entity type does not support prompt-based queued creation\n   * via system_create; the tool will reject the call rather than silently degrade.\n   * The returned metadata must satisfy this entity's metadata schema (with\n   * status set to \"generating\"); central code only stamps id/timestamps/visibility.\n   */\n  buildStub?(input: { id: string; title: string }): {\n    content: string;\n    metadata: TMetadata;\n  };\n}\n\n/**\n * Sort field specification for multi-field sorting\n */\nexport interface SortField {\n  /** Field to sort by - \"created\", \"updated\", or a metadata field name */\n  field: string;\n  /** Sort direction */\n  direction: \"asc\" | \"desc\";\n  /** Sort NULL values before non-NULL values (default: false / SQLite default) */\n  nullsFirst?: boolean;\n}\n\n/**\n * List entities options\n * Generic over metadata type for type-safe filtering\n */\nexport interface ListOptions<TMetadata = Record<string, unknown>> {\n  limit?: number;\n  offset?: number;\n  /** Multi-field sorting - supports system fields (created, updated) and metadata fields */\n  sortFields?: SortField[];\n  filter?: {\n    // Typed metadata filter - partial match on metadata fields\n    metadata?: Partial<TMetadata>;\n    visibilityScope?: ContentVisibility;\n  };\n  /** Filter to only entities with metadata.status = \"published\" */\n  publishedOnly?: boolean;\n}\n\n/**\n * Search options\n */\nexport interface SearchOptions {\n  limit?: number;\n  offset?: number;\n  types?: string[];\n  excludeTypes?: string[];\n  sortBy?: \"relevance\" | \"created\" | \"updated\";\n  sortDirection?: \"asc\" | \"desc\";\n  /** Score multipliers per entity type - applied after initial search */\n  weight?: Record<string, number>;\n  visibilityScope?: ContentVisibility;\n  /** Include queued/failed generation stubs in search results (default: false) */\n  includeUngenerated?: boolean;\n}\n\n/**\n * Configuration for entity type registration\n */\nexport interface EntityTypeConfig {\n  /** Score multiplier for search results (default: 1.0) */\n  weight?: number;\n  /** Whether to generate embeddings for this entity type (default: true).\n   *  Set to false for entity types with non-textual content (e.g., images). */\n  embeddable?: boolean;\n  /** Whether this entity type may be used as source material for derived projections (default: true).\n   *  Set to false for projection outputs that would create feedback loops. */\n  projectionSource?: boolean;\n  /** Publish semantics for status-bearing entity types. Statuses listed here\n   *  represent publication commitment/execution states and require the\n   *  `publish` entity action when entered or modified. */\n  publish?: {\n    publishStatuses: string[];\n  };\n}\n\n/**\n * Core entity service interface for read-only operations\n * Used by core plugins that need entity access but shouldn't modify entities\n */\nexport interface GetEntityRequest {\n  entityType: string;\n  id: string;\n  /**\n   * Optional visibility scope. Undefined fails closed to \"public\" — callers\n   * with elevated access must opt up explicitly.\n   */\n  visibilityScope?: ContentVisibility;\n}\n\nexport type GetEntityRawRequest = GetEntityRequest;\n\nexport interface ListEntitiesRequest {\n  entityType: string;\n  options?: ListOptions | undefined;\n}\n\nexport interface CountEntitiesRequest {\n  entityType: string;\n  options?: Pick<ListOptions, \"publishedOnly\" | \"filter\"> | undefined;\n}\n\nexport interface CreateEntityRequest<T extends BaseEntity> {\n  entity: EntityInput<T>;\n  options?: CreateEntityOptions | undefined;\n}\n\nexport interface CreateEntityFromMarkdownRequest {\n  input: CreateEntityFromMarkdownInput;\n  options?: CreateEntityOptions | undefined;\n}\n\nexport interface UpdateEntityRequest<T extends BaseEntity> {\n  entity: T;\n  options?: EntityJobOptions | undefined;\n}\n\nexport interface DeleteEntityRequest {\n  entityType: string;\n  id: string;\n}\n\nexport interface UpsertEntityRequest<T extends BaseEntity> {\n  entity: T;\n  options?: EntityJobOptions | undefined;\n}\n\nexport interface EntitySearchRequest {\n  query: string;\n  options?: SearchOptions | undefined;\n}\n\nexport interface SearchWithDistancesRequest {\n  query: string;\n}\n\nexport interface ICoreEntityService {\n  // Read-only operations\n  getEntity<T extends BaseEntity>(request: GetEntityRequest): Promise<T | null>;\n\n  /**\n   * Get entity without content resolution (raw)\n   * Used internally to avoid recursion when resolving image references\n   */\n  getEntityRaw<T extends BaseEntity>(\n    request: GetEntityRawRequest,\n  ): Promise<T | null>;\n\n  listEntities<T extends BaseEntity>(\n    request: ListEntitiesRequest,\n  ): Promise<T[]>;\n\n  search<T extends BaseEntity = BaseEntity>(\n    request: EntitySearchRequest,\n  ): Promise<SearchResult<T>[]>;\n\n  // Entity type information\n  getEntityTypes(): string[];\n  hasEntityType(type: string): boolean;\n\n  // Entity counts\n  countEntities(request: CountEntitiesRequest): Promise<number>;\n  /**\n   * Group counts by entity type. Fails closed: undefined visibilityScope\n   * filters to public-only counts so aggregate insights cannot reveal\n   * non-public entity existence.\n   */\n  getEntityCounts(\n    visibilityScope?: ContentVisibility,\n  ): Promise<Array<{ entityType: string; count: number }>>;\n\n  /** Get configuration for a specific entity type */\n  getEntityTypeConfig(type: string): EntityTypeConfig;\n\n  /** Get weight map for all registered entity types with non-default weights */\n  getWeightMap(): Record<string, number>;\n}\n\n/**\n * Entity service interface for managing brain entities\n */\nexport interface IEntitiesNamespace {\n  /** Register a new entity type with schema and adapter */\n  register<TEntity extends BaseEntity>(\n    entityType: string,\n    schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>,\n    adapter: EntityAdapter<TEntity>,\n    config?: EntityTypeConfig,\n  ): void;\n\n  /**\n   * Get the adapter for an entity type.\n   *\n   * Returns the structural `EntityAdapter<BaseEntity>` view — namespace\n   * consumers don't narrow by entity type. For typed access tied to a\n   * specific `TEntity`, use the underlying `EntityRegistry.getAdapter<T>`\n   * directly (see `entity-serializer.ts`).\n   */\n  getAdapter(entityType: string): EntityAdapter<BaseEntity> | undefined;\n\n  /** Extend an adapter's frontmatterSchema with additional fields */\n  extendFrontmatterSchema(\n    type: string,\n    extension: z.ZodObject<z.ZodRawShape>,\n  ): void;\n\n  /** Get effective frontmatter schema (base + extensions) for an entity type */\n  getEffectiveFrontmatterSchema(\n    type: string,\n  ): z.ZodObject<z.ZodRawShape> | undefined;\n\n  /** Update an existing entity */\n  update<TEntity extends BaseEntity>(\n    entity: TEntity,\n  ): Promise<{ entityId: string; jobId: string }>;\n\n  /** Register a data source for dynamic content */\n  registerDataSource(dataSource: DataSource): void;\n\n  /** Register a create interceptor for this plugin's entity type */\n  registerCreateInterceptor(\n    entityType: string,\n    interceptor: CreateInterceptor,\n  ): void;\n\n  /** Register a raw-upload durable save handler for this plugin's entity type */\n  registerUploadSaveHandler(registration: UploadSaveHandlerRegistration): void;\n}\n\nexport interface EntityService extends ICoreEntityService {\n  // Mutations\n  createEntity<T extends BaseEntity>(\n    request: CreateEntityRequest<T>,\n  ): Promise<EntityMutationResult>;\n  createEntityFromMarkdown(\n    request: CreateEntityFromMarkdownRequest,\n  ): Promise<EntityMutationResult>;\n  updateEntity<T extends BaseEntity>(\n    request: UpdateEntityRequest<T>,\n  ): Promise<EntityMutationResult>;\n  deleteEntity(request: DeleteEntityRequest): Promise<boolean>;\n  upsertEntity<T extends BaseEntity>(\n    request: UpsertEntityRequest<T>,\n  ): Promise<EntityMutationResult & { created: boolean }>;\n  storeEmbedding(data: StoreEmbeddingData): Promise<void>;\n\n  // Serialization\n  serializeEntity(entity: BaseEntity): string;\n  deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;\n\n  // Counts\n  countEmbeddings(): Promise<number>;\n\n  // Diagnostics\n  searchWithDistances(\n    request: SearchWithDistancesRequest,\n  ): Promise<Array<{ entityId: string; entityType: string; distance: number }>>;\n\n  // Lifecycle\n  initialize(): Promise<void>;\n\n  // Job status\n  getAsyncJobStatus(jobId: string): Promise<{\n    status: \"pending\" | \"processing\" | \"completed\" | \"failed\";\n    error?: string;\n  } | null>;\n}\n\n/**\n * Entity Registry interface for managing entity types and their schemas/adapters\n */\nexport interface EntityRegistry {\n  registerEntityType<\n    TEntity extends BaseEntity<TMetadata>,\n    TMetadata = Record<string, unknown>,\n  >(\n    type: string,\n    schema: z.ZodType<unknown>,\n    adapter: EntityAdapter<TEntity, TMetadata>,\n    config?: EntityTypeConfig,\n  ): void;\n\n  getSchema(type: string): z.ZodType<unknown>;\n\n  getAdapter<\n    TEntity extends BaseEntity<TMetadata>,\n    TMetadata = Record<string, unknown>,\n  >(\n    type: string,\n  ): EntityAdapter<TEntity, TMetadata>;\n\n  hasEntityType(type: string): boolean;\n\n  validateEntity(type: string, entity: unknown): BaseEntity;\n\n  getAllEntityTypes(): string[];\n\n  /** Get configuration for a specific entity type */\n  getEntityTypeConfig(type: string): EntityTypeConfig;\n\n  /** Get weight map for all registered entity types with non-default weights */\n  getWeightMap(): Record<string, number>;\n\n  registerCreateInterceptor(type: string, interceptor: CreateInterceptor): void;\n\n  getCreateInterceptor(type: string): CreateInterceptor | undefined;\n\n  registerUploadSaveHandler(registration: UploadSaveHandlerRegistration): void;\n\n  getUploadSaveHandler(\n    mediaType: string,\n  ): UploadSaveHandlerRegistration | undefined;\n\n  registerPersistValidator(type: string, validator: PersistValidator): void;\n\n  getPersistValidator(type: string): PersistValidator | undefined;\n\n  /**\n   * Extend an adapter's frontmatterSchema with additional fields.\n   * Used by plugins to add domain-specific fields (e.g., professional-site adds tagline to profile).\n   * Extensions are merged into the effective schema returned by getEffectiveFrontmatterSchema().\n   */\n  extendFrontmatterSchema(\n    type: string,\n    extension: z.ZodObject<z.ZodRawShape>,\n  ): void;\n\n  /**\n   * Get the effective frontmatter schema for an entity type,\n   * with all registered extensions merged in.\n   * Returns undefined if the adapter has no frontmatterSchema.\n   */\n  getEffectiveFrontmatterSchema(\n    type: string,\n  ): z.ZodObject<z.ZodRawShape> | undefined;\n}\n\n/**\n * Database configuration for entity service\n */\nexport type { DbConfig as EntityDbConfig } from \"@brains/contracts\";\n",
+    "import { z } from \"@brains/utils\";\nimport type { DataSource } from \"./datasource-types\";\nimport {\n  contentVisibilitySchema,\n  type ContentVisibility,\n  type RawContentVisibility,\n} from \"./visibility\";\n\n/**\n * Entity type for unstructured notes (the \"note\" entity type).\n * Used as a sentinel for the default catch-all markdown file shape —\n * no typed frontmatter schema required, content is the entire file body.\n */\nexport const NOTE_ENTITY_TYPE = \"note\";\n\n/**\n * Embedding job data - minimal data for job queue\n * Content is NOT stored to avoid large base64 data in job queue\n * (which would end up in dashboard hydration props JSON)\n * Handler fetches fresh content from entity when processing\n */\nexport interface EmbeddingJobData {\n  id: string;\n  entityType: string;\n  /** Hash of content at job creation time - for staleness detection */\n  contentHash: string;\n  operation: \"create\" | \"update\";\n}\n\n/**\n * Options for entity mutation operations (create, update, upsert)\n */\nexport interface EntityJobOptions {\n  priority?: number;\n  maxRetries?: number;\n}\n\nexport {\n  contentVisibilitySchema,\n  normalizeContentVisibility,\n  getVisibleContentVisibilities,\n  isVisibleWithinScope,\n  permissionToVisibilityScope,\n  canWriteVisibility,\n} from \"./visibility\";\nexport type { ContentVisibility, RawContentVisibility } from \"./visibility\";\n\n/**\n * Options for entity creation (extends EntityJobOptions with deduplication)\n */\nexport interface CreateEntityOptions extends EntityJobOptions {\n  deduplicateId?: boolean;\n}\n\n/**\n * Result of an entity mutation that triggers an embedding job.\n * When skipped is true, content was unchanged — no DB write, no event, no embedding job.\n */\nexport interface EntityMutationResult {\n  entityId: string;\n  jobId: string;\n  skipped: boolean;\n}\n\n/**\n * Input for adapter-validated direct creation from finalized markdown.\n */\nexport interface CreateEntityFromMarkdownInput {\n  entityType: string;\n  id: string;\n  markdown: string;\n}\n\n/**\n * Data for storing an embedding for an entity\n */\nexport interface StoreEmbeddingData {\n  entityId: string;\n  entityType: string;\n  embedding: Float32Array;\n  contentHash: string;\n}\n\n/**\n * Base entity schema that all entities must extend\n */\nexport const baseEntitySchema = z.object({\n  id: z.string(),\n  entityType: z.string(),\n  content: z.string(),\n  created: z.string().datetime(),\n  updated: z.string().datetime(),\n  visibility: contentVisibilitySchema,\n  metadata: z.record(z.string(), z.unknown()),\n  contentHash: z.string(),\n});\n\n/**\n * Base entity type - generic to support typed metadata\n * TMetadata defaults to Record<string, unknown> for backward compatibility\n */\nexport interface BaseEntity<TMetadata = Record<string, unknown>> {\n  id: string;\n  entityType: string;\n  content: string;\n  created: string;\n  updated: string;\n  visibility: ContentVisibility;\n  metadata: TMetadata;\n  /** SHA256 hash of content for change detection */\n  contentHash: string;\n}\n\n/**\n * Entity input type for creation - allows partial entities with optional system fields\n * contentHash is excluded because it's computed automatically by the entity service\n */\nexport type EntityInput<T extends BaseEntity> = Omit<\n  T,\n  \"id\" | \"created\" | \"updated\" | \"contentHash\" | \"visibility\"\n> & {\n  id?: string;\n  created?: string;\n  updated?: string;\n  visibility?: RawContentVisibility;\n};\n\n/**\n * Search result type\n */\nexport interface SearchResult<T extends BaseEntity = BaseEntity> {\n  entity: T;\n  score: number;\n  excerpt: string;\n}\n\n/**\n * Normalized system_create input shape used by plugin create interceptors.\n */\nexport interface CreateCoverImageInput {\n  generate?: boolean | undefined;\n  prompt?: string | undefined;\n}\n\nexport interface CreateFromAttachmentInput {\n  kind: \"entity-attachment\";\n  sourceEntityType: string;\n  sourceEntityId: string;\n  attachmentType: string;\n}\n\nexport interface CreateFromUploadInput {\n  kind: \"upload\";\n  id: string;\n}\n\nexport type CreateFromInput = CreateFromAttachmentInput | CreateFromUploadInput;\n\nexport type CreateTransform = \"extract-markdown\";\n\nexport interface CreateInput {\n  entityType: string;\n  prompt?: string;\n  title?: string;\n  content?: string;\n  url?: string;\n  from?: CreateFromInput;\n  transform?: CreateTransform;\n  replace?: boolean;\n  targetEntityType?: string;\n  targetEntityId?: string;\n  coverImage?: boolean | CreateCoverImageInput;\n}\n\n/**\n * Minimal caller context forwarded to plugin create interceptors.\n */\nexport interface CreateExecutionContext {\n  interfaceType: string;\n  userId: string;\n  channelId?: string;\n  channelName?: string;\n}\n\n/**\n * Result returned to system_create when a plugin fully handles creation.\n */\nexport const createResultAttachmentSchema = z.object({\n  mediaType: z.string(),\n  url: z.string(),\n  downloadUrl: z.string().optional(),\n  previewUrl: z.string().optional(),\n  filename: z.string().optional(),\n  sizeBytes: z.number().optional(),\n  source: z\n    .object({\n      entityType: z.string().optional(),\n      entityId: z.string().optional(),\n      attachmentType: z.string().optional(),\n    })\n    .optional(),\n});\n\nexport type CreateResultAttachment = z.infer<\n  typeof createResultAttachmentSchema\n>;\n\nexport type CreateResult =\n  | {\n      success: true;\n      data: {\n        entityId?: string;\n        jobId?: string;\n        status: string;\n        attachment?: CreateResultAttachment;\n      };\n    }\n  | { success: false; error: string };\n\n/**\n * Plugin create interceptors can either fully handle creation,\n * or continue with a rewritten normalized input.\n */\nexport type CreateInterceptionResult =\n  | { kind: \"handled\"; result: CreateResult }\n  | { kind: \"continue\"; input: CreateInput };\n\nexport type CreateInterceptor = (\n  input: CreateInput,\n  executionContext: CreateExecutionContext,\n) => Promise<CreateInterceptionResult>;\n\nexport interface UploadSaveInput {\n  upload: CreateFromUploadInput;\n  title?: string;\n}\n\nexport type UploadSaveHandler = (\n  input: UploadSaveInput,\n  executionContext: CreateExecutionContext,\n) => Promise<CreateResult>;\n\nexport interface UploadSaveHandlerRegistration {\n  entityType: string;\n  mediaTypes: string[];\n  handler: UploadSaveHandler;\n}\n\n/**\n * Called before an entity is persisted (on create or update). Throws to reject\n * the write with an operator-facing error. Use this for cross-entity invariants\n * the per-entity Zod schema cannot express.\n */\nexport type PersistValidator<T extends BaseEntity = BaseEntity> = (\n  entity: T,\n  context: { operation: \"create\" | \"update\" },\n) => Promise<void>;\n\n/**\n * Minimal event bus contract used by entity-service for lifecycle events.\n * Kept structural to avoid coupling this package to a concrete messaging service.\n */\nexport interface EntityEventBus {\n  send(request: {\n    type: string;\n    payload: Record<string, unknown>;\n    sender: string;\n    target?: string;\n    metadata?: Record<string, unknown>;\n    broadcast?: boolean;\n  }): Promise<unknown>;\n}\n\n/**\n * Interface for entity adapter - handles conversion between entities and markdown\n * following the hybrid storage model\n *\n * @template TEntity - The full entity type\n * @template TMetadata - The metadata type (defaults to Record<string, unknown>)\n */\nexport interface EntityAdapter<\n  TEntity extends BaseEntity<TMetadata>,\n  TMetadata = Record<string, unknown>,\n> {\n  entityType: string;\n  schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>;\n\n  // Convert entity to markdown content (may include frontmatter for entity-specific fields)\n  toMarkdown(entity: TEntity): string;\n\n  // Extract entity-specific fields from markdown\n  // Returns Partial<TEntity> as core fields come from database\n  fromMarkdown(markdown: string): Partial<TEntity>;\n\n  // Extract metadata from entity for search/filtering - now strongly typed\n  extractMetadata(entity: TEntity): TMetadata;\n\n  // Parse frontmatter metadata from markdown\n  parseFrontMatter<TFrontmatter>(\n    markdown: string,\n    schema: z.ZodSchema<TFrontmatter>,\n  ): TFrontmatter;\n\n  // Generate frontmatter for markdown\n  generateFrontMatter(entity: TEntity): string;\n\n  /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */\n  frontmatterSchema?: z.ZodObject<z.ZodRawShape>;\n\n  /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */\n  isSingleton?: boolean;\n\n  /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */\n  hasBody?: boolean;\n\n  /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */\n  getBodyTemplate(): string;\n\n  /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */\n  supportsCoverImage?: boolean;\n\n  /** Optional: Extract coverImageId from entity content/frontmatter */\n  getCoverImageId?(entity: TEntity): string | undefined;\n\n  /**\n   * Optional: build the markdown content and metadata for a queued-generation stub.\n   * When undefined, this entity type does not support prompt-based queued creation\n   * via system_create; the tool will reject the call rather than silently degrade.\n   * The returned metadata must satisfy this entity's metadata schema (with\n   * status set to \"generating\"); central code only stamps id/timestamps/visibility.\n   */\n  buildStub?(input: { id: string; title: string }): {\n    content: string;\n    metadata: TMetadata;\n  };\n}\n\n/**\n * Sort field specification for multi-field sorting\n */\nexport interface SortField {\n  /** Field to sort by - \"created\", \"updated\", or a metadata field name */\n  field: string;\n  /** Sort direction */\n  direction: \"asc\" | \"desc\";\n  /** Sort NULL values before non-NULL values (default: false / SQLite default) */\n  nullsFirst?: boolean;\n}\n\n/**\n * List entities options\n * Generic over metadata type for type-safe filtering\n */\nexport interface ListOptions<TMetadata = Record<string, unknown>> {\n  limit?: number;\n  offset?: number;\n  /** Multi-field sorting - supports system fields (created, updated) and metadata fields */\n  sortFields?: SortField[];\n  filter?: {\n    // Typed metadata filter - partial match on metadata fields\n    metadata?: Partial<TMetadata>;\n    visibilityScope?: ContentVisibility;\n  };\n  /** Filter to only entities with metadata.status = \"published\" */\n  publishedOnly?: boolean;\n}\n\n/**\n * Search options\n */\nexport interface SearchOptions {\n  limit?: number;\n  offset?: number;\n  types?: string[];\n  excludeTypes?: string[];\n  sortBy?: \"relevance\" | \"created\" | \"updated\";\n  sortDirection?: \"asc\" | \"desc\";\n  /** Score multipliers per entity type - applied after initial search */\n  weight?: Record<string, number>;\n  visibilityScope?: ContentVisibility;\n  /** Include queued/failed generation stubs in search results (default: false) */\n  includeUngenerated?: boolean;\n}\n\n/**\n * Configuration for entity type registration\n */\nexport interface EntityTypeConfig {\n  /** Score multiplier for search results (default: 1.0) */\n  weight?: number;\n  /** Whether to generate embeddings for this entity type (default: true).\n   *  Set to false for entity types with non-textual content (e.g., images). */\n  embeddable?: boolean;\n  /** Whether this entity type may be used as source material for derived projections (default: true).\n   *  Set to false for projection outputs that would create feedback loops. */\n  projectionSource?: boolean;\n  /** Publish semantics for status-bearing entity types. Statuses listed here\n   *  represent publication commitment/execution states and require the\n   *  `publish` entity action when entered or modified. */\n  publish?: {\n    publishStatuses: string[];\n  };\n}\n\n/**\n * Core entity service interface for read-only operations\n * Used by core plugins that need entity access but shouldn't modify entities\n */\nexport interface GetEntityRequest {\n  entityType: string;\n  id: string;\n  /**\n   * Optional visibility scope. Undefined fails closed to \"public\" — callers\n   * with elevated access must opt up explicitly.\n   */\n  visibilityScope?: ContentVisibility;\n}\n\nexport type GetEntityRawRequest = GetEntityRequest;\n\nexport interface ListEntitiesRequest {\n  entityType: string;\n  options?: ListOptions | undefined;\n}\n\nexport interface CountEntitiesRequest {\n  entityType: string;\n  options?: Pick<ListOptions, \"publishedOnly\" | \"filter\"> | undefined;\n}\n\nexport interface CreateEntityRequest<T extends BaseEntity> {\n  entity: EntityInput<T>;\n  options?: CreateEntityOptions | undefined;\n}\n\nexport interface CreateEntityFromMarkdownRequest {\n  input: CreateEntityFromMarkdownInput;\n  options?: CreateEntityOptions | undefined;\n}\n\nexport interface UpdateEntityRequest<T extends BaseEntity> {\n  entity: T;\n  options?: EntityJobOptions | undefined;\n}\n\nexport interface DeleteEntityRequest {\n  entityType: string;\n  id: string;\n}\n\nexport interface UpsertEntityRequest<T extends BaseEntity> {\n  entity: T;\n  options?: EntityJobOptions | undefined;\n}\n\nexport interface EntitySearchRequest {\n  query: string;\n  options?: SearchOptions | undefined;\n}\n\nexport interface SearchWithDistancesRequest {\n  query: string;\n}\n\nexport interface ICoreEntityService {\n  // Read-only operations\n  getEntity<T extends BaseEntity>(request: GetEntityRequest): Promise<T | null>;\n\n  /**\n   * Get entity without content resolution (raw)\n   * Used internally to avoid recursion when resolving image references\n   */\n  getEntityRaw<T extends BaseEntity>(\n    request: GetEntityRawRequest,\n  ): Promise<T | null>;\n\n  listEntities<T extends BaseEntity>(\n    request: ListEntitiesRequest,\n  ): Promise<T[]>;\n\n  search<T extends BaseEntity = BaseEntity>(\n    request: EntitySearchRequest,\n  ): Promise<SearchResult<T>[]>;\n\n  // Entity type information\n  getEntityTypes(): string[];\n  hasEntityType(type: string): boolean;\n\n  // Entity counts\n  countEntities(request: CountEntitiesRequest): Promise<number>;\n  /**\n   * Group counts by entity type. Fails closed: undefined visibilityScope\n   * filters to public-only counts so aggregate insights cannot reveal\n   * non-public entity existence.\n   */\n  getEntityCounts(\n    visibilityScope?: ContentVisibility,\n  ): Promise<Array<{ entityType: string; count: number }>>;\n\n  /** Get configuration for a specific entity type */\n  getEntityTypeConfig(type: string): EntityTypeConfig;\n\n  /** Get weight map for all registered entity types with non-default weights */\n  getWeightMap(): Record<string, number>;\n}\n\n/**\n * Entity service interface for managing brain entities\n */\nexport interface IEntitiesNamespace {\n  /** Register a new entity type with schema and adapter */\n  register<TEntity extends BaseEntity>(\n    entityType: string,\n    schema: z.ZodType<TEntity, z.ZodTypeDef, unknown>,\n    adapter: EntityAdapter<TEntity>,\n    config?: EntityTypeConfig,\n  ): void;\n\n  /**\n   * Get the adapter for an entity type.\n   *\n   * Returns the structural `EntityAdapter<BaseEntity>` view — namespace\n   * consumers don't narrow by entity type. For typed access tied to a\n   * specific `TEntity`, use the underlying `EntityRegistry.getAdapter<T>`\n   * directly (see `entity-serializer.ts`).\n   */\n  getAdapter(entityType: string): EntityAdapter<BaseEntity> | undefined;\n\n  /** Extend an adapter's frontmatterSchema with additional fields */\n  extendFrontmatterSchema(\n    type: string,\n    extension: z.ZodObject<z.ZodRawShape>,\n  ): void;\n\n  /** Get effective frontmatter schema (base + extensions) for an entity type */\n  getEffectiveFrontmatterSchema(\n    type: string,\n  ): z.ZodObject<z.ZodRawShape> | undefined;\n\n  /** Update an existing entity */\n  update<TEntity extends BaseEntity>(\n    entity: TEntity,\n  ): Promise<{ entityId: string; jobId: string }>;\n\n  /** Register a data source for dynamic content */\n  registerDataSource(dataSource: DataSource): void;\n\n  /** Register a create interceptor for this plugin's entity type */\n  registerCreateInterceptor(\n    entityType: string,\n    interceptor: CreateInterceptor,\n  ): void;\n\n  /** Register a raw-upload durable save handler for this plugin's entity type */\n  registerUploadSaveHandler(registration: UploadSaveHandlerRegistration): void;\n}\n\nexport interface EntityService extends ICoreEntityService {\n  // Mutations\n  createEntity<T extends BaseEntity>(\n    request: CreateEntityRequest<T>,\n  ): Promise<EntityMutationResult>;\n  createEntityFromMarkdown(\n    request: CreateEntityFromMarkdownRequest,\n  ): Promise<EntityMutationResult>;\n  updateEntity<T extends BaseEntity>(\n    request: UpdateEntityRequest<T>,\n  ): Promise<EntityMutationResult>;\n  deleteEntity(request: DeleteEntityRequest): Promise<boolean>;\n  upsertEntity<T extends BaseEntity>(\n    request: UpsertEntityRequest<T>,\n  ): Promise<EntityMutationResult & { created: boolean }>;\n  storeEmbedding(data: StoreEmbeddingData): Promise<void>;\n\n  // Serialization\n  serializeEntity(entity: BaseEntity): string;\n  deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;\n\n  // Counts\n  countEmbeddings(): Promise<number>;\n\n  // Diagnostics\n  searchWithDistances(\n    request: SearchWithDistancesRequest,\n  ): Promise<Array<{ entityId: string; entityType: string; distance: number }>>;\n\n  // Lifecycle\n  initialize(): Promise<void>;\n\n  // Job status\n  getAsyncJobStatus(jobId: string): Promise<{\n    status: \"pending\" | \"processing\" | \"completed\" | \"failed\";\n    error?: string;\n  } | null>;\n}\n\n/**\n * Entity Registry interface for managing entity types and their schemas/adapters\n */\nexport interface EntityRegistry {\n  registerEntityType<\n    TEntity extends BaseEntity<TMetadata>,\n    TMetadata = Record<string, unknown>,\n  >(\n    type: string,\n    schema: z.ZodType<unknown>,\n    adapter: EntityAdapter<TEntity, TMetadata>,\n    config?: EntityTypeConfig,\n  ): void;\n\n  getSchema(type: string): z.ZodType<unknown>;\n\n  getAdapter<\n    TEntity extends BaseEntity<TMetadata>,\n    TMetadata = Record<string, unknown>,\n  >(\n    type: string,\n  ): EntityAdapter<TEntity, TMetadata>;\n\n  hasEntityType(type: string): boolean;\n\n  validateEntity(type: string, entity: unknown): BaseEntity;\n\n  getAllEntityTypes(): string[];\n\n  /** Get configuration for a specific entity type */\n  getEntityTypeConfig(type: string): EntityTypeConfig;\n\n  /** Get weight map for all registered entity types with non-default weights */\n  getWeightMap(): Record<string, number>;\n\n  registerCreateInterceptor(type: string, interceptor: CreateInterceptor): void;\n\n  getCreateInterceptor(type: string): CreateInterceptor | undefined;\n\n  registerUploadSaveHandler(registration: UploadSaveHandlerRegistration): void;\n\n  getUploadSaveHandler(\n    mediaType: string,\n  ): UploadSaveHandlerRegistration | undefined;\n\n  registerPersistValidator(type: string, validator: PersistValidator): void;\n\n  getPersistValidator(type: string): PersistValidator | undefined;\n\n  /**\n   * Extend an adapter's frontmatterSchema with additional fields.\n   * Used by plugins to add domain-specific fields (e.g., professional-site adds tagline to profile).\n   * Extensions are merged into the effective schema returned by getEffectiveFrontmatterSchema().\n   */\n  extendFrontmatterSchema(\n    type: string,\n    extension: z.ZodObject<z.ZodRawShape>,\n  ): void;\n\n  /**\n   * Get the effective frontmatter schema for an entity type,\n   * with all registered extensions merged in.\n   * Returns undefined if the adapter has no frontmatterSchema.\n   */\n  getEffectiveFrontmatterSchema(\n    type: string,\n  ): z.ZodObject<z.ZodRawShape> | undefined;\n}\n\n/**\n * Database configuration for entity service\n */\nexport type { DbConfig as EntityDbConfig } from \"@brains/contracts\";\n",
     "import { z, Logger, type ProgressReporter } from \"@brains/utils\";\nimport type {\n  EntityService as IEntityService,\n  EmbeddingJobData,\n  EntityEventBus,\n} from \"../types\";\nimport type { IEmbeddingService } from \"../embedding-types\";\nimport type { JobHandler } from \"@brains/job-queue\";\nimport { internalFullScope } from \"../internal-scope\";\n/**\n * Zod schema for embedding job data validation\n * Content is NOT in job data - fetched fresh from entity when processing\n */\nconst embeddingJobDataSchema = z.object({\n  id: z.string().min(1, \"Entity ID is required\"),\n  entityType: z.string().min(1, \"Entity type is required\"),\n  contentHash: z.string().min(1, \"Content hash is required\"),\n  operation: z.enum([\"create\", \"update\"]),\n});\n\n/**\n * Job handler for embedding generation\n * Processes entities to generate embeddings using the EmbeddingService\n * Implements Component Interface Standardization pattern\n */\nexport class EmbeddingJobHandler implements JobHandler<\"embedding\"> {\n  private static instance: EmbeddingJobHandler | null = null;\n  private logger: Logger;\n  private embeddingService: IEmbeddingService;\n  private entityService: IEntityService;\n  private messageBus?: EntityEventBus;\n\n  /**\n   * Get the singleton instance\n   */\n  public static getInstance(\n    entityService: IEntityService,\n    embeddingService: IEmbeddingService,\n    messageBus?: EntityEventBus,\n  ): EmbeddingJobHandler {\n    EmbeddingJobHandler.instance ??= new EmbeddingJobHandler(\n      entityService,\n      embeddingService,\n      messageBus,\n    );\n    return EmbeddingJobHandler.instance;\n  }\n\n  /**\n   * Reset the singleton instance (primarily for testing)\n   */\n  public static resetInstance(): void {\n    EmbeddingJobHandler.instance = null;\n  }\n\n  /**\n   * Create a fresh instance without affecting the singleton\n   */\n  public static createFresh(\n    entityService: IEntityService,\n    embeddingService: IEmbeddingService,\n    messageBus?: EntityEventBus,\n  ): EmbeddingJobHandler {\n    return new EmbeddingJobHandler(entityService, embeddingService, messageBus);\n  }\n\n  /**\n   * Private constructor to enforce singleton pattern\n   */\n  private constructor(\n    entityService: IEntityService,\n    embeddingService: IEmbeddingService,\n    messageBus?: EntityEventBus,\n  ) {\n    this.logger = Logger.getInstance().child(\"EmbeddingJobHandler\");\n    this.embeddingService = embeddingService;\n    this.entityService = entityService;\n    if (messageBus) {\n      this.messageBus = messageBus;\n    }\n  }\n\n  /**\n   * Process an embedding job\n   * Generates embedding for entity content and stores it in the embeddings table\n   * Entity must already exist in entities table (stored immediately by createEntity/updateEntity)\n   */\n  public async process(\n    data: EmbeddingJobData,\n    jobId: string,\n    progressReporter: ProgressReporter,\n  ): Promise<void> {\n    try {\n      this.logger.debug(\"Processing embedding job\", {\n        jobId,\n        entityId: data.id,\n        entityType: data.entityType,\n        contentHash: data.contentHash,\n      });\n\n      // Report initial progress\n      await progressReporter.report({\n        progress: 0,\n        total: 2,\n        message: `Generating embedding for ${data.entityType} ${data.id}`,\n      });\n\n      // Fetch fresh entity - content is NOT stored in job data to avoid\n      // large base64 data bloating job queue and dashboard hydration props.\n      const currentEntity = await this.entityService.getEntity({\n        entityType: data.entityType,\n        id: data.id,\n        visibilityScope: internalFullScope(\n          \"embedding regeneration must index every entity, no user surface\",\n        ),\n      });\n\n      if (!currentEntity) {\n        this.logger.warn(\"Entity no longer exists, skipping embedding job\", {\n          jobId,\n          entityId: data.id,\n          entityType: data.entityType,\n          operation: data.operation,\n        });\n        return;\n      }\n\n      // Check if content has changed since job was queued (staleness detection)\n      if (currentEntity.contentHash !== data.contentHash) {\n        this.logger.info(\n          \"Entity content changed since job created, skipping stale embedding\",\n          {\n            jobId,\n            entityId: data.id,\n            entityType: data.entityType,\n            jobContentHash: data.contentHash,\n            currentContentHash: currentEntity.contentHash,\n          },\n        );\n        return;\n      }\n\n      // Generate embedding using fresh content from entity\n      const { embedding, usage } =\n        await this.embeddingService.generateEmbedding(currentEntity.content);\n\n      // Log usage event for monitoring\n      this.logger.info(\"ai:usage\", {\n        operation: \"embedding\",\n        provider: \"openai\",\n        model: \"text-embedding-3-small\",\n        inputTokens: usage.tokens,\n        outputTokens: 0,\n      });\n\n      // Report progress after embedding generation\n      await progressReporter.report({\n        progress: 1,\n        total: 2,\n        message: `Storing embedding for ${data.entityType} ${data.id}`,\n      });\n\n      // Store the embedding in the embeddings table\n      await this.entityService.storeEmbedding({\n        entityId: data.id,\n        entityType: data.entityType,\n        embedding,\n        contentHash: data.contentHash,\n      });\n\n      // Emit entity:embedding:ready event after successful save\n      // Note: entity:created is now emitted by createEntity() when entity is first persisted\n      if (this.messageBus) {\n        this.logger.debug(\n          `Emitting entity:embedding:ready event for ${data.entityType}:${data.id}`,\n        );\n\n        await this.messageBus.send({\n          type: \"entity:embedding:ready\",\n          payload: {\n            entityType: data.entityType,\n            entityId: data.id,\n            entity: currentEntity,\n          },\n          sender: \"entity-service\",\n          broadcast: true,\n        });\n      }\n\n      // Report completion\n      await progressReporter.report({\n        progress: 2,\n        total: 2,\n        message: `Completed embedding for ${data.entityType} ${data.id}`,\n      });\n\n      this.logger.debug(\"Embedding job completed successfully\", {\n        jobId,\n        entityId: data.id,\n        embeddingDimensions: embedding.length,\n      });\n    } catch (error) {\n      this.logger.error(\"Embedding job failed\", {\n        jobId,\n        entityId: data.id,\n        entityType: data.entityType,\n        error,\n      });\n      throw error;\n    }\n  }\n\n  /**\n   * Handle embedding job errors\n   */\n  public async onError(\n    error: Error,\n    data: EmbeddingJobData,\n    jobId: string,\n  ): Promise<void> {\n    this.logger.error(\"Embedding job error handler called\", {\n      jobId,\n      entityId: data.id,\n      entityType: data.entityType,\n      contentHash: data.contentHash,\n      errorMessage: error.message,\n      errorStack: error.stack,\n    });\n  }\n\n  /**\n   * Validate and parse embedding job data using Zod schema\n   * Ensures type safety and data integrity\n   */\n  public validateAndParse(data: unknown): EmbeddingJobData | null {\n    try {\n      const result = embeddingJobDataSchema.parse(data);\n\n      this.logger.debug(\"Embedding job data validation successful\", {\n        entityId: result.id,\n        entityType: result.entityType,\n        contentHash: result.contentHash,\n      });\n\n      return result;\n    } catch (error) {\n      this.logger.warn(\"Invalid embedding job data\", {\n        data,\n        validationError: error instanceof z.ZodError ? error.issues : error,\n      });\n      return null;\n    }\n  }\n}\n",
     "import type { EntityDB } from \"./db\";\nimport {\n  getVisibleContentVisibilities,\n  type BaseEntity,\n  type ContentVisibility,\n  type SearchResult,\n  type SearchOptions,\n} from \"./types\";\nimport type { IEmbeddingService } from \"./embedding-types\";\nimport type { EntitySerializer } from \"./entity-serializer\";\nimport { z, type Logger } from \"@brains/utils\";\nimport { sql, and, desc, inArray, type SQL } from \"drizzle-orm\";\nimport { entities } from \"./schema/entities\";\n\nexport const MAX_SEARCH_QUERY_CHARS = 12_000;\n\nexport function prepareSearchQuery(\n  query: string,\n  logger?: Logger,\n  maxChars = MAX_SEARCH_QUERY_CHARS,\n): string {\n  const normalizedQuery = query.trim().replace(/\\s+/g, \" \");\n\n  if (normalizedQuery.length <= maxChars) {\n    return normalizedQuery;\n  }\n\n  logger?.warn(\"Truncating search query that exceeds max length\", {\n    originalLength: normalizedQuery.length,\n    truncatedLength: maxChars,\n  });\n\n  return normalizedQuery.slice(0, maxChars);\n}\n\n/**\n * Schema for search options (excluding tags)\n */\nconst searchOptionsSchema = z.object({\n  limit: z.number().int().positive().optional().default(20),\n  offset: z.number().int().min(0).optional().default(0),\n  types: z.array(z.string()).optional().default([]),\n  excludeTypes: z.array(z.string()).optional().default([]),\n  weight: z.record(z.string(), z.number()).optional(),\n  visibilityScope: z.enum([\"public\", \"shared\", \"restricted\"]).optional(),\n  includeUngenerated: z.boolean().optional().default(false),\n});\n\n/**\n * EntitySearch handles all search operations for entities\n * Extracted from EntityService for single responsibility\n */\nexport class EntitySearch {\n  private db: EntityDB;\n  private embeddingService: IEmbeddingService;\n  private serializer: EntitySerializer;\n  private logger: Logger;\n\n  constructor(\n    db: EntityDB,\n    embeddingService: IEmbeddingService,\n    serializer: EntitySerializer,\n    logger: Logger,\n  ) {\n    this.db = db;\n    this.embeddingService = embeddingService;\n    this.serializer = serializer;\n    this.logger = logger.child(\"EntitySearch\");\n  }\n\n  /**\n   * Search entities by query using vector similarity\n   */\n  public async search<T extends BaseEntity = BaseEntity>(\n    query: string,\n    options?: SearchOptions,\n  ): Promise<SearchResult<T>[]> {\n    const validatedOptions = searchOptionsSchema.parse(options ?? {});\n    const {\n      limit,\n      offset,\n      types,\n      excludeTypes,\n      weight,\n      visibilityScope,\n      includeUngenerated,\n    } = validatedOptions;\n\n    // Check if we have weights to apply\n    const hasWeights = weight && Object.keys(weight).length > 0;\n    const preparedQuery = prepareSearchQuery(query, this.logger);\n\n    this.logger.debug(\n      `Searching entities with query (${preparedQuery.length} chars)`,\n    );\n\n    // Generate embedding for the query\n    const { embedding: queryEmbedding } =\n      await this.embeddingService.generateEmbedding(preparedQuery);\n\n    // Convert Float32Array to JSON array for SQL\n    const embeddingArray = JSON.stringify(Array.from(queryEmbedding));\n\n    const weightMultiplier = this.buildWeightMultiplier(\n      hasWeights ? weight : undefined,\n    );\n\n    // Build type filter conditions for drizzle\n    const typeConditions: SQL[] = [];\n    if (types.length > 0) {\n      typeConditions.push(\n        sql`${entities.entityType} IN (${sql.join(\n          types.map((t) => sql`${t}`),\n          sql`, `,\n        )})`,\n      );\n    }\n    if (excludeTypes.length > 0) {\n      typeConditions.push(\n        sql`${entities.entityType} NOT IN (${sql.join(\n          excludeTypes.map((t) => sql`${t}`),\n          sql`, `,\n        )})`,\n      );\n    }\n\n    return this.searchWithAttachedDb<T>(\n      embeddingArray,\n      weightMultiplier,\n      [\n        ...typeConditions,\n        ...this.buildVisibilityConditions(visibilityScope),\n        ...this.buildGenerationStatusConditions(includeUngenerated),\n      ],\n      limit,\n      offset,\n      preparedQuery,\n    );\n  }\n\n  private buildVisibilityConditions(\n    visibilityScope?: ContentVisibility,\n  ): SQL[] {\n    // Fail closed: undefined scope filters to public-only.\n    const scope: ContentVisibility = visibilityScope ?? \"public\";\n    if (scope === \"restricted\") {\n      return [];\n    }\n    return [inArray(entities.visibility, getVisibleContentVisibilities(scope))];\n  }\n\n  private buildGenerationStatusConditions(includeUngenerated: boolean): SQL[] {\n    if (includeUngenerated) return [];\n    return [\n      sql`(json_extract(${entities.metadata}, '$.status') IS NULL OR json_extract(${entities.metadata}, '$.status') NOT IN ('generating', 'failed'))`,\n    ];\n  }\n\n  /**\n   * FTS5 boost weight. When a keyword match is found, this fraction of the\n   * final score comes from FTS5 rank, the rest from vector similarity.\n   * 0.3 = 30% keyword, 70% semantic.\n   */\n  private static readonly FTS_ALPHA = 0.3;\n\n  /**\n   * Build a parameterized CASE expression for entity-type score multipliers.\n   * Weight keys may be caller-provided, so avoid raw SQL string interpolation.\n   */\n  private buildWeightMultiplier(weight?: Record<string, number>): SQL {\n    const entries = Object.entries(weight ?? {}).filter(([, multiplier]) =>\n      Number.isFinite(multiplier),\n    );\n\n    if (entries.length === 0) {\n      return sql`1.0`;\n    }\n\n    const cases = entries.map(\n      ([entityType, multiplier]) =>\n        sql`WHEN ${entities.entityType} = ${entityType} THEN ${multiplier}`,\n    );\n\n    return sql`CASE ${sql.join(cases, sql` `)} ELSE 1.0 END`;\n  }\n\n  /**\n   * Execute search against an attached embedding database (aliased as \"emb\").\n   */\n  private async searchWithAttachedDb<T extends BaseEntity = BaseEntity>(\n    embeddingArray: string,\n    weightMultiplier: SQL,\n    typeConditions: SQL[],\n    limit: number,\n    offset: number,\n    query: string,\n  ): Promise<SearchResult<T>[]> {\n    const alpha = EntitySearch.FTS_ALPHA;\n\n    // Vector similarity score (0..1, higher is better)\n    const vectorScore = sql<number>`(1.0 - vector_distance_cos(emb_e.embedding, vector32(${embeddingArray})) / 2.0) * (${weightMultiplier})`;\n    const distanceExpr = sql<number>`vector_distance_cos(emb_e.embedding, vector32(${embeddingArray}))`;\n\n    // FTS5 keyword boost via subquery: 1.0 when matched, 0.0 when not.\n    // Wrap in double quotes for phrase matching — prevents special characters\n    // (?, *, OR, AND, etc.) from being parsed as FTS5 operators.\n    const ftsQuery = '\"' + query.replace(/\"/g, '\"\"') + '\"';\n    const ftsBoost = sql<number>`CASE WHEN EXISTS (\n      SELECT 1 FROM entity_fts WHERE entity_fts MATCH ${ftsQuery}\n        AND entity_id = ${entities.id} AND entity_type = ${entities.entityType}\n    ) THEN 1.0 ELSE 0.0 END`;\n\n    // Combined score: (1-α)*vector + α*keyword_match\n    const combinedScore = sql<number>`(${1 - alpha} * ${vectorScore}) + (${alpha} * ${ftsBoost})`;\n\n    const results = await this.db\n      .select({\n        id: entities.id,\n        entityType: entities.entityType,\n        content: entities.content,\n        contentHash: entities.contentHash,\n        visibility: entities.visibility,\n        created: entities.created,\n        updated: entities.updated,\n        metadata: entities.metadata,\n        distance: distanceExpr,\n        weighted_score: combinedScore,\n      })\n      .from(entities)\n      .innerJoin(\n        sql`emb.embeddings AS emb_e`,\n        sql`${entities.id} = emb_e.entity_id AND ${entities.entityType} = emb_e.entity_type`,\n      )\n      .where(and(sql`${distanceExpr} < 0.82`, ...typeConditions))\n      .orderBy(desc(combinedScore))\n      .limit(limit)\n      .offset(offset);\n\n    return this.mapSearchResults<T>(results, query);\n  }\n\n  /**\n   * Search entities by type and query\n   */\n  public async searchEntities(\n    entityType: string,\n    query: string,\n    options?: { limit?: number },\n  ): Promise<SearchResult[]> {\n    // Build search options with the entity type filter\n    const searchOptions: SearchOptions = {\n      types: [entityType],\n      limit: options?.limit ?? 20,\n      offset: 0,\n      sortBy: \"relevance\",\n      sortDirection: \"desc\",\n    };\n\n    return this.search(query, searchOptions);\n  }\n\n  /**\n   * Return all embedded entities with their raw cosine distance to the query.\n   * No threshold filter — used for diagnostics and threshold tuning.\n   * Results sorted by distance ascending (closest first).\n   */\n  public async searchWithDistances(\n    query: string,\n  ): Promise<\n    Array<{ entityId: string; entityType: string; distance: number }>\n  > {\n    const preparedQuery = prepareSearchQuery(query, this.logger);\n    const { embedding: queryEmbedding } =\n      await this.embeddingService.generateEmbedding(preparedQuery);\n    const embeddingArray = JSON.stringify(Array.from(queryEmbedding));\n\n    const distanceExpr = sql<number>`vector_distance_cos(emb_e.embedding, vector32(${embeddingArray}))`;\n\n    const results = await this.db\n      .select({\n        entityId: entities.id,\n        entityType: entities.entityType,\n        distance: distanceExpr,\n      })\n      .from(entities)\n      .innerJoin(\n        sql`emb.embeddings AS emb_e`,\n        sql`${entities.id} = emb_e.entity_id AND ${entities.entityType} = emb_e.entity_type`,\n      )\n      .orderBy(sql`${distanceExpr} ASC`);\n\n    return results;\n  }\n\n  /**\n   * Transform raw query rows into SearchResult objects\n   */\n  private mapSearchResults<T extends BaseEntity = BaseEntity>(\n    results: Array<{\n      id: string;\n      entityType: string;\n      content: string;\n      contentHash: string;\n      visibility: ContentVisibility;\n      created: number;\n      updated: number;\n      metadata: unknown;\n      weighted_score: number;\n    }>,\n    query: string,\n  ): SearchResult<T>[] {\n    const searchResults: SearchResult<T>[] = [];\n\n    for (const row of results) {\n      try {\n        const metadata: Record<string, unknown> =\n          typeof row.metadata === \"string\"\n            ? JSON.parse(row.metadata)\n            : (row.metadata as Record<string, unknown>);\n\n        const entity = this.serializer.reconstructEntity<T>({\n          id: row.id,\n          entityType: row.entityType,\n          content: row.content,\n          contentHash: row.contentHash,\n          visibility: row.visibility,\n          created: row.created,\n          updated: row.updated,\n          metadata,\n        });\n\n        searchResults.push({\n          entity,\n          score: row.weighted_score,\n          excerpt: this.createExcerpt(row.content, query),\n        });\n      } catch (error) {\n        this.logger.error(`Failed to parse entity during search: ${error}`);\n      }\n    }\n\n    const queryPreview =\n      query.length > 50 ? query.substring(0, 50) + \"...\" : query;\n    this.logger.debug(\n      `Found ${searchResults.length} results for query \"${queryPreview}\"`,\n    );\n\n    return searchResults;\n  }\n\n  /**\n   * Create an excerpt from content based on query\n   */\n  private createExcerpt(content: string, query: string): string {\n    const maxLength = 200;\n    const queryLower = query.toLowerCase();\n    const contentLower = content.toLowerCase();\n\n    // Find the position of the query in the content\n    const position = contentLower.indexOf(queryLower);\n\n    if (position !== -1) {\n      // Extract text around the query\n      const start = Math.max(0, position - 50);\n      const end = Math.min(content.length, position + queryLower.length + 50);\n      let excerpt = content.slice(start, end);\n\n      // Add ellipsis if needed\n      if (start > 0) excerpt = \"...\" + excerpt;\n      if (end < content.length) excerpt = excerpt + \"...\";\n\n      return excerpt;\n    }\n\n    // If query not found, return beginning of content\n    return (\n      content.slice(0, maxLength) + (content.length > maxLength ? \"...\" : \"\")\n    );\n  }\n}\n",
     "import matter from \"gray-matter\";\nimport { z } from \"@brains/utils\";\nimport type { BaseEntity, ContentVisibility } from \"./types\";\nimport { contentVisibilitySchema } from \"./types\";\n\n/**\n * Configuration for frontmatter handling\n */\nexport interface FrontmatterConfig<T extends BaseEntity> {\n  /**\n   * Fields to explicitly include in frontmatter\n   * If not specified, includes all non-system fields\n   */\n  includeFields?: (keyof T)[];\n\n  /**\n   * Fields to exclude from frontmatter\n   * By default excludes: id, entityType, content, created, updated\n   */\n  excludeFields?: (keyof T)[];\n\n  /**\n   * Custom serializers for complex fields\n   */\n  customSerializers?: {\n    [K in keyof T]?: (value: T[K]) => unknown;\n  };\n\n  /**\n   * Custom deserializers for complex fields\n   */\n  customDeserializers?: {\n    [K in keyof T]?: (value: unknown) => T[K];\n  };\n}\n\n// Default system fields that should not be in frontmatter\nconst DEFAULT_SYSTEM_FIELDS: Array<keyof BaseEntity> = [\n  \"id\",\n  \"entityType\",\n  \"content\",\n  \"contentHash\",\n  \"created\",\n  \"updated\",\n  \"visibility\",\n];\n\n/**\n * Extract metadata fields from an entity for frontmatter\n * Returns only non-system fields by default\n */\nexport function extractMetadata<T extends BaseEntity>(\n  entity: T,\n  config?: FrontmatterConfig<T>,\n): Record<string, unknown> {\n  const { includeFields, excludeFields = [], customSerializers } = config ?? {};\n  const excludedFieldNames = new Set<string>([\n    ...DEFAULT_SYSTEM_FIELDS.map(String),\n    ...excludeFields.map(String),\n  ]);\n\n  const metadata: Record<string, unknown> = {};\n\n  // Get all fields from the entity\n  const allFields = Object.keys(entity) as Array<keyof T>;\n\n  // Determine which fields to include\n  let fieldsToProcess: Array<keyof T>;\n  if (includeFields) {\n    // If includeFields is specified, only include those\n    fieldsToProcess = includeFields.filter(\n      (field) => !excludedFieldNames.has(String(field)),\n    );\n  } else {\n    // Otherwise include all fields except excluded ones\n    fieldsToProcess = allFields.filter(\n      (field) => !excludedFieldNames.has(String(field)),\n    );\n  }\n\n  // Process each field\n  for (const field of fieldsToProcess) {\n    const value = entity[field];\n\n    // Skip undefined values\n    if (value === undefined) {\n      continue;\n    }\n\n    // Use custom serializer if available\n    if (customSerializers && field in customSerializers) {\n      const serializer = customSerializers[field];\n      if (serializer) {\n        metadata[field as string] = serializer(value);\n      }\n    } else {\n      metadata[field as string] = value;\n    }\n  }\n\n  return metadata;\n}\n\n/**\n * Generate markdown with frontmatter from content and metadata\n */\nexport function generateMarkdownWithFrontmatter(\n  content: string,\n  metadata: Record<string, unknown>,\n): string {\n  // Only add frontmatter if there's metadata\n  if (Object.keys(metadata).length === 0) {\n    return content;\n  }\n\n  const cleaned = Object.fromEntries(\n    Object.entries(metadata).filter(([, v]) => v !== undefined),\n  );\n  return matter.stringify(content, cleaned);\n}\n\n/**\n * Helper to convert all Date objects to ISO strings recursively\n */\nfunction convertDatesToStrings(obj: unknown): unknown {\n  if (obj instanceof Date) {\n    return obj.toISOString();\n  }\n  if (Array.isArray(obj)) {\n    return obj.map(convertDatesToStrings);\n  }\n  if (obj !== null && typeof obj === \"object\") {\n    const result: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(obj)) {\n      result[key] = convertDatesToStrings(value);\n    }\n    return result;\n  }\n  return obj;\n}\n\n/**\n * Parse markdown with frontmatter into content and metadata\n */\nexport function parseMarkdownWithFrontmatter<T>(\n  markdown: string,\n  schema: z.ZodSchema<T>,\n): {\n  content: string;\n  metadata: T;\n} {\n  const { content, data } = matter(markdown);\n\n  // Convert all Date objects to strings before parsing with Zod\n  const normalizedData = convertDatesToStrings(data);\n\n  return {\n    content: content.trim(),\n    metadata: schema.parse(normalizedData),\n  };\n}\n\n/**\n * Apply custom deserializers to metadata\n */\nexport function deserializeMetadata<T extends BaseEntity>(\n  metadata: Record<string, unknown>,\n  config?: FrontmatterConfig<T>,\n): Record<string, unknown> {\n  if (!config?.customDeserializers) {\n    return metadata;\n  }\n\n  const result: Record<string, unknown> = { ...metadata };\n\n  for (const [field, deserializer] of Object.entries(\n    config.customDeserializers,\n  )) {\n    if (field in metadata) {\n      result[field] = deserializer(metadata[field]);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Generate frontmatter string from metadata\n */\nexport function generateFrontmatter(metadata: Record<string, unknown>): string {\n  if (Object.keys(metadata).length === 0) {\n    return \"\";\n  }\n\n  // Use gray-matter to generate frontmatter\n  const fullMarkdown = matter.stringify(\"\", metadata);\n\n  // Extract just the frontmatter part\n  const match = fullMarkdown.match(/^---\\n[\\s\\S]*?\\n---/);\n  return match ? match[0] : \"\";\n}\n\nconst visibilityFrontmatterSchema = z.object({\n  visibility: contentVisibilitySchema,\n});\n\nexport function extractVisibilityFromMarkdown(\n  markdown: string,\n): ContentVisibility {\n  const parsed = matter(markdown);\n  return visibilityFrontmatterSchema.parse(parsed.data).visibility;\n}\n\nexport function hasVisibilityFrontmatter(markdown: string): boolean {\n  const frontmatterMatch = markdown.match(/^---\\r?\\n[\\s\\S]*?\\r?\\n---/);\n  const visibilityMatch = frontmatterMatch?.[0].match(/^visibility:/m);\n  return visibilityMatch !== null && visibilityMatch !== undefined;\n}\n\nexport function applyVisibilityToMarkdown(\n  markdown: string,\n  visibility: ContentVisibility,\n): string {\n  if (visibility === \"public\" && !hasVisibilityFrontmatter(markdown)) {\n    return markdown;\n  }\n\n  const parsed = matter(markdown);\n  const frontmatter = Object.fromEntries(\n    Object.entries(parsed.data).filter(([key]) => key !== \"visibility\"),\n  );\n\n  if (visibility !== \"public\") {\n    frontmatter[\"visibility\"] = visibility;\n  }\n\n  return generateMarkdownWithFrontmatter(parsed.content.trim(), frontmatter);\n}\n",