@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/cli/system.ts

@@ -0,0 +1,94 @@
+/**
+ * Die Systemadapter der Ports, die praktisch jeder Befehl braucht.
+ *
+ * ZUR DETERMINISMUS-REGEL: `Date.now()` und `crypto.randomUUID()` stehen hier
+ * — und NUR hier — hinter den Ports `Clock` und `Random`. Sie fliessen nie
+ * ungefragt in Ergebnisdaten: die Uhr wird vom Abrufkern ausschliesslich fuer
+ * den Recency-Boost und von Adaptern fuer Protokollstempel verwendet, der
+ * Zufall nur fuer Korrelations-IDs. Wer deterministische Ergebnisse braucht,
+ * injiziert stattdessen die Fakes des testkits — genau deshalb sind es Ports.
+ */
+
+import { getRandomValues, randomUUID } from "node:crypto";
+
+import type { Clock, LogEvent, LoggerPort, Random } from "@untangle-code/domain";
+
+/**
+ * Die Systemuhr.
+ *
+ * `Date.now()` steht hier — und die Determinismusregel des Repos verbietet es
+ * ueberall sonst. Das ist kein Widerspruch, sondern der Zweck: eine Regel, die
+ * die Wanduhr aus der Analyse-Logik heraushaelt, braucht GENAU EINE Stelle, an
+ * der die Wanduhr trotzdem gelesen wird. Diese ist es. Deshalb steht die
+ * Ausnahme in `eslint.config.js` auf diese Datei beschraenkt und nicht als
+ * `eslint-disable`-Kommentar im Code, wo sie sich unbemerkt ausbreiten wuerde.
+ */
+export const systemClock: Clock = {
+  nowEpochMs: () => Date.now(),
+  nowIso: () => new Date().toISOString(),
+};
+
+/**
+ * Die Systemzufallsquelle.
+ *
+ * Bewusst `node:crypto` und NICHT `Math.random()`: der Port liefert unter
+ * anderem `uuid()` fuer Korrelations- und Schreib-IDs, und dafuer ist ein
+ * vorhersagbarer Generator die falsche Wahl. Dass die Determinismusregel
+ * `Math.random()` ohnehin verbietet, faellt damit zusammen — der bessere Code
+ * ist hier auch der regelkonforme.
+ */
+export const systemRandom: Random = {
+  nextFloat: () => {
+    // 53 Bit aus 8 Zufallsbytes: dieselbe Aufloesung, die ein Double traegt.
+    const bytes = getRandomValues(new Uint8Array(8));
+    let value = 0;
+    for (const byte of bytes) value = value * 256 + byte;
+    return value / 2 ** 64;
+  },
+  nextInt: (maxExclusive: number) => {
+    if (maxExclusive <= 0) return 0;
+    // Verwerfen statt Modulo: Modulo verzerrt, wenn 2^32 kein Vielfaches von
+    // `maxExclusive` ist. Die Schleife endet mit Wahrscheinlichkeit 1.
+    const limit = Math.floor(0x1_0000_0000 / maxExclusive) * maxExclusive;
+    for (;;) {
+      const [draw] = getRandomValues(new Uint32Array(1));
+      if (draw !== undefined && draw < limit) return draw % maxExclusive;
+    }
+  },
+  bytes: (length: number) => getRandomValues(new Uint8Array(length)),
+  uuid: () => randomUUID(),
+};
+
+/**
+ * Ein Logger, der NUR nach stderr schreibt und standardmaessig schweigt.
+ *
+ * Grund: Protokollzeilen auf stdout wuerden die Nutzdaten der `--format=json`-
+ * Ausgabe zerstoeren. Und ein Werkzeug, das ungefragt protokolliert, ist im
+ * Terminal unbrauchbar — deshalb ist `error` die Vorgabestufe und `--verbose`
+ * hebt sie an.
+ */
+const LEVEL_ORDER: Record<string, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+  trace: 4,
+};
+
+export function createStderrLogger(
+  level: "error" | "warn" | "info" | "debug" | "trace",
+  bindings: Readonly<Record<string, unknown>> = {},
+): LoggerPort {
+  const threshold = LEVEL_ORDER[level] ?? 0;
+  const logger: LoggerPort = {
+    log(event: LogEvent): void {
+      const eventLevel = LEVEL_ORDER[event.level] ?? 0;
+      if (eventLevel > threshold) return;
+      process.stderr.write(`${JSON.stringify({ ...bindings, ...event })}\n`);
+    },
+    child(childBindings) {
+      return createStderrLogger(level, { ...bindings, ...childBindings });
+    },
+  };
+  return logger;
+}

