v1.3.0

Added

• Modo CAG — Cache-Augmented Generation (épica KJR-PCS-0017):
  query --answer --mode cag carga el corpus COMPLETO como contexto del
  modelo en vez de recuperar top-k chunks. Contexto determinista y
  estable (orden por ruta, contextHash) para amortizar el prompt-cache
  del proveedor; sensibilidad efectiva = máximo global del manifest (el
  gate y redactPII aplican por el mismo camino guardado que RAG);
  presupuesto --max-context-chars (default 400K chars) con fallo
  explícito — nunca truncado silencioso. No requiere vector store para
  responder. API: buildCagContext, DEFAULT_CAG_MAX_CHARS.

v1.2.0

Added

• karajan-rag report-issue (KJR-TSK-0140): reporta fricciones al
  repo público con una issue saneada — rutas home colapsadas a ~ y PII
  redactada con el propio redactPII del pipeline (emails, teléfonos,
  NIF/NIE, tarjetas, IBAN, resistente a ofuscación Unicode). Dedup contra
  las issues abiertas por solape de título (degrada sin bloquear;
  --force para saltarlo). Por defecto imprime preview + URL prefabricada
  — publicar es decisión humana; --publish usa el CLI de gh. --json
  para agentes. El prompt start.md instruye a los agentes IA a reportar
  fricciones con él, confirmando siempre antes de publicar.

v1.1.0

Added

• Instalación con garantías (KJR-TSK-0138): scripts/install.sh
  (Linux/macOS, POSIX) y scripts/install.ps1 (Windows, PowerShell 5.1) —
  npm-first con Node ≥18, o autoprovisión del Node LTS oficial en
  ~/.karajan-rag/node verificando SHASUMS256, con staging + backup +
  rollback. Instalan el paquete junto al peer del store por defecto
  (@lancedb/lancedb): instalación completa o fallo claro, nunca producto
  degradado en silencio (opt-out KJR_NO_STORE=1). Servidos desde
  rag.karajancode.com/install.sh y /install.ps1.
• Prompts de arranque para agentes IA: docs/prompts/start.md
  (enrutador OS-aware), install-machine.md y rag-project.md — con regla
  dura de parar-y-esperar ante privilegios elevados y la decisión de
  sensibilidad siempre en manos del usuario. El usuario solo pega:
  "I want a RAG over this project: read rag.karajancode.com/start.md and
  do what it says."
• Aliases del CLI: kj-rag y kjr como bins equivalentes a
  karajan-rag (aditivo, el nombre largo sigue siendo el canónico).
• --version / -v en el CLI — la sonda que usan el instalador y el
  enrutador de prompts.

v1.0.0

Changed

• API pública estable. Desde esta versión aplica semver estricto: los
  cambios breaking requieren major y la política de deprecación
  garantiza 2 minors de preaviso. La superficie exportada queda fijada
  por el test de contrato (tests/public-api.test.js).

Security

• Revisión independiente de la política de sensibilidad y el redactor
  PII completada (criterio final de salida de la serie 0.x): 3 pasadas
  iterativas de verificación hostil ejecutadas por un modelo de otro
  proveedor (OpenAI Codex, sandbox read-only), con informes íntegros
  versionados en docs/security/reviews/. Veredicto final: APROBADO
  CON RESERVAS en el perímetro declarado. El proceso destapó y corrigió
  4 hallazgos + residuales:
  • KJR-BUG-0007 (crítico): el reindex incremental no reestampaba la
    sensibilidad de ficheros sin cambios; además, la query confiaba en la
    metadata del store. Ahora el nivel se persiste por fichero en el
    manifest, un nivel distinto fuerza reprocesado y el manifest actúa
    como suelo autoritativo en query (ante discrepancia gana el nivel
    más restrictivo; una fuente desconocida nunca es public).
  • KJR-BUG-0010 (alto): el inventario de flujos del paquete de auditoría
    no cubría RerankerRole (llm) ni EvaluatorRole — corregido el
    inventario y señalizada la frontera de responsabilidad en JSDoc.
  • KJR-BUG-0008: las reglas de sensibilidad matcheaban por prefijo de
    string; ahora respetan fronteras de segmento de ruta y las formas
    ambiguas (./, .., \, absolutas) se rechazan en validación.
  • KJR-BUG-0009: redactPII era evadible con Unicode — ahora normaliza
    NFKC, elimina zero-width y acepta NIF/NIE con separadores; los
    homoglifos quedan como límite conocido declarado y fijado por test.

