feat(#462 ): add federation list verb

2026-06-24 20:46:19 -05:00
11 changed files with 6 additions and 1791 deletions
--- a/.woodpecker/publish.yml
+++ b/.woodpecker/publish.yml
@@ -1,5 +1,5 @@
 # Build, publish npm packages, and push Docker images
-# Runs on main for stable publishes and on next for integration-line prereleases/images
+# Runs only on main branch push/tag
 variables:
  # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
@@ -23,21 +23,9 @@ variables:
          - 'docs/**'
          - '**/*.md'
          - '.woodpecker/**'
    - event: [push, manual]
      branch: next
  - &main_image_build_when
    - event: tag
    - event: [push, manual]
      branch: main
      path:
        exclude:
          - 'packages/mosaic/**'
          - 'docs/**'
          - '**/*.md'
          - '.woodpecker/**'
 when:
-  - branch: [main, next]
+  - branch: [main]
    event: [push, manual, tag]
 steps:
@@ -115,84 +103,6 @@ steps:
    depends_on:
      - build
  publish-next-npm:
    image: *node_image
    # Durable @next integration-line publish. Runs only on next; never writes
    # the latest dist-tag and never commits the computed prerelease versions.
    when:
      - event: [push, manual]
        branch: next
    environment:
      NPM_TOKEN:
        from_secret: gitea_token
      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
      CI_PIPELINE_NUMBER: ${CI_PIPELINE_NUMBER}
    commands:
      - *enable_pnpm
      - |
        if [ "$CI_COMMIT_BRANCH" != "next" ]; then
          echo "[publish-next] FATAL: publish-next-npm may only run on next (got '$CI_COMMIT_BRANCH')" >&2
          exit 1
        fi
        if [ -z "$CI_PIPELINE_NUMBER" ]; then
          echo "[publish-next] FATAL: CI_PIPELINE_NUMBER is required for prerelease versioning" >&2
          exit 1
        fi
        echo "//git.mosaicstack.dev/api/packages/mosaicstack/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
        echo "@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/" >> ~/.npmrc
        DIST_TAGS_JSON="$(npm view @mosaicstack/mosaic dist-tags --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/ --json)"
        DIST_TAGS_JSON="$DIST_TAGS_JSON" node -e 'const tags = JSON.parse(process.env.DIST_TAGS_JSON || "{}"); if (!tags || typeof tags !== "object" || !Object.hasOwn(tags, "latest")) { throw new Error("Gitea npm registry did not return a usable dist-tags object"); } console.log(`[publish-next] registry dist-tags OK: latest=${tags.latest}`);'
        node <<'NODE'
        const fs = require('node:fs');
        const path = require('node:path');
        const pipelineNumber = process.env.CI_PIPELINE_NUMBER;
        const roots = ['apps', 'packages', 'plugins'];
        const updated = [];
        function walk(dir) {
          if (!fs.existsSync(dir)) return;
          for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
            if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.turbo') continue;
            const fullPath = path.join(dir, entry.name);
            if (entry.isDirectory()) {
              const packagePath = path.join(fullPath, 'package.json');
              if (fs.existsSync(packagePath)) updatePackage(packagePath);
              walk(fullPath);
            }
          }
        }
        function updatePackage(packagePath) {
          const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
          if (!manifest.name?.startsWith('@mosaicstack/') || manifest.private) return;
          const stableMatch = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(manifest.version);
          if (!stableMatch) {
            throw new Error(`${manifest.name} has unsupported semver version '${manifest.version}'`);
          }
          const [, major, minor, patch] = stableMatch;
          const oldVersion = manifest.version;
          manifest.version = `${major}.${minor}.${Number(patch) + 1}-next.${pipelineNumber}`;
          fs.writeFileSync(packagePath, `${JSON.stringify(manifest, null, 2)}\n`);
          updated.push(`${manifest.name} ${oldVersion} -> ${manifest.version}`);
        }
        for (const root of roots) walk(root);
        if (updated.length === 0) throw new Error('No publishable @mosaicstack/* packages found');
        console.log(`[publish-next] computed prerelease versions for ${updated.length} packages:`);
        for (const line of updated) console.log(`[publish-next] ${line}`);
        NODE
        pnpm --filter "@mosaicstack/*" --filter "!@mosaicstack/web" --filter "!@mosaicstack/mosaic-as" publish --no-git-checks --access public --tag next
        EXPECTED_VERSION="$(node -p "require('./packages/mosaic/package.json').version")"
        RESOLVED_VERSION="$(npm view @mosaicstack/mosaic@next version --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/)"
        if [ "$RESOLVED_VERSION" != "$EXPECTED_VERSION" ]; then
          echo "[publish-next] FATAL: @mosaicstack/mosaic@next resolved '$RESOLVED_VERSION', expected '$EXPECTED_VERSION'" >&2
          exit 1
        fi
        echo "[publish-next] @mosaicstack/mosaic@next resolves to $RESOLVED_VERSION"
    depends_on:
      - build
  # TODO: Uncomment when ready to publish to npmjs.org
  # publish-npmjs:
  #   image: *node_image
@@ -224,17 +134,8 @@ steps:
      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
      - |
        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "next" ]; then
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
          if [ -n "$CI_COMMIT_TAG" ]; then
            echo "[publish] FATAL: next gateway publish must be sha-only; refusing tag '$CI_COMMIT_TAG'" >&2
            exit 1
          fi
          echo "[publish] next gateway publish is sha-only"
        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:latest"
        elif [ -z "$CI_COMMIT_TAG" ]; then
          echo "[publish] FATAL: gateway image publish may only run for main, next, or tag events" >&2
          exit 1
        fi
        if [ -n "$CI_COMMIT_TAG" ]; then
          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/gateway:$CI_COMMIT_TAG"
@@ -245,7 +146,7 @@ steps:
  build-appservice:
    image: gcr.io/kaniko-project/executor:debug
-    when: *main_image_build_when
+    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
@@ -271,7 +172,7 @@ steps:
  build-web:
    image: gcr.io/kaniko-project/executor:debug
-    when: *main_image_build_when
+    when: *image_build_when
    environment:
      REGISTRY_USER:
        from_secret: gitea_username
