Constitución vs Runtime: un monorepo, 16 SaaS verticales, sin fork

Dos repositorios, una plataforma

Un monorepo que aloja más de un producto choca con el mismo fork tarde o temprano. Una vertical necesita una columna extra en Company, otra necesita saltarse el flujo de auth común para SSO, una tercera quiere su propio handler de webhook de billing. Cada una arranca parchando el código compartido. Cada una termina con la copia vendoreada. La plataforma ahora son siete copias de la misma cosa, divergiendo.

La separación que evita esto es más vieja que la idea de monorepo. Separar contrato de implementación. El contrato es el repositorio inite-ecosystem — JSON Schemas, YAMLs de capability, un manifiesto, un validator. La implementación es inite-shared — 19 paquetes TypeScript, Postgres real, HTTP real. Las verticales (rent, estate, shop, events, health, education, club y las demás entre las 16 del registry) consumen ambos.

El manifiesto del repo-constitución es corto y estructural:

Un pull request que agrega cualquier cosa de la columna izquierda se rechaza al toque. El repo sirve a la spec; la spec sirve a las verticales; las verticales corren el negocio. Ese orden es toda la arquitectura.

Qué contrata el contrato, en concreto

Una vertical declara conformance con un único manifiesto YAML. El formato es chico:

ecosystem: "^0.1.0"
id: inite.rent
name: INITE Rent
version: 1.0.0
domain: car_rental
maturity: production

capabilities:
  - { id: inbox,   version: "^1.0.0" }
  - { id: billing, version: "^1.0.0" }

runtime_packages:
  - "@inite/auth"
  - "@inite/billing"

entities:
  - { id: vehicle }
  - { id: reservation }

Ese manifiesto compromete a la vertical con tres cosas. Ring 1 — cinco entidades obligatorias (User, Company, UserCompanyRole, ApiKey, CompanyPermissionOverride) tienen que existir en su schema Prisma o estar declaradas como aliases. Ring 2 — cada capability listada en capabilities: obliga a la vertical a entregar el set completo de entidades que ese capability exige. Declaraste inbox, entregás Conversation y Message en la forma que espera el bundle. Sin eso, no podés listar el capability. Ring 3 — todo lo demás (vehicle, reservation, listing, appointment) es libre. La spec no limita forma, nombres ni semántica.

La herramienta de conformance recorre manifiesto más schema Prisma y produce un reporte present/partial/missing por entidad. El drift aparece como estado en el registry, no como fork silencioso.

Qué se gana operativamente

Tres propiedades aparecen recién cuando la separación está hecha de verdad.

Primero — el upgrade del runtime queda desacoplado del cambio de contrato. Un fix en @inite/auth es un patch de runtime. Llega a cada vertical que consume el paquete, al ritmo de pull de la vertical. La spec no se mueve. No hay migración en los 16 productos. No hay entrada en el CHANGELOG de la constitución.

Segundo — los cambios incompatibles tienen una sola superficie forzada. Quitar un campo de Company es un bump MAJOR de spec. La migración entra al repositorio de spec como carpeta fixtures/migrations/<from>-to-<to>/ con manifiestos antes y después por cada vertical afectada, walkthrough escrito y ventana de deprecation de al menos un MINOR antes de que el schema viejo deje de validar. Las verticales se quedan en el MINOR anterior el tiempo que necesiten — porque la regla de caret semver zero-major trata ^0.1.0 como ~0.1.0, y el manifiesto no flota solo hacia el cambio incompatible. Tienen que hacer opt-in.

Tercero — el registry queda como fuente de verdad sobre la salud de la plataforma. En la versión 0.2.0-rc.4 el registry rastrea 18 verticales en siete buckets de estado:

Esa tabla se actualiza en cada release de spec. Una vertical que entra en drift más allá de la ventana acordada cae en el mismo review. Un capability que no llegó a producción en dos releases pasa a revisión. El registry es el dashboard.

Por qué el runtime no es dueño de nada en la spec

