Struct ActionSpec 

pub struct ActionSpec { /* private fields */ }

One action a resource exports to the palette: an ActionType bound to the Target it acts on. Small: the type is shared, so a resource of ten thousand items holds each of its types once.

It reads as its type (spec.id, spec.contract).

Implementations

impl ActionSpec

pub fn action_type(&self) -> &Arc<ActionType>

The type this spec binds: what every resource offering the action shares. Bind it to other targets with ActionType::bind.

pub fn target(&self) -> &Target

What this spec acts on.

pub fn type_mut(&mut self) -> &mut ActionType

This spec’s type, to change: copied first when other specs share it, so a change to one item’s action never reaches another’s.

pub fn input(&self) -> ActionInput<'_>

How the palette collects this action’s input.

pub fn encode_immediate(&self) -> Option<Arc<EncodedAction>>

The action an Immediate spec fires, or None for one that takes input or is deferred. An action declared with what it acts on in its builder was encoded once, when declared; one bound to a target is encoded for it now.

pub fn published_encoding(&self) -> Option<&Arc<EncodedAction>>

The encoding an Immediate spec already holds, when it was encoded once and shared by every resource offering it; None for one built from its target when it is invoked. Reads, never builds: validating a surface of ten thousand items runs no action.

pub fn build_deferred(&self) -> Option<EncodedAction>

Run a Deferred spec’s builder, unchecked: None for any other. Callers check the result’s type against the declared one, as the door does.

pub fn run_by(self, provider: impl Into<String>) -> ActionSpec

This action as provider publishes and runs it: a view shows another provider’s resource and binds its controls to that provider’s actions. The view’s publisher never runs nor publishes it; its host invokes it at provider, which admits and runs it as any caller’s.

pub fn run_as(self, run: RunBy) -> ActionSpec

Self::run_by as run says where the provider publishes it.

pub fn run_by_provider(&self) -> Option<&RunBy>

Where another provider than the resource’s publisher runs this action (Self::run_by).

pub fn provider(&self) -> Option<&str>

The provider that runs this action, when it is another than the resource’s publisher (Self::run_by).

pub fn applied_as( self, kind: impl Into<String>, label: impl Into<String>, ) -> ActionSpec

Mark this action as applied as the enclosing resource of kind kind (labelled label): a nested resource (a note’s rich-text body) publishes its document actions re-encoded as the record’s field edit, so the record’s surface, permissions and history decide them.

pub fn history_context( &self, id: &str, kind: &str, label: &str, ) -> ActionContext

The history entry of invoking this action on the resource id, of kind kind and labelled label. It names that resource, of the kind whose action the value is: for a nested resource’s action, the enclosing resource’s kind and label, with the nested resource kept as a NESTED_RESOURCE_FACET facet. Naming the nested kind made the change claim a kind its app’s surface does not describe, so every receiver held it and the signer refused it.

pub fn fixed_invocation_encoding(&self) -> Option<&EncodedAction>

Borrow the actual fixed encoding used by the typed invocation builder. None means the builder is opaque, even if its palette input is Immediate. This is comparison data, never permission to invoke an action.

pub fn has_continuation_identity(&self) -> bool

Whether a provider installed continuation evidence. An installed provider returning unknown is distinct from having no provider.

pub fn deferred_invocation_type(&self) -> Option<&str>

Declared type of an explicit deferred invocation. This is inert metadata, never an encoding or authorization to execute the retained builder.

pub fn validate_json( &self, supplied: &Map<String, Value>, ) -> Result<(), ArgError>

Strict argument validation without invoking an encoder.

pub fn bound(&self) -> &[(String, Value)]

The arguments this action fixes (Self::with_bound), by name.

pub fn with_bound(self, values: Vec<(String, Value)>) -> ActionSpec

This action fixing values: a declaration offered on the item it acts on (“rename this album”), its item parameter bound and left out of Self::params. A caller that passes a bound argument anyway is heard as leaving it out when it names the bound value (an item’s id also in a longer form of the item’s address, sheets/<id>), and refused, naming the bound value, when it names another: the action acts on its item only.

