# Offering actions, entry and choices Load this card when a task decides what a person can do on a page: endpoint entry (`DefaultRequest`, landing forwarding), the Actions surface and its input presentation, `RequestConfirmation`, response-level and field-level `ConstrainedBy`, named action controls, or what native Back does. Its rules are generated from the [Endpoint protocols and runtime contract](../reference/protocols.md#default-request-entry-and-dynamic-actions), which owns them. Rows that open a request are [links](links.md); a calculated allowed set is on the [calculation card](calculations.md). ## Order of work 1. Decide endpoint entry and its landing (`entry.*`, `landing.*`). 2. Declare each page's `NextRequest` set and, when the service decides its membership, the response `ConstrainedBy` (`actions.response-constraint.*`, `actions.auto-selection`) and named controls (`actions.control.*`). 3. Check how each offered Request is presented by its input (`actions.tap.*`, `actions.input.*`, `actions.hierarchical.*`, `actions.editor.*`) and mark the critical ones (`actions.confirmation.*`). 4. Constrain enumerated and Union request fields from service data (`choices.*`), then compile with Studio and fix every reported rule. ## Rules to apply Studio does not check these rules. Each is quoted from its owner. ### Backend-constrained choices Owner: [protocols.md#backend-constrained-choices](../reference/protocols.md#backend-constrained-choices) - `choices.constrained-by.own-source`: Each occurrence of the constrained field is filtered only by the source its own path resolves to. - `choices.source.service-written`: The service writes it and the user never does: populate it from backend response data through CopyFrom, including copying its containing cookie, supply it directly in EditRequest, or assign it from a field calculation reply or a [link return](../reference/protocols.md#link-return) through CopyTo under the [calculated allowed sets](../reference/protocols.md#calculated-allowed-sets) rules. Between those writes the set is stable; ordinary editing never replaces the source or its containing data. - `choices.entries.values`: For an Enumeration, entries are its declared numeric values. For a Union, entries are its original schema discriminants, never positions in the filtered chooser. `[1]` permits only choice 1; `[0, 2]` permits choices 0 and 2. - `choices.empty-and-null`: An absent or null source offers no choice and blocks submission with the field error, also for a Nullable field. An empty source offers no declared choice: it blocks submission for a non-nullable field, while for a [Nullable](../reference/presentation.md#nullable-choices) field it leaves exactly one answer, null, which is how a service says the question does not apply. Duplicate entries do not create extra choices. Null is not a numeric choice; ordinary Nullable semantics apply when the allowed set is nonempty. Undefined remains unanswered and cannot be submitted for a non-nullable field. - `choices.consistent-prefill` (judgment): Clients show only permitted choices and validate the selection before sending. A selected Union branch retains its ordinary editable payload and nested-field validation. A singleton allowed set does not construct an unfinished payload on the server or automatically submit the editor. Missing or malformed cookie data, an empty allowed set, or a prefilled choice outside the set blocks submission with a field error. Clients do not silently replace a conflicting prefill; the application must supply consistent values and cookies. - `choices.singleton`: **Singleton allowed set.** When a non-nullable field is undefined and its current allowed set has exactly one entry, the client selects that choice through ordinary initialization, exactly as a Union [`Default`](../reference/schema.md#43-value-constraint-and-presentation-attributes) selects its variant. The field is not locked: a Union branch's payload stays editable, submission still validates membership, and nothing is submitted automatically. A nullable field with a nonempty allowed set is not selected, because null is a second answer; a nullable field whose allowed set is empty, and which is unanswered, is answered with null the same way, since null is then its only answer. A value it holds outside an empty set stays a field error that the person resolves by choosing the null answer. When a [calculated allowed set](../reference/protocols.md#calculated-allowed-sets) shrinks to one entry while the field is undefined, the same selection is part of that atomic editor change; if the set later widens, the selection stays as an ordinary one. This is a data rule, owned here and not by presentation: it writes the value whether or not the field's row is drawn, and a Display Template [`when_single_choice`](../reference/presentation.md#single-choice-rows) rule only decides whether to draw the row of a field this rule has answered without a payload. A scalar [EnumSource](../reference/presentation.md#common-field-metadata) host follows the same rule when its source offers exactly one selectable member; a [List host](../reference/schema.md#enumsource-list-hosts) never takes it. ### Default request entry and dynamic actions Owner: [protocols.md#default-request-entry-and-dynamic-actions](../reference/protocols.md#default-request-entry-and-dynamic-actions) - `entry.default-request.optional`: DefaultRequest is optional; an input-free payload alone does not make a Request the default. - `entry.default-request.owns-entry`: An explicit DefaultRequest owns initial interactive entry, including when the protocol also has a default subscription. Without the explicit marker, the existing default subscription remains the initial data source. With neither, the landing presents the available requests in declaration order, except [link-only requests](../reference/protocols.md#link-only), using chart previews instead of rows for chart requests with executable inputs. That landing is a displayed value without data whose actions are those requests. An input-free payload alone never makes a Request the default. Invoke an explicit default request as a client-owned correlated Request, never as a pooled subscription. While pending, show loading; an error keeps retry available. A late or duplicate reply cannot reopen an interaction that the user has left. Do not automatically replay an entry request merely because a view recomposes or a subscription reports new data. - `entry.landing-forwarding`: **Landing forwarding.** On entry, a protocol landing with exactly one eligible action always selects it without a chooser. A landing supplied by DefaultRequest or default SubscriptionData uses that value's filtered NextRequest; a request-list landing uses its discovered requests. Apply access, ExcludeUI, and ConstrainedBy where applicable, and exclude LinkOnly before counting. This rule applies to static as well as constrained action sets, independently of visible landing content. Validate and send a request with no editable input, or open its ordinary popup/editor and await submission when it has input. Defaults do not make editable fields input-free, and RequestConfirmation still requires confirmation. With no eligible action keep the landing; with several, await a choice. Chart workspaces and automatic previews retain their own entry rules. For a landing with [named action controls](../reference/protocols.md#named-action-controls), count the deduplicated union of requests actually offered through those controls. - `entry.forwarding-result`: The selected landing action's result is the initial working result, not another landing-forwarding step; it follows the regular response and editor rules. A plain Response, with neither NextRequest nor WorkflowRequest, is the [non-transition acknowledgement](../reference/protocols.md#protocol-roles) and never replaces the landing, including a subscription landing. The [landing and Back](../reference/protocols.md#control-endpoint-landing-and-native-back) rule applies to every working result, including a dynamically selected resume page. For example, entry can send Enter, receive a landing offering only OpenInterview, send OpenInterview, and resolve its reply into an editing Request. The editor waits for submission; its NextRequest does not authorize automatic submission. Rendering, subscription updates, and auxiliary traffic do not repeat forwarding; initial default subscription data is used for forwarding only as part of an explicit endpoint entry, never merely because inline data appeared in the endpoint list. - `entry.no-fallback-listing`: Once an entry or forwarding request has been selected, never fall back to listing all protocol requests on failure. DefaultRequest does not authorize automatic submission of an editor. Existing WorkflowRequest and EditRequest replies open their editor without submitting. - `entry.no-visible-content`: A normal response with no visible content presents only its NextRequest choices, through its [named action controls](../reference/protocols.md#named-action-controls) when it declares them; its reference context follows the [interaction reference context rule](../reference/protocols.md#interaction-reference-context). Hidden fields and hidden ancestors contribute no visible content. Nil and containers with no visible descendants contribute none; a visible scalar or List still counts even when its value is empty or null. Apply existing presentation rules recursively, including union selection. A response with visible content opens the ordinary response screen. This presentation rule does not turn a terminal acknowledgement into a navigation transition. An action response whose dynamic set is empty retains its action surface with no actions. ### Single-action confirmation and input presentation Owner: [protocols.md#single-action-confirmation-and-input-presentation](../reference/protocols.md#single-action-confirmation-and-input-presentation) - `actions.eligible-count`: **Actions chooses a request before input determines whether to send it.** Count the current displayed value's eligible NextRequest choices after access, ExcludeUI, ConstrainedBy, and LinkOnly filtering, and, when the page supplies an explicit `Actions` array, only its members ([named action controls](../reference/protocols.md#named-action-controls)): - `actions.tap.none`: | Eligible Actions choices | On tapping Actions | | --- | --- | | None | Hide the button. | - `actions.tap.one`: | Eligible Actions choices | On tapping Actions | | --- | --- | | Exactly one | Select that request directly, without a chooser, then apply the input rule below. | - `actions.tap.several`: | Eligible Actions choices | On tapping Actions | | --- | --- | | Several | Open the ordered chooser; send nothing until the person selects a request and its input rule permits sending. | - `actions.display-is-not-choice`: The Actions tap in the one-choice case is the person's choice of that request. Merely displaying one action is not a choice and never authorizes sending. The same input rule applies to a chosen menu item, Quick Action, or declared link. The [inline subscription header](../reference/endpoint-presentation.md#endpoint-list-with-displayed-subscription-data) keeps its required drawer even for one choice; it is not the Actions button or a new landing entry. - `actions.input.none`: | Constructed request input | Presentation | | --- | --- | | No editable input fields | Validate and send at once. A RequestConfirmation request first requires its Send/Cancel dialog. | - `actions.input.one-field`: | Constructed request input | Presentation | | --- | --- | | One editable primitive or enum field, or one hierarchical choice field as defined below | Use the one-field popup with its normal confirmation and cancellation controls. | - `actions.input.complex`: | Constructed request input | Presentation | | --- | --- | | More complex input | Use the existing full request editor with its normal submit and cancellation controls. | - `actions.input.counting`: Use the existing request-composition rules after initialization, including hidden subtrees and constrained choices; count input fields, not rendered layout rows. An input field is one the person can edit: a Hidden, ReadOnly, or Fixed field is not input, also when a ReadOnly field is visible. A visible ReadOnly or Fixed value is still shown, because it is visible for the person to see: a request with one editable field beside such a value uses the full request editor, not the one-field popup. - `actions.input.defaults-keep-input`: Default or CopyFrom values do not remove editable input: even a completely initialized editable request waits for the person to submit its popup/editor. Cancelling or dismissing a popup or an editor sends nothing and preserves the current protocol data and reference context. One choice sends at most one request, with ordinary validation and request correlation: recomposition, repeated taps, or returning to a retained response must not replay it. A popup or an editor whose originating surface has been left or replaced cannot send. ### Hierarchical single field requests Owner: [protocols.md#hierarchical-single-field-requests](../reference/protocols.md#hierarchical-single-field-requests) - `actions.hierarchical.shape`: **Hierarchical single-field requests.** A single editable choice field may be a non-nullable Union whose branches carry Enumerations or further such Unions. Single-field record wrappers may preserve that shape; Hidden construction fields do not add editable input. Every branch must have this choice-only shape. Other editable payloads, nullable containers, Lists, or visible ReadOnly/Fixed companion content retain the ordinary full editor. This is general one-field request composition, applicable to category/item selection as well as navigation; it requires no new attribute, grouping catalog or template opt-in. ### Single-action confirmation and input presentation Owner: [protocols.md#single-action-confirmation-and-input-presentation](../reference/protocols.md#single-action-confirmation-and-input-presentation) - `actions.hierarchical.sources-available`: Sources needed while browsing inactive branches must be available through normal construction without changing the live selection, invoking calculations, or sending domain requests to discover choices. - `actions.hierarchical.overview-leaf` (judgment): For hierarchical navigation, a group's overview must be an explicit destination leaf; its expand/collapse header is not an action. [AI Search](../reference/protocols.md#candidate-discovery-and-assembly-before-ai) reuses this builder to construct one complete invocation for each eligible leaf of an offered action. The navigation hierarchy can therefore serve both Go to and Search without a second catalog of bound links. ### Request confirmation Owner: [protocols.md#request-confirmation](../reference/protocols.md#request-confirmation) - `actions.confirmation.declaration`: **Critical requests.** `@LibertasRequestConfirmation` and `#[libertas_request_confirmation]` take no argument and emit `{"Name":"RequestConfirmation","Value":"true"}` on a protocol Request variant, the marker form of DefaultRequest and LinkOnly. - `actions.confirmation.dialog`: Whenever a person's choice, landing forwarding, or submission is about to send a marked request, the client first shows a dialog that names the action, with its display name and description, and offers **Send** and **Cancel**. The rule holds for every entry point and every input: ### Single-action confirmation and input presentation Owner: [protocols.md#single-action-confirmation-and-input-presentation](../reference/protocols.md#single-action-confirmation-and-input-presentation) - `actions.confirmation.no-input`: | Constructed request input | Presentation of a marked request | | --- | --- | | No editable input fields | The dialog takes the place of the immediate send, also when Actions has only one eligible request and skips its chooser. | - `actions.confirmation.one-field`: | Constructed request input | Presentation of a marked request | | --- | --- | | One editable primitive, enum or hierarchical choice field | The one-field popup, then the dialog after the popup is confirmed. | - `actions.confirmation.complex`: | Constructed request input | Presentation of a marked request | | --- | --- | | More complex input | The full request editor, also a workflow editor, then the dialog after Submit. A previous action that names a marked request shows the dialog before it is sent. | - `actions.confirmation.ai-assistant`: The marker is a rule for presentation to a person and a requirement on the AI assistant. For the AI assistant, the Hub starts the generated tool's description with "Requires user confirmation." and instructs the assistant, in every turn that offers such a tool, to state the action and its values and to call the tool only after the user confirms in a later message; the Hub does not verify the confirmation. The marker does not change the wire form of the request or its validation. A program that calls the endpoint directly is not affected, and the service still validates every request. - `actions.auto-selection.person-choice`: Outside [landing entry](../reference/protocols.md#default-request-entry-and-dynamic-actions), only the person's choice sends a request without editable input. [Automatic singleton selection](../reference/protocols.md#response-action-constraints) is not such a choice: only an accepted regular Response with no visible content, no [named action controls](../reference/protocols.md#named-action-controls), and exactly one eligible constrained action may automatically open that action's popup or editor once. A request without editable input that it would select stays offered as the one action until the person chooses it. Visible response content, including link rows, stays displayed. Rendering, layout changes, subscription updates, and return to retained content do not select or send an action. A regular reply therefore never sends a next action by itself. - `actions.auto-requests-only`: Apart from the [landing forwarding rule](../reference/protocols.md#default-request-entry-and-dynamic-actions), the only requests that follow a reply without the person's choice are auxiliary [field calculations](../reference/protocols.md#field-calculation-requests) and the [refresh](../reference/presentation.md#master-detail-panes) of a master-detail leading page. ### Request editor variant identity Owner: [protocols.md#request-editor-variant-identity](../reference/protocols.md#request-editor-variant-identity) - `actions.editor.one-variant`: A request editor composes exactly one protocol variant, fixed by its entry point: a chooser selection, a direct link, or a server-delivered EditRequest or WorkflowRequest. A default request is sent without an editor, so it is not an editor entry point; the editor that follows default entry is installed by its reply. The editor's root row is that variant, never a selector over the Endpoint protocol Union. Android, iOS, and Libertas Studio must not offer the protocol's other variants from the root row, on tap, long-press, or any other gesture, and must not render the root with a selectable-union affordance. Changing the request type means leaving the editor and choosing another action. Unions inside the request payload keep their ordinary variant selection. The **Actions** surface belongs to an accepted response only; a request editor has none, so nothing in it may open an action chooser or navigate to another request except a declared [link](../reference/protocols.md#links) or a declared [previous action](../reference/protocols.md#submit-previous-actions-and-completion). A link is neither the Actions surface nor a chooser; links and previous actions are the only ways an editor opens another request. ### Control endpoint landing and native Back Owner: [protocols.md#control-endpoint-landing-and-native-back](../reference/protocols.md#control-endpoint-landing-and-native-back) - `landing.kinds`: The endpoint defines its landing entry independently of later interactions. There are exactly two landing kinds, determined by the operation actually sent for default entry, never by a response variant or a later working page: - `landing.subscription-landing`: **Subscription landing:** the selected default entry request was sent as a SubscriptionRequest. Retain that live page underneath at most one working page, including its subscription owner, reference context, layout, and scroll position. Later working results replace that working page, never the subscription landing. Inline default data uses its existing endpoint-list location as the retained landing, without creating a duplicate page. - `landing.non-subscription-landing`: **Non-subscription landing:** default entry uses an ordinary Request, or no default is selected and entry begins with the request list. The initial landing page is the working page; later interactions replace or update that one page, without retaining the initial page underneath it. - `landing.fresh-entry-no-context`: Fresh endpoint entry has **no reference context** from an abandoned page; never construct it from that page's response or cookie. A working subscription cannot overwrite the retained default subscription's snapshot. - `landing.no-page-history`: Clients keep no history of intermediate working pages and do not remember or compare an initial message type for navigation. Live [stacked-link pages](../reference/protocols.md#links) are temporary displays above this working surface, with local pop-only dismissal. The service may select a different initial or resumed working page for each endpoint entry. - `landing.entry-replies`: The reply to landing entry itself can be displayed without NextRequest; do not suppress it as an acknowledgement of a previous screen. A plain Response to a selected landing action remains the [non-transition acknowledgement](../reference/protocols.md#protocol-roles) and leaves landing in place, under the [forwarding rule](../reference/protocols.md#default-request-entry-and-dynamic-actions). An explicitly selected SubscriptionRequest installs its completing Response as the first state of its own SubscriptionData snapshot, whether or not it declares NextRequest; that reply is stable rather than an acknowledgement. A failure or Error preserves the originating page under ordinary retry rules. - `landing.native-back.exits`: Exit that endpoint immediately, regardless of the displayed message type, payload, workflow step, or resume state. Return to the endpoint list for a multi-endpoint task, or exit the task for a single-endpoint task. - `landing.native-back.no-restart`: Do not reveal or restart landing, repeat entry or forwarding, or send a PrevRequest. From the endpoint list itself, exit the task. - `landing.native-back.stacked-first`: A stacked idle composer, picker, modal, chart, or [stacked-link page](../reference/protocols.md#links) closes first and reveals its underlying live page. A sent request instead follows [exit while pending](../reference/protocols.md#exit-while-pending); its surface cannot be dismissed alone. - `landing.native-back.system-back`: These rules apply to the Back button and system back navigation alike. A [transient request composer](../reference/endpoint-presentation.md#protocol-transaction-stack) first follows its cancellation and pending-response rules. A local picker or modal retains its ordinary dismissal behavior. Abandoned pending replies, calculations, and explicit subscriptions cannot navigate or overwrite the new entry or another interaction. Back does not undo a request already accepted by the backend. Workflow PrevRequest remains a separate explicit protocol action. ### Response action constraints Owner: [protocols.md#response-action-constraints](../reference/protocols.md#response-action-constraints) - `actions.response-constraint.membership-only`: NextRequest declares the complete possible action set and its display order. The ConstrainedBy array supplies membership only: its order never reorders actions. For example, NextRequest `A,B,C` with allowed discriminants for `C,A` displays `A,C`. No separate order attribute is needed. - `actions.response-constraint.server-discriminants`: Each integer in the response's allowed array identifies an original protocol Union discriminant of the server schema, never a position in NextRequest or a filtered action list; a client App whose protocol arranges the Union differently reads it under the [capability prefix rule](../reference/protocols.md#capability-prefixes). - `actions.response-constraint.empty-and-duplicates`: Only declared actions in the allowed set are displayed, after the ordinary access and ExcludeUI restrictions. An empty array is valid and means no actions; duplicate entries do not duplicate actions. Landing uses its separate [forwarding rule](../reference/protocols.md#default-request-entry-and-dynamic-actions). - `actions.auto-selection`: On a regular response, if the constrained set, after access and visibility filtering and without [link-only requests](../reference/protocols.md#link-only), contains exactly one action, keep the response visible when it has visible content, including link rows. Choosing Actions opens that request directly, without a chooser. Only a response with no visible content and no [named action controls](../reference/protocols.md#named-action-controls) automatically selects its sole action once for that accepted response, then applies the [single-action presentation rule](../reference/protocols.md#single-action-confirmation-and-input-presentation): one popup-eligible field uses the existing one-field popup, and complex input uses the full editor. Automatic selection never sends: a request without editable input stays offered as the one action and is sent when the person chooses it. Never auto-submit a workflow editor or serialize an unfinished request. Rendering or returning to the same retained response must not repeat the selection. - `actions.response-constraint.update-refilters`: A subscription update re-filters the actions and never selects one, also when it leaves exactly one: automatic selection happens only for an accepted correlated Response without visible content, because auxiliary traffic never navigates. Use the visible-content definition under [default entry](../reference/protocols.md#default-request-entry-and-dynamic-actions); the initial working result after a landing action follows this same rule; the landing action source uses its forwarding rule. Without ConstrainedBy, NextRequest remains static. - `actions.response-constraint.removal-keeps-surface`: The set belongs to the installed response and is replaced only with a newly accepted response or subscription update. It is not evaluated against an editor or another interaction. An update that removes a request from the set neither leaves nor replaces the surface: a popup, editor, or confirmation dialog already opened for that request may still send it, and the service checks it as it checks every request. Every action entry point, including declared [links](../reference/protocols.md#links) on its rows and menus, uses the same filtered set. Backend authorization and state checks still apply when a selected request arrives. ### Named action controls Owner: [protocols.md#named-action-controls](../reference/protocols.md#named-action-controls) - `actions.control.dual-role`: On a dual-role variant it applies only while the value is displayed, never in its Request editor. Hidden keeps the source list out of content and editors; the marker creates a separate control for its choices. - `actions.control.membership`: The App supplies each control's current membership as original protocol Union Request discriminants of the server schema in the marked field, read under the [capability prefix rule](../reference/protocols.md#capability-prefixes). The field array never names a NextRequest position or changes order. Start with `NextRequest`, apply the response's existing ConstrainedBy ceiling, access and ExcludeUI restrictions, then intersect each control with its own array. LinkOnly requests are absent from every control. Duplicates collapse; an empty array hides only that control. Without an `Actions` field, Actions offers the shared eligible set. A named control does not remove its requests from Actions. To separate the controls, the App supplies an explicit Actions array. - `actions.control.links-shared-set`: Links continue to use the shared response set independently of control-specific arrays. - `actions.control.presentation`: Zero eligible choices hide a control; one choice selects its Request directly on tap; several open the ordinary ordered chooser. The Request owns its CopyFrom, field ConstrainedBy, inputs, confirmation, validation, and submission. A control has no tapped data row or bound List member and never borrows another panel's unfinished editor values. A regular page declaring any ActionControl stays displayed even when it has only one eligible request and all ordinary content is Hidden. Rendering, caption changes, and subscription updates never activate it. Pages without this attribute keep the preceding automatic presentation rule. - `actions.control.landing-count`: On landing entry, count the deduplicated union of actual targets offered by its controls, including implicit Actions. LinkOnly and requests omitted from all controls do not count. The ordinary landing forwarding rule then applies once. A retained subscription landing never forwards again. Named controls do not change landing kind, native Back, interaction correlation, or the Next submission control of an embedded editor. See [action-control presentation](../reference/presentation.md#named-action-controls) for captions, placement, and template customization. ## Rules Studio enforces Studio rejects a source that breaks one of these rules. The owner holds the full rule. ### Backend-constrained choices Owner: [protocols.md#backend-constrained-choices](../reference/protocols.md#backend-constrained-choices) - `choices.constrained-by.placement`: Field ConstrainedBy constrains an Enumeration or Union in request data; on a Response it constrains NextRequest - `choices.source.hidden-int-list`: The ConstrainedBy source is a Hidden non-nullable list of non-nullable integers - `choices.studio-checks`: A WorkflowRequest initializes the ConstrainedBy source or its containing cookie through CopyFrom ### Default request entry and dynamic actions Owner: [protocols.md#default-request-entry-and-dynamic-actions](../reference/protocols.md#default-request-entry-and-dynamic-actions) - `entry.default-request.declaration`: DefaultRequest marks at most one input-free Request variant, never ExcludeUI or LinkOnly - `entry.default-request.no-chart`: A chart-producing request cannot be DefaultRequest ### Single-action confirmation and input presentation Owner: [protocols.md#single-action-confirmation-and-input-presentation](../reference/protocols.md#single-action-confirmation-and-input-presentation) - `actions.confirmation.placement`: RequestConfirmation goes only on a variant carrying Request, never on a DefaultRequest ### Response action constraints Owner: [protocols.md#response-action-constraints](../reference/protocols.md#response-action-constraints) - `actions.response-constraint.declaration`: Response ConstrainedBy needs NextRequest, excludes WorkflowRequest and Error, and reads a hidden integer list ### Named action controls Owner: [protocols.md#named-action-controls](../reference/protocols.md#named-action-controls) - `actions.control.declaration`: Named action controls sit on direct Hidden non-nullable integer-List fields of a displayed NextRequest page - `actions.control.name`: A control name is a case-sensitive identifier unique on its page; Actions names the built-in control