stack/docs/scratchpads/FED-M3-07-capabilities.md

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