@salsita-ai/sdk 0.50.0-develop.2331d4a6b7 → 0.50.0-develop.2be7811d51

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:
@@ -457,6 +491,85 @@ phoenix screenshot -o preview.png -w 1920 --height 1080
 | `--height`        | `1080`  | Image height in pixels         |
 | `--format` / `-f` | `png`   | Image format (`png` or `jpeg`) |
 
+### `phoenix variants`
+
+Show several options over the configurator and wait for your pick. It is built for coding agents: when a decision is a matter of taste, such as the edge of a table top, how glossy a finish is or where a control sits, the agent writes one file per option, you choose in the browser, and the command hands your answer back to the agent.
+
+```bash
+phoenix variants .phoenix/variants/table-edge --title 'Which edge suits the table?' --description 'Only the edge of the top differs.'
+```
+
+Every `<id>.variant.js` script or `<id>.html` page in the folder is one option, shown in file-name order. Each script edits frontend project files on top of the same captured baseline. Original is always the first choice and restores that baseline. Switching options removes the previous option's edits and applies the selected script; the editor dialog has any number of choices on the left and your already loaded configurator on the right.
+
+```js
+// .phoenix/variants/brand/blue.variant.js
+export const title = 'Blue brand'
+export const description = 'A blue primary colour with the current layout.'
+
+export default ({ read, write, remove }) => {
+  const file = 'src/handlers/theme.ts'
+  write(file, read(file).replace("main: '#E93335'", "main: '#2364aa'"))
+}
+```
+
+`read(path)` always reads the baseline. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Scripts run in the browser and collect edits; Phoenix validates and writes the batch locally. Supported files are YAML under `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants also run on the server, so a script cannot edit them.
+
+For standalone UI or branding proposals, write self-contained HTML files. Each page renders in its own iframe when selected; its `<title>` names the option and `<meta name="description" content="...">` describes it. HTML and scripts may share a set if their file names give distinct option ids.
+
+```html
+<!-- .phoenix/variants/brand/blue.html -->
+<!doctype html>
+<title>Blue studio</title>
+<meta name="description" content="A calm blue identity with generous spacing." />
+<style>
+  body {
+    margin: 0;
+    padding: 40px;
+    background: #f0f5fa;
+    color: #163b66;
+    font-family: sans-serif;
+  }
+</style>
+<h1>Made for your everyday.</h1>
+<button>Design your table</button>
+```
+
+Scripts run once per selection. The completed file batch calls the existing rebuild queue directly, without a separate file-change event stream or a watcher that reapplies the option.
+
+Use script options for controls, layout, brand, lights, visual effects, materials, positions, components, elements and transformers. Changes to the model, schemas, data or deployment settings are rejected before any files are written. Environment files, webhooks, their shared implementation dependencies, dependencies and uploaded assets cannot be overridden. Files connected through symbolic links are also excluded, so restoring the baseline preserves the original files. No server preparation or webhook rebuild runs for a variant transaction.
+
+Picking a script keeps its exact implementation in the project. Picking an HTML page returns the selected proposal for the agent to implement; the page itself changes no project source files. Choosing Original keeps the captured baseline. Users finish by confirming Original or another option. Escape stays available to the configurator, and clicking the backdrop leaves the comparison open. The agent can use `--close` to restore the baseline source files without giving an answer. Phoenix records recovery information on disk and restores interrupted previews at the next `phoenix dev` start. It never overwrites a file edited outside the preview: switching options over such an edit is refused, and when the comparison ends, or is restored at the next start, that file is left as it is with a warning in the dev log while the others are restored. Other source changes made while a comparison is open are rebuilt once it ends.
+
+Answers are held for four seconds with Undo and Send now.
+
+The command prints the outcome as JSON. After `chosen` it removes the folder:
+
+| `status`  | Meaning                                                                                                                                      |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chosen`  | An option was picked: `choice` is its id, or `null` for Original; `label` is its name.                                                       |
+| `waiting` | The wait ran out. The preview stays open: the same command attaches to it again, and an answer given in between is returned by the next run. |
+| `closed`  | The preview was closed without an answer, by `--close` or by another set of options taking its place. The folder is kept.                    |
+
+| Flag                   | Default                       | Description                                               |
+| ---------------------- | ----------------------------- | --------------------------------------------------------- |
+| `--title` / `-t`       | `Which option do you prefer?` | Question shown above the options                          |
+| `--description` / `-d` | —                             | A line saying what differs between the options            |
+| `--timeout`            | `540`                         | Seconds to wait for the answer                            |
+| `--keep`               | `false`                       | Keep the folder after the answer                          |
+| `--close`              | `false`                       | Close the open preview without an answer; needs no folder |
+| `--port` / `-p`        | `3020`                        | Editor WebSocket port                                     |
+
+Known limits:
+
+- Variant transactions start rebuilding immediately, bypassing the normal file-watcher debounce. Hot reload still needs to parse and apply the updated implementation. There is no wait for UI or scene loading to settle; allow a visible transition to finish before judging or choosing.
+- Only one option is displayed at a time; simultaneous comparison is not supported.
+- For script options and Original, the dialog moves the existing configurator into the preview and returns it on close, preserving the loaded scene, camera and UI state. Opening the dialog starts no second application or initial loading screen. Configuration interactions still change the current configuration; restoring source files does not undo them.
+- Custom scripts are trusted project code. Their file API stages edits; scripts must not make network requests or other side effects.
+- Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
+- Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
+
+Generated projects carry the `phoenix-variants` agent skill, which tells coding agents when to offer options, how to write each kind and what to do with your answer.
+
 ## SDK Development
 
 ### `phoenix link`
