Device plugins¶
Native plugins in the Limiara app (apps/device-shell) are Tauri plugins
with a Rust half and, on phones, a Swift half for iOS and a Kotlin half
for Android, as device-push is (ADR 0030 §5).
They get nothing ambient: each one declares the local-only capabilities it
uses, and the shell hands it a handle for exactly those
(ADR 0024 §6). These capabilities are
not user permissions and grant nothing in the workspace. A plugin that
needs record content reads it through the engine as the signed-in member,
so sharing, permissions and the offline lease still decide.
Local capabilities¶
| Capability | What it reaches |
|---|---|
device.replica_changes |
The replica change feed: what changed in the device's copy of the workspace, by id. |
device.route_context |
The current-route context: which object or record the web shell shows, by id. |
device.assistant |
The assistant bridge: the assistant.v1 operations and the index stream, for a system assistant. |
Declare them with platform_device::capabilities::PluginDeclaration, and
ask the controller for the grant when the shell builds the plugin:
let declaration = PluginDeclaration::new("device-route-probe", &["device.route_context"])?;
let grant = controller.grant(&declaration);
let routes = grant.route_context()?; // declared: a subscription
let refused = grant.replica_changes(); // not declared: device.capability_not_granted
An unknown capability name refuses the whole declaration
(device.capability_unknown). None of them needs an OS permission, and
the web view reaches none of them: no route of the local command bridge
serves the feed, and the route context only takes messages from the web
shell, never hands them back.
The replica change feed¶
A ChangeSubscription yields FeedEvents: a sequence number, the
workspace, and one change. Changes carry ids, never field values
(ADR 0034 §9):
| Change | Meaning |
|---|---|
upserted (object, record) |
Created, changed or undeleted, on the device or on the server. |
removed (object, record, reason) |
deleted, on either side and including a delete that won a conflict, or access_lost, when sharing or permissions changed on the server. |
object_removed (object, reason) |
Every record of the object at once: left_replica (deleted, or no longer readable) or plugin_suspended for an object a plugin declared. |
definitions_changed (metadata_version) |
Fields, labels or other definitions moved; re-read what you derive from them. |
workspace_locked, workspace_unlocked |
The offline lease locked the replica, or a sync reopened it. |
workspace_cleared (reason) |
signed_out or wiped: the last event for the workspace, published before its files are deleted. |
rebuild (reason) |
subscribed, opened (a workspace opened) or fell_behind: rebuild from the records you can list. |
Delivery is at least once, in the order changes were committed, while the
app runs. The feed keeps the latest 1,024 events; a subscriber that falls
further behind gets rebuild and carries on from there. It is not
persisted, so a plugin rebuilds at launch. Treat events as prompts to read
again, not as counts: an upserted record you can no longer read is gone.
The current-route context¶
A RouteSubscription holds the latest CurrentRoute: the workspace, a
route pattern (home, object, new_record, record, search,
settings or other), and the object and record id where the pattern has
them, or nothing when no workspace page is shown. It holds one value, so a
slow plugin sees where the shell is now rather than every step. The route
never steps back: the web shell sends one message at a time, and the bridge
keeps the latest one it received over an earlier one it is still checking.
When the shell shows no workspace page while the workspace stays open, such
as when every feature is disabled, the route is other.
The web shell sends it only to a host whose UI contributions carry
route_context: true, which the server's never do. It sends the pattern's
name, never the address, so search terms and filters stay in the page. The
bridge treats the message as untrusted data: it accepts only that shape,
an object the member reads in the replica and a record id of that object,
and passes it on as data.
The assistant bridge¶
A plugin that connects a system assistant (Siri's App Intents on iOS,
AppFunctions on Android) declares device.assistant and gets an
AssistantBridge from grant.assistant()
(ADR 0034). No route of the local
command bridge and no Tauri command serves it, so nothing in the web view
can reach it. The bridge holds all of the logic; the plugin's Swift or
Kotlin half maps the platform's calls onto bridge requests and the answers
back onto the platform's types, and never reads the replica, checks
permissions, formats values or writes its own messages.
Requests and answers¶
Every request is an AssistantRequest under the assistant.v1 contract,
as Rust types or as JSON through call_json. The contract file,
crates/platform-device/contract/assistant.v1.schema.json
(platform_device::assistant::SCHEMA), is a JSON Schema of every request,
answer and index update, with each code's sentence; code the native half
against it:
{"contract": "assistant.v1", "assistant": "siri", "device_unlocked": true,
"operation": {"name": "get", "object": "custom:account", "record": "a01-0000000001"}}
assistantissiriorgemini. The shell builds the bridge for its platform's assistant, and a request naming another is refused.device_unlockedis what the platform says. Require an unlocked device with the platform's own setting as well; the bridge refuses a locked one (assistant.device_locked), so a mistake fails closed.
Every call runs as the signed-in member through the command bridge, so permissions, sharing, field-level security, validation rules and lookup filters apply as they do in the app. Before each one the bridge checks the workspace's assistant policy in the replica's definitions, which only narrows what the member could reach. Answers are inert data: values with display text the bridge formatted, never markup.
| Operation | What it does |
|---|---|
describe |
The exposed objects with the fields the member reads, the offered quick actions and whether records have a timeline, with the metadata version. Ask again when it moves. |
search |
Search over the exposed objects, or one (object), at most 20 results. |
get |
One record's readable values, each with a display value. |
list |
Records of one object, with at most 5 typed conditions and one sort, 50 a page with a cursor. |
timeline |
A record's Activity timeline, paged with a cursor. |
actions |
The quick actions offered on an object or a record. |
create, update, run_action |
Prepare a change and answer with a confirmation. |
commit |
Makes a prepared change, with the confirmation's token only. |
on_screen |
The record the app shows, by id, when its object is exposed. |
A list condition is {"test": ..., "field": ..., "value": ...} with the
test equals, not_equals, contains, before, after, between (with
from and to) or is_empty. The bridge compiles conditions into the
record query language; never send query text. Delete, owner changes,
sharing, bulk changes and metadata changes are not offered.
Writes: prepare, confirm, commit¶
create, update and run_action run the save path as a dry run and
answer with a Confirmation: the object's label, the record's name for an
update or a quick action, each field the request sets with its label and
new display value (not what a before-save automation adds when the change
is saved), and a token. Show it to the member with the platform's own
confirmation, every time, then send commit with the token. There is no
way to skip the confirmation, and nothing writes without a token.
A token is single use, lives two minutes and is bound to that exact change,
the record's version and the metadata version. commit refuses
assistant.confirmation_invalid (used, expired or unknown) and
assistant.confirmation_stale (the record or the definitions moved): ask
the member again. Writes record the assistant as the source, and the
device's push marks them so the server checks them against its current
policy; a write it no longer allows comes back as assistant.not_allowed,
like any write the server refuses.
Errors¶
An error answer has a code, a message to speak or show as it is, and
for assistant.invalid the failing fields with their labels and
messages. Branch on the code; never compose a message.
| Code | When |
|---|---|
assistant.signed_out |
No workspace on the device, or a sign-out or wipe in progress. |
assistant.locked |
Past the offline lease. |
assistant.unavailable |
The key or storage cannot be opened. |
assistant.device_locked |
The device is locked. |
assistant.disabled |
Assistant access is off for the workspace or on this device. |
assistant.not_found |
No such record, or one the member cannot read: the same answer. |
assistant.object_not_exposed |
The policy does not expose the object, or the member cannot read it. |
assistant.not_writable |
The policy does not let assistants write the object. |
assistant.action_not_offered |
The policy does not offer the quick action. |
assistant.not_permitted |
The member may not make this change. |
assistant.invalid |
The request or a value is not valid. |
assistant.confirmation_invalid, assistant.confirmation_stale |
See above. |
assistant.not_allowed |
The server's policy refused a pushed write. |
assistant.failed |
Anything else. |
The member's settings on the device¶
DeviceAssistantSettings holds the member's choice on the device, kept
with the stored session: assistant_access (on by default; off answers
assistant.disabled) and indexing (off until the member turns it on).
The shell changes them with Controller::set_assistant_settings.
The index stream¶
A plugin that keeps the OS's semantic or search index takes
bridge.index_stream() and applies its updates, and nothing else, to the
index:
| Update | Apply it by |
|---|---|
upsert (entry) |
Adding the entry, or replacing the one for the same record. |
remove (workspace, object, record) |
Removing one entry. |
remove_object (workspace, object) |
Removing the object's entries. |
remove_workspace (workspace) |
Removing the workspace's entries. |
rebuild (workspace) |
Removing the workspace's entries; the upsert updates that follow are what it holds. |
refresh (workspace, expires_at) |
Moving every entry's expiry of the workspace. |
Entries are already filtered: indexing needs the workspace switch, the
object's indexable setting and the member's indexing setting, and holds
only the record's id, its object's label, its name unless the policy
excludes it, and the readable fields the policy does not exclude. Group
entries by workspace (a domain identifier on iOS, a namespace on
Android) and set each entry's expiry to expires_at, the offline lease
length from when it was written; refresh moves it after each sync. A
lease that locks keeps the index. Sign-out and wipe remove the workspace's
entries before its replica goes.
At each launch, after the shell opened what it holds, call
bridge.sweep(&indexed) with the workspaces the index holds entries for.
Remove every workspace it lists, and every entry that expired before
remove_expired_before.
On-screen awareness uses on_screen and ids only. Describe the activity
with the record's name only when the object is indexable, and never mark
it as eligible for public indexing.
The reference harness¶
apps/assistant-harness drives the assistant bridge with no phone, and
is the conformance check native assistant plugins are built against
(ADR 0034, slice 4). It starts a
workspace server on a loopback port, signs a device in, syncs it into an
encrypted SQLite replica, and sends each request through call_json as
the JSON bytes a plugin would. Time moves only when a script moves the
harness's clock, which is both the confirmation token's clock and the
replica's trusted clock for the offline lease.
cargo run --locked -p assistant-harness -- run --assistant both
cargo run --locked -p assistant-harness -- run tests/assistant-harness/04-tokens.json
cargo run --locked -p assistant-harness -- export --assistant both --out harness-export
cargo run --locked -p assistant-harness -- session --assistant gemini
cargo run --locked -p assistant-harness -- schema
Scripts are JSON files in tests/assistant-harness/, in the
assistant-harness.v1 format. Each step does one thing and yields one
document, which expect checks with JSON Pointers:
{"note": "a used token is refused",
"call": {"operation": {"name": "commit", "token": "${first}"}},
"expect": {"error": "assistant.confirmation_invalid",
"message": "That confirmation is no longer valid. Ask again to make the change."}}
| Step | What it does |
|---|---|
call |
Sends operation, with contract, assistant and device_unlocked filled in unless given, or raw bytes. malformed: true marks a request the contract file must refuse; the bridge must answer it assistant.invalid. |
world |
sync, push_queue, begin_sign_out, sign_out, wipe, sign_in, storage_unavailable, device_settings, set_switch, set_policy, relabel, server_update, server_record, server_history, device_history, web (a web-shell request), set_offline_limit, advance_clock and check_lease. |
index |
subscribe to the index stream, drain what is ready ({"updates": [...], "refreshes": n}), or sweep for the workspaces an OS index holds. |
expect takes kind (the result's), error and message (the code and
the sentence spoken), equals, matches (objects need only the keys
given), includes and excludes (an array element that matches),
length, present, absent, never_contains, kinds (the index
updates' kinds, in order) and same_as (a document an earlier step kept
with save_document). save keeps a value as a variable, used as
${name}: every script starts with workspace, other_workspace,
member, device, assistant, other_assistant, offline_limit and
the reference records acme, hidden (a colleague's the member cannot
read) and vault (in an object the policy does not expose). The world's
objects and fields are described at the top of
apps/assistant-harness/src/world.rs.
On every call the harness also checks the request and the answer against the contract file, and that an error's message is its code's sentence or one of its documented forms, with no id, hidden value or code in it. A run of the whole suite fails if the scripts together missed an operation, a condition test, a result kind, an error code or its sentence, a write kind prepared or committed, an index update kind or a world action.
Replaying it in a native plugin's tests¶
A Swift or Kotlin plugin's own tests replay the suite through their bridge binding, without re-implementing any of it:
- Export.
assistant-harness export --assistant both --out DIRwritesassistant.v1.schema.json, the scripts, andtranscripts/{script}.{assistant}.jsonfor each script and assistant: the variables, and for each step the step with its variables resolved, the exactrequestbytes and thedocumentthe bridge answered. - Decode. Feed every
documentof a call step to the binding's answer decoding and check that it maps the result kinds onto the platform's types, passesmessagethrough unchanged and branches only oncode. Ids, tokens and times differ between runs, so compare the shape and the fixed values, not the ids. - Encode. For each intent or function the plugin declares, build the
request from the platform's parameters and check it against the
transcript's
requestand against the contract file. - Live. Run
assistant-harness session, which prints the variables, then reads steps (the script format, one JSON object a line) on standard input and answers each with{"ok": true, "document": ..., "request": ...}or{"ok": false, "error": "..."}. A test that routes its binding'scall_jsonthrough{"call": {"raw": "<request>"}}steps drives the reference world from Swift or Kotlin, and can replay a script's world and index steps in between.
Plugins an app adds¶
The shell names its own plugins (device-keystore, device-browser,
device-push and, in debug builds, device-route-probe). An app crate
built on the shell can link more native plugins without the shell naming
them. It depends on the device-shell library with its entry-point
feature off (the shell's own app::run, its Tauri configuration and its
web build), declares its own mobile entry point with its own Tauri
configuration, and builds the app with device_shell::app::AppBuilder:
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
let built = PluginDeclaration::new("device-example", &["device.route_context"])
.map_err(|error| error.to_string())
.and_then(|declaration| {
AppPlugin::new(declaration, example::init(), |app, grant| {
let routes = grant.route_context().map_err(|error| error.to_string())?;
example::follow(app, routes);
Ok(())
})
.and_then(|plugin| AppBuilder::new().plugin(plugin))
.map_err(|error| error.to_string())
});
match built {
Ok(builder) => builder.run(tauri::generate_context!()),
Err(error) => eprintln!("the app could not start: {error}"),
}
}
- The plugin is registered with Tauri before the app starts, after the
shell's own. Its declaration names it: a declaration for another plugin
is refused (
device.plugin_name_mismatch), as is a name the shell uses (device.plugin_reserved) or one added twice (device.plugin_duplicate). - The start function runs once, after the controller has reopened what the device holds, with the grant the controller builds from the declaration: exactly what it names, as for the shell's own plugins. A plugin that cannot start is logged and left out; the app goes on.
- Nothing widens. An extra plugin has the same local capabilities as any other, and the same limits: the web view reaches none of them, and records are read through the engine as the member.
The route probe¶
apps/device-shell/src-tauri/route-probe is the reference: a debug-build
test plugin that declares device.route_context and records each route as
ids. Its Swift and Kotlin halves write a trail in the app's temporary
directory. The desktop tests drive a route through the limiara:// scheme
to it, and the ios and android workflows ask a debug build for a
simulated route by creating simulate-route in that directory, then read
the trail from the simulator's container and the emulator.