--- a/apps/gateway/src/tests/integration/federation-m3-list.integration.test.ts
+++ b/apps/gateway/src/tests/integration/federation-m3-list.integration.test.ts
@@ -1,519 +0,0 @@
 /**
 * Federation M3 single-gateway integration tests (FED-M3-10).
 *
 * Covers MILESTONES.md M3 acceptance:
 *  - #6: malformed certificate OIDs fail with 401; valid cert + revoked grant fails with 403.
 *  - #7: max_rows_per_query caps list results.
 *
 * Strategy:
 *  - Real PostgreSQL via @mosaicstack/db.
 *  - Mocked TLS context/Fastify request shim for FederationAuthGuard.
 *  - Direct controller calls using the real POST /api/federation/v1/list/:resource contract.
 *
 * Run:
 *   FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test -- \
 *     src/__tests__/integration/federation-m3-list.integration.test.ts
 */
 import 'reflect-metadata';
 import * as crypto from 'node:crypto';
 import type { ExecutionContext } from '@nestjs/common';
 import { Test, type TestingModule } from '@nestjs/testing';
 import type { FastifyReply, FastifyRequest } from 'fastify';
 import {
  and,
  createDb,
  eq,
  federationGrants,
  federationPeers,
  inArray,
  missionTasks,
  missions,
  projects,
  tasks,
  teamMembers,
  teams,
  type Db,
  type DbHandle,
  users,
 } from '@mosaicstack/db';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { DB } from '../../database/database.module.js';
 import { GrantsService } from '../../federation/grants.service.js';
 import { FederationAuthGuard } from '../../federation/server/federation-auth.guard.js';
 import { FederationScopeService } from '../../federation/server/scope.service.js';
 import { FederationListQueryService } from '../../federation/server/verbs/list-query.service.js';
 import { ListController } from '../../federation/server/verbs/list.controller.js';
 import {
  makeMosaicIssuedCert,
  makeSelfSignedCert,
 } from '../../federation/__tests__/helpers/test-cert.js';
 const run = process.env['FEDERATED_INTEGRATION'] === '1';
 const PG_URL = process.env['DATABASE_URL'] ?? 'postgresql://mosaic:mosaic@localhost:5433/mosaic';
 const RUN_ID = `fed-m3-10-${crypto.randomUUID()}`;
 const CERT_SERIAL_HEX = crypto.randomUUID().replace(/-/g, '').toUpperCase();
 interface TestIds {
  readonly subjectUserId: string;
  readonly otherUserId: string;
  readonly peerId: string;
  readonly revokedPeerId: string;
  readonly activeGrantId: string;
  readonly revokedGrantId: string;
  readonly subjectProjectId: string;
  readonly subjectMissionId: string;
  readonly otherProjectId: string;
  readonly teamId: string;
  readonly unauthorizedTeamId: string;
  readonly teamProjectId: string;
  readonly taskIds: readonly string[];
  readonly excludedTaskIds: readonly string[];
  readonly subjectNoteId: string;
  readonly otherUserNoteId: string;
 }
 function pemToDer(pem: string): Buffer {
  return Buffer.from(
    pem
      .replace(/-----BEGIN CERTIFICATE-----/, '')
      .replace(/-----END CERTIFICATE-----/, '')
      .replace(/\s+/g, ''),
    'base64',
  );
 }
 function makeFederationRequest(certPem: string): FastifyRequest {
  return {
    raw: {
      socket: {
        getPeerCertificate: () => ({
          raw: pemToDer(certPem),
          serialNumber: CERT_SERIAL_HEX,
        }),
      },
    },
  } as unknown as FastifyRequest;
 }
 function makeGuardContext(request: FastifyRequest): {
  readonly context: ExecutionContext;
  readonly sent: { statusCode?: number; payload?: unknown };
 } {
  const sent: { statusCode?: number; payload?: unknown } = {};
  const reply = {
    status: (statusCode: number) => {
      sent.statusCode = statusCode;
      return {
        header: () => ({
          send: (payload: unknown) => {
            sent.payload = payload;
          },
        }),
      };
    },
  } as unknown as FastifyReply;
  const context = {
    switchToHttp: () => ({
      getRequest: () => request,
      getResponse: () => reply,
    }),
  } as unknown as ExecutionContext;
  return { context, sent };
 }
 async function insertUser(db: Db, id: string, label: string): Promise<void> {
  await db.insert(users).values({
    id,
    name: `${RUN_ID}-${label}`,
    email: `${RUN_ID}-${label}@federation-test.invalid`,
    emailVerified: false,
  });
 }
 async function seedFixtures(db: Db): Promise<TestIds> {
  const subjectUserId = `${RUN_ID}-subject`;
  const otherUserId = `${RUN_ID}-other`;
  const peerId = crypto.randomUUID();
  const revokedPeerId = crypto.randomUUID();
  const activeGrantId = crypto.randomUUID();
  const revokedGrantId = crypto.randomUUID();
  const subjectProjectId = crypto.randomUUID();
  const subjectMissionId = crypto.randomUUID();
  const otherProjectId = crypto.randomUUID();
  const teamId = crypto.randomUUID();
  const unauthorizedTeamId = crypto.randomUUID();
  const teamProjectId = crypto.randomUUID();
  const taskIds = [crypto.randomUUID(), crypto.randomUUID(), crypto.randomUUID()] as const;
  const excludedTaskIds = [crypto.randomUUID(), crypto.randomUUID()] as const;
  const subjectNoteId = crypto.randomUUID();
  const otherUserNoteId = crypto.randomUUID();
  await insertUser(db, subjectUserId, 'subject');
  await insertUser(db, otherUserId, 'other');
  await db.insert(teams).values([
    {
      id: teamId,
      name: `${RUN_ID} allowed team`,
      slug: `${RUN_ID}-allowed-team`,
      ownerId: subjectUserId,
      managerId: subjectUserId,
    },
    {
      id: unauthorizedTeamId,
      name: `${RUN_ID} unauthorized team`,
      slug: `${RUN_ID}-unauthorized-team`,
      ownerId: otherUserId,
      managerId: otherUserId,
    },
  ]);
  await db.insert(teamMembers).values([
    { teamId, userId: subjectUserId, role: 'member' },
    { teamId: unauthorizedTeamId, userId: subjectUserId, role: 'member' },
  ]);
  await db.insert(projects).values([
    {
      id: subjectProjectId,
      name: `${RUN_ID} subject personal project`,
      ownerType: 'user',
      ownerId: subjectUserId,
    },
    {
      id: otherProjectId,
      name: `${RUN_ID} other personal project`,
      ownerType: 'user',
      ownerId: otherUserId,
    },
    {
      id: teamProjectId,
      name: `${RUN_ID} unauthorized team project`,
      ownerType: 'team',
      teamId: unauthorizedTeamId,
    },
  ]);
  await db.insert(missions).values({
    id: subjectMissionId,
    name: `${RUN_ID} subject mission`,
    projectId: subjectProjectId,
    userId: subjectUserId,
  });
  await db.insert(tasks).values([
    {
      id: taskIds[0],
      title: `${RUN_ID} visible task 1`,
      missionId: subjectMissionId,
      createdAt: new Date('2026-06-25T03:00:00.000Z'),
      updatedAt: new Date('2026-06-25T03:00:00.000Z'),
    },
    {
      id: taskIds[1],
      title: `${RUN_ID} visible task 2`,
      projectId: subjectProjectId,
      createdAt: new Date('2026-06-25T02:00:00.000Z'),
      updatedAt: new Date('2026-06-25T02:00:00.000Z'),
    },
    {
      id: taskIds[2],
      title: `${RUN_ID} visible task 3`,
      projectId: subjectProjectId,
      createdAt: new Date('2026-06-25T01:00:00.000Z'),
      updatedAt: new Date('2026-06-25T01:00:00.000Z'),
    },
    {
      id: excludedTaskIds[0],
      title: `${RUN_ID} other user task`,
      projectId: otherProjectId,
      createdAt: new Date('2026-06-25T04:00:00.000Z'),
      updatedAt: new Date('2026-06-25T04:00:00.000Z'),
    },
    {
      id: excludedTaskIds[1],
      title: `${RUN_ID} unauthorized team task`,
      projectId: teamProjectId,
      createdAt: new Date('2026-06-25T05:00:00.000Z'),
      updatedAt: new Date('2026-06-25T05:00:00.000Z'),
    },
  ]);
  await db.insert(missionTasks).values([
    {
      id: subjectNoteId,
      missionId: subjectMissionId,
      userId: subjectUserId,
      notes: `${RUN_ID} subject visible note`,
      createdAt: new Date('2026-06-25T03:30:00.000Z'),
      updatedAt: new Date('2026-06-25T03:30:00.000Z'),
    },
    {
      id: otherUserNoteId,
      missionId: subjectMissionId,
      userId: otherUserId,
      notes: `${RUN_ID} other user note on subject mission`,
      createdAt: new Date('2026-06-25T04:30:00.000Z'),
      updatedAt: new Date('2026-06-25T04:30:00.000Z'),
    },
  ]);
  await db.insert(federationPeers).values([
    {
      id: peerId,
      commonName: `${RUN_ID}-active-peer`,
      displayName: `${RUN_ID} Active Peer`,
      certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
      certSerial: CERT_SERIAL_HEX,
      certNotAfter: new Date(Date.now() + 86_400_000),
      state: 'active',
    },
    {
      id: revokedPeerId,
      commonName: `${RUN_ID}-revoked-peer`,
      displayName: `${RUN_ID} Revoked Peer`,
      certPem: '-----BEGIN CERTIFICATE-----\nMOCK\n-----END CERTIFICATE-----\n',
      certSerial: `${CERT_SERIAL_HEX}${RUN_ID.replace(/-/g, '').slice(0, 8).toUpperCase()}`,
      certNotAfter: new Date(Date.now() + 86_400_000),
      state: 'active',
    },
  ]);
  await db.insert(federationGrants).values([
    {
      id: activeGrantId,
      peerId,
      subjectUserId,
      status: 'active',
      scope: {
        resources: ['tasks', 'notes'],
        excluded_resources: [],
        filters: {
          tasks: { include_personal: true, include_teams: [] },
          notes: { include_personal: true, include_teams: [] },
        },
        max_rows_per_query: 2,
      },
    },
    {
      id: revokedGrantId,
      peerId,
      subjectUserId,
      status: 'revoked',
      revokedAt: new Date(),
      revokedReason: `${RUN_ID} revoked grant fixture`,
      scope: {
        resources: ['tasks'],
        excluded_resources: [],
        max_rows_per_query: 2,
      },
    },
  ]);
  return {
    subjectUserId,
    otherUserId,
    peerId,
    revokedPeerId,
    activeGrantId,
    revokedGrantId,
    subjectProjectId,
    subjectMissionId,
    otherProjectId,
    teamId,
    unauthorizedTeamId,
    teamProjectId,
    taskIds,
    excludedTaskIds,
    subjectNoteId,
    otherUserNoteId,
  };
 }
 async function cleanupFixtures(db: Db, ids: TestIds | undefined): Promise<void> {
  if (!ids) {
    return;
  }
  await db
    .delete(missionTasks)
    .where(inArray(missionTasks.id, [ids.subjectNoteId, ids.otherUserNoteId]))
    .catch(() => {});
  await db
    .delete(tasks)
    .where(inArray(tasks.id, [...ids.taskIds, ...ids.excludedTaskIds]))
    .catch(() => {});
  await db
    .delete(missions)
    .where(eq(missions.id, ids.subjectMissionId))
    .catch(() => {});
  await db
    .delete(projects)
    .where(inArray(projects.id, [ids.subjectProjectId, ids.otherProjectId, ids.teamProjectId]))
    .catch(() => {});
  await db
    .delete(teamMembers)
    .where(
      and(
        eq(teamMembers.userId, ids.subjectUserId),
        inArray(teamMembers.teamId, [ids.teamId, ids.unauthorizedTeamId]),
      ),
    )
    .catch(() => {});
  await db
    .delete(teams)
    .where(inArray(teams.id, [ids.teamId, ids.unauthorizedTeamId]))
    .catch(() => {});
  await db
    .delete(federationGrants)
    .where(inArray(federationGrants.id, [ids.activeGrantId, ids.revokedGrantId]))
    .catch(() => {});
  await db
    .delete(federationPeers)
    .where(inArray(federationPeers.id, [ids.peerId, ids.revokedPeerId]))
    .catch(() => {});
  await db
    .delete(users)
    .where(inArray(users.id, [ids.subjectUserId, ids.otherUserId]))
    .catch(() => {});
 }
 describe.skipIf(!run)('federation M3 list verb — single-gateway integration', () => {
  let handle: DbHandle;
  let db: Db;
  let moduleRef: TestingModule;
  let guard: FederationAuthGuard;
  let listController: ListController;
  let ids: TestIds | undefined;
  beforeAll(async () => {
    handle = createDb(PG_URL);
    db = handle.db;
    ids = await seedFixtures(db);
    moduleRef = await Test.createTestingModule({
      controllers: [ListController],
      providers: [
        { provide: DB, useValue: db },
        GrantsService,
        FederationAuthGuard,
        FederationScopeService,
        FederationListQueryService,
      ],
    }).compile();
    guard = moduleRef.get(FederationAuthGuard);
    listController = moduleRef.get(ListController);
  }, 30_000);
  afterAll(async () => {
    await moduleRef?.close().catch((e: unknown) => console.error('[fed-m3-10 cleanup]', e));
    await cleanupFixtures(db, ids).catch((e: unknown) => console.error('[fed-m3-10 cleanup]', e));
    await handle?.close().catch((e: unknown) => console.error('[fed-m3-10 cleanup]', e));
  });
  it('#6 — rejects a client cert with malformed/missing Mosaic OIDs with 401', async () => {
    const malformedOidCert = await makeSelfSignedCert();
    const request = makeFederationRequest(malformedOidCert);
    const { context, sent } = makeGuardContext(request);
    await expect(guard.canActivate(context)).resolves.toBe(false);
    expect(sent.statusCode).toBe(401);
    expect(sent.payload).toMatchObject({
      error: {
        code: 'unauthorized',
        message: expect.stringContaining('missing required OID'),
      },
    });
    expect(request.federationContext).toBeUndefined();
  });
  it('#6 — rejects a valid client cert when its grant is revoked with 403', async () => {
    expect(ids).toBeDefined();
    const revokedCert = await makeMosaicIssuedCert({
      grantId: ids!.revokedGrantId,
      subjectUserId: ids!.subjectUserId,
    });
    const request = makeFederationRequest(revokedCert);
    const { context, sent } = makeGuardContext(request);
    await expect(guard.canActivate(context)).resolves.toBe(false);
    expect(sent.statusCode).toBe(403);
    expect(sent.payload).toMatchObject({
      error: {
        code: 'forbidden',
        message: 'Federation access denied',
      },
    });
    expect(request.federationContext).toBeUndefined();
  });
  it('#7 — enforces max_rows_per_query on POST /api/federation/v1/list/:resource', async () => {
    expect(ids).toBeDefined();
    const activeCert = await makeMosaicIssuedCert({
      grantId: ids!.activeGrantId,
      subjectUserId: ids!.subjectUserId,
    });
    const request = makeFederationRequest(activeCert);
    const { context } = makeGuardContext(request);
    await expect(guard.canActivate(context)).resolves.toBe(true);
    const response = await listController.list('tasks', request, { limit: 100 });
    const returnedIds = response.items.map((item) => item['id']);
    expect(response.items).toHaveLength(2);
    expect(response._truncated).toBe(true);
    expect(response.nextCursor).toEqual(expect.any(String));
    expect(returnedIds).toEqual([ids!.taskIds[0], ids!.taskIds[1]]);
    expect(returnedIds).not.toContain(ids!.taskIds[2]);
    for (const excludedId of ids!.excludedTaskIds) {
      expect(returnedIds).not.toContain(excludedId);
    }
    expect(response.items.every((item) => item._source === 'local')).toBe(true);
  });
  it('excludes another user mission task notes on the same authorized mission', async () => {
    expect(ids).toBeDefined();
    const activeCert = await makeMosaicIssuedCert({
      grantId: ids!.activeGrantId,
      subjectUserId: ids!.subjectUserId,
    });
    const request = makeFederationRequest(activeCert);
    const { context } = makeGuardContext(request);
    await expect(guard.canActivate(context)).resolves.toBe(true);
    const response = await listController.list('notes', request, { limit: 10 });
    const returnedIds = response.items.map((item) => item['id']);
    expect(returnedIds).toEqual([ids!.subjectNoteId]);
    expect(returnedIds).not.toContain(ids!.otherUserNoteId);
    expect(response.items.every((item) => item._source === 'local')).toBe(true);
  });
  it('fails closed for unsupported list resources', async () => {
    expect(ids).toBeDefined();
    const activeCert = await makeMosaicIssuedCert({
      grantId: ids!.activeGrantId,
      subjectUserId: ids!.subjectUserId,
    });
    const request = makeFederationRequest(activeCert);
    const { context } = makeGuardContext(request);
    await expect(guard.canActivate(context)).resolves.toBe(true);
    await expect(listController.list('widgets', request, {})).rejects.toMatchObject({
      response: {
        error: {
          code: 'scope_violation',
          message: 'Requested federation resource is not supported',
        },
      },
      status: 403,
    });
  });
 });
