Skip to content

Application DSL (documento único: pantallas, roles y flujos) ​

El Application DSL es la capa de aplicación que se construye sobre el Entity Manager: un único documento JSON por versión publicada que declara la identidad de la aplicación, sus roles propios (distintos de OWNER/ADMIN/MEMBER/VIEWER de empresa), los planos activos (client_persist, server_process o ambos, no excluyentes), forms, views y flujos — con un layout de widgets del catálogo cerrado y un snapshot de los contratos de entidad en vigor que esa versión usa. Publicar rechaza cualquier referencia a un widget, disparador, condición, acción, entidad, campo o rol que no exista en el documento o en el catálogo de entidades del autor.

Conceptos clave ​

  • Dos catálogos: plataforma y tenant, igual que el Entity Manager — un tenant nunca ve las aplicaciones de otro tenant.
  • Un documento lógico por versión: identidad + roles + planos + forms + views + flujos + el snapshot de los contratos de entidad que esa versión usa (nunca instancias).
  • Ciclo: borrador → PUT del documento (validación estructural en cada guardado) → publish (revalida todo el documento, resuelve/ registra entidades y valida cada referencia contra el contrato resuelto) → versión publicada e inmutable. Un cambio posterior crea una versión nueva (POST .../versions); la publicada no se toca.
  • Catálogos cerrados (ampliarlos es enmienda de spec):
    • Widgets de layout: section, tabs, field, label, table, button.
    • Disparadores de flujo: on_submit, on_click, on_open, on_instance_create, on_instance_update, on_instance_delete.
    • Condiciones de flujo: field (eq/neq/gt/gte/lt/lte/empty/not_empty), actor_has_role, all, any.
    • Acciones de flujo: write_instance, navigate, message.
  • Roles de la app, no de empresa: cada form, view y disparador de usuario declara qué roles de esta aplicación pueden usarlo. Un rol referenciado que no está declarado → rechazo.
  • Planos no excluyentes: el documento declara client_persist, server_process o ambos. Cada form/view/flujo declara qué plano(s) usa, siempre dentro de lo que la app activó. Un flujo que pide run_on both exige que ambos planos estén activos.
  • AccessPolicy: el documento puede declarar accessPolicies[] — un techo por operation (read/write) y entidad (entity: null = toda la app) que solo restringe los planos. El plano efectivo es la intersección de (1) planos activos de la versión, (2) planos que propone la pantalla o el flujo y (3) planos que permite la política aplicable. Una política nunca añade un plano, y si la intersección queda vacía la publicación o la operación se rechaza.
  • Ownership: el documento puede declarar ownershipRules[] — el campo del payload que guarda el id del dueño. El servidor lo fija con el actor autenticado al crear, exige ser dueño para leer/editar y acota los listados a las instancias propias; el cliente nunca puede asignar otro dueño ni aflojar el filtro.
  • ABAC: el documento puede declarar abacRules[] — reglas allow/deny sobre el actor (id, roles de app resueltos en servidor) y campos de la instancia, con un IR de catálogo cerrado (actor_id, actor_has_role, instance_field, all, any). Nunca texto libre de tenant; solo restringe.
  • Forms: una sola entidad, campos con mode: write | display, layout con widgets del catálogo. Un widget field con displayOnly (campo N:1 relacionado, p. ej. owner.name) solo se muestra, nunca se escribe.
  • Views: una sola entidad, mode: list | detail; en modo listado exige un widget table.
  • Identificadores de widget únicos en toda la aplicación (no solo por pantalla).
  • Entidades: cada una referenciada (kind: existing) debe existir ya en el catálogo del autor; o declarada inline (kind: new + schema) — al publicar se registra y publica en el Entity Manager del catálogo del autor, con las mismas reglas de nombre (409 + sugerencias si choca). Las entidades declaradas se limitan al catálogo del propio autor (plataforma o su tenant) — referenciar una entidad de plataforma seguida por el tenant no está cubierto por esta entrega.
  • Chunks eager/lazy: el arranque (GET .../document/eager) trae identidad, roles, planos, forms/views no marcados lazy y los contratos de entidad que usan; los flujos son lazy por defecto salvo que se marquen eager. El resto se pide como chunk (GET .../versions/:version/chunks/:kind/:name) — respuesta { kind, data, applicationId, version } (applicationId/version aditivos a kind/data). Un chunk de otra versión o inexistente → 404, sin filtrar contenido de otras versiones o tenants; el Runtime rechaza al fusionar si applicationId/version no coinciden con el documento cargado; la respuesta es idempotente ante peticiones repetidas.
  • Contexto de ejecución: las rutas HTTP runtime de documento, chunks, persistencia y procesos requieren X-App-Project-Id y X-App-Environment-Id. El backend valida que proyecto, entorno, empresa y aplicación coincidan y resuelve exclusivamente el snapshot del currentRelease asignado a ese entorno. Los chunks deben pedir la versión de ese snapshot; el release anterior deja de servir cuando se retira del entorno. Publicar una versión DSL nueva no cambia por sí solo el runtime de preview ni producción.
  • Límites (Ajustes, cambian solo hacia adelante): 50 forms, 50 views, 20 roles, 50 flujos, 100 widgets por form o view.

Generación asistida por IA (AI-DSL-001) ​

La skill compartible application-dsl.generate-draft permite que un assistant de tenant convierta una petición en lenguaje natural en un borrador Application DSL. La resolución de proveedor, credenciales, límites de uso y consumo pasan por AIService y la gobernanza AI existentes; el modelo no recibe el tenant ni el rol de la sesión.

La operación requiere OWNER/ADMIN y es de solo lectura: valida estructura, límites vigentes, entidades existentes/nuevas y referencias de campos contra el catálogo tenant activo. Devuelve un candidato draft con authorizationInputs pendientes para que pueda abrirse y editarse en el editor. Las policy/rule collections se vacían; los roles en forms/views/triggers se dejan como arrays vacíos y se eliminan las condiciones actor_has_role. Si la validación normal rechaza esos valores vacíos, el candidato se conserva con errores en español para completarlo manualmente. Las políticas, los roles de acceso y las asignaciones quedan en manos de la persona. Incluso cuando la validación estructural pasa, valid=false, publishable=false y reviewRequired=true hasta la revisión humana. El handler nunca guarda, asigna roles ni publica. Facturación, archivos y push solo se pueden proponer cuando exista una operación concreta registrada en el catálogo DSL; el modelo no puede inventar una integración.

