/**
 * @factory/ai — provider adapters.
 *
 *  - `OpenAIAdapter` / `OssAdapter` / `CustomAdapter` — one OpenAI-compatible
 *    adapter (baseUrl + optional Bearer key; OSS dimension discovered at
 *    first use)
 *  - `AnthropicAdapter` — claude family; **no embed** (gateway routes embed
 *    to the fallback provider)
 *  - `GoogleAdapter` — gemini family (`:streamGenerateContent?alt=sse`)
 *  - `MockProvider` — deterministic, dependency-free, for the CI capability
 *    suite (TASK-0121: "identical assertion set runs against the mock
 *    provider always, and against the real provider when AI_REAL_TEST=1")
 */

export { AnthropicAdapter, type AnthropicOptions } from "./anthropic.js";
export { GoogleAdapter, type GoogleOptions } from "./google.js";
export {
  CustomAdapter,
  OpenAIAdapter,
  OpenAICompatibleAdapter,
  OssAdapter,
  type OpenAICompatibleOptions,
} from "./openai-compatible.js";
export { abortError };
import { abortError } from "./http.js";
import {
  ProviderHttpError,
  httpJson,
  isRetryableStatus,
  sseData,
  type HttpOptions,
} from "./http.js";
import { mapColumnsToProperties, parseMarkdownTable } from "../schemas/database.js";

/**
 * A deterministic in-process provider for unit tests and the CI capability
 * suite: echoes structured responses, honors the chat chunk protocol
 * (text deltas → tool calls → final usage), and counts "tokens" as
 * characters/4 so usage assertions are exact.
 */
export class MockProvider {
  readonly id: "openai" | "anthropic" | "google" | "oss" | "custom";
  /** When > 0, `chat` throws a retryable HTTP `failStatus` for the next `failTimes` calls. */
  failTimes = 0;
  /** HTTP status the failures carry (default 429; use 500 for the 5xx path). */
  failStatus = 429;
  calls = 0;
  /**
   * TASK-0122: ms to wait BETWEEN deltas (0 = no pacing). Tests that assert
   * mid-stream cancellation set this so the consumer's abort lands between
   * deltas; the wait races `req.signal` and aborts throw `AbortError`.
   */
  deltaDelayMs = 0;
  /**
   * TASK-0122 (E2E): when > 0, `chat` emits exactly this many deltas and
   * then throws a retryable `failStatus` — a deterministic MID-stream
   * provider outage. The gateway never re-streams after partial output
   * (would duplicate content), so the consumer sees the error in-band:
   * exactly ONE user request fails, the next (the UI's Retry button) is a
   * fresh call and succeeds. 0 = disabled (the default).
   */
  failAfterDeltas = 0;
  /** Embedding dimension the mock reports. */
  readonly dimension: number;
  private callsSeen: { model: string }[] = [];

  constructor(id: "openai" | "anthropic" | "google" | "oss" | "custom" = "openai", dimension = 8) {
    this.id = id;
    this.dimension = dimension;
  }

  async models(): Promise<
    Array<{ id: string; provider: "openai" | "anthropic" | "google" | "oss" | "custom"; kind: "chat" | "embed" | "chat+embed"; contextWindow: number; maxOutput: number; toolCalls: boolean; vision: boolean; pricePer1kIn: number; pricePer1kOut: number; dimension: number }>
  > {
    return [
      {
        id: "mock-chat",
        provider: this.id,
        kind: "chat",
        contextWindow: 32_000,
        maxOutput: 4_096,
        toolCalls: true,
        vision: false,
        pricePer1kIn: 0,
        pricePer1kOut: 0,
        dimension: 0,
      },
    ];
  }