--- a/apps/gateway/src/federation/federation.module.ts
+++ b/apps/gateway/src/federation/federation.module.ts
@@ -5,8 +5,6 @@ import { EnrollmentController } from './enrollment.controller.js';
 import { EnrollmentService } from './enrollment.service.js';
 import { FederationController } from './federation.controller.js';
 import { CapabilitiesController } from './server/verbs/capabilities.controller.js';
 import { GetController } from './server/verbs/get.controller.js';
 import { FederationGetQueryService } from './server/verbs/get-query.service.js';
 import { GrantsService } from './grants.service.js';
 import { FederationClientService, QuerySourceService } from './client/index.js';
 import { FederationAuthGuard, FederationScopeService } from './server/index.js';
@@ -14,13 +12,7 @@ import { ListController } from './server/verbs/list.controller.js';
 import { FederationListQueryService } from './server/verbs/list-query.service.js';
@Module({
-  controllers: [
+  controllers: [EnrollmentController, FederationController, CapabilitiesController, ListController],
    EnrollmentController,
    FederationController,
    CapabilitiesController,
    ListController,
    GetController,
  ],
  providers: [
    AdminGuard,
    CaService,
@@ -31,7 +23,6 @@ import { FederationListQueryService } from './server/verbs/list-query.service.js
    FederationAuthGuard,
    FederationScopeService,
    FederationListQueryService,
    FederationGetQueryService,
  ],
  exports: [
    CaService,
@@ -42,7 +33,6 @@ import { FederationListQueryService } from './server/verbs/list-query.service.js
    FederationAuthGuard,
    FederationScopeService,
    FederationListQueryService,
    FederationGetQueryService,
  ],
 })
 export class FederationModule {}
