feat(LFXV2-2472): expose committee→project lookup via NATS request-reply

Add lfx.committee-api.get_project request-reply subject so consumers
(e.g. mailing-list-service) can resolve a committee UID to its owning
project UID without routing through the v1-sync-helper.

- pkg/constants/subjects.go: add CommitteeGetProjectSubject constant
- pkg/api/committee.go: new public contract package with typed
  request/response structs (GetCommitteeProjectRequest/Response)
- port/message_handler.go: add HandleCommitteeGetProject to interface
- service/message_handler.go: implement handler — JSON unmarshal,
  UUID validation, GetBase lookup, structured not-found reply envelope
- committee_handler.go / providers.go: wire subject into router and
  NATS queue subscription map
- message_handler_test.go: table-driven tests for success, not-found,
  malformed JSON, and invalid UUID cases
- docs/nats-request-reply.md: document all request-reply subjects
- nats-messaging.md: add get_project to inbound RPC subject inventory
- README.md: reference new docs/nats-request-reply.md

Issue: LFXV2-2472

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Jordan Evans <jevans@linuxfoundation.org>

Author: jordane

.claude/skills/committee-service-dev/references/nats-messaging.md

@@ -18,6 +18,7 @@ Repo-local inventory of NATS subjects, queue groups, KV buckets, Object Stores,
 ```go
 "lfx.committee-api.get_name"                      // get committee name by UID
 "lfx.committee-api.list_members"                  // list committee members
+"lfx.committee-api.get_project"                   // resolve committee UID to owning project UID (pkg/api: GetCommitteeProjectRequest/Response)
 ```
 
 ### Inbound event subjects (consumed from other services)

README.md

@@ -56,6 +56,7 @@ The LFX v2 Committee Service is a RESTful API service that manages committees an
 - [Invite & Application Flows](docs/invite-application-flows.md) — membership modes, invite/application lifecycle, state transitions, and edge cases
 - [Indexer Contract](docs/indexer-contract.md) — authoritative reference for all messages sent to the indexer service
 - [FGA Contract](docs/fga-contract.md) — authoritative reference for all messages sent to the fga-sync service
+- [NATS Request-Reply Subjects](docs/nats-request-reply.md) — synchronous request/reply subjects served by this service for inter-service queries
 - [Committee CLI](cmd/committee-cli/README.md) — operational tool for running data repair and sync tasks against the service
 
 ## Releases

cmd/committee-api/service/committee_handler.go

