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 embedded in the compositor. SI perceives desktop state, forms intent, and invokes capabilities through PCP Core. It is not an external agent or a separate process; it is a compositor subsystem.

Compositor The Wayland compositor (Wayfire-based) that manages all surfaces, applications, and input. The compositor is the authority on what exists on the desktop. PCP operates within the compositor process.

Adapter A compositor module that recognizes application patterns and derives semantic capabilities from them. Adapters bridge the gap between raw accessibility data and the structured capability format that PCP Core expects.

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 compositor at registration time.

Capability Registry The compositor’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 AT-SPI2 accessibility data. Tier 2b capabilities come from the Wine/MSAA bridge. Tier 3 capabilities are compositor-internal.

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

Tier 2 (AT-SPI2) Applications that expose accessibility data through AT-SPI2. The compositor probes the accessibility tree, pattern-matches UI elements, and enriches discovered capabilities with element IDs.

Tier 2b (Wine) Windows applications running under Wine. The Wine bridge translates MSAA and UIA accessibility data into the PCP capability format.

Tier 3 (Compositor) Capabilities that exist entirely within the compositor: window management, workspace switching, display configuration. Registered at startup, never change during a session.

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 (HMAC chain) log of every action and permission decision. Separate audit files exist for each privilege domain. Retained for 90 days.

Infrastructure

Supervisor The PCP supervision layer responsible for watchdog monitoring, memory budget enforcement, and panic recovery. The supervisor operates at trust level 3 and can intervene when PCP Core misbehaves.

Event Bus The in-process 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).