  async *chat(req: {
    model: string;
    messages: Array<{ role: string; content: unknown }>;
    tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
    maxTokens?: number;
    metadata?: Record<string, string>;
    signal?: AbortSignal;
  }): AsyncIterable<{
    delta?: string;
    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
    usage?: { in: number; out: number; total: number };
    finishReason?: "stop" | "tool_calls" | "length" | "error";
    done: boolean;
  }> {
    this.calls += 1;
    this.callsSeen.push({ model: req.model });
    if (this.failTimes > 0) {
      this.failTimes -= 1;
      const { ProviderHttpError } = await import("./http.js");
      throw new ProviderHttpError(this.failStatus, "mock provider failure", this.failStatus === 429 || this.failStatus >= 500);
    }
    // TASK-0123: deterministic WRITING mode. The app layer opts in via
    // `metadata.mode = "writing"` (+ `action`). The "model" parses the
    // `[BLOCK <id>]` markers the prompt builder emits (so the unit/E2E path
    // exercises the REAL prompt → provider contract, not a side channel) and
    // answers with ONE `toolCallDelta` carrying the `generateBlocks` result:
    // a deterministic per-block transform of the block's own text.
    if (req.metadata?.mode === "writing") {
      yield* this.writingChat(req);
      return;
    }
    // TASK-0124: deterministic DATABASE-GENERATION mode. The app layer opts in
    // via `metadata.mode = "database"` (+ `action` ∈ generate|extract|formula,
    // and, for generate, `prompt`; for extract, `columns`; for formula,
    // `properties`). The "model" parses the markers the prompt builder emits
    // and answers with ONE `toolCallDelta` carrying a VALID, deterministic
    // tool call — so the unit/E2E path exercises the REAL prompt → provider
    // → server-validation contract. A `metadata.hostile` seam makes it emit a
    // deliberately INVALID call (to exercise the retry-once → 422 path).
    if (req.metadata?.mode === "database") {
      yield* this.databaseChat(req);
      return;
    }
    // TASK-0125: deterministic RAG mode. The app layer opts in via
    // `metadata.mode = "rag"` and puts the retrieved, numbered context in the
    // user message as `[n] Source: <label>` blocks (the REAL prompt → provider
    // contract — a real model would answer from that context with inline
    // `[n]` citations; the mock deterministically cites the FIRST source so
    // tests can assert the answer carries the seeded fact + a `[n]` marker
    // that the server-side citation builder matches to the `sources` frame).
    if (req.metadata?.mode === "rag") {
      yield* this.ragChat(req);
      return;
    }
    // TASK-0126: deterministic PAGE-GENERATION mode. The app layer opts in via
    // `metadata.mode = "generate"`. The "model" answers with ONE `toolCallDelta`
    // carrying the canonical "product launch plan" PLAN (a ref-based structured
    // tool list) — so the unit/integration/E2E path exercises the REAL prompt →
    // provider → server-validation → executor contract. A `metadata.generateFailStep`
    // seam (armed via the internal test seam) makes it emit a plan whose Nth step
    // the executor CANNOT run (an unknown ref) → the rollback-on-failure path.
    if (req.metadata?.mode === "generate") {
      yield* this.generateChat(req);
      return;
    }
    // T-172…T-175 (A-010): deterministic ASSISTANT mode. The app layer opts in
    // via `metadata.mode = "assistant"` (+ `action`). The "model" parses the
    // context the prompt builder emitted (numbered sources / `[id]` candidates
    // / the notes text) and answers with ONE `toolCallDelta` carrying a VALID,
    // deterministic tool call — so the unit/integration path exercises the
    // REAL prompt → provider → server-validation contract. A `metadata.hostile`
    // seam makes it emit a deliberately INVALID call (retry-once → 422 path).
    if (req.metadata?.mode === "assistant") {
      yield* this.assistantChat(req);
      return;
    }
    // deterministic echo: reply with the last user message (first 40 chars).
    // Streamed as one delta per word (deterministic; ≥3 chunks for a normal
    // sentence) so streaming consumers (TASK-0122 SSE / the E2E panel)
    // observe real incremental updates — the concatenation is identical to
    // the old 2-chunk split.
    const lastUser = [...req.messages].reverse().find((m) => m.role === "user");
    const text = typeof lastUser?.content === "string" ? lastUser.content.slice(0, 40) : "ok";
    // TASK-0122: when the caller sent a system message (the context
    // assembler), append its tail to the echo so tests can assert what the
    // model actually SAW (context inclusion / permission-drop verification).
    const sysMsg = [...req.messages].filter((m) => m.role === "system").pop();
    const sysTail =
      sysMsg && typeof sysMsg.content === "string" ? ` [SYS:${sysMsg.content.slice(-200)}]` : "";
    const words = text.length === 0 ? ["ok"] : text.split(" ");
    const pace = async (): Promise<void> => {
      if (this.deltaDelayMs <= 0) return;
      if (req.signal?.aborted) throw abortError();
      await new Promise<void>((resolve) => {
        const timer = setTimeout(resolve, this.deltaDelayMs);
        const onAbort = (): void => {
          clearTimeout(timer);
          resolve();
        };
        req.signal?.addEventListener("abort", onAbort, { once: true });
        // (the timer's cleanup is harmless — it fires at most once after
        // resolve, on an already-settled promise)
      });
      if (req.signal?.aborted) throw abortError();
    };
    for (let i = 0; i < words.length; i++) {
      await pace();
      yield { delta: (i > 0 ? " " : "") + words[i]!, done: false };
      // TASK-0122 (E2E): mid-stream provider outage — after exactly
      // `failAfterDeltas` deltas the stream dies with a retryable status.
      // The gateway never re-streams partial output, so the consumer sees
      // the failure in-band (SSE `error` delta) instead of an auto-retry.
      if (this.failAfterDeltas > 0) {
        this.failAfterDeltas -= 1;
        if (this.failAfterDeltas === 0) {
          throw new ProviderHttpError(
            this.failStatus,
            "mock provider mid-stream failure",
            this.failStatus === 429 || this.failStatus >= 500,
          );
        }
      }
    }
    // Arming is single-shot and MUST fire even for short answers: if the
    // word stream ended before the count was consumed, fail right here
    // (still mid-stream — the usage/done chunk never goes out).
    if (this.failAfterDeltas > 0) {
      this.failAfterDeltas = 0;
      throw new ProviderHttpError(
        this.failStatus,
        "mock provider mid-stream failure",
        this.failStatus === 429 || this.failStatus >= 500,
      );
    }
    if (sysTail) {
      await pace();
      yield { delta: sysTail, done: false };
    }
    if (req.tools && req.tools.length > 0) {
      const first = req.tools[0]!;
      yield {
        toolCallDelta: { id: "mock_call_0", name: first.name, arguments: { echoed: text } },
        done: false,
      };
      yield {
        usage: { in: Math.ceil(text.length / 4), out: Math.ceil(text.length / 4), total: Math.ceil(text.length / 2) },
        finishReason: "tool_calls",
        done: true,
      };
      return;
    }
    yield {
      usage: { in: Math.ceil(text.length / 4), out: Math.ceil(text.length / 4), total: Math.ceil(text.length / 2) },
      finishReason: "stop",
      done: true,
    };
  }

