Struct ActionSpec 

pub struct ActionSpec {
    pub id: String,
    pub label: String,
    pub description: Option<String>,
    pub locus: ExecutionLocus,
    pub kind: OperationKind,
    pub operation_type: Option<String>,
    pub contract: ActionContract,
    pub input: ActionInput,
    /* private fields */
}

One action a resource exports to the palette.

Fields

id: String

Stable id within the resource (e.g. "like", "reply").

label: String

description: Option<String>

locus: ExecutionLocus

Declared execution locus (mirrors the concrete action’s Action::locus), so the palette can show/route it before the action is built.

kind: OperationKind

Whether this mutates the shared document, performs an external effect, or changes only the invoking application’s local view.

operation_type: Option<String>

The single protocol type routed for an effect/view operation. Keeping this beside the descriptor lets the host prove that publication and the widget’s handler registry agree, including prompted operations whose encoded value does not exist until arguments are bound.

contract: ActionContract

Machine-readable safety, availability, lifecycle, and result contract.

input: ActionInput

Implementations

impl ActionSpec

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.

Errors

Returns an ArgError when the deferred declaration is malformed or supplied does not bind to the declared parameters.

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_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( 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 that first collects a free-text argument, then builds its encoded action from it.

Projects to one required Text parameter named PROMPTED_PARAM, described by 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.

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. 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_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 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) so every existing action keeps saying exactly what it said.

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

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

pub fn programmatic(self) -> ActionSpec

Offer this action only to programmatic callers — agents, scripts, and the controls or surfaces that submit it — never in a listing a person picks from (the action palette, menus). It stays published, resolvable and invocable by address, under the same permission, confirmation and history rules as every other action. Recorded as PROGRAMMATIC_TAG so the property crosses every boundary the inert contract does.

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 is_programmatic(&self) -> bool

Whether this action is offered only to programmatic callers. See programmatic.

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_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 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. See ActionContract::kind.

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

Set what the action is: its kind and the field it writes.

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

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

pub fn reversible(self) -> ActionSpec

pub fn retry_policy(self, retry: RetryPolicy) -> ActionSpec

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, permission, 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.

Errors

Returns ArgError when the supplied arguments do not satisfy this action’s declared parameters.

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

build_args for arguments that arrived as JSON.

Errors

Returns ArgError when a value is unrepresentable or the supplied arguments do not satisfy this action’s declared parameters.

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.

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.