karajan-code 3.14.0 → 3.15.0

package/src/orchestrator/stages/coder-stage.js

@@ -68,6 +68,12 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       // the plan, the rest are scoped to this HU. All four pass through
       // untouched when the caller omits them (legacy single-task runs).
       adrs, specSection, reviewerFindings, huId,
+      // PAR-E2 (KJC-TSK-0629): the stage's config wins over the role's own —
+      // worktree lanes pass a laneConfig whose projectDir is the worktree.
+      projectDir: config?.projectDir || null,
+      // PAR-H (KJC-TSK-0631): lane env (KJ_LANE_SLOT / KJ_PORT_OFFSET)
+      // reaches the coder subprocess so services it starts don't collide.
+      env: config?.lane_env || null,
       onOutput: coderStall.onOutput,
       // Lets Brain Recovery persist a standby snapshot if the coder's
       // provider hits a quota cap mid-run (KJC hibernation wiring).
@@ -429,8 +435,10 @@ export async function runTddCheckStage({ config, logger, emitter, eventBase, ses
   logger.setContext({ iteration, stage: "tdd" });
   let tddDiff, untrackedFiles;
   try {
-    tddDiff = await generateDiff({ baseRef: session.session_start_sha });
-    untrackedFiles = await getUntrackedFiles();
+    // PAR-E2 (KJC-TSK-0629): diff where the coder actually worked — a
+    // worktree lane's changes are invisible from the main tree.
+    tddDiff = await generateDiff({ baseRef: session.session_start_sha, projectDir: config?.projectDir || null });
+    untrackedFiles = await getUntrackedFiles(config?.projectDir || null);
   } catch (err) {
     logger.warn(`TDD diff generation failed: ${err.message}`);
     return { action: "continue", stageResult: { ok: false, summary: `TDD check failed: ${err.message}` } };

package/src/orchestrator/stages/reviewer-stage.js

@@ -194,14 +194,14 @@ async function handleReviewerRejection({ review, repeatDetector, config, logger,
   });
 }
 
-export async function fetchReviewDiff(session, logger) {
+export async function fetchReviewDiff(session, logger, projectDir = null) {
   let diff;
   if (session.ci_pr_number) {
     const { getPrDiff } = await import("../../ci/pr-diff.js");
     diff = await getPrDiff(session.ci_pr_number);
     logger.info(`Reviewer reading PR diff #${session.ci_pr_number}`);
   } else {
-    diff = await generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true });
+    diff = await generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true, projectDir });
   }
   // Inbound boundary: mask hardcoded secrets before the diff reaches the
   // (possibly cloud) reviewer model. Runs BEFORE the injection guard below so
