synaptum 1.0.0rc1__tar.gz

synaptum-1.0.0rc1/.github/humo.py

@@ -0,0 +1,39 @@
+"""Lo mínimo que un consumidor hace, contra la copia instalada desde el índice.
+
+Vive en un fichero y no incrustado en el workflow porque un heredoc dentro de un
+bloque YAML dentro de un bucle de reintentos es tres capas de citado que nadie
+quiere depurar en un incidente. Además así se puede ejecutar en local, que es
+donde conviene descubrir que está roto.
+
+Importa **desde el paquete**, nunca desde un submódulo interno: es la diferencia
+que dejó a Axonium con un rc publicado al que le faltaban seis exportaciones y
+el CI en verde.
+"""
+
+import asyncio
+
+import synaptum
+from synaptum import Agent, Session, tool
+from synaptum.testing import FakeGateway, says
+
+
+@tool
+async def eco(texto: str) -> str:
+    """Devuelve lo que recibe."""
+    return texto
+
+
+async def main() -> None:
+    agente = Agent("humo", model="openai-compatible:m", tools=[eco])
+    pasos = [
+        paso
+        async for paso in agente.run(
+            "hola", session=Session("r1", FakeGateway(says("hola")))
+        )
+    ]
+    assert pasos[-1].output == "hola", pasos[-1]
+    print("instalado desde el índice y funcionando:", synaptum.__version__)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

synaptum-1.0.0rc1/.github/workflows/release.yml

@@ -0,0 +1,120 @@
+# SYN-74 · Publicación por Trusted Publishing (OIDC).
+#
+# No hay token en ninguna parte: GitHub firma una identidad efímera y el índice
+# la verifica. El secreto no está mejor guardado — no existe, así que no se
+# puede filtrar, ni caducar sin avisar, ni acabar en el historial de un chat.
+#
+# Lo que hay que configurar en el índice (una vez, en «Publishing»):
+#
+#     owner       Root1V
+#     repository  synaptum-framework
+#     workflow    release.yml
+#     environment testpypi   (o pypi)
+#
+# El `environment` no es decorativo: es lo que permite exigir una aprobación
+# manual antes de que algo salga, y lo que hace que el publisher no valga para
+# cualquier workflow del repositorio.
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      index:
+        description: Dónde publicar
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  # No se publica lo que no pasa. Reutiliza el workflow de tests en vez de
+  # copiarlo: dos suites que se copian divergen, y la que diverge es siempre la
+  # que guarda la puerta.
+  tests:
+    uses: ./.github/workflows/tests.yml
+
+  build:
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv build --out-dir dist
+
+      # Que el artefacto diga la misma versión que el código. Son dos sitios y
+      # se editan a mano; un wheel publicado como una versión y que por dentro
+      # dice otra manda a quien depure al sitio equivocado, y no falla nunca.
+      - name: la versión del artefacto es la del código
+        run: |
+          VERSION=$(uv run python -c "import synaptum; print(synaptum.__version__)")
+          ls dist/synaptum-${VERSION}-py3-none-any.whl dist/synaptum-${VERSION}.tar.gz
+          echo "publicando $VERSION"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.index }}
+    permissions:
+      id-token: write        # lo único que hace falta: acuñar el token OIDC
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: >-
+            ${{ inputs.index == 'pypi'
+                && 'https://upload.pypi.org/legacy/'
+                || 'https://test.pypi.org/legacy/' }}
+
+  # Instalar desde el índice y ejecutar ESA copia. Un tag no es una release
+  # hasta que alguien puede instalarlo: Axonium publicó un rc cuyo CI estaba en
+  # verde y al que le faltaban seis exportaciones, porque sus tests importaban
+  # del submódulo interno y ningún consumidor hace eso.
+  verify:
+    needs: publish
+    runs-on: ubuntu-latest
+    env:
+      # En una sola línea y como variable de entorno: una expresión de GitHub
+      # partida en varias líneas dentro de un `run` es legal y difícil de leer,
+      # y esto se lee en un incidente.
+      INDEX: ${{ inputs.index == 'pypi' && 'https://pypi.org/simple/' || 'https://test.pypi.org/simple/' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: leer la versión que se acaba de publicar
+        run: |
+          echo "VERSION=$(python -c "
+          import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])
+          ")" >> "$GITHUB_ENV"
+
+      # Un índice tarda en servir lo que acaba de aceptar, y cuánto es variable.
+      # La espera y la comprobación son **el mismo paso** a propósito: una sonda
+      # aparte puede decir que sí por un motivo que no es el índice —lo hizo, en
+      # local, mirando el entorno en vez del índice— y entonces la verificación
+      # arranca creyendo que hay algo. Si la instalación funciona, está servido.
+      - name: instalar desde el índice y usarlo como un consumidor
+        run: |
+          for intento in $(seq 1 30); do
+            if uv run --isolated --no-project \
+                 --index-url "$INDEX" --extra-index-url https://pypi.org/simple/ \
+                 --with "synaptum==$VERSION" python "$GITHUB_WORKSPACE/.github/humo.py"; then
+              echo "verificado tras ${intento} intento(s)"
+              exit 0
+            fi
+            echo "intento ${intento}: el índice todavía no lo sirve"
+            sleep 10
+          done
+          echo "synaptum==$VERSION no se pudo instalar desde $INDEX cinco minutos después"
+          exit 1

