@salsita-ai/sdk 0.50.0-develop.eb204e0da4 → 0.50.0-develop.f42416a4e6

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -327,15 +327,49 @@ as restart-required unless their feature documentation explicitly states live-up
 
 Builds the project for production deployment.
 
-| Flag             | Env Variable    | Default | Description                    |
-| ---------------- | --------------- | ------- | ------------------------------ |
-| `--onlyFrontend` | —               | —       | Build only the frontend bundle |
-| `--onlyWebhook`  | —               | —       | Build only webhooks            |
-| `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
-| `--debug`        | `DEBUG`         | `false` | Verbose logging                |
+| Flag              | Env Variable    | Default | Description                                         |
+| ----------------- | --------------- | ------- | --------------------------------------------------- |
+| `--onlyFrontend`  | —               | —       | Build only the frontend bundle                      |
+| `--onlyWebhook`   | —               | —       | Build only webhooks                                 |
+| `--force` / `-f`  | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache                      |
+| `--banner <text>` | —               | —       | Replaces the application line of the banner comment |
+| `--debug`         | `DEBUG`         | `false` | Verbose logging                                     |
 
 The build target can also be controlled via `BUILD_TARGET` env (`frontend`, `webhook`, or `both`).
 
+#### Banner comment
+
+Every JavaScript file the frontend build emits (the configurator, admin and embedded bundles, and the editor's entry and lazy chunks) starts with a comment that identifies the build, so `head -n 5 <bundle.js>` tells two deployed bundles of nearly the same size apart:
+
+```js
+/*!
+ * App version: 1.2.3; Commit: 9fd79ce0f4c1a2b3d4e5f60718293a4b5c6d7e8f
+ * Built with Salsita SDK 3.4.0. Copyright (c) Salsita s.r.o. All rights reserved.
+ * Third-party licences: THIRD-PARTY-LICENSES.txt
+ */
+```
+
+The first line is the application's. By default it holds `applicationVersion` from `spec/application.yaml` and the commit checked out in the project, read with `git rev-parse HEAD`. Where git cannot read a commit for the project (no checkout, git missing or refusing the repository, or the project's `package.json` is not tracked by the repository around it), the line holds the version only and `--debug` logs it; this is the case for a platform build from uploaded sources.
+
+`--banner <text>` replaces that line with your own text, for example when CI knows a release name the spec does not:
+
+```sh
+pnpm phoenix build --banner "Release: ${RELEASE_NAME}; Commit: ${COMMIT_SHA}"
+```
+
+The line is **public**: it ships in every bundle. The default publishes the application version and the commit SHA; pass `--banner ""` to leave the line out, and never put a secret or internal detail in your own text. The text is written as comment text only. Each line of a multi-line value (or each repeated `--banner`) becomes its own comment line and `*/` is written as `*\/`. There is no environment-variable fallback, and the option has no effect on webhook output or with `--onlyWebhook`. Lazy chunks keep their hashed file name when only the banner text changes.
+
+The banner and the licences file below are produced by the application-spec pipeline; the legacy pipeline's build ignores `--banner`.
+
+#### Third-party licences
+
+The frontend build writes `.phoenix/dist/frontend/THIRD-PARTY-LICENSES.txt` next to the bundles and the banner comment points to it. It lists every third-party package whose code or styles are in any of the frontend bundles, once each, sorted by name and version, with the package's version, the licence declared in its `package.json` and the text of its licence file (`LICENSE*`, `LICENCE*` or `COPYING*`). A package that ships no licence file is listed without the text. Your project's own source is not listed.
+
+Deploy the file together with the bundles, so the notices those licences ask for travel with every copy. The build lists licences; it does not judge whether a licence suits your product. Two kinds of package are not in the list, so add their notices yourself when you use them:
+
+- packages used only inside a web worker, which are bundled separately;
+- packages a stylesheet reaches on its own, through CSS `@import`, Sass `@use` or `url()`. A stylesheet imported from JavaScript or TypeScript (`import 'some-font/index.css'`) is listed.
+
 #### Bundle-size budgets
 
 Application-spec projects can set gzip-size limits for the standalone configurator and webhook bundles. Add the optional `budgets` section to a spec YAML file:
@@ -569,9 +603,11 @@ SDK-builder workspaces sign the CLI in with a personal API token instead of proj
 
 Signs the CLI in to the SDK-builder workspace `<customer>`:
 
-1. Opens Studio, where you approve the sign-in (use `--no-open` to only print the link).
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
 2. Studio sends a one-time code back to the CLI on `127.0.0.1`.
-3. The CLI exchanges the code for a token.
+3. The CLI exchanges the code for a token with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
+
+**Deny** in Studio stops the CLI at once: it exits with `The sign-in was denied in Studio` and no token is created. The link works for five minutes and only for the CLI that printed it; after that, Studio shows that it no longer works and the CLI gives up.
 
 The token is stored in `~/.phoenix/credentials.json`, readable only by you, per server, together with the Studio URL of the sign-in; `PHOENIX_CREDENTIALS_FILE` moves the file. The token works until you revoke it. Signing in again to the same server revokes the token it replaces; the CLI warns if the server could not revoke it.
 
@@ -592,28 +628,32 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
-### `phoenix feedback <message>`
+### `phoenix feedback [message]`
 
 Sends feedback about the SDK, the CLI, the documentation or Studio to the Phoenix team. It needs `phoenix login`: the server records the workspace, user and API token of the sign-in, so the message itself needs no introduction.
 
 ```bash
 phoenix feedback "phoenix build reports a missing entity when a module file is empty" --type bug
+phoenix feedback --file report.txt --type bug
 ```
 
-| Flag                   | Env            | Default                       | Description                                          |
-| ---------------------- | -------------- | ----------------------------- | ---------------------------------------------------- |
-| `--type`               | —              | `other`                       | What the feedback is about: `bug`, `idea` or `other` |
-| `--contact`            | —              | —                             | How to reach you, when you want a reply              |
-| `--agent`              | —              | —                             | Name of the coding agent that writes the feedback    |
-| `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about              |
-| `--region`             | —              | `eu`                          | Phoenix region of the workspace: `eu` or `us`        |
-| `--serverUrl` / `-su`  | —              | the region's server           | Phoenix server URL, for a local or custom server     |
+Pass the message as the argument for a short note, or `--file` for a longer report: the content of the file is the message, read as UTF-8, so quotes, backticks and new lines arrive unchanged. Giving both, or neither, is an error.
+
+| Flag                   | Env            | Default                       | Description                                               |
+| ---------------------- | -------------- | ----------------------------- | --------------------------------------------------------- |
+| `--file`               | —              | —                             | Text file that holds the message, instead of the argument |
+| `--type`               | —              | `other`                       | What the feedback is about: `bug`, `idea` or `other`      |
+| `--contact`            | —              | —                             | How to reach you, when you want a reply                   |
+| `--agent`              | —              | —                             | Name of the coding agent that writes the feedback         |
+| `--projectSlug` / `-p` | `PROJECT_SLUG` | `project` of the spec, if any | Workspace project the feedback is about                   |
+| `--region`             | —              | `eu`                          | Phoenix region of the workspace: `eu` or `us`             |
+| `--serverUrl` / `-su`  | —              | the region's server           | Phoenix server URL, for a local or custom server          |
 
