# FED-M3-07 — Capabilities Verb Scratchpad

## Objective

Implement `GET /api/federation/v1/capabilities` in `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`.

## Scope

- Add read-only capabilities controller under federation server verbs.
- Use `FederationAuthGuard` only; active grant is sufficient and no native RBAC/scope-service eval runs.
- Response shape: `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope.
- Register controller in `FederationModule`.
- Unit-test happy path, defaults, no-context guard seam, and invalid scope handling.

## Constraints / assumptions

- Issue: #462.
- Branch: `feat/federation-m3-verb-capabilities` from `origin/main` (`3eeed04e`).
- Depends on M3-03 auth guard; guard attaches `request.federationContext.scope` after active-grant validation.
- ASSUMPTION: `supported_verbs` is the M3 verb set from `@mosaicstack/types` (`list`, `get`, `capabilities`).
- ASSUMPTION: `filters`/`rate_limit` are intentionally omitted for FED-M3-07 because the card’s response shape lists only the four required fields.
- Budget: no explicit hard cap from orchestrator; working cap ~4K-8K tokens for card implementation + tests + PR cycle.

## Plan

1. Write controller unit tests first.
2. Implement controller and module registration.
3. Run scoped tests + typecheck/lint/format.
4. Run Codex code/security review and remediate.
5. Commit, queue guard, push, PR via wrapper.

## Progress

- 2026-06-24: Intake complete; fresh worktree created from origin/main.
- 2026-06-24: Added `CapabilitiesController`, registered it in `FederationModule`, and added 5 unit tests.
- 2026-06-24: Code/security reviews passed with no findings.

## Tests run

- `pnpm --filter @mosaicstack/gateway test -- capabilities.controller.spec.ts` — PASS (5 tests).
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
- `pnpm format:check` — PASS.
- `pnpm typecheck` — PASS (41/41 turbo tasks).
- `pnpm lint` — PASS (23/23 turbo tasks).
- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit PostgreSQL connection/schema state for the `messages` table. Changed capabilities tests passed; failure is outside FED-M3-07 surface. No `fleet-personas.spec` flake encountered.

## Review evidence

- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.

## Risks / blockers

- Full repo `pnpm test` may hit known `fleet-personas.spec` flake per orchestrator; ignore that specific flake if encountered.
- Previous card saw local DB schema issue in `cross-user-isolation.test.ts`; scoped capabilities tests should be authoritative for this surface.

## Acceptance evidence mapping

| Acceptance criterion                                                       | Evidence                                                                                                                   |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET `/api/federation/v1/capabilities` exists                               | Route metadata test in `capabilities.controller.spec.ts`; scoped test PASS                                                 |
| Uses active-grant auth guard and no RBAC eval                              | Guard metadata test confirms only `FederationAuthGuard`; controller has no service injections/RBAC calls; scoped test PASS |
| Response enumerates resources/excluded/max rows/supported verbs from scope | Happy-path/default scope tests + response schema parse; scoped test PASS                                                   |
| Read-only/no persistence side effects                                      | Controller only parses request `federationContext.scope` and returns a DTO; no DB/service dependency; code review PASS     |