> > > SpecLogosInteractionFileSpec

Logos Interaction File Spec

Purpose

This is a draft implementation specification for .interaction files and their first renderer in SOTER Portal. .interaction is the operational counterpart of .view. Where .view answers "what should be shown?", .interaction answers "what can the user do here?".

An .interaction file describes a small UI surface that lets a user provide input and request a command. The command may later be routed to a ledger, observer, API or command router. In the MVP, command execution may stop at a local JSON payload preview.

Scope

This document captures the agreed MVP scope:

.interaction is the operational counterpart of .view,
SOTER Portal renders .interaction to HTML,
the first renderer uses light JS/jQuery only for local UI behavior,
the visual style follows the Carbon-inspired direction of SOTER Portal,
the element name is command, not action, to avoid conflict with SVO Action,
the four semantic element types (Interaction, Field, Command, Rule), their recommended attributes, a complete MVP example, renderer behavior, visual style, and MVP validation rules.

Non-Goals

The MVP does not include:

full Hollow Client,
WebSocket streaming,
full UI-AST runtime,
command routing to the observer,
ledger writes,
tenant-specific renderer behavior,
complete widget library.

The following .view concepts should not be reused directly in .interaction:

diagram projectors such as bpmn-io, d2, plantuml, native_svg,
diagram node coordinates,
visual routing details,
board-only presentation hints,
analytical dashboard semantics as a primary concern.

.interaction is not a diagram definition. It is described here as a Logos element-based grammar, not as the Logos parser syntax itself (see LogosLanguageSpec.md for the base grammar).

Terminology

Term	Meaning
`.interaction`	File format describing an operational UI surface (screen, panel, form) built from Logos `element` blocks.
`command`	The element type representing a UI operation request; deliberately not named `action` to avoid conflict with SVO `Action`.
`Interaction`	Semantic element type defining the screen, panel or form.
`Field`	Semantic element type defining one input or display-control field.
`Command`	Semantic element type defining an operation requested by the UI.
`Rule`	Semantic element type defining validation or conditional visibility.
`preview_payload`	The MVP `Command` method: renders the command and produces a JSON payload preview without executing it.

Model or Contract

The MVP grammar uses standard Logos element blocks with four semantic types:

type: Interaction
type: Field
type: Command
type: Rule

action is intentionally not used. In SOTER, Action already has SVO meaning. A UI operation request is a command.

The shorthand block form (interaction RegisterCost, field Amount, command CreateCost, rule AmountPositive) may be accepted by specialized renderers, but it is not valid for the current canonical Logos parser. Repository and tenant files that go through the pipeline should use element ... syntax.

Rules

Relationship to `.view`

.interaction should reuse only the parts of .view that make sense for an operational UI.

The following concepts can be reused:

Concept	Meaning in `.view`	Meaning in `.interaction`
`title`	display title	panel/form title
`label`	display label	UI label
`description`	explanatory text	form/panel help text
`focus`	model element or scope to show	model element/scope being operated on
`layout`	projection layout	form/panel arrangement
`bind`	data or source binding	field-to-payload binding
`trigger`	UI/event trigger	command trigger
`mode`	read/rendering mode	command/query/update mode
`source`	data source	option/source provider
`target`	projection or output target	entity/command target
`options`	presentation options	select choices or field options
`format`	output format	input formatting hint

`Interaction`

Defines the screen, panel or form.

Recommended attributes:

Attribute	Required	Meaning
`name`	yes	Stable semantic identifier; remains stable even if the element header is rewritten to UUID form
`title`	yes	User-facing title
`description`	no	Help or context text
`mode`	no	`command`, `query`, `create`, `update`; default `command`
`intent`	no	Business intent, e.g. `create`, `append_fact`, `preview_payload`
`target`	no	Target entity or domain object
`layout`	no	`form`, `panel`, `wizard`, `table_form`; default `form`
`submit`	no	Name of the command triggered by submit
`focus`	no	Source model element/scope

`Field`

Defines one input or display-control field.

Recommended attributes:

Attribute	Required	Meaning
`type`	yes	Logos semantic type: `Field`
`name`	yes	Stable field identifier
`field_type`	yes	Field renderer type
`label`	yes	User-facing label
`bind`	yes	Payload key
`required`	no	`true` or `false`
`placeholder`	no	Input placeholder
`default`	no	Initial value
`options`	for `select`	Inline choices
`source`	no	Future external/provider choices
`help`	no	Field-level hint
`currency`	for `money`	Currency code
`format`	no	Date/number/text format hint

Supported field types for MVP:

text
textarea
number
money
date
select
checkbox
hidden

`Command`

Defines an operation requested by the UI.

The first implementation does not execute commands against the ledger. It can render the command and produce a JSON payload preview.

Recommended attributes:

Attribute	Required	Meaning
`type`	no	`command`; explicit for clarity
`name`	yes	Stable command identifier
`method`	yes	`preview_payload` for MVP
`target`	no	Target entity, ledger stream or API
`payload`	yes	Comma-separated list of field binds
`label`	no	Button label
`confirm`	no	Optional confirmation message

`Rule`

Defines validation or conditional visibility.

Rules are optional for MVP. The renderer should tolerate missing or unsupported rules.

Recommended attributes:

