import type { MemoryEntry, MemorySearchResult } from "./store.js";
import type { ScopeMatchMode } from "./scope-policy.js";

export interface MemoryStoreStats {
  totalCount: number;
  scopeCounts: Record<string, number>;
  categoryCounts: Record<string, number>;
}

export type MemoryStoreUpdate = {
  text?: string;
  vector?: number[];
  importance?: number;
  category?: MemoryEntry["category"];
  metadata?: string;
  timestamp?: number;
  language?: string;
  fts_text?: string;
};

export interface MemoryStorePort {
  /** scopeMatch 见 scope-policy.ts 的 ScopeMatchMode：缺省 "family"（历史行为，
   *  无冒号 scope 按前缀），"exact" 由调用方在"我给的是一个具体 scope 名"时显式声明。 */
  stats(scopeFilter?: string[], scopeMatch?: ScopeMatchMode): Promise<MemoryStoreStats>;
  list(
    scopeFilter?: string[],
    category?: string,
    limit?: number,
    offset?: number,
    scopeMatch?: ScopeMatchMode,
  ): Promise<MemoryEntry[]>;
  /** 按 id 批量取真实向量。list()/listPage() 为性能恒返回 vector:[]（假空数组），
   *  任何要做相似度/聚类的消费者必须用这个回填——promote_scan 与 dream 3b 都栽过同一坑。 */
  getVectors(ids: string[]): Promise<Map<string, number[]>>;
  /** DB 层真分页(where/limit/offset 下推),全库维护扫描用;list() 是全量拉取再切片。 */
  listPage(opts?: {
    scopeFilter?: string[];
    category?: string;
    limit?: number;
    offset?: number;
    includeVector?: boolean;
  }): Promise<MemoryEntry[]>;
  get(id: string, scopeFilter?: string[]): Promise<MemoryEntry | null>;
  getById(id: string): Promise<MemoryEntry | null>;
  store(entry: Omit<MemoryEntry, "id" | "timestamp"> & { id?: string }): Promise<MemoryEntry>;
  update(id: string, updates: MemoryStoreUpdate, scopeFilter?: string[]): Promise<MemoryEntry | null>;
  /** metadata 读改写的单写通道(per-id 串行队列)。新代码改 metadata 一律走这里,
   *  不要 getById+update 裸 RMW(并发覆盖)。 */
  patchMetadata(
    id: string,
    patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>,
    scopeFilter?: string[],
  ): Promise<MemoryEntry | null>;
  /** metadata 批量读改写：单锁单 commit 写一批行（≤200/批）。patchFn 在锁内以库中
   *  最新行为底座、按数组序依次应用（同批闭包可传递决策）。单条失败跳过不炸整批，
   *  返回成功写入数。dream 3a/3b/auto-gc 的写放大治理入口（2026-08-14）。 */
  patchMetadataBatch(
    patches: Array<{
      id: string;
      patchFn: (meta: Record<string, unknown>, entry: MemoryEntry) => Record<string, unknown>;
    }>,
    scopeFilter?: string[],
  ): Promise<number>;
  /** Remove version-group metadata from groups with only one surviving member.
   *  Implementations should take one membership snapshot and apply repairs under
   *  the same write lock so concurrent group creation cannot invalidate the plan. */
  repairSingletonVersionGroups(): Promise<number>;
  vectorSearch(
    vector: number[],
    limit?: number,
    minScore?: number,
    scopeFilter?: string[],
    scopeMatch?: ScopeMatchMode,
  ): Promise<MemorySearchResult[]>;
}