  /**
   * TASK-0123 — deterministic writing mode (`metadata.mode = "writing"`).
   *
   * The app layer (TASK-0123 `ai-writing.service`) sends the selected +
   * context blocks as delimited `[SELECTED <id>]…[/SELECTED <id>]` /
   * `[CONTEXT <id>]…[/CONTEXT <id>]` markers in the user message and opts in
   * with `metadata: { mode: "writing", action, language? }`. The mock plays
   * the "model" end of that REAL contract (no side channel): it parses the
   * markers and answers with ONE tool call (`generateBlocks`) whose
   * `blocks` are deterministic per-action transforms of each block's own
   * text:
   *
   *   summarize → `Summarized: <first 80 chars>`   (per block)
   *   rewrite   → `Rewritten: <text>`
   *   improve   → `Improved: <text>`
   *   translate → `Translated to <language>: <text>`
   *
   * `metadata.forceUnknownId` appends a blockId the prompt never contained —
   * the deterministic seam for the server-side "unknown ID → drop + note"
   * validation (integration). The TASK-0122 mid-stream-outage arming
   * (`failAfterDeltas`) is honored: an armed writing call dies before the
   * tool call goes out (still mid-stream — no usage/done frame leaves).
   */
  private async *writingChat(req: {
    messages: Array<{ role: string; content: unknown }>;
    tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
    metadata?: Record<string, string>;
    signal?: AbortSignal;
  }): AsyncIterable<{
    delta?: string;
    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
    usage?: { in: number; out: number; total: number };
    finishReason?: "stop" | "tool_calls" | "length" | "error";
    done: boolean;
  }> {
    const action = req.metadata?.action ?? "rewrite";
    const language = req.metadata?.language;
    const blocks = parseWritingBlocks(req.messages);
    const totalChars = blocks.reduce((n, b) => n + b.text.length, 0);
    const usage = { in: Math.ceil(totalChars / 4), out: Math.ceil(totalChars / 4), total: Math.ceil(totalChars / 2) };

    if (this.deltaDelayMs > 0) {
      await new Promise<void>((resolve) => setTimeout(resolve, this.deltaDelayMs));
    }
    if (req.signal?.aborted) throw abortError();
    if (this.failAfterDeltas > 0) {
      this.failAfterDeltas = 0;
      throw new ProviderHttpError(
        this.failStatus,
        "mock provider mid-stream failure",
        this.failStatus === 429 || this.failStatus >= 500,
      );
    }

    const toolName = req.tools?.[0]?.name ?? "generateBlocks";
    const out: Array<{ blockId: string; newText: string }> = blocks.map((b) => ({
      blockId: b.id,
      newText: writingTransform(action, b.text, language),
    }));
    const forceUnknown = req.metadata?.forceUnknownId;
    if (forceUnknown) out.push({ blockId: forceUnknown, newText: "Injected unknown block id (mock seam)." });

    yield {
      toolCallDelta: { id: "mock_writing_0", name: toolName, arguments: { blocks: out } },
      done: false,
    };
    yield { usage, finishReason: "tool_calls", done: true };
  }

