PrincipalGrain: Standardizing Identity-Scoped Agent Tracking

Why Principal?

The old name overloaded the word client. Sometimes client meant an HTTP caller, SDK consumer, MCP client, browser, or LLM client. In other places it meant the identity-scoped owner of agent tracking. Those are different ideas.

A principal may be a human user, a system identity, a tenant, a service account, or another authenticated caller. That language fits FabrCore's tracking and ACL model better than client or owner.

What Changed

IClientGrain, ClientGrain, ClientGrainState, and ClientGrainOptions are now IPrincipalGrain, PrincipalGrain, PrincipalGrainState, and PrincipalGrainOptions. Registry entries now use EntityType.Principal, lifecycle methods use RegisterPrincipal and DeactivatePrincipal, and eviction reports PrincipalTrackingRemoved.

Operational names moved too: persistent state, telemetry sources, and metrics now use the principal naming family, including fabrcore.principal.*.

What Did Not Change

The word client still belongs where it means an access mechanism. HttpClient, SDK API clients, OpenAI-compatible clients, MCP clients, LLM chat clients, and Orleans IClusterClient are still clients. The rename is about identity-scoped ownership and tracking.

The Host API wire headers also keep their current names for now. For example, x-user-handle carries the principal handle partition used by the Host API.

FabrCore.Client Removed

The obsolete FabrCore.Client project has been removed. Applications should call FabrCore through the Host REST API, WebSocket ingress, host services, and the typed SDK API client in FabrCore.Sdk.

Migration Guidance

• Replace ClientGrain references with PrincipalGrain.
• Rename identity-scoped owner/client/user-handle prose to principal-handle language where it describes tracking or ACL boundaries.
• Update diagnostics expectations to use EntityType.Principal.
• Remove dependencies on FabrCore.Client, ClientContext, DirectMessageSender, and ChatDock.