feat(config): add federated tier and rename team→standalone (FED-M1-01)

Aligns mosaic.config tier vocabulary with the federation PRD:
- Adds `federated` to the tier enum (Postgres + Valkey + pgvector)
- Renames `team` → `standalone` in StorageTier / GatewayStorageTier
- Keeps `team` as a deprecated alias that warns to stderr and maps to standalone
- Adds DEFAULT_FEDERATED_CONFIG (port 5433, pgvector memory)
- Corrects DEFAULT_STANDALONE_CONFIG.memory to keyword (PRD line 247)
- Wizard interactive promptTier offers local/standalone/federated
- Wizard headless env path now hard-rejects unknown MOSAIC_STORAGE_TIER
  values with a message naming all three valid tiers
- Interactive DATABASE_URL pre-fill is tier-aware: standalone→5432, federated→5433
- 10 new unit tests for the validator + 3 new wizard headless tests

No new behavior beyond the enum and defaults — pgvector enforcement,
tier-detector, and docker-compose overlays land in FED-M1-02..04.

Refs #460

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docker-compose.federated.yml

@@ -1,60 +0,0 @@
-# docker-compose.federated.yml — Federated tier overlay
-#
-# USAGE:
-#   docker compose -f docker-compose.federated.yml --profile federated up -d
-#
-# This file is a standalone overlay for the Mosaic federated tier.
-# It is NOT an extension of docker-compose.yml — it defines its own services
-# and named volumes so it can run independently of the base dev stack.
-#
-# IMPORTANT — HOST PORT CONFLICTS:
-#   The federated services bind the same host ports as the base dev stack
-#   (5433 for Postgres, 6380 for Valkey). You must stop the base dev stack
-#   before starting the federated stack on the same machine:
-#     docker compose down
-#     docker compose -f docker-compose.federated.yml --profile federated up -d
-#
-# pgvector extension:
-#   The vector extension is created automatically at first boot via
-#   ./infra/pg-init/01-extensions.sql (CREATE EXTENSION IF NOT EXISTS vector).
-#
-# Tier configuration:
-#   Used by `mosaic` instances configured with `tier: federated`.
-#   DEFAULT_FEDERATED_CONFIG points at:
-#     postgresql://mosaic:mosaic@localhost:5433/mosaic
-
-services:
-  postgres-federated:
-    image: pgvector/pgvector:pg17
-    profiles: [federated]
-    ports:
-      - '${PG_FEDERATED_HOST_PORT:-5433}:5432'
-    environment:
-      POSTGRES_USER: mosaic
-      POSTGRES_PASSWORD: mosaic
-      POSTGRES_DB: mosaic
-    volumes:
-      - pg_federated_data:/var/lib/postgresql/data
-      - ./infra/pg-init:/docker-entrypoint-initdb.d:ro
-    healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U mosaic']
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-  valkey-federated:
-    image: valkey/valkey:8-alpine
-    profiles: [federated]
-    ports:
-      - '${VALKEY_FEDERATED_HOST_PORT:-6380}:6379'
-    volumes:
-      - valkey_federated_data:/data
-    healthcheck:
-      test: ['CMD', 'valkey-cli', 'ping']
-      interval: 5s
-      timeout: 3s
-      retries: 5
-
-volumes:
-  pg_federated_data:
-  valkey_federated_data:

docs/federation/TASKS.md

@@ -16,9 +16,9 @@
 Goal: Gateway runs in `federated` tier with containerized PG+pgvector+Valkey. No federation logic yet. Existing standalone behavior does not regress.
 
 | id        | status      | description                                                                                                                                                                                                        | issue | agent  | branch                          | depends_on | estimate | notes                                                                                                             |
-| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| FED-M1-01 | done        | Extend `mosaic.config.json` schema: add `"federated"` to `tier` enum in validator + TS types. Keep `local` and `standalone` working. Update schema docs/README where referenced.                                   | #460  | sonnet | feat/federation-m1-tier-config  | —          | 4K       | Shipped in PR #470. Renamed `team` → `standalone`; added `team` deprecation alias; added `DEFAULT_FEDERATED_CONFIG`.              |
-| FED-M1-02 | in-progress | Author `docker-compose.federated.yml` as an overlay profile: Postgres 17 + pgvector extension (port 5433), Valkey (6380), named volumes, healthchecks. Compose-up should boot cleanly on a clean machine.          | #460  | sonnet | feat/federation-m1-compose      | FED-M1-01  | 5K       | Bumped PG16→PG17 to match base compose. Overlay defines distinct `postgres-federated`/`valkey-federated` services, profile-gated. |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| FED-M1-01 | in-progress | Extend `mosaic.config.json` schema: add `"federated"` to `tier` enum in validator + TS types. Keep `local` and `standalone` working. Update schema docs/README where referenced.                                   | #460  | sonnet | feat/federation-m1-tier-config  | —          | 4K       | Schema lives in `packages/types`; validator in gateway bootstrap. No behavior change yet — enum only.             |
+| FED-M1-02 | not-started | Author `docker-compose.federated.yml` as an overlay profile: Postgres 16 + pgvector extension (port 5433), Valkey (6380), named volumes, healthchecks. Compose-up should boot cleanly on a clean machine.          | #460  | codex  | feat/federation-m1-compose      | FED-M1-01  | 5K       | Overlay on existing `docker-compose.yml`; no changes to base file. Add `profile: federated` gating.               |
 | FED-M1-03 | not-started | Add pgvector support to `packages/storage/src/adapters/postgres.ts`: create extension on init (idempotent), expose vector column type in schema helpers. No adapter changes for non-federated tiers.               | #460  | codex  | feat/federation-m1-pgvector     | FED-M1-02  | 8K       | Extension create is idempotent `CREATE EXTENSION IF NOT EXISTS vector`. Gate on tier = federated.                 |
 | FED-M1-04 | not-started | Implement `apps/gateway/src/bootstrap/tier-detector.ts`: reads config, asserts PG/Valkey/pgvector reachable for `federated`, fail-fast with actionable error message on failure. Unit tests for each failure mode. | #460  | codex  | feat/federation-m1-detector     | FED-M1-03  | 8K       | Structured error type with remediation hints. Logs which service failed, with host:port attempted.                |
 | FED-M1-05 | not-started | Write `scripts/migrate-to-federated.ts`: one-way migration from `local` (PGlite) / `standalone` (PG without pgvector) → `federated`. Dumps, transforms, loads; dry-run + confirm UX. Idempotent on re-run.         | #460  | codex  | feat/federation-m1-migrate      | FED-M1-04  | 10K      | Do NOT run automatically. CLI subcommand `mosaic migrate tier --to federated --dry-run`. Safety rails.            |

packages/config/src/index.ts

@@ -5,5 +5,4 @@ export {
   DEFAULT_FEDERATED_CONFIG,
   loadConfig,
   validateConfig,
-  detectFromEnv,
 } from './mosaic-config.js';

packages/config/src/mosaic-config.spec.ts

@@ -1,7 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   validateConfig,
-  detectFromEnv,
   DEFAULT_LOCAL_CONFIG,
   DEFAULT_STANDALONE_CONFIG,
   DEFAULT_FEDERATED_CONFIG,
@@ -107,64 +106,4 @@ describe('DEFAULT_* config constants', () => {
     const url = (DEFAULT_FEDERATED_CONFIG.storage as { url: string }).url;
     expect(url).toContain('5433');
   });
