@crossworks/client-types 0.230.43

package/src/lib/safe-download.ts

@@ -0,0 +1,97 @@
+/**
+ * Safe headers for serving stored file bytes.
+ *
+ * A user (or an email/agent-ingested file) can upload an SVG or HTML document
+ * with embedded `<script>`. If we echo the stored mime type with
+ * `content-disposition: inline`, the browser executes that script in our
+ * origin — stored XSS, and on the public `/s/[token]` share route it runs for
+ * any visitor. This helper closes that:
+ *
+ *   - `X-Content-Type-Options: nosniff` always, so the browser can't upgrade a
+ *     mislabeled response to an executable type.
+ *   - `inline` only for an allowlist of genuinely previewable types; everything
+ *     else — notably `text/html` — is forced to `attachment` (download) and
+ *     relabeled `application/octet-stream`.
+ *   - `image/svg+xml` is served inline with its real type so the UI can embed
+ *     it via `<img>` (where SVG scripts never run), but with a hardening CSP
+ *     that `sandbox`es the document and blocks scripts/network. That defangs
+ *     the one path where an SVG would execute: direct top-level navigation to
+ *     the raw URL. See `SVG_CSP` below.
+ */
+
+/**
+ * Locked-down policy for SVG bytes. `sandbox` (with no `allow-scripts`) is the
+ * load-bearing directive: even on direct navigation the SVG renders as an
+ * inert, scriptless document in a unique origin. `default-src 'none'` cuts off
+ * network egress (no beacons / external fetches); inline `<style>`, `data:`
+ * images and fonts stay allowed so legitimate SVGs still render. This header is
+ * ignored when the SVG loads as an `<img>` subresource, which is harmless —
+ * images don't execute scripts regardless.
+ */
+const SVG_CSP =
+  "default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:; sandbox";
+
+/** Base mime types safe to render inline. HTML is deliberately absent. */
+const INLINE_SAFE = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'image/bmp',
+  'image/x-icon',
+  'application/pdf',
+  'text/plain',
+  'audio/mpeg',
+  'audio/ogg',
+  'audio/wav',
+  'audio/webm',
+  'audio/mp4',
+  'audio/aac',
+  'audio/flac',
+  'video/mp4',
+  'video/webm',
+  'video/ogg',
+  'video/quicktime',
+]);
+
+function baseType(mime: string | null | undefined): string {
+  return (mime ?? '').split(';')[0]!.trim().toLowerCase();
+}
+
+export type SafeDownloadHeaders = {
+  'content-type': string;
+  'content-disposition': string;
+  'x-content-type-options': 'nosniff';
+  'content-security-policy'?: string;
+};
+
+/**
+ * Headers for serving `bytes` of `mimeType` named `filename`. Previewable types
+ * render inline with their real type; everything else downloads as an opaque
+ * octet-stream. SVG renders inline too, but with `SVG_CSP` to neutralize any
+ * embedded script on direct navigation. The filename is RFC 5987
+ * percent-encoded, so it can never inject header content regardless of its
+ * characters.
+ */
+export function safeDownloadHeaders(
+  mimeType: string | null | undefined,
+  filename: string | null | undefined,
+): SafeDownloadHeaders {
+  const mime = baseType(mimeType);
+  const encoded = encodeURIComponent(filename || 'download');
+  if (mime === 'image/svg+xml') {
+    return {
+      'content-type': 'image/svg+xml',
+      'content-disposition': `inline; filename*=UTF-8''${encoded}`,
+      'x-content-type-options': 'nosniff',
+      'content-security-policy': SVG_CSP,
+    };
+  }
+  const inline = mime.length > 0 && INLINE_SAFE.has(mime);
+  return {
+    'content-type': inline ? mime : 'application/octet-stream',
+    'content-disposition': `${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encoded}`,
+    'x-content-type-options': 'nosniff',
+  };
+}

package/src/mermaid-theme.ts