  /**
   * TASK-0125 — deterministic RAG mode (`metadata.mode = "rag"`).
   *
   * The app layer (TASK-0125 `rag.service`) sends the retrieved, numbered
   * context as `[n] Source: <label>\n<chunk text>` blocks followed by a
   * `Question: <q>` line, and opts in with `metadata: { mode: "rag" }`. The
   * mock plays the "model" end of that REAL contract: it parses the first
   * source block and streams a deterministic, CITED answer —
   * `According to [1] (<label>): <first 200 chars of the chunk text>` — so
   * tests can assert the answer contains the seeded fact, the `[n]` marker,
   * and the source label. No context → a deterministic "no results" answer
   * (the app layer normally short-circuits before the chat call; this keeps
   * the provider total even if it does not).
   */
  private async *ragChat(req: {
    messages: Array<{ role: string; content: unknown }>;
    metadata?: Record<string, string>;
    signal?: AbortSignal;
  }): AsyncIterable<{
    delta?: string;
    usage?: { in: number; out: number; total: number };
    finishReason?: "stop" | "tool_calls" | "length" | "error";
    done: boolean;
  }> {
    const lastUser = [...req.messages].reverse().find((m) => m.role === "user");
    const userText = typeof lastUser?.content === "string" ? lastUser.content : "";
    const first = parseRagSource(userText);
    const answer = first
      ? `According to [${first.n}] (${first.label}): ${first.text.slice(0, 200)}`
      : "I could not find any workspace content that answers this question. Try different wording.";
    const usage = {
      in: Math.ceil(userText.length / 4),
      out: Math.ceil(answer.length / 4),
      total: Math.ceil((userText.length + answer.length) / 4),
    };
    const words = answer.split(" ");
    for (let i = 0; i < words.length; i++) {
      if (this.deltaDelayMs > 0) {
        await new Promise<void>((resolve) => setTimeout(resolve, this.deltaDelayMs));
      }
      if (req.signal?.aborted) throw abortError();
      yield { delta: (i > 0 ? " " : "") + words[i]!, done: false };
    }
    yield { usage, finishReason: "stop", done: true };
  }

  async embed(req: { model: string; texts: string[]; metadata?: Record<string, string> }): Promise<{
    model: string;
    dimension: number;
    vectors: number[][];
    usage: { tokens: number };
    latencyMs: number;
    provider: "openai" | "anthropic" | "google" | "oss" | "custom";
  }> {
    this.calls += 1;
    if (this.id === "anthropic") {
      const { ProviderHttpError } = await import("./http.js");
      throw new ProviderHttpError(501, "Anthropic has no embedding API", false);
    }
    const vectors = req.texts.map((t) => {
      const v = new Array<number>(this.dimension).fill(0);
      v[0] = Math.min(1, t.length / 100);
      if (this.dimension > 1) v[1] = 0.5;
      return v;
    });
    return {
      model: req.model,
      dimension: this.dimension,
      vectors,
      usage: { tokens: Math.ceil(req.texts.join(" ").length / 4) },
      latencyMs: 0,
      provider: this.id,
    };
  }

  async health(): Promise<{ ok: boolean; latencyMs: number }> {
    return { ok: true, latencyMs: 0 };
  }

  get callsSeenModels(): string[] {
    return this.callsSeen.map((c) => c.model);
  }

  /**
   * TASK-0124 — deterministic database-generation mode
   * (`metadata.mode = "database"`). See the selection point in `chat`. The
   * "model" parses the markers the prompt builder emits into the USER message
   * (so the unit/E2E path exercises the REAL prompt → provider → server
   * validation contract, not a metadata side-channel) and answers with ONE
   * `toolCallDelta` carrying a deterministic tool call:
   *   - generate → `createDatabase` (title/properties derived from the prompt)
   *   - extract  → `insertRecords`  (parses `[PROP <id>]` + the `[ROWS]` table)
   *   - formula  → `generateFormula` (parses `[PROP <name>] <type>` lines)
   * `metadata.hostile = "1"` (armed via the internal test seam) makes it emit a
   * deliberately INVALID call → the retry-once → 422 path.
   */
  private async *databaseChat(req: {
    messages: Array<{ role: string; content: unknown }>;
    metadata?: Record<string, string>;
    signal?: AbortSignal;
  }): AsyncIterable<{
    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
    usage?: { in: number; out: number; total: number };
    finishReason?: "stop" | "tool_calls" | "length" | "error";
    done: boolean;
  }> {
    if (this.deltaDelayMs > 0) await new Promise<void>((r) => setTimeout(r, this.deltaDelayMs));
    if (req.signal?.aborted) throw abortError();

    const userMsg = [...req.messages].reverse().find((m) => m.role === "user");
    const text = typeof userMsg?.content === "string" ? userMsg.content : "";
    const action = req.metadata?.action ?? "generate";
    // Hostile is ARMed PER ACTION (the seam sets which feature is hostile).
    // The arming persists across the two calls of a single retry-once request
    // (generate/extract/formula each call twice), so BOTH attempts are invalid
    // → the true 422 path. It is cleared between tests via the seam/reset.
    const armedAction = req.metadata?.hostile; // "generate" | "extract" | "formula"
    const hostile = armedAction === action;

    let toolName = "createDatabase";
    let args: Record<string, unknown> = {};
    if (action === "extract") {
      toolName = "insertRecords";
      args = mockDatabaseExtract(text, hostile);
    } else if (action === "formula") {
      toolName = "generateFormula";
      args = mockDatabaseFormula(text, hostile);
    } else {
      toolName = "createDatabase";
      args = mockDatabaseGenerate(text, hostile);
    }

    yield { toolCallDelta: { id: "mock_db_0", name: toolName, arguments: args }, done: false };
    const chars = JSON.stringify(args).length;
    yield { usage: { in: Math.ceil(chars / 4), out: Math.ceil(chars / 4), total: Math.ceil(chars / 2) }, finishReason: "tool_calls", done: true };
  }