-
-  it('DEFAULT_FEDERATED_CONFIG has enableVector=true on storage', () => {
-    const storage = DEFAULT_FEDERATED_CONFIG.storage as {
-      type: string;
-      url: string;
-      enableVector?: boolean;
-    };
-    expect(storage.enableVector).toBe(true);
-  });
-});
-
-describe('detectFromEnv — tier env-var routing', () => {
-  const originalEnv = process.env;
-
-  beforeEach(() => {
-    // Work on a fresh copy so individual tests can set/delete keys freely.
-    process.env = { ...originalEnv };
-    delete process.env['MOSAIC_STORAGE_TIER'];
-    delete process.env['DATABASE_URL'];
-    delete process.env['VALKEY_URL'];
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  it('no env vars → returns local config', () => {
-    const config = detectFromEnv();
-    expect(config.tier).toBe('local');
-    expect(config.storage.type).toBe('pglite');
-    expect(config.memory.type).toBe('keyword');
-  });
-
-  it('MOSAIC_STORAGE_TIER=federated alone → returns federated config with enableVector=true', () => {
-    process.env['MOSAIC_STORAGE_TIER'] = 'federated';
-    const config = detectFromEnv();
-    expect(config.tier).toBe('federated');
-    expect(config.memory.type).toBe('pgvector');
-    const storage = config.storage as { type: string; enableVector?: boolean };
-    expect(storage.enableVector).toBe(true);
-  });
-
-  it('MOSAIC_STORAGE_TIER=federated + DATABASE_URL → uses the URL and still has enableVector=true', () => {
-    process.env['MOSAIC_STORAGE_TIER'] = 'federated';
-    process.env['DATABASE_URL'] = 'postgresql://custom:pass@db.example.com:5432/mydb';
-    const config = detectFromEnv();
-    expect(config.tier).toBe('federated');
-    const storage = config.storage as { type: string; url: string; enableVector?: boolean };
-    expect(storage.url).toBe('postgresql://custom:pass@db.example.com:5432/mydb');
-    expect(storage.enableVector).toBe(true);
-    expect(config.memory.type).toBe('pgvector');
-  });
-
-  it('MOSAIC_STORAGE_TIER=standalone alone → returns standalone-shaped config (not local)', () => {
-    process.env['MOSAIC_STORAGE_TIER'] = 'standalone';
-    const config = detectFromEnv();
-    expect(config.tier).toBe('standalone');
-    expect(config.storage.type).toBe('postgres');
-    expect(config.memory.type).toBe('keyword');
-  });
 });

packages/config/src/mosaic-config.ts

@@ -40,11 +40,7 @@ export const DEFAULT_STANDALONE_CONFIG: MosaicConfig = {
 
 export const DEFAULT_FEDERATED_CONFIG: MosaicConfig = {
   tier: 'federated',
-  storage: {
-    type: 'postgres',
-    url: 'postgresql://mosaic:mosaic@localhost:5433/mosaic',
-    enableVector: true,
-  },
+  storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5433/mosaic' },
   queue: { type: 'bullmq' },
   memory: { type: 'pgvector' },
 };
@@ -123,30 +119,7 @@ export function validateConfig(raw: unknown): MosaicConfig {
 /*  Loader                                                             */
 /* ------------------------------------------------------------------ */
 
-export function detectFromEnv(): MosaicConfig {
-  const tier = process.env['MOSAIC_STORAGE_TIER'];
-
-  if (tier === 'federated') {
-    if (process.env['DATABASE_URL']) {
-      return {
-        ...DEFAULT_FEDERATED_CONFIG,
-        storage: {
-          type: 'postgres',
-          url: process.env['DATABASE_URL'],
-          enableVector: true,
-        },
-        queue: {
-          type: 'bullmq',
-          url: process.env['VALKEY_URL'],
-        },
-      };
-    }
-    // MOSAIC_STORAGE_TIER=federated without DATABASE_URL — use the default
-    // federated config (port 5433, enableVector: true, pgvector memory).
-    return DEFAULT_FEDERATED_CONFIG;
-  }
-
-  if (tier === 'standalone') {
+function detectFromEnv(): MosaicConfig {
   if (process.env['DATABASE_URL']) {
     return {
       ...DEFAULT_STANDALONE_CONFIG,
@@ -160,26 +133,6 @@ export function detectFromEnv(): MosaicConfig {
       },
     };
   }
-    // MOSAIC_STORAGE_TIER=standalone without DATABASE_URL — use the default
-    // standalone config instead of silently falling back to local.
-    return DEFAULT_STANDALONE_CONFIG;
-  }
-
-  // Legacy: DATABASE_URL set without MOSAIC_STORAGE_TIER — treat as standalone.
-  if (process.env['DATABASE_URL']) {
-    return {
-      ...DEFAULT_STANDALONE_CONFIG,
-      storage: {
-        type: 'postgres',
-        url: process.env['DATABASE_URL'],
-      },
-      queue: {
-        type: 'bullmq',
-        url: process.env['VALKEY_URL'],
-      },
-    };
-  }
-
   return DEFAULT_LOCAL_CONFIG;
 }
 

packages/db/src/schema.ts

@@ -372,11 +372,7 @@ export const messages = pgTable(
 
 // ─── pgvector custom type ───────────────────────────────────────────────────
 
-export const vector = customType<{
-  data: number[];
-  driverParam: string;
-  config: { dimensions: number };
-}>({
+const vector = customType<{ data: number[]; driverParam: string; config: { dimensions: number } }>({
   dataType(config) {
     return `vector(${config?.dimensions ?? 1536})`;
   },

packages/storage/src/adapters/postgres.spec.ts

@@ -1,107 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { DbHandle } from '@mosaicstack/db';
-
-// Mock @mosaicstack/db before importing the adapter
-vi.mock('@mosaicstack/db', async (importOriginal) => {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const actual = await importOriginal<Record<string, any>>();
-  return {
-    ...actual,
-    createDb: vi.fn(),
-    runMigrations: vi.fn().mockResolvedValue(undefined),
-  };
-});
-
-import { createDb, runMigrations } from '@mosaicstack/db';
-import { PostgresAdapter } from './postgres.js';
-
-describe('PostgresAdapter — vector extension gating', () => {
-  let mockExecute: ReturnType<typeof vi.fn>;
-  let mockDb: { execute: ReturnType<typeof vi.fn> };
-  let mockHandle: Pick<DbHandle, 'close'> & { db: typeof mockDb };
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockExecute = vi.fn().mockResolvedValue(undefined);
-    mockDb = { execute: mockExecute };
-    mockHandle = { db: mockDb, close: vi.fn().mockResolvedValue(undefined) };
-    vi.mocked(createDb).mockReturnValue(mockHandle as unknown as DbHandle);
-  });
-
-  it('calls db.execute with CREATE EXTENSION IF NOT EXISTS vector when enableVector=true', async () => {
-    const adapter = new PostgresAdapter({
-      type: 'postgres',
-      url: 'postgresql://test:test@localhost:5432/test',
-      enableVector: true,
-    });
-
-    await adapter.migrate();
-
-    // Should have called execute
-    expect(mockExecute).toHaveBeenCalledTimes(1);
-
-    // Verify the SQL contains the extension creation statement.
-    // Prefer Drizzle's public toSQL() API; fall back to queryChunks if unavailable.
-    // NOTE: queryChunks is an undocumented Drizzle internal (drizzle-orm ^0.45.x).
-    // toSQL() was not present on the raw sql`` result in this version — if a future
-    // Drizzle upgrade adds it, remove the fallback path and delete this comment.
-    const sqlObj = mockExecute.mock.calls[0]![0] as {
-      toSQL?: () => { sql: string; params: unknown[] };
-      queryChunks?: Array<{ value: string[] }>;
-    };
-    const sqlText = sqlObj.toSQL
-      ? sqlObj.toSQL().sql.toLowerCase()
-      : (sqlObj.queryChunks ?? [])
-          .flatMap((chunk) => chunk.value)
-          .join('')
-          .toLowerCase();
-    expect(sqlText).toContain('create extension if not exists vector');
-  });
-
-  it('does NOT call db.execute for extension when enableVector is false', async () => {
-    const adapter = new PostgresAdapter({
-      type: 'postgres',
-      url: 'postgresql://test:test@localhost:5432/test',
-      enableVector: false,
-    });
-
-    await adapter.migrate();
-
-    expect(mockExecute).not.toHaveBeenCalled();
-    expect(vi.mocked(runMigrations)).toHaveBeenCalledOnce();
-  });
-
-  it('does NOT call db.execute for extension when enableVector is unset', async () => {
-    const adapter = new PostgresAdapter({
-      type: 'postgres',
-      url: 'postgresql://test:test@localhost:5432/test',
-    });
-
-    await adapter.migrate();
-
-    expect(mockExecute).not.toHaveBeenCalled();
-    expect(vi.mocked(runMigrations)).toHaveBeenCalledOnce();
-  });
-
-  it('calls runMigrations after the extension is created', async () => {
-    const callOrder: string[] = [];
-    mockExecute.mockImplementation(() => {
-      callOrder.push('execute');
-      return Promise.resolve(undefined);
-    });
-    vi.mocked(runMigrations).mockImplementation(() => {
-      callOrder.push('runMigrations');
-      return Promise.resolve();
-    });
-
-    const adapter = new PostgresAdapter({
-      type: 'postgres',
-      url: 'postgresql://test:test@localhost:5432/test',
-      enableVector: true,
-    });
-
-    await adapter.migrate();
-
-    expect(callOrder).toEqual(['execute', 'runMigrations']);
-  });
-});

packages/storage/src/adapters/postgres.ts

@@ -66,19 +66,13 @@ export class PostgresAdapter implements StorageAdapter {
   private handle: DbHandle;
   private db: Db;
   private url: string;
-  private enableVector: boolean;
 
   constructor(config: Extract<StorageConfig, { type: 'postgres' }>) {
     this.url = config.url;
-    this.enableVector = config.enableVector ?? false;
     this.handle = createDb(config.url);
     this.db = this.handle.db;
   }
 
-  private async ensureVectorExtension(): Promise<void> {
-    await this.db.execute(sql`CREATE EXTENSION IF NOT EXISTS vector`);
-  }
-
   async create<T extends Record<string, unknown>>(
     collection: string,
     data: T,
@@ -155,9 +149,6 @@ export class PostgresAdapter implements StorageAdapter {
   }
 
   async migrate(): Promise<void> {
-    if (this.enableVector) {
-      await this.ensureVectorExtension();
-    }
     await runMigrations(this.url);
   }
 

packages/storage/src/types.ts

@@ -38,6 +38,6 @@ export interface StorageAdapter {
 }
 
 export type StorageConfig =
-  | { type: 'postgres'; url: string; enableVector?: boolean }
+  | { type: 'postgres'; url: string }
   | { type: 'pglite'; dataDir?: string }
   | { type: 'files'; dataDir: string; format?: 'json' | 'md' };