Intent Taxonomy

Overview

Every action the System Intelligence layer performs through PCP belongs to an intent category. This taxonomy exists for three reasons: permission routing, confirmation gating, and audit classification.

Permission routing uses the category to determine which privilege domain handles the action. An APP_MANAGEMENT intent routes through the desktop management path, while a FILE_OPERATION intent routes through the filesystem access path. This separation lets the compositor enforce per-domain policies without inspecting individual action parameters.

Confirmation gating ties user prompts to the risk profile of the category. A STATE_QUERY reads data and never prompts the user. A FILE_OPERATION that deletes data prompts unless the caller holds elevated privileges. The side_effects field on each capability refines this further within the category.

Audit classification tags every logged PCP action with its category and effect level. Operators reviewing audit trails can filter by category to see all file operations, all media playback controls, or all hardware adjustments without reading individual action payloads.

The taxonomy is not a hierarchy of importance. SYSTEM is not “higher” than ELEMENT_INTERACTION. The categories are orthogonal dimensions of the desktop model, and the compositor treats them as parallel routing keys.

Category Tree

The complete intent tree contains twelve categories. Each leaf node is a concrete action that SI can invoke through PCP Core.

INTENT
├── APP_MANAGEMENT
│   ├── app.launch(desktop_id, args?)
│   ├── app.close(app_id, force?)
│   └── app.switch(target)
├── SURFACE_MANAGEMENT
│   ├── surface.focus(surface_id)
│   ├── surface.minimize(surface_id)
│   ├── surface.maximize(surface_id)
│   ├── surface.close(surface_id)
│   ├── surface.move(surface_id, geometry)
│   ├── surface.resize(surface_id, geometry)
│   ├── surface.tile(surface_id, edge)
│   └── surface.arrange(layout, constraints)
├── ELEMENT_INTERACTION
│   ├── element.activate(element_id)
│   ├── element.select(element_id)
│   ├── element.toggle(element_id, state)
│   ├── element.scroll(element_id, direction, amount)
│   └── element.drag(element_id, target)
├── TEXT_INPUT
│   ├── text.set(element_id, text)
│   ├── text.insert(element_id, text, position?)
│   ├── text.delete(element_id, range)
│   ├── text.replace(element_id, range, text)
│   └── text.format(element_id, format)
├── TEXT_QUERY
│   ├── text.get(element_id, range?)
│   ├── text.search(element_id, query)
│   ├── text.get_selection(element_id)
│   └── text.get_full_document(element_id)
├── NAVIGATION
│   ├── nav.focus_app(target)
│   ├── nav.focus_element(element_id)
│   ├── nav.go_back(element_id)
│   └── nav.switch_tab(element_id, tab_index)
├── STATE_QUERY
│   ├── state.get_focused_app()
│   ├── state.get_visible_surfaces()
│   ├── state.get_workspace()
│   └── state.get_clipboard()
├── SYSTEM
│   ├── system.audio.volume(level)
│   ├── system.network.wifi(state)
│   ├── system.power(state)
│   └── system.packages(action, package)
├── MEDIA_PLAYBACK
│   ├── media.play()
│   ├── media.pause()
│   ├── media.seek(position)
│   └── media.set_volume(level)
├── COMMUNICATION
│   ├── comm.send_message(target, content)
│   └── comm.read_messages(source)
├── FILE_OPERATION
│   ├── file.open(path)
│   ├── file.save(path, content)
│   ├── file.copy(src, dst)
│   └── file.delete(path)
└── HARDWARE
    ├── hardware.display.brightness(level)
    └── hardware.input.send(events)

APP_MANAGEMENT controls application lifecycle: launching, closing, and switching between running applications. These actions operate on the desktop model’s application list.

SURFACE_MANAGEMENT controls compositor surfaces: focus, minimize, maximize, close, move, resize, tile, and arrange. Every action targets a specific surface by its compositor-assigned identifier.

ELEMENT_INTERACTION activates, selects, toggles, scrolls, and drags UI elements within a surface. These actions require the target surface to expose an element tree, which means Tier 1 and Tier 2 applications only.

TEXT_INPUT modifies text within an element: set, insert, delete, replace, and format. Like element interaction, these actions require a target surface with an element tree.

TEXT_QUERY reads text content: get a range, search within, get the current selection, or read an entire document. These are read-only operations on element text.

NAVIGATION moves focus between applications, elements, and tab contexts within an application. These actions change where subsequent input events land.

STATE_QUERY reads compositor and desktop state: the focused application, visible surfaces, current workspace, and clipboard contents. These actions never modify state.

SYSTEM controls system-wide settings: audio volume, network state, power state, and package management. These actions operate outside any individual application.

MEDIA_PLAYBACK controls media playback: play, pause, seek, and volume. These actions target whichever application currently holds the media session.

COMMUNICATION sends and reads messages. These actions interact with the system’s messaging infrastructure.

FILE_OPERATION opens, saves, copies, and deletes files. These actions pass through the filesystem privilege domain and carry the highest confirmation requirements.

HARDWARE controls physical device parameters: display brightness and raw input event injection. These actions operate at the device driver level.

