Glossary

Core Concepts

PCP (Portal Control Protocol) The protocol that governs how System Intelligence perceives and acts on the desktop. PCP defines the message format, capability discovery, permission model, and execution pipeline. Every action SI takes flows through PCP.

System Intelligence (SI) The reasoning layer. SI perceives desktop state through PCP events, forms intent, and invokes capabilities through the daemon. It connects to the daemon as a PCP client, with the same standing as any other client — no privileged in-process path.

Compositor The Wayland compositor that manages all surfaces, applications, and input. The compositor is the authority on what exists on the desktop. It contributes surface and workspace state to PCP through the compositor capability domain; it does not host PCP.

Adapter A daemon module that recognizes application patterns and derives semantic capabilities from them. Adapters bridge the gap between raw accessibility data and the structured capability format the registry stores.

Capability A semantic operation an application or system component can perform. Capabilities are the unit of functionality that SI invokes. Examples: mail.compose, window.close, volume.set.

Structural Terms

Surface A top-level window or popup tracked by the compositor. Every surface has an ID, a title, a geometry, and a set of state flags (focused, minimized, fullscreen). Surfaces are the spatial unit of the desktop.

Element A single interactive UI component from the AT-SPI2 accessibility tree. Buttons, text fields, menu items, sliders, and links are all elements. Elements are the finest-grained targets that PCP can address.

Intent A structured representation of what SI wants to do. An intent has a type (navigate, activate, delete, compose), a target (an app, surface, or element), and parameters. Intents enter the execution pipeline after target resolution.

Session Context The current desktop ambient state: focused surface, open applications, recent interactions, workspace layout, and input modality. The session context informs target resolution and default app selection.

Execution Pipeline The full request lifecycle from intent classification to audit logging. The pipeline has six stages: target resolution, permission check, action resolution, execution, state verification, and audit logging.

Capability System

Capability Manifest A complete list of capabilities a Tier 1 (native) application exposes. Manifests are signed by the developer using Ed25519 and verified by the daemon at registration time.

Capability Registry The daemon’s live database of all capabilities from all running applications. The registry updates dynamically as applications launch, close, and change state.

Capability Tier The classification of how a capability was discovered. Tier 1 capabilities come from signed manifests. Tier 2 capabilities are derived from accessibility data — AT-SPI2, or MSAA/UIA through the Wine bridge for Windows applications. Tier 3 capabilities are backed by input simulation.

Tier 1 (Native) Applications that ship a signed capability manifest. The daemon loads the manifest and registers capabilities directly, without runtime probing. This is the fastest and most reliable tier.

Tier 2 (Accessibility) Applications that expose accessibility data — through AT-SPI2, or through MSAA/UIA when running under Wine. The daemon probes the accessibility tree, pattern-matches UI elements, and enriches discovered capabilities with element IDs.

Tier 3 (Simulation) The universal fallback. Applications that expose neither a manifest nor accessibility data receive window-level capabilities driven by synthetic input. The compositor’s own operations (window management, workspace switching, display configuration) are exposed separately through the compositor capability domain, not as a tier.

Security and Permissions

Domain APP, COMPOSITOR, or SYSTEM. The three privilege boundaries in PCP’s security model. Domains are separated by hard walls that prevent cross-domain escalation without explicit authentication.

Privilege Domain A synonym for domain. Used when emphasizing the security boundary rather than the operational scope.

Trust Level (TL) An authentication level (0 through 3) that determines what actions a request is authorized to perform. TL0 is unauthenticated public access. TL1 is standard user access. TL2 is elevated (privileged) access. TL3 is compositor-internal system access.

Auth Level A synonym for trust level. Used in permission mapping tables.

Confirmation Gate A multi-modal prompt (voice, visual, haptic) that requires the user to explicitly approve an action before execution. Triggered by destructive or high-privilege actions.

Audit Trail An append-only, tamper-evident (hash chain) log of every action and permission decision. Separate audit files exist for each privilege domain. Retained for 90 days.

Infrastructure

Supervisor The fault-isolation layer. In the primary model, isolation comes from process boundaries: the daemon, the compositor, and each Tier 1 application run in separate processes. A supervision library provides analogous watchdog and recovery machinery for hosts that embed PCP servers in-process.

Event Bus The daemon’s message bus that delivers compositor events, AT-SPI2 events, and capability change events to subscribers. Events support smart coalescing to reduce redundant updates.

Smart Coalescing An event optimization that merges rapid successive state changes into a single delivery. For example, 50 resize events in 100ms are coalesced into one delivery with the final geometry.

Element Cache An in-memory cache of AT-SPI2 accessibility tree data per surface. The cache avoids repeated D-Bus roundtrips for queries that hit recently-read elements. Budgeted at 256 KiB per surface.

Capability Diff An event describing changes to an application’s capabilities: capabilities added, removed, or modified. Diffs are emitted when the adapter detects a state change (new dialog, document opened, network state changed).