@@ -221,7 +221,7 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
 
   let diff;
   try {
-    diff = await fetchReviewDiff(session, logger);
+    diff = await fetchReviewDiff(session, logger, config?.projectDir || null);
   } catch (err) {
     logger.warn(`Review diff generation failed: ${err.message}`);
     return { approved: false, blocking_issues: [{ description: `Diff generation failed: ${err.message}` }], non_blocking_suggestions: [], summary: `Reviewer failed: cannot generate diff — ${err.message}`, confidence: 0 };

package/src/plan/plan-executor.js

@@ -24,6 +24,10 @@ export function planToHuBatch(plan) {
     task_type: hu.task_type || "sw",
     status: hu.status === "certified" ? "certified" : hu.status,
     blocked_by: hu.blocked_by || [],
+    // KJC-BUG-0110: scope must survive as its own field — the parallel
+    // scheduler treats a scopeless story as exclusive, so dropping it
+    // silently degrades --parallel N to sequential.
+    scope: hu.scope || null,
     certified: { text: hu.scope || hu.title },
     acceptance_criteria: hu.acceptance_criteria || [],
     acceptance_tests: hu.acceptance_tests || [],

package/src/plan/preflight-hu.js

@@ -88,6 +88,9 @@ export async function prependPreflightHu(plan, projectDir) {
     title: "[PREFLIGHT-000] Verificar entorno de desarrollo listo",
     description: "[PREFLIGHT-000] Block functional HUs until the project's environment is reproducible: deps installed, build/test/lint passing, git tree clean, cloud auth ready when applicable.",
     task_type: "infra",
+    // KJC-BUG-0108: without an explicit status, `kj plan ready` rejects the
+    // whole plan with "invalid status undefined".
+    status: "pending",
     blocked_by: [],
     reuse: [],
     acceptance_tests: composePreflightTests(stack, projectDir),

package/src/rag/embedder.js

@@ -1,81 +1,2 @@
-// KJC-PCS-0049 Step 2 — Ollama embedder adapter for the RAG pipeline.
-// Talks to a local Ollama server (POST /api/embeddings) and returns
-// Float32Array vectors. Cero deps externas; usa fetch global.
-//
-// Defaults:
-//   url       = process.env.KJ_OLLAMA_URL or "http://localhost:11434"
-//   model     = process.env.KJ_OLLAMA_EMBED_MODEL or "nomic-embed-text"
-//   dim       = 768  (matches nomic-embed-text)
-//   timeoutMs = 30000
-
-const DEFAULT_URL = "http://localhost:11434";
-const DEFAULT_MODEL = "nomic-embed-text";
-const DEFAULT_DIM = 768;
-const DEFAULT_TIMEOUT_MS = 30000;
-
-export class OllamaEmbedderError extends Error {
-  constructor(message, { cause, status } = {}) {
-    super(message);
-    this.name = "OllamaEmbedderError";
-    if (cause) this.cause = cause;
-    if (status != null) this.status = status;
-  }
-}
-
-export class OllamaEmbedder {
-  constructor({
-    url = process.env.KJ_OLLAMA_URL || DEFAULT_URL,
-    model = process.env.KJ_OLLAMA_EMBED_MODEL || DEFAULT_MODEL,
-    dim = DEFAULT_DIM,
-    timeoutMs = DEFAULT_TIMEOUT_MS,
-    fetchFn = globalThis.fetch,
-  } = {}) {
-    this.url = url.replace(/\/$/, "");
-    this.model = model;
-    this.dim = dim;
-    this.timeoutMs = timeoutMs;
-    this.fetch = fetchFn;
-  }
-
-  /** Single-text embedding. Returns Float32Array(dim). */
-  async embed(text) {
-    if (typeof text !== "string" || text.length === 0) {
-      throw new OllamaEmbedderError("embed: text must be a non-empty string");
-    }
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-    let res;
-    try {
-      res = await this.fetch(`${this.url}/api/embeddings`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ model: this.model, prompt: text }),
-        signal: ctrl.signal,
-      });
-    } catch (err) {
-      throw new OllamaEmbedderError(`Ollama embed request failed (${this.url}): ${err.message}`, { cause: err });
-    } finally {
-      clearTimeout(timer);
-    }
-    if (!res.ok) {
-      throw new OllamaEmbedderError(`Ollama embed HTTP ${res.status} from ${this.url}`, { status: res.status });
-    }
-    const body = await res.json();
-    const arr = body?.embedding;
-    if (!Array.isArray(arr) || arr.length === 0) {
-      throw new OllamaEmbedderError("Ollama response missing 'embedding' array");
-    }
-    if (arr.length !== this.dim) {
-      throw new OllamaEmbedderError(`Ollama dim mismatch: got ${arr.length}, expected ${this.dim} for model ${this.model}`);
-    }
-    return Float32Array.from(arr);
-  }
-
-  /** Batch embedding (sequential — Ollama /api/embeddings is single-text). */
-  async embedBatch(texts) {
-    if (!Array.isArray(texts)) throw new OllamaEmbedderError("embedBatch: texts must be an array");
-    const out = [];
-    for (const t of texts) out.push(await this.embed(t));
-    return out;
-  }
-}
+// Shim: embedder now lives in karajan-core/rag (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedder";

package/src/rag/embedders/_cloud-base.js