package/src/cli/vector-store-policy.ts

@@ -0,0 +1,213 @@
+/**
+ * WP-222 — DIE EINE STELLE, DIE ENTSCHEIDET, WELCHER VEKTORSPEICHER BENUTZT
+ * WERDEN DARF.
+ *
+ * Vorher stand diese Regel zweimal im Werkzeug, und die zwei Fassungen
+ * widersprachen sich in einer Sicherheitsfrage:
+ *
+ *   `untangle init`   kannte spec.md §3.2 und prueft den ueblichen
+ *                     Standardport eines fremden Vektorspeichers
+ *                     ABSICHTLICH NICHT. Es schrieb den Grund sogar in die
+ *                     erzeugte Konfiguration.
+ *   `untangle doctor` kannte die Regel nicht. Es liess `qdrant.mode =
+ *                     "managed"` vom Speicheradapter aufloesen, der ohne
+ *                     `url` auf denselben Standardport zurueckfiel, fand
+ *                     dort eine FREMDE Instanz mit fremden Daten, meldete
+ *                     "[OK ] Qdrant — Erreichbar" und empfahl, dorthin zu
+ *                     indizieren.
+ *
+ * Zwei Befehle desselben Werkzeugs, zwei Antworten, und die gefaehrlichere
+ * gewann: der Nutzer folgt dem Diagnosewerkzeug, nicht dem Kommentar in
+ * einer Datei. Die Ursache war nicht, dass eine der beiden Fassungen falsch
+ * war — die Ursache war, dass es ZWEI gab.
+ *
+ * Also: hier steht sie einmal. `init` bezieht von hier, welche Adressen es
+ * ueberhaupt anfassen darf; `doctor` und jeder andere Befehl bekommen ihren
+ * Speicher ueber `cli/workspace.ts`, das vor dem Verdrahten hier fragt. Wer
+ * eine dritte Fassung schreibt, muss diese Datei umgehen — und das faellt
+ * auf.
+ *
+ * DIE REGEL, in einem Satz: Untangle benutzt seinen EIGENEN verwalteten
+ * Speicher, es sei denn, der Nutzer hat eine Adresse ausdruecklich benannt.
+ * Ein Zurueckfallen auf eine fremde Vorgabeadresse gibt es nicht.
+ */
+
+import type { QdrantConfig } from "@untangle-code/config";
+
+import { OperationalError } from "./exit.js";
+
+/**
+ * Der verwaltete Qdrant-REST-Port (spec.md §3.1). Dieser Dienst gehoert
+ * Untangle: eigener Container, eigenes Volume. Auf ihn darf geschrieben
+ * werden.
+ */
+export const MANAGED_QDRANT_URL = "http://127.0.0.1:16333";
+
+/**
+ * Adressen, die Untangle von sich aus NIEMALS annimmt.
+ *
+ * `6333` ist der Vorgabeport von Qdrant selbst und damit genau der Port, auf
+ * dem auf einem Entwicklungsrechner die Instanz von JEMAND ANDEREM liegt —
+ * mit den Daten von jemand anderem. spec.md §3.2 verbietet, in fremde
+ * Infrastruktur einzugreifen. Eine Konfiguration, die diesen Port
+ * stillschweigend uebernaehme, wuerde beim naechsten Befehl hineinschreiben.
+ */
+export const FOREIGN_DEFAULT_QDRANT_URLS: readonly {
+  readonly url: string;
+  readonly reason: string;
+}[] = [
+  {
+    url: "http://127.0.0.1:6333",
+    reason:
+      "Default port of a foreign instance; spec.md §3.2 prohibits modifying foreign " +
+      "services. Select it explicitly with UNTANGLE_QDRANT_URL; otherwise `untangle` starts " +
+      "an owned instance on 16333 with its own volume.",
+  },
+];
+
+/** Woher die Adresse kommt — das ist der ganze Unterschied. */
+export type VectorStoreOrigin =
+  | "embedded"
+  /** Aus `qdrant.url` einer Konfigurationsdatei. Der Nutzer hat sie hingeschrieben. */
+  | "configured"
+  /** Aus `UNTANGLE_QDRANT_URL`. Der Nutzer hat sie benannt. */
+  | "environment"
+  /** Untangles eigener verwalteter Speicher (spec.md §3.1). */
+  | "managed";
+
+export interface VectorStoreDecision {
+  /** Die Adresse, die benutzt werden darf — oder die abgelehnte. */
+  readonly url: string;
+  readonly origin: VectorStoreOrigin;
+  readonly allowed: boolean;
+  /** Bei `allowed === false`: warum nicht. Sonst: wie die Adresse zustande kam. */
+  readonly reason: string;
+  /** Bei `allowed === false` Pflicht: GENAU EIN naechster Schritt. */
+  readonly nextStep?: string;
+}
+
+function normalize(url: string): string {
+  return url.trim().replace(/\/+$/u, "");
+}
+
+/** Steht diese Adresse auf der Liste der fremden Vorgabeadressen? */
+export function foreignDefaultFor(url: string): { url: string; reason: string } | undefined {
+  const wanted = normalize(url);
+  return FOREIGN_DEFAULT_QDRANT_URLS.find((entry) => normalize(entry.url) === wanted);
+}
+
+/**
+ * Die Entscheidung.
+ *
+ * Warum das Feld `qdrant.url` als „ausdrueckliche Nennung" zaehlt: es hat
+ * KEINE Produktvorgabe (`DEFAULT_QDRANT_CONFIG` setzt nur `mode`). Steht dort
+ * etwas, dann hat es eine Nutzerebene hingeschrieben — eine Datei, die
+ * Umgebung oder ein Argument. Genau das ist die Zustimmung, die spec.md §3.2
+ * verlangt, bevor Untangle eine fremde Instanz anfasst.
+ */
+export function decideVectorStore(input: {
+  qdrant: QdrantConfig;
+  env: Readonly<Record<string, string | undefined>>;
+}): VectorStoreDecision {
+  const fromConfig = input.qdrant.url;
+  if (fromConfig !== undefined && fromConfig.length > 0) {
+    const foreign = foreignDefaultFor(fromConfig);
+    return {
+      url: fromConfig,
+      origin: "configured",
+      allowed: true,
+      reason:
+        foreign === undefined
+          ? "explicitly configured as `qdrant.url`"
+          : "explicitly configured as `qdrant.url`; selecting this foreign " +
+            "selecting the default address is therefore an explicit user decision (spec.md §3.2)",
+    };
+  }
+
+  const fromEnv = input.env["UNTANGLE_QDRANT_URL"];
+  if (fromEnv !== undefined && fromEnv.length > 0) {
+    return {
+      url: fromEnv,
+      origin: "environment",
+      allowed: true,
+      reason: "explicitly selected through UNTANGLE_QDRANT_URL",
+    };
+  }
+
+  if (input.qdrant.mode === "external") {
+    // Kein Zurueckfallen. „external" ohne Adresse ist ein Konfigurationsfehler
+    // und wird als solcher gemeldet, nicht durch Raten geheilt.
+    return {
+      url: "",
+      origin: "configured",
+      allowed: false,
+      reason: 'qdrant.mode is "external", but no `qdrant.url` is set.',
+      nextStep:
+        "Set your own instance's address as `qdrant.url`, or set " + 'qdrant.mode to "managed".',
+    };
+  }
+
+  return {
+    url: MANAGED_QDRANT_URL,
+    origin: "managed",
+    allowed: true,
+    reason: "Untangle's owned managed store (spec.md §3.1, port 16333)",
+  };
+}
+
+/**
+ * Der Riegel.
+ *
+ * Er sitzt hinter der Entscheidung, weil eine Adresse auch auf anderem Wege
+ * dort landen kann — ein kuenftiger Adapter mit eigener Vorgabe, eine
+ * Migration, ein Tippfehler in einer Vorgabekonstanten. Wird eine fremde
+ * Vorgabeadresse benutzt, OHNE dass sie jemand benannt hat, bricht der
+ * Befehl ab statt hineinzuschreiben.
+ */
+export function assertVectorStoreAllowed(decision: VectorStoreDecision, resolvedUrl: string): void {
+  if (!decision.allowed) {
+    throw new OperationalError(decision.reason, decision.nextStep ?? "See `untangle init`.");
+  }
+  if (decision.origin !== "managed") {
+    return;
+  }
+  const foreign = foreignDefaultFor(resolvedUrl);
+  if (foreign === undefined) {
+    return;
+  }
+  throw new OperationalError(
+    `${resolvedUrl} is the default port of a foreign Qdrant instance and was not explicitly ` +
+      `selected; Untangle will not take it over automatically. ${foreign.reason}`,
+    `Set UNTANGLE_QDRANT_URL=${resolvedUrl} if this instance is yours; ` +
+      `otherwise start an owned instance on ${MANAGED_QDRANT_URL}.`,
+  );
+}
+
+/**
+ * Welche Adressen `init` ueberhaupt anfassen darf — dieselbe Regel, von der
+ * anderen Seite gelesen.
+ *
+ * `probe` sind die Adressen, an die eine (ausschliesslich lesende) Anfrage
+ * gehen darf. `skipped` sind die bewusst ausgelassenen, JEWEILS MIT GRUND:
+ * eine ausgelassene Pruefung ohne Begruendung waere ein stilles
+ * Ueberspringen (E4), und genau dieses Schweigen hat `doctor` gefehlt.
+ */
+export function qdrantProbePlan(env: Readonly<Record<string, string | undefined>>): {
+  probe: string[];
+  skipped: { url: string; reason: string }[];
+} {
+  const configured = env["UNTANGLE_QDRANT_URL"];
+  const probe =
+    configured === undefined || configured.length === 0
+      ? [MANAGED_QDRANT_URL]
+      : normalize(configured) === normalize(MANAGED_QDRANT_URL)
+        ? [MANAGED_QDRANT_URL]
+        : [configured, MANAGED_QDRANT_URL];
+
+  const probing = new Set(probe.map(normalize));
+  const skipped = FOREIGN_DEFAULT_QDRANT_URLS.filter(
+    (entry) => !probing.has(normalize(entry.url)),
+  ).map((entry) => ({ ...entry }));
+
+  return { probe, skipped };
+}

