@rizom/brain 0.2.0-alpha.149 → 0.2.0-alpha.151

package/dist/entities.d.ts

@@ -1,17 +1,15 @@
-import { z } from 'zod/v4';
-
+import { z } from "zod/v4";
+//#region ../../shell/entity-service/src/visibility.d.ts
 declare const canonicalContentVisibilitySchema: z.ZodEnum<{
-    public: "public";
-    shared: "shared";
-    restricted: "restricted";
+  public: "public";
+  shared: "shared";
+  restricted: "restricted";
 }>;
 type ContentVisibility = z.infer<typeof canonicalContentVisibilitySchema>;
 type RawContentVisibility = ContentVisibility | "private";
-declare const contentVisibilitySchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [
-    typeof canonicalContentVisibilitySchema,
-    z.ZodLiteral<"private">
-]>>, z.ZodTransform<ContentVisibility, RawContentVisibility | undefined>>;
-
+declare const contentVisibilitySchema: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [typeof canonicalContentVisibilitySchema, z.ZodLiteral<"private">]>>, z.ZodTransform<ContentVisibility, RawContentVisibility | undefined>>;
+//#endregion
+//#region ../../shell/entity-service/src/types.d.ts
 /**
  * Entity type for unstructured notes (the "note" entity type).
  * Used as a sentinel for the default catch-all markdown file shape —
@@ -22,61 +20,60 @@ declare const NOTE_ENTITY_TYPE = "note";
  * Options for entity mutation operations (create, update, upsert)
  */
 interface EntityMutationEventContext {
-    conversationId?: string;
-    channelId?: string;
-    runId?: string;
-    toolCallId?: string;
+  conversationId?: string;
+  channelId?: string;
+  runId?: string;
+  toolCallId?: string;
 }
 interface EntityJobOptions {
-    priority?: number;
-    maxRetries?: number;
-    eventContext?: EntityMutationEventContext;
+  priority?: number;
+  maxRetries?: number;
+  eventContext?: EntityMutationEventContext;
 }
-
 /**
  * Options for entity creation (extends EntityJobOptions with deduplication)
  */
 interface CreateEntityOptions extends EntityJobOptions {
-    deduplicateId?: boolean;
+  deduplicateId?: boolean;
 }
 /**
  * Result of an entity mutation that triggers an embedding job.
  * When skipped is true, content was unchanged — no DB write, no event, no embedding job.
  */
 interface EntityMutationResult {
-    entityId: string;
-    jobId: string;
-    skipped: boolean;
+  entityId: string;
+  jobId: string;
+  skipped: boolean;
 }
 /**
  * Input for adapter-validated direct creation from finalized markdown.
  */
 interface CreateEntityFromMarkdownInput {
-    entityType: string;
-    id: string;
-    markdown: string;
+  entityType: string;
+  id: string;
+  markdown: string;
 }
 /**
  * Data for storing an embedding for an entity
  */
 interface StoreEmbeddingData {
-    entityId: string;
-    entityType: string;
-    embedding: Float32Array;
-    contentHash: string;
+  entityId: string;
+  entityType: string;
+  embedding: Float32Array;
+  contentHash: string;
 }
 /**
  * Base entity schema that all entities must extend
  */
 declare const baseEntitySchema: z.ZodObject<{
-    id: z.ZodString;
-    entityType: z.ZodString;
-    content: z.ZodString;
-    created: z.ZodString;
-    updated: z.ZodString;
-    visibility: typeof contentVisibilitySchema;
-    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    contentHash: z.ZodString;
+  id: z.ZodString;
+  entityType: z.ZodString;
+  content: z.ZodString;
+  created: z.ZodString;
+  updated: z.ZodString;
+  visibility: typeof contentVisibilitySchema;
+  metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  contentHash: z.ZodString;
 }>;
 type EntitySchema<T> = z.ZodType<T, unknown>;
 /**
@@ -84,121 +81,121 @@ type EntitySchema<T> = z.ZodType<T, unknown>;
  * TMetadata defaults to Record<string, unknown> for backward compatibility
  */
 interface BaseEntity<TMetadata = Record<string, unknown>> {
-    id: string;
-    entityType: string;
-    content: string;
-    created: string;
-    updated: string;
-    visibility: ContentVisibility;
-    metadata: TMetadata;
-    /** SHA256 hash of content for change detection */
-    contentHash: string;
+  id: string;
+  entityType: string;
+  content: string;
+  created: string;
+  updated: string;
+  visibility: ContentVisibility;
+  metadata: TMetadata;
+  /** SHA256 hash of content for change detection */
+  contentHash: string;
 }
 /**
  * Entity input type for creation - allows partial entities with optional system fields
  * contentHash is excluded because it's computed automatically by the entity service
  */
 type EntityInput<T extends BaseEntity> = Omit<T, "id" | "created" | "updated" | "contentHash" | "visibility"> & {
-    id?: string;
-    created?: string;
-    updated?: string;
-    visibility?: RawContentVisibility;
+  id?: string;
+  created?: string;
+  updated?: string;
+  visibility?: RawContentVisibility;
 };
 /**
  * Search result type
  */
 interface SearchResult<T extends BaseEntity = BaseEntity> {
-    entity: T;
-    score: number;
-    excerpt: string;
+  entity: T;
+  score: number;
+  excerpt: string;
 }
 /**
  * Normalized system_create input shape used by plugin create interceptors.
  */
 interface CreateCoverImageInput {
-    generate?: boolean | undefined;
-    prompt?: string | undefined;
+  generate?: boolean | undefined;
+  prompt?: string | undefined;
 }
 interface CreateFromAttachmentInput {
-    kind: "entity-attachment";
-    sourceEntityType: string;
-    sourceEntityId: string;
-    attachmentType: string;
+  kind: "entity-attachment";
+  sourceEntityType: string;
+  sourceEntityId: string;
+  attachmentType: string;
 }
 interface CreateFromUploadInput {
-    kind: "upload";
-    id: string;
+  kind: "upload";
+  id: string;
 }
 interface CreateFromConversationMessageInput {
-    kind: "conversation-message";
-    messageId?: string | undefined;
+  kind: "conversation-message";
+  messageId?: string | undefined;
 }
 type CreateFromInput = CreateFromAttachmentInput | CreateFromUploadInput | CreateFromConversationMessageInput;
 type CreateTransform = "extract-markdown" | "preserve";
 interface CreateInput {
-    entityType: string;
-    prompt?: string;
-    title?: string;
-    content?: string;
-    url?: string;
-    from?: CreateFromInput;
-    transform?: CreateTransform;
-    replace?: boolean;
-    sourceEntityType?: string;
-    sourceEntityId?: string;
-    sourceEntityIds?: string[];
-    targetEntityType?: string;
-    targetEntityId?: string;
-    coverImage?: boolean | CreateCoverImageInput;
+  entityType: string;
+  prompt?: string;
+  title?: string;
+  content?: string;
+  url?: string;
+  from?: CreateFromInput;
+  transform?: CreateTransform;
+  replace?: boolean;
+  sourceEntityType?: string;
+  sourceEntityId?: string;
+  sourceEntityIds?: string[];
+  targetEntityType?: string;
+  targetEntityId?: string;
+  coverImage?: boolean | CreateCoverImageInput;
 }
 /**
  * Minimal caller context forwarded to plugin create interceptors.
  */
 interface CreateExecutionContext {
-    interfaceType: string;
-    userId: string;
-    channelId?: string;
-    channelName?: string;
+  interfaceType: string;
+  userId: string;
+  channelId?: string;
+  channelName?: string;
 }
 /**
  * Result returned to system_create when a plugin fully handles creation.
  */
 declare const createResultAttachmentSchema: z.ZodObject<{
-    mediaType: z.ZodString;
-    url: z.ZodString;
-    downloadUrl: z.ZodOptional<z.ZodString>;
-    previewUrl: z.ZodOptional<z.ZodString>;
-    filename: z.ZodOptional<z.ZodString>;
-    sizeBytes: z.ZodOptional<z.ZodNumber>;
-    source: z.ZodOptional<z.ZodObject<{
-        entityType: z.ZodOptional<z.ZodString>;
-        entityId: z.ZodOptional<z.ZodString>;
-        attachmentType: z.ZodOptional<z.ZodString>;
-    }>>;
+  mediaType: z.ZodString;
+  url: z.ZodString;
+  downloadUrl: z.ZodOptional<z.ZodString>;
+  previewUrl: z.ZodOptional<z.ZodString>;
+  filename: z.ZodOptional<z.ZodString>;
+  sizeBytes: z.ZodOptional<z.ZodNumber>;
+  source: z.ZodOptional<z.ZodObject<{
+    entityType: z.ZodOptional<z.ZodString>;
+    entityId: z.ZodOptional<z.ZodString>;
+    attachmentType: z.ZodOptional<z.ZodString>;
+  }>>;
 }>;
 type CreateResultAttachment = z.infer<typeof createResultAttachmentSchema>;
 type CreateResult = {
-    success: true;
-    data: {
-        entityId?: string;
-        jobId?: string;
-        status: string;
-        attachment?: CreateResultAttachment;
-    };
+  success: true;
+  data: {
+    entityId?: string;
+    jobId?: string;
+    status: string;
+    attachment?: CreateResultAttachment;
+  };
 } | {
-    success: false;
-    error: string;
+  success: false;
+  error: string;
 };
 /**
  * Plugin create interceptors can either fully handle creation,
  * or continue with a rewritten normalized input.
  */
 type CreateInterceptionResult = {
-    kind: "handled";
-    result: CreateResult;
+  kind: "handled";
+  result: CreateResult;
 } | {
-    kind: "continue";
-    input: CreateInput;
+  kind: "continue";
+  input: CreateInput;
 };
 type CreateInterceptor = (input: CreateInput, executionContext: CreateExecutionContext) => Promise<CreateInterceptionResult>;
 /**
@@ -209,177 +206,177 @@ type CreateInterceptor = (input: CreateInput, executionContext: CreateExecutionC
  * @template TMetadata - The metadata type (defaults to Record<string, unknown>)
  */
 interface EntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata = Record<string, unknown>> {
-    entityType: string;
-    /**
-     * One declarative sentence describing what this entity type is. This is the
-     * data the model reads to select `entityType`, replacing hardcoded example
-     * phrasings in system instructions. Required: every type must define itself.
-     */
-    purpose: string;
-    schema: EntitySchema<TEntity>;
-    toMarkdown(entity: TEntity): string;
-    fromMarkdown(markdown: string): Partial<TEntity>;
-    extractMetadata(entity: TEntity): TMetadata;
-    parseFrontMatter<TFrontmatter>(markdown: string, schema: {
-        parse(data: unknown): TFrontmatter;
-    }): TFrontmatter;
-    generateFrontMatter(entity: TEntity): string;
-    /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */
-    frontmatterSchema?: z.ZodObject<z.ZodRawShape>;
-    /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */
-    isSingleton?: boolean;
-    /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */
-    hasBody?: boolean;
-    /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */
-    getBodyTemplate(): string;
-    /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */
-    supportsCoverImage?: boolean;
-    /** Optional: Extract coverImageId from entity content/frontmatter */
-    getCoverImageId?(entity: TEntity): string | undefined;
-    /**
-     * Optional: build the markdown content and metadata for a queued-generation stub.
-     * When undefined, this entity type does not support prompt-based queued creation
-     * via system_create; the tool will reject the call rather than silently degrade.
-     * The returned metadata must satisfy this entity's metadata schema (with
-     * status set to "generating"); central code only stamps id/timestamps/visibility.
-     */
-    buildStub?(input: {
-        id: string;
-        title: string;
-    }): {
-        content: string;
-        metadata: TMetadata;
-    };
+  entityType: string;
+  /**
+   * One declarative sentence describing what this entity type is. This is the
+   * data the model reads to select `entityType`, replacing hardcoded example
+   * phrasings in system instructions. Required: every type must define itself.
+   */
+  purpose: string;
+  schema: EntitySchema<TEntity>;
+  toMarkdown(entity: TEntity): string;
+  fromMarkdown(markdown: string): Partial<TEntity>;
+  extractMetadata(entity: TEntity): TMetadata;
+  parseFrontMatter<TFrontmatter>(markdown: string, schema: {
+    parse(data: unknown): TFrontmatter;
+  }): TFrontmatter;
+  generateFrontMatter(entity: TEntity): string;
+  /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */
+  frontmatterSchema?: z.ZodObject<z.ZodRawShape>;
+  /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */
+  isSingleton?: boolean;
+  /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */
+  hasBody?: boolean;
+  /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */
+  getBodyTemplate(): string;
+  /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */
+  supportsCoverImage?: boolean;
+  /** Optional: Extract coverImageId from entity content/frontmatter */
+  getCoverImageId?(entity: TEntity): string | undefined;
+  /**
+   * Optional: build the markdown content and metadata for a queued-generation stub.
+   * When undefined, this entity type does not support prompt-based queued creation
+   * via system_create; the tool will reject the call rather than silently degrade.
+   * The returned metadata must satisfy this entity's metadata schema (with
+   * status set to "generating"); central code only stamps id/timestamps/visibility.
+   */
+  buildStub?(input: {
+    id: string;
+    title: string;
+  }): {
+    content: string;
+    metadata: TMetadata;
+  };
 }
 /**
  * Sort field specification for multi-field sorting
  */
 interface SortField {
-    /** Field to sort by - "created", "updated", or a metadata field name */
-    field: string;
-    /** Sort direction */
-    direction: "asc" | "desc";
-    /** Sort NULL values before non-NULL values (default: false / SQLite default) */
-    nullsFirst?: boolean;
+  /** Field to sort by - "created", "updated", or a metadata field name */
+  field: string;
+  /** Sort direction */
+  direction: "asc" | "desc";
+  /** Sort NULL values before non-NULL values (default: false / SQLite default) */
+  nullsFirst?: boolean;
 }
 /**
  * List entities options
  * Generic over metadata type for type-safe filtering
  */
 interface ListOptions<TMetadata = Record<string, unknown>> {
-    limit?: number;
-    offset?: number;
-    /** Multi-field sorting - supports system fields (created, updated) and metadata fields */
-    sortFields?: SortField[];
-    filter?: {
-        metadata?: Partial<TMetadata>;
-        visibilityScope?: ContentVisibility;
-    };
-    /** Filter to only entities with metadata.status = "published" */
-    publishedOnly?: boolean;
+  limit?: number;
+  offset?: number;
+  /** Multi-field sorting - supports system fields (created, updated) and metadata fields */
+  sortFields?: SortField[];
+  filter?: {
+    metadata?: Partial<TMetadata>;
+    visibilityScope?: ContentVisibility;
+  };
+  /** Filter to only entities with metadata.status = "published" */
+  publishedOnly?: boolean;
 }
 /**
  * Search options
  */
 interface SearchOptions {
-    limit?: number;
-    offset?: number;
-    types?: string[];
-    excludeTypes?: string[];
-    sortBy?: "relevance" | "created" | "updated";
-    sortDirection?: "asc" | "desc";
-    /** Score multipliers per entity type - applied after initial search */
-    weight?: Record<string, number>;
-    visibilityScope?: ContentVisibility;
-    /** Include queued/failed generation stubs in search results (default: false) */
-    includeUngenerated?: boolean;
-    /** Minimum relevance score to return. Omit for no score cutoff. */
-    minScore?: number;
+  limit?: number;
+  offset?: number;
+  types?: string[];
+  excludeTypes?: string[];
+  sortBy?: "relevance" | "created" | "updated";
+  sortDirection?: "asc" | "desc";
+  /** Score multipliers per entity type - applied after initial search */
+  weight?: Record<string, number>;
+  visibilityScope?: ContentVisibility;
+  /** Include queued/failed generation stubs in search results (default: false) */
+  includeUngenerated?: boolean;
+  /** Minimum relevance score to return. Omit for no score cutoff. */
+  minScore?: number;
 }
 /**
  * Configuration for entity type registration
  */
 interface EntityTypeConfig {
-    /** Score multiplier for search results (default: 1.0) */
-    weight?: number;
-    /** Whether to generate embeddings for this entity type (default: true).
-     *  Set to false for entity types with non-textual content (e.g., images). */
-    embeddable?: boolean;
-    /** Whether this entity type may be used as source material for derived projections (default: true).
-     *  Set to false for projection outputs that would create feedback loops. */
-    projectionSource?: boolean;
-    /** Publish semantics for status-bearing entity types. Statuses listed here
-     *  represent publication commitment/execution states and require the
-     *  `publish` entity action when entered or modified. */
-    publish?: {
-        publishStatuses: string[];
-    };
+  /** Score multiplier for search results (default: 1.0) */
+  weight?: number;
+  /** Whether to generate embeddings for this entity type (default: true).
+   *  Set to false for entity types with non-textual content (e.g., images). */
+  embeddable?: boolean;
+  /** Whether this entity type may be used as source material for derived projections (default: true).
+   *  Set to false for projection outputs that would create feedback loops. */
+  projectionSource?: boolean;
+  /** Publish semantics for status-bearing entity types. Statuses listed here
+   *  represent publication commitment/execution states and require the
+   *  `publish` entity action when entered or modified. */
+  publish?: {
+    publishStatuses: string[];
+  };
 }
 /**
  * Core entity service interface for read-only operations
  * Used by core plugins that need entity access but shouldn't modify entities
  */
 interface GetEntityRequest {
-    entityType: string;
-    id: string;
-    /**
-     * Optional visibility scope. Undefined fails closed to "public" — callers
-     * with elevated access must opt up explicitly.
-     */
-    visibilityScope?: ContentVisibility;
+  entityType: string;
+  id: string;
+  /**
+   * Optional visibility scope. Undefined fails closed to "public" — callers
+   * with elevated access must opt up explicitly.
+   */
+  visibilityScope?: ContentVisibility;
 }
 type GetEntityRawRequest = GetEntityRequest;
 interface ListEntitiesRequest {
-    entityType: string;
-    options?: ListOptions | undefined;
+  entityType: string;
+  options?: ListOptions | undefined;
 }
 interface CountEntitiesRequest {
-    entityType: string;
-    options?: Pick<ListOptions, "publishedOnly" | "filter"> | undefined;
+  entityType: string;
+  options?: Pick<ListOptions, "publishedOnly" | "filter"> | undefined;
 }
 interface CreateEntityRequest<T extends BaseEntity> {
-    entity: EntityInput<T>;
-    options?: CreateEntityOptions | undefined;
+  entity: EntityInput<T>;
+  options?: CreateEntityOptions | undefined;
 }
 interface CreateEntityFromMarkdownRequest {
-    input: CreateEntityFromMarkdownInput;
-    options?: CreateEntityOptions | undefined;
+  input: CreateEntityFromMarkdownInput;
+  options?: CreateEntityOptions | undefined;
 }
 interface UpdateEntityRequest<T extends BaseEntity> {
-    entity: T;
-    options?: EntityJobOptions | undefined;
+  entity: T;
+  options?: EntityJobOptions | undefined;
 }
 interface DeleteEntityRequest {
-    entityType: string;
-    id: string;
+  entityType: string;
+  id: string;
 }
 interface UpsertEntityRequest<T extends BaseEntity> {
-    entity: T;
-    options?: EntityJobOptions | undefined;
+  entity: T;
+  options?: EntityJobOptions | undefined;
 }
 interface EntitySearchRequest {
-    query: string;
-    options?: SearchOptions | undefined;
+  query: string;
+  options?: SearchOptions | undefined;
 }
 interface SearchWithDistancesRequest {
-    query: string;
+  query: string;
 }
 /**
  * Context passed to all DataSource operations
  * Contains internal state that should not be mixed with user query parameters
  */
 interface BaseDataSourceContext {
-    /**
-     * Whether to filter to only published/complete content
-     * Set by site-builder: true for production, false for preview
-     */
-    publishedOnly?: boolean;
-    /**
-     * Scoped entity service that auto-applies publishedOnly filter
-     * Datasources should use this instead of their injected entityService
-     * to ensure consistent filtering behavior across environments
-     */
-    entityService: EntityService;
+  /**
+   * Whether to filter to only published/complete content
+   * Set by site-builder: true for production, false for preview
+   */
+  publishedOnly?: boolean;
+  /**
+   * Scoped entity service that auto-applies publishedOnly filter
+   * Datasources should use this instead of their injected entityService
+   * to ensure consistent filtering behavior across environments
+   */
+  entityService: EntityService;
 }
 /**
  * DataSource Interface
@@ -389,138 +386,137 @@ interface BaseDataSourceContext {
  * via their dataSourceId property.
  */
 interface DataSource {
-    /**
-     * Unique identifier for this data source
-     */
-    id: string;
-    /**
-     * Human-readable name for this data source
-     */
-    name: string;
-    /**
-     * Optional description of what this data source provides
-     */
-    description?: string;
-    /**
-     * Optional: Fetch existing data
-     * Used by data sources that aggregate or retrieve data (e.g., dashboard stats, API data)
-     * DataSources validate output using the provided schema
-     * @param query - Query parameters for fetching data
-     * @param outputSchema - Schema for validating output data
-     * @param context - Context with environment
-     */
-    fetch?: <T>(query: unknown, outputSchema: z.ZodSchema<T>, context: BaseDataSourceContext) => Promise<T>;
-    /**
-     * Optional: Generate new content
-     * Used by data sources that create content (e.g., AI-generated content, reports)
-     */
-    generate?: <T>(request: unknown, schema: z.ZodSchema<T>) => Promise<T>;
-    /**
-     * Optional: Transform content between formats
-     * Used by data sources that convert content (e.g., markdown to HTML, data formatting)
-     */
-    transform?: <T>(content: unknown, format: string, schema: z.ZodSchema<T>) => Promise<T>;
+  /**
+   * Unique identifier for this data source
+   */
+  id: string;
+  /**
+   * Human-readable name for this data source
+   */
+  name: string;
+  /**
+   * Optional description of what this data source provides
+   */
+  description?: string;
+  /**
+   * Optional: Fetch existing data
+   * Used by data sources that aggregate or retrieve data (e.g., dashboard stats, API data)
+   * DataSources validate output using the provided schema
+   * @param query - Query parameters for fetching data
+   * @param outputSchema - Schema for validating output data
+   * @param context - Context with environment
+   */
+  fetch?: <T>(query: unknown, outputSchema: z.ZodSchema<T>, context: BaseDataSourceContext) => Promise<T>;
+  /**
+   * Optional: Generate new content
+   * Used by data sources that create content (e.g., AI-generated content, reports)
+   */
+  generate?: <T>(request: unknown, schema: z.ZodSchema<T>) => Promise<T>;
+  /**
+   * Optional: Transform content between formats
+   * Used by data sources that convert content (e.g., markdown to HTML, data formatting)
+   */
+  transform?: <T>(content: unknown, format: string, schema: z.ZodSchema<T>) => Promise<T>;
 }
 /**
  * DataSource capabilities for discovery and validation
  */
 interface DataSourceCapabilities {
-    canFetch: boolean;
-    canGenerate: boolean;
-    canTransform: boolean;
+  canFetch: boolean;
+  canGenerate: boolean;
+  canTransform: boolean;
 }
 interface ICoreEntityService {
-    getEntity<T extends BaseEntity>(request: GetEntityRequest): Promise<T | null>;
-    /**
-     * Get entity without content resolution (raw)
-     * Used internally to avoid recursion when resolving image references
-     */
-    getEntityRaw<T extends BaseEntity>(request: GetEntityRawRequest): Promise<T | null>;
-    listEntities<T extends BaseEntity>(request: ListEntitiesRequest): Promise<T[]>;
-    search<T extends BaseEntity = BaseEntity>(request: EntitySearchRequest): Promise<SearchResult<T>[]>;
-    getEntityTypes(): string[];
-    hasEntityType(type: string): boolean;
-    countEntities(request: CountEntitiesRequest): Promise<number>;
-    /**
-     * Group counts by entity type. Fails closed: undefined visibilityScope
-     * filters to public-only counts so aggregate insights cannot reveal
-     * non-public entity existence.
-     */
-    getEntityCounts(visibilityScope?: ContentVisibility): Promise<Array<{
-        entityType: string;
-        count: number;
-    }>>;
-    /** Get configuration for a specific entity type */
-    getEntityTypeConfig(type: string): EntityTypeConfig;
-    /** Get weight map for all registered entity types with non-default weights */
-    getWeightMap(): Record<string, number>;
+  getEntity<T extends BaseEntity>(request: GetEntityRequest): Promise<T | null>;
+  /**
+   * Get entity without content resolution (raw)
+   * Used internally to avoid recursion when resolving image references
+   */
+  getEntityRaw<T extends BaseEntity>(request: GetEntityRawRequest): Promise<T | null>;
+  listEntities<T extends BaseEntity>(request: ListEntitiesRequest): Promise<T[]>;
+  search<T extends BaseEntity = BaseEntity>(request: EntitySearchRequest): Promise<SearchResult<T>[]>;
+  getEntityTypes(): string[];
+  hasEntityType(type: string): boolean;
+  countEntities(request: CountEntitiesRequest): Promise<number>;
+  /**
+   * Group counts by entity type. Fails closed: undefined visibilityScope
+   * filters to public-only counts so aggregate insights cannot reveal
+   * non-public entity existence.
+   */
+  getEntityCounts(visibilityScope?: ContentVisibility): Promise<Array<{
+    entityType: string;
+    count: number;
+  }>>;
+  /** Get configuration for a specific entity type */
+  getEntityTypeConfig(type: string): EntityTypeConfig;
+  /** Get weight map for all registered entity types with non-default weights */
+  getWeightMap(): Record<string, number>;
 }
 interface EmbeddingBackfillResult {
-    queued: number;
-    skipped: number;
+  queued: number;
+  skipped: number;
 }
 interface EmbeddingIndexStats {
-    missingEmbeddings: number;
-    staleEmbeddings: number;
-    failedEmbeddings: number;
-    /** Entities whose type generates embeddings (non-embeddable types excluded). */
-    embeddableEntities: number;
-    /** Embeddable entities whose embedding is present and current. */
-    embeddedEntities: number;
+  missingEmbeddings: number;
+  staleEmbeddings: number;
+  failedEmbeddings: number;
+  /** Entities whose type generates embeddings (non-embeddable types excluded). */
+  embeddableEntities: number;
+  /** Embeddable entities whose embedding is present and current. */
+  embeddedEntities: number;
 }
 interface IndexReadinessOptions {
-    timeoutMs: number;
-    intervalMs?: number;
+  timeoutMs: number;
+  intervalMs?: number;
 }
 interface IndexReadinessStatus extends EmbeddingIndexStats {
-    ready: boolean;
-    degraded: boolean;
-    activeEmbeddingJobs: number;
+  ready: boolean;
+  degraded: boolean;
+  activeEmbeddingJobs: number;
 }
 interface EntityService extends ICoreEntityService {
-    createEntity<T extends BaseEntity>(request: CreateEntityRequest<T>): Promise<EntityMutationResult>;
-    createEntityFromMarkdown(request: CreateEntityFromMarkdownRequest): Promise<EntityMutationResult>;
-    updateEntity<T extends BaseEntity>(request: UpdateEntityRequest<T>): Promise<EntityMutationResult>;
-    deleteEntity(request: DeleteEntityRequest): Promise<boolean>;
-    upsertEntity<T extends BaseEntity>(request: UpsertEntityRequest<T>): Promise<EntityMutationResult & {
-        created: boolean;
-    }>;
-    storeEmbedding(data: StoreEmbeddingData): Promise<void>;
-    backfillMissingEmbeddings(): Promise<EmbeddingBackfillResult>;
-    isIndexReady(): boolean;
-    awaitIndexReady(options: IndexReadinessOptions): Promise<IndexReadinessStatus>;
-    serializeEntity(entity: BaseEntity): string;
-    deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;
-    countEmbeddings(): Promise<number>;
-    searchWithDistances(request: SearchWithDistancesRequest): Promise<Array<{
-        entityId: string;
-        entityType: string;
-        distance: number;
-    }>>;
-    initialize(): Promise<void>;
-    getAsyncJobStatus(jobId: string): Promise<{
-        status: "pending" | "processing" | "completed" | "failed";
-        error?: string;
-    } | null>;
-}
-
+  createEntity<T extends BaseEntity>(request: CreateEntityRequest<T>): Promise<EntityMutationResult>;
+  createEntityFromMarkdown(request: CreateEntityFromMarkdownRequest): Promise<EntityMutationResult>;
+  updateEntity<T extends BaseEntity>(request: UpdateEntityRequest<T>): Promise<EntityMutationResult>;
+  deleteEntity(request: DeleteEntityRequest): Promise<boolean>;
+  upsertEntity<T extends BaseEntity>(request: UpsertEntityRequest<T>): Promise<EntityMutationResult & {
+    created: boolean;
+  }>;
+  storeEmbedding(data: StoreEmbeddingData): Promise<void>;
+  backfillMissingEmbeddings(): Promise<EmbeddingBackfillResult>;
+  isIndexReady(): boolean;
+  awaitIndexReady(options: IndexReadinessOptions): Promise<IndexReadinessStatus>;
+  serializeEntity(entity: BaseEntity): string;
+  deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;
+  countEmbeddings(): Promise<number>;
+  searchWithDistances(request: SearchWithDistancesRequest): Promise<Array<{
+    entityId: string;
+    entityType: string;
+    distance: number;
+  }>>;
+  initialize(): Promise<void>;
+  getAsyncJobStatus(jobId: string): Promise<{
+    status: "pending" | "processing" | "completed" | "failed";
+    error?: string;
+  } | null>;
+}
+//#endregion
+//#region ../../shell/entity-service/src/adapters/base-entity-adapter.d.ts
 /** Interface for objects that can generate a body template. */
 interface BodyTemplateProvider {
-    generateBodyTemplate(): string;
+  generateBodyTemplate(): string;
 }
-type DefaultEntityFrontmatter<TMetadata extends object> = {
-    [K in keyof TMetadata]?: TMetadata[K] | undefined;
-};
+type DefaultEntityFrontmatter<TMetadata extends object> = { [K in keyof TMetadata]?: TMetadata[K] | undefined; };
 type BaseEntityFrontmatterSchema<TFrontmatter> = z.ZodObject<z.ZodRawShape> & z.ZodType<TFrontmatter>;
 interface BaseEntityAdapterConfig<TEntity extends BaseEntity<TMetadata>, TMetadata extends object, TFrontmatter = DefaultEntityFrontmatter<TMetadata>> {
-    entityType: string;
-    purpose: string;
-    schema: EntitySchema<TEntity>;
-    frontmatterSchema: BaseEntityFrontmatterSchema<TFrontmatter>;
-    isSingleton?: boolean;
-    hasBody?: boolean;
-    supportsCoverImage?: boolean;
-    bodyFormatter?: BodyTemplateProvider;
+  entityType: string;
+  purpose: string;
+  schema: EntitySchema<TEntity>;
+  frontmatterSchema: BaseEntityFrontmatterSchema<TFrontmatter>;
+  isSingleton?: boolean;
+  hasBody?: boolean;
+  supportsCoverImage?: boolean;
+  bodyFormatter?: BodyTemplateProvider;
 }
 /**
  * Abstract base class for entity adapters.
@@ -532,82 +528,79 @@ interface BaseEntityAdapterConfig<TEntity extends BaseEntity<TMetadata>, TMetada
  * Subclasses must implement toMarkdown() and fromMarkdown().
  */
 declare abstract class BaseEntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata extends object = Record<string, unknown>, TFrontmatter = DefaultEntityFrontmatter<TMetadata>> implements EntityAdapter<TEntity, TMetadata> {
-    readonly entityType: string;
-    readonly purpose: string;
-    readonly schema: EntitySchema<TEntity>;
-    readonly frontmatterSchema: z.ZodObject<z.ZodRawShape>;
-    readonly isSingleton?: boolean;
-    readonly hasBody?: boolean;
-    readonly supportsCoverImage?: boolean;
-    private readonly fmSchema;
-    private readonly bodyFormatter;
-    constructor(config: BaseEntityAdapterConfig<TEntity, TMetadata, TFrontmatter>);
-    abstract fromMarkdown(markdown: string): Partial<TEntity>;
-    /**
-     * Serialize an entity to markdown.
-     *
-     * Rebuilds frontmatter from entity.metadata overlaid on any existing
-     * frontmatter parsed from entity.content. Body comes from renderBody,
-     * which defaults to the body portion of entity.content (frontmatter
-     * stripped).
-     *
-     * Adapters that want the body to reflect typed fields (e.g. a
-     * structured about/skills section) override renderBody. Adapters that
-     * need entirely custom serialization override toMarkdown.
-     */
-    toMarkdown(entity: TEntity): string;
-    /**
-     * Render the body section of the entity.
-     *
-     * Default returns the body portion of entity.content (frontmatter
-     * stripped). Override when the body should be rebuilt from typed
-     * fields on the entity.
-     */
-    protected renderBody(entity: TEntity): string;
-    private readExistingFrontmatter;
-    extractMetadata(entity: TEntity): TMetadata;
-    parseFrontMatter<T>(markdown: string, schema: {
-        parse(data: unknown): T;
-    }): T;
-    getBodyTemplate(): string;
-    generateFrontMatter(entity: TEntity): string;
-    /** Strip frontmatter and return the body content. */
-    protected extractBody(markdown: string): string;
-    /** Parse frontmatter using this adapter's frontmatter schema. */
-    protected parseFrontmatter(markdown: string): TFrontmatter;
-    /** Combine body and frontmatter into a markdown string. */
-    protected buildMarkdown(body: string, frontmatter: Record<string, unknown>): string;
-}
-
+  readonly entityType: string;
+  readonly purpose: string;
+  readonly schema: EntitySchema<TEntity>;
+  readonly frontmatterSchema: z.ZodObject<z.ZodRawShape>;
+  readonly isSingleton?: boolean;
+  readonly hasBody?: boolean;
+  readonly supportsCoverImage?: boolean;
+  private readonly fmSchema;
+  private readonly bodyFormatter;
+  constructor(config: BaseEntityAdapterConfig<TEntity, TMetadata, TFrontmatter>);
+  abstract fromMarkdown(markdown: string): Partial<TEntity>;
+  /**
+   * Serialize an entity to markdown.
+   *
+   * Rebuilds frontmatter from entity.metadata overlaid on any existing
+   * frontmatter parsed from entity.content. Body comes from renderBody,
+   * which defaults to the body portion of entity.content (frontmatter
+   * stripped).
+   *
+   * Adapters that want the body to reflect typed fields (e.g. a
+   * structured about/skills section) override renderBody. Adapters that
+   * need entirely custom serialization override toMarkdown.
+   */
+  toMarkdown(entity: TEntity): string;
+  /**
+   * Render the body section of the entity.
+   *
+   * Default returns the body portion of entity.content (frontmatter
+   * stripped). Override when the body should be rebuilt from typed
+   * fields on the entity.
+   */
+  protected renderBody(entity: TEntity): string;
+  private readExistingFrontmatter;
+  extractMetadata(entity: TEntity): TMetadata;
+  parseFrontMatter<T>(markdown: string, schema: {
+    parse(data: unknown): T;
+  }): T;
+  getBodyTemplate(): string;
+  generateFrontMatter(entity: TEntity): string;
+  /** Strip frontmatter and return the body content. */
+  protected extractBody(markdown: string): string;
+  /** Parse frontmatter using this adapter's frontmatter schema. */
+  protected parseFrontmatter(markdown: string): TFrontmatter;
+  /** Combine body and frontmatter into a markdown string. */
+  protected buildMarkdown(body: string, frontmatter: Record<string, unknown>): string;
+}
+//#endregion
+//#region ../../shell/entity-service/src/frontmatter.d.ts
 /**
  * Configuration for frontmatter handling
  */
 interface FrontmatterConfig<T extends BaseEntity> {
-    /**
-     * Fields to explicitly include in frontmatter
-     * If not specified, includes all non-system fields
-     */
-    includeFields?: (keyof T)[];
-    /**
-     * Fields to exclude from frontmatter
-     * By default excludes: id, entityType, content, created, updated
-     */
-    excludeFields?: (keyof T)[];
-    /**
-     * Custom serializers for complex fields
-     */
-    customSerializers?: {
-        [K in keyof T]?: (value: T[K]) => unknown;
-    };
-    /**
-     * Custom deserializers for complex fields
-     */
-    customDeserializers?: {
-        [K in keyof T]?: (value: unknown) => T[K];
-    };
+  /**
+   * Fields to explicitly include in frontmatter
+   * If not specified, includes all non-system fields
+   */
+  includeFields?: (keyof T)[];
+  /**
+   * Fields to exclude from frontmatter
+   * By default excludes: id, entityType, content, created, updated
+   */
+  excludeFields?: (keyof T)[];
+  /**
+   * Custom serializers for complex fields
+   */
+  customSerializers?: { [K in keyof T]?: (value: T[K]) => unknown; };
+  /**
+   * Custom deserializers for complex fields
+   */
+  customDeserializers?: { [K in keyof T]?: (value: unknown) => T[K]; };
 }
 interface FrontmatterValidationSchema<T> {
-    parse(data: unknown): T;
+  parse(data: unknown): T;
 }
 /**
  * Generate markdown with frontmatter from content and metadata
@@ -617,25 +610,26 @@ declare function generateMarkdownWithFrontmatter(content: string, metadata: Reco
  * Parse markdown with frontmatter into content and metadata
  */
 declare function parseMarkdownWithFrontmatter<T>(markdown: string, schema: FrontmatterValidationSchema<T>): {
-    content: string;
-    metadata: T;
+  content: string;
+  metadata: T;
 };
 /**
  * Generate frontmatter string from metadata
  */
 declare function generateFrontmatter(metadata: Record<string, unknown>): string;
-
+//#endregion
+//#region ../../shell/entity-service/src/pagination.d.ts
 /**
  * Schema for pagination information
  * Used by datasources that return paginated lists
  */
 declare const paginationInfoSchema: z.ZodObject<{
-    currentPage: z.ZodNumber;
-    totalPages: z.ZodNumber;
-    totalItems: z.ZodNumber;
-    pageSize: z.ZodNumber;
-    hasNextPage: z.ZodBoolean;
-    hasPrevPage: z.ZodBoolean;
+  currentPage: z.ZodNumber;
+  totalPages: z.ZodNumber;
+  totalItems: z.ZodNumber;
+  pageSize: z.ZodNumber;
+  hasNextPage: z.ZodBoolean;
+  hasPrevPage: z.ZodBoolean;
 }>;
 /**
  * Pagination information type
@@ -650,16 +644,16 @@ declare function buildPaginationInfo(totalItems: number, page: number, pageSize:
  * Options for paginating items
  */
 interface PaginateOptions {
-    page?: number | undefined;
-    limit?: number | undefined;
-    pageSize?: number | undefined;
+  page?: number | undefined;
+  limit?: number | undefined;
+  pageSize?: number | undefined;
 }
 /**
  * Result of paginating items
  */
 interface PaginateResult<T> {
-    items: T[];
-    pagination: PaginationInfo | null;
+  items: T[];
+  pagination: PaginationInfo | null;
 }
 /**
  * Paginate a list of items
@@ -673,6 +667,5 @@ interface PaginateResult<T> {
  * @returns Paginated items and optional pagination info
  */
 declare function paginateItems<T>(items: T[], options: PaginateOptions): PaginateResult<T>;
-
-export { BaseEntityAdapter, NOTE_ENTITY_TYPE, baseEntitySchema, buildPaginationInfo, generateFrontmatter, generateMarkdownWithFrontmatter, paginateItems, paginationInfoSchema, parseMarkdownWithFrontmatter };
-export type { BaseDataSourceContext, BaseEntity, CreateExecutionContext, CreateInput, CreateInterceptionResult, CreateInterceptor, CreateResult, DataSource, DataSourceCapabilities, EntityAdapter, EntityInput, EntityMutationResult, EntityTypeConfig, FrontmatterConfig, ListOptions, PaginateOptions, PaginateResult, PaginationInfo, SearchOptions, SearchResult };
+//#endregion
+export { type BaseDataSourceContext, type BaseEntity, BaseEntityAdapter, type CreateExecutionContext, type CreateInput, type CreateInterceptionResult, type CreateInterceptor, type CreateResult, type DataSource, type DataSourceCapabilities, type EntityAdapter, type EntityInput, type EntityMutationResult, type EntityTypeConfig, type FrontmatterConfig, type ListOptions, NOTE_ENTITY_TYPE, type PaginateOptions, type PaginateResult, type PaginationInfo, type SearchOptions, type SearchResult, baseEntitySchema, buildPaginationInfo, generateFrontmatter, generateMarkdownWithFrontmatter, paginateItems, paginationInfoSchema, parseMarkdownWithFrontmatter };