pub fn deferred( id: impl Into<String>, label: impl Into<String>, locus: ExecutionLocus, type_id: impl Into<String>, build: impl Fn() -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

A document operation whose no-argument builder runs only at execution. Both invocation lanes share this one closure; construction never runs it.

pub fn deferred_on( id: impl Into<String>, label: impl Into<String>, locus: ExecutionLocus, type_id: impl Into<String>, build: impl Fn(&Target) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

deferred for a type shared by many targets: the builder is given the target of the spec being invoked.

pub fn deferred_operation( id: impl Into<String>, label: impl Into<String>, kind: OperationKind, type_id: impl Into<String>, build: impl Fn() -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

An effect/view operation with deferred no-argument encoding.

pub fn immediate<A>( id: impl Into<String>, label: impl Into<String>, type_id: impl Into<String>, action: &A, ) -> Result<ActionSpec, ActionError>

where A: Action + Serialize,

An action that fires immediately. type_id must match the app’s registry registration for A.

Projects to zero parameters: invoking it externally with an empty argument set yields exactly the pre-encoded action the palette fires.

Errors

Returns ActionError when action cannot be encoded.

pub fn immediate_encoded( id: impl Into<String>, label: impl Into<String>, locus: ExecutionLocus, encoded: EncodedAction, ) -> ActionSpec

An action that fires immediately, from an EncodedAction the caller already holds.

immediate is the usual door — it takes a typed action and reads its locus — but a caller that has only the encoded form (a stored action, a fixture, one that arrived over a wire) has no typed value to hand it. Projects to zero parameters, the same as immediate.

pub fn prompted_param( id: impl Into<String>, label: impl Into<String>, param: ActionParam, placeholder: impl Into<String>, locus: ExecutionLocus, build: impl Fn(&str) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

An action that first collects a free-text argument, then builds its encoded action from it, the argument being the parameter param: ActionParam::required("title", ParamType::Text, "The note's new title"). The name and description are what an agent reads, and the description is also the palette’s prompt.

The projection and the palette share the same build closure, so an external invocation and the on-screen affordance produce the byte-identical EncodedAction. Callers that hold the typed text find where it goes with Self::prompt_param, never by name. Name the parameter for what it is (title, name, comment): an agent reads it, and the generic PROMPTED_PARAM tells it nothing.

pub fn prompted_param_on( id: impl Into<String>, label: impl Into<String>, param: ActionParam, placeholder: impl Into<String>, locus: ExecutionLocus, build: impl Fn(&Target, &str) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

prompted_param for a type shared by many targets: the builder is given the target of the spec being invoked.

pub fn prompt_param(&self) -> Option<&str>

The name of the parameter the typed text of a prompted action goes into, or None for an action that collects no text. The one place a caller holding the text of a prompt (the palette, a broker request, a continuation) learns where it belongs.

pub fn entry_param(&self) -> Option<&str>

The parameter one line of typed text fills, when the action is a capture: it declares one (ActionParam::entry).

pub fn prompt_arguments(&self, text: &str) -> Option<Map<String, Value>>

text as this action’s typed arguments, when it is a prompted action.

pub fn operation<T>( id: impl Into<String>, label: impl Into<String>, kind: OperationKind, type_id: impl Into<String>, payload: &T, ) -> Result<ActionSpec, ActionError>

where T: Serialize,

An immediate effect or view operation owned by the application.

Errors

Returns ActionError::Encode if payload fails to serialize.

pub fn prompted_operation( id: impl Into<String>, label: impl Into<String>, prompt: impl Into<String>, placeholder: impl Into<String>, kind: OperationKind, type_id: impl Into<String>, build: impl Fn(&str) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

A prompted effect or view operation owned by the application.

pub fn typed( id: impl Into<String>, label: impl Into<String>, placeholder: impl Into<String>, locus: ExecutionLocus, params: Vec<ActionParam>, build: impl Fn(&ActionArgs) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

An action with a real typed argument surface.

This is the constructor for an argument that has a type — a number in 0..=1, a rate, one of a fixed set of filter names — rather than prose a lenient parser guesses at. ActionArgs::bind enforces the declaration, so a caller that sends "hlaf" for a choice parameter gets a named refusal instead of a silent default.

The palette can still offer it. Its input is derived from params:

• no parameters → Immediate of the action build returns for an empty argument set;
• otherwise → Prompted collecting the primary parameter (the first required one, else the first), parsed into its declared type.

A palette entry is one text field, so for a multi-parameter action it can only carry the primary argument and the rest are left unbound — which is why build sees ActionArgs and decides what an absent optional means. Text the palette cannot parse into the primary parameter’s type is likewise left unbound rather than coerced; only the keyboard path can be that lossy, and the external path stays strict.

pub fn typed_on( id: impl Into<String>, label: impl Into<String>, placeholder: impl Into<String>, locus: ExecutionLocus, params: Vec<ActionParam>, build: impl Fn(&Target, &ActionArgs) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

typed for a type shared by many targets: the builder is given the target of the spec being invoked. A nullary one is encoded per invocation, as its target says what it does.

pub fn typed_operation( id: impl Into<String>, label: impl Into<String>, placeholder: impl Into<String>, kind: OperationKind, type_id: impl Into<String>, params: Vec<ActionParam>, build: impl Fn(&ActionArgs) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

A typed effect or view operation. This is the non-document counterpart to typed, with the same strict multi-parameter binding.

pub fn typed_operation_on( id: impl Into<String>, label: impl Into<String>, placeholder: impl Into<String>, kind: OperationKind, type_id: impl Into<String>, params: Vec<ActionParam>, build: impl Fn(&Target, &ActionArgs) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

typed_operation for a type shared by many targets, as typed_on is for typed.

pub fn with_immediate(self, encoded: EncodedAction) -> ActionSpec

Fire encoded at once when a person chooses the action (the palette, a menu, the shortcut), asking nothing; a caller that passes arguments still binds them against its parameters. For a typed action whose arguments all have a meaning when left out (open search, unnarrowed).

pub fn with_immediate_per_target(self) -> ActionSpec

Fire at once when a person chooses the action, asking nothing, encoded per invocation from its target: with_immediate for a type shared by many targets. For a typed action whose parameters are all optional, each with a meaning when left out; a caller that passes arguments still binds them against its parameters. An action with a required parameter keeps asking for it.

pub fn with_continuation_identity( self, resolver: impl for<'a> Fn(ContinuationQuery<'a>) -> Option<ContinuationEvidence> + Send + Sync + 'static, ) -> ActionSpec

Opt one action into inert, provider-defined continuation evidence.

pub fn continuation_identity( &self, query: ContinuationQuery<'_>, ) -> Option<ContinuationEvidence>

Resolve comparison-only evidence for the exact input or draft domain. A mismatched response variant is rejected as unsupported.

pub fn prompted_content( id: impl Into<String>, label: impl Into<String>, prompt: impl Into<String>, placeholder: impl Into<String>, locus: ExecutionLocus, build: impl Fn(&str) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

An action whose one argument is the content hash of bytes this machine already holds, rather than typed words — a separate constructor (not a parameter on Self::prompted_param) so every existing action keeps saying exactly what it said.

pub fn prompted_content_on( id: impl Into<String>, label: impl Into<String>, prompt: impl Into<String>, placeholder: impl Into<String>, locus: ExecutionLocus, build: impl Fn(&Target, &str) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

prompted_content for a type shared by many targets: the builder is given the target of the spec being invoked.

pub fn with_keywords<S>( self, keywords: impl IntoIterator<Item = S>, ) -> ActionSpec

where S: Into<String>,

Declare the other words people use for this action ([Self::keywords]): plain words, one phrase each, no repetition of the label.

pub fn with_icon(self, icon: impl Into<String>) -> ActionSpec

Give the action its own picture ([Self::icon]), by its Lucide name.

pub fn with_description(self, description: impl Into<String>) -> ActionSpec

pub fn with_state(self, state: ActionState) -> ActionSpec

Show state on the action’s row (ActionState): publish the action anew when it changes.

pub fn with_contract(self, contract: ActionContract) -> ActionSpec

pub fn unavailable( self, code: impl Into<String>, reason: impl Into<String>, ) -> ActionSpec

pub fn destructive(self) -> ActionSpec

A deletion: its kind is deletion_kind, and the tags the spec already carries settle its confirmation — asked with a click unless a compensated undo says Undo takes it back.

pub fn for_audience(self, audience: Audience) -> ActionSpec

List this action for audience only (Audience). Recorded in the contract’s tags, so the audience crosses every boundary the inert contract does. Call after with_contract, which replaces the tags.

pub fn reads_document(self) -> ActionSpec

Declare this read-only action as the one that answers, with no arguments, the first page of the app’s open document. Recorded as DOCUMENT_READ_TAG, so a caller that just opened a file finds it in the directory. Call after with_contract, which replaces the tags.

pub fn opens_path(self, extensions: &[&str]) -> ActionSpec

Declare this action as the one that opens the file its path parameter names in this app instance, of any type when extensions is empty, else of those (lowercase, no dot). Recorded as OPENS_PATH_TAG, so a caller that launches the app with a file opens it here, and never through an action that only happens to take a path. Call after with_contract, which replaces the tags.

pub fn audience(&self) -> Audience

Who this action is listed for. See for_audience.

pub fn reaches_people(&self) -> bool

Whether people’s listings (the palette, menus) offer it.

pub fn reaches_agents(&self) -> bool

Whether agents’ listings offer it.

pub fn takes_a_row_answer(&self) -> bool

Whether a row a person picks can supply what it asks for: nothing, or the one line its prompt collects (a name, a number, a date). One that needs several arguments, or a list, an object or another resource’s address, is taken by callers that name them (agents, scripts, the controls bound to where the person is), never from a row.

pub fn carrying(self) -> ActionSpec

Declare that this action carries the resource’s other actions (a generic typed edit, a group of edits): history records the actions it carried, never this one.

pub fn carries_actions(&self) -> bool

Whether this action carries the resource’s other actions. See Self::carrying.

pub fn with_risk( self, classify: impl Fn(&ActionArgs) -> RiskLevel + Send + Sync + 'static, ) -> ActionSpec

Classify each invocation’s risk from its bound arguments, for an action whose consequence depends on them (a generic edit whose value may delete). Whenever the classified risk requires confirmation, the host asks for exactly the confirmation a declared destructive action gets; otherwise the action runs directly. The contract advertises ARGUMENT_RISK_TAG so callers that cannot classify know to expect it.

pub fn with_risk_on( self, classify: impl Fn(&Target, &ActionArgs) -> RiskLevel + Send + Sync + 'static, ) -> ActionSpec

with_risk for a type shared by many targets: the classifier is given the target of the spec being invoked.

pub fn with_need_of( self, classify: impl Fn(&ActionArgs) -> ActionNeed + Send + Sync + 'static, ) -> ActionSpec

Classify what each invocation is from its bound arguments, for an action whose consequence depends on them (a generic edit: a reply writes only the comments, a deletion changes the document). The declared ActionContract::kind and ActionContract::field stay the least any invocation is, which is what a host offers the action under; every gate that admits an invocation asks need_for too.

pub fn need_for_args(&self, args: &ActionArgs) -> ActionNeed

What one invocation with these bound arguments is: the classifier’s verdict, else the declared contract’s.

pub fn need_for( &self, json: Option<&Map<String, Value>>, argument: Option<&str>, ) -> ActionNeed

What one invocation is, by the value it carries: json, or the palette’s and legacy text door’s argument (typed JSON behind ARGUMENTS_JSON_PREFIX, one line of text for the primary parameter, or nothing). Arguments that do not bind build no action, so they are what the declaration says.

pub fn with_undo_of( self, classify: impl Fn(&ActionArgs) -> bool + Send + Sync + 'static, ) -> ActionSpec

Decide per invocation whether Undo takes it back, for an action that carries others (a group: Undo takes it back only when it takes back every member). Without it, the contract’s can_be_undone decides.

pub fn undoable_for(&self, args: &ActionArgs) -> bool

Whether Undo takes back one invocation with these bound arguments.

pub fn risk_for(&self, args: &ActionArgs) -> RiskLevel

The risk of one invocation: the classifier’s verdict for these arguments, or the declared ActionContract::risk.

pub fn confirmation_for_args(&self, args: &ActionArgs) -> ConfirmationPolicy

The confirmation one invocation with these bound arguments needs: the declared policy when there is one, else Confirm when risk_for requires confirmation. Every gate that admits an invocation asks this, never the declared policy alone.

pub fn confirmation_for_json( &self, supplied: &Map<String, Value>, ) -> ConfirmationPolicy

confirmation_for_args for arguments that arrived as JSON. Arguments that do not bind cannot build an action at all, so they get the declared policy.

pub fn confirmation_for_argument( &self, argument: Option<&str>, ) -> ConfirmationPolicy

confirmation_for_args for the palette and legacy text door: typed JSON behind ARGUMENTS_JSON_PREFIX, one line of text for the primary parameter, or nothing.

pub fn privileged(self) -> ActionSpec

pub fn of_kind(self, kind: ActionKind) -> ActionSpec

Set what the action is able to do, as the declaration sees it. See ActionContract::kind.

pub fn with_need(self, need: ActionNeed) -> ActionSpec

Set the field the action writes, and its kind unless the declaration named one (of_kind), which a need does not overrule.

pub fn below_field(self, field: impl Into<String>) -> ActionSpec

Place the action below the one field it writes. See ActionContract::field.

pub fn execution(self, execution: ExecutionMode) -> ActionSpec

pub fn returns(self, result: ResultSpec) -> ActionSpec

pub fn rewrapped( self, wrapped_type: &str, wrap: impl Fn(EncodedAction) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

This document action as another resource carries it: every action it builds passes through wrap, which re-encodes it as the action of the resource that contains this one (a rich-text edit becomes the note’s edit of its body, registered under wrapped_type). Parameters, kind, field, risk and confirmation stay this action’s. A builder’s refusal passes through unchanged. An effect or view operation is returned as it is: it writes nothing to wrap.

pub fn routed( self, operation_type: &str, wrap: impl Fn(EncodedAction) -> EncodedAction + Send + Sync + 'static, ) -> ActionSpec

This document action, carried out on another document than the one its resource’s host holds (the person’s own record, a settings section): published as an effect operation of operation_type whose value is wrap of the encoded action, which the host answering operation_type applies to that document. Parameters, kind, permission, risk and confirmation stay this action’s. An effect or view operation is returned as it is.

pub fn params(&self) -> &[ActionParam]

What an invocation of this action must carry. Empty for the nullary majority.

Part of the descriptor rather than something a caller discovers by trying: enumeration is all a caller that cannot see the screen has to work from, so an action whose parameters were not advertised would be un-invokable except by guesswork.

pub fn build_args( &self, supplied: impl IntoIterator<Item = (String, ArgValue)>, ) -> Result<EncodedAction, ArgError>

Bind supplied against params and build the action.

Strict: a missing, unknown, wrong-typed or out-of-choice argument is refused here, and the caller never receives an EncodedAction to dispatch — so a bad call cannot become a partial mutation, because nothing was ever handed to the executor.

pub fn build_json( &self, supplied: &Map<String, Value>, ) -> Result<EncodedAction, ArgError>

build_args for arguments that arrived as JSON.

pub fn build_text(&self, text: &str) -> Option<EncodedAction>

The palette lane’s encoding for one typed text argument, exactly as a prompted affordance builds it. None when this action collects no text.

impl ActionSpec

pub fn requires(self, requirement: ContextRequirement) -> ActionSpec

Declare a precondition on the invoker’s view. The operation stays at its stable address in every participant’s tree and in the published schema; the invoker’s tree refuses it when the precondition fails.

pub fn participant_view(self) -> ActionSpec

Declare that this View operation changes only the invoking participant’s own view, so a remote participant may invoke it.

Methods from Deref<Target = ActionType>

pub fn bind(self: &Arc<ActionType>, target: Target) -> ActionSpec

This type bound to target: the action one item offers.

Trait Implementations

impl Clone for ActionSpec

fn clone(&self) -> ActionSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Deref for ActionSpec

type Target = ActionType

The resulting type after dereferencing.

fn deref(&self) -> &ActionType

Dereferences the value.