Ontoref: Ontología y Reflexión
El deck de la charla — ontología y reflexión que viven con el código
Jesús Pérez
·
Las diapositivas de la presentación de Ontoref: por qué la ontología y la reflexión de un proyecto deben vivir con el código, versionadas y verificables. Carrusel navegable + PDF descargable.
¿Qué estamos resolviendo?
Los problemas
🔴
Epistemic drift
El código hace X, el equipo cree que hace Y.
Silencioso. Acumulativo.
El código hace X, el equipo cree que hace Y.
Silencioso. Acumulativo.
🔴
Multi-actor collision
Humano + agente IA escriben al mismo fichero,
sin coordinación.
Humano + agente IA escriben al mismo fichero,
sin coordinación.
🟠
Decision amnesia
¿Por qué se tomó esta decisión? ¿Quién la autorizó?
¿Por qué se tomó esta decisión? ¿Quién la autorizó?
🟠
Config schizophrenia
Staging funciona, prod no. ¿Qué campo cambió y cuándo?
Staging funciona, prod no. ¿Qué campo cambió y cuándo?
🟠
Docs como artefactos muertos
Escritas una vez, olvidadas, nunca actualizadas.
Escritas una vez, olvidadas, nunca actualizadas.
🟡
Agent con ceguera
Los agentes IA empiezan sin contexto,
violan invariantes establecidas.
Los agentes IA empiezan sin contexto,
violan invariantes establecidas.
Ejemplo: desincronización real
# Documentación (2024-01)
config.max_retries = 3
# Código actual (después de cambio sin registrar)
config.max_retries = 7
# Equipo cree que está usando 3 ✗
# Sistema usa 7 silenciosamente ✓
# Nadie sabe cuándo cambió ni por quéEl coste de ignorarlo
Deuda técnica → arreglable
Deuda epistémica → sistémica
Deuda de confianza → letalTécnica
Refactoriza, reescribe, corrige.
1-3 sprints
Epistémica
Acumula silenciosamente. No sabes dónde.
Crece cada semana
Confianza
Se disuelve cuando se descubre el drift.
Imposible reparar rápido
Escenario: 6 meses de ignorar
Mes 1: "Solo refactorizar esto"
Mes 2: "Documentación está desactualizada"
Mes 3: "¿Por qué prod falla y staging no?"
Mes 4: "Nadie sabe quién cambió qué"
Mes 5: Pánico. Rollback arriesgado.
Mes 6: Equipo rechaza cambios nuevos.
"No confiamos sin entender" Estos problemas no tienen solución técnica.
Tienen solución de arquitectura.
Tienen solución de arquitectura.
Verdad y operación — dos fuerzas que deben coexistir
Yin — la capa formal
Lo que debe ser verdad
- Nickel schemas → corrección estructural
en tiempo de definición - ADR constraints → "esto nunca puede violarse"
- Config seals → estados sellados, verificables con sha256
- Ontology invariants → lo que no puede cambiar
sin un nuevo ADR - Hashes matemáticos → prueba de qué fue sellado
y cuándo
Yang — la capa operacional
Cómo las cosas se mueven y cambian
- Nu commands → transformación estructurada de datos
- Actors (human/agent/CI) → mismo protocolo,
distintas capacidades - Register flow → captura cambios,
los enruta al artefacto correcto - Mode definitions → secuencias de operaciones
con verificación - Pre-commit hooks → sincronización forzada
en el momento del commit
Yang sin Yin = fluido pero caótico. Cualquier cosa puede cambiar. Nada es verificable.
Yin sin Yang = correcto pero inútil. Schemas perfectos sin operaciones = documentación muerta.El sistema vive en la coexistencia.
Los ingredientes
CAPA DECLARATIVA · Nickel
.ontology/ · adrs/ · reflection/schemas/ · reflection/configs/Tipos fuertes, contratos, enums. Falla en definición, no en runtime.
CAPA OPERACIONAL · Nushell
adr · register · config · backlog · forms · prereqsPipelines tipadas sobre datos estructurados. No streams de texto.
PUNTO DE ENTRADA · Bash → Nu
stratum.sh · actor detection · locking · NICKEL_IMPORT_PATHUn único entry point. Detecta actor, adquiere lock, despacha al módulo Nu correcto.
GRAFO DE CONOCIMIENTO · Ontología + ADRs
nodes · invariants · gates · dimensions · states
El sistema sabe qué sabe. Actor-agnostic. Machine-queryable.
ESTADOS SELLADOS · Config + Historia
profiles · sha256 seals · audit trail · rollback
Inmutabilidad verificable. Drift detection. Trazabilidad completa ADR/PR/bug.
Nickel — configuración con tipos, sin runtime
Qué es Nickel
- Lenguaje de configuración con tipos fuertes (de Tweag)
- Puramente declarativo: sin efectos secundarios, sin loops, sin runtime
- Superset de JSON: JSON válido es Nickel válido
- Imports:
let s = import "schema.ncl" in - Contratos:
field | TypeName— verificado al merge - Enums tipados:
[| 'Proposed, 'Accepted, 'Superseded |] - Registros abiertos/cerrados:
{ _: String }vs{ field | String } nickel export file.ncl→ JSON estable pipelines Nu
El sistema de tipos es la documentación.
Por qué no alternativas
YAML → sin tipos, whitespace-sensitive,
coerciones implícitas
TOML → sin tipos ≥ primitivos, sin imports
JSON → sin comentarios, sin imports, sin tipos
HCL → efectos secundarios, no es config pura
CUE → similar pero peor historia de imports
KCL → tipos + validación, pero vendedor
lenguaje opacoPor qué aquí específicamente
- ADR constraints necesitan typecheck, no validación manual
- Perfiles de config deben fallar en definición, no en runtime
nickel exportproduce JSON estable para consumo Nu
# YAML: silently accepts garbage
actor: developr # typo, accepted
# Nickel: rejected at typecheck
{ actor | [| 'developer, 'agent, 'ci |] = "developr" }
# ^^^^^^^^^
# error: tag not in enum typeNushell — datos estructurados, no streams de texto
Shell tradicional: texto opaco
# Bash: parsear texto, error-prone
grep 'severity' adrs/adr-001.json |\
python3 -c "import sys,json; ..."Nushell: records nativos
nickel export adrs/adr-001.ncl
| from json
| get constraints
| where severity == "Hard"
| select id claim╭───┬────────────┬──────────────────────────────╮
│ # │ id │ claim │
├───┼────────────┼──────────────────────────────┤
│ 0 │ adr-001-c1 │ nickel export must succeed… │
│ 1 │ adr-001-c2 │ schema is sole source of… │
╰───┴────────────┴──────────────────────────────╯Nickel → Nu → Bash — tres capas, tres roles
Nickel exporta JSON tipado
Nunca strings mágicos. Contratos en la definición, no en runtime.
Nu consume estructuras
Tables, records, pipelines. Filter, sort, merge — sin awk ni sed.
Bash orquesta procesos
Locking, signals, exec. Solo lo que bash hace de forma nativa.
# Constraints Hard del sistema completo
glob "adrs/adr-*.ncl"
| each { |f| nickel export $f | complete | get stdout }
| each { from json }
| where status == "Accepted"
| get constraints | flatten
| where severity == "Hard"DAGs y FSMs — grafos acíclicos y máquinas de estado
FSM: ciclo de vida de un ADR
┌──────────┐ adr accept ┌──────────┐
│ Proposed │ ───────────▶ │ Accepted │
└──────────┘ └──────────┘
│ new ADR
│ supersedes
▼
┌────────────┐
│ Superseded │
└────────────┘Transiciones typecheck-enforced en Nickel:
status | [| 'Proposed, 'Accepted, 'Superseded |]
superseded_by | String | default = "" Las transiciones inválidas no existen
— el tipo las elimina del espacio de posibilidades.
Un ADR no puede volver a Proposed.
Superseded no puede tener constraints activas.
— el tipo las elimina del espacio de posibilidades.
Un ADR no puede volver a Proposed.
Superseded no puede tener constraints activas.
DAG: ontología como grafo de dependencias
invariante: backend-agnostic-core
└─ tensión: nickel-as-canonical-schema
└─ gate: nickel-primacy-gate [activa]
└─ protege: nickel-integration-depth
invariante: zero-external-runtime-core
└─ gate: core-dependency-gate [activa]
└─ protege: backend-agnostic-corePor qué importa la aciclicidad
→ Un invariante no puede depender de sí mismo
→ Las gates protegen nodos hoja, no ciclos
→ El rollback es determinista: sin ambigüedad de orden
# Invariantes activos
nickel export .ontology/core.ncl
| from json | get nodos
| where invariante == true
| select id descripcionLa Ontología Operacional — el grafo operacional
core.ncl — lo que no puede cambiar
# .ontology/core.ncl
{
nodos = [
{
id = "backend-agnostic-core",
invariante = true,
descripcion = "business logic sin deps de UI",
tensiones = ["nickel-as-canonical-schema"],
},
],
practicas = [...],
} Tocar un nodo con
invariante = true requiere un nuevo ADR. Sin excepción. state.ncl y gate.ncl — dónde estamos
nickel export .ontology/state.ncl
| from json | get dimensiones
| select id estado_actual estado_deseadobackend-maturity multi-stable → all-production
nickel-integration-depth schema-input → bidirectionalnickel export .ontology/gate.ncl
| from json | get membranas
| where activa == true
| select id permeabilidad protegecore-dependency-gate Low [backend-agnostic-core, ...]
nickel-primacy-gate Low [nickel-as-canonical-schema] La ontología no es un diagrama.
Es un grafo consultable que el sistema y los agentes leen.
Es un grafo consultable que el sistema y los agentes leen.
Reflection — modos, formas, módulos, perfiles
Modo: especificación ejecutable
# reflection/modes/new_service.ncl
{
id = "new_service",
trigger = "When adding a service",
steps = [
{
id = "create-adr",
actor = "developer",
action = "Draft ADR for service boundary",
cmd = "stratum form new_adr",
on_error = { strategy = "abort" },
},
{
id = "seal-config",
actor = "developer",
action = "Apply initial config seal",
cmd = "stratum config apply development",
depends_on = [{ step = "create-adr" }],
on_error = { strategy = "abort" },
},
],
}Forma: entrada estructurada tipada
# reflection/forms/register_change.ncl
{
elements = [
{ type = "section_header", label = "Change" },
{
type = "text",
id = "title",
label = "Title",
required = true,
},
{
type = "select",
id = "change_type",
options = ["feature","fix","refactor","config"],
},
]
}Perfil de config = estado sellado
sha256(nickel export profile.ncl) — drift detection instantáneastratum config verify development → compara hash actual con hash sellado ADRs vivos
— de documento muerto a constraint machine
Estructura Nickel de un ADR
# adrs/adr-001-nickel-as-canonical.ncl
let s = import "adrs/schema.ncl" in
{
id = "adr-001",
title = "Nickel as First-Class Form Definition",
status = "Accepted",
date = "2025-12-01",
constraints = [
{
id = "adr-001-c1",
severity = "Hard",
claim =
"nickel export must succeed before "
++ "any user interaction",
},
],
superseded_by = "",
} | s.ADRCiclo de vida y consulta
Proposed ──────▶ Accepted ──────▶ Superseded
│ ▲
│ new ADR │
└──────── superseded_by ────────────┘Constraints Hard activas del sistema
glob "adrs/adr-*.ncl"
| each { |f|
nickel export $f | complete
| if $in.exit_code == 0 {
$in.stdout | from json
} else { null }
}
| compact
| where status == "Accepted"
| get constraints | flatten
| where severity == "Hard"
| select id claim El conjunto activo de constraints es el contrato en vigor — no la prosa del ADR. La prosa explica el porqué. Los constraints enforcan el qué.
Implementación — las partes y cómo encajan
Stack de archivos operativos
stratum.sh ← entry point, locking, env
└─ reflection/bin/stratum.nu ← dispatcher
├─ modules/adr.nu ← ADR lifecycle
├─ modules/register.nu ← CHANGELOG + ontology
├─ modules/config.nu ← sealed profiles
├─ modules/backlog.nu ← backlog items
└─ modules/forms.nu ← TypeDialog integrated
.ontology/ ← queryable truth
├─ core.ncl ← invariants
├─ state.ncl ← dimensions
└─ gate.ncl ← active guards
adrs/ ← typed decisions
reflection/configs/ ← sealed config historyFlujo de escritura protegida
stratum.sh
detect actor → acquire lock (mkdir) → delegate → release
Lock resources
manifest (config apply/rollback) · changelog (register) · backlog (done/cancel)Timestamp IDs
cfg-20260309T045206-developer — colisión imposible, sin TOCTOU# Advisory lock: mkdir es POSIX-atómico
mkdir .stratumiops/locks/manifest.lock 2>/dev/null
echo "$$:developer:$(date -u +%Y%m%dT%H%M%SZ)"
> .stratumiops/locks/manifest.lock/ownerMecánica y flujo — casos de uso reales
Flujo: registrar un cambio
①
stratum register → forma TypeDialog interactiva②
Clasificar: tipo de cambio, impacto, ADR relacionado
③
Artefacto: entrada CHANGELOG + stub ADR si aplica
④
Verificar:
nickel typecheck debe pasar⑤
Sellar si afecta config:
stratum config applyDetección de drift
stratum config apply production --adr adr-006 --pr 42
# Meses después:
stratum config verify production
# → ✓ verified a3f7c12d8b4e9f01...
# → ✗ DRIFT DETECTED stored vs current hashRollback verificado
stratum config history production
stratum config rollback production \
cfg-20260301T120000-developer \
--adr adr-007 \
--note "revert breaking change"→
snapshot_hash verifica integridad antes de restaurar→ Rollback genera nuevo sello — la historia es append-only
→ Trazabilidad completa: ADR + PR + bug en cada sello
cfg-20260301T120000-developer (original)
└─ cfg-20260309T045206-agent (change)
└─ cfg-20260309T120000-developer (rollback)Integración en proyectos — onboarding al ecosistema
Lo que un proyecto necesita
proyecto/
.ontology/
core.ncl ← invariants del proyecto
state.ncl ← dimensiones de madurez
gate.ncl ← guards activos
adrs/
schema.ncl
reflection.ncl
adr-001-*.ncl ← ADR fundacional
reflection/
forms/ ← TypeDialog forms
modes/ ← operational modes
configs/ ← sealed profiles
modules/ ← Nu modules
bin/stratum.nu
stratum.shInicialización
Comando de onboarding
/onboard-project → genera .ontology/
+ ADR fundacionalPrimer ADR obligatorio
Define las invariantes — qué no puede cambiar sin ADR nuevo
Pre-commit como sincronización
nickel typecheck en cada commit— la capa declarativa nunca queda rota
./stratum.sh check
# ✓ nushell 0.110.0
# ✓ nickel 1.9.0
# ✓ .ontology/core.ncl exportable
# ✓ adrs/adr-001 Accepted
# ✗ no sealed config profiles yetIntegración con Claude Code & Uso concurrente
SessionStart: contexto automático
stratum-session-start.sh se ejecuta al inicio de cada sesión: === STRATUM CONTEXT: typedialog ===
ADRS
adr-001 [Accepted] Nickel as First-Class Form...
adr-002 [Accepted] NCL element order from position
HARD CONSTRAINTS
adr-001-c1 nickel export must succeed before...
adr-002-c1 web/tui must render headers interleaved
STATE
backend-maturity: multi-stable → all-production
ACTIVE GATES
nickel-primacy-gate [Low] Protects: nickel-as-...
=== END STRATUM CONTEXT ===Uso concurrente: humano + agente IA
IDs timestamp con actor
cfg-20260309T045206-developer
cfg-20260309T045207-agent
cfg-20260309T045207-agent
Sin coordinador. Sin TOCTOU. Trazabilidad por actor.
Advisory locks (mkdir)
Serializa escrituras en manifest/changelog/backlog. Stale detection por PID.
Actor-agnostic protocol
El sistema no distingue humano de agente. El protocolo enforcea igual para ambos.
Worktrees aíslan el working-tree (branches diferentes).
Locking serializa escrituras sobre el mismo árbol.
Son complementarios, no alternativos.
Locking serializa escrituras sobre el mismo árbol.
Son complementarios, no alternativos.
¿Te ha resultado útil? Valóralo
¿Tienes algo que aportar?
Cuéntame qué opinas, qué sugieres, o si seguimos explorando este tema.
·
lecturas