feat: export provider contracts for the plugin surface brainy consumes

Native accelerators (cortex) register providers for metadataIndex, graphIndex,
hnsw, entityIdMapper, cache, columnStore, and aggregation. Until now the exact
method/property surface brainy calls on each was implicit — a provider could
drop a member brainy depends on and only fail at runtime when that path ran.

This defines and exports the provider contracts from the stable
@soulcraft/brainy/plugin entrypoint:
- MetadataIndexProvider, GraphIndexProvider, HnswProvider,
  EntityIdMapperProvider, CacheProvider — each typed as exactly the surface
  brainy calls (optional/feature-detected members like HNSW setPersistMode and
  enableCOW are intentionally excluded).
- Re-exports ColumnStoreProvider and AggregationProvider (and the aggregate
  types) from the same entrypoint so a plugin author can import the whole
  provider surface from one place.

Brainy's own baseline classes now `implements` these contracts
(MetadataIndexManager, GraphAdjacencyIndex, HNSWIndex, EntityIdMapper,
UnifiedCache), so the interfaces can never silently diverge from what brainy
ships — and any provider that declares `implements` gets a compile error the
moment brainy starts requiring a new member.

The embeddings/embedBatch providers stay typed by the existing EmbeddingFunction
(no duplicate interface added). Type-only changes; no runtime behavior change.

src/plugin.ts

@@ -8,7 +8,28 @@
  * Plugins are auto-detected by package name or registered manually.
  */
 