--- a/apps/gateway/src/federation/server/verbs/tests/get-query.service.spec.ts
+++ b/apps/gateway/src/federation/server/verbs/tests/get-query.service.spec.ts
@@ -1,348 +0,0 @@
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import {
  createPgliteDb,
  missionTasks,
  missions,
  projects,
  runPgliteMigrations,
  teams,
  users,
  type Db,
  type DbHandle,
 } from '@mosaicstack/db';
 import type { FederationScopeQueryFilter } from '../../scope.service.js';
 import { FederationGetQueryService } from '../get-query.service.js';
 const CREDENTIAL_FILTER: FederationScopeQueryFilter = {
  resource: 'credentials',
  subjectUserId: 'user-1',
  includePersonal: true,
  teamIds: [],
  limit: 1,
  maxRowsPerQuery: 25,
 };
 const SUBJECT_USER_ID = 'fed-m3-06-subject';
 const OTHER_USER_ID = 'fed-m3-06-other';
 const TEAM_ID = '06000000-0000-4000-8000-000000000001';
 const UNAUTHORIZED_TEAM_ID = '06000000-0000-4000-8000-000000000002';
 const PERSONAL_PROJECT_ID = '06000000-0000-4000-8000-000000000101';
 const TEAM_PROJECT_ID = '06000000-0000-4000-8000-000000000102';
 const UNAUTHORIZED_PROJECT_ID = '06000000-0000-4000-8000-000000000103';
 const PERSONAL_MISSION_ID = '06000000-0000-4000-8000-000000000201';
 const TEAM_MISSION_ID = '06000000-0000-4000-8000-000000000202';
 const UNAUTHORIZED_MISSION_ID = '06000000-0000-4000-8000-000000000203';
 const SUBJECT_TEAM_NOTE_ID = '06000000-0000-4000-8000-000000000301';
 const OTHER_TEAM_NOTE_ID = '06000000-0000-4000-8000-000000000302';
 const SUBJECT_PERSONAL_NOTE_ID = '06000000-0000-4000-8000-000000000303';
 const SUBJECT_UNAUTHORIZED_NOTE_ID = '06000000-0000-4000-8000-000000000304';
 let dbHandle: DbHandle | undefined;
 function makeService() {
  return new FederationGetQueryService({} as Db);
 }
 function makeDbService() {
  if (!dbHandle) {
    throw new Error('test DB not initialized');
  }
  return new FederationGetQueryService(dbHandle.db);
 }
 async function seedNotesFixture() {
  if (!dbHandle) {
    throw new Error('test DB not initialized');
  }
  await dbHandle.db.insert(users).values([
    {
      id: SUBJECT_USER_ID,
      name: 'Federation Subject',
      email: `${SUBJECT_USER_ID}@example.test`,
      emailVerified: false,
    },
    {
      id: OTHER_USER_ID,
      name: 'Federation Other',
      email: `${OTHER_USER_ID}@example.test`,
      emailVerified: false,
    },
  ]);
  await dbHandle.db.insert(teams).values([
    {
      id: TEAM_ID,
      name: 'FED-M3-06 Team',
      slug: 'fed-m3-06-team',
      ownerId: SUBJECT_USER_ID,
      managerId: SUBJECT_USER_ID,
    },
    {
      id: UNAUTHORIZED_TEAM_ID,
      name: 'FED-M3-06 Unauthorized Team',
      slug: 'fed-m3-06-unauthorized-team',
      ownerId: OTHER_USER_ID,
      managerId: OTHER_USER_ID,
    },
  ]);
  await dbHandle.db.insert(projects).values([
    {
      id: PERSONAL_PROJECT_ID,
      name: 'FED-M3-06 Personal Project',
      ownerId: SUBJECT_USER_ID,
      ownerType: 'user',
    },
    {
      id: TEAM_PROJECT_ID,
      name: 'FED-M3-06 Team Project',
      teamId: TEAM_ID,
      ownerType: 'team',
    },
    {
      id: UNAUTHORIZED_PROJECT_ID,
      name: 'FED-M3-06 Unauthorized Project',
      teamId: UNAUTHORIZED_TEAM_ID,
      ownerType: 'team',
    },
  ]);
  await dbHandle.db.insert(missions).values([
    {
      id: PERSONAL_MISSION_ID,
      name: 'FED-M3-06 Personal Mission',
      projectId: PERSONAL_PROJECT_ID,
      userId: SUBJECT_USER_ID,
    },
    {
      id: TEAM_MISSION_ID,
      name: 'FED-M3-06 Team Mission',
      projectId: TEAM_PROJECT_ID,
      userId: SUBJECT_USER_ID,
    },
    {
      id: UNAUTHORIZED_MISSION_ID,
      name: 'FED-M3-06 Unauthorized Mission',
      projectId: UNAUTHORIZED_PROJECT_ID,
      userId: SUBJECT_USER_ID,
    },
  ]);
  await dbHandle.db.insert(missionTasks).values([
    {
      id: SUBJECT_TEAM_NOTE_ID,
      missionId: TEAM_MISSION_ID,
      userId: SUBJECT_USER_ID,
      notes: 'subject note on team mission',
      createdAt: new Date('2026-06-24T03:00:00.000Z'),
      updatedAt: new Date('2026-06-24T03:00:00.000Z'),
    },
    {
      id: OTHER_TEAM_NOTE_ID,
      missionId: TEAM_MISSION_ID,
      userId: OTHER_USER_ID,
      notes: 'other user note on team mission',
      createdAt: new Date('2026-06-24T02:00:00.000Z'),
      updatedAt: new Date('2026-06-24T02:00:00.000Z'),
    },
    {
      id: SUBJECT_PERSONAL_NOTE_ID,
      missionId: PERSONAL_MISSION_ID,
      userId: SUBJECT_USER_ID,
      notes: 'subject note on personal mission',
      createdAt: new Date('2026-06-24T01:00:00.000Z'),
      updatedAt: new Date('2026-06-24T01:00:00.000Z'),
    },
    {
      id: SUBJECT_UNAUTHORIZED_NOTE_ID,
      missionId: UNAUTHORIZED_MISSION_ID,
      userId: SUBJECT_USER_ID,
      notes: 'subject note outside grant-visible missions',
      createdAt: new Date('2026-06-24T04:00:00.000Z'),
      updatedAt: new Date('2026-06-24T04:00:00.000Z'),
    },
  ]);
 }
 describe('FederationGetQueryService', () => {
  beforeAll(async () => {
    dbHandle = createPgliteDb(`memory://fed-m3-06-get-${Date.now()}`);
    await runPgliteMigrations(dbHandle);
    await seedNotesFixture();
  });
  afterAll(async () => {
    await dbHandle?.close();
    dbHandle = undefined;
  });
  it('denies sensitive resources in native RBAC for M3 get reads', async () => {
    const service = makeService();
    await expect(
      service.evaluateReadAccess({
        grantId: 'grant-1',
        peerId: 'peer-1',
        subjectUserId: 'user-1',
        resource: 'credentials',
      }),
    ).resolves.toMatchObject({
      allowed: false,
      reason: 'credentials federation get access is not implemented in M3',
    });
  });
  it('allows personal memory reads without requiring team lookup', async () => {
    const service = makeService();
    await expect(
      service.evaluateReadAccess({
        grantId: 'grant-1',
        peerId: 'peer-1',
        subjectUserId: 'user-1',
        resource: 'memory',
      }),
    ).resolves.toEqual({
      allowed: true,
      access: { includePersonal: true, teamIds: [] },
    });
  });
  it('uses subject team membership as the native RBAC upper bound for task and note reads', async () => {
    const service = makeService();
    const listSubjectTeamIds = vi.fn().mockResolvedValue(['team-1', 'team-2']);
    (
      service as unknown as {
        listSubjectTeamIds: (subjectUserId: string) => Promise<string[]>;
      }
    ).listSubjectTeamIds = listSubjectTeamIds;
    await expect(
      service.evaluateReadAccess({
        grantId: 'grant-1',
        peerId: 'peer-1',
        subjectUserId: 'user-1',
        resource: 'tasks',
      }),
    ).resolves.toEqual({
      allowed: true,
      access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
    });
    expect(listSubjectTeamIds).toHaveBeenCalledWith('user-1');
  });
  it('does not query storage for sensitive get resources even if scope allowed them', async () => {
    const service = makeService();
    await expect(service.get({ filter: CREDENTIAL_FILTER, id: 'cred-1' })).resolves.toEqual({
      status: 'denied',
      reason: 'credentials federation get is not implemented',
    });
  });
  it('fails closed for unsupported resources instead of returning undefined', async () => {
    const service = makeService();
    await expect(
      service.get({
        filter: {
          ...CREDENTIAL_FILTER,
          resource: 'unknown-resource' as FederationScopeQueryFilter['resource'],
        },
        id: 'row-1',
      }),
    ).resolves.toEqual({
      status: 'denied',
      reason: 'Unsupported federation get resource: unknown-resource',
    });
  });
  it('does not leak another user mission task note through team-scoped get reads', async () => {
    const service = makeDbService();
    await expect(
      service.get({
        filter: {
          resource: 'notes',
          subjectUserId: SUBJECT_USER_ID,
          includePersonal: false,
          teamIds: [TEAM_ID],
          limit: 1,
          maxRowsPerQuery: 10,
        },
        id: OTHER_TEAM_NOTE_ID,
      }),
    ).resolves.toEqual({
      status: 'denied',
      reason: 'Note is outside the federated scope',
    });
  });
  it('does not return subject notes from missions outside the grant-visible project set', async () => {
    const service = makeDbService();
    await expect(
      service.get({
        filter: {
          resource: 'notes',
          subjectUserId: SUBJECT_USER_ID,
          includePersonal: true,
          teamIds: [TEAM_ID],
          limit: 1,
          maxRowsPerQuery: 10,
        },
        id: SUBJECT_UNAUTHORIZED_NOTE_ID,
      }),
    ).resolves.toEqual({
      status: 'denied',
      reason: 'Note is outside the federated scope',
    });
  });
  it('returns a subject note only when subject ownership and authorized mission intersect', async () => {
    const service = makeDbService();
    await expect(
      service.get({
        filter: {
          resource: 'notes',
          subjectUserId: SUBJECT_USER_ID,
          includePersonal: false,
          teamIds: [TEAM_ID],
          limit: 1,
          maxRowsPerQuery: 10,
        },
        id: SUBJECT_TEAM_NOTE_ID,
      }),
    ).resolves.toMatchObject({
      status: 'found',
      item: {
        id: SUBJECT_TEAM_NOTE_ID,
        missionId: TEAM_MISSION_ID,
        content: 'subject note on team mission',
      },
    });
  });
  it('does not return subject personal notes when includePersonal is false', async () => {
    const service = makeDbService();
    await expect(
      service.get({
        filter: {
          resource: 'notes',
          subjectUserId: SUBJECT_USER_ID,
          includePersonal: false,
          teamIds: [TEAM_ID],
          limit: 1,
          maxRowsPerQuery: 10,
        },
        id: SUBJECT_PERSONAL_NOTE_ID,
      }),
    ).resolves.toEqual({
      status: 'denied',
      reason: 'Note is outside the federated scope',
    });
  });
 });
