/**
 * 活动基座六件 —— 活动开发者看到的**全部世界**(编码规范 §8.2;语义出处 OS 4.1)。
 *
 * 「基座即笼子:契约限承诺、工具限能力、交互限入口、记忆与留痕限事实、数据限归属、
 *  LLM 调用限模型 —— **内容归活动,笼子归系统**。
 *  活动代码**无环境能力**,一切能力经调用契约注入,越权在结构上不可能。」
 */
import type {
  ActivityMemoryLayer,
  ChatCardDraft,
  LedgerKey,
  LedgerRow,
  ViewBlockLike,
  WorkOrderDraft,
} from './types.ts';

/* ① 契约 —— 只读:活动启动前冻结,运行中不得变更 */
export type ContractSpec = {
  readonly activityId: string;
  readonly version: string;
  /** 输入:data(已过 schema 校验)+ message(委托消息,可为空) */
  readonly data: Readonly<Record<string, unknown>>;
  readonly message: string | undefined;
  readonly outputPorts: { readonly mandatory: readonly string[]; readonly selective: readonly string[] };
  readonly prohibitions: readonly string[];
  /** AI 可自决的范围;超出必须调「人 · 决策」 */
  readonly discretion: readonly string[];
};

/* ② 交互 —— 对话流(唯一回环输入口,只出不进)+ 视图区容器(只读呈现) */
export type InteractionHandle = {
  /** 视图流控:按局面推结构化块 */
  pushView(blocks: readonly ViewBlockLike[]): Promise<void>;
  /** 视图模版 —— 过净化门:含脚本 / 外部资源即被拒 */
  pushHtml(html: string): Promise<void>;
  /** 对话区输出(AI 发言) */
  say(text: string, tag?: 'conclusion' | 'guidance' | 'criterion'): Promise<void>;
  /** 调人:工单两模式 */
  issueWorkOrder(order: WorkOrderDraft): Promise<{ id: string }>;
  /** 调人:对话卡族(决策 / 补全 / 评价) */
  issueCard(card: ChatCardDraft): Promise<{ id: string }>;
};

/* ③ 记忆 —— 任务记忆只有**窗口配置**一个可配项;活动记忆只有存与取 */
export type MemoryHandle = {
  /** 每次 LLM 调用加载多少轮会话历史 —— 活动侧唯一记忆接口 */
  window(size: number): Promise<ReadonlyArray<{ at: string; title: string; side: string }>>;
  /** 活动记忆按定位选摘(渐进披露);**语义引擎不读** */
  recall(options?: { layers?: readonly ActivityMemoryLayer[]; limit?: number }): Promise<
    ReadonlyArray<{ layer: ActivityMemoryLayer; statement: string }>
  >;
};

/* ④ 数据(台账)—— 三级寻址 + 通用事务接口;放行前一切写入落草稿层 */
export type LedgerHandle = {
  /** 任务视图 = 正式版 + 本任务草稿层(读己之写) */
  read(address: string, where?: Readonly<Record<string, string | number>>): Promise<LedgerRow[]>;
  /** 草稿写 —— **不产生数据事件**;放行时合并入正式版 */
  write(address: string, key: LedgerKey, patch: LedgerRow): Promise<void>;
};

/* ⑤ 工具(调用契约)—— 授权在白名单与契约,不在活动代码 */
export type ToolInvokerHandle = {
  invoke(tool: string, input: Readonly<Record<string, unknown>>): Promise<{
    ok: boolean;
    output?: Record<string, unknown>;
    error?: { code: string; message: string };
  }>;
  /** 写类动作:登记为动作意向(入参冻结),放行后由系统执行落地 */
  intend(tool: string, input: Readonly<Record<string, unknown>>, label: string): Promise<void>;
  /** 立监听:AI 对世界只有触达(动作)与等待(监听)两种姿势;**时限必配** */
  listen(input: {
    eventType: 'data' | 'time';
    keyFilter: Readonly<Record<string, string>>;
    deadline: string;
  }): Promise<{ id: string }>;
};

/* ⑥ LLM 调用 —— 活动只声明**自定义模型名**,不触厂商与密钥 */
export type LlmHandle = {
  generate(input: {
    /** 自定义模型名(逻辑名) */
    model: string;
    prompt: string;
    system?: string;
    /** 给定即要求结构化出参并校验 */
    outputSchema?: Record<string, unknown>;
  }): Promise<{ text: string; object?: unknown }>;
};

/** 六件合体 —— 活动运行时拿到的全部句柄 */
export type ActivityBase = {
  readonly contract: ContractSpec;
  readonly interaction: InteractionHandle;
  readonly memory: MemoryHandle;
  readonly ledger: LedgerHandle;
  readonly tools: ToolInvokerHandle;
  readonly llm: LlmHandle;
};