Appearance
Decisiones para el refinamiento
Estado: decisiones vigentes. La revisión 5 implementa la fundación multi-business; las separaciones físicas de verticales y el backend continúan pendientes. Fecha de revisión: 2026-09-16.
D01. Plataforma y stack
Monolito modular en NestJS 12 / TypeScript sobre Node.js 24 con PostgreSQL. Organización, identidad, acceso y capacidades constituyen la base. Catálogo, inventario, ventas y pagos son módulos de negocio reutilizables, no requisitos funcionales de cualquier tenant.
La instalación limpia de Ninaku Core requiere PostgreSQL 18. La imagen inicial de PostgreSQL 17 es histórica. El workflow ejecuta los SQL en PostgreSQL 18 nativo y registra la versión menor efectiva en el log; las pruebas históricas no sustituyen esa ejecución. No seleccionar ORM, broker, proveedor de nube o framework de CQRS en este PR.
D02. Una definición canónica por schema
Cada schema tiene un archivo fuente propietario. Tablas, restricciones, funciones y políticas deben quedar trazables a ese propietario. Infraestructura como extensiones y orquestación de instalación es una excepción técnica identificada, no un nuevo dominio.
El baseline todavía incumple la concentración por archivo en 0050, 0170, 0300 y 0400. Se conserva íntegro en esta entrega. No se eliminarán FK para simular independencia.
Procedimiento para el próximo cambio: mover primero definiciones sin dependencias posteriores, ubicar puentes en un propietario de integración explícito y calcular el orden real. Si una regla restante requiere una fase tardía, definir su fuente en el archivo del propietario y una instalación por fases con llamadas explícitas o artefactos derivados reproducibles. No introducir un runner complejo antes de probar un caso real. Nunca otorgar acceso runtime a una instalación parcial sin seguridad finalizada. Un instalador final solo orquesta; no mantiene otra copia manual de reglas.
D03. Independencia tiene tres niveles
- Comercial: habilitar capacidades por organización.
- Aplicación: módulos colaboran mediante contratos públicos y conservan sus escrituras.
- Instalación: un módulo no exige físicamente tablas de verticales ausentes.
El baseline implementa estructura para capacidades, pero sus FK aún fuerzan dependencias amplias. Una columna nullable o una capacidad desactivada no elimina una dependencia DDL. El objetivo inmediato es demostrar core e inventario sin cocina; no prometer todas las combinaciones de 38 schemas.
D04. Organización, propiedad y colaboración
Organization es el límite tenant. Business Unit modela una unidad de negocio administrativa/operativa y Vertical declara capacidades funcionales; no son el mismo concepto. Legal Entity identifica la entidad legal; Brand, la identidad comercial; Site, el lugar; Outlet, la unidad operativa. Las asignaciones efectivas Outlet→Business Unit y Outlet→Legal Entity conservan vigencia. Sales congela ambas dimensiones y Payments congela Legal Entity.
Un tenant puede combinar verticales. Dos organizaciones independientes no comparten acceso por pertenecer a Ninaku ni por tener el mismo propietario humano. Relaciones B2B requieren aceptación, alcance, revocación y mensajes autorizados. No exponer IDs, datos personales ni costos internos fuera del contrato.
D05. Inventario
El historial de cantidad y valoración conserva la autoridad. Los saldos son reconstruibles; el saldo usado para admitir una salida debe ser coherente dentro de la transacción o derivarse bajo el bloqueo adecuado. Una proyección asíncrona sirve para reportes, no para garantizar capacidad.
Conservar unidades/incrementos explícitos, precisión exacta, historial de primer uso, lotes, tránsito, conteos y diferencias. Separar transferencia en una entidad legal de operaciones entre entidades. Registrar correcciones por movimientos/contrapartidas según el contrato, sin reescribir significado histórico.
D06. Offline por operación
El cliente registra comandos y resultados locales durables. Sync no duplica reglas del dominio. El servidor aplica el mismo contrato usado online y distingue hechos ya ocurridos de intenciones todavía rechazables. Una orden offline_replay debe referenciar un comando Sync tipado del módulo Sales, con dispositivo, Outlet y tiempo efectivo coherentes; una marca booleana aislada no basta.
La desconexión impide garantizar disponibilidad global si varios dispositivos gastan la misma capacidad sin coordinación. Elegir reconciliación, asignación previa exclusiva u obligación de estar online por operación. La revocación de permisos no puede ser instantánea en un dispositivo aislado: definir autorización offline limitada, vigencia y tratamiento de hechos registrados durante la desconexión. No confiar solo en la hora del dispositivo.
D07. SQL y el caso de uso
SQL canónico conserva integridad, RLS y mecanismos de concurrencia. El caso de uso en Application coordina autorización, transacción y consecuencias. Los resolvers ya presentes en SQL se conservan hasta decidir explícitamente si se trasladan; no duplicar su autoridad en Application.
El ORM futuro no genera un modelo alternativo ni ejecuta DDL al arrancar. Todo adaptador participante en una operación atómica comparte conexión/transacción y contexto tenant. Persistencia de contexto con parámetros y alcance transaccional; separar autoridad de onboarding de la operación ordinaria.
D08. Validación vinculada a la fuente
Evidencia = commit + archivos/checksums + entorno + escenario + resultado. Una cuenta histórica de pruebas no valida este repositorio. Distinguir revisión estática, instalación, comportamiento, carga, recuperación y producto completo.
La revisión 5 añade pruebas nativas adversariales para la fundación multi-business, ownership de Payments, bridges Cash/Treasury, replay offline y provisión concurrente. Los escenarios aún no cubiertos continúan pendientes y no se consideran certificados por analogía.
D09. Clean Architecture por módulo
Una aplicación desplegable con límites de módulo y dependencias dirigidas hacia Domain/Application. Contratos entre módulos en proceso; no acceso a repositorios, SQL, clientes PostgreSQL ni infraestructura interna de otro módulo. El host compone y las transacciones coordinadas conservan una única unidad de trabajo cuando la regla exige atomicidad. La especificación vigente está en MODULE_CONTRACTS.md.
D10. API por caso de uso y presupuesto de pantalla
Máximo dos solicitudes de datos para carga inicial normal con sesión válida; contenido acotado, paginación y consultas adicionales bajo demanda. Compositores de lectura evitan que el frontend coordine veinte APIs. Escrituras por acciones de negocio, idempotentes donde producen efectos, errores Problem Details y contratos OpenAPI explícitos. No confundir pocas llamadas HTTP con pocas consultas SQL.
D11. Moneda e idioma independientes
Conservar moneda de documento/pago y moneda funcional por ledger, con snapshots de conversión y reglas de redondeo explícitas. Locale de interfaz, contenido traducido y documentos tienen resoluciones distintas. No inferir moneda o zona horaria del idioma. El análisis actual registra un riesgo concreto de redondeo FX pendiente de resolver con pruebas de negocio.
D12. Destino de telemetría
Grafana Cloud es el destino elegido para trazas y métricas OTLP, mediante el gateway de la región prod-sa-east-1. Staging ya lo configura con OTEL_EXPORTER_OTLP_ENDPOINT (URL base que termina en /otlp; el SDK añade la ruta de cada señal) y OTEL_EXPORTER_OTLP_HEADERS. La cabecera debe ser el par completo Authorization=Basic <base64>, nunca solo el valor base64: el parser exige la forma nombre=valor por cada entrada separada por comas y hace fallar el arranque nombrando OTEL_EXPORTER_OTLP_HEADERS si falta el =, el nombre o el valor, en vez de dejar la exportación sin autenticar con un 401 silencioso. Muestreo y retención siguen sin decidir.
D13. Compatibilidad de contrato OpenAPI
Un cambio incompatible en el OpenAPI publicado falla el CI salvo que el componente major de info.version haya subido respecto al baseline. Subir el major es la forma explícita y autodocumentada de aceptar una ruptura de contrato: no depende de una excepción manual ni de que alguien recuerde justificarla, y deja constancia del cambio en el propio documento.
D14. Severidad de logs para 404
Un 404 por ruta no reconocida se registra en info; un 404 por ruta reconocida pero recurso no encontrado permanece en warn. warn se reserva para lo que una persona puede necesitar atender: si el rastreo automático de rutas inexistentes también fuera warn, el ruido de escáneres y bots ahogaría la señal real.
D15. Checks requeridos en main y staging
railway-and-migrator, pre-foundation-integrity, openapi-compatibility y docs-site son los checks que deben quedar requeridos en main y staging. Un job que corre sin ser requerido no bloquea un merge roto; no es un gate. Hoy ninguno lo es: los rulesets están inertes por el plan de la organización, como explica D20, así que estos cuatro se ejecutan sin bloquear nada.
El 12 de octubre de 2026 el propietario retiró build-test (app.yml) y sql-regressions (database.yml): juntos tardaban unos 45 minutos por corrida, gastaban los minutos del plan gratuito y sus fallos aparecían recién al promover a main, cuando el trabajo ya estaba en staging. Los reemplazan el npm run verify completo y local de quien integra, que ya corre build, pruebas unitarias, integración y e2e contra PostgreSQL 18, y el npm run db:test manual sobre un clúster desechable que AGENTS.md sección 8 exige antes de fusionar una PR que toque database/ y antes de cada promoción a main.
D16. Flujo de entrega
El trabajo entra por pull requests independientes hacia staging, cada una acotada a 400 líneas cambiadas y fusionada en orden. Ninguna apunta a otra: ese flujo exige un reapuntado manual después de cada fusión, y un reapuntado olvidado ya dejó trabajo fusionado fuera de staging, que hubo que recuperar con una pull request adicional. staging se fusiona a main con merge commit, nunca squash, para conservar el historial de cada pull request. Con el CI de main en verde, staging avanza en fast-forward hasta el commit de fusión de main, de modo que ambas ramas quedan en el mismo punto y la siguiente tanda de trabajo parte de una base idéntica.
D17. Resolución de la versión de servicio
La versión de servicio expuesta en cada registro de log y span se resuelve como SERVICE_VERSION explícita; si falta, RAILWAY_GIT_COMMIT_SHA truncada a 12 caracteres; si tampoco existe, unknown. El orden asegura que un span pueda rastrearse hasta el build que lo produjo sin depender de que alguien la declare manualmente en cada entorno.
D18. Contratos públicos entre módulos
Cada módulo de negocio posee una superficie pública explícita bajo contracts/. Otro módulo puede consumir esa superficie, pero no puede importar repositorios, SQL, infraestructura, handlers internos ni tipos del driver PostgreSQL del módulo proveedor. Contract significa lo que el módulo ofrece; Port significa lo que el módulo necesita y permanece interno salvo decisión explícita.
La colaboración se divide en tres modos y no se unifica en un bus genérico: contrato síncrono en proceso cuando el resultado es necesario para completar el caso de uso, read contract para composiciones de lectura, y evento durable mediante outbox/inbox para consecuencias desacoplables o recuperables. No hay HTTP interno entre módulos del mismo monolito.
Cuando una invariancia exige atomicidad entre varios propietarios, los contratos participantes pueden compartir una sesión/transacción Foundation opaca y tenant-safe; esa superficie no expone pg.PoolClient. Cada módulo conserva sus propias escrituras e invariantes. Los efectos externos nunca se consideran atómicos con PostgreSQL y usan orquestación recuperable.
Los contratos usan lenguaje de negocio y tipos command/query/result explícitos. No exponen entidades ORM, filas crudas, query builders, SDKs externos ni operaciones CRUD universales. Los verticales consumen exactamente los mismos contratos y no son un atajo para escribir tablas de módulos compartidos.
npm run lint:module-boundaries bloquea en CI los imports cross-module hacia domain/, application/, infrastructure/ o presentation/ de otro módulo y permite únicamente su superficie pública documentada, desde antes de que exista el primer módulo real. La convención completa y criterios de aceptación viven en MODULE_CONTRACTS.md.
D19. Alcance del CI por lo que cambia
En las pull requests, cada workflow se ejecuta solo si la petición toca los archivos de los que depende. En los push a main y staging no hay filtro alguno: las ramas de registro se verifican siempre completas.
La decisión se tomó con medición, no por intuición. En una jornada de 29 commits el repositorio consumió unos 119 minutos de ejecución, de los cuales 79 correspondieron a database e infrastructure; en esos mismos 29 commits no hubo un solo cambio bajo database/ ni bajo .railway/. Dos tercios del gasto se fueron en verificar entradas que nadie había tocado.
Los filtros se derivan de lo que cada workflow ejecuta realmente, no de lo que su nombre sugiere. Todos los scripts db:* viven bajo database/ y iac:typecheck bajo .railway/, de modo que sus filtros son directos. Hay dos dependencias que no son evidentes y que, omitidas, producirían verdes falsos: app ejecuta db:prepare antes de integración y e2e, así que depende de database/, y su suite unitaria cubre los specs de tooling/; infrastructure construye la imagen del migrador desde database/Dockerfile, así que también depende de database/.
repository queda sin filtrar a propósito. Es el más barato de los cuatro y es el portón estructural: openapi:compat necesita ver todo cambio para detectar deriva del contrato, y un filtro lo volvería ciego justo cuando importa.
Cada workflow declara además un grupo de concurrencia que cancela ejecuciones superadas, pero solo en pull requests. Un push a main o staging nunca se cancela.
Trampa a recordar si vuelven los rulesets: un workflow con filtro de rutas que además sea check requerido nunca reporta en las pull requests que omite, y esa pull request no puede fusionarse jamás. Hoy la combinación no se da porque no hay ningún ruleset activo, como explica D20. Cuando vuelvan, hay que sacar esos checks de la lista de requeridos o agregar un job complementario con el mismo nombre y el filtro inverso que simplemente tenga éxito.
D20. Hoy no hay protección de rama
La organización está en plan free con el repositorio privado, así que GitHub responde 403 Upgrade to GitHub Pro or make this repository public tanto en la API de rulesets como en la protección clásica de rama. No hay ruleset activo, no hay check requerido, y nada rechaza un force push, un merge sin revisar ni un merge con checks en rojo o ausentes.
El flujo de entrega de D16 y de RAILWAY_OPERATIONS.md sigue siendo el correcto. Hoy se sostiene porque las personas lo siguen, no porque algo lo imponga, y conviene decirlo en vez de suponer una compuerta que no existe: quien confía en que el sistema lo va a frenar deja de frenarse solo.
Para que vuelva a ser una compuerta hacen falta tres cosas: subir el plan o hacer público el repositorio, declarar los dos rulesets que describe RAILWAY_OPERATIONS.md, y marcar como requeridos los cinco checks de D15. La trampa de los filtros de rutas frente a los checks requeridos está en D19.
D21. Una organización activa conserva administración
Un administrador válido es un principal humano activo, con membresía activa, un rol activo del tenant o global, el permiso activo organization.account.manage y alcance de toda la organización. Varias personas pueden cumplirlo a la vez; la garantía es que quede al menos una.
La garantía empieza cuando platform.organization_provisioning_requests registra la admisión como completada. Una fila de organization.organizations creada sin esa admisión no es una organización habilitada para operar, y no se infiere administración desde el nombre de un rol.
Se rechaza al confirmar la transacción cualquier camino que deje sin administrador a una organización activa y admitida: borrar la última asignación administradora, suspender o terminar su última membresía, reducir su alcance a una sucursal o a otra dimensión, bloquear al último principal, desactivar o mover su rol, quitarle el permiso administrativo, renombrar o deprecar ese permiso, y reactivar una organización suspendida que no recuperó administración. Borrar la evidencia de admisión tampoco elude el control: una fila de provisioning completada es inmutable.
Una organización suspendida o archivada conserva su historia sin administrador activo. Eso nunca la habilita para operar. Bloquear a una persona en toda la plataforma y suspender una de sus membresías siguen siendo decisiones distintas.
identity.assert_administration_preserved (database/canonical/0400_cross_domain_contracts.sql) levanta 23514 con CONSTRAINT='identity_last_administrator_required'. Nueve triggers DEFERRABLE INITIALLY DEFERRED la invocan sobre identity.identities, identity.roles, identity.permissions, identity.role_permissions, identity.memberships, identity.role_assignments, identity.access_scopes, organization.organizations y platform.organization_provisioning_requests. Que sean diferidos es lo que permite reemplazar administración dentro de una misma transacción sin pasar por un estado inválido, y un pg_advisory_xact_lock por organización es lo que impide que dos transacciones concurrentes se quiten el último administrador entre sí. Desde la revisión 171 (migración 0145) identity.roles e identity.role_permissions no toman el candado global exclusivo ni revisan todas las organizaciones: una edición de rol toma la compuerta global en modo compartido y el candado de su propia organización, y su verificación diferida (identity.check_role_administration_preserved) revisa solo las organizaciones que tienen asignado el rol cambiado; un rol del sistema conserva el candado global exclusivo. database/tests/contracts/administration-contracts.ts y roles-management-contracts.ts cubren cada uno de esos caminos.
Por qué está escrita aquí. Esta garantía se aplicaba en SQL y no se podía leer en ningún documento vigente: su definición vivía en un archivo de historial que se borró. Un invariante que nadie puede leer se rompe en el primer módulo que lo desconozca, y este cruza tres esquemas.
D22. Origen de la policy de verificación y TOTP, y quién posee sus límites
AppConfigService.outOfBandCode y AppConfigService.totp exponen la configuración de entorno como valores tipados sin validar su rango de negocio: el esquema de Foundation (environment-variables.schema.ts) solo verifica forma (texto, entero, entero no negativo), nunca formato conocido, longitud, dígitos RFC 6238, algoritmo o duración de paso. Foundation no puede importar del dominio de Identity (regla R4 de MODULE_CONTRACTS.md), así que no hay una segunda copia de esos límites para mantener sincronizada.
El dominio de Identity es el único dueño de esos límites: buildOutOfBandCodePolicy (verification-code.ts) exige un formato de OUT_OF_BAND_CODE_FORMAT y una longitud entera entre OUT_OF_BAND_CODE_MINIMUM_LENGTH (6) y OUT_OF_BAND_CODE_MAXIMUM_LENGTH (12); buildTotpPolicy (totp-policy.ts) exige dígitos y algoritmo RFC 6238, un paso entero entre TOTP_STEP_SECONDS_MINIMUM (15) y TOTP_STEP_SECONDS_MAXIMUM (120), y un desfase entero entre 0 y TOTP_ALLOWED_SKEW_STEPS_MAXIMUM (2). Un paso más corto que 15 segundos rota el código más rápido de lo que una persona puede leerlo y escribirlo; uno más largo que 120 segundos deja un código capturado válido el tiempo suficiente para debilitar "posesión ahora" a "posesión en algún momento de los últimos dos minutos". Cada paso adicional de desfase ensancha linealmente el conjunto de códigos que el servidor acepta a la vez, la misma tolerancia de la que se beneficia un atacante; un paso (la propia tolerancia de RFC 6238 para el retraso de transmisión) es el default, y dos sigue siendo una excepción acotada para redes lentas o relojes visiblemente desincronizados, nunca una ventana sin límite.
VerificationPolicyService (infrastructure/verification/verification-policy.service.ts) construye ambas políticas una sola vez, en su constructor, llamando a esos dos builders con los valores crudos de AppConfigService. Como Nest instancia todos los providers de un módulo cargado de forma no perezosa al compilar el módulo, un valor fuera de esos límites lanza ahí mismo, antes de que la aplicación termine de arrancar: la validación de forma en Foundation nunca es la última palabra, y no hace falta duplicar el límite de negocio para conseguir el mismo arranque fallido. identity.module.spec.ts prueba exactamente este camino para cada límite.
VerificationPolicyPort (application/ports/verification-policy.port.ts) es la única puerta por la que un caso de uso llega a estas políticas: emitir o verificar un código por email/WhatsApp, y construir o verificar un TOTP, siempre pasan por this.verificationPolicy.outOfBandCodePolicy(), .totpPolicy() o .totpPolicyForMethod(stored), nunca por una constante propia ni por AppConfigService directamente. Cuando llegue el override por organización (tabla en PostgreSQL, junto al módulo organization), sustituye únicamente la implementación de este puerto; ningún caso de uso cambia.
OutOfBandCodeSchema (presentation/dtos/out-of-band-code.schema.ts) y los esquemas de código TOTP (second-factor-confirmation-request.schema.ts, sign-in-second-factor-request.schema.ts) validan un superconjunto de toda policy posible (6 a 12 caracteres; 6 u 8 dígitos), no la forma exacta de la policy vigente: un código emitido antes de un cambio de policy conserva esa forma, así que Presentación sigue aceptándolo hasta que expira por sí solo, y solo el hash comparado en Aplicación decide si es correcto. verification-code-policy.e2e-spec.ts prueba que un código así emitido sigue confirmando después de que la aplicación reinicia con otra policy, y que el presupuesto de intentos del challenge y el contador de bloqueo de cuenta no se reinician por ese cambio, porque viven en PostgreSQL y el cambio de policy es puramente un valor en memoria de la aplicación.
Un cambio de policy de TOTP nunca invalida un método ya inscrito. identity.totp_methods (database/canonical/0040_identity.sql, migración 0012_totp_methods_remember_their_policy.sql, baseline revisión 22) guarda digits, algorithm y period_seconds junto a cada método, NOT NULL con default igual al comportamiento de hoy (6, SHA1, 30) y con CHECK idénticos a los límites del dominio (totp_methods_digits_chk, totp_methods_algorithm_chk, totp_methods_period_seconds_chk). protect_totp_lifecycle() extiende la misma inmutabilidad que ya protegía secret_ref: ninguna de las tres columnas puede cambiar después de la inscripción, solo una re-inscripción las reemplaza. La inscripción (EnrolSecondFactorUseCase) guarda la policy global vigente en ese momento junto al secreto; la confirmación (ConfirmSecondFactorUseCase) y el segundo paso del inicio de sesión (CompleteSignInSecondFactorUseCase) verifican cada método contra totpPolicyForMethod(stored) — la policy que ese método tiene grabada, combinada con el allowedSkewSteps global vigente, porque el desfase es tolerancia del servidor, no forma del autenticador — nunca contra totpPolicy(), la policy global "para inscripciones nuevas". totp-policy.e2e-spec.ts prueba contra PostgreSQL real que una aplicación autenticadora inscrita en 6/SHA1/30 sigue iniciando sesión con su código de 6 dígitos después de que la aplicación reinicia configurada en 8/SHA256/60, y que una inscripción nueva hecha después del reinicio recibe la policy nueva.
D23. Una identidad puede tener password y proveedor a la vez, y nunca se enlazan solos
identity.authentication_methods ya era el registro único de credenciales de una identidad (password, external_provider, passkey), con identity.password_credentials e identity.external_identities como tablas de detalle 1:1. Antes de esta revisión, el único camino para adquirir una credencial external_provider era OAuthSignInRepository.resolveIdentity() durante el sign-in con proveedor, que crea una identidad nueva cuando el (provider, subject) no está enlazado a nadie; no existía ningún camino para que una identidad ya autenticada (por password o por otro proveedor) adquiriera una credencial adicional sin pasar por sign-in. Esta revisión agrega dos rutas de escritura sobre el mismo modelo, sin ninguna migración de esquema: el CHECK/índice único que hacía falta ya existía.
Crear un password no reemplaza uno existente. POST /password-methods (CreatePasswordMethodUseCase, IdentityPasswordMethodRepository.claimPassword) bloquea la fila de identity.identities con FOR UPDATE, comprueba si ya existe un método password activo y, si lo hay, responde 409 · identity.password_method_exists sin tocar nada; si no, inserta authentication_methods + password_credentials en la misma transacción. Nunca revoca sesiones porque no compromete nada: a diferencia de PasswordChangeUseCase (que reemplaza un hash y por eso cierra toda otra sesión), esta ruta solo puede ejecutarse cuando no hay password que sustituir. authentication_methods_one_active_password_uq (parcial, WHERE method_type = 'password' AND revoked_at IS NULL) es la garantía de última línea si el lock se saltara.
Enlazar un proveedor nunca fusiona identidades, y nunca por email. POST /sign-in-methods/providers (LinkProviderUseCase) verifica el ID token con el mismo OAuthIdentityVerifierPort y gasta el nonce con el mismo ProviderNonceRepositoryPort que el sign-in con proveedor — mismo emisor, audiencia, pin de firma y nonce de un solo uso —, todo antes de escribir nada. OAuthSignInRepository.linkIdentity() toma el mismo advisory lock por (provider, subject) que ya usaba resolveIdentity(), comprueba si ese par ya está enlazado a cualquier identidad y, si lo está, responde el mismo 409 · identity.provider_link_refused sin distinguir si el dueño es la propia identidad que llama o una completamente distinta: la respuesta nunca revela cuál de las dos causas fue. external_identities_provider_subject_uq (única sobre (provider, subject), sin importar la identidad) es la garantía de última línea. La identidad destino la decide siempre el llamador autenticado (caller.identityId), nunca una coincidencia de provider_email: ese campo es una instantánea informativa, nunca una clave de emparejamiento, exactamente como ya documentaba el CHECK de la tabla.
El último camino de entrada ahora cuenta un proveedor enlazado como se cuenta a sí mismo, y la fórmula se evalúa igual sin importar qué se remueve. identity.sign_in_methods.WaysInSnapshot reemplaza el booleano hasActiveSelfSufficientMethod por activeSelfSufficientMethodCount, porque POST /sign-in-methods/:id/removals (lockRemovableSignInMethod) ahora también reconoce un método external_provider activo como objetivo removible (antes solo reconocía identificadores verificados y el password). hasRemainingWayIn() calcula, para el removedKind presentado, cuántos métodos self-sufficient sobrevivirían (restando uno solo cuando lo que se remueve es el propio google/apple), cuántos identificadores verificados sobrevivirían (restando uno solo cuando lo que se remueve es el propio identificador) y si el password sobrevive (false solo cuando lo que se remueve es el propio password); queda una vía de entrada cuando sobrevive al menos un método self-sufficient, o sobreviven a la vez un identificador verificado y un password activo. Una primera versión de este cambio evaluaba la rama self-sufficient con un return anticipado que nunca consultaba la combinación identificador+password: una identidad con un email verificado, un password activo y un Google enlazado no podía remover ese Google (contaba 0 métodos self-sufficient restantes y nunca llegaba a mirar que el email y el password seguían intactos), aunque el email+password siguiera siendo una vía de entrada completa. La revisión adversarial de RDD detectó esto antes del commit; last-way-in-policy.spec.ts prueba con una tabla las cinco combinaciones que separan ambas ramas. revokeSignInMethod() decide entre revocar un identity.login_identifiers o un identity.authentication_methods reutilizando isIdentifierType(kind), ya importado, en vez de una lista nueva. La consulta que localiza un método de proveedor removible bloquea la fila con FOR UPDATE OF method (no FOR UPDATE liso): un FOR UPDATE sin acotar sobre el JOIN a identity.external_identities exige privilegio UPDATE en esa tabla, que ninaku_runtime nunca tiene (solo SELECT, INSERT) porque esta ruta nunca escribe ahí; acotar el lock a authentication_methods —la única fila que revokeSignInMethod() de verdad actualiza— evita pedir un grant nuevo.
Desenlazar (o remover una contraseña) ahora conserva la sesión que llama y termina toda otra sesión. identity.authentication_methods_revoke_sessions (trigger AFTER UPDATE, database/canonical/0400_cross_domain_contracts.sql) revocaba toda sesión de una identidad, sin excepción, cuando cualquier método de autenticación pasaba a revoked_at IS NOT NULL; hasta la revisión que introdujo el desenlace de proveedor eso solo se ejercitaba al revocar un password (que sí actualiza authentication_methods), nunca al revocar un identificador (que solo actualiza identity.login_identifiers y no dispara este trigger). Al hacer removible un proveedor, esa revisión ejercitó ese trigger por primera vez con la sesión que llama, y esa sesión también terminaba revocada — el mismo defecto que ya evitaba PasswordChangeUseCase (que nunca toca revoked_at, así que nunca dispara este trigger, y revoca las demás sesiones explícitamente). Esta revisión cierra esa inconsistencia: identity.revoke_compromised_method_sessions() distingue una transición de status a compromised — termina toda sesión sin excepción, es la ruta de un método comprometido — de una transición simple de revoked_at, que ahora respeta un ajuste local a la transacción, identity.surviving_session_id, fijado con set_config(..., true) antes del UPDATE. IdentitySignInMethodRepository.revoke() fija ese ajuste con caller.sessionId antes de revocar un password o un proveedor vinculado desde POST /sign-in-methods/:id/removals, así que esa ruta ahora tiene el mismo contrato que el cambio de contraseña: la sesión que llama sobrevive, toda otra sesión de la identidad termina. Una revocación sin sesión que llama (por ejemplo, una herramienta administrativa que actualiza la fila directamente, sin fijar ese ajuste) sigue terminando toda sesión, igual que antes. Fuera de este trigger, otras dos rutas de Identity también terminan sesiones y siguen el mismo criterio — perdonar la sesión que llama solo cuando existe una: PasswordChangeUseCase, ya citado arriba, perdona caller.sessionId porque prueba la contraseña vigente desde una sesión viva; ConfirmPasswordRecoveryUseCase (IdentityPasswordRecoveryRepository.commitRecovery()) confirma un canje/challenge sin ninguna sesión que llame, así que su propia consulta explícita (REVOKE_ALL_SESSIONS, sin excepción alguna) termina toda sesión de la identidad exactamente como la rama comprometida del trigger, sin fijar ni consultar identity.surviving_session_id. sign-in-method-providers.e2e-spec.ts prueba que la identidad sigue entrando con email+password en una sesión nueva y que ese (provider, subject) desenlazado queda refusado en cualquier otra puerta — POST /sign-ins responde 401 · identity.sign_in_refused y POST /step-ups/providers responde 403 · identity.step_up_confirmation_refused — porque ambos leen eligible a partir de method.status = 'active' AND method.revoked_at IS NULL, nunca de la mera presencia de la fila en external_identities; remove-sign-in-method-sessions.integration-spec.ts prueba la supervivencia de la sesión que llama, para un password y para un proveedor removidos. Migración 0016_voluntary_method_revocation_spares_the_caller.sql.
Remover un autenticador TOTP conserva la sesión que llama y termina toda otra sesión, sin pasar por ningún trigger. identity.totp_methods vive fuera de identity.authentication_methods, así que revocar un método TOTP nunca dispara authentication_methods_revoke_sessions: antes de esta revisión, RemoveSecondFactorUseCase revocaba la fila de totp_methods y no terminaba ninguna sesión, a diferencia de cada otra ruta de esta sección. IdentitySecondFactorRepository.revokeOtherSessions() repite, dentro de la misma transacción, la misma consulta explícita que ya usa IdentityPasswordChangeRepository.commitPasswordChange() (UPDATE identity.sessions ... WHERE identity_id = $1 AND id <> $2 AND revoked_at IS NULL), nunca el ajuste transaccional identity.surviving_session_id: como esta ruta jamás actualiza authentication_methods, no hay trigger que respetar y no hace falta uno nuevo. RemoveSecondFactorUseCase.execute() la invoca solo cuando revokeVerifiedMethod() revocó de verdad una fila, con la razón second factor removed. remove-second-factor.use-case.spec.ts prueba la secuencia revoke → revoke-other-sessions → audit → commit y que un id que la revocación no tocó nunca termina ninguna sesión; remove-second-factor-sessions.integration-spec.ts prueba contra PostgreSQL real que la sesión que llama sobrevive y toda otra sesión de la identidad termina.
Un proveedor sin enlace nunca crea una segunda identidad cuando su email verificado ya pertenece a una cuenta activa. POST /sign-ins con un proveedor resolvía un (provider, subject) sin enlace creando siempre una identidad nueva, incluso cuando el token vouchaba por un email ya verificado en otra identidad — por ejemplo, tras desenlazar Google de una cuenta con email+password, volver a entrar con ese mismo Google creaba una segunda identidad en vez de negarse. OAuthSignInRepository.resolveIdentity() ahora, antes de crear una identidad nueva, busca un identity.login_identifiers activo (revoked_at IS NULL) y verificado (verified_at IS NOT NULL) cuyo normalized_value case-insensitive coincida con el email del token — solo cuando el token lo vouchó (email_verified: true; OAuthIdentityVerifierService.readVerifiedEmail() ya descarta el email si el proveedor no lo marcó verificado, así que resolved.email definido implica siempre email_verified: true). Si existe, se niega con 409 · identity.account_exists_for_provider_email sin crear ni enlazar nada — enlazar automáticamente violaría esta misma decisión ("nunca se enlazan solos") — y el detalle le dice al llamador que entre con el método existente y enlace el proveedor desde la cuenta. Un email no verificado por el proveedor, o que no coincide con ningún identificador activo, conserva el comportamiento de hoy: crea una identidad nueva. La consulta que busca ese identificador (FIND_ACTIVE_IDENTITY_BY_VERIFIED_EMAIL) nunca junta contra identity.identities ni filtra por su status: la refusa se aplica exactamente igual cuando la identidad dueña del email está active, blocked, disabled o archived, así que bloquear una identidad nunca es evadible creando una segunda por esta puerta, y el mismo 409 genérico —nunca uno distinto ni un detalle adicional— tampoco revela que la identidad encontrada está bloqueada. provider-sign-in.e2e-spec.ts y oauth-sign-in.repository.integration-spec.ts prueban las tres ramas, más el pliegue de mayúsculas (refuses when an existing identity verified its email in mixed case and the provider token already carries it lowercased) y una identidad bloqueada (refuses even when the matching identity is blocked, never creating a second identity to evade it).
Ninguna de las rutas de esta sección usa migraciones de esquema. La única migración de la revisión que introdujo el desenlace de proveedor (0014_password_method_and_provider_link_are_audited.sql) siembra los dos nuevos Audit Action Type que esas rutas graban.
D24. Caché condicional, esquemas y medición de latencia se aplican con criterio, no por defecto
Estas reglas deciden cuándo una ruta lleva ETag, qué valida su esquema, cuándo entra a la medición de latencia y qué objetivo de latencia le corresponde. Cada una existe por un costo concreto; aplicarlas donde ese costo no existe agrega código y pruebas sin beneficio.
Una lectura lleva ETag solo cuando se lee mucho y cambia poco. Califican el catálogo público de planes (GET /plans), los datos de referencia, el perfil y la estructura de una organización, y el plan y los límites vigentes de una organización. No califican los datos operativos que cambian en segundos (pedidos, inventario, sesiones) ni las listas paginadas por cursor: su ETag cambiaría en casi toda lectura y el 304 no ahorraría nada, mientras que el hash sí costaría en cada respuesta. Un controlador que califica devuelve HttpConditionalResponse; HttpEnvelopeInterceptor compara If-None-Match y responde 304 sin cuerpo.
El ETag se deriva de los datos que la respuesta devuelve, nunca del reloj ni del proceso. Sirve una versión del agregado o un hash del contenido exacto (el catálogo usa un hash del catálogo del país pedido). Cada ruta con ETag tiene una prueba que cambia el dato subyacente y comprueba que el ETag cambia y que el If-None-Match anterior ya no produce 304; un ETag que no cambia cuando el dato cambia sirve contenido viejo sin que nadie lo note.
Una respuesta que depende del tenant o del usuario nunca lleva Cache-Control: public. public permite que un CDN o proxy compartido guarde la respuesta y se la entregue a otra persona. Esas rutas usan private, no-cache: el navegador conserva la copia, revalida con If-None-Match y nunca la comparte. Solo una lectura sin sesión e idéntica para todo llamador, como el catálogo (public, max-age=60), puede ser public.
Una escritura sobre un recurso que se lee con ETag acepta If-Match. Si el ETag enviado ya no coincide con el estado actual, assertIfMatchSatisfied (foundation/http/conditional-requests/conditional-request.ts) responde 412 y no escribe nada: dos administradores que editan el mismo perfil no se pisan en silencio.
La estructura de una organización usa una sola versión para toda la organización, y ese atajo tiene costos declarados. GET /organization y GET /organization/structure toman su ETag de organization.structure_versions, que avanza con cualquier escritura de la estructura o del perfil. Por eso dos administradores que editan cosas sin relación (un sitio y una marca) pueden recibir 412 el uno del otro si ambos mandan If-Match; el ETag del perfil cambia con cada escritura de la estructura aunque el perfil no haya cambiado; y una respuesta de escritura no devuelve un ETag nuevo, así que el cliente vuelve a leer antes de la siguiente escritura condicional. A cambio, If-Match cuesta leer una fila bloqueada y no un hash del contenido. La estructura además muestra la unidad de negocio y la entidad legal vigentes hoy en la fecha del sitio, que cambian sin ninguna escritura cuando pasa la medianoche del sitio o vence un valid_until; su ETag agrega un hash de esas asignaciones vigentes, así un If-None-Match viejo deja de dar 304 cuando cambian, y If-Match sigue aceptando ese ETag mientras la versión no cambie. El ETag del perfil no depende de fechas y no lleva ese hash.
Toda petición y toda respuesta tiene un esquema Zod estricto. El esquema de entrada rechaza campos desconocidos en vez de ignorarlos, así un campo mal escrito falla con 400 en lugar de perderse. El esquema de respuesta alimenta el documento OpenAPI y es lo que el frontend genera como tipo; una respuesta sin esquema es un contrato que nadie puede verificar.
Una ruta caliente entra a perf:http; una ruta administrativa no. Caliente es una ruta que se ejecuta en cada sesión o en cada pantalla de uso diario (iniciar sesión, refrescar sesión, leer el catálogo, leer el plan vigente). perf:http la mide con un cliente y con 16 clientes concurrentes y reporta p50, p90, p95 y p99. Las rutas del panel de plataforma se usan pocas veces al día y no entran.
Una consulta sobre una tabla que crece sin límite se revisa con EXPLAIN (ANALYZE, BUFFERS) antes de entrar. Si el plan hace un Seq Scan sobre esa tabla, la misma migración agrega el índice que el filtro y el orden necesitan. Las tablas acotadas por diseño (planes, mercados, personal de plataforma) no lo necesitan.
Las rutas que calculan un hash de contraseña tienen su propio objetivo de latencia. Iniciar sesión con contraseña, registrarse, y crear, cambiar o recuperar una contraseña ejecutan Argon2id, que es lento a propósito: esa lentitud es lo que encarece un ataque de fuerza bruta. Esas rutas se miden contra p50 < 100 ms, p90 < 150 ms, p95 < 200 ms y p99 < 300 ms; el resto de la API conserva los objetivos de AGENTS.md §5. Los parámetros de Argon2id (password-hasher.service.ts: 19 MiB, timeCost 2, parallelism 1) son el mínimo de OWASP y no se bajan para cumplir un objetivo de latencia. Cambiar a bcrypt no mejora nada: OWASP lo pone detrás de Argon2id, y su resistencia a hardware dedicado es menor al mismo costo. Si una ruta de contraseña no cumple su objetivo bajo carga, la respuesta es más CPU o limitar la concurrencia de hashing, nunca un hash más débil.
Los precios de un plan no incluyen impuestos. platform.plan_offerings.amount guarda el monto antes de impuestos y ninguna columna lo contradice; el frontend lo muestra como "sin IVA". Si un país exige mostrar el precio con impuestos incluidos, ese modo se agrega en markets (el país), no en la oferta, y solo cuando ese país exista.
D25. El detail de un error es técnico y en inglés; el cliente traduce desde code
detail en Problem Details explica la causa de un fallo a quien integra la API y siempre está en inglés. La API no traduce mensajes de error ni negocia su idioma con Accept-Language. El texto que ve el usuario final lo pone el cliente, a partir de code: un identificador estable (identity.sign_in_refused, foundation.validation_failed) que forma parte del contrato y nunca cambia sin versión nueva.
Traducir en el servidor obligaría a mantener cada mensaje (hoy unos 60) en todos los idiomas soportados, y cada fallo nuevo nacería con esa deuda. Además, el cliente sabe mejor que el servidor cómo contarle un error a su usuario: un mismo code puede verse distinto en una pantalla de caja y en un formulario de registro. Separar el mensaje para el integrador del mensaje para el usuario elimina esa deuda sin perder información, porque code sigue identificando el caso exacto y meta.errors sigue señalando el campo.
La negociación de idioma de src/foundation/locales/ queda reservada para contenido de negocio que sí se sirve localizado, como los nombres de catálogo de las tablas de traducción; ver CURRENCY_AND_LANGUAGE.md.
D26. El outbox se despacha desde PostgreSQL con un worker separado, nunca con BullMQ/Redis
Los cuatro flujos de seguridad de Identity (código de registro, alta de método de acceso, recuperación de contraseña, step-up) enviaban su código de verificación con una llamada síncrona y real al proveedor (SES, Wasender) dentro de la petición HTTP, hasta 10 segundos por intento, con cuatro órdenes distintas entre "confirmar el challenge" y "enviar el código" — incluido un caso, step-up, que enviaba antes de confirmar el challenge. AGENTS.md §5.4 y MODULE_CONTRACTS.md §4.3 nombraban BullMQ como despachador, un paquete que nunca se instaló; events.* ya tenía un outbox con forma de producción (claim_outbox_batch con FOR UPDATE SKIP LOCKED, lease, reintentos, dead letters) sin ningún grant y sin ningún módulo que lo usara. El diseño completo vive en OUTBOX_USE_CASES.md; esta decisión fija por qué su forma es la que es.
La cola vive en PostgreSQL; la despacha un worker que corre como su propio servicio de Railway (OB1), nunca BullMQ/Redis. El objetivo es que la API nunca se sature, y la saturación no viene de la tecnología de cola sino de dónde corren la espera al proveedor y sus reintentos: si esa espera vive dentro del proceso que atiende peticiones HTTP, un proveedor lento satura la API sin importar qué cola exista detrás de él. Moviendo el envío a un proceso separado, la fila de outbox se inserta en la misma transacción que el cambio de negocio (challenge, alta, etc.), así que un rollback de uno es un rollback del otro y ningún mensaje se pierde por una escritura que nunca comprometió. PostgreSQL, no BullMQ, es la fuente de verdad de la cola: no hay un segundo servicio (Redis) que pagar, operar ni mantener consistente con la base de datos, y events.outbox_records ya probaba el mecanismo (FOR UPDATE SKIP LOCKED + lease) sin necesitar nada nuevo. Si el volumen alguna vez lo exige, BullMQ puede sentarse detrás de este mismo outbox como un despachador más — esta decisión es sobre la fuente de verdad de la cola, no una prohibición permanente de BullMQ en el resto del sistema (AVAILABILITY_AND_PERFORMANCE.md §10, NESTJS_STACK_GUIDE.md §14 siguen permitiéndolo para trabajo asíncrono que no sea despacho de outbox).
Los mensajes de seguridad de Identity usan un outbox propio, sin organization_id (OB2). events.* y notifications.* exigen organization_id NOT NULL y su propia política RLS por tenant; los cuatro flujos de Identity ocurren antes de que exista contexto de tenant (un registro, un step-up, una recuperación de contraseña), así que forzarlos por el outbox tenant-scoped significaría inventar un organization_id falso o debilitar el NOT NULL/la RLS que protege cada fila de negocio real. identity.security_outbox_messages (propuesta) copia casi textual la forma ya probada de events.outbox_records, sin la columna de tenant, y un mismo worker despacha ambos outbox — la separación es estructural (una tabla sin organization_id no puede confundirse con una tenant-scoped), no solo una convención de código.
El OTP viaja cifrado y se borra apenas se envía (OB3). El código de verificación existe en claro solo en memoria, mientras se genera y se hashea para el challenge; en la tabla, solo como un sobre AES-GCM bajo una clave propia (distinta de la clave TOTP), con el id del challenge como contexto AAD — así un bug que mezclara el ciphertext de dos mensajes falla cerrado (open() lanza) en vez de entregar un código equivocado. El worker descifra, envía y borra la fila de ciphertext en la misma transacción que marca el mensaje published; un ciphertext que nunca llega a enviarse se borra cuando su challenge expira, así el secreto nunca sobrevive más tiempo del que puede ser útil.
La entrega es al menos una vez, nunca exactamente una vez (OB9). Un worker que se cae después de enviar pero antes de registrar el intento deja el mensaje reclamable de nuevo; el siguiente worker lo reenvía. Este es el mismo contrato que events.outbox_records ya documenta ("Publication is at-least-once; consumers must be idempotent"), heredado sin fortalecerlo. Un código duplicado es una molestia de UX, nunca un agujero de seguridad, porque el código sigue siendo de un solo uso en la capa del challenge; la alternativa — no reintentar una entrega ambigua (INDETERMINATE) — cambia ese riesgo por uno peor: dejar a la persona sin ningún código que funcione cuando el envío sí llegó a destino.
Un rol dedicado, ninaku_worker, es el único que despacha (OB6). ninaku_runtime (la API) nunca recibe EXECUTE sobre las funciones de claim/record de ningún outbox — solo sobre la función de encolado, dentro de la misma transacción que ya escribe el cambio de negocio. ninaku_worker recibe exactamente EXECUTE sobre claim/record/purge y SELECT+DELETE sobre el ciphertext, nunca acceso a identity.password_credentials, totp_methods, recovery_codes ni a ninguna tabla de negocio. Un proceso de API comprometido que intentara despachar un mensaje se refuta con 42501 antes de tocar una fila, la misma garantía estructural que ya separa platform.provision_organization de provision_organization_for_caller.
Excepción de sign_up al supersede de reenvío (OB7, revisión 40): un mensaje sign_up nunca supersede a otro, porque confirmar un registro exige la propia contraseña del registrante y, a diferencia de add_sign_in_method/password_recovery/step_up — siempre pedidos por el propio dueño de la cuenta, o donde cualquier código sirve para ella —, superseder dejaría a un atacante que registra la dirección de una víctima bloqueando el código todavía no entregado de esa víctima, una denegación de servicio vía reenvío que los otros tres propósitos nunca sufren.
Un dead letter no se reproduce: se reemite (OX-O2, revisión 44). El ciphertext de un mensaje se borra al pasar a dead_lettered (OB3) y el challenge guarda solo un hash argon2 del código, así que el código original no se puede recuperar ni reenviar; el comando de staff con step-up genera un código nuevo para el mismo challenge todavía abierto, reemplaza de forma atómica el hash del challenge (el código viejo deja de servir) y encola un mensaje nuevo con ese código sellado, rechazando los dead letters superseded_by_resend o challenge_expired, los challenges ya cerrados y los destinos que ya tienen un mensaje más nuevo vivo. La ruta vive en Platform, junto al resto de los comandos de staff, y el caso de uso completo llama al contrato público de Identity (SecurityOutboxOperationsContract), que es quien posee el generador de códigos, el hasher y el cifrador: es la forma mínima que cumple R1–R9 sin que Platform importe nada interno de Identity y sin duplicar esas piezas.
D27. Una invitación viaja por el outbox de seguridad de Identity (propuesta, J1)
Estado: propuesta, reversible. Delegada por el dueño del producto para el recorrido J1 "Traer a mi equipo" (ORGANIZATION_USE_CASES.md, decisiones J1 a).
Una invitación se entrega como un quinto propósito, invitation, de identity.security_outbox_messages, el outbox que el worker ya despacha (D26). El token de la invitación se sella con el mismo cifrador del outbox (security-outbox-otp-cipher.service.ts, AAD messageId:purpose), se envía por correo con SES o por WhatsApp con Wasender según el identifier_type de la invitación, y se borra en la transacción que marca el mensaje published, o cuando la invitación vence o se revoca. El token es un secreto al portador, justo el tipo de contenido para el que se construyó OB3.
Por qué no el outbox de tenant ahora. events.outbox_records no tiene código que lo escriba y el worker no lo reclama. Construirlo para un solo tipo de mensaje significa un segundo ciclo de reclamo, una segunda superficie de dead letters, RLS de tenant para ninaku_worker y un segundo lugar donde guardar un secreto; el outbox de tenant queda para eventos de negocio (OUTBOX_USE_CASES.md OX-E1 a OX-E3).
Qué necesita el esquema (cambio mínimo, una migración).
security_outbox_messages.challenge_idpasa a ser nullable y una nuevainvitation_id uuidreferenciaidentity.invitations(id); un check exige exactamente una de las dos, yinvitation_idexactamente cuandopurpose = 'invitation'. Un challenge no puede hacer de invitación:identity.authentication_challenges.identity_idesNOT NULLy un invitado puede no tener identidad.security_outbox_messages_purpose_chkadmite'invitation'.security_outbox_messages_one_pending_per_purpose_destination_uqy el supersede dentro deidentity.enqueue_security_outbox_messageexcluyen'invitation', como ya excluyen'sign_up': si no, la organización B que invita a una dirección mandaría a dead letter la invitación pendiente de la organización A a la misma dirección. Un reenvío retira a su predecesor porinvitation_id.identity.claim_security_outbox_messageshace hoy un inner join conidentity.authentication_challenges, así que una fila de invitación quedaría arrendada y nunca devuelta; debe tomar el vencimiento del challenge o de la invitación.identity.purge_expired_security_outbox_ciphertextsdebe hacer lo mismo, y además borrar el ciphertext de una invitación revocada.identity.open_security_outbox_reissue_as_staffrechaza un mensaje de invitación: la reemite el dueño (O33), staff no puede acuñar un token para un tenant.- Una nueva
SECURITY DEFINERidentity.enqueue_invitation_message(p_message_id, p_invitation_id, p_ciphertext, p_nonce, p_key_version)lee el destino de la fila de la invitación (la API no puede redirigir un mensaje) y aplica los límites de D29; una nuevaidentity.withdraw_invitation_message(p_invitation_id)manda a dead letter uno pendiente coninvitation_revoked. El claim devuelve el nombre de la organización para el texto del mensaje.
Revisión (revisión de arquitectura de J1-1, verificada contra la rama local feat/invitation-delivery-schema). El caso de uso de invitar no conoce el outbox: depende de un puerto de aplicación de Identity, InvitationDeliveryPort, con schedule(context, delivery) y withdraw(context, invitationId), donde context es el TransactionContext de src/foundation/database/transaction-context.ts de la misma transacción de tenant que inserta la invitación, así que la entrega sigue siendo atómica con el insert y con la revocación. El adaptador de hoy sella el token con el cifrador del outbox y llama a identity.enqueue_invitation_message / identity.withdraw_invitation_message; mañana puede ser un adaptador de Notifications sin tocar el caso de uso. Los límites de D29 viven en la función de PostgreSQL, no en el puerto: un adaptador futuro debe cargarlos (llamar a la misma función o reproducir sus reglas con sus pruebas) o deja a Ninaku escribiendo a terceros sin techo. La revisión encontró además, y se verificó en el código de la rama, que lo escrito arriba no se cumple todavía en cuatro puntos: el claim no devuelve el nombre de la organización (ni siquiera invitation_id); withdraw_invitation_message solo retira mensajes pending, y ni el claim ni identity.record_security_outbox_attempt miran el estado de la invitación, así que un mensaje ya arrendado de una invitación revocada o vencida todavía puede entregarse; el diferimiento entre organizaciones cuenta mensajes retirados o en dead letter y no tiene tope; y identity.list_security_outbox_dead_letters_as_staff sigue con un inner join a identity.authentication_challenges, así que staff no ve los dead letters de invitaciones que el backlog sí cuenta. Se corrigen en la tajada J1-1b, antes de J1-2 (ORGANIZATION_USE_CASES.md, plan de implementación). La migración 0054 (revisión 64) las corrige: el claim devuelve organization_name e invitation_id al final de sus columnas, no arrienda el mensaje de una invitación revocada, aceptada o vencida (lo manda a dead letter con el ciphertext borrado) y record_security_outbox_attempt no lo devuelve a pending; un mensaje ya entregado al proveedor no se puede retirar, y lo garantizado es que no hay un intento nuevo ni queda ciphertext.
D28. El secreto de la invitación y su aceptación (propuesta, J1)
Estado: propuesta, reversible (decisiones J1 b).
El token son 32 bytes aleatorios codificados en base64url. Solo se guarda sha256(token), en identity.invitations.token_hash (invitations_token_hash_chk ya exige 32 bytes o más; invitations_token_hash_uq lo vuelve una clave de búsqueda); un hash rápido alcanza porque el token tiene 256 bits de entropía, a diferencia de una contraseña o un código de seis dígitos. Ninguna respuesta, línea de log ni registro de auditoría lleva jamás el token, tampoco el del invitador: una sesión robada del invitador puede revocar o reemitir, pero nunca cosechar un enlace con el que alguien pueda unirse.
El enlace pone el token en el fragmento de la URL (/join#token=...) para que nunca llegue a un servidor ni a un log de proxy. La app lo envía en un cuerpo: POST /invitation-previews (sesión opcional, no escribe nada) y POST /invitation-acceptances (sesión obligatoria). Ninguna de las dos rutas recibe un id de invitación, así que los ids no se pueden sondear. Aceptar exige el token y una sesión cuya identidad tenga verificado el identificador invitado (identity_invitation_verified_recipient): un enlace reenviado, por sí solo, no une a nadie.
Errores: un token desconocido responde 404 · identity.invitation_not_found, idéntico para todo token desconocido; uno conocido pero vencido, revocado o ya aceptado responde 409 · identity.invitation_closed sin decir cuál (solo alcanza ese punto quien tiene el token); un token válido con la identidad equivocada responde 403 · identity.invitation_recipient_mismatch, que nunca dice si otra identidad es dueña del identificador. Ambas rutas usan ANSWERS_A_CHALLENGE_RATE_LIMIT.
Aceptar corre en una nueva función SECURITY DEFINER, identity.accept_invitation(bytea), porque el invitado no tiene contexto de tenant y toda política de las tablas de invitaciones, membresías, asignaciones de rol y alcances de acceso lo exige. Toma al llamador de app.identity_id, nunca de un parámetro, y escribe ella misma el registro de auditoría de tenant con los ajustes de la solicitud cambiados a la nueva membresía, con la misma forma que platform.provision_organization_for_caller y platform.record_organization_provisioned.
Rechazado: devolverle el enlace al invitador para que lo comparta a mano (la cosecha por sesión robada de arriba); aceptar solo con el token (cualquiera a quien se reenvíe el enlace se uniría).
D29. Límites de invitaciones, asientos, privilegio, divulgación de membresía y vencimiento (propuesta, J1)
Estado: propuesta, reversible (decisiones J1 c a g).
Límites contra abuso. Una organización puede hacer que Ninaku escriba a terceros arbitrarios, y el aprovisionamiento es autoservicio, así que los límites viven en PostgreSQL y no solo en el Throttler por IP. identity.enqueue_invitation_message (D27) es el único cuello de botella por el que pasa toda invitación saliente, y aplica, bajo advisory locks por organización y por identificador:
- invitaciones abiertas por organización ≤ el límite de plan
identity.pending_invitations(nueva fila deplatform.limit_definitions; 20 en Pionero, igual que sus asientos):409 · identity.invitation_pending_limit_reached. Es un límite de plan porque escala con el tamaño de equipo del plan; - como máximo 30 invitaciones nuevas por organización por cada 24 horas móviles, una constante en la función (un techo contra abuso, no un término comercial):
429 · identity.invitation_rate_limited; - como máximo un mensaje de invitación por identificador por organización por hora, entre invitar y reemitir:
429 · identity.invitation_rate_limitedconRetry-After; - como máximo 3 mensajes de invitación por identificador por cada 24 horas móviles entre todas las organizaciones; más allá, el mensaje se encola con un
available_atposterior en vez de rechazarse, para que un rechazo nunca revele que otra organización invitó a la misma persona. Necesita un índice nuevoidentity.invitations (identifier_type, normalized_value, created_at DESC).
El Throttler agrega un techo por IP: un nuevo INVITES_A_PERSON_RATE_LIMIT (20 cada 10 minutos) en invitar y reemitir, y ANSWERS_A_CHALLENGE_RATE_LIMIT en previsualizar y aceptar.
Asientos. Una invitación no reserva asiento (identity.assert_membership_seat_available ya lo dice). El dueño puede enviar más invitaciones que asientos libres; las aceptaciones por encima del límite se rechazan en el commit por el trigger diferido memberships_seat_limit_trg, con respuesta 409 · identity.seat_limit_reached, y la invitación sigue abierta para poder aceptarse cuando se libere un asiento. GET /memberships responde meta.seats = { used, limit } con un conteo y platform.effective_limit, ambos baratos, para que la app avise antes de enviar. Rechazado: un asiento por invitación abierta, que deja que invitaciones ociosas bloqueen contrataciones reales.
Privilegio. En J1 solo quien tiene organization.account.manage en toda la organización invita, revoca o reemite (identity.effective_permission(membership, code, NULL), la comprobación que ya usa todo comando de Organization). Un rol ofrecido debe estar activo, ser global o de esta organización, y no otorgar organization.account.manage, así que organization_owner nunca se puede ofrecer y una invitación nunca crea un administrador. Se aplica en el caso de uso y otra vez en SQL: identity.validate_invitation_role() (el trigger de identity.invitation_role_assignments) gana un rechazo para un rol que otorga organization.account.manage, y identity.accept_invitation vuelve a comprobar los roles que copia, porque los permisos de un rol pueden cambiar después de enviada la invitación. Los invitadores con alcance esperan a que exista un administrador con alcance; su regla (un alcance ofrecido debe estar cubierto por uno de los alcances administrativos del invitador) queda escrita en J1.
Ya es miembro. Invitar a un identificador verificado en una identidad con una membresía vigente (ended_at IS NULL) de esta organización responde 409 · identity.invitee_already_member: el invitador es un administrador autorizado y el dato concierne a su propia organización. Cualquier otro identificador, sea de un no miembro o de nadie, responde el mismo 201.
Vencimiento. Siete días por defecto, de 1 a 30 a pedido. Reemitir revoca la fila vieja (su token deja de servir en esa transacción) e inserta una nueva con un token nuevo y un vencimiento contado desde la reemisión, enlazada por una nueva columna replaces_invitation_id; token_hash y expires_at son inmutables por identity.protect_invitation_lifecycle(), así que extender una fila no es posible y mantendría vivo un enlace posiblemente filtrado.
Revisión (contención). La regla de privilegio de arriba es el primer paso de una regla general: un invitador puede ofrecer un rol con un alcance solo si (1) cada permiso del rol lo tiene él mismo en sus permisos efectivos, con un alcance que cubre el alcance ofrecido; (2) el alcance ofrecido está cubierto por uno de sus alcances administrativos; y (3) el rol no contiene ningún permiso administrativo no delegable. En J1 la comprobación de un único código (organization.account.manage) cumple (3), y (1) se cumple porque los roles ofrecibles no tienen permisos todavía (D30). Cuando existan más permisos administrativos, el código único se reemplaza por un atributo de identity.permissions que marque un permiso como administrativo (columna nueva, no existe hoy). Además, identity.enqueue_invitation_message debe comprobar en SQL que la membresía llamadora (identity.current_membership_id()) tiene organization.account.manage en toda la organización, porque identity.invitations.invited_by_membership_id es nullable y hoy la función solo exige contexto de tenant.
Revisión (diferimiento). El tope de 3 mensajes por identificador entre organizaciones cuenta solo los mensajes pending, leased o published de otras invitaciones, y el diferimiento nunca pasa de una hora antes del expires_at de la invitación: el tope cede ante la invitación en vez de matarla en silencio. Sin esto, una organización hostil que invita y revoca a la misma persona empuja las invitaciones de otra organización más allá de su vencimiento (verificado en la rama de J1-1: la consulta no filtra por estado ni acota el resultado). Rechazar en vez de diferir sigue descartado, porque revelaría que otra organización invitó a la misma persona.
D30. Roles del sistema por vertical, ofrecidos según el contexto (propuesta, J1)
Estado: propuesta, reversible. Decidida por el dueño del producto el 2026-10-02: quien invita elige un rol de trabajo concreto (mesero, cocina, cajero, gerente), y las dos primeras verticales en salir son Restaurante y Retail.
Tres clases de rol, sin jerarquía. Un rol de identity.roles es (1) neutral: lo define Ninaku, organization_id y vertical_code nulos, sirve en cualquier negocio; (2) de vertical: lo define Ninaku, organization_id nulo, vertical_code no nulo, solo tiene sentido donde esa vertical está activa; (3) propio de una organización ("Barista"): organization_id no nulo, lo crea el dueño en un recorrido posterior de administración de roles, no en J1. Ningún rol tiene rango ni hereda de otro: lo que un rol permite es exactamente la lista de sus permisos en identity.role_permissions, y "gerente puede más que cajero" se expresa con permisos, nunca con un orden entre roles.
Una columna nueva. identity.roles.vertical_code varchar(80) NULL, con llave foránea a platform.verticals(code) (constraint nueva roles_vertical_fk); NULL significa neutral. Un check nuevo exige que un rol propio de una organización no tenga vertical en esta versión (organization_id IS NULL OR vertical_code IS NULL), para que la regla de oferta de abajo no tenga un caso que nadie diseñó. Los índices únicos de código (roles_system_code_ci_uq, roles_organization_code_ci_uq) no cambian: un código de sistema es único entre todas las verticales.
Quién los define. Ninaku, por migración, nunca la API: ninaku_runtime solo tiene SELECT sobre identity.roles y identity.role_permissions, y la política roles_insert_policy exige organization_id del tenant. Hoy no existe ninguna fila en platform.verticals en una base creada con db:prepare (solo las pruebas las insertan), así que la misma tajada siembra primero las verticales restaurant ("Restaurant") y retail ("Retail"), ambas active.
Los siete roles sembrados (organization_id nulo, status = 'active'). El esquema tiene una sola columna name (varchar(120)) y ninguna tabla de traducción de roles, así que name va en inglés y la app muestra el nombre en español a partir de code, igual que traduce un error desde su code (D25); no se agrega una tabla identity.role_translations hasta que exista un rol propio con nombre escrito por el cliente que deba traducirse.
code | vertical_code | name | description | Nombre en la app (es) |
|---|---|---|---|---|
manager | — | Manager | Runs the daily operation of the places in its scope. Not an administrator: never holds organization.account.manage. | Gerente |
cashier | — | Cashier | Takes payments and closes sales at a point of sale. | Cajero |
waiter | restaurant | Waiter | Serves tables: opens service, takes orders and sends them to the kitchen and the bar. | Mesero |
kitchen | restaurant | Kitchen | Prepares the food orders sent to the kitchen. | Cocina |
bar | restaurant | Bar | Prepares the drink orders sent to the bar. | Bar |
sales_associate | retail | Sales associate | Attends customers on the sales floor and prepares their sales. | Asesor de ventas |
stock_keeper | retail | Stock keeper | Receives goods, counts stock and moves it between storage locations. | Bodeguero |
Nacen sin permisos, y es seguro. Los permisos nacen con el módulo que los aplica (ventas, cocina, inventario no existen todavía), así que los siete roles se siembran sin filas en identity.role_permissions. identity.effective_permission(membership, code, outlet) hace inner join de role_assignments con role_permissions y permissions, así que para una membresía cuyos únicos roles no tienen permisos devuelve false para todo código y todo alcance: el rol es una etiqueta que no concede nada. Cada módulo futuro agrega sus permisos a estos roles en su propia migración (INSERT ... ON CONFLICT DO NOTHING sobre identity.role_permissions), y en la misma migración se los agrega a organization_owner, porque la regla de contención (revisión de D29) exige que quien invita tenga cada permiso que ofrece: si el dueño no los tuviera, dejaría de poder invitar a un mesero el día que el mesero gane su primer permiso.
Revisión (revisión 178). La frase «ventas, cocina, inventario no existen todavía» ya no vale para ventas ni inventario: sales.orders.take, sales.orders.read, pricing.prices.view, pricing.prices.manage, settings.assignments.manage e inventory.stock.receive ya están asignados a roles de sistema en sus migraciones (por ejemplo cashier y waiter reciben sales.orders.take y sales.orders.read), y existe la API de roles y del catálogo de permisos (ACCESS_USE_CASES.md).
Revisión (K1 del catálogo, migración 0075). El catálogo es el primer módulo que da permisos a estos roles, tal como dice CATALOG_USE_CASES.md §7.2: manager recibe catalog.items.manage, catalog.items.view, catalog.assortment.manage y catalog.sellables.view; cashier y waiter, solo catalog.sellables.view; sales_associate, catalog.items.view y catalog.sellables.view; stock_keeper, catalog.items.view; kitchen y bar, ninguno; y organization_owner recibe los cuatro. Desde entonces el punto (1) de la regla de contención de D29 ya no se cumple por estar vacíos los roles: hoy solo se comprueba el permiso administrativo (3), así que un administrador cuyo rol propio tiene organization.account.manage y ningún permiso del catálogo puede ofrecer manager. El dueño tiene los cuatro, así que su camino no cambia; comprobar (1) queda pendiente para Identity.
Regla de oferta. Una invitación (y, más adelante, O26) puede ofrecer un rol con un alcance solo si el rol está active, es de sistema o de esta organización, no es administrativo (D29), y además es neutral o su vertical está activa (platform.business_unit_verticals.status = 'active') en al menos una de las unidades de negocio que cubre el alcance. Las unidades cubiertas son: toda la organización → sus unidades de negocio activas; una unidad de negocio → esa; una sucursal (outlet) → su unidad de negocio efectiva hoy (organization.effective_business_unit(org, outlet, current_date)) y, con include_descendants, también las de sus descendientes; una marca, un sitio o una persona jurídica → las unidades efectivas hoy de sus sucursales. Un alcance que no cubre ninguna unidad de negocio solo puede recibir roles neutrales. Se aplica en el caso de uso y otra vez en SQL, en un trigger nuevo sobre identity.invitation_access_scopes y dentro de identity.accept_invitation, porque una vertical puede desactivarse después de enviada la invitación. Rechazo: 422 · identity.invitation_role_vertical_inactive (código nuevo).
Un rol de una vertical que la organización no usa existe en el catálogo global y la organización lo lee (la política roles_select_policy deja leer todo rol de sistema), pero nunca se le ofrece ni se le puede asignar con un alcance donde esa vertical no está activa. Desactivar una vertical (O11) no borra asignaciones ya hechas ni invitaciones abiertas: la asignación sigue siendo una etiqueta, el módulo de la vertical exige la vertical activa en cada comando (platform.assert_operation_allowed ya recibe p_vertical_code), y una invitación abierta se rechaza al aceptarla.
Retirar un rol, nunca borrarlo. Un rol sembrado no se borra jamás (role_assignments y invitation_role_assignments lo referencian y el historial lo necesita). Se retira con status: inactive (reversible) o archived (final), siempre por migración. Un rol no active no se ofrece (identity.validate_role_assignment ya lo rechaza, 422 · identity.invitation_refused) y, ojo, deja de conceder sus permisos a quien ya lo tiene, porque effective_permission exige r.status = 'active'; retirar un rol con titulares exige mover antes a esas personas a otro rol.
Rechazado:
- Una lista global de roles sin vertical: el dueño de una tienda vería "Mesero" y "Cocina" en su formulario, y nada impediría ofrecerlos donde no significan nada.
- Copias por organización creadas al activar una vertical: N copias de cada rol que cada migración de permisos tendría que alcanzar, y la desactivación tendría que decidir qué hacer con ellas.
- Jerarquía o rango entre roles: duplica lo que ya dicen los permisos y vuelve opaca la contención ("rango mayor" no dice qué permisos se delegan).
D31. Las tareas pesadas de un módulo usan una cola propia del módulo con organization_id
Estado: vigente (OD7, ASSETS_USE_CASES.md §4.2 SG7; registrada en la etapa A1a-1, migración 0083).
Un módulo cuyo trabajo pesado (procesar una imagen, generar sus renditions, purgar sus objetos) no es un evento de integración guarda ese trabajo en una tabla de cola propia, dentro de su propio esquema, con organization_id NOT NULL y la misma forma que events.outbox_records: estado (pending, leased, completed, dead_lettered), lease (lease_owner, lease_token, lease_expires_at) con su check de forma, attempt_count acotado, available_at para el backoff y dead letter al agotar los reintentos. La fila se encola en la misma transacción que el cambio de negocio, y solo ninaku_worker la reclama y registra su resultado, siempre a través de funciones SECURITY DEFINER del módulo (FOR UPDATE SKIP LOCKED más lease, como D26); ninaku_runtime nunca reclama ni despacha.
events.* queda para los eventos de integración entre módulos: un trabajo interno de un módulo no es un hecho que otros módulos consuman, y meterlo en events.outbox_records mezclaría sus reintentos, su retención y sus permisos con los de la integración. El primer usuario es assets.processing_jobs (SG7).
Rechazado: reusar events.outbox_records para el trabajo interno de un módulo (la razón de arriba), y BullMQ/Redis como fuente de verdad de la cola (D26).
D32. Un punto de venta solo puede ocultar artículos del surtido de su unidad de negocio
Estado: vigente (decidida por el dueño, CATALOG_OPTIONS_V2.md OV24 y "K16 as built"; registrada en la rebanada K16, migración 0106).
El catálogo es abstracto y se administra por unidad de negocio o por punto de venta, sin banderas por canal. La unidad de negocio sigue siendo la unidad del surtido (business_unit_catalogs, business_unit_items) y varios puntos de venta pueden compartirla. Para decir "este artículo no se vende en este punto de venta" existe catalog.outlet_hidden_items, una capa de excepciones que solo ocultan: lo que vende un punto de venta es el surtido de la unidad que lo opera hoy menos los artículos que oculta, nunca algo que la unidad no lista. Una fila por punto de venta y artículo; ocultar un artículo oculta todas sus variantes; las filas sobreviven si el punto de venta cambia de unidad y se aplican al surtido de la nueva. Las cartas siguen siendo presentación y nunca limitan lo que se vende.
La regla vive en un solo fragmento SQL (hiddenAtOutlet, una sonda por clave (organization_id, outlet_id, item_id) por artículo candidato) que comparten la lectura del punto de venta, la búsqueda, el escaneo, resolve y admit de CatalogSellableContract (con outletId opcional: si el punto de venta no existe, es de otra organización o no lo opera la unidad dada, se rechaza con outlet_not_operated_by_unit en la misma sentencia, y sin él se juzga la unidad sola) y la disponibilidad de los componentes de un combo; catalog.variant_is_listed_at_outlet es su par en SQL y no cambia ninguna firma existente.
Rechazado: un surtido propio por punto de venta (dos fuentes de verdad del surtido y un punto de venta que vende lo que su unidad no lista), y una bandera por canal en el catálogo (OV18: el canal no es un hecho del catálogo).
D33. Las franjas horarias de una carta viven en la asignación al punto de venta y las evalúa el servidor en la zona horaria del sitio
Estado: vigente (decidida por el dueño, CATALOG_OPTIONS_V2.md "S1 as built" y CATALOG_USE_CASES.md C31; registrada en la rebanada S1, migración 0107).
Un negocio muestra cartas distintas a horas distintas en un punto de venta ("Desayuno" hasta las 11:00, "Almuerzo" ciertos días). Las cartas solo organizan la pantalla de la caja y nunca limitan lo que se vende: admit las ignora. La franja pertenece a la asignación de la carta al punto de venta (catalog.outlet_menus), no a la carta: la carta sigue siendo reutilizable en toda la organización y la misma carta puede abrir de 06:00 a 11:00 en un punto de venta y de 07:00 a 12:00 en otro. Una carta asignada sin franja se muestra siempre. Una franja son días de la semana ISO (1 a 7, todos si se omiten) y una hora de inicio (inclusive) y de fin (exclusiva) en hora local del sitio del punto de venta; una franja que termina antes de lo que empieza cruza la medianoche y pertenece al día en que empieza. Hasta 14 franjas por carta (dos servicios por cada uno de los siete días) y las que se solapan en una misma carta se rechazan (422 catalog.menu_windows_overlap), no se fusionan: dos franjas que comparten un minuto casi siempre son un error de captura y fusionarlas lo ocultaría. Se guardan en catalog.outlet_menu_windows y catalog.outlet_menu_window_weekdays (dos tablas porque una carta necesita varias franjas y cada franja un conjunto repetido de días, y no caben como columnas de outlet_menus).
El servidor evalúa, en SQL, en el momento de la lectura y con la zona horaria del sitio (organization.outlet_operating_context publica ahora site_timezone, así Catalog no lee tablas de Organization). El instante lo da un Clock de Foundation que el caso de uso lee una vez y pasa como parámetro a las dos sentencias de la lectura de la caja, así que las pruebas lo inyectan. La comparación es de reloj de pared: un cambio de horario de verano mueve la franja con el reloj. La etiqueta de la caja se deriva del conjunto de cartas abiertas (una máscara de bits sobre sus posiciones, exacta, no un hash) y del próximo instante en que cambia (menusValidUntil, que viaja también en el cuerpo), de modo que cambia sin ninguna escritura cuando el reloj abre o cierra una franja y nunca contesta 304 a un conjunto viejo. Quedan fuera de S1 los feriados y los rangos de fechas.
Rechazado: una columna de horario en catalog.menus (la carta es de toda la organización y cada punto de venta tiene su horario), que el dispositivo evalúe las franjas (dos relojes y dos zonas horarias que pueden discrepar, y un 304 sin forma de saber que el conjunto cambió), un hash corto del conjunto en la etiqueta (una colisión contestaría 304 a un conjunto viejo; la máscara no colisiona), una ruta hermana /menu-windows (dos escrituras para un mismo caso de uso, con dos If-Match y dos registros de auditoría) y fusionar las franjas solapadas.
D34. Las variantes se definen por dimensiones estructuradas del catálogo y una combinación de valores no se repite entre variantes activas
Estado: vigente (decidida por el arquitecto de la rebanada K13, CATALOG_OPTIONS_V2.md sección 8 y "K13 as built"; registrada en la rebanada K13a, migración 0109).
La matriz de variantes escribía códigos y nombres concatenados (m-azul, M / Azul): no había forma de pedir "todas las variantes azules" ni de filtrar por una dimensión. Las dimensiones son datos del catálogo, no del artículo, así "Azul" es el mismo valor en una camisa y en un pantalón. Cada tabla responde las siete preguntas de API_AND_SCHEMA_DISCIPLINE.md, y en las cuatro el dueño es Catalog, el lector es la lectura de artículos, el listado de dimensiones y el filtro del listado de artículos, y el escritor es la matriz de variantes (POST /catalog/items/{itemId}/variant-matrix):
variant_dimensions: una dimensión del catálogo (Talla, Color), concodeúnico por catálogo sin distinguir mayúsculas; no cabe enitemsporque la comparten todos los artículos y el filtro cruza artículos. Se crea la primera vez que una matriz la nombra y se archiva, nunca se borra.variant_dimension_values: un valor (M, Azul) con id estable,codeúnico por dimensión; no cabe como texto de la variante porque un cambio de nombre no puede cambiar su identidad ni sus traducciones futuras. Se retira, nunca se borra.item_variant_dimensions: cuáles dimensiones, y en qué orden, definen las variantes de un artículo; como máximo tres (sort_order0 a 2 único por artículo, de modo que la base de datos rechaza una cuarta sin necesitar un disparador). Se fija con la primera matriz del artículo y no cambia.item_variant_dimension_values: el valor que una variante tiene en cada dimensión del artículo (una fila por variante y dimensión; llaves compuestas hacen que la dimensión sea una del artículo y la variante sea de ese artículo). No cabe enitem_variantsporque son hasta tres hechos con identidad propia.
Invariante: dos variantes activas de un artículo no repiten la misma combinación de valores. Lo impone la base de datos con disparadores de restricción diferidos (al insertar vínculos y al pasar una variante a active), serializados por artículo con FOR NO KEY UPDATE sobre su fila; las variantes sin vínculos (la variante por defecto y las anteriores) se toleran. Que una variante vinculada tenga un valor por cada dimensión del artículo lo comprueba la aplicación, no el disparador. Las variantes existentes ganan sus valores cuando el dueño vuelve a aplicar la matriz: sus códigos son opacos y no se analizan.
Rechazado: columnas shirt_size o shoe_color por vertical (el modelo no se amplía por rubro), atributos descriptivos como material o corte (no definen la variante; esperan un lector con nombre), analizar los códigos concatenados para rellenar los valores (adivinar identidad) y un disparador de conteo para el máximo de tres (la restricción de posición lo cubre).
D35. El límite de cada opción por oferta vive en su propia tabla
Estado: vigente (rebanada K14a, migración 0108; faltaba su justificación).
catalog.item_modifier_group_option_overrides guarda, por oferta de un grupo de modificadores en un artículo y por opción, el máximo de unidades que esa oferta permite (0 a 999; 0 significa que la opción no se ofrece en esa oferta). El dueño es Catalog; la escribe el caso de uso que fija las ofertas de un artículo (K14b) y la leen la lectura del artículo y la caja. El invariante es una fila por oferta y opción, con la opción del mismo grupo que la oferta. No cabe en la oferta ni en la opción porque una oferta necesita un límite por cada opción y una opción tiene un límite distinto por cada oferta. Las filas se reemplazan con borrar e insertar junto con los valores por defecto de la oferta, y se borran en cascada con ella.
D36. Una opción de texto y sus indicaciones de presentación son columnas de la opción
Estado: vigente (rebanada K14c, migración 0110; CATALOG_OPTIONS_V2.md OV13, OV14 y "K14c as built").
Un grabado o un mensaje de pastel es una opción cuyo valor escribe el cliente. Se agrega el tipo text a catalog.modifier_options junto con cuatro columnas que son indicaciones: text_max_length (1 a 500, solo para text), prefix (add, extra, light, no, on_the_side, substitute), prints_on_receipt e prints_on_kitchen_ticket. No se crea ninguna tabla: cada dato es un atributo de una sola opción, lo escribe el mismo caso de uso que fija las opciones de un grupo (PUT /catalog/modifier-groups/{modifierGroupId}) y lo leen las mismas lecturas que ya leen la opción. Un prefijo no cambia ninguna venta: Producción decide el efecto (add, remove, replace, scale) y Catalog solo evita las combinaciones que Producción rechazaría al vender, con restricciones CHECK (light, no, on_the_side y substitute piden cantidad máxima 1; no, on_the_side y substitute solo van en opciones instruction; una opción text tiene cantidad exactamente 1 y ningún prefijo o add). Que extra como efecto scale pida cantidad 1 (X11) no se puede imponer aquí: el efecto es de Producción (OV18) y ella lo rechaza al vender.
Catalog no guarda el texto que escribe un cliente: lo guardará Ventas (X3, X10), que debe agregar la rama text a su comprobación de tipos antes de consumir opciones de texto. Las ofertas guardadas no se vuelven a juzgar al escribir una opción (K5).
Rechazado: una tabla de presentación por opción (un dato por opción no necesita identidad propia), un tipo de grupo input en lugar de un tipo de opción (un grupo mezcla opciones de texto y de elección), guardar el prefijo como un efecto de venta (acoplaría Catalog a Producción) y banderas por canal para la impresión (OV18, OV24: solo dos indicaciones, sin canal).
D37. Las marcas regulatorias de un artículo viven en su propia tabla y el catálogo no hace cumplir ninguna
Estado: vigente (rebanada K15a, migración 0111; CATALOG_OPTIONS_V2.md sección 17 y "K15a as built").
catalog.item_regulatory_flags (item_id, flag) declara qué es el producto para una farmacia, una licorería o una ferretería: age_restricted_alcohol, age_restricted_tobacco, prescription_only, pharmacy_only o hazardous_goods. El dueño es Catalog; la escribe el caso de uso que actualiza el artículo (PATCH /catalog/items/{itemId} con regulatoryFlags, y el alta del artículo) y la leen la lectura del artículo y, más adelante, Ventas o un módulo de cumplimiento para aplicar su propia regla. El invariante es una fila por artículo y marca, con las marcas del vocabulario cerrado de la restricción. Su ciclo de vida es reemplazar el conjunto completo (borrar e insertar, por eso el rol de la API recibe SELECT, INSERT, DELETE y nunca UPDATE) y borrarse con el reemplazo. No cabe en items porque un artículo tiene varias marcas, ni como arreglo de texto porque el vocabulario cerrado y la llave compuesta del artículo (organización y catálogo) los impone la base de datos. Catalog declara y no hace cumplir: no bloquea ventas, no pide edad ni receta; la regla pertenece a quien la aplica y lee la marca a través de sus contratos (OV18).
La misma migración acota las descripciones de artículos, categorías y grupos de modificadores a 2000 caracteres (el límite que la API ya imponía, pero la API no es el único escritor posible de una base con datos: importaciones y cargas por SQL no están probadas), exige que el mínimo y el máximo de venta de una variante sean múltiplos de su paso (la API aceptaba cualquier política que cumpliera item_variants_sales_quantity_policy_chk, así que un mínimo de 0,1 con paso 0,25 pudo guardarse) y agrega el contenido neto de la etiqueta a la variante (net_content_quantity y net_content_unit_code, los dos o ninguno). La unidad del contenido neto se valida en la aplicación contra reference.units_of_measure y no tiene llave foránea (OV18: ninguna llave nueva hacia otro módulo). El precio por unidad lo calcula Pricing. Las cuatro restricciones se crean NOT VALID y un bloque DO las valida solo si una consulta de auditoría no encuentra filas que las rompan; si las encuentra, la migración no revierte el despliegue: deja la restricción sin validar, emite un WARNING con la cuenta de filas y no toca ningún dato. Toda escritura nueva se comprueba igual; una fila vieja que la rompe solo puede cambiarse dejándola válida (corregirla es una decisión del dueño de los datos, nunca de la migración). Una instalación limpia no tiene filas, así que las valida y el canónico declara las restricciones válidas.
Rechazado: una columna de arreglo de marcas en items, hacer cumplir la edad o la receta dentro de Catalog, una llave foránea de la unidad del contenido neto, y quitar catalog_items_organization_status_idx sin una prueba de que ningún plan la usa.
D38. La marca del producto es del catálogo y no es la marca de la organización
Estado: vigente (rebanada K15c, migración 0112; CATALOG_OPTIONS_V2.md sección 17.1 y "K15c as built").
organization.brands (0020_organization.sql) es la marca comercial con la que opera la organización (su nombre de cara al cliente). Un artículo del catálogo necesita otra cosa: la marca del fabricante del producto que vende (Coca-Cola, Bosch, Nike), para buscar y filtrar. Son hechos distintos con dueños distintos, y mezclarlos obligaría a una llave foránea de Catalog hacia el esquema de Organization (OV18, D18). catalog.product_brands (id, organization_id, catalog_id, name, status) responde las siete preguntas así: el dueño es Catalog; el hecho es «esta marca de fabricante existe en este catálogo»; la escriben el alta, el cambio de nombre y el archivo de una marca (POST /catalog/product-brands, PATCH y POST .../transitions); la leen la lista de marcas, la lectura del artículo (productBrand: { id, name }) y el filtro productBrandId de la lista de artículos; el invariante es un nombre por catálogo sin distinguir mayúsculas, archivadas incluidas, y que la marca de un artículo sea del mismo catálogo y organización (llave foránea compuesta items_product_brand_fk, que no se aplica cuando el artículo no tiene marca); el ciclo de vida es active o archived y nunca se borra (el rol de la API no recibe DELETE); y no cabe en items porque muchos artículos comparten una marca y el nombre se renombra en un solo lugar.
Archivar una marca que artículos activos usan está permitido y el artículo la conserva: archivar significa «no la ofrezcas para artículos nuevos», no «sácala de los existentes». El artículo sigue mostrando productBrand y se puede filtrar por ella; para quitarla se edita el artículo con productBrandId: null. Un artículo no puede recibir una marca archivada (422 catalog.product_brand_archived). El catálogo admite como máximo 1000 marcas, archivadas incluidas, para que la lista las devuelva todas.
Rechazado: reutilizar organization.brands (acopla Catalog con Organization y confunde dos hechos), guardar la marca como texto libre del artículo (sin catálogo de nombres no hay filtro fiable), una tabla puente artículo-marca (un artículo tiene a lo sumo una marca) y un nombre único solo entre las activas (un renombrado o una restauración podrían chocar sin que nadie lo vea).
D39. Los identificadores del fabricante son filas de la variante, no códigos de canal
Estado: vigente (rebanada K15d, migración 0113; CATALOG_OPTIONS_V2.md sección 17 y "K15d as built").
Una variante puede llevar identificadores propios del producto: el número de parte del fabricante (mpn), el isbn de un libro y el código del fabricante, en catalog.item_variant_identifiers (item_variant_id, scheme, value). Hay a lo sumo un valor por esquema por variante (llave primaria (item_variant_id, scheme)), el valor tiene de 1 a 100 caracteres y no es blanco (el NUL no cabe en un varchar de PostgreSQL y la API lo rechaza antes), y no es único entre variantes: el documento de diseño no lo pide, dos proveedores pueden compartir un MPN y una unicidad inventada rechazaría catálogos legítimos. Los códigos de barras siguen siendo de barcodes y los identificadores de canal (marketplaces, GTIN de un tercero) quedan fuera: pertenecen a la integración que los usa.
Se escriben dentro de la escritura de variante que ya existe (identifiers, una lista opcional que reemplaza el conjunto) y la lectura del artículo los muestra solo cuando la variante tiene alguno, de modo que ninguna respuesta existente cambia.
Rechazado: una columna por esquema en item_variants (cada esquema nuevo sería una migración de la tabla caliente), unicidad global del valor, y mezclar estos identificadores con los códigos de barras.
D40. El catálogo publica sus cambios como eventos tipados, escritos por disparadores en la transacción del cambio
Estado: vigente (rebanada K12a, migración 0114; CATALOG_OPTIONS_V2.md sección 7 y "K12a as built").
Un dispositivo sin conexión necesita saber qué cambió después de la versión del catálogo que ya tiene, sin volver a leerlo todo, y un retiro tiene que llegarle como un hecho que pueda aplicar (una lápida), no como una ausencia. Cada sentencia que mueve catalog.catalog_versions escribe además, en la misma transacción y bajo el mismo bloqueo de la fila de versión, un evento por agregado que cambió: catalog.item, variant, barcode, offer, modifier, bundle, menu, category y listing .changed, versión de contrato 1. La carga es mínima y estable: schemaVersion, catalogVersion (la versión de la organización después de esa sentencia), change (upserted, retired o removed), el id del agregado, el status cuando el evento sale de la fila del propio agregado y, en un retiro o una eliminación, retiredAt (la lápida). Nunca lleva nombres, precios, códigos de barras ni secretos: el dispositivo relee por id. El contrato ejecutable es src/modules/catalog/contracts/catalog-change-event.ts.
Por qué disparadores y no código de aplicación. El invariante es «toda sentencia que mueve la versión deja un evento». Los disparadores de versión de 31 tablas ya viven en la base y los activan todos los comandos, también los que se agreguen; repetir la escritura del evento en 126 archivos de infraestructura haría que una escritura nueva olvidada dejara de anunciarse sin que ninguna prueba fallara. Los nuevos disparadores corren después de los de versión (el nombre _change_feed_ ordena después de _catalog_version_, y un contrato lo verifica), leen la versión que la sentencia acaba de producir y escriben con events.append_tenant_event, la función que Events publica: SECURITY DEFINER, exige contexto de tenant, exige que el tipo de evento pertenezca al módulo productor y tenga una versión de contrato publicada, y crea el evento, su publicación y su fila de outbox. El propio disparador (catalog.record_change_feed) es SECURITY DEFINER con search_path fijado, de modo que quien escribe una tabla del catálogo no necesita ningún privilegio sobre events: el rol de la API no recibe USAGE sobre el esquema ni EXECUTE sobre la función, no puede reescribir, borrar ni forjar un evento, y ningún rol de prueba ni futuro que escriba el catálogo necesita una concesión nueva. Catalog no escribe tablas de otro módulo (OV18, D18).
Orden de bloqueos. Todo comando del catálogo toma primero la fila de versión; el evento toma después el contador de publicaciones de la organización. Un productor de eventos de otro módulo que tome el contador antes que la fila de versión del catálogo (por ejemplo Sales emitiendo un evento antes de llamar a admit) puede entrar en deadlock con un comando del catálogo: ese productor debe emitir sus eventos después de admit.
Fuera de un contexto de tenant. Una escritura privilegiada sin contexto de tenant (una migración, una herramienta administrativa) mueve la versión y no escribe eventos: Events exige el tenant, y exigirlo en el disparador rompería las migraciones de datos. Un dispositivo cuya versión local queda detrás de una versión sin evento debe pedir un arranque nuevo (K12b); una migración que cambie datos del catálogo lo declara.
Qué queda fuera. product_brands, variant_dimensions y variant_dimension_values mueven la versión y no escriben eventos: ninguna lectura del punto de venta los usa todavía (K12b decide si el arranque los lleva, y entonces se mapean). Las tablas de traducciones, alérgenos, etiquetas dietéticas y nutrición no tienen disparadores de versión porque ningún caso de uso las lee ni las escribe; los agrega la primera rebanada que las use (C23, C24). Un contrato falla si aparece una tabla del catálogo con disparador de versión que no escribe eventos ni está en la lista de exclusiones, o una tabla sin disparador de versión fuera de la lista de pendientes.
Dentro de la función. events.append_tenant_event aplaza (SET CONSTRAINTS ... DEFERRED) las tres comprobaciones de completitud del evento y la llave del contador: son diferibles pero una transacción que ya pidió SET CONSTRAINTS ALL IMMEDIATE las evaluaría entre la inserción del evento y la de su publicación y su outbox, y fallaría. Los disparadores diferidos del catálogo (la asignación de la primera unidad de negocio) escriben sus eventos al confirmar.
Rechazado: escribir los eventos desde los casos de uso o los repositorios (arriba), un evento por comando con la lista de cambios (el comando no conoce lo que tocan las cascadas y la cobertura por versión deja de ser exacta), una tabla propia catalog.change_log (duplicaría Events, su outbox y su orden de publicación), dar INSERT sobre events.domain_events o EXECUTE sobre la función al rol de la API (permitiría forjar eventos de cualquier módulo) y llevar nombres o precios en la carga (duplicaría hechos que ya tienen dueño y filtraría datos a un evento que se reenvía).
D41. El arranque de un dispositivo es un corte fijado a una versión, no una instantánea larga
Estado: vigente (rebanada K12b, sin migración; CATALOG_OPTIONS_V2.md sección 7 y "K12b as built").
Un dispositivo que trabaja sin conexión descarga lo que vende un outlet en muchas páginas y después aplica los eventos de D40. Para que la composición sea exacta, la descarga tiene que ser un corte del catálogo: el estado en una versión V, con todos los eventos de versión menor o igual a V ya dentro y ninguno de versión mayor. GET /catalog/outlets/{outletId}/bootstrap responde el corte (la versión del catálogo, la versión de la estructura y la unidad de negocio que opera el outlet, como un valor opaco cut) y los datos de referencia en una sola instantánea REPEATABLE READ de solo lectura, con el mismo permiso y el mismo modelo del punto de venta (catalog.sellables.view en el outlet). GET /catalog/outlets/{outletId}/bootstrap/items?cut=... entrega las páginas de artículos, sin tope de cantidad, con cursor por llaves; cada página se lee en su propia instantánea, compara primero el corte actual con el pedido y responde 409 catalog.bootstrap_cut_moved sin leer nada si cambió. Si todas las páginas de una descarga vieron el mismo corte, ninguna escritura del catálogo ni de la estructura se confirmó entre la primera y la última lectura, así que el resultado es exactamente el catálogo en V.
Por qué no una instantánea de toda la descarga. Una instantánea de PostgreSQL vive dentro de una transacción de una conexión; no puede cruzar peticiones HTTP, y mantener una transacción abierta (o una instantánea exportada) durante toda la descarga de un dispositivo retendría una conexión del pool y la limpieza de versiones de fila por minutos, por dispositivo. La alternativa de una sola respuesta no tiene tope. Por qué no «reiniciar solo las páginas que un delta tocó». Exigiría servir una página tal como estaba en V después de una escritura posterior, y el catálogo actualiza las filas en su lugar y no guarda versiones anteriores. El costo aceptado: si el catálogo cambia durante la descarga, el dispositivo la reinicia desde la apertura. Una página de 100 artículos (el máximo del contrato HTTP) cuesta unos milisegundos (PERFORMANCE_BASELINE.md sección 23), así que 3.000 artículos son 30 páginas y una ventana de pocos segundos; un reinicio solo es probable si el catálogo se edita más de una vez por descarga.
El empalme con el feed. El dispositivo aplica los eventos catalog.*.changed de la organización cuyo catalogVersion es mayor que el del corte, en el orden de publicación, y descarta los de versión menor o igual (ya están en los datos). No detecta huecos por aritmética de versiones: la versión también se mueve por tablas que no escriben eventos (product_brands, variant_dimensions, variant_dimension_values, D40) y el feed solo anuncia lo que un dispositivo lee. Una lápida (retired o removed) borra lo que su id nombra y todo lo que cuelga de ahí; un upserted obliga a releer ese agregado. El servidor de eventos y la lectura por id de un agregado son del módulo Sync, que no existe: Catalog expone el corte y las páginas y documenta lo que Sync debe agregar (un cursor de eventos «después de la versión V» filtrado a catalog.*, y la relectura por id).
Qué lleva y qué no. Los artículos que el outlet vende (la regla del punto de venta, OV24: la unidad de negocio decide el surtido y el outlet solo oculta), cada variante con su sku y sus códigos de barras activos (de ahí el dispositivo arma su índice local código → variante), las ofertas de modificadores y combos del artículo, las imágenes por referencia, el árbol de categorías y las definiciones de los grupos de modificadores. No lleva marcas de producto ni dimensiones de variante: ninguna pantalla del punto de venta las muestra, la lectura en línea del punto de venta tampoco, y como sus cambios no escriben eventos (D40) un arranque que las incluyera dejaría a los dispositivos desactualizados sin que nada se lo dijera; si una pantalla las necesita, la misma rebanada que las agregue al arranque mapea sus tablas a eventos. Tampoco lleva las cartas ni sus ventanas horarias: organizan la pantalla, dependen del reloj y siguen leyéndose en línea.
Permisos. Cada llamada vuelve a decidir catalog.sellables.view en el outlet antes de mirar nada: un permiso revocado o un alcance movido detiene la página siguiente (403, la misma negativa llana que las demás lecturas), y un outlet de otra organización o de otra unidad no se puede arrancar con el corte de otro. Lo que el dispositivo ya descargó no se borra por una revocación: invalidar el alcance local es de Sync (siguiente sesión) y de K12c.
Rechazado: un token firmado que lleve el corte dentro del cursor (el corte vencido se distingue mejor con un 409 propio que con el 400 de un cursor inválido), una instantánea exportada con pg_export_snapshot, versionar las filas del catálogo para servir cortes pasados, incluir las cartas con una fecha de validez, y poner la posición de publicación de Events en la respuesta (Catalog no la posee, y catalogVersion ya ordena el feed del catálogo sin Sync).
D42. Los rótulos de un combo son una proyección del catálogo, mantenida por disparadores, no una consulta recursiva en cada lectura
Estado: vigente (migración 0119, revisión 146).
Los alérgenos de un combo son la unión de los de sus componentes posibles (contains gana a may_contain) y una etiqueta dietética solo la lleva si la tiene todo componente posible, también a través de combos anidados hasta la profundidad 8. Calcularlo en cada lectura exigía una recursión sobre bundle_groups y bundle_group_items por cada combo de la página: el punto de venta pasó de 33,0 a 41,4 ms en catalog-till-sellables-combos y la búsqueda de combos superó el presupuesto de 15 ms.
Elegido: la tabla catalog.bundle_food_label_projection (organización, combo, tipo, rótulo, presencia), escrita por la función catalog.refresh_bundle_food_labels(organización, artículos) que llaman cinco disparadores de sentencia (asignaciones de alérgenos y de etiquetas, grupos, opciones y estado del artículo). La función sube por los combos que contienen los artículos cambiados (profundidad 8), borra sus filas y las vuelve a calcular con la misma semántica de antes (opción retirada y artículo archivado no cuentan, opción o grupo desactivado sí). Corre en la misma transacción y bajo el mismo bloqueo de la fila de versión del catálogo que el cambio que la provoca, así que ninguna escritura del catálogo (casos de uso, importaciones, clones, SQL de un operador) deja la proyección atrás, y ninguna lectura la recalcula: el punto de venta y las lecturas del artículo la unen por llave primaria.
Medido, por qué no una función SQL (a). Con 5, 20 y 49 combos el enunciado recursivo cuesta 1,2, 2,8 y 6,0 ms de ejecución y 0,8 ms de planificación. Una función LANGUAGE sql o plpgsql solo ahorraría la planificación: la ejecución, que es lo que crece con la página, queda igual. Rechazada.
Rechazado: una caché por versión de catálogo (esconde el costo y se pierde en un proceso nuevo, justo donde la latencia importa), recalcular al leer con un índice más (la recursión no es de índice), y escribir la proyección desde los casos de uso (una importación, un clon o un SQL de operador la dejarían atrás).
Qué no cambia. La proyección es derivada: el clon no la copia (los disparadores la rehacen al insertar las filas copiadas) y no mueve la versión del catálogo ni escribe eventos (el cambio que la provoca ya lo hizo). El rol de la aplicación puede leerla, insertarla y borrarla bajo la política de inquilino.
D43. El perfil nutricional es una versión publicada por destino y base, no una fila que se edita
Estado: vigente (migración 0119, revisión 147).
Un perfil de nutrición describe un artículo entero o una variante, sobre una base (serving, per_100g o per_100ml). Cada cambio de hechos publica una versión nueva: la anterior queda archivada, nunca se edita ni se borra, y la versión nueva es el máximo de las del destino más uno (no el conteo, así un historial con huecos no repite números). Una publicación idéntica a la vigente (mismos hechos en cualquier orden, redondeados a seis decimales) no escribe, no audita y no mueve la versión del catálogo (already_in_effect); retirar lo que no está publicado también. Cada destino y base guardan como máximo 100 versiones (catalog.nutrition_versions_full, 422) y cada perfil 40 hechos (400 en el esquema); los nutrientes salen de reference.nutrients y uno desconocido se rechaza antes de escribir (catalog.nutrient_unknown).
Rutas. PUT y DELETE /catalog/items/{itemId}/nutrition (con If-Match), GET /catalog/items/{itemId}/nutrition y GET .../nutrition/versions con cursor de keyset. La lectura del artículo trae solo un resumen (nutrition: base, versión y cantidad de hechos), nunca los hechos.
Elegido: índice simple por item_id (item_nutrition_profiles_item_idx). La búsqueda por artículo filtra con lower(status) = 'published' para no tomar el índice GiST parcial de exclusión, que no sirve a una búsqueda por clave.
Qué no hace. La importación no lleva nutrición: los perfiles son versionados y fechados, y un documento de importación no tiene dónde decir la versión ni la base sin duplicar estas rutas. El clon sí los copia (migración 0125).
D50. Los atributos tipados los define el negocio como datos de la organización y el valor sigue al artículo
Un negocio describe sus artículos sin columnas nuevas: una laptop tiene procesador (lista), pulgadas (número), peso (número con unidad) y garantía (booleano); una camisa, material (texto). La decisión fija dónde vive cada cosa y qué es un valor.
Definiciones y opciones son de la organización, no del catálogo. catalog.attribute_definitions y catalog.attribute_options no llevan catalog_id: son datos compartidos por todos los catálogos de la organización, como los alérgenos y las etiquetas dietéticas, y por eso el clon de un catálogo no los copia (EXCLUDED_TABLES de la prueba de deriva lo dice con su razón) y las definiciones comparten código en todos los catálogos. El valor (catalog.item_attribute_values) sigue al artículo: lleva catalog_id asignado por catalog.assign_catalog_id desde su artículo, un valor de variante lleva además la variante, y el clon copia los valores con la misma definición y la misma opción sin remapear nada.
Un valor es exactamente una columna. text_value, number_value, boolean_value u option_id según el tipo de la definición, y el CHECK item_attribute_values_one_typed_value_chk exige que sea la de su tipo y solo esa. El tipo y multi_select se copian a la fila y la llave foránea compuesta (definition_id, value_kind, multi_select, organization_id) con ON UPDATE CASCADE hace que cambiar el tipo de una definición con valores falle por el CHECK y que pasar de multi a simple falle por el índice único. Un valor por objetivo (artículo o variante) y definición, salvo una lista multi_select, que tiene una fila por opción.
Sin fórmulas, sin anidamiento, con topes en constantes: 200 definiciones por organización, 200 opciones por definición y 100 valores almacenados por artículo con sus variantes (catalog-limits.ts). Un número tiene hasta 14 dígitos enteros y 6 decimales; un texto, 500 caracteres. La unidad de un número es una unidad de referencia (reference.units_of_measure), validada por la aplicación como el contenido neto.
API. Las definiciones y sus opciones se administran con acciones delta (/catalog/attribute-definitions); el valor de un artículo o de una variante se pone con PUT /catalog/items/{id}/attributes/{code} y se borra con DELETE, sin reemplazar la colección. Las lecturas del artículo y de la lista llevan attributes ({ code: valor }) solo con include=attributes, y la lista filtra con attr.<code>=valor, attr.<code>.min y attr.<code>.max dentro de la misma sentencia (conjuntos candidatos intersectados, como la marca y la dimensión), con índices parciales por tipo. Una definición inactiva o archivada deja de mostrarse y de aceptar valores, pero sus valores se conservan.
Qué no hace. No traduce (el patrón de *_translations de la tarea C23 se añadirá sin tocar estas tablas), no emite un evento propio por cambio de definición (un valor emite catalog.item.changed y toda escritura mueve la versión del catálogo) y no calcula facetas (S3).
Rechazado: columnas JSONB en catalog.items (sin tipos ni índices por clave, y el clon y la deriva no las ven), definiciones por catálogo (el negocio tendría que redefinir «peso» en cada catálogo y el filtro no cruzaría catálogos), un valor por columna de la definición (un CHECK por tipo sin llave foránea que lo ate).
Por qué AttributeCommands no comparte base con ProductBrandCommands. Los dos repiten la secuencia admitir, bloquear la versión, bloquear la fila, comparar If-Match, aplicar y releer, pero cada paso toca un puerto y un agregado distintos (la definición lleva sus opciones y su etiqueta las cubre; la marca es una fila plana). Una clase base o una fábrica genérica para ocho líneas por lado es la abstracción que la guía prohíbe (se extrae con tres o más copias de la misma forma y motivo de cambio) y escondería de qué fila se toma el bloqueo; lint:duplicates no encuentra ningún clon. Si aparece una tercera copia, se extrae entonces.
D51. La búsqueda de artículos busca dentro del texto con trigramas desde tres caracteres y el orden de la lista es un dato del cursor
La lista de artículos (GET /catalog/items) ordena por sort (name, code, createdAt, updatedAt, status) y order (asc o desc), siempre con id como desempate, y cada orden pagina con el mismo cursor keyset: el cursor firma el orden y el sentido junto con los filtros, de modo que un cursor de otro orden, de otra organización o manipulado se rechaza con 400. El orden por defecto (nombre ascendente) no añade nada al cursor, así que los cursores del espacio de trabajo y los ya emitidos siguen valiendo.
Diseño más barato y correcto. Los artículos ya tienen name_search_key y code_search_key y las variantes sku_search_key, columnas generadas por catalog.search_key (minúsculas sin acentos). Una búsqueda que contiene el texto no necesita otra columna: la migración 0121 añade índices GIN (organization_id, <clave> gin_trgm_ops) sobre esas claves y sobre item_variant_barcodes.barcode (solo códigos activos), con las extensiones pg_trgm y btree_gin (ambas de confianza en PostgreSQL 13 o superior; el propietario de la base las crea). btree_gin permite que el GIN lleve organization_id como primera columna: sin ella, un trigrama frecuente recorrería las filas de todas las organizaciones. El nombre de marca no lleva índice: una organización tiene pocas marcas y se filtran por su clave calculada antes de unirlas a los artículos por catalog_items_product_brand_idx.
Regla de tres caracteres. Con menos de tres caracteres no hay trigramas que usar y un LIKE '%a%' recorrería todos los artículos de la organización; ahí la búsqueda sigue siendo por prefijo, que usa los índices de clave. Desde tres caracteres se busca dentro del nombre, el código, cualquier SKU y el nombre de la marca; si el texto son solo dígitos, también dentro de los códigos de barras activos. %, _ y \ son literales (se escapan en SQL sobre la clave ya normalizada).
Índices de orden. code pasa a (organization_id, catalog_id, status, code_search_key, id) y se añaden los de created_at, updated_at y status, todos con id al final: cada rama por estado sigue leyendo en orden con LIMIT sin ordenar todo el catálogo. Se pagan en la escritura de catalog.items (cuatro índices btree y dos GIN más), un coste asumido porque el catálogo se lee mucho más de lo que se escribe.
Rechazado: una columna de texto de búsqueda unificada (duplica los datos y obliga a mantenerla en cuatro tablas), ILIKE sin índice (una exploración secuencial por consulta), unaccent (no es inmutable, no se puede indexar) y buscar siempre por prefijo (no encuentra «latte» dentro de «Café latte»).
Nota de integración (0121 en una base con datos). La migración corre dentro de una transacción con CREATE INDEX simple, que bloquea las escrituras de catalog.items, catalog.item_variants y catalog.item_variant_barcodes mientras se construyen los índices, y el rol del migrador crea las extensiones pg_trgm y btree_gin igual que btree_gist en database/canonical/0000_extensions.sql (la convención del repositorio: las extensiones las crea el rol que instala, no el rol de la API). No hay convención de índices CONCURRENTLY en las migraciones (corren en una transacción y CREATE INDEX CONCURRENTLY no puede), así que en una base de producción con muchos artículos quien opera debe construir primero los índices con CREATE INDEX CONCURRENTLY fuera de la transacción de la migración, con los mismos nombres y definiciones, y dejar que la migración los encuentre ya hechos solo si se reescribe con IF NOT EXISTS; hasta entonces el despliegue en una base grande se hace en una ventana de mantenimiento. Es una nota de despliegue y no cambia el código.
D52. Una operación masiva sobre artículos es todo o nada, con un registro idempotente propio y un solo registro de auditoría
POST /catalog/bulk-operations aplica una operación (estado, categorías o marca) a hasta 200 artículos en una sola transacción. Todo o nada por petición: si un artículo no puede recibir la operación la respuesta es 422 catalog.bulk_operation_rejected con cada id y su problema, y no se escribe nada; el dryRun devuelve los mismos problemas por id con 200 y no escribe, no registra y no audita. Aplicar parcialmente obligaría al cliente a reconciliar qué se aplicó y, con la clave de idempotencia, a decidir qué reproduce una repetición; todo o nada deja una sola respuesta posible.
Idempotencia. Un artículo no se crea, así que la clave no puede vivir en una fila del recurso como en las demás creaciones: catalog.bulk_operations (organización, clave única, hash de la petición, operación y el informe) se escribe en la misma transacción que el cambio y es lo que una repetición devuelve. Una petición rechazada no escribe nada y la clave queda libre.
Una sola auditoría. Un registro catalog.bulk_operation.applied con la operación y los conteos, no uno por artículo (200 registros por petición costarían más que el cambio). La liberación de códigos de barras al archivar es una sentencia por lote y se cuenta en el mismo registro.
Reglas sin copia. El estado usa las reglas de item-lifecycle.ts (judgeItemTransition); las categorías usan assertCategoriesUsable y la marca usableBrand. El tope de 200 se mide: 200 artículos con un evento de cambio cada uno cuestan unos 80 ms.
Fuera del primer corte: listar y deslistar del surtido de una unidad de negocio, que ya tiene su propia ruta por lotes con las reglas de modo.
D53. El orden de las categorías es el sort_order de los hijos de un padre, renumerado de 0 en una sola sentencia
Mover una categoría («antes de tal hermana») y ordenar a todos los hijos de un padre son acciones y no una edición de sortOrder uno por uno: el cliente de la pantalla de árbol conoce la posición que quiere, no los números. El servidor lee los hijos del padre destino bloqueados en orden de id (después de la fila de versión del catálogo y de la categoría), calcula el orden nuevo y escribe solo los números que cambian con un UPDATE ... FROM unnest. Una petición que no cambia nada no escribe ni audita. El orden completo (PUT /catalog/categories/order) exige nombrar a todos los hijos exactamente una vez, archivados incluidos, porque un orden parcial dejaría posiciones ambiguas.
Auditoría. Se reutiliza catalog.category.moved con el atributo catalog.category.order (los ids antes y después) en lugar de sembrar una acción nueva: ordenar los hijos de un padre es mover categorías y evita una migración solo para un código de acción.
Fuera de este corte: duplicar artículos, grupos de modificadores y menús (/duplications).
D54. Duplicar un artículo, un grupo de modificadores o un menú es una sola función SQL por entidad, con la idempotencia en la propia fila de la copia
POST /catalog/items/{itemId}/duplications, POST /catalog/modifier-groups/{modifierGroupId}/duplications y POST /catalog/menus/{menuId}/duplications reciben {code?, name?} (el cuerpo {} es válido) y el Idempotency-Key obligatorio, y copian la entidad con lo que cuelga de ella en una transacción: el servidor deriva todo lo demás de la base. Cada copia es una llamada a catalog.duplicate_item, duplicate_modifier_group o duplicate_menu (migración 0125), funciones INVOKER que comparten catalog.duplication_begin (contexto de tenant, READ COMMITTED, fila de catalog_versions primero), catalog.copy_value (la regla de códigos), catalog.duplication_reject y los conteos; las copias de filas usan arreglos uuid[] como catalog.clone_catalog.
Reglas. El nombre omitido es el del origen más (copy); el código omitido es el del origen más -copy, luego -copy-2, -copy-3… el primero libre en el catálogo sin distinguir mayúsculas, recortado para caber en 80 caracteres; un código enviado que ya existe responde 409 catalog.code_taken sin sufijo. El SKU de cada variante se regenera con la misma regla (-copy, -copy-2…, 120 caracteres). Los códigos de barras y los identificadores de variante no se copian (son únicos mientras están activos); las imágenes se copian por referencia (el mismo activo, solo las listas y no archivadas); las ofertas de modificadores con sus predeterminados y topes, las categorías, los atributos, las banderas regulatorias, las dimensiones de variantes y los grupos de combo se copian; el artículo copiado no está en ningún menú. La copia de un artículo conserva su estado; la de un menú nace draft; la de un grupo no se ofrece en ningún artículo. Un origen archivado responde 422 (catalog.item_archived, catalog.modifier_group_archived, catalog.menu_archived); un origen inexistente o de otra organización 404. Los topes reutilizan las constantes existentes: 100 menús (MENU_LIMIT), 500 grupos (MODIFIER_GROUP_LIMIT) y, para artículos, 1200 por catálogo (ITEM_LIMIT, el mismo valor que admite un clon), con 422 catalog.item_limit_reached.
Idempotencia sin tabla nueva. items, modifier_groups y menus ya tienen creation_idempotency_key y creation_request_hash; la copia los lleva y el replay la encuentra por la clave: mismo hash responde 201 con Idempotent-Replayed: true y la copia tal como está ahora (conteos recalculados), otro hash 409 idempotency.key_reused. Por eso no hay tabla de registro que excluir del cubrimiento del clon.
Respuesta magra. {id, code, name, duplicatedFrom: {id}, counts} con el ETag de la copia en la cabecera (el mismo que devuelve el GET del recurso nuevo). Un solo registro de auditoría catalog.item.duplicated, catalog.modifier_group.duplicated o catalog.menu.duplicated con el origen y los conteos, sin un registro por fila. Permiso: el de crear la entidad (catalog.items.manage con la capacidad del catálogo).
Costo medido. 11 sentencias para un artículo de 2 y para uno de 20 variantes y un cuerpo de unos 330 bytes (test/e2e/catalog-duplications-budget.e2e-spec.ts).
Fuera de este corte: alérgenos y etiquetas dietéticas (no están en esta rama) y la validación sin escribir.
D55. El informe de salud del catálogo es una sentencia por revisión, de solo lectura, con la etiqueta derivada de la versión del catálogo
GET /catalog/health calcula once revisiones (artículos sin categoría, sin imagen o sin variante activa, grupos de modificadores vacíos, ofertas y grupos de combo que no se pueden satisfacer, menús vacíos, destinos archivados en ofertas activas, identificadores duplicados, artículos ofrecidos en ninguna parte y variantes retiradas en menús). Una sentencia por revisión, cada una sobre todo el catálogo con conjuntos (NOT EXISTS, agrupaciones previas, nunca una consulta por artículo): el número de sentencias no depende del número de artículos, y pedir menos revisiones con include pide menos sentencias. Se descartó una sola sentencia gigante porque un plan malo en una revisión arrastraría a todas y porque no se podría medir ni limitar cada una.
Cada revisión devuelve la cuenta total y hasta limit identificadores (5 por defecto, 50 como máximo) de las mismas violaciones, en orden de id, para que la pantalla muestre el número real y enlace a unos pocos. La gravedad (error, warning, info) es un dato de la revisión, no del llamador.
Lectura pura. Pide catalog.items.view como las demás lecturas, no exige el plan y no escribe ni audita. La etiqueta fuerte se deriva de la versión del catálogo de la organización (que mueve cualquier escritura de catálogo), el catálogo, las revisiones y el límite: el informe cambia solo cuando el catálogo cambia y If-None-Match responde 304. No se añadió ninguna columna ni tabla.
Decisiones de contenido. Un artículo activo siempre conserva una variante por defecto activa (lo exige la base de datos), así que «sin variante vendible» nombra artículos inactivos que no se pueden activar todavía. Un SKU duplicado solo puede existir recortado y en minúsculas, porque el índice único ya lo impide tal cual. Un identificador es «duplicado» cuando una fila archivada lo conserva, la trampa al restaurarla. Un artículo está «ofrecido» si tiene una entrada activa en un menú activo, está en el surtido de una unidad, o una unidad toma todo el catálogo.
Medido con 5.000 artículos: las mismas sentencias que un catálogo vacío, cuerpo de menos de 3.000 bytes y como máximo 4,1 buffers por artículo y revisión con estadísticas congeladas antes de la importación. Pruebas de mutación: una por rama de cada revisión (invertir NOT EXISTS, cambiar el estado comparado, quitar DISTINCT, relajar el mínimo, quitar el recorte del SKU, quitar cada rama del UNION); todas hicieron fallar catalog-health-checks.e2e-spec.ts.
D56. Las fechas y los canales de venta de un menú: fechas del local, sin canal es todos, y los menús pueden solaparse
Un menú se ofrece entre valid_from y valid_until (fechas, extremos incluidos, entre 2000-01-01 y 2100-12-31) y en los canales de venta de catalog.menu_channels. La fecha es la del local que muestra el menú, en la zona horaria de su sitio, el mismo reloj que ya usa el horario del día (operating.local_now); no existe una zona horaria de la organización y no se añadió ninguna. Sin filas de canal, el menú se ofrece en todos los canales; la lectura del puesto de venta recibe un salesChannelId opcional: ausente no filtra (el comportamiento anterior), presente muestra solo los menús sin canal o que lo listan. El canal forma parte de la etiqueta de la lectura, que sigue a la fecha local porque la máscara de menús mostrados la incluye. Dos menús activos pueden solaparse: no hay restricción de exclusión, el orden del local decide.
Contrato de escritura. Tres rutas deltas (PUT .../window, POST .../channels, DELETE .../channels/{id}) con If-Match obligatorio, sin Idempotency-Key, respuesta {menuId, outcome, changed, etag} y already_in_effect que no escribe, no audita y no mueve la versión. Las fechas y los canales entran en la etiqueta del menú. Quitar un canal que el menú no lista es already_in_effect (no se consulta el esquema de organización para distinguir un canal desconocido); añadir uno inexistente o de otra organización es 404 por la clave foránea compuesta (sales_channel_id, organization_id).
Clonar y duplicar copian fechas y canales. Costo medido: 10 sentencias y 180 bytes por cambio real, 8 y 192 ya en vigor; la lectura del puesto no cambia de número de sentencias.
D57. La integración del catálogo exige privilegios de extensión, índices CONCURRENTLY en producción y publica la versión 14.0.0
Estado: vigente (migraciones 0121 y 0125, revisión 149).
Extensiones (0121). La migración 0121 crea pg_trgm y btree_gin. El rol que despliega las migraciones necesita el privilegio CREATE sobre la base de datos (o las extensiones creadas de antemano por un superusuario); sin él la migración falla con permission denied to create extension.
Índices sobre una base con datos (0121). Dentro de la transacción de la migración los CREATE INDEX bloquean las escrituras de catalog.items, catalog.item_variants y catalog.item_variant_barcodes. En una base de producción con datos, los índices de 0121 se construyen antes con CREATE INDEX CONCURRENTLY fuera de la transacción (mismos nombres y definición). Las sentencias CREATE INDEX de la migración no llevan IF NOT EXISTS, así que ese despliegue ejecuta el resto de 0121 y reserva la migración (ninaku_migrations.claim) sin repetir esos índices, o los suelta justo antes de aplicarla.
Duplicar conserva lo que declara el plato (0145). duplicate_item copia traducciones del artículo y de sus variantes, alérgenos, etiquetas dietéticas y perfiles nutricionales con sus hechos; duplicate_menu copia las traducciones del menú, secciones y entradas; duplicate_modifier_group las del grupo y sus opciones.
OpenAPI 14.0.0 (cambios incompatibles aceptados por el salto de mayor 13 a 14, comparados con origin/staging):
POST /catalog/items/{itemId}/variants201: la respuesta pasa a ser lean y deja de devolvercategories,code,description,images,itemId,modifierGroups,name,productBrand,regulatoryFlags,statusyvariants(se piden coninclude=item).GET /catalog/menus200:datapasa de objeto a arreglo y desaparecedata.menus.- No hay más cambios incompatibles: el resto son rutas, parámetros y propiedades añadidos.
D58. Un catálogo activo por unidad, y el catálogo es parte de cada consulta, nunca de la identidad
Una organización puede tener varios catálogos (el complemento catalog.multiple_catalogs solo gobierna crear y clonar; no hay tope de catálogos). Cada unidad de negocio vende de un catálogo activo (índice único parcial), none es un modo de surtido de esa asignación y no la ausencia de ella, volver a un catálogo conserva el modo guardado y las cartas viejas de los outlets quedan dormidas. El catálogo por defecto nunca sale de active, un catálogo con una asignación activa no se desactiva ni se archiva, y restaurar deja el catálogo en inactive.
Cómo se elige el catálogo. Las colecciones (listas, espacio de trabajo, dimensiones, búsqueda de códigos) y las altas llevan catalogId opcional; sin él es el catálogo por defecto. Las rutas por id trabajan en el catálogo del registro que nombran, así que el identificador de un artículo no cambia de significado. Un catalogId desconocido es 404 catalog.not_found.
Qué se cuenta dónde. Los topes de categorías, grupos de modificadores, cartas y marcas se cuentan dentro del catálogo, como los códigos, los nombres y los códigos de barras activos, que ya eran únicos por catálogo en la base; cada catálogo tiene su propio margen. Un catálogo inactive es un borrador y recibe escrituras; uno archived las rechaza con 422 catalog.catalog_archived y el campo catalogId, y se sigue leyendo.
Por qué no un encabezado ni un catálogo «actual» de la sesión. Un parámetro explícito se ve en el registro de acceso, se puede repetir y cabe en la llave de idempotencia; un estado de sesión haría que la misma petición cambiara de significado entre dos pantallas.
Lecciones. Una consulta «de la organización» es un defecto en cuanto hay dos catálogos (la comprobación de código de barras y los topes lo eran); se prueba el aislamiento con un segundo catálogo que contenga los mismos datos (un clon) y no con uno vacío; el catálogo de la llamada se escribe como una sola subconsulta escalar para no cambiar el plan de la caja ni de las lecturas.
Rechazado: un tope de artículos por catálogo (no existía por organización), copiar los topes a una tabla por catálogo, un encabezado X-Catalog-Id.
D59. El historial de un registro lo guarda Catálogo, con disparadores de sentencia, y solo restaura sus campos propios
La auditoría no sirve para restaurar: guarda antes y después de algunos campos, anota una importación o un clon como conteos, vive bajo su propia retención y Catálogo no tiene un contrato para leerla. Catálogo guarda catalog.entity_revisions (jsonb de los campos propios, versión, actor y campos cambiados) escrito por disparadores de sentencia con tablas de transición en artículos, categorías, marcas de producto y grupos de modificadores, de modo que cualquier camino de escritura (API, importación, clon, SQL masivo) deja su revisión, por conjuntos y sin una llamada por fila.
Retención. Las últimas 50 revisiones por registro; la sentencia que escribe la más nueva borra las viejas de las filas que tocó por el índice único, así que no hay trabajo programado ni bloqueo ancho. Una versión podada es 410, una versión que el registro nunca alcanzó es 404.
Qué se restaura. Solo los campos propios guardados (código, nombre, descripción, y la modalidad y la marca de un artículo, el padre y el orden de una categoría); el estado, las variantes, los códigos de barras, las ofertas y las estructuras de combos y cartas no se versionan y un restablecimiento no los toca. Restaurar es una edición normal: mismas comprobaciones, If-Match, una sola anotación de auditoría y una revisión nueva; una versión igual a la actual es already_in_effect.
Medido. Con los ocho disparadores activos o apagados, importar 500 artículos, renombrar 200 y clonar 1.200 quedan dentro del ruido entre corridas (mismas sentencias), por debajo del 25 %, de modo que la creación también deja revisión y la línea base perezosa solo cubre lo anterior a la migración.
Rechazado: leer la auditoría, un disparador por fila, una tabla de revisiones por entidad, guardar todas las revisiones sin tope, y una acción de auditoría propia para restablecer (la edición ya audita con la acción de su registro).
D60. Las funciones invocadoras de Catálogo no fijan search_path, y RLS no se fuerza
Ocho funciones de Catálogo que el rol de ejecución puede llamar (ensure_default_catalog, assert_item_default_variant, variant_is_listed, variant_is_listed_at_outlet, assert_variant_listed, resolve_barcode, assert_menu_entry_variant_configuration, refresh_bundle_food_labels) corren con los privilegios de quien llama y no fijan search_path; el rol de ejecución no puede crear objetos, así que no hay nada que anteponer en la ruta de búsqueda y no se eleva ningún privilegio. Las dos funciones SECURITY DEFINER del esquema sí fijan pg_catalog, pg_temp y están en la lista justificada del contrato catalog-isolation-contracts.ts.
RLS queda habilitado y no forzado en las tablas de Catálogo, como en el resto del repositorio salvo contabilidad: el dueño es el rol de migración y el rol de ejecución no es dueño ni omite RLS, lo que el contrato comprueba.
Rechazado: forzar RLS solo en Catálogo (rompería la convención y no cambia lo que el rol de ejecución puede leer) y añadir SET search_path a las ocho funciones (una migración nueva sin riesgo que cubrir).
D61. Los change sets de Catálogo son un diario de comandos que se reproduce por los casos de uso reales, nunca una copia del catálogo
Un cambio de temporada (el menú nuevo, las ventanas de un local) se prepara como un borrador de un catálogo, sin tocar datos vivos. Se rechazó clonar el catálogo y editar la copia (el clon acuña ids nuevos de artículo y variante, y Precios, Cocina, Fidelización y Analítica los referencian) y se rechazó una sombra por agregado (duplica las invariantes que los casos de uso ya poseen). Se eligió un diario: cada operación es {clientOpId, op, target, body} y el cuerpo es, por referencia, el esquema de la ruta viva (OPERATION_CONTRACT), así que no puede divergir; la prueba de deriva falla si una ruta de escritura viva de menús o de menús de un local no está registrada ni excluida con su razón.
S10.1 solo graba, valida y compara: nada de lo que hace escribe datos vivos, ni sube la versión del catálogo, ni emite eventos del feed (las tres tablas no tienen disparadores de versión ni de feed). Publicar, previsualizar y deshacer quedan fuera (S10.2, S10.3 y S8). Reglas: un solo borrador abierto por catálogo (índice único parcial, sin candado extra: dos creaciones a la vez dan un 201 y un 409); catalog.change_sets.write para crear, grabar, quitar y descartar, read para leer, listar y comparar, y preview y publish solo se siembran; If-Match con la etiqueta del change set (428 y 412); 200 operaciones por borrador, 50 por petición, 16 KiB por operación y un cuerpo de hasta 1 MiB; vigencia de 30 días por defecto (hasta 90) con expires_at como dato, y un borrador vencido se lee como expired y se materializa al crear el siguiente. Todas las escrituras toman primero la fila de catalog_versions (el mismo orden que cualquier escritura del catálogo, así que un catálogo retenido da 503 con Retry-After y nunca un interbloqueo) y después la fila del change set; los tipos de operación son datos sembrados (catalog.change_set_operation_types), no columnas.
La validación al grabar es la real y sin escribir: la derivación pura de la ruta viva (deriveEntrySections), el juicio de menús de un local y el plan de estructura del menú se ejecutan contra el estado vivo y, para las altas, contra los artículos del mismo catálogo; un destino de otro catálogo da 422. No prueba que una secuencia de comandos se aplique junta: eso lo prueba la publicación. Cuesta 14 sentencias por petición de grabación sea cual sea el número de operaciones sobre un destino (cada menú se lee una vez por petición).
Dos desviaciones del diseño aprobado: las migraciones son 0126 y siguientes (el diseño reservaba 0150 a 0154, que dejaron de existir al consolidar la cadena 0115 a 0125), y la operación outlet.menu.window.set es outlet.menus.set, porque la única ruta viva de ventanas de local es PUT /catalog/outlets/{outletId}/menus, que reemplaza la lista de menús y sus ventanas (no existe una ruta delta de ventana de local). Un op desconocido es un 400 de validación del campo operations.N.op, no un código propio. La tabla catalog.change_set_operation_types no lleva organization_id (es un dato de referencia, solo lectura para el rol de ejecución): los contratos de aislamiento la declaran en una lista de tablas globales con su razón (GLOBAL_REFERENCE_TABLES) y comprueban que no guarda datos de un tenant. Un change set nunca se clona (la prueba de deriva del clon lo excluye con su razón).
Rechazado: clonar y editar el clon, una sombra por agregado, un parámetro changeSetId en las rutas vivas (cada caso de uso vivo tendría que conocerlo), un límite de 100 KB para el cuerpo de grabación (50 operaciones de hasta 16 KiB no caben), y un estado expired materializado por un barredor en esta rebanada.
D62. Publicar un change set reproduce el diario dentro de un alcance de réplica, con presupuestos medidos
Publicar es una transacción que toma primero la fila de versión del catálogo y después la del change set, compara la etiqueta base de cada operación con la viva (toda la comparación antes de aplicar nada) y reproduce las operaciones por los casos de uso reales, que siguen comprobando el permiso de su ruta viva para quien publica: tener solo catalog.change_sets.publish no permite cambiar lo que no se podría cambiar directamente. Un AsyncLocalStorage (el alcance de réplica, src/foundation/transactions/replay-scope.ts) hace que el ejecutor de transacciones de tenant reutilice la transacción abierta (abrir otra conexión se bloquearía contra la fila de versión), y desvía la auditoría de CatalogAccess a un colector para que se escriba un solo registro catalog.change_set.published con los conteos. Los casos de uso internos no tienen idempotencia por operación; la clave de publicación vive en la fila del change set y su respuesta se guarda ahí.
Medición (harness catalog-change-sets-replay-measurement.e2e-spec.ts): 103, 519, 1,039 y 2,079 sentencias para 10, 50, 100 y 200 operaciones (unas 11 por operación de menú), 1,1 subidas de versión del catálogo y 1,1 eventos del feed por operación, y entre 3,7 y 6,6 s para 200 operaciones según la carga de la máquina. Con 200 el reloj de 4 s no alcanza, así que el tope por borrador baja a 100 (constante, CHECK de la migración 0127, metadatos y documentos a la vez). Presupuesto de coste por publicación 1.200 unidades (11 por operación de menú, 15 por outlet.menus.set), rechazado antes de aplicar con 422 catalog.change_set_too_costly; presupuesto de reloj 4 s, superado a mitad de camino se deshace todo con 503 y Retry-After 5 (el cuerpo es el problema genérico de la plataforma: toda falla 5xx se responde como foundation.internal_error, de modo que el código del catálogo nunca se ve); lock_timeout 2 s sin cambios.
Decisiones menores: los conflictos viajan como errores de campo operations.N con las etiquetas esperada y viva en el mensaje y meta.truncated (el sobre de problemas no admite otro miembro); los códigos siguen la convención con guion bajo del resto del módulo (catalog.change_set_conflict, no catalog.change_set.conflict); un rechazo de permiso dentro de la réplica no deja registro denegado (se desharía con la transacción); ready reproduce el diario dentro de un punto de guardado que se deshace.
D63. La vista previa y el diff resuelto reproducen el diario en una transacción que siempre se deshace, con la misma regla de permisos estricta que publicar
GET /catalog/change-sets/{id}/preview/outlets/{outletId}/sellables y GET /catalog/change-sets/{id}/diff?mode=resolved comparten una puerta (change-set-replay-gate.ts): permisos catalog.change_sets.read y catalog.change_sets.preview (antes de tomar ningún bloqueo, un rechazo no deja registro como toda lectura), luego la fila de versión del catálogo FOR UPDATE (mismo orden que publicar), la lectura del change set (404 si no existe o es de otra organización), 409 catalog.change_set_not_open si no está abierto, 422 catalog.catalog_archived y el presupuesto de coste. La reproducción corre dentro de runValidatingOnly, que hace que el ejecutor deshaga la transacción al final: no queda fila, ni evento del feed, ni registro de auditoría de éxito, y la versión del catálogo no se mueve (probado contando las filas de todas las tablas del catálogo, el feed y la auditoría antes y después, también tras un fallo forzado y con ediciones vivas concurrentes).
Regla estricta de permisos (elegida a propósito): la vista previa ejecuta los casos de uso internos con su admisión; quien previsualiza necesita además el permiso de cada operación de su ruta viva y catalog.sellables.view en el outlet. No se salta la admisión para que un revisor sin derechos de escritura vea más de lo que podría ver cambiando directamente: el documento de la vista previa y el diff resuelto exponen datos del catálogo y precios de menú que ese miembro no puede leer por la ruta viva. El coste es que un revisor "solo lectura" no puede previsualizar un change set que toca menús; quien quiera ese perfil debe recibir catalog.items.manage o equivalente, y eso es una decisión de producto explícita, no un descuido.
El outlet: la lectura es exactamente la del till (ReadWhatAnOutletSellsUseCase.read, mismo SQL y proyección, locale y salesChannelId incluidos) dentro de la misma transacción; solo se añadió at a la consulta (el reloj inyectado sigue siendo el valor por defecto). El outlet debe ser de una unidad de negocio que hoy tiene asignado el catálogo del change set; cualquier otro (de otra organización, desconocido o de otro catálogo) responde el mismo 404, y el permiso del till se comprueba antes de reproducir. La respuesta añade previewOf {changeSetId, etag, baseCatalogVersion, liveCatalogVersion, stale}, Cache-Control: no-store, ningún ETag y nunca 304 (Express responde 304 a If-None-Match: * aunque no haya ETag, así que la ruta descarta las cabeceras condicionales con un interceptor), y meta no lleva catalogVersion porque la versión reproducida es ficticia. La vista previa no compara las etiquetas base (un set obsoleto se muestra marcado stale y una operación que ya no se puede aplicar responde lo que respondería su ruta viva).
Límite de frecuencia: una réplica por miembro y change set cada 5 s (429 rate_limit.exceeded con Retry-After), contada con el almacén del throttler; la clave incluye al miembro para que alguien sin permiso no pueda agotar la ventana de otro, y el diff de diario no cuenta. El valor es un proveedor (CHANGE_SET_REPLAY_RATE_LIMIT) para que las pruebas lo cambien.
Medición y decisión sobre el bloqueo (catalog-change-sets-preview-cost.e2e-spec.ts, mundo de 105 ítems): 137 sentencias y 237 ms para 10 operaciones, 553 y 605 ms para 50, 1.073 y 1,9 s para 100, respuesta de 35.875 bytes (tope 40.000); una escritura viva lanzada a los 15 ms esperó 223, 589 y 1.917 ms: el bloqueo se mantiene durante toda la vista previa. ¿Conviene saltar el bloqueo y reproducir sin esperar, aceptando datos obsoletos? No: se probó quitando el FOR UPDATE explícito y la escritura viva esperó igual (157, 667 y 1.303 ms), porque la primera sentencia de escritura reproducida dispara el disparador que actualiza la fila de versión y la retiene hasta el rollback. Una vista previa sin bloqueo exigiría suprimir ese disparador en el alcance de réplica (SQL, S10.5). Por eso se mantiene el bloqueo explícito (orden de bloqueos determinista y 503 con Retry-After antes de hacer trabajo) y se acota el daño con el tope de 100 operaciones, el presupuesto de reloj de 4 s, la frecuencia de 1 por 5 s y el lock_timeout de 2 s. El presupuesto de reloj depende de la carga de la máquina: un portátil cargado tardó 2,9 s en 100 operaciones y 3,7 a 6,6 s en 200; el valor (CHANGE_SET_PUBLISH_WALL_CLOCK_MS, 4.000) se publica en GET /catalog/metadata (limits.changeSets.publishWallClockMs) y el cliente no debe asumir que un set de 100 operaciones cabe siempre en una máquina lenta.
Diff resuelto: añade a cada agregado del diff de diario resolved {entity, before, after, created, changed, removed, reordered, truncated} (ids y nombres, hasta 100 por lista, sin documentos) leído antes y después de la réplica, y resolvedAgainst {baseCatalogVersion, liveCatalogVersion, stale}; el modo por defecto no cambia. reordered solo compara el orden de las entidades que existen antes y después, así que añadir o quitar una nunca lo activa.
Hallazgos de esta tanda: toda falla 5xx se responde como foundation.internal_error (los códigos 503 propios del catálogo no son visibles; Retry-After se añadió al 503 de publicar que tardó demasiado y la documentación se corrigió); el presupuesto de reloj de la réplica es ahora un proveedor para poder probar el aborto a mitad de camino de punta a punta.
D64. Los change sets reproducen también los deltas de ítem y las creaciones, con ids reservados al grabar
S10.4 agrega al registro de operaciones once deltas de ítem sobre rutas vivas (item.category.add|change|remove, item.offer.add|change|remove|move, bundle.choice.add|change|remove, item.status.change) y tres creaciones (menu.create, item.create, category.create), cada una con el esquema del cuerpo de su ruta viva por referencia y el caso de uso vivo como manejador. Los nombres difieren del encargo (item.modifierGroup.*, item.bundleChoice.*) porque el código de tipo de operación es ^[a-z]+(\.[a-z]+)+$ y no admite mayúsculas. Las migraciones son 0128 (tres tipos de objetivo y diez filas de tipos), 0129 (entity_id, índice único y tres tipos de creación) y 0130 (el tipo item_status y item.status.change): todo lo variable sigue siendo dato.
Agregados y etiquetas: una categoría o una oferta de un ítem se comparan con la etiqueta del ítem (ITEM_ENTITY_TAG) y las opciones de un combo con la de la composición (BUNDLE_ENTITY_TAG), las mismas que usan sus rutas vivas, de modo que una edición viva del ítem entre grabar y publicar da 412 catalog.change_set_conflict. Los tipos de objetivo (item_categories, item_offers, bundle_choices) separan lo que el diff resuelto lista; un registro de adaptadores de agregado (ChangeSetAggregates: etiqueta, catálogo y resumen) reemplaza los if por tipo que había en el diff, el diff resuelto, el validador y los manejadores. Se añadió ItemRepositoryPort.catalogOf para comprobar que el ítem pertenece al catálogo del change set.
Costura de ids (R1): los casos de uso de creación toman su id primario de newEntityId() (foundation/identifiers/new-entity-id.ts), que fuera de una réplica devuelve un uuid v7 nuevo y dentro de ella entrega, una sola vez, el id que el diario reservó para esa operación (ReplayScope.entityIds, un PreallocatedEntityIds por réplica). Ninguna ruta viva puede elegir un id: el cuerpo estricto rechaza una clave desconocida y la costura solo existe dentro del alcance. Al grabar, la operación de creación recibe un uuid v7 (entity_id, igual a target_id, único entre organizaciones y tiempo); la respuesta lo devuelve como entityId y un reintento con el mismo clientOpId devuelve el mismo. La clave de idempotencia del caso de uso es ese id. Al reproducir, si ya existe una entidad con el id reservado, 409 catalog.change_set_entity_id_taken sin aplicar nada; si la operación no consume el id reservado, la réplica falla.
Validación al grabar en orden: las operaciones se validan en orden de seq contra el diario: un destino que ni existe vivo ni lo creó una operación anterior es 404; una creación de otro catálogo es 422. Una operación sobre una entidad que solo existe en el borrador no tiene etiqueta base (cadena vacía, sin comparación) y, si su cuerpo menciona una entidad solo del borrador, se omite el ensayo en seco de la derivación (ready lo reproduce todo). Quitar una creación que otra operación usa es 409 catalog.change_set_operation_in_use.
Medición (catalog-change-sets-replay-measurement-items.e2e-spec.ts): sentencias por operación 8 (alta y cambio de categoría), 6 (baja), 10 (alta y movimiento de oferta), 4 (cambio), 9 (baja), 11 (cada delta de combo), 5 (transición de estado), 9 (menú), 10 (ítem y categoría), entre 3 y 13 ms cada una; una réplica mixta de 10, 50 y 100 operaciones cuesta 73, 349 y 694 sentencias (unos 7 ms por operación). Los pesos del presupuesto son esas cifras redondeadas hacia arriba (CHANGE_SET_OPERATION_COST, expuestos en GET /catalog/metadata junto con la lista de tipos de operación); con el mayor peso (11) cien operaciones suman 1.100 y el presupuesto de 1.200 unidades y el tope de 100 no cambian.
Excluido, con razón (el test de deriva lo exige y lo lista): las rutas PUT que reemplazan todo (clasificación, ofertas, composición del combo, estructura del menú, listado de un local), la edición de perfil, canales, ventana y transiciones de un menú, y la duplicación (una creación que clona). El test de deriva también exige y excluye con razón el surtido de una unidad de negocio (PUT .../assortment y POST .../assortment/listing-changes: no son un delta del catálogo del change set sino del surtido de una unidad). Fuera de las familias cubiertas quedan, sin registrar y sin exigencia del test, las transiciones de la variante y el resto de rutas de ítem (alérgenos, nutrición, atributos, imágenes, variantes): cada una pide su propio agregado, etiqueta y resumen y se deja para una tanda posterior.
Rechazado: un EntityIdSource inyectado en los casos de uso (tres constructores y todos sus dobles de prueba) frente a una función con alcance de réplica; aceptar un id elegido por el cliente en las rutas vivas; e iniciar las creaciones por un código de operación con mayúsculas.
D65. Una réplica de change set no retiene la versión del catálogo: el disparador de versión y el feed leen un alcance de réplica que solo abre el ejecutor de la réplica
Problema (D63 lo midió y lo dejó abierto): la primera sentencia de escritura de una réplica dispara el disparador de versión por sentencia, que actualiza la fila de catalog.catalog_versions y la retiene hasta el final de la transacción. Una vista previa (siempre deshecha, hasta 1,9 s con 100 operaciones) bloqueaba toda escritura viva del catálogo, y una publicación de N operaciones subía la versión unas N veces y escribía unos N eventos del feed.
Decisión (migración 0131): tres funciones y un ajuste de cuatro disparadores. catalog.begin_replay_scope(modo) (publish o preview, nada más; exige contexto de tenant activo) fija el ajuste local de transacción ninaku.catalog_replay = '<modo>:<id de transacción>'; catalog.replay_mode() lo lee y solo lo honra si el id de transacción coincide con el de la transacción en curso; catalog.end_replay_scope() lo cierra. Los disparadores bump_catalog_version, bump_category_tree_version, bump_category_tree_version_of_translations y record_change_feed (cada uno definido una sola vez en su forma final, con la unión del comportamiento anterior cuando no hay alcance) hacen lo siguiente dentro de un alcance: en preview no suben nada, no escriben eventos y no tocan la fila de versión; en publish solo marcan que hubo cambios (y, para el árbol de categorías, que el árbol cambió) y end_replay_scope sube la versión una vez (más categories_version una vez si el árbol cambió) y solo si alguna sentencia cambió filas: una publicación que no cambia nada deja la versión como estaba, igual que antes. Los eventos del feed de una publicación llevan la versión v + 1 (la que producirá el cierre) y su clave catalog-change:<versión>:<evento>:<md5 del contenido> los deduplica: el feed recibe los cambios netos, uno por contenido distinto.
Por qué es seguro: (1) solo el ejecutor de la réplica lo abre (ChangeSetReplay.applyThen, dentro de runReplaying); ninguna ruta viva llama a la función ni acepta un valor del cliente, y el alcance es una transacción: se borra al cerrar, al hacer commit y al hacer rollback; (2) el valor lleva el id de transacción, así que un ajuste de sesión que sobreviva a su transacción o copiado de otra es inerte (mutación: quitar la comprobación del id deja pasar la prueba de contrato, que falla); (3) la función exige contexto de tenant y el rol de runtime solo recibe EXECUTE de las tres funciones nuevas; (4) un fallo a mitad de réplica no cierra el alcance: la transacción se deshace entera y no se sube nada; (5) la lectura de la versión en una vista previa (CatalogVersionRepository.lockVersion bajo un alcance preview, y readVersion en la puerta de réplica) es un SELECT sin FOR UPDATE; las escrituras vivas esperan solo por las filas concretas que la réplica bloquea (el menú o el ítem que toca), no por todo el catálogo.
Medición (catalog-change-sets-replay-isolation.e2e-spec.ts, por HTTP, antes → después): una escritura viva lanzada a los 200 ms de una vista previa esperó 545 → 7 ms con 50 operaciones y 1.700 → 6 ms con 100 (con 10 operaciones la vista previa dura 240 ms y la espera, unos 110 ms en ambos casos, es el bucle de eventos serializando la respuesta de 173 KB); las subidas de versión de publicar 10, 50 y 100 operaciones de menú pasaron de 10, 50 y 100 a 1 y los eventos del feed de 10, 50 y 100 a 1; cada réplica cuesta 2 sentencias más (abrir y cerrar el alcance).
Límites que quedan: ready sigue tomando la fila de versión primero (orden de bloqueos de toda escritura del change set, porque sella validated_at_catalog_version); su ensayo corre en modo preview (sin subir ni escribir eventos) pero la retiene mientras dura (hasta el presupuesto de 4 s). Moverlo a una lectura sin bloqueo exigiría invertir el orden de bloqueos o reintentar si la versión cambió; no se hizo. La respuesta de la vista previa crece con el menú (unos 150 bytes por entrada).
Rechazado: un parámetro que cada caso de uso pase al repositorio (toca todos los repositorios y puertos); inhabilitar los disparadores con session_replication_role (requiere superusuario y apaga también las comprobaciones de integridad); y un ajuste sin id de transacción.
D66. Un barrido acotado marca como expirados los borradores vencidos y otro purga los cuerpos de los change sets terminados, con la retención en datos
Expiración (migración 0132, catalog.expire_change_sets(p_limit), SECURITY DEFINER, ejecutable solo por ninaku_worker): marca expired (y sube revision, que cambia el ETag) los change sets draft o ready con expires_at <= now(), de los más viejos a los más nuevos, FOR UPDATE SKIP LOCKED y un máximo por corrida (el valor sweep_batch_size de catalog.change_set_settings, 100; el parámetro solo lo baja). No toma la fila de versión: un escritor tiene la fila del change set después de la de versión y el barrido nunca espera, así que no hay inversión de orden ni interbloqueo, y un change set que un escritor tiene bloqueado se deja para la corrida siguiente. Es idempotente (no hay candidatos la segunda vez) y no toca el catálogo vivo, su versión ni su feed. La lectura ya derivaba expired de expires_at y las escrituras ya lo trataban como cerrado (409 catalog.change_set_not_open) o lo marcaban al abrir otro borrador; el barrido solo materializa el estado y libera el índice de un borrador abierto por catálogo.
Auditoría: un registro catalog.change_set.expired por change set (acción nueva, actor_requirement requerido, sin decisión de autorización), con el estado antes y después. La auditoría de tenant exige un contexto activo y un actor, así que la función toma, solo dentro de la transacción y restaurando los ajustes previos, la identidad que abrió el borrador y su membresía activa, con origen system. Si esa persona ya no tiene membresía activa no hay contexto posible: el change set se expira igualmente y se cuenta como unaudited en el resultado (el registro de log del trabajo lo informa); la transición queda en la propia fila (status, revision).
Aislamiento: el barrido corre con el rol del trabajo (ninaku_worker, como las purgas de la bandeja de seguridad de identidad y de los uploads de assets) y recorre todas las organizaciones; el rol de runtime no tiene EXECUTE (prueba de contrato: 42501) y por RLS cada tenant sigue leyendo solo lo suyo antes y después. El contrato de fundaciones del catálogo decía que el worker no tenía acceso al esquema catalog; ahora exige lo que importa de verdad: el worker recibe USAGE del esquema solo para llamar a las dos funciones de barrido (su único EXECUTE en el esquema) y ningún privilegio sobre ninguna tabla del catálogo. Lo ejecuta ChangeSetSweepJob (cada 60 s, un barrido a la vez, hasta 20 lotes por corrida) en el proceso worker, registrado en WorkerModule mediante CatalogChangeSetSweepModule.
Purga de cuerpos: catalog.purge_change_set_payloads(p_limit) reemplaza por {} el payload de las operaciones de los change sets published, discarded o expired cuyo momento final (published_at, discarded_at o expires_at) supera la retención y pone payload_purged_at (con revisión +1). La retención es el dato payload_retention_days = 90 (catalog.change_set_settings, solo lectura para el runtime): no hay número en el código. Se conservan ids, tipos de operación, objetivos, estado, marcas de tiempo, base_etag, entity_id, publish_result y el enlace de auditoría, así que el historial y el diff de diario siguen legibles; las lecturas devuelven purgedAt (nulo mientras se conservan). Un CHECK impide marcar como purgado un change set abierto. Es idempotente, acotada por lote y empieza por el más viejo. La purga no escribe registro de auditoría propio: los registros de creación, listo, publicación y expiración permanecen y la fila lleva payload_purged_at.
Rechazado: expirar solo de forma perezosa al acceder (un borrador abandonado seguiría bloqueando el índice de abierto por catálogo hasta que alguien abra otro); borrar las operaciones al purgar (se pierde el diff histórico); y una columna expired_at (el momento es expires_at).
D67. Endurecimiento de S10: Validate-Only en todas las rutas que escriben el diario, y una publicación vacía no sube la versión
Hallazgo: Validate-Only: true en POST /catalog/change-sets, DELETE .../operations/{seq} y POST .../discard era ignorado en silencio (esas rutas no estaban marcadas) y ejecutaba la escritura real: un cliente que pedía una comprobación abría un borrador, quitaba una operación o descartaba el change set. Ahora las tres llevan @ValidateOnlyRoute: responden 200 {valid, problems} con el mismo problema que daría la llamada real (404, 400, 412, 428...), no escriben nada y no cambian el ETag. Cada ruta de S10 que escribe (crear, registrar, quitar, descartar, listo, publicar) soporta ahora la comprobación.
Publicación vacía: un change set sin operaciones se marca listo y se publica (200, operationCount 0). Con D65 sigue sin tocar el catálogo: la versión no sube, no hay eventos y queda un registro de auditoría de publicación. Se probó que un end_replay_scope que subiera siempre la versión rompe esa prueba.
Cubierto sin cambios: los casos 429 (publicar/listo y vista previa), 428/412/400/404, límite de 1 MiB y 51 operaciones, 503 con Retry-After por lock_timeout de 2 s y por el presupuesto de reloj de 4 s (con pruebas de integración de punta a punta que no necesitan ningún gancho en el código de producción: el segundo usa el proveedor CHANGE_SET_REPLAY_BUDGET), archivado del catálogo, descartar/publicar/listo en cualquier orden, descartar frente a publicar concurrentes, reintento del mismo Idempotency-Key con y sin otro cuerpo y unicode en el nombre (NUL, 201 caracteres y solo espacios dan 400). No existe borrado lógico en el diario: lo único borrado de verdad es una operación quitada de un borrador.
D68. El suministro de una variante se declara en una ruta por lugar: gana la más específica y una sola ruta activa por variante y lugar
Decisión (migración 0137): inventory.supply_routes da a cada variante del catálogo una ruta por lugar (organización, unidad de negocio o punto de venta), con fechas y un tipo stock, recipe o untracked; una restricción de exclusión gist impide dos rutas activas de la misma variante y el mismo lugar con fechas que se solapan. inventory.resolve_supply_route elige la más específica (punto de venta, luego unidad de negocio, luego organización). Las líneas de una ruta stock viven en inventory.supply_route_stock_lines (una por artículo, con su cantidad) y su integridad se exige con disparadores de restricción diferidos. Una ruta untracked declara que la variante no descuenta stock: así "sin ruta" es un error (23514) y "no se controla" es un dato.
Rechazado: un vínculo catálogo a stock por organización (inventory.catalog_stock_links, que se copió a una ruta de organización y se eliminó), porque no distingue lugares; y fusionar rutas de varios niveles, porque la receta o el stock de un nivel no se suma al de otro.
D69. El libro de recetas es global y las recetas se asignan por ruta; marca y sitio volverán como grupos de puntos de venta
Decisión (migración 0138): production.supply_route_recipes liga una receta (con versión fijada opcional y una escala por unidad de venta) a una ruta de tipo recipe, con una clave foránea compuesta (supply_route_id, route_kind, organization_id) y un CHECK de tipo: una ruta stock o untracked nunca tiene receta. Reemplaza a production.recipe_assignments; las dimensiones de marca y sitio se retiran hasta que existan los grupos de puntos de venta, y la migración se niega, con los ids, a copiar una asignación de marca o sitio o que se solape con una ruta activa. production.resolve_recipe_version pasa a (organización, variante, unidad de negocio, outlet, fecha), resuelve por D68 y falla con 23503 si la ruta de receta no tiene receta; production.recipe_routes_without_recipe lista esas rutas.
D70. Una ubicación pertenece a la organización, a una unidad de negocio o a un punto de venta, y las reglas de ubicación de salida tienen una precedencia documentada
Decisión (migración 0139): inventory.locations.business_unit_id (nulo con el punto de venta; inventory_locations_scope_chk impide nombrar ambos) da tres alcances. inventory.issue_location_rules ordena ubicaciones por tipo de movimiento (issue, sales_issue, production_input, waste) para un alcance de organización, unidad de negocio o punto de venta, y opcionalmente por canal y artículo; dos exclusiones gist mantienen una ubicación por rango y un rango por ubicación en el mismo juego de reglas activo. inventory.resolve_issue_locations aplica esta precedencia: el juego de reglas más específico reemplaza al general (punto de venta, unidad de negocio, organización; luego artículo, luego canal), se ordena por rango, omite ubicaciones inactivas, no disponibles o de otra entidad legal; sin regla utilizable devuelve las ubicaciones activas del punto de venta por código, si no las de la unidad, si no nada. Solo resuelve: nunca mueve stock.
D71. El piso de stock reservado se exige al confirmar por el vínculo de consumo, sin lista de tipos de movimiento
Decisión (migración 0134): stock_ledger_reserved_floor_trg es un disparador de restricción diferido que llama a inventory.enforce_reserved_stock_floor: con el modo de stock negativo prevent, al confirmar la existencia cubre la cantidad reservada activa no consumida, por artículo y ubicación y por lote. Una salida de libro está permitida si la cubre su vínculo de consumo (reservation_consumptions, una por asiento y completa, migración 0133), no por una lista de tipos de movimiento: un tipo nuevo no puede saltarse la reserva ni exige tocar el disparador. Al mover needed_on se revalidan el lote y la capacidad a la nueva fecha (0135 y 0136).
Rechazado: una lista de tipos de movimiento exentos, porque cada tipo nuevo la volvía a abrir.
D72. La ruta directa pasa por los planes de consumo (tipo direct): un solo puente de Ventas a stock
Decisión (migraciones 0141 y 0142): production.consumption_plans admite el tipo direct, sin versión de receta y con supply_route_id de una ruta stock; las contribuciones route_line salen de production.direct_plan_requirement. El plan, la reserva y la cantidad pasan por production.supply_order_source, settle_order_supply y cancel_order_supply, que Ventas llama dentro de su propia transacción, y supply_feasible_units da las unidades prometibles. Una ruta recipe devuelve recipe_not_handled y una untracked no crea nada. Las ejecuciones de producción nunca referencian un plan directo, porque su clave foránea exige una versión de receta.
D73. Los escritores de stock son idempotentes por clave, y liberar es idempotente por estado
Decisión (migraciones 0140 y 0142): inventory.reserve_stock y inventory.consume_reservation son idempotentes por organización y clave (la misma clave y la misma solicitud devuelven el mismo resultado; otra solicitud con esa clave se rechaza con 23505), y production.supply_order_source y settle_order_supply derivan claves SHA-256 de longitud fija de la del llamador. inventory.release_reservation no lleva clave: liberar una reserva ya terminada no cambia nada y devuelve lo consumido y lo liberado. Los escritores toman los bloqueos de capacidad inventory.lock_stock_capacity en orden, de modo que dos llamadas con los mismos artículos en otro orden no se bloquean entre sí.
D74. La compuerta de verificación corre como un servicio de Railway de una sola ejecución
Decisión: D15 retiró el runner de GitHub Actions (build-test y sql-regressions) y dejó npm run verify y npm run db:test como disciplina local. La compuerta completa ahora también puede correr como el servicio gate-runner, declarado solo en staging en .railway/railway.ts: construye tooling/gate/Dockerfile desde la rama gate/run, levanta su propio PostgreSQL 18 desechable con colación ICU, corre db:test, db:fresh más db:test:prepare y npm run verify, imprime NINAKU_GATE_STEP por paso y NINAKU_GATE_RESULT OK|FAILED <sha>, y termina (restartPolicyType: NEVER, tope de 90 minutos) para no facturar en reposo. No tiene variables ni referencias a la base de staging ni a otros servicios.
Rechazado: reponer los workflows pesados de GitHub Actions, porque consumen los 2,000 minutos mensuales del plan gratuito que se reservan para la promoción a producción; y correr la compuerta contra la base de staging, porque db:test y db:fresh recrean bases. No es una compuerta que bloquee fusiones: sigue sin haber ruleset (D20) y el resultado lo pega quien integra en la PR. Queda fuera de la primera versión la comparación de paridad entre staging y la prueba de upgrade.