/**
 * module: memory —— 对外类型(编码规范 §10.1)。
 */
import type { AttributionSide, TaskId } from '@contracts';
import type {
  ActivityMemoryEntry,
  CandidateIncrement,
  Evidence,
  MemoryLayer,
} from './internal/domain/activity-memory.ts';
import type { EntryKind, GovernanceMark, MemoryEntry, VersionStamp } from './internal/domain/task-memory.ts';
import type { LogLine, Metrics, MetricsInput } from './internal/domain/task-log.ts';

export type {
  ActivityMemoryEntry,
  AttributionSide,
  CandidateIncrement,
  EntryKind,
  Evidence,
  GovernanceMark,
  LogLine,
  MemoryEntry,
  MemoryLayer,
  Metrics,
  MetricsInput,
  VersionStamp,
};

export { NoEvidenceError } from './internal/domain/activity-memory.ts';

/** 追加一条任务记忆 —— 归侧由 kind 自动推导,调用方不得指定(零埋点) */
export type AppendEntry = {
  readonly taskId: TaskId;
  readonly kind: EntryKind;
  readonly title: string;
  readonly detail?: Record<string, unknown>;
  readonly stamp: VersionStamp;
  readonly governance?: Partial<GovernanceMark>;
  readonly linksTo?: string;
  readonly eventRef?: string;
};

export type DistillInput = {
  readonly taskId: TaskId;
  readonly activityId: string;
  readonly trigger: 'terminal' | 'milestone';
  readonly milestone?: string;
  readonly prompt: string;
};

export type MemoryService = {
  /* 任务记忆:框架自动记录、只追加 */
  append(entry: AppendEntry): Promise<MemoryEntry>;
  history(taskId: TaskId): Promise<MemoryEntry[]>;
  /** 活动侧唯一可配置项:窗口大小 —— 每次 LLM 调用加载多少轮 */
  window(taskId: TaskId, size: number): Promise<MemoryEntry[]>;
  seal(taskId: TaskId): Promise<void>;

  /* 任务日志:任务记忆的两级投影 */
  taskLog(taskId: TaskId, options?: { canSeeMasked?: boolean }): Promise<LogLine[]>;
  /** 叙述性小结(LLM,可选)—— 叙述是视图不是事实,不入事实库 */
  narrate(taskId: TaskId): Promise<string | undefined>;

  /* 活动记忆:四层存取;写入唯蒸馏 */
  loadActivityMemory(
    activityId: string,
    options?: { layers?: readonly MemoryLayer[]; limit?: number },
  ): Promise<ActivityMemoryEntry[]>;
  /** **不设直写旁路**:唯一写入口是蒸馏钩子 */
  distill(input: DistillInput): Promise<ActivityMemoryEntry[]>;
  /** 人可修剪 —— 治理台 · 记忆管理 */
  prune(entryId: string): Promise<void>;
  setIncrementState(entryId: string, state: CandidateIncrement['state']): Promise<void>;

  metrics(input: Omit<MetricsInput, 'entries'> & { taskIds: readonly TaskId[] }): Promise<Metrics>;
};