@@ -0,0 +1,167 @@
+/**
+ * The single map from Mantle theme tokens → Mermaid `themeVariables`.
+ *
+ * Two surfaces render Mermaid and both come through here, so a palette change
+ * lands in one place: the Pages/chat NodeView (client/web page-editor
+ * diagram-view) and the /print surface's PDF sidecar, which loads this as an
+ * IIFE from share-runtime (server/web build-share-runtime step 5).
+ *
+ * The house rule for colour: **filled shapes that carry text sit on neutral
+ * surfaces** (`background`/`card`/`muted`/`secondary`) with `foreground` text.
+ * The `chart-1..5` tokens are 3:1 data ink — fine as fills where nothing has
+ * to be read on top of them (pie slices, journey task chips, gitgraph
+ * branches), never as text and never behind a label. Where a diagram type
+ * needs more series than the palette has, the palette CYCLES: the theme
+ * generator owns every colour in the product (`pnpm themes:build`), so
+ * inventing an off-palette sixth hue here is not an option.
+ *
+ * Values must be concrete — mermaid's `base` theme runs khroma colour maths on
+ * them, which parses hex/rgb/hsl but not `color-mix()`. The generated
+ * themes.css emits plain hex, so reading the token straight out of
+ * `getComputedStyle` is safe.
+ */
+
+/** Resolve a CSS custom property to a concrete value; the fallback keeps a
+ *  missing token from yielding an empty colour string. */
+export type ThemeToken = (name: string, fallback: string) => string;
+
+/** GitHub-ish light defaults — only reached if a token is missing entirely. */
+const FALLBACK_CHARTS = ['#666ed1', '#ae467f', '#ad5700', '#4b830f', '#00889b'];
+
+/**
+ * @param token   resolves `--foo` against whatever element owns the theme
+ * @param darkMode mermaid's `base` theme branches on this for every value NOT
+ *   set below — gantt/journey section tints (a `-1` vs `-4` lighten
+ *   multiplier), `edgeLabelBackground`, gitgraph `branchLabelColor`, quadrant
+ *   `scaleLabelColor`. Unset it defaults to false, i.e. light-mode maths on a
+ *   dark brain.
+ */
+export function mermaidThemeVariables(
+  token: ThemeToken,
+  darkMode: boolean,
+): Record<string, string | boolean> {
+  const charts = [1, 2, 3, 4, 5].map((i) => token(`--chart-${i}`, FALLBACK_CHARTS[i - 1]!));
+  /** Categorical fill by index, cycling once the 5 chart tokens run out. */
+  const series = (i: number) => charts[i % charts.length]!;
+
+  const foreground = token('--foreground', '#1f2328');
+  const mutedForeground = token('--muted-foreground', '#59636e');
+  const background = token('--background', '#ffffff');
+  const card = token('--card', '#ffffff');
+  const muted = token('--muted', '#f6f8fa');
+  const secondary = token('--secondary', '#eff2f5');
+  const accent = token('--accent', '#eaeef2');
+  const border = token('--border', '#d1d9e0');
+  const primary = token('--primary', '#0969da');
+  const destructive = token('--destructive', '#d1242f');
+
+  const vars: Record<string, string | boolean> = {
+    darkMode,
+    fontFamily: 'Inter, ui-sans-serif, system-ui, sans-serif',
+
+    // ── Core surfaces. Most diagram types derive from these three "primary/
+    // secondary/tertiary" slots rather than naming their own variable, which
+    // is why sequence, class, state and ER already track the theme without
+    // per-type entries below.
+    background,
+    mainBkg: muted,
+    primaryColor: muted,
+    primaryTextColor: foreground,
+    primaryBorderColor: border,
+    secondaryColor: card,
+    secondaryTextColor: foreground,
+    secondaryBorderColor: border,
+    tertiaryColor: background,
+    tertiaryTextColor: foreground,
+    tertiaryBorderColor: border,
+    lineColor: mutedForeground,
+    textColor: foreground,
+    noteBkgColor: muted,
+    noteTextColor: foreground,
+    noteBorderColor: border,
+
+    // ── Gantt. Section bands alternate three neutral surfaces; task bars stay
+    // neutral too because mermaid paints the task label INSIDE the bar, so a
+    // chart fill would put 3:1 data ink behind text. `crit` is the one solid
+    // fill, hence `background` as its ink (light text on the light-mode
+    // destructive, dark text on the dark-mode one — the token flips with the
+    // mode, so one value is correct in both).
+    sectionBkgColor: muted,
+    altSectionBkgColor: background,
+    sectionBkgColor2: card,
+    excludeBkgColor: secondary,
+    taskBkgColor: accent,
+    taskBorderColor: border,
+    activeTaskBkgColor: secondary,
+    activeTaskBorderColor: primary,
+    doneTaskBkgColor: muted,
+    doneTaskBorderColor: border,
+    critBkgColor: destructive,
+    critBorderColor: destructive,
+    todayLineColor: primary,
+    gridColor: border,
+    vertLineColor: border,
+    taskTextColor: foreground,
+    taskTextOutsideColor: foreground,
+    taskTextClickableColor: primary,
+
+    // ── Quadrant chart. Four subtle neutral surfaces make the quadrants read
+    // as a checkerboard without competing with the plotted points, which are
+    // the only thing here that should carry chart ink.
+    quadrant1Fill: background,
+    quadrant2Fill: muted,
+    quadrant3Fill: card,
+    quadrant4Fill: secondary,
+    quadrant1TextFill: foreground,
+    quadrant2TextFill: foreground,
+    quadrant3TextFill: foreground,
+    quadrant4TextFill: foreground,
+    quadrantPointFill: series(0),
+    quadrantPointTextFill: foreground,
+    quadrantXAxisTextFill: mutedForeground,
+    quadrantYAxisTextFill: mutedForeground,
+    quadrantTitleFill: foreground,
+    quadrantInternalBorderStrokeFill: border,
+    quadrantExternalBorderStrokeFill: border,
+
+    // ── Pie text + strokes. Slice fills are chart ink (below); the label sits
+    // ON the slice, so it takes `background` — which inverts with the mode and
+    // therefore contrasts with a chart token in both.
+    pieStrokeColor: background,
+    pieOuterStrokeColor: border,
+    pieTitleTextColor: foreground,
+    pieSectionTextColor: background,
+    pieLegendTextColor: foreground,
+
+    // ── Error strip (mermaid's own, not the NodeView's).
+    errorBkgColor: destructive,
+    errorTextColor: background,
+  };
+
+  // ── Categorical series. Mermaid names these individually and falls back to
+  // hardcoded pastels for any index left unset, so each family is filled to
+  // its full count rather than the first five.
+  for (let i = 0; i < 12; i++) {
+    vars[`pie${i + 1}`] = series(i); // pie1..pie12 (1-based)
+    vars[`cScale${i}`] = series(i); // mindmap / journey sections
+  }
+  for (let i = 0; i < 8; i++) {
+    vars[`git${i}`] = series(i); // gitgraph branches
+    vars[`fillType${i}`] = series(i); // user-journey task chips
+  }
+  return vars;
+}
+
+/**
+ * The same map, read off `<html>` — what both live browsers want. Dark mode
+ * comes from the `dark` class next-themes sets; the /print surface never sets
+ * it, which is correct, since a PDF forces a light background regardless of
+ * the brain's mode.
+ */
+export function mermaidThemeVariablesFromDocument(): Record<string, string | boolean> {
+  const cs = getComputedStyle(document.documentElement);
+  return mermaidThemeVariables(
+    (name, fallback) => cs.getPropertyValue(name).trim() || fallback,
+    document.documentElement.classList.contains('dark'),
+  );
+}

