Module contract 

Machine-readable operational semantics for exported actions.

Labels explain an action to a person. This module explains it to callers that must plan safely without seeing the application: whether it is currently available, what confirmation it needs, whether a failed call may be retried, how it completes, and what it returns.

Structs

ActionContract

Complete operational contract copied into every inert descriptor.

ActionNeed

What one invocation of an action is, for the grants deciding it: its kind, the one field of its resource it writes when it writes only one (a reply writes the comments), which places it below that field in the tree, and whether it is privileged (RiskLevel::Privileged): it exercises authority over the workspace or others in it, so the person’s own grants must allow it (tilo_action_policy::Verdict::privileged).

Offload

How an offloadable action runs away from the device it was invoked on.

Enums

ActionKind

What an action is able to do, derived by the framework from the action’s code and never declared by an app.

Audience

Who an action is listed for. The app declares it. Most actions are for Everyone, which is the default. An action outside a listing’s audience stays published, resolvable and invocable by address, under the same permission, confirmation and history rules as any other. It just isn’t offered there.

Availability

Whether an action can be invoked in the resource’s current state.

ConfirmationPolicy

Confirmation required after argument binding and immediately before run.

ExecutionMode

Completion behavior advertised before invocation.

ResultSpec

Shape of a successful result. Schemas use JSON Schema so non-Rust callers do not need a parallel Tilo-only type system.

RetryPolicy

What a caller may safely do after losing the completion response.

RiskLevel

Consequence class used by policy, confirmation UI, and audit logs.

Constants

AGENTS_AUDIENCE_TAG

ActionContract::tags entry of an action for Audience::Agents.

ARGUMENT_RISK_TAG

ActionContract::tags entry of an action whose risk, and therefore whether it needs confirmation, depends on the arguments it is invoked with (a generic edit that may delete). The publishing host classifies each invocation; a caller that cannot classify arguments treats the action as requiring confirmation (see ActionContract::advertised_confirmation).

ATTENDED_TAG

The contract tag of an action that needs its person attending: it opens a chooser for them, asks them for a credential or a sign-in, or shows something only they may see. Whoever acts for a person (an agent, a bot, an app) is always asked first, and no answer allows it unasked, not even one given for that very action. The person’s own click needs no workspace’s consent: the chooser, the sign-in or the reveal in front of them is their decision, so like an effect of OWN_DEVICE_SCOPE it needs only what reading needs and runs only on the device of whoever starts it.

COMPENSATED_UNDO_TAG

ActionContract::tags entry of an action that reaches outside its document through a queue (a file rename the device carries out) and whose undo queues the compensating change. It is still an Outside action for the grants deciding it, but it can be taken back: a person reviewing it is told it changes their work, not that it sends something away.

DOCUMENT_READ_TAG

ActionContract::tags entry of the read-only action that answers, when invoked with no arguments, the first page of the document an app has open (a word processor’s text, a sheet’s used cells, a deck’s outline). A caller that just opened a file reads it through this action without knowing the app.

FIELD_EDIT_PARAM

The parameter of a generic field edit that carries the edit.

HOST_RENDER_TAG

ActionContract::tags entry of an effect a host answers in a render service of its own rather than in the record’s confined app worker: rendering a timeline to video needs a GPU and a media stack, which a confined worker has neither of. A host without such a service leaves the effect out of what its agents are offered.

HOST_UNSUPPORTED_CODE

Availability::Unavailable code of an action whose REQUIRES_HOST_PREFIX requirement this host cannot meet.

HOUSEKEEPING_TAG

