refactor: move InMemoryStrategy to driver-memory, strategy contracts to spec

- Move AnalyticsStrategy, StrategyContext, DriverCapabilities interfaces
  to @objectstack/spec/contracts (Protocol First principle)
- Move InMemoryStrategy from service-analytics to driver-memory
- Replace built-in InMemoryStrategy with internal FallbackDelegateStrategy
  in AnalyticsService (auto-added when fallbackService is configured)
- service-analytics/strategies/types.ts now re-exports from spec
- Analytics service registration remains in service-analytics (already correct)
- All tests pass: 30 service-analytics, 94 driver-memory, 6704 spec

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/94c99192-9b5e-4b97-809a-902bc64293c3

Author: Copilot

…ics/src/strategies/in-memory-strategy.ts …/driver-memory/src/in-memory-strategy.tspackages/services/service-analytics/src/strategies/in-memory-strategy.ts renamed to packages/plugins/driver-memory/src/in-memory-strategy.ts packages/services/service-analytics/src/strategies/in-memory-strategy.ts renamed to packages/plugins/driver-memory/src/in-memory-strategy.ts

@@ -1,13 +1,12 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { AnalyticsQuery, AnalyticsResult } from '@objectstack/spec/contracts';
-import type { AnalyticsStrategy, StrategyContext } from './types.js';
+import type { AnalyticsQuery, AnalyticsResult, AnalyticsStrategy, StrategyContext } from '@objectstack/spec/contracts';
 
 /**
  * InMemoryStrategy — Priority 3
  *
  * Delegates to an existing `IAnalyticsService` instance that was registered
- * as a fallback (typically `MemoryAnalyticsService` from `@objectstack/driver-memory`).
+ * as a fallback (typically `MemoryAnalyticsService` from this package).
  *
  * This is the lowest-priority strategy, used in:
  * - `dev` / `test` environments

packages/plugins/driver-memory/src/index.ts

@@ -11,6 +11,8 @@ export { LocalStoragePersistenceAdapter } from './persistence/local-storage-adap
 export { MemoryAnalyticsService } from './memory-analytics.js';
 export type { MemoryAnalyticsConfig } from './memory-analytics.js';
 
+export { InMemoryStrategy } from './in-memory-strategy.js';
+
 export default {
   id: 'com.objectstack.driver.memory',
   version: '1.0.0',

packages/services/service-analytics/src/__tests__/analytics-service.test.ts

@@ -7,7 +7,6 @@ import { AnalyticsService } from '../analytics-service.js';
 import { CubeRegistry } from '../cube-registry.js';
 import { NativeSQLStrategy } from '../strategies/native-sql-strategy.js';
 import { ObjectQLStrategy } from '../strategies/objectql-strategy.js';
-import { InMemoryStrategy } from '../strategies/in-memory-strategy.js';
 import type { DriverCapabilities } from '../strategies/types.js';
 
 // ─────────────────────────────────────────────────────────────────
@@ -262,98 +261,69 @@ describe('ObjectQLStrategy', () => {
 });
 
 // ─────────────────────────────────────────────────────────────────
-// InMemoryStrategy
+// FallbackDelegateStrategy (internal, tested via AnalyticsService)
 // ─────────────────────────────────────────────────────────────────
 
-describe('InMemoryStrategy', () => {
-  const strategy = new InMemoryStrategy();
-
-  it('should have correct name and priority', () => {
-    expect(strategy.name).toBe('InMemoryStrategy');
-    expect(strategy.priority).toBe(30);
-  });
-
-  it('should handle when fallbackService is available', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: false }),
-      fallbackService: {
-        query: vi.fn(),
-        getMeta: vi.fn(),
-      },
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(true);
-  });
-
-  it('should handle when inMemory capability is true', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: true }),
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(true);
-  });
-
-  it('should not handle without fallback and not inMemory', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: false }),
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(false);
-  });
-
-  it('should delegate to fallback service', async () => {
+describe('FallbackDelegateStrategy (via AnalyticsService)', () => {
+  it('should auto-add FallbackDelegateStrategy when fallbackService is configured', async () => {
     const mockResult: AnalyticsResult = { rows: [{ count: 10 }], fields: [{ name: 'count', type: 'number' }] };
-    const fallbackService = {
+    const fallback: IAnalyticsService = {
       query: vi.fn().mockResolvedValue(mockResult),
-      getMeta: vi.fn(),
+      getMeta: vi.fn().mockResolvedValue([]),
     };
 
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: true }),
-      fallbackService,
-    };
+    const service = new AnalyticsService({
+      cubes: [ordersCube],
+      logger: silentLogger,
+      fallbackService: fallback,
+    });
 
-    const result = await strategy.execute(baseQuery, ctx);
-    expect(fallbackService.query).toHaveBeenCalledWith(baseQuery);
+    const result = await service.query(baseQuery);
+    expect(fallback.query).toHaveBeenCalledWith(baseQuery);
     expect(result).toEqual(mockResult);
   });
 
-  it('should throw when no fallback service', async () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: true }),
-    };
+  it('should NOT add FallbackDelegateStrategy when no fallbackService', async () => {
+    const service = new AnalyticsService({
+      cubes: [ordersCube],
+      logger: silentLogger,
+      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: false }),
+    });
 
-    await expect(strategy.execute(baseQuery, ctx)).rejects.toThrow('No fallback analytics service');
+    await expect(service.query(baseQuery)).rejects.toThrow('No strategy can handle');
   });
 
-  it('should delegate generateSql to fallback', async () => {
-    const fallbackService = {
+  it('should delegate generateSql to fallback service', async () => {
+    const fallback: IAnalyticsService = {
       query: vi.fn(),
       getMeta: vi.fn(),
       generateSql: vi.fn().mockResolvedValue({ sql: 'SELECT 1', params: [] }),
     };
 
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: true }),
-      fallbackService,
-    };
+    const service = new AnalyticsService({
+      cubes: [ordersCube],
+      logger: silentLogger,
+      fallbackService: fallback,
+    });
 
-    const { sql } = await strategy.generateSql(baseQuery, ctx);
+    const { sql } = await service.generateSql(baseQuery);
     expect(sql).toBe('SELECT 1');
   });
 
   it('should return placeholder SQL when fallback has no generateSql', async () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: true }),
-      fallbackService: { query: vi.fn(), getMeta: vi.fn() },
+    const fallback: IAnalyticsService = {
+      query: vi.fn().mockResolvedValue({ rows: [], fields: [] }),
+      getMeta: vi.fn(),
     };
 
-    const { sql } = await strategy.generateSql(baseQuery, ctx);
-    expect(sql).toContain('InMemoryStrategy');
+    const service = new AnalyticsService({
+      cubes: [ordersCube],
+      logger: silentLogger,
+      fallbackService: fallback,
+    });
+
+    const { sql } = await service.generateSql(baseQuery);
+    expect(sql).toContain('FallbackDelegateStrategy');
   });
 });
 
@@ -389,7 +359,7 @@ describe('AnalyticsService', () => {
     expect(result.rows).toHaveLength(1);
   });
 
-  it('should fall back to InMemoryStrategy with fallback service', async () => {
+  it('should fall back to FallbackDelegateStrategy with fallback service', async () => {
     const mockResult: AnalyticsResult = {
       rows: [{ count: 100 }],
       fields: [{ name: 'count', type: 'number' }],

packages/services/service-analytics/src/analytics-service.ts

@@ -13,7 +13,6 @@ import { CubeRegistry } from './cube-registry.js';
 import type { AnalyticsStrategy, DriverCapabilities, StrategyContext } from './strategies/types.js';
 import { NativeSQLStrategy } from './strategies/native-sql-strategy.js';
 import { ObjectQLStrategy } from './strategies/objectql-strategy.js';
-import { InMemoryStrategy } from './strategies/in-memory-strategy.js';
 
 /**
  * Configuration for AnalyticsService.
@@ -73,7 +72,10 @@ const DEFAULT_CAPABILITIES: DriverCapabilities = {
  * |:---:|:---|:---|
  * | P1 (10) | NativeSQLStrategy | Driver supports raw SQL |
  * | P2 (20) | ObjectQLStrategy | Driver supports aggregate AST |
- * | P3 (30) | InMemoryStrategy | Fallback service registered |
+ * | P3 (30) | (custom / InMemoryStrategy from driver-memory) | Injected by user |
+ *
+ * When `fallbackService` is configured, an internal delegate strategy
+ * is automatically appended at priority 30 as a safety net.
  *
  * The service also owns a `CubeRegistry` for metadata discovery and
  * auto-inference from object schemas.
@@ -103,11 +105,19 @@ export class AnalyticsService implements IAnalyticsService {
     };
 
     // Build strategy chain (built-in + custom, sorted by priority)
+    // InMemoryStrategy is NOT built-in — it lives in @objectstack/driver-memory
+    // and should be passed via config.strategies when needed.
+    // When fallbackService is configured, an internal delegate is added at P3.
     const builtIn: AnalyticsStrategy[] = [
       new NativeSQLStrategy(),
       new ObjectQLStrategy(),
-      new InMemoryStrategy(),
     ];
+
+    // Auto-add fallback delegate when fallbackService is provided
+    if (config.fallbackService) {
+      builtIn.push(new FallbackDelegateStrategy());
+    }
+
     const custom = config.strategies || [];
     this.strategies = [...builtIn, ...custom].sort((a, b) => a.priority - b.priority);
 
@@ -188,3 +198,34 @@ export class AnalyticsService implements IAnalyticsService {
     );
   }
 }
+
+/**
+ * FallbackDelegateStrategy — Internal strategy for fallback service delegation.
+ *
+ * Automatically added to the strategy chain when `fallbackService` is configured.
+ * Not exported — consumers who need explicit in-memory support should use
+ * `InMemoryStrategy` from `@objectstack/driver-memory`.
+ */
+class FallbackDelegateStrategy implements AnalyticsStrategy {
+  readonly name = 'FallbackDelegateStrategy';
+  readonly priority = 30;
+
+  canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean {
+    if (!query.cube) return false;
+    return !!ctx.fallbackService;
+  }
+
+  async execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult> {
+    return ctx.fallbackService!.query(query);
+  }
+
+  async generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{ sql: string; params: unknown[] }> {
+    if (ctx.fallbackService?.generateSql) {
+      return ctx.fallbackService.generateSql(query);
+    }
+    return {
+      sql: `-- FallbackDelegateStrategy: SQL generation not supported for cube "${query.cube}"`,
+      params: [],
+    };
+  }
+}