v0.7.0

Fixed

• KJR-BUG-0006 cerrado — la capa easy aplica la sensitivity policy
  completa (ADR-005 §6, hallazgo H1 de la auditoría interna). El nivel
  efectivo de una consulta es el máximo de los chunks recuperados y
  toda salida hacia un LLM pasa por la policy:
  • query --answer: --adapter explícito no permitido para el nivel →
    error accionable (nivel, permitidos y cómo corregirlo); adapter de
    config/default no permitido → se enruta al primer proveedor permitido
    con aviso. El registry incluye ollama (HTTP local) para que
    confidential tenga siempre salida.
  • eval --judges: flag nuevo --sensitivity (default seguro
    internal) con gate que rechaza jueces no permitidos antes de enviar
    nada.
  • Los índices creados antes de 0.7.0 no tienen marca de nivel: sus
    chunks cuentan como internal (nunca public). Reindexa para
    aplicar tus reglas.

Added

• Sensibilidad declarable en karajan.config.json: easy.sensitivity
  (nivel del corpus) y easy.sensitivityRules (excepciones por prefijo de
  ruta, gana la primera que matchea), con validación estricta. El wizard
  de init pregunta el nivel; index estampa cada documento y los chunks
  lo heredan hasta el store; los hits de query exponen sensitivity.
• API nueva exportada: maxSensitivity, resolveDocumentSensitivity,
  effectiveSensitivityOfHits, enforceEasyAdapterPolicy y
  generateAnswerForHits (generación con routing y redacción PII sobre
  hits ya recuperados, testeable sin peers).
• redactPII cubre IBAN (hallazgo H3): ES e internacional, con y sin
  separadores, placeholder [REDACTED_IBAN] y conteo counts.iban.
• Docs: sección «Sensibilidad y privacidad» en docs/easy-rag.md y
  caso de uso real de despliegue GCP en docs/case-study-gcp.md
  (criterio de 1.0 cumplido).

Security

• Paquete de auditoría actualizado: H1 corregido (este release), H2
  cerrado con decisión registrada (embedders remotos = documentación
  prescriptiva; la capa easy solo ofrece embedders locales) y H3
  corregido (IBAN). Queda únicamente la auditoría externa como criterio
  de 1.0 pendiente.

v0.6.1

Security

• Mitigación KJR-BUG-0006: la capa easy no aplicaba la sensitivity
  policy ni la redacción PII prometidas por ADR-005 §6 (hallazgo H1 de la
  revisión interna). Desde ahora query --answer y eval --judges
  redactan PII (emails, teléfonos, NIF/NIE, tarjetas) de pregunta,
  contextos y respuestas antes de cualquier salida a un LLM, con test de
  no-regresión. El routing completo por nivel de sensibilidad queda
  rastreado en KJR-BUG-0006.

Added

• Paquete de auditoría de sensibilidad/PII (KJR-TSK-0130, criterio
  1.0): docs/security/sensitivity-audit.md — alcance, modelo de
  amenazas, inventario de flujos hacia proveedores por camino (con estado
  de policy y redacción en cada uno), hallazgos de la revisión interna
  (H1 alta → bug + mitigación; H2/H3 documentados) y checklist para el
  auditor externo.

• Política de deprecación formalizada (KJR-TSK-0129, criterio 1.0):
  docs/DEPRECATION.md — compromiso de 2 minors de preaviso desde la
  1.0, convención de triple señal (@deprecated en JSDoc + sección
  Deprecated en CHANGELOG + aviso runtime único) y proceso de retirada.
  Helper deprecate(name, {since, removal, alternative}) que emite un
  DeprecationWarning estándar de Node una sola vez por proceso
  (respeta --no-deprecation), exportado en el barrel. Enlazada desde
  README y marcada en el ROADMAP.