--- a/apps/gateway/src/federation/server/verbs/tests/get.controller.spec.ts
+++ b/apps/gateway/src/federation/server/verbs/tests/get.controller.spec.ts
@@ -1,207 +0,0 @@
 import 'reflect-metadata';
 import { RequestMethod } from '@nestjs/common';
 import type { FastifyRequest } from 'fastify';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { FederationAuthGuard } from '../../federation-auth.guard.js';
 import type {
  FederationScopeEvaluationResult,
  FederationScopeQueryFilter,
 } from '../../scope.service.js';
 import { GetController } from '../get.controller.js';
 import type { FederationGetQueryResult } from '../get-query.service.js';
 const FEDERATION_CONTEXT = {
  grantId: 'grant-1',
  peerId: 'peer-1',
  subjectUserId: 'user-1',
  scope: { resources: ['tasks'], max_rows_per_query: 25 },
 };
 const TASK_FILTER: FederationScopeQueryFilter = {
  resource: 'tasks',
  subjectUserId: 'user-1',
  includePersonal: true,
  teamIds: ['team-1'],
  limit: 1,
  maxRowsPerQuery: 25,
 };
 function makeRequest(): FastifyRequest {
  return { federationContext: FEDERATION_CONTEXT } as unknown as FastifyRequest;
 }
 function allowedScope(
  filter: FederationScopeQueryFilter = TASK_FILTER,
 ): FederationScopeEvaluationResult {
  return { allowed: true, filter };
 }
 function makeController(opts?: {
  scopeResult?: FederationScopeEvaluationResult;
  queryResult?: FederationGetQueryResult;
 }) {
  const scope = {
    evaluateAccess: vi.fn().mockResolvedValue(opts?.scopeResult ?? allowedScope()),
  };
  const query = {
    evaluateReadAccess: vi.fn(),
    get: vi.fn().mockResolvedValue(
      opts?.queryResult ?? {
        status: 'found',
        item: {
          id: 'task-1',
          title: 'Federated task',
          createdAt: new Date('2026-06-24T00:00:00.000Z'),
        },
      },
    ),
  };
  return {
    controller: new GetController(scope as never, query as never),
    scope,
    query,
  };
 }
 describe('GetController', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });
  it('declares POST /api/federation/v1/get/:resource/:id protected only by FederationAuthGuard', () => {
    expect(Reflect.getMetadata('path', GetController)).toBe('api/federation/v1/get');
    expect(Reflect.getMetadata('path', GetController.prototype.get)).toBe(':resource/:id');
    expect(Reflect.getMetadata('method', GetController.prototype.get)).toBe(RequestMethod.POST);
    expect(Reflect.getMetadata('__guards__', GetController)).toEqual([FederationAuthGuard]);
  });
  it('runs AuthGuard context through ScopeService and returns one local-source tagged row', async () => {
    const { controller, scope, query } = makeController();
    const response = await controller.get('tasks', 'task-1', makeRequest());
    expect(scope.evaluateAccess).toHaveBeenCalledWith({
      context: FEDERATION_CONTEXT,
      resource: 'tasks',
      requestedLimit: 1,
      nativeRbac: query,
    });
    expect(query.get).toHaveBeenCalledWith({ filter: TASK_FILTER, id: 'task-1' });
    expect(response).toEqual({
      item: {
        id: 'task-1',
        title: 'Federated task',
        createdAt: new Date('2026-06-24T00:00:00.000Z'),
        _source: 'local',
      },
    });
  });
  it('returns a federation error envelope when auth guard context is missing', async () => {
    const { controller, scope, query } = makeController();
    await expect(
      controller.get('tasks', 'task-1', {} as unknown as FastifyRequest),
    ).rejects.toMatchObject({
      response: {
        error: {
          code: 'unauthorized',
          message: 'Federation context missing',
        },
      },
      status: 401,
    });
    expect(scope.evaluateAccess).not.toHaveBeenCalled();
    expect(query.get).not.toHaveBeenCalled();
  });
  it('returns a federation error envelope when scope evaluation denies access', async () => {
    const { controller, query } = makeController({
      scopeResult: {
        allowed: false,
        deny: {
          code: 'resource_excluded',
          stage: 'resource_exclusion',
          statusCode: 403,
          message: 'Requested federation resource is explicitly excluded by grant scope',
          grantId: 'grant-1',
          peerId: 'peer-1',
          subjectUserId: 'user-1',
          resource: 'credentials',
        },
      },
    });
    await expect(controller.get('credentials', 'cred-1', makeRequest())).rejects.toMatchObject({
      response: {
        error: {
          code: 'scope_violation',
          message: 'Requested federation resource is explicitly excluded by grant scope',
        },
      },
      status: 403,
    });
    expect(query.get).not.toHaveBeenCalled();
  });
  it('returns 404 when the scoped query layer cannot find the resource id', async () => {
    const { controller } = makeController({ queryResult: { status: 'not_found' } });
    await expect(controller.get('tasks', 'missing-task', makeRequest())).rejects.toMatchObject({
      response: { error: { code: 'not_found' } },
      status: 404,
    });
  });
  it('returns 403 when the resource exists outside the RBAC/scope intersection', async () => {
    const { controller } = makeController({
      queryResult: { status: 'denied', reason: 'Task is outside the federated scope' },
    });
    await expect(controller.get('tasks', 'task-2', makeRequest())).rejects.toMatchObject({
      response: {
        error: {
          code: 'scope_violation',
          message: 'Task is outside the federated scope',
        },
      },
      status: 403,
    });
  });
  it('fails closed when the query layer denies an unsupported resource', async () => {
    const unsupportedFilter: FederationScopeQueryFilter = {
      ...TASK_FILTER,
      resource: 'unknown-resource' as FederationScopeQueryFilter['resource'],
    };
    const { controller } = makeController({
      scopeResult: allowedScope(unsupportedFilter),
      queryResult: {
        status: 'denied',
        reason: 'Unsupported federation get resource: unknown-resource',
      },
    });
    await expect(controller.get('unknown-resource', 'row-1', makeRequest())).rejects.toMatchObject({
      response: {
        error: {
          code: 'scope_violation',
          message: 'Unsupported federation get resource: unknown-resource',
        },
      },
      status: 403,
    });
  });
  it('rejects empty ids before evaluating scope', async () => {
    const { controller, scope, query } = makeController();
    await expect(controller.get('tasks', '   ', makeRequest())).rejects.toMatchObject({
      response: { error: { code: 'invalid_request' } },
      status: 400,
    });
    expect(scope.evaluateAccess).not.toHaveBeenCalled();
    expect(query.get).not.toHaveBeenCalled();
  });
 });