  /**
   * TASK-0126 — deterministic page-generation mode (`metadata.mode =
   * "generate"`). The "model" answers with ONE `toolCallDelta` carrying the
   * canonical PLAN — a ref-based structured tool list for the "product launch
   * plan" (a page with section headings, then a Tasks database with a
   * status select + due date + 2 sample records). The plan is DETERMINISTIC
   * (same prompt → same plan) so the unit/integration/E2E path exercises the
   * REAL prompt → provider → server-validation → executor contract.
   *
   * `metadata.generateFailStep` (a 1-based step number, armed via the
   * internal test seam) makes the mock emit a plan whose Nth step references a
   * ref that does not exist → the executor's step fails → the rollback path.
   * (The plan is still schema-valid; the FAILURE is a run-time unknown ref,
   * which is the deterministic way to force a step to fail.)
   */
  private async *generateChat(req: {
    messages: Array<{ role: string; content: unknown }>;
    metadata?: Record<string, string>;
    signal?: AbortSignal;
  }): AsyncIterable<{
    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
    usage?: { in: number; out: number; total: number };
    finishReason?: "stop" | "tool_calls" | "length" | "error";
    done: boolean;
  }> {
    // Signal-aware "plan latency": `generateSlowMs` (armed via the internal
    // test seam) makes the plan fetch outlast the service's total timeout so
    // the timeout watchdog fires; the wait RESOLVES (not hangs) on abort and
    // the post-wait check then throws, so the test is fast (≈ timeoutMs).
    const slowMs = req.metadata?.generateSlowMs ? Number.parseInt(req.metadata.generateSlowMs, 10) : this.deltaDelayMs;
    if (slowMs > 0) {
      const sig = req.signal;
      if (sig?.aborted) throw abortError();
      await new Promise<void>((resolve) => {
        const timer = setTimeout(resolve, slowMs);
        sig?.addEventListener("abort", () => {
          clearTimeout(timer);
          resolve();
        }, { once: true });
      });
      if (sig?.aborted) throw abortError();
    }

    const userMsg = [...req.messages].reverse().find((m) => m.role === "user");
    const text = typeof userMsg?.content === "string" ? userMsg.content : "";
    const failStep = req.metadata?.generateFailStep ? Number.parseInt(req.metadata.generateFailStep, 10) : 0;

    const plan = mockGeneratePlan(text, failStep);
    const args = JSON.parse(JSON.stringify(plan)) as Record<string, unknown>;
    yield { toolCallDelta: { id: "mock_gen_0", name: "generatePlan", arguments: args }, done: false };
    const chars = JSON.stringify(args).length;
    yield { usage: { in: Math.ceil(chars / 4), out: Math.ceil(chars / 4), total: Math.ceil(chars / 2) }, finishReason: "tool_calls", done: true };
  }