• Cobertura ≥90% con umbral en CI (KJR-TSK-0128, criterio 1.0): cuatro
  rondas de tests dirigidos (+44 tests) elevan la cobertura global a
  97.5% líneas/statements, 94.5% funciones y 88.9% branches (desde
  95.1/91.3/83.8). El script pnpm coverage pasa a fallar por debajo de
  los umbrales (statements/lines 95, functions 92, branches 87), de modo
  que las regresiones de cobertura rompen el build. Las ramas restantes
  sin cubrir son defensas de streams de proceso y fallbacks de peers no
  simulables sin fragilidad.

v0.6.0

Added

• karajan-rag doctor [ruta] (KJR-TSK-0126, roadmap 0.6.0):
  diagnóstico de entorno e índice sin efectos — node, peers opcionales
  (@lancedb/lancedb, @huggingface/transformers, pg), CLIs de IA en
  PATH, variables de entorno relevantes, config del proyecto
  (válida/ausente/inválida) y estado del índice (fingerprint, ficheros,
  chunks). Cada ✗/⚠ incluye el comando exacto para arreglarlo; exit code
  1 solo con errores. runDoctorChecks (puro, deps inyectables) y
  runDoctorCommand en el barrel.

• SDK embebible createRag() (KJR-TSK-0125, roadmap 0.6.0): fachada
  programática para frameworks (Astro/Next/Fastify/workers) sin CLI —
  {index, query, status, close} con los mismos defaults ADR-005 que los
  subcomandos easy. Acepta backends por nombre (lancedb/pgvector/
  in-memory) o instancias inyectadas de store/embedder. status sin
  índice y pgvector sin PG_URL fallan con instrucción exacta.
  Ejemplos copiables por framework en docs/easy-rag.md → sección SDK.

• Factory createOllamaClient (KJR-TSK-0124, roadmap 0.6.0): una
  configuración compartida (baseUrl, model, embedModel) produce las
  tres piezas contra el mismo proceso Ollama — adapter (generación
  blocking vía POST /api/generate, sin depender del binario),
  streamAdapter (NDJSON existente) y embedder (OpenAI-compatible
  existente). RAG 100% local con un solo endpoint.

• Adapter anthropic HTTP (KJR-TSK-0123, roadmap 0.6.0):
  runAnthropic contra la Messages API (/v1/messages, headers
  x-api-key + anthropic-version: 2023-06-01) sin SDK, con modelo por
  defecto claude-opus-4-8, fetch inyectable y stop_reason/usage
  expuestos en providerMeta (un refusal o max_tokens es decisión
  del caller, sin fallbacks silenciosos). Complemento a runClaudeCli
  para entornos sin shell (Cloud Run, workers). Proveedor público: entra
  en el nivel public de la sensitivity policy junto a openai.

• Adapter openai HTTP (KJR-TSK-0122, roadmap 0.6.0): runOpenAi
  contra Chat Completions públicas sin SDK (fetch inyectable, errores
  HTTP explícitos, baseUrl configurable para gateways compatibles).
  Proveedor público: entra en el nivel public de la sensitivity
  policy por defecto — nunca recibe contenido confidential/internal.

v0.5.0

Added

• Backpressure en ingestas grandes (KJR-TSK-0120, roadmap 0.5.0):
  indexDirectory embebe y upsertea por lotes de batchSize
  (DEFAULT_INGEST_BATCH_SIZE = 64) en vez de cargar todos los
  embeddings de un fichero de golpe, con progreso por lote vía onEvent.
  Flag --batch-size N en karajan-rag index con validación estricta.
  Resultado idéntico al indexado sin lotes (mismos chunks y manifest).

• Migración asistida entre stores (KJR-TSK-0119, roadmap 0.5.0):
  scan({batchSize}) como async generator en los tres stores (Pg pagina
  en SQL con orden estable; Lance trocea query().toArray() —
  documentado) y migrateVectorStore(source, target, {batchSize, onProgress}): valida dimensiones antes de escribir, propaga el
  fingerprint vía ensureIndexFingerprint (destino con otro espacio →
  corta sin escribir), upsert por lotes idempotente. Sin re-embedding:
  cambiar de backend (p. ej. LanceDB local → pgvector en cloud) sin
  reindexar.

