PCP · pcp

PCP Core — Capability Protocol Foundation

Core types, traits, and error definitions for the Portal Capability Protocol (PCP). Defines PcpServer trait, CapabilityManifest, Element model, and cross-cutting services (audit, permission, signing, rate limiting).

pcp-corev0.2.0pcp

23.2K

Lines of Code

Tests

190

Files

Architecture

28 modules: types (core types), traits (PcpServer trait), element (UI element model), surface (surface/workspace model), manifest (capability manifest and signing), detection (app detection), event (event bus types), permission (permission engine), audit (audit logging), rate_limit (rate limiting), session (session management), signing (Ed25519 manifest signing), i18n (internationalization), learning (learning state types), recovery (crash recovery types), pipeline (detection pipeline), supervision (app supervision), gates (capability gates), invalidation (cache invalidation), narrative (narrative synthesis types), pattern (pattern matching), performance (performance tracking), resolution (action resolution), transaction (transaction model), adapter_rich (rich adapter types), capability_diff (capability diffing), debug_mode (debug utilities), action_resolution (action resolution), error (PcpError).

Overview

pcp-core is the foundation of the Portal Capability Protocol — the typed protocol that allows Portal-native applications (Tier 1) and external apps via AT-SPI2 (Tier 2) to expose their capabilities to the Portal desktop. The crate defines the PcpServer trait (6 async methods: manifest, invoke, validate_params, subscribe_events, query_dynamic_state, shutdown), the capability model (CapabilityManifest, Capability, CapabilityCategory, AuthLevel, SideEffect), the UI element model (Element with AtspiRole, AtspiState, TableInfo, ValueInfo, TextSelection), and the surface model (Surface, Geometry, WorkspaceId). It also includes cross-cutting concerns: audit logging, permission engine, Ed25519 manifest signing, rate limiting, session management, and i18n string catalogs.

Key Types

PcpServerCore trait (6 async methods): manifest(), invoke(), validate_params(), subscribe_events(), query_dynamic_state(), shutdown(). Every Tier 1 app implements this.

CapabilityManifestApp capability manifest — app_id, capabilities (id, category, auth_level, side_effect), signing info. Signed with Ed25519.

CapabilitySingle capability definition — id, category (FormatAction/NavigationAction/etc.), auth_level, side_effect flag.

ElementUI element model — ElementId, AtspiRole (button/text/edit/etc.), AtspiState, TableInfo, ValueInfo, TextSelection, ElementRelationships.

SurfaceSurface model — SurfaceId, Geometry, SurfaceType, SurfaceState, OutputId, WorkspaceId, TileEdge.

PcpErrorError type — manifest errors, permission denied, rate limited, capability not found, invocation failures.

AuthLevelAuthentication level required for a capability — None, AppIdentity, UserConfirmation.

SideEffectWhether a capability modifies state — Pure (read-only) or Destructive (modifies).

Modules

traits

PcpServer trait — the 6-method server contract every Tier 1 app implements.

manifest

Capability manifest types — CapabilityManifest, Capability, CapabilityCategory, AuthLevel, SideEffect, ManifestError.

element

UI element model — Element with role, state, relationships, table info, value info, text selection.

surface

Surface model — Surface with geometry, type, state, output and workspace associations.

detection

App detection — how Portal discovers and registers apps (Tier 1 via .desktop files, Tier 2 via AT-SPI2).

event

Event types — PcpPushEvent, EventDomain, SubscriptionId, OverflowStrategy for the push event bus.

permission

Permission engine — checks auth levels and user confirmations for capability invocations.

audit

Audit logging — records all capability invocations for security analysis.

signing

Ed25519 manifest signing — load_or_create_key, sign_manifest, verify_manifest.

rate_limit

Rate limiting — per-app, per-capability invocation rate limits.

session

Session management — client sessions for stateful capability interactions.

learning

Learning state types — CapabilityUsageRecord, ConfirmationBehavior, AdapterEffectivenessScore.

recovery

Recovery types — CrashRecoveryManager, TransactionRecord, RecoveryPhase, DataDurability.

Data Flow

App implements PcpServer → registers with pcpd via .desktop X-Portal-PCP-Manifest → pcpd verifies Ed25519 signature → capabilities become available → Portal invokes via IPC

Dependencies

External (17)

thiserror workspaceserde workspaceserde_json workspacetokio workspacechrono workspacedashmap workspacetracing workspacehmac workspacesha2 workspaceuuid workspaceasync-trait workspacegetrandom 0.2ed25519-dalek workspacerand workspacebase64 workspacedirs workspaceparking_lot workspace

Foundation crate — all other PCP crates depend on this. External: serde, async-trait, thiserror, ed25519-dalek.