--- a/apps/gateway/src/federation/server/verbs/get-query.service.ts
+++ b/apps/gateway/src/federation/server/verbs/get-query.service.ts
@@ -1,311 +0,0 @@
 /**
 * Federation get query layer (FED-M3-06).
 *
 * Read-only DB adapter used by GetController after FederationAuthGuard and
 * FederationScopeService have established the subject user, allowed resource,
 * native-RBAC intersection, and row cap. Audit writes are intentionally
 * deferred to M4.
 */
 import { Inject, Injectable } from '@nestjs/common';
 import {
  and,
  eq,
  inArray,
  insights,
  or,
  missionTasks,
  missions,
  preferences,
  projects,
  tasks,
  teamMembers,
  type Db,
 } from '@mosaicstack/db';
 import { DB } from '../../../database/database.module.js';
 import type {
  FederationNativeRbacEvaluator,
  FederationNativeRbacRequest,
  FederationNativeRbacResult,
  FederationScopeQueryFilter,
 } from '../scope.service.js';
 export interface FederationGetQueryRequest {
  readonly filter: FederationScopeQueryFilter;
  readonly id: string;
 }
 export interface FederationGetQueryFoundResult<T extends object = Record<string, unknown>> {
  readonly status: 'found';
  readonly item: T;
 }
 export interface FederationGetQueryNotFoundResult {
  readonly status: 'not_found';
 }
 export interface FederationGetQueryDeniedResult {
  readonly status: 'denied';
  readonly reason: string;
 }
 export type FederationGetQueryResult<T extends object = Record<string, unknown>> =
  | FederationGetQueryFoundResult<T>
  | FederationGetQueryNotFoundResult
  | FederationGetQueryDeniedResult;
 type RowObject = Record<string, unknown>;
 function firstRow<T>(rows: T[]): T | undefined {
  return rows[0];
 }
 function rowBelongsToAccessibleProjectOrMission(
  row: { projectId?: string | null; missionId?: string | null },
  projectIds: readonly string[],
  missionIds: readonly string[],
 ): boolean {
  return (
    (typeof row.projectId === 'string' && projectIds.includes(row.projectId)) ||
    (typeof row.missionId === 'string' && missionIds.includes(row.missionId))
  );
 }
@Injectable()
 export class FederationGetQueryService implements FederationNativeRbacEvaluator {
  constructor(@Inject(DB) private readonly db: Db) {}
  async evaluateReadAccess(
    request: FederationNativeRbacRequest,
  ): Promise<FederationNativeRbacResult> {
    if (request.resource === 'credentials' || request.resource === 'api_keys') {
      return {
        allowed: false,
        reason: `${request.resource} federation get access is not implemented in M3`,
        details: { resource: request.resource },
      };
    }
    if (request.resource === 'memory') {
      return { allowed: true, access: { includePersonal: true, teamIds: [] } };
    }
    const teamIds = await this.listSubjectTeamIds(request.subjectUserId);
    return { allowed: true, access: { includePersonal: true, teamIds } };
  }
  async get<T extends RowObject = RowObject>(
    request: FederationGetQueryRequest,
  ): Promise<FederationGetQueryResult<T>> {
    return this.getByResource(request.filter, request.id) as Promise<FederationGetQueryResult<T>>;
  }
  private async getByResource(
    filter: FederationScopeQueryFilter,
    id: string,
  ): Promise<FederationGetQueryResult> {
    switch (filter.resource) {
      case 'tasks':
        return this.getTask(filter, id);
      case 'notes':
        return this.getNote(filter, id);
      case 'memory':
        return this.getMemory(filter, id);
      case 'credentials':
      case 'api_keys':
        return { status: 'denied', reason: `${filter.resource} federation get is not implemented` };
      default:
        return {
          status: 'denied',
          reason: `Unsupported federation get resource: ${String(filter.resource)}`,
        };
    }
  }
  private async listSubjectTeamIds(subjectUserId: string): Promise<string[]> {
    const rows = await this.db
      .select({ teamId: teamMembers.teamId })
      .from(teamMembers)
      .where(eq(teamMembers.userId, subjectUserId));
    return rows.map((row) => row.teamId);
  }
  private async listAccessibleProjectIds(filter: FederationScopeQueryFilter): Promise<string[]> {
    const clauses = [];
    if (filter.includePersonal) {
      clauses.push(and(eq(projects.ownerType, 'user'), eq(projects.ownerId, filter.subjectUserId)));
    }
    if (filter.teamIds.length > 0) {
      // Project team ownership follows TeamsService.canAccessProject: team-owned
      // rows are authorized through projects.teamId, while ownerId remains the
      // user who created/bootstrapped the project.
      clauses.push(
        and(eq(projects.ownerType, 'team'), inArray(projects.teamId, [...filter.teamIds])),
      );
    }
    if (clauses.length === 0) {
      return [];
    }
    const rows = await this.db
      .select({ id: projects.id })
      .from(projects)
      .where(clauses.length === 1 ? clauses[0] : or(...clauses));
    return rows.map((row) => row.id);
  }
  private async listMissionIds(projectIds: readonly string[]): Promise<string[]> {
    if (projectIds.length === 0) {
      return [];
    }
    const rows = await this.db
      .select({ id: missions.id })
      .from(missions)
      .where(inArray(missions.projectId, [...projectIds]));
    return rows.map((row) => row.id);
  }
  private async getTask(
    filter: FederationScopeQueryFilter,
    id: string,
  ): Promise<FederationGetQueryResult> {
    const row = firstRow(
      await this.db
        .select({
          id: tasks.id,
          title: tasks.title,
          description: tasks.description,
          status: tasks.status,
          priority: tasks.priority,
          projectId: tasks.projectId,
          missionId: tasks.missionId,
          assignee: tasks.assignee,
          tags: tasks.tags,
          dueDate: tasks.dueDate,
          metadata: tasks.metadata,
          createdAt: tasks.createdAt,
          updatedAt: tasks.updatedAt,
        })
        .from(tasks)
        .where(eq(tasks.id, id))
        .limit(1),
    );
    if (!row) {
      return { status: 'not_found' };
    }
    const projectIds = await this.listAccessibleProjectIds(filter);
    const missionIds = await this.listMissionIds(projectIds);
    if (!rowBelongsToAccessibleProjectOrMission(row, projectIds, missionIds)) {
      return { status: 'denied', reason: 'Task is outside the federated scope' };
    }
    return { status: 'found', item: row as RowObject };
  }
  private async getNote(
    filter: FederationScopeQueryFilter,
    id: string,
  ): Promise<FederationGetQueryResult> {
    const row = firstRow(
      await this.db
        .select({
          id: missionTasks.id,
          missionId: missionTasks.missionId,
          taskId: missionTasks.taskId,
          userId: missionTasks.userId,
          status: missionTasks.status,
          content: missionTasks.notes,
          createdAt: missionTasks.createdAt,
          updatedAt: missionTasks.updatedAt,
        })
        .from(missionTasks)
        .where(eq(missionTasks.id, id))
        .limit(1),
    );
    if (!row || row.content === null || row.content === '') {
      return { status: 'not_found' };
    }
    const projectIds = await this.listAccessibleProjectIds(filter);
    const missionIds = await this.listMissionIds(projectIds);
    // mission_tasks rows are user-scoped even when the mission belongs to a team.
    // Scope-visible missions must intersect with subject ownership; team scope
    // narrows mission IDs but never widens note reads to another user's rows.
    if (row.userId !== filter.subjectUserId || !missionIds.includes(row.missionId)) {
      return { status: 'denied', reason: 'Note is outside the federated scope' };
    }
    const item = { ...row } as RowObject;
    delete item['userId'];
    return { status: 'found', item };
  }
  private async getMemory(
    filter: FederationScopeQueryFilter,
    id: string,
  ): Promise<FederationGetQueryResult> {
    const [insightRow, preferenceRow] = await Promise.all([
      this.db
        .select({
          id: insights.id,
          userId: insights.userId,
          kind: insights.source,
          content: insights.content,
          category: insights.category,
          relevanceScore: insights.relevanceScore,
          metadata: insights.metadata,
          createdAt: insights.createdAt,
          updatedAt: insights.updatedAt,
        })
        .from(insights)
        .where(eq(insights.id, id))
        .limit(1)
        .then(firstRow),
      this.db
        .select({
          id: preferences.id,
          userId: preferences.userId,
          kind: preferences.category,
          key: preferences.key,
          value: preferences.value,
          source: preferences.source,
          mutable: preferences.mutable,
          createdAt: preferences.createdAt,
          updatedAt: preferences.updatedAt,
        })
        .from(preferences)
        .where(eq(preferences.id, id))
        .limit(1)
        .then(firstRow),
    ]);
    const candidates = [insightRow, preferenceRow].filter(
      (row): row is NonNullable<typeof row> => row !== undefined,
    );
    if (candidates.length === 0) {
      return { status: 'not_found' };
    }
    if (!filter.includePersonal) {
      return { status: 'denied', reason: 'Memory personal rows are outside the federated scope' };
    }
    const accessible = candidates.find((row) => row.userId === filter.subjectUserId);
    if (!accessible) {
      return { status: 'denied', reason: 'Memory row belongs to another subject user' };
    }
    const item = { ...accessible } as RowObject;
    delete item['userId'];
    return { status: 'found', item };
  }
 }