• Fingerprint persistente en el store (KJR-TSK-0118, roadmap 0.5.0 —
  ADR-002 generalizado): los tres stores exponen
  get/setIndexFingerprint (campo en InMemory, tabla <tabla>_meta en
  Postgres, fichero sidecar .karajan-fingerprint en LanceDB — cópialo
  si mueves la tabla de sitio) y el helper ensureIndexFingerprint
  registra/valida el espacio vectorial fallando con error accionable
  ante mismatch. El indexer easy lo aplica como defensa en profundidad:
  escribir con un embedder/dimensiones incompatibles corta antes de
  mezclar espacios, tenga o no manifest el directorio.

• deleteByDocument(documentId) en los tres vector stores
  (KJR-TSK-0117, roadmap 0.5.0): borra todos los chunks de un documento
  en una llamada. InMemory filtra por metadata.documentId; PgVector por
  metadata->>'documentId'; LanceDB estrena columna top-level
  document_id (las tablas creadas antes de 0.5.0 no la tienen —
  deleteByDocument sobre ellas falla con instrucción de reindexar). El
  indexer easy la usa al invalidar documentos, con fallback al borrado
  por chunkIds del manifest. Queda documentado y testeado que la
  EmbeddingCache (content-addressed: fingerprint + sha256) no requiere
  invalidación ante borrados/reindexados.

v0.4.0

Added

• Métricas locales de evaluación (KJR-TSK-0111, roadmap 0.4.0):
  faithfulness, contextPrecision, contextRecall, answerRelevance
  y el agregador evaluateAnswer en src/evaluation/local-metrics.js.
  Variantes léxico-deterministas (solape de tokens de contenido, con
  stopwords/interrogativos es-en filtrados) sin LLM ni dependencias:
  aptas para baselines offline y CI. Valores siempre en [0,1], entradas
  degeneradas con semántica definida y relevantIds vacío → error
  explícito. Re-exportadas en el barrel.

• Golden set offline (KJR-TSK-0112, roadmap 0.4.0): corpus mínimo en
  examples/golden/ (facturación/envíos/soporte) + golden.json con
  preguntas, respuestas esperadas, fuentes relevantes y baseline
  calibrado al pipeline de stubs. Runner en
  src/evaluation/golden-runner.js (loadGoldenSet, validateGoldenSet,
  runGoldenSet): indexa con HashEmbedder + InMemoryVectorStore, lanza
  el retrieval híbrido y compara las medias de las métricas locales
  contra el baseline — cualquier caída falla señalando métrica y peores
  casos. Corre como test (tests/golden-set.test.js): guardián de
  regresión en CI sin credenciales.

• Disagreement auto-labelling (KJR-TSK-0113, roadmap 0.4.0): cada
  JudgeVerdict de evaluateMultiJudge incluye ahora label
  (consensus/outlier, null si el score no es parseable) y deviation
  respecto a la mediana; el EvaluationReport agrega outliers con los
  providers desviados ≥ threshold. La mediana como consenso resiste a un
  juez desviado; con dos jueces enfrentados ambos quedan como outlier
  (no hay consenso posible). Cambio aditivo: aggregateScore y
  disagreement no cambian.

• Prompt-template auditado del Reranker LLM (KJR-TSK-0114, roadmap
  0.4.0): el prompt inline de RerankerRole (modo llm) se extrae a
  src/retrieval/rerank-prompt.js (buildRerankPrompt,
  RERANK_PROMPT_VERSION, RERANK_SNIPPET_MAX_CHARS) sin cambio de
  redacción (v1). Tests snapshot congelan el texto exacto: cambiarlo
  exige actualizar snapshot y versión conscientemente en el mismo PR.