Operaciones App Data asistidas (AI-APPDATA-001) ​

Las skills shareables app-data.collection.list, app-data.collection.get, app-data.collection.create y app-data.collection.update invocan el runtime App Data de esta sección. Solo resuelven una app publicada y activa en el tenant autenticado (incluidas apps de plataforma que ese tenant sigue) y requieren el contexto de proyecto/entorno de la conversación autenticada. El servidor trata las cabeceras como selectores y valida tenant, proyecto, entorno y release activo con la misma autorización runtime que las rutas directas; sin ese contexto no cae al catálogo activo ni al namespace administrativo. Cada llamada vuelve a exigir ai_assistants y delega los checks de app role, view/form, plano y seguridad al ApplicationDslService. Los argumentos tienen schemas cerrados; se rechazan propiedades desconocidas y el modelo no puede elegir tenant, empresa, usuario, rol ni entorno. list/get son de lectura; create/update se muestran para revisión y esperan la confirmación explícita existente antes de escribir. No existe operación assistant para borrar ni acceso SQL o a colecciones arbitrarias.

Follow, pin, aceptar y fork ​

Un tenant puede seguir una versión publicada de una aplicación de plataforma sin copiar su documento. El follow ancla una versión concreta (pinnedVersion); publicar vN+1 en plataforma no mueve el pin de los tenants que siguen deben aceptar explícitamente. En cualquier momento el tenant puede hacer fork: copia la versión anclada (documento + contratos de entidad) a su propio catálogo y corta el follow — a partir de ahí es independiente y ya no recibe nada de la app de plataforma.

  • Follow ancla entidades: seguir una app pin-ea automáticamente, en el Entity Manager del tenant, cada entidad de los entityContracts de la versión seguida (mismo mecanismo que POST /entity-manager/tenant/follows, invocado internamente con skipIfExists). Seguir entidades adicionales que la app no declara es un vínculo aparte e independiente — no lo gestiona este endpoint.
  • Roles declarados del follow: la respuesta de follow / list / accept incluye declaredRoleKeys — las keys de roles de la versión anclada — para que el panel de asignación (FE-058) pueda ofrecer un desplegable sin filtrar el documento de plataforma. Solo keys; no labels ni pantallas/flujos.
  • Aceptar: mueve el pin a una versión publicada posterior ({ version? }, por defecto la más reciente) y ancla cualquier entidad nueva que esa versión declare — las ya ancladas no se tocan. Si alguna instancia activa del tenant no cumple el schema de un contrato que la aceptación pondría en vigor, la operación se rechaza con 409 ENTITY_SCHEMA_ACCEPT_BLOCKED + invalidInstances[] (mismas reglas que el accept del Entity Manager; las bajas no bloquean). Sin versión publicada posterior → 400.
  • Fork: copia el documento y los entityContracts de la versión anclada al catálogo del tenant como una definición publicada independiente (forkedFromDefinitionId / forkedFromVersion para trazabilidad) y elimina el follow. No copia instancias. Las entidades ancladas por el follow no se forkean automáticamente — siguen su propio ciclo de vida en Entity Manager.
  • Retiro de plataforma: cuando Super Admin retira (.../versions/:version/retire) una versión global, solo cambia ese registro de plataforma. Si quedan follows tenant anclados, el endpoint devuelve conflicto genérico 409 y no enumera ni modifica follows, asignaciones de roles o datos tenant. Cada OWNER/ADMIN debe hacer un fork manual autorizado desde el ámbito de su empresa antes de reintentar el retiro.
  • Solo aplica a aplicaciones del catálogo de plataforma; una app propia de tenant no se sigue.
  • Fork traslada las asignaciones de roles: el fork manual autorizado mueve, en el mismo paso, las filas de app_dsl_role_assignments que el tenant tenía sobre la app de plataforma a la definición resultante del fork — OWNER/ADMIN no tienen que reasignar nada a mano y no quedan filas huérfanas sobre el id de plataforma. Está acotado por companyId: nunca toca las asignaciones de otro tenant que siga la misma app.

Asignación de roles de la app a miembros ​

Los roles de una app son un modelo propio de esa aplicación, no las asignaciones a personas. OWNER o ADMIN de la empresa asignan y revocan roles de la app a miembros de esa misma empresa — nunca desde el body, siempre desde el contexto del tenant activo (X-Company-Id o JWT). La app referenciada por :id puede ser una app propia del catálogo del tenant o una app de plataforma seguida (follow):

  • Para una app propia, los roles válidos son los de la versión publicada en vigor.
  • Para una app de plataforma seguida, los roles válidos son los de la versión anclada (pinnedVersion) del follow — no la última publicada en plataforma. Las keys disponibles para el desplegable de asignación llegan en declaredRoleKeys del follow, sin filtrar el documento de plataforma.
  • Sin fork no hay forma de redefinir roles de una app de plataforma seguida: el catálogo del tenant nunca contiene la definición de plataforma, así que no existe un borrador sobre el que hacer PUT .../document para ella. Solo se asignan personas a los roles que la versión anclada ya trae. Tras un fork, la copia sí vive en el catálogo del tenant y sus roles se pueden versionar normalmente.
  • Un no miembro de la empresa como destinatario se rechaza con 404.
  • MEMBER o VIEWER no pueden asignar ni revocar — 403, igual que el resto del módulo
  • Un rol no declarado en la versión vigente/anclada se rechaza con 400 (ya validado al publicar para forms/views/flujos; aquí se revalida contra la asignación).
  • Un miembro puede tener varios roles de la misma app a la vez — el uso de pantallas es la unión de esos roles; asignar un rol ya tenido es idempotente (devuelve la fila existente).
  • Ser OWNER/ADMIN/MEMBER/VIEWER de empresa, o tener el permiso de operar instancias del Entity Manager, no concede estas operaciones por sí solo son modelos distintos.
  • Aplicar estos roles en el plano de datos (lecturas/escrituras como app) queda fuera de esta entrega — ver "Fuera de alcance" abajo.
  • Limpieza al salir de la empresa: cuando un miembro deja de pertenecer a la empresa (DELETE /companies/:id/users/:userId), el sistema elimina sus asignaciones de roles de app de esa empresa (consumidor ApplicationDslMemberRemovedListener sobre el evento company.member-removed). Si vuelve a ser miembro más tarde, no recupera roles: hace falta una nueva asignación explícita de OWNER/ADMIN.