synaptum-1.0.0rc1/.github/workflows/tests.yml

@@ -0,0 +1,46 @@
+# SYN-77 · Los tests corren donde puede verlos cualquiera, no solo en un portátil.
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:          # lo reutiliza la publicación: no se publica lo que no pasa
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # Sin SYNAPTUM_CONTRACTS a propósito. Los corpus dorados son artefactos
+      # conjuntos de varios proyectos y viven fuera de este repositorio: aquí no
+      # están, y la suite tiene que pasar igual. Si su ausencia la rompiera
+      # serían una dependencia — y una que no se puede instalar.
+      - name: pytest
+        run: uv run --frozen pytest
+
+      # El paquete que se publica es lo que hay que probar, no el árbol de
+      # fuentes. Un wheel al que le falte un fichero pasa la suite y falla al
+      # instalarse, que es exactamente lo que este paso ve y el anterior no.
+      - name: el wheel instala y funciona por sí solo
+        run: |
+          uv build --out-dir dist
+          uvx twine check dist/*
+          uv run --isolated --no-project --with dist/*.whl python -c "
+          import synaptum, pathlib, sys
+          assert (pathlib.Path(synaptum.__file__).parent / 'py.typed').exists(), \
+              'falta py.typed: quien instale esto no ve un solo tipo'
+          ajenos = [m for m in sys.modules
+                    if not m.startswith(('synaptum', '_')) and '.' not in m
+                    and m not in sys.stdlib_module_names]
+          assert not ajenos, f'el núcleo arrastró dependencias: {ajenos}'
+          print('ok', synaptum.__version__)
+          "

synaptum-1.0.0rc1/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables (may contain credentials)
+.env
+*.env

synaptum-1.0.0rc1/.python-version

@@ -0,0 +1 @@
+3.13

synaptum-1.0.0rc1/API.md

@@ -0,0 +1,87 @@
+# Política de estabilidad de API
+
+`SYN-46`. Esta política vale para cualquiera que construya sobre Synaptum, y no depende de quién sea.
+
+Nació de un caso concreto: un arnés retiró su DSL de autoría nativo apoyándose en que Synaptum sería
+esa capa. Una decisión así es difícil de revertir, y la contrapartida no podía quedarse en una frase
+de un acuerdo: tiene que decir qué está garantizado, durante cuánto y qué no. Lo que sigue aplica
+igual a quien llegue mañana sin haber estado en aquella conversación.
+
+## Qué es superficie pública
+
+**Lo que `synaptum/__init__.py` exporta, y nada más.**
+
+Un símbolo alcanzable solo por su módulo —`synaptum.run.journal.Replay`, por ejemplo— es interno
+aunque no lleve guion bajo, y puede cambiar sin aviso. Si algo interno te hace falta, pídelo y lo
+promovemos; usarlo desde fuera es aceptar que se romperá.
+
+La superficie está **fijada por un test**: cualquier cambio en `__all__` rompe la suite y obliga a
+actualizar el fichero de referencia a mano. No es burocracia — es que una política que nadie
+comprueba se erosiona, y ya hemos visto esa lección tres veces en este proyecto.
+
+## Qué queda fuera a propósito
+
+| Fuera | Por qué |
+|---|---|
+| Representación interna de los eventos | Lo que se garantiza es el **contrato de la costura**, no cómo se guardan los campos en memoria |
+| Mensajes de error y sus textos | Los códigos de razón sí son estables; la prosa no |
+| El módulo `synaptum.testing` | Es andamiaje de desarrollo y evoluciona con lo que haga falta probar |
+| Cualquier cosa marcada `experimental` en su docstring | Declarado a la entrada, sin sorpresa |
+
+## Versionado
+
+SemVer **a partir de `1.0.0`**:
+
+- **MAJOR** — se quita algo de la superficie pública, o se cambia lo que significa.
+- **MINOR** — se añade. Añadir un campo con valor por defecto, un parámetro opcional o un símbolo
+  nuevo es minor.
+- **PATCH** — correcciones que no cambian la superficie.
+
+**Antes de `1.0.0` la superficie puede cambiar**, y decirlo claro vale más que fingir lo contrario.
+Estamos en `1.0.0.dev0`. Lo que sí se compromete desde hoy está en la sección siguiente.
+
+## Qué se garantiza ya, antes de 1.0.0
+
+Dos bloques, con garantías distintas y conviene no confundirlos:
+
+### Lo que viaja por la costura — garantía del contrato, no de este paquete
+
+El vocabulario del modelo, la taxonomía de eventos y los dos protocolos de costura están
+especificados en `contratos/` y versionados aparte, con una ventana de **dos versiones menores
+vivas**. Esa garantía es más fuerte que la de esta política y no depende de ella: alguien puede
+implementar la costura sin usar Synaptum.
+
+### La API de autoría — sobre la que se escriben agentes
+
+```python
+Agent · tool · Tool · Session · Limits · Risk
+```
+
+Sobre estos seis:
+
+1. **No se quitan ni se renombran antes de `1.0.0`** sin un cambio acordado en el canal de
+   coordinación, con la razón por escrito.
+2. **Los parámetros existentes no cambian de significado.** Añadir parámetros opcionales sí es
+   posible.
+3. **Los valores por defecto no se relajan en la dirección permisiva.** `risk=READ` e
+   `idempotent=False` son deliberadamente asimétricos —permisivo en riesgo, conservador en
+   durabilidad— y cambiarlos alteraría en silencio el comportamiento de código ya escrito. Endurecer
+   un default es un cambio MAJOR; relajarlo, directamente no se hace.
+
+## Deprecación
+
+Un símbolo que va a desaparecer:
+
+1. Emite `DeprecationWarning` con el sustituto nombrado en el mensaje.
+2. **Sigue funcionando durante al menos dos versiones menores.** Misma ventana que la costura, por
+   coherencia y porque permite a los tres proyectos desplegar sin coordinar una fecha de corte.
+3. Solo entonces se quita, y en una MAJOR.
+
+Un aviso de deprecación que no nombra el sustituto es un aviso incompleto: el que lo recibe tiene
+que poder actuar sin abrir un issue.
+
+## Qué hacer si esto se rompe
+
+Si un cambio nuestro rompe a alguien que construye sobre esto **fuera de lo que esta política
+permite**, es un fallo nuestro y se revierte — no se negocia una migración a posteriori. Ese es el
+sentido de haberlo escrito antes.

synaptum-1.0.0rc1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Registro de cambios
+
+Formato [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/). Versionado según
+[`API.md`](API.md): SemVer desde `1.0.0`, con ventana de deprecación de dos versiones menores.
+
+## [1.0.0rc1] — 2026-09-13
+
+Publicado en TestPyPI. Instalable con `--index-url https://test.pypi.org/simple/`.
+
+Primera publicación. **Es un candidato y no una `1.0.0`, a propósito.** La superficie está completa
+contra el contrato de hoy y no va a cambiar por gusto, pero la Fase 2 (economía de contexto) todavía
+puede tocarla, y el compromiso de estabilidad de [`API.md`](API.md) arranca en `1.0.0`. Prometerlo
+antes de tiempo sería peor que esperar.
+
+
+Primera línea `1.0.x`. La `0.x`, con un diseño distinto, quedó congelada en
+[v0.4.0](https://github.com/Root1V/synaptum-framework/releases/tag/v0.4.0) y **no hay ruta de
+migración**: la superficie no se parece. El estado por elemento está en [`roadmap.md`](roadmap.md).
+
+### Añadido
+
+- Bucle del agente como stream de eventos tipados — `Agent.run()` y `Agent.stream()`.
+- Ejecución durable: al reanudar un run, **una inferencia ya pagada no se paga otra vez**.
+  `MemoryCheckpointer` y `SqliteCheckpointer` como implementaciones de referencia.
+- Identidad determinista de paso (`000003-model`), publicada como especificación abierta, y que
+  además viaja como clave de idempotencia hacia proveedores que la admitan.
+- Herramientas con esquema derivado de la firma: `@tool`. `risk` e `idempotent` se declaran.
+- Vocabulario unificado de modelo con `Usage` de **tres estados** — medido, sin medir, estimado.
+- Adaptador `openai-compatible` y transporte HTTP de desarrollo, ambos sin dependencias.
+- Prompts como configuración versionada.
+- `FakeGateway` y `ReplayGateway` como infraestructura de desarrollo de primera clase.
+- Marcador `py.typed`: los tipos llegan a quien consume el paquete.
+
+### Pendiente antes de `1.0.0`
+
+Economía de contexto (Fase 2) y multi-agente (Fase 3). Ver [`roadmap.md`](roadmap.md).

synaptum-1.0.0rc1/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: synaptum
+Version: 1.0.0rc1
+Summary: Provider-agnostic agent framework and durable runtime. Owns execution semantics; the harness owns the substrate.
+Project-URL: Homepage, https://github.com/Root1V/synaptum-framework
+Project-URL: Repository, https://github.com/Root1V/synaptum-framework
+Project-URL: Changelog, https://github.com/Root1V/synaptum-framework/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Root1V/synaptum-framework/issues
+Author-email: Emeric Espiritu Santiago <emericespiritusantiago@gmail.com>
+License-Expression: MIT
+Keywords: agent-framework,agents,durable-execution,llm,provider-agnostic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1; extra == 'anthropic'
+Provides-Extra: axonium
+Requires-Dist: axonium>=1.0.0rc3; extra == 'axonium'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=2; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.30; extra == 'otel'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# Synaptum
+
+**Framework de agentes y runtime durable, agnóstico al proveedor.**
+
+Synaptum es dueño de la *semántica* de ejecución de un agente: qué es un paso, dónde puede cortarse,
+qué puede repetirse, y cómo se vuelve a derivar el contexto. El *sustrato* —dónde se persiste, con
+qué retención, bajo qué política— pertenece al arnés que lo opera.
+
+> **Versión:** `1.0.0.dev0` · **Python:** ≥ 3.13 · **Licencia:** MIT
+>
+> **En construcción.** La línea 0.x, con un diseño distinto, está congelada en
+> [v0.4.0](https://github.com/Root1V/synaptum-framework/releases/tag/v0.4.0). El estado real de esta
+> por elemento está en [`roadmap.md`](https://github.com/Root1V/synaptum-framework/blob/main/roadmap.md).
+
+---
+
+## La idea
+
+El bucle de un agente no es un `while` escondido: es un generador asíncrono que **cede el control en
+cada frontera significativa**.
+
+```python
+async for step in agent.run(tarea, session=session):
+    match step:
+        case ToolStep(phase=Phase.ATTEMPTED, risk=Risk.DESTRUCTIVE):
+            ...
+        case ModelStep(phase=Phase.COMPLETED, usage=consumo):
+            ...
+        case FinalStep(output=salida):
+            ...
+```
+
+De esa forma salen cuatro propiedades, y ninguna otra estructura las da a la vez:
+
+1. **El arnés obtiene sus puntos de enganche** sin que Synaptum sepa que existe. Aprobaciones,
+   guardarraíles y métricas son consumidores del stream.
+2. **Cada `yield` es una frontera de checkpoint natural.**
+3. **Interrumpir es dejar de iterar**; reanudar es volver a llamar con el mismo `run_id`.
+4. **Probar es iterar una lista.**
+
+## Lo que justifica todo lo demás
+
+Al reanudar un run, **una inferencia ya pagada no se paga otra vez.**
+
+```python
+store = SqliteCheckpointer("runs.db")
+
+# Primera vuelta: dos llamadas al modelo, una a una herramienta.
+async for step in agent.run("lee /x", session=Session("run-1", gateway, store)):
+    ...
+
+# El proceso muere. Otro proceso, otra conexión, mismo run_id.
+async for step in agent.run("lee /x", session=Session("run-1", otro_gateway, store)):
+    ...   # cero llamadas al modelo, cero a la herramienta
+```
+
+La ventana de contexto no se almacena: se **vuelve a derivar** de los mismos resultados en el mismo
+orden. Guardarla sería guardar dos veces lo mismo y arriesgarse a que discrepen.
+
+Esto se apoya en una sola pieza: la **identidad determinista de paso**, publicada como
+especificación abierta. Quien la implemente obtiene la misma propiedad sin importar nada de Synaptum
+ni hablar Python.
+
+## Herramientas
+
+El esquema sale de la firma. Un esquema escrito aparte se desincroniza, y cuando lo hace el modelo
+manda argumentos que la función no acepta — lejos del cambio que lo causó y con una inferencia ya
+pagada.
+
+```python
+@tool(risk=Risk.DESTRUCTIVE)
+async def borrar(path: Annotated[str, "Ruta absoluta"], forzar: bool = False) -> str:
+    """Borra un fichero del disco."""
+    ...
+```
+
+`risk` e `idempotent` se declaran y no se deducen: no son propiedades del tipo sino del **efecto**, y
+ninguna anotación puede saber que una función que devuelve `str` mueve dinero.
+
+Los defaults son asimétricos a propósito — **permisivo en riesgo, conservador en durabilidad**: quien
+calla obtiene la clase más inocua y la garantía más cara.
+
+Un tipo que no sabemos traducir **falla al decorar**, no al invocar.
+
+## Probarlo
+
+```bash
+uv run python examples/01_agente.py
+```
+
+Corre **sin inferencia**: las respuestas van guionizadas, y el resto es real —las herramientas se
+ejecutan, el journal se escribe, el consumo se mide—. Para apuntar a un modelo de verdad, dos
+variables y **el mismo fichero sin tocar**:
+
+```bash
+export SYNAPTUM_BASE_URL=http://localhost:8080/v1
+export SYNAPTUM_MODEL=qwen3-0.6b
+uv run python examples/01_agente.py
+```
+
+Que el mismo código sirva para las dos cosas no es comodidad: es la propiedad. Ver
+[`examples/`](https://github.com/Root1V/synaptum-framework/tree/main/examples) — el bucle entero, la reanudación **medida** (no afirmada), una aprobación
+humana a mitad de run, y el streaming con cancelación.
+
+## Sin dependencias
+
+```bash
+pip install synaptum      # 0 dependencias
+```
+
+El núcleo es stdlib puro. Pydantic, los proveedores, MCP y OpenTelemetry son extras. Los adaptadores
+se descubren por *entry points*, así que el núcleo no conoce a ninguno.
+
+## Desarrollo sin inferencia
+
+No hay modelos locales disponibles en modo autónomo, así que el doble de desarrollo es
+infraestructura y no una utilidad de test. Ejercita todo lo que el bucle sabe hacer: llamadas a
+herramientas con ejecución real, streaming con cancelación, las tres disposiciones de denegación, la
+taxonomía de errores y el consumo de tres estados.
+
+```python
+from synaptum.testing import FakeGateway, ReplayGateway, calls, says
+
+# Guion escrito a mano: directo, y suficiente para la mayoría.
+gateway = FakeGateway(calls("leer", path="/x"), says("dice hola"), tools=[leer])
+
+# Respuestas reales grabadas, normalizadas por el adaptador de verdad.
+gateway = ReplayGateway("fixtures/chat_completion.json", tools=[leer])
+```
+
+Un guion a mano dice lo que uno espera; una grabación dice lo que el proveedor hizo — y la diferencia
+aparece en los caminos que nadie escribe porque no se le ocurren.
+
+## Dónde encaja
+
+Synaptum se sostiene solo. Habla con dos piezas por **protocolo**, y trae una implementación de
+referencia completa de cada una:
+
+```
+arnés          política, aprobaciones, secretos, retención, escalado
+  │            Gateway — decide y ejecuta          · por defecto: LocalGateway
+Synaptum       semántica de ejecución              ← esto
+  │            Checkpointer — persiste, no decide  · por defecto: SqliteCheckpointer
+almacén
+                                    ─────
+proveedor      cualquier endpoint OpenAI-compatible · por defecto: HttpModel
+```
+
+**Las dos costuras son protocolos estructurales (`typing.Protocol`), no clases base.** Quien las
+implemente no hereda ni importa nada nuestro, y puede estar escrito en otro lenguaje al otro lado de
+un socket. No hay ningún arnés, SDK ni plataforma de inferencia concretos en el árbol de
+dependencias: `pip install synaptum` trae **cero** paquetes.
+
+En el despliegue donde nació, esas dos ranuras las ocupan un arnés llamado Aeon y un SDK llamado
+Axonium sobre una plataforma de inferencia local. Nada de eso es un requisito, y el paquete no los
+nombra: son **un** relleno posible de un protocolo abierto. El extra `[axonium]` existe para quien
+tenga esa combinación, y es opcional como el de Anthropic o el de OpenAI.
+
+`LocalGateway` **avisa de que no aplica política** y marca cada comprobación con `enforced=False` —
+una comprobación dentro del proceso gobernado es advisoria, y que un run pase por ahí sin
+denegaciones no dice nada sobre si pasaría por un gateway real.
+
+## Contratos compartidos
+
+Tres especificaciones con casos dorados, ejecutables por cualquier implementación con su propio
+runner. **Viven fuera de este repositorio** porque son artefactos conjuntos de varios proyectos, y
+copiarlos aquí los convertiría en una copia que se desincroniza. Synaptum no depende de ellos: son
+evidencia adicional, y sin ellos la suite pasa igual (209 de 277; el resto se salta).
+
+```bash
+export SYNAPTUM_CONTRACTS=/ruta/a/contratos    # opcional
+```
+
+
+| Contrato | Estado |
+|---|---|
+| Costura de durabilidad | 8 casos · verdes contra nuestras dos implementaciones |
+| Identidad de paso | 10 casos · verdes |
+| Normalización entre proveedores | 14 casos · verdes contra el adaptador Python, todos menos uno **grabaciones reales** |
+
+Los casos describen **resultados observables** y nunca estructuras internas: dos implementaciones sin
+una línea de código en común tienen que poder reproducirlos.
+
+Que los cuerpos sean grabaciones reales y no ejemplos escritos a mano ya encontró dos fallos
+nuestros. Un stream que era **solo razonamiento** no emitía ni un evento, porque el cuerpo inventado
+que teníamos antes solo llevaba deltas de texto. Y en un stream de razonamiento que termina llamando
+a una herramienta, el cierre del pensamiento caía **en mitad de la llamada**: cerrábamos el ciclo al
+ver texto, y ahí no había texto.
+
+Un caso dorado **no fija cifras**. Una regrabación tiró cinco de los nuestros sin que ninguna
+implementación hubiera cambiado: fijaban tokens y un id de réplica, que pertenecen a una grabación y
+no a la especificación. Lo que se afirma es si un contador está medido o sin medir, y cómo se
+relacionan entre sí.
+
+## Estabilidad
+
+Qué se garantiza, durante cuánto y qué no: está **escrito y comprobado por un test**, no recordado.
+Un arnés retiró su DSL de autoría apoyándose en ese compromiso, que es por qué existe por escrito.
+Ver [`API.md`](https://github.com/Root1V/synaptum-framework/blob/main/API.md).
+
+## Estado
+
+| Fase | |
+|---|---|
+| **0 · Contratos** | completa |
+| **1 · Núcleo durable** | completa |
+| **2 · Contexto y observabilidad** | sin empezar |
+| **3 · Multi-agente** | sin empezar |
+
+`roadmap.md` lleva el detalle por elemento.
+
+---
+
+MIT © 2026 · Emeric Espiritu Santiago