Arquitectura completa del Supercontexto / Biblioteca (mapa vivo)

Arquitectura completa del Supercontexto / Biblioteca

Mapa vivo del sistema, escrito para que bib_ask pueda explicar el propio sistema que lo sirve. Origen: auditoría integral del Supercontexto (03-07-2026, s194). Si cambias una pieza, actualiza esta página.

Qué es

El Supercontexto es el sistema de conocimiento de CreaRackSL: un grafo de código y documentación + un buscador semántico con síntesis + una wiki auto-mantenida + la capa documental de sesiones (STATE/NEXT/LOG). Sirve a tres públicos: los agentes Claude del equipo (Regla 0/19), el staff (Oráculo, sitio workspace) y los usuarios finales de CreaRack Pro (Help Widget).

Las piezas y dónde vive cada una

Pieza	Tecnología	Dónde
Grafo (nodos/aristas)	D1 `crearacksl-workspace-db` · tablas `bib_nodes`/`bib_edges`/`bib_docs`/`bib_chunks`	Cloudflare
Índice vectorial	Vectorize `bib-chunks` (bge-m3, 1024 dims; D1 `embedding_b64` solo fallback)	Cloudflare
MCP server (tools `bib_`/`wiki_`)	Pages Functions — `functions/api/mcp/` (dispatch `index.ts`, handlers `biblioteca.ts`, `archivo.ts`, `archivo-core.ts`, `wiki.ts`)	Cloudflare
Síntesis de `bib_ask`/Oráculo/Tutor	`gemma-4-26b-a4b-it` vía Google AI Studio (REST, responseSchema)	Google
Embeddings	Workers AI `@cf/baai/bge-m3`	Cloudflare
Wiki (≈900 páginas)	`src/content/wiki/*.md` (repo = verdad) + `bib_wiki_pages` (D1 = índice) con reconciliación	GitHub + D1
Sitio	Astro SSG → CF Pages (deploy por cron Hetzner cada 10 min, debounce por SHA)	Cloudflare
Mantenimiento (crons)	Servidor Hetzner OPS `crearack-ops` (migrado de STAGE el 03-07-2026)	Hetzner
Capa documental de sesiones	`public/supercontext/` — STATE.md (snapshot vivo) · briefings/NEXT.md (operativo) · LOG.md (bitácora); históricos en `archive/supercontext/` (fuera de public, no se publica ni se indexa)	GitHub

Flujo de lectura (retrieval)

bib_ask / bib_search_semantic / Oráculo / Help Widget comparten el mismo motor (archivo-core.ts):

Embedding de la pregunta (bge-m3, +HyDE opcional RETRIEVAL_HYDE=1).
KNN en Vectorize (<500 ms) con over-fetch ×2 y dedup por contenido (s194) → top-k limpio. Fallback D1 full-scan solo si Vectorize falta.
Trim de frases (RETRIEVAL_TRIM=1, −25-32 % tokens sin pérdida de recall).
Síntesis con Gemma 4 (~2 s; timeout 40 s) con sanitizeChunk (redacción de secretos + anti prompt-injection) y clampRepetition.

Modo Help (user_facing=true): over-fetch 20 → filtro a 5 chunks de páginas crearack--*; el “Informante” (state_context) inyecta estado en vivo SOLO en la síntesis, no en el retrieval.
Modo Oráculo: top-5 de todo el corpus, historial 12 mensajes, rate-limit 40/min.

Flujo de escritura (mantenimiento del grafo)

Todo corre en crons de OPS (0 minutos de Actions, coste ~$0.5-2/día casi todo embeddings):

Circuito	Frecuencia	Qué refresca
`bib-reindex` (Pro)	AST 10 min · OpenAPI+docs 1 h · communities diario	nodos Python, endpoints, docs del repo Pro
`bib-reindex-ws ts`	L+J	AST TypeScript del workspace
`bib-reindex-ws supercontext`	diario	briefings de `public/supercontext` (excluye LOG.md, reports/, _archive/)
`bib-reindex-ws claude-method`	L+J	.md del método
`bib-reindex-ws chunks`	diario	embeddings de los docs de Pro
`bib-reindex-ws wiki`	diario incremental · domingo `--full` (s194)	nodos-doc + embeddings de `src/content/wiki`
`biblioteca-crons`	lint diario (+reclaim) · curator L+J · utility L+M+V · drift diario	salud de la wiki (Haiku 4.5)
`cron-heartbeat`	30 min	dead-man’s-switch por email de todos los anteriores

En cada commit con código, el agente reporta bib_report_change (hook pre-commit lo exige) → marca nodos stale y señala docs a actualizar.

El “escritor” (Bibliotecario-Ingest)

Pipeline 3-tier (.github/scripts/bib_ingest.py): heurística $0 → triage Haiku (~$0.01) → deep Haiku 4.5 ($0.05-0.50) que crea/actualiza páginas wiki tras cada merge. Estuvo OFF (Actions) desde la crisis de presupuesto; desde s194 corre como cron post-merge en OPS. La doc dual manual (Regla 27) sigue vigente; el ingest es la red de seguridad.

Límites conocidos

CF Workers: ~1.000 subrequests/invocación (verificado en producción, incidente s50) · D1 ~100 bind params (se trocea a 90) · Vectorize delete_by_ids máx 100 ids.
wiki_lint_bulk con verificación de fuentes trabaja con presupuestos (max_source_fetches) para no agotar subrequests.
El schema de una tool MCP queda congelado por sesión de Claude Code (param nuevo ⇒ llamar por curl).

Historial de saneos relevantes

s50 (05-2026): arquitectura de reindex definitiva + chunking del OpenAPI + purga de nodos huérfanos.
s183 (01-07): reclaim de páginas stale (auto-revalidación) + heartbeat.
s193 (03-07): migración de crons y CI a OPS.
s194 (03-07): dedup del retrieval, purga de 220 chunks _archive + 1.870 chunks duplicados (−33 % del índice), realineado de 81 bib_docs + 1.243 source_path fantasma (Documentation/*), archivo histórico fuera de public/, wiki al cron de reindex.

Véase también

[[feature—supercontext—reconcile-d1-repo]]
[[crearack-tech—backend—biblioteca]]