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

packages/config/src/index.ts

@@ -1,7 +1,8 @@
 export type { MosaicConfig, StorageTier, MemoryConfigRef } from './mosaic-config.js';
 export {
   DEFAULT_LOCAL_CONFIG,
-  DEFAULT_TEAM_CONFIG,
+  DEFAULT_STANDALONE_CONFIG,
+  DEFAULT_FEDERATED_CONFIG,
   loadConfig,
   validateConfig,
 } from './mosaic-config.js';

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

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  validateConfig,
+  DEFAULT_LOCAL_CONFIG,
+  DEFAULT_STANDALONE_CONFIG,
+  DEFAULT_FEDERATED_CONFIG,
+} from './mosaic-config.js';
+
+describe('validateConfig — tier enum', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let stderrSpy: any;
+
+  beforeEach(() => {
+    stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+  });
+
+  it('accepts tier="local"', () => {
+    const result = validateConfig({
+      tier: 'local',
+      storage: { type: 'pglite', dataDir: '.mosaic/storage-pglite' },
+      queue: { type: 'local', dataDir: '.mosaic/queue' },
+      memory: { type: 'keyword' },
+    });
+    expect(result.tier).toBe('local');
+  });
+
+  it('accepts tier="standalone"', () => {
+    const result = validateConfig({
+      tier: 'standalone',
+      storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5432/mosaic' },
+      queue: { type: 'bullmq' },
+      memory: { type: 'keyword' },
+    });
+    expect(result.tier).toBe('standalone');
+  });
+
+  it('accepts tier="federated"', () => {
+    const result = validateConfig({
+      tier: 'federated',
+      storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5433/mosaic' },
+      queue: { type: 'bullmq' },
+      memory: { type: 'pgvector' },
+    });
+    expect(result.tier).toBe('federated');
+  });
+
+  it('accepts deprecated tier="team" as alias for "standalone" and emits a deprecation warning', () => {
+    const result = validateConfig({
+      tier: 'team',
+      storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5432/mosaic' },
+      queue: { type: 'bullmq' },
+      memory: { type: 'keyword' },
+    });
+    expect(result.tier).toBe('standalone');
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('DEPRECATED'));
+  });
+
+  it('rejects an invalid tier with an error listing all three valid values', () => {
+    expect(() =>
+      validateConfig({
+        tier: 'invalid',
+        storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5432/mosaic' },
+        queue: { type: 'bullmq' },
+        memory: { type: 'keyword' },
+      }),
+    ).toThrow(/local.*standalone.*federated|federated.*standalone.*local/);
+  });
+
+  it('error message for invalid tier mentions all three valid values', () => {
+    let message = '';
+    try {
+      validateConfig({
+        tier: 'invalid',
+        storage: { type: 'postgres', url: 'postgresql://...' },
+        queue: { type: 'bullmq' },
+        memory: { type: 'keyword' },
+      });
+    } catch (err) {
+      message = err instanceof Error ? err.message : String(err);
+    }
+    expect(message).toContain('"local"');
+    expect(message).toContain('"standalone"');
+    expect(message).toContain('"federated"');
+  });
+});
+
+describe('DEFAULT_* config constants', () => {
+  it('DEFAULT_LOCAL_CONFIG has tier="local"', () => {
+    expect(DEFAULT_LOCAL_CONFIG.tier).toBe('local');
+  });
+
+  it('DEFAULT_STANDALONE_CONFIG has tier="standalone"', () => {
+    expect(DEFAULT_STANDALONE_CONFIG.tier).toBe('standalone');
+  });
+
+  it('DEFAULT_FEDERATED_CONFIG has tier="federated" and pgvector memory', () => {
+    expect(DEFAULT_FEDERATED_CONFIG.tier).toBe('federated');
+    expect(DEFAULT_FEDERATED_CONFIG.memory.type).toBe('pgvector');
+  });
+
+  it('DEFAULT_FEDERATED_CONFIG uses port 5433 (distinct from standalone 5432)', () => {
+    const url = (DEFAULT_FEDERATED_CONFIG.storage as { url: string }).url;
+    expect(url).toContain('5433');
+  });
+});

packages/config/src/mosaic-config.ts

@@ -7,7 +7,7 @@ import type { QueueAdapterConfig as QueueConfig } from '@mosaicstack/queue';
 /*  Types                                                              */
 /* ------------------------------------------------------------------ */
 
