82a358f18d
ontoref-derive: #[onto_mcp_tool] attribute macro registers MCP tool unit-structs in
the catalog at link time via inventory::submit!; annotated item is emitted unchanged,
ToolBase/AsyncTool impls stay on the struct. All 34 tools migrated from manual wiring
(net +5: ontoref_list_projects, ontoref_search, ontoref_describe,
ontoref_list_ontology_extensions, ontoref_get_ontology_extension).
validate modes (ADR-018): reads level_hierarchy from workflow.ncl and checks every
.ncl mode for level declared, strategy declared, delegate chain coherent, compose
extends valid. mode resolve <id> shows which hierarchy level handles a mode and why.
--self-test generates synthetic fixtures in a temp dir for CI smoke-testing.
validate run-cargo: two-step Cargo.toml resolution — workspace layout first
(crates/<check.crate>/Cargo.toml), single-crate fallback by package name or repo
basename. Lets the same ADR constraint shape apply to workspace and single-crate repos.
ontology/schemas/manifest.ncl: registry_topology_type contract — multi-registry
coordination, push targets, participant scopes, per-namespace capability.
reflection/requirements/base.ncl: oras ≥1.2.0, cosign ≥2.0.0, sops ≥3.9.0, age
≥1.1.0, restic declared as Hard/Soft requirements with version_min, check_cmd, and
install_hint (ADR-017 toolchain surface).
ADR-019: per-file recipient routing for tenant isolation without multi-vault. Schema
additions: sops.recipient_groups + sops.recipient_rules in ontoref-project.ncl.
secrets-bootstrap generates .sops.yaml from project.ncl in declarative mode. Three
new secrets-audit checks: recipient-routing-coherent, recipient-routing-coverage,
no-multi-vault. Adoption templates: single-team/, multi-tenant/, agent-first/.
Integration templates: domain-producer/, mode-producer/, mode-consumer/.
UI: project_picker surfaces registry badge (⟳ participant) and vault badge
(⛁ vault_id · N, green=declarative / amber=legacy) per project card. Expanded panel
adds collapsible Registry section with namespace, endpoint, and push/pull capability.
manage.html gains Runtime Services card — MCP and GraphQL toggleable without restart
via HTMX POST /ui/manage/services/{service}/toggle.
describe.nu: capabilities JSON includes registry_topology and vault_state per project.
sync.nu: drift check extended to detect //! absence on newly registered crates.
qa.ncl: six entries — credential-vault-best-practice (layered data-flow diagram),
credential-vault-templates (paths A/B/C), credential-vault-troubleshooting (15 named
errors), integration-what-and-why (ADR-042 OCI federation), integration-how-to-implement,
integration-troubleshooting.
on+re: core.ncl + manifest.ncl updated to reflect OCI, MCP, and mode-hierarchy nodes.
Deleted stale presentation assets (2026-02 slides + voice notes).
106 lines
8.1 KiB
Markdown
106 lines
8.1 KiB
Markdown
---
|
|
# Post metadata
|
|
id: "tu-ontologia-deberia-vivir-con-tu-codigo"
|
|
title: "Tu ontología debería vivir con tu código"
|
|
slug: "tu-ontologia-deberia-vivir-con-tu-codigo"
|
|
subtitle: "Soberanía, federación, y por qué la infraestructura de conocimiento sin hogar no es infraestructura"
|
|
excerpt: "Los knowledge graphs enterprise viven en un triplestore mantenido por un equipo dedicado en la plataforma de un vendor. Cuando el equipo cambia, el presupuesto se recorta, o el vendor pivota, el conocimiento desaparece. Ontoref toma el enfoque opuesto: conocimiento soberano y local-first que vive junto a su sujeto, versionado, consultable a través de cuatro superficies, y federado sin un broker central."
|
|
|
|
# Publication info
|
|
author: "Jesús Pérez"
|
|
date: "2026-05-10"
|
|
published: false
|
|
featured: false
|
|
|
|
# Categorization
|
|
category: "ontoref"
|
|
tags: ["ontoref", "soberania", "federacion", "radicle", "jujutsu", "infraestructura-conocimiento"]
|
|
|
|
# Display
|
|
read_time: "6 min read"
|
|
sort_order: 4
|
|
css_class: "category-ontoref"
|
|
category_description: "Ontoref — protocolo y herramientas para el auto-conocimiento estructurado en proyectos de software"
|
|
category_published: true
|
|
---
|
|
|
|
# Tu ontología debería vivir con tu código
|
|
|
|
Jessica Talisman, en su charla de KGC 2026, dice algo que merece destacarse: *"Tu ontología es tu moat — tu IP."*
|
|
|
|
Tiene razón. Y está describiendo el modelo enterprise de knowledge graphs, donde el moat está retenido en el triplestore de un vendor, mantenido por un equipo dedicado, en una plataforma con suscripción. Cuando el equipo cambia, el presupuesto se recorta, o el vendor pivota, el moat se drena.
|
|
|
|
Ontoref toma el enfoque opuesto.
|
|
|
|
## Qué significa conocimiento soberano
|
|
|
|
En ontoref, el conocimiento de qué es un proyecto — sus principios, prácticas, tensiones, decisiones arquitectónicas, estado operacional — vive como archivos NCL junto al código. En el repositorio. Versionado con la misma disciplina que el source.
|
|
|
|
Esto no es un enfoque de documentación. Es una decisión de almacenamiento con consecuencias arquitectónicas:
|
|
|
|
- **Ningún vendor puede quitártelo.** La ontología está en tu repo, no en su base de datos.
|
|
- **Sin migración de plataforma.** GitHub, Gitea, Radicle — el conocimiento se mueve con el código.
|
|
- **Sin infraestructura dedicada.** El daemon corre localmente; los archivos son la fuente de verdad.
|
|
- **Offline por defecto.** El conocimiento que requiere conexión de red para existir no es infraestructura — es un servicio.
|
|
|
|
La analogía más cercana es SQLite vs. PostgreSQL: local-first, embebido, siempre disponible, sin conexión requerida. Cuando necesitas distribución, la añades. Pero el baseline es soberanía.
|
|
|
|
## Cuatro superficies, una fuente
|
|
|
|
Almacenamiento soberano no significa aislado. Ontoref expone el mismo conocimiento ontológico a través de cuatro superficies simultáneamente:
|
|
|
|
**CLI (Nushell):** La interfaz nativa del developer. `ontoref describe project`, `ontoref graph ontology`, `ontoref sync diff --docs`. Rápido, scriptable, composable en CI. La superficie para humanos que viven en la terminal y para checks automatizados que corren en pipelines.
|
|
|
|
**UI (axum):** Una interfaz web para inspección visual, onboarding y gestión. No un dashboard sobre una API remota — un servidor local que renderiza el mismo conocimiento respaldado por NCL. La superficie para project managers, nuevos contribuidores, o cualquiera que prefiera navegar un grafo visualmente.
|
|
|
|
**MCP:** La superficie de agentes. El endpoint MCP de ontoref es la capa semántica que se sienta encima del protocolo de transporte. Como identifica correctamente el framework de Talisman, MCP mueve bytes — no establece significado compartido. Ontoref provee ese significado a través de su capa ontológica, expuesta vía MCP a agentes que necesitan conocimiento estructurado del proyecto para trabajar con precisión en lugar de alucinar contexto.
|
|
|
|
**GraphQL:** La superficie de integración. SPARQL es el estándar del semantic web, pero GraphQL es lo que la mayoría de developers conocen y cada ecosistema de herramientas soporta. Una API GraphQL sobre el DAG ontológico elimina la barrera de expertise sin sacrificar estructura.
|
|
|
|
Cuatro superficies, una fuente canónica: los archivos NCL en el repositorio.
|
|
|
|
## jj y Radicle
|
|
|
|
El modelo de almacenamiento se combina naturalmente con una clase específica de herramientas VCS.
|
|
|
|
**Jujutsu (jj):** Un VCS compatible con Git donde el working copy es siempre un commit — no hay dirty state. Esto se alinea directamente con el enfoque de ontoref de captura continua de estado: cada estado del proyecto es capturable, cada transición es un evento de primera clase. El operation log de jj es el equivalente VCS del historial de sesiones de reflexión de ontoref.
|
|
|
|
**Radicle:** Colaboración de código P2P, local-first, soberana. Si el código es soberano, el conocimiento sobre ese código también debería serlo. Radicle como transporte significa que la federación de proyectos con ontoref no depende de ninguna plataforma centralizada — sin GitHub, sin GitLab, sin Gitea hosteado. Los nodos se descubren entre sí e intercambian conocimiento directamente.
|
|
|
|
Juntos: código soberano y conocimiento soberano, distribuidos sin un broker central.
|
|
|
|
## Federación sin broker central
|
|
|
|
El modelo enterprise para federación de conocimiento es un knowledge graph central al que todos los proyectos apuntan. Un equipo lo mantiene. Una plataforma lo aloja. Cada query lo atraviesa.
|
|
|
|
El modelo de federación de ontoref es distinto:
|
|
|
|
```
|
|
proyecto-A consulta: ¿qué proyectos implementan "zero-trust-auth"?
|
|
proyecto-B, proyecto-C responden desde sus propias ontologías
|
|
sin servidor central que lo sepa todo
|
|
```
|
|
|
|
Esto es posible porque cada proyecto se describe a sí mismo. El DAG ontológico en `.ontology/core.ncl` es consultable sin ninguna dependencia externa. La federación vía NATS conecta los daemons — el daemon de cada proyecto se registra, publica sus capacidades, y responde a queries de otros daemons en la federación.
|
|
|
|
El resultado: visibilidad a nivel de ecosistema sin centralización a nivel de ecosistema. Puedes descubrir qué proyectos comparten tus constraints arquitectónicos, cuáles implementan prácticas compatibles, cuáles están en estados conflictivos — sin que ninguno requiera una plataforma compartida.
|
|
|
|
## Por qué esta arquitectura ahora
|
|
|
|
Dos cambios hicieron esto viable:
|
|
|
|
**La IA agéntica como consumidor.** Antes de los agentes, la infraestructura de conocimiento se construía para consumo humano — ontólogos manteniendo grafos para que los analistas los consultaran. Los agentes son diferentes: necesitan conocimiento machine-readable, estructurado y tipado para operar con precisión. El modelo multi-superficie de ontoref está diseñado para un mundo donde el consumidor principal del conocimiento del proyecto no es un humano leyendo un wiki sino un agente tomando decisiones en una ventana de contexto.
|
|
|
|
**Local-first como el default.** La tendencia de una década hacia todo en la nube está revirtiendo para la infraestructura de conocimiento. Los riesgos son claros: vendor lock-in, discontinuidad de plataforma, pérdida de soberanía, y el coste compuesto de dependencias externas para lo que debería ser conocimiento interno. Local-first con federación opcional es la arquitectura que sobrevive a los cambios de plataforma.
|
|
|
|
## El argumento del moat
|
|
|
|
El framing de Talisman — "tu ontología es tu moat" — es más acertado de lo que ella puede pretender. Un moat funciona porque está unido a lo que protege. Un moat almacenado en la base de datos de otra persona no es un moat. Es un acuerdo de servicio.
|
|
|
|
Cuando el conocimiento de qué es tu proyecto, por qué existe como existe, y qué decisiones tienen consecuencias duraderas vive junto al código que implementa esas decisiones — versionado, consultable, soberano, federado — es genuinamente tuyo. Se acumula. Sobrevive a cambios de equipo. Informa a agentes. Puede ser consultado por proyectos que dependen de ti.
|
|
|
|
Ese es el tipo de moat que vale la pena construir.
|
|
|
|
---
|
|
|
|
*Ontoref es open source. La especificación del protocolo, la automatización en Nushell, y los crates de Rust están en [github.com/jesusperezlorenzo/ontoref](https://github.com/jesusperezlorenzo/ontoref).*
|