-A message holds at most 5000 characters. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; nothing of the project's files is attached. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
+A message holds at most 100,000 characters, from the argument or from the file. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; no file of the project is attached, and the Phoenix team reads a build's sources through the build's page in Studio. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
 
-Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and what must never go into it: secrets, customer data and the project's source. The command needs a server with API 1.40.0 or newer.
+Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
 
 ## Next Steps
 

package/dist/docs/phoenix/project-structure.mdx

@@ -40,6 +40,7 @@ project-root/
 | `components/`   | Phoenix system components (ECS)                                        |
 | `elements/`     | Page elements (pages, providers)                                       |
 | `expressions/`  | Domain logic expressions                                               |
+| `actions/`      | Implementations of the domain actions declared under `actions:`        |
 | `invariants/`   | Domain constraints                                                     |
 | `transformers/` | Data transformation logic                                              |
 | `handlers/`     | Event & lifecycle handlers                                             |
@@ -249,6 +250,7 @@ project-root/
 │   ├── components/                # Phoenix system components (ECS)
 │   ├── elements/                  # UI elements (pages, providers)
 │   ├── expressions/               # Domain logic expressions
+│   ├── actions/                   # Domain action implementations
 │   ├── invariants/                # Domain constraints
 │   ├── transformers/              # Data transformation logic
 │   ├── handlers/                  # Event & lifecycle handlers
@@ -362,6 +364,7 @@ Domain logic files define the business rules and computed properties of your con
 | Purpose      | Location            | Example Files                                  |
 | ------------ | ------------------- | ---------------------------------------------- |
 | Expressions  | `src/expressions/`  | `table.ts`, `legs.ts`, `module.ts`             |
+| Actions      | `src/actions/`      | `move-part.ts`, `swap-cabinets.ts`             |
 | Invariants   | `src/invariants/`   | `top.ts`, `legs.ts`                            |
 | Transformers | `src/transformers/` | `fix-table-top-material-update-transformer.ts` |
 | Migrations   | `src/migrations/`   | `v2.ts`, `v3.ts`, `v4.ts`                      |
@@ -510,7 +513,7 @@ The `application.yaml` file contains global application-level settings. These fi
 | Field                | Type     | Description                                                                                                                                                                                       |
 | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `project`            | `string` | Server project `phoenix dev` develops in: a project slug, or `default` for the default project of the signed-in workspace. Read only by the CLI; overridden by `--projectSlug` and `PROJECT_SLUG` |
-| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant and stored on the deployment record                                                                                          |
+| `applicationVersion` | `string` | Semantic version (`x.y.z`) exported as `ApplicationVersion` constant, stored on the deployment record and named in the banner comment of built bundles                                            |
 | `webComponentTag`    | `string` | Custom HTML web component tag name for embedding                                                                                                                                                  |
 | `pageTitle`          | `string` | Browser page title                                                                                                                                                                                |
 

package/dist/docs/phoenix/sdk-builder-workflow.mdx

@@ -36,11 +36,11 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`phoenix login` opens Studio, where you approve the sign-in. Studio sends a one-time code back to the CLI on `127.0.0.1`, and the CLI exchanges it for a personal token. The code only works for the CLI that asked for it and expires after five minutes. Use `--no-open` to print the link instead of opening a browser.
+`phoenix login` opens Studio, where you name the token and approve the sign-in. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
 
 The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you, with one entry per server. `PHOENIX_CREDENTIALS_FILE` moves the file. The token acts for you in your workspace until you revoke it. It stops working when you are removed from the workspace or banned.
 
-`pnpm phoenix logout` revokes the token and removes it from the file. Studio's **CLI tokens** page lists your tokens with when they were last used, and revokes any of them, for example one left on another computer.
+`pnpm phoenix logout` revokes the token and removes it from the file. Studio's **CLI tokens** page lists your tokens by the names you gave them, with when they were last used, and revokes any of them, for example one left on another computer. A revoked token leaves the list.
 
 `login`, `logout` and `deploy` follow the region, not the `SERVER_URL` in the project's `.env`. `dev` follows the region too when `.env` has no `SERVER_URL`:
 
@@ -94,9 +94,10 @@ Studio's **Builds & deployments** page lists your builds and shows which one you
 Tell us what is broken, confusing or missing, from wherever you are:
 
 - In Studio, **Send beta feedback** in the sidebar opens a short form.
-- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- In the terminal, `pnpm phoenix feedback "<message>" --type bug|idea|other` sends it with your sign-in, and `--file <path>` sends a text file instead of the argument. See the [CLI reference](?path=/docs/phoenix-phoenix-cli--docs).
+- On a build's page in Studio, **Download sources** downloads the archive `phoenix deploy` uploaded for that build, so a report only needs to name the build.
 
-Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. They are told never to include secrets, customer data or your project's source. After a deploy goes live, the agent also asks you, once per conversation, to rate building with Phoenix from 0 to 10; it tells you the answer goes to the Phoenix team, shows the message and sends it only after you approve it.
+Coding agents working in your project use the same command, guided by the generated `phoenix-feedback` skill. They never send on their own: an agent shows you a draft, right away when the problem is crucial and otherwise at the end of the task, and sends it only after you approve it. A report names the build with its Studio page link and the live configurator, says what the agent was doing, what happened and what it expected, quotes the exact error and ends with a condensed conversation log. Agents are told never to include secrets, credentials or personal data; parts of your project and your own words go in only through a draft you approved. When you are done with the configurator, the agent also asks you, once per conversation, to evaluate the run: minutes spent, then scores from 0 to 10 for the agent's guidance, functionality, UX, 3D quality, UI visuals and the overall result, and your comments. It asks one question at a time, never picks a score for you, tells you the answers go to the Phoenix team, shows the message and sends it only after you approve it.
 
 ## Known limits
 

package/dist/domain/actions/action-factory.d.ts

@@ -0,0 +1,10 @@
+import type { ActionImplementations, ActionTypes } from '../core/action.js';
+import type { $DomainEntity, DomainEntity } from '../core/model.js';
+/**
+ * Creates the `implementActions` factory the generated `domain-spec.ts` exposes as
+ * `phx.domain.implementActions`. A module in `src/actions/` implements any subset of the declared
+ * actions and gets each parameter and result typed from the spec; a name the spec does not declare
+ * is a type error, since its implementation would have to be `never`. The generated barrel merges
+ * the modules and checks that every declared action is implemented.
+ */
+export declare const createActionFactory: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes>() => <IMPLEMENTATIONS extends Partial<ActionImplementations<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, ACTION_TYPES>>>(implementations: IMPLEMENTATIONS & Readonly<Record<Exclude<keyof IMPLEMENTATIONS, keyof ACTION_TYPES>, never>>) => IMPLEMENTATIONS;

package/dist/domain/actions/action-factory.js

@@ -0,0 +1 @@
+export const createActionFactory=()=>t=>t;

package/dist/domain/actions/prepare-action-implementations.d.ts