Entrega del documento por chunks eager/lazy ​

Quién puede recibir el documento de arranque o un chunk la misma comprobación en ambos endpoints (document/eager y versions/:version/chunks/:kind/:name), no solo OWNER/ADMIN como el resto del módulo:

  • Un Super Admin puede recibir una definición únicamente en el espacio global de plataforma; en espacio tenant necesita una membresía UserCompany activa y los permisos de esa empresa.
  • Un OWNER/ADMIN con membresía activa en el tenant dueño de la app (catálogo propio), o que sigue esa app de plataforma sin haber hecho fork (space=platform + follow activo).
  • Un MEMBER/VIEWER con al menos un rol de la app asignado (reutiliza el almacén de asignaciones de — app_dsl_role_assignments), sea la app propia del tenant o una app de plataforma seguida.
  • Cualquier otro caso en catálogo tenant se rechaza con 403. En catálogo plataforma, un caller no autorizado recibe 404 — el mismo código que un id inexistente — para no filtrar existencia de apps de plataforma (/ residual). Esto es solo la puerta de entrega: no sustituye al persistir o invocar un proceso (planos, fuera de esta entrega — ver abajo).

Validación de publish: publish revalida todo el documento lógico, incluidos los chunks marcados lazy — por ejemplo, un flujo lazy con una acción write_instance que referencia un campo inexistente en el contrato de entidad bloquea la publicación de toda la versión, no solo esa parte. Las condiciones field de un flujo se cruzan además contra los campos declarados del form/view del disparador y contra el contrato de entidad en vigor. El árbol all/any de condiciones no puede superar APPLICATION_DSL_MAX_CONDITION_DEPTH (16, alineado con el Runtime).

La selección del release nunca usa la versión publicada global más reciente en las rutas runtime. Cada petición vuelve a comprobar la membresía actual; los IDs de proyecto/entorno solo seleccionan el contexto y no conceden acceso. Releases de otro tenant, sin asignación activa, con hash distinto o cuyo follow de plataforma ya no está anclado a esa versión se rechazan.

Plano de persistencia de cliente ​

Cuando la versión activa client_persist, el SDK de cliente (o cualquier caller HTTP directo) lee y escribe instancias a través de un form o una view de la versión activa en vigor de la app — nunca contra el Entity Manager directamente. Estas rutas viven bajo tenant/applications/:id/forms/... y tenant/applications/:id/views/..., resuelven :id igual que las asignaciones de rol (app propia del tenant, o app de plataforma seguida vía su pinnedVersion) y aplican, en este orden:

  1. Autenticación (guard global) y tenant resuelto del contexto (X-Company-Id/JWT), nunca de un id enviado por el cliente.
  2. Release activo del proyecto/entorno identificado por X-App-Project-Id y X-App-Environment-Id; su snapshot inmutable fija la versión DSL, contratos de entidad y flows. Si no hay release activo, o se pide un chunk de otra versión, la petición se rechaza. Un client_persist no activo en esa versión → 403.
  3. Rol de app asignado, resuelto en servidor desde app_dsl_role_assignments el cliente nunca envía la lista de roles; si la envía en el cuerpo (p. ej. { "roles": [...] }), se rechaza como campo no declarado, no se ignora silenciosamente . Sin al menos un rol que el form/view declare → 403. Ser OWNER/ADMIN de la empresa, o tener el grant de operar instancias del Entity Manager , no sustituye este rol — son caminos de autorización distintos; un test E2E dedicado prueba ambos caminos en paralelo sobre el mismo MEMBER para que no quede duda de que son independientes.
  4. Campos de escritura del form (POST/PATCH .../forms/:formName/instances[/:id]): el body { payload } debe ser exactamente un subconjunto de los campos declarados mode: write — cualquier campo fuera de esa lista, incluido un widget field displayOnly (N:1 relacionado) , se rechaza con 400 y no persiste nada.
  5. Campos de la view (GET .../views/:viewName/instances[/:id]): la respuesta se proyecta siempre a los campos que la view declara — nunca se devuelve un campo fuera de ese contrato . Un sort/searchFields/filters[].field de la query fuera de esos campos se rechaza con 400 antes de tocar el store; sobre este mismo camino ya aplican, desde la ola el techo de planos de AccessPolicy, ownership, ABAC, Query Security y field-level security/inmutables — ver las secciones dedicadas más abajo.
  6. Schema, aplicado por EntityInstanceService (los mismos métodos que usa el panel Entity Manager: create/update/get/list) — sus twins *AsApplication toman el companyId ya resuelto del contexto y omiten por completo el grant del panel.

Persistir vía Entity Manager directamente, sin pasar por este plano, no cuenta como uso de la app

Tras un create/update exitoso por este plano, el Runtime de cliente (fuera de este módulo, ola O1-RT) puede ejecutar los flujos on_submit de esa pantalla con run_on: client o both usando el documento que ya recibió por document/eager/chunks — este módulo no ejecuta

flujos ni Runtime.

App Data — superficie de colecciones ​

App Data es el alias nombrado, de cara al producto, del plano client_persist anterior — la ola quepromovió el 2026-09-17. El contrato de programación preferente es appData.collection("customers") en el SDK (server y browser) — nunca db ni nada que sugiera acceso SQL directo u Open CRUD. Es una superficie distinta del panel Entity Manager: vive bajo tenant/applications/:id/collections/:collectionName/instances, nunca bajo /entity-manager/....

