[STAGING] FAC-132 feat: role-aware analysis pipeline triggering and output surfacing (#336) (#337)

Backend half of the FAC-132 integration slice — wires role + scope guards
onto the analysis pipeline endpoints and exposes the list/discovery surface
the frontend needs.

- AnalysisController: @UseJwtGuard(DEAN, CHAIRPERSON, CAMPUS_HEAD,
  SUPER_ADMIN) at the class level with method-level widening to include
  FACULTY for GET reads; new GET /analysis/pipelines list endpoint;
  ParseUUIDPipe on :id params.
- PipelineOrchestratorService: scope-authorization helpers
  (assertCanCreatePipeline, fillAndAssertListScope,
  assertCanAccessPipeline) gate Create/Confirm/Cancel/GetPipelineStatus/
  GetRecommendations; scoped roles (DEAN/CHAIRPERSON/CAMPUS_HEAD) tried
  before FACULTY/STUDENT so multi-role Moodle users (DEAN+FACULTY) aren't
  falsely rejected; auto-fills the scope axis when the caller has exactly
  one assigned scope, else 400.
- TD-8: partial unique index uq_analysis_pipeline_active_scope enforces
  one active pipeline per (semester, scope) tuple at the DB with a
  text-literal 'NONE' sentinel for nullable FKs. CreatePipeline wraps
  flush in a try/catch for UniqueConstraintViolationException and re-
  fetches the winner (idempotent race recovery). existingFilter now
  binds every non-provided scope field to null, matching the index.
- TD-9: pipeline-status response 'scope' replaced with paired IDs + display
  values so the frontend can use IDs for cache keys and display values
  for UI. Create/Confirm/Cancel now also return PipelineSummary shape.
- ScopeResolverService: add public ResolveCampusIds(semesterId) helper
  scoped to campuses hosting the given semester.
- DI: AnalysisModule registers User (for RolesGuard.UserRepository) and
  imports DataLoaderModule (for CurrentUserInterceptor.UserLoader).
- Tests: 62/62 passing — scope authorization matrix across all roles,
  404-precedes-403 (AC-17), unique-index race handling, DEAN+FACULTY
  multi-role precedence, list-endpoint delegation.
- Docs: Access Control section in analysis-pipeline.md and pipeline-
  scope addendum in scope-resolution.md.

Author: y4nder

_bmad-output/implementation-artifacts/tech-spec-fac-132-analysis-pipeline-interaction.md

@@ -152,6 +152,10 @@ When a user holds multiple roles, the highest-priority role wins:
 2. `DEAN` — department-level scope
 3. `CHAIRPERSON` — program-level scope (narrower)
 
+### Pipeline-scope authorization
+
+Analysis-pipeline authorization (create/confirm/cancel/read) reuses `ResolveDepartmentIds`, `ResolveProgramIds`, and `ResolveCampusIds`. Pipeline-specific rules — required axis per role, list default-fill, FACULTY auto-override, 404-before-403 ordering, and the active-scope unique index — live in [analysis-pipeline.md §Access Control](../workflows/analysis-pipeline.md#access-control). `PipelineOrchestratorService` calls these resolvers before any DB write or flush so a foreign caller cannot cause side effects.
+
 ## Source Files
 
 | File                                                          | Purpose                                                      |

docs/architecture/scope-resolution.md

@@ -154,3 +154,93 @@ Returns a structured response with:
 - Sentiment gate statistics
 - Warnings and error messages
 - Timestamps (created, confirmed, completed)
+
+The `scope` object returns **both IDs and display values** side-by-side (e.g., `{ semesterId, semesterCode, departmentId, departmentCode, facultyId, facultyName, ... }`). IDs are used by the frontend for cache keys and lookups; display values are used for rendering. See FAC-132 TD-9 for the contract.
+
+## Discovery
+
+**Endpoint:** `GET /analysis/pipelines`
+
+Returns the 10 most recent pipelines matching the query, ordered by `createdAt DESC`. Query parameters:
+
+| Parameter                | Required | Description                         |
+| ------------------------ | -------- | ----------------------------------- |
+| `semesterId`             | Yes      | Target semester                     |
+| `facultyId`              | No       | Filter to a specific faculty member |
+| `departmentId`           | No       | Filter to a department              |
+| `programId`              | No       | Filter to a program                 |
+| `campusId`               | No       | Filter to a campus                  |
+| `courseId`               | No       | Filter to a course                  |
+| `questionnaireVersionId` | No       | Filter to a specific version        |
+
+Scope-filling behavior per role is documented in [Access Control](#access-control).
+
+## Access Control
+
+Authorization for every `/analysis/*` endpoint is enforced at two layers:
+
+1. **Role guard (`@UseJwtGuard` + `RolesGuard`)** — class-level allowlist plus per-method widening. Roles outside the allowlist get `403 Forbidden` before the service runs.
+2. **Service-layer scope check** — `PipelineOrchestratorService` validates the caller's institutional scope against the pipeline's scope fields via `ScopeResolverService`. Belt-and-braces against guard misconfiguration.
+
+### Role allowlist per endpoint
+
+| Endpoint                                       | Allowed roles                                        |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `POST /analysis/pipelines`                     | SUPER_ADMIN, DEAN, CHAIRPERSON, CAMPUS_HEAD          |
+| `POST /analysis/pipelines/:id/confirm`         | SUPER_ADMIN, DEAN, CHAIRPERSON, CAMPUS_HEAD          |
+| `POST /analysis/pipelines/:id/cancel`          | SUPER_ADMIN, DEAN, CHAIRPERSON, CAMPUS_HEAD          |
+| `GET  /analysis/pipelines`                     | SUPER_ADMIN, DEAN, CHAIRPERSON, CAMPUS_HEAD, FACULTY |
+| `GET  /analysis/pipelines/:id/status`          | SUPER_ADMIN, DEAN, CHAIRPERSON, CAMPUS_HEAD, FACULTY |
+| `GET  /analysis/pipelines/:id/recommendations` | SUPER_ADMIN, DEAN, CHAIRPERSON, CAMPUS_HEAD, FACULTY |
+
+STUDENT and ADMIN are never in the allowlist. STUDENT is end-user; ADMIN is reserved for admin-console operations (not analytics).
+
+### Create / Confirm / Cancel / Read-by-id scope matrix
+
+These operations require an **explicit scope filter** on the axis appropriate to the caller's role. Absence of the filter returns `400 Bad Request` with `"scope filter required for your role"`. A filter outside the caller's resolved set returns `403 Forbidden` with `"scope not in your assigned access"`.
+
+| Role        | Required on create           | Validation against                          |
+| ----------- | ---------------------------- | ------------------------------------------- |
+| SUPER_ADMIN | None (`semesterId` only OK)  | — (unrestricted)                            |
+| DEAN        | `departmentId`               | `ResolveDepartmentIds(semesterId)`          |
+| CHAIRPERSON | `programId`                  | `ResolveProgramIds(semesterId)`             |
+| CAMPUS_HEAD | `campusId` OR `departmentId` | `ResolveCampusIds` / `ResolveDepartmentIds` |
+| FACULTY     | _(blocked at guard — 403)_   | —                                           |
+| STUDENT     | _(blocked at guard — 403)_   | —                                           |
+
+**Read-by-id additional rules:**
+
+- FACULTY may read `GET /:id/status` or `GET /:id/recommendations` only when `pipeline.faculty.id === user.id`. Department-scoped pipelines (null `faculty` FK) are 403 for FACULTY.
+- A pipeline with a **null** scope field on the caller's axis (e.g., `pipeline.department === null` for a DEAN) is 403 for all scoped roles — null means "no filter", i.e., broader-than-role access, reserved for SUPER_ADMIN.
+- Pipelines not found return `404 Not Found` **before** the scope check, so 404 takes precedence over 403. This exposes a minor existence-oracle for scoped roles who know a foreign UUID. Bounded by UUID opacity and the fact that FACULTY never learns foreign UUIDs (see list auto-override below).
+
+### List scope-filling
+
+`GET /analysis/pipelines` fills in the caller's resolved scope when the corresponding query parameter is omitted — this differs from create, which 400s on absence. Rationale: the dean dashboard can call `listPipelines({ semesterId })` without needing to enumerate department UUIDs on the client.
+
+| Role        | Behavior                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| SUPER_ADMIN | Query unchanged.                                                                                                                            |
+| DEAN        | If `departmentId` omitted, service fills an IN-filter with `ResolveDepartmentIds(semesterId)`. If provided, verify ∈ resolved set else 403. |
+| CHAIRPERSON | Same with `programId` and `ResolveProgramIds(semesterId)`.                                                                                  |
+| CAMPUS_HEAD | Same with `campusId` and `ResolveCampusIds(semesterId)`.                                                                                    |
+| FACULTY     | `facultyId` is silently overridden to the caller's own user id. Any foreign `facultyId` in the query is dropped.                            |
+| STUDENT     | 403.                                                                                                                                        |
+
+The FACULTY auto-override prevents enumeration of other faculty's pipelines and ensures FACULTY never learns foreign pipeline UUIDs.
+
+### Population requirement for ownership checks
+
+`ConfirmPipeline`, `CancelPipeline`, `GetPipelineStatus`, and `GetRecommendations` populate `['faculty', 'department', 'program', 'campus']` on the pipeline before running `assertCanAccessPipeline`. Reading `pipeline.faculty?.id` through an unpopulated reference proxy is fragile — explicit populate is load-bearing.
+
+### Scope check ordering for side-effecting endpoints
+
+For `ConfirmPipeline` and `CancelPipeline`, the scope check runs **before** any `fork.flush()`, status mutation, or queue enqueue. A foreign caller must never cause side effects — even when an unrelated check (e.g., worker URL misconfiguration) would otherwise fail the pipeline.
+
+### Unique-scope invariant
+
+A partial unique index (`uq_analysis_pipeline_active_scope`) enforces one active pipeline per `(semester, scope tuple)` at the DB level. Concurrent creates with identical scope produce `UniqueConstraintViolationException`; the orchestrator catches it and re-fetches the winner so both callers see the same pipeline id (idempotent).
+
+### Scope drift mid-pipeline
+
+A DEAN who triggers a pipeline and is then reassigned to a different department mid-execution loses read access to their own pipeline. This mirrors `/analytics/*` behavior and is intentional — the scope check evaluates against current assignments, not historical ones.

docs/workflows/analysis-pipeline.md

@@ -77,7 +77,7 @@
           "autoincrement": false,
           "primary": false,
           "nullable": false,
-          "unique": false,
+          "unique": true,
           "length": 255,
           "precision": null,
           "scale": null,
@@ -408,6 +408,23 @@
           "keyName": "analysis_pipeline_semester_id_status_index",
           "unique": false,
           "primary": false
+        },
+        {
+          "columnNames": [
+            "semester_id",
+            "COALESCE(faculty_id, NONE::character varying)",
+            "COALESCE(department_id, NONE::character varying)",
+            "COALESCE(program_id, NONE::character varying)",
+            "COALESCE(campus_id, NONE::character varying)",
+            "COALESCE(course_id, NONE::character varying)",
+            "COALESCE(questionnaire_version_id, NONE::character varying)"
+          ],
+          "composite": true,
+          "constraint": false,
+          "keyName": "uq_analysis_pipeline_active_scope",
+          "unique": true,
+          "primary": false,
+          "expression": "CREATE UNIQUE INDEX uq_analysis_pipeline_active_scope ON public.analysis_pipeline USING btree (semester_id, COALESCE(faculty_id, 'NONE'::character varying), COALESCE(department_id, 'NONE'::character varying), COALESCE(program_id, 'NONE'::character varying), COALESCE(campus_id, 'NONE'::character varying), COALESCE(course_id, 'NONE'::character varying), COALESCE(questionnaire_version_id, 'NONE'::character varying)) WHERE ((status <> ALL (ARRAY['COMPLETED'::text, 'FAILED'::text, 'CANCELLED'::text])) AND (deleted_at IS NULL))"
         }
       ],
       "checks": [],

src/migrations/.snapshot-faculytics_db.json

@@ -0,0 +1,42 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260414155236 extends Migration {
+  // FAC-132: partial unique index enforcing one canonical pipeline per
+  // (semester, scope) tuple while any non-terminal pipeline exists.
+  //
+  // Why a partial index (not @Unique decorator or plain unique constraint):
+  // - `analysis_pipeline` scope FKs (faculty_id, department_id, ...) are
+  //   nullable. Postgres treats NULL as distinct in unique constraints, so a
+  //   plain constraint would permit unlimited duplicate (semester, NULL,
+  //   NULL, ...) active pipelines. COALESCE-to-sentinel fixes this.
+  // - Soft-deleted rows and terminal-state pipelines (COMPLETED/FAILED/
+  //   CANCELLED) must NOT participate — a new active pipeline for a scope
+  //   should always be insertable once the previous one settles.
+  //
+  // FK columns are varchar(255) (see Migration20260313170918) — the text
+  // literal 'NONE' is the sentinel. Do NOT cast to uuid; the columns are
+  // text-typed.
+
+  private readonly INDEX_NAME = 'uq_analysis_pipeline_active_scope';
+
+  override async up(): Promise<void> {
+    this.addSql(`
+      CREATE UNIQUE INDEX "${this.INDEX_NAME}"
+        ON "analysis_pipeline" (
+          "semester_id",
+          COALESCE("faculty_id", 'NONE'),
+          COALESCE("department_id", 'NONE'),
+          COALESCE("program_id", 'NONE'),
+          COALESCE("campus_id", 'NONE'),
+          COALESCE("course_id", 'NONE'),
+          COALESCE("questionnaire_version_id", 'NONE')
+        )
+        WHERE "status" NOT IN ('COMPLETED', 'FAILED', 'CANCELLED')
+          AND "deleted_at" IS NULL;
+    `);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`DROP INDEX IF EXISTS "${this.INDEX_NAME}";`);
+  }
+}