package/src/model-choices.ts

@@ -0,0 +1,118 @@
+/**
+ * Curated model choices offered in the onboarding "Models" step.
+ *
+ * PURE DATA — imported by both the onboarding client (cards UI) and the API
+ * route (validation), so keep it dependency-free. Lives in system-manifest/
+ * because it's product-shipped model policy: the `recommended` entry in each
+ * list MUST match the corresponding manifest default (`PERSONA_MANIFEST.model`
+ * / the indexing workers' model in `MANIFEST_WORKERS`) — onboarding merely
+ * writes the user's pick as operator overlay on top of the manifest seed.
+ *
+ * Slugs are OpenRouter ids (verified against the live catalog). `azure: true`
+ * marks OpenAI-family models that can also be served from an Azure OpenAI
+ * deployment (the Azure route strips the `openai/` prefix to form the
+ * deployment name). Prices are indicative $/M tokens (in · out) — shown to
+ * the user as a class signal, not a quote.
+ */
+export type ModelChoice = {
+  /** OpenRouter model slug (`vendor/model`). */
+  id: string;
+  /** Display name for the card. */
+  name: string;
+  /** One-line honest pitch — strengths + who should pick it. */
+  blurb: string;
+  /** Indicative pricing, e.g. "$3 · $15 /M". */
+  price: string;
+  /** Deployable on Azure OpenAI (OpenAI-family only). */
+  azure?: boolean;
+  /** The shipped default — pre-selected, badge on the card. */
+  recommended?: boolean;
+};
+
+/** Top-tier choices for the assistant (the persona/responder agent). */
+export const ASSISTANT_MODEL_CHOICES: readonly ModelChoice[] = [
+  {
+    id: 'anthropic/claude-sonnet-5',
+    name: 'Claude Sonnet 5',
+    blurb:
+      'The shipped default — Anthropic’s newest Sonnet: superb reasoning and tool use, 1M context, and cheaper than the generation before it.',
+    price: '$2 · $10 /M',
+    recommended: true,
+  },
+  {
+    id: 'anthropic/claude-opus-4.8',
+    name: 'Claude Opus 4.8',
+    blurb:
+      'Anthropic’s flagship — the strongest option for hard technical and analytical work. Same class Mantle uses for its app-builder.',
+    price: '$5 · $25 /M',
+  },
+  {
+    id: 'openai/gpt-5.5',
+    name: 'GPT-5.5',
+    blurb:
+      'OpenAI’s newest flagship — excellent general intelligence. The top-tier pick that can also run from an Azure OpenAI deployment.',
+    price: '$5 · $30 /M',
+    azure: true,
+  },
+  {
+    id: 'x-ai/grok-4.20',
+    name: 'Grok 4.20',
+    blurb:
+      'Frontier-class at a budget price — fast and capable, the value pick if cost per conversation matters most.',
+    price: '$1.25 · $2.50 /M',
+  },
+];
+
+/** Fast/cheap choices for the background workers (indexing pipeline: the
+ *  extractor, summarizer, reflector, document reader, and narrator). These
+ *  process EVERYTHING the brain ingests, so price and speed dominate. */
+export const WORKER_MODEL_CHOICES: readonly ModelChoice[] = [
+  {
+    id: 'google/gemini-3.1-flash-lite',
+    name: 'Gemini 3.1 Flash Lite',
+    blurb:
+      'The shipped default — very fast, very cheap, 1M-token context. Ideal for the always-on indexing that reads everything you add.',
+    price: '$0.25 · $1.50 /M',
+    recommended: true,
+  },
+  {
+    id: 'openai/gpt-5.4-nano',
+    name: 'GPT-5.4 Nano',
+    blurb:
+      'The cheapest capable worker — great throughput on light summarisation. The budget pick on the Azure route.',
+    price: '$0.20 · $1.25 /M',
+    azure: true,
+  },
+  {
+    id: 'openai/gpt-5.4-mini',
+    name: 'GPT-5.4 Mini',
+    blurb:
+      'A step up in extraction quality while staying cheap — the stronger Azure-capable worker for dense technical documents.',
+    price: '$0.75 · $4.50 /M',
+    azure: true,
+  },
+  {
+    id: 'anthropic/claude-haiku-4.5',
+    name: 'Claude Haiku 4.5',
+    blurb:
+      'The premium fast model — noticeably sharper summaries and fact extraction, at a higher per-token price than the other workers.',
+    price: '$1 · $5 /M',
+  },
+];
+
+/** Worker kinds the onboarding "worker model" pick applies to — the text
+ *  indexing pipeline. Modality workers (tts/stt/vision/image_gen/search)
+ *  keep their manifest defaults; they're tuned per-modality in Settings. */
+export const WORKER_MODEL_KINDS = [
+  'extractor',
+  'summarizer',
+  'reflector',
+  'document',
+  'narrator',
+  'suggester',
+] as const;
+
+/** Azure deployment name for a curated slug (`openai/gpt-5.4` → `gpt-5.4`). */
+export function azureDeploymentName(slug: string): string {
+  return slug.replace(/^openai\//, '');
+}

package/src/runners-types.ts

@@ -0,0 +1,195 @@
+/**
+ * Pure types + presentation helpers for the Runners screen — Mantle's in-app
+ * replica of the DBOS admin console. No DBOS / pg imports, so it's safe to pull
+ * into a client component without dragging the DBOS SDK + postgres into the
+ * browser bundle. The server-only data layer lives in `./runners.ts`.
+ *
+ * Everything here mirrors DBOS's WorkflowStatus / StepInfo (the system-DB
+ * execution journal); see apps/api/src/runs.ts for the original apps/api-side
+ * read layer this parallels.
+ */
+
+/** DBOS workflow lifecycle states (StatusString in the SDK). */
+export type RunnerStatus =
+  | 'ENQUEUED'
+  | 'PENDING'
+  | 'SUCCESS'
+  | 'ERROR'
+  | 'CANCELLED'
+  | 'MAX_RECOVERY_ATTEMPTS_EXCEEDED'
+  | 'DELAYED';
+
+/** Order shown as filter chips (active states first, terminal after). */
+export const RUNNER_STATUSES: RunnerStatus[] = [
+  'ENQUEUED',
+  'PENDING',
+  'SUCCESS',
+  'ERROR',
+  'CANCELLED',
+  'MAX_RECOVERY_ATTEMPTS_EXCEEDED',
+  'DELAYED',
+];
+
+/** A run is still in flight (queued, delayed, or executing). */
+export function isRunnerActive(status: string): boolean {
+  return status === 'ENQUEUED' || status === 'PENDING' || status === 'DELAYED';
+}
+
+/** A single runner execution, projected from DBOS WorkflowStatus. */
+export type RunnerRun = {
+  workflowID: string;
+  /** Runner function name, e.g. 'assistantTurnWorkflow' / 'pingWorkflow'. */
+  name: string;
+  status: string;
+  queue?: string;
+  /** Which apps/api process executed it (helps when scaled out). */
+  executorId?: string;
+  appVersion?: string;
+  /** How many times DBOS has tried to recover this run after a crash. */
+  recoveryAttempts?: number;
+  createdAt: number;
+  dequeuedAt?: number;
+  completedAt?: number;
+  updatedAt?: number;
+  /** Wall-clock the runner actually executed (ms). Undefined until completed. */
+  runMs?: number;
+  /** End-to-end latency incl. queue wait (ms). Undefined until completed. */
+  totalMs?: number;
+  /** Time spent waiting in the queue before a worker picked it up (ms). */
+  queuedMs?: number;
+  /** Failure message when status is a failure state. */
+  error?: string;
+};
+
+/** One journaled step within a run (DBOS StepInfo). */
+export type RunnerStep = {
+  functionID: number;
+  name: string;
+  durationMs?: number;
+  startedAt?: number;
+  completedAt?: number;
+  /** Set when this step invoked a child workflow. */
+  childWorkflowID?: string;
+  error?: string;
+};
+
+/** A run plus its steps and (truncated) input/output, for the detail pane. */
+export type RunnerRunDetail = RunnerRun & {
+  /** Truncated JSON preview of the run's input args (owner-only). */
+  input?: string;
+  /** Truncated JSON preview of the run's return value (owner-only). */
+  output?: string;
+  steps: RunnerStep[];
+};
+
+/** Queue config + live counts — the header "is the runner healthy" strip. */
+export type RunnerQueueHealth = {
+  name: string;
+  /** Global cap on concurrently-executing runs across all workers. */
+  concurrency?: number;
+  /** Per-worker cap. */
+  workerConcurrency?: number;
+  rateLimit?: { limitPerPeriod: number; periodSec: number };
+  /** Runs waiting in the queue (ENQUEUED). */
+  enqueued: number;
+  /** Runs currently executing (PENDING). */
+  pending: number;
+  /** See RunnerListPage.engineAvailable. */
+  engineAvailable?: boolean;
+};
+
+export type RunnerListPage = {
+  runs: RunnerRun[];
+  /** True when another page exists (we over-fetch by one to know). */
+  hasMore: boolean;
+  /**
+   * False when the DBOS system database is not readable from here — runners
+   * were never provisioned, or the app connects with a role that cannot see the
+   * schema. Distinguishes "no runs" from "no runner engine", which otherwise
+   * look identical to a healthy idle queue.
+   */
+  engineAvailable?: boolean;
+};
+
+/** The lifecycle controls this screen exposes (the "observe + lifecycle" cut —
+ *  no destructive maintenance like delete / garbage-collect). */
+export type RunnerAction = 'cancel' | 'resume' | 'restart' | 'fork';
+
+/**
+ * Which lifecycle actions make sense for a run in a given status. Drives which
+ * buttons render in the detail pane.
+ *  - cancel:  only an in-flight run can be cancelled.
+ *  - resume:  re-run a halted run from its last completed step.
+ *  - restart: fork from step 0 → a brand-new run from scratch (new id).
+ *  - fork:    fork from a chosen step → a new run (new id).
+ */
+export function availableActions(status: string): RunnerAction[] {
+  switch (status) {
+    case 'ENQUEUED':
+    case 'PENDING':
+    case 'DELAYED':
+      return ['cancel'];
+    case 'CANCELLED':
+    case 'MAX_RECOVERY_ATTEMPTS_EXCEEDED':
+      return ['resume', 'restart', 'fork'];
+    case 'ERROR':
+      return ['resume', 'restart', 'fork'];
+    case 'SUCCESS':
+      return ['restart', 'fork'];
+    default:
+      return [];
+  }
+}
+
+export const RUNNER_ACTION_LABEL: Record<RunnerAction, string> = {
+  cancel: 'Cancel',
+  resume: 'Resume',
+  restart: 'Restart',
+  fork: 'Fork from step',
+};
+
+/** Status dot colour — mirrors the /traces palette (emerald/amber/destructive/
+ *  muted) plus sky for "queued/waiting" so a waiting run reads apart from a
+ *  running one. */
+export function runnerStatusDot(status: string): string {
+  switch (status) {
+    case 'SUCCESS':
+      return 'bg-emerald-500';
+    case 'ERROR':
+    case 'MAX_RECOVERY_ATTEMPTS_EXCEEDED':
+      return 'bg-destructive';
+    case 'CANCELLED':
+      return 'bg-muted-foreground/40';
+    case 'PENDING':
+      return 'bg-amber-500';
+    case 'ENQUEUED':
+    case 'DELAYED':
+      return 'bg-sky-500';
+    default:
+      return 'bg-muted-foreground/40';
+  }
+}
+
+export function runnerStatusText(status: string): string {
+  switch (status) {
+    case 'SUCCESS':
+      return 'text-emerald-700 dark:text-emerald-300';
+    case 'ERROR':
+    case 'MAX_RECOVERY_ATTEMPTS_EXCEEDED':
+      return 'text-destructive-ink';
+    case 'CANCELLED':
+      return 'text-muted-foreground';
+    case 'PENDING':
+      return 'text-amber-700 dark:text-amber-300';
+    case 'ENQUEUED':
+    case 'DELAYED':
+      return 'text-sky-700 dark:text-sky-300';
+    default:
+      return 'text-muted-foreground';
+  }
+}
+
+/** Compact label for a status (the long MAX_RECOVERY… is unwieldy in a chip). */
+export function runnerStatusLabel(status: string): string {
+  return status === 'MAX_RECOVERY_ATTEMPTS_EXCEEDED' ? 'MAX RETRIES' : status;
+}

package/src/search-query.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { parseSearchQuery, SEARCH_NODE_TYPES } from './search-query';
+
+const sp = (query: string) => new URLSearchParams(query);
+
+describe('parseSearchQuery', () => {
+  it('requires q', () => {
+    expect(parseSearchQuery(sp(''))).toEqual({ error: 'q required' });
+    expect(parseSearchQuery(sp('q=%20%20'))).toEqual({ error: 'q required' });
+  });
+
+  it('defaults: nodes mode, limit 20', () => {
+    const r = parseSearchQuery(sp('q=printer'));
+    expect(r).toEqual({
+      q: 'printer',
+      mode: 'nodes',
+      type: undefined,
+      branch: undefined,
+      tags: undefined,
+      limit: 20,
+    });
+  });
+
+  it('accepts chunks mode, rejects unknown modes', () => {
+    expect(parseSearchQuery(sp('q=x&mode=chunks'))).toMatchObject({ mode: 'chunks' });
+    expect(parseSearchQuery(sp('q=x&mode=fuzzy'))).toEqual({
+      error: "mode must be 'nodes' or 'chunks'",
+    });
+  });
+
+  it('validates type against the tool enum', () => {
+    for (const t of SEARCH_NODE_TYPES) {
+      expect(parseSearchQuery(sp(`q=x&type=${t}`))).toMatchObject({ type: t });
+    }
+    expect(parseSearchQuery(sp('q=x&type=widget'))).toEqual({ error: "unknown type 'widget'" });
+  });
+
+  it('validates branch as ltree-safe', () => {
+    expect(parseSearchQuery(sp('q=x&branch=files.work'))).toMatchObject({ branch: 'files.work' });
+    expect(parseSearchQuery(sp('q=x&branch=files.work;drop'))).toEqual({
+      error: 'invalid branch',
+    });
+    expect(parseSearchQuery(sp('q=x&branch=.leading'))).toEqual({ error: 'invalid branch' });
+  });
+
+  it('rejects over-long branches (Postgres ltree label cap is 255)', () => {
+    const longLabel = 'a'.repeat(256);
+    expect(parseSearchQuery(sp(`q=x&branch=files.${longLabel}`))).toEqual({
+      error: 'invalid branch',
+    });
+    const longTotal = Array.from({ length: 60 }, () => 'abcdefghij').join('.');
+    expect(parseSearchQuery(sp(`q=x&branch=${longTotal}`))).toEqual({
+      error: 'invalid branch',
+    });
+  });
+
+  it('splits tags on commas, trims, drops empties, caps at 10', () => {
+    expect(parseSearchQuery(sp('q=x&tags=work,%20home%20,,'))).toMatchObject({
+      tags: ['work', 'home'],
+    });
+    const many = Array.from({ length: 14 }, (_, i) => `t${i}`).join(',');
+    const r = parseSearchQuery(sp(`q=x&tags=${many}`));
+    expect(r).toMatchObject({ tags: Array.from({ length: 10 }, (_, i) => `t${i}`) });
+    expect(parseSearchQuery(sp('q=x&tags=%20,'))).toMatchObject({ tags: undefined });
+  });
+
+  it('clamps limit to 1..50 with default 20', () => {
+    expect(parseSearchQuery(sp('q=x&limit=5'))).toMatchObject({ limit: 5 });
+    expect(parseSearchQuery(sp('q=x&limit=500'))).toMatchObject({ limit: 50 });
+    expect(parseSearchQuery(sp('q=x&limit=0'))).toEqual({ error: 'invalid limit' });
+    expect(parseSearchQuery(sp('q=x&limit=abc'))).toEqual({ error: 'invalid limit' });
+  });
+
+  it('limit parsing is strict-integer, not parseInt-prefix', () => {
+    expect(parseSearchQuery(sp('q=x&limit=1e3'))).toMatchObject({ limit: 50 }); // 1000 → clamp
+    expect(parseSearchQuery(sp('q=x&limit=2.9'))).toEqual({ error: 'invalid limit' });
+    expect(parseSearchQuery(sp('q=x&limit=5abc'))).toEqual({ error: 'invalid limit' });
+    expect(parseSearchQuery(sp('q=x&limit=-1'))).toEqual({ error: 'invalid limit' });
+  });
+
+  it('rejects an over-long q', () => {
+    expect(parseSearchQuery(sp(`q=${'a'.repeat(501)}`))).toEqual({
+      error: 'q too long (max 500)',
+    });
+  });
+});