  /**
   * T-172…T-175 — deterministic ASSISTANT mode (`metadata.mode = "assistant"`).
   *
   * Parses the markers the app layer's prompt builder emits (numbered sources
   * `[n] label`, candidate pages `[<id>] title`, the raw notes text) and
   * answers with ONE `toolCallDelta` carrying a VALID, deterministic tool call
   * — so the integration path exercises the REAL prompt → provider →
   * server-validation contract (exactly the writing/database/rag/generate
   * pattern). `metadata.hostile` (armed via the internal seam) makes it emit a
   * deliberately INVALID call → the "validate → retry once → 422, no write"
   * path.
   */
  private async *assistantChat(req: {
    messages: Array<{ role: string; content: unknown }>;
    tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
    metadata?: Record<string, string>;
    signal?: AbortSignal;
  }): AsyncIterable<{
    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
    usage?: { in: number; out: number; total: number };
    finishReason?: "stop" | "tool_calls" | "length" | "error";
    done: boolean;
  }> {
    if (req.signal?.aborted) throw abortError();
    const user = [...req.messages].reverse().find((m) => m.role === "user");
    const text = typeof user?.content === "string" ? user.content : "";
    const action = req.metadata?.action ?? "extract-actions";
    const toolName = req.tools?.[0]?.name ?? "extractActionItems";

    // The deterministic "model" output per capability.
    let args: Record<string, unknown>;
    if (req.metadata?.hostile) {
      // Deliberately INVALID (fails the app layer's zod validation) → the
      // retry-once path emits this again → 422, no write.
      args = { invalid: "hostile mock tool call" };
    } else if (action === "extract-actions") {
      // The notes' bullet lines (the prompt puts the raw text under a header):
      // every "- …" / "* …" / "1. …" line becomes a task.
      const lines = text
        .split("\n")
        .map((l) => l.match(/^\s*(?:[-*]|\d+[.)])\s+(.+)$/)?.[1]?.trim())
        .filter((l): l is string => Boolean(l && l.length > 1 && l.length <= 200));
      args = { actions: lines.slice(0, 10).map((l) => ({ title: l.replace(/\.$/, "") })) };
    } else if (action === "generate-faqs") {
      // Numbered sources → one FAQ per source, citing it (the RAG-style [n]
      // marker the app layer validates against the retrieved set).
      const sources = [...text.matchAll(/^\[(\d+)\]\s+(.+)$/gm)];
      const faqs = sources.slice(0, 15).map((m) => ({
        question: `About ${m[2]!.trim()}?`,
        answer: `Deterministic answer (per [${m[1]}]).`,
      }));
      args = {
        title: `FAQ: ${sources.length || 1} source${sources.length === 1 ? "" : "s"}`,
        faqs: faqs.length ? faqs : [{ question: "Anything?", answer: "Deterministic answer (per [1])." }],
      };
    } else if (action === "find-duplicates") {
      // Candidate ids `[<id>] title` — the mock groups them 2 at a time
      // (the app layer filters ids to the permission-filtered set).
      const ids = [...text.matchAll(/^\[([^\]\s]+)\]\s+(.+)$/gm)].map((m) => m[1]!);
      const groups: Array<{ pageIds: string[]; similarity: number; reason: string }> = [];
      for (let i = 0; i + 1 < ids.length; i += 2) {
        groups.push({ pageIds: [ids[i]!, ids[i + 1]!], similarity: 0.9, reason: "Overlapping content (mock)." });
      }
      // Hostile-forgery seam (separate from `hostile`): also emit an id the
      // prompt never contained → the server's no-fabricated-refs drop path.
      if (req.metadata?.forgeId) groups.push({ pageIds: [ids[0] ?? "p1", "forged-id"], similarity: 0.8, reason: "Forged id (mock seam)." });
      args = { groups };
    } else if (action === "find-stale") {
      // Flag the FIRST two candidates (deterministic subset).
      const ids = [...text.matchAll(/^\[([^\]\s]+)\]\s+(.+)$/gm)].map((m) => m[1]!);
      args = { pages: ids.slice(0, 2).map((id) => ({ pageId: id, reason: "Contains outdated dates (mock)." })) };
    } else {
      // suggest-metadata: derive from the page's own title.
      const titleLine = text.match(/^Page title:\n(.+)$/m)?.[1]?.trim() ?? "Untitled";
      args = { title: titleLine ? `Revised: ${titleLine}`.slice(0, 200) : "Revised page", description: "Deterministic description grounded in the page (mock)." };
    }

    const serialized = JSON.stringify(args);
    yield { toolCallDelta: { id: "mock_assistant_0", name: toolName, arguments: JSON.parse(serialized) }, done: false };
    const chars = serialized.length;
    yield { usage: { in: Math.ceil(chars / 4), out: Math.ceil(chars / 4), total: Math.ceil(chars / 2) }, finishReason: "tool_calls", done: true };
  }
}

// ── TASK-0126 page-generation mode helpers ───────────────────────────────────

/**
 * The canonical "product launch plan" PLAN the mock emits. Ref-based (see
 * `schemas/generate.ts`): the root page is created first (no `ref` → the
 * executor's root), its section headings are inserted under it, and a Tasks
 * database is created under the root with a status select + due date + 2
 * sample records. `failStep` (1-based) injects a step at that position that
 * references a NON-EXISTENT ref (the executor fails the step → rollback).
 */