Contract tag on the declaration of a housekeeping verb: a change about the record rather than to it (#[action(housekeeping)], such as marking a channel read). An app does these on its own, so nobody is asked to review or confirm one: one an app emits while History shows a past version is dropped, and the app does it again once the person is back.

INCOMING_MESSAGE_FACET

Facet the executor writes on a change made by a verb its app marks #[action(incoming_message)]: a message someone received. The IncomingMessage trigger fires on it without knowing the app’s schema.

INCOMING_MESSAGE_TAG

Contract tag on the declaration of such a verb, so a surface and a catalogue show it.

IRREVERSIBLE_TAG

ActionContract::tags entry of an action whose document change Undo reverts but which also loses something Undo cannot bring back (an account’s secret every device forgets): it cannot be taken back, so a destructive one is confirmed through every door.

MAX_OFFLOAD_CPU_TIME_MS

Largest CPU time an Offload may declare: a compute job’s ceiling.

MAX_OFFLOAD_MEMORY_BYTES

Largest memory an Offload may declare: a compute job’s ceiling.

MAX_OFFLOAD_OUTPUT_BYTES

Largest output an Offload may declare: a compute job’s ceiling.

MEMBER_OWN_TAG

ActionContract::tags entry of an action any member of a workspace may ask the workspace’s host to run for themselves on a record of the workspace (linking their own account elsewhere). The host runs it as that member, under their own standing, so the action’s door and its own checks decide what it may do; its answer goes back to the asking device alone.

MIN_OFFLOAD_MEMORY_BYTES

Smallest memory an Offload may declare: a compute job’s floor.

OPENS_PATH_EXTENSION_PREFIX

Prefix of the ActionContract::tags entries naming the file extensions (lowercase, without the dot) an OPENS_PATH_TAG action opens: open:path-ext:csv. An opener naming none opens any file.

OPENS_PATH_TAG

ActionContract::tags entry of the action that opens the file its path parameter names in this app instance, reading it inside the app’s sandbox. A caller that launched the app with a file opens it through this action, and only through an action that declares it: one taking a path for another purpose (importing an installer image, exporting) is never guessed from its name.

OWN_DEVICE_SCOPE

The contract tag of an effect whose whole scope is the invoking person’s own device: it touches nothing a workspace shares and no one else (their clipboard, their own appearance, a network test from their own browser, a draft of their own). A workspace’s grants have nothing to consent to, so it needs only what reading needs (ActionContract::need), and a guest presses it as the workspace’s owner does. Whatever shared it goes on to change goes through that change’s own action and is decided there. Being the invoker’s own device, it runs only for the person at the device it acts on and those acting for them. An effect that reaches other people (a direct message, a call, a shared live context) is not of this scope.

OWN_RECORD_SCOPE

The contract tag of an action that changes a record of the invoking person’s own (their contact directory, a settings section of theirs), carried out on that record rather than on the workspace’s document. Only the host of that person changes it, and only for them, so a workspace’s grants and roles have nothing to decide: it needs only what reading needs (ActionContract::need). What it does stays its kind: a change Undo takes back is still Undoable, and asks nothing before it runs.

PEOPLE_AUDIENCE_TAG

ActionContract::tags entry of an action for Audience::People.

REQUIRES_HOST_PREFIX

Prefix of the ActionContract::tags entries naming a capability of the host the action needs: requires-host:native-paths. On a host without it the action is published unavailable, coded HOST_UNSUPPORTED_CODE, and so refused, wherever it is offered: an app declares what its action needs once instead of hiding it per host. A requirement the host does not know is one it lacks.

REQUIRES_NATIVE_PATHS_TAG

REQUIRES_HOST_PREFIX entry of an action that reaches files through their file system path, as importing a folder by its path does; browser storage has no paths.

UNTRUSTED_CONTENT_TAG

ActionContract::tags entry of an action whose result carries content from outside the user’s own data (a web page’s text, its logs): data for the caller to reason about, never instructions to follow.

Functions

action_node

The node of the action action on the resource resource (of kind resource_kind) the app app publishes, below base (a workspace, or the root for a path relative to one), and below the one field it writes if any: where every door decides it.

phrase_is_meaningful

Whether a typed confirmation phrase names what the action destroys (a drive’s name, an app’s name), rather than a generic word such as “CONFIRM”. A typed phrase is for irreversible, high-risk actions, and its point is that the person reads what they are about to lose.

resource_node

The node of the resource resource (of kind resource_kind) the app app publishes, below base (a workspace, or the root for a path relative to one): where a reading of it is decided, as an action of it is at action_node.