src/migrations/Migration20260414155236_fac-132-pipeline-scope-unique-index.ts

@@ -1,18 +1,21 @@
 import { Test, TestingModule } from '@nestjs/testing';
+import { AuthGuard } from '@nestjs/passport';
 import { AnalysisController } from './analysis.controller';
 import { PipelineOrchestratorService } from './services/pipeline-orchestrator.service';
 import { PipelineStatus } from './enums';
 import {
   auditTestProviders,
   overrideAuditInterceptors,
 } from '../audit/testing/audit-test.helpers';
+import { RolesGuard } from 'src/security/guards/roles.guard';
+import { CurrentUserInterceptor } from '../common/interceptors/current-user.interceptor';
 
 const makeMockPipeline = (
   overrides: Partial<Record<string, unknown>> = {},
 ) => ({
   id: 'p1',
   status: PipelineStatus.AWAITING_CONFIRMATION,
-  semester: { id: 's1' },
+  semester: { id: 's1', code: 'S2026' },
   faculty: undefined,
   questionnaireVersion: undefined,
   department: undefined,
@@ -27,6 +30,7 @@ const makeMockPipeline = (
   warnings: [],
   errorMessage: undefined,
   createdAt: new Date('2026-01-01T00:00:00Z'),
+  updatedAt: new Date('2026-01-01T00:00:00Z'),
   confirmedAt: undefined,
   completedAt: undefined,
   ...overrides,
@@ -36,6 +40,7 @@ describe('AnalysisController', () => {
   let controller: AnalysisController;
   let mockOrchestrator: {
     CreatePipeline: jest.Mock;
+    ListPipelines: jest.Mock;
     ConfirmPipeline: jest.Mock;
     CancelPipeline: jest.Mock;
     GetPipelineStatus: jest.Mock;
@@ -45,6 +50,7 @@ describe('AnalysisController', () => {
   beforeEach(async () => {
     mockOrchestrator = {
       CreatePipeline: jest.fn(),
+      ListPipelines: jest.fn(),
       ConfirmPipeline: jest.fn(),
       CancelPipeline: jest.fn(),
       GetPipelineStatus: jest.fn(),
@@ -60,7 +66,16 @@ describe('AnalysisController', () => {
         },
         ...auditTestProviders(),
       ],
-    });
+    })
+      .overrideGuard(AuthGuard('jwt'))
+      .useValue({ canActivate: () => true })
+      .overrideGuard(RolesGuard)
+      .useValue({ canActivate: () => true })
+      .overrideInterceptor(CurrentUserInterceptor)
+      .useValue({
+        intercept: (_ctx: unknown, next: { handle: () => unknown }) =>
+          next.handle(),
+      });
     const module: TestingModule =
       await overrideAuditInterceptors(builder).compile();
 
@@ -81,17 +96,20 @@ describe('AnalysisController', () => {
         user: { userId: 'u1', moodleUserId: 1 },
       } as unknown as Parameters<typeof controller.CreatePipeline>[1];
 
-      const result = await controller.CreatePipeline(body, req);
+      const result = (await controller.CreatePipeline(
+        body,
+        req,
+      )) as unknown as {
+        id: string;
+        status: string;
+        scope: { semesterId: string };
+        coverage: { responseRate: number };
+      };
 
-      expect(result).toEqual(
-        expect.objectContaining({
-          id: 'p1',
-          status: PipelineStatus.AWAITING_CONFIRMATION,
-          semesterId: 's1',
-          triggeredById: 'u1',
-          responseRate: 0.5,
-        }),
-      );
+      expect(result.id).toBe('p1');
+      expect(result.status).toBe(PipelineStatus.AWAITING_CONFIRMATION);
+      expect(result.scope.semesterId).toBe('s1');
+      expect(result.coverage.responseRate).toBe(0.5);
       expect(mockOrchestrator.CreatePipeline).toHaveBeenCalledWith(body, 'u1');
     });
   });
@@ -103,15 +121,15 @@ describe('AnalysisController', () => {
       });
       mockOrchestrator.ConfirmPipeline.mockResolvedValue(mockPipeline);
 
-      const result = await controller.ConfirmPipeline('p1');
+      const result = (await controller.ConfirmPipeline('p1')) as unknown as {
+        id: string;
+        status: string;
+        scope: { semesterId: string };
+      };
 
-      expect(result).toEqual(
-        expect.objectContaining({
-          id: 'p1',
-          status: PipelineStatus.EMBEDDING_CHECK,
-          semesterId: 's1',
-        }),
-      );
+      expect(result.id).toBe('p1');
+      expect(result.status).toBe(PipelineStatus.EMBEDDING_CHECK);
+      expect(result.scope.semesterId).toBe('s1');
       expect(mockOrchestrator.ConfirmPipeline).toHaveBeenCalledWith('p1');
     });
   });