-export type StorageTier = 'local' | 'team';
+export type StorageTier = 'local' | 'standalone' | 'federated';
 
 export interface MemoryConfigRef {
   type: 'pgvector' | 'sqlite-vec' | 'keyword';
@@ -31,10 +31,17 @@ export const DEFAULT_LOCAL_CONFIG: MosaicConfig = {
   memory: { type: 'keyword' },
 };
 
-export const DEFAULT_TEAM_CONFIG: MosaicConfig = {
-  tier: 'team',
+export const DEFAULT_STANDALONE_CONFIG: MosaicConfig = {
+  tier: 'standalone',
   storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5432/mosaic' },
   queue: { type: 'bullmq' },
+  memory: { type: 'keyword' },
+};
+
+export const DEFAULT_FEDERATED_CONFIG: MosaicConfig = {
+  tier: 'federated',
+  storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5433/mosaic' },
+  queue: { type: 'bullmq' },
   memory: { type: 'pgvector' },
 };
 
@@ -42,7 +49,7 @@ export const DEFAULT_TEAM_CONFIG: MosaicConfig = {
 /*  Validation                                                         */
 /* ------------------------------------------------------------------ */
 
-const VALID_TIERS = new Set<string>(['local', 'team']);
+const VALID_TIERS = new Set<string>(['local', 'standalone', 'federated']);
 const VALID_STORAGE_TYPES = new Set<string>(['postgres', 'pglite', 'files']);
 const VALID_QUEUE_TYPES = new Set<string>(['bullmq', 'local']);
 const VALID_MEMORY_TYPES = new Set<string>(['pgvector', 'sqlite-vec', 'keyword']);
@@ -55,9 +62,19 @@ export function validateConfig(raw: unknown): MosaicConfig {
   const obj = raw as Record<string, unknown>;
 
   // tier
-  const tier = obj['tier'];
+  let tier = obj['tier'];
+  // Deprecated alias: 'team' → 'standalone' (kept for backward-compat with 0.0.x installs)
+  if (tier === 'team') {
+    process.stderr.write(
+      '[mosaic] DEPRECATED: tier="team" is deprecated — use "standalone" instead. ' +
+        'Update your mosaic.config.json.\n',
+    );
+    tier = 'standalone';
+  }
   if (typeof tier !== 'string' || !VALID_TIERS.has(tier)) {
-    throw new Error(`Invalid tier "${String(tier)}" — expected "local" or "team"`);
+    throw new Error(
+      `Invalid tier "${String(tier)}" — expected "local", "standalone", or "federated"`,
+    );
   }
 
   // storage
@@ -105,7 +122,7 @@ export function validateConfig(raw: unknown): MosaicConfig {
 function detectFromEnv(): MosaicConfig {
   if (process.env['DATABASE_URL']) {
     return {
-      ...DEFAULT_TEAM_CONFIG,
+      ...DEFAULT_STANDALONE_CONFIG,
       storage: {
         type: 'postgres',
         url: process.env['DATABASE_URL'],

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

@@ -216,8 +216,8 @@ describe('gatewayConfigStage', () => {
     expect(daemonState.startCalled).toBe(0);
   });
 
-  it('honors MOSAIC_STORAGE_TIER=team in headless path', async () => {
-    process.env['MOSAIC_STORAGE_TIER'] = 'team';
+  it('honors MOSAIC_STORAGE_TIER=standalone in headless path', async () => {
+    process.env['MOSAIC_STORAGE_TIER'] = 'standalone';
     process.env['MOSAIC_DATABASE_URL'] = 'postgresql://test/db';
     process.env['MOSAIC_VALKEY_URL'] = 'redis://test:6379';
 
@@ -231,12 +231,75 @@ describe('gatewayConfigStage', () => {
     });
 
     expect(result.ready).toBe(true);
-    expect(state.gateway?.tier).toBe('team');
+    expect(state.gateway?.tier).toBe('standalone');
     const envContents = readFileSync(daemonState.envFile, 'utf-8');
     expect(envContents).toContain('DATABASE_URL=postgresql://test/db');
     expect(envContents).toContain('VALKEY_URL=redis://test:6379');
     const mosaicConfig = JSON.parse(readFileSync(daemonState.mosaicConfigFile, 'utf-8'));
-    expect(mosaicConfig.tier).toBe('team');
+    expect(mosaicConfig.tier).toBe('standalone');
+  });
+
+  it('accepts deprecated MOSAIC_STORAGE_TIER=team as alias for standalone', async () => {
+    process.env['MOSAIC_STORAGE_TIER'] = 'team';
+    process.env['MOSAIC_DATABASE_URL'] = 'postgresql://test/db';
+    process.env['MOSAIC_VALKEY_URL'] = 'redis://test:6379';
+
+    const p = buildPrompter();
+    const state = makeState('/home/user/.config/mosaic');
+
+    const result = await gatewayConfigStage(p, state, {
+      host: 'localhost',
+      defaultPort: 14242,
+      skipInstall: true,
+    });
+
+    // Deprecated alias 'team' maps to 'standalone'
+    expect(result.ready).toBe(true);
+    expect(state.gateway?.tier).toBe('standalone');
+    const mosaicConfig = JSON.parse(readFileSync(daemonState.mosaicConfigFile, 'utf-8'));
+    expect(mosaicConfig.tier).toBe('standalone');
+  });
+
+  it('honors MOSAIC_STORAGE_TIER=federated in headless path', async () => {
+    process.env['MOSAIC_STORAGE_TIER'] = 'federated';
+    process.env['MOSAIC_DATABASE_URL'] = 'postgresql://test/feddb';
+    process.env['MOSAIC_VALKEY_URL'] = 'redis://test:6379';
+
+    const p = buildPrompter();
+    const state = makeState('/home/user/.config/mosaic');
+
+    const result = await gatewayConfigStage(p, state, {
+      host: 'localhost',
+      defaultPort: 14242,
+      skipInstall: true,
+    });
+
+    expect(result.ready).toBe(true);
+    expect(state.gateway?.tier).toBe('federated');
+    const envContents = readFileSync(daemonState.envFile, 'utf-8');
+    expect(envContents).toContain('DATABASE_URL=postgresql://test/feddb');
+    const mosaicConfig = JSON.parse(readFileSync(daemonState.mosaicConfigFile, 'utf-8'));
+    expect(mosaicConfig.tier).toBe('federated');
+    expect(mosaicConfig.memory.type).toBe('pgvector');
+  });
+
+  it('rejects an unknown MOSAIC_STORAGE_TIER value in headless mode with a descriptive warning', async () => {
+    process.env['MOSAIC_STORAGE_TIER'] = 'federatd'; // deliberate typo
+
+    const warnFn = vi.fn();
+    const p = buildPrompter({ warn: warnFn });
+    const state = makeState('/home/user/.config/mosaic');
+
+    const result = await gatewayConfigStage(p, state, {
+      host: 'localhost',
+      defaultPort: 14242,
+      skipInstall: true,
+    });
+
+    // The stage surfaces validation errors as ready:false (warning is shown to the user).
+    expect(result.ready).toBe(false);
+    // The warning message must name all three valid values.
+    expect(warnFn).toHaveBeenCalledWith(expect.stringMatching(/local.*standalone.*federated/i));
   });
 
   it('regenerates config when portOverride differs from saved GATEWAY_PORT', async () => {

packages/mosaic/src/stages/gateway-config.ts

@@ -84,10 +84,15 @@ async function promptTier(p: WizardPrompter): Promise<GatewayStorageTier> {
         hint: 'embedded database, no dependencies',
       },
       {
-        value: 'team',
-        label: 'Team',
+        value: 'standalone',
+        label: 'Standalone',
         hint: 'PostgreSQL + Valkey required',
       },
+      {
+        value: 'federated',
+        label: 'Federated',
+        hint: 'PostgreSQL + Valkey + pgvector, federation server+client',
+      },
     ],
   });
   return tier;
@@ -437,7 +442,21 @@ async function collectAndWriteConfig(
     p.log('Headless mode detected — reading configuration from environment variables.');
 
     const storageTierEnv = process.env['MOSAIC_STORAGE_TIER'] ?? 'local';
-    tier = storageTierEnv === 'team' ? 'team' : 'local';
+    if (storageTierEnv === 'team') {
+      // Deprecated alias — warn and treat as standalone
+      process.stderr.write(
+        '[mosaic] DEPRECATED: MOSAIC_STORAGE_TIER=team is deprecated — use "standalone" instead.\n',
+      );
+      tier = 'standalone';
+    } else if (storageTierEnv === 'standalone' || storageTierEnv === 'federated') {
+      tier = storageTierEnv;
+    } else if (storageTierEnv !== '' && storageTierEnv !== 'local') {
+      throw new GatewayConfigValidationError(
+        `Invalid MOSAIC_STORAGE_TIER="${storageTierEnv}" — expected "local", "standalone", or "federated" (deprecated alias "team" also accepted)`,
+      );
+    } else {
+      tier = 'local';
+    }
 
     const portEnv = process.env['MOSAIC_GATEWAY_PORT'];
     port = portEnv ? parseInt(portEnv, 10) : opts.defaultPort;
@@ -453,13 +472,13 @@ async function collectAndWriteConfig(
     hostname = hostnameEnv;
     corsOrigin = corsOverride ?? deriveCorsOrigin(hostnameEnv, 3000);
 
-    if (tier === 'team') {
+    if (tier === 'standalone' || tier === 'federated') {
       const missing: string[] = [];
       if (!databaseUrl) missing.push('MOSAIC_DATABASE_URL');
       if (!valkeyUrl) missing.push('MOSAIC_VALKEY_URL');
       if (missing.length > 0) {
         throw new GatewayConfigValidationError(
-          'Headless install with tier=team requires env vars: ' + missing.join(', '),
+          `Headless install with tier=${tier} requires env vars: ` + missing.join(', '),
         );
       }
     }
@@ -467,11 +486,15 @@ async function collectAndWriteConfig(
     tier = await promptTier(p);
     port = await promptPort(p, opts.defaultPort);
 
-    if (tier === 'team') {
+    if (tier === 'standalone' || tier === 'federated') {
+      const defaultDbUrl =
+        tier === 'federated'
+          ? 'postgresql://mosaic:mosaic@localhost:5433/mosaic'
+          : 'postgresql://mosaic:mosaic@localhost:5432/mosaic';
       databaseUrl = await p.text({
         message: 'DATABASE_URL',
-        initialValue: 'postgresql://mosaic:mosaic@localhost:5433/mosaic',
-        defaultValue: 'postgresql://mosaic:mosaic@localhost:5433/mosaic',
+        initialValue: defaultDbUrl,
+        defaultValue: defaultDbUrl,
       });
       valkeyUrl = await p.text({
         message: 'VALKEY_URL',
@@ -521,7 +544,7 @@ async function collectAndWriteConfig(
     `OTEL_SERVICE_NAME=mosaic-gateway`,
   ];
 
-  if (tier === 'team' && databaseUrl && valkeyUrl) {
+  if ((tier === 'standalone' || tier === 'federated') && databaseUrl && valkeyUrl) {
     envLines.push(`DATABASE_URL=${databaseUrl}`);
     envLines.push(`VALKEY_URL=${valkeyUrl}`);
   }
@@ -545,12 +568,19 @@ async function collectAndWriteConfig(
           queue: { type: 'local', dataDir: join(opts.gatewayHome, 'queue') },
           memory: { type: 'keyword' },
         }
-      : {
-          tier: 'team',
-          storage: { type: 'postgres', url: databaseUrl },
-          queue: { type: 'bullmq', url: valkeyUrl },
-          memory: { type: 'pgvector' },
-        };
+      : tier === 'federated'
+        ? {
+            tier: 'federated',
+            storage: { type: 'postgres', url: databaseUrl },
+            queue: { type: 'bullmq', url: valkeyUrl },
+            memory: { type: 'pgvector' },
+          }
+        : {
+            tier: 'standalone',
+            storage: { type: 'postgres', url: databaseUrl },
+            queue: { type: 'bullmq', url: valkeyUrl },
+            memory: { type: 'keyword' },
+          };
 
   writeFileSync(opts.mosaicConfigFile, JSON.stringify(mosaicConfig, null, 2) + '\n', {
     mode: 0o600,

packages/mosaic/src/types.ts

@@ -58,7 +58,7 @@ export interface HooksState {
   acceptedAt?: string;
 }
 
-export type GatewayStorageTier = 'local' | 'team';
+export type GatewayStorageTier = 'local' | 'standalone' | 'federated';
 
 export interface GatewayAdminState {
   name: string;