Skip to content

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.
  • 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_process or both. Every form/view/flow declares which plane(s) it uses, always within what the app activated. A flow requesting run_on both requires both planes to be active.
  • AccessPolicy: the document may declare accessPolicies[] — a ceiling per operation (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/deny rules 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. A field widget with displayOnly (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 a table widget.
  • 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/version additive to kind/data). A chunk from another version or a nonexistent one → 404, without leaking content from other versions or tenants; the Runtime refuses to merge when applicationId/version do 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-Id and X-App-Environment-Id. The backend validates that project, environment, company and application match and resolves exclusively the snapshot of the currentRelease assigned 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 as POST /entity-manager/tenant/follows, invoked internally with skipIfExists). 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 409 ENTITY_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 entityContracts into the tenant catalogue as an independent published definition (forkedFromDefinitionId / forkedFromVersion for 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_assignments rows 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 by companyId: 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's declaredRoleKeys, 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 .../document for 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 (the ApplicationDslMemberRemovedListener consumer on the company.member-removed event). 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 UserCompany membership 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:

  1. Authentication (global guard) and tenant resolved from the context (X-Company-Id/JWT), never from an id sent by the client.
  2. Active release of the project/environment identified by X-App-Project-Id and X-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. A client_persist not active in that version → 403.
  3. 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.
  4. Form write fields (POST/PATCH .../forms/:formName/instances[/:id]): the { payload } body must be exactly a subset of the fields declared mode: write — any field outside that list, including a displayOnly field widget (related N:1), is rejected with 400 and nothing is persisted.
  5. 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's sort/searchFields/filters[].field outside 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.
  6. Schema, applied by EntityInstanceService (the same methods the Entity Manager dashboard uses: create/update/get/list) — its *AsApplication twins take the companyId already 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 same assertFormWritePayload rules as client_persist.
  • GET .../collections/:collectionName/instances[/:id] — read through the collection's view, projected onto its declared fields; the same assertViewQueryFieldsAllowed rules as client_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[]:

json
"accessPolicies": [
  { "operation": "write", "entity": "Thing", "planes": ["client_persist"] },
  { "operation": "read", "entity": null, "planes": ["client_persist", "server_process"] }
]
  • Closed catalogue: operation ∈ read/write; entity is null (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 (assertAccessPolicyAllowsPlane on the four client_persist/App Data routes and in processFormSubmit). It applies to the same collection resolution and client-persist.ts/server-process.ts checks 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).

json
"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 a PATCH either.
  • 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 the client_persist/App Data routes of application-dsl.service.ts (create/update/get/list) and from server_process's write_instance execution. 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.

json
"abacRules": [
  {
    "entity": "Lead",
    "effect": "allow",
    "conditions": [
      { "type": "actor_has_role", "role": "agent" },
      { "type": "instance_field", "field": "title", "operator": "eq", "value": "Acme" }
    ]
  }
]
  • Conditions: actor_id (op eq/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 the all/any combinators. A rule's conditions combine with AND and the rule requires at least one.
  • Decision: deny wins if any applicable rule matches; if applicable allow rules 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 from application-dsl.service.ts on the same routes as ownership (client_persist/App Data, and server_process's write_instance). The app role feeding actor_has_role is the same one assigned in app_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):

json
"querySecurityRules": [
  { "entity": "Thing", "deny": true },
  {
    "entity": "Customer",
    "requiredFilters": [{ "field": "region", "op": "eq", "value": "us" }]
  }
]
  • deny rejects the whole listing with 403, 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 the client_persist path.
  • requiredFilters is a closed { field, op, value } catalogue with op restricted to eq/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: null applies to the whole app; several applicable rules compose (deny from any wins; the requiredFilters of all are unioned).
  • Field validation in validate/publish: each requiredFilter's field is cross-checked against the entity's declared filterable fields in force (or a one-hop related path reference.field whose target is filterable). A mandatory filter over a non-filterable — or nonexistent — field is rejected in validate/publish with 400, 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 from listViewInstances/listCollectionInstances in application-dsl.service.ts, after the view field contract and before reaching EntityInstanceService. 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:

json
"fieldSecurityRules": [
  { "entity": "Employee", "field": "salary", "allowRoles": ["manager"] },
  { "entity": "Employee", "field": "internalNotes", "denyWrite": true },
  { "entity": null, "field": "externalId", "immutable": true }
]
  • denyWrite blocks the field for the app plane without exception — any payload touching it (present in the payload, even with the same value) is rejected with 403 and nothing is persisted.
  • allowRoles restricts 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 with 403.
  • immutable rejects 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: null applies 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 from application-dsl.service.ts on the same routes as ownership/ABAC (create/update of client_persist and App Data, and server_process's write_instance): assertFieldSecurityAllowsWrite runs over the write payload before stamping ownership; assertImmutableFieldsNotChanged runs on update, 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):

  1. Authentication and tenant resolved from the context (X-Company-Id/JWT), like client_persist — never from an id sent by the client.
  2. Active version in force of that app for that tenant (owned, or pinned from a follow). A server_process not active in that version → 403.
  3. The form proposes server_process within the planes the version activated — a version with both planes active can have screens proposing only one of them.
  4. Assigned app role that the form declares, resolved on the server exactly like client_persist (same assertActorHasScreenRole, same assignment store) — the client never sends the role list.
  5. Form write fields: the { payload } body must be exactly a subset of the mode: write fields (the same assertFormWritePayload as client_persist) — any undeclared field, including an attempt to send roles or valid in the body, is rejected with 400 and no flow runs.
  6. Eligible flow selection (domain/flow-executor.ts): that form's on_submit flows with run_on: server or both. A run_on: client flow never runs here.
  7. Trigger role: of the eligible flows, only those declaring, in their own trigger.roles, one of the actor's already assigned roles are evaluated — several on_submit flows 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).
  8. Conditions (domain/condition-evaluator.ts): evaluates the catalogue IR (field with eq/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.
  9. Validate every write_instance before persisting any (QA fix; there is no transaction infrastructure in this project): for each write_instance attempt 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) that createAsApplication runs internally through a shared prepareCreate, 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: two write_instance calls on the same entity colliding on a unique field are rejected in this step (400) before any save(), not at the second persist. (Entity Manager relation-policy cascades do use a database transaction; this is different.)
  10. 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 uses EntityInstanceService.createAsApplication — the same no-dashboard-grant path as client_persist. This delivery's action type only supports creation (it carries no instanceId to update); see "Resolved ambiguities" below.
    • navigate / message — returned as-is in actions, for the Runtime to apply.
    • invoke_resource — only platform.test.noop, in a runOn: server flow; 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 in document.events; accepted only in on_submit with runOn: server. on_event listeners 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, no write_instance and 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_event is explicitly rejected at execution time (it is not silently ignored) — an additional defence to the catalogue validation already running at publish. 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 of mode: write fields, not a separate schema for the process. It reuses assertFormWritePayload without duplicating semantics.
  • Whether the process endpoint can write instances: yes, through a flow's write_instance action — never directly from the process body the way client_persist does. The process itself persists nothing unless an eligible flow says so ("it persists if the flow says so").
  • Which fields write_instance writes: 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 in createAsApplication.
  • 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.

MethodRouteWho
PATCH/application-dsl/:space/applications/:idPlatform: 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/applicationsPlatform: Super Admin. Tenant: active OWNER/ADMIN member
GET/application-dsl/:space/applicationsSame
GET/application-dsl/:space/applications/:idSame — 404 when it belongs to another catalogue
PUT/application-dsl/:space/applications/:id/documentReplaces the draft document — 400 when already published
POST/application-dsl/:space/applications/:id/publishValidates the whole document and publishes
POST/application-dsl/:space/applications/:id/versionsCreates a draft from the published version
GET/application-dsl/:space/applications/:id/repository-exportPlatform: 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/validateSame — 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/eagerPlatform: 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/:nameSame — chunk (kind = form|view|flow) of that exact version
POST/application-dsl/tenant/application-followsOWNER/ADMIN — follows a platform app ({ definitionId } or { name }); pins its entities; the response includes declaredRoleKeys
GET/application-dsl/tenant/application-followsOWNER/ADMIN — lists the tenant's follows (pinnedVersion, declaredRoleKeys, …)
POST/application-dsl/tenant/application-follows/:followId/acceptOWNER/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/forkOWNER/ADMIN — copies the pinned version and cuts the follow ({ name? })
POST/application-dsl/platform/applications/:id/versions/:version/retireSuper Admin — changes the global version only; generic conflict when pinned follows remain, without mutating tenant relations
POST/application-dsl/tenant/applications/:id/role-assignmentsOWNER/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-assignmentsOWNER/ADMIN — lists that app's assignments
DELETE/application-dsl/tenant/applications/:id/role-assignments/:userId/:roleKeyOWNER/ADMIN — revokes an assignment (204, idempotent)
POST/application-dsl/tenant/applications/:id/forms/:formName/instancesOWNER/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/:instanceIdSame — updates an instance through the same form; requires ownership and applies ABAC
GET/application-dsl/tenant/applications/:id/views/:viewName/instancesSame, 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/:instanceIdSame — one instance projected onto the view fields
POST/application-dsl/tenant/applications/:id/forms/:formName/processOWNER/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.json is 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/validate also runs validateApplicationDslDocument; a document with a valid format that the server rejects returns NIMOAPP_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 the application-repository-export capability (app-repository-export.get and app-repository-export.validate, both read, OWNER/ADMIN, no confirmation), protected by the nimo:application-repository-export:read scope. The model only supplies space, id and 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 ​

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": { "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": []
  }
}
http
POST /application-dsl/tenant/applications/:id/publish

Example — assign a role to a member ​

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

Example — persist/read through the client_persist plane ​

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

Example — invoking the server_process plane ​

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

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