Application DSL (single document: screens, roles and flows)
The Application DSL is the application layer built on top of the Entity Manager: a single JSON document per published version that declares the application's identity, its own roles (distinct from the company's OWNER/ADMIN/MEMBER/VIEWER), the active planes (client_persist, server_process or both, not mutually exclusive), forms, views and flows — with a widget layout from the closed catalogue and a snapshot of the entity contracts in force that the version uses. Publishing rejects any reference to a widget, trigger, condition, action, entity, field or role that does not exist in the document or in the author's entity catalogue.
Key concepts
- Two catalogues: platform and tenant, just like the Entity Manager — a tenant never sees another tenant's applications.
- One logical document per version: identity + roles + planes + forms + views + flows + the snapshot of the entity contracts that version uses (never instances).
- Cycle: draft → document
PUT(structural validation on every save) →publish(revalidates the whole document, resolves/registers entities and validates every reference against the resolved contract) → published and immutable version. A later change creates a new version (POST .../versions); the published one is untouched. - Closed catalogues (widening them is a spec amendment):
- Layout widgets:
section,tabs,field,label,table,button. - Flow triggers:
on_submit,on_click,on_open,on_instance_create,on_instance_update,on_instance_delete. - Flow conditions:
field(eq/neq/gt/gte/lt/lte/empty/not_empty),actor_has_role,all,any. - Flow actions:
write_instance,navigate,message.
- Layout widgets:
- App roles, not company roles: every form, view and user trigger declares which roles of this application may use it. A referenced role that is not declared → rejection.
- Non-exclusive planes: the document declares
client_persist,server_processor both. Every form/view/flow declares which plane(s) it uses, always within what the app activated. A flow requestingrun_onbothrequires both planes to be active. - AccessPolicy: the document may declare
accessPolicies[]— a ceiling peroperation(read/write) and entity (entity: null= the whole app) that only restricts the planes. The effective plane is the intersection of (1) the version's active planes, (2) the planes the screen or flow proposes and (3) the planes the applicable policy allows. A policy never adds a plane, and if the intersection is empty the publication or the operation is rejected. - Ownership: the document may declare
ownershipRules[]— the payload field holding the owner's id. The server stamps it with the authenticated actor on create, requires ownership to read/edit and narrows listings to the actor's own instances; the client can never assign another owner nor loosen the filter. - ABAC: the document may declare
abacRules[]—allow/denyrules over the actor (id, app roles resolved on the server) and instance fields, with a closed-catalogue IR (actor_id,actor_has_role,instance_field,all,any). Never free tenant text; it only restricts. - Forms: a single entity, fields with
mode: write | display, a layout with widgets from the catalogue. Afieldwidget withdisplayOnly(a related N:1 field, e.g.owner.name) is only shown, never written. - Views: a single entity,
mode: list | detail; in list mode it requires atablewidget. - Widget identifiers unique across the whole application (not only per screen).
- Entities: each one referenced (
kind: existing) must already exist in the author's catalogue; or declared inline (kind: new+schema) — on publish it is registered and published in the Entity Manager of the author's catalogue, with the same naming rules (409 + suggestions on a clash). Declared entities are limited to the author's own catalogue (platform or its tenant) — referencing a platform entity followed by the tenant is not covered by this delivery. - Eager/lazy chunks: the boot document (
GET .../document/eager) brings identity, roles, planes, forms/views not marked lazy and the entity contracts they use; flows are lazy by default unless marked eager. The rest is requested as a chunk (GET .../versions/:version/chunks/:kind/:name) — response{ kind, data, applicationId, version }(applicationId/versionadditive tokind/data). A chunk from another version or a nonexistent one → 404, without leaking content from other versions or tenants; the Runtime refuses to merge whenapplicationId/versiondo not match the loaded document; the response is idempotent on repeated requests. - Execution context: the runtime HTTP routes for document, chunks, persistence and processes require
X-App-Project-IdandX-App-Environment-Id. The backend validates that project, environment, company and application match and resolves exclusively the snapshot of thecurrentReleaseassigned to that environment. Chunks must request that snapshot's version; the previous release stops being served when it is retired from the environment. Publishing a new DSL version does not by itself change the preview or production runtime. - Limits (Settings, move forward only): 50 forms, 50 views, 20 roles, 50 flows, 100 widgets per form or view.
AI-assisted generation (AI-DSL-001)
The shareable skill application-dsl.generate-draft lets a tenant assistant turn a natural-language request into an Application DSL draft. Provider resolution, credentials, usage limits and consumption go through AIService and the existing AI governance; the model receives neither the tenant nor the session role.
The operation requires OWNER/ADMIN and is read-only: it validates structure, current limits, existing and new entities, and field references against the active tenant catalogue. It returns a draft candidate with pending authorizationInputs so it can be opened and edited in the editor. The policy and rule collections are emptied; roles in forms/views/triggers are left as empty arrays and actor_has_role conditions are removed. If normal validation rejects those empty values, the candidate is kept with errors so it can be completed manually. Policies, access roles and assignments stay in the person's hands. Even when structural validation passes, valid=false, publishable=false and reviewRequired=true until human review. The handler never saves, assigns roles or publishes. Billing, files and push can only be proposed when a concrete operation is registered in the DSL catalogue; the model cannot invent an integration.
Assisted App Data operations (AI-APPDATA-001)
The shareable skills app-data.collection.list, app-data.collection.get, app-data.collection.create and app-data.collection.update invoke this section's App Data runtime. They only resolve an application published and active in the authenticated tenant (including platform apps that tenant follows) and require the project/environment context of the authenticated conversation. The server treats the headers as selectors and validates tenant, project, environment and active release with the same runtime authorization as the direct routes; without that context it does not fall back to the active catalogue or the administrative namespace. Every call requires ai_assistants again and delegates the app-role, view/form, plane and security checks to ApplicationDslService. The arguments have closed schemas; unknown properties are rejected and the model cannot choose tenant, company, user, role or environment. list/get are reads; create/update are shown for review and wait for the existing explicit confirmation before writing. There is no assistant operation to delete, nor SQL access or access to arbitrary collections.
Follow, pin, accept and fork
A tenant can follow a published version of a platform application without copying its document. The follow pins a specific version (pinnedVersion); publishing vN+1 on the platform does not move the pin of following tenants — they must accept explicitly. At any time the tenant can fork: it copies the pinned version (document + entity contracts) into its own catalogue and cuts the follow — from then on it is independent and receives nothing more from the platform app.
- Following pins entities: following an app automatically pins, in the tenant's Entity Manager, every entity in the followed version's
entityContracts(the same mechanism asPOST /entity-manager/tenant/follows, invoked internally withskipIfExists). Following additional entities the app does not declare is a separate, independent link — this endpoint does not manage it. - The follow's declared roles: the follow / list / accept response includes
declaredRoleKeys— the role keys of the pinned version — so the assignment dashboard can offer a dropdown without leaking the platform document. Keys only; no labels and no screens/flows. - Accepting: moves the pin to a later published version (
{ version? }, the latest by default) and pins any new entity that version declares — already pinned ones are untouched. If any active tenant instance does not satisfy the schema of a contract that acceptance would put in force, the operation is rejected with 409ENTITY_SCHEMA_ACCEPT_BLOCKED+invalidInstances[](same rules as the Entity Manager's accept; soft deletes do not block). With no later published version → 400. - Fork: copies the pinned version's document and
entityContractsinto the tenant catalogue as an independent published definition (forkedFromDefinitionId/forkedFromVersionfor traceability) and removes the follow. It copies no instances. Entities pinned by the follow are not forked automatically — they follow their own lifecycle in the Entity Manager. - Platform retirement: when a Super Admin retires (
.../versions/:version/retire) a global version, only that platform record changes. If tenant follows remain pinned, the endpoint returns a generic 409 conflict and neither enumerates nor modifies follows, role assignments or tenant data. Each OWNER/ADMIN must perform an authorized manual fork from their company's scope before retrying the retirement. - It only applies to applications in the platform catalogue; a tenant's own app is not followed.
- Fork moves role assignments: the authorized manual fork moves, in the same step, the
app_dsl_role_assignmentsrows the tenant had on the platform app to the fork's resulting definition — OWNER/ADMIN have to reassign nothing by hand and no orphan rows are left on the platform id. It is scoped bycompanyId: it never touches another tenant's assignments on the same followed app.
Assigning app roles to members
An app's roles are a model of that application, not the assignments to people. An OWNER or ADMIN of the company assigns and revokes app roles for members of that same company — never from the body, always from the active tenant context (X-Company-Id or JWT). The app referenced by :id may be an app owned by the tenant catalogue or a followed platform app:
- For an owned app, the valid roles are those of the published version in force.
- For a followed platform app, the valid roles are those of the follow's pinned version (
pinnedVersion) — not the latest published on the platform. The keys available for the assignment dropdown arrive in the follow'sdeclaredRoleKeys, without leaking the platform document. - Without a fork there is no way to redefine the roles of a followed platform app: the tenant catalogue never contains the platform definition, so there is no draft on which to
PUT .../documentfor it. You only assign people to the roles the pinned version already carries. After a fork, the copy does live in the tenant catalogue and its roles can be versioned normally. - A recipient who is not a member of the company is rejected with 404.
- MEMBER or VIEWER cannot assign or revoke — 403, like the rest of the module.
- A role not declared in the current/pinned version is rejected with 400 (already validated at publish time for forms/views/flows; here it is revalidated against the assignment).
- A member can hold several roles of the same app at once — screen usage is the union of those roles; assigning an already-held role is idempotent (returns the existing row).
- Being the company's OWNER/ADMIN/MEMBER/VIEWER, or holding the Entity Manager instance-operation permission, does not grant these operations by itself — they are distinct models.
- Applying these roles on the data plane (reads/writes as the app) is outside this delivery — see "Out of scope" below.
- Cleanup on leaving the company: when a member stops belonging to the company (
DELETE /companies/:id/users/:userId), the system deletes their app role assignments for that company (theApplicationDslMemberRemovedListenerconsumer on thecompany.member-removedevent). If they become a member again later, they do not get the roles back: a new explicit OWNER/ADMIN assignment is required.
Document delivery by eager/lazy chunks
Who can receive the boot document or a chunk — the same check on both endpoints (document/eager and versions/:version/chunks/:kind/:name), not just OWNER/ADMIN like the rest of the module:
- A Super Admin can receive a definition only in the global platform space; in tenant space they need an active
UserCompanymembership and that company's permissions. - An OWNER/ADMIN with an active membership in the tenant that owns the app (its own catalogue), or who follows that platform app without having forked (
space=platform+ active follow). - A MEMBER/VIEWER with at least one app role assigned (it reuses the assignment store —
app_dsl_role_assignments), whether the app is the tenant's own or a followed platform app. - Any other case in a tenant catalogue is rejected with 403. In the platform catalogue, an unauthorized caller receives 404 — the same code as a nonexistent id — so platform app existence is not leaked. This is only the delivery gate: it does not replace what happens when persisting or invoking a process (planes, outside this delivery — see below).
Publish validation: publish revalidates the whole logical document, including chunks marked lazy — for example, a lazy flow with a write_instance action referencing a nonexistent field in the entity contract blocks the publication of the entire version, not just that part. A flow's field conditions are also cross-checked against the trigger's form/view declared fields and against the entity contract in force. The condition all/any tree cannot exceed APPLICATION_DSL_MAX_CONDITION_DEPTH (16, aligned with the Runtime).
Release selection never uses the latest globally published version on the runtime routes. Every request rechecks the current membership; project/environment IDs only select the context and grant no access. Releases from another tenant, without an active assignment, with a different hash, or whose platform follow is no longer pinned to that version are rejected.
Client persistence plane
When the active version has client_persist, the client SDK (or any direct HTTP caller) reads and writes instances through a form or a view of the app's active version in force — never against the Entity Manager directly. These routes live under tenant/applications/:id/forms/... and tenant/applications/:id/views/..., resolve :id the same way as role assignments (an app owned by the tenant, or a followed platform app through its pinnedVersion) and apply, in this order:
- Authentication (global guard) and tenant resolved from the context (
X-Company-Id/JWT), never from an id sent by the client. - Active release of the project/environment identified by
X-App-Project-IdandX-App-Environment-Id; its immutable snapshot fixes the DSL version, entity contracts and flows. If there is no active release, or a chunk from another version is requested, the request is rejected. Aclient_persistnot active in that version → 403. - Assigned app role, resolved on the server from
app_dsl_role_assignments— the client never sends the role list; if it sends it in the body (e.g.{ "roles": [...] }), it is rejected as an undeclared field, not silently ignored. Without at least one role the form/view declares → 403. Being the company's OWNER/ADMIN, or holding the Entity Manager instance-operation grant, does not replace this role — they are distinct authorization paths; a dedicated E2E test proves both paths in parallel on the same MEMBER so there is no doubt they are independent. - Form write fields (
POST/PATCH .../forms/:formName/instances[/:id]): the{ payload }body must be exactly a subset of the fields declaredmode: write— any field outside that list, including adisplayOnlyfieldwidget (related N:1), is rejected with 400 and nothing is persisted. - View fields (
GET .../views/:viewName/instances[/:id]): the response is always projected onto the fields the view declares — a field outside that contract is never returned. A query'ssort/searchFields/filters[].fieldoutside those fields is rejected with 400 before touching the store; on this same path, since the O3-SEC wave, the AccessPolicy plane ceiling, ownership, ABAC, Query Security and field-level security/immutables already apply — see the dedicated sections below. - Schema, applied by
EntityInstanceService(the same methods the Entity Manager dashboard uses:create/update/get/list) — its*AsApplicationtwins take thecompanyIdalready resolved from the context and skip the dashboard grant entirely.
Persisting through the Entity Manager directly, without going through this plane, does not count as using the app.
After a successful create/update through this plane, the client Runtime (outside this module, the O1-RT wave) can run that screen's on_submit flows with run_on: client or both using the document it already received through document/eager/chunks — this module runs neither flows nor Runtime.
App Data — collections surface
App Data is the product-facing named alias of the earlier client_persist plane — the O2-APPDATA wave that promoted it on 2026-09-17. The preferred programming contract is appData.collection("customers") in the SDK (server and browser) — never db nor anything suggesting direct SQL access or Open CRUD. It is a surface distinct from the Entity Manager dashboard: it lives under tenant/applications/:id/collections/:collectionName/instances, never under /entity-manager/....
A collection is a form (write side) and/or a view (read side) sharing the same name declared in the version in force — for example, a "customers" form and a "customers" view in the same document form the customers collection. Name resolution lives in domain/app-data.ts (findCollectionForm/findCollectionView); everything else — authentication, tenant, version in force, assigned app role, write field contract, projection onto the view fields, rejection of out-of-contract queries — is exactly the same path as the previous section's client_persist (domain/client-persist.ts), reused without duplicating authorization logic.
Path (b), never the EM grant: a grant to operate instances in the Entity Manager dashboard does not authorize any App Data route, exactly as it does not authorize client_persist — they share the same Storage Runtime but are independent authorization paths. test/e2e/application-dsl-app-data.e2e-spec.ts proves this explicitly: a MEMBER with the EM grant but no assigned app role is rejected (403) on all four collection routes, while the same MEMBER can operate through the EM dashboard.
The complementary side — with the full Storage Security stack active — is proven by test/e2e/application-dsl-storage-security-em-grant.e2e-spec.ts: a MEMBER authorized only by their grant to operate dashboard instances (no app role, or a role the policy denies) still creates, reads, updates and lists through /entity-manager/** with the same values path (b) rejects (another owner, a denyWrite field, an immutable field, a role blocked by ABAC, a listing denied by Query Security), while that same MEMBER is rejected (403) on the app routes. It is the cross proof that the app plane and the dashboard grant are independent authorities and neither contaminates the other.
Storage Security — AccessPolicy, ownership, ABAC and Query Security: the layer the earlier spec left as an extension point landed in the O3-SEC wave (2026-09-18: AccessPolicy; ownership and ABAC; Query Security) and hooks onto this same collection resolution and the same client-persist.ts checks on the App Data path (b) — never onto the EM dashboard grant. Collection create/update/get goes through the same domain/ownership.ts and domain/abac.ts as client_persist, and listCollectionInstances applies the same domain/query-security.ts as listViewInstances (the same read path). See the AccessPolicy — plane ceiling, Ownership — instance owner, ABAC — rules over actor and instance and Query Security — listing restrictions sections below.
Routes (the same MEMBER/VIEWER RBAC-level guard as client_persist; the real authorization is server-side):
POST/PATCH .../collections/:collectionName/instances[/:id]— write through the collection's form; the sameassertFormWritePayloadrules asclient_persist.GET .../collections/:collectionName/instances[/:id]— read through the collection's view, projected onto its declared fields; the sameassertViewQueryFieldsAllowedrules asclient_persist.
SDK: client.appData.collection(applicationId, collectionName) (Node and Browser) returns a handle with create/update/get/list, wrapping those four routes — there is no parallel HTTP client.
AccessPolicy — plane ceiling
The application plane's Storage Security layer adds an additional plane ceiling without touching the Entity Manager dashboard grant. The document may declare accessPolicies[]:
"accessPolicies": [
{ "operation": "write", "entity": "Thing", "planes": ["client_persist"] },
{ "operation": "read", "entity": null, "planes": ["client_persist", "server_process"] }
]- Closed catalogue:
operation∈read/write;entityisnull(the whole app) or the name of an entity declared in the version;planes⊆client_persist/server_process. - It only restricts: the effective plane of an operation is the intersection of the version's active planes, the ones the screen or flow proposes, and the ones the applicable policy allows. A policy can never add a plane the screen did not propose or the version did not activate.
- Empty intersection → rejection: at publish time, if the form (write), the view (read) or a write flow is left with no plane, publication is rejected (
BadRequest). In an operation, the server recomputes the intersection and rejects (403) when the policy does not allow the plane the operation needs — the client is never the authority. - Several applicable policies (an app-wide one and a per-entity one, say) compose their ceiling by intersection, so they can only narrow each other.
- Hook point:
domain/access-policy.ts(pure computation) +document.validator.ts(rejection at publish) +application-dsl.service.ts(assertAccessPolicyAllowsPlaneon the fourclient_persist/App Data routes and inprocessFormSubmit). It applies to the same collection resolution andclient-persist.ts/server-process.tschecks of path (b); the EM dashboard grant (a) is neither consulted nor modified.
Ownership — instance owner
The document may declare ownershipRules[] — a closed { entity, ownerField } catalogue saying which payload field stores the id of the user who owns the instance. entity: null applies to the whole app; several applicable rules compose as a ceiling (all must be satisfied).
"ownershipRules": [
{ "entity": null, "ownerField": "ownerId" }
]- On create: the server stamps the ownership field with the authenticated actor — never with what the client sends. If the client tries to assign the instance to another owner, the write is rejected (
403); it is not silently overwritten. - On read/update of an existing instance: the actor must be the owner under all applicable rules; otherwise
403. The ownership field cannot be reassigned to another owner in aPATCHeither. - On list: the server adds a mandatory exact-equality filter (
ownerField = actorId) to the client's query — it is concatenated, never replaced — so a listing over an entity with ownership is always narrowed to the actor's instances. An ownership field holding several ids (owner + participants) cannot be expressed as a predicate in this closed vocabulary: it is still required when reading or editing one instance, and a listing only returns rows whose field is exactly the actor's id (fail-closed, no leak). - Hook point:
domain/ownership.ts(pure rules, no I/O) called from theclient_persist/App Data routes ofapplication-dsl.service.ts(create/update/get/list) and fromserver_process'swrite_instanceexecution. It is the same collection resolution and the identical path (b); the EM dashboard grant (a) is neither consulted nor modified.
ABAC — rules over actor and instance
The document may declare abacRules[] — allow/deny rules with a closed-catalogue IR over the actor (resolved on the server) and the instance. There is no free tenant text and no expressions: the format itself has nowhere to host them.
"abacRules": [
{
"entity": "Lead",
"effect": "allow",
"conditions": [
{ "type": "actor_has_role", "role": "agent" },
{ "type": "instance_field", "field": "title", "operator": "eq", "value": "Acme" }
]
}
]- Conditions:
actor_id(opeq/neq/in),actor_has_role(app roles assigned and resolved on the server — never a list the client asserts),instance_field(eq/neq/gt/gte/lt/lte/empty/not_empty, over a payload field) and theall/anycombinators. A rule's conditions combine with AND and the rule requires at least one. - Decision:
denywins if any applicable rule matches; if applicableallowrules exist, at least one must match. With no applicable rules, only the app-role/plane ceiling governs (ABAC rules never grant what the role model did not already grant). - In listings: rules depending only on the actor are evaluated once — if they deny, the whole listing is rejected (
403); rules referencing instance fields are evaluated row by row and the ones that do not pass are simply not returned, so a rule can only narrow what is listed. - Hook point:
domain/abac.ts(pure evaluator, no I/O) called fromapplication-dsl.service.tson the same routes as ownership (client_persist/App Data, andserver_process'swrite_instance). The app role feedingactor_has_roleis the same one assigned inapp_dsl_role_assignments, resolved on the server.
Query Security — listing restrictions
Beyond the view field contract (assertViewQueryFieldsAllowed), the document may declare querySecurityRules[] — a closed catalogue restricting app listings (listViewInstances/listCollectionInstances, App Data included because it shares the same read path):
"querySecurityRules": [
{ "entity": "Thing", "deny": true },
{
"entity": "Customer",
"requiredFilters": [{ "field": "region", "op": "eq", "value": "us" }]
}
]denyrejects the whole listing with403, regardless of the view or the AccessPolicy ceiling — but only the listing: writing through the form/collection of that same entity stays intact, because Query Security touches neither planes nor the rest of theclient_persistpath.requiredFiltersis a closed{ field, op, value }catalogue withoprestricted toeq/in— never a free-text tenant expression. The server always adds them to the query that arrived from the client (they are concatenated, never replaced): the resolved query applies both filter sets with AND, so the client cannot loosen, remove or override a mandatory filter by filtering the same field itself.entity: nullapplies to the whole app; several applicable rules compose (denyfrom any wins; therequiredFiltersof all are unioned).- Field validation in validate/publish: each
requiredFilter's field is cross-checked against the entity's declaredfilterablefields in force (or a one-hop related pathreference.fieldwhose target is filterable). A mandatory filter over a non-filterable — or nonexistent — field is rejected invalidate/publishwith400, instead of failing every app listing later at runtime. This replicates at authoring time the same rule the query engine already applies at listing time (assertQueryAllowed). - Hook point:
domain/query-security.ts(pure rules, no I/O) called fromlistViewInstances/listCollectionInstancesinapplication-dsl.service.ts, after the view field contract and before reachingEntityInstanceService. It is not Entity Manager dashboard Open CRUD — the dashboard's query model is untouched — nor does it replace AccessPolicy's plane ceiling (above): Query Security only bounds which rows a listing may return.
Field-level security and immutables
Beyond the narrow mode: write/display each form already declares, the document may declare fieldSecurityRules[] — a closed catalogue restricting which fields the app plane may write and whether a field, once written, may change again:
"fieldSecurityRules": [
{ "entity": "Employee", "field": "salary", "allowRoles": ["manager"] },
{ "entity": "Employee", "field": "internalNotes", "denyWrite": true },
{ "entity": null, "field": "externalId", "immutable": true }
]denyWriteblocks the field for the app plane without exception — any payload touching it (present in thepayload, even with the same value) is rejected with403and nothing is persisted.allowRolesrestricts writing the field to the listed app roles, resolved on the server (app_dsl_role_assignments) — never a role the client asserts. An actor without any of those roles touching the field is rejected with403.immutablerejects a write that changes the field's value once it already has a non-empty one. Setting it for the first time (on create, or on update while still empty/absent) is allowed; resending the same value is a no-op, not a violation.- A rule never forces the field to be present — it only restricts a write that touches it. A field with no applicable rule does not change behaviour.
entity: nullapplies to the whole app; several applicable rules on the same field compose as a ceiling (all must be satisfied — they never widen each other).- Hook point:
domain/field-security.ts(pure rules, no I/O) called fromapplication-dsl.service.tson the same routes as ownership/ABAC (create/updateofclient_persistand App Data, andserver_process'swrite_instance):assertFieldSecurityAllowsWriteruns over the write payload before stamping ownership;assertImmutableFieldsNotChangedruns onupdate, comparing against the existing instance. It is the same collection resolution and the same path (b); the EM dashboard grant (a) is neither consulted nor modified.
Server process plane
When the active version has server_process, the client invokes POST tenant/applications/:id/forms/:formName/process over that version in force: the backend evaluates conditions and runs that form's on_submit flows with run_on: server or both, and returns the UI actions (navigate, message) those flows produced. The client may pre-validate beforehand with the same IR (same contract semantics) but that never replaces what follows, always revalidated on the server (double validation):
- Authentication and tenant resolved from the context (
X-Company-Id/JWT), likeclient_persist— never from an id sent by the client. - Active version in force of that app for that tenant (owned, or pinned from a follow). A
server_processnot active in that version → 403. - The form proposes
server_processwithin the planes the version activated — a version with both planes active can have screens proposing only one of them. - Assigned app role that the form declares, resolved on the server exactly like
client_persist(sameassertActorHasScreenRole, same assignment store) — the client never sends the role list. - Form write fields: the
{ payload }body must be exactly a subset of themode: writefields (the sameassertFormWritePayloadasclient_persist) — any undeclared field, including an attempt to sendrolesorvalidin the body, is rejected with 400 and no flow runs. - Eligible flow selection (
domain/flow-executor.ts): that form'son_submitflows withrun_on: serverorboth. Arun_on: clientflow never runs here. - Trigger role: of the eligible flows, only those declaring, in their own
trigger.roles, one of the actor's already assigned roles are evaluated — severalon_submitflows of the same form, each with a different role, can coexist without clashing; the one that does not apply to this actor simply does not fire (it is not a rejection of the whole request). - Conditions (
domain/condition-evaluator.ts): evaluates the catalogue IR (fieldwitheq/neq/gt/gte/lt/lte/empty/not_empty,actor_has_role,all,any) against the already-validated payload values and the actor's assigned roles — no I/O, no expression text, no tenant JavaScript. A flow whose conditions are not met runs no action. - Validate every
write_instancebefore persisting any (QA fix; there is no transaction infrastructure in this project): for eachwrite_instanceattempt the conditions let through,EntityInstanceService.validateAsApplication(companyId, entity, payload, pendingPeers)is called first — the same pipeline (schema/payload, uniqueness against current instances and against earlier intents of the same batch for the same entity, references, files) thatcreateAsApplicationruns internally through a sharedprepareCreate, so the two paths can never diverge on which payload is valid. If any attempt fails that validation, the whole request is rejected with 400 and nothing is persisted — not even an earlier attempt that would have validated on its own. Uniqueness across intents: twowrite_instancecalls on the same entity colliding on a unique field are rejected in this step (400) before anysave(), not at the second persist. (Entity Manager relation-policy cascades do use a database transaction; this is different.) - Action execution, in order, only after the previous step (
domain/flow-executor.ts+EntityInstanceService):write_instance— persists an instance of the entity the action declares, with the fields the action itself (not the form) declares, taken from the already-validated payload; it usesEntityInstanceService.createAsApplication— the same no-dashboard-grant path asclient_persist. This delivery's action type only supports creation (it carries noinstanceIdto update); see "Resolved ambiguities" below.navigate/message— returned as-is inactions, for the Runtime to apply.invoke_resource— onlyplatform.test.noop, in arunOn: serverflow; the backend runs it before persisting writes and records actor/app/Resource/result. It accepts no tenant inputs, URLs or code; it returns{ status: "ok" }internally. On failure it answers a generic error before saving instances. The result is not returned to the client.emit_event— emits a static ID declared indocument.events; accepted only inon_submitwithrunOn: server.on_eventlisteners must also be server and are resolved within the same application and version, in emission and declaration order. The Event carries no payload: the listener can use no field conditions, nowrite_instanceand cannot emit Events again. Dispatch is local and synchronous; a failure returns an error, with no distributed transport, retries or fanout to clients.- Events are internal signals for flows, not user notifications. A notification aimed at a client uses the existing Notifications SSE channel (
GET /notifications/stream) when there is an explicit audience; there is no automatic bridge from Events. - Any action type outside
write_instance/navigate/message/invoke_resource/emit_eventis explicitly rejected at execution time (it is not silently ignored) — an additional defence to the catalogue validation already running atpublish. Resources with external effects require a versioned atomicity contract before being registered.
The response is { actions: FlowUiAction[], createdInstanceIds: string[] } — the actions in the order the executed flows produced them, and the ids of any instance created by a write_instance, also in execution order.
Accepted residual risk (multi-write_instance without a single transaction): step 9 removes the original QA scenario — a write_instance we already know is invalid never leaves a previous write persisted, because everything is validated before anything is written — and also the scenario of two intents of the same entity with the same unique value validating only against current peers and colliding at the second save(). What it does not remove is a database-level failure between two save() calls of step 10 itself (the connection dropping right after persisting the first write_instance and before the second, say): that flow still does not wrap several independent creates in a transaction. It is an explicitly accepted risk, not a pending defect: the validation surfaces (invalid intent, or a uniqueness collision between intents of the batch) are already closed. Not to be confused with the Entity Manager's onDelete policies, which are atomic.
A run_on: both flow can be triggered by this plane and, separately, by the client Runtime through client_persist — the app does not force choosing a single plane for the whole of it.
Resolved ambiguities
- Which payload is validated and against which contract: the same contract as
client_persist— the process body is exactly the form's set ofmode: writefields, not a separate schema for the process. It reusesassertFormWritePayloadwithout duplicating semantics. - Whether the process endpoint can write instances: yes, through a flow's
write_instanceaction — never directly from the process body the wayclient_persistdoes. The process itself persists nothing unless an eligible flow says so ("it persists if the flow says so"). - Which fields
write_instancewrites: the ones the action itself declares (action.fields), taken from the payload already validated by the form — not every form field nor the raw body. A field the action declares but the payload does not carry is simply omitted (not a 400): required-field validation on the destination entity still applies normally increateAsApplication. - Update vs creation: this delivery's action catalogue includes no instance identifier in
write_instance, so it only creates. Adding an update-by-id variant is a catalogue widening (a spec amendment), not something implemented here. - Triggers other than form
on_submit(on_click,on_open,on_instance_create/update/delete) have no process endpoint of their own in this delivery — the spec only covers submitting a form to the process plane; they are left out until an amendment explicitly covers those triggers from this plane.
Out of scope for this delivery
- The server/browser SDK and the Dashboard surface.
- External Resource providers,
start_flow, distributed Event transport and Event fanout to clients are out of scope. Notifications SSE remains the existing channel for client-directed notifications with an explicit audience.
Endpoints
All require Authorization: Bearer <token>. space is platform or tenant.
| Method | Route | Who |
|---|---|---|
PATCH | /application-dsl/:space/applications/:id | Platform: Super Admin. Tenant: active OWNER/ADMIN member — renames with { name }; empty or duplicate → 400, another catalogue → 404. Updates metadata only and does not alter DSL versions. |
POST | /application-dsl/:space/applications | Platform: Super Admin. Tenant: active OWNER/ADMIN member |
GET | /application-dsl/:space/applications | Same |
GET | /application-dsl/:space/applications/:id | Same — 404 when it belongs to another catalogue |
PUT | /application-dsl/:space/applications/:id/document | Replaces the draft document — 400 when already published |
POST | /application-dsl/:space/applications/:id/publish | Validates the whole document and publishes |
POST | /application-dsl/:space/applications/:id/versions | Creates a draft from the published version |
GET | /application-dsl/:space/applications/:id/repository-export | Platform: Super Admin. Tenant: OWNER/ADMIN — reproducible repository artifact of the published version in force (nimoapp.json, canonical DSL document, bootstrap, lockfile, README, entities); read-only and 400 when the stored document does not validate in the backend |
POST | /application-dsl/:space/applications/:id/repository-export/validate | Same — validates { formatVersion, manifest, files } against the versioned format and the real backend validator; answers { valid, diagnostics } without writing anything |
GET | /application-dsl/:space/applications/:id/document/eager | Platform: Super Admin. Tenant: active OWNER/ADMIN member (owner or following the app), or a member with ≥1 app role assigned — boot document of the version in force |
GET | /application-dsl/:space/applications/:id/versions/:version/chunks/:kind/:name | Same — chunk (kind = form|view|flow) of that exact version |
POST | /application-dsl/tenant/application-follows | OWNER/ADMIN — follows a platform app ({ definitionId } or { name }); pins its entities; the response includes declaredRoleKeys |
GET | /application-dsl/tenant/application-follows | OWNER/ADMIN — lists the tenant's follows (pinnedVersion, declaredRoleKeys, …) |
POST | /application-dsl/tenant/application-follows/:followId/accept | OWNER/ADMIN — accepts a later version ({ version? }); updates declaredRoleKeys; 409 when active instances do not satisfy the schema; 400 when there is no later version |
POST | /application-dsl/tenant/application-follows/:followId/fork | OWNER/ADMIN — copies the pinned version and cuts the follow ({ name? }) |
POST | /application-dsl/platform/applications/:id/versions/:version/retire | Super Admin — changes the global version only; generic conflict when pinned follows remain, without mutating tenant relations |
POST | /application-dsl/tenant/applications/:id/role-assignments | OWNER/ADMIN — assigns an app role ({ userId, roleKey }) to a member; 404 when not a member or the app is not active; 400 when the role is not declared |
GET | /application-dsl/tenant/applications/:id/role-assignments | OWNER/ADMIN — lists that app's assignments |
DELETE | /application-dsl/tenant/applications/:id/role-assignments/:userId/:roleKey | OWNER/ADMIN — revokes an assignment (204, idempotent) |
POST | /application-dsl/tenant/applications/:id/forms/:formName/instances | OWNER/ADMIN/MEMBER/VIEWER at RBAC level; requires an assigned app role the form declares — creates an instance through the client_persist plane; stamps ownership and applies ABAC |
PATCH | /application-dsl/tenant/applications/:id/forms/:formName/instances/:instanceId | Same — updates an instance through the same form; requires ownership and applies ABAC |
GET | /application-dsl/tenant/applications/:id/views/:viewName/instances | Same, role the view declares — paginated listing projected onto the view fields, narrowed by ownership, ABAC and Query Security |
GET | /application-dsl/tenant/applications/:id/views/:viewName/instances/:instanceId | Same — one instance projected onto the view fields |
POST | /application-dsl/tenant/applications/:id/forms/:formName/process | OWNER/ADMIN/MEMBER/VIEWER at RBAC level; requires an assigned app role the form declares and that the form/version activate server_process — runs that form's server/both on_submit flows and returns { actions, createdInstanceIds } |
Repository export
The artifact that keeps the app editable in a repository is defined once in @nimobase/core (repository-format) and generated by the backend from the published version in force:
nimoapp.json manifest of managed paths and hashes (includes its own path)
app.document.json canonical editable DSL document — the source of truth
bootstrap.json what to load; references the document and the lockfile
nimoapp.lock.json exact runtime versions (@nimobase/core, runtime, components, sdk)
README.md generated; declares the source of truth
entities/<name>.json contract snapshot of each entity
assets/** optional assets declared in the manifest- Lossless roundtrip:
app.document.jsonis the document exactly as the backend validator normalized it; exporting and reading it back reconstructs the same document. - No secrets: keys with a secret-like name and values shaped like credentials are rejected; the diagnostic only reports the path, never the value.
- Pinned dependencies: exact versions within the
@nimobase/*scope only; ranges and tags are rejected (NIMOAPP_UNPINNED_DEPENDENCY). - An invalid format produces a diagnostic, not an exception: unsupported schema version, path outside
managedPaths, mismatched hash, missing file, unsafe entity name, incoherent bootstrap or an artifact from another application. - Validated with the real backend:
.../repository-export/validatealso runsvalidateApplicationDslDocument; a document with a valid format that the server rejects returnsNIMOAPP_BACKEND_DOCUMENT_INVALID(source: backend). No compiler equivalence is promised. - Boundary: both routes carry the
(internal)label; they do not appear in public OpenAPI, the public SDK, external MCP or the embeddable chat. They are read-only: they neither publish, create nor modify versions. - Internal transport: the platform client is
ApplicationRepositoryExportInternalService(@core/services). Internal authenticated Nimo uses theapplication-repository-exportcapability (app-repository-export.getandapp-repository-export.validate, bothread, OWNER/ADMIN, no confirmation), protected by thenimo:application-repository-export:readscope. The model only suppliesspace,idand the artifact: the tenant and the published version are resolved by the server. A public SDK, an external MCP client, a normal tenant session and the embeddable widget are rejected; the widget allowlist does not even accept marking them public.
Example — define and publish
POST /application-dsl/tenant/applications
Content-Type: application/json
{ "name": "crm-mobile" }PUT /application-dsl/tenant/applications/:id/document
Content-Type: application/json
{
"document": {
"roles": [{ "key": "agent", "label": { "en": "Agent" } }],
"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": { "en": "Title" }, "fieldName": "title" }
],
"roles": ["agent"],
"loading": "eager",
"planes": ["client_persist", "server_process"]
}
],
"views": [],
"flows": []
}
}POST /application-dsl/tenant/applications/:id/publishExample — assign a role to a member
POST /application-dsl/tenant/applications/:id/role-assignments
Content-Type: application/json
{ "userId": "<memberId>", "roleKey": "agent" }DELETE /application-dsl/tenant/applications/:id/role-assignments/:userId/agentExample — persist/read through the client_persist plane
POST /application-dsl/tenant/applications/:id/forms/CreateLead/instances
Content-Type: application/json
{ "payload": { "title": "Acme" } }GET /application-dsl/tenant/applications/:id/views/LeadsList/instancesExample — invoking the server_process plane
POST /application-dsl/tenant/applications/:id/forms/CreateLead/process
Content-Type: application/json
{ "payload": { "title": "Acme" } }{
"actions": [
{ "type": "message", "text": { "en": "Saved" } },
{
"type": "navigate",
"target": { "screenType": "view", "screenName": "LeadsList" }
}
],
"createdInstanceIds": ["9c2b..."]
}