Attribute	Required	Meaning
`type`	yes	Logos semantic type: `Rule`
`name`	yes	Stable rule identifier
`rule_type`	yes	`validation` or `visibility`
`field`	no	Field affected by the rule
`expression`	yes	Boolean expression
`message`	no	User-facing message

Renderer behavior

The Portal renderer should:

Detect .interaction and .interaction.json files.
Parse the file into an internal structure.
Render the main interaction as a panel.
Render every field as a form control.
Render the selected command as a submit button.
On submit, collect field values by bind.
Apply basic local checks, especially required: true.
Display JSON payload preview.
Show explicit fallback UI for unsupported fields, commands or rules.

The first renderer may use JavaScript or jQuery for small local behaviors:

collecting field values,
showing JSON payload preview,
local required-field checks,
toggling conditional sections,
formatting simple values.

Visual style

The renderer should follow the SOTER Portal direction:

Carbon-inspired,
dense but readable,
low ornamentation,
no Material Design dependency in new UI,
no oversized marketing layout,
clear field labels,
compact helper text,
sharp panel boundaries and subtle grid lines.

Recommended CSS concepts:

soter-interaction-panel
soter-interaction-header
soter-interaction-form
soter-field
soter-field-label
soter-field-control
soter-field-help
soter-command-bar
soter-payload-preview
soter-fallback

Examples

Interaction element example:

element RegisterCost:
    type: Interaction
    name: RegisterCost
    title: "Register construction cost"
    description: "Create a cost entry for a construction project."
    mode: command
    intent: create
    target: Cost
    layout: form
    submit: CreateCost

Field element example:

element Amount:
    type: Field
    name: Amount
    field_type: money
    label: "Amount"
    bind: amount
    required: true
    currency: PLN

Command element example:

element CreateCost:
    type: Command
    name: CreateCost
    method: preview_payload
    target: Cost
    payload: project_id, cost_type, amount, invoice_number, occurred_at
    label: "Create cost"

Rule element example:

element AmountPositive:
    type: Rule
    name: AmountPositive
    rule_type: validation
    field: Amount
    expression: amount > 0
    message: "Amount must be greater than zero."

Complete MVP example

soter v1

element RegisterCost:
    type: Interaction
    name: RegisterCost
    title: "Register construction cost"
    description: "Create a cost entry for a construction project."
    mode: command
    intent: create
    target: Cost
    layout: form
    submit: CreateCost

element Project:
    type: Field
    name: Project
    field_type: select
    label: "Project"
    bind: project_id
    required: true
    source: Project.list
    help: "Select the construction project."

element CostType:
    type: Field
    name: CostType
    field_type: select
    label: "Cost type"
    bind: cost_type
    required: true
    options: material, labor, equipment, subcontractor, transport

element Amount:
    type: Field
    name: Amount
    field_type: money
    label: "Amount"
    bind: amount
    required: true
    currency: PLN

element InvoiceNumber:
    type: Field
    name: InvoiceNumber
    field_type: text
    label: "Invoice number"
    bind: invoice_number
    required: false

element OccurredAt:
    type: Field
    name: OccurredAt
    field_type: date
    label: "Cost date"
    bind: occurred_at
    required: true

element AmountPositive:
    type: Rule
    name: AmountPositive
    rule_type: validation
    field: Amount
    expression: amount > 0
    message: "Amount must be greater than zero."

element CreateCost:
    type: Command
    name: CreateCost
    method: preview_payload
    target: Cost
    payload: project_id, cost_type, amount, invoice_number, occurred_at
    label: "Create cost"

Example payload preview produced by the renderer:

{
  "interaction": "RegisterCost",
  "command": "CreateCost",
  "method": "preview_payload",
  "target": "Cost",
  "payload": {
    "project_id": "acme-road-001",
    "cost_type": "material",
    "amount": "1250.00",
    "invoice_number": "FV/12/2026",
    "occurred_at": "2026-06-02"
  }
}

Validation

Minimum supported validation for the MVP:

required field check,
number/money field parseability,
simple select value membership when options is inline.

Unsupported rule expressions should not block rendering. They should be shown as non-fatal warnings in the UI.

Compatibility

This is a draft implementation specification. The MVP scope described here (one renderer, .interaction -> HTML, light JS/jQuery local behaviors) is the agreed starting point; it does not commit to any of the future extensions below until they are separately specified and approved.

After MVP, .interaction can evolve toward:

command routing to Ledger/Observer,
append-only ledger event creation,
api_post and api_patch command methods,
field sources backed by query providers,
conditional visibility,
repeatable groups,
read-only summary sections,
typed payload schemas,
server-side validation,
preview and dry-run execution,
tenant-aware catalogs.

Open Questions

None captured in the source material beyond the "Future Extensions" list above.

Tracking issue: https://github.com/piotrmoskal/soter/issues/114.

Related broader backlog items: dynamic UI-AST renderer, compilation of views to JSON/UI-AST, Hollow Client, command routing, operational widget library.

Logos Interaction File Spec

Purpose

Scope

Non-Goals

Terminology

Model or Contract

Rules

Relationship to .view

Interaction

Field

Command

Rule

Renderer behavior

Visual style

Examples

Complete MVP example

Validation

Compatibility

Open Questions

Related Documents

Relationship to `.view`

`Interaction`

`Field`

`Command`

`Rule`