export function mockGeneratePlan(prompt: string, failStep = 0): { tools: Array<Record<string, unknown>> } {
  const title = "Product Launch Plan";
  const sections = ["Objectives", "Requirements", "Timeline", "Risks", "Team", "Meeting Notes"];
  const tools: Array<Record<string, unknown>> = [
    { name: "createPage", args: { title, blocks: [] } },
  ];
  // Fail seam: inject a broken step at the requested position.
  const broken: Record<string, unknown> = {
    name: "insertBlocks",
    args: { pageRef: "no_such_ref", blocks: [{ type: "PARAGRAPH", content: { text: "boom" } }] },
  };
  if (failStep > 0 && failStep <= tools.length + 1) tools.splice(failStep - 1, 0, broken);
  // Section headings (one insertBlocks step for the whole section list — the
  // executor appends each block in order under the root page).
  tools.push({
    name: "insertBlocks",
    args: {
      pageRef: undefined,
      blocks: sections.map((s) => ({ type: "HEADING_2", content: { text: s } })),
    },
  });
  // The Tasks database (under the root page): a status select + a due date.
  // The seeded Title/Status already exist on a fresh database — so the plan
  // declares only its OWN extra columns (Due) + the seeded Status options are
  // already there. We still add a "Due" date column (the spec's "a date").
  tools.push({
    name: "createDatabase",
    args: {
      ref: "tasks",
      pageRef: undefined, // the root page
      title: "Tasks",
      properties: [{ name: "Due", type: "date" }],
      sampleRecords: [
        { properties: { Title: "Draft launch announcement", Due: "2026-01-15" } },
        { properties: { Title: "Schedule launch review", Due: "2026-01-20" } },
      ],
    },
  });
  // (prompt is echoed into the description-less plan for observability; it
  // does not change the deterministic structure — the E2E asserts structure.)
  void prompt;
  return { tools };
}

// ── TASK-0124 database-generation mode helpers ────────────────────────────────

/** The deterministic `createDatabase` tool call the mock emits for a prompt. */
export function mockDatabaseGenerate(prompt: string, hostile: boolean): Record<string, unknown> {
  const title = (prompt.trim().slice(0, 60) || "Generated database").replace(/[^\p{L}\p{N}\s:—-]/gu, "").trim() || "Generated database";
  if (hostile) {
    // A type NOT in the generated allowlist → the server must reject it with a
    // per-property reason (and, after the retry-once, a 422).
    return {
      title,
      description: "hostile (mock)",
      properties: [{ name: "Broken", type: "relation" }],
      sampleRecords: [],
    };
  }
  return {
    title,
    description: `Generated from: ${prompt.trim().slice(0, 80)}`,
    // NOTE: the generated db already SEEDS a "Title" + a "Status" select —
    // the model must not re-declare them (the server rejects a 2nd
    // "status"). So the mock's own select is named "State", not "Status".
    properties: [
      { name: "Name", type: "text" },
      { name: "State", type: "select", options: [{ name: "To Do" }, { name: "Done" }] },
      { name: "Due", type: "date" },
      { name: "Done?", type: "checkbox" },
    ],
    // Sample records are keyed by property NAME; the record TITLE comes from
    // the "Title" key (the seeded title property), the rest by their names.
    sampleRecords: [
      { properties: { Title: "First item", Name: "First item", State: "To Do", Due: "2026-01-01", "Done?": false } },
      { properties: { Title: "Second item", Name: "Second item", State: "Done", Due: "2026-01-02", "Done?": true } },
    ],
  };
}

/**
 * The deterministic `insertRecords` tool call the mock emits for an extract.
 * Parses the prompt markers the TASK-0124 prompt builder emits:
 *   `[PROP <propertyId>] <Name> (<TYPE>)` — the database's real properties,
 *   `<<<PASTE … PASTE>>>` — the user's pasted text (usually a markdown
 *   table). The table is parsed with the SAME deterministic parser the server
 *   uses (`parseMarkdownTable`); columns that match no property BY NAME go in
 *   `ignoredColumns`.
 */
export function mockDatabaseExtract(text: string, hostile: boolean): Record<string, unknown> {
  const props: Array<{ id: string; name: string; type: string }> = [];
  {
    const re = /\[PROP ([A-Za-z0-9_-]+)\]\s+([^\n<]+?)\s*\(([^)\n]+)\)/g;
    let m: RegExpExecArray | null;
    while ((m = re.exec(text)) !== null) props.push({ id: m[1]!, name: m[2]!.trim(), type: m[3]!.trim() });
  }
  // The pasted region (fall back to the whole prompt when the markers are
  // absent — the parser is harmless on prose: it just finds the pipe rows).
  const paste = /<<<PASTE\n([\s\S]*?)\nPASTE>>>/.exec(text);
  const pasted = paste ? paste[1]! : text;
  const table = parseMarkdownTable(pasted);
  if (hostile) {
    // A record referencing a property id the database does NOT have → the
    // server's per-record validation must reject it (no partial write).
    return { records: [{ properties: { does_not_exist: "x" } }], ignoredColumns: [] };
  }
  if (!table.isTable || table.rows.length === 0) {
    return { records: [], ignoredColumns: table.columns };
  }
  const mapping = mapColumnsToProperties(table.columns, props.map((p) => ({ id: p.id, name: p.name })));
  const records = table.rows.map((row) => {
    const properties: Record<string, unknown> = {};
    for (const pair of mapping.mapped) {
      const cell = row[pair.column] ?? "";
      if (cell !== "") properties[pair.propertyId] = cell;
    }
    return { properties };
  });
  return { records, ignoredColumns: mapping.ignored };
}

