fix(access): verify subscription readiness with real user keys

When subscription access is requested with an explicit access_api_key, assign the subscription to the real target user, bind that user's API key to the subscription group, and probe readiness with the same key instead of falling back to a managed synthetic user.

Update the runtime/reconcile flows, adapter tests, and source-of-truth docs so subscription_ready now reflects user-visible host access rather than managed-key-only closure success.

internal/host/sub2api/client.go

@@ -151,6 +151,7 @@ type AssignSubscriptionRequest struct {
 type EnsureSubscriptionAccessRequest struct {
 	UserSelector string
 	GroupID      string
+	ProbeAPIKey  string
 }
 
 type SubscriptionAccessRef struct {

internal/host/sub2api/sub2api_test.go

@@ -851,7 +851,7 @@ func TestAssignSubscriptionWithMock(t *testing.T) {
 	}
 }
 
-func TestEnsureSubscriptionAccessWithMock(t *testing.T) {
+func TestEnsureSubscriptionAccessManagedProbeWithMock(t *testing.T) {
 	var calls []string
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		calls = append(calls, r.Method+" "+r.URL.Path)
@@ -911,6 +911,45 @@ func TestEnsureSubscriptionAccessWithMock(t *testing.T) {
 	}
 }
 
+func TestEnsureSubscriptionAccessRealUserProbeWithMock(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodGet && r.URL.Path == "/api/v1/admin/users/1/api-keys":
+			w.Write([]byte(`{"data":{"items":[{"id":501,"key":"caller-probe-key","name":"user-key"}]}}`))
+		case r.Method == http.MethodPut && r.URL.Path == "/api/v1/admin/api-keys/501":
+			var req struct {
+				GroupID int64 `json:"group_id"`
+			}
+			if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+				t.Fatalf("decode bind api key request: %v", err)
+			}
+			if req.GroupID != 101 {
+				t.Fatalf("group id = %d, want 101", req.GroupID)
+			}
+			w.Write([]byte(`{"data":{"api_key":{"id":501}}}`))
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	client, _ := NewClient(srv.URL, WithBearerToken("admin-token"))
+	ref, err := client.EnsureSubscriptionAccess(context.Background(), EnsureSubscriptionAccessRequest{
+		UserSelector: "1",
+		GroupID:      "101",
+		ProbeAPIKey:  "caller-probe-key",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ref.UserID != "1" {
+		t.Fatalf("user id = %q, want 1", ref.UserID)
+	}
+	if ref.APIKey != "caller-probe-key" {
+		t.Fatalf("api key = %q, want caller-probe-key", ref.APIKey)
+	}
+}
+
 func TestCheckGatewayAccessWithMock(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("Authorization"); got != "Bearer gk" {

internal/host/sub2api/subscription_access.go

@@ -52,6 +52,9 @@ func (c *Client) EnsureSubscriptionAccess(ctx context.Context, req EnsureSubscri
 	if err != nil {
 		return SubscriptionAccessRef{}, fmt.Errorf("parse group id %q: %w", groupID, err)
 	}
+	if probeAPIKey := strings.TrimSpace(req.ProbeAPIKey); probeAPIKey != "" {
+		return c.ensureRealSubscriptionAccess(ctx, selector, groupInt, probeAPIKey)
+	}
 
 	identity := buildManagedSubscriptionIdentity(selector, groupID)
 	user, err := c.findManagedSubscriptionUser(ctx, identity.Email)
@@ -82,7 +85,7 @@ func (c *Client) EnsureSubscriptionAccess(ctx context.Context, req EnsureSubscri
 	if err != nil {
 		return SubscriptionAccessRef{}, err
 	}
-	if err := c.bindManagedSubscriptionAPIKey(ctx, keyRecord.ID, groupInt); err != nil {
+	if err := c.bindAPIKeyGroup(ctx, keyRecord.ID, groupInt); err != nil {
 		return SubscriptionAccessRef{}, err
 	}
 	return SubscriptionAccessRef{UserID: strconv.FormatInt(user.ID, 10), APIKey: identity.CustomKey}, nil
@@ -297,11 +300,55 @@ func (c *Client) findManagedSubscriptionAPIKey(ctx context.Context, userID int64
 	return nil, fmt.Errorf("managed api key %q not found for user %d", identity.KeyName, userID)
 }
 
-func (c *Client) bindManagedSubscriptionAPIKey(ctx context.Context, keyID, groupID int64) error {
+func (c *Client) ensureRealSubscriptionAccess(ctx context.Context, selector string, groupID int64, probeAPIKey string) (SubscriptionAccessRef, error) {
+	userID, err := strconv.ParseInt(strings.TrimSpace(selector), 10, 64)
+	if err != nil {
+		return SubscriptionAccessRef{}, fmt.Errorf("parse real subscription user id %q: %w", selector, err)
+	}
+	keyRecord, err := c.findUserAPIKeyByRawKey(ctx, userID, probeAPIKey)
+	if err != nil {
+		return SubscriptionAccessRef{}, err
+	}
+	if err := c.bindAPIKeyGroup(ctx, keyRecord.ID, groupID); err != nil {
+		return SubscriptionAccessRef{}, err
+	}
+	return SubscriptionAccessRef{
+		UserID: strconv.FormatInt(userID, 10),
+		APIKey: probeAPIKey,
+	}, nil
+}
+
+func (c *Client) findUserAPIKeyByRawKey(ctx context.Context, userID int64, rawKey string) (*adminAPIKeyRecord, error) {
+	statusCode, _, body, err := c.perform(ctx, http.MethodGet, fmt.Sprintf("/api/v1/admin/users/%d/api-keys?page=1&page_size=1000&sort_by=created_at&sort_order=desc", userID), nil)
+	if err != nil {
+		return nil, fmt.Errorf("list user api keys: %w", err)
+	}
+	if statusCode < http.StatusOK || statusCode >= http.StatusMultipleChoices {
+		return nil, newHTTPError(http.MethodGet, fmt.Sprintf("/api/v1/admin/users/%d/api-keys", userID), statusCode, body)
+	}
+	var envelope struct {
+		Data struct {
+			Items []adminAPIKeyRecord `json:"items"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		return nil, fmt.Errorf("decode user api keys response: %w", err)
+	}
+	trimmedRawKey := strings.TrimSpace(rawKey)
+	for _, item := range envelope.Data.Items {
+		if strings.TrimSpace(item.Key) == trimmedRawKey {
+			key := item
+			return &key, nil
+		}
+	}
+	return nil, fmt.Errorf("probe api key not found for user %d", userID)
+}
+
+func (c *Client) bindAPIKeyGroup(ctx context.Context, keyID, groupID int64) error {
 	payload := map[string]any{"group_id": groupID}
 	statusCode, _, body, err := c.perform(ctx, http.MethodPut, fmt.Sprintf("/api/v1/admin/api-keys/%d", keyID), payload)
 	if err != nil {
-		return fmt.Errorf("bind managed api key group: %w", err)
+		return fmt.Errorf("bind api key group: %w", err)
 	}
 	if statusCode < http.StatusOK || statusCode >= http.StatusMultipleChoices {
 		return newHTTPError(http.MethodPut, fmt.Sprintf("/api/v1/admin/api-keys/%d", keyID), statusCode, body)