@@ -123,15 +141,15 @@ describe('AnalysisController', () => {
       });
       mockOrchestrator.CancelPipeline.mockResolvedValue(mockPipeline);
 
-      const result = await controller.CancelPipeline('p1');
+      const result = (await controller.CancelPipeline('p1')) as unknown as {
+        id: string;
+        status: string;
+        scope: { semesterId: string };
+      };
 
-      expect(result).toEqual(
-        expect.objectContaining({
-          id: 'p1',
-          status: PipelineStatus.CANCELLED,
-          semesterId: 's1',
-        }),
-      );
+      expect(result.id).toBe('p1');
+      expect(result.status).toBe(PipelineStatus.CANCELLED);
+      expect(result.scope.semesterId).toBe('s1');
       expect(mockOrchestrator.CancelPipeline).toHaveBeenCalledWith('p1');
     });
   });
@@ -141,7 +159,13 @@ describe('AnalysisController', () => {
       const mockStatus = {
         id: 'p1',
         status: PipelineStatus.SENTIMENT_ANALYSIS,
-        scope: { semester: 'S2026' },
+        // TD-9 shape — paired IDs + display values
+        scope: {
+          semesterId: 's1',
+          semesterCode: 'S2026',
+          departmentId: null,
+          departmentCode: null,
+        },
         coverage: { totalEnrolled: 100, submissionCount: 50 },
         stages: {
           embeddings: {
@@ -189,6 +213,31 @@ describe('AnalysisController', () => {
     });
   });
 
+  describe('ListPipelines', () => {
+    it('should delegate to orchestrator.ListPipelines and map to summary DTOs', async () => {
+      const mockPipeline = makeMockPipeline({
+        semester: { id: 's1', code: 'S2026' },
+      });
+      mockOrchestrator.ListPipelines.mockResolvedValue([mockPipeline]);
+
+      const query = { semesterId: 's1' };
+      const result = await controller.ListPipelines(query);
+
+      expect(mockOrchestrator.ListPipelines).toHaveBeenCalledWith(query);
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(1);
+      const first = result[0] as unknown as {
+        id: string;
+        status: string;
+        scope: { semesterId: string; semesterCode: string };
+      };
+      expect(first.id).toBe('p1');
+      expect(first.status).toBe(PipelineStatus.AWAITING_CONFIRMATION);
+      expect(first.scope.semesterId).toBe('s1');
+      expect(first.scope.semesterCode).toBe('S2026');
+    });
+  });
+
   describe('GetRecommendations', () => {
     it('should delegate to orchestrator.GetRecommendations with correct id', async () => {
       const mockResponse = {