packages/services/service-analytics/src/index.ts

@@ -14,5 +14,6 @@ export { CubeRegistry } from './cube-registry.js';
 // Strategies
 export { NativeSQLStrategy } from './strategies/native-sql-strategy.js';
 export { ObjectQLStrategy } from './strategies/objectql-strategy.js';
-export { InMemoryStrategy } from './strategies/in-memory-strategy.js';
 export type { AnalyticsStrategy, StrategyContext, DriverCapabilities } from './strategies/types.js';
+
+// Note: InMemoryStrategy is exported from @objectstack/driver-memory

packages/services/service-analytics/src/strategies/types.ts

@@ -1,84 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { AnalyticsQuery, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
-import type { Cube } from '@objectstack/spec/data';
-
-/**
- * Driver capability descriptor.
- *
- * Used by the strategy chain to decide at runtime which execution path
- * is available for a given cube / object.
- */
-export interface DriverCapabilities {
-  /** Driver supports native SQL execution (e.g. Postgres, MySQL, SQLite). */
-  nativeSql: boolean;
-  /** Driver supports ObjectQL aggregate() operations. */
-  objectqlAggregate: boolean;
-  /** Driver is an in-memory implementation (dev/test only). */
-  inMemory: boolean;
-}
-
-/**
- * Context passed to every strategy so it can access shared infrastructure.
- */
-export interface StrategyContext {
-  /** Resolve a cube definition by name. */
-  getCube(name: string): Cube | undefined;
-  /** Probe driver capabilities for the object backing a cube. */
-  queryCapabilities(cubeName: string): DriverCapabilities;
-  /**
-   * Execute a raw SQL string on the driver that owns `objectName`.
-   * Only available when `nativeSql` capability is true.
-   */
-  executeRawSql?(objectName: string, sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
-  /**
-   * Execute an ObjectQL aggregate query.
-   * Only available when `objectqlAggregate` capability is true.
-   */
-  executeAggregate?(objectName: string, options: {
-    groupBy?: string[];
-    aggregations?: Array<{ field: string; method: string; alias: string }>;
-    filter?: Record<string, unknown>;
-  }): Promise<Record<string, unknown>[]>;
-  /**
-   * Fallback in-memory analytics service (e.g. MemoryAnalyticsService from driver-memory).
-   */
-  fallbackService?: {
-    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
-    getMeta(cubeName?: string): Promise<CubeMeta[]>;
-    generateSql?(query: AnalyticsQuery): Promise<{ sql: string; params: unknown[] }>;
-  };
-}
-
 /**
- * AnalyticsStrategy — One link in the priority-ordered strategy chain.
- *
- * Each strategy is responsible for:
- * 1. Determining whether it *can* handle a query (via `canHandle`).
- * 2. Executing the query using its specific driver path.
- * 3. Optionally generating a SQL representation of the query.
+ * Strategy pattern types — re-exported from @objectstack/spec/contracts
+ * for convenience. The canonical definitions live in the spec package.
  */
-export interface AnalyticsStrategy {
-  /** Human-readable strategy name (e.g. 'NativeSQLStrategy'). */
-  readonly name: string;
-  /** Priority (lower = higher priority). P1=10, P2=20, P3=30. */
-  readonly priority: number;
-
-  /**
-   * Return `true` if this strategy can handle the given query in the
-   * current runtime context (driver capabilities, cube availability, etc.).
-   */
-  canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
-
-  /**
-   * Execute the analytical query.
-   * Called only when `canHandle` returned `true`.
-   */
-  execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult>;
-
-  /**
-   * Generate a SQL representation without executing.
-   * Called only when `canHandle` returned `true`.
-   */
-  generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{ sql: string; params: unknown[] }>;
-}
+export type {
+  AnalyticsStrategy,
+  StrategyContext,
+  DriverCapabilities,
+} from '@objectstack/spec/contracts';