--- a/apps/gateway/src/federation/server/verbs/get.controller.ts
+++ b/apps/gateway/src/federation/server/verbs/get.controller.ts
@@ -1,100 +0,0 @@
 /**
 * Federation get verb (FED-M3-06).
 *
 * POST /api/federation/v1/get/:resource/:id
 *
 * Pipeline: FederationAuthGuard attaches the active grant context, then
 * FederationScopeService enforces grant scope + native RBAC intersection, then
 * the read-only query layer fetches one local row and tags it with `_source`.
 * Read audit-log writes are deferred to M4; this controller does not persist
 * request or response bodies.
 */
 import { Controller, HttpException, Inject, Param, Post, Req, UseGuards } from '@nestjs/common';
 import type { FastifyRequest } from 'fastify';
 import {
  FederationInvalidRequestError,
  FederationNotFoundError,
  FederationScopeViolationError,
  FederationUnauthorizedError,
  SOURCE_LOCAL,
  type FederationGetResponse,
  type SourceTag,
 } from '@mosaicstack/types';
 import { FederationAuthGuard } from '../federation-auth.guard.js';
 import '../federation-context.js';
 import { FederationScopeService } from '../scope.service.js';
 import { FederationGetQueryService } from './get-query.service.js';
 type FederatedRow = Record<string, unknown> & SourceTag;
 function scopeDenyToHttpException(deny: {
  readonly statusCode: 400 | 403;
  readonly message: string;
 }): HttpException {
  const ErrorClass =
    deny.statusCode === 400 ? FederationInvalidRequestError : FederationScopeViolationError;
  return new HttpException(new ErrorClass(deny.message, deny).toEnvelope(), deny.statusCode);
 }
@Controller('api/federation/v1/get')
@UseGuards(FederationAuthGuard)
 export class GetController {
  constructor(
    @Inject(FederationScopeService) private readonly scope: FederationScopeService,
    @Inject(FederationGetQueryService) private readonly query: FederationGetQueryService,
  ) {}
  @Post(':resource/:id')
  async get(
    @Param('resource') resource: string,
    @Param('id') id: string,
    @Req() request: FastifyRequest,
  ): Promise<FederationGetResponse<FederatedRow>> {
    if (!request.federationContext) {
      throw new HttpException(
        new FederationUnauthorizedError('Federation context missing').toEnvelope(),
        401,
      );
    }
    if (id.trim().length === 0) {
      throw new HttpException(
        new FederationInvalidRequestError('Federation get id must not be empty').toEnvelope(),
        400,
      );
    }
    const scopeResult = await this.scope.evaluateAccess({
      context: request.federationContext,
      resource,
      requestedLimit: 1,
      nativeRbac: this.query,
    });
    if (!scopeResult.allowed) {
      throw scopeDenyToHttpException(scopeResult.deny);
    }
    const result = await this.query.get({ filter: scopeResult.filter, id });
    if (result.status === 'not_found') {
      throw new HttpException(
        new FederationNotFoundError('Requested federation resource was not found').toEnvelope(),
        404,
      );
    }
    if (result.status === 'denied') {
      throw new HttpException(
        new FederationScopeViolationError(result.reason, {
          resource,
          id,
          grantId: request.federationContext.grantId,
          peerId: request.federationContext.peerId,
          subjectUserId: request.federationContext.subjectUserId,
        }).toEnvelope(),
        403,
      );
    }
    return { item: { ...result.item, _source: SOURCE_LOCAL } };
  }
 }
--- a/docs/guides/dev-guide.md
+++ b/docs/guides/dev-guide.md
@@ -211,17 +211,6 @@ pnpm format:check && pnpm typecheck && pnpm lint
 A pre-push hook enforces this mechanically.
 ### CI Publish Channels
 Woodpecker `.woodpecker/publish.yml` keeps stable and integration-line artifacts separate:
 | Source                            | npm packages                                                                                                  | Gateway image                                                                            |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | `main` push/manual or release tag | committed package versions published to Gitea npm without changing the dist-tag workflow                      | `gateway:sha-<short>` plus `gateway:latest` on `main`, and the release tag on tag events |
 | `next` push/manual                | CI-computed prereleases, `<target-stable>-next.<CI_PIPELINE_NUMBER>`, published with `npm publish --tag next` | `gateway:sha-<short>` only                                                               |
 `next` never publishes npm `latest` or Docker `latest`. The next npm publish step verifies that `@mosaicstack/mosaic@next` resolves to the computed prerelease before the pipeline can pass.
 ---
 ## Adding New Agent Tools