@@ -1,24 +1,2 @@
-// KJC-TSK-0442 — shared POST helper for cloud embedders (OpenAI, Voyage).
-// Same envelope: Bearer auth, JSON body shaped by caller, JSON response
-// extracted by caller, dim validated against the adapter's expected size.
-export async function cloudEmbed(adapter, text, ErrCls, { provider, body, extract }) {
-  if (typeof text !== "string" || text.length === 0) throw new ErrCls("embed: text must be a non-empty string");
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), adapter.timeoutMs);
-  let res;
-  try {
-    res = await adapter.fetch(adapter.url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${adapter.apiKey}` },
-      body: JSON.stringify(body),
-      signal: ctrl.signal,
-    });
-  } catch (err) { throw new ErrCls(`${provider} embed request failed: ${err.message}`, { cause: err }); }
-  finally { clearTimeout(timer); }
-  if (!res.ok) throw new ErrCls(`${provider} embed HTTP ${res.status}`, { status: res.status });
-  const json = await res.json();
-  const arr = extract(json);
-  if (!Array.isArray(arr) || arr.length === 0) throw new ErrCls(`${provider} response missing embedding`);
-  if (arr.length !== adapter.dim) throw new ErrCls(`${provider} dim mismatch: got ${arr.length}, expected ${adapter.dim} for model ${adapter.model}`);
-  return Float32Array.from(arr);
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/_cloud-base";

package/src/rag/embedders/cohere.js

@@ -1,28 +1,2 @@
-// KJC-TSK-0446 — Cohere embed-v3 adapter. Cohere returns
-// { embeddings: { float: [[...]] } } when `embedding_types: ["float"]`
-// is requested, or { embeddings: [[...]] } in legacy v1. We extract the
-// modern shape with a v1 fallback.
-import { cloudEmbed } from "./_cloud-base.js";
-
-const DEFAULTS = { url: "https://api.cohere.com/v2/embed", model: "embed-multilingual-v3.0", dim: 1024, timeoutMs: 30000 };
-
-export class CohereEmbedderError extends Error {
-  constructor(message, { cause, status } = {}) { super(message); this.name = "CohereEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
-}
-
-export class CohereEmbedder {
-  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_COHERE_KEY, model = process.env.KJ_COHERE_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
-    // KJC architecture invariant: scoped env var (KJ_COHERE_KEY), not the
-    // generic COHERE_API_KEY — same rule as OpenAI/Voyage adapters.
-    if (!apiKey) throw new CohereEmbedderError("Cohere embedder requires an api_key (config.rag.embedder.api_key or KJ_COHERE_KEY env)");
-    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
-  }
-  async embed(text) {
-    return cloudEmbed(this, text, CohereEmbedderError, {
-      provider: "Cohere",
-      body: { model: this.model, texts: [text], input_type: "search_document", embedding_types: ["float"] },
-      extract: (b) => b?.embeddings?.float?.[0] || b?.embeddings?.[0],
-    });
-  }
-  async embedBatch(texts) { if (!Array.isArray(texts)) throw new CohereEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/cohere";

package/src/rag/embedders/factory.js

@@ -1,29 +1,2 @@
-// KJC-TSK-0442 / KJC-TSK-0446 — Embedder factory. Selects provider from
-// config.rag.embedder.provider (ollama | openai | voyage | cohere | mistral;
-// default ollama). Each provider has its own dim default; the factory wires
-// it so the caller does not need to know.
-import { OllamaEmbedder } from "../embedder.js";
-import { OpenAIEmbedder } from "./openai.js";
-import { VoyageEmbedder } from "./voyage.js";
-import { CohereEmbedder } from "./cohere.js";
-import { MistralEmbedder } from "./mistral.js";
-import { ONNXEmbedder } from "./onnx.js";
-
-const PROVIDERS = {
-  ollama: { cls: OllamaEmbedder, dim: 768 },
-  openai: { cls: OpenAIEmbedder, dim: 1536 },
-  voyage: { cls: VoyageEmbedder, dim: 1024 },
-  cohere: { cls: CohereEmbedder, dim: 1024 },
-  mistral: { cls: MistralEmbedder, dim: 1024 },
-  onnx: { cls: ONNXEmbedder, dim: 384 },
-};
-
-export function makeEmbedder(config = {}) {
-  const cfg = config?.rag?.embedder || {};
-  const provider = cfg.provider || "ollama";
-  const spec = PROVIDERS[provider];
-  if (!spec) throw new Error(`Unknown embedder provider: ${provider}. Supported: ${Object.keys(PROVIDERS).join(", ")}`);
-  const dim = cfg.dim || spec.dim;
-  return new spec.cls({ url: cfg.url, apiKey: cfg.api_key, model: cfg.model, dim, timeoutMs: cfg.timeout_ms });
-}
-
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/factory";

package/src/rag/embedders/mistral.js

@@ -1,26 +1,2 @@
-// KJC-TSK-0446 — Mistral AI embeddings adapter. EU-hosted, useful for
-// users with GDPR constraints that prefer not to send chunks to US
-// endpoints. Single model today (`mistral-embed`, 1024 dim).
-import { cloudEmbed } from "./_cloud-base.js";
-
-const DEFAULTS = { url: "https://api.mistral.ai/v1/embeddings", model: "mistral-embed", dim: 1024, timeoutMs: 30000 };
-
-export class MistralEmbedderError extends Error {
-  constructor(message, { cause, status } = {}) { super(message); this.name = "MistralEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
-}
-
-export class MistralEmbedder {
-  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_MISTRAL_KEY, model = process.env.KJ_MISTRAL_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
-    // KJC architecture invariant: scoped env var (KJ_MISTRAL_KEY).
-    if (!apiKey) throw new MistralEmbedderError("Mistral embedder requires an api_key (config.rag.embedder.api_key or KJ_MISTRAL_KEY env)");
-    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
-  }
-  async embed(text) {
-    return cloudEmbed(this, text, MistralEmbedderError, {
-      provider: "Mistral",
-      body: { model: this.model, input: [text] },
-      extract: (b) => b?.data?.[0]?.embedding,
-    });
-  }
-  async embedBatch(texts) { if (!Array.isArray(texts)) throw new MistralEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/mistral";

package/src/rag/embedders/onnx.js

@@ -1,63 +1,2 @@
-// KJC-TSK-0447 — ONNX local embedder via @huggingface/transformers
-// (formerly @xenova/transformers). Runs sentence-transformer models
-// directly in Node — no API key, no Docker, no Ollama.
-//
-// First call downloads the model weights to ~/.cache/huggingface/ (~80 MB
-// for the default MiniLM). Subsequent calls reuse the cache, so the steady
-// state is fully offline.
-//
-// Default model: `Xenova/all-MiniLM-L6-v2` (384 dim, ~80 MB, fast).
-// Higher-quality alternative: `Xenova/jina-embeddings-v2-base-en`
-// (768 dim, ~260 MB, slower but better for retrieval).
-
-const DEFAULTS = { model: "Xenova/all-MiniLM-L6-v2", dim: 384, pooling: "mean", normalize: true };
-
-export class ONNXEmbedderError extends Error {
-  constructor(message, { cause } = {}) { super(message); this.name = "ONNXEmbedderError"; if (cause) this.cause = cause; }
-}
-
-async function loadTransformers() {
-  // Prefer the modern @huggingface/transformers (post-2024 rebrand);
-  // fall back to @xenova/transformers for users still on the legacy package.
-  // Both are optional peer deps — Karajan does not ship them by default to
-  // keep the install size small (~500 MB with WASM + weights). The user
-  // installs whichever they prefer when they opt into provider: onnx.
-  /* eslint-disable import-x/no-unresolved */
-  try { return await import("@huggingface/transformers"); }
-  catch (e1) {
-    try { return await import("@xenova/transformers"); }
-    catch (e2) {
-      throw new ONNXEmbedderError(
-        "ONNX embedder requires @huggingface/transformers (or legacy @xenova/transformers). Install with `npm install @huggingface/transformers`.",
-        { cause: e2 },
-      );
-    }
-  }
-  /* eslint-enable import-x/no-unresolved */
-}
-
-export class ONNXEmbedder {
-  constructor({ model = process.env.KJ_ONNX_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, pooling = DEFAULTS.pooling, normalize = DEFAULTS.normalize } = {}) {
-    Object.assign(this, { model, dim, pooling, normalize, _pipe: null });
-  }
-  async _ensurePipeline() {
-    if (this._pipe) return this._pipe;
-    const transformers = await loadTransformers();
-    this._pipe = await transformers.pipeline("feature-extraction", this.model);
-    return this._pipe;
-  }
-  async embed(text) {
-    if (typeof text !== "string" || text.length === 0) throw new ONNXEmbedderError("embed: text must be a non-empty string");
-    const pipe = await this._ensurePipeline();
-    const out = await pipe(text, { pooling: this.pooling, normalize: this.normalize });
-    const arr = Array.from(out.data || []);
-    if (arr.length !== this.dim) throw new ONNXEmbedderError(`ONNX dim mismatch: got ${arr.length}, expected ${this.dim} for model ${this.model}`);
-    return Float32Array.from(arr);
-  }
-  async embedBatch(texts) {
-    if (!Array.isArray(texts)) throw new ONNXEmbedderError("embedBatch: texts must be an array");
-    const out = [];
-    for (const t of texts) out.push(await this.embed(t));
-    return out;
-  }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/onnx";

package/src/rag/embedders/openai.js

@@ -1,22 +1,2 @@
-// KJC-TSK-0442 — OpenAI text-embeddings adapter.
-import { cloudEmbed } from "./_cloud-base.js";
-
-const DEFAULTS = { url: "https://api.openai.com/v1/embeddings", model: "text-embedding-3-small", dim: 1536, timeoutMs: 30000 };
-
-export class OpenAIEmbedderError extends Error {
-  constructor(message, { cause, status } = {}) { super(message); this.name = "OpenAIEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
-}
-
-export class OpenAIEmbedder {
-  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_OPENAI_KEY, model = process.env.KJ_OPENAI_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
-    // KJC architecture invariant: Karajan does not read provider API keys
-    // (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) — those belong to the CLI
-    // agents Karajan spawns. RAG embedders are the one exception: they
-    // call the OpenAI endpoint directly, but use a Karajan-scoped env var
-    // (KJ_OPENAI_KEY) so the invariant stays clean.
-    if (!apiKey) throw new OpenAIEmbedderError("OpenAI embedder requires an api_key (config.rag.embedder.api_key or KJ_OPENAI_KEY env)");
-    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
-  }
-  async embed(text) { return cloudEmbed(this, text, OpenAIEmbedderError, { provider: "OpenAI", body: { model: this.model, input: text }, extract: (b) => b?.data?.[0]?.embedding }); }
-  async embedBatch(texts) { if (!Array.isArray(texts)) throw new OpenAIEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/openai";

package/src/rag/embedders/voyage.js

@@ -1,18 +1,2 @@
-// KJC-TSK-0442 — Voyage AI embeddings adapter.
-import { cloudEmbed } from "./_cloud-base.js";
-
-const DEFAULTS = { url: "https://api.voyageai.com/v1/embeddings", model: "voyage-code-3", dim: 1024, timeoutMs: 30000 };
-
-export class VoyageEmbedderError extends Error {
-  constructor(message, { cause, status } = {}) { super(message); this.name = "VoyageEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
-}
-
-export class VoyageEmbedder {
-  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_VOYAGE_KEY, model = process.env.KJ_VOYAGE_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
-    // Same invariant as OpenAIEmbedder: Karajan-scoped env var.
-    if (!apiKey) throw new VoyageEmbedderError("Voyage embedder requires an api_key (config.rag.embedder.api_key or KJ_VOYAGE_KEY env)");
-    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
-  }
-  async embed(text) { return cloudEmbed(this, text, VoyageEmbedderError, { provider: "Voyage", body: { model: this.model, input: [text], input_type: "document" }, extract: (b) => b?.data?.[0]?.embedding }); }
-  async embedBatch(texts) { if (!Array.isArray(texts)) throw new VoyageEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
-}
+// Shim: moved to karajan-core/rag/embedders (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/embedders/voyage";

package/src/rag/rerank.js

@@ -1,74 +1,4 @@
-// KJC-TSK-0449 — Cross-encoder rerank stage. Re-scores the top-N hits
-// from the hybrid retriever using a (query, passage) cross-encoder.
-//
-// Cross-encoders are slower than the bi-encoder embedders (they jointly
-// encode query + passage instead of caching the passage), but they are
-// substantially more precise for the final top-K ranking. Karajan calls
-// the reranker only on the post-fusion candidates (≤topK*2), so the
-// added latency is bounded.
-//
-// Model is loaded dynamically via @huggingface/transformers (same dep as
-// the ONNX embedder, KJC-TSK-0447). Default: `Xenova/ms-marco-MiniLM-L-6-v2`,
-// the de-facto standard sentence-transformers reranker.
-
-const DEFAULT_MODEL = "Xenova/ms-marco-MiniLM-L-6-v2";
-
-export class RerankError extends Error {
-  constructor(message, { cause } = {}) { super(message); this.name = "RerankError"; if (cause) this.cause = cause; }
-}
-
-async function loadTransformers() {
-  /* eslint-disable import-x/no-unresolved */
-  try { return await import("@huggingface/transformers"); }
-  catch (e1) {
-    try { return await import("@xenova/transformers"); }
-    catch (e2) {
-      throw new RerankError(
-        "rerank requires @huggingface/transformers (or legacy @xenova/transformers). Install with `npm install @huggingface/transformers`.",
-        { cause: e2 },
-      );
-    }
-  }
-  /* eslint-enable import-x/no-unresolved */
-}
-
-/**
- * Lazy singleton — first call downloads weights (~80 MB), every subsequent
- * call reuses the same pipeline instance.
- */
-let _pipelinePromise = null;
-function getPipeline(modelName) {
-  if (!_pipelinePromise) _pipelinePromise = (async () => {
-    const t = await loadTransformers();
-    // text-classification pipeline returns the cross-encoder relevance score
-    // for a `[query, passage]` text pair when applied to a CE model.
-    return t.pipeline("text-classification", modelName);
-  })();
-  return _pipelinePromise;
-}
-
-/** Reset for tests. */
-export function _resetPipeline() { _pipelinePromise = null; }
-
-/**
- * Rerank `hits` against `queryText` using the cross-encoder. Returns a NEW
- * array sorted by descending rerank score (best first), `score` mutated
- * so the existing downstream code (kindBoost, slicing) keeps working.
- *
- * Each input hit is treated as a [query, hit.text] pair. Truncates the
- * passage to `maxChars` to avoid blowing past the CE model's context
- * window — most CE models handle 512 tokens, ~2000 chars is safe.
- *
- * If `pipelineFn` is injected (tests), it bypasses model loading.
- */
-export async function rerank(queryText, hits, { model = process.env.KJ_RERANK_MODEL || DEFAULT_MODEL, maxChars = 2000, pipelineFn = null } = {}) {
-  if (!queryText || typeof queryText !== "string") throw new RerankError("rerank: queryText must be a non-empty string");
-  if (!Array.isArray(hits)) throw new RerankError("rerank: hits must be an array");
-  if (hits.length === 0) return hits;
-  const pipe = pipelineFn || await getPipeline(model);
-  const pairs = hits.map((h) => ({ text: queryText, text_pair: String(h.text || "").slice(0, maxChars) }));
-  const results = await pipe(pairs);
-  return hits
-    .map((h, i) => ({ ...h, _rerank: Number(results[i]?.score) || 0, score: -Number(results[i]?.score) || 0 }))
-    .sort((a, b) => a.score - b.score);
-}
+// Shim: rerank now lives in karajan-core/rag so the hu-board workspace
+// can consume it without a relative dep on the CLI src tree.
+// KJC-TSK-0632 PR2.
+export { RerankError, _resetPipeline, rerank } from "karajan-core/rag/rerank";

package/src/rag/retriever.js

@@ -1,127 +1,2 @@
-// KJC-PCS-0049 Step 5 — Retriever for the RAG pipeline.
-import { searchSimilar, searchBM25, getEmbeddingsByIds } from "./vec-store.js";
-import { parseWhere, buildWhereSql } from "./where-parser.js";
-import { rerank } from "./rerank.js";
-
-const DEFAULT_KIND_BOOST = { plan: 0.05, onboarding: 0.03, code: 0 };
-
-// KJC-TSK-0440 — asymmetric source/test boost.
-const SOURCE_BOOST_NON_TEST = 0.05;
-const TEST_TERMS_RE = /\b(test|tests|spec|specs|expect|describe|it\(|jest|vitest|mocha)\b/i;
-const TEST_PATH_RE = /[\\/](tests?|specs?|__tests__)[\\/]|\.test\.[jt]sx?$|\.spec\.[jt]sx?$/i;
-
-function shouldBoostSources(queryText) { return !TEST_TERMS_RE.test(queryText); }
-function isTestPath(source) { return TEST_PATH_RE.test(source || ""); }
-
-// KJC-TSK-0443 — fuse semantic + keyword hits into a unified candidate set.
-// For 'semantic'/'keyword' modes we surface that side. For 'hybrid' (default)
-// we min-max normalise both scores to [0,1] (lower=better) and linear-combine
-// via alpha * semantic + (1-alpha) * keyword. Result written back to
-// `distance` so the kind+source boost pipeline keeps working unchanged.
-function fuseHits(semantic, keyword, alpha, mode) {
-  if (mode === "semantic") return semantic;
-  if (mode === "keyword") return keyword.map((h) => ({ ...h, distance: h.bm25 }));
-  const byId = new Map();
-  for (const h of semantic) byId.set(h.id, { ...h, _sem: h.distance });
-  for (const h of keyword) {
-    const prev = byId.get(h.id);
-    if (prev) prev._kw = h.bm25;
-    else byId.set(h.id, { ...h, _kw: h.bm25, distance: h.bm25 });
-  }
-  const list = [...byId.values()];
-  const norm = (vals) => {
-    const xs = vals.filter((v) => Number.isFinite(v));
-    if (xs.length === 0) return () => 0.5;
-    const min = Math.min(...xs); const max = Math.max(...xs); const span = max - min || 1;
-    return (v) => Number.isFinite(v) ? (v - min) / span : 1;
-  };
-  const nSem = norm(list.map((h) => h._sem));
-  const nKw = norm(list.map((h) => h._kw));
-  for (const h of list) h.distance = alpha * nSem(h._sem) + (1 - alpha) * nKw(h._kw);
-  return list;
-}
-
-// KJC-TSK-0484 PR-B — Maximal Marginal Relevance. Given an ordered list of
-// candidates (best-first by `score`), pick `topK` that balance relevance
-// against intra-result diversity. `lambda=1` collapses to plain relevance;
-// `lambda=0` maximises diversity. Cosine sim between candidate embeddings
-// drives the redundancy penalty. Candidates without an embedding are kept
-// at the end (no penalty applies).
-function cosineSim(a, b) {
-  if (!a || !b || a.length !== b.length) return 0;
-  let dot = 0; let na = 0; let nb = 0;
-  for (let i = 0; i < a.length; i += 1) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
-  const denom = Math.sqrt(na) * Math.sqrt(nb);
-  return denom === 0 ? 0 : dot / denom;
-}
-
-export function mmrRerank(candidates, embeddings, { topK, lambda = 0.7 }) {
-  const remaining = candidates.slice();
-  const picked = [];
-  const relevance = (c) => 1 / (1 + Math.max(0, c.score ?? c.distance ?? 0));
-  while (picked.length < topK && remaining.length > 0) {
-    let bestIdx = 0; let bestVal = -Infinity;
-    for (let i = 0; i < remaining.length; i += 1) {
-      const c = remaining[i];
-      const rel = relevance(c);
-      let maxSim = 0;
-      const ce = embeddings.get(c.id);
-      if (ce && picked.length > 0) {
-        for (const p of picked) {
-          const pe = embeddings.get(p.id);
-          if (pe) maxSim = Math.max(maxSim, cosineSim(ce, pe));
-        }
-      }
-      const score = lambda * rel - (1 - lambda) * maxSim;
-      if (score > bestVal) { bestVal = score; bestIdx = i; }
-    }
-    picked.push(remaining.splice(bestIdx, 1)[0]);
-  }
-  return picked;
-}
-
-export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null, mode = "hybrid", alpha = 0.6, where = null, rerankOpts = null, diversify = false, mmrLambda = 0.7 } = {}) {
-  if (!text || typeof text !== "string") throw new Error("query: text must be a non-empty string");
-  const fetchK = Math.min(50, topK * 2);
-  const scopeKind = scope === "plans" ? "plan" : scope === "code" ? "code" : scope === "onboarding" ? "onboarding" : null;
-  // KJC-TSK-0448 — metadata filter. `where` is a string like "symbol=Foo AND
-  // hu_id=HU-003"; we parse once and reuse the SQL fragment across both
-  // semantic and keyword searches.
-  const parsed = parseWhere(where);
-  if (!parsed.ok) throw new Error(`query: ${parsed.error}`);
-  const { sql: whereSql, params: whereParams } = buildWhereSql(parsed.clauses);
-  const opts = { kind: scopeKind, project, whereSql, whereParams };
-  const wantSemantic = mode !== "keyword";
-  const wantKeyword = mode !== "semantic";
-  const semanticHits = wantSemantic ? searchSimilar(db, await embedder.embed(text), fetchK, opts) : [];
-  const keywordHits = wantKeyword ? searchBM25(db, text, fetchK, opts) : [];
-  const raw = fuseHits(semanticHits, keywordHits, alpha, mode);
-  if (raw.length === 0) return [];
-  const boostSources = shouldBoostSources(text);
-  const scored = raw.map((r) => {
-    const kindB = kindBoost[r.kind] || 0;
-    const sourceB = (boostSources && r.kind === "code" && !isTestPath(r.source)) ? SOURCE_BOOST_NON_TEST : 0;
-    return { ...r, score: r.distance - kindB - sourceB };
-  }).sort((a, b) => a.score - b.score);
-  // KJC-TSK-0484 PR-B — MMR diversification over topK*2 candidates. Fetches
-  // embeddings only when requested; cosine between candidate vectors drives
-  // the redundancy penalty so near-duplicates that survived dedup (e.g. a
-  // boilerplate chunk repeated under slightly different wording) get pushed
-  // down. Skipped entirely when `diversify=false` (default).
-  let reranked;
-  if (diversify) {
-    const pool = scored.slice(0, Math.min(scored.length, topK * 2));
-    const embeddings = getEmbeddingsByIds(db, pool.map((c) => c.id));
-    reranked = mmrRerank(pool, embeddings, { topK, lambda: mmrLambda });
-  } else {
-    reranked = scored.slice(0, topK);
-  }
-  // KJC-TSK-0449 — optional cross-encoder rerank. When `rerankOpts` is set,
-  // we re-score the topK survivors with a (query, passage) cross-encoder;
-  // the kind+source boost has already been applied, so the rerank acts as
-  // a finer-grained quality lever on top.
-  if (rerankOpts) return await rerank(text, reranked, rerankOpts);
-  return reranked;
-}
-
-export { fuseHits, cosineSim };
+// Shim: retriever now lives in karajan-core/rag (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/retriever";