package/src/cli/version.ts

@@ -0,0 +1,2 @@
+/** Package version shared by the CLI and its MCP entry point. */
+export const CLI_VERSION = "0.1.0";

package/src/cli/workspace.ts

@@ -0,0 +1,324 @@
+/**
+ * Die Verdrahtung, die fast jeder Befehl braucht: von der Konfiguration im
+ * Projekt zu den fertigen Adaptern.
+ *
+ * Diese Datei ist bewusst die EINZIGE Stelle, an der die Oberflaeche
+ * Adapterklassen anfasst. Jeder Befehl bekommt danach nur noch Ports zu
+ * sehen. Das ist keine Kosmetik: es ist der Grund, warum sich `query` gegen
+ * den In-Memory-Speicher des testkits genauso testen laesst wie gegen ein
+ * echtes Qdrant.
+ */
+
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  assertConfigValid,
+  deriveEmbeddingProfile,
+  loadConfig,
+  type ConfigIssue,
+  type EffectiveUntangleConfigV1,
+  type LoadConfigResult,
+} from "@untangle-code/config";
+import {
+  buildEmbeddingProfileId,
+  compareCodepoints,
+  embeddingProfileShortId,
+  type EmbeddingProfile,
+  type EmbeddingProvider,
+  type VectorStore,
+  type MetadataStore,
+  type GraphStore,
+} from "@untangle-code/domain";
+import { OllamaEmbeddingProvider } from "@untangle-code/embeddings-ollama";
+import {
+  createHybridSearchEngine,
+  type HybridSearchEngine,
+  type ProfileTargetV1,
+  type SearchGraphEnrichmentPort,
+} from "@untangle-code/search";
+import { createLanceDbStorage } from "@untangle-code/storage-lancedb";
+import {
+  FetchQdrantTransport,
+  codeCollectionName,
+  createQdrantStorage,
+  resolveQdrantStorageConfig,
+  textToBm25SparseVector,
+  QDRANT_STORAGE_DEFAULTS,
+  type QdrantStorageConfig,
+} from "@untangle-code/storage-qdrant";
+
+import { OperationalError } from "./exit.js";
+import type { IndexStateScope, IndexStateV1 } from "./index-state.js";
+import { systemClock, systemRandom } from "./system.js";
+import { assertVectorStoreAllowed, decideVectorStore } from "./vector-store-policy.js";
+
+/** Die aufgeloeste Sicht des Projekts, wie sie jeder Befehl sieht. */
+export interface WorkspaceView {
+  readonly root: string;
+  readonly config: EffectiveUntangleConfigV1;
+  readonly load: LoadConfigResult;
+  readonly workspaceId: string;
+  readonly profile: EmbeddingProfile;
+  readonly profileId: string;
+  readonly profileShortId: string;
+  /** Repository-IDs aus der Konfiguration, codepoint-sortiert. */
+  readonly repoIds: readonly string[];
+}
+
+/**
+ * Laedt die Konfiguration und leitet Identitaeten ab.
+ *
+ * `strict` entscheidet ueber spec.md §4.8: mit `strict` bricht ein
+ * Konfigurationsfehler ab (was jeder Befehl tut, der wirklich etwas tut),
+ * ohne `strict` kommen die Befunde als Daten zurueck (was `doctor` braucht,
+ * denn `doctor` soll den Fehler ja BERICHTEN statt an ihm zu sterben).
+ */
+export function loadWorkspace(options: {
+  cwd: string;
+  env: Readonly<Record<string, string | undefined>>;
+  workspaceIdOverride?: string | undefined;
+  strict: boolean;
+}): WorkspaceView {
+  const load = loadConfig({
+    cwd: options.cwd,
+    env: options.env as NodeJS.ProcessEnv,
+  });
+  if (options.strict) assertConfigValid(load.errors);
+
+  const profile = deriveEmbeddingProfile(load.effectiveConfig);
+  const profileId = buildEmbeddingProfileId(profile);
+  const repoIds = (load.effectiveConfig.repositories ?? [])
+    .map((repo) => repo.id)
+    .sort(compareCodepoints);
+
+  return {
+    root: load.sources.projectRoot ?? load.sources.configBaseDir,
+    config: load.effectiveConfig,
+    load,
+    workspaceId: options.workspaceIdOverride ?? load.workspaceId,
+    profile,
+    profileId,
+    profileShortId: embeddingProfileShortId(profileId),
+    repoIds,
+  };
+}
+
+/** Konfigurationsbefunde als Textzeilen — Warnungen wie Fehler, nie stumm. */
+export function describeConfigIssues(issues: readonly ConfigIssue[]): string[] {
+  return issues
+    .map((issue) => `${issue.path || "(root)"}: ${issue.message} [${issue.code}]`)
+    .sort(compareCodepoints);
+}
+
+export interface StorageWiring {
+  readonly qdrantConfig?: QdrantStorageConfig;
+  readonly backend: "lancedb" | "qdrant";
+  readonly storeUrl: string;
+  readonly storagePath?: string;
+  readonly collectionPrefix: string;
+  readonly storage: {
+    vectorStore: VectorStore;
+    metadataStore: MetadataStore;
+    graphStore: GraphStore;
+    close?: () => Promise<void>;
+  };
+  readonly vectorStore: VectorStore;
+  readonly codeCollection: string;
+  /** Woher die benutzte Adresse kommt — `doctor` zeigt das dem Nutzer. */
+  readonly decision: ReturnType<typeof decideVectorStore>;
+}
+
+/**
+ * Build the selected storage adapter from the resolved configuration.
+ * Local LanceDB is lazy; the service ownership policy below applies to Qdrant.
+ *
+ * WP-222: das ist der Engpass, durch den JEDER Befehl geht, der einen
+ * Vektorspeicher anfasst — und deshalb die Stelle, an der die Regel aus
+ * `vector-store-policy.ts` durchgesetzt wird. Sie wird VOR dem Aufloesen
+ * gefragt und danach noch einmal gegen das Ergebnis geprueft: die
+ * Entscheidung bestimmt die Adresse, statt eine Adapter-Vorgabe hinterher zu
+ * segnen. Vorher fiel `mode: "managed"` ohne `url` im Adapter auf den
+ * Standardport einer fremden Instanz zurueck, und `doctor` meldete diese
+ * Instanz als in Ordnung.
+ */
+export function wireStorage(
+  view: WorkspaceView,
+  env: Readonly<Record<string, string | undefined>>,
+): StorageWiring {
+  if (view.config.storage.backend === "lancedb") return wireLanceDbStorage(view);
+  if (view.config.storage.backend !== "qdrant") {
+    throw new OperationalError(
+      "Invalid storage backend.",
+      "Set storage.backend to lancedb or qdrant.",
+    );
+  }
+  const decision = decideVectorStore({ qdrant: view.config.qdrant, env });
+  if (!decision.allowed) {
+    throw new OperationalError(decision.reason, decision.nextStep ?? "See `untangle init --help`.");
+  }
+
+  let qdrantConfig: QdrantStorageConfig;
+  try {
+    qdrantConfig = resolveQdrantStorageConfig({ ...view.config.qdrant, url: decision.url }, env);
+  } catch (error) {
+    throw new OperationalError(
+      `Cannot resolve Qdrant configuration: ${errorMessage(error)}`,
+      'Check your configuration\'s `qdrant` section; mode "external" requires `url`.',
+      { cause: error },
+    );
+  }
+  assertVectorStoreAllowed(decision, qdrantConfig.url);
+
+  const transport = new FetchQdrantTransport({
+    url: qdrantConfig.url,
+    ...(qdrantConfig.apiKey === undefined ? {} : { apiKey: qdrantConfig.apiKey }),
+    requestTimeoutMs: qdrantConfig.requestTimeoutMs,
+  });
+  const storage = createQdrantStorage({ config: qdrantConfig, clock: systemClock, transport });
+
+  return {
+    backend: "qdrant",
+    storeUrl: qdrantConfig.url,
+    collectionPrefix: qdrantConfig.collectionPrefix,
+    qdrantConfig,
+    storage,
+    vectorStore: storage.vectorStore,
+    codeCollection: codeCollectionName(qdrantConfig.collectionPrefix, view.profileShortId),
+    decision,
+  };
+}
+
+/** Local storage is lazy: wiring and missing-index reads create no directories. */
+function wireLanceDbStorage(view: WorkspaceView): StorageWiring {
+  const storagePath = canonicalLocalPath(
+    path.resolve(view.root, view.config.storage.path ?? ".untangle/index/lancedb"),
+  );
+  const storeUrl = pathToFileURL(storagePath).href;
+  const config = QDRANT_STORAGE_DEFAULTS;
+  const storage = createLanceDbStorage({
+    path: storagePath,
+    clock: systemClock,
+    collectionPrefix: config.collectionPrefix,
+    upsertMaxPoints: config.upsertMaxPoints,
+    upsertBudgetBytes: config.upsertBudgetBytes,
+    graphPartBudgetBytes: config.graphPartBudgetBytes,
+  });
+  return {
+    backend: "lancedb",
+    storeUrl,
+    storagePath,
+    collectionPrefix: config.collectionPrefix,
+    storage,
+    vectorStore: storage.vectorStore,
+    codeCollection: codeCollectionName(config.collectionPrefix, view.profileShortId),
+    decision: {
+      url: storeUrl,
+      origin: "embedded",
+      allowed: true,
+      reason: "project-local LanceDB; no database server required",
+    },
+  };
+}
+
+function canonicalLocalPath(selected: string): string {
+  try {
+    return realpathSync(selected);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const parent = path.dirname(selected);
+    if (parent === selected) throw error;
+    return path.join(canonicalLocalPath(parent), path.basename(selected));
+  }
+}
+
+/** Old Qdrant records retain their endpoint identity; embedded stores never adopt them. */
+export function matchesStoredBackend(
+  state: IndexStateV1,
+  wiring: Pick<StorageWiring, "backend" | "storeUrl">,
+): boolean {
+  return (
+    (state.storageBackend ?? "qdrant") === wiring.backend &&
+    (state.storeUrl ?? state.qdrantUrl) === wiring.storeUrl
+  );
+}
+
+export function storageIndexScope(
+  wiring: Pick<StorageWiring, "backend" | "storeUrl">,
+): Pick<IndexStateScope, "storageBackend" | "storeUrl"> {
+  return { storageBackend: wiring.backend, storeUrl: wiring.storeUrl };
+}
+
+/** Baut den Ollama-Embedder aus der aufgeloesten Konfiguration. */
+export function wireEmbedder(view: WorkspaceView): EmbeddingProvider {
+  const embeddings = view.config.embeddings;
+  return new OllamaEmbeddingProvider(
+    {
+      profile: view.profile,
+      mode: embeddings.mode,
+      url: embeddings.url,
+      apiKeyEnv: embeddings.apiKeyEnv,
+      contextLength: embeddings.contextLength,
+      batchSize: embeddings.batchSize,
+      maxConnections: embeddings.maxConnections,
+      requestTimeoutMs: embeddings.requestTimeoutMs,
+    },
+    { clock: systemClock, random: systemRandom },
+  );
+}
+
+/**
+ * Baut den Abrufkern.
+ *
+ * Ein Ziel je Embedding-Profil (spec.md §13.4). Diese Fassung kennt genau ein
+ * Profil — das der Konfiguration. Mehrere Profile in einem Workspace sind im
+ * Abrufkern vorgesehen, hier aber noch nicht konfigurierbar; das steht so in
+ * der README unter „Bekannte Grenzen".
+ */
+export function wireSearchEngine(input: {
+  view: WorkspaceView;
+  vectorStore: VectorStore;
+  collection: string;
+  embedder: EmbeddingProvider;
+  indexContexts?: readonly {
+    repoId: string;
+    refId: string;
+    generationId: string;
+    corpusRevisionFingerprint?: string;
+    outcome: "running" | "completed" | "cancelled" | "failed";
+  }[];
+  graphEnrichment?: SearchGraphEnrichmentPort;
+}): HybridSearchEngine {
+  const target: ProfileTargetV1 = {
+    embeddingProfileId: input.view.profileId,
+    collection: input.collection,
+    repoIds: [...input.view.repoIds],
+    embedder: input.embedder,
+    ...(input.indexContexts === undefined ? {} : { indexContexts: input.indexContexts }),
+  };
+  return createHybridSearchEngine({
+    vectorStore: input.vectorStore,
+    targets: [target],
+    defaults: {
+      workspaceId: input.view.workspaceId,
+      limit: input.view.config.search.defaultLimit,
+      candidateLimit: input.view.config.search.defaultCandidateLimit,
+    },
+    searchConfig: input.view.config.search,
+    clock: systemClock,
+    sparseVectorizer: textToBm25SparseVector,
+    ...(input.graphEnrichment === undefined ? {} : { graphEnrichment: input.graphEnrichment }),
+  });
+}
+
+/** Die Botschaft eines unbekannten Wurfs, ohne je `[object Object]` zu zeigen. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}