Los paquetes de runtime declaran un contract_version en registry/capabilities.yaml. Ocho de los diecinueve están en 1.0.0 — contrato estable, los cambios incompatibles exigen bump MAJOR del runtime. Los once restantes están en 0.1.0 — bundles que todavía se están calibrando, como @inite/accounting y @inite/inbox-ui, donde el contrato no es estructural todavía. La spec no pina versiones de runtime. Solo referencia contratos de paquete. Un capability bundle puede decir @inite/inbox >= 0.5.0, pero nunca == 1.0.3.

La dirección inversa es asimétrica a propósito. El runtime no puede enviar un cambio de contrato — eso solo la spec. El runtime puede enviar una implementación del contrato bajo la spec actual, y esa implementación se mueve en su propio eje de versión. Cuando la spec quiere quitar un campo de Company, sale el MAJOR de spec, el runtime se ajusta, las verticales migran a su ritmo dentro de la ventana de deprecation.

Esto funciona porque en el repositorio de spec no hay nada ejecutable que se pueda romper. No hay servicio que actualizar. No hay base que migrar. No hay comportamiento que testear. El repo son JSON Schemas, YAMLs de capability, ejemplos y validator. Un PATCH de spec es edición de docs. Un MINOR es un campo opcional nuevo en una entidad o un capability nuevo. Un MAJOR es el único lugar donde los cambios incompatibles se escriben — explícitamente, con ejemplos, con ventana de deprecation.

Cómo se ve esto en las verticales reales

inite.rent corre sobre Ring 1 más inbox, billing, incidents y notifications, con un Ring 3 de cerca de veinte entidades de dominio (Vehicle, Reservation, RentalContract, InsurancePolicy, MaintenanceRecord y demás). Declara maturity: production y es la única vertical en ese estado hoy.

inite.estate corre sobre el mismo Ring 1, el mismo inbox y un Ring 3 distinto — Property, Listing, Deal, Showing, Offer. El inbox se comporta igual en las dos porque implementan el mismo contrato; storefront y búsqueda divergen porque Ring 3 es libre.

inite.shop es la que tira más fuerte de storefront y billing — ahí vive la integración con agentic commerce. Ring 3 son Product, Variant, Order, Cart, Customer (aliased de User por el mapa aliases: del manifiesto). Que Customer se llame distinto localmente está registrado en el manifiesto — alcanza para que inite-conform confirme la presencia de Ring 1 incluso con el alias.

Tres verticales distintas. Una spec. Las mismas cinco entidades Ring 1 bajo nombres locales diferentes. El mismo capability inbox entregando los mismos primitivos de conversación. Tres Ring 3 distintos que la spec no ve y no necesita ver. La forma operativa de esta tesis vive en un motor, muchas pieles.

Cuándo este es el formato equivocado

La separación constitución-vs-runtime es el formato equivocado en dos casos. El primero — un producto único que nunca va a ser más que él mismo. Agregar repo de spec, registry y herramienta de conformance a una empresa de un producto es overhead sin retorno. El monorepo común alcanza. El segundo — un portfolio de productos que no comparten nada en la capa de datos. Si el producto A es un juego iOS single-player y el producto B es una plataforma B2B de compras, compartir una entidad Company no es la palanca que parece. La separación paga cuando hay un contrato real y recurrente — SaaS multitenant que comparte identidad, billing, conversaciones y notificaciones — entre productos que parecen distintos por fuera e iguales por dentro.

Para Inite, 16 productos comparten un Ring 1, los ocho Ring 2 capabilities estables y el mismo set de servicios horizontales. La separación se paga muchas veces. Sin ella, cada vertical tendría su propio fork de @inite/auth en un trimestre. Con ella, el registry rastrea drift honesto, la spec se mueve a su ritmo y el runtime envía fixes a todos los productos a la vez. La fábrica detrás de los 16 está descrita en el modelo operativo Inite.

Dos repositorios. 16 productos. Un contrato al que se le permite cambiar de forma deliberada, y un runtime al que se le permite cambiar de forma continua. Ese es el patrón completo. El caso aplicado en deploy real está en el protocolo INITE en 6 etapas.