• karajan-rag eval <golden.json> [corpus] (KJR-TSK-0115, roadmap
  0.4.0): evaluación declarativa desde CLI. Ejecuta el golden set offline
  (stubs deterministas), reporta cada métrica contra su baseline (✓/✗ con
  peores casos) y termina con exit code 1 si el baseline falla — apto
  para CI. --judges claude,ollama añade veredictos LLM-as-judge por
  caso con aggregateScore y outliers etiquetados. --dimensions N
  para el embedder del run. runEvalCommand re-exportado en el barrel.

Fixed

• Easy RAG — guarda de integridad manifest↔store (KJR-BUG-0005,
  PR #93): si .karajan/manifest.json declara ficheros pero el store
  está vacío (in-memory recién creado o persistente vaciado),
  indexDirectory reportaba "sin cambios" y las queries devolvían vacío
  en silencio. Ahora descarta el manifest y reindexa completo,
  notificándolo por onEvent.

Bugs detectados durante la validación del despliegue real en GCP
(KJR-TSK-0110, primer caso de uso en producción del módulo deploy/gcp):

• deploy/gcp — Cloud SQL (KJR-BUG-0001, PR #87): el provider google
  ~>6.0 crea instancias con edición ENTERPRISE_PLUS por defecto, que
  rechaza tiers compartidos; se fija edition = "ENTERPRISE", compatible
  con el default db-f1-micro.
• Migración pgvector (KJR-BUG-0002, PR #90): karajan_rag_chunks.id
  pasa de uuid a text — los chunk ids de la capa Easy RAG son texto
  estable (doc:ruta.md#0) y el INSERT fallaba. Se retira pgcrypto y se
  documenta el ajuste de dimensión según el fingerprint del manifest.
• deploy/gcp — Cloud Run (KJR-BUG-0003, PR #88): deletion_protection = false explícito; el default del provider impedía reemplazar
  revisiones fallidas y rompía terraform destroy.
• Dockerfile (KJR-BUG-0004, PR #89): pg no llegaba a la imagen — la
  stage de deps heredaba el package.json del repo y npm lo omitía por
  figurar en devDependencies. Ahora los backends (pg,
  @lancedb/lancedb) se instalan sobre un package.json aislado.

v0.3.0

Documentation

• Guía "RAG en 5 minutos" (docs/easy-rag.md, KJR-TSK-0108): flujo
  completo de la capa Easy RAG — index/query/serve en local, contenedor y
  GCP — con las garantías transversales (sensitivity first, sin fallbacks
  silenciosos, determinismo). Sección nueva en el README y ROADMAP
  reestructurado: Easy RAG pasa a ser la 0.3.0 (entregada en main),
  evaluación avanzada → 0.4.0, persistencia → 0.5.0, ecosistema → 0.6.0+.

Added

• Módulo Terraform deploy/gcp/ (KJR-TSK-0107): monta el RAG en
  Google Cloud con terraform apply -var project_id=.... Cloud Run v2
  (imagen del Dockerfile, startup probe sobre /health, scale-to-zero),
  Cloud SQL Postgres 16 con pgvector por socket Cloud SQL, bucket GCS con
  el índice montado read-only en /data vía GCS FUSE, PG_URL en Secret
  Manager (contraseña generada por Terraform), Artifact Registry y service
  account con permisos mínimos. API privada por defecto
  (allow_unauthenticated=false); terraform destroy sin huérfanos con
  protecciones explícitas para la base y el bucket. README con el flujo
  completo (build+push, migración pgvector, index vía cloud-sql-proxy,
  rsync del índice, query con identity token). Validado con
  terraform fmt + validate. Layout preparado para deploy/aws|azure.

• Imagen Docker del servidor RAG (KJR-TSK-0106): Dockerfile
  multi-stage sobre node:22-slim, usuario no root, con los backends
  opcionales preinstalados (pg, @lancedb/lancedb). Sirve el índice
  montado en /data vía HTTP; configuración solo por entorno (PORT,
  KARAJAN_STORE=lancedb|pgvector, PG_URL) — sin secretos horneados.
  docker-compose.yml añade el servicio rag junto a pgvector para un
  RAG local end-to-end. Verificado con smoke real: index + serve + curl
  a /health y /query dentro del contenedor.

• karajan-rag serve [ruta] (ADR-005, KJR-TSK-0105): sirve el índice
  Easy RAG sin dependencias nuevas. Modo MCP stdio por defecto
  (JSON-RPC 2.0 delimitado por líneas: initialize, tools/list, tools/call)
  con dos tools — rag_query (híbrido vector+BM25) y rag_status —
  consumibles desde Claude Code o cualquier cliente MCP. Modo HTTP
  (--http --port N): POST /query {question, topK?} y GET /health,
  con validación estricta y errores JSON. El mismo RagService sirve
  índices locales (lancedb) o remotos (--store pgvector + PG_URL) —
  contrato que empaquetarán la imagen Docker y el Terraform de GCP.
  Módulos nuevos src/easy/{rag-service,http-server,mcp-server}.js,
  re-exportados en el barrel.

• karajan-rag init [ruta] (ADR-005, KJR-TSK-0104): scaffold de
  karajan.config.json con la sección easy (store, embedder,
  dimensions, topK, adapter). Wizard interactivo con defaults; --yes
  para modo no interactivo (CI/scripts); no sobreescribe sin --force;
  añade .karajan/ al .gitignore. index y query leen la config
  como defaults del proyecto — los flags de CLI siempre ganan, y una
  config inválida falla con el error exacto (nunca se ignora). Nuevo
  módulo src/easy/config.js (loadEasyConfig, saveEasyConfig,
  validateEasyConfig, DEFAULT_EASY_CONFIG) re-exportado en el barrel.

• karajan-rag query "<pregunta>" [ruta] (ADR-005, KJR-TSK-0103):
  consulta el índice local sin escribir pipeline. Retrieval híbrido en dos
  etapas (vector search sobre el store persistente + BM25 sobre los
  candidatos, merge 50/50 de scores normalizados), dedupe por overlap y
  salida fichero:línea (score) + pasaje. El embedder y las dimensiones
  se derivan del fingerprint del manifest (imposible consultar con un
  espacio vectorial distinto al indexado). --answer --adapter <cli>
  genera respuesta con contexto vía GeneratorRole (claude/codex/gemini/
  ollama/azure/bedrock/vertex). Índice inexistente → error con el comando
  exacto para crearlo. Nuevos queryIndex y runQueryCommand en el barrel.

• karajan-rag index <ruta> (ADR-005, KJR-TSK-0102): construye o
  actualiza un índice RAG persistente local en .karajan/ con un solo
  comando. Autodetecta código/docs/datos vía presets, embebe en batch y
  hace upsert al store. Reindex incremental: manifest.json guarda el
  fingerprint del índice (ADR-002) y el hash por fichero — solo se
  reprocesan añadidos/cambiados, los borrados se invalidan del store, y
  un cambio de embedder/dimensiones fuerza reindex completo (nunca se
  mezclan espacios vectoriales). Flags: --store lancedb|pgvector|in-memory
  (default lancedb, error accionable si falta el peer; pgvector
  requiere PG_URL), --embedder hash|transformers, --dimensions N.
  Módulos nuevos src/easy/{manifest,indexer,cli}.js, re-exportados en el
  barrel (indexDirectory, diffManifest, runIndexCommand, etc.).

• Easy RAG — autodetección de fuentes y presets (ADR-005, KJR-TSK-0101):
  detectSourceType, resolvePreset, classifySources y chunkWithPreset
  en src/easy/presets.js. Clasifican ficheros por extensión (código /
  docs / datos, con binarios y desconocidos excluidos de forma explícita)
  y devuelven presets inmutables que reutilizan los chunkers existentes
  con defaults deterministas (hash + lancedb, ADR-005). Los presets
  nunca tocan la policy de sensibilidad ni la redacción PII.

• Chunker chunkByRecords: para fuentes tabulares (CSV/TSV/JSONL) en
  lotes de N registros; CSV/TSV prependen la cabecera a cada chunk para
  conservar el contexto de columnas, JSONL trocea por objeto. Detección
  auto de formato por la primera línea. Re-exportado en el barrel.