refactor(providers): unify provider profile identity and scoped references #2371

Description

Unify provider-profile identity around the OpenShell resource convention and make profile references explicitly workspace-aware.

ProviderProfile was introduced as an unscoped catalog value with a logical id. Custom profile storage later wrapped it in StoredProviderProfile.metadata, copying profile.id into metadata.name. Providers now refer to that same logical key through Provider.type, with the profile scope carried separately in Provider.profile_workspace.

The resulting identity model has several names for the same value and two meanings of id:

provider.type == profile.id == stored_profile.metadata.name
stored_profile.metadata.id == opaque resource UUID

For user-managed profiles, the actual reference is composite:

(provider.profile_workspace, provider.type)
    ->
(stored_profile.metadata.workspace, stored_profile.metadata.name)

This is easy for both humans and agents to misuse. It has also allowed runtime catalog code to erase profile scope and index entries only by normalized profile ID.

Context

• ProviderProfile.id originated when profiles were catalog payloads rather than stored resources: feat(providers): add profile-backed policy composition #1037.
• StoredProviderProfile { ObjectMeta metadata; ProviderProfile profile; } was added with the custom registry: feat(providers): add custom profile registry #1170.
• Workspace scoping in feat(workspace): add workspace resource model with scoping, membershi… #2243 exposes the mismatch because the profile scope is stored outside the profile payload and is lost when source snapshots are reduced to ProviderProfile values.
• Profile List/Get currently also serve two different concerns: exact-scope management of user profiles and discovery of the effective runtime catalog. Those concerns need explicit APIs or read models.

This cleanup does not need to preserve the existing provider-profile wire or file shape. Do not add compatibility aliases, fallback lookup paths, or data backfills; update the model and its consumers atomically.

Proposed Direction

1. Separate profile specification from profile identity. For example, introduce a ProviderProfileSpec containing credentials, endpoints, binaries, discovery, and presentation fields.

2. Use ObjectMeta.name as the canonical name for stored user-managed profile resources. Keep ObjectMeta.id as the opaque resource UUID.

3. Introduce one typed profile key/reference containing scope and canonical name. Provider runtime code should resolve profiles through this type rather than passing bare strings:

   ProfileKey {
       scope: Platform | Workspace(name) | WorkspaceAgnostic,
       name: NormalizedProfileName,
   }
   

4. Have profile sources return entries that retain scope and source provenance. Built-in and interceptor-provided entries should be represented explicitly as workspace-agnostic/source-managed rather than relying on implicit fallback behavior.

5. Key EffectiveProviderProfileCatalog by the typed profile key and require provider resolution, policy composition, refresh, environment resolution, and revision hashing to use the provider's complete profile reference.

6. Separate effective-catalog discovery from exact-scope user-profile CRUD, or otherwise make the read semantics explicit. CLI preflight and runtime creation must observe the same effective catalog; mutation APIs must target only mutable user-managed resources in the requested scope.

7. Rename or restructure Provider.type and Provider.profile_workspace so the protobuf expresses a single profile reference instead of two independently interpreted fields.

8. Update profile YAML, CLI output/input, protobufs, architecture documentation, published provider documentation, and interceptor contracts to use the new terminology consistently.

Definition of Done

• A profile's canonical name is represented once; ProviderProfile.id is removed rather than mirrored into metadata.name.
• Resource UUIDs and human-addressable names have distinct, consistently documented meanings.
• No runtime profile lookup accepts only a raw profile ID/name when scope is required.
• Platform and workspace profiles with the same canonical name can coexist and resolve according to an explicit provider reference.
• Different workspaces can independently define the same profile name.
• Built-in and interceptor-provided profiles retain explicit source and scope semantics.
• Effective catalog List/Get or replacement discovery APIs use the configured provider-profile sources.
• User-managed CRUD operates on the exact requested scope and cannot mutate source-managed profiles.
• Tests cover same-name platform/workspace profiles, same-name profiles across workspaces, source-managed profiles, CLI creation, policy composition, refresh, and environment resolution.
• Architecture and user-facing provider documentation describe the canonical terminology and lookup rules.