Capability Schema

Each capability in the taxonomy is described by a structured schema. The compositor validates this schema at capability registration time and rejects malformed declarations.

{
  "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$" },
  "name": { "type": "string" },
  "description": { "type": "string" },
  "category": { "enum": ["APP_MANAGEMENT", "SURFACE_MANAGEMENT", "ELEMENT_INTERACTION", "TEXT_INPUT", "TEXT_QUERY", "NAVIGATION", "STATE_QUERY", "SYSTEM", "MEDIA_PLAYBACK", "COMMUNICATION", "FILE_OPERATION", "HARDWARE"] },
  "parameters": { "type": "object" },
  "returns": { "type": "object" },
  "side_effects": { "enum": ["none", "read", "write", "destructive", "network", "system"] },
  "confirmation_required": { "type": "boolean", "default": false },
  "undo_window_ms": { "type": ["integer", "null"] },
  "version": { "type": "string", "pattern": "^\\d+\\.\\d+$", "default": "1.0" },
  "auth_level": { "enum": ["public", "user", "privileged", "system"] }
}

id is the capability identifier. It must match the dot-separated format described below.

name is a human-readable label for display in management interfaces and audit logs.

description explains what the capability does. The compositor does not interpret this field, but management tooling and audit review interfaces use it.

category places the capability in one of the twelve intent categories. The compositor uses this for routing and policy enforcement.

parameters defines the input schema. The structure is an arbitrary JSON object, and the compositor validates it against the capability handler’s expected input type.

returns defines the output schema. Like parameters, this is an arbitrary JSON object validated at invocation time.

side_effects classifies what happens when the capability is invoked. This field drives confirmation gating and audit detail level. The full classification is described in the Side Effects section below.

confirmation_required is a boolean override. When true, the compositor prompts the user for confirmation before executing the action, regardless of the side_effects classification. When false (the default), the compositor uses the side_effects field to decide.

undo_window_ms defines the time window after invocation during which an undo is possible. A null value means the action is not undoable. The compositor uses this to present undo UI and to gate destructive actions that cannot be reversed.

version tracks the capability schema version. The default is 1.0. When a capability’s parameter or return schema changes, the version increments. The compositor can serve multiple versions simultaneously.

auth_level controls which privilege domains can invoke the capability. public capabilities are available to any caller. user capabilities require the caller to hold the user session context. privileged capabilities require elevation. system capabilities are restricted to the compositor itself.

Capability ID Format

A capability ID is a dot-separated string with a minimum of three parts. The general format is:

{domain}.{app_id}.{action}

The domain identifies the functional area. The taxonomy categories use short lowercase names: app, surface, element, text, nav, state, system, media, comm, file, hardware.

The app_id identifies the target application or subsystem. For applications, this follows reverse-DNS convention: org.xfce.mousepad. For system-level capabilities, it uses system or a subsystem name: system.audio.

The action identifies the specific operation within the domain.

Examples:

file.org.xfce.mousepad.open
mail.org.mozilla.thunderbird.compose
system.audio.volume
hardware.display.brightness

The reverse-DNS format for the app_id segment prevents namespace collisions. Two different applications named “editor” from different organizations register distinct capabilities: text.org.example.editor.read and text.com.other.editor.read.

The full ID pattern enforced by the schema is ^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$. This requires at least two dots (three segments), lowercase alphanumeric characters, and no leading digits in any segment.

Side Effects Classification

The side_effects field on each capability determines three things: whether the compositor prompts the user, how detailed the audit log entry is, and whether the action can be undone.

Level	Meaning	Confirmation	Audit Detail	Undoable
none	No observable effect	Never	Minimal (action only)	Not applicable
read	Reads data without modification	Never	Standard (action + target)	Not applicable
write	Modifies data, reversible	Only if auth_level < privileged	Standard (action + target + delta)	Within undo_window_ms
destructive	Modifies data, not reversible	Always	Full (action + target + full state)	No
network	Sends data over the network	Always	Full (action + target + payload size)	No
system	Alters system-wide state	Always	Full (action + target + before/after)	Within undo_window_ms

The none level applies to navigation and focus changes. The compositor logs that the action occurred but records nothing about the previous or resulting state.

The read level applies to all query operations. STATE_QUERY capabilities, TEXT_QUERY capabilities, and any capability that returns data without modifying it use this level. The audit log records what was queried but not the result.

The write level covers reversible modifications. Changing text in a document, resizing a surface, or adjusting volume all fall here. The compositor allows undo within the configured window and logs the change delta.

The destructive level covers irreversible modifications. Deleting a file, force-closing an application, or clearing a clipboard uses this level. The compositor always prompts the user unless the caller holds privileged or system auth level.

The network level covers any capability that transmits data outside the local system. Sending a message, fetching a URL, or syncing state to a remote service all use this level. The compositor always prompts and logs payload metadata (size, destination) but not content.

The system level covers changes to global system state: installing packages, toggling network interfaces, or changing power state. These actions affect all users and all applications, so the compositor always prompts and logs the full before-and-after state.