/**
 * The deterministic `generateFormula` tool call the mock emits. `properties`
 * = `[PROP <name>] <type>` lines. It builds a REAL, engine-valid expression
 * referencing the first two properties: `if` (a bool) when the first is a
 * string-ish type, else `sum`/`+`. `hostile` emits an expression that the
 * engine cannot parse (an unknown function) → the retry-once → 422 path.
 */
export function mockDatabaseFormula(text: string, hostile: boolean): Record<string, unknown> {
  const props: Array<{ name: string; type: string }> = [];
  const re = /\[PROP ([^\n\]]+?)\]\s+([a-z_]+)/g;
  let m: RegExpExecArray | null;
  while ((m = re.exec(text)) !== null) props.push({ name: m[1]!.trim(), type: m[2]! });
  if (hostile) {
    // An expression the formula engine CANNOT parse (unknown function) → the
    // retry-once → 422 `formula_invalid` path.
    return { expression: "explode(prop(\"x\"))", explanation: "hostile (unknown function)" };
  }
  const [a] = props;
  if (a) {
    return { expression: `if(prop("${a.name}") == "Done", 100, 0)`, explanation: `Deterministic formula over ${a.name}.` };
  }
  return { expression: "now()", explanation: "No properties; a now() expression." };
}

// ── TASK-0123 writing-mode helpers ────────────────────────────────────────────

/** Parse the delimited block markers the TASK-0123 prompt builder emits into
 *  the user message. `[SELECTED <id>]…[/SELECTED <id>]` are the blocks the
 *  user asked the model to edit; `[CONTEXT <id>]…[/CONTEXT <id>]` are the
 *  surrounding ±5 blocks (never edited). Returns selected blocks in prompt
 *  order. */
export function parseWritingBlocks(messages: Array<{ role: string; content: unknown }>): Array<{ id: string; text: string }> {
  const userMsg = [...messages].reverse().find((m) => m.role === "user");
  if (!userMsg) return [];
  const text = typeof userMsg.content === "string" ? userMsg.content : "";
  const out: Array<{ id: string; text: string }> = [];
  const re = /\[SELECTED ([A-Za-z0-9_-]+)\]\n?([\s\S]*?)\n?\[\/SELECTED \1\]/g;
  let m: RegExpExecArray | null;
  while ((m = re.exec(text)) !== null) {
    out.push({ id: m[1]!, text: (m[2] ?? "").trim() });
  }
  return out;
}

/**
 * Parse the FIRST numbered context block the TASK-0125 RAG prompt builder
 * emits into the user message:
 *   `[n] Source: <label>\n<chunk text>\n\n` — followed by either another
 *   `[n] Source:` block, the `Question:` line, or end of message.
 * Returns `null` when no source block is present (the "no results" answer).
 */
export function parseRagSource(
  userText: string,
): { n: number; label: string; text: string } | null {
  // The block always starts at the very beginning of the user message (the
  // service builds `<contextBlocks>\n\nQuestion: …`), so `^` is anchored to
  // string start and the `$` alternative is the TRUE end — deliberately NOT
  // multiline: a `/m` flag would let `$` match every line break and truncate
  // multi-line chunk text at its first newline (e.g. a whole-page body
  // `Title\n<fact>` would yield only `Title` — TASK-0125 integration caught
  // this with the seeded `Launch Runbook\n…Zanzibar-7.` parent body).
  const m = /^\[(\d+)\] Source: ([^\n]+)\n([\s\S]*?)(?=\n\[\d+\] Source: |\nQuestion: |$)/.exec(userText);
  if (!m) return null;
  return { n: Number(m[1]!), label: m[2]!.trim(), text: (m[3] ?? "").trim() };
}

/** Deterministic per-action transform (TASK-0123). */
export function writingTransform(action: string, text: string, language?: string): string {
  const t = text.trim();
  switch (action) {
    case "summarize":
      return `Summarized: ${t.slice(0, 80)}`;
    case "improve":
      return `Improved: ${t}`;
    case "translate":
      return `Translated to ${language ?? "the target language"}: ${t}`;
    case "rewrite":
    default:
      return `Rewritten: ${t}`;
  }
}