/**
 * pi-loom ↔ pi-esr: Memory bridge type contract
 *
 * These types mirror pi-esr's `memory-bridge.ts` ESRMemoryProvider interface.
 * They live here rather than as a shared npm package to keep both plugins
 * zero-overhead (no cross-package build step). When pi-esr's interface changes,
 * this file is the single place to update in pi-loom.
 *
 * Design: entity_id is an opaque string — no type-level coupling to pi-esr.
 */

/** A reference handle to a stored memory, returned from store/search/listByEntity. */
export interface ESRMemoryRef {
  ref_id: string;
  provider: string;
  entity_id: string;
  kind: "summary" | "decision" | "incident" | "note";
  title?: string;
  created_at: string;
  metadata?: Record<string, unknown>;
}

/** A full memory record: reference + content text. */
export interface ESRMemoryRecord {
  ref: ESRMemoryRef;
  content: string;
}

/** A single timeline entry for an entity. */
export interface ESRMemoryTimelineEntry {
  ref: ESRMemoryRef;
  content: string;
}

/** A journal entry recording an entity state transition. */
export interface ESRMemoryJournalEntry {
  entity_id: string;
  transition: string;
  created_at: string;
}

/** Input shape for storing a new memory via ESR bridge. */
export interface ESRMemoryStoreInput {
  entityId: string;
  kind: ESRMemoryRef["kind"];
  content: string;
  title?: string;
  metadata?: Record<string, unknown>;
}

/** Input shape for searching memories via ESR bridge. */
export interface ESRMemorySearchInput {
  query: string;
  entityId?: string;
  kinds?: ESRMemoryRef["kind"][];
  limit?: number;
}

/** Input shape for listing memories by entity. */
export interface ESRMemoryEntityQuery {
  entityId: string;
  kinds?: ESRMemoryRef["kind"][];
  limit?: number;
}

/** Input shape for querying an entity's state journal. */
export interface ESRMemoryJournalQuery {
  entityId: string;
  limit?: number;
}

/**
 * The memory provider contract that pi-esr expects.
 * LoomMemoryProvider implements this, backed by pi-loom's LoomStore.
 */
export interface ESRMemoryProvider {
  readonly name: string;
  isAvailable(): Promise<boolean>;
  store(input: ESRMemoryStoreInput): Promise<ESRMemoryRef>;
  search(input: ESRMemorySearchInput): Promise<ESRMemoryRef[]>;
  listByEntity(input: ESRMemoryEntityQuery): Promise<ESRMemoryRef[]>;
  timeline(input: ESRMemoryEntityQuery): Promise<ESRMemoryTimelineEntry[]>;
  count(entityId?: string): Promise<number>;
  recordJournal(entityId: string, transition: string, metadata?: Record<string, unknown>): Promise<void>;
  getJournal(input: ESRMemoryJournalQuery): Promise<ESRMemoryJournalEntry[]>;
  getAllJournal(limit?: number): Promise<ESRMemoryJournalEntry[]>;
  fetch(refs: ESRMemoryRef[]): Promise<ESRMemoryRecord[]>;
  render(refs: ESRMemoryRef[]): Promise<string>;
}