@rizom/brain 0.2.0-alpha.130 → 0.2.0-alpha.132

package/dist/plugins.js.map

@@ -268,7 +268,7 @@
     "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 \"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 EntityMutationEventContext {\n  conversationId?: string;\n  channelId?: string;\n  runId?: string;\n  toolCallId?: string;\n}\n\nexport interface EntityJobOptions {\n  priority?: number;\n  maxRetries?: number;\n  eventContext?: EntityMutationEventContext;\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 interface CreateFromConversationMessageInput {\n  kind: \"conversation-message\";\n  messageId?: string | undefined;\n}\n\nexport type CreateFromInput =\n  | CreateFromAttachmentInput\n  | CreateFromUploadInput\n  | CreateFromConversationMessageInput;\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\n  /**\n   * One declarative sentence describing what this entity type is. This is the\n   * data the model reads to select `entityType`, replacing hardcoded example\n   * phrasings in system instructions. Required: every type must define itself.\n   */\n  purpose: string;\n\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 EmbeddingBackfillResult {\n  queued: number;\n  skipped: number;\n}\n\nexport interface EmbeddingFailureReference {\n  entityId: string;\n  entityType: string;\n  contentHash: string;\n}\n\nexport interface EmbeddingIndexStats {\n  missingEmbeddings: number;\n  staleEmbeddings: number;\n  failedEmbeddings: number;\n}\n\nexport interface IndexReadinessOptions {\n  timeoutMs: number;\n  intervalMs?: number;\n}\n\nexport interface IndexReadinessStatus extends EmbeddingIndexStats {\n  ready: boolean;\n  degraded: boolean;\n  activeEmbeddingJobs: number;\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  backfillMissingEmbeddings(): Promise<EmbeddingBackfillResult>;\n  isIndexReady(): boolean;\n  awaitIndexReady(\n    options: IndexReadinessOptions,\n  ): Promise<IndexReadinessStatus>;\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 EntityMutationEventContext {\n  conversationId?: string;\n  channelId?: string;\n  runId?: string;\n  toolCallId?: string;\n}\n\nexport interface EntityJobOptions {\n  priority?: number;\n  maxRetries?: number;\n  eventContext?: EntityMutationEventContext;\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 interface CreateFromConversationMessageInput {\n  kind: \"conversation-message\";\n  messageId?: string | undefined;\n}\n\nexport type CreateFromInput =\n  | CreateFromAttachmentInput\n  | CreateFromUploadInput\n  | CreateFromConversationMessageInput;\n\nexport type CreateTransform = \"extract-markdown\" | \"preserve\";\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\n  /**\n   * One declarative sentence describing what this entity type is. This is the\n   * data the model reads to select `entityType`, replacing hardcoded example\n   * phrasings in system instructions. Required: every type must define itself.\n   */\n  purpose: string;\n\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 EmbeddingBackfillResult {\n  queued: number;\n  skipped: number;\n}\n\nexport interface EmbeddingFailureReference {\n  entityId: string;\n  entityType: string;\n  contentHash: string;\n}\n\nexport interface EmbeddingIndexStats {\n  missingEmbeddings: number;\n  staleEmbeddings: number;\n  failedEmbeddings: number;\n}\n\nexport interface IndexReadinessOptions {\n  timeoutMs: number;\n  intervalMs?: number;\n}\n\nexport interface IndexReadinessStatus extends EmbeddingIndexStats {\n  ready: boolean;\n  degraded: boolean;\n  activeEmbeddingJobs: number;\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  backfillMissingEmbeddings(): Promise<EmbeddingBackfillResult>;\n  isIndexReady(): boolean;\n  awaitIndexReady(\n    options: IndexReadinessOptions,\n  ): Promise<IndexReadinessStatus>;\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",