@@ -0,0 +1,15 @@
+import type { ActionDefinitions, AnyActionImplementations } from '../core/index.js';
+/** The declared actions that have no implementation, and the implementations of undeclared names. */
+export interface ActionImplementationConflicts {
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+}
+/** Compares the names of the declared actions with the implemented ones. */
+export declare const findActionImplementationConflicts: (declared: readonly string[], implementations: AnyActionImplementations) => ActionImplementationConflicts;
+/**
+ * Validates the implemented actions against the declared ones, as `prepareDomainExpressions` does
+ * for expressions: a declared action without an implementation throws, so the domain is not
+ * instantiated with an action that can only fail when it is called; an implementation of an
+ * undeclared name is logged. Returns the implementations unchanged.
+ */
+export declare const prepareActionImplementations: (definitions: ActionDefinitions, implementations: AnyActionImplementations) => AnyActionImplementations;

package/dist/domain/actions/prepare-action-implementations.js

@@ -0,0 +1,5 @@
+export const findActionImplementationConflicts=(e,n)=>{let t=Object.keys(n);return{missing:e.filter(e=>!t.includes(e)),extra:t.filter(n=>!e.includes(n))}};export const prepareActionImplementations=(e,n)=>{let{missing:t,extra:i}=findActionImplementationConflicts(Object.values(e).map(e=>e.name),n);if(0===t.length&&0===i.length)return n;let o=Error("Domain cannot be instantiated because there are conflicts between declared and implemented actions."+(t.length>0?`
+
+Missing actions: ${t.join(", ")}. Add each to a default export of phx.domain.implementActions({ ... }) in src/actions/.`:"")+(i.length>0?`
+
+Extra actions: ${i.join(", ")}. Declare each under "actions" in a spec file or remove its implementation.`:"")+"\n");if(t.length>0)throw o;return console.error(o),n};

package/dist/domain/application/application-config.d.ts