@@ -29,6 +29,7 @@ func (mhs *MessageHandlerService) HandleMessage(ctx context.Context, msg port.Tr
 	handlers := map[string]func(ctx context.Context, msg port.TransportMessenger) ([]byte, error){
 		constants.CommitteeGetNameSubject:            mhs.handleCommitteeGetName,
 		constants.CommitteeListMembersSubject:        mhs.handleCommitteeListMembers,
+		constants.CommitteeGetProjectSubject:         mhs.handleCommitteeGetProject,
 		constants.MailingListCommitteeChangedSubject: mhs.handleMailingListChanged,
 		constants.CommitteeUpdatedSubject:            mhs.handleCommitteeUpdated,
 		constants.CommitteeMemberCreatedSubject:      mhs.handleCommitteeMemberCreated,
@@ -110,6 +111,10 @@ func (mhs *MessageHandlerService) handleCommitteeLinkCreated(ctx context.Context
 	return mhs.messageHandler.HandleCommitteeLinkCreated(ctx, msg)
 }
 
+func (mhs *MessageHandlerService) handleCommitteeGetProject(ctx context.Context, msg port.TransportMessenger) ([]byte, error) {
+	return mhs.messageHandler.HandleCommitteeGetProject(ctx, msg)
+}
+
 func (mhs *MessageHandlerService) respondWithError(ctx context.Context, msg port.TransportMessenger, errorMsg string) {
 	errResponse := []byte(fmt.Sprintf(`{"error":"%s"}`, errorMsg))
 	if err := msg.Respond(errResponse); err != nil {

cmd/committee-api/service/providers.go

@@ -874,6 +874,7 @@ func QueueSubscriptions(ctx context.Context, committeeReader port.CommitteeReade
 	subjects := map[string]func(context.Context, port.TransportMessenger){
 		constants.CommitteeGetNameSubject:            messageHandlerService.HandleMessage,
 		constants.CommitteeListMembersSubject:        messageHandlerService.HandleMessage,
+		constants.CommitteeGetProjectSubject:         messageHandlerService.HandleMessage,
 		constants.MailingListCommitteeChangedSubject: messageHandlerService.HandleMessage,
 		constants.CommitteeUpdatedSubject:            messageHandlerService.HandleMessage,
 		constants.CommitteeMemberCreatedSubject:      messageHandlerService.HandleMessage,

docs/nats-request-reply.md

@@ -0,0 +1,144 @@
+# NATS Request-Reply Subjects
+
+This document describes the NATS request-reply subjects served by the committee service. These are synchronous, point-to-point subjects (core NATS request/reply with a queue group) used by other services to query committee state. All subjects share the `lfx.committee-api.queue` queue group.
+
+For event subjects emitted by this service (fire-and-forget publishes) see [Indexer Contract](indexer-contract.md) and [FGA Contract](fga-contract.md).
+
+---
+
+## `lfx.committee-api.get_project`
+
+Resolves a v2 committee UID to the UID of the project that owns it.
+
+**Subject constant:** `pkg/constants` — `CommitteeGetProjectSubject`.  
+**Request/response types:** `pkg/api` — `GetCommitteeProjectRequest`, `GetCommitteeProjectResponse`.  
+Consumers should import both packages to use the typed structs and constant rather than hard-coding strings.
+
+### Request
+
+```json
+{ "committee_uid": "<v2 UUID>" }
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `committee_uid` | string (UUID v4) | yes | The v2 UID of the committee to look up. |
+
+### Response (success)
+
+```json
+{ "project_uid": "<v2 UUID>" }
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `project_uid` | string (UUID v4) | The v2 UID of the owning project. |
+
+### Response (not found)
+
+```json
+{ "error": "not found" }
+```
+
+Returned when no committee exists for the supplied UID. The NATS reply is still sent (no timeout); only the `error` field is set.
+
+### Response (request error)
+
+```json
+{ "error": "<message>" }
+```
+
+Returned for malformed JSON or an invalid (non-UUID) `committee_uid`. The `error` field describes the failure.
+
+### Example
+
+```go
+import committeeapi "github.com/linuxfoundation/lfx-v2-committee-service/pkg/api"
+
+reqBytes, _ := json.Marshal(committeeapi.GetCommitteeProjectRequest{CommitteeUID: committeeUID})
+msg, err := nc.Request(committeeapi.GetCommitteeProjectSubject, reqBytes, 5*time.Second)
+if err != nil {
+    // NATS timeout or connection error
+}
+
+var resp committeeapi.GetCommitteeProjectResponse
+if err := json.Unmarshal(msg.Data, &resp); err != nil {
+    // malformed reply
+}
+if resp.Error != "" {
+    // "not found" or request validation error
+}
+// resp.ProjectUID is the owning project's v2 UID
+```
+
+---
+
+## `lfx.committee-api.get_name`
+
+Returns the display name of a committee.
+
+> **Wire format:** plain-text, not JSON. Request payload is the raw committee UID string; success reply is the raw name string; failure reply is `{"error":"<message>"}`.
+
+**Defined in:** `pkg/constants` — `CommitteeGetNameSubject`.
+
+### Request
+
+```
+<committee_uid>
+```
+
+Plain UTF-8 UUID string (no JSON wrapper).
+
+### Response (success)
+
+```
+<committee name>
+```
+
+Plain UTF-8 string.
+
+### Response (failure)
+
+```json
+{ "error": "<message>" }
+```
+
+---
+
+## `lfx.committee-api.list_members`
+
+Returns all members of a committee as a JSON array.
+
+> **Wire format:** plain-text UID in, JSON array out. Request payload is the raw committee UID string.
+
+**Defined in:** `pkg/constants` — `CommitteeListMembersSubject`.
+
+### Request
+
+```
+<committee_uid>
+```
+
+Plain UTF-8 UUID string (no JSON wrapper).
+
+### Response (success)
+
+JSON array of committee member objects:
+
+```json
+[
+  {
+    "uid": "...",
+    "committee_uid": "...",
+    "username": "...",
+    "role": "...",
+    ...
+  }
+]
+```
+
+### Response (failure)
+
+```json
+{ "error": "<message>" }
+```

internal/domain/port/message_handler.go

@@ -10,6 +10,11 @@ import "context"
 type CommitteeAttributeHandler interface {
 	// HandleCommitteeGetAttribute handles committee get attribute messages
 	HandleCommitteeGetAttribute(ctx context.Context, msg TransportMessenger, attribute string) ([]byte, error)
+	// HandleCommitteeGetProject resolves a committee UID to its owning project UID.
+	// Request payload: JSON-encoded GetCommitteeProjectRequest (pkg/api).
+	// Success reply: JSON-encoded GetCommitteeProjectResponse with ProjectUID set.
+	// Not-found reply: JSON-encoded GetCommitteeProjectResponse with Error set to "not found".
+	HandleCommitteeGetProject(ctx context.Context, msg TransportMessenger) ([]byte, error)
 }
 
 // CommitteeMemberHandler handles member-related messages: responding to external

internal/service/message_handler.go

@@ -17,6 +17,7 @@ import (
 	"github.com/linuxfoundation/lfx-v2-committee-service/internal/domain/model"
 	"github.com/linuxfoundation/lfx-v2-committee-service/internal/domain/port"
 	emailsvc "github.com/linuxfoundation/lfx-v2-committee-service/internal/service/email"
+	committeeapi "github.com/linuxfoundation/lfx-v2-committee-service/pkg/api"
 	"github.com/linuxfoundation/lfx-v2-committee-service/pkg/constants"
 	"github.com/linuxfoundation/lfx-v2-committee-service/pkg/errors"
 	"github.com/linuxfoundation/lfx-v2-committee-service/pkg/fields"
@@ -209,6 +210,48 @@ func (m *messageHandlerOrchestrator) HandleCommitteeGetAttribute(ctx context.Con
 	return []byte(strValue), nil
 }
 
+// HandleCommitteeGetProject resolves a committee UID to its owning project UID.
+// The request payload must be a JSON-encoded GetCommitteeProjectRequest.
+// On success it returns a JSON-encoded GetCommitteeProjectResponse with ProjectUID set.
+// When the committee does not exist it returns a JSON-encoded GetCommitteeProjectResponse
+// with Error set to "not found" (successful reply, not a Go error) so the NATS router
+// sends the structured payload back to the caller rather than the generic error envelope.
+func (m *messageHandlerOrchestrator) HandleCommitteeGetProject(ctx context.Context, msg port.TransportMessenger) ([]byte, error) {
+	var req committeeapi.GetCommitteeProjectRequest
+	if err := json.Unmarshal(msg.Data(), &req); err != nil {
+		slog.ErrorContext(ctx, "failed to unmarshal get_project request", "error", err)
+		return nil, errors.NewValidation("invalid get_project request payload", err)
+	}
+
+	slog.DebugContext(ctx, "committee get project request", "committee_uid", req.CommitteeUID)
+
+	if _, err := uuid.Parse(req.CommitteeUID); err != nil {
+		slog.ErrorContext(ctx, "invalid committee UID in get_project request", "error", err, "committee_uid", req.CommitteeUID)
+		return nil, errors.NewValidation("invalid committee UID", err)
+	}
+
+	committee, _, err := m.committeeReader.GetBase(ctx, req.CommitteeUID)
+	if err != nil {
+		var nf errors.NotFound
+		if stderrors.As(err, &nf) {
+			slog.DebugContext(ctx, "committee not found for get_project request", "committee_uid", req.CommitteeUID)
+			return json.Marshal(committeeapi.GetCommitteeProjectResponse{Error: "not found"})
+		}
+		slog.ErrorContext(ctx, "failed to get committee base for get_project request",
+			"error", err,
+			"committee_uid", req.CommitteeUID,
+		)
+		return nil, err
+	}
+
+	slog.DebugContext(ctx, "committee get project response",
+		"committee_uid", req.CommitteeUID,
+		"project_uid", committee.ProjectUID,
+	)
+
+	return json.Marshal(committeeapi.GetCommitteeProjectResponse{ProjectUID: committee.ProjectUID})
+}
+
 // HandleCommitteeListMembers handles the retrieval of all members for a committee
 func (m *messageHandlerOrchestrator) HandleCommitteeListMembers(ctx context.Context, msg port.TransportMessenger) ([]byte, error) {
 

internal/service/message_handler_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/linuxfoundation/lfx-v2-committee-service/internal/domain/model"
 	"github.com/linuxfoundation/lfx-v2-committee-service/internal/domain/port"
 	"github.com/linuxfoundation/lfx-v2-committee-service/internal/infrastructure/mock"
+	committeeapi "github.com/linuxfoundation/lfx-v2-committee-service/pkg/api"
 	"github.com/linuxfoundation/lfx-v2-committee-service/pkg/constants"
 	errs "github.com/linuxfoundation/lfx-v2-committee-service/pkg/errors"
 	emailapi "github.com/linuxfoundation/lfx-v2-email-service/pkg/api"
@@ -2515,3 +2516,114 @@ func TestHandleInviteAccepted(t *testing.T) {
 		})
 	}
 }
+
+func TestMessageHandlerOrchestratorHandleCommitteeGetProject(t *testing.T) {
+	ctx := context.Background()
+
+	testCommitteeUID := uuid.New().String()
+	testProjectUID := "test-project-uid"
+	testCommittee := &model.Committee{
+		CommitteeBase: model.CommitteeBase{
+			UID:        testCommitteeUID,
+			ProjectUID: testProjectUID,
+			Name:       "Test Committee",
+		},
+	}
+
+	tests := []struct {
+		name             string
+		setupMock        func(mockRepo *mock.MockRepository)
+		messageData      []byte
+		expectedError    bool
+		errorType        interface{}
+		validateResponse func(*testing.T, []byte)
+	}{
+		{
+			name: "success - returns project UID",
+			setupMock: func(mockRepo *mock.MockRepository) {
+				mockRepo.ClearAll()
+				mockRepo.AddCommittee(testCommittee)
+			},
+			messageData:   mustMarshalGetProjectJSON(t, committeeapi.GetCommitteeProjectRequest{CommitteeUID: testCommitteeUID}),
+			expectedError: false,
+			validateResponse: func(t *testing.T, response []byte) {
+				var resp committeeapi.GetCommitteeProjectResponse
+				require.NoError(t, json.Unmarshal(response, &resp))
+				assert.Equal(t, testProjectUID, resp.ProjectUID)
+				assert.Empty(t, resp.Error)
+			},
+		},
+		{
+			name: "not found - returns error envelope",
+			setupMock: func(mockRepo *mock.MockRepository) {
+				mockRepo.ClearAll()
+			},
+			messageData:   mustMarshalGetProjectJSON(t, committeeapi.GetCommitteeProjectRequest{CommitteeUID: uuid.New().String()}),
+			expectedError: false,
+			validateResponse: func(t *testing.T, response []byte) {
+				var resp committeeapi.GetCommitteeProjectResponse
+				require.NoError(t, json.Unmarshal(response, &resp))
+				assert.Equal(t, "not found", resp.Error)
+				assert.Empty(t, resp.ProjectUID)
+			},
+		},
+		{
+			name:          "malformed JSON payload - returns validation error",
+			setupMock:     func(mockRepo *mock.MockRepository) {},
+			messageData:   []byte(`not-json`),
+			expectedError: true,
+			errorType:     errs.Validation{},
+			validateResponse: func(t *testing.T, response []byte) {
+				assert.Nil(t, response)
+			},
+		},
+		{
+			name:          "invalid UUID in payload - returns validation error",
+			setupMock:     func(mockRepo *mock.MockRepository) {},
+			messageData:   mustMarshalGetProjectJSON(t, committeeapi.GetCommitteeProjectRequest{CommitteeUID: "not-a-uuid"}),
+			expectedError: true,
+			errorType:     errs.Validation{},
+			validateResponse: func(t *testing.T, response []byte) {
+				assert.Nil(t, response)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			mockRepo := mock.NewMockRepository()
+			tt.setupMock(mockRepo)
+
+			handler := NewMessageHandlerOrchestrator(
+				WithCommitteeReaderForMessageHandler(
+					NewCommitteeReaderOrchestrator(
+						WithCommitteeReader(mockRepo),
+					),
+				),
+			)
+
+			mockMsg := newMockTransportMessenger(constants.CommitteeGetProjectSubject, tt.messageData)
+
+			response, err := handler.HandleCommitteeGetProject(ctx, mockMsg)
+
+			if tt.expectedError {
+				require.Error(t, err)
+				if tt.errorType != nil {
+					assert.IsType(t, tt.errorType, err)
+				}
+			} else {
+				require.NoError(t, err)
+			}
+
+			tt.validateResponse(t, response)
+		})
+	}
+}
+
+// mustMarshalGetProjectJSON marshals v to JSON and fails the test on error.
+func mustMarshalGetProjectJSON(t *testing.T, v interface{}) []byte {
+	t.Helper()
+	b, err := json.Marshal(v)
+	require.NoError(t, err)
+	return b
+}