Una colección es un form (lado escritura) y/o una view (lado lectura) que comparten el mismo nombre declarado en la versión en vigor — por ejemplo, un form "customers" y una view "customers" en el mismo documento forman la colección customers. La resolución del nombre vive en domain/app-data.ts (findCollectionForm/findCollectionView); todo lo demás — autenticación, tenant, versión en vigor, rol de app asignado, contrato de campos de escritura, proyección a los campos de la view, rechazo de query fuera de contrato — es exactamente el mismo camino que client_persist de la sección anterior (domain/client-persist.ts), reutilizado sin duplicar lógica de autorización.

Camino (b), nunca el grant EM: un grant de operar instancias del panel Entity Manager no autoriza ninguna ruta de App Data, exactamente igual que no autoriza client_persist — comparten el mismo Storage Runtime pero son caminos de autorización independientes. test/e2e/application-dsl-app-data.e2e-spec.ts prueba esto explícitamente: un MEMBER con el grant EM pero sin rol de app asignado es rechazado (403) en las cuatro rutas de colección, mientras que el mismo MEMBER sí puede operar vía el panel EM.

El complemento por el lado contrario — y con el stack completo de Storage Security activo — lo prueba test/e2e/application-dsl-storage-security-em-grant.e2e-spec.ts: un MEMBER autorizado solo por su grant de operar instancias del panel EM (sin rol de app, o con el rol que la política deniega) sigue creando, leyendo, actualizando y listando por /entity-manager/** con los mismos valores que el camino (b) rechaza (otro dueño, campo denyWrite, campo inmutable, rol bloqueado por ABAC, listado denegado por Query Security), mientras ese mismo MEMBER es rechazado (403) en las rutas de la app. Es la prueba cruzada de: el plano de app y el grant del panel son autoridades independientes y ninguna contamina a la otra.

Storage Security — AccessPolicy, ownership, ABAC y Query Security: la capa que dejó como punto de extensión aterrizó en la ola (2026-09-18: AccessPolicy; ownership y ABAC; Query Security) y se engancha sobre esta misma resolución de colección y los mismos checks de client-persist.ts en el camino App Data (b) — nunca sobre el grant del panel EM. El create/update/get de colección pasa por el mismo domain/ownership.ts y domain/abac.ts que client_persist, y listCollectionInstances aplica el mismo domain/query-security.ts que listViewInstances (mismo camino de lectura). Ver las secciones AccessPolicy — techo de planos, Ownership — dueño de la instancia, ABAC — reglas sobre actor e instancia y Query Security — restricciones sobre listados más abajo.

Rutas (mismo guard MEMBER/VIEWER a nivel RBAC que client_persist; la autorización real es server-side):

  • POST/PATCH .../collections/:collectionName/instances[/:id] — escritura vía el form de la colección; mismas reglas de assertFormWritePayload que client_persist.
  • GET .../collections/:collectionName/instances[/:id] — lectura vía la view de la colección, proyectada a sus campos declarados; mismas reglas de assertViewQueryFieldsAllowed que client_persist.

SDK: client.appData.collection(applicationId, collectionName) (Node y Browser) devuelve un handle con create/update/get/list, envolviendo esas cuatro rutas — no hay cliente HTTP paralelo.

AccessPolicy — techo de planos ​

La capa Storage Security del plano de aplicación añade un techo adicional de planos sin tocar el grant del panel Entity Manager. El documento puede declarar accessPolicies[]:

json
"accessPolicies": [
  { "operation": "write", "entity": "Thing", "planes": ["client_persist"] },
  { "operation": "read", "entity": null, "planes": ["client_persist", "server_process"] }
]
  • Catálogo cerrado: operation ∈ read/write; entity es null (toda la app) o el nombre de una entidad declarada en la versión; planes ⊆ client_persist/server_process.
  • Solo restringe: el plano efectivo de una operación es la intersección de los planos activos de la versión, los que propone la pantalla o el flujo, y los que permite la política aplicable. Una política nunca puede añadir un plano que la pantalla no propuso o la versión no activó.
  • Intersección vacía → rechazo: al publicar, si el form (escritura), la view (lectura) o un flujo de escritura quedan sin plano, la publicación se rechaza (BadRequest). En una operación, el servidor recalcula la intersección y rechaza (403) si la política no permite el plano que la operación necesita — el cliente nunca es la autoridad.
  • Varias políticas aplicables (una app-wide y una por entidad, p. ej.) componen su techo por intersección, por lo que solo pueden estrecharse entre sí.
  • Punto de enganche: domain/access-policy.ts (cálculo puro) + document.validator.ts (rechazo al publicar) + application-dsl.service.ts (assertAccessPolicyAllowsPlane en las cuatro rutas client_persist/App Data y en processFormSubmit). Se aplica a la misma resolución de colección y checks de client-persist.ts/server-process.ts del camino (b); el grant del panel EM (a) no se consulta ni se modifica.

Ownership — dueño de la instancia ​

El documento puede declarar ownershipRules[] — un catálogo cerrado { entity, ownerField } que dice qué campo del payload guarda el id del usuario dueño de la instancia. entity: null aplica a toda la app; varias reglas aplicables componen como techo (hay que cumplirlas todas).

json
"ownershipRules": [
  { "entity": null, "ownerField": "ownerId" }
]
  • Al crear: el servidor estampa el campo de ownership con el actor autenticado — nunca con lo que envíe el cliente. Si el cliente intenta asignar la instancia a otro dueño, la escritura se rechaza (403), no se sobreescribe en silencio.
  • Al leer/actualizar una instancia existente: el actor debe ser dueño bajo todas las reglas aplicables; si no, 403. El campo de ownership tampoco se puede reasignar a otro dueño en un PATCH.
  • Al listar: el servidor añade un filtro obligatorio de igualdad exacta (ownerField = actorId) a la consulta del cliente — se concatena, nunca reemplaza — así que un listado sobre una entidad con ownership siempre queda acotado a las instancias del actor. Un campo de ownership con varios ids (dueño + participantes) no se puede expresar como predicado en este vocabulario cerrado: se sigue exigiendo en la lectura/edición de una instancia, y un listado solo devuelve las filas cuyo campo sea exactamente el id del actor (fail-closed, sin fuga).
  • Punto de enganche: domain/ownership.ts (reglas puras, sin I/O) llamado desde las rutas client_persist/App Data de application-dsl.service.ts (create/update/get/list) y desde la ejecución de write_instance del plano server_process. Es la misma resolución de colección e idéntico camino (b); el grant del panel EM (a) no se consulta ni se modifica.

ABAC — reglas sobre actor e instancia ​

El documento puede declarar abacRules[] — reglas allow/deny con un IR de catálogo cerrado sobre el actor (resuelto en servidor) y la instancia. No hay texto libre de tenant ni expresiones: el propio formato no tiene dónde alojarlas.

json
"abacRules": [
  {
    "entity": "Lead",
    "effect": "allow",
    "conditions": [
      { "type": "actor_has_role", "role": "agent" },
      { "type": "instance_field", "field": "title", "operator": "eq", "value": "Acme" }
    ]
  }
]
  • Condiciones: actor_id (op eq/neq/in), actor_has_role (los roles de app asignados y resueltos en servidor, — nunca una lista que afirme el cliente), instance_field (eq/neq/gt/gte/lt/lte/empty/not_empty, sobre un campo del payload) y los combinadores all/any. Las condiciones de una regla se combinan con AND y la regla exige al menos una.
  • Decisión: deny gana si alguna regla aplicable coincide; si existen reglas allow aplicables, hace falta que al menos una coincida. Sin reglas aplicables, manda solo el techo de rol de app/planos (las reglas ABAC nunca conceden lo que el modelo de roles no concedía ya).
  • En listados: las reglas que solo dependen del actor se evalúan una vez — si deniegan, el listado entero se rechaza (403); las que referencian campos de instancia se evalúan fila a fila y las que no pasan simplemente no se devuelven, así que una regla solo puede acotar lo listado.
  • Punto de enganche: domain/abac.ts (evaluador puro, sin I/O) llamado desde application-dsl.service.ts en las mismas rutas que ownership (client_persist/App Data, y write_instance del plano server_process). El rol de app que aporta actor_has_role es el mismo asignado en app_dsl_role_assignments, resuelto en servidor.

Query Security — restricciones sobre listados ​

Además del contrato de campos de la view (assertViewQueryFieldsAllowed), el documento puede declarar querySecurityRules[] — un catálogo cerrado que restringe los listados de app (listViewInstances/listCollectionInstances, incluye App Data porque comparte el mismo camino de lectura):

json
"querySecurityRules": [
  { "entity": "Thing", "deny": true },
  {
    "entity": "Customer",
    "requiredFilters": [{ "field": "region", "op": "eq", "value": "us" }]
  }
]
  • deny rechaza el listado entero con 403, independientemente de la view o del techo de AccessPolicy — pero solo el listado: la escritura por form/colección de esa misma entidad sigue intacta, porque Query Security no toca planos ni el resto del camino client_persist.
  • requiredFilters es un catálogo cerrado { field, op, value } con op restringido a eq/in — nunca una expresión de tenant en texto libre. El servidor los añade siempre a la consulta que llegó del cliente (se concatenan, nunca reemplazan): la consulta resuelta aplica ambos conjuntos de filtros con AND, así que el cliente no puede aflojar, quitar ni sobreescribir un filtro obligatorio filtrando el mismo campo por su cuenta.
  • entity: null aplica a toda la app; varias reglas aplicables componen (deny de cualquiera gana; los requiredFilters de todas se unen).
  • Validación de campos en validate/publish: el campo de cada requiredFilter se cruza contra los campos declarados filterable de la entidad en vigor (o una ruta relacionada de un salto reference.field cuyo destino sea filtrable). Un filtro obligatorio sobre un campo no filtrable — o inexistente — se rechaza en validate/publish con 400, en vez de fallar después cada listado de la app en tiempo de ejecución. Esto replica en autoría la misma regla que ya aplica el motor de consultas en listing time (assertQueryAllowed).
  • Punto de enganche: domain/query-security.ts (reglas puras, sin I/O) llamado desde listViewInstances/listCollectionInstances en application-dsl.service.ts, después del contrato de campos de la view y antes de llegar a EntityInstanceService. No es Open CRUD del panel Entity Manager el modelo de consultas del panel no se toca — ni sustituye al techo de planos de AccessPolicy (arriba): Query Security solo acota qué filas puede devolver un listado.

Field-level security e inmutables ​

Más allá del acotado mode: write/display que ya declara cada form, el documento puede declarar fieldSecurityRules[] — un catálogo cerrado que restringe qué campos puede escribir el plano de app y si un campo, una vez escrito, puede volver a cambiar:

json
"fieldSecurityRules": [
  { "entity": "Employee", "field": "salary", "allowRoles": ["manager"] },
  { "entity": "Employee", "field": "internalNotes", "denyWrite": true },
  { "entity": null, "field": "externalId", "immutable": true }
]
  • denyWrite bloquea el campo para el plano de app sin excepción — cualquier payload que lo toque (esté presente en el payload, aunque sea con el mismo valor) se rechaza con 403 y no persiste nada.
  • allowRoles restringe la escritura del campo a los roles de app listados, resueltos en servidor (app_dsl_role_assignments) nunca un rol que afirme el cliente. Un actor sin ninguno de esos roles que toque el campo se rechaza con 403.
  • immutable rechaza una escritura que cambie el valor del campo una vez que ya tiene un valor no vacío. Fijarlo por primera vez (al crear, o al actualizar mientras sigue vacío/ausente) se permite; reenviar el mismo valor es un no-op, no una violación.
  • Una regla nunca obliga a que el campo esté presente — solo restringe una escritura que lo toca. Un campo sin ninguna regla aplicable no cambia de comportamiento.
  • entity: null aplica a toda la app; varias reglas aplicables sobre el mismo campo componen como techo (hay que cumplirlas todas — nunca se ensanchan entre sí).
  • Punto de enganche: domain/field-security.ts (reglas puras, sin I/O) llamado desde application-dsl.service.ts en las mismas rutas que ownership/ABAC (create/update de client_persist y App Data, y write_instance del plano server_process): assertFieldSecurityAllowsWrite corre sobre el payload de escritura antes de estampar ownership; assertImmutableFieldsNotChanged corre en update comparando contra la instancia existente. Es la misma resolución de colección y el mismo camino (b); el grant del panel EM (a) no se consulta ni se modifica.

Plano de procesos de servidor ​

Cuando la versión activa server_process, el cliente invoca POST tenant/applications/:id/forms/:formName/process sobre esa versión en vigor: el backend evalúa condiciones y ejecuta los flujos on_submit de ese form con run_on: server o both, y devuelve las acciones de UI (navigate, message) que esos flujos produjeron. El cliente puede pre-validar antes con el mismo IR (misma semántica de contrato) pero eso nunca sustituye lo que sigue, revalidado siempre en servidor (doble validación):

  1. Autenticación y tenant resueltos del contexto (X-Company-Id/JWT), igual que client_persist — nunca de un id enviado por el cliente.
  2. Versión activa en vigor de esa app para ese tenant (propia o anclada de un follow). Un server_process no activo en esa versión → 403.
  3. El form propone server_process dentro de los planos que la versión activó — una versión con ambos planos activos puede tener screens que solo proponen uno de los dos.
  4. Rol de app asignado que el form declare, resuelto en servidor exactamente igual que client_persist (mismo assertActorHasScreenRole, misma store de asignaciones) el cliente nunca envía la lista de roles.
  5. Campos de escritura del form: el body { payload } debe ser exactamente un subconjunto de los campos mode: write (mismo assertFormWritePayload que client_persist) — cualquier campo no declarado, incluido un intento de enviar roles o valid en el cuerpo, se rechaza con 400 y no se ejecuta ningún flujo.
  6. Selección de flujos elegibles (domain/flow-executor.ts): los on_submit de ese form con run_on: server o both. Un flujo run_on: client nunca se ejecuta aquí.
  7. Rol del disparador: de los flujos elegibles, solo se evalúan los que declaran, en su propio trigger.roles, alguno de los roles ya asignados del actor — varios flujos on_submit del mismo form, cada uno con un rol distinto, pueden coexistir sin pisarse; el que no aplica a este actor simplemente no se dispara (no es un rechazo de toda la petición).
  8. Condiciones (domain/condition-evaluator.ts): evalúa el IR de catálogo (field con eq/neq/gt/gte/lt/lte/empty/not_empty, actor_has_role, all, any) contra los valores del payload ya validado y los roles asignados del actor — sin I/O, sin texto de expresión, sin JavaScript de tenant. Un flujo cuyas condiciones no se cumplen no ejecuta ninguna acción.
  9. Validación de todos los write_instance antes de persistir ninguno (QA fix + , sin infraestructura de transacciones en este proyecto): por cada intento write_instance que las condiciones dejaron pasar, se llama primero a EntityInstanceService.validateAsApplication(companyId, entity, payload, pendingPeers) — el mismo pipeline (schema/payload, unicidad frente a las instancias actuales y a los intents anteriores del mismo lote para la misma entidad, referencias, ficheros) que ejecuta createAsApplication internamente vía un prepareCreate compartido, para que las dos rutas nunca puedan divergir en qué payload es válido. Si cualquier intento falla esa validación, la petición entera rechaza con 400 y no se persiste nada — ni siquiera un intento anterior que sí habría validado por su cuenta. Garantía de unicidad entre intents: dos write_instance sobre la misma entidad que colisionan en un campo único se rechazan en este paso (400) antes de cualquier save(), no en el segundo persist. (Las cascadas de política de relación del Entity Manager sí usan transacción de BD; esto es distinto.)
  10. Ejecución de acciones, en orden, solo tras el paso anterior (domain/flow-executor.ts + EntityInstanceService):
    • write_instance — persiste una instancia de la entidad que la acción declara, con los campos que la propia acción (no el form) declara, tomados del payload ya validado; usa EntityInstanceService.createAsApplication — el mismo camino sin grant de panel que client_persist. El tipo de acción de esta entrega solo soporta creación (no lleva un instanceId a actualizar); ver "Ambigüedades resueltas" abajo.
    • navigate / message — se devuelven tal cual en actions, para que el Runtime los aplique.
    • invoke_resource — solo platform.test.noop, en un flujo runOn: server; el backend lo ejecuta antes de persistir escrituras y registra actor/app/Resource/resultado. No admite entradas, URLs ni código de tenant; devuelve internamente { status: "ok" }. Si falla, responde con error genérico antes de guardar instancias. El resultado no se devuelve al cliente.
    • emit_event — emite un ID estático declarado en document.events; solo se acepta en on_submit con runOn: server. Los listeners on_event también deben ser server y se resuelven dentro de la misma aplicación y versión, en orden de emisión y declaración. El Event no lleva payload: el listener no puede usar condiciones de campos, write_instance ni volver a emitir Events. El dispatch es local y síncrono; un fallo devuelve error, sin transporte distribuido, reintentos ni fanout a clientes.
    • Events son señales internas para flujos, no notificaciones a usuarios. Una notificación dirigida a un cliente usa el canal existente Notifications SSE (GET /notifications/stream) cuando hay audiencia explícita; no existe un puente automático desde Events.
    • Cualquier tipo de acción fuera de write_instance/navigate/message/invoke_resource/emit_event se rechaza explícitamente en ejecución (no se ignora en silencio) — defensa adicional a la validación de catálogo que ya corre en publish. Resources con efectos externos requieren un contrato versionado de atomicidad antes de registrarse.

La respuesta es { actions: FlowUiAction[], createdInstanceIds: string[] } — las acciones en el orden en que las produjeron los flujos ejecutados, y los ids de cualquier instancia creada por un write_instance, también en orden de ejecución.

Riesgo residual aceptado (multi-write_instance sin una sola transacción): el paso 9 elimina el escenario de QA original — un write_instance que ya sabemos inválido nunca deja un write previo persistido, porque todo se valida antes de escribir nada — y también el de (dos intents de la misma entidad con el mismo valor único validando solo contra peers actuales y colisionando en el segundo save()). Lo que no elimina es un fallo a nivel de base de datos entre dos llamadas save() del propio paso 10 (por ejemplo, la conexión se cae justo después de persistir el primer write_instance y antes del segundo): ese flujo aún no envuelve varios creates independientes en una transacción. Es un riesgo aceptado explícitamente, no un defecto pendiente: las superficies de validación (intent inválido o colisión de unicidad entre intents del lote) ya están cerradas. No confundir con las políticas onDelete del Entity Manager, que sí son atómicas.

Un flujo run_on: both puede dispararse por este plano y, por separado, por el Runtime de cliente vía client_persist la app no obliga a elegir un solo plano para toda ella.

Ambigüedades resueltas ​

  • Qué payload se valida y contra qué contrato: el mismo contrato que client_persist — el body del proceso es exactamente el conjunto de campos mode: write del form, no un esquema aparte para el proceso. Reutiliza assertFormWritePayload sin duplicar semántica.
  • Si el endpoint de proceso puede escribir instancias: sí, mediante la acción write_instance de un flujo — nunca directamente desde el body del proceso como hace client_persist. El proceso en sí no persiste nada si ningún flujo elegible lo indica ("persiste si el flujo lo indica").
  • Qué campos escribe write_instance: los que la propia acción declara (action.fields), tomados del payload ya validado por el form — no todos los campos del form ni el body crudo. Un campo que la acción declara pero el payload no trae simplemente se omite (no es un 400): la validación de campos requeridos en la entidad de destino sigue aplicando normalmente en createAsApplication.
  • Actualización vs creación: el catálogo de acciones de esta entrega no incluye un identificador de instancia en write_instance, así que solo crea. Añadir una variante de actualización por id es una ampliación de catálogo (enmienda de spec), no algo implementado aquí.
  • Disparadores distintos de on_submit de form (on_click, on_open, on_instance_create/update/delete) no tienen endpoint de proceso propio en esta entrega — solo especifica el envío de un form al plano de procesos; se deja fuera hasta que una ampliación cubra explícitamente esos disparadores desde este plano.

Fuera de alcance de esta entrega (/004/005/006) ​

  • SDK server/browser y superficie del Dashboard —.
  • Providers externos de Resources, start_flow, transporte distribuido de Events y fanout de Events a clientes están fuera de. Notifications SSE sigue siendo el canal existente para notificaciones dirigidas a clientes con audiencia explícita.

Endpoints ​

Todos requieren Authorization: Bearer <token>. space es platform o tenant.

MétodoRutaQuién
PATCH/application-dsl/:space/applications/:idPlataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN — renombra con { name }; vacío o duplicado → 400, otro catálogo → 404. Actualiza solo metadatos y no altera versiones DSL.
POST/application-dsl/:space/applicationsPlataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN
GET/application-dsl/:space/applicationsIgual
GET/application-dsl/:space/applications/:idIgual — 404 si es de otro catálogo
PUT/application-dsl/:space/applications/:id/documentReemplaza el documento del borrador — 400 si ya está publicado
POST/application-dsl/:space/applications/:id/publishValida todo el documento y publica
POST/application-dsl/:space/applications/:id/versionsCrea un borrador a partir de la versión publicada
GET/application-dsl/:space/applications/:id/repository-exportPlataforma: Super Admin. Tenant: OWNER/ADMIN — artefacto reproducible de repositorio de la versión publicada en vigor (nimoapp.json, documento DSL canónico, bootstrap, lockfile, README, entidades); solo lectura y 400 si el documento almacenado no valida en el backend
POST/application-dsl/:space/applications/:id/repository-export/validateIgual — valida { formatVersion, manifest, files } contra el formato versionado y el validador real del backend; responde { valid, diagnostics } sin escribir nada
GET/application-dsl/:space/applications/:id/document/eagerPlataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN (dueño o que sigue la app), o miembro con ≥1 rol de app asignado documento de arranque de la versión en vigor
GET/application-dsl/:space/applications/:id/versions/:version/chunks/:kind/:nameIgual chunk (kind = form|view|flow) de esa versión exacta
POST/application-dsl/tenant/application-followsOWNER/ADMIN — sigue una app de plataforma ({ definitionId } o { name }); ancla sus entidades; respuesta incluye declaredRoleKeys
GET/application-dsl/tenant/application-followsOWNER/ADMIN — lista los follows del tenant (pinnedVersion, declaredRoleKeys, …)
POST/application-dsl/tenant/application-follows/:followId/acceptOWNER/ADMIN — acepta una versión posterior ({ version? }); actualiza declaredRoleKeys; 409 si instancias activas no cumplen el schema; 400 si no hay versión posterior
POST/application-dsl/tenant/application-follows/:followId/forkOWNER/ADMIN — copia la versión anclada y corta el follow ({ name? })
POST/application-dsl/platform/applications/:id/versions/:version/retireSuper Admin — cambia solo la versión global; conflicto genérico si quedan follows anclados, sin mutar relaciones tenant
POST/application-dsl/tenant/applications/:id/role-assignmentsOWNER/ADMIN — asigna un rol de la app ({ userId, roleKey }) a un miembro; 404 si no es miembro o la app no está activa; 400 si el rol no está declarado
GET/application-dsl/tenant/applications/:id/role-assignmentsOWNER/ADMIN — lista las asignaciones de esa app
DELETE/application-dsl/tenant/applications/:id/role-assignments/:userId/:roleKeyOWNER/ADMIN — revoca una asignación (204, idempotente)
POST/application-dsl/tenant/applications/:id/forms/:formName/instancesOWNER/ADMIN/MEMBER/VIEWER a nivel RBAC; requiere rol de app asignado que el form declare crea una instancia por el plano client_persist; estampa ownership y aplica ABAC
PATCH/application-dsl/tenant/applications/:id/forms/:formName/instances/:instanceIdIgual — actualiza una instancia por el mismo form; exige ser dueño y aplica ABAC
GET/application-dsl/tenant/applications/:id/views/:viewName/instancesIgual, rol que la view declare — lista paginada proyectada a los campos de la view, acotada por ownership, ABAC y Query Security
GET/application-dsl/tenant/applications/:id/views/:viewName/instances/:instanceIdIgual — una instancia proyectada a los campos de la view
POST/application-dsl/tenant/applications/:id/forms/:formName/processOWNER/ADMIN/MEMBER/VIEWER a nivel RBAC; requiere rol de app asignado que el form declare y que el form/versión activen server_process ejecuta los flujos on_submit server/both de ese form y devuelve { actions, createdInstanceIds }

Exportación a repositorio ​

El artefacto que conserva la app editable en un repositorio se define una sola vez en @nimobase/core (repository-format) y lo genera el backend desde la versión publicada en vigor:

nimoapp.json          manifiesto de rutas gestionadas y hashes (incluye su propia ruta)
app.document.json     documento DSL canónico editable — la fuente de verdad
bootstrap.json        qué cargar; referencia el documento y el lockfile
nimoapp.lock.json     versiones runtime exactas (@nimobase/core, runtime, components, sdk)
README.md             generado; declara la fuente de verdad
entities/<nombre>.json  snapshot del contrato de cada entidad
assets/**             assets opcionales declarados en el manifiesto
  • Roundtrip sin pérdidas: app.document.json es el documento tal como lo normalizó el validador del backend; exportar y volver a leerlo reconstruye el mismo documento.
  • Sin secretos: claves con nombre de secreto y valores con forma de credencial se rechazan; el diagnóstico solo informa la ruta, nunca el valor.
  • Dependencias fijadas: solo versiones exactas y del alcance @nimobase/*; rangos y tags se rechazan (NIMOAPP_UNPINNED_DEPENDENCY).
  • Formato inválido produce diagnóstico, no una excepción: versión de esquema no soportada, ruta fuera de managedPaths, hash que no coincide, archivo faltante, entidad con nombre inseguro, bootstrap incoherente o artefacto de otra aplicación.
  • Validado con el backend real: .../repository-export/validate ejecuta además validateApplicationDslDocument; un documento con formato válido que el servidor rechaza devuelve NIMOAPP_BACKEND_DOCUMENT_INVALID (source: backend). No se promete equivalencia de compiladores.
  • Frontera: las dos rutas llevan la etiqueta (internal); no aparecen en OpenAPI público, SDK público, MCP externo ni chat embebible. Son de solo lectura: no publican, crean ni modifican versiones.
  • Transporte interno: el cliente de plataforma es ApplicationRepositoryExportInternalService (@core/services). Nimo autenticado interno usa la capacidad application-repository-export (app-repository-export.get y app-repository-export.validate, ambas read, OWNER/ADMIN, sin confirmación), protegida por el scope nimo:application-repository-export:read. El modelo solo aporta space, id y el artefacto: el tenant y la versión publicada los resuelve el servidor. Un SDK público, un cliente MCP externo, una sesión tenant normal y el widget embebible son rechazados; el allowlist del widget ni siquiera admite marcarlas como públicas.

Ejemplo — definir y publicar ​

http
POST /application-dsl/tenant/applications
Content-Type: application/json

{ "name": "crm-mobile" }
http
PUT /application-dsl/tenant/applications/:id/document
Content-Type: application/json

{
  "document": {
    "roles": [{ "key": "agent", "label": { "es": "Agente" } }],
    "planes": ["client_persist", "server_process"],
    "accessPolicies": [
      { "operation": "read", "entity": null, "planes": ["client_persist"] }
    ],
    "ownershipRules": [
      { "entity": "Lead", "ownerField": "ownerId" }
    ],
    "abacRules": [
      {
        "entity": "Lead",
        "effect": "allow",
        "conditions": [{ "type": "actor_has_role", "role": "agent" }]
      }
    ],
    "entities": [
      { "kind": "new", "name": "Lead", "schema": { "fields": [{ "name": "title", "type": "string", "required": true }, { "name": "ownerId", "type": "string", "required": false }] } }
    ],
    "forms": [
      {
        "name": "CreateLead",
        "entity": "Lead",
        "fields": [{ "fieldName": "title", "mode": "write" }],
        "layout": [
          { "id": "title-field", "type": "field", "order": 1, "label": { "es": "Título" }, "fieldName": "title" }
        ],
        "roles": ["agent"],
        "loading": "eager",
        "planes": ["client_persist", "server_process"]
      }
    ],
    "views": [],
    "flows": []
  }
}
http
POST /application-dsl/tenant/applications/:id/publish

Ejemplo — asignar un rol a un miembro ​

http
POST /application-dsl/tenant/applications/:id/role-assignments
Content-Type: application/json

{ "userId": "<memberId>", "roleKey": "agent" }
http
DELETE /application-dsl/tenant/applications/:id/role-assignments/:userId/agent

Ejemplo — persistir/leer por el plano client_persist ​

http
POST /application-dsl/tenant/applications/:id/forms/CreateLead/instances
Content-Type: application/json

{ "payload": { "title": "Acme" } }
http
GET /application-dsl/tenant/applications/:id/views/LeadsList/instances

Ejemplo — invocar el plano server_process ​

http
POST /application-dsl/tenant/applications/:id/forms/CreateLead/process
Content-Type: application/json

{ "payload": { "title": "Acme" } }
json
{
  "actions": [
    { "type": "message", "text": { "es": "Guardado" } },
    {
      "type": "navigate",
      "target": { "screenType": "view", "screenName": "LeadsList" }
    }
  ],
  "createdInstanceIds": ["9c2b..."]
}