@@ -112,7 +112,8 @@ export interface AssistantFieldOptions {
  * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
  * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
  * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
- * writable fields, and absent means none. Consumed by the configurator GraphQL system.
+ * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
+ * declared action it runs, and absent means none. Consumed by the configurator GraphQL system.
  */
 export interface AssistantManifest {
     readonly sdl: string;
@@ -122,6 +123,7 @@ export interface AssistantManifest {
     readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
+    readonly actions?: Readonly<Record<string, string>>;
 }
 export type AdminPagesSpec = {
     readonly presets?: boolean | {

package/dist/domain/application/assistant-mutations.d.ts

@@ -1,9 +1,9 @@
+import type { Localizable } from '@salsita-ai/common/utils';
 import { type StateUpdate } from '../components/updates.js';
-import type { Domain } from '../core/domain.js';
-import { type $DomainEntity, type DomainEntity } from '../core/model.js';
+import type { AnyActionContext } from '../core/action.js';
+import { type DomainEntity } from '../core/model.js';
 import type { DomainState } from '../core/state.js';
 import type { AssistantManifest } from './application-config.js';
-import { type AssistantRecipeContext } from './assistant-recipe-groups.js';
 type AnyDomainState = DomainState<DomainEntity<string>>;
 /**
  * Update tag of user-intended entity deletions, from the configurator's delete controls and the
@@ -12,19 +12,19 @@ type AnyDomainState = DomainState<DomainEntity<string>>;
 export declare const deleteEntityUpdateTag = "deleteEntity";
 /** Update tag of the entity modifications the assistant's `modify<Type>` mutations make. */
 export declare const modifyEntityUpdateTag = "modifyEntity";
-/** The domain of any application, as far as a mutation implementation reads it. */
-type AnyDomain = Domain<DomainEntity<string>, DomainEntity<string>, Record<string, $DomainEntity<DomainEntity<string>>>>;
 /** The arguments of one mutation field, as the GraphQL executor coerced them against the field's schema. */
 export type AssistantMutationArgs = Readonly<Record<string, unknown>>;
 /**
- * What a mutation implementation reads besides its arguments and the state it runs against. The
- * recipe context is what `addChild` and `replaceEntity` read their recipe groups and cook their recipes with, and what
- * `modify<Type>` reads the choices of a field with.
+ * What a mutation implementation reads besides its arguments and the state it runs against: the
+ * manifest, and the context the application's actions run with on that state. The built-ins and the
+ * custom mutations share it, so a built-in reads the domain, the component reader and the recipe
+ * cooker through `action.systems`, the way an action implementation does.
  */
-export interface AssistantMutationContext extends AssistantRecipeContext {
+export interface AssistantMutationContext {
     readonly manifest: AssistantManifest;
-    /** Validates a changed entity against its shape, and reads entities for the result of a field. */
-    readonly domain: Pick<AnyDomain, 'validateEntity' | 'getEntity' | 'get$Entity'>;
+    readonly action: AnyActionContext;
+    /** Resolves a title in the current language, for recipe keys and option names. */
+    readonly resolveLocalizable: (message: Localizable) => string;
 }
 /** The working state a mutation field ran against and the state its applied updates produced. */
 export interface AssistantMutationStateChange {
@@ -56,9 +56,10 @@ export interface AssistantMutationDeclaration {
     readonly implementation: AssistantMutationImplementation;
 }
 /**
- * The declaration resolving a `Mutation` field: a built-in by its name, or the shared modify
- * implementation when the name is `modify` followed by an entity type the manifest declares writable
- * fields for. `undefined` when the configurator has no implementation for the field.
+ * The declaration resolving a `Mutation` field: a built-in by its name, the action a custom mutation
+ * of that name runs, or the shared modify implementation when the name is `modify` followed by an
+ * entity type the manifest declares writable fields for. `undefined` when the configurator has no
+ * implementation for the field.
  */
 export declare const findAssistantMutation: (fieldName: string, manifest: AssistantManifest) => AssistantMutationDeclaration | undefined;
 export {};

package/dist/domain/application/assistant-mutations.js

@@ -1 +1 @@
-import{z as e}from"zod";import{systemUpdateFactory as t}from"../components/updates.js";import{DomainEntityIdSchema as i}from"../core/model.js";import{findAssistantFieldOptions as r,readAssistantFieldOptions as n}from"./assistant-field-options.js";import{assistantAddedEntityIds as o,findAssistantRecipeGroups as a,prepareAssistantRecipeUpdates as s,readAssistantRecipeGroup as d}from"./assistant-recipe-groups.js";export const deleteEntityUpdateTag="deleteEntity";export const modifyEntityUpdateTag="modifyEntity";let l=e.string().regex(new RegExp(i.pattern),'An entity id is the type name, a dash and a number, e.g. "Root-1". Query the current entities and use an id they return.'),p=e.object({id:l}),h=e.object({id:l,delta:e.record(e.unknown())}),u="modify",f=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],y=e=>Array.isArray(e)?e.map(y):"object"!=typeof e||null===e||Array.isArray(e)?e:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,y(t)])),c=e.object({parentId:l,recipeGroupId:e.string(),recipeKey:e.string()}),g=e.object({entityId:l,recipeGroupId:e.string(),recipeKey:e.string()}),m=e=>e.map(e=>`"${e}"`).join(", "),$=[{name:"deleteEntity",implementation:(e,i,{manifest:r})=>{let{id:n}=p.parse(e),o=i.entities.find(e=>e.id===n);if(!o)throw Error(`Entity "${n}" does not exist, so it cannot be deleted. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let a=r.deletableTypes??[];if(!a.includes(o.type))throw Error(`Entity "${n}" is a ${o.type}, which is not deletable. ${a.length>0?`Only entities of these types can be deleted: ${a.join(", ")}.`:"No entity type is deletable."} Delete an entity of a deletable type instead.`);return{updates:[t.EntityDeletion({entityId:o.id,updateTag:"deleteEntity"})],readResult:({previousState:e,state:t})=>{var i;let r;return[o.id,...(i=o.id,r=new Set(t.entities.map(e=>e.id)),e.entities.map(e=>e.id).filter(e=>e!==i&&!r.has(e)))]}}}},{name:"addChild",implementation:(e,t,i)=>{let{parentId:r,recipeGroupId:n,recipeKey:l}=c.parse(e),p=t.entities.find(e=>e.id===r);if(!p)throw Error(`Entity "${r}" does not exist, so nothing can be added to it. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let h=a(i.manifest,"child",p.type),u=h.find(e=>e.groupId===n);if(!u)throw Error(`Entity "${r}" is a ${p.type}, which has no recipe group "${n}". ${h.length>0?`Its recipe groups are: ${m(h.map(({groupId:e})=>e))}.`:`Nothing can be added to a ${p.type}.`} Query "meta { childRecipes { groupId } }" on the entity you want to add to and use a groupId it returns.`);let f=d("child",u,p.id,t,i);if(!f)throw Error(`The recipe group "${n}" is not available on "${r}" right now, so nothing can be added from it. The configurator offers a group only in some states of the configuration. Query "meta { childRecipes { groupId } }" on "${r}" to see the groups it offers now.`);let y=f.recipes.find(e=>e.key===l);if(!y)throw Error(`The recipe group "${n}" on "${r}" has no recipe with the key "${l}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let g=s(y,f,p.id,t,i);return{updates:g,readResult:e=>o(g,p.id,e).map(t=>i.domain.get$Entity(t,e.state))}}},{name:"replaceEntity",implementation:(e,t,i)=>{let{entityId:r,recipeGroupId:n,recipeKey:l}=g.parse(e),p=t.entities.find(e=>e.id===r);if(!p)throw Error(`Entity "${r}" does not exist, so it cannot be replaced. It may have been deleted or replaced by an earlier operation or field; a replaced entity gets a new id. Query the current entities and use an id they return.`);let h=a(i.manifest,"replace",p.type),u=h.find(e=>e.groupId===n);if(!u)throw Error(`Entity "${r}" is a ${p.type}, which has no replace recipe group "${n}". ${h.length>0?`Its replace recipe groups are: ${m(h.map(({groupId:e})=>e))}.`:`A ${p.type} cannot be replaced.`} Query "meta { replaceRecipes { groupId } }" on the entity you want to replace and use a groupId it returns.`);let f=d("replace",u,p.id,t,i);if(!f)throw Error(`The recipe group "${n}" is not available on "${r}" right now, so it cannot be replaced from it. The configurator offers a group only in some states of the configuration. Query "meta { replaceRecipes { groupId } }" on "${r}" to see the groups it offers now.`);let y=f.recipes.find(e=>e.key===l);if(!y)throw Error(`The recipe group "${n}" on "${r}" has no recipe with the key "${l}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let c=s(y,f,p.id,t,i);return{updates:c,readResult:e=>o(c,p.id,e).map(t=>i.domain.get$Entity(t,e.state))}}}];export const findAssistantMutation=(e,i)=>{let o,a,s=$.find(t=>t.name===e);if(s||!e.startsWith(u))return s;let d=e.slice(u.length),l=f(i.writableFields??{},d);return l&&(o=`${u}${d}`,a=Object.keys(l).join(", "),{name:o,implementation:(e,i,s)=>{let{manifest:p,domain:c}=s,{id:g,delta:m}=h.parse(e),$=i.entities.find(e=>e.id===g);if(!$)throw Error(`Entity "${g}" does not exist, so it cannot be modified. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);if($.type!==d)throw Error(`Entity "${g}" is a ${$.type}, but ${o} modifies only ${d} entities. ${f(p.writableFields??{},$.type)?`Use ${u}${$.type} for it instead.`:`${$.type} has no writable fields, so it cannot be modified; pass the id of a ${d}.`}`);let w=Object.entries(m).flatMap(([e,t])=>{let i=f(l,e);return void 0===i?[]:[{field:e,property:i,value:y(t)}]}),b=Object.fromEntries(w.map(({property:e,value:t})=>[e,t]));if(0===Object.keys(b).length)throw Error(`The delta of ${o} is empty, so there is nothing to change on "${g}". Set at least one of its fields: ${a}.`);let E=c.validateEntity({...$,...b});if(!E.success){let e=w.filter(({field:e,property:t})=>e!==t).map(({field:e,property:t})=>`${e} is stored as ${t}`);throw Error(`The delta would make "${g}" an invalid ${d}: ${E.errors.join("; ")}. ${e.length>0?`The messages name stored properties: ${e.join(", ")}. `:""}Nothing was changed. Send values that fit the types and the allowed values the schema describes for these fields.`)}let j=r(p,d);for(let{field:e,value:t}of w){let r=j.find(t=>t.field===e);if(!r?.validate||null===t)continue;let o=n(r,$.id,i,s);if(o&&!o.some(e=>e.value===t))throw Error(`${JSON.stringify(t)} is not a value "${e}" of "${g}" can take right now. ${o.length>0?`The configurator offers these values: ${o.map(e=>JSON.stringify(e.value)).join(", ")}.`:"The configurator offers no value for it in this state."} Nothing was changed. Send one of the offered values; "meta { ${r.edgeName} }" on the entity lists them with their names. When the values depend on another field of this delta, change that field in an earlier mutation field of the same operation.`)}return{updates:[t.DomainEntityModification({entityId:$.id,stateDelta:b,updateTag:"modifyEntity"})],readResult:({state:e})=>c.getEntity($.id,e)?c.get$Entity($.id,e):null}}})};
+import{z as e}from"zod";import{systemUpdateFactory as t}from"../components/updates.js";import{DomainEntityIdSchema as i}from"../core/model.js";import{findAssistantFieldOptions as n,readAssistantFieldOptions as r}from"./assistant-field-options.js";import{assistantAddedEntityIds as o,findAssistantRecipeGroups as a,prepareAssistantRecipeUpdates as s,readAssistantRecipeGroup as d}from"./assistant-recipe-groups.js";export const deleteEntityUpdateTag="deleteEntity";export const modifyEntityUpdateTag="modifyEntity";let l=({action:e,resolveLocalizable:t})=>({componentReader:e.systems.componentReader,recipeCooker:e.systems.recipeCooker,resolveLocalizable:t}),p=e.string().regex(new RegExp(i.pattern),'An entity id is the type name, a dash and a number, e.g. "Root-1". Query the current entities and use an id they return.'),h=e.object({id:p}),c=e.object({id:p,delta:e.record(e.unknown())}),y="modify",u=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],f=e=>Array.isArray(e)?e.map(f):"object"!=typeof e||null===e||Array.isArray(e)?e:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,f(t)])),m=e.object({parentId:p,recipeGroupId:e.string(),recipeKey:e.string()}),g=e.object({entityId:p,recipeGroupId:e.string(),recipeKey:e.string()}),$=e=>e.map(e=>`"${e}"`).join(", "),w=[{name:"deleteEntity",implementation:(e,i,{manifest:n})=>{let{id:r}=h.parse(e),o=i.entities.find(e=>e.id===r);if(!o)throw Error(`Entity "${r}" does not exist, so it cannot be deleted. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let a=n.deletableTypes??[];if(!a.includes(o.type))throw Error(`Entity "${r}" is a ${o.type}, which is not deletable. ${a.length>0?`Only entities of these types can be deleted: ${a.join(", ")}.`:"No entity type is deletable."} Delete an entity of a deletable type instead.`);return{updates:[t.EntityDeletion({entityId:o.id,updateTag:"deleteEntity"})],readResult:({previousState:e,state:t})=>{var i;let n;return[o.id,...(i=o.id,n=new Set(t.entities.map(e=>e.id)),e.entities.map(e=>e.id).filter(e=>e!==i&&!n.has(e)))]}}}},{name:"addChild",implementation:(e,t,i)=>{let{parentId:n,recipeGroupId:r,recipeKey:p}=m.parse(e),h=t.entities.find(e=>e.id===n);if(!h)throw Error(`Entity "${n}" does not exist, so nothing can be added to it. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let c=a(i.manifest,"child",h.type),y=c.find(e=>e.groupId===r);if(!y)throw Error(`Entity "${n}" is a ${h.type}, which has no recipe group "${r}". ${c.length>0?`Its recipe groups are: ${$(c.map(({groupId:e})=>e))}.`:`Nothing can be added to a ${h.type}.`} Query "meta { childRecipes { groupId } }" on the entity you want to add to and use a groupId it returns.`);let u=l(i),f=d("child",y,h.id,t,u);if(!f)throw Error(`The recipe group "${r}" is not available on "${n}" right now, so nothing can be added from it. The configurator offers a group only in some states of the configuration. Query "meta { childRecipes { groupId } }" on "${n}" to see the groups it offers now.`);let g=f.recipes.find(e=>e.key===p);if(!g)throw Error(`The recipe group "${r}" on "${n}" has no recipe with the key "${p}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let w=s(g,f,h.id,t,u);return{updates:w,readResult:e=>o(w,h.id,e).map(t=>i.action.systems.domain.get$Entity(t,e.state))}}},{name:"replaceEntity",implementation:(e,t,i)=>{let{entityId:n,recipeGroupId:r,recipeKey:p}=g.parse(e),h=t.entities.find(e=>e.id===n);if(!h)throw Error(`Entity "${n}" does not exist, so it cannot be replaced. It may have been deleted or replaced by an earlier operation or field; a replaced entity gets a new id. Query the current entities and use an id they return.`);let c=a(i.manifest,"replace",h.type),y=c.find(e=>e.groupId===r);if(!y)throw Error(`Entity "${n}" is a ${h.type}, which has no replace recipe group "${r}". ${c.length>0?`Its replace recipe groups are: ${$(c.map(({groupId:e})=>e))}.`:`A ${h.type} cannot be replaced.`} Query "meta { replaceRecipes { groupId } }" on the entity you want to replace and use a groupId it returns.`);let u=l(i),f=d("replace",y,h.id,t,u);if(!f)throw Error(`The recipe group "${r}" is not available on "${n}" right now, so it cannot be replaced from it. The configurator offers a group only in some states of the configuration. Query "meta { replaceRecipes { groupId } }" on "${n}" to see the groups it offers now.`);let m=f.recipes.find(e=>e.key===p);if(!m)throw Error(`The recipe group "${r}" on "${n}" has no recipe with the key "${p}". Recipes and their keys change with the configuration and with the language. List the recipes of the group again and use a key it returns.`);let w=s(m,f,h.id,t,u);return{updates:w,readResult:e=>o(w,h.id,e).map(t=>i.action.systems.domain.get$Entity(t,e.state))}}}];export const findAssistantMutation=(e,i)=>{let o,a,s=w.find(t=>t.name===e),d=u(i.actions??{},e);if(s)return s;if(void 0!==d)return{name:e,implementation:(e,t,{action:i})=>i.systems.actionSystem.prepareAction(d,f(e),t)};if(!e.startsWith(y))return;let p=e.slice(y.length),h=u(i.writableFields??{},p);return h&&(o=`${y}${p}`,a=Object.keys(h).join(", "),{name:o,implementation:(e,i,s)=>{let{manifest:d}=s,{domain:m}=s.action.systems,{id:g,delta:$}=c.parse(e),w=i.entities.find(e=>e.id===g);if(!w)throw Error(`Entity "${g}" does not exist, so it cannot be modified. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);if(w.type!==p)throw Error(`Entity "${g}" is a ${w.type}, but ${o} modifies only ${p} entities. ${u(d.writableFields??{},w.type)?`Use ${y}${w.type} for it instead.`:`${w.type} has no writable fields, so it cannot be modified; pass the id of a ${p}.`}`);let b=Object.entries($).flatMap(([e,t])=>{let i=u(h,e);return void 0===i?[]:[{field:e,property:i,value:f(t)}]}),E=Object.fromEntries(b.map(({property:e,value:t})=>[e,t]));if(0===Object.keys(E).length)throw Error(`The delta of ${o} is empty, so there is nothing to change on "${g}". Set at least one of its fields: ${a}.`);let j=m.validateEntity({...w,...E});if(!j.success){let e=b.filter(({field:e,property:t})=>e!==t).map(({field:e,property:t})=>`${e} is stored as ${t}`);throw Error(`The delta would make "${g}" an invalid ${p}: ${j.errors.join("; ")}. ${e.length>0?`The messages name stored properties: ${e.join(", ")}. `:""}Nothing was changed. Send values that fit the types and the allowed values the schema describes for these fields.`)}let v=n(d,p);for(let{field:e,value:t}of b){let n=v.find(t=>t.field===e);if(!n?.validate||null===t)continue;let o=r(n,w.id,i,l(s));if(o&&!o.some(e=>e.value===t))throw Error(`${JSON.stringify(t)} is not a value "${e}" of "${g}" can take right now. ${o.length>0?`The configurator offers these values: ${o.map(e=>JSON.stringify(e.value)).join(", ")}.`:"The configurator offers no value for it in this state."} Nothing was changed. Send one of the offered values; "meta { ${n.edgeName} }" on the entity lists them with their names. When the values depend on another field of this delta, change that field in an earlier mutation field of the same operation.`)}return{updates:[t.DomainEntityModification({entityId:w.id,stateDelta:E,updateTag:"modifyEntity"})],readResult:({state:e})=>m.getEntity(w.id,e)?m.get$Entity(w.id,e):null}}})};

package/dist/domain/core/action.d.ts

@@ -0,0 +1,67 @@
+import type { ExtendedJsonSchema } from '@salsita-ai/common/utils';
+import type { StateUpdate, UpdateFactory } from '../components/updates.js';
+import type { DomainContextSystems } from '../domain-context/domain-context-systems.js';
+import type { IdSequence } from '../domain-context/store-system/next-domain-entity-id.js';
+import type { ExpressionContext } from './expression.js';
+import type { $DomainEntity, DomainEntity } from './model.js';
+import type { DomainState } from './state.js';
+/**
+ * The parameter and result types of the actions an application declares under `actions`, keyed by
+ * action name. Codegen derives it from the spec; `ActionSystem.prepareAction` and the
+ * `implementActions` factory are typed against it.
+ */
+export type ActionTypes = Record<string, {
+    readonly params: unknown;
+    readonly result: unknown;
+}>;
+/**
+ * One action as the spec declares it, carried into the domain factory by the generated code:
+ * `params` is the AJV-ready object schema of its parameters, which `prepareAction` validates the
+ * arguments against before the implementation runs, and `description` says what the action does.
+ */
+export interface ActionDefinition {
+    readonly name: string;
+    readonly description?: string;
+    readonly params: ExtendedJsonSchema;
+}
+/** The declared actions of an application by name; empty when the spec declares none. */
+export type ActionDefinitions = Readonly<Record<string, ActionDefinition>>;
+/** The working state an action ran against and the state its applied updates produced. */
+export interface ActionStateChange<ENTITIES extends DomainEntity<string>> {
+    readonly previousState: DomainState<ENTITIES>;
+    readonly state: DomainState<ENTITIES>;
+}
+/**
+ * What one action prepares: the updates it wants applied, computed from the state it ran against,
+ * and how to read its result from the change they made, including whatever the transformers added.
+ * Nothing is staged or committed; the caller decides what to do with the updates.
+ */
+export interface PreparedAction<ENTITIES extends DomainEntity<string>, RESULT> {
+    readonly updates: ReadonlyArray<StateUpdate<ENTITIES, ENTITIES>>;
+    readonly readResult: (change: ActionStateChange<ENTITIES>) => RESULT;
+}
+/**
+ * What an action implementation reads besides its parameters and the state: the expression context
+ * (domain, data, projections), the domain systems, an id sequence for entities it creates, and the
+ * update factory typed for the application's entities.
+ */
+export interface ActionContext<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> {
+    readonly expressionContext: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
+    readonly systems: DomainContextSystems<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>;
+    readonly getIdSequence: () => IdSequence<ENTITIES>;
+    readonly updates: UpdateFactory<ENTITIES>;
+}
+export type AnyActionContext = ActionContext<any, any, any, any, any, any, any, any, any, any>;
+/**
+ * The implementation of one declared action. It must not change anything itself; a thrown error
+ * fails the call, and its message reaches whoever asked for the action, so it says what went wrong
+ * and how to fix the request.
+ */
+export type ActionImplementation<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, PARAMS, RESULT> = (params: PARAMS, state: DomainState<ENTITIES>, context: ActionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>) => PreparedAction<ENTITIES, RESULT>;
+export type AnyActionImplementation = ActionImplementation<any, any, any, any, any, any, any, any, any, any, any, unknown>;
+/** The implementations of every declared action by name, as the generated barrel merges them from `src/actions/`. */
+export type ActionImplementations<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes> = {
+    readonly [NAME in keyof ACTION_TYPES]: ActionImplementation<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, ACTION_TYPES[NAME]['params'], ACTION_TYPES[NAME]['result']>;
+};
+/** The action implementations of an application with their types erased, as the runtime spec slice holds them. */
+export type AnyActionImplementations = Readonly<Record<string, AnyActionImplementation>>;

package/dist/domain/core/action.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/core/domain-factory.d.ts

@@ -1,4 +1,5 @@
 import type { ExtendedJsonSchema } from '@salsita-ai/common/utils';
+import type { ActionDefinitions, AnyActionImplementations } from './action.js';
 import type { Expression } from './expression.js';
 import type { MigrateFunction } from './migrations.js';
 import type { $DomainEntity, DomainEntity, EntityByType } from './model.js';
@@ -25,6 +26,9 @@ export interface DomainFactoryContext<ENTITIES extends DomainEntity<string>, ALL
     frontendData: SchemaOfObject<FRONTEND_DATA>;
     backendData: ExtendedJsonSchema | undefined;
     isAdminDomain: boolean;
+    /** The actions the spec declares, and their implementations from `src/actions/`; both empty for a domain without actions. */
+    actions: ActionDefinitions;
+    actionImplementations: AnyActionImplementations;
 }
 export type AnyDomainFactory = DomainFactory<any, any, any, any, any, any>;
 export declare class DomainFactory<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, _$MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>> {

package/dist/domain/core/index.d.ts

@@ -1,4 +1,5 @@
 export type { EnhancedJsonObjectSchemaType, EnhancedJsonSchemaType, JsonSchemaType, MemberImport, } from './enhanced-json-schema.js';
+export type { ActionContext, ActionDefinition, ActionDefinitions, ActionImplementation, ActionImplementations, ActionStateChange, ActionTypes, AnyActionContext, AnyActionImplementation, AnyActionImplementations, PreparedAction, } from './action.js';
 export { extendedSchemaValidator, getExtendedSchemaValidator } from './json-schema.js';
 export { _unsafeBuildDomainEntityId, domainEntityTypeFromId, createVirtualEntityId, isDomainEntityId, isVirtualEntityId, VirtualEntityIdSchema, isEqualEntityTypeAndId, parseDomainEntityId, DomainEntityIdSchema, DomainEntitySchema, $DomainEntitySchema, } from './model.js';
 export type { $DomainEntity, DomainEntity, VirtualEntityId, DomainEntityId, EntityIdSchema, EntityByType, EntityId, } from './model.js';

package/dist/domain/domain-builder.d.ts

@@ -1,4 +1,5 @@
 import { type ExtendedJsonSchema } from '@salsita-ai/common/utils';
+import type { ActionDefinition, AnyActionImplementations } from './core/action.js';
 import { type AliasMap, type ExpandAlias, type TypeOrAlias } from './core/alias.js';
 import type { AnonymousExpression } from './core/expression.js';
 import { DomainFactory } from './core/index.js';
@@ -24,10 +25,16 @@ export declare class DomainBuilder<ENTITIES extends DomainEntity<string>, ALLOWE
     private readonly backendData;
     private readonly migrate;
     private readonly isAdminDomain;
+    private readonly actions;
+    private readonly actionImplementations;
     private constructor();
     static from<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ALIASES extends Readonly<Record<string, ENTITIES>>>(entities: EntityReflections<ENTITIES>, aliasMap: AliasMap<ALIASES>, $entityReflections: $EntityReflections<ENTITIES>, allowedRootEntityTypes: ReadonlyArray<ALLOWED_ROOT_ENTITIES['type']>, modelVersion: number, publishedData: SchemaOfObject<PUBLISHED_DATA>, sessionData: SchemaOfObject<SESSION_DATA>, frontendData: SchemaOfObject<FRONTEND_DATA>, backendData: ExtendedJsonSchema | undefined, isAdminDomain: boolean): DomainBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, ALIASES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
     withMigrate(migration: MigrateFunction<ENTITIES>): DomainBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, ALIASES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
     withExpressions(implementation: AliasedExpressions<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES>): DomainBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, ALIASES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
+    /** Declares the actions of the domain, as the generated `domain-spec.ts` reads them from the spec's `actions` section. */
+    withActions(actions: readonly ActionDefinition[]): DomainBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, ALIASES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
+    /** Adds the implementations of the declared actions, as the generated barrel merges them from `src/actions/`. */
+    withActionImplementations(implementations: AnyActionImplementations): DomainBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, ALIASES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
     build: () => DomainFactory<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
 }
 export {};

package/dist/domain/domain-builder.js

@@ -1 +1 @@
-import{expandAlias as i}from"./core/alias.js";import{DomainFactory as t}from"./core/index.js";import{MigrateFunctionBuilder as e}from"./core/migrations.js";import{withProfilerLabel as s}from"./utils/profiler-label.js";export class DomainBuilder{entities;aliasMap;$entityReflections;allowedRootEntityTypes;implemented;modelVersion;publishedData;sessionData;frontendData;backendData;migrate;isAdminDomain;constructor(i,t,e,s,a,n,o,l,r,h,d,m){this.entities=i,this.aliasMap=t,this.$entityReflections=e,this.allowedRootEntityTypes=s,this.implemented=a,this.modelVersion=n,this.publishedData=o,this.sessionData=l,this.frontendData=r,this.backendData=h,this.migrate=d,this.isAdminDomain=m}static from(i,t,s,a,n,o,l,r,h,d){let m=e.fromVersions({1:i}).to(1).using({}).build();return new DomainBuilder(i,t,s,a,{},n,o,l,r,h,m,d)}withMigrate(i){return new DomainBuilder(this.entities,this.aliasMap,this.$entityReflections,this.allowedRootEntityTypes,this.implemented,this.modelVersion,this.publishedData,this.sessionData,this.frontendData,this.backendData,i,this.isAdminDomain)}withExpressions(t){let e={...this.implemented};return Object.entries(t).forEach(([t,a])=>{i(this.aliasMap,t).forEach(i=>{let n={...e[i]};e[i]=n,Object.entries(a).forEach(([e,a])=>{let o=n[e];if(o)throw Error(`Duplicate expression ${i}.${e}: The expression is defined on both ${t} and ${o.origin.typeOrAlias}, which would lead to ambiguous usage. Please ensure that expressions are only defined once.`);n[e]={...a,evaluate:s(`${i}_${e}`,a.evaluate),origin:{name:e,typeOrAlias:t}}})})}),new DomainBuilder(this.entities,this.aliasMap,this.$entityReflections,this.allowedRootEntityTypes,e,this.modelVersion,this.publishedData,this.sessionData,this.frontendData,this.backendData,this.migrate,this.isAdminDomain)}build=()=>{let i=this.implemented,s=this.migrate??e.fromVersions({1:this.entities}).to(1).using({}).build();return new t({aliasMap:this.aliasMap,entityReflections:this.entities,$entityReflections:this.$entityReflections,expressions:i,allowedRootEntityTypes:this.allowedRootEntityTypes,modelVersion:this.modelVersion,migrate:s,publishedData:this.publishedData,sessionData:this.sessionData,frontendData:this.frontendData,backendData:this.backendData,isAdminDomain:this.isAdminDomain})}}
+import{expandAlias as t}from"./core/alias.js";import{DomainFactory as i}from"./core/index.js";import{MigrateFunctionBuilder as e}from"./core/migrations.js";import{withProfilerLabel as s}from"./utils/profiler-label.js";export class DomainBuilder{entities;aliasMap;$entityReflections;allowedRootEntityTypes;implemented;modelVersion;publishedData;sessionData;frontendData;backendData;migrate;isAdminDomain;actions;actionImplementations;constructor(t,i,e,s,a,n,o,h,l,m,r,d,p,c){this.entities=t,this.aliasMap=i,this.$entityReflections=e,this.allowedRootEntityTypes=s,this.implemented=a,this.modelVersion=n,this.publishedData=o,this.sessionData=h,this.frontendData=l,this.backendData=m,this.migrate=r,this.isAdminDomain=d,this.actions=p,this.actionImplementations=c}static from(t,i,s,a,n,o,h,l,m,r){let d=e.fromVersions({1:t}).to(1).using({}).build();return new DomainBuilder(t,i,s,a,{},n,o,h,l,m,d,r,{},{})}withMigrate(t){return new DomainBuilder(this.entities,this.aliasMap,this.$entityReflections,this.allowedRootEntityTypes,this.implemented,this.modelVersion,this.publishedData,this.sessionData,this.frontendData,this.backendData,t,this.isAdminDomain,this.actions,this.actionImplementations)}withExpressions(i){let e={...this.implemented};return Object.entries(i).forEach(([i,a])=>{t(this.aliasMap,i).forEach(t=>{let n={...e[t]};e[t]=n,Object.entries(a).forEach(([e,a])=>{let o=n[e];if(o)throw Error(`Duplicate expression ${t}.${e}: The expression is defined on both ${i} and ${o.origin.typeOrAlias}, which would lead to ambiguous usage. Please ensure that expressions are only defined once.`);n[e]={...a,evaluate:s(`${t}_${e}`,a.evaluate),origin:{name:e,typeOrAlias:i}}})})}),new DomainBuilder(this.entities,this.aliasMap,this.$entityReflections,this.allowedRootEntityTypes,e,this.modelVersion,this.publishedData,this.sessionData,this.frontendData,this.backendData,this.migrate,this.isAdminDomain,this.actions,this.actionImplementations)}withActions(t){return new DomainBuilder(this.entities,this.aliasMap,this.$entityReflections,this.allowedRootEntityTypes,this.implemented,this.modelVersion,this.publishedData,this.sessionData,this.frontendData,this.backendData,this.migrate,this.isAdminDomain,Object.fromEntries(t.map(t=>[t.name,t])),this.actionImplementations)}withActionImplementations(t){return new DomainBuilder(this.entities,this.aliasMap,this.$entityReflections,this.allowedRootEntityTypes,this.implemented,this.modelVersion,this.publishedData,this.sessionData,this.frontendData,this.backendData,this.migrate,this.isAdminDomain,this.actions,{...this.actionImplementations,...t})}build=()=>{let t=this.implemented,s=this.migrate??e.fromVersions({1:this.entities}).to(1).using({}).build();return new i({aliasMap:this.aliasMap,entityReflections:this.entities,$entityReflections:this.$entityReflections,expressions:t,allowedRootEntityTypes:this.allowedRootEntityTypes,modelVersion:this.modelVersion,migrate:s,publishedData:this.publishedData,sessionData:this.sessionData,frontendData:this.frontendData,backendData:this.backendData,isAdminDomain:this.isAdminDomain,actions:this.actions,actionImplementations:this.actionImplementations})}}

package/dist/domain/domain-context/action-system/action-system.d.ts

@@ -0,0 +1,40 @@
+import type { ActionContext, ActionTypes, PreparedAction } from '../../core/action.js';
+import type { $DomainEntity, DomainEntity } from '../../core/model.js';
+import type { DomainState } from '../../core/state.js';
+import type { DomainContextSelectors } from '../../domain-runtime/domain-context/index.js';
+export interface ActionSystemContext {
+    /**
+     * The action system's window into the runtime registry: the declared actions and their
+     * implementations are read per call, never snapshotted, so a hot-reloaded spec or action file is
+     * observed without rebuilding the system.
+     */
+    readonly selectors: DomainContextSelectors;
+}
+/** ActionSystem with its types erased — how the runtime selectors expose the instance. */
+export type AnyActionSystem = ActionSystem<any, any, any, any, any, any, any, any, any, any, any>;
+/**
+ * Runs the actions an application declares under `actions` and implements in `src/actions/`. It
+ * only prepares: an action gets the state it is called on and returns the updates it wants applied
+ * with a reader for its result, and the caller stages, commits or dry-runs them. Every caller of an
+ * action goes through it, so all of them run the same domain logic.
+ */
+export declare class ActionSystem<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes> {
+    private readonly _context;
+    /** One compiled validator per declared action, rebuilt only when the declarations change. */
+    private readonly _selectValidators;
+    private readonly _updates;
+    constructor(_context: ActionSystemContext);
+    /**
+     * The context an implementation runs with on `state`. Code that prepares updates outside an
+     * action can run on the same context, so it can do everything an action can, the same way.
+     */
+    readonly createContext: (state: DomainState<ENTITIES>) => ActionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>;
+    /**
+     * Prepares the action `name` with `args` on `state`. The arguments are validated against the
+     * params schema the action declares, and the implementation is called with the validated
+     * parameters and the context of the state; nothing is staged or committed. Throws for an unknown
+     * action, arguments that do not fit the schema, or a declared action without an implementation.
+     * The result of `readResult` is not validated: the generated type is its contract.
+     */
+    readonly prepareAction: <NAME extends keyof ACTION_TYPES & string>(name: NAME, args: unknown, state: DomainState<ENTITIES>) => PreparedAction<ENTITIES, ACTION_TYPES[NAME]['result']>;
+}

package/dist/domain/domain-context/action-system/action-system.js

@@ -0,0 +1 @@
+import{createSelector as t}from"@salsita-ai/common/utils";import{createUpdateFactory as e}from"../../components/updates.js";import{extendedSchemaValidator as s}from"../../core/json-schema.js";import{getIdSequence as o}from"../store-system/next-domain-entity-id.js";export class ActionSystem{_context;_selectValidators=t([t.leaf(t=>t)],t=>new Map(Object.values(t).map(t=>[t.name,s.compile(t.params)])));_updates=e();constructor(t){this._context=t}createContext=t=>({expressionContext:this._context.selectors.getExpressionContext(),systems:this._context.selectors.getDomainSystems(),getIdSequence:()=>o(t.entities,[]),updates:this._updates});prepareAction=(t,e,o)=>{let n=this._context.selectors.getActionDefinitions(),i=Object.values(n).find(e=>e.name===t);if(!i){let e=Object.values(n).map(t=>`"${t.name}"`);throw Error(`Unknown action "${t}". ${e.length>0?`The application declares these actions: ${e.join(", ")}.`:"The application declares no actions."} Declare it under "actions" in a spec file and implement it in src/actions/.`)}let a=this._selectValidators(n).get(i.name);if(a&&!a(e))throw Error(`The arguments of action "${t}" do not fit its params: ${s.errorsText(a.errors)}. Nothing was changed. Send arguments that fit the params the action declares.`);return(Object.entries(this._context.selectors.getActionImplementations()).find(([e])=>e===t)?.[1])(e,o,this.createContext(o))}}

package/dist/domain/domain-context/domain-context-systems.d.ts

@@ -1,8 +1,10 @@
+import type { ActionTypes } from '../core/action.js';
 import type { Domain } from '../core/domain.js';
 import type { $DomainEntity, DomainEntity } from '../core/model.js';
 import type { ComponentReader, DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
 import type { BlenderProjections, CollisionProjections, CompositionProjections, ConstraintProjections, PositionProjections, ProjectedEntitiesProjections, SnappingProjections, ValidationProjections } from '../projections/index.js';
 import type { SketchingProjections } from '../sketching/sketching-projections.js';
+import type { ActionSystem } from './action-system/action-system.js';
 import type { DimensionSystem } from './dimension-system/dimension-system.js';
 import type { NavigationSystem } from './navigation-system/navigation-system.js';
 import type { RecipeCookerSystem } from './recipe-system/recipe-cooker-system.js';
@@ -14,7 +16,7 @@ import type { UndoSystem } from './undo-system.js';
  * The `DomainContext` lifecycle orchestrates these systems but does not expose them.
  * Consumers read this record through `DomainContextSelectors.getDomainSystems()`.
  */
-export interface DomainContextSystems<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> {
+export interface DomainContextSystems<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes = ActionTypes> {
     /**
      * The system graph's window into the runtime registry. Consumers outside the domain systems use
      * it to read spec-derived values live rather than through construction-time snapshots.
@@ -30,6 +32,7 @@ export interface DomainContextSystems<ENTITIES extends DomainEntity<string>, ALL
     readonly dimensionSystem: DimensionSystem<ENTITIES>;
     readonly undoSystem: UndoSystem<ENTITIES, $MAP>;
     readonly recipeCooker: RecipeCookerSystem<ENTITIES>;
+    readonly actionSystem: ActionSystem<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, ACTION_TYPES>;
     readonly sketchingProjections: SketchingProjections<ENTITIES>;
     readonly collisionProjections: CollisionProjections<ENTITIES>;
     readonly positionProjections: PositionProjections<ENTITIES>;
@@ -37,4 +40,4 @@ export interface DomainContextSystems<ENTITIES extends DomainEntity<string>, ALL
     readonly projectedEntitiesProjections: ProjectedEntitiesProjections<ENTITIES>;
     readonly constraintProjections: ConstraintProjections<ENTITIES>;
 }
-export type AnyDomainContextSystems = DomainContextSystems<any, any, any, any, any, any, any>;
+export type AnyDomainContextSystems = DomainContextSystems<any, any, any, any, any, any, any, any>;

package/dist/domain/domain-context/index.d.ts

@@ -13,6 +13,7 @@ export { createCascadeRefPruningTransformer } from './relation-transformers/casc
 export { createCreateEntityRefsTransformer } from './relation-transformers/create-entity-refs.js';
 export { type CanBeUndonePredicate, type CanBeUndoneContext, type UndoCapabilities, UndoSystem, UNDO_REDO_RESET_TAG, isUndoRedoReset, } from './undo-system.js';
 export { DimensionSystem, type AnyDimensionSystem, type DimensionSystemContext, type AngleDimensionViolation, type DistanceDimensionViolation, type GenericDimensionViolation, } from './dimension-system/dimension-system.js';
+export { ActionSystem, type AnyActionSystem, type ActionSystemContext } from './action-system/action-system.js';
 export { RecipeFactoryBuilder, type EntityRecipe } from './recipe-system/recipes.js';
 export { RecipeCookerSystem, type AnyRecipeCookerSystem, type RecipeCookerSystemContext, ReplaceRecipeUpdateTag, isReplaceEntityUpdate, type IsReplaceRecipeUpdate, CreateRecipeUpdateTag, isCreateEntityUpdate, type IsCreateRecipeUpdate, } from './recipe-system/recipe-cooker-system.js';
 export { type DomainContextSystems, type AnyDomainContextSystems } from './domain-context-systems.js';