@@ -594,28 +707,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                                             |
@@ -188,7 +189,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### DO NOT EDIT (Fully Auto-Generated)
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build
+- **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
 - `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
@@ -197,7 +198,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 
@@ -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
@@ -314,6 +316,7 @@ project-root/
 │   │   └── builders.ts
 │   ├── .swc/                      # SWC transpiled sources
 │   ├── .lingui/                   # Compiled i18n catalogs
+│   ├── variants/                  # Option files of `phoenix variants`, written by coding agents
 │   ├── dist/                      # Build output
 │   │   ├── frontend/              # Frontend bundles
 │   │   └── webhooks/              # Webhook bundles
@@ -362,6 +365,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 +514,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

@@ -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/components/updates.d.ts

@@ -7,6 +7,8 @@ export interface ComponentModification<COMPONENT_TYPE extends SystemComponentTyp
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     writableState: WritableStateOfComponent<COMPONENT_TYPE>;
     metadata?: Record<string, unknown>;
@@ -17,6 +19,8 @@ export interface EphemeralRecordModification<COMPONENT_TYPE extends SystemCompon
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     writableState: WritableStateOfComponent<COMPONENT_TYPE>;
 }
@@ -25,6 +29,8 @@ export interface EphemeralRecordCreation<COMPONENT_TYPE extends SystemComponentT
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     initialState: StateOfComponent<COMPONENT_TYPE>;
 }
@@ -34,6 +40,8 @@ export interface EphemeralRecordDeletion<COMPONENT_TYPE extends SystemComponentT
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export type DomainEntityStateDelta<ENTITY extends DomainEntity<string>> = Partial<Omit<ENTITY, 'id' | 'type'>>;
 export interface DomainEntityModification<ENTITY extends DomainEntity<string> = DomainEntity<string>> {
@@ -41,6 +49,8 @@ export interface DomainEntityModification<ENTITY extends DomainEntity<string> =
     entityId: ENTITY['id'];
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     stateDelta: DomainEntityStateDelta<ENTITY>;
     origin?: ComponentModification<SystemComponentTypeConstraint>;
 }
@@ -55,6 +65,8 @@ export interface DomainEntityCreation<ENTITY extends DomainEntity<string>, PAREN
     collection?: string;
     parentId: PARENT['id'];
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export interface DomainEntityReplacement<ENTITY extends DomainEntity<string>> {
     kind: 'replaceDomainEntity';
@@ -63,12 +75,16 @@ export interface DomainEntityReplacement<ENTITY extends DomainEntity<string>> {
     updateTag: string;
     keepChildren: boolean;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export interface EntityDeletion<ENTITY extends DomainEntity<string>> {
     kind: 'deleteEntity';
     entityId: EntityId<ENTITY>;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export type DataUpdate<ENTITY extends DomainEntity<string>, PARENT extends DomainEntity<string>> = EphemeralRecordModification | EphemeralRecordCreation | EphemeralRecordDeletion | DomainEntityModification<ENTITY> | DomainEntityCreation<ENTITY, PARENT> | DomainEntityReplacement<ENTITY> | EntityDeletion<ENTITY>;
 export type StateUpdate<ENTITY extends DomainEntity<string>, PARENT extends DomainEntity<string>> = ComponentModification<SystemComponentTypeConstraint> | DataUpdate<ENTITY, PARENT>;

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>> {