--- a/docs/scratchpads/462-fed-m3-06-get-verb.md
+++ b/docs/scratchpads/462-fed-m3-06-get-verb.md
@@ -1,38 +0,0 @@
 # Scratchpad — FED-M3-06 get verb
 ## Objective
 Implement `POST /api/federation/v1/get/:resource/:id` for M3 inbound federation reads.
 ## Scope
 - `apps/gateway/src/federation/server/verbs/get.controller.ts`
 - `apps/gateway/src/federation/server/verbs/get-query.service.ts`
 - Unit coverage for controller pipeline + query service RBAC guardrails
 - Register controller/service in `FederationModule`
 ## Plan
 1. Mirror the list verb pipeline: `FederationAuthGuard` → `FederationScopeService` → read-only query service.
 2. Return one `_source: "local"` tagged item on success.
 3. Return federation error envelopes:
   - `404 not_found` when the resource id does not exist.
   - `403 scope_violation` when the row exists but falls outside native RBAC/scope intersection.
   - `400 invalid_request` for malformed ids/scope requests.
 4. Keep read audit persistence deferred to M4; no body or response persistence in M3.
 ## Verification Evidence
 - Rebased onto `origin/main` at `86e106fcc9a1dfa3a18f7846bb477be128794aad` after M3-05 merged; resolved `FederationModule` by registering both list and get verb controllers/services.
 - Review-change coverage added for comment 15971:
  - get note access now requires subject ownership AND authorized mission intersection.
  - missing federation context returns structured `401 unauthorized` envelope.
  - unsupported get resources fail closed with structured denial.
  - PGlite regressions cover cross-user note exclusion and subject-note unauthorized-mission exclusion.
 - `pnpm --filter @mosaicstack/gateway test -- src/federation/server/verbs/__tests__/get.controller.spec.ts src/federation/server/verbs/__tests__/get-query.service.spec.ts` — pass (2 files / 17 tests; re-run after review changes).
 - `pnpm --filter @mosaicstack/gateway build` — pass (re-run after review changes).
 - `pnpm build` — pass (23 successful tasks before review changes).
 - `pnpm typecheck` — pass (41 successful tasks; re-run after review changes).
 - `pnpm lint` — pass (23 successful tasks; re-run after review changes).
 - `pnpm format:check` — pass (re-run after review changes).
 - `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings after review changes.
--- a/docs/scratchpads/B1-next-durable-publish-design.md
+++ b/docs/scratchpads/B1-next-durable-publish-design.md
@@ -1,82 +0,0 @@
 # B1 / @next Durable Publish Pipeline — Design
 ## Objective
 Make `next` a durable integration line that publishes the artifacts required by downstream federation boot tests without manual builds.
 Every merge to `next` publishes:
 1. **npm prerelease packages** to the Gitea npm registry with dist-tag `next`.
 2. **Gateway container image** tagged only as `gateway:sha-<short>`.
 The existing stable release behavior remains isolated to `main` / tags.
 ## Registry verification
 Target registry: `https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`.
 Pre-implementation checks:
 - `npm view @mosaicstack/mosaic dist-tags --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/ --json` returned a dist-tags object (`latest: 0.0.48`).
 - `npm view @mosaicstack/mosaic@latest version --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/` resolved `0.0.48`.
 - `@next` currently returns 404 because no `next` dist-tag exists yet; this is expected before the first next prerelease publish.
 Pipeline design includes a post-publish verification that `npm view @mosaicstack/mosaic@next version` resolves to the exact CI-computed prerelease version. If Gitea fails to honor the `next` dist-tag, the pipeline fails closed.
 ## Version scheme
 The prerelease version is computed at publish time only; no `package.json` version changes are committed.
 For each non-private `@mosaicstack/*` package:
 ```text
 <target-stable>-next.<CI_PIPELINE_NUMBER>
 ```
 Where:
 - `CI_PIPELINE_NUMBER` is Woodpecker's monotonic pipeline number.
 - `target-stable` is the package's current committed stable version with the patch component incremented.
  - Example: `@mosaicstack/mosaic` `0.0.48` publishes as `0.0.49-next.1626`.
  - Example: `@mosaicstack/gateway` `0.0.6` publishes as `0.0.7-next.1626`.
 Rationale:
 - npm semver sorts `0.0.49-next.1627` above `0.0.49-next.1626`.
 - The prerelease does not overtake the future stable `0.0.49`.
 - The monotonic pipeline number avoids conflicts across repeated `next` merges.
 ## Branch and tag guardrails
 | Pipeline path         | Branch/event                   | Publishes                                               | Forbidden              |
 | --------------------- | ------------------------------ | ------------------------------------------------------- | ---------------------- |
 | stable npm publish    | `main` push/manual or tag      | package versions already committed in package manifests | `@next` dist-tag       |
 | next npm publish      | `next` push/manual only        | CI-computed prereleases with `--tag next`               | `latest` dist-tag      |
 | gateway image         | `main` push/manual or tag      | `sha-<short>` + `latest` on main + tag on tag events    | next prerelease npm    |
 | gateway image         | `next` push/manual only        | `sha-<short>` only                                      | `latest`               |
 | appservice/web images | `main` push/manual or tag only | existing stable image behavior                          | next image publication |
 The pipeline has explicit branch checks inside the publish commands as a second fail-closed layer beyond Woodpecker `when` clauses.
 ## Implementation plan
 1. Widen `.woodpecker/publish.yml` top-level `when` to include `next` so the publish pipeline runs on next merges.
 2. Keep existing `publish-npm` on `main` / tags only.
 3. Add `publish-next-npm` for `next` push/manual only:
   - configure Gitea npm auth from existing `gitea_token` secret as `NPM_TOKEN`;
   - preflight registry dist-tag metadata;
   - compute prerelease versions in CI by temporarily editing package manifests in the workspace;
   - run `pnpm publish ... --tag next` against non-private `@mosaicstack/*` packages;
   - verify `@mosaicstack/mosaic@next` resolves to the computed version.
 4. Split image `when` anchors:
   - `image_build_when` includes `next` and is used by `build-gateway`;
   - `main_image_build_when` keeps appservice/web on main/tags only.
 5. Keep gateway next image destinations to `sha-<short>` only; no `latest` on next.
 ## Risk controls
 - Auth/registry failures are fatal.
 - No manual image build/push path is introduced.
 - No production `latest` tags are touched from `next`.
 - No `@latest` npm dist-tags are touched from `next`.
 - All changes live in CI config and docs; no runtime source behavior changes.
--- a/docs/scratchpads/FED-M3-10-integration-tests.md
+++ b/docs/scratchpads/FED-M3-10-integration-tests.md
@@ -1,60 +0,0 @@
 # FED-M3-10 — Federation M3 Integration Tests
 ## Objective
 Add single-gateway gateway integration tests for M3 acceptance #6 and #7.
 ## Branch / base
 - Branch: `feat/federation-m3-integration`
 - Base: `origin/next` (`838701bd` after M3-06/#683 merge)
 - PR base when unblocked: `next`
 ## Scope
 - Real PostgreSQL via `@mosaicstack/db`.
 - Mocked TLS context / Fastify request shim for `FederationAuthGuard`.
 - Direct controller calls using the real M3 route contract: `POST /api/federation/v1/list/:resource` with body `{ limit?, cursor? }`.
 - Gated by `FEDERATED_INTEGRATION=1`.
 - No federation harness dependency.
 ## Fixture notes
 Aligned with the B2 seed design vocabulary:
 - `tasks` visibility uses personal `projects` + `missions` chain.
 - `notes` are `mission_tasks.notes`; the integration suite asserts subject-only note visibility on an authorized mission.
 - Seed includes a second user and unauthorized team/project tasks to prove exclusion from the max-row-cap list result.
 - Grants/peers are direct DB fixtures; cert auth still runs through `FederationAuthGuard` using real X.509 certs generated by existing test helpers.
 ## Current implementation
 Added `apps/gateway/src/__tests__/integration/federation-m3-list.integration.test.ts` covering:
 1. M3 #6 — cert missing Mosaic OIDs returns 401 federation `unauthorized` envelope.
 2. M3 #6 — valid cert whose grant row is `revoked` returns 403 federation `forbidden` envelope.
 3. M3 #7 — active grant with `max_rows_per_query: 2` caps `list tasks`, returns `_truncated` + `nextCursor`, source-tags rows, and excludes other-user / unauthorized-team tasks.
 4. Cross-user notes invariant — subject can list their own `mission_tasks.notes` row while another user's note on the same authorized mission is excluded.
 5. Unsupported-resource invariant — `list widgets` fails closed with a federation `scope_violation` envelope.
 ## Verification
 - `pnpm --filter @mosaicstack/types build` — PASS.
 - `pnpm --filter @mosaicstack/db build` — PASS.
 - `pnpm --filter @mosaicstack/storage build` — PASS.
 - `pnpm --filter @mosaicstack/brain build` — PASS.
 - `pnpm --filter @mosaicstack/queue build` — PASS.
 - `pnpm --filter @mosaicstack/config build` — PASS.
 - `pnpm --filter @mosaicstack/auth build` — PASS.
 - `pnpm --filter @mosaicstack/gateway test -- src/__tests__/integration/federation-m3-list.integration.test.ts` — PASS skipped when `FEDERATED_INTEGRATION` unset (5 skipped).
 - `FEDERATED_INTEGRATION=1 pnpm --filter @mosaicstack/gateway test -- src/__tests__/integration/federation-m3-list.integration.test.ts` — PASS (5 tests) after local `docker compose up -d postgres` + `pnpm --filter @mosaicstack/db db:push`.
 - `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
 - `pnpm --filter @mosaicstack/gateway lint` — PASS.
 - `pnpm format:check` — PASS.
 - `~/.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.
 ## Push / PR
 - #683 landed in `next`; branch rebased onto `origin/next` before push.
 - CI is serialized; run queue guard before push.