-import type { StorageAdapter } from './coreTypes.js'
+import type {
+  StorageAdapter,
+  Vector,
+  VectorDocument,
+  GraphVerb,
+} from './coreTypes.js'
+import type { NounType, VerbType } from './types/graphTypes.js'
+import type { MetadataIndexStats } from './utils/metadataIndex.js'
+import type { GraphIndexStats } from './graph/graphAdjacencyIndex.js'
+
+// Re-export the provider contracts that already live closer to their
+// implementations so a plugin author (Cortex) can import the *entire*
+// provider surface from one stable entrypoint: `@soulcraft/brainy/plugin`.
+export type { ColumnStoreProvider } from './indexes/columnStore/types.js'
+export type {
+  AggregationProvider,
+  AggregateDefinition,
+  AggregateGroupState,
+  AggregateResult,
+  AggregateQueryParams,
+  GroupByDimension,
+} from './types/brainy.types.js'
 
 /**
  * Plugin interface — all brainy plugins must implement this.
@@ -58,6 +79,180 @@ export interface BrainyPluginContext {
   readonly version: string
 }
 
+// ===========================================================================
+// Provider contracts — the EXACT surface Brainy calls on each registered
+// provider.
+//
+// These interfaces are the type-level half of the provider-parity guarantee.
+// They capture only what Brainy actually invokes, so a native accelerator
+// (Cortex) that declares `implements MetadataIndexProvider` gets a compile
+// error the moment a method Brainy depends on is dropped or its signature
+// drifts. Brainy's own baseline classes (`MetadataIndexManager`,
+// `GraphAdjacencyIndex`, `HNSWIndex`, `EntityIdMapper`, `UnifiedCache`)
+// implement them too, so the contract can never silently diverge from the
+// thing Brainy ships.
+//
+// Keep these in lockstep with the call sites in `brainy.ts` and the index
+// classes. When Brainy starts calling a new member, add it here — every
+// implementation then fails to compile until it provides the member.
+// ===========================================================================
+
+/**
+ * The `'metadataIndex'` provider — a drop-in for `MetadataIndexManager`.
+ * Brainy calls this surface via `this.metadataIndex.*` (see `brainy.ts`) and
+ * the transactional add/remove operations.
+ */
+export interface MetadataIndexProvider {
+  init(): Promise<void>
+  flush(): Promise<void>
+  rebuild(): Promise<void>
+
+  addToIndex(id: string, entityOrMetadata: any, skipFlush?: boolean, deferWrites?: boolean): Promise<void>
+  removeFromIndex(id: string, metadata?: any): Promise<void>
+
+  getIds(field: string, value: any): Promise<string[]>
+  getIdsForFilter(filter: any): Promise<string[]>
+  getIdsForTextQuery(query: string): Promise<Array<{ id: string; matchCount: number }>>
+  getSortedIdsForFilter(filter: any, orderBy: string, order?: 'asc' | 'desc'): Promise<string[]>
+  getFilterValues(field: string): Promise<string[]>
+  getFilterFields(): Promise<string[]>
+  getFieldValueForEntity(entityId: string, field: string): Promise<any>
+  getFieldsForType(nounType: NounType): Promise<Array<{ field: string; affinity: number; occurrences: number; totalEntities: number }>>
+  getFieldStatistics(): Promise<Map<string, unknown>>
+  getFieldsWithCardinality(): Promise<Array<{ field: string; cardinality: number; distribution: string }>>
+  getOptimalQueryPlan(filters: Record<string, any>): Promise<unknown>
+
+  /** Report which index path a `where` clause on `field` will hit (drives `brain.explain()`). */
+  explainField(field: string): Promise<{ path: 'column-store' | 'sparse-chunked' | 'none'; notes?: string }>
+
+  getCountForCriteria(field: string, value: any): Promise<number>
+  getEntityCountByType(type: string): number
+  getEntityCountByTypeEnum(type: NounType): number
+  getTotalEntityCount(): number
+  getAllEntityCounts(): Map<string, number>
+  getTopNounTypes(n: number): NounType[]
+  getTopVerbTypes(n: number): VerbType[]
+  getAllNounTypeCounts(): Map<NounType, number>
+  getAllVerbTypeCounts(): Map<VerbType, number>
+  getAllVFSEntityCounts(): Promise<Map<string, number>>
+
+  detectAndRepairCorruption(): Promise<void>
+  validateConsistency(): Promise<{
+    healthy: boolean
+    avgEntriesPerEntity: number
+    entityCount: number
+    indexEntryCount: number
+    recommendation: string | null
+  }>
+
+  tokenize(text: string): string[]
+  extractTextContent(data: any): string
+
+  getStats(): Promise<MetadataIndexStats>
+
+  /** The shared UUID ↔ int mapper. Brainy reads `.getUuid(intId)` off the result. */
+  getIdMapper(): { getUuid(intId: number): string | undefined }
+
+  /** The column store the coordinator delegates `where`/`orderBy` to. */
+  readonly columnStore: import('./indexes/columnStore/types.js').ColumnStoreProvider
+}
+
+/**
+ * The `'graphIndex'` provider — a drop-in for `GraphAdjacencyIndex`.
+ * Brainy calls this surface via `this.graphIndex.*` (some optional-chained).
+ */
+export interface GraphIndexProvider {
+  /** `false` until the index has loaded; Brainy probes this before fast paths. */
+  readonly isInitialized: boolean
+
+  getNeighbors(
+    id: string,
+    optionsOrDirection?: { direction?: 'in' | 'out' | 'both'; limit?: number; offset?: number } | 'in' | 'out' | 'both'
+  ): Promise<string[]>
+  getVerbIdsBySource(sourceId: string, options?: { limit?: number; offset?: number }): Promise<string[]>
+  getVerbIdsByTarget(targetId: string, options?: { limit?: number; offset?: number }): Promise<string[]>
+  getVerbsBatchCached(verbIds: string[]): Promise<Map<string, GraphVerb>>
+
+  rebuild(): Promise<void>
+  flush(): Promise<void>
+  close(): Promise<void>
+  size(): number
+
+  getStats(): GraphIndexStats
+  getRelationshipStats(): {
+    totalRelationships: number
+    relationshipsByType: Record<string, number>
+    uniqueSourceNodes: number
+    uniqueTargetNodes: number
+    totalNodes: number
+  }
+  getRelationshipCountByType(type: string): number
+  getTotalRelationshipCount(): number
+  getAllRelationshipCounts(): Map<string, number>
+}
+
+/**
+ * The object returned by the `'hnsw'` provider factory — a drop-in for
+ * `HNSWIndex`. Brainy calls this surface via `this.index.*` plus the
+ * transactional add/remove operations. `enableCOW`, `getItem`, and
+ * `setPersistMode` are intentionally absent: Brainy guards each with
+ * feature-detection (`typeof x === 'function'`), so they are optional and not
+ * part of the required contract (Brainy's own `HNSWIndex` omits
+ * `setPersistMode`, for instance).
+ */
+export interface HnswProvider {
+  addItem(item: VectorDocument): Promise<string>
+  removeItem(id: string): Promise<boolean>
+  search(
+    queryVector: Vector,
+    k?: number,
+    filter?: (id: string) => Promise<boolean>,
+    options?: { rerank?: { multiplier: number }; candidateIds?: string[] }
+  ): Promise<Array<[string, number]>>
+  size(): number
+  clear(): void
+  rebuild(options?: any): Promise<void>
+  flush(): Promise<number>
+  getPersistMode(): 'immediate' | 'deferred'
+}
+
+/**
+ * The `'entityIdMapper'` provider — a drop-in for `EntityIdMapper`. Injected
+ * into the TypeScript `MetadataIndexManager` when a native metadata index is
+ * not also registered; that coordinator calls this full surface (incl.
+ * `getAllIntIds`, the all-ids universe for negation / `exists:false` filters).
+ */
+export interface EntityIdMapperProvider {
+  init(): Promise<void>
+  getOrAssign(uuid: string): number
+  getUuid(intId: number): string | undefined
+  getInt(uuid: string): number | undefined
+  remove(uuid: string): boolean
+  flush(): Promise<void>
+  clear(): Promise<void>
+  getAllIntIds(): number[]
+  intsIterableToUuids(ints: Iterable<number>): string[]
+  readonly size: number
+}
+
+/**
+ * The `'cache'` provider — a drop-in for `UnifiedCache`. Brainy installs it as
+ * the global cache (`setGlobalCache`) and calls this surface via
+ * `getGlobalCache()`.
+ */
+export interface CacheProvider {
+  getSync(key: string): any | undefined
+  set(key: string, data: any, type: 'hnsw' | 'metadata' | 'embedding' | 'other', size: number, rebuildCost?: number): void
+  delete(key: string): boolean
+  deleteByPrefix(prefix: string): number
+  clear(type?: 'hnsw' | 'metadata' | 'embedding' | 'other'): void
+}
+
+// The `'embeddings'` / `'embedBatch'` providers are function-shaped and already
+// typed by the existing `EmbeddingFunction` (see `coreTypes.ts`), which Brainy
+// uses at the `getProvider('embeddings')` call site. No separate interface is
+// added here to avoid a duplicate, unwired contract.
+
 /**
  * Storage adapter